跳转至

openclaw node

运行一个无头节点主机，它连接到 Gateway WebSocket，并默认在本机上暴露 system.run / system.which。使用 --commands 可以限制通告的命令面，例如限制为只读会话共享。

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

为什么使用节点主机？

当你希望智能体在其他机器上运行命令，而不需要在那些机器上安装完整的 macOS 伴侣应用时，请使用节点主机。

常见用例：

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

执行仍受节点主机上的执行审批和每个智能体允许列表保护，因此你可以保持命令访问范围明确且显式。

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

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

浏览器代理（零配置）

如果节点上未禁用 browser.enabled，节点主机会自动通告一个浏览器代理。这让智能体可以在该节点上使用浏览器自动化，而无需额外配置。

默认情况下，代理会暴露节点的正常浏览器配置文件面。如果你设置 nodeHost.browserProxy.allowProfiles，代理将变得受限：非允许列表中的配置文件目标会被拒绝，并且持久配置文件的创建/删除路由会通过代理被阻止。

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

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

运行（前台）

对于一次粘贴式入门，请使用openclaw connect。它接受一次性加入 URL 或与 --pair 相同的设置代码形式，然后运行此节点主机运行时。

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

或者粘贴来自 Control UI 设备页面的短生命周期节点设置链接：

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

选项：

  • --host <host>: Gateway WebSocket 主机（默认：127.0.0.1）
  • --pair <code-or-url>: 从设置代码或 oc-pair:// URL 读取 Gateway 端点、引导令牌、TLS 模式以及可选证书固定。显式 Gateway 标志会覆盖来自 --pair 的值。
  • --pair-if-needed <code-or-url>: 使用与 --pair 相同的端点选项，但在存在已保存的设备令牌时优先使用它。监督进程可以在配对后重启同一命令。不能与 --pair 组合使用。
  • --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>: 覆盖节点显示名称
  • --session-host: 为此前台进程托管 worker 会话，而不更改已保存的 worker 托管偏好
  • --commands <ids>: 持久化一个精确的逗号分隔命令允许列表（可重复）；仅通告可用匹配项及其所需能力。禁用计算机使用、技能、插件工具、MCP 服务器和 worker 托管。省略该标志会保留已保存的列表。
  • --all-commands: 通告完整的默认命令面，并忘记任何已保存的 --commands 允许列表。不能与 --commands 组合使用。
  • --share-installed-apps: 在 macOS 上，通过 device.apps 通告已安装应用
  • --no-share-installed-apps: 禁用已安装应用共享

节点主机的 Gateway 认证

--pair 在首次连接时使用一个 10 分钟有效的一次性引导令牌。配对后，重连使用持久设备凭据。管理员签发的引导注册会批准该设备及其首次声明的命令面，包括已声明的 system.run。后续的命令、能力或权限扩展仍需要 openclaw nodes approve。Gateway 命令策略和节点主机的执行审批仍是独立的关卡。本地执行审批默认为 full，且 ask: "off"；如果该访问范围过宽，请在使用设置链接前配置它们。node install --pair 被有意设为不可用，因为短生命周期的 bearer 设置链接不应持久化到服务参数中。

对于受管理的前台进程，--pair-if-needed 会在重启之间复用原生设备令牌存储；它不会保留单独的注册标记。请保留节点状态目录。设置代码过期后，只要已保存的身份和节点令牌存在，并且每个选定的 Gateway 端点都与已保存的 Gateway 范围匹配，节点仍可以重连。已过期的引导令牌绝不会被发送。已过期的设置代码不能注册新的状态目录，也不能替换已吊销的设备令牌；需要时请提供新的代码。显式 --pair 仍会拒绝已过期的设置代码。

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

  • 首先检查 OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD。
  • 当使用已配对的节点凭据重新连接到已保存的 Gateway 端点时，使用该凭据并跳过配置认证。显式的环境变量覆盖仅提供其自身凭据。
  • 否则，应用本地配置回退：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_* 环境变量。

