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

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

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

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

这是小白最常见的一种误操作。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 的认证框里再连。

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 机器的门。

这个坑非常阴。官方 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 地址，官方还特别强调：必须要有有效的认证路径，不能裸奔绑定。

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 
   
     
     
       --role operator openclaw devices remove 
      
        openclaw devices approve 
        
        
       
     

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

很多人忽视了一点：你在聊天界面里看到的 401，不一定是 OpenClaw 自身的认证失败，也可能是它向 OpenAI、Anthropic、Google 等模型提供商发请求时，被对方判成未授权。官方模型认证文档明确写到，OpenClaw 支持 API Key、OAuth、Claude CLI 复用等多种模式；但对于长期运行的 Gateway，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，也同理，把对应的 _API_KEY 放进去。

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 映射关系，永远看不出来。

官方 FAQ 提到了一个非常实用但容易被忽视的问题：OpenClaw 的 auth profiles 是按 agent 存储的，当前路径是 ~/.openclaw/agents/ /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 配 auth，要么把主 agent 的 auth-profiles.json 复制到新 agent 的对应目录。

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

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

如果你的 OpenClaw 接了外部聊天平台、Webhook 或第三方触发接口，那么 401 还可能根本不发生在模型层，也不发生在控制面板层，而是发生在外部平台回调 OpenClaw 时。官方 Webhooks 文档写得很清楚：每个请求都必须带 hook token，推荐走 Authorization: Bearer ，也支持 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 ，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 
   
     
     
       --role operator openclaw devices remove 
      
        openclaw devices approve 
        
        
       
     

这套是官方给的 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。

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

真正高效的排查方式，是先问自己一句：是谁在拒绝谁？

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