`openclaw node` 无头节点主机：CLI 参考与源码级解析

openclaw node无头节点主机：CLI 参考与源码级解析

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw

导读

openclaw node是 OpenClaw 的无头节点主机（headless node host）命令行入口，它让 Agent 能够通过 Gateway 在本机之外的其他机器上执行system.run/system.which，而无需在这些机器上安装完整的 macOS 伴侣应用。本文将完整梳理node run/node install的全部参数、网关鉴权规则、配对与命令面审批流程、身份状态存储，并结合src/cli/node-cli/下的真实实现源码解释底层行为，帮助你搭建一个安全、可审计的远程执行节点。

何时需要节点主机

当你的 Gateway 运行在一台机器上，而你想让 Agent在网络中的其他机器上执行命令时，节点主机是标准方案。典型场景包括：

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

执行仍然受执行审批（exec approvals）和节点主机上的按 Agent 白名单约束，因此命令访问范围可以保持显式、受限。角色分工参考 docs/nodes/node-host.md 中的职责表：Gateway 主机负责收消息、跑模型、路由工具调用；节点主机负责在节点机器上执行system.run/system.which；审批则通过节点上的~/.openclaw/state/openclaw.sqlite#exec_approvals_config本地强制。

在 macOS 上，菜单栏应用已把该节点主机运行时内嵌进自身的节点连接，并增加原生 Mac 能力。只有当你刻意想要一个不带应用的纯无头节点时才需要手动运行openclaw node run；同时运行两者会为同一台机器创建两个节点身份。

前台运行：openclaw node run

最直接的启动方式是前台运行：

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

也可以从 Control UI 的 Devices 页面复制短时有效的节点设置链接：

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

--pair接受设置码或oc-pair://URL，从中读取 Gateway 端点、引导令牌、TLS 模式和可选的证书指纹；显式的网关参数会覆盖--pair携带的对应值。

完整参数说明：

源码中这些参数在 src/cli/node-cli/register.ts 注册：run子命令先通过resolveNodePairGatewayOptions解析--pair，再用resolveNodeGatewayOptions合并既有配置，随后调用runNodeHost进入节点主机运行循环；非法端口会先于启动被拦截（--port解析失败时输出格式化错误并退出）。--no-tls与--tls-fingerprint互斥的校验也在该入口完成（--no-tls cannot be combined with --tls-fingerprint）。

一键配对：openclaw connect

对于"一条命令完成配对"的引导场景，优先使用openclaw connect。在 Gateway 上铸造单次使用链接：

openclaw devices join-code

然后在节点机器上粘贴输出命令：

npx openclaw connect https://gateway.example/j/<shortcode>

短码含 128 位熵，随设置凭证约 10 分钟后过期，且只能取用一次。openclaw connect兑换短时引导凭证、把端点写入既有节点主机状态，然后运行与openclaw node run相同的运行时；可加--service先配对再安装为平台用户服务，或加--commands只暴露指定命令面（详见后文）。

网关鉴权解析规则

openclaw node run与openclaw node install均从配置/环境解析网关鉴权（节点命令上没有--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.passwordSecretRef，节点鉴权失败关闭（不做远程回退掩盖）；
• 在gateway.mode=remote下，远程客户端字段（gateway.remote.token/gateway.remote.password）按远程优先级规则同样可参与；
• 节点主机鉴权解析只认可OPENCLAW_GATEWAY_*环境变量。

已保存的端点包含 host、port、TLS 模式和上下文路径；更改其中任何一项都会恢复常规的配置/环境鉴权解析。因此，节点可以在与本地 Gateway 共享状态目录的同时，重连到另一个已配对的 Gateway，而无需在重启时发送本地 Gateway 的密码。SSH 隧道场景可参考 docs/nodes/node-host.md：先ssh -N -L 18790:127.0.0.1:18789 user@gateway-host，再export OPENCLAW_GATEWAY_TOKEN=...并指向隧道本地端运行。

引导配对与 Cloudflare Access

--pair使用10 分钟单次使用的引导令牌完成首次连接；配对后重连改用持久的设备凭证。管理员铸造的引导注册会批准该设备及其首次声明的命令面（含已声明的system.run）；之后的命令、能力或权限扩展仍需要openclaw nodes approve。网关命令策略与节点主机本地的执行审批是两道独立的门。

