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携带的对应值。完整参数说明参数说明--host hostGateway WebSocket 主机默认127.0.0.1--pair code-or-url从设置码或oc-pair://URL 读取端点、引导令牌、TLS 模式与证书指纹显式网关参数优先--port portGateway WebSocket 端口默认18789--context-path pathGateway WebSocket 上下文路径如/openclaw-gw追加到 WebSocket URL--tls对网关连接使用 TLS--no-tls即使本地 Gateway 配置启用 TLS也强制明文连接不能与--tls-fingerprint同用--tls-fingerprint sha256期望的 TLS 证书指纹sha256--node-id id覆盖共享 SQLite 状态中的客户端实例 ID不会重置配对--display-name name覆盖节点显示名--commands ids持久化精确逗号分隔的命令白名单可重复只通告可用匹配项及其必需能力同时禁用 computer use、技能、插件工具、MCP 服务器和 worker 托管。省略该参数则保留已保存列表--all-commands通告完整默认命令面并遗忘已保存的--commands白名单不能与--commands并用--share-installed-appsmacOS 上通过device.apps通告已安装应用--no-share-installed-apps禁用已安装应用共享源码中这些参数在 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.moderemote下远程客户端字段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 usergateway-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_IDclient-id export CF_ACCESS_CLIENT_SECRETclient-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_WS1否则节点启动失败关闭并提示改用wss://、SSH 隧道或 Tailscale。这是进程环境的 opt-in不是openclaw.json配置键openclaw node install在安装命令环境中存在该变量时会把它持久化进受监督的节点服务。后台服务openclaw node install把无头节点主机安装为用户级服务macOS 用 launchd、Linux 用 systemd、Windows 用 Task Scheduleropenclaw node install --host gateway-host --port 18789参数与node run大体一致另有参数说明--runtime node\|bun服务运行时默认node。Bun 1.4 且带 WAL-reset-safenode:sqlite是显式 opt-in仍推荐 Node--force已安装时重新安装/覆盖设置OPENCLAW_WRAPPER指向可执行包装文件时用它替代所选运行时与 CLI 入口包装器接收node run及连接参数必须自行启动 OpenClaw 并转发这些参数。若安装报告运行时探测失败检查错误中指定的可执行文件和工作目录例如用runuser切换用户时先切换到目标用户可读的目录探测失败不意味着已安装的 Node 版本不受支持——升级提示只保留给缺失或不支持的运行时。Linuxsystemd 用户服务安装后执行sudo loginctl enable-linger user。若未启用 lingeringsystemd --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.mdgateway.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.tsloadDeviceIdentityIfPresent只读加载找不到身份时打印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时用该目录状态用途state/openclaw.sqliteconfig_machine_state键nodeHost.config客户端实例 ID、显示名、Gateway 连接元数据客户端以该 ID 作为instanceId发送state/openclaw.sqlitedevice_identitiesprimary签名的 Ed25519 密钥对与派生的设备 ID签名连接中该设备 ID 就是被路由的节点 ID 与配对身份state/openclaw.sqlitedevice_auth_tokens按密码学设备 ID 与 role 键控的已配对设备令牌要点node.list/node.describe中的gatewayLocal标记与 Gateway 状态目录中的主设备身份精确匹配覆盖--node-id不会改变它。拥有自己状态目录和密钥的节点即使在同一台机器上也是独立的--node-id只改共享 SQLite 状态中的客户端实例 ID不改变密码学设备 ID也不清除配对鉴权迁移退役的node.json同样不重置配对保持state/openclaw.sqlite私密——它包含设备密钥对和鉴权令牌。撤销并重新配对在 Gateway 上执行openclaw nodes remove --node id|name|ip在节点上openclaw node restart或停止后重跑前台openclaw node run启动设备配对流程若openclaw devices list看不到请求且节点报告AUTH_DEVICE_TOKEN_MISMATCH再重启/重跑一次——被拒绝的尝试会清除已被撤销的本地令牌下一次尝试才能请求配对在 Gateway 上openclaw devices list然后openclaw devices approve deviceRequestId再次重启/重跑节点。为配对暂停的客户端在批准后不会自动恢复该重连会创建独立的命令面请求在 Gateway 上openclaw nodes pending然后openclaw nodes approve nodeRequestId。两个请求 ID 相互独立适用的受信任 CIDR 策略可以自动批准首次设备配对但命令面批准始终是独立检查。旧版状态迁移旧版 OpenClaw 把节点主机状态存在node.json、签名身份在identity/device.json、配对鉴权在identity/device-auth.json。停止节点主机后执行一次openclaw doctor --fixDoctor 会认领每个退役来源、校验、导入并验证规范 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 idspreAction钩子在命令执行前拦截--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 approvalssystem.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 执行走hostnode的 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_HOSTapp可要求必须走伴侣应用执行主机且无本地回退。小结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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考