buma logo
电话：15550927555 微信：bm8150 坐标：山东临沂
预约咨询
OpenClaw · Dashboard · Authentication

OpenClaw unauthorized / AUTH_TOKEN_MISMATCH 怎么办：Dashboard 鉴权与 token drift 排查

如果你最近在搜 OpenClaw unauthorized、OpenClaw AUTH_TOKEN_MISMATCH、OpenClaw dashboard unauthorized、OpenClaw 1008、AUTH_DEVICE_TOKEN_MISMATCH、PAIRING_REQUIRED，大概率不是想看一句“把 token 填对就行”，而是已经卡在 Dashboard 能打开但连不上、Control UI 一直 unauthorized、换了机器后突然 1008、同一个网关有人能进有人进不去，或者明明 token 没改过却还是报 mismatch。按 OpenClaw 官方 Dashboard、Gateway troubleshooting、openclaw devices 与中文文档的共同口径，这类问题不能只靠刷新页面。更稳的顺序是先确认网关目标和 URL，再看共享 token，再区分设备 token 是否漂移，最后判断是不是设备审批或角色授权没过。很多人表面看到的是同一个 unauthorized，底层其实是四类不同问题。

咨询排障思路 返回文章中心

发布时间

2026-03-14

作者

BUMA 内容团队

资料来源

OpenClaw 官方 Dashboard / Gateway troubleshooting / devices、Clawdbot 中文文档

适合谁看

正在排查 Dashboard unauthorized、1008、token drift、设备授权失败的人

Quick Judgment

先说结论：unauthorized 不是一个问题，而是至少 4 层不同故障

OpenClaw 官方 Gateway troubleshooting 已经把 Dashboard / Control UI 的 auth 细节码拆得很清楚。真正高效的做法不是盯着“为什么报 unauthorized”，而是先认清返回的细节码到底是哪一个。

01

AUTH_TOKEN_MISSING

客户端根本没带共享 token。最常见是本地页面开对了，但 Control UI 设置里没填 token，或者显式指定 URL 后没有同步带凭据。

02

AUTH_TOKEN_MISMATCH

客户端带了 token，但跟网关当前共享 token 不一致。高频场景是 token 改过、连错网关、或旧浏览器会话还缓存着老 token。

03

AUTH_DEVICE_TOKEN_MISMATCH

共享 token 可能没错，但某台设备之前缓存的 per-device token 已经过期、被轮换或被撤销，导致设备身份链路失配。

04

PAIRING_REQUIRED

设备身份已经被识别到，但当前角色还没有通过审批。也就是说，它不是“密码错了”，而是“这台设备还没被允许做这个角色”。

05

device identity required

更偏安全上下文或设备握手问题，常见于非安全上下文、缺少设备身份信息、或连接方式不满足设备认证前提。

06

重复 1008 / reconnect loop

它通常只是握手被策略拒绝的表面表现。真正根因仍要回到 token、device token、pairing 或连接目标上拆。

为什么同样是 Dashboard 连不上，官方会让你先看 auth detail code？

因为 unauthorized 只是大类结果，不足以指导动作。OpenClaw 官方 Gateway troubleshooting 里专门给了 error.details.code 的 quick map，就是为了避免你把不同层级的问题混在一起处理。比如 AUTH_TOKEN_MISSING 代表客户端没送共享 token；AUTH_TOKEN_MISMATCH 代表共享 token 与网关当前值不一致；AUTH_DEVICE_TOKEN_MISMATCH 代表设备级 token 漂移；PAIRING_REQUIRED 代表设备身份被识别到，但当前角色还没批准。如果你没先分层，最容易做的错误动作就是一直重开页面、重启网关，最后还是回到原点。

Dashboard 官方文档还补了一个很关键的背景：Control UI 的认证是在 WebSocket 握手阶段通过 connect.params.auth 强制执行的。也就是说，页面能打开，不代表认证已经通过；浏览器能看到 UI，也不代表你的握手参数、共享 token、设备 token 一定是对的。很多用户会把“页面能渲染出来”误当成“服务一定正常”，但真正失败的往往发生在连接握手这一步。

对中文用户来说，这篇最重要的价值是把“看起来都像 unauthorized”的问题拆成可执行路径。只要细节码看对了，下一步该查什么，其实会非常明确。

Dashboard unauthorized 的第一轮排查，官方顺序应该怎么走？

第一步：openclaw gateway status。先确认网关服务是不是在跑，别在服务没起来的前提下排 auth。

第二步：openclaw status。补看总览，确认你当前 CLI 指向的网关目标、配置主线和基本状态没有明显偏差。

第三步：openclaw logs --follow。把握手阶段的报错抓出来，重点看是 AUTH_TOKEN_MISSING、AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH 还是 PAIRING_REQUIRED。

第四步：openclaw doctor。它不是只查模型和环境，也会帮助你发现配置与服务层的阻塞，避免你对着前端现象乱猜。

第五步：openclaw gateway status --json。官方 troubleshooting 专门把它放进 Dashboard 场景里，用于更精确地核对 probe URL、dashboard URL 与连接目标。

如果是远程网关，Dashboard 官方页还明确建议：先保证 URL 可达，必要时用 SSH 隧道把远程 127.0.0.1:18789 映射回来，再去看 token。因为连错目标时，你看到的 token mismatch 很可能只是“你连的根本不是你以为的那个网关”。

Detail Codes

4 个最关键的 auth 细节码，分别该怎么处理

先认码，再决定动作。别把设备审批问题当 token 错误，也别把 token 漂移当成网关宕机。

AUTH_TOKEN_MISSING：没带共享 token