已保存的端点包含其主机、端口、TLS 模式和上下文路径。更改其中任何一项都会恢复正常的配置/环境变量认证解析。因此，节点可以与本地 Gateway 共享其状态目录，同时重新连接到另一个已配对的 Gateway，而无需在重启时发送本地 Gateway 的密码。

对于位于 Cloudflare Access 后面的 Gateway，请在 openclaw connect、openclaw node run 或 openclaw node install 之前同时设置 CF_ACCESS_CLIENT_ID 和 CF_ACCESS_CLIENT_SECRET。节点会将环境变量 SecretRef 存储在其规范的 gateway.cloudflareAccess.clientId 和 clientSecret 连接键下。已安装的服务会将这些值保存在受管服务环境文件中，而不是服务参数或内联 supervisor 定义中。Access 凭据要求 HTTPS/WSS；明文 HTTP/WS 会在 SecretRef 解析之前失败，而不带凭据的明文节点路由保持不变。参见 无法托管节点的 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）。

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
  • --no-tls：即使本地 Gateway 配置启用了 TLS，也强制使用明文 Gateway 连接
  • --tls-fingerprint <sha256>：预期的 TLS 证书指纹（sha256）
  • --node-id <id>：覆盖存储在共享 SQLite 状态中的客户端实例 ID（不会重置配对）
  • --display-name <name>：覆盖节点显示名称
  • --commands <ids>：为已安装的服务持久化命令允许列表（可重复），限制与 node run 相同。
  • --all-commands：通告完整的默认命令面，并忘记任何已保存的 --commands 允许列表。不能与 --commands 组合使用。
  • --share-installed-apps：在 macOS 上，通过 device.apps 通告已安装的应用程序
  • --no-share-installed-apps：禁用已安装应用程序共享
  • --runtime <node|bun>：服务运行时（默认：node）。Bun 1.4+ 且具备 WAL-reset-safe node:sqlite 是显式选择；仍推荐 Node。
  • --runtime-path <path>：固定一个通过运行时能力检查的绝对 Node/Bun 可执行文件。
  • --force：如果已安装，则重新安装/覆盖

显式固定会保存在机器状态元数据中，并在重启和强制重新安装之间保留。使用另一个 --runtime-path 替换它， 或使用不带 --runtime-path 的 openclaw node install --runtime node --force 返回自动选择。不可用或不支持的固定会失败，而不是静默选择另一个运行时。对包含空格的路径加引号。

将 OPENCLAW_WRAPPER 设置为可执行包装文件，以代替所选运行时和 CLI 入口点。包装器会接收 node run 和 连接参数；它必须启动 OpenClaw 并转发这些参数。

如果安装报告运行时探测失败，请检查错误中提到的可执行文件和工作目录。例如，使用 runuser 切换用户时，请先切换到目标用户可以读取的目录。探测失败并不意味着已安装的 Node 版本不受支持；升级 建议仅针对缺失或不受支持的运行时。

Linux（systemd 用户服务）： 安装后运行 sudo loginctl enable-linger <user>。 如果没有启用 lingering，systemd --user 会在你最后一个 SSH 会话结束时拆除节点服务， 因此节点会在注销后静默离线。 当检测到 lingering 已禁用时，openclaw node install 会打印此警告。

管理服务：

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

使用 openclaw node run 运行前台节点主机（无服务）。 要删除已保存的命令允许列表，请在前台运行 openclaw node run --all-commands ，或使用 openclaw node install --force --all-commands 重新安装服务。重置是持久的； 替换后的服务参数不再携带 --commands。

服务命令接受 --json 以输出机器可读格式。 当没有安装受管节点服务时，node start 和 node restart 会打印安装提示并以非零状态退出；请先运行 openclaw node install。停止一个不存在的服务仍然是成功的空操作。

节点主机在进程内重试 Gateway 重启和网络关闭。如果 Gateway 报告终止性 token/密码/引导身份验证暂停，节点主机会记录关闭详情并以非零状态退出，以便 launchd/systemd/Task Scheduler 使用新的配置和凭据重启它。在设备配对待处理期间，节点会持续重连，采用指数退避，上限为 30 秒，并在批准后自动连接。

自动更新

