如果你最近在终端里用 Codex 时报了一串unexpected status 401 unauthorized: incorrect api key provided，多半是 API Key 校验出问题了。这篇文章把自己从安装、配置到解决 401 报错的整套流程整理出来，当作一份可以直接照抄的 Codex 安装教程。内容涵盖基础环境准备、API Key 获取、登录配置、config.toml 详细参数，以及所有人都会踩一遍的 401 排查路径，最后附上接入 DeepSeek、OpenRouter 等第三方服务的扩展玩法。新手可以顺着走一遍，被 401 折磨过的老手可以直接跳到第五节。
1. Codex 是什么？为什么有人一装就卡在登录？
1.1 一句话讲清 Codex CLI
Codex 是 OpenAI 推出的 AI 编程助手，而这里讨论的是它的命令行版本，也就是 Codex CLI。它不是一个网页插件，而是直接跑在你终端里的代理程序，你可以在命令行里让它读文件、改代码、执行命令，它基于大模型理解你的指令，帮你完成从代码生成到 Git 提交的整套操作。
我用下来的感受是，它比单纯在网页里问 ChatGPT 要顺手得多，因为它在本地有工作区访问权限，可以直接操作项目文件。你给它一句“帮我看看这个仓库的测试为什么挂了”，它能自己定位测试文件、运行命令、分析报错、给你修复建议，甚至直接改完。
不过，正因为它是本地 CLI 工具，它需要一种方式验证“你是谁”“你有没有权限调用模型”。这个验证方式就是 API Key。很多人第一次安装时会卡在这一步：启动 Codex 后要求输入 API Key，输进去却被告知 401 Unauthorized。这其实就是认证没通过，和“账号密码错误”是同一回事。
1.2 为什么用 API Key 而不是账号密码
老用户可能会问：为什么 Codex 不直接让我输入 OpenAI 的邮箱密码？原因很简单：CLI 工具跑在你的本地环境里，如果用账号密码登录，那就意味着工具需要有能力保存你的登录态，甚至可能接触到你的账号级权限。一旦本机被植入恶意脚本，账号泄露的风险会非常大。
API Key 是一种更安全、更可控的授权方式。你可以单独创建一个 Key，限定它的额度、权限，甚至随时吊销。即使你的某个项目环境被攻破，攻击者拿到的也只是一个权限受控的 Key，而不是你的完整账号。它的工作原理本质上就是一个随机字符串，请求时放在 HTTP 头里发给服务端，服务端拿这个字符串去数据库查对应的账号和权限。
所以你在配置 Codex 时，需要做的不是“登录账号”，而是“把 API Key 配置给 Codex”，让它每次请求时都带上这个凭证。
1.3 这篇教程适合谁
说实话，Codex CLI 的安装门槛不算低。需要你有一点命令行基础，至少要会打开终端、理解npm命令、知道环境变量是什么。适合下面几类人：
- 已经拥有 OpenAI API Key，但想把 Codex 用起来的开发者。
- 在团队里负责搭建 AI 编程环境，需要给同事写一份可复现的安装文档的人。
- 遇到 401 报错不知道从何下手的同学，这篇教程会带你从日志到 Key 到端点一层层排查。
- 想试试把 Codex 接入 DeepSeek、OpenRouter 等模型服务的玩家。
如果你是纯零基础用户，连 Node.js 都没装过，建议先把第一节的环境准备部分反复看两遍，其实也没多少东西，耐心一点就能过。
2. 安装前准备：环境依赖与下载
2.1 Node.js 版本要求与检查
Codex CLI 本身是 Node.js 写的，所以第一步是确保本机有可用的 Node.js 运行时。我 2026 年 9 月实测的版本要求是 Node.js 18 及以上，如果你用的是 20 LTS 或者 22 LTS，基本不会遇到问题。如果你还在用 Node 16 或者更老的版本，建议先升级，否则安装时会直接报engine相关的错误。
检查方式很简单，打开终端输入：
node -v npm -v我个人的建议是直接装最新的 LTS 版本，不要去追非稳定版。Codex 更新频率很快，但 Node 的稳定才是基础。如果你同时装了多个 Node 版本，记得确认当前默认版本是你想要的那个，因为npm全局包的安装位置是和 Node 版本绑定的。
如果你在 Windows 上，安装 Node.js 时记得勾选“Add to PATH”选项，不然后面执行npm install时总是提示找不到命令。很多人的安装教程就是卡在这一步，明明装了 Node 却跑不起来。
2.2 安装 Codex CLI
环境没问题之后，安装 Codex 就一行命令的事：
npm install -g @openai/codex-g表示全局安装，这样你在任何目录下都能直接执行codex命令。安装完成后，先跑一下版本号验证是否成功：
codex --version正常情况下会输出一个类似codex 0.2.x的版本号。如果没有输出，可能是npm的全局 bin 目录没加到 PATH 里，Windows 用户可以检查一下%APPDATA%\npm，macOS/Linux 用户检查/usr/local/bin。
需要说明的是，Codex 官方也提供 Homebrew 等安装方式，但我个人更推荐 npm，原因有两点：一是发布最及时，新版本能第一时间通过npm update -g @openai/codex升级；二是跨平台体验一致，你在 Windows、macOS、Linux 上用到的命令完全一样。
2.3 关于官方下载与安装包的坑
我在网上看到不少人会搜索“Codex 安装包”或者“Codex 官网下载”。这里需要提醒一下：Codex CLI 没有传统意义上的独立安装包，它靠的是 npm 包分发。如果你在搜索引擎里找到某个站点提供了.exe或者.dmg的“Codex 安装包”，先留个心眼，那大概率不是官方渠道。
我并不是说第三方封装完全不能用，但命令行工具这东西，更新频率高、依赖复杂，手动封装包很容易滞后版本，而且安全性不可控。你无法保证别人在你机器上放了一个什么脚本。与其冒这个险，不如老老实实走 npm 官方源安装。
安装完之后先别急着跑任务，下一步是准备 API Key。
3. API Key 获取与首次登录配置
3.1 OpenAI API Key 获取方法与权限说明
API Key 是 Codex 的通行证。如果你已经有 OpenAI 账号并且充值过，获取 Key 的路径很直接：登录 platform.openai.com，进入 API Keys 页面，点击“Create new secret key”，给它起个名字，比如codex-cli，然后复制下来。
这里有几个关键细节很多人不知道：
- Key 只在创建时完整显示一次，关闭页面后就再也看不到了。如果忘了，只能重新生成一个新的。
- 创建 Key 时建议同时设置项目级别的权限限制，而不是创建一个全账号通用的 Key。万一泄露了，影响面可以被控制住。
- 免费额度账号也能生成 Key，但 Codex CLI 依赖的模型调用不一定会被免费额度覆盖，建议提前确认账号的计费状态。
生成 Key 之后，可以先拿去 OpenAI 的 API 页面或者 Postman 里做个连通性测试，避免后面 Codex 报错时还要回头怀疑 Key 本身的可用性。
3.2 首次登录：codex login 与 API Key 输入
拿到 Key 后，在终端里先随便进入一个项目目录，然后执行：
codex login首次运行会弹出一个交互式界面，让你选登录方式。最新的 Codex 版本通常提供三种方式：
- OpenID Connect：适合企业级 SSO 登录，一般个人用户用不到。
- API Key：最常见，输入你在 OpenAI 平台创建的 Key。
- Sign in with GitHub：通过 GitHub 账号授权，本质上也绑定的是平台账号的额度。
个人用户直接选 API Key 就行。选中后它会提示你粘贴 Key，注意粘贴时终端里可能不会显示任何字符，这是正常现象，不是卡了。粘贴完按回车，它会帮你写配置文件并完成一次内部验证。
如果你之前已经登录过，想换个 Key 重新登录，可以看看自己的主目录下有没有.codex目录，里面有一个auth.json文件，里面记录着当前登录用的 Key。切号时可以直接编辑这个文件，或者删掉后重新执行codex login。
3.3 登录后的验证
登录完成后，先做一个最简单的测试，让 Codex 响应一个基础问题：
codex exec "say hello"如果配置正常，它会调用模型并返回一段问候语。如果此时直接看到401，那就别急着往下走，先把第五节的内容看完。如果你能正常收到回复，恭喜，基础链路已经通了。
这里我再补充一个个人习惯：我会在第一次跑通后立刻检查auth.json的权限位。把它的权限设置为只有当前用户可读写，避免 Key 被本机其他用户读取。
chmod 600 ~/.codex/auth.json这个习惯价值很大，因为 API Key 本质上是你的钱袋子凭证，被别人拿到就等着被刷爆吧。
4. 配置详解：config.toml 与环境变量
4.1 config.toml 在哪里
Codex 的配置集中在~/.codex/config.toml。不管你在哪个目录下执行codex，它默认读的都是这个文件。如果你用的是团队内部定制版，也可以通过CODEX_HOME环境变量把配置目录指到其他地方。
我第一次安装时找这个文件找了半天，因为它不是自动生成的，是登录成功后才会写出来。如果你执行过codex login，直接打开这个文件，你会看到类似这样的内容：
model = "gpt-5-codex" model_provider = "openai" approval_policy = "on-request" [model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com" env_key = "OPENAI_API_KEY" wire_api = "responses"这只是最基础的形态。你可以在里面加很多自定义参数，常见的包括：
model：指定使用哪个模型，比如gpt-5-codex、gpt-5、o3。approval_policy：控制命令执行的审批策略，常见值有on-request、on-failure、never。model_provider：决定请求走哪家供应商，默认是openai，可以改成deepseek、openrouter等。base_url：API 服务的根地址。
我的建议是，凡是涉及远程服务配置的改动，都先备份一份config.toml，避免改错之后找不到原来能用的版本。
4.2 常用配置项深度说明
很多人配置config.toml时会忽略一个核心参数wire_api。这个参数决定了 Codex 用哪种协议格式和模型服务通信。
responses：OpenAI 最新的 Responses API，Codex 默认值。chat：兼容老式 Chat Completions API，主要是给第三方供应商用的。
你如果把base_url指向 DeepSeek，但wire_api还是默认的responses，大概率会直接报路由错误或者 404。因为 DeepSeek 的兼容层只实现了 Chat Completions，没有实现 Responses API。所以接第三方服务时，wire_api一般都要改成chat。
approval_policy也很重要，我个人推荐个人项目用on-request，也就是每次要执行命令前问你一下。虽然这样交互上会多一点确认，但至少不会出现 Codex 擅自把你的文件删了的情况。
4.3 环境变量配置与 Key 管理技巧
除了config.toml，Codex 还支持从环境变量里读取 API Key，避免把 Key 直接写进配置文件。如果你不想让 Key 明文出现在auth.json或者config.toml中，可以在终端配置文件（.zshrc、.bashrc）中设定：
export OPENAI_API_KEY="sk-xxxx"然后在config.toml的 provider 配置里用env_key指定：
[model_providers.openai] name = "OpenAI" base_url = "https://api.openai.com" env_key = "OPENAI_API_KEY" wire_api = "responses"这样 Codex 就会优先从环境变量去取 Key，而不依赖auth.json。这个方式的好处是，你可以把config.toml放进 Git 仓库里给同事共享，而真正的 Key 还留在每个人的环境变量中，不会因为误传仓库而泄露。
Windows 用户设置环境变量后，记得重新打开终端，让新变量生效。macOS 用户如果用 zsh，改完.zshrc后执行source ~/.zshrc。
5. 401 报错解决实录（含常见问题速查）
5.1 401 报错到底在报什么
401 Unauthorized是所有 API 请求中最折磨人的错误。HTTP 协议里的 401 意思是“服务器认出了你的请求，但拒绝了你的身份凭证”。换成大白话就是：服务器知道有个请求来了，但你给它的门禁卡刷不开门，或者这门禁卡根本不在系统里。
对于 Codex 来说，最常见的报错长这样：
Error: unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****注意看后面那一长串sk-开头的字符串，那是服务器在回显它收到的 Key。它已经把明文打出来了，所以不用猜是不是网络问题，直接逐项核对就能找到原因。
另外有一种报错稍有差别：
unexpected status 401 unauthorized: authentication fails, your api key: ****这个通常是 Key 本身有格式问题，比如复制的时候多了一个空格、少了几位字符，服务器识别不了这个 Key 的格式。
5.2 排查步骤一：看完整报错与日志
遇到 401，第一步不是疯狂重试，而是先打开 Codex 的日志。 日志一般会输出到终端，但细节不全时可以用：
codex --debug或者查看~/.codex/log/codex.log。日志里会记录请求的完整 URL、请求头、响应体，能帮你判断问题出在 Key 上，还是出在端点配置上。
我见过有的项目配置了自定义base_url，写错了一个字符导致请求发到了错误域名；这种问题从终端简洁的报错信息里根本看不出来，但日志里非常明显。多花一分钟看日志，能省下半小时盲目排查。
5.3 排查步骤二：验证 API Key 本身
终端里的 401 不一定都是 Codex 的问题。最好的办法是绕过 Codex，直接用命令行工具调一次 API 验证 Key。 以 OpenAI 为例，可以用curl发一个最简请求：
curl -X POST https://api.openai.com/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer sk-xxxx" \ -d '{"model":"gpt-4o-mini","messages":[{"role":"user","content":"hi"}]}'如果返回正常回复，说明 Key 有效，问题出在 Codex 的配置上。如果返回 401，说明 Key 确实有问题，需要检查：
- 是否复制完整，粘贴时有没有吞掉末尾字符。
- 是否在错误的平台创建，比如把某个第三方平台的 Key 当成了 OpenAI 的 Key。
- 账号是否欠费或被封禁，欠费状态下 Key 可能被暂时停用。
- 是否设置了过强的权限限制，比如某些 Key 只允许访问特定模型，访问其他模型时也会报 401。
5.4 排查步骤三：确认端点（Base URL）没写错
如果你在config.toml里自定义了base_url，那 401 排查时一定要把端点地址和模型服务商的规则对齐。 第三方的兼容服务通常要求：
base_url = "https://api.deepseek.com/v1" wire_api = "chat"此时要注意路径后缀。有时候服务商要求写全https://api.deepseek.com，有时候要求写到/v1。写错了，请求会到错误路径，可能注册成功的响应也变成一个带重定向的页面，导致 Codex 误判。
还有一个小细节，很多第三方服务要求base_url前面必须是https://，你如果只写了域名不带协议，Codex 会默认用http://而不是https://，这种情况下不仅 401，还容易触发安全性错误。
5.5 其他常见错误速查表
这里整理一份我在实际使用中遇到的冷门问题，你可以直接对号入座：
| 现象 | 常见原因 | 解决方案 |
|---|---|---|
| 401 + incorrect api key provided | Key 复制不完整或已吊销 | 重新生成 Key，确认粘贴内容 |
| 401 + authentication fails | Key 格式错误或来源不对 | 确认是 OpenAI 官方 Key 而非第三方平台 Key |
| 404 + endpoint not found | base_url 路径写错或 wire_api 不匹配 | 检查服务商文档，调整路径和 wire_api |
| 400 + invalid model | 模型名在当前 Key 权限之外 | 换一个可用模型，或检查 Key 限制 |
| cc switch local proxy failed while handling codex endpoint /responses | 本地网络代理规则拦截了请求 | 检查本地网络代理设置，确保 api.openai.com 请求不受干扰 |
| timeout / connection reset | 网络环境不稳定 | 换个网络环境重新试 |
| Please login again | auth.json 失效或不存在 | 执行codex login重新认证 |
表格里特意列了“本地网络代理规则拦截”这条。很多人以为是 Codex 坏了，其实是你电脑上运行着网络代理类软件，它不会拦截网页访问，但会拦截命令行工具的终端请求，导致 Codex 报出听起来很奇怪的错误。这时候需要调整网络代理的规则，把 API 请求的域名放行。
6. 实战扩展：Codex 接入 DeepSeek、OpenRouter 等第三方
6.1 为什么有人要把 Codex 接到第三方
有些人没有 OpenAI 的账号或额度，但想体验 Codex 的终端交互方式；也有人是有多套模型服务，想统一在一个 CLI 里调用。于是就有了“Codex 接 DeepSeek”这种玩法。
原理上很简单：Codex 只是客户端，底层模型是谁不重要。只要你有一个兼容 API 的服务商，把它的 Key 和端点填进配置就能用。 完全没必要把 Codex 绑定死在 OpenAI 上。实测下来，DeepSeek 的模型在代码生成上确实水准不错，性价比也高，日常写脚本完全够用。
6.2 配置自定义 Base URL
以 DeepSeek 为例，你需要先去 DeepSeek 开放平台创建一个 API Key，然后修改~/.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"记得在环境变量里补上：
export DEEPSEEK_API_KEY="sk-..."完成后重启 Codex，再用之前那个codex exec "say hello"测试。 如果返回的模型名是deepseek-chat，说明切换成功。
如果你想接 OpenRouter，配置也几乎一样，只是把base_url指向 OpenRouter 的官方地址，再用 OpenRouter 的 Key 去认证：
[model_providers.openrouter] name = "OpenRouter" base_url = "https://openrouter.ai/api/v1" env_key = "OPENROUTER_API_KEY" wire_api = "chat"6.3 切换后的注意点
接第三方服务时有几个坑必须先告诉你。
- 并不是所有第三方都完整支持 Codex 的所有功能。
codex exec里的代码执行、文件读取这些能力和底层模型相关，模型能力弱的话体验会明显下滑。 - 第三方服务的 API 格式和 OpenAI 官方格式可能存在差异。 别一上来就报 401，先确认服务商的 API 文档写的是
/chat/completions还是/responses，对应调整wire_api。 - 环境变量要多注意。 如果你之前已经导出了
OPENAI_API_KEY，而你把model_provider切到deepseek，但env_key没改，Codex 可能会尝试读取空的DEEPSEEK_API_KEY，最后拿到一个无效 Key，报 401。这种错误很隐蔽，排查起来也很费劲。
我的实操经验是每切换一个 provider 就对照config.toml里三层信息：model、base_url、env_key。三个都对应上，基本不会出问题。
最后再分享一个小技巧：遇到任何登录或 401 问题时，第一反应不是删配置重装，而是用codex --debug跑一次，把日志保存下来。日志里几乎会直接告诉你 Key 是什么、请求发到了哪里、服务器回应了什么。比起对着屏幕猜，看日志始终是最快的排查方式。我把它放在这里不是凑字数，而是这个习惯帮我省过太多次调试时间，希望你也能用上。
