你有没有遇到过这样的情况终端里敲下codex任务还没开始屏幕上先弹出一行刺眼的401 Unauthorized。你下意识觉得是 API Key 过期了于是去后台重新生成一个复制粘贴进去再跑还是 401。删掉配置重新登录依然 401。最后甚至怀疑是不是服务端在抽风结果打开网页版一看一切正常。这个场景我太熟了。Codex 的 401 问题看似简单但实际排查起来涉及 API Key 本身、shell 环境变量、配置文件格式、桌面端与命令行读取差异好几个层面。很多时候你折腾半天问题根源往往在一个意想不到的地方——比如系统密钥串里残留的旧 Key或者 shell 配置里一条早已不用的环境变量。这篇文章把我踩过的坑和完整的排查路径都整理出来每一条都配了可复现的验证方法希望能帮你少走几个小时的弯路。1. 401 到底在拒绝谁认证链路的两个入口要排查 401先得搞清楚 Codex 在拿什么证明你是谁。这一步很多人跳过结果一直在错误的方向上打转。1.1 API Key 模式一个字符串承载的信任API Key 模式是 Codex 最直接的认证方式。你在请求头里带上一个形如Authorization: Bearer sk-...的字符串服务端校验这个字符串是否有效、是否被授权访问目标模型。它的逻辑很简单只要 Key 对得上就放行对不上、过期了、权限不够一律 401。这里有个关键点容易忽略Key 是分环境的。官方后台生成的 Key 会绑定账户权限和计费方式有的 Key 只能访问特定模型有的 Key 只覆盖某个项目范围。你拿出一个 Key 去请求一个它无权访问的模型返回的同样是 401而不是提示模型不存在。换句话说401 并不等于Key 无效也可能等于Key 有效但没这个权限。另外还要留意 Key 的版本问题。Codex 的令牌体系经历过多次调整早期可能是长 token 全局有效后来逐渐细分成短期 token 刷新机制。如果你手里的 Key 是很早之前生成的而服务端已经启用了新策略旧 Key 在没有正确配置的情况下就会直接失效。我的建议是遇到 401 先重新生成一个新的 Key 再试这是成本最低的验证动作。1.2 账号登录模式Token 过期与刷新机制除了 API KeyCodex 还支持基于账号体系的 OAuth 登录。登录成功后会拿到一个 access token 存在本地这个 token 是有生命周期的。短则几个小时长则几天过期之后工具应该自动走刷新流程换新 token。一旦刷新失败——比如 refresh token 本身也过期了、网络中断、账户被登出——表现就是 401。这个模式下的 401 有点迷惑性因为你的账号明明没问题网页端也能打开只是终端里的 Codex 不知道它的 token 已经失效了。很多人这时候去重新生成 API Key结果治标不治本因为工具可能还在用旧的登录态根本没走 Key 认证。怎么区分当前走的是哪种模式看请求日志里的 Authorization 头。如果是Bearer sk-...那就是 API Key 模式如果是一串很长的、看不出规律的随机字符串那多半是 OAuth token。下一节我会讲怎么开日志到时候一眼就能分辨。2. 先盯住环境变量十个 401 里七个是 Key 被劫持进入正式排查前我强烈建议先检查环境变量。因为 Codex 读取配置有明确的优先级环境变量 配置文件 交互式登录态。这意味着哪怕你在配置文件里填了正确的 Key只要 shell 里存在一个名为OPENAI_API_KEY的旧值工具就会舍配置文件而取环境变量然后带着一个错误的 Key 去请求服务端。2.1 shell 配置里的旧 Key 残留这个坑我踩过不止一次。早前为了测试某个脚本我在~/.zshrc里 export 了一个临时 Key后来项目结束了Key 删了但 export 那句话一直留在配置里。某天再用 Codex 时无论我怎么改配置文件请求头里永远带着那行残留 Key服务端当然给我 401。检查方法很简单在终端执行echo $OPENAI_API_KEY如果输出有值再看它的来源grep -n OPENAI_API_KEY ~/.zshrc ~/.bashrc ~/.profile 2/dev/null如果确实存在旧值先unset OPENAI_API_KEY再跑一次 Codex。能通说明就是环境变量残留不能通再继续看下一步。2.2 一行一条命令验证 Key 真伪很多人一拿到 401 就下意识觉得Key 过期了实际上 Key 本身可能是好的只是请求头里的值被污染了。与其反复猜测不如直接把 Key 拿到手用 curl 模拟一次请求来验证它是否真的有效。curl -sS https://api.openai.com/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-xxx \ -d {model:gpt-4o-mini,messages:[{role:user,content:hi}],max_tokens:5}注意请求里的模型名要填自己账户有权限的模型否则可能因为权限不足被拒影响判断。把sk-xxx换成实际的 Key。如果返回一段 JSON 且包含choices说明 Key 本身没问题问题出在 Codex 读取到的值跟这个正确的 Key 对不上。如果返回401 invalid_api_key说明 Key 真的失效了直接回后台生成新的。如果返回其他 4xx 错误比如 404 或 403那可能是模型名不对、账户欠费或权限配置问题跟 401 的排查路径就不同了。这一步做完基本能把Key 本身坏了和Key 是好的但没用上区分开后面就好办了。3. 配置文件才是重灾区新旧版本交替造成的读取错位如果环境变量没问题Key 验证也通过但 Codex 还是 401那问题大概率出在配置文件上。Codex 这类工具迭代快配置文件格式跟着变稍不注意就会踩到新旧格式的坑。3.1 config.toml 与 auth.json 的职责分野新版 Codex 的配置集中在~/.codex/config.toml而早期的登录态和密钥信息存在~/.codex/auth.json。这两个文件职责不同config.toml模型选择、provider 配置、API Base URL、Key 文件路径等。auth.json登录后写入的 token 凭据。如果你的 config.toml 里自定义了 provider那么认证逻辑会被重定向。举个例子有人为了走代理或者自定义网关会在model_providers里加一段[model_providers.custom] name custom base_url https://api.example.com/v1 env_key CUSTOM_API_KEY这段配置本身没问题但它意味着 Codex 不会再读OPENAI_API_KEY而是去读CUSTOM_API_KEY。如果你没设置这个环境变量或者这个变量值不对请求就会被发往一个不接受你的 Key 的地址结果就是 401。还有一种更隐蔽的情况auth.json 里存的是旧 token而新版本工具升级后优先读 auth.json 而不是 config.toml 里配置的 Key。工具继续用旧 token 去请求旧 token 过期了自然 401。这时候哪怕你把 Key 改得再正确也没用因为请求头里带的根本不是你改的那个 Key。遇到这种情况处理方式是把过期的登录态清掉强制走 Key 模式。直接删除或重命名 auth.jsonmv ~/.codex/auth.json ~/.codex/auth.json.bak然后重新运行 Codex看它是否开始使用环境变量里的 Key。如果恢复再把旧的 auth.json 删掉即可。3.2 文件权限与隐藏字符看不见的破坏者这部分属于看着奇怪但确实会发生的坑。Codex 对配置文件有权限要求如果~/.codex目录或 auth.json 的权限过于开放工具可能拒绝读取并回退到某种未认证状态表现同样是 401 或类似警告。你可以检查一下权限ls -la ~/.codex/正常情况下目录权限应该是 700仅自己可读写执行文件权限应该是 600。如果看到 644 或 755 这类偏开放的值修正过来再试chmod 700 ~/.codex chmod 600 ~/.codex/auth.json ~/.codex/config.toml另一个隐藏问题是复制 Key 时带入的换行符或空格。很多人在网页上复制 Key 时会顺便把末尾的空格复制进去粘贴到环境变量或配置文件后肉眼看不出来但请求头里就带着这个多余的字符服务端校验自然失败。验证命令也很简单echo -n $OPENAI_API_KEY | xxd | tail -3正常输出末尾应该是十六进制字符如果看到0a换行或20空格说明值被污染了重新设置一次。4. 桌面端读不到配置GUI 进程与终端的环境隔离如果你用 Codex 的桌面端或 IDE 扩展很可能会遇到一个更让人抓狂的场景命令行跑得好好的桌面端一直 401。这通常不是桌面端的错而是 GUI 应用与终端进程天生不在一个环境里。4.1 为什么命令行能用、桌面版却持续 401终端环境是从 shell 里继承的你在~/.zshrc或~/.bashrc里 export 的变量终端启动 Codex 时能读到。但桌面应用不是由 shell 启动的——在 macOS 上它由 launchd 拉起在 Windows 上由桌面管理器拉起。这些进程根本不会去读你的.zshrc所以里面定义的OPENAI_API_KEY对桌面端完全不生效。这也解释了为什么命令行能通桌面端 401。你以为是桌面端读取配置的方式有问题实际上它连看都没看到你的环境变量。解决办法有两条路要么在桌面端的设置界面里显式填入 API Key它通常会存到系统密钥串里要么在 Codex 的配置文件里显式指定 Key 文件绕过环境变量。配置文件里可以加这样一段# 指定从某个文件读取 Key而不是环境变量 # api_key_file /path/to/your/key用文件方式的好处是无论 CLI 还是桌面端都走同一条读取路径避免两套环境两套配置的混乱。4.2 密钥串缓存改 Key 之后桌面端还在用旧值这是我在实际排查中花时间最多的地方。桌面端把 Key 存进系统密钥串macOS 的 Keychain、Windows 的凭据管理器后你再去后台改 Key、删 Key桌面端是不知情的。它每次启动优先从密钥串里找历史保存的值除非你显式在那里的界面上删除或更新否则它永远带着旧 Key 在请求。我见过最典型的情况是某开发者在网页后台把旧的 Key 删了生成新的在桌面端设置里填了新 Key但系统密钥串里还残留着更早的一条旧记录。桌面端读取顺序并不是设置里的优先于密钥串于是每次都命中那条最旧的失效 Key401 源源不断。排查方法以 macOS 为例打开钥匙串访问搜索 codex 或 openai看是否有旧记录有就删掉。Windows 则去凭据管理器里找类似条目清理。清理完重启桌面应用让它重新读取你在设置里填的新值问题通常就解决了。这个坑最坑的地方在于你看桌面端的设置界面它显示的是新 Key但实际请求时用的是密钥串里的旧 Key。界面显示和实际生效值不一致极容易让人误判方向。5. 一步步从日志揪出 401一份可以直接照抄的排查清单前面讲了很多可能的原因但实际操作中你不能每个都试一遍。最高效的做法是开启调试日志直接看请求头里到底带了什么。日志会告诉你真相而不是让你猜。5.1 开启调试日志先看请求头再谈其他Codex 支持调试日志输出一般可以在启动命令里加--verbose或设置环境变量LOG_LEVELDEBUG。具体的开关名不同版本略有差异但思路一致让工具打印出每一次 API 请求的详细信息。重点看两个位置Authorization 请求头确认前缀是Bearer确认后面跟的字符串是当前期望的 Key还是某段陌生 token。请求的 URL确认发往的地址是不是自己以为的官方地址有没有被配置文件重定向到某个自定义 base_url。如果你的请求头里带了一串既不是sk-开头、也不是你设置的 Key 的字符串那基本可以断定走的是登录 token而且这个 token 已经失效。清掉 auth.json强制回到 Key 模式。如果 URL 不是预期地址回看 config.toml 里的model_providers段确认base_url和env_key是否配对正确。5.2 排查顺序表与验证操作下面这张表是我每次处理 401 都会走的顺序按由快到慢、由简单到复杂的顺序排列。建议你严格按这个顺序来改一步、验证一步不要一次改多个变量——否则出了问题你根本不知道是哪个改动起效的。排查项快速验证操作修复方式Key 本身是否有权curl 模拟一次真实请求无效则后台重新生成shell 环境变量残留echo $OPENAI_API_KEY清理.zshrc等文件或unset配置文件优先级冲突检查 config.toml 的env_key指向统一指向正确的环境变量名登录态过期开日志看 Authorization 头重命名/删除 auth.json文件权限异常ls -la ~/.codex/chmod 700/600隐藏字符污染 Keyecho -n $KEY | xxd重新设置 Key桌面端密钥串残留系统密钥串搜索 codex/openai删除旧条目并重启应用API Base URL 被重定向开日志观察请求 URL修正 provider 配置每一步验证之间只做一个改动然后立刻重试。如果问题消失说明就是这个原因如果没消失撤销这个改动进入下一项。不要图省事一次改完那样出了问题还是要回头一步步排查反而更慢。最后说点我的个人体会。处理这类 401 问题心态上要意识到它往往不是一个坏 Key那么简单而是认证链路里某个环节读到了旧值。环境变量、配置文件、系统密钥串这三处各自都可能保存一份凭据哪一份是最新最正确的哪一份会被优先读取需要你花几分钟确认清楚。尤其是桌面端界面显示正确不代表实际请求正确密钥串缓存这个坑值得所有用 GUI 版 Codex 的人记住。如果你把上面这张表完整走一遍仍然没有解决那就要考虑是不是网络层面的问题——比如本地代理把请求做了改写、HTTP 代理返回了 401 页面导致 Codex 误读。这种情况可以临时直连验证一次或者把代理相关环境变量逐个去掉试试。多试几次定位到真正作祟的那一环问题基本都会迎刃而解。