1. 安装本身很简单复杂的是登录这一关1.1 先想明白Codex 缺了 API Key 就是空壳标题写着Codex 安装教程但我得先说句实话Codex 的安装真的不难难的是安装完之后那一串认证配置和 401 报错。Codex 本质上是一个命令行客户端它本地不运行什么大模型所有推理请求都要发送到云端模型接口。也就是说你装好 CLI 只是拿到了一个壳真正的命脉是 API Key——没有它Codex 连一句 hello 都跑不出来。这也是为什么网上搜索Codex 安装教程时结果里总是混着大量和 API Key、401、base_url、第三方网关相关的报错。很多人在安装阶段一切顺利结果第一次运行就撞上unexpected status 401 unauthorized然后开始怀疑人生。这篇文章就是按照 2026 年 9 月这个时间点的实战情况来写的主线就三条装好、登录、解决 401。如果你是第一次接触 Codex或者卡在某个认证报错里出不来照着往下走就行。1.2 一句话装完 CodexCodex CLI 目前最主流的安装方式还是 npm 全局安装。前提是你机器上已经有 Node.js 环境建议 Node.js 20 以上npm 版本别太老。装完 Node 之后打开终端执行npm install -g openai/codex装完验证一下codex --version能打印出版本号说明 CLI 已经正常落地。我看到过不少人卡在这一步最常见的三个现象是codex: command not foundnpm 全局 bin 目录没有加入 PATH检查一下npm prefix -g对应的目录把它配到 PATH 里。安装时权限报错npm 全局目录需要写权限macOS/Linux 上建议用sudo或者给用户目录授权别硬改全局目录权限。npm 下载特别慢可以用你所在地区的 npm 镜像源npm config set registry一行搞定这里不展开。装完先别急着用因为接下来才是真正的分水岭你到底要怎么登录。1.3 离线安装和其他包管理器的替代方案如果你所在环境对 npm 不太友好Codex 也有压缩包形式的分发可以从官方仓库的 Release 页面下载对应平台的二进制解压后把可执行文件放进 PATH。macOS 用户也可以用 HomebrewLinux 用户如果有兴趣可以自己编译但说实话没必要——npm 和官方 Release 是两条最省事的路其余方案适合有特殊环境约束的人。这部分我就不铺开讲了记住一句话安装方式不影响后面的认证配置你在 Windows、macOS 还是 Linux 上遇到的问题99% 都出自认证环节。2. API Key 登录的三条路径选一条就能开始干活2.1 官方 OpenAI API Key最直接的正路如果你手里已经有 OpenAI 平台的 API Key直接用它就行。Codex 支持多种认证方式但既然是 API Key 登录核心就是在运行 Codex 时让程序拿到你的 key。最简单的做法是设置环境变量export OPENAI_API_KEYsk-proj-...然后运行codex。Codex 启动时会读取这个变量用它作为请求的凭证。这是最干净、最容易排查的方式——因为环境变量是进程级的你换终端就失效不会污染配置。去 OpenAI 平台创建 Key 时有几个细节提醒一下创建后一定要当场复制保存平台只显示一次注意 API Key 的权限范围如果只用来跑 Codex不建议把所有权限都放开另外留意一下余额和限流情况401 是认证问题403 和 429 则是权限和限流问题别混淆。这些看起来是小事但排查报错时它们会成为关键的区分依据。2.2 第三方 OpenAI 兼容网关DeepSeek、OpenRouter 这类怎么配2026 年这个时间点很多人不再只用一个模型提供方而是用 DeepSeek、OpenRouter、或者自建网关来统一管理多个上游模型。Codex 对 OpenAI 兼容接口的支持让这类方案成为可能。配置核心就两步改 base_url、换对应的 API Key。以 DeepSeek 为例你只需要在配置里指定export OPENAI_BASE_URLhttps://api.deepseek.com/v1 export OPENAI_API_KEYsk-...你自己的 DeepSeek key以 OpenRouter 为例export OPENAI_BASE_URLhttps://openrouter.ai/api/v1 export OPENAI_API_KEYsk-or-...注意这里没有魔法Codex 只是把请求发到你指定的 base_url剩下的认证完全取决于你给的 key 在那个平台是否有效。很多第三方网关的 401 都是因为 key 不对、key 对应的账号没有权限、或者 base_url 少了一段路径导致请求打到了错误的地方。2.3 配置文件直连不跑登录流程把凭证写进配置文件除了环境变量Codex 也支持把 API Key 写进配置文件。配置文件默认在~/.codex/config.toml结构大致是这样model gpt-5-codex [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 api_key sk-proj-...不同版本字段名会有差异但思路一致Codex 支持通过配置声明多个模型提供方每个提供方有自己的 base_url 和 api_key。用配置文件的好处是它全局生效不用每次开终端都 export 环境变量坏处是 key 明文躺在磁盘上而且一旦配置文件里写了 key环境变量可能不会覆盖它具体行为取决于版本这会成为后面 401 的一个隐藏来源。我个人的实践建议是优先用环境变量。Key 写在配置文件里出了 401你会多一个是不是配置文件和环境变量打架了的猜测写在环境变量里逻辑简单问题好定位。3. 拆解 401 报错热搜词里的那些报错原文到底在说什么3.1 api key is required in authorization header请求里根本没有 key这个报错的原文通常长这样{code:api_key_required,message:api key is required in authorization header}翻译过来就是服务端收到了你的请求但检查请求头时发现 Authorization 头不存在或者是空的。Codex 理论上会自动带上 Authorization 头为什么会出现这个常见原因是环境变量没配好——比如OPENAI_API_KEY没生效、key 是空字符串、或者你用的配置文件字段名写错了Codex 根本没读到 key。有个容易误导人的地方这个报错往往是在你以为已经配好 key的情况下出现的所以排查时先确认运行 Codex 的进程真的继承到了正确的环境变量。3.2 missing bearer or basic authentication认证格式不对这个报错也很典型unexpected status 401 unauthorized: missing bearer or basic authentication它的意思是Authorization 头是存在的但里面既不是 Bearer 格式也不是 Basic 格式。正常情况下 OpenAI 兼容接口要求的是Authorization: Bearer sk-xxx。为什么会出现既不是 Bearer 也不是 Basic多半是有人把 key 直接拼错了或者在某个中间环节比如你写的网关转发脚本把前缀吃了。还有一种情况是你在配置里给 key 加了引号引号被当成 key 的一部分传了上去。3.3 invalid_api_key 与 incorrect api key providedkey 本身无效OpenAI 风格的错误响应是{code:invalid_api_key,message:...}第三方网关则常见这种incorrect api key provided: asd3967281.。这两类报错说明服务端成功解析出了 key认证之后发现 key 无效。可能是 key 复制错了、key 被删了、key 过期了、或者 key 被平台标记了。看到incorrect api key provided后面跟着一长串明文时建议你顺手把终端日志里的 key 清理掉别留在剪贴板和历史记录里。3.4 网关层失败authentication fails, your api key: **** 与本地转发服务第三方网关的报错五花八门。常见的authentication fails, your api key: ****表示网关接收到了掩码后的 key但网关配置的上游凭证有问题。还有一类热搜词里的报错是cc switch local proxy failed while handling codex endpoint /responses.这里说的 local proxy 需要解释一下它指的是本机的 API 统一转发服务开发者经常用这类服务把 OpenAI、DeepSeek 等多个上游聚合成一个入口Codex 只连接这个本地入口。报错出现在处理/responses端点时通常意味着本地网关本身就没能认证成功上游而不是 Codex 的问题。排查时优先看网关后台配置的上游 key 是否还有效再看网关有没有把认证头正确传给上游。这类报错很容易让人误以为Codex 坏了实际上把网关端的上游 key 更新一下就好了。3.5 模型路由缺 keyno api key for provider route deepseek-official最后一种 401 变体虽然不是直接返回 401 状态码但也是热搜词里的高发问题llm-deepseek: no api key for provider route deepseek-official这类报错出现的前提是你的 Codex 配置里声明了多个模型提供方并且某个模型的路由指向了 DeepSeek但这个提供方没有配置 key。Codex 在执行请求前检查路由配置发现找不到对应 key直接把请求挡下来。解决办法是去配置文件里给对应的 provider route 补上 api_key或者把模型路由指到你实际配了 key 的那个提供方上。我把这些报错整理成一张表方便你对照着查报错特征根因方向优先排查项api_key_required请求头里没有 key环境变量是否正确继承missing bearer or basic authenticationAuthorization 格式不对Bearer 前缀是否完整、有无引号invalid_api_key/incorrect api key providedkey 本身无效key 是否正确、过期、被删authentication fails, your api key: ****网关上游凭证失败本地网关后台的上游 keylocal proxy failed while handling codex endpoint本地转发服务处理失败网关配置的上游认证no api key for provider route ...路由缺 key配置文件 provider 段是否补全4. 401 排查的完整链路按顺序做十分钟内定位4.1 第一步用 curl 直接打 API绕开 Codex遇到 401我强烈建议你先别折腾 Codex先用 curl 直接请求。这会把Codex 的锅和认证的锅彻底分开。比如你用的是官方 OpenAIcurl -s https://api.openai.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY用 DeepSeekcurl -s https://api.deepseek.com/v1/models \ -H Authorization: Bearer $OPENAI_API_KEY如果 curl 返回 200说明 key 本身没问题问题出在 Codex 进程读取 key 的方式上如果 curl 也返回 401那问题就清晰了key 或 base_url 至少有一个不对。这一步能把排查范围缩小一半。4.2 第二步核对 base_url 与 key 的匹配关系curl 通了之后再回头检查 Codex 的配置。两个字段必须匹配你访问的接口地址、你提供的 key。官方 key 配官方地址DeepSeek 的 key 配 DeepSeek 的地址OpenRouter 的 key 配 OpenRouter 的地址。三者乱配是最常见的 401 来源之一。还有一个容易踩的小细节base_url 的路径。有的平台要求填https://api.xxx.com/v1有的平台会自动兼容/v1和根路径但你别赌它能兼容。用各平台文档里明确给出的地址别顺手加个/chat/completions之类的完整接口路径到 base_url 里——那个是接口路径不是服务地址。4.3 第三步检查本地网关/转发服务的认证链路如果你用了统一接入网关不管是 one-api、new-api 还是 LiteLLM 这类Codex 请求的是http://localhost:端口之类的本地地址此时链路是Codex 到本地网关再由本地网关到上游平台。401 可能出现在两段Codex 到本地网关这一段的 key 不对检查 Codex 配置里填的 base_url 和 api_key 是否和本地网关创建的令牌匹配。本地网关到上游这一段的 key 失效去网关后台看上游渠道的 API Key很多网关会在上游 key 过期后直接抛 401而日志里显示的却是请求来自本地网关。4.4 第四步检查环境变量与配置文件是否互相覆盖这一步最容易忽略。很多人既在 config.toml 里写了 api_key又在 shell 里 export 了 OPENAI_API_KEY然后开始疯狂怀疑人生。Codex 读取配置的优先级在不同版本里不完全一样但冲突是客观存在的。建议做法只从一个地方注入 key。要么用环境变量要么用配置文件不要两个都设。unset OPENAI_API_KEY env | grep -i openai看看当前环境里还残留哪些相关变量把不需要的提前清掉再重新运行 Codex。4.5 最后一步用调试模式看真实响应新版 Codex CLI 支持调试模式运行的时候可以打开日志输出查看它实际发出的 HTTP 请求和响应。Codex 是 Rust 写的很多场景下用RUST_LOGdebug之类的环境变量就能打开日志具体开关以你安装版本的codex --help为准。看到实际请求头里 Authorization 的值是什么、服务端返回了什么就基本尘埃落定了。很多时候401 的真相就藏在你以为 Codex 会做的事和它实际没做的事之间。5. 配置文件里的隐蔽坑这些字段写错一样报 4015.1 base_url 的斜杠与尾路径https://api.deepseek.com/v1和https://api.deepseek.com/v1/看起来差不多但有些网关对路径拼接非常敏感。Codex 会按照它自己的规则在 base_url 后面拼接口路径如果你配置的 base_url 多了或少了/v1导致最终请求打到不存在的端点服务端有时会返回 404有时会因为无法正确识别而返回 401。我的习惯是严格按照平台文档给的示例填不要在末尾加斜杠也不要在后面多加路径。5.2 key 复制时混入空白字符和引号你可能觉得这是低级错误但我真见过不少次复制 key 时把前导或者结尾的换行、空格一起复制进去了。配置解析器可能不 trim于是实际发出的 key 是sk-xxx\n服务端一比对就 401。更隐蔽的是有人习惯在 toml 里给 key 加双引号但编辑器默认的引号是中文引号解析器读出来就是带着引号的 key。所以配置好之后至少用echo $OPENAI_API_KEY | wc -c之类的命令确认长度是否符合预期。5.3 多供应商并存时每个路由都要有自己的 key前面提到no api key for provider route这类错误。如果你的配置文件里声明了多个 provider要确保每个 provider 都配了对应的 api_key。Codex 在选模型时是按名找路由不会因为你其他地方有 key 就自动借用。最常见的场景是有人配了 DeepSeek 的路由却没有在路由下面写 key于是模型一运行就报 401 或缺 key。这个排查起来很简单打开配置文件逐段核对 provider 和 api_key 是否成对。5.4 版本升级后的登录态失效如果你以前用过codex login的浏览器登录方式后来切换成 API Key 方式需要留意旧的登录态缓存。热搜词里codex auth token is unavailable指的就是这类情况Codex 运行时想读取旧的 auth token发现它不可用于是走认证失败路径。此时不要只盯着 API Key 配没配还要看看登录态缓存是否过期、版本升级后配置项是否被迁移。干脆一点把旧的登录态缓存删掉重新走一遍 API Key 配置省得两边打架。5.5 何时该考虑环境变量而不是配置文件最后补充一个观点如果你要频繁切换模型提供方比如今天用官方、明天用第三方网关环境变量比配置文件更灵活。写一个小的脚本按项目分别声明不同的 OPENAI_API_KEY 和 OPENAI_BASE_URL运行 Codex 时带上既干净又不容易冲突。配置文件适合长期固定用一种平台的场景。至于团队协作建议把 key 放在共享的密钥管理里不要在仓库里提交含 key 的配置示例哪怕只是演示用的占位符也要养成习惯写成your-api-key。坦白说Codex 或者任何 AI 编程工具出现的 unexpected status 401 unauthorized九成以上都不是产品本身的 bug而是 key、base_url、环境变量、网关转发这四者之间某处出现了错位。我自己的排查习惯已经固定成一条流水线先 curl 证明 key 能用再看 base_url 是否匹配紧接着查环境变量和配置文件有没有互相覆盖最后才用调试模式看细节。按这个顺序走很少超过十分钟。还有一个值得养成的习惯任何包含 key 的终端日志、错误输出在发到论坛或者工单系统之前都先打码。搜索结果里那些incorrect api key provided: asd3967281.的原文其实都是别人简化或者打码过的版本。真实环境里服务端可能直接把 key 明文回显在日志里注意清理终端历史记录别让一个调试过程变成泄露事故。最后再分享一个小技巧如果你在配置完恨不得立刻跑一个 Hello World却总是 401试试先跑一次不带任何参数的codex --version确认 CLI 正常再跑一个极简的对话请求。这两个动作能把程序本身的问题和认证配置的问题分隔开。Codex 本身值得花时间研究别让认证问题浇灭你最初的热情。
