本页介绍如何打开和认证 OpenClaw Gateway 的浏览器仪表盘（Control UI）。默认地址 http://localhost:18789/，支持 token、密码、Tailscale Serve 身份头、trusted-proxy 四种认证方式。涵盖 SecretRef 管理 token 时的行为、AUTH_TOKEN_MISMATCH 重试机制、token 漂移修复，以及 1008 错误排查。

仪表盘（Dashboard / Control UI）

Gateway 仪表盘是浏览器 Control UI，默认在 / 路径提供服务（通过 gateway.controlUi.basePath 覆盖）。

快速打开（本地 Gateway）：

• http://127.0.0.1:18789/（或 http://localhost:18789/）

关键参考：

• Control UI——使用方法和 UI 功能。
• Tailscale——Serve/Funnel 自动化。
• Web 接口——绑定模式和安全说明。

认证通过 WebSocket 握手强制执行，方式为：

• connect.params.auth.token
• connect.params.auth.password
• 当 gateway.auth.allowTailscale: true 时的 Tailscale Serve 身份头
• 当 gateway.auth.mode: "trusted-proxy" 时的可信代理身份头

详见 Gateway 配置 中的 gateway.auth。

安全注意：Control UI 是管理员界面（聊天、配置、exec 批准）。不要将其公开暴露在互联网上。UI 在 sessionStorage 中保存当前浏览器标签会话和所选网关 URL 的仪表盘 URL token，并在加载后从 URL 中清除。优先使用 localhost、Tailscale Serve 或 SSH 隧道。

快速路径（推荐）

• 引导完成后，CLI 自动打开仪表盘并打印干净的（无 token 化的）链接。
• 随时重新打开：openclaw dashboard（复制链接，如果可能则打开浏览器，无头环境显示 SSH 提示）。
• 若 UI 提示共享密钥认证，将配置的 token 或密码粘贴到 Control UI 设置中。

认证基础（本地与远程）

• 本地：打开 http://127.0.0.1:18789/。
• 共享密钥 token 来源：gateway.auth.token（或 OPENCLAW_GATEWAY_TOKEN）；openclaw dashboard 可以通过 URL 片段传递 token 用于一次性引导，Control UI 将其保存在 sessionStorage 中（针对当前浏览器标签会话和所选网关 URL）而非 localStorage。
• 若 gateway.auth.token 由 SecretRef 管理，openclaw dashboard 按设计打印/复制/打开无 token 化的 URL，避免在 shell 日志、剪贴板历史或浏览器启动参数中暴露外部管理的 token。
• 若 gateway.auth.token 配置为 SecretRef 但在当前 shell 中未解析，openclaw dashboard 仍会打印无 token 化的 URL，并附带可操作的认证设置指引。
• 共享密钥密码：使用配置的 gateway.auth.password（或 OPENCLAW_GATEWAY_PASSWORD）。仪表盘不会跨重载持久化密码。
• 身份识别模式：当 gateway.auth.allowTailscale: true 时，Tailscale Serve 可通过身份头满足 Control UI/WebSocket 认证；非回环的身份感知反向代理可满足 gateway.auth.mode: "trusted-proxy"。在这些模式下，仪表盘无需粘贴共享密钥即可连接 WebSocket。
• 非本地访问：使用 Tailscale Serve、带 token 的非回环共享密钥绑定、带 gateway.auth.mode: "trusted-proxy" 的非回环身份感知反向代理，或 SSH 隧道。HTTP API 仍使用共享密钥认证，除非你有意运行私有入口的 gateway.auth.mode: "none" 或 trusted-proxy HTTP 认证。见 Web 接口。

遇到"unauthorized"或 1008 错误时

• 确认 Gateway 可访问（本地：openclaw status；远程：SSH 隧道 ssh -N -L 18789:127.0.0.1:18789 user@host 然后打开 http://127.0.0.1:18789/）。
• 对于 AUTH_TOKEN_MISMATCH：客户端可能在 Gateway 返回重试提示时用缓存的设备 token 进行一次可信重试。该缓存 token 重试会复用 token 的已缓存批准范围；显式指定 deviceToken 或 scopes 的调用方仍保留其请求的范围集。若重试后认证仍失败，需手动解决 token 漂移。
• 在该重试路径之外，连接认证优先级依次为：显式共享 token/密码 → 显式 deviceToken → 已存储的设备 token → 引导 token。
• 在异步 Tailscale Serve Control UI 路径上，同一 {scope, ip} 的失败尝试在失败认证限流器记录前会被串行化，因此第二个并发的错误重试可能已显示 retry later。
• Token 漂移修复步骤，请按照 Token 漂移恢复清单 操作。
• 从网关主机检索或提供共享密钥：
  • Token：openclaw config get gateway.auth.token
  • 密码：解析配置的 gateway.auth.password 或 OPENCLAW_GATEWAY_PASSWORD
  • SecretRef 管理的 token：解析外部 secret 提供商，或在此 shell 中导出 OPENCLAW_GATEWAY_TOKEN，然后重新运行 openclaw dashboard
  • 未配置 token：openclaw doctor --generate-gateway-token
• 在仪表盘设置中，将 token 或密码粘贴到认证字段，然后连接。
• UI 语言选择器在 Overview → Gateway Access → Language，注意是在"网关访问"卡片内，而非"外观"设置下。

常见问题

Q: openclaw dashboard 打印的链接没有 token，该怎么登录？

A: 当 gateway.auth.token 由 SecretRef 管理时，CLI 出于安全考虑不会将 token 暴露在 URL 或剪贴板中。打开仪表盘后，在设置页面手动粘贴 token，或在当前 shell 中导出 OPENCLAW_GATEWAY_TOKEN 环境变量后重新运行 openclaw dashboard。

Q: 为什么连接仪表盘时提示 AUTH_TOKEN_MISMATCH？

A: 通常是 Gateway 重启后 token 轮换导致客户端缓存的旧 token 失效。Gateway 会自动触发一次可信重试，若仍失败说明需要手动修复 token 漂移——运行 openclaw config get gateway.auth.token 获取当前有效 token，重新粘贴到仪表盘设置。

Q: Tailscale Serve 模式下还需要粘贴 token 吗？

A: 不需要。当 gateway.auth.allowTailscale: true 时，Tailscale Serve 的身份头本身即可满足认证，WebSocket 连接无需单独粘贴 token。注意本地回环连接（非 Tailscale 路径）仍走正常的 token/密码认证。