openclaw connect¶
将当前机器作为无头节点连接到 OpenClaw Gateway。该命令兑换短期引导凭据,将 Gateway 端点保存到现有节点宿主状态中,并运行与 openclaw node run 相同的运行时。
创建加入命令¶
在 Gateway 主机上,使用管理员凭据铸造一个一次性加入 URL:
该命令会打印 URL 和一条可粘贴的命令:
该短码具有 128 位熵,会随设置凭据在大约 10 分钟后过期,并且只能获取一次。如果它已过期或已被使用,请重新铸造一个。
前台连接¶
在要连接的机器上粘贴打印出的命令:
如有需要,可在注册期间设置设备名称:
节点将保持在前台运行,直到你将其停止。
若要只暴露选定的命令,请传入一个以逗号分隔的精确命令 ID 列表。对于 Session Share 节点:
该标志可重复使用。允许列表是持久的节点状态,在 --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 明确给予本地同意:
前台同意仅适用于该进程。它不会更改 openclaw.json,因此下次正常启动节点宿主时仍为非托管状态。
重新连接已配对节点¶
加入 URL 和设置码均为一次性,因此在节点停止后重新运行原始的 openclaw connect <join-url> 命令会报告加入码未找到或已过期。节点会在节点宿主状态中保留其配对的设备令牌和 Gateway 端点。请使用 openclaw node run 重新连接,并重复任何进程作用域标志:
在不带目标的情况下运行 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 来创建可丢弃的云机器:
即使机器的持久节点配置禁用了 worker 托管,该进程也会托管 worker 会话。它不会安装服务,也不能与 --service 或 --session-host 组合使用。Gateway 拥有设置身份和配对节点的生命周期:一次性设置凭据被消耗后,提供者重放会恢复持久化的设备令牌;环境拆除会在释放云租约后移除节点角色。
--ephemeral 旨在用于可丢弃机器上由提供者管理的状态目录,而非用作注册个人设备的快捷方式。
安装为服务¶
传入 --service 以兑换引导凭据,并将节点宿主安装为平台用户服务:
OpenClaw 会在安装服务之前完成首次经过身份验证的连接。短生命周期的引导令牌绝不会存储在服务命令或节点宿主配置中;后续启动使用持久的配对设备令牌。当针对已保存的端点重启时,共置 Gateway 的配置凭据不会覆盖配对令牌。显式的 OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD 环境凭据仍具有优先权。使用 openclaw node status 检查已安装的服务。
该服务默认不托管 worker 会话。要同意完整的 worker 会话托管,请添加 --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