彻底解决 OpenClaw「1008：需要配对」网关连接失败错误（超详细图文教程）

很多 OpenClaw 用户在尝试将网关连接到 Control UI 或仪表盘时，会反复看到 “Disconnected (1008): pairing required” 的提示。这是因为网关和客户端（浏览器或应用）之间尚未完成设备授权配对。OpenClaw 出于安全考虑强制要求配对，以防止未授权访问。首次连接时，网关会要求客户端提供已批准的设备身份和令牌，如果缺少或未获批准，就会出现 1008 错误，导致无法看到实时仪表盘。

要恢复正常连接，必须完成配对和认证流程：即将网关令牌提供给客户端，并批准待处理的配对请求。配对成功后，UI 就能正常连接并保持稳定，不再弹出该错误。

错误到底是什么意思

这个错误来源于 OpenClaw 的安全机制。网关在接受 WebSocket 连接前，必须验证有效的令牌或已批准的设备身份。Control UI 运行在浏览器中，浏览器在尝试连接时会向网关发送设备身份标识。如果网关未批准该身份，就会以 1008 错误码拒绝连接。

最常见的触发场景包括：

• 没有有效网关令牌就直接访问仪表盘。
• 在 Docker 环境下运行 OpenClaw，没有正确转发或信任本地网络头信息。
• 重新安装应用、清除浏览器本地存储，导致已保存的令牌丢失。

快速解决「需要配对」问题

下面是修复 1008 配对错误、让网关正常连接的完整步骤。

获取并使用你的网关令牌

• 在主机上找到令牌文件，通常位于~/.openclaw/openclaw.json或类似的配置文件中。
• 也可以使用命令生成全新的令牌：openclaw doctor --generate-gateway-token。
• 进入 Control UI 的仪表盘设置页面，将令牌粘贴进去并保存。
• 保存令牌后刷新仪表盘页面，重新尝试连接。

批准待处理的设备配对请求

• 使用 OpenClaw CLI 或容器命令查看待批准的配对请求。
• Docker 环境下常用命令如下：

docker compose exec openclaw-gateway \
  node dist/index.js devices list

• 会列出带有 ID 的待处理请求。
• 批准某个设备使用以下命令：

docker compose exec openclaw-gateway \
  node dist/index.js devices approve <ID>

• 批准完成后，仪表盘应该能正常连接，不再显示 1008 错误。

配置变更后重新配对

• 如果重新安装了浏览器应用或清除了本地存储，原有设备身份会丢失。
• 此时需要重新配对：打开仪表盘，粘贴令牌，在提示出现新设备请求时批准即可。

检查网络与代理设置

• 在某些托管环境或使用反向代理时，请求到达网关的地址可能被改变。
• 网关可能将这些请求视为不受信任来源，从而强制要求配对。
• 建议正确配置受信任代理，或在合适场景下将网关绑定到 localhost，让客户端被识别为本地连接，直接接受令牌。

实用小贴士

• 使用 Docker 时，强烈建议通过localhost:18789访问仪表盘，远程主机或非标准端口容易导致令牌认证失败。
• 每次修改配置后，建议重启网关服务：openclaw gateway restart。
• 如果问题仍未解决，请查看网关日志，查找设备不匹配或网络拒绝的相关提示。

总结

OpenClaw 通过存储设备凭证和配对令牌来保障远程访问安全。只有经过明确批准的客户端才能控制网关。这种配对机制也让终端 CLI 之外的节点或应用能够可靠运行。

只要正确完成令牌配置和设备配对，网关就能稳定连接。你将获得完整的 Control UI、日志查看和管理功能，再也不用反复面对配对提示。