配置 Codex、ChatBox、Cherry Studio 或其他 AI 工具时，经常会遇到一个很让人困惑的问题：API Key 明明已经填了，但客户端还是提示 401。
很多人第一反应是“是不是 Key 不能用了”，但实际排查下来，401 不一定只和 Key 有关。接口地址、认证格式、模型名称、账号权限、额度状态，都可能让客户端返回类似的认证失败提示。
这篇文章按实际排查顺序整理一下。遇到 401 时，不建议一上来就反复重建 Key，可以先从下面 5 个地方看起。
1. 先看 base_url 有没有填错
很多 401 看起来像 Key 错了，其实是base_url填错了。
base_url是客户端请求接口的入口地址。很多工具支持 OpenAI 兼容 API，所以它们通常会让你填三个核心字段：
base_url api_key model这三个字段只要有一个不对，请求就可能失败。
base_url常见错误有这几种：
- 把官网登录地址填进去了
- 少写了
/v1 - 多复制了空格或换行
- 填成了文档页、控制台页，而不是接口地址
- 多写了一层路径，导致客户端实际请求地址不正确
一般来说，OpenAI 兼容接口会长得像这样：
https://yunshuapi.cn/v1这里以云舒 API 的接口地址为例。不同平台提供的地址不一样，实际使用时还是要以自己后台或文档里给出的接口地址为准。
如果你不确定地址是不是正确，可以看客户端实际报错里有没有请求 URL。有些工具会在日志里显示请求到了哪个地址，这个信息很有用。
2. 检查 API Key 有没有复制完整
API Key 建议重新复制一次，重点看这几个细节：
- 前后有没有多空格
- 有没有少复制一段
- Key 是否已经被删除、禁用或重置
- 当前工具是否读到了正确的环境变量
如果是命令行工具，可以先确认环境变量有没有设置成功：
echo$OPENAI_API_KEY如果这里输出为空，说明当前终端环境没有读到 Key。这个时候即使你在别的地方配置过，也不代表当前工具能拿到。
有些用户还会遇到一个情况：在终端里设置了环境变量，但从桌面应用启动的工具读不到。这是因为桌面应用和终端不一定共享同一套环境变量。遇到这种情况，可以优先在工具自己的设置页面里填 Key，或者按该工具文档要求写入配置文件。
公开发文章、截图或提交代码时，不要展示真实 API Key。示例里建议统一写成：
你的 API Key或者：
sk-xxxx不要把完整 Key 放出来。
3. 看认证字段是不是客户端要求的格式
不同工具的配置方式不完全一样。有的在界面里填 Key，有的读取环境变量，有的需要写在配置文件里。
以配置文件为例，思路大概是这样：
model_provider = "yunshu" model = "模型名称" [model_providers.yunshu] name = "Yunshu" base_url = "https://yunshuapi.cn/v1" wire_api = "responses" requires_openai_auth = true这里最关键的是三项：base_url、api_key、model。
如果客户端要求的是 OpenAI 兼容格式，一般会把 Key 放到请求头里。你在界面上不一定能看到这个过程，但配置项要写对。
常见问题包括：
- Key 填到了模型名称里
- base_url 和 api_key 写反了
- 配置文件缩进或字段名写错
- 客户端没有切换到自定义模型提供方
- 保存配置后没有重启客户端
如果工具支持“测试连接”，建议先点一次测试连接。测试失败时，不要只看弹窗提示，最好顺手看一下日志。日志里的错误通常比界面提示更具体。
4. 确认 model 名称是真实可用的
有些工具会把模型报错包装成认证失败，所以model也要一起看。
不要凭感觉填写模型名，建议在平台的模型列表里复制。比如同样是 GPT 系列，不同平台可能会使用不同的模型标识。
如果看到model not found，通常是这几种原因：
- 模型名写错
- 当前账号没有这个模型权限
- 当前分组或 Key 没有绑定对应模型
- 客户端默认模型和平台支持列表不一致
举个例子，有些客户端默认会填一个模型名，但你当前接口并不一定支持这个名称。这个时候 Key 是对的，地址也是对的，但因为模型名不匹配，最终还是请求失败。
建议做法是：打开平台后台的模型列表，复制一个当前可用的模型名，再粘贴到客户端里。不要手打，尤其是模型名里带横线、点号或版本号的时候，很容易多一个字符或少一个字符。
5. 看当前 Key 有没有权限或额度
如果地址、Key、模型名都没问题，再看账号侧状态：
- Key 是否启用
- 当前分组是否允许调用该模型
- 额度是否足够
- 是否触发频率限制
- 后台调用日志里有没有更具体的错误
如果后台有请求日志，优先看日志里的错误信息，比只看客户端提示更准确。
这里有一个判断方法：如果后台完全没有请求记录，说明请求可能还没真正打到平台，优先查base_url、网络和客户端配置。如果后台有请求记录，而且记录里显示认证失败、模型不存在或权限不足，就按日志提示继续处理。
另外，401、402、429 这几个状态码容易混在一起看：
401：通常和认证有关，比如 Key 错误、Key 失效、认证格式不对。402：通常和额度或账户状态有关。429：通常和请求频率、并发或限流有关。model not found：通常是模型名不匹配，或当前 Key 没有对应模型权限。
客户端有时候不会把这些错误展示得很细，所以后台日志很重要。
一个建议的排查顺序
如果你现在已经遇到 401，可以按下面这个顺序来：
- 先复制平台提供的接口地址，确认
base_url是否包含正确路径。 - 重新复制 API Key，检查前后有没有空格。
- 确认客户端使用的是 OpenAI 兼容 API 配置方式。
- 从平台模型列表里复制一个可用的
model。 - 保存配置后重启客户端，再发起一次测试。
- 如果仍然失败，打开后台调用日志，看有没有请求记录。
这个顺序的好处是，先排除最常见、最容易改的问题。很多 401 并不需要复杂处理，把地址和模型名对齐之后就能恢复。
配置时可以记住这张表
| 字段 | 作用 | 常见错误 |
|---|---|---|
base_url | 接口入口地址 | 填成官网、控制台或少了/v1 |
api_key | 身份认证 | 多空格、复制不完整、Key 被重置 |
model | 要调用的模型 | 模型名写错、没有权限、客户端默认值不适配 |
只要这三项对齐，大多数 OpenAI 兼容 API 工具都能先跑起来。
小结
遇到 401，不要只盯着 API Key。建议按这个顺序排查：
base_url -> API Key -> 认证格式 -> model -> 权限和额度如果你同时在多个工具里配置 OpenAI 兼容 API，可以把接口地址、模型名和 Key 管理方式统一起来。像云舒 API 这类统一入口，主要适合需要集中管理模型、Key 和调用记录的场景。
个人测试时，不用一开始就把配置弄得很复杂。先把最基础的三项配置对：base_url、api_key、model。这三项没有问题，再去看权限、额度和日志，排查效率会高很多。