用完 OpenClaw 突然开始成片报 401，重启没用，换模型也没用，很容易误以为平台挂了。其实 401 说的是「身份没通过」，跟网络通不通、额度够不够是两回事。这篇不解释状态码定义，只给一条从本地配置到中转站后台的排查顺序，帮你几分钟内锁定是哪一层把凭证弄丢了。
用完 OpenClaw 突然开始成片报 401，重启没用，换模型也没用，这种情况很容易让人以为平台挂了。但 401 说的是「身份没通过」，跟网络通不通、账户里还有没有额度是两回事。网络断了通常是超时或连接拒绝，额度没了多半是 402 或别的提示，401 只指向一件事：对端没认出来你是谁。
所以别急着重装或者换工具。正确的做法是按鉴权链路从本地配置一路查到中转站后台，看是哪一层把凭证弄丢了。下面这条顺序按「先排除便宜的可能性」来排，多数情况在前两层就能定位。顺手可以先到 /tools/verify 看一眼中转站本身是否在线，确认不是整站故障。
先分清：401 是谁在拒绝你
同样是 401，来源不同，解法完全相反。OpenClaw 本地校验阶段就报 401，说明密钥字段压根没被读到，或者读到的是一段空值、占位符，跟服务端一点关系都没有。这种情况你去中转站后台翻半天日志，只会白忙。
另一种是请求已经发出去了、响应体里带着 401 回来，那才是中转站或上游在判断凭证。区分方法很简单：看报错是立刻弹出还是等了一会儿才回来；立刻弹的多半是本地校验，等网络往返的才是服务端响应。把这两种分开，后面的排查路径才不会走岔。
| 现象 | 大概率位置 | 先看哪里 |
|---|---|---|
| 报错瞬间出现，日志里没有出站请求 | 本地配置 | 配置文件、环境变量、密钥字段 |
| 有出站记录，响应体带 401 | 服务端鉴权 | 密钥状态、请求头格式、Base URL |
| 只在某个客户端里报，换个客户端就通 | 客户端配置 | 协议类型、字段名前缀、缓存配置 |
| 同一个密钥昨天通今天不通 | 平台侧 | 后台密钥是否被禁用或过期 |
第一层：密钥本身与请求头写法
第一层永远先怀疑密钥文本本身。复制粘贴最容易出的事是开头或结尾多带了引号、空格、换行，或者密钥被界面截断显示成省略号，你复制的是显示值而不是原值。这类问题肉眼很难看出来，把密钥粘到纯文本编辑器里看首尾字符最靠谱。
- 确认密钥前后没有引号、空格、换行，也没有被界面省略号截断
- 确认请求头字段名和前缀格式符合你所用协议的约定，两种协议的前缀写法不一样，混用必然被拒
- 确认后台里这把密钥是启用状态，没有被禁用、过期或者额度耗尽
- 确认环境变量和配置文件里写的不是同一个旧值，改了一处另一处还在生效
协议前缀这块特别容易踩。有的协议要求特定的头部字段名配特定前缀，有的则是另一种写法，抄网上示例的时候没对上自己实际用的协议，就会稳定报 401。密钥会被中间环节改写时，先到 /ai-dict/category/infra 对一遍常见字段名再动手，别凭记忆改。
还有一种情况是密钥本身没问题，但平台侧已经把它禁用了或额度耗尽。这类也会以 401 的形式返回，光看客户端永远看不出来，必须去后台确认密钥状态。判断标准：同一个密钥在另一个客户端也报 401，基本可以排除客户端问题，直接去后台。
第二层：中转站侧与 Base URL 指向
Base URL 是最隐蔽的一层。末尾多写或者少写一段路径，请求就可能打到不校验鉴权的端点上去，表现是 401，但根因是地址错了而不是凭证错了。尤其换过中转站的人，旧域名残留在配置里没清掉，看着像密钥失效，其实是打到了错误的服务器。
- 核对当前域名打开配置文件，看 Base URL 指向哪家。和你以为在用的那家对不对得上，域名拼写有没有细微差别。
- 核对路径段看末尾路径是否完整、是否多了斜杠。把完整 URL 拼出来，和文档里给的示例形式比一比。
- 换客户端对照拿同一把密钥在另一个客户端里发一次请求。那边通、这边不通，就把范围锁死在 OpenClaw 的配置侧。
- 回后台看记录到中转站后台看这条请求有没有出现在调用日志里。有记录说明请求到了，没记录说明压根没打对地址。
中转站本身的可信度和各家实测状态可以到 /sites 和 /rankings 对照，看你现在用的这家是不是近期状态就不稳定。要说明的是，如果报错里同时夹着 403 或 429，说明还叠加了权限或限流问题，那就不是单纯 401，本文的顺序得配合其他文章一起看。
第三层：OpenClaw 自己的配置文件与缓存
前面都排干净了，再回到 OpenClaw 自身。这一层最常见的坑是优先级打架：环境变量和配置文件同时存在，你以为改的是生效的那份，实际跑的是另一份被覆盖的值。改完一定要确认实际生效的是哪一份，别只看文件里写了什么。
另一个坑是热加载。改完配置后进程要完整重启，热加载不一定把新凭证读进去，尤其凭证类字段经常是启动时读一次就缓存在内存里。多人共用的机器上还要检查是不是有另一份全局配置把你的设置覆盖掉了，这种在团队环境里特别常见。
- 排查顺序
- 先看单条请求的原始报错文本，再逐层往前推，别一上来就重装
- 重启方式
- 确认是完整重启进程，不是热加载，凭证类字段尤其要冷启动
- 配置文件
- 确认实际生效的是哪一份，环境变量和配置文件的优先级要搞清
- 共享机器
- 检查有没有全局配置覆盖了你的个人设置
重装能解决的是文件损坏，解决不了配置优先级和缓存，前者少见，后者常见。
怎么让这类报错下次好查
与其每次出问题都从头猜，不如把容易出事的几项做成一份固定清单，出问题先对清单。清单不用复杂，覆盖密钥、Base URL、协议类型这三项就够，多数 401 都出在这三项上。
- 把密钥、Base URL、协议类型做成一份可对照的清单，出问题先对这三项
- 日志里留下请求头字段名和端点路径，方便回溯，但不要落盘完整密钥
- 团队里换个密钥就跑不通的情况，多半是分发环节被改过格式，统一走一个分发渠道
- 每次改配置后记录改了哪一份文件，下次好判断是不是优先级问题
团队分发密钥时最容易出格式问题：有人从聊天工具里复制、有人从文档里复制，引号和换行就在这一步被带进去。统一走一个分发渠道，能省掉很多这类排查。
适用范围也要说清：这套顺序针对的是鉴权类 401。如果你的报错里同时出现 403 或 429，说明权限或限流也出了问题，得配合对应方法一起看；如果中转站整站都在报错，那就不是你的配置问题，先去核对站点状态。各家价格与状态这类会变的数字，到 /sites 和 /price-watch 核对当时的数字。
下一步先确认你现在用的中转站是不是在线、近期状态稳不稳，再回本地对密钥和 Base URL，能少走很多弯路。→常见问题
密钥在别的地方能用，为什么 OpenClaw 里报 401？
大概率不是密钥失效，而是 OpenClaw 读到的不是你改的那份配置，或者请求头字段写法与协议约定不一致。先确认生效的配置文件路径，再对比一条成功请求和这条失败请求的请求头差异，通常两处就能对上。
换了中转站之后开始报 401，要动哪些地方？
重点看 Base URL 有没有跟着换，以及新站要求的鉴权头格式是否和旧站一致。密钥一般也要重新签发，旧密钥在新站是不认的。改完先到 /tools/verify 确认站点在线，再回客户端重启验证。
401 和额度用尽、被限流是一回事吗？
不是。额度耗尽和限流通常返回的是另外的状态码，401 只表示身份没通过。但有些平台会把密钥被停用这类情况也归到 401 里，所以除了看状态码，还要回中转站后台确认这只密钥当前是否处于可用状态。
