1. 为什么 2026 年还有人在折腾 Codex 的 API Key 登录先说个真实场景。上周有个做后端的朋友找我说他的 Codex 突然罢工了终端里刷出一行红字unexpected status 401 unauthorized: missing bearer or basic authentication in header。他第一反应是是不是账号被封了第二反应是是不是要重新买号。我让他把~/.codex/config.toml和~/.codex/auth.json两个文件发过来扫了一眼就找到问题了——他把 API Key 写进了config.toml的model_provider段里而 Codex 从某个版本开始只认auth.json里的凭证config.toml里那行直接被当成unrecognized configuration setting忽略了。这就是 Codex 这类 CLI 工具最坑的地方配置入口有两个职责边界却经常变。官方文档更新慢社区教程又互相抄导致 2026 年了还有一堆人卡在 401 上。这篇东西就是把我自己踩过的坑、帮别人排查过的案例整理成一份能直接抄作业的流程。核心围绕四件事API Key 怎么登录、config.toml和auth.json各自管什么、401 报错怎么按图索骥地查、以及接入第三方模型比如 DeepSeek、OpenRouter时那些反直觉的细节。不管你是刚下载 Codex 安装包的新手还是已经用了一阵子但被配置搞晕的老用户都能从里面找到对应自己问题的段落。我尽量不写那种第一步打开官网、第二步点击下载的废话教程重点放在为什么这么配和报错了到底看哪里。因为 Codex 的报错信息虽然啰嗦但每一句其实都指向了具体文件的具体字段只是大部分人没耐心读完。2. Codex 的配置体系拆解config.toml 与 auth.json 的分工2.1 两个文件两套逻辑别混着写Codex 的配置分两层这是理解所有 401 问题的前提。auth.json管的是身份凭证。它里面存的是 API Key、OAuth token 这类你是谁的信息。位置通常在~/.codex/auth.jsonWindows 下是C:\Users\你的用户名\.codex\auth.json。这个文件是敏感文件权限要收紧别随手丢进 Git 仓库。config.toml管的是行为配置。模型选哪个、provider 指向谁、超时多少、MCP server 怎么挂、日志级别多高全在这里。它不该出现任何明文密钥——这是很多人第一个踩的坑。我见过最常见的错误配置长这样# 错误示范把 key 写进 config.toml model gpt-5-codex model_provider openai api_key sk-xxxxxxxx # 这行会被忽略甚至触发警告Codex 启动时会打印一句codex is ignoring 1 unrecognized configuration setting. check for typos or deprecated settings后面跟着config.toml的路径和具体字段名。很多人看到这行直接略过然后继续在 401 里打转。这行警告就是答案本身它明确告诉你哪个字段没被识别。2.2 为什么官方要把凭证和配置分开从工程角度讲这是为了让配置文件可以安全地分享和版本管理。你可以把config.toml提交到团队仓库让所有人用同一套模型参数、同一套 MCP 配置但每个人的auth.json各自独立。如果密钥混在config.toml里一旦提交就是事故。另一个原因是凭证的刷新机制。OAuth 登录拿到的 token 会过期需要程序自动刷新并回写auth.json。如果 token 存在config.toml里程序回写就会破坏你手写的注释和格式。分开之后auth.json就是个纯数据文件程序想怎么改怎么改不影响你的配置。理解了这层分工很多报错就顺了。比如codex auth token is unavailable问题一定在auth.json或登录流程跟config.toml里的模型设置没关系。反过来model provider openai not found这种就是config.toml里 provider 名字写错了跟密钥无关。2.3 目录结构长什么样一个健康的~/.codex/目录大概是这样~/.codex/ ├── auth.json # 凭证权限 600 ├── config.toml # 行为配置 ├── history.jsonl # 会话历史可选 ├── log/ # 日志目录 └── sessions/ # 会话状态Windows 下路径是C:\Users\用户名\.codex\。注意那个点号开头的目录在资源管理器里默认是隐藏的很多人找不到就以为文件不存在。直接在地址栏敲%USERPROFILE%\.codex回车最快。提示如果你在 Windows 上看到报错路径里出现中文用户名比如C:\Users\丁子洋\.codex\config.toml一般不影响使用但如果遇到诡异的路径解析问题可以考虑把 Codex 的配置目录通过环境变量指到一个纯英文路径下。3. API Key 登录的完整实操流程3.1 拿到 Key 之后先别急着写文件不管你用的是官方渠道还是第三方中转拿到 API Key 的第一件事是验证这个 Key 本身是活的。很多人跳过这步直接把 Key 塞进配置然后被 401 折磨半天最后发现是 Key 复制时多了个空格或者少了一位。用 curl 直接打一次接口最稳妥curl https://api.openai.com/v1/models \ -H Authorization: Bearer sk-你的key返回一个模型列表 JSON 就说明 Key 有效。如果返回{code:invalid_api_key,message:invalid api key}那问题在 Key 本身跟 Codex 无关别往下折腾了。这一步能过滤掉大概三成的401 问题——它们根本不是 Codex 的配置问题是 Key 本身无效、过期、或者被限流了。3.2 写入 auth.json 的正确姿势确认 Key 有效后写auth.json。格式如下{ OPENAI_API_KEY: sk-你的真实key }注意几点字段名是OPENAI_API_KEY全大写下划线分隔。写成api_key或openaiApiKey都不认。值是纯字符串不要加Bearer前缀。前缀是请求头里才加的写进文件里会导致incorrect api key provided。JSON 不允许尾随逗号。key: value,后面如果直接跟}就是语法错误Codex 会报解析失败。如果你用的是 OAuth 登录codex login走浏览器授权那种auth.json会被程序自动写入里面可能是access_token、refresh_token、expires_at这类字段不需要你手动碰。手动改反而容易把刷新逻辑搞坏。3.3 用环境变量登录的替代方案不想写文件的话Codex 也认环境变量export OPENAI_API_KEYsk-你的keyWindows PowerShell 下$env:OPENAI_API_KEYsk-你的key这种方式适合临时测试或者 CI 环境。缺点是每次开新终端都要重设而且如果同时装了多个 AI CLI 工具环境变量会互相干扰。我个人的习惯是长期用的写auth.json临时切换的用环境变量。环境变量的优先级通常高于auth.json。也就是说如果你auth.json里写的是 A key环境变量里是 B key实际生效的是 B。这个特性可以用来做快速切换但也容易造成我明明改了文件怎么没生效的困惑。3.4 登录状态自检配好之后跑一条最简单的命令验证codex say hello如果返回正常文本说明凭证链路通了。如果报 401先看报错的具体措辞下一节会按措辞分类排查。4. 401 报错分类排查从报错原文定位问题401 不是一个错误是一类错误。Codex 会把上游返回的原始信息透传出来所以报错原文里的每个词都是线索。我把它分成几类对照着查基本能覆盖九成情况。4.1 missing bearer or basic authentication in header完整报错unexpected status 401 unauthorized: missing bearer or basic authentication in header这句话的意思是请求根本没带认证头。不是 Key 错了是压根没传。可能原因auth.json文件不存在或者路径不对比如放在了项目目录而不是用户目录。文件存在但字段名写错Codex 读不到于是当没认证处理。环境变量和文件都没配裸奔状态。排查顺序先确认~/.codex/auth.json存在再确认字段名是OPENAI_API_KEY最后确认没有语法错误。用cat ~/.codex/auth.json | python -m json.tool验证 JSON 合法性能解析就说明格式没问题。4.2 invalid_api_key / incorrect api key provided完整报错可能是unexpected status 401 unauthorized: {code:invalid_api_key,message:invalid api key}或者incorrect api key provided: sk-j6wci****。这类是Key 本身有问题。注意报错里会显示 Key 的前几位和后几位中间打码拿这个跟你的真实 Key 对一下能发现很多低级错误复制时首尾多了空格或换行。Key 被截断了比如只复制了一半。用的是已经失效的旧 Key。Key 属于另一个账号没有当前模型的权限。有个细节报错里显示的sk-j6wci****如果跟你以为的 Key 开头对不上说明 Codex 读到的根本不是你改的那个文件。这时候要检查是不是有多个auth.json或者环境变量覆盖了文件。4.3 api_key_required完整报错{code:api_key_required,message:api key is required in authorization header}这个通常出现在第三方中转或自建网关场景。上游服务要求认证头里必须有 Key但 Codex 发出去的请求没带。原因往往是config.toml里配了自定义 provider但没告诉 Codex 这个 provider 需要认证。解决方向检查config.toml里对应 provider 的配置确认env_key字段指向了正确的环境变量名或者确认auth.json里的 Key 能被这个 provider 识别。4.4 insufficient permissions完整报错unexpected status 401 unauthorized: you have insufficient permissions for this operationKey 是有效的但权限不够。常见于用的是免费额度账号访问了需要付费的模型。Key 被限制了 scope只能调部分接口。组织级别的权限策略限制了该 Key。这类问题改配置没用得去账号后台看权限设置。4.5 排查速查表报错关键词根因方向优先检查missing bearer没传认证头auth.json 是否存在、字段名invalid_api_keyKey 无效Key 是否复制完整、是否过期incorrect api keyKey 不匹配报错显示的 Key 片段是否对得上api_key_required上游要求认证provider 配置、env_key 指向insufficient permissions权限不足账号套餐、Key scopetoken is unavailable凭证缺失登录流程、auth.json 内容提示排查时永远先看报错原文不要凭经验猜。Codex 的报错信息虽然长但信息量很足逐字读一遍比盲目改配置快得多。5. config.toml 常见配置错误与修复5.1 provider 名字写错model provider openai not found报错原文请修复 config.toml:model provider openai not found这个报错的意思是你在config.toml里指定了一个 provider 名字但 Codex 的内置 provider 列表里没有这个名字你也没有自定义它。内置的 provider 名字是固定的比如openai、anthropic这类。如果你写的是openai-official、openai_api这种自造名字就会报这个错。修复方式有两种一是改回内置名字model_provider openai二是显式定义这个 provider[model_providers.my-provider] name my-provider base_url https://api.example.com/v1 env_key MY_API_KEY定义之后model_provider才能指向my-provider。5.2 被忽略的配置项unrecognized configuration setting报错原文codex is ignoring 1 unrecognized configuration setting. check for typos or deprecated settings. user (c:\users\丁子洋\.codex\config.toml): mcp_servers.node_repl.type is ignored.这行信息非常明确mcp_servers.node_repl.type这个字段被忽略了。可能原因字段名拼错了比如mcp_server少了个 s。这个字段在当前版本已经废弃改成了别的名字。字段层级放错了应该在外层却写进了内层。修复就是按报错里给出的完整路径去改。注意报错会给出文件绝对路径如果你改的文件跟这个路径不一致说明你改错文件了——这在多用户或配置目录被重定向的情况下很常见。5.3 模型名不存在config.toml里model xxx写了一个不存在的模型名请求发出去会被上游拒绝有时表现为 401有时是 404。确认模型名的办法是查官方模型列表或者用 curl 打/v1/models看返回里有没有。5.4 一个可用的最小配置模板model gpt-5-codex model_provider openai [model_providers.openai] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY这个模板只保留最必要的字段。新手建议从这个开始跑通了再逐步加 MCP、加超时、加日志。一次性堆一大堆配置出问题很难定位是哪个字段引起的。6. 接入第三方模型DeepSeek、OpenRouter 的配置要点6.1 为什么第三方接入更容易出 401第三方模型服务DeepSeek、OpenRouter 等的认证方式和官方不完全一样。有的用标准 Bearer有的要求额外的 header有的 Key 格式完全不同比如v2v-开头、sk-or-开头。Codex 默认按官方的方式发请求接第三方时如果 provider 配置没写对就会 401。6.2 接入 DeepSeek 的配置model deepseek-chat model_provider deepseek [model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY然后在auth.json或环境变量里提供DEEPSEEK_API_KEY。注意env_key的值是环境变量的名字不是 Key 本身。这是最容易搞混的地方——很多人把 Key 直接写在env_key后面结果 Codex 去找一个叫sk-xxxx的环境变量当然找不到。报错llm-deepseek: no api key for provider route deepseek-official就是这类问题的典型表现provider 路由找不到对应的 Key。6.3 接入 OpenRouter 的配置OpenRouter 的 Key 以sk-or-开头base_url 是https://openrouter.ai/api/v1。model anthropic/claude-sonnet-4 model_provider openrouter [model_providers.openrouter] name openrouter base_url https://openrouter.ai/api/v1 env_key OPENROUTER_API_KEYOpenRouter 的模型名是厂商/模型格式写错也会报错。另外 OpenRouter 对某些模型有额外的路由要求如果报 401 但 Key 确认有效可以查一下是不是模型名或路由策略的问题。6.4 第三方接入的通用检查清单base_url结尾要不要带/v1不同服务要求不同查文档确认。env_key填的是环境变量名不是 Key。Key 的格式前缀对不对sk-、sk-or-、v2v-等。模型名是否在该服务的支持列表里。是否需要额外的 header有些服务要求HTTP-Referer或X-Title。7. 实操心得与避坑清单7.1 改完配置一定要重启Codex 在启动时读取配置运行中改文件不会热加载。改完config.toml或auth.json后退出当前会话重新进。我见过有人改完文件在当前会话里反复试一直报同样的错以为改错了其实是没重启。7.2 备份再改auth.json和config.toml改之前先复制一份。尤其是auth.json如果里面是 OAuth token手改坏了可能导致要重新走一遍登录流程。备份命令cp ~/.codex/auth.json ~/.codex/auth.json.bak cp ~/.codex/config.toml ~/.codex/config.toml.bak7.3 权限收紧auth.json里是明文密钥Linux/macOS 下建议设成 600chmod 600 ~/.codex/auth.jsonWindows 下虽然权限模型不同但也别把这个文件放在共享目录或同步盘里。7.4 日志是你的朋友遇到搞不定的 401开日志看原始请求。config.toml里可以调日志级别日志目录在~/.codex/log/。原始请求里能看到实际发出去的 header 和 URL比猜快得多。7.5 常见问题速查现象可能原因解决改配置没生效没重启退出重进报错路径和改的文件不一致改错文件按报错路径改环境变量和文件冲突优先级问题统一用一处第三方 401env_key 填成 Key改成环境变量名JSON 解析失败尾随逗号/语法错用 json.tool 验证中文用户名路径报错路径解析重定向配置目录7.6 一个我踩过的坑有次帮人排查他坚称auth.json里 Key 是对的我让他把文件内容贴出来发现字段名写的是OPENAI_KEY少了个API。Codex 读不到就当没认证报missing bearer。这种错误肉眼很难发现因为看起来差不多。所以字段名一定要对着文档逐字核对别凭记忆写。另一个坑是 Windows 下用记事本编辑config.toml保存时带了 BOM 头导致 TOML 解析失败。换成 VS Code 或 Notepad 编辑保存为 UTF-8 无 BOM 就好了。8. 关于 cc switch 和本地代理报错的说明热词里出现了cc switch local proxy failed while handling codex endpoint /responses这类报错。这通常出现在使用本地代理或切换工具的场景下。核心问题是代理层没有正确转发认证头。Codex 发出的请求带着Authorization头如果中间经过一层本地代理代理在转发时把这个头丢了或者改坏了上游就会返回 401。排查方向确认代理是否透传Authorization头。确认代理的目标地址和 Codex 配置的base_url一致。确认代理本身不需要额外的认证。这类问题的本质还是认证链路断了只是断在中间层而不是 Codex 本身。排查思路和前面一样从报错原文定位是哪一层没传认证。9. 最后分享几个实用技巧关于 Key 的管理我现在的做法是按用途分 Key日常开发一个、测试一个、接第三方的一个。这样出问题时能快速定位是哪个环节也方便单独吊销。所有 Key 都存在密码管理器里auth.json里只放当前在用的那个。关于配置版本管理我会把config.toml里的非敏感部分抽出来放到一个 dotfiles 仓库auth.json永远不进仓库。换机器时 clone 下来再手动补auth.json五分钟搞定。关于报错排查养成一个习惯先把报错原文完整读一遍再动手。Codex 的报错信息里通常包含了文件路径、字段名、甚至修复建议比任何教程都精准。大部分人出错不是因为不会配是因为没读报错。如果这篇东西帮你解决了问题那最好如果还有没覆盖到的报错把原文贴出来按第 4 节的分类表对一下基本都能找到方向。配置这东西理解了文件分工和认证链路剩下的就是耐心。