OpenClaw 使用中出现 401 的原因分析：不是一个报错，而是三层认证同时在拦你

如果你刚接触 OpenClaw，建议先阅读 OpenClaw 新手排坑指南。\n\n很多人一看到 OpenClaw 报 401，第一反应就是"API Key 填错了"。这话有时候对，但只对一小部分情况。OpenClaw 的 401，本质上不是一个单一问题，而是至少三层认证中的某一层没有通过：第一层是 Gateway 自身认证，第二层是 模型提供商认证，第三层是 渠道、Webhook 或回调认证。更麻烦的是，有些场景里它不会直白打印一个标准 HTTP 401，而是表现成 unauthorized、WebSocket 1008、AUTH_TOKEN_MISMATCH、AUTH_DEVICE_TOKEN_MISMATCH，甚至是"明明服务在跑，但面板就是连不上"。官方文档也明确把这些情况放进了同一类故障排查路径里。

关于 401/403 的完整排查流程，也可以参考 OpenClaw 认证错误排查指南。\n\n所以，排查 OpenClaw 的 401，最怕的不是不会命令，而是一上来就猜错方向。你得先问清楚：这个 401，到底是 Gateway 在拒绝你，还是模型提供商在拒绝 OpenClaw，还是外部渠道回调在拒绝接入。只有先把"谁在拒绝谁"这件事弄清楚，后面的处理才不会越修越乱。官方推荐的第一组诊断命令也正是围绕这个思路展开的：先看 openclaw status，再看 openclaw gateway status，再跟日志 openclaw logs --follow，最后才是 openclaw doctor 和更细的 probe。

一、最常见的 401：Gateway 认证没通过

在 OpenClaw 里，Gateway 是控制平面。无论你是在控制面板里连 Web 界面，还是用 CLI 打远程 Gateway，或者调用它暴露出来的 HTTP 接口，首先过的都是 Gateway 这一关。官方文档写得很清楚，Gateway 常见认证模式有三种：token、password、trusted-proxy；如果是 token 或 password 模式，HTTP 侧要走 Authorization: Bearer <token-or-password>，而 Control UI / Dashboard 则在 WebSocket 连接阶段校验认证。

这就解释了为什么很多人会遇到一种很诡异的情况：网页能打开，服务也在跑，但一连接就是 unauthorized。这不是服务挂了，而是"地址打通了，认证没打通"。官方在 Dashboard 排障页里直接写出了几种典型细分码：AUTH_TOKEN_MISSING 表示客户端根本没带共享 token；AUTH_TOKEN_MISMATCH 表示带了，但和 Gateway 当前 token 不一致；AUTH_DEVICE_TOKEN_MISMATCH 表示缓存的设备 token 已经过期或被撤销；PAIRING_REQUIRED 则表示这个设备身份被识别了，但还没有被批准到当前角色。

1）最容易忽略的坑：你手动指定了 URL，却没带凭证

这是小白最常见的一种误操作。OpenClaw 官方文档明确说明：一旦你显式设置了 --url，CLI 就不会再从配置或环境里自动回退凭证；Control UI 也是一样，只要你用了 gatewayUrl，就必须显式提供 token 或 password，不会再自动帮你补。也就是说，你手动指定了远程地址，并不等于 OpenClaw 会自动知道你该用哪把钥匙。

这类问题的处理办法非常直接。先确认当前 Gateway 用的是什么认证：

openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw gateway status

如果你在用 Dashboard，官方建议直接在 Gateway 主机上取 token：openclaw config get gateway.auth.token；如果压根没配置共享密钥，可以用 openclaw doctor --generate-gateway-token 重新生成，然后把 token 粘到 Control UI 的认证框里再连。

2）远程模式、本地模式混了，连到了对的地址，却拿着错的钥匙

OpenClaw 最近的排障文档专门提醒了一个升级后很容易出现的问题：如果 gateway.mode=remote，CLI 可能正在打远程，而你本地服务其实是好的；相反，你以为自己在打本地，实际却在尝试远程 Gateway。官方给出的典型现象就是：gateway connect failed: 往往是 URL/端口错了，而 unauthorized 往往表示端点可达但认证不对。

所以别一见 401 就急着换 token，先查清楚你到底连的是谁：

openclaw gateway status
openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw status

如果你发现自己其实连错了目标，那怎么换密钥都没用，因为你是在拿 A 机器的 token 去敲 B 机器的门。

3）配置字段写旧了，看起来像有 token，实际上 Gateway 根本没认

这个坑非常阴。官方 Troubleshooting 页明确写到：旧字段如 gateway.token 并不能替代 gateway.auth.token。也就是说，配置文件里你觉得自己"明明写了 token"，但如果写在旧路径上，新的认证逻辑根本不认。结果表面上看就像：服务起来了，端口也通，偏偏 RPC probe 失败，或者面板连上来就 401。