长时间运行的打包 node run 进程和已安装的节点服务默认每小时检查一次更新。新版本会在独立的节点运行时中准备，同时保留全局 CLI 包和同位置的 Gateway 不变。激活会等待命令、终端、worker、插件工作、待处理输出和清理均处于空闲状态。然后节点会带着现有身份、配对、设置和启动选项重启。自动激活之间至少间隔 12 小时；没有会中断繁忙工作的截止时间。

在节点机器上使用以下命令禁用：

openclaw config set nodeHost.autoUpdate.enabled false

update.checkOnStart: false 和 OPENCLAW_NO_AUTO_UPDATE=1 也会禁用节点自动更新。Gateway 的 update.auto.enabled 偏好设置是独立的。源码检出、原生应用节点、私有 worker、dev 和 extended-stable 安装不会自动应用。需要数据库迁移的版本会推迟到常规更新流程。参见 无头节点更新。

配对

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

当 Gateway 主机可以非交互式地 SSH 到节点主机（同一用户、受信任的主机密钥）时，待处理请求会被自动批准：Gateway 会通过 SSH 在节点主机上运行 openclaw node identity --json，并在设备密钥完全匹配时批准。此功能默认开启；有关要求和禁用方法（gateway.nodes.pairing.sshVerify: false），参见 SSH 验证设备自动批准。

否则，请通过以下方式手动批准：

openclaw devices list
openclaw devices approve <deviceRequestId>

设备批准允许连接；命令面需要单独批准。在设备批准待处理期间，节点会持续重连，采用指数退避，上限为 30 秒。批准后，其下一次重连会在 Gateway 上创建一个独立的命令面请求：

openclaw nodes pending
openclaw nodes approve <nodeRequestId>
openclaw nodes describe --node <idOrNameOrIp>

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

设备请求 ID 和节点请求 ID 是不同的。初始未批准的命令面没有有效命令。SSH 验证和引导注册可以自动批准第一个命令面；后续扩展需要批准。在扩展等待期间，之前已批准且仍然声明并被允许的命令保持有效。

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

openclaw node identity --json

它会打印 state/openclaw.sqlite 中 primary 行的设备 ID 和公钥，并且永远不会创建数据库或新身份。

在严格管控的节点网络中，Gateway 操作员可以明确选择自动批准来自受信任 CIDR 的首次节点配对：

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

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

受信任网络的设备批准不会批准节点的命令面。检查 openclaw nodes pending 并批准独立的命令面请求。

如果节点使用更改后的身份验证详情（role/scopes/公钥）重试配对，则之前的待处理请求会被取代，并创建新的 requestId。批准前请再次运行 openclaw devices list。

身份与配对状态

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

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

node.list 和 node.describe 中的 gatewayLocal 表示与 Gateway 状态目录中的主要设备身份完全匹配。覆盖 --node-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 行，然后删除旧文件。节点启动， 包括 macOS 应用的 worker，会保留这些输入，交由 Doctor 处理。待处理的设备认证或 exec 批准会在能力准备之前阻止启动。 缺少规范身份，同时存在已弃用的身份数据或中断的导入声明，也会在创建新密钥之前阻止启动。当旧版本重新创建 identity/device.json 时， 现有有效的规范身份仍具有权威性；Doctor 负责清理该过期文件。请保持 state/openclaw.sqlite 为私有； 其中包含设备密钥对和认证令牌。

执行批准

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

  • $OPENCLAW_STATE_DIR/state/openclaw.sqlite#exec_approvals_config，或者 当变量未设置时为 ~/.openclaw/state/openclaw.sqlite#exec_approvals_config
  • 执行批准
  • 从 Gateway 使用 openclaw approvals get --node <id|name|ip> 检查， 或使用 openclaw approvals set --node <id|name|ip> --file <path> 替换；参见 批准 CLI。

对于已批准的异步节点 exec，OpenClaw 会在提示之前准备一个规范的 systemRunPlan。 之后已批准的 system.run 转发会复用该存储的计划，因此在批准请求创建之后对 command/cwd/session 字段的编辑会被拒绝， 而不是改变节点实际执行的内容。

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