openclaw node

运行一个无头节点主机，连接到 Gateway WebSocket，并在本机暴露 system.run / system.which 能力。

为什么需要节点主机？

当你希望 Agent 在网络中的其他机器上运行命令，又不想在那台机器上安装完整的 macOS 伴侣应用时，节点主机是最佳选择。

常见使用场景：

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

执行仍然受节点主机上的 exec 审批和每个 agent 的允许列表控制，因此你可以保持命令访问的范围清晰明确。

浏览器代理（零配置）

节点主机会自动广播浏览器代理，前提是节点上的 browser.enabled 未被禁用。这样 Agent 就可以在该节点上使用浏览器自动化，无需额外配置。

默认情况下，代理暴露节点的普通浏览器 profile 界面。如果设置了 nodeHost.browserProxy.allowProfiles，代理会变为限制性模式：不在允许列表中的 profile 目标会被拒绝，持久 profile 的创建/删除路由也会通过代理被阻止。

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

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

前台运行

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

选项：

• --host <host>：Gateway WebSocket 主机（默认：127.0.0.1）
• --port <port>：Gateway WebSocket 端口（默认：18789）
• --tls：为 gateway 连接使用 TLS
• --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
• --node-id <id>：覆盖节点 id（清除配对 token）
• --display-name <name>：覆盖节点显示名称

节点主机的 Gateway 认证

openclaw node run 和 openclaw node install 从配置/环境变量解析 gateway 认证（node 命令没有 --token/--password 标志）：

• 首先检查 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
• 然后是本地配置回退：gateway.auth.token / gateway.auth.password。
• 在本地模式下，节点主机有意不继承 gateway.remote.token / gateway.remote.password。
• 如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置且未解析，节点认证解析会安全失败（不存在远程回退掩盖）。
• 在 gateway.mode=remote 下，远程客户端字段（gateway.remote.token / gateway.remote.password）也会按远程优先规则参与。
• 节点主机认证解析只遵守 OPENCLAW_GATEWAY_* 环境变量。

服务（后台）

将无头节点主机安装为用户服务。

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

选项：

• --host <host>：Gateway WebSocket 主机（默认：127.0.0.1）
• --port <port>：Gateway WebSocket 端口（默认：18789）
• --tls：为 gateway 连接使用 TLS
• --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
• --node-id <id>：覆盖节点 id（清除配对 token）
• --display-name <name>：覆盖节点显示名称
• --runtime <runtime>：服务运行时（node 或 bun）
• --force：如果已安装则重新安装/覆盖

管理服务：

openclaw node status
openclaw node stop
openclaw node restart
openclaw node uninstall

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

服务命令支持 --json 输出机器可读结果。

配对

首次连接时，会在 Gateway 上创建一个待处理的设备配对请求（role: node）。 通过以下命令批准：

openclaw devices list
openclaw devices approve <requestId>

如果节点以变更后的认证详情（角色/权限范围/公钥）重试配对， 之前的待处理请求会被取代，并创建新的 requestId。 批准之前请再次运行 openclaw devices list。

节点主机将其节点 id、token、显示名称和 gateway 连接信息存储在 ~/.openclaw/node.json 中。

Exec 审批

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

• ~/.openclaw/exec-approvals.json
• Exec approvals
• openclaw approvals --node <id|name|ip>（从 Gateway 编辑）

实用场景：在你的 NAS 或家庭服务器上跑一个节点主机，龙虾就能帮你远程执行维护脚本——既省心又不用开 SSH 暴露端口。