如果你最近在终端里用 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 CLICodex 是 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%\npmmacOS/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_urlAPI 服务的根地址。我的建议是凡是涉及远程服务配置的改动都先备份一份config.toml避免改错之后找不到原来能用的版本。4.2 常用配置项深度说明很多人配置config.toml时会忽略一个核心参数wire_api。这个参数决定了 Codex 用哪种协议格式和模型服务通信。responsesOpenAI 最新的 Responses APICodex 默认值。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.tomlCodex 还支持从环境变量里读取 API Key避免把 Key 直接写进配置文件。如果你不想让 Key 明文出现在auth.json或者config.toml中可以在终端配置文件.zshrc、.bashrc中设定export OPENAI_API_KEYsk-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 providedKey 复制不完整或已吊销重新生成 Key确认粘贴内容401 authentication failsKey 格式错误或来源不对确认是 OpenAI 官方 Key 而非第三方平台 Key404 endpoint not foundbase_url 路径写错或 wire_api 不匹配检查服务商文档调整路径和 wire_api400 invalid model模型名在当前 Key 权限之外换一个可用模型或检查 Key 限制cc switch local proxy failed while handling codex endpoint /responses本地网络代理规则拦截了请求检查本地网络代理设置确保 api.openai.com 请求不受干扰timeout / connection reset网络环境不稳定换个网络环境重新试Please login againauth.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.tomlmodel 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_KEYsk-...完成后重启 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 chat6.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 是什么、请求发到了哪里、服务器回应了什么。比起对着屏幕猜看日志始终是最快的排查方式。我把它放在这里不是凑字数而是这个习惯帮我省过太多次调试时间希望你也能用上。