Low🔗 Connectivity#WebSocket

网关 WebSocket 持续断开和重新连接

作者 Jason Guo发布于 2026年3月5日更新于 2026年9月5日

// 浏览器控制 UI 显示无休止的'连接中...'旋转图标，或网关显示重复的 WebSocket 升级失败。通常由过期的认证令牌或缺少 CORS Origin 标头引起。

rotate_token.sh

✅ 修复方法 1 — 清除认证令牌并重新登录

过期令牌导致 WebSocket 401 → 快速重连循环

# 从浏览器清除过期认证令牌
localStorage.removeItem('openclaw_token')

# 或使用 CLI 重新生成令牌
openclaw auth rotate

# 然后重新加载控制 UI

cors.yaml

✅ 修复方法 2 — 将您的 Origin 添加到 CORS 允许列表

添加您的实际 Origin — 通配符 '*' 默认禁用

# 在 openclaw.yaml 中
gateway:
  cors:
    origins:
      - http://localhost:3000
      - https://your-custom-domain.com
      - http://192.168.1.100:3000  # 从局域网访问时的本地 IP

nginx.conf

✅ 修复方法 3 — 检查网关端口和反向代理标头

nginx WebSocket 代理配置

# nginx 示例 — 添加到您的 location 块
location /ws {
  proxy_pass http://localhost:8080;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
  proxy_read_timeout 86400;  # 24小时以防止超时断开
}

ℹ 常见于反向代理后端

如果 OpenClaw 在 nginx/Caddy/Traefik 后面，请确保 WebSocket 升级标头（Upgrade、Connection、Sec-WebSocket-*）被正确转发。缺少标头会导致 101 Switching Protocols 握手失败。

← 心跳泄露

❓ 常见问题

Q1. 如何判断认证令牌是否过期？

检查网关日志中是否有 '401 Unauthorized' 或 'token expired' 消息。也可以打开浏览器开发工具 → 网络标签，过滤 'WS' 查看 WebSocket 请求——快速循环且状态为 401 是最明显的迹象。在服务器端用 'openclaw gateway auth-token --show' 重新生成令牌，然后在浏览器中清除 localStorage（'localStorage.clear()'）以强制重新登录。

Q2. 反向代理会导致这个问题吗？

是的，这实际上是最常见的原因。不转发 WebSocket 升级头的反向代理（nginx、Caddy、Traefik、HAProxy）会导致握手失败，浏览器立即重试，形成循环。修复方法是在代理配置中添加 WebSocket 头：Upgrade、Connection、Host，以及较长的 proxy_read_timeout（24 小时用 86400）。没有超时延长，代理会在 60-90 秒后关闭连接。

Q3. 可以完全禁用控制 UI 吗？

可以。在 config.yaml 中设置 'gateway: ui: false' 并重启网关。代理仍可通过 CLI 和消息渠道（Telegram、WhatsApp、Discord）完全正常工作。如果在没有正确 HTTPS 的公共服务器上运行 OpenClaw，禁用 UI 还可以减少攻击面。

Q4. WebSocket 短暂连接后每 60-90 秒断开一次，是什么问题？

这几乎总是反向代理超时问题。代理在默认读取超时后（nginx 通常为 60 秒）关闭空闲的 WebSocket 连接。在 nginx 的 location 块中添加 'proxy_read_timeout 86400;' 将其延长到 24 小时。Caddy 可以使用 '@websocket' 匹配器。Traefik 的 WebSocket 超时由路由器配置中的 'readTimeout' 控制。

Q5. 浏览器控制台出现 CORS 错误，如何修复？

当浏览器请求的 Origin 头与 openclaw.yaml 中的允许来源不匹配时，会出现 CORS 错误。将您的确切来源（协议 + 域名 + 端口）添加到 cors.origins 列表。常见错误：忘记端口号（'http://localhost' vs 'http://localhost:3000'）、使用 http 而非 https、或使用通配符（'*'）——OpenClaw 默认出于安全原因禁用通配符。在浏览器开发工具 → 网络 → 请求头中查看确切的 Origin 值。

Q6. 重连循环只对某些用户发生而不是所有人，为什么？

这表明问题特定于某些浏览器、网络条件或会话，而非服务器端配置问题。常见原因：(1) 某个用户有过期的缓存令牌而其他人有新令牌；(2) 该用户网络上的企业 VPN 或防火墙在终止 WebSocket 连接；(3) 用户在不在 CORS 允许列表中的不同子网。让受影响的用户从不同浏览器或网络尝试以缩小范围。

← 所有问题

✅ 修复方法 3 — 检查网关端口和反向代理标头

nginx WebSocket 代理配置

# nginx 示例 — 添加到您的 location 块
location /ws {
  proxy_pass http://localhost:8080;
  proxy_http_version 1.1;
  proxy_set_header Upgrade $http_upgrade;
  proxy_set_header Connection "upgrade";
  proxy_set_header Host $host;
  proxy_read_timeout 86400;  # 24小时以防止超时断开
}