处理办法就是别凭感觉改配置，直接检查真实配置路径：

openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token
openclaw config get gateway.bind
openclaw doctor

如果你把 Gateway 绑定到了 lan、tailnet 或 custom 这类非 loopback 地址，官方还特别强调：必须要有有效的认证路径，不能裸奔绑定。

4）token 漂移：最烦的一类"我明明没改，怎么突然 401 了"

OpenClaw 官方现在把这类问题叫 token drift。典型场景是：你曾经连通过 Dashboard 或其他客户端，后来 Gateway token 换了、设备 token 旧了，或者配对状态发生了变化。此时客户端还拿着旧凭证去连，就会出现 AUTH_TOKEN_MISMATCH 或 AUTH_DEVICE_TOKEN_MISMATCH。官方甚至专门给了一套 "Token drift recovery checklist"。

官方给出的修复顺序是：

openclaw config get gateway.auth.token
openclaw devices list
openclaw devices rotate --device <deviceId> --role operator
openclaw devices remove <deviceId>
openclaw devices approve <requestId>

简单理解就是：先确认当前 Gateway 的共享 token，再找出那台出问题的设备，先尝试旋转它的 operator token；如果还不行，就删掉旧配对，重新批准。官方文档明确说明，正常重连的认证优先级是：显式 shared token/password，接着显式 deviceToken，再到存储的 device token，最后才是 bootstrap token。也正因为这个优先级链条存在，旧状态残留时就会显得特别"玄学"。

二、第二类 401：不是 OpenClaw 拒绝你，而是模型提供商拒绝 OpenClaw

很多人忽视了一点：你在聊天界面里看到的 401，不一定是 OpenClaw 自身的认证失败，也可能是它向 OpenAI、Anthropic、Google 等模型提供商发请求时，被对方判成未授权。官方模型认证文档明确写到，OpenClaw 支持 API Key、OAuth、Claude CLI 复用等多种模式；但对于长期运行的 Gateway，API Key 通常是最稳定、最可预测的选择。

1）你在 shell 里配了 API Key，但后台服务根本没继承到

这是现实里最常见的一类。你在当前终端里 export OPENAI_API_KEY=...，手工跑一下也许可以；可只要 Gateway 是通过 systemd 或 launchd 跑起来的，它就未必继承你当前 shell 的环境变量。OpenClaw 官方文档明确建议：对于守护进程场景，更稳的做法是把密钥放进 ~/.openclaw/.env，然后重启 daemon，再用 openclaw models status 和 openclaw doctor 复查。

处理方式是这样的：

cat >> ~/.openclaw/.env <<'EOF'
OPENAI_API_KEY=你的key
EOF
openclaw models status
openclaw doctor

如果你用的是 Anthropic、Google 或别的 provider，也同理，把对应的 <PROVIDER>_API_KEY 放进去。

2）模型选对了，凭证没跟上

