跳转至

节点主机

远程节点主机(system.run)

当你的 Gateway 运行在一台机器上,而你想在另一台机器上执行命令时,请使用节点主机。模型仍然与网关通信;当选择 host=node 时,网关会将 exec 调用转发到节点主机。

角色 职责
网关主机 接收消息、运行模型、路由工具调用。
节点主机 在节点机器上执行 system.run/system.which。
审批 在节点主机上通过 ~/.openclaw/state/openclaw.sqlite#exec_approvals_config 强制执行。

审批说明:

  • 受审批支持的节点运行会绑定精确的请求上下文。在审批前,exec 路径会准备一个规范的 systemRunPlan;一旦获批,网关转发的是该已存储的计划,而不是之后调用者编辑过的 command/cwd/session 字段,并在运行前重新验证工作目录。
  • 对于直接的 shell/运行时文件执行,OpenClaw 也会尽力绑定一个具体的本地文件操作数;如果该文件在执行前发生变化,则拒绝运行。
  • 如果 OpenClaw 无法为解释器/运行时命令精确识别出一个具体的本地文件,受审批支持的执行将被拒绝,而不是假装具备完整的运行时覆盖。对于更广泛的解释器语义,请使用沙箱、独立主机,或显式的可信允许列表/完整工作流。

无法托管节点的网关部署

