node-connect

节点连接

目标：修复一个确定的客户端与一个确定的 Gateway 之间的连接，然后验证该客户端已建立新连接。

1. 锁定目标

在进行任何更改前，记录目标环境/配置文件、OpenClaw 二进制文件、配置/状态根目录、Gateway URL/端口，以及服务。

• 对所有配置、日志、服务、设备和节点命令，都使用指定的部署包装器/配置文件。
• 绝不要切换到裸 openclaw、验证环境或名称相似的部署。
• 如果全局可执行文件已过时，通过其所属方调用目标。
• 验证状态、配置、日志和进程身份描述的是同一个 Gateway。

在更改配对或身份验证前，先识别目标 Gateway。

2. 对客户端分类

在选择命令前，根据请求和 Gateway 日志进行分类：

• Control UI 浏览器： 用户提到浏览器、仪表板、Control UI 或 webchat；日志显示 client=openclaw-control-ui 或 mode=webchat。
• 原生移动端/节点： 官方应用显示 Connect、Scan QR 或 setup code；日志/请求元数据表明这是原生客户端或 role=node。

手机可能属于任一种客户端。不要对手机浏览器使用 openclaw qr 或 openclaw nodes status；这些命令用于原生移动端/节点配对。

3. 观察失败的尝试

通过已锁定的目标运行以下命令：

openclaw gateway status --deep
openclaw logs --follow --json
openclaw devices list
openclaw config get gateway.mode
openclaw config get gateway.bind
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.allowTailscale
openclaw config get gateway.tailscale.mode

在日志实时输出时，让客户端重试一次。关联其客户端 ID、模式、平台、地址、身份验证结果、设备 ID、用户和关闭代码。忽略其他已配对设备。

解读首次失败的转换：

• 没有匹配的 Gateway 尝试：路由、DNS、TLS、来源或代理问题。
• token_missing、password_missing、不匹配或 Tailscale 身份失败：配对前身份验证失败，因此待处理列表为空是预期情况。
• pairing required：路由和身份验证均已成功；批准确切的待处理请求。
• client connected：将 conn、client、mode 和 role 与确切客户端匹配。接纳先于 hello 响应；如果随后出现 1006，保留身份验证/配对状态，并检查 hello 投递、生命周期、传输、代理或重连。较旧版本会使用重叠的 authenticated user connected / webchat connected 记录，这些记录不会显示临时客户端。
• 没有匹配的应用层接纳记录时，单独出现 1006 并不能证明身份验证/配对成功；请检查更早的握手转换。

4. 验证路由

选择一种拓扑：同一台机器、LAN、tailnet 或公共反向代理。不要混用。

• 浏览器版 Control UI 需要 HTTPS 或 localhost 才能使用浏览器设备身份。远程纯 HTTP 的 Tailnet/LAN URL 不能替代。
• gateway.tailscale.mode=off 表示 OpenClaw 不负责管理 Serve/Funnel。这并不能证明 Tailscale 或外部管理的 Serve 路由不存在。
• 涉及 Tailscale 时，检查实时状态，而不要根据 OpenClaw 配置推断：

tailscale status --json
tailscale serve status --json

将客户端 URL 与通往已锁定 Gateway 的监听器/代理路由相匹配。

5A. Control UI 浏览器通道

查找配对请求前，先恢复浏览器身份验证：

• 对于令牌/密码身份验证，请在 Control UI 设置中输入凭据。切勿将永久密钥放入聊天、日志或 URL 中。
• 优先在 Gateway 主机上运行 openclaw dashboard，以进行一次性签名交接。只有在操作员能够读取该主机剪贴板时，才使用 --no-open；并确保主机浏览器/剪贴板不在 Agent 工具的访问范围内。切勿截取 dashboard --json 的输出：其中可能暴露交接信息和共享凭据。切勿将回环交接 URL 转发、改写或发送到远程手机。
• 对于 Tailscale Serve，请验证当前路由和转发的身份。仅在预期的信任边界内启用 gateway.auth.allowTailscale。通过浏览器设备身份验证的 Tailscale Control UI 身份验证可以跳过配对。

身份验证成功后：

• 重试；切勿根据身份验证前的尝试推断是否需要配对。令牌/密码身份验证可能显示 pairing required；已验证的 Tailscale 身份可以跳过配对。
• 如果日志显示 pairing required，请重新列出设备并批准确切的请求 ID。
• 已验证的 Tailscale 连接成功后，可能不会创建待处理或已配对设备条目，这是正常的。
• 如果反复出现 1006，请保留身份验证/配对状态并检查重连证据。

5B. 原生移动端/节点通道

在锁定的目标上检查原生路由，不要暴露设置凭据：

openclaw qr --json | jq '{gatewayUrl, gatewayUrls, auth, access, accessDowngraded, urlSource}'

对于控制远程 Gateway 的 CLI，请在 --json 前添加 --remote；它会选择 gateway.remote.url 和远程凭据。如果无法使用脱敏过滤器，请勿在 Agent 可见的输出中运行原始 QR JSON。

验证 gatewayUrl 和 urlSource。设置码的敏感程度等同于密码：请操作员从 Control UI → Devices → Pair device 复制，或者在 Agent 工具之外的终端中运行 openclaw qr --setup-code-only，然后直接粘贴到官方应用中。切勿通过 Agent/聊天/工具输出转发设置码。在修复 URL/身份验证问题后或设置码过期后，请生成新的设置码。

如果应用报告 pairing required：

openclaw devices list
openclaw devices approve --latest   # preview only; exits without approval
openclaw devices approve <requestId>
openclaw nodes status

--latest 只会预览当前请求；切勿将其视为批准。由于重试可能会取代原请求，请在执行确切 ID 的命令前立即重新列出请求。切勿按位置、时间或相似度批准。

6. 关联并完成

批准前，请核对可用的请求、设备/公钥、客户端、模式/角色、平台、地址、用户和重试时间信息。

只有在最终更改后进行的新尝试证明所有适用检查均通过，才能宣布成功：

• 确切的客户端已连接到锁定的 Gateway；
• 预期的身份验证成功；
• 浏览器已完成初始请求，或者原生节点已显示在 openclaw nodes status 中；
• 批准时使用了确切的请求 ID；并且
• 后续没有立即发生身份验证、配对或重连失败。

QR/设置码、启动的浏览器、空的待处理列表、批准操作、已配对设备数量或 Tailscale ping，都只能证明一个状态转换。

报告诊断结果、选择的路由/身份验证通道、确切客户端的证据，以及任何仍未成功的状态转换。