Dashboard 认证引导与 token 漂移该怎么处理

最近官方对 openclaw dashboard 和 Web Dashboard 文档补得更细以后，一个很值得中文用户单独记住的点是：

• Dashboard 打不开，很多时候不是网页坏了
• 而是本地、远程、token、SecretRef 和浏览器状态混在一起了

第一原则：先区分你是在本地还是远程

这一步最重要。

更稳的判断通常是：

• 本地：直接确认 127.0.0.1:18789
• 远程：优先 SSH tunnel、Tailscale Serve 或明确 tailnet 入口

如果这一步不先分开，后面看到 1008 unauthorized 很容易误判。

第二原则：优先用 openclaw dashboard

根据当前官方 CLI 文档，openclaw dashboard 现在已经不只是“帮你打开浏览器”，而是在尽量走更稳的认证引导路径。

尤其是当：

• token 来自配置
• token 来自 OPENCLAW_GATEWAY_TOKEN
• token 来自 SecretRef

它比手打 URL 更少变量。

第三原则：SecretRef token 场景不要期待 tokenized URL

这是最近官方补得很值的一条边界。

当前 CLI 文档明确说明：

• 如果 gateway.auth.token 是 SecretRef-managed
• openclaw dashboard 会故意输出 non-tokenized URL

原因不是功能不全，而是为了避免把外部 secret 暴露到：

• 终端输出
• 剪贴板历史
• 浏览器启动参数

第四原则：浏览器里的 token 是临时引导，不是长期真相

根据最近官方 Web Dashboard 文档，Control UI 会：

• 把 URL token 从地址上剥掉
• 在当前浏览器 tab/session 范围内保存当前 gateway URL 的鉴权状态

这意味着浏览器缓存很重要，但它不是最终事实来源。
真正的 auth source 仍然应该回到：

• gateway.auth.token
• OPENCLAW_GATEWAY_TOKEN
• SecretRef 上游

第五原则：AUTH_TOKEN_MISMATCH 更像“状态漂移”而不是“站点坏了”

最近官方文档对 token drift 的处理已经更明确。
更稳的理解方式是：

• Gateway 端 token 变了
• 浏览器端还在拿旧值
• 当前实例归属或缓存状态漂了

这不是前端小故障，而是认证状态不一致。

一条更稳的恢复顺序

通常更适合按这条线走：

1. 先确认 Gateway 可达
2. 再确认当前是本地还是远程
3. 再跑 openclaw dashboard
4. 如果是 SecretRef token，优先回到 secret provider 或当前 shell 环境
5. 必要时在 Dashboard 设置里重新粘贴 token

最容易踩的坑

1. 远程时还拿本地 URL 判断

会把实例归属搞混。

2. 看到 non-tokenized URL 就以为 CLI 出错

在 SecretRef 场景下这反而是官方故意的安全设计。

3. 把浏览器缓存当最终 token 来源

真正的 token 还是要回到 Gateway 侧配置。

什么时候该怀疑 token 漂移

• 最近重生过 token
• 切过不同 Gateway
• 本地和远程实例来回切换
• 当前浏览器曾连接过别的环境

下一步推荐

• Dashboard 快速打开与认证行为
• SecretRefs 和运行时快照应该怎么理解
• 远程打开 Control UI 的正确方式