Codex 安装配置与 401 报错排查实战指南-育师

1. 为什么 2026 年还有人在折腾 Codex 的安装

Codex 这个工具从发布到现在，安装流程其实一直在变。2026 年 9 月这个时间点，官方把认证体系做了一次比较大的调整，以前那种直接填个 API Key 就能跑的日子已经过去了。现在你打开终端敲下codex命令，大概率会遇到的第一件事就是让你登录，而登录方式又分了好几种，选错了就是无穷无尽的 401 报错。

我前后在 Windows、macOS 和 Linux 三个平台上都装过 Codex，踩过的坑包括但不限于：auth.json写错字段导致认证失败、config.toml里多写了一个不认识的配置项被静默忽略、API Key 复制时带上了多余空格、以及最经典的unexpected status 401 unauthorized: incorrect api key provided。这些问题的根源其实就那么几个，但官方文档写得比较散，社区里的教程又大多是复制粘贴的，真正能解决问题的信息得自己一点点试出来。

这篇内容适合三类人：第一类是刚接触 Codex、连安装包在哪下都不太确定的新手；第二类是已经装上了但卡在登录或 401 报错上、反复重装也没用的朋友；第三类是想把 Codex 接到第三方模型服务（比如 DeepSeek、OpenRouter 这类）上、需要手动改配置的老手。我会把安装、认证、配置、排错这四个环节拆开讲，每个环节都给出我实际验证过的操作步骤和参数说明，你照着做基本能跑通。

需要提前说明的是，Codex 的版本迭代很快，我写这篇内容时用的是 2026 年 9 月前后的稳定版，如果你用的是更早或更晚的版本，个别字段名可能有差异，但整体思路是通用的。另外，所有涉及 API Key 的操作，我都建议你在本地环境做，不要把 Key 提交到任何公开仓库里，这个后面会细说。

2. 安装前的环境准备与版本选择

2.1 确认你的系统环境和依赖版本

Codex 的安装方式在不同系统上差别挺大。Windows 用户现在有两种选择：一种是走桌面版安装包，另一种是用命令行版本。桌面版的好处是图形界面友好，登录流程有引导，适合不想折腾配置文件的人；命令行版本更灵活，适合需要脚本化调用或者在远程服务器上用的场景。macOS 和 Linux 用户基本只有命令行版本这一条路，安装方式主要是通过包管理器或者直接下载二进制文件。

在动手之前，先确认几个基础依赖。Node.js 的版本建议在 20.x 以上，低于这个版本可能会在安装过程中报模块解析错误。Python 环境不是必须的，但如果你打算用某些插件或者做二次开发，建议装一个 3.10 以上的版本。另外，确保你的终端能正常访问外网，因为安装过程中需要拉取一些依赖包。

我遇到过一种情况：用户本地装了多个 Node 版本，npm和node指向的不是同一个版本，结果安装脚本跑一半就挂了。你可以用下面这两条命令确认一下：

node -v npm -v

如果两个版本号差距很大，建议先用nvm或者fnm把版本统一一下。Windows 用户如果用的是 PowerShell，注意执行策略可能会阻止脚本运行，需要先设置一下：

Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned

这个操作只是允许本地脚本执行，不会降低系统整体安全性，可以放心做。

2.2 安装包获取渠道与校验方法

Codex 的安装包获取渠道主要有两个：官方发布页面和包管理器。官方发布页面会提供各个平台的安装包和校验值，下载后建议核对一下哈希值，避免下载到被篡改的文件。包管理器方式更省事，但版本更新可能会有延迟。

Windows 桌面版的安装包是一个.exe文件，双击后按引导走就行。安装过程中会让你选择安装路径，默认路径在 C 盘用户目录下，如果你的 C 盘空间紧张，可以改到其他盘。安装完成后，桌面会生成一个快捷方式，开始菜单里也能找到。

命令行版本的安装，macOS 用户可以用 Homebrew：

brew install codex

Linux 用户如果用的是 Debian 系，可以下载.deb包后用dpkg安装；如果是其他发行版，建议直接下载二进制文件放到/usr/local/bin下，然后赋予执行权限：

chmod +x /usr/local/bin/codex

Windows 命令行版本可以通过 npm 全局安装：

npm install -g @codex/cli

安装完成后，在终端输入codex --version，如果能正常输出版本号，说明安装成功了。如果提示命令找不到，检查一下 npm 的全局 bin 目录是否在 PATH 里。

注意：不要从第三方站点下载所谓的“汉化版”或“破解版”安装包，这类包经常被植入额外脚本，轻则导致配置异常，重则泄露你的 API Key。官方渠道虽然下载速度可能慢一点，但安全性有保障。

3. API Key 登录与认证机制详解

