401 通常表示请求已经到达服务端，但凭证没有被认可，所以先别急着换网络或重装 SDK。要判断的其实是三件事：你手上的 key 是不是中转服务方发的、请求打到的域名是否与这把 key 配套、以及客户端实际发出的 Authorization 头有没有被改写或丢失。把这三项固定下来，再复现一次最小请求，绝大多数 401 都会收敛到某一项上；如果三项都正常仍然 401，就要看错误信息是上游返回的还是中转层返回的，两者排查方向不同。
401 是认证层面的失败，不是连通性失败。先看错误体由谁返回：message 来自中转层，多半是 key 与中转域名不匹配，或请求头在中间环节被覆盖；来自上游，则重点查 key 是否过期、被禁用、没有该模型权限。用最小 curl 复现，再逐项对比 SDK 实际发出的 Authorization 头，是收敛最快的一步。改完以返回 200 且响应含正常 usage 字段确认，不要以“没超时”当作成功。
先确认当前场景和目标
这个问题成立的前提是：请求能建立连接并拿到 HTTP 响应，响应码为 401，且通常带一段 JSON 错误体。如果客户端表现是超时、DNS 解析失败、连接被重置，那不属于本文范围，应先去查域名解析和出网策略。
动任何配置之前，建议先确认下面几项，缺一项就容易反复试错：
- 调用用的是中转服务方发放的 key，还是上游厂商的原始 key。两者不能混用，中转域名只认中转方发的 key。
- base_url 填的是中转域名，还是 SDK 默认的官方地址。很多客户端只改 api_key 没改 base_url，结果就是拿中转 key 去打上游。
- 错误体里的 message 或 code 是中转层写的，还是上游透传的。有经验的中转会在错误体里加自己的标识，先读这段文本再判断。
- 401 与 403 要分开看：401 是凭证没被认可，403 是凭证被认可但权限不够。把 403 当 401 排查，会一直卡在换 key 上。
按这个顺序处理
第一步，用最小请求复现，把 SDK 和业务代码全部撇开。下面的骨架只保留必要字段，把域名、模型名替换成中转方给你的实际值：
curl -i https://<中转域名>/v1/chat/completions \
-H "Authorization: Bearer $AI_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<模型名>",
"messages": [{"role": "user", "content": "ping"}],
"max_tokens": 16
}'加上 -i 是为了同时看到状态行和响应头，便于判断请求到底有没有打到预期服务。如果这条 curl 返回 200，说明 key 和域名本身可用，问题出在客户端侧。
第二步，检查 key 字符串本身。Authorization 头必须是 Bearer 加一个空格再加 key，多一个空格、少一个空格、换行符混进去都会导致 401。key 从文件或环境变量读取时尤其容易带上尾部空白或回车符，可以先确认一下长度和字节内容：
printf '%s' "$AI_API_KEY" | wc -c
printf '%s' "$AI_API_KEY" | od -c | tail -n 2如果字节数和你在后台看到的 key 长度不一致，基本就是复制时带了不可见字符。
第三步，检查环境变量覆盖。多数 SDK 会优先读 OPENAI_API_KEY、OPENAI_BASE_URL 这类变量，代码里传了参数也可能被环境变量或配置文件里的旧值覆盖。可以先在运行环境里打印实际生效值，确认没有被上一套配置残留影响。
第四步，确认 base_url 与路径拼接。/v1 是否已经包含在 base_url 里，各家 SDK 处理方式不一致：有的会自动补 /v1/chat/completions，有的要求你写全。拼接错了有时反馈的是 404，但也有中转会把未知路径一并回成 401，所以不要只凭状态码判断。
第五步，看链路中间有没有改写请求头。经过网关、反向代理或某些客户端插件时，Authorization 可能被剥掉或替换。这里常见的表现是：curl 直连正常，走应用链路就 401。可以先在服务端日志里核对收到的请求头是否存在。
第六步，如果以上都正常，再联系中转方确认 key 状态：是否已过期、是否超额度、是否被禁用、当前分组是否有目标模型权限。这类信息只有服务方后台能看到，自己猜不出来。
改完后怎么验证
验证要分层做，避免一次改多处之后不知道是哪一处起了作用。
- 先跑那条最小 curl，预期信号是状态行 200，响应体里有正常的
choices与usage字段。只看“有返回”不够，错误体同样有返回。 - 再用业务代码里的 SDK 跑同一个模型、同一段消息。如果此时仍然 401，就把 SDK 的请求日志打开，或者用调试代理抓一次实际发出的 URL 和请求头，与 curl 逐项比对，通常差异就在 base_url 或 Authorization 上。
- 换一个模型名再试一次。换成别的模型后能通，说明原模型没有权限，属于 403 类问题被包装成了 401；仍然不通，则仍是凭证层面的问题。
- 观察错误体的变化趋势：从 401 变成 404，说明认证通过了但路径不对；变成 429，说明认证已经通过、只是触发了限流。这两种都算往前推进了一步。
容易忽略的边界
一是不要把 401 一律当成自己的配置问题。key 轮换、后台重置、服务方临时故障都可能让一批调用同时失败。可以先确认同一时间其他调用方是否正常，再决定要不要改自己的配置。
二是密钥不要写进前端代码、日志或提交记录。排查时打印 key 只打前几位和后几位，中间用固定字符替代，确认长度即可。
三是部分中转对请求头的字段名有约定，Authorization、x-api-key、api-key 并非所有实现都接受同一种，这一点只能以服务方说明为准，不要靠试错硬猜；如果服务方只支持某种形式而你用的 SDK 固定写死另一种，回退方案是换用支持自定义请求头的客户端，而不是去改 SDK 内部私有字段。
四是保留两套配置分开放：一套直连、一套中转，用环境变量切换，并给变量加上能区分的名字。这样下次再出现 401，可以直接判断当前生效的是哪一套，不必回溯改动历史。
五是 SDK 版本差异会影响 base_url 的处理方式，升级或降级后行为可能改变。如果不是为了修复具体问题，排查期间不建议同时升级版本，否则会把配置问题和版本问题搅在一起。