OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

CLI 命令

节点

openclaw node

运行一个连接到 Gateway 网关 WebSocket，并在此机器上公开 system.run / system.which 的无头节点主机。

在 macOS 上，菜单栏应用已将此节点主机运行时嵌入自身的节点连接中，并添加了 Mac 原生能力。仅当你有意在 Mac 上使用不含该应用的无头节点时，才使用 openclaw node run。同时运行两者会为同一台机器创建两个节点身份。

为什么使用节点主机？

当你希望智能体在网络中的其他机器上运行命令，而又不想在那里安装完整的 macOS 配套应用时，请使用节点主机。

常见用例：

  • 在远程 Linux/Windows 机器（构建服务器、实验室机器、NAS）上运行命令。
  • 在 Gateway 网关上保持 Exec 沙箱隔离，但将已批准的运行委托给其他主机。
  • 为自动化或 CI 节点提供轻量级无头执行目标。

执行仍受节点主机上的 Exec 审批和按智能体配置的允许列表保护，因此你可以明确限定命令访问范围。

openclaw node run 可以在连接后发布由插件或 MCP 支持的工具。Gateway 网关默认信任来自已配对节点的描述符，同时要求每个描述符的命令仍处于该节点已获批准的命令范围内。智能体会将每个接受的描述符视为普通插件工具，但执行仍会通过 node.invoke，因此断开节点连接后，新智能体运行中将不再提供该工具。Gateway 网关操作员可以使用 gateway.nodes.pluginTools.enabled: false 禁用发布。

对于声明式 MCP 工具，请在节点机器上的 openclaw.json 中，将常规 MCP 服务器结构添加到 nodeHost.mcp.servers 下，然后重启节点主机。节点会声明受审批控制的 mcp.tools.call.v1 命令族，并在连接后发布列出的工具；以后更改服务器列表无需重新配对。请参阅 节点托管的 MCP 服务器。

浏览器代理（零配置）

如果节点上未禁用 browser.enabled，节点主机会自动公布浏览器代理。这使智能体无需额外配置即可在该节点上使用浏览器自动化。

默认情况下，代理会公开节点的常规浏览器配置文件范围。如果设置了 nodeHost.browserProxy.allowProfiles，代理将变为限制模式：系统会拒绝定位非允许列表中的配置文件，并通过代理阻止持久化配置文件的创建/删除路由。

如有需要，可在节点上将其禁用：

json5
{  nodeHost: {    browserProxy: {      enabled: false,    },  },}

运行（前台）

bash
openclaw node run --host <gateway-host> --port 18789

选项：

  • --host <host>：Gateway 网关 WebSocket 主机（默认值：127.0.0.1）
  • --port <port>：Gateway 网关 WebSocket 端口（默认值：18789）
  • --context-path <path>：Gateway 网关 WebSocket 上下文路径（例如 /openclaw-gw）。追加到 WebSocket URL。
  • --tls：对 Gateway 网关连接使用 TLS
  • --no-tls：即使本地 Gateway 网关配置启用了 TLS，也强制使用明文 Gateway 网关连接
  • --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
  • --node-id <id>：覆盖共享 SQLite 状态中存储的客户端实例 ID（不会重置配对）
  • --display-name <name>：覆盖节点显示名称

节点主机的 Gateway 网关身份验证

openclaw node run 和 openclaw node install 从配置/环境变量解析 Gateway 网关身份验证（节点命令不提供 --token/--password 标志）：

  • 首先检查 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
  • 然后回退到本地配置：gateway.auth.token / gateway.auth.password。
  • 在本地模式下，节点主机有意不继承 gateway.remote.token / gateway.remote.password。
  • 如果通过 SecretRef 显式配置的 gateway.auth.token / gateway.auth.password 无法解析，节点身份验证解析将以失败关闭方式终止（不会通过远程回退掩盖问题）。
  • 在 gateway.mode=remote 中，远程客户端字段（gateway.remote.token / gateway.remote.password）也会按照远程优先级规则参与解析。
  • 节点主机身份验证解析仅接受 OPENCLAW_GATEWAY_* 环境变量。

对于连接到明文 ws:// Gateway 网关的节点，系统接受回环地址、私有 IP 字面量、.local 和 Tailnet *.ts.net 主机。对于其他受信任的私有 DNS 名称，请设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1；若未设置，节点启动将以失败关闭方式终止，并要求你使用 wss://、SSH 隧道或 Tailscale。这是进程环境的选择性启用项，而不是 openclaw.json 配置键。 如果安装命令的环境中存在该值，openclaw node install 会将其持久化到受监管的节点服务中。

服务（后台）

将无头节点主机安装为用户服务（macOS 上为 launchd，Linux 上为 systemd，Windows 上为 Windows Task Scheduler）。

bash
openclaw node install --host <gateway-host> --port 18789

选项：

  • --host <host>：Gateway 网关 WebSocket 主机（默认值：127.0.0.1）
  • --port <port>：Gateway 网关 WebSocket 端口（默认值：18789）
  • --context-path <path>：Gateway 网关 WebSocket 上下文路径（例如 /openclaw-gw）。追加到 WebSocket URL。
  • --tls：对 Gateway 网关连接使用 TLS
  • --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
  • --node-id <id>：覆盖共享 SQLite 状态中存储的客户端实例 ID（不会重置配对）
  • --display-name <name>：覆盖节点显示名称
  • --runtime <runtime>：服务运行时（node）
  • --force：如果已安装，则重新安装/覆盖