3.1 API Key 的获取与格式识别

Codex 支持的登录方式主要有两种：一种是走官方账号的 OAuth 登录，另一种是直接用 API Key 认证。OAuth 登录适合个人用户，点几下就能完成；API Key 认证适合需要自动化或者接第三方服务的场景。

API Key 的获取路径在官方控制台的 API 管理页面，创建一个新的 Key 后，系统会显示一串以sk-开头的字符串。这里有个细节要注意：Key 只在创建时显示一次，关掉页面后就看不到了，所以创建后立刻复制保存。我见过不少人创建完 Key 后没复制，回头找不到又得重新建一个。

Key 的格式一般是sk-加上一长串字符，总长度在 40 到 60 个字符之间。复制的时候特别容易带上首尾空格，或者把换行符也复制进去，这两种情况都会导致认证失败。建议复制后先粘贴到一个纯文本编辑器里，确认没有多余字符再使用。

如果你打算用第三方模型服务，比如 DeepSeek 或者 OpenRouter，它们的 Key 格式可能不一样。OpenRouter 的 Key 也是sk-开头，但 DeepSeek 的 Key 格式可能是另一套规则。不管哪种，核心原则是一样的：Key 必须完整、准确、没有多余字符。

3.2 auth.json 文件的结构与写入方式

Codex 的认证信息默认存在auth.json文件里，这个文件的位置根据系统不同有所区别。Windows 下一般在C:\Users\你的用户名\.codex\auth.json，macOS 和 Linux 下在~/.codex/auth.json。如果这个文件不存在，Codex 在首次登录时会自动创建。

auth.json的结构比较简单，核心字段就几个：

{ "api_key": "sk-你的实际Key", "provider": "openai", "email": "你的邮箱" }

api_key字段填你获取到的 Key，provider字段表示你用哪家服务，默认是openai，如果你接的是第三方服务，这里要改成对应的标识。email字段是可选的，填不填都不影响认证，但填上后在某些管理界面里能看到关联信息。

写入这个文件时，最容易出问题的地方是 JSON 格式。少一个引号、多一个逗号、用了中文引号，都会导致解析失败。我建议用支持 JSON 语法高亮的编辑器来改这个文件，比如 VS Code 或者 Notepad++，改完后用在线 JSON 校验工具过一遍，确认格式没问题再保存。

还有一种情况是文件权限问题。Linux 和 macOS 下，如果auth.json的权限设置得太开放，Codex 可能会拒绝读取。稳妥的做法是把权限设成只有当前用户可读写：

chmod 600 ~/.codex/auth.json

Windows 下一般不存在这个问题，但如果你把文件放在了共享目录里，也可能遇到权限相关的报错。

3.3 登录流程中的常见卡点与绕行方案

OAuth 登录流程看起来简单，但实际用起来卡点不少。最常见的是浏览器回调失败，也就是你在浏览器里完成了授权，但终端这边没收到回调，一直卡在等待状态。这种情况通常是本地端口被占用或者防火墙拦截导致的。解决办法是换一个端口，或者临时关闭防火墙再试一次。

另一个常见问题是手机号验证。部分地区的账号在登录时会要求手机号验证，如果你没有绑定手机号，流程就走不下去。这种情况下只能改用 API Key 认证，绕过 OAuth 流程。

还有一种情况是登录后提示codex auth token is unavailable，意思是认证令牌没拿到。这通常是因为登录过程中网络中断，或者本地缓存了过期的令牌。解决办法是删掉auth.json文件重新登录，让 Codex 重新走一遍认证流程。

如果你在公司网络环境下，可能会遇到代理相关的报错，比如cc switch local proxy failed while handling codex endpoint /responses。这类报错说明本地代理配置和 Codex 的请求路径冲突了。你可以检查一下环境变量里的HTTP_PROXY和HTTPS_PROXY设置，如果不需要代理就清掉，如果需要就确保代理地址是正确的。

4. config.toml 配置文件的正确写法

4.1 核心配置项逐条解读

config.toml是 Codex 的主配置文件，位置和auth.json在同一目录下。这个文件控制着模型选择、请求参数、插件开关等核心行为。文件格式是 TOML，比 JSON 稍微宽松一点，但字段名和层级结构必须写对。

一个基础的配置大概长这样：

model = "gpt-5.6-sol" provider = "openai" temperature = 0.7 max_tokens = 4096 [mcp_servers] enabled = true

model字段指定用哪个模型，这个值必须和官方支持的模型列表对上，写错了会报model is not supported的错误。provider字段和auth.json里的对应，表示服务提供方。temperature控制输出的随机性，值越高越随机，值越低越确定，一般设在 0.5 到 0.8 之间比较合适。max_tokens限制单次请求的最大输出长度，设得太小会导致回答被截断，设得太大又可能浪费额度。

[mcp_servers]这一节是插件相关的配置，如果你不用插件，可以把这一整节删掉。如果留着但配置不对，Codex 会提示mcp_servers.node_repl.type is ignored这类警告，意思是某个字段没被识别。这种警告一般不影响使用，但看着烦，建议把不用的配置项清理掉。

4.2 第三方模型接入的配置方法

把 Codex 接到第三方模型服务上，是很多人关心的场景。以 DeepSeek 为例，你需要在config.toml里改几个地方：

model = "deepseek-chat" provider = "deepseek-official" base_url = "https://api.deepseek.com/v1" [providers.deepseek-official] api_key = "你的DeepSeek Key"

base_url字段指定第三方服务的接口地址，这个地址必须写对，写错了会报连接超时或者 404。provider字段的值要和[providers.xxx]这一节的名称对应上，否则会提示no api key for provider route。

OpenRouter 的配置类似，只是base_url和模型名称不一样：

model = "openrouter/auto" provider = "openrouter" base_url = "https://openrouter.ai/api/v1" [providers.openrouter] api_key = "你的OpenRouter Key"

这里有个坑要注意：不同第三方服务的模型名称规则不一样，有的用deepseek-chat，有的用deepseek/deepseek-chat，写错了会报模型不存在的错误。建议先去对应服务的文档里确认一下模型名称的准确写法。

4.3 配置校验与常见语法错误排查

config.toml的语法错误是导致启动失败的主要原因之一。TOML 对缩进不敏感，但对字段名的大小写和引号很敏感。比如model写成Model就识别不了，字符串值必须用双引号，不能用单引号。

如果你不确定配置写得对不对，可以用 Codex 自带的校验命令：

codex config validate

这个命令会检查配置文件里的语法错误和未知字段，并给出具体的行号和提示。如果提示unrecognized configuration setting，说明某个字段名写错了或者已经废弃了，需要对照官方文档改过来。

还有一种情况是配置文件编码问题。Windows 下用记事本保存的文件默认可能是 GBK 编码，而 Codex 期望的是 UTF-8。编码不对会导致中文注释变成乱码，严重时整个文件解析失败。解决办法是用 VS Code 或者 Notepad++ 把文件另存为 UTF-8 格式。

提示：改完config.toml后，建议重启一下 Codex 服务，让配置生效。有些配置项是启动时加载的，不重启不会生效。

5. 401 报错的分类排查与解决实录

5.1 incorrect api key provided 的三种成因

unexpected status 401 unauthorized: incorrect api key provided这个报错我见过太多次了，成因基本可以归为三类。

第一类是 Key 本身有问题。可能是 Key 已经过期、被撤销，或者复制的时候漏了字符。你可以去官方控制台确认一下 Key 的状态，如果显示已失效，就重新创建一个。复制的时候建议用“复制到剪贴板”按钮，不要手动选中复制，避免漏字符。

第二类是 Key 和 provider 不匹配。比如你用的是 OpenAI 的 Key，但provider字段写成了deepseek-official，认证自然过不了。检查一下auth.json和config.toml里的 provider 是否一致。

第三类是环境变量覆盖了配置文件。Codex 会优先读取环境变量里的OPENAI_API_KEY，如果这个变量存在但值是错的，就会覆盖掉auth.json里的正确 Key。你可以用下面这条命令检查一下：

echo $OPENAI_API_KEY

如果输出了值，而且和你的实际 Key 不一样，就把它清掉：

unset OPENAI_API_KEY

Windows 下用set OPENAI_API_KEY=来清除。

5.2 missing bearer or basic authentication 的触发条件

unexpected status 401 unauthorized: missing bearer or basic authentication这个报错的意思是请求里没带认证信息。触发条件通常是auth.json文件不存在，或者文件存在但内容为空。

先确认文件是否存在：

ls -la ~/.codex/auth.json

如果文件不存在，说明你还没完成登录，需要先走一遍登录流程。如果文件存在但大小为 0，说明写入失败了，可能是磁盘权限问题或者写入过程中断。删掉这个空文件重新登录一次。

还有一种情况是文件存在且内容正常，但 Codex 读的是另一个路径下的配置。比如你在 Windows 上用了 WSL，WSL 里的 Codex 读的是 Linux 用户目录下的配置，而不是 Windows 用户目录下的。这种情况下需要把配置文件复制到 WSL 对应的目录里。

5.3 第三方服务 401 与 invalid_api_key 的区分处理

接第三方服务时，401 报错的信息格式可能不一样。比如 OpenRouter 返回的是{"code":"invalid_api_key","message":"invalid api key"}，DeepSeek 返回的可能是authentication fails, your api key: ****。虽然都是 401，但处理方式有区别。

OpenRouter 的invalid_api_key通常是因为 Key 没有正确配置到[providers.openrouter]这一节里，或者 Key 本身在 OpenRouter 后台被禁用了。去 OpenRouter 的控制台确认一下 Key 的状态，然后检查配置文件里的字段名是否写对。

DeepSeek 的authentication fails多半是 Key 格式问题。DeepSeek 的 Key 有时候会带一些特殊字符，复制的时候容易出错。建议把 Key 粘贴到纯文本编辑器里，确认没有多余空格和换行，再写入配置文件。

如果第三方服务的接口地址变了，也会导致 401。比如服务商把api.deepseek.com改成了api.deepseek.ai，你还在用旧地址，请求就会被拒绝。这种情况去服务商的文档页面确认一下最新的接口地址。

5.4 排查速查表与避坑清单

为了让你在遇到 401 时能快速定位问题，我整理了一张速查表：

报错信息	可能原因	排查动作
incorrect api key provided	Key 错误或过期	重新创建 Key，检查环境变量
missing bearer or basic authentication	auth.json 缺失或为空	检查文件是否存在，重新登录
invalid_api_key	第三方 Key 配置错误	检查 provider 配置节和 Key 状态
authentication fails	Key 格式问题	检查 Key 是否有空格或换行
cc switch local proxy failed	代理配置冲突	检查 HTTP_PROXY 环境变量
model is not supported	模型名称写错	对照官方文档确认模型名

除了表格里的内容，还有几个避坑点值得单独说。第一，不要同时在auth.json和环境变量里设置 Key，容易冲突。第二，改完配置后一定要重启 Codex，不然改动静默不生效。第三，如果用了多个模型服务，确保每个服务的配置节名称不重复。第四，定期检查 Key 的有效期，有些服务的 Key 是有有效期的，过期了不会自动提醒。

6. 实操全流程复盘与经验沉淀

6.1 从零到跑通的完整操作记录

我把整个流程从头到尾走一遍，你可以对照着操作。第一步，确认系统环境，Node.js 版本在 20.x 以上，终端能正常访问外网。第二步，下载安装包，Windows 用桌面版，macOS 用 Homebrew，Linux 用二进制文件。第三步，安装完成后运行codex --version确认安装成功。

第四步，获取 API Key，去官方控制台创建，复制后粘贴到纯文本编辑器里确认没有多余字符。第五步，创建auth.json文件，填入 Key 和 provider 信息，用 JSON 校验工具确认格式正确。第六步，创建config.toml文件，填入模型名称和基础参数，如果接第三方服务就加上对应的 provider 配置节。

第七步，运行codex config validate检查配置，有错误就按提示改。第八步，启动 Codex，发一条测试消息，确认能正常收到回复。如果报 401，按上一节的速查表逐项排查。

整个流程走下来，顺利的话十分钟能搞定，遇到问题可能要折腾半小时到一小时。我建议第一次装的时候把每一步的输出都记下来，出问题了方便回溯。

6.2 配置备份与多环境同步技巧

Codex 的配置文件不大，但丢了很麻烦，尤其是 API Key 这种东西，重新创建又要走一遍流程。我习惯把auth.json和config.toml备份到一个安全的地方，比如加密的笔记软件或者私有的 Git 仓库。

如果你在多台机器上用 Codex，可以用软链接的方式同步配置。比如在 macOS 上，把配置文件放在 iCloud 目录下，然后在~/.codex/里创建软链接指向 iCloud 里的文件。这样改一处，所有机器都生效。

Windows 下可以用符号链接：

New-Item -ItemType SymbolicLink -Path "$env:USERPROFILE\.codex\config.toml" -Target "D:\configs\codex\config.toml"

不过要注意，软链接的方式在跨平台时可能会有路径分隔符的问题，Windows 用反斜杠，Linux 和 macOS 用正斜杠，写配置的时候要留意。

6.3 版本升级后的配置迁移注意事项

Codex 升级后，配置文件格式偶尔会有变化。比如某个字段被废弃了，或者新增了必填字段。升级后如果启动报错，先看报错信息里有没有提到具体的字段名，然后对照官方更新日志改。

我遇到过升级后mcp_servers这一节的字段名变了，旧配置里的type字段被改成了mode，不改就报unrecognized configuration setting。这种时候不要慌，把旧配置备份一份，然后按新格式改，改完用codex config validate验证一下。

如果升级后问题太多，可以考虑回退到上一个版本。包管理器安装的可以用版本号指定安装旧版，二进制文件安装的就重新下载旧版替换一下。不过回退只是临时方案，长期来看还是要跟上新版本的配置格式。