OpenClaw 的配置参考文档明确提醒：如果你直接选了某个 provider/model，就必须配置匹配的 provider 凭证。比如 google/* 需要 GEMINI_API_KEY 或 GOOGLE_API_KEY，openai/* 需要 OPENAI_API_KEY，fal/* 需要 FAL_KEY。这意味着一种很常见的误区：你以为是在改"模型"，其实你同时也切换了"认证体系"。

举个最典型的例子：你原来一直在跑 openai/gpt-5.4，后来切去 google/gemini-3.1-pro-preview，结果没有补 Google 的 key。你会感觉"我明明有 Key，为什么还 401"，但问题在于：你有的是 OpenAI 的 key，不是当前模型对应的 key。这个错，不排查 provider/model 映射关系，永远看不出来。

3）多 agent、多 auth store，结果你改的是错的那一份

官方 FAQ 提到了一个非常实用但容易被忽视的问题：OpenClaw 的 auth profiles 是按 agent 存储的，当前路径是 ~/.openclaw/agents/<agentId>/agent/auth-profiles.json。如果你是多 agent 结构，就可能存在多份 auth-profiles.json。这时你以为自己已经配置好了凭证，实际只是改到了另一个 agent 身上。官方对 No credentials found for profile anthropic:default 这类报错的修复建议，也明确要求你先确认 auth-profiles 到底落在哪个 agentDir。

所以一旦你怀疑是 provider 侧 401，别只盯着环境变量，也看看是不是 agent 配错了：

openclaw models status
openclaw status --all
openclaw doctor

如果是新 agent 没带认证，官方 FAQ 建议要么重新跑 openclaw agents add <id> 配 auth，要么把主 agent 的 auth-profiles.json 复制到新 agent 的对应目录。

4）OAuth 和 API Key 同时存在，表面像"认证丢了"

这个问题很隐蔽。官方 Model Failover 文档写得很直白：如果同一个 provider 下面同时存在 OAuth profile 和 API key profile，而你又没有固定 profile，OpenClaw 会按规则轮转，导致不同消息之间在不同凭证之间来回切换。官方原话甚至专门写了个小节，叫 "Why OAuth can look lost"。

处理办法有两个。第一，用 auth.order[provider] 固定 profile 顺序；第二，在支持的 UI/聊天界面里通过 …@<profileId> 把当前会话钉到一个特定 profile。否则你会感觉"刚刚还好好的，下一条怎么就未授权了"，其实不是凭证真的消失了，而是路由到了另一份 auth profile。

三、第三类 401：渠道、Webhook 或回调令牌校验失败

如果你的 OpenClaw 接了外部聊天平台、Webhook 或第三方触发接口，那么 401 还可能根本不发生在模型层，也不发生在控制面板层，而是发生在外部平台回调 OpenClaw 时。官方 Webhooks 文档写得很清楚：每个请求都必须带 hook token，推荐走 Authorization: Bearer <token>，也支持 x-openclaw-token，而 query string token 是被拒绝的。少这个 token，就是标准的未授权。

Mattermost 是另一个典型。官方配置参考里写明：原生 slash command 的回调，是通过 Mattermost 在注册命令时返回的每命令 token 来认证的；如果注册失败，或者命令根本没激活，OpenClaw 会直接拒绝该回调，并报 Unauthorized: invalid command token.。

BlueBubbles 也一样。官方文档明确强调：Webhook 认证始终是必须的；如果请求里没有带上与 channels.bluebubbles.password 匹配的 password/guid，OpenClaw 会直接拒绝 BlueBubbles webhook，请求体甚至还没来得及完整解析就会被挡掉。

Google Chat 则是另一种形态。官方 Google Chat 渠道文档说明，Google Chat 发给 Gateway 的 webhook POST 会包含 Authorization: Bearer <token>，OpenClaw 会在读取完整请求体前就先校验这个 bearer token，并把它和配置里的 audienceType 与 audience 做比对。也就是说，这不是"收到了再慢慢看"，而是你一开始就得满足它的受众验证规则。

四、最值得小白照抄的一套排查顺序

OpenClaw 的 401，最怕瞎改。真正稳的做法，是按层排。

先跑第一组总览命令：

openclaw status
openclaw gateway status
openclaw logs --follow
openclaw doctor

这是官方推荐的基础命令梯子，用来先判断是 Gateway 层、服务层，还是更上层的 provider/channel 问题。

如果你怀疑是 Gateway 认证，继续查：

openclaw config get gateway.mode
openclaw config get gateway.remote.url
openclaw config get gateway.auth.mode
openclaw config get gateway.auth.token

如果你用的是控制面板或远程 URL，记住一个硬规则：显式 --url 或 gatewayUrl 不会回退到已有凭证。要么显式带 token/password，要么回到默认本地链路。

如果你怀疑是设备 token 漂移，就查：

openclaw devices list
openclaw devices rotate --device <deviceId> --role operator
openclaw devices remove <deviceId>
openclaw devices approve <requestId>

这套是官方给的 token drift 修复流程。

如果你怀疑是模型提供商未授权，就查：

openclaw models status
openclaw doctor

然后确认 API Key 是否真的被 Gateway 进程继承，必要时把 key 放进 ~/.openclaw/.env，再重启服务。

如果你怀疑是渠道回调，就看具体渠道配置和日志，不要再盯着模型了。Mattermost 看 command token，BlueBubbles 看 password，Webhook 看 hook token，Google Chat 看 bearer 和 audience。

五、最后说句最实在的话：401 从来不是"一个错误"

OpenClaw 里的 401，最可怕的地方，不是它难，而是它太像。Gateway token 错了会像 401，设备 token 漂移会像 401，provider API key 没继承会像 401，Webhook 回调令牌不对也会像 401。你只要一股脑把所有未授权都归结成"API Key 不对"，后面就很容易在错误的方向上越修越深。官方文档其实早就把思路给透了：先分层，再定位，再处理。

理解 OpenClaw 审批机制 有助于理解权限控制逻辑。\n\n真正高效的排查方式，是先问自己一句：是谁在拒绝谁？

是你的浏览器被 Gateway 拒绝，还是 Gateway 被模型提供商拒绝，还是外部平台回调被 OpenClaw 拒绝。只要这个问题答对了，401 并不神秘；答错了，它才会像鬼一样缠着你。