openclaw connect¶
将当前机器作为无头节点连接到 OpenClaw Gateway。该命令会兑换一个短时效的引导凭据，在现有节点主机状态中保存 Gateway 端点，并运行与 openclaw node run 相同的运行时。
创建加入命令¶
在 Gateway 主机上，使用管理员凭据生成一个一次性加入 URL：
该命令会打印 URL 和一条可粘贴的命令：
短码具有 128 位熵，会在大约 10 分钟后随设置凭据一起过期，并且只能获取一次。如果它已过期或已被使用，请生成另一个代码。
在前台连接¶
在你想要连接的机器上粘贴打印出的命令：
如有需要，可在注册期间设置设备名称：
节点会保持在前台，直到你停止它。
要仅公开选定的命令，请传入一个由逗号分隔的精确命令 ID 列表。对于 Session Share 节点：
该标志可重复使用。允许列表是持久节点状态，并且在 --service 安装后也适用；省略它会保留已保存的列表。它会过滤可用命令及其所需能力，并禁用计算机使用、技能、插件工具发布、MCP 服务器和工作器托管。当没有请求的命令可用时，启动会失败。Gateway 配对审批会显示最终声明的命令。
要恢复完整的默认功能面，对于前台节点请使用 openclaw node run --all-commands，对于已安装服务请使用 openclaw node install --force --all-commands。再次注册时，请使用 openclaw connect <join-url>
--all-commands（对于服务请添加 --service）。这会忘记已保存的允许列表；--all-commands 不能与 --commands 组合使用。
要让该前台进程托管完整工作器会话，请使用 --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。
环境管理的云节点¶
工作器提供商对一次性云机器使用 --ephemeral：
即使机器的持久节点配置禁用了工作器托管，该进程也会托管工作器会话。它不会安装服务，也不能与 --service 或 --session-host 组合使用。Gateway 拥有设置身份和配对节点生命周期：提供商重放会在一次性设置凭据被消费后恢复持久化的设备令牌，环境拆除会在释放云租约后移除节点角色。
--ephemeral 旨在用于一次性机器上由提供商管理的状态目录，而不是作为注册个人设备的快捷方式。
安装为服务¶
传入 --service 以兑换引导凭据，并将节点主机安装为平台用户服务：
OpenClaw 会在安装服务之前完成首次经过身份验证的连接。短时效引导令牌永远不会存储在服务命令或节点主机配置中；后续启动使用持久的配对设备令牌。当针对该已保存端点重启时，同置 Gateway 的配置凭据不会覆盖配对令牌。显式的 OPENCLAW_GATEWAY_TOKEN 或 OPENCLAW_GATEWAY_PASSWORD 环境凭据仍然优先。使用 openclaw node status 检查已安装的服务。
该服务默认不托管工作器会话。要同意完整的工作器会话托管，请添加 --session-host：
一次性引导连接会进行身份验证并保存持久设备身份，而不会宣告工作器托管。只有在该连接成功后，OpenClaw 才会持久化 nodeHost.workerRuns.enabled=true，保留配置的其余部分，并安装服务。如果配置写入失败，服务安装不会开始。已安装的服务启动时，会根据此持久同意宣告工作器托管和精确容量。
接受的目标¶
| 选项 | 用途 |
| 选项 | 用途 |
|---|---|
| ----------------------- | --------------------------------------------------------------------------------------------------------------------- |
--commands <ids> |
保存一个精确的逗号分隔节点命令允许列表（可重复）。适用于前台运行和已安装服务。 |
--all-commands |
通告完整默认命令范围，并忘记任何已保存的 --commands 允许列表。与 --commands 冲突。 |
--display-name <name> |
设置节点显示名称。 |
--service |
先配对，然后将节点安装为用户服务。 |
--session-host |
同意工作节点托管。显式命令允许列表会禁用托管。 |
--ephemeral |
运行由提供商管理的可丢弃工作节点。 |
--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，例如 http://127.0.0.1/j/<shortcode>。直接设置代码可以携带 Gateway TLS 证书指纹，这使节点主机能够在解码负载后固定自签名 Gateway 证书。
负载决定保存的主机、端口、TLS 模式、WebSocket 上下文路径以及有序的回退端点。普通连接和前台连接不会添加 openclaw.json 键；--service --session-host 会显式持久化上述工作节点托管同意。
吊销行为¶
加入代码和已配对设备具有各自独立的生命周期：
- 销毁或使加入代码过期可防止使用该代码再次注册。
- 它不会断开或移除已经兑换该代码的节点。
- 要吊销普通已注册机器，请使用
openclaw devices remove <deviceId>移除其已配对设备。 - 由环境管理的
--ephemeral节点会在其所属云环境被销毁时自动移除。
故障排除¶
如果加入 URL 报告其缺失或已过期，请使用
openclaw devices join-code 生成一个新的。已使用的代码会故意返回与未知代码相同的结果。如果本机已经兑换了该代码，请改用已保存的配对重新连接；参见 重新连接已配对节点。
如果 HTTPS 加入 URL 使用了本机不信任的证书，请使用包含 TLS 固定的直接 oc-pair:// 或裸设置代码形式。
有关服务管理、显式连接标志、节点状态和 exec 审批行为，请参见 节点。
本页原文 Markdown：在 AtomGit 查看·内容源自开源项目 cl/openclaw