1. 先搞清楚 401 到底卡在哪一环Codex 报401 unauthorized这件事我前前后后帮人排查过不下几十次说实话它本身一点都不复杂复杂的是大家一看到 401 就慌然后开始乱改配置把本来能跑的环境改得更乱。401 的本质只有一个服务端收到了你的请求但认为你没通过身份认证。注意是“认证”不是“授权”这两者经常被混为一谈。认证是“你是谁”授权是“你能干什么”。401 属于前者403 才属于后者。所以当你看到401 unauthorized第一反应应该是去查凭证而不是去查权限或者模型名。Codex 这个工具链比较特殊它同时存在两种认证路径一种是走官方账号体系的登录态也就是codex login那一套另一种是走 API Key 直连OPENAI_API_KEY或者自定义base_url那一套。这两条路径的凭证来源、存储位置、优先级都不一样所以 401 的成因也分成两大阵营。热词里出现的codex auth token is unavailable、missing bearer or basic authentication、invalid_api_key、api_key_required、incorrect api key provided其实分别对应了不同环节的失败不能一概而论。我先把最常见的几类 401 报错做个归类你对照自己的报错信息先定位报错原文片段含义大概率原因missing bearer or basic authentication请求头里压根没带认证信息环境变量没生效、配置文件没读到invalid_api_key/incorrect api key provided带了 key但 key 无效key 拼错、过期、被撤销、复制带了空格api_key_required服务端要求 key但你没给用了第三方 base_url 但没配 keycodex auth token is unavailable本地登录态失效或不存在登录过期、凭证文件损坏insufficient permissions认证过了但权限不够账号套餐或项目权限问题这张表建议你先存下来后面排查会反复用到。很多人一上来就问“Codex 401 怎么办”但连自己报的是哪一条都没看清这就好比去医院只说“我不舒服”医生没法下手。先读报错再动手这是排查任何认证问题的第一原则。另外要提醒一句热词里混进来的zlmedia describe:401 unauthorized和 Codex 其实没关系那是另一个流媒体服务的报错别被带偏了。同理429 too many requests是限流跟 401 是两码事虽然有时候会连着出现但处理思路完全不同。2. 认证链路拆解Codex 到底怎么认你的身份2.1 两条认证路径的优先级关系要修 401你得先知道 Codex 在发起请求时到底是从哪里拿凭证的。根据我实际抓包和翻配置的经验Codex CLI 的凭证读取大致遵循这样一个优先级顺序命令行显式传入的参数比如--api-key当前 shell 会话里的环境变量OPENAI_API_KEY、CODEX_API_KEY等项目目录下的配置文件.codex/config之类用户主目录下的全局配置文件~/.codex/下的凭证文件通过codex login写入的登录态 token这个顺序很关键。我遇到过太多这样的情况用户明明在终端里export OPENAI_API_KEYsk-xxx了结果还是 401最后发现是项目目录下有个旧的配置文件把环境变量覆盖了。因为配置文件的优先级在某些版本里是高于环境变量的具体取决于你用的版本和启动方式。所以排查时一定要从高优先级往低优先级逐个确认而不是只盯着一个地方看。提示不同版本的 Codex 在优先级实现上可能有细微差异如果你发现行为和上面描述不符先用codex --version确认版本再去翻对应版本的文档或源码。不要拿 A 版本的结论去套 B 版本。2.2 登录态与 API Key 不能混用这是另一个高频坑。codex login走的是账号登录流程它会拿到一个短期有效的 token存在本地。而OPENAI_API_KEY走的是 API Key 直连。这两套东西在同一个请求里只能用一个。如果你既登录了账号又设置了 API Key某些版本会优先用登录态某些版本会优先用 Key行为不一致就容易出现“我明明配了 key 却报 token unavailable”这种诡异现象。我的建议很明确要么纯用登录态要么纯用 API Key别混。如果你要接第三方兼容端点比如热词里提到的set codex_base_urlhttps://api.deepseek.com/v1这种那就必须走 API Key 路径并且要把登录态清干净否则登录态的 token 会被发到第三方端点对方当然不认直接 401。清理登录态的方法通常是删掉本地的凭证缓存目录具体路径因系统而异# 类 Unix 系统常见位置先确认再删 ls -la ~/.codex/ # 确认里面有 auth 相关文件后备份再清理 mv ~/.codex/auth.json ~/.codex/auth.json.bakWindows 下一般在%USERPROFILE%\.codex\目录里。删之前一定先备份别问我怎么知道的删错了重新登录有时候还会遇到手机号验证的麻烦。2.3 base_url 改错是 401 的重灾区热词里set codex_base_urlhttps://api.deepseek.com/v1这条特别典型。很多人想用第三方模型服务就把 base_url 改成了对方的地址但忘了同步改 key或者 key 的格式对方根本不认。第三方端点返回的 401 信息往往和官方不一样比如{code:invalid_api_key,message:invalid api key}这种一看就是对方服务端吐出来的。这里有个判断技巧看报错的 JSON 结构。官方 OpenAI 的报错结构是固定的{error: {message: ..., type: ..., code: ...}}而第三方兼容端点经常简化成{code: ..., message: ...}或者{detail: ...}。热词里那条{detail:the gpt-5.6-sol model is not supported...}就是典型的第三方或代理层返回的格式。看到detail字段基本可以确定你不是在跟官方端点说话。所以当你改了 base_url 之后报 401排查顺序是先确认 key 是不是这个端点签发的再确认 key 有没有多余空格最后确认这个端点是不是要求额外的 header有些兼容层要求特定的Authorization格式或者额外的项目 ID header。3. 一步修复从报错到跑通的标准流程3.1 第一步永远是确认凭证本身有效在动任何配置之前先用最原始的方式验证你的 key 到底能不能用。这一步能帮你排除掉一半的问题。用 curl 直接打端点绕开 Codex 的所有封装# 官方端点验证 curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY # 第三方兼容端点验证把地址换成你的 base_url curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY如果这一步就返回 401那问题 100% 在 key 本身或者端点地址上跟 Codex 没关系你改 Codex 配置改到天亮也没用。如果这一步通了但 Codex 还是 401那问题就在 Codex 的凭证读取环节继续往下查。我见过最离谱的一个案例用户的 key 是从网页上复制的末尾带了一个看不见的换行符curl 里因为 shell 处理没暴露但写进配置文件后就变成了sk-xxx\n服务端解析失败直接 401。所以复制 key 之后一定要检查首尾有没有空白字符用echo -n $OPENAI_API_KEY | wc -c数一下长度跟预期对不上就是有问题。3.2 环境变量的作用域陷阱export OPENAI_API_KEYsk-xxx这条命令只在当前 shell 会话里有效。你在这个终端里跑 Codex 没问题但如果你新开了一个终端窗口用 IDE 的集成终端跑用 systemd、launchd 之类的服务方式跑在 VS Code 里通过插件跑那这个环境变量根本不存在Codex 自然拿不到 key报missing bearer or basic authentication或者api_key_required。解决办法是把环境变量写进 shell 的启动文件里让它对每个新会话都生效# bash 用户 echo export OPENAI_API_KEYsk-xxx ~/.bashrc source ~/.bashrc # zsh 用户 echo export OPENAI_API_KEYsk-xxx ~/.zshrc source ~/.zshrcWindows 用户则要通过系统环境变量设置界面或者用setx命令setx OPENAI_API_KEY sk-xxx注意setx设置后需要重开终端才生效当前窗口读不到。这个细节坑过无数人设置完发现没用其实是没重开窗口。注意把 key 写进.bashrc这类文件时如果这个文件会被同步到云端或者提交到 git你的 key 就泄露了。更稳妥的做法是用单独的、被 gitignore 的文件来存然后在启动文件里 source 它。3.3 配置文件格式错误导致的静默失败Codex 的配置文件如果是 JSON 或 TOML 格式一个多余的逗号、一个引号不匹配就会导致整个文件解析失败。而解析失败的表现往往不是明确的“配置文件错误”而是静默地忽略这个文件然后 Codex 拿不到任何凭证报 401。排查方法是用工具验证配置文件语法# JSON 文件 python -m json.tool ~/.codex/config.json # TOML 文件 python -c import tomllib; tomllib.load(open(config.toml,rb))如果输出报错那就是格式问题。修好格式再试。我个人的习惯是配置文件改完立刻验证一遍语法别等到跑起来报错了才回头查。3.4 完整的一步修复脚本把上面这些串起来我给你一个可以直接抄的排查脚本按顺序执行哪一步断了就停在哪一步修#!/bin/bash echo 1. 检查环境变量 if [ -z $OPENAI_API_KEY ]; then echo OPENAI_API_KEY 未设置 else echo key 长度: $(echo -n $OPENAI_API_KEY | wc -c) echo key 前缀: ${OPENAI_API_KEY:0:7} fi echo 2. 检查 base_url echo base_url: ${OPENAI_BASE_URL:-未设置使用默认} echo 3. 检查配置文件 ls -la ~/.codex/ 2/dev/null || echo 无 .codex 目录 echo 4. 直连端点验证 BASE${OPENAI_BASE_URL:-https://api.openai.com/v1} curl -s -o /dev/null -w %{http_code}\n \ $BASE/models \ -H Authorization: Bearer $OPENAI_API_KEY最后那个 HTTP 状态码200 就是通的401 就是 key 或端点问题404 是端点地址写错了。这个脚本我放在自己的 dotfiles 里每次换机器或者怀疑配置有问题就跑一遍比瞎猜快得多。4. 高频 401 场景与对应解法速查4.1 场景一全新安装后第一次就 401这种情况八成是压根没配凭证。Codex 装完不会自动帮你登录你得手动执行codex login或者设置 API Key。热词里codex安装教程、codex安装 windows桌面版这些搜索量高说明很多新手卡在安装后的第一步。解法先跑codex login按提示完成账号登录。如果登录流程走不通比如卡在手机号验证那就改用 API Key 方式设置好OPENAI_API_KEY再跑。4.2 场景二昨天还能用今天突然 401这种“突然失效”的情况最常见的原因是登录态过期。账号登录拿到的 token 是有有效期的过期后需要重新登录。另一个可能是 key 被撤销或额度耗尽。解法先codex login重新登录试试。如果用的是 API Key去后台确认 key 状态和余额。热词里codex exceeded retry limit, last status: 429说明有人遇到了限流限流和 401 有时会交替出现别混淆。4.3 场景三接了第三方端点后 401热词里codex接入deepseek、deepseek接入codex这类需求很多。接了第三方端点后 401核心就三件事base_url 对不对、key 是不是对方的、请求格式对方认不认。解法用 3.1 节的 curl 方法直接验证第三方端点。如果 curl 通了 Codex 不通检查 Codex 是不是还在用登录态登录态 token 发到第三方当然 401。4.4 场景四VS Code 插件里 401 但终端正常这是环境隔离问题。VS Code 插件运行在自己的进程环境里不一定继承你终端的环境变量。热词里vscode codex、vscode接入codex搜索量高这个坑很普遍。解法在 VS Code 的设置里显式配置 API Key或者确保 VS Code 是从已经设置好环境变量的终端启动的macOS 下从终端code .启动 VS Code 就能继承环境变量。场景首要排查点快速验证全新安装 401是否配了凭证codex login或查环境变量突然 401登录态是否过期重新登录第三方端点 401base_url 与 key 是否匹配curl 直连验证IDE 内 401环境变量是否继承终端启动 IDE配置文件 401文件语法是否正确语法校验工具5. 几个容易被忽略的细节和我的实操心得5.1 代理层和中间件的干扰热词里cc switch local proxy failed while handling codex endpoint /responses这条很值得说。有些人会在本地跑一个代理层来转发请求这个代理层如果配置不当会把Authorizationheader 丢掉或者改错导致后端收到请求时没有认证信息返回missing bearer or basic authentication。排查这种问题关键是看请求到底经过了哪些环节。你可以在代理层加日志打印出转发前后的 header对比一下Authorization还在不在。我遇到过代理层把 header 名大小写改了导致失败的也遇到过代理层自作主张加了额外 header 导致冲突的。代理这东西能不用就不用非要用就确保它透明转发。5.2 key 的格式校验别偷懒不同服务的 key 格式不一样。官方的 key 一般是sk-开头第三方可能用别的前缀。热词里incorrect api key provided: asd3967281.这种一看就是填了个明显不是 key 的字符串。还有sk-j6wci****这种带掩码的说明是从某个界面复制了脱敏后的 key那当然不能用。我的习惯是拿到 key 先做三个检查前缀对不对、长度对不对、有没有空白字符。这三步能挡掉大部分低级错误。5.3 别忽视版本差异Codex 更新比较频繁不同版本在认证逻辑上可能有变化。热词里codex cli、codex插件、codex skill这些说明生态在快速演进。遇到 401 时先确认你的版本然后去对应版本的 issue 区搜一下很可能别人已经踩过同样的坑。我个人的做法是固定一个稳定版本用不追最新。新版本出来先观望一两周看看有没有认证相关的 bug 反馈确认稳定了再升。这个习惯帮我省了很多排查时间。5.4 日志是你的朋友Codex 一般会输出请求日志把日志级别调到 debug能看到它实际用了哪个凭证、请求发到了哪个地址。这比猜快一百倍。很多人排查 401 全靠猜改一个配置试一次效率极低。打开 debug 日志一眼就能看出问题在哪。# 大多数 CLI 支持通过环境变量调日志级别 export CODEX_LOG_LEVELdebug codex 你的命令看日志时重点关注三样东西请求的 URL、Authorization header 的值会被部分掩码、以及服务端返回的完整错误体。这三样凑齐401 基本无处遁形。5.5 一个反直觉的经验最后分享一个反直觉的点有时候 401 不是你的问题是服务端的问题。服务端在维护、在灰度、在抽风都可能返回 401。这种情况下你怎么改配置都没用。判断方法是换个时间段再试或者用完全独立的另一套凭证试。如果两套凭证都 401那大概率是服务端的事等一会儿就好别把自己折腾得怀疑人生。我印象很深的一次折腾了两个小时配置最后发现是对方服务端在发版半小时后自己就好了。从那以后我养成了一个习惯遇到 401 先花两分钟确认凭证确认没问题就等十分钟再试一次还不行再深入排查。这个习惯帮我避免了很多无效劳动。
