解决 Web UI 配对要求问题

当您在 容器化部署（Docker、Kubernetes 等）中访问 Web 界面时，可能会遇到错误：

disconnected (1008): pairing required

这个错误通常 不会 出现在本地直接运行的部署中，因为本地连接被自动识别为可信。

问题描述

症状

• Web UI 立即断开连接，显示错误消息
• 浏览器控制台显示 WebSocket 关闭代码 1008 和原因 pairing required
• 但其他渠道（Feishu、Telegram、Discord 等）能正常工作
• 网关日志显示类似：[ws] closed before connect ... reason=pairing required

示例日志

openclaw-gateway-1 | 2026-02-01T06:35:03.089Z [ws] closed before connect conn=823f4c49-... 
remote=192.168.65.1 origin=http://localhost:18789 reason=pairing required

根本原因

Web UI 连接的认证路径取决于连接如何到达网关：

部署方式	WebSocket 源	识别方式	需要配对？
本地直接运行	localhost/127.0.0.1	真正的本地连接	❌ 不需要
Docker（同主机）	127.0.0.1（经容器栈）	网络连接	✅ 需要配置
远程服务器	LAN/Internet IP	网络连接	✅ 需要配置
Kubernetes	Pod 内部 DNS	网络连接	✅ 需要配置

在容器化部署中，即使浏览器访问 http://127.0.0.1:18789/，WebSocket 连接也经过容器网络栈处理，因此被视为网络连接而触发严格的设备配对检查。

解决方案

方案 1：启用 Web UI 不安全认证（推荐）

这是最简单、最推荐的解决方案。它告诉网关允许基于令牌的 Web UI 认证，无需设备配对。

本地部署：

openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

Docker 部署：

docker compose run --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true
docker compose restart openclaw-gateway

手动编辑配置文件：

编辑 ~/.openclaw/openclaw.json，在 gateway 部分添加：

{
  "gateway": {
    "port": 18789,
    "mode": "local",
    "bind": "loopback",
    "auth": {
      "mode": "token",
      "token": "your-token-here"
    },
    "controlUi": {
      "allowInsecureAuth": true
    }
  }
}

然后重启网关。

方案 2：使用 HTTPS + 设备认证

如果您在远程服务器上运行网关，最安全的方法是使用 HTTPS 和设备认证。

# 设置 Tailscale Serve（推荐用于远程）
openclaw configure gateway.tailscale.serve

# 或配置反向代理使用 HTTPS
openclaw config set gateway.controlUi.basePath https://your-domain.com

然后通过 HTTPS 访问 Web UI，浏览器将能够生成设备身份进行加密配对。

参见 Tailscale 和 控制 UI。

验证配置

确认配置已正确应用：

# 方法 1：检查配置值
openclaw config get gateway.controlUi.allowInsecureAuth

# 方法 2：查看整个配置
openclaw config get gateway.controlUi

# 方法 3：检查配置文件
cat ~/.openclaw/openclaw.json | grep -A 3 controlUi

应该看到 allowInsecureAuth 设置为 true。

网关重启检查

重启后，检查网关日志确认配置已加载：

# 本地
openclaw logs --follow | grep -i "controlUi\|allow"

# Docker
docker compose logs -f openclaw-gateway | grep -i "control"

然后尝试重新打开 Web UI（刷新浏览器）。

安全考量

为什么这是安全的？

1. 网络隔离

   • gateway.bind=loopback 限制网关仅在本地监听
   • 容器内部部署不会暴露给外部网络
   • 仅具有网络访问权限的用户可以尝试连接

2. 令牌认证

   • 即使启用 allowInsecureAuth，所有 Web UI 连接仍需有效令牌
   • 令牌由 docker-setup.sh 自动生成，不在日志中暴露
   • 无效或缺失令牌的请求被拒绝

3. 应用于 Web UI 仅

   • allowInsecureAuth 仅影响 Web UI（Control UI）连接
   • 不影响其他渠道或 API 的认证
   • 设备配对仍对其他连接类型应用

何时不应使用

• ❌ 公网服务器：如果网关直接暴露到互联网，不要启用此选项。改用 HTTPS + 设备认证。
• ❌ 共享主机：如果多个用户可以访问本机，应使用设备认证进行更强的隔离。

常见场景

场景 1：Docker Compose 本地开发

# 一次性修复
docker compose run --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true
docker compose restart openclaw-gateway

# 然后在浏览器中打开
open http://127.0.0.1:18789/?token=$(cat ~/.openclaw/openclaw.json | jq -r '.gateway.auth.token')

场景 2：Kubernetes 部署

# 在 Pod 中执行
kubectl exec -it <pod> -- /bin/sh -c \
  'openclaw config set gateway.controlUi.allowInsecureAuth true'

# 端口转发到本地
kubectl port-forward svc/openclaw-gateway 18789:18789

# 打开 Web UI
open http://127.0.0.1:18789/?token=...

场景 3：远程 VPS 部署

# SSH 到服务器
ssh user@vps-host

# 设置配置
openclaw config set gateway.controlUi.allowInsecureAuth true
openclaw gateway restart

# 从本地机器通过 SSH 隧道访问
ssh -L 18789:localhost:18789 user@vps-host

# 打开浏览器
open http://127.0.0.1:18789/?token=...

故障排除

仍然显示 "pairing required"

1. 确认网关已重启

   openclaw gateway status

   查看是否显示最近启动时间。

2. 检查配置文件

   cat ~/.openclaw/openclaw.json | jq '.gateway.controlUi'

   应该看到 { "allowInsecureAuth": true }

3. 查看网关日志

   openclaw logs | tail -50 | grep -i "control\|pairing"

   查找任何配置加载错误。

4. 清理浏览器缓存

   • 清除浏览器缓存或使用无痕窗口
   • 尝试不同的浏览器

Docker 中的权限错误

# 如果遇到权限错误，尝试显式指定用户
docker compose run --user node --rm openclaw-cli config set gateway.controlUi.allowInsecureAuth true

相关文档

• 控制 UI
• 网关认证
• 设备配对
• 令牌不匹配
• Tailscale 集成
• Docker 部署