跳转至

openclaw connect

将当前机器作为无头节点连接到 OpenClaw Gateway。该命令兑换短期引导凭据,将 Gateway 端点保存到现有节点宿主状态中,并运行与 openclaw node run 相同的运行时。

创建加入命令

在 Gateway 主机上,使用管理员凭据铸造一个一次性加入 URL:

openclaw devices join-code

该命令会打印 URL 和一条可粘贴的命令:

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

该短码具有 128 位熵,会随设置凭据在大约 10 分钟后过期,并且只能获取一次。如果它已过期或已被使用,请重新铸造一个。

前台连接

在要连接的机器上粘贴打印出的命令:

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

如有需要,可在注册期间设置设备名称:

npx openclaw connect https://gateway.example/j/<shortcode> --display-name "Build Node"

节点将保持在前台运行,直到你将其停止。

若要只暴露选定的命令,请传入一个以逗号分隔的精确命令 ID 列表。对于 Session Share 节点:

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

该标志可重复使用。允许列表是持久的节点状态,在 --service 安装后同样生效;省略它会保留已保存的列表。它会过滤可用命令及其所需能力,并禁用 computer use、skills、plugin-tool 发布、MCP 服务器和 worker 托管。当没有请求的命令可用时,启动会失败。Gateway 配对审批会显示由此声明的命令。

若要恢复完整的默认能力范围,对于前台节点请使用 openclaw node run --all-commands,对于已安装的服务请使用 openclaw node install --force --all-commands。再次注册时,请使用 openclaw connect <join-url> --all-commands(服务则加上 --service)。这会丢弃已保存的允许列表;--all-commands 不能与 --commands 组合使用。

要让该前台进程托管完整的 worker 会话,请使用 --session-host 明确给予本地同意:

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

前台同意仅适用于该进程。它不会更改 openclaw.json,因此下次正常启动节点宿主时仍为非托管状态。

重新连接已配对节点

加入 URL 和设置码均为一次性,因此在节点停止后重新运行原始的 openclaw connect <join-url> 命令会报告加入码未找到或已过期。节点会在节点宿主状态中保留其配对的设备令牌和 Gateway 端点。请使用 openclaw node run 重新连接,并重复任何进程作用域标志:

openclaw node run --session-host

在不带目标的情况下运行 openclaw connect 不会进行连接。当节点宿主状态中已保存 Gateway 端点和节点设备令牌时,它会以错误退出,并打印与你传入标志匹配的 openclaw node run 命令(如果该配对仍然有效则使用),否则打印要与新加入 URL 一起使用的 openclaw connect 命令。使用 --service 时,它会改而打印 openclaw node install --force;如果你同时传入了 --session-host,则会在前面加上 openclaw config set nodeHost.workerRuns.enabled true。如果首次注册从未完成,它只会指向一个新的加入 URL。设备令牌并不绑定到单个端点:在与不同 Gateway 的注册失败后,重新连接命令可能会失败,因此请改为重新注册。要再次注册该机器,请使用 openclaw devices join-code 铸造一个新的加入 URL。

环境托管的云节点

Worker 提供者使用 --ephemeral 来创建可丢弃的云机器:

npx openclaw connect <setup-code> --ephemeral

即使机器的持久节点配置禁用了 worker 托管,该进程也会托管 worker 会话。它不会安装服务,也不能与 --service 或 --session-host 组合使用。Gateway 拥有设置身份和配对节点的生命周期:一次性设置凭据被消耗后,提供者重放会恢复持久化的设备令牌;环境拆除会在释放云租约后移除节点角色。

--ephemeral 旨在用于可丢弃机器上由提供者管理的状态目录,而非用作注册个人设备的快捷方式。

安装为服务

传入 --service 以兑换引导凭据,并将节点宿主安装为平台用户服务:

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

OpenClaw 会在安装服务之前完成首次经过身份验证的连接。短生命周期的引导令牌绝不会存储在服务命令或节点宿主配置中;后续启动使用持久的配对设备令牌。当针对已保存的端点重启时,共置 Gateway 的配置凭据不会覆盖配对令牌。显式的 OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD 环境凭据仍具有优先权。使用 openclaw node status 检查已安装的服务。

该服务默认不托管 worker 会话。要同意完整的 worker 会话托管,请添加 --session-host:

npx openclaw connect https://gateway.example/j/<shortcode> --service --session-host

一次性引导连接会进行身份验证并保存持久的设备身份,而不会宣告 worker 托管。只有在该连接成功后,OpenClaw 才会持久化 nodeHost.workerRuns.enabled=true,保留其余配置,并安装服务。如果配置写入失败,则不会开始安装服务。安装后的服务在启动时会根据这一持久同意宣告 worker 托管及确切容量。

可接受的目标

| 选项 | 用途 |

选项 用途
----------------------- ---------------------------------------------------------------------------------------------------------------------
--commands <ids> 保存一个精确的、以逗号分隔的节点命令允许列表(可重复)。适用于前台运行和已安装的服务。
--all-commands 公布完整的默认命令集,并清除任何已保存的 --commands 允许列表。与 --commands 冲突。
--display-name <name> 设置节点显示名称。
--service 先配对,然后将节点安装为用户服务。
--session-host 同意 worker 托管。显式命令允许列表会禁用托管。
--ephemeral 运行由提供商管理的一次性 worker 节点。
--target-file <path> 从文件读取加入目标,并在成功读取后消费该交接。

openclaw connect <target> 接受:

  • https://<gateway>/j/<shortcode> 加入 URL;
  • oc-pair://<setup-code> URL;
  • 裸 base64url 设置代码。

--target-file <path> 接受大小不超过 64 KiB 的常规文件。它仅在读取到非空目标后 才删除该路径。如果文件为空、过大、不可读,或不是常规文件,OpenClaw 会将其保留在原处。允许符号链接;OpenClaw 会读取其目标,在成功读取后删除符号链接, 并保留底层文件。休眠的安装程序包装器使用此交接, 以避免将一次性目标放入子进程参数中。

加入 URL 必须使用 HTTPS。仅回环 Gateway URL (例如 http://127.0.0.1/j/<shortcode>)接受普通 HTTP。直接设置代码可以携带 Gateway TLS 证书指纹,这使节点主机在解码负载后能够固定自签名 Gateway 证书。

负载决定保存的主机、端口、TLS 模式、WebSocket 上下文路径, 以及有序的回退端点。普通连接和前台连接不会添加 openclaw.json 键;--service --session-host 会显式持久化上述 worker 托管同意。

吊销行为

加入代码和已配对设备具有各自独立的生命周期:

  • 销毁或使加入代码过期会阻止使用该代码再次注册。
  • 它不会断开或移除已经兑换它的节点。
  • 要吊销普通已注册机器,请使用 openclaw devices remove <deviceId> 移除其已配对设备。
  • 由环境管理的 --ephemeral 节点会在其所属云环境被销毁时自动移除。

故障排查

如果加入 URL 报告其缺失或已过期,请使用 openclaw devices join-code 生成一个新的。已使用的代码会故意返回与未知代码 相同的结果。如果本机已经兑换了它,请改用已保存的配对重新连接;参见 重新连接已配对节点。

如果 HTTPS 加入 URL 使用了本机不信任的证书,请使用包含 TLS 固定值的直接 oc-pair:// 或裸设置代码形式。

有关服务管理、显式连接标志、节点 状态和 exec 审批行为,请参见 节点。

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