跳转至

节点主机

远程节点主机（system.run）

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

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

审批说明：

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

无法托管节点的 Gateway 部署

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

  • 机器身份验证： Tailscale 身份头不会为节点角色连接进行身份验证。在 gateway.auth.mode: "trusted-proxy" 中，新节点也无法提供代理的用户身份头。若要使用共享 token，请切换到 token 模式，并使用 SecretRef 配置 gateway.auth.token；trusted-proxy 模式会拒绝混合 token 配置。trusted-proxy Gateway 只能将 gateway.auth.password 用于干净的 loopback/直接调用方。参见 trusted-proxy 混合 token 配置。
  • 节点接入 URL： 如果只有默认的 gateway.bind: "loopback" 且没有通告端点，openclaw devices join-code 会报告 Gateway 仅绑定到 loopback，并建议将 gateway.publicOrigin 作为主要修复方式。对于公共 HTTPS 入口，请将其设置为代理可到达的 origin。现有的 Tailscale Serve、gateway.remote.url、由 bind 派生的地址，以及配对专用的 plugins.entries.device-pair.config.publicUrl 覆盖仍保留其优先级；publicOrigin 提供 loopback 回退。远程加入 URL 需要 TLS；仅启用 LAN bind 不会启用明文远程加入 URL。显式配置的 loopback 端点可以生成 HTTP 加入 URL，但加入机器必须能够到达该 loopback 端点，例如通过本地隧道。明文 LAN 配对可以直接使用设置代码。
  • 节点接入支持： 加入代码创建和 /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 路由上，而不是被忽略的整个 agent 运行时键。多 agent 名册还必须设置 agents.ownership: "explicit"。参见 Codex 配对设备放置 和 运行时策略。
  • 边缘路由： 当反向代理或访问边缘位于 Gateway 前面时，节点必须在加入请求、其主要 Gateway WebSocket 以及 worker WebSocket 上满足边缘身份验证。请保持 /__openclaw__/worker 的 WebSocket 升级启用。你也可以将 /j/* 和 /__openclaw__/worker 从边缘身份验证中豁免，因为这两个路由都强制使用自己的短期凭据。参见 worker 协议。

对于由 Cloudflare Access 前置的 Gateway：

  1. 在 Cloudflare Zero Trust 中，创建一个 Access 服务 token。当 Cloudflare 显示其 Client ID 和 Client Secret 时，请复制它们。
  2. 在保护 Gateway 的 Access 应用上，添加一个接受该 token 的 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 值。上述环境回退会将这些键持久化为 env SecretRefs，而不是复制的明文。对于已安装的节点，OpenClaw 会将环境值存储在托管服务环境文件中，而不是内联在 launchd、systemd 或 Task Scheduler 定义中。解析后的值绑定到已配置的 Gateway origin，并且不会跨重定向跟随。对于明文 http:// 或 ws:// 路由，OpenClaw 会在解析前拒绝该键值对；无凭据的 loopback 和私有网络明文行为保持不变。

启动节点主机（前台）

在节点机器上：

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

对于一键粘贴设置，请从 Control UI 的设备页面创建 节点主机 设置链接，然后在节点机器上运行其可复制的命令：

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

该链接为一次性使用，并在 10 分钟后过期。它会在可用时提供端点、bootstrap Token、TLS 模式和证书固定。显式 Gateway 标志会覆盖对应的 --pair 值。管理员签发的 bootstrap 注册会批准设备及其首次声明的命令面，包括声明时的 system.run 和 system.which。后续的命令、能力或权限扩展仍会创建审批请求。Gateway 命令策略和节点主机的执行审批仍然适用。本地执行审批默认为 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 绑定到回环地址（gateway.bind=loopback，本地模式下的默认值），远程节点主机无法直接连接。请创建 SSH 隧道，并将节点主机指向隧道的本地端。

示例（节点主机 -> Gateway 主机）：

# 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 支持 Token 或密码身份验证。
  • 优先使用环境变量：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，节点主机身份验证将失败关闭。
  • 节点主机身份验证解析仅认可 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）及其规范父目录必须满足文件系统所有者的检查。没有 sticky 保护的组可写或全局可写父目录会阻止 会话托管，即使 node-host 目录本身是私有的。

节点日志和 environments.list 会标识出有问题的目录以及补救措施：在节点上运行 chmod go-w '<reported-path>'，然后重启节点主机。在更改共享目录权限之前，请先审查这些权限；或者，将节点状态移动到私有目录下。OpenClaw 不会更改父目录权限或绕过暂存检查。受信任的 sticky 系统临时目录仍受支持。

A session-host failure does not disconnect the node or disable its desktop and other available commands. environments.list keeps a connected node available, reports sessionHost: false and the hosting diagnostic, and refuses session placement until the hosting problem is repaired.

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

Disabled-host reasons are published only when the Gateway advertises node-worker-host-diagnostics-v1. Older Gateways still receive disabled hosting; the node log retains the reason. Workspace transfers also report the same remediation if permissions change after startup.

禁用主机原因仅在 Gateway 通告 node-worker-host-diagnostics-v1 时发布。旧版 Gateway 仍会收到禁用托管；节点日志会保留原因。工作区迁移也会在启动后权限发生变化时报告相同的修复措施。

自动节点更新

打包的无头节点默认每小时检查一次更新，前台模式和服务模式均如此。它们会准备一个独立的运行时，等待所有节点工作空闲，然后以相同的身份、配对和启动选项重启并重新连接。节点更新不会替换全局 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 验证和引导注册可以自动批准第一个表面；仅可信网络设备批准则不能。后续扩展需要批准，而先前已批准且仍保持声明和允许状态的命令仍可以运行。Gateway 命令策略 和节点本地 exec 批准仍然是独立的关卡。

命名选项：

  • openclaw node run / openclaw node install 上的 --display-name（持久化在共享的 nodeHost.config SQLite 机器状态值中，与客户端实例 ID 和 Gateway 连接元数据一起）。
  • 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 在 payload 中返回 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 路径上携带的请求 payload 字段（见上文），而不是 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 可以运行一个无头节点主机（无 UI），它连接到 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