node install --pair被有意禁用——短时 bearer 设置链接不得持久化到服务参数中。

当 Gateway 位于 Cloudflare Access 之后时，在openclaw connect、openclaw node run或openclaw node install之前同时设置：

export CF_ACCESS_CLIENT_ID="<client-id>" export CF_ACCESS_CLIENT_SECRET="<client-secret>"

节点把环境值存为规范连接键gateway.cloudflareAccess.clientId/clientSecret下的env SecretRef（而非明文副本）；已安装服务把这些值保存在托管的服务环境文件中，而不是服务参数或内联 supervisor 定义中。Access 凭证要求 HTTPS/WSS；明文 HTTP/WS 会在 SecretRef 解析之前失败，而无需凭证的明文节点路由保持不变。

明文 WS 的限制

对于连接明文ws://网关的节点，回环、私有 IP 字面量、.local和 Tailnet*.ts.net主机被接受；其他受信任的私有 DNS 名称需要设置：

export OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1

否则节点启动失败关闭，并提示改用wss://、SSH 隧道或 Tailscale。这是进程环境的 opt-in，不是openclaw.json配置键；openclaw node install在安装命令环境中存在该变量时，会把它持久化进受监督的节点服务。

后台服务：openclaw node install

把无头节点主机安装为用户级服务（macOS 用 launchd、Linux 用 systemd、Windows 用 Task Scheduler）：

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

参数与node run大体一致，另有：

设置OPENCLAW_WRAPPER指向可执行包装文件时，用它替代所选运行时与 CLI 入口；包装器接收node run及连接参数，必须自行启动 OpenClaw 并转发这些参数。若安装报告运行时探测失败，检查错误中指定的可执行文件和工作目录（例如用runuser切换用户时，先切换到目标用户可读的目录）；探测失败不意味着已安装的 Node 版本不受支持——升级提示只保留给缺失或不支持的运行时。

Linux（systemd 用户服务）：安装后执行sudo loginctl enable-linger <user>。若未启用 lingering，systemd --user会在最后一个 SSH 会话结束时拆除节点服务，导致登出后节点悄然离线。openclaw node install检测到 lingering 被禁用时会打印该警告。

服务生命周期管理：

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

• 服务命令均支持--json输出机器可读结果；
• node start/node restart在未安装受管服务时打印安装提示并以非零码退出；先执行openclaw node install。停止不存在的服务是成功的空操作；
• 要删除已保存的命令白名单：前台运行openclaw node run --all-commands，或openclaw node install --force --all-commands重装服务。重置是持久的，替换后的服务参数不再携带--commands；
• 节点主机进程内重试网关重启与网络断开；若网关报告终结性的 token/password/bootstrap 鉴权暂停，节点主机记录关闭详情并以非零码退出，让 launchd/systemd/Task Scheduler 用新的配置和凭证重启。配对中（PAIRING_REQUIRED）的暂停则留在前台流程中，以便待审批请求获得批准。

源码中status、identity、install、uninstall、stop、start、restart统一在 src/cli/node-cli/register.ts 注册，install 的--runtime、--force、--json等选项在安装动作中透传给runNodeDaemonInstall（实现在 src/cli/node-cli/daemon.ts）。

配对流程与命令面审批

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

自动批准：当 Gateway 主机能非交互 SSH到节点主机（同用户、受信任主机密钥）时，Gateway 在节点上运行openclaw node identity --json，并在设备密钥精确匹配时自动批准。该行为默认开启；禁用方法见 docs/gateway/pairing.md（gateway.nodes.pairing.sshVerify: false）。

手动批准两步走：

# 1. 批准设备连接 openclaw devices list openclaw devices approve <deviceRequestId> # 2. 批准命令面（重启节点后产生独立请求） openclaw nodes pending openclaw nodes approve <nodeRequestId> openclaw nodes describe --node <idOrNameOrIp>

关键语义：