管理服务：

bash
openclaw node statusopenclaw node startopenclaw node stopopenclaw node restartopenclaw node uninstall

使用 openclaw node run 运行前台节点主机（不使用服务）。

服务命令接受 --json 以输出机器可读格式。

节点主机会在进程内重试 Gateway 网关重启和网络连接关闭。如果 Gateway 网关报告因令牌/密码/引导身份验证而进入终止性暂停，节点主机会记录关闭详情并以非零状态退出，以便 launchd/systemd/Task Scheduler 使用最新配置和凭据重启它。因需要配对而导致的暂停会保留在前台流程中，以便批准待处理请求。

配对

首次连接会在 Gateway 网关上创建一个待处理的设备配对请求（role: node）。

如果 Gateway 网关主机能够以非交互方式通过 SSH 连接到节点主机（同一用户、受信任的主机密钥），待处理请求将自动获批：Gateway 网关通过 SSH 在节点主机上运行 openclaw node identity --json，并在设备密钥完全匹配时批准。此功能默认启用；有关要求以及如何禁用它（gateway.nodes.pairing.sshVerify: false），请参阅 经 SSH 验证的设备自动批准。

否则，请通过以下命令手动批准：

bash
openclaw devices listopenclaw devices approve <requestId>

检查 Gateway 网关用于验证的本地节点身份：

bash
openclaw node identity --json

该命令会输出 state/openclaw.sqlite 中 primary 行的设备 ID 和公钥，并且绝不会创建数据库或新身份。

在严格控制的节点网络中，Gateway 网关操作员可以显式选择启用来自受信任 CIDR 的首次节点配对自动批准：

json5
{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

此功能默认禁用（未设置 autoApproveCidrs）。它仅适用于来自 Gateway 网关所信任客户端 IP、且未请求权限范围的全新 role: node 配对。操作员/浏览器客户端、Control UI、WebChat，以及角色、权限范围、元数据或公钥升级仍需手动批准。

如果节点使用已更改的身份验证详情（角色/权限范围/公钥）重试配对，先前的待处理请求将被取代，并创建新的 requestId。请在批准前再次运行 openclaw devices list。

身份和配对状态

无头节点将其客户端实例 ID 与 Gateway 网关用于配对和路由的签名设备身份分开。此状态位于 OpenClaw 状态目录中（默认为 ~/.openclaw，设置 $OPENCLAW_STATE_DIR 时则使用后者）：

状态 用途
state/openclaw.sqlite (node_host_config) 客户端实例 ID、显示名称和 Gateway 网关连接元数据。客户端将此 ID 作为 instanceId 发送。
state/openclaw.sqlite (device_identities, primary) 签名的 Ed25519 密钥对及派生设备 ID。对于签名连接，此设备 ID 是用于路由的节点 ID 和配对身份。
state/openclaw.sqlite (device_auth_tokens) 已配对的设备令牌，以加密设备 ID 和角色为键。

--node-id 仅更改共享 SQLite 状态中的客户端实例 ID。它不会更改加密设备 ID，也不会清除配对身份验证。使用 openclaw doctor --fix 迁移已停用的 node.json 同样不会重置配对。要撤销节点并重新配对：

  1. 在 Gateway 网关上运行 openclaw nodes remove --node <id|name|ip>。
  2. 在节点上，使用 openclaw node restart 重启已安装的服务，或停止后重新运行前台 openclaw node run 命令。这会启动设备配对流程。如果 openclaw devices list 未显示请求，而节点报告 AUTH_DEVICE_TOKEN_MISMATCH，请再重启或重新运行一次。被拒绝的尝试会清除本地现已撤销的令牌；下一次尝试即可请求配对。
  3. 在 Gateway 网关上运行 openclaw devices list，然后运行 openclaw devices approve <deviceRequestId>。
  4. 再次重启或重新运行节点。因配对而暂停的客户端不会在批准后自动恢复；此次重新连接会创建单独的命令范围请求。
  5. 在 Gateway 网关上运行 openclaw nodes pending，然后运行 openclaw nodes approve <nodeRequestId>。

两个请求 ID 彼此不同。适用的受信任 CIDR 策略可以自动批准首次设备配对步骤；命令范围审批仍是单独的检查。

较旧的 OpenClaw 版本将节点主机状态存储在 node.json 中，将签名身份存储在 identity/device.json 中，并将已配对身份验证信息存储在 identity/device-auth.json 中。停止节点主机并运行一次 openclaw doctor --fix；Doctor 会接管每个已停用的源、对其进行验证、导入并验证规范 SQLite 行，然后删除旧文件。当任一已停用文件或中断的 Doctor 接管仍然存在时，普通节点命令会以失败关闭方式终止，并显示此修复指令。请将 state/openclaw.sqlite 保密；它包含设备密钥对和身份验证令牌。

Exec 审批

system.run 受本地 Exec 审批控制：

  • $OPENCLAW_STATE_DIR/exec-approvals.json，或 变量未设置时的 ~/.openclaw/exec-approvals.json
  • Exec 审批
  • openclaw approvals --node <id|name|ip>（从 Gateway 网关编辑）

对于已批准的异步节点 Exec，OpenClaw 会在提示前准备规范的 systemRunPlan。随后获批的 system.run 转发会复用已存储的计划，因此，审批请求创建后对命令/cwd/会话字段所做的编辑会被拒绝，而不会改变节点实际执行的内容。

相关内容

Was this useful?
On this page

On this page