1. 为什么 2026 年还有人在折腾 Codex 的 API Key 登录先说清楚一件事Codex 这个命令行工具从 2025 年下半年开始登录方式就彻底变了。以前你装完直接codex login走浏览器授权就完事现在官方把重心全压到了 API Key 和config.toml上尤其是接第三方模型比如 DeepSeek、OpenRouter的场景配置文件写错一个字段就是 401。我身边至少五个同事在群里问过“为什么我 key 明明是对的还报 unauthorized”最后查出来全是auth.json和config.toml打架。这篇东西就是把我自己从零装到跑通、再到帮别人排查 401 的完整过程捋一遍。核心关键词就几个Codex 安装、API Key 登录、config.toml、auth.json、401 报错。适合谁看如果你是刚拿到 Codex 安装包、准备在 Windows 或 macOS 上跑起来的新手或者你已经装好了但卡在unexpected status 401 unauthorized这个报错上那这篇就是给你写的。我不讲虚的直接按我实际操作的顺序来每一步都告诉你为什么这么做以及哪里最容易翻车。先给一个整体判断Codex 的配置体系现在是“两层结构”——auth.json管凭证config.toml管模型和 provider。90% 的 401 不是 key 错了而是这两层没对齐。你只要把这两个文件的关系理清楚后面基本不会再被卡住。2. 安装前的环境准备与版本选择2.1 确认你的系统环境和安装渠道Codex 目前主流的分发方式有三种npm 全局安装、官方安装包Windows 桌面版 / macOS dmg、以及从源码构建。我实测下来npm 方式最适合需要频繁切换 provider 的人因为升级和回滚都方便桌面版适合只想点开就用、不折腾配置的。Windows 用户注意如果你用的是 WSL那 Codex 要装在 WSL 里面不要装在 Windows 宿主侧否则路径里的C:\Users\丁子洋\.codex\config.toml这种反斜杠路径会让它读不到配置。我踩过这个坑报错就是codex is ignoring 1 unrecognized configuration setting其实是文件根本没被加载。macOS 用户相对省心但要注意 Node 版本。Codex CLI 对 Node 有最低版本要求低于这个版本装完能启动但会在登录阶段静默失败。建议先跑一遍node -v npm -v如果 Node 低于 18先升级。别问为什么我试过用 16 跑codex login直接卡住不报错排查了半小时才发现是版本问题。2.2 安装命令与验证是否装成功npm 方式一条命令npm install -g openai/codex装完先别急着登录先验证二进制是否可用codex --version能打印版本号说明装好了。如果提示command not found大概率是 npm 全局 bin 目录没进 PATH。Windows 上这个目录通常是%APPDATA%\npmmacOS 是/usr/local/bin或~/.npm-global/bin。这一步不解决后面所有配置都是白搭。提示安装过程中如果卡在idealTree阶段多半是网络源的问题换一个 npm 镜像源再试不要反复重装。2.3 目录结构先搞清楚 .codex 文件夹在哪Codex 所有配置都放在用户目录下的.codex文件夹里。这是后面所有操作的根系统配置目录路径WindowsC:\Users\用户名\.codex\macOS/Users/用户名/.codex/Linux/home/用户名/.codex/这个目录里最关键的两个文件是auth.json和config.toml。很多人报chatgpt 无法加载 config.toml 因此此对话串无法继续就是因为这个目录下文件缺失或者格式写坏了。装完之后如果目录不存在手动建一个别指望它自己生成。3. API Key 登录的完整流程拆解3.1 先拿到一个能用的 API Key登录的前提是你手里有一个有效的 key。来源无非几种官方平台申请的、第三方聚合平台比如 OpenRouter发的、或者自建服务端生成的。不管哪种拿到之后先做一件事确认这个 key 对应的 endpoint 和模型名。因为 Codex 的 401 里有一类特别典型unexpected status 401 unauthorized: {code:invalid_api_key,message:invalid api key}这种是 key 本身无效或过期。还有一类是unexpected status 401 unauthorized: missing bearer or basic authentication这种是请求头里压根没带上 key属于配置没生效不是 key 的问题。分清楚这两类排查方向完全不同。3.2 auth.json 的正确写法auth.json是存凭证的地方。最简结构长这样{ OPENAI_API_KEY: sk-你的key }注意几点第一key 必须带引号JSON 不接受裸字符串第二字段名是OPENAI_API_KEY不是api_key也不是apikey写错了 Codex 读不到就会报api key is required in authorization header第三这个文件不要有 BOM 头Windows 上用记事本保存容易带 BOM导致解析失败。我建议直接用 VS Code 或nano编辑。如果你用的是第三方 provider比如 DeepSeek那auth.json里可能还要加对应的环境变量名具体看 provider 文档。但核心逻辑不变auth.json 负责“我是谁”config.toml 负责“我要连哪里”。3.3 config.toml 的模型与 provider 配置这是最容易出错的地方。一个能跑通的最小config.tomlmodel gpt-4o [model_providers.openai] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY逐行解释model指定默认模型[model_providers.openai]定义一个 provider名字叫 openaibase_url是接口地址env_key告诉 Codex 去哪个环境变量或 auth.json 字段取 key。这里有个高频报错请修复 config.toml:model provider openai not found原因是你model里写的 provider 前缀和下面定义的 provider 名对不上。比如你写model openai/gpt-4o那下面就必须有一个[model_providers.openai]。名字必须严格一致大小写敏感。还有一个坑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.这是说某个字段被忽略了通常是字段名拼错或者版本不支持。这种警告不一定致命但如果被忽略的正好是 provider 相关字段那 401 就来了。看到unrecognized configuration setting一定要去核对字段名。3.4 登录命令与验证配置写好后跑codex login如果它提示你输入 key说明auth.json没被读到检查路径和格式。如果直接进入交互界面说明登录成功。再跑一个简单请求验证codex hello能返回内容就通了。如果返回 401往下看排查部分。4. 401 报错的分类排查与解决4.1 按报错信息定位问题源头401 不是一个错误是一类错误。我把它整理成一张速查表报错信息关键词大概率原因解决方向invalid_api_keykey 错误或过期重新生成 key更新 auth.jsonapi_key_required请求没带 key检查 env_key 字段和 auth.json 字段名missing bearer认证头缺失检查 base_url 和 provider 配置insufficient permissionskey 权限不足换有权限的 key 或调整账号权限incorrect api key provided: sk-j6wci****key 被截断或含空格检查复制时是否带多余字符authentication fails, your api key: ****key 格式对但服务端拒绝确认 endpoint 和 key 是否匹配这张表我建议存下来下次报错直接对号入座能省掉大量瞎试的时间。4.2 代理与本地转发导致的 401有一类报错特别迷惑cc switch local proxy failed while handling codex endpoint /responses. unexpected status 401 unauthorized这是本地代理层转发时出的问题。如果你用了 cc switch 这类工具做 provider 切换它会在本地起一个代理Codex 请求先到代理再到真实 endpoint。这时候 401 可能来自代理本身而不是上游。排查方法先绕过代理直接用base_url指向真实地址测一次。如果直连能通那就是代理配置里的 key 没传对。注意本地代理场景下auth.json里的 key 和代理配置里的 key 可能不是同一个别搞混。4.3 config.toml 格式错误的连锁反应TOML 对格式很敏感。少一个引号、多一个逗号整个文件解析失败Codex 会退回到默认配置然后你就看到 401。常见格式错误字符串没加引号model gpt-4o错model gpt-4o对表头写错[model_providers.openai]不能写成[model_providers openai]重复定义同一个 provider 定义两次后者覆盖前者容易导致 key 丢失我建议每次改完config.toml用一个在线 TOML 校验器过一遍或者本地装个taplo检查。别嫌麻烦这一步能挡掉一半的 401。4.4 环境变量与 auth.json 的优先级冲突Codex 取 key 的顺序通常是环境变量 auth.json。如果你系统里设了一个旧的OPENAI_API_KEY环境变量而 auth.json 里是新 key那 Codex 会用旧的那个然后报 401。这种情况特别隐蔽因为你看 auth.json 怎么看都是对的。解决办法先查环境变量。echo $OPENAI_API_KEYWindows 上用echo %OPENAI_API_KEY%。如果有值且和 auth.json 不一致要么清掉环境变量要么把环境变量更新成新 key。我一般建议统一用 auth.json 管理环境变量留空避免这种冲突。5. 多 Provider 切换与进阶配置5.1 同时配置多个 provider 的写法实际使用中经常需要在官方和第三方之间切换。config.toml支持定义多个 providermodel deepseek-chat [model_providers.openai] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY [model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY切换时只改model那一行或者用命令行参数覆盖。这样比每次重写整个文件安全得多。5.2 接入 DeepSeek 等第三方模型的注意事项接第三方最常见的报错是llm-deepseek: no api key for provider route deepseek-official这说明 provider 名和实际路由对不上。第三方平台的 provider 命名有自己的规则不能想当然。比如你定义的是deepseek但工具内部路由找的是deepseek-official那就找不到 key。解决办法是查该平台的接入文档用它规定的 provider 名。另外第三方模型的base_url一定要带/v1后缀大多数情况漏了会 404 或者 401。这个细节文档里经常不写清楚但实测很关键。5.3 用 cc switch 管理多套配置如果你经常在多个 key 之间切换手动改文件太累。cc switch 这类工具的思路是维护多套配置一键切换。但用它的时候要注意切换后要确认auth.json和config.toml是配套的别出现 config 指向 A provider 而 auth 里只有 B 的 key。我见过有人切换后忘了同步 auth.json结果一直 401查了半天。6. 实操心得与常见问题速查6.1 我踩过的三个典型坑第一个坑Windows 记事本保存config.toml带了 BOMCodex 解析失败但不报明确错误只报 401。换成 VS Code 保存为 UTF-8 无 BOM 就好了。第二个坑key 复制时末尾带了一个空格肉眼看不出来报incorrect api key provided。用cat -A auth.json能看到行尾的$前面有空格。第三个坑同时装了桌面版和 CLI 版两个版本读的配置目录不一样改了 CLI 的配置但实际跑的是桌面版。确认你启动的是哪个二进制。6.2 排查 401 的标准动作清单遇到 401按这个顺序走基本能定位确认codex --version能跑排除安装问题确认.codex目录路径正确文件存在用 TOML 校验器检查config.toml格式检查auth.json字段名和 key 格式检查环境变量是否覆盖了 auth.json直连测试排除代理干扰换一个已知可用的 key 交叉验证这七步走完还搞不定的基本就是服务端侧的问题了不是本地配置能解决的。6.3 关于 key 安全的一点提醒auth.json里存的是明文 key别把这个文件传到任何公开仓库。.codex目录建议加进.gitignore。另外网上那些“openai api key 分享”的内容一律不要用来源不明的 key 随时可能失效而且有安全风险。自己申请自己的这是底线。配置这东西第一次配通之后一定要把能用的config.toml和auth.json备份一份。下次换机器或者重装直接复制过去改 key 就行能省掉大量重复排查的时间。我现在就是一套配置走天下换环境五分钟搞定。