• 设备请求 ID 与节点请求 ID 是两回事。设备批准只承认连接，不批准命令面；未批准的初始命令面没有有效命令；
• 节点暂停在PAIRING_REQUIRED时，手动批准后不会自动恢复；用openclaw node restart或重新前台运行openclaw node run触发重连，重连会创建独立的命令面请求；
• SSH 验证与引导注册可以自动批准首个命令面；后续扩展仍需审批，而已批准并仍声明且允许的命令在等待扩展期间保持有效；
• 若节点以更改后的鉴权细节（role/scopes/public key）重试配对，之前的待处理请求被取代并生成新requestId，批准前应重新执行openclaw devices list。

在严格控制节点网络中，Gateway 操作员可显式 opt-in 对受信任 CIDR的首次节点配对自动批准：

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

默认禁用（autoApproveCidrs未设置）。它只适用于来自 Gateway 信任的客户端 IP、无请求 scopes 的全新role: node配对；操作员/浏览器客户端、Control UI、WebChat 以及 role/scope/metadata/公钥升级仍需手动审批。且受信任网络审批不批准命令面，仍需检查openclaw nodes pending并批准独立的面请求。

本地身份检查

openclaw node identity --json

输出primary行（state/openclaw.sqlite）中的设备 ID 与公钥，绝不创建数据库或新身份。源码见 src/cli/node-cli/identity.ts：loadDeviceIdentityIfPresent只读加载，找不到身份时打印no node device identity found (start the node host once with openclaw node run or openclaw node install)并以非零码退出——这正是 SSH 验证配对探针可以安全远程调用的原因：它不会在未运行过节点主机的主机上铸造新身份。

身份与配对状态存储

无头节点把客户端实例 ID与 Gateway 用于配对和路由的签名设备身份分开，全部存放在 OpenClaw 状态目录（默认~/.openclaw，或设置$OPENCLAW_STATE_DIR时用该目录）：

要点：

• node.list/node.describe中的gatewayLocal标记与 Gateway 状态目录中的主设备身份精确匹配；覆盖--node-id不会改变它。拥有自己状态目录和密钥的节点即使在同一台机器上也是独立的；
• --node-id只改共享 SQLite 状态中的客户端实例 ID，不改变密码学设备 ID，也不清除配对鉴权；迁移退役的node.json同样不重置配对；
• 保持state/openclaw.sqlite私密——它包含设备密钥对和鉴权令牌。

撤销并重新配对

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 行，然后删除旧文件。只要任一退役文件或未完成的 Doctor 认领存在，普通节点命令就会失败关闭并给出修复指引。

限制命令面：--commands的源码实现

--commands与--all-commands由 src/cli/node-cli/command-options.ts 统一注入到node、node run与node install。collectNodeCommandIds把逗号分隔的值拆分、去重、排序并校验非空（空 ID 抛出--commands requires comma-separated non-empty command ids）；preAction钩子在命令执行前拦截--all-commands与--commands并存的情况并报错conflictingOption。

语义要点：

• 白名单保存在节点的持久机器状态中，对已安装服务同样生效；后续启动省略该参数会保留已保存列表；
• 节点只通告既可用又在白名单内的命令及其必需能力；没有请求的命令可用时启动失败；Gateway 配对审批会显示最终声明的命令；
• 显式白名单同时禁用 computer use、技能扫描与发布、插件工具发布、MCP 服务器与 worker 托管；白名单不能启用已禁用的插件或让不可用命令变得可用。

例如一个只发布会话而不暴露执行能力的 Session Share 节点：

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

恢复完整默认命令面：前台openclaw node run --all-commands，或服务openclaw node install --force --all-commands；用openclaw connect重新注册时加--all-commands（可配--service）。这会把已保存白名单持久删除，并替换服务的--commands参数。

浏览器代理（零配置）

节点主机在browser.enabled未被禁用时自动通告浏览器代理，让 Agent 无需额外配置即可在该节点上做浏览器自动化。默认情况下代理暴露节点常规的浏览器配置文件面；若设置nodeHost.browserProxy.allowProfiles，代理转为限制模式：非白名单的配置文件定位被拒绝，且通过代理的持久配置文件创建/删除路由被阻断。

需要时可在节点上禁用：

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

插件与 MCP 工具发布