这类问题最直接，意思就是客户端没有把必须的共享 token 带到握手里。官方 Dashboard 页给出的处理是：先从网关主机确认 gateway.auth.token，如果没有配置就用 openclaw doctor --generate-gateway-token 生成；如果是 SecretRef 管理的 token，就先确保当前 shell 能解析到它，再重新执行 openclaw dashboard。对使用 Control UI 的人来说，更实际的动作是把 token 粘进设置页的 auth 字段，然后重新 connect。

这类问题最怕的是“以为自己已经填过”。如果你切换了浏览器标签页、切了不同网关 URL、或者从本地改成了远程 URL，当前会话里保存的 token 可能并不会自动跟着切过去，所以仍然要按当前连接目标重新确认一遍。

AUTH_TOKEN_MISMATCH：共享 token 漂移

官方 Troubleshooting 的说法很直接：如果网关返回 canRetryWithDeviceToken=true，客户端可以做一次可信重试；如果重试后仍然失败，就要按 token drift 的方向人工修。也就是说，这不是单纯“输错了一次”的概念，而更像是客户端和服务端对当前 token 版本已经失去同步。

高频场景包括：网关 token 刚被改过、你连到了另一台网关、某个浏览器会话里还保留着旧 token、团队里有人把共享 token 更新了但当前设备没同步到。此时继续只刷新 Dashboard 基本没用，更稳的动作是先确认网关主机上的当前 token，再重新输入或更新当前客户端。

AUTH_DEVICE_TOKEN_MISMATCH：设备级 token 失效

这类问题更容易被忽略，因为很多人只盯共享 token。官方 openclaw devices 文档明确给了 token drift recovery checklist：先确认当前共享 token 来源，再用 openclaw devices list 找到受影响设备，然后执行 openclaw devices rotate --device <deviceId> --role operator；如果轮换还不够，再移除旧设备记录、重新批准 pairing。换句话说，这一类更像“设备身份缓存坏了”，不是“网关密码错了”。

如果你换过浏览器环境、迁移过机器，或者管理员做过设备 token 轮换，这一类就尤其常见。它的修法也不在前端，而在设备记录管理层。

PAIRING_REQUIRED：设备还没拿到当前角色权限

官方 quick map 的解释是：设备身份已知，但还没被批准用于当前角色。也就是说，网关知道你是谁，但还没允许你以这个角色连接。下一步动作不是换 token，而是去看 openclaw devices list，然后执行 openclaw devices approve <requestId> 或 --latest。如果你跳过这一步，只会陷入“token 明明没错，为什么还是 unauthorized”的循环。

这类问题在多设备协作、远程控制台、节点或新浏览器首次接入时更常见。它不是错误输入，而是安全审批流程的一部分。

OpenClaw token drift 官方恢复清单，最该怎么用？

如果你遇到的是反复 AUTH_TOKEN_MISMATCH 或 AUTH_DEVICE_TOKEN_MISMATCH，最值得照抄的不是论坛经验，而是官方 devices 文档里的 token drift recovery checklist。顺序是这样的：先用 openclaw config get gateway.auth.token 确认当前网关共享 token；再用 openclaw devices list 找到受影响设备；然后对该设备执行 openclaw devices rotate --device <deviceId> --role operator；如果轮换还不够，再移除旧设备，再重新 approve pairing；最后再让客户端带着当前共享 token 重新连接。

这个顺序很关键，因为它说明 OpenClaw 的 auth 漂移并不只有一层。共享 token、设备 token、pairing 审批，这三条链任何一条漂移，都可能在前端表现成类似的 unauthorized。很多用户只修共享 token，不碰设备记录，所以会出现“我明明已经填了最新 token，为什么还是不行”的错觉。

如果你是团队环境，建议把这套恢复顺序写进内部 SOP。因为一旦有多人共用远程 Gateway，token 轮换、设备更换、浏览器切换会比单机环境频繁得多，auth drift 也更容易发生。

本地与远程 Dashboard，为什么排法不完全一样？

本地 Gateway 的快路径相对简单：直接打开 http://127.0.0.1:18789/，再用 openclaw dashboard 辅助打开或复制干净链接即可。官方还特别提醒：Control UI 是 admin surface，不应该公开暴露；更推荐 localhost、Tailscale Serve 或 SSH 隧道，而不是把它直接暴露在公网。

远程场景复杂在两个地方。第一，你得先确认自己连的是哪台网关；第二，远程 URL 与 auth 凭据必须成对正确。官方 devices 文档甚至强调：当你显式传入 --url 时，CLI 不会回退使用配置或环境里的凭据，必须显式传 --token 或 --password。这意味着很多“我明明配过 token”的案例，其实是因为你在新 URL 上没有同步带上对应凭据。

所以远程 Dashboard 出问题时，正确顺序通常是：先确认目标 URL，再确认 token 来源，再看设备审批，而不是直接把锅甩给浏览器或页面缓存。

一句话判断框架

OpenClaw Dashboard 出现 unauthorized、1008、AUTH_TOKEN_MISMATCH 时，先判断是没带共享 token、共享 token 漂移、设备 token 漂移，还是设备角色还没批准；这四类问题表面很像，修法完全不同。

最适合什么时候看这篇？

适合你已经确认 Dashboard 地址没错，但 Control UI 仍然 unauthorized、重连循环、1008、或换设备后突然全部失配时。先把鉴权层拆清，再去查网关服务或渠道问题，效率会高很多。

Related Reading

相关推荐

如果你现在卡的是控制台、服务启动、日志或设备批准，可以顺着这几篇继续看。

Need Help

想把 OpenClaw Dashboard 的 unauthorized 一次拆清？

如果你正在排查 token drift、设备授权、远程 Dashboard 连接或 1008 重连循环，我可以继续帮你把问题拆成共享 token、设备 token、pairing 和连接目标 4 层。

预约咨询 查看 FAQ