跳转到主要内容

​
openclaw node

运行一个无头节点主机，它会连接到 Gateway 网关 WebSocket，并在这台机器上暴露 system.run / system.which。

​
为什么使用节点主机？

当你希望智能体在你的网络中其他机器上运行命令，而不想在那里安装完整的 macOS 配套应用时，可以使用节点主机。 常见用例：
  • 在远程 Linux/Windows 机器上运行命令（构建服务器、实验室机器、NAS）。
  • 在网关上保持 exec 沙箱隔离，但将已批准的运行委派给其他主机。
  • 为自动化或 CI 节点提供轻量级、无头执行目标。
执行仍然受exec 审批和节点主机上的按智能体 allowlist 保护，因此你可以让命令访问保持范围明确且显式。

​
浏览器代理（零配置）

如果节点上的 browser.enabled 未被禁用，节点主机会自动广播浏览器代理。这样智能体无需额外配置即可在该节点上使用浏览器自动化。 默认情况下，代理会暴露节点的普通浏览器配置文件表面。如果你设置了 nodeHost.browserProxy.allowProfiles，代理会变为限制模式：非 allowlist 中的配置文件定向会被拒绝，并且持久配置文件的创建/删除路由会通过代理被阻止。 如有需要，可在节点上禁用它： 
{
  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）
  • --context-path <path>：Gateway 网关 WebSocket 上下文路径（例如 /openclaw-gw）。会追加到 WebSocket URL。
  • --tls：为 Gateway 网关连接使用 TLS
  • --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
  • --node-id <id>：覆盖节点 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。
  • 如果 gateway.auth.token / gateway.auth.password 通过 SecretRef 显式配置但无法解析，节点认证解析会失败关闭（不会用远程回退来掩盖）。
  • 在 gateway.mode=remote 中，远程客户端字段（gateway.remote.token / gateway.remote.password）也会按远程优先级规则成为候选。
  • 节点主机认证解析只遵循 OPENCLAW_GATEWAY_* 环境变量。
对于连接到明文 ws:// Gateway 网关的节点，loopback、私有 IP 字面量、.local 和 Tailnet *.ts.net 主机会被接受。对于其他受信任的私有 DNS 名称，请设置 OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1；如果没有设置，节点启动会失败关闭，并要求你使用 wss://、SSH 隧道或 Tailscale。这是一个进程环境 opt-in，而不是 openclaw.json 配置键。 当安装命令环境中存在该变量时，openclaw node install 会将其持久化到受监督的节点服务中。

​
服务（后台）

将无头节点主机安装为用户服务（macOS 上是 launchd，Linux 上是 systemd，Windows 上是 Windows Task Scheduler）。 
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>：覆盖节点 ID（清除配对令牌）
  • --display-name <name>：覆盖节点显示名称
  • --runtime <runtime>：服务运行时（node 或 bun）
  • --force：如果已安装，则重新安装/覆盖
管理服务： 
openclaw node status
openclaw node start
openclaw node stop
openclaw node restart
openclaw node uninstall
使用 openclaw node run 运行前台节点主机（无服务）。 服务命令接受 --json 以输出机器可读内容。 节点主机会在进程内重试 Gateway 网关重启和网络关闭。如果 Gateway 网关报告终止性的令牌/密码/引导认证暂停，节点主机会记录关闭详情并以非零状态退出，以便 launchd/systemd/Task Scheduler 可以使用新的配置和凭证重启它。需要配对的暂停会留在前台流程中，以便待处理请求可以被批准。

​
配对

第一次连接会在 Gateway 网关上创建一个待处理的设备配对请求（role: node）。 通过以下方式批准： 
openclaw devices list
openclaw devices approve <requestId>
在严格控制的节点网络中，Gateway 网关操作员可以显式选择从受信任 CIDR 自动批准首次节点配对： 
{
  gateway: {
    nodes: {
      pairing: {
        autoApproveCidrs: ["192.168.1.0/24"],
      },
    },
  },
}
默认情况下这处于禁用状态（autoApproveCidrs 未设置）。它仅适用于来自 Gateway 网关信任的客户端 IP、没有请求权限范围的新 role: node 配对。操作员/浏览器客户端、Control UI、WebChat，以及角色、权限范围、元数据或公钥升级仍然需要手动批准。 如果节点使用已更改的认证详情（角色/权限范围/公钥）重试配对，之前的待处理请求会被取代，并创建新的 requestId。批准前请再次运行 openclaw devices list。 节点主机会将其节点 ID、令牌、显示名称和 Gateway 网关连接信息存储在 OpenClaw 状态目录中的 node.json（默认是 ~/.openclaw，或设置了 $OPENCLAW_STATE_DIR 时使用该目录）。

​
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 转发会复用该已存储的计划，因此批准请求创建后对 command/cwd/session 字段的编辑会被拒绝，而不是改变节点实际执行的内容。

​
相关