openclaw node run连接后可以发布插件或 MCP 支撑的工具。Gateway默认信任已配对节点的描述符，但要求每个描述符的命令保持在节点已批准的命令面内。Agent 把每个被接受的描述符视为普通插件工具，但执行仍走node.invoke——因此断开节点后，新 Agent 运行中该工具即消失。Gateway 操作员可通过gateway.nodes.pluginTools.enabled: false关闭发布，也可用gateway.nodes.commands.deny: ["mcp.tools.call.v1"]精确阻断执行（详见 docs/nodes/mcp-and-skills.md 中节点托管 MCP 服务器一节）。

声明式 MCP 工具：在节点机器的openclaw.json中以标准 MCP 服务器形态配置nodeHost.mcp.servers，然后重启节点主机。节点声明审批门控的mcp.tools.call.v1命令族并在连接后发布所列工具；后续修改服务器列表无需重新配对。注意：节点托管的 v1 路径不支持 OAuth MCP 服务器；工具调用通过mcp.tools.call.v1回到该节点，Gateway 侧不需要匹配的 MCP 配置或 JS 插件。

Exec approvals：system.run的门控

system.run由节点本地的执行审批把关：

• 存储位置：$OPENCLAW_STATE_DIR/state/openclaw.sqlite#exec_approvals_config，变量未设置时为~/.openclaw/state/openclaw.sqlite#exec_approvals_config；
• 参考 docs/tools/exec-approvals.md；
• 从 Gateway 侧编辑：openclaw approvals --node <id|name|ip>。

安全细节（systemRunPlan）：对于已批准的异步节点执行，OpenClaw 在提示前先准备规范化的systemRunPlan；之后获批的system.run转发复用该已存储计划，因此审批请求创建后对 command/cwd/session 字段的编辑会被拒绝，而不会改变节点实际执行的内容。docs/nodes/node-host.md 中还提到：执行路径会重新校验工作目录；若无法为解释器/运行时命令确定恰好一个具体本地文件操作数，审批式执行会被拒绝，而不是假装覆盖全部运行时语义。

其他执行面要点：

• system.run返回 payload 中的 stdout/stderr/退出码；shell 执行走host=node的 exec 工具路径，2026.3.31 起独立的nodes.run执行路径已被移除，nodes保留为显式节点命令的直接 RPC 面；
• nodes invoke不暴露system.run/system.run.prepare，它们只在 exec 路径上；
• shell 包装（bash|sh|zsh ... -c/-lc）中请求级env会被收敛为显式白名单（TERM、LANG、LC_*、COLORTERM、NO_COLOR、FORCE_COLOR）；
• 节点主机忽略env对象中的PATH覆盖，并在运行前剔除大量解释器/ shell 启动变量（如NODE_OPTIONS、PYTHONPATH、BASH_ENV、DYLD_*、LD_*）；需要额外 PATH 时配置节点主机服务环境，而不是经env传入；
• Windows 节点主机在白名单模式下，经cmd.exe /c的 shell 包装运行仍需审批；
• 未识别的节点platform/deviceFamily元数据使用保守默认白名单，排除system.run/system.which；确有需要时经gateway.nodes.commands.allow显式加入。

macOS 节点模式（菜单栏应用）中，system.run由应用内的执行审批（Settings → Exec approvals）门控，ask/allowlist/full 行为与无头节点主机一致，被拒提示返回SYSTEM_RUN_DENIED；无头节点主机在 macOS 上默认本地执行，设置OPENCLAW_NODE_EXEC_HOST=app可要求必须走伴侣应用执行主机且无本地回退。

小结

openclaw node把 OpenClaw 的执行能力从 Gateway 主机安全地延伸到网络中的任意机器：node run负责前台运行与调试，node install负责 launchd/systemd/Task Scheduler 下的常驻服务，--pair/openclaw connect负责一次粘贴的引导配对，--commands/--all-commands负责把命令面收敛到精确白名单，devices/nodes双轨审批把"设备连接"与"命令面"分开审计，而state/openclaw.sqlite中实例 ID、设备身份、配对令牌的三段式隔离保证了撤销、重配对与迁移的可操作性。相关的完整命令面、配对细节与执行行为还可继续阅读 docs/cli/connect.md、docs/nodes/node-host.md 与 docs/tools/exec-approvals.md。

【免费下载链接】openclawThe AI that really does things. Any OS. Any Platform. The lobster way. 🦞项目地址: https://gitcode.com/GitHub_Trending/cl/openclaw