API Key 填了还是 401？先检查这 5 个地方

配置 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接口入口地址填成官网、控制台或少了/v1api_key身份认证多空格、复制不完整、Key 被重置model要调用的模型模型名写错、没有权限、客户端默认值不适配只要这三项对齐大多数 OpenAI 兼容 API 工具都能先跑起来。小结遇到 401不要只盯着 API Key。建议按这个顺序排查base_url - API Key - 认证格式 - model - 权限和额度如果你同时在多个工具里配置 OpenAI 兼容 API可以把接口地址、模型名和 Key 管理方式统一起来。像云舒 API 这类统一入口主要适合需要集中管理模型、Key 和调用记录的场景。个人测试时不用一开始就把配置弄得很复杂。先把最基础的三项配置对base_url、api_key、model。这三项没有问题再去看权限、额度和日志排查效率会高很多。