claude code 401 报错

用 Claude Code 写着写着突然弹 401，常见于换过 Key、切过中转站、改过环境变量或终端换了 shell 之后。这篇不讲原理，只给一条从低成本到高成本的排查顺序：先确认是哪一层在拒绝你，再逐项改配置并验证。读完你能自己判断是 Key 失效、变量没生效，还是中转侧鉴权头不匹配。

用 Claude Code 写着写着突然弹 401，多数不是网络挂了，而是鉴权那一环出了问题。常见触发场景就那么几个：刚换过 API Key、刚切过中转站、改过环境变量、或者换了个终端和 shell。401 的意思是「服务端收到了你的请求，但不认你带的凭据」，所以排查方向始终围绕「凭据从哪来、有没有传对、对面认不认」三条线。

下面给一条从低成本到高成本的排查顺序：先确认是哪一层在拒绝你，再逐项改配置并当场验证。别一上来就重装工具或换账号，那是最贵的动作，往往也是最没必要的动作。

先判断是哪一层在拒绝你

401 和网络不通要分开看。如果报错里带上了上游返回的信息，说明请求已经打到服务端，纯粹是鉴权被拒；如果连不上、超时、DNS 失败，那是另一类问题，不在这篇范围。先把这两类分开，能省掉一半无效操作。

• 看报错原文有没有上游返回体：有，说明请求到了服务端，问题在凭据或鉴权头；没有，先确认网络和 Base URL 可达
• 分三层定位：本地压根没读到凭据、凭据本身已失效、中转或网关侧不认这个鉴权头格式
• 低成本验证：拿同一条 Key 走一次最简请求，绕开 Claude Code 自身配置，看是工具问题还是 Key 问题
• 横向对照：同一个 Key 在别的客户端正常、只有 Claude Code 报错，基本就锁定在工具自己的配置读取上

检查凭据与环境变量有没有真的生效

这一层最容易被忽略：变量改了，但当前进程根本没读到。shell 配置文件、项目级配置、系统环境变量三者优先级不同，生效范围也不同。判断标准很简单——新开一个终端，把变量打印出来看，而不是凭记忆觉得「应该生效了」。

1. 确认变量来源先搞清楚当前 shell 读的是哪一份配置，再决定往哪儿改。
2. 重新加载改完配置新开终端或重载配置，旧进程不会自动读新值。
3. 核对待值把变量值原样打印出来，看有没有多余引号、结尾空格或混进换行。
4. 单点验证只改这一项就验一次，通过再做下一步。

走中转站时最容易踩的鉴权坑

如果请求经过中转站或网关，鉴权的判断点就不在你本地了，而在对面认不认你带的这个鉴权头。协议格式不匹配时，往往在网关层就被判 401，根本到不了内容层，这种情况下你怎么调模型参数都没用。

鉴权头格式

中转侧可能只认某一种写法，格式不对直接在网关被拒，表现为 401

Base URL

少写或多写路径段，会把请求送到没有鉴权逻辑的入口

凭据残留

换站后旧 Key 没清干净，工具同时带两套凭据，服务端取到的是错的那一个

站点可信度

挑站前看它的检测记录和鉴权口径，别只看宣传页

选站和核对口径时，别只信页面上的宣传。到站内的站点目录和检测工具看它的实际记录，具体条目和当时的检测结果以页面为准。

改完怎么验证，以及什么情况不用继续折腾

排查最大的坑是「一次改五个地方」，改完失败了你也不知道是哪项起的作用。正确做法是改一项、验一次，把变量控制住。验证也分梯度：先用最简请求确认鉴权通了，再跑一个真实小任务，最后才回到日常用法。

• 验证顺序：最简请求 → 真实小任务 → 日常用法，逐级确认，别一步到位
• 换新 Key、清旧变量、换个客户端仍报 401，问题多半在账号或中转侧，继续改本地配置没意义
• 团队多人同时报错，先怀疑共享凭据或网关侧变更，而不是挨个查每个人的本地环境
• 确认是服务侧问题时，直接找服务方核对，比在本地反复试更快

想确认是不是服务侧异常（比如限流或鉴权口径临时调整），可以到站内的服务状态页看有没有对应记录，具体状态和当时的说明以页面显示为准，不要凭猜测下结论。