即使节点托管不可用,Gateway 仍可对浏览器用户保持健康状态。在接入节点之前,请在 Gateway 上运行 openclaw doctor,并检查以下前置条件:

  • 机器身份验证: Tailscale 身份头不会对节点角色连接进行身份验证。在 gateway.auth.mode: "trusted-proxy" 下,新节点也无法提供代理的用户身份头。要使用共享令牌,请切换到令牌模式并使用 SecretRef 配置 gateway.auth.token;trusted-proxy 模式会拒绝混合令牌配置。trusted-proxy Gateway 只能为纯回环/直连调用者使用 gateway.auth.password。参见 trusted-proxy 混合令牌配置。
  • 节点接入 URL: 若仅使用默认的 gateway.bind: "loopback" 且没有宣告的端点,openclaw devices join-code 会报告 Gateway 仅绑定到回环地址,并建议将 gateway.publicOrigin 作为主要修复方式。对于公共 HTTPS 入口,请将其设置为代理可达的源。现有的 Tailscale Serve、gateway.remote.url、绑定派生地址,以及配对专用的 plugins.entries.device-pair.config.publicUrl 覆盖仍保持其优先级;publicOrigin 提供回环回退。远程 join URL 需要 TLS;仅启用 LAN 绑定并不能启用明文远程 join URL。显式配置的回环端点可以产生 HTTP join URL,但加入机器必须能到达该回环端点,例如通过本地隧道。明文 LAN 配对可以直接使用设置码。
  • 节点接入支持: join-code 的创建和 /j 兑换是 Gateway 的核心操作。它们不需要启用 device-pair 插件,即使其保留的 publicUrl 配置字段可以提供端点。有关打印的 npx openclaw connect <url> 命令,请参见 加入码。
  • 设备会话运行时: 配对设备运行器支持嵌入式 OpenClaw 运行时以及明确授权的 Codex remote-exec;ACPX 路由无法调度到配对设备。Codex 需要在 gateway.nodes.commands.allow 中包含 codex.exec-server.stdio.v1,再加上其常规的配对和调用审批。运行时策略属于 provider/model 路由,而不是那些被忽略的整个智能体运行时键。多智能体名册还必须设置 agents.ownership: "explicit"。参见 Codex 配对设备放置 和 运行时策略。
  • 边缘路由: 当反向代理或访问边缘位于 Gateway 前端时,节点必须在 join 请求、其主 Gateway WebSocket 和 worker WebSocket 上满足边缘身份验证。请保持 /__openclaw__/worker 的 WebSocket 升级启用。你也可以将 /j/* 和 /__openclaw__/worker 从边缘身份验证中豁免,因为这两个路由都强制执行自己的短期凭据。参见 worker 协议。

对于由 Cloudflare Access 前置的 Gateway:

  1. 在 Cloudflare Zero Trust 中,创建一个 Access 服务令牌。当 Cloudflare 显示 Client ID 和 Client Secret 时,请复制它们。
  2. 在保护 Gateway 的 Access 应用程序上添加一个接受该令牌的 Service Auth 策略。如果 /j/* 和 /__openclaw__/worker 是单独的 Access 应用程序,请将同一策略添加到两者。
  3. 在节点上,提供传统的环境变量回退并连接:
export CF_ACCESS_CLIENT_ID="<client-id>"
export CF_ACCESS_CLIENT_SECRET="<client-secret>"
openclaw connect https://gateway.example/j/<code> --service

规范的节点连接键是 gateway.cloudflareAccess.clientId 和 gateway.cloudflareAccess.clientSecret;两者都接受 SecretInput 值。上面的环境变量回退会将这些键作为环境 SecretRef 持久化,而不是复制明文。对于已安装的节点,OpenClaw 会将环境值存储在受管服务环境文件中,而不是内联到 launchd、systemd 或 Task Scheduler 定义中。解析后的值绑定到已配置的 Gateway 源,并且不会跨重定向跟随。在明文 http:// 或 ws:// 路由上,OpenClaw 会在解析前拒绝配对;无凭据的回环和私有网络明文行为保持不变。

启动节点主机(前台)

在节点机器上:

openclaw node run --host <gateway-host> --port 18789 --display-name "Build Node"

如需一键设置,请从 Control UI 的 Devices 页面创建节点主机设置链接,然后在节点机器上运行其可复制命令:

openclaw node run --pair "oc-pair://<setup-code>"

该链接为一次性使用,10 分钟后过期。它提供端点、引导令牌、TLS 模式以及可用的证书固定信息。显式的网关标志会覆盖相应的 --pair 值。由管理员铸造的引导注册会批准该设备及其首次声明的命令面,包括声明的 system.run 和 system.which。后续的命令、能力或权限扩展仍会生成审批请求。网关命令策略和节点主机的 exec 审批 仍然适用。本地 exec 审批默认为 full,且 ask: "off";如果该访问权限过宽,请在使用链接前对其进行配置。另请参阅 节点配对。

node run 还接受 --pair、--context-path(Gateway WS 上下文路径)、--tls、--tls-fingerprint <sha256> 和 --node-id(覆盖旧版客户端实例 ID;这不会重置配对)。在 macOS 上,传入 --share-installed-apps 以通告 device.apps;共享默认关闭。使用 --no-share-installed-apps 可禁用之前已保存的选入设置。

传入 --session-host 可为该前台进程启用 worker 托管,而无需更改已保存的偏好设置。自动重启会保留此选择。

通过 SSH 隧道远程连接网关(回环绑定)

如果 Gateway 绑定到回环地址(gateway.bind=loopback,本地模式下的默认值),远程节点主机将无法直接连接。请创建 SSH 隧道,并将节点主机指向隧道的本地端。

示例(节点主机 -> 网关主机):

# Terminal A (keep running): forward local 18790 -> gateway 127.0.0.1:18789
ssh -N -L 18790:127.0.0.1:18789 user@gateway-host

# Terminal B: export the gateway token and connect through the tunnel
export OPENCLAW_GATEWAY_TOKEN="<gateway-token>"
openclaw node run --host 127.0.0.1 --port 18790 --display-name "Build Node"

说明:

  • openclaw node run 支持令牌或密码认证。
  • 优先使用环境变量:OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
  • 配置回退为 gateway.auth.token / gateway.auth.password。
  • 在本地模式下,节点主机会有意忽略 gateway.remote.token / gateway.remote.password。
  • 在远程模式下,gateway.remote.token / gateway.remote.password 根据远程优先级规则生效。
  • 如果配置了活动的本地 gateway.auth.* SecretRefs 但未能解析,节点主机认证将默认失败(fail closed)。
  • 节点主机认证解析仅接受 OPENCLAW_GATEWAY_* 环境变量。

限制节点命令面

将 --commands <ids> 传给 openclaw node run、openclaw node install 或 openclaw connect,以仅通告一个显式的、以逗号分隔的精确命令 ID 列表。例如,Session Share 节点可以在不暴露执行或其他机器能力的情况下发布会话:

openclaw connect <join-url> --service \
  --commands openclaw.sessions.list.v1,openclaw.sessions.read.v1

该标志可重复使用。允许列表会保存到节点的持久化机器状态中,包括已安装服务;在后续启动时省略该标志将保留已保存的列表。节点仅通告既可用又在允许列表中的命令,且只通告其所需的能力。如果没有所请求的命令可用,启动将失败。Gateway 配对审批会精确显示所声明的命令;Gateway 命令策略仍适用于调用。

显式允许列表还会禁用计算机使用、技能扫描与发布、插件工具发布、MCP 服务器以及 worker 托管。允许列表不会启用已禁用的插件,也不会让不可用的命令变为可用。

使用前台的 openclaw node run --all-commands 或已安装服务的 openclaw node install --force --all-commands 可恢复完整的默认命令面。使用 openclaw connect 注册时,添加 --all-commands,并可选择添加 --service。这会永久移除已保存的允许列表,并替换服务的 --commands 参数。请勿将 --all-commands 与 --commands 结合使用。

启动节点主机(服务)

openclaw node install --host <gateway-host> --port 18789 --display-name "Build Node"
openclaw node start
openclaw node restart

node install 还接受 --context-path、--tls、--tls-fingerprint、--node-id(仅限旧版客户端实例 ID)、--share-installed-apps / --no-share-installed-apps、--runtime <node|bun>(默认:node)以及用于重新安装的 --force。Bun 需要 1.4+ 版本,且具备 WAL 重置安全的 node:sqlite,并且是显式选入的;Node 仍是推荐选项。node status、node stop 和 node uninstall 也可用。

节点关闭会等待插件可用性监视器和正在进行的计算机执行完成清理,并报告这些清理操作的失败。如果某条命令报告 Node disconnect cleanup failed,请重新连接节点以重试断开清理,然后再发送下一条命令。

会话主机工作区权限

使用 --session-host 启动的节点会在通告会话容量之前检查工作区暂存。在 Unix 上,状态目录(OPENCLAW_STATE_DIR 或 ~/.openclaw)及其规范的祖先目录必须通过文件系统所有者的检查。没有粘滞位保护且组可写或全局可写的祖先目录会阻止会话托管,即使 node-host 目录本身是私有的也是如此。

节点日志和 environments.list 会指出有问题的目录及补救方法:在节点上运行 chmod go-w '<reported-path>',然后重启节点主机。在更改共享目录权限之前请先进行审查;或者,将节点状态移动到私有目录下。OpenClaw 不会更改祖先目录权限,也不会绕过暂存检查。受信任的粘滞系统临时目录仍然受支持。

会话宿主(session-host)故障不会断开节点连接,也不会禁用其桌面及其他可用命令。environments.list 会保持已连接节点可用,报告 sessionHost: false 及托管诊断信息,并在托管问题修复之前拒绝会话放置。

仅当 Gateway 通告 node-worker-host-diagnostics-v1 时,才会发布禁用宿主的原因。较旧的 Gateway 仍会收到禁用托管状态;原因会保留在节点日志中。如果启动后权限发生变化,工作区转移也会报告相同的修复措施。

自动节点更新

打包的无头(headless)节点默认每小时检查一次更新,前台模式和服务模式均如此。它们会准备一个单独的运行时,等待所有节点工作空闲,然后以相同的身份、配对和启动选项重启并重新连接。节点更新不会替换全局 CLI 包或同置的 Gateway。自动激活至少间隔 12 小时,繁忙的工作可以无限期推迟更新。

在节点上设置 nodeHost.autoUpdate.enabled: false 可选择退出。共享的 update.checkOnStart: false 和 OPENCLAW_NO_AUTO_UPDATE=1 退出选项同样适用。源码检出、原生应用节点、私有 worker、dev 和 extended-stable 安装不会自动应用更新。需要数据库迁移的版本会交由正常更新流程处理。有关空闲工作规则和配置,请参阅无头节点更新。

配对 + 命名

在 Gateway 主机上,批准设备请求:

openclaw devices list
openclaw devices approve <deviceRequestId>

如果节点使用更改后的身份验证详细信息重试,请重新运行 openclaw devices list 并批准当前的 requestId。

在设备审批待处理期间,节点会持续重新连接,指数退避上限为 30 秒。批准后,其下一次重新连接会创建单独的命令面请求。在 Gateway 上:

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes describe --node <id|name|ip>

如果较旧的客户端已经报告重新连接已暂停,请使用 openclaw node restart 重启已安装的节点,或者停止并重新运行一次其前台 openclaw node run 命令。

设备请求 ID 与节点请求 ID 是不同的。初始未获批的命令面没有任何有效命令。SSH 验证注册和 bootstrap 注册可以自动批准第一个命令面;仅凭受信任网络的设备审批则不能。后续扩展需要审批,而先前已批准且当前仍被声明并允许的命令仍可运行。Gateway 命令策略 和节点本地 exec 审批仍是相互独立的关卡。

命名选项:

  • 在 openclaw node run / openclaw node install 上使用 --display-name(与客户端实例 ID 和 Gateway 连接元数据一起持久化在共享的 nodeHost.config SQLite 机器状态值中)。
  • openclaw nodes rename --node <id|name|ip> --name "Build Node"(Gateway 覆盖)。

无头身份状态

无头节点在共享 SQLite 中维护三条独立的状态记录:

  • ~/.openclaw/state/openclaw.sqlite(config_machine_state,键 nodeHost.config):客户端实例 ID、显示名称和 Gateway 连接元数据。
  • ~/.openclaw/state/openclaw.sqlite(device_identities,键 primary):已签名的设备密钥对和派生出的加密设备 ID。
  • ~/.openclaw/state/openclaw.sqlite(device_auth_tokens):按加密设备 ID 和角色索引的已配对设备身份验证令牌。

对于已签名的节点,Gateway 使用加密设备 ID 进行配对和节点路由。客户端实例 ID 仅是连接元数据。因此,更改 --node-id 或迁移已退役的 node.json 不会重置配对。有关支持的撤销并重新配对流程和升级说明,请参阅身份与配对状态。

已退役的 identity/device.json 和 identity/device-auth.json 文件是 Doctor 管理的迁移输入。停止节点宿主并运行 openclaw doctor --fix;Doctor 会在删除旧文件之前将其中的行导入 SQLite 并验证。

无头节点和 macOS 应用 worker 在准备能力之前会检查此状态。存在待处理的设备身份验证或 exec 审批,或者缺少规范身份却留有已退役身份数据时,需要运行 Doctor;启动过程会保留这些输入,不会创建替换密钥或导入执行策略。有效的规范身份会优先于过期的 identity/device.json 数据。

系统命令(节点宿主 / macOS 节点)

macOS 节点和无头节点宿主均暴露 system.run.prepare、system.run、system.which 和 system.execApprovals.get/set;macOS 节点还暴露 system.notify。

示例:

openclaw nodes notify --node <idOrNameOrIp> --title "Ping" --body "Gateway ready"
openclaw nodes invoke --node <idOrNameOrIp> --command system.which --params '{"bins":["git"]}'

说明:

  • system.run 在载荷中返回 stdout/stderr/退出码。
  • Shell 执行通过 exec 工具进行,使用 host=node;独立的 nodes.run 执行路径已在 2026.3.31 中移除。nodes 仍是显式节点命令的直接 RPC 命令面。
  • nodes invoke 不暴露 system.run 或 system.run.prepare;这些仅保留在 exec 路径上。
  • exec 路径读取节点策略并准备规范的 systemRunPlan。在 full/off 执行模式下,会解析工作目录别名,而不会额外添加仅限审批的脚本检查。当调用方或节点策略要求审批绑定时,更严格的路径和脚本检查仍然有效。一旦审批通过,gateway 转发的是该已存储的计划,而不是调用方之后编辑的任何 command/cwd/session 字段。
  • system.notify 遵循 macOS 应用的通知权限状态;支持 --priority <passive|active|timeSensitive> 和 --delivery <system|overlay|auto>。
  • 无法识别的节点 platform / deviceFamily 元数据会使用保守的默认允许列表,其中排除 system.run 和 system.which。如果你确实需要在未知平台上使用这些命令,请通过 gateway.nodes.commands.allow 显式添加。
  • system.run 请求支持 cwd、env 映射、timeoutMs 和 needsScreenRecording —— 这些是 exec 路径上携带的请求载荷字段(见上文),不是 nodes invoke CLI 标志。
  • 对于 shell 包装器(bash|sh|zsh ... -c/-lc),请求范围内的 env 值会被缩减为显式允许列表(TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR)。
  • 在允许列表模式下,对于始终允许(allow-always)的决策,已知的调度包装器(env、flock、nice、nohup、stdbuf、timeout)会持久化内部可执行文件路径,而不是包装器路径。如果取消包装不安全,则不会自动持久化任何允许列表条目。
  • 在允许列表模式下,Windows 节点宿主上通过 cmd.exe /c 运行的 shell 包装器需要审批(仅允许列表条目不会自动允许包装器形式)。
  • 节点宿主会忽略 env 对象中的 PATH 覆盖,并在运行命令之前剥离一大组持续维护的解释器/shell 启动变量(例如 NODE_OPTIONS、PYTHONPATH、BASH_ENV、DYLD_*、LD_*)。如果你需要额外的 PATH 条目,请配置节点宿主服务环境(或将工具安装到标准位置),而不是通过 env 传递 PATH。
  • 在 macOS 节点模式下,system.run 由 macOS 应用中的 exec 审批(设置 → Exec approvals)控制。Ask/allowlist/full 模式的行为与无头节点宿主相同;被拒绝的提示会返回 SYSTEM_RUN_DENIED。
  • 在无头节点宿主上,system.run 由本地 SQLite exec 审批行控制;具体到 macOS,请参阅下方无头节点宿主下的 exec-host 路由环境变量。

无头节点主机(跨平台)

OpenClaw 可以运行 无头节点主机(无界面),它连接到 Gateway WebSocket 并暴露 system.run / system.which。这在 Linux/Windows 上,或在与服务器并行运行最小节点时很有用。

启动方式:

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

注意事项:

  • 仍需要设备配对和命令面审批;请按照 配对 + 命名 完成两个阶段。
  • 客户端实例元数据、签名设备身份和配对认证使用独立的状态记录;参见 无头身份状态。
  • 执行审批通过本地强制执行,路径为 ~/.openclaw/state/openclaw.sqlite#exec_approvals_config(参见 执行审批)。
  • 在 macOS 上,无头节点主机默认在本地执行 system.run。设置 OPENCLAW_NODE_EXEC_HOST=app 可要求使用配套应用的执行主机,且无本地回退。OPENCLAW_NODE_EXEC_FALLBACK 不会改变当前路由。
  • 当 Gateway WS 使用 TLS 时,添加 --tls / --tls-fingerprint。

Mac 节点模式

  • macOS 菜单栏应用作为节点连接到 Gateway WS 服务器(因此 openclaw nodes … 可针对此 Mac 使用)。
  • 在远程模式下,应用会为 Gateway 端口打开 SSH 隧道,并连接到 localhost。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw