2026 年 9 月我前后帮三个朋友装 Codex发现一个很反直觉的事安装这一步几乎没人卡住真正让人抓狂的全是安装之后的登录和配置阶段。报错来来去去就那么几句——“unexpected status 401 unauthorized: incorrect api key provided: sk-svcac***”“auth token is unavailable”“authentication fails, your api key: ****”还有套了本地转发工具之后冒出来的“failed while handling codex endpoint /responses”。这篇文章就把这些报错一次讲透从装环境、拿 API Key、写 config.toml到 401 的逐层排查再到把 Codex 接到 DeepSeek 这类兼容接口上的实战配置。适合刚下好 Codex 但还没跑通第一次对话的新手也适合已经被 401 折腾了半小时以上、正准备砸键盘的人。1. 装 Codex 前先把 Node.js、Git 和接口可达性这三件事办妥1.1 Node.js 版本旧版本能跑新版本更稳Codex CLI 本质上是一个 Node.js 应用官方仓库对 Node 版本有要求。2026 年 9 月这个时间点我的建议是直接用 Node.js 20 LTS 或 22 LTS别再用 18 了——虽然 18 也能跑但新版本 Codex 的依赖树越来越新某些依赖在新版 Node 下才会有更好的表现。你可能看到热词里有“node版本24.19如何配置commitlint”这类搜索说明不少人已经装到了 Node 24。24 当然可以跑 Codex但如果你在 npm 全局安装时看到 engine 相关的警告不要慌那通常是依赖声明和实际 Node 版本不完全匹配造成的提示不代表装不上。真正需要担心的是另一种情况公司电脑或者服务器上同时装了多个 Node 版本node -v看到的和npm实际使用的不是同一个这时候全局安装 Codex 会出现“命令找不到”或者“版本对不上”的诡异问题。稳妥的做法是用 nvm 管理版本nvm install 22 nvm use 22 node -v npm -v确认版本之后再执行全局安装npm install -g openai/codex装完之后用codex --version验证一下。如果这个命令返回了版本号安装环节基本就结束了。另外Git 也不是可选项——Codex 在会话中会用到 Git 做版本控制相关操作Windows 上如果没装 Git某些功能会静默失效而不是直接报错所以顺手git --version检查一下。1.2 安装方式npm 全局安装和桌面版二选一Codex 的形态不止 CLI 一种。Windows 上还有桌面版安装包下载安装包之后双击安装界面里可以直接登录对不想碰命令行的用户友好很多。但我个人建议如果你打算长期用、想配合 VS Code 写代码还是 CLI 版顺手。原因很简单CLI 版的配置体系config.toml和桌面版是同一套但 CLI 更容易调试出问题的时候你能看到完整的错误输出而桌面版很多时候只给你一个“发生了错误”的弹窗。CLI 装好之后先跑一次codex它会自动帮你建好~/.codex目录。这个目录后续非常重要你的登录态和配置文件都在里面。另外注意CLI 的登录态和桌面版的登录态并不是自动同步的你在桌面版登录了回到终端里跑codex该报 401 还是会报 401。这也是我见过很多人的第一个坑。1.3 接口可达性先测通再谈配置这一节我不展开讨论任何网络加速手段只强调一个开发常识你的机器必须能直接访问到你配置的 base_url。很多看起来像鉴权失败的报错根源其实是请求根本没到达服务端。最快的探测方式是用 curlcurl -I https://api.openai.com/v1/models如果能正常返回 HTTP 状态码比如 200 或 401说明连接层面是通的如果卡住不动、超时、或者返回一堆看不懂的连接错误就要先解决连通性问题再去折腾 API Key否则方向就搞反了。这里也顺便回应一个高频问题“Codex 国内能用吗”答案是能但不必在“如何访问官方服务”这条路上死磕。更省事的做法是直接把 Codex 的 base_url 指到你网络环境下能正常访问的兼容服务商接口上比如 DeepSeek 提供的 OpenAI 兼容 REST API。这样你既不损失 Codex 的使用体验又绕开了网络层面的不确定性。后面第 5 章我会给完整配置。2. API Key 的获取、管理与 Codex 登录方式2.1 获取 API Key 时容易被忽略的权限细节API Key 是你和模型服务端之间的唯一凭证。以 OpenAI 官方平台为例登录后在 API Keys 页面生成新 Key格式通常是sk-开头也有一类是sk-svcac开头的服务账号 Key。注意这个sk-svcac前缀。热词里出现的高频报错“incorrect api key provided: sk-svcac***”很多就是服务账号 Key 的问题。服务账号 Key 一般绑定特定的项目或者角色权限范围跟你个人账号生成的普通 Key 不完全一样。当 Codex 发出的请求所用的认证方式、请求头、模型访问路径和这个 Key 的权限不匹配时服务端就会直接判定为 Key 不正确。我的建议是普通个人使用就生成一个标准 API Key不要非用服务账号 Key。生成后立刻复制保存因为 OpenAI 只显示一次。另外有些人的 Key 本身没抄错但复制的时候多了一个空格或者换行肉眼看不出来用的时候就会被判定为 incorrect api key。我处理这类问题时的第一个动作永远是在终端里检查环境变量或配置文件中的 Key 首尾有没有多余字符。如果你走的是 OpenRouter 这条路它生成的 Key 是sk-or-开头用法逻辑类似但 base_url 要对应改成 OpenRouter 的接口地址。后面配置章节会直接给出字段写法。2.2 两种登录方式codex login 与 --api-keyCodex 的登录方式有两种很多人分不清什么时候用哪种。第一种是codex login。它会拉起浏览器走 OpenAI 账号的 OAuth 授权流程。这种方式适合你直接使用 OpenAI 官方服务。登录过程中 Codex 会在本地开一个回调端口接收授权结果。如果这个端口被占用或者浏览器没正常打开登录流程就会卡住。第二种是codex login --api-key。它会直接要求你粘贴 API Key而不是走 OAuth。这种方式尤其适合你使用非官方服务商的时候因为 DeepSeek、OpenRouter 这类平台没有 OpenAI 的 OAuth 授权流程只能用 API Key 认证。实际使用中我碰到过一个非常隐蔽的问题如果你在环境变量里设置了OPENAI_API_KEYCodex 某些版本会优先读环境变量导致你明明执行了codex login登录态也不生效。表现就是看起来很正常的会话一问就报 401。解决办法是检查并清掉多余的环境变量或者用unset OPENAI_API_KEY之后再登录。2.3 登录态文件 auth.json位置、权限与丢失场景登录后的凭证信息会写入~/.codex/auth.json。正常情况下它的内容类似{ OPENAI_API_KEY: sk-... }这个文件就是 Codex 每次请求时读取 Key 的来源之一。它出问题会导致三个典型报错文件不存在——很多新手其实没完成登录直接跑 codex就会看到auth token is unavailable。文件权限过宽——我遇到过某次操作后 auth.json 变成 666 权限Codex 出于安全考虑拒绝读取表现同样是登录态丢失。文件里存的 Key 是旧的或者被撤销的——那就是五花八门的 401 变体。解决方式很简单chmod 600 ~/.codex/auth.json别小看这一条。权限问题在 Windows 上不明显但在 Linux 和 macOS 上非常常见。如果你在服务器上跑 Codex尤其要注意。文件不存在的时候最快的方式就是重新执行一次登录而不是手动去造这个文件。3. config.toml 配置逐字段拆解以及本地转发工具的用法3.1 config.toml 文件位置与最小可用配置Codex 的主配置文件在~/.codex/config.toml。如果你从来没改过第一次跑codex时会自动生成默认配置里面只定义了官方 provider 和默认模型。对于多数人来说最小可用配置长这样model gpt-5.2-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses注意两点model字段的模型名要以你账号实际可见的模型为准不同账号能用的模型不一样抄别人的模型名很常见地会得到 404 或者模型不可用model_provider必须和下方定义的 provider 块名称完全一致拼写错一个字母Codex 就会退回默认 provider配置等于白写。我见过不少人把model_provider写成model_providers或者忘记在[]里的名字加引号看起来小事但跑起来全是什么“unknown provider”“falling back to default provider”然后在日志里绕半天。先检查拼写再检查逻辑。3.2 核心字段拆解base_url、env_key、wire_api 各自管什么这三个字段是配置的灵魂。base_url决定请求发往哪里。OpenAI 官方是https://api.openai.com/v1DeepSeek 是https://api.deepseek.com/v1OpenRouter 是https://openrouter.ai/api/v1。这个字段一旦写错请求就会发到一个不存在的地址上收到的错误五花八门但最常见的是 404 和连接失败。env_key决定 Codex 从哪个环境变量读取 API Key。Codex 的读取优先级一般是先看 config.toml 里定义的env_key对应的环境变量再看 auth.json 里对应的字段。比如env_key OPENAI_API_KEY那它会尝试读OPENAI_API_KEY这个环境变量读不到就回落到 auth.json 的OPENAI_API_KEY字段。如果你接 DeepSeek把它改成DEEPSEEK_API_KEY并且登录时也写入对应的 Key才能正常对接。wire_api决定请求协议。最核心的区别是responses和chat。OpenAI 官方新接口走responses端点也就是你会在报错里看到的/responses很多第三方服务兼容的是chat端点即/chat/completions。如果你的 provider 是 DeepSeek 这类第三方wire_api还写成responses对方根本不认识这个路径必定报错。3.3 为什么模型名与接口地址不匹配时401 和 404 会一起出现很多人遇到 401 报错时会忽略一个现象有时候同一个请求里前面还在报 401改了一下配置又变成 404 了。这其实说明你的方向已经偏了。401 和 404 对应的排查维度完全不同报错类型指向的问题第一排查动作401 Unauthorized鉴权失败Key 不对、格式不对、服务端不认检查 API Key 本身404 Not Found接口路径不对服务端没有这个端点检查 base_url 和 wire_api模型不存在/不可用模型名写错或账号无权访问检查 model 字段举个例子你配置的是 DeepSeek 的 base_url但wire_api还写着responses那 Codex 就会向 DeepSeek 的/responses路径发请求DeepSeek 没有这个端点返回 404。此时如果你脑袋一热去换 API Key当然怎么换都是白搭。所以排查报错时先分清报错的 HTTP 状态码再去动对应的配置能省大量时间。3.4 用本地端口转发工具CC Switch 等统一管理多个 Key 时的配置热词里频繁出现的“CC Switch”本质上是一个本地端口转发工具。它的原理是在你机器上的某个本地端口比如 127.0.0.1:8080起一个转发服务Codex 把请求发到本地这个服务再把请求转发到你预设的上游 API并且帮你替换请求头里的 Key。很多人用它来“一键切换”多个模型服务商不用反复改 config.toml。思路很香但坑也不少。最常见的报错就是“CC Switch 本地转发服务启动失败无法处理 Codex 的 /responses 请求”。这里面其实有两个独立问题第一本地转发服务没起来。检查方式很简单curl http://127.0.0.1:8080/v1/models如果连接失败说明服务进程挂了或者端口不对。去看工具的日志通常能找到端口冲突或者上游地址配置错误的提示。第二Codex 的请求路径和本地转发工具的版本不兼容。部分旧版本转发工具只实现了/chat/completions转发没有实现/responses端点。当 Codex 发的是/responses请求时本地转发服务自己先返回“路径不存在”之类的错误这个错误再被 Codex 包装成看不懂的报错。解决办法有两个方向要么把 config.toml 里对应 provider 的wire_api改成chat让 Codex 走/chat/completions要么升级转发工具到支持responses端点的版本。还有人会导入网上分享的“订阅配置源”来更新 provider 预设。更新配置源之后一定要重启本地转发服务并且重新核对 config.toml 里的model_provider是否还指向上次那个名字。服务商预设一变模型名单和连接方式都可能跟着变Codex 里还写着旧的 provider 名就容易直接失效。4. 401 报错完整排查链路三种常见场景我按实际遇到频率从高到低说4.1 场景一incorrect api key provided: sk-xxx这是最典型的 401报错原文长这样unexpected status 401 unauthorized: incorrect api key provided: sk-svcac***看到这个报错绝大多数情况下就是 Codex 发请求时带的 Key 服务端不认。但“不认”的原因分好几种我列一个排查顺序确认 Key 有没有被截断或混入空格。可以用这个命令检查环境变量里的 Key 长度以及首尾有没有异常字符echo -n $OPENAI_API_KEY | wc -c确认 Key 是否过期或被撤销。到服务商后台重新生成一个新 Key换上去试一次立刻就能排除这个因素。确认 Codex 读到的是不是你刚更新的 Key。前面说过Codex 会同时看环境变量和 auth.json如果你更新了 auth.json但环境变量里还残留旧 KeyCodex 会读环境变量。这个问题特别隐蔽我建议把环境变量里的统一清掉只保留 auth.json 作为唯一事实来源。确认当前请求的模型路径和 Key 归属平台匹配。你用 DeepSeek 的 Key 却请求 OpenAI 的地址服务端当然拒绝你用 OpenAI 的 Key 请求 DeepSeek 的地址也是一样的下场。4.2 场景二auth token is unavailable这个报错说白了就是 Codex 找不到可用的登录凭据。它不一定代表你的 Key 有问题更多时候是登录态文件的问题。按顺序检查ls -la ~/.codex/ cat ~/.codex/auth.json如果auth.json不存在说明你从未成功登录或者某个清理操作把它删了。直接重新执行登录即可。如果文件存在看看内容里的 Key 字段名和 config.toml 里的env_key对不对得上。比如你接 DeepSeekauth.json 里存的是OPENAI_API_KEY而 config.toml 里env_key写的DEEPSEEK_API_KEY两边对不上Codex 自然觉得“没有 token”。这个场景我还有一个补充某些版本在检测到 auth.json 权限不安全时会拒绝读取。具体表现就是一切配置看着都对但每次请求都报 auth token is unavailable。用chmod 600 ~/.codex/auth.json修好权限之后问题立刻消失。4.3 场景三authentication fails, your api key: ****这个报错和场景一有点像但语义上有微妙区别。场景一明确说你提供的 Key 不正确而这个场景倾向于“你的 Key 确实存在但认证失败”常见原因是账户级的问题。比如你的服务商账户欠费、Key 被主动停用、或者账户被限制访问某个模型。处理方式也很直接登录服务商后台检查账户状态和账单情况重新生成新 Key 并且确认它启用了如果项目里还有 Studio 模式或团队账号的场景确认 Key 的角色权限足够。另外有些服务的 API Key 会在请求头里原样回显一部分报错里看到的****就是脱敏后的 Key。它能回显说明请求头是带上了的问题多半出在服务端对 Key 的存储比对结果上。所以这个场景不需要再折腾本地配置字节直接把注意力放到服务商侧。4.4 标准排查流程从客户端请求到服务端校验的逐层验证踩过几次 401 之后我总结了一个固定排查顺序不绕弯首先用 curl 直接向目标接口发起一次裸请求绕过 Codex验证 API Key 本身对不对。以 OpenAI 为例curl https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY如果这条命令返回 JSON哪怕里面说模型列表为空说明 Key 本身有效问题出在 Codex 配置层。如果这条命令也返回 401那就别再折腾 Codex 了回去看 Key 和账户。其次把 Codex 配置简化到不能再简只用官方 provider 和一个核心模型排除第三方转发工具的干扰。简化之后如果正常了那问题就在之前的 provider 配置或转发工具上。最后把环境变量全部清掉让 Codex 只读 auth.json。这个动作能将配置变量降到最少对比排查最有效。整个流程跑一遍大概五分钟。说实话大多数人卡在 401 上半小时都是因为在这三层之间反复横跳没有逐层隔离。5. 把 Codex 接到 DeepSeek 等兼容接口上配置实践与实测经验5.1 为什么越来越多的人选择接第三方兼容接口原因无非两个成本和可达性。成本方面DeepSeek 这类服务的定价比 OpenAI 官方低很多日常写代码、改 bug 的消耗明显便宜。可达性方面就像第 1.3 节说的如果你的网络环境访问官方接口不顺畅接一个能正常访问的兼容接口是更省事、更合规的替代方案。Codex 本身是一个客户端你完全可以把它的模型服务商从默认的 OpenAI 换成任意兼容服务。多说一句换服务商不改变 Codex 的交互方式你还是用同一个终端工具只是请求发往的目标和底层模型变了。这意味着你之前学的 Codex 用法全都可以继续用。5.2 实际配置示例DeepSeek 的 provider 写法接 DeepSeek 的完整配置如下model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat关键点有两个。第一wire_api必须写成chat。DeepSeek 提供的是 OpenAI 兼容的/chat/completions接口没有/responses端点。如果你这里写成responsesCodex 发出的请求路径就是错的会直接报 404 或者被本地转发工具拦截。这一条是接入第三方时最容易踩的硬坑。第二登录的时候要用 DeepSeek 的 API Key 执行一次登录或者直接把 DeepSeek 的 Key 写入 auth.json 对应的字段。config.toml 只告诉你 Codex“去哪里拿 Key”拿到的 Key 是什么取决于 auth.json 里存了什么。codex login --api-key # 粘贴你的 DeepSeek API Key5.3 接入第三方接口之后的实测体验与注意点我自己用 DeepSeek 接 Codex 跑了几周整体处于“能用但不完全相同”的状态。日常的代码生成、单函数实现、配置修改这些任务完成得不错速度也快。但两件事需要降低预期一是工具调用function calling的稳定性DeepSeek 对工具调用格式的支持不如 OpenAI 原生模型那么顺滑复杂 agent 任务偶尔会出现工具调用参数解析失败的情况二是上下文长度和实际有效上下文之间有一定出入大文件分析时可能感觉“它没看到后面的内容”。另外如果你在 config.toml 里同时配置了多个 provider比如 OpenAI 和 DeepSeek 都写了一定要确保每次切换时model_provider字段和model字段是一致的。我见过有人改了 model 改成deepseek-chatprovider 却还留在openai结果 Codex 用 DeepSeek 的模型名去请求 OpenAI 的接口服务端直接返回模型不存在或者鉴权失败又是一轮无意义的排查。从 DeepSeek 这边排查 401 的思路和官方平台一样先用 curl 测curl https://api.deepseek.com/v1/models \ -H Authorization: Bearer $DEEPSEEK_API_KEY通了再去查 Codex 配置不要舍近求远。6. 配置折腾多了分享几个我觉得特别值得记住的操作习惯每次改 config.toml 之前先备份一份。我用的是最笨但最有效的方法cp ~/.codex/config.toml ~/.codex/config.toml.bak改坏了直接恢复两秒钟的事。曾经有个朋友改完配置后连基础对话都用不了了但他完全想不起改过哪里最后只能从零开始重写。备份这个习惯能让你永远有后悔药。还有一个小技巧检查 Key 是否被正确写入时不要在终端里完整打印 Key。用head -c 20只看前 20 个字符既确认了 Key 已经写入又不会把完整 Key 留在终端历史和日志里。head -c 20 ~/.codex/auth.json最后说一个我个人的体会Codex 的配置体系其实特别简单核心就三样——base_url 告诉它去哪API Key 告诉它你是谁wire_api 告诉它怎么说话。401 报错之所以吓人是因为它把网络层、配置层、账户层的问题全部混在一个“未授权”的壳子里。你只要坚持用 curl 做隔离测试一层一层拆基本没有解不开的。至于那些看着长得差不多的别的报错下次遇到先看状态码再查对应的层就顺了。