Codex 这个终端里的 AI 编程助手从去年火到今年2026 年 9 月这个时间点大家问得最多的依然还是老四样怎么安装、API Key 怎么配、能不能接第三方模型、以及那个让人血压升高的401 unauthorized。这篇就把安装教程、API Key 登录配置和 401 报错解决一次讲透基于我这半年多用下来的实际踩坑经验不是官网文档复读机。适合刚接触 Codex CLI 的开发者也适合那些配好了但一运行就报incorrect api key provided的老哥。1. 装之前先搞清楚Codex 是什么需要什么环境1.1 这个工具到底是干嘛的值不值得装Codex 是 OpenAI 开源的一个命令行 AI 编程助手本质是一个跑在你终端里的智能体。它跟你在网页上问 ChatGPT 最大的区别是它可以直接读你本地仓库的文件、帮你改代码、执行命令、跑测试甚至提交 commit。说人话就是——你给它一个任务它在你的项目目录里实际动手干活而不是只给你一段粘贴回去的代码。拿我自己的使用场景举例接手一个老项目时我会直接对 Codex 说“帮我梳理一下这个仓库的模块结构找出入口文件和数据流向”它会自己打开目录、读文件、给出结论。修 bug 的时候把报错信息丢给它它能定位到具体文件改完还会跑一遍测试验证。说白了它把“读代码、改代码、验证代码”这条链路打通了你更像是项目经理它是那个执行力很强的开发。2026 年 9 月这个版本Codex 已经支持多文件批量修改、沙箱执行环境、agentic 自主规划任务日常开发完全够用。适合谁前端后端全栈都可以尤其适合写 Python、TypeScript、Go 这类工程代码的人。如果你是刚开始接触命令行的小白也没关系下面所有步骤我都按“对着做就能跑”的标准写。1.2 必备环境Node.js 和 Git 是硬门槛Codex 是用 npm 包分发的所以 Node.js 是第一个硬性依赖。官方要求 Node.js 18 以上我个人建议直接上 20 或 22 的 LTS 版本省得到时候因为版本太老遇到奇怪问题。装完后终端里敲这两条命令确认node -v npm -v能输出版本号就说明 Node 环境没问题。如果这两条命令报“command not found”那就得先装 Node.js。macOS 用户用 Homebrew 一条命令brew install nodeLinux 用户走 apt 或从 Node 官网下载预编译包Windows 用户我建议直接装完 Node 后把 Git Bash 或 WSL2 配好后面很多命令行操作会舒服很多。第二个依赖是 Git。Codex 在分析项目时经常要靠git diff看改动在 agentic 模式下还要自己 commit没有 Git 它根本转不起来。检查方式git --version没有 Git 的话同样用 Homebrew 或系统包管理器装一下。很多人安装失败其实不是 Codex 的问题而是 Node 或 Git 没装好这一步先自检能省掉后面一整串烦恼。2. 安装 Codex主流的两种方式够用了2.1 npm 全局安装最通用的一条路npm 是安装 Codex 最通用的方式命令就一条npm install -g openai/codex装完验证codex --version能输出版本号就说明装好了。以后要升级也很简单npm update -g openai/codexnpm 这种方式的好处是跟 Node 生态绑定紧密升级及时Linux、macOS、Windows 都能用。缺点是全局安装偶尔会遇到权限问题报错长这样Error: EACCES: permission denied, access /usr/local/lib/node_modules意思是 npm 全局目录没有写权限。最粗暴的解法是sudo npm install -g openai/codex但我更推荐把 npm 全局目录改成用户目录下的路径一劳永逸。具体操作是执行npm config set prefix ~/.npm-global然后把~/.npm-global/bin加进 PATH重新打开终端再装一次。这样以后装任何全局包都不用 sudo也不怕权限错乱。2.2 Homebrew 和二进制包适合 macOS 和离线场景macOS 用户如果不想让 Node 掺和可以用 Homebrew 直接装brew install codex brew upgrade codex这个方式的好处是 Homebrew 会自动处理依赖升级也方便。不过要说明一点brew 仓库里的 Codex 版本更新可能比 npm 稍微滞后一点点具体看维护节奏日常使用差别不大。还有一种場景是离线环境或内网开发机npm 和 brew 都走不通。这种时候就去 Codex 的 GitHub Releases 页面下载对应平台Linux/macOS/Windows的预编译二进制包包名一般是codex-平台-架构.tar.gz这种格式解压后把里面的可执行文件放到/usr/local/bin或任意 PATH 目录下直接codex --version验证就行。有个小提醒Mac 上如果是 Apple Silicon 芯片下载时要选aarch64的包别下成x86_64的虽然能跑但会走 Rosetta 转译性能差点意思。怎么确认架构终端里敲uname -m。3. API Key 登录与配置把 Codex 真正跑起来3.1 API Key 从哪来怎么拿更安全API Key 是 Codex 按量计费模式的钥匙。如果你用的是 OpenAI 官方服务去 OpenAI Platform 的 API Keys 页面创建点“Create new secret key”生成一串以sk-开头的字符串。注意这个 key 只在创建那一刻完整显示一次页面关掉就再也看不到了所以必须立刻复制保存到密码管理器里。我见过太多人栽在这件事上key 没保存刷新页面后找不回来只能重新生成。这倒不是大问题麻烦的是有一部分人把从网页版 ChatGPT 复制出来的 token当成 API Key 用——这俩完全不是一回事。API Key 是开发者平台的凭据跟网页版订阅登录态不能混用你用网页版的东西去配 Codex不报 401 才怪。再一个安全点API Key 不要截图发群里不要提交到 Git 仓库。key 的权限尽量做小OpenAI 平台支持创建带预算上限的 key团队用的话按人按项目分开建别一把 key 走天下。第三方兼容平台比如 DeepSeek 开放平台、OpenRouter也都提供类似格式的sk-key获取流程大同小异去对应平台的 API Keys 页面创建即可。3.2 两种登录形态ChatGPT 订阅登录 vs API Key 模式Codex 支持两种认证方式搞清楚这个后面 401 的坑能少踩一半。第一种是 ChatGPT 账号登录适合手里有 ChatGPT Plus 或 Pro 订阅的人。终端执行codex login它会拉起浏览器让你授权授权成功后凭据存到~/.codex/auth.json。这种模式不按 token 单独计费直接用订阅额度。第二种是 API Key 模式也是这篇教程的重点。API Key 模式不需要执行codex login你只需要让 Codex 能找到 key 就行。最常见的方式是设置环境变量export OPENAI_API_KEYsk-xxxxxxxxxxxx为了每次打开终端都生效把这行写进你的 shell 配置文件里比如~/.zshrc或~/.bashrc。这里有个非常关键的细节如果你之前用codex login登录过 ChatGPT 账号后来想切到 API Key 模式一定要先执行codex logout如果不做这一步Codex 可能仍然优先读取auth.json里的登录态导致你配好了OPENAI_API_KEY也白搭——它压根没用你的 key当然更谈不上 401 不 401 了。我个人的习惯是一台机器只保留一种凭据来源要么纯登录态要么纯 API Key绝不混着来。3.3 配置文件 config.toml 的核心字段一次看懂除了环境变量Codex 还支持通过配置文件~/.codex/config.toml来定模型、定服务商、定 key。这是最灵活的方式尤其适合接第三方模型。一份最基础的 OpenAI 官方配置长这样# ~/.codex/config.toml model gpt-5-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指定跑哪个模型OpenAI 官方模型名以平台文档为准我这里写的gpt-5-codex是目前常见的 Codex 模型名2026 年 9 月如果你在模型列表里看到更新的版本直接替换即可。model_provider默认走哪个 provider写的是上面定义的 provider 块名字。[model_providers.openai]一个 provider 定义块。name是显示名base_url是 API 地址env_key是告诉 Codex“读哪个环境变量来拿 key”wire_api是请求协议格式。配置文件的好处是你不用在 shell 里维护一堆环境变量key 都通过env_key去环境变量里取配置文件本身不存明文密钥这个习惯一定要养成。你甚至可以不用环境变量直接在 provider 里写api_key sk-xxx但我不推荐——配置文件经常会被同步工具或团队共享明文 key 放里面等于裸奔。4. 第三方模型接入DeepSeek 与 OpenRouter 配置实例4.1 为什么那么多人要把第三方模型接进来不是所有人都有 OpenAI 官方 API 的配额也不是所有人都愿意为官方模型付那个单价。第三方 OpenAI 兼容服务的优势很实际价格便宜、模型选择多、额度管理灵活。Codex 这个工具本身设计得比较开放只要接口协议兼容它就能跑。我自己的主力配置就是混合型的日常写代码用 OpenAI 官方模型跑一些批量重命名、日志分析这种不怎么需要智力的任务就切到 DeepSeek成本能省不少。所以学会配置第三方 provider 不是花活是实实在在省钱省事。4.2 DeepSeek 接入别忘了 wire_api chatDeepSeek 的开放平台提供 OpenAI 兼容接口接进 Codex 很简单但有一个坑必须提前说Codex 默认用 Responses API 协议而 DeepSeek 这类第三方服务通常只兼容 Chat Completions 老协议你要是照抄默认配置直接跑会报各种各样的 400/404 错误。正确的 DeepSeek 配置是这样# ~/.codex/config.toml 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这一步是把 Codex 的请求协议切回 Chat Completions。很多人配完不生效、或者报404 Not Found十有八九就是漏了这一行。环境变量方面你需要在 shell 里导出DEEPSEEK_API_KEY而不是OPENAI_API_KEY因为配置文件里env_key指向的是DEEPSEEK_API_KEY。DeepSeek 的模型名主要有deepseek-chat和deepseek-reasoner两个前者是通用对话模型日常改代码够用后者带推理能力适合需要深度分析的任务但响应慢一些、限流也更紧。想跑的是推理模型就把model字段改成deepseek-reasoner。4.3 OpenRouter 接入模型名记得带前缀OpenRouter 是一个聚合平台一个 key 能访问很多家模型配置方式和 DeepSeek 类似但有两个细节不一样。第一个是base_url要填https://openrouter.ai/api/v1不是/v1后面的路径也别再加东西。第二个是模型名必须带提供商前缀比如openai/gpt-5-codex、anthropic/claude-sonnet-4、google/gemini-3-pro具体名字以 OpenRouter 网站的模型列表为准直接复制它显示的名字就行。配置示例# ~/.codex/config.toml model openai/gpt-5-codex model_provider openrouter [model_providers.openrouter] name OpenRouter base_url https://openrouter.ai/api/v1 env_key OPENROUTER_API_KEY wire_api autoOpenRouter 的请求协议支持情况比 DeepSeek 好一些wire_api填auto让它自己协商就行。如果某个模型报协议不兼容再把wire_api改成chat重试。另外 OpenRouter 有一个自身特点在请求头里带上HTTP-Referer和X-Title可以让官方后台统计调用来源方便你按项目看用量但这个属于进阶玩法不影响跑起来。4.4 警惕配置切换工具留下的坑local proxy failed配置写多了以后很多人会懒得手动改config.toml于是用一些第三方 GUI 配置切换工具来管理 provider比如社区里常见的 cc-switch。这类工具的本意是好的帮你维护多套配置一键切换。但它有个很恶心的副作用就是某些版本会在config.toml里写入一个指向本机端口的base_url类似http://127.0.0.1:xxxxx靠工具内置的本地中转服务转发请求。如果这个本地服务没启动、端口被占用、或者切完配置后工具直接退出了Codex 请求就会失败。热搜里那个cc switch local proxy failed while handling codex endpoint /responses就是这个场景的典型报错。排查方法很简单打开~/.codex/config.toml看一眼当前 provider 的base_url是不是指向127.0.0.1或localhost。如果是要么重新开一下那个切换工具让它把服务启起来要么直接把base_url改回你要用的官方 API 地址保存后重启 Codex。我自己的建议是这类工具当配置生成器用可以生成完自己检查一遍config.toml再跑别完全依赖它当运行时服务。5. 401 报错全解析incorrect api key provided 到底哪错了5.1 先看懂 401 的几种报错文案401 是 HTTP 状态码意思是“未认证”翻译成人话就是服务器收到了你的请求但觉得你没资格访问。Codex 场景下不同服务商返回的文案不太一样但意思差不多报错原文常见来源实际含义unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****OpenAI 官方请求头里的 key 无效服务端不认unexpected status 401 unauthorized: authentication fails, your api key: ****OpenRouter 等第三方key 没通过认证多半是格式或归属问题unexpected status 401 unauthorized: incorrect api key provided:OpenAIkey 字段为空或解析失败401 unauthorized (no api key)各种压根没读到 key环境变量没生效注意第一种报错里那个sk-svcac****这是服务端把 key 脱敏后展示出来的前几位不是说你 key 的完整值就是sk-svcac。它是在告诉你我确实收到了一个 key但这个 key 我没法用。换句话说请求已经发出去了问题出在 key 本身不合法。5.2 七步定位法从 key 到请求链路逐个排查遇到 401 别慌按照下面这套顺序排查绝大多数都能定位到根因。我给它起了个名叫“七步定位法”每一步都不难关键是别跳步。第一步先确认 key 本身到底有没有问题。打开 OpenAI Platform 的 API Keys 页面看看你那个 key 还在不在、有没有被删除或禁用。如果不确定干脆重新生成一个新的这是最省事的验证方法。第二步用 curl 直接测 key 有效性绕过 Codex 单独验证curl -sS https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY | head -n 20能返回 JSON 列表说明 key 有效返回 401 说明 key 真的有问题。这一步能帮你把锅甩清楚——到底是 key 坏了还是 Codex 配置坏了。第三步检查环境变量有没有被污染或覆盖。最常见的情况是你设置了多个 key或者.env文件里带引号。看环境变量前几位就行别把完整 key 打出来echo ${OPENAI_API_KEY:0:10}如果显示的是空说明环境变量根本没设。如果显示sk-开头带引号说明你在.env或export的时候把双引号也存进去了这个引号会跟着 key 一起发送服务端自然不认识。正确做法export OPENAI_API_KEYsk-真实key引号是为了防止 shell 把特殊字符吃掉但它不会被存进变量值里。至于.env文件很多解析工具是不会帮你剥引号的所以.env里建议写成OPENAI_API_KEYsk-xxx不带引号。第四步打开~/.codex/config.toml核对 provider 配置。重点看base_url是不是你真正想请求的服务地址model_providers有没有写错。很多 401 其实是把 DeepSeek 的 key 配到了 OpenAI 的 provider 下——不同平台的 key 不通用看起来都是sk-开头但服务端验证体系完全不一样。第五步检查auth.json登录态是否在捣乱。执行codex logout这个命令会把上次 ChatGPT 登录的 token 清掉。如果你之前登过 ChatGPT 账号这会强制 Codex 走环境变量或配置文件里的 key 来源。第六步看请求到底打到了哪里。Codex 支持调试日志运行时加上--debug参数版本不同可能参数名略不一样用codex --help看日志相关选项就行codex --debug看日志里实际请求的 URL 和 Authorization 头能一眼看出 base_url 是否被改成了本地端口、key 是否真的传上去了。第七步检查模型名是否与提供方匹配。OpenAI 官方 key 不能配deepseek-chat模型OpenRouter 的 key 配deepseek-chat也要写成deepseek/deepseek-chat前缀格式。模型名写错有时会报 404有时也会以 401 的形式出现因为服务端在认证机制上就把不认识的模型归属直接拒绝了。5.3 别把 429 和 400 当成 401 处理401 是认证问题但它身边还有两个长得挺像的兄弟很多人排查时一锅乱炖白白浪费时间。429 是“请求太多/配额不足”报错里通常带rate limit或quota字样。出现这个错误别去改 key那是白费劲——你的 key 没问题是额度用完了或并发超了。解法是去平台充值、等限流窗口过去或者换一个并发额度更高的模型。400 是“请求格式不对”常出现在你配了wire_api responses但目标服务商不支持 Responses API 的时候。这种时候把wire_api改成chat就能解决也就是上一节 DeepSeek 配置里的那个关键字段。区分这三个错误的方法很简单401 和 key 有关429 和钱/量有关400 和协议/参数有关。报错文案里找关键词即可incorrect api key基本锁定 401rate limit锁定 429bad request锁定 400。6. 踩坑实录与一套能用的日常习惯6.1 我踩过的五个真实事故第一个事故是.env引号事故。当时我在.env里写了OPENAI_API_KEYsk-xxx然后工具加载时把引号一起带进了环境变量Codex 疯狂报incorrect api key provided: sk-xxx。排查了半天才发现是引号问题去掉引号立刻好了。从那以后我所有.env里的 key 一律不带引号。第二个事故是登录态覆盖事故。我一开始用 ChatGPT 账号登录过 Codex后来想切到 API Key 模式配好了环境变量结果还是报 401。百思不得其解最后发现auth.json里的旧 token 还在Codex 优先用了它。执行codex logout之后一切恢复正常。第三个事故是把 DeepSeek 的 key 填到了 OpenAI 的 provider 配置下。因为我图省事直接把env_key改成了OPENAI_API_KEY但里面装的是 DeepSeek 的 key。Codex 把请求发到api.openai.comOpenAI 一看这 key 不是我的直接 401。这个错误看着像是 key 坏了实际是配置指向错了。第四个事故是配置工具的本地转发服务没启动。我用 cc-switch 从 OpenAI 切到别的 provider 后Codex 一直报cc switch local proxy failed while handling codex endpoint /responses检查config.toml才发现base_url变成了http://127.0.0.1:xxxxx而那个中转进程根本没跑起来。手动把base_url改回官方地址解决。第五个事故是旧环境变量残留。我在 shell 里 export 过一次旧 key后来重新配置了新 key但没重启终端旧的值一直占着变量。每次运行 Codex 都是旧 key当然 401。用unset OPENAI_API_KEY清理后再 export 新 key 才解决。这个事提醒我改完 key 务必重启终端或者确认环境变量真的是新值。6.2 值得养成的四个配置习惯这些习惯都是血的教训总结出来的建议直接照抄。第一key 永远不进配置文件明文一律走env_key引用环境变量。这样就算config.toml被同步到别的机器也不会泄露密钥。第二环境变量只设当前项目需要的 key。你的 shell 里只保留一个OPENAI_API_KEY如果你同时在测多个 provider就用config.toml里的env_key做隔离别让 key 互相干扰。第三定期回平台检查 key 用量。OpenAI 和 DeepSeek 的控制台都能看请求次数和消费金额养成每周看一眼的习惯能提前发现异常的调用暴增。一旦觉得 key 泄露了立刻在平台撤销并重新生成。第四团队共用配额时尽量走一个统一的服务网关不要让每个人都持有主 key。网关做一层转发和审计既能控制成本也能在出问题时定位到人。当然这个不是每个人都有条件但对团队使用场景来说价值很大。6.3 一套暴力的 401 重置流程90% 都能这么收场最后分享一套我自己屡试不爽的“暴力重置法”。遇到 401先别深入分析直接按顺序执行这三步codex logout unset OPENAI_API_KEY export OPENAI_API_KEYsk-全新的key第一步清登录态第二步清环境变量残留第三步注入全新 key然后重新跑 Codex。为什么说它能覆盖 90% 的情况因为绝大多数 401 都出在三个地方登录态覆盖、环境变量残留/污染、key 本身失效。这三步正好把这三种情况一次性全部归零重置。如果三步走完还报 401那基本可以确定是 key 被服务端判定无效了。这时候别纠结直接去对应平台生成一把新 key 再试一次成本比来回查配置低得多。我个人的体会是Codex 的 401 报错里真正“莫名其妙”的情况其实很少绝大多数都是配置来源太杂导致的。你只要坚持“一台机器一种凭据来源、key 不写明文、改配置后重启终端”这三个小原则这个错误基本告别你的开发日常。希望这篇能把你的 Codex 环境一把跑通毕竟把时间花在写代码上比花在跟 401 斗智斗勇上值多了。