1. 为什么 2026 年还有人在折腾 Codex 的安装Codex 这个工具从发布到现在安装流程其实一直在变。2026 年 9 月这个时间点官方把认证体系做了一次比较大的调整以前那种直接填一个 API Key 就能跑起来的方式现在多了一层配置文件的校验逻辑。我身边不少朋友在升级之后都遇到了 401 报错有的是 Key 本身的问题有的是配置文件写错了位置还有的是环境变量和配置文件打架。这篇文章主要面向三类人第一类是刚接触 Codex、准备在 Windows 或 macOS 上从零安装的新手第二类是之前用过旧版本、升级后发现登录不上去的老用户第三类是已经在用 Codex 但偶尔被 401 报错卡住、想搞清楚背后原理的进阶用户。核心关键词会围绕Codex 安装、API Key 登录、config.toml 配置、auth.json 认证文件以及401 报错排查这几个点展开。我自己的环境是 Windows 11 加上 macOS 双平台都在用所以下面提到的路径和操作会覆盖这两个系统。如果你用的是 Linux大部分逻辑是相通的只是路径需要换成对应的家目录位置。整篇内容会从安装包获取开始一路讲到认证配置、常见报错排查最后给出一份可以直接抄的配置模板。2. Codex 安装前的环境准备与版本选择2.1 安装包从哪里获取比较稳妥Codex 的安装包来源主要有两个渠道官方发布页面和包管理器。官方发布页面提供的是独立安装包Windows 下是.exe或.msimacOS 下是.dmg或.pkg。包管理器渠道则是通过 npm 或者 Homebrew 来安装命令行版本。我个人的建议是如果你只是想在桌面端使用优先走官方安装包因为桌面版会自动处理一些依赖和路径问题。如果你需要在终端里频繁调用那就走包管理器。需要注意的是网上有一些第三方站点会提供所谓的“汉化版”或者“优化版”安装包这类包我强烈不建议使用因为你无法确认里面有没有被植入额外的逻辑。提示下载完成后务必核对安装包的哈希值。官方页面通常会提供 SHA256 校验码用系统自带的certutil或shasum命令比对一下确认文件没有被篡改。2.2 Windows 与 macOS 的安装差异Windows 下的安装相对直接双击安装包一路下一步即可。但有一个细节容易被忽略安装路径尽量不要包含中文或空格。我见过有人把 Codex 装在C:\用户\张三\我的软件\这样的路径下结果启动时读取配置文件失败报了一堆莫名其妙的错误。默认路径C:\Users\你的用户名\AppData\Local\Codex\是最稳妥的。macOS 下如果是通过 Homebrew 安装命令是brew install codex安装完成后二进制文件会放在/opt/homebrew/bin/或者/usr/local/bin/下。如果是通过.dmg安装拖拽到 Applications 文件夹即可。macOS 有一个坑是 Gatekeeper 拦截首次打开可能会提示“无法验证开发者”需要在“系统设置 - 隐私与安全性”里手动允许一次。2.3 安装完成后的首次启动检查安装完成后不要急着去配置 API Key。先做一次空启动看看程序本身能不能正常运行。在终端里输入codex --version如果能看到版本号输出说明二进制文件没问题。如果提示“command not found”那就是 PATH 环境变量没有配置好需要手动把安装目录加到 PATH 里。Windows 下检查 PATH 的方法是打开“系统属性 - 高级 - 环境变量”看看用户变量里的 Path 有没有包含 Codex 的安装目录。macOS 下则是检查~/.zshrc或~/.bash_profile里有没有对应的 export 语句。这一步看起来简单但我遇到过的安装问题里有将近三成都是 PATH 没配好导致的。3. API Key 的获取与登录方式拆解3.1 API Key 从哪里申请Codex 使用的 API Key 需要从对应的开发者平台获取。登录你的开发者账号后在 API Keys 管理页面点击“创建新密钥”系统会生成一串以sk-开头的字符串。这串字符只会显示一次关闭页面后就再也看不到了所以一定要当场复制保存到安全的地方。这里有一个常见的误区很多人以为 API Key 就是账号密码可以反复查看。实际上它更像是一把一次性发放的钥匙丢了就只能重新生成一把。我自己的做法是生成后立刻存到密码管理器里同时在本地留一份加密备份。另外要注意不要把 API Key 直接写在代码里提交到 Git 仓库这是最容易被泄露的方式。3.2 两种登录方式的取舍Codex 目前支持两种认证方式一种是直接使用 API Key另一种是通过账号授权登录。API Key 方式的优点是配置简单、不依赖浏览器适合在服务器或容器环境里使用。账号授权方式的优点是可以用组织级别的权限管理适合团队协作场景。我个人的选择是本地开发用 API Key因为切换方便团队共享环境用账号授权因为可以统一管理权限。如果你只是个人使用API Key 完全够用了。需要注意的是两种方式的配置文件格式不一样混用的时候容易出错后面会详细讲。3.3 环境变量与配置文件的优先级Codex 读取 API Key 的顺序是环境变量 配置文件 默认值。也就是说如果你在环境变量里设置了CODEX_API_KEY那么配置文件里写的 Key 就会被忽略。这个机制本身是合理的但很多人不知道导致改了配置文件发现不生效其实是环境变量在“捣乱”。排查这个问题的方法是在终端里输入echo $CODEX_API_KEYmacOS/Linux或echo %CODEX_API_KEY%Windows看看有没有输出。如果有输出说明环境变量已经设置了你需要决定是删掉环境变量还是更新它的值。我一般建议在开发机上统一用配置文件管理把环境变量清掉避免混淆。4. config.toml 与 auth.json 的配置细节4.1 config.toml 的核心字段说明config.toml是 Codex 的主配置文件通常放在用户目录下的.codex文件夹里。Windows 下的路径是C:\Users\你的用户名\.codex\config.tomlmacOS 下是~/.codex/config.toml。这个文件用的是 TOML 格式对缩进和引号比较敏感写错了会直接导致解析失败。核心字段包括model指定使用的模型名称、api_keyAPI 密钥、base_url接口地址以及mcp_servers扩展服务配置。其中model字段需要填写平台支持的模型标识符填错了会报“model is not supported”的错误。base_url一般不需要改除非你有自定义的接口地址。注意TOML 格式里字符串必须用双引号包裹不能用单引号。我见过有人从网上复制配置时带了中文引号结果一直报解析错误排查了半天才发现是引号的问题。4.2 auth.json 的作用与生成方式auth.json是认证信息的存储文件和config.toml放在同一个目录下。当你通过账号授权方式登录时Codex 会自动生成这个文件里面包含了访问令牌和刷新令牌。如果你用的是 API Key 方式这个文件可能不存在或者只包含一个简单的结构。这个文件的安全级别很高因为它里面的令牌可以直接访问你的账号。我建议把这个文件的权限设置为仅当前用户可读。Windows 下可以右键属性 - 安全 - 高级把其他用户的权限全部去掉。macOS 下用chmod 600 ~/.codex/auth.json即可。另外这个文件不要同步到云盘或者提交到版本控制里。4.3 配置文件写错后的典型表现配置文件写错的表现有很多种最常见的是启动时直接报错退出提示“unrecognized configuration setting”。这种一般是字段名拼错了比如把mcp_servers写成了mcp_server。还有一种情况是配置能加载但运行时行为不符合预期比如模型没生效、接口地址没切换这种一般是字段层级写错了。排查配置问题的一个技巧是先用一个最小化的配置文件测试确认基础功能正常后再逐步添加其他字段。这样能快速定位到是哪个字段出了问题。另外Codex 在启动时会输出配置加载的日志把日志级别调到 debug 可以看到详细的解析过程。5. 401 报错的完整排查路径5.1 401 报错的几种典型形态401 报错在 Codex 里有很多变体不同的错误信息指向不同的问题。我整理了一张对照表方便快速定位错误信息关键词可能原因排查方向incorrect api key providedAPI Key 本身无效或已过期重新生成 Keymissing bearer or basic authentication请求头里没有带认证信息检查配置文件和环境变量invalid_api_keyKey 格式正确但服务端不认确认 Key 所属平台是否匹配cc switch local proxy failed本地代理配置冲突检查代理设置auth token is unavailable令牌文件缺失或损坏重新登录生成 auth.json这张表是我在实际排查中总结出来的基本上覆盖了九成以上的 401 场景。下面会针对每一类展开讲具体的处理方法。5.2 API Key 无效的确认与替换当你看到incorrect api key provided时第一件事是确认 Key 有没有复制完整。API Key 通常比较长复制时容易漏掉末尾几个字符。我建议把 Key 粘贴到文本编辑器里检查一下长度和开头结尾是否符合预期。如果 Key 确认完整那就去开发者平台看看这个 Key 的状态。有些 Key 可能被设置了过期时间或者被手动禁用了。还有一种情况是 Key 所属的账号欠费了服务端会拒绝所有请求。确认没问题后重新生成一个新 Key 替换掉旧的然后重启 Codex。5.3 配置文件与环境变量冲突的处理missing bearer or basic authentication这个错误通常意味着 Codex 根本没有读到任何认证信息。可能的原因有三个配置文件路径不对、环境变量为空、或者配置文件格式错误导致解析失败。我的排查顺序是这样的先确认配置文件在正确的位置用ls ~/.codex/看看文件在不在然后检查文件内容确认api_key字段有值最后检查环境变量看看有没有设置空的CODEX_API_KEY。这三步走完基本能定位到问题所在。5.4 代理与网络层导致的 401有些 401 报错其实不是认证问题而是网络层的问题。比如你配置了本地代理但代理没有正确转发认证头服务端收到的请求里就没有认证信息。这种情况下错误信息里通常会带cc switch local proxy failed这样的关键词。处理方法是检查代理配置确认代理是否需要对特定域名放行。如果你不需要代理直接把代理关掉再试。另外有些企业网络会做 SSL 拦截导致证书验证失败也会表现为 401。这种情况下需要把企业证书导入到系统信任列表里。6. 常见问题速查与避坑经验6.1 配置文件加载失败的排查清单配置文件加载失败是最让人头疼的问题因为错误信息往往很模糊。我整理了一份排查清单按顺序检查基本能解决大部分问题确认文件路径正确Windows 下注意用户目录名有没有中文确认文件编码是 UTF-8不要用 GBK 或带 BOM 的 UTF-8确认 TOML 语法正确可以用在线 TOML 校验工具检查确认字段名没有拼写错误对照官方文档逐个核对确认没有重复的字段TOML 不允许同一个键出现两次这份清单里的第三条和第五条是最容易被忽略的。TOML 对语法要求比较严格多一个逗号或者少一个引号都会导致整个文件解析失败。6.2 模型不支持报错的应对方法the model is not supported when using codex这个错误说明你配置的模型名称不在支持列表里。Codex 支持的模型列表会不定期更新旧的名字可能被废弃了。解决方法是去官方文档查一下当前支持的模型名称然后更新config.toml里的model字段。需要注意的是不同平台支持的模型可能不一样。如果你用的是第三方接口需要确认那个接口支持哪些模型。我一般会在配置文件里保留一个注释掉的备用模型名主模型出问题时可以快速切换。6.3 登录状态丢失的恢复流程有时候 Codex 会突然提示登录失效需要重新认证。这种情况通常是auth.json里的令牌过期了。恢复流程很简单删除旧的auth.json然后重新执行登录命令。Codex 会引导你完成授权流程生成新的令牌文件。如果重新登录后还是提示失效那可能是系统时间不对。令牌验证依赖系统时间如果时间偏差太大服务端会拒绝令牌。检查一下系统时间是否自动同步Windows 下在“设置 - 时间和语言”里开启自动同步macOS 下在“系统设置 - 通用 - 日期与时间”里开启。6.4 我踩过的几个坑第一个坑是配置文件里的注释。TOML 支持用#写注释但有些编辑器会自动把注释格式化导致注释跑到不该在的位置。我有一次在api_key后面加了个注释结果编辑器把注释和值挤到了同一行解析就出错了。后来我养成了习惯注释单独占一行。第二个坑是路径里的波浪号。在配置文件里写路径时~不一定能被正确展开。我建议用绝对路径或者用环境变量来拼接。这个问题在 Windows 上尤其明显因为 Windows 根本不认~这个符号。第三个坑是多个配置文件共存。有些工具会在不同位置生成配置文件Codex 读取的是用户目录下的那个但你可能改的是安装目录下的那个。确认你改的是正确的文件可以用codex config path命令查看当前使用的配置文件路径。7. 一份可以直接抄的配置模板7.1 最小可用配置如果你只是想快速跑起来用下面这个最小配置就够了model gpt-5.6-sol api_key sk-你的实际密钥 base_url https://api.example.com/v1把api_key替换成你自己的 Keybase_url如果官方没有特殊要求可以删掉这一行。保存到~/.codex/config.toml然后重启 Codex 即可。7.2 带扩展服务的完整配置如果你需要用到 MCP 扩展服务可以参考下面这个更完整的模板model gpt-5.6-sol api_key sk-你的实际密钥 base_url https://api.example.com/v1 [mcp_servers.node_repl] type stdio command node args [repl.js]注意mcp_servers下面的字段层级type和command都是node_repl的子字段。写错了层级会导致配置被忽略启动时会提示unrecognized configuration setting。7.3 配置文件的备份与版本管理配置文件改多了容易乱我建议用 Git 来管理。在.codex目录下初始化一个仓库把config.toml加进去但千万不要把auth.json加进去。可以写一个.gitignore文件把auth.json排除掉。每次改配置前先提交一次改完测试通过后再提交一次。这样出问题的时候可以快速回滚到上一个可用版本。我自己的习惯是在提交信息里写清楚这次改了什么、为什么改方便以后回溯。8. 关于 Codex 使用的一些个人体会Codex 这个工具从安装到跑通说难不难说简单也不简单。难点主要在于配置文件的细节和认证流程的理解。我见过很多人卡在 401 报错上其实大部分情况下问题都很简单要么是 Key 复制错了要么是配置文件位置不对要么是环境变量在捣乱。我的建议是遇到问题不要慌按照“先确认基础环境、再检查认证信息、最后排查网络层”的顺序来。大部分问题在前两步就能解决。另外养成看日志的习惯Codex 的日志里其实写得很清楚只是很多人不看。最后分享一个小技巧如果你在多个设备上使用 Codex可以把配置文件放在云盘同步目录里然后用符号链接指向.codex目录。这样改一次配置所有设备都能生效。但记得auth.json不要同步每台设备单独登录。