折腾 Codex 配置绝对是最近命令行玩家们最统一的痛点光看那一串报错就让人头皮发麻config.toml 加载失败、环境变量不生效、Windows 安装到一半卡住、刚打开会话就提示 cant load config.toml so this thread cant resume……说实话Codex 本身真不难装难的是大部分人把顺序搞反了——还没装完就开始改配置配置没写好就去设环境变量结果每个环节都在互相甩锅。这篇我按自己实际跑通的经验把“先安装、再按顺序创建 config.toml 和环境变量”这条完整链路拆开讲顺便把最近高频出现的几个报错invalid type: string live expected a boolean、cc switch local proxy failed、Windows 安装未完成之类逐个拆解。适合刚接触 Codex、或者已经被配置折磨到想卸载的朋友照着顺序做一遍大概率能省下大半天排查时间。1. 先搞懂 Codex 的启动链路才能看懂为什么报错1.1 Codex 启动时到底要读哪些东西Codex 看起来就是个终端程序但它启动时依赖的东西其实有三层可执行文件本身、config.toml 配置文件、以及当前终端会话里的环境变量。很多人以为只要 npm 装完了就能直接跑实际上 Codex 启动时会先去找~/.codex/config.toml这个文件把里面的模型、服务商、鉴权方式全部解析出来再从环境变量里取对应的 API Key最后才能向模型接口发请求。这个流程不是可选的是硬性的。config.toml 如果解析失败整个程序直接罢工config.toml 解析成功但环境变量没配又会在请求阶段报鉴权错误。很多人遇到的情况是装好了config.toml 也写了但一运行就报错最后发现环境变量根本没设置或者设置完没开新终端导致根本没生效。所以第一步不是急着配这配那而是先理解 Codex 的启动顺序读取 config.toml → 解析模型与服务商 → 读取环境变量里的密钥 → 发起网络请求。这个顺序决定了后面每一步的先后关系也决定了报错时该往哪个方向排查。1.2 配置、环境变量、网络三者的依赖顺序这三者的依赖关系可以用一句话概括config.toml 决定“连谁”环境变量决定“用什么身份连”网络决定“能不能连上”。config.toml 里写的model_provider决定了 Codex 去找哪个服务商配置model决定了用哪个模型名env_key决定了去读哪个环境变量来取密钥。也就是说环境变量必须在 config.toml 里被“引用”才有意义反过来config.toml 里引用了环境变量但环境变量不存在启动后必然报错。网络这一层最容易被忽略。Codex 最终要发起 HTTP 请求到模型服务商的 API 地址如果系统里有代理环境变量指向一个不存在的本地代理或者 base_url 写错了就会在请求阶段冒出莫名其妙的长报错比如最近很多人遇到的 cc switch local proxy failed while handling codex endpoint /responses。这个我后面会专门讲。我把三者关系整理成一张表方便你对照排查环节作用出错时的典型表现config.toml决定连哪个服务商、哪个模型、读哪个环境变量error loading config.toml启动即退出环境变量提供 API Key 等身份凭据401、403、auth token missing网络与端点让请求真正到达模型接口proxy failed、timeout、connection refused1.3 一个“顺序错了”引发的连环报错案例我之前帮朋友排查过一次他的情况特别典型。他先照着网上教程把 config.toml 写好了里面配了自定义服务商env_key 指向MY_API_KEY然后他在系统环境变量里也设置了MY_API_KEY但运行 codex 还是报 401。排查了一圈才发现问题他是在设置环境变量之前打开终端的设置完直接在当前窗口里运行 codex。环境变量是在终端启动时加载进会话的已经打开的窗口根本读不到新设置的值。这就是典型的“顺序错误”——不是配置错而是环境的时序错。还有一次更离谱他把 API Key 直接写在了 config.toml 的 env_key 字段里比如env_key sk-xxxx。env_key 字段要的是环境变量的名字不是密钥本身这么写 Codex 会去读一个叫sk-xxxx的环境变量自然是空的然后报鉴权失败。这种问题不看文档根本想不到属于典型的“概念错位”。所以我才反复强调顺序先把程序装好再创建配置文件再设置环境变量最后启动测试。每一步都验证通过再进入下一步基本能避开九成以上的配置报错。2. 先把 Codex 装好安装步骤与 Windows 卡住的解法2.1 安装前先检查 Node.js 环境Codex 官方推荐通过 npm 全局安装所以前提条件是你的机器上有 Node.js 和 npm。别小看这一步我见过好几个人卡在安装报错上最后发现是 Node.js 版本太老。Codex 对 Node.js 版本有最低要求老版本 Node 跑 npm install 时经常报奇怪的语法错误或者引擎不兼容。先打开终端分别执行下面两条命令确认版本node -v npm -v如果你看到 Node 版本是 16 甚至更低强烈建议先升级到 LTS 版本再继续。Windows 用户直接去官网下载 LTS 安装包覆盖安装即可Linux 用户可以用系统自带的包管理器装新版macOS 用户如果之前是 brew 安装的直接brew upgrade node。版本确认没问题后再确认 npm 本身能正常工作。很多时候 Windows 上安装未完成根源是 npm 缓存损坏或者网络中断而不是 Codex 本身的问题。2.2 npm 安装 Codex 的标准姿势环境没问题后安装本身只有一条命令npm install -g openai/codex注意包名是openai/codex不是codex。如果你之前装过旧版本或者装错包先执行npm uninstall -g codex openai/codex清理干净再重装。macOS 和 Linux 用户如果遇到权限报错 EACCES说明当前用户对全局 node_modules 目录没有写权限。这种情况下不建议直接 sudo 硬装容易把权限搞乱更稳妥的办法是把 npm 的全局目录改成用户目录下的位置具体做法官方文档有详细说明核心就是给 npm 指定一个当前用户有权限的 prefix。Windows 用户建议用管理员身份打开 PowerShell 再执行安装命令能避免不少因为目录权限导致的“安装未完成”问题。2.3 Windows 安装未完成的常见原因最近搜“codex windows 安装未完成”的人特别多我复盘了一下基本逃不出下面几个原因第一网络中断导致 npm 下载一半就断掉。npm 安装过程中如果网络不稳定会出现一堆莫名其妙的错误看起来像安装失败其实就是包没下全。解决方法是先清理缓存再重试npm cache clean --force npm install -g openai/codex如果网络确实很差可以考虑把 npm 镜像源切到国内镜像命令是npm config set registry https://registry.npmmirror.com装完再换回去也行。这是常规操作跟代理、绕过之类的事情无关纯粹是加速下载。第二杀毒软件拦截。Windows Defender 或者其他安全软件有时候会拦截 npm 写入全局目录的动作导致安装“看起来成功了但 codex.exe 没生成”。遇到这种情况暂时关闭实时防护再安装装完再开回来即可。第三PATH 没生效。安装其实成功了但你在同一个终端窗口里执行codex --version提示找不到命令这是因为 npm 全局目录没有加入 PATH或者加入后当前窗口没重新加载。关掉终端重新开一个或者直接新开 PowerShell 再试通常就能解决。2.4 装完先验证别急着写配置安装完成后先别急着创建 config.toml先跑一个最简单的验证codex --version能正常输出版本号说明安装这一环已经通了。如果这一步就报错后面配再多都是白搭。我见过有人 config.toml 改了十几次结果问题根本不在配置而是 codex 命令压根没装上。验证通过后还要确认一下默认配置目录是否生成了。首次运行 codex 时程序通常会自动创建~/.codex目录。如果没生成手动创建也可以这个目录就是 config.toml 和大本营后面所有配置都在这里。另外提一句codex 支持两种登录方式一种是用 ChatGPT 账号执行codex login另一种是用 API Key 配合环境变量。我个人更推荐 API Key 方式流程简单可控出问题也好排查。如果你是彻底的新手建议先走 API Key 这条线。3. config.toml按顺序创建先跑通最小配置3.1 配置文件放在哪里Windows / macOS / Linuxconfig.toml 的固定位置是用户主目录下的.codex文件夹里文件名必须叫config.toml大小写和拼写都不能错。各平台的完整路径如下macOS/Users/你的用户名/.codex/config.tomlLinux/home/你的用户名/.codex/config.tomlWindowsC:\Users\你的用户名\.codex\config.tomlWindows 下在 PowerShell 里可以直接用$env:USERPROFILE\.codex\config.toml这个写法在 cmd 里用%USERPROFILE%\.codex\config.toml。如果.codex目录不存在手动创建一下。macOS/Linux 执行mkdir -p ~/.codexWindows PowerShell 执行New-Item -ItemType Directory -Force $env:USERPROFILE\.codex创建文件时强烈建议别用 Windows 自带的“记事本”老版本去新建再另存有些场景下会带上 BOM 头导致 TOML 解析器第一行就报错。用 VS Code、Sublime、Notepad 这类编辑器保存时明确选择 UTF-8 无 BOM 编码。3.2 最小可用配置模板很多人一上来就照着网上的“豪华配置”抄里面塞满了各种自定义 provider、实验性开关结果哪个字段名拼错都不知道。我的建议是先写一个最小配置跑通了再逐步扩展。打开 config.toml写入model gpt-5-codex model_provider openai就这两行先保存退出。然后确保环境变量里有OPENAI_API_KEY这一步在第四章详细讲再执行codex exec 用一句话介绍你自己如果 Codex 正常返回内容说明最基础的链路已经打通config.toml 解析成功、环境变量读取成功、网络请求成功。这时候你再往配置里加自定义服务商就有了一个可回退的“健康基线”。提示model 字段的值以你账号实际可用的模型名为准不同时期 Codex 默认模型会变化。如果填了不存在的模型名启动时不一定报错但请求阶段会提示 model not found 或返回 404那是模型名问题不是配置文件语法问题。3.3 接入自定义模型服务商DeepSeek 示例Codex 开源后支持通过 OpenAI 兼容接口接入其他模型服务商这也是最近“codex 接入 deepseek”热度很高的原因。配置文件里用[model_providers.xxx]这种表格语法来定义一个服务商然后在顶层把model_provider指向它。以 DeepSeek 为例完整的配置长这样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逐项拆解一下name服务商的显示名称随便起不影响请求。base_urlAPI 根地址Codex 会在它后面拼接具体的接口路径。这里只写 API 根地址不要写完整的/chat/completions路径否则会拼出重复路径导致 404。env_key指向环境变量的名字。Codex 启动时会去读名为DEEPSEEK_API_KEY的环境变量拿它的值作为鉴权密钥。wire_api接口协议类型。填chat表示走 Chat Completions 协议大多数 OpenAI 兼容服务商都支持填responses表示走 Responses 协议目前主要是 OpenAI 官方接口在用。设置好之后再配置环境变量DEEPSEEK_API_KEY重启终端执行codex exec 你好测试。如果通了说明自定义服务商接得没问题。3.4 TOML 类型陷阱为什么“照着抄”也会报错config.toml 是 TOML 格式TOML 是强类型格式布尔值就是true或false字符串必须加双引号数字就是数字。很多人照着教程抄把布尔值写成了带引号的字符串或者把字符串写成了裸词解析器一看类型不匹配整个文件加载失败报错还非常抽象。比如最近高频出现的error loading config.toml: invalid type: string live, expected a boolean十有八九就是把某个布尔字段填成了一个字符串。我见过有人这么写[model_providers.custom] name Custom base_url https://api.example.com/v1 env_key MY_API_KEY requires_openai_auth liverequires_openai_auth这个字段需要的值是true或false结果填了带引号的liveTOML 解析器立刻报类型错误。很可能本意是想设别的字段结果值粘到了布尔字段上这种错很难一眼看出来因为人眼会下意识忽略“类型”这个东西。排查这种问题最有效的办法是“二分注释法”把 config.toml 里一半的内容用#注释掉重新运行如果还报错就注释另一半直到锁定出问题的那一行。另外也可以把文件内容复制到任意一个 TOML 在线校验工具里检查语法能快速定位到具体行号和列号比自己眯着眼数行高效得多。这里把最容易踩的类型错误整理成一张表错误写法正确写法说明requires_openai_auth truerequires_openai_auth true布尔值不能加引号wire_api chatwire_api chat字符串必须加引号model gpt-5-codexmodel gpt-5-codex字符串必须加引号env_key sk-xxxenv_key MY_API_KEYenv_key 填环境变量名不是密钥本身最后提醒一句每次改完 config.toml不需要重新安装 Codex但需要把正在运行的 codex 进程退出重开它只在启动时读取一次配置文件。4. 环境变量设置顺序决定成败4.1 API Key 为什么不能写进 config.toml很多新手会问既然 config.toml 都要配置了为什么不直接把 API Key 写在里面一了百了答案是 Codex 的设计根本不支持而且也不应该支持。config.toml 里的env_key字段用来指定环境变量的名字意思就是“密钥你自己去环境变量里找别往配置文件里塞”。这样做的好处有三点第一config.toml 经常会被分享、存档、甚至提交到代码仓库如果里面写了明文密钥等于裸奔第二环境变量可以在不同终端、不同项目里灵活切换不用反复改文件第三密钥轮换时只需要改环境变量不用动配置。所以标准做法是在 config.toml 里用env_key声明“我要读哪个环境变量”然后到系统里把这个环境变量设置好。OpenAI 官方接口的核心环境变量是OPENAI_API_KEY如果是自定义服务商环境变量名就对应你在 config.toml 里写的env_key值。比如上文的 DeepSeek 例子就是DEEPSEEK_API_KEY。4.2 Linux / macOS / Windows 环境变量设置方法macOS 和 Linux 的设置在原理上完全一样都是往 shell 配置文件里追加 export 语句。bash 用户编辑~/.bashrczsh 用户编辑~/.zshrcecho export OPENAI_API_KEYsk-你的密钥 ~/.bashrc source ~/.bashrcsource的目的是让当前终端立即加载新配置省得重开。如果之后新开终端发现变量还在说明写对地方了如果新开终端变量丢了说明你很可能写错文件了zsh 用户写到了.bashrc或者反过来。Windows 下最常用的是setx命令setx OPENAI_API_KEY sk-你的密钥在 cmd 里也一样setx OPENAI_API_KEY sk-你的密钥注意setx 设置的是用户级环境变量但已经打开的终端窗口不会自动加载必须关闭终端重新打开变量才会进入当前会话。这一步无数人踩坑设置完发现没生效其实是没重开窗口。如果你不太习惯命令行也可以走图形界面右键“此电脑”→ 属性 → 高级系统设置 → 环境变量在用户变量里新建OPENAI_API_KEY值填密钥确定保存后重开终端。4.3 环境变量生效后的验证与冒烟测试设置完环境变量第一件事是验证它真的被终端读到了而不是直接去跑 Codex。macOS/Linux 执行echo $OPENAI_API_KEYWindows PowerShell 执行echo $env:OPENAI_API_KEYWindows cmd 执行echo %OPENAI_API_KEY%如果输出的是你设置的密钥说明环境变量已经生效。如果输出为空重开终端再看一次。确认环境变量没问题后再执行一次冒烟测试codex exec 你好正常返回就说明整条链路通了。这里强调一下这条命令是排错利器它短平快不进入交互模式配置有任何问题都会直接抛出来比开一个交互会话去试要干净得多。5. 高频报错排查实录照着这个顺序抄作业5.1 invalid type: string live, expected a boolean这个报错最近出现频率极高完整信息差不多是error loading config.toml: invalid type: string live, expected a boolean。它的本质就是 config.toml 里某个字段的类型不对TOML 解析器期望一个布尔值true/false结果你给了一个字符串。我在 3.4 里已经讲过这个问题的来龙去脉这里给一个标准排查顺序第一步打开 config.toml先看最外层有没有奇怪的裸词。有些人复制教程时会把模型名或者别的值粘到布尔位置上肉眼不一定看得出。第二步把疑似有问题的 provider 表格整体注释掉重新运行看报错是否消失。如果消失问题就在这个表格里。第三步在表格里二分注释字段一路缩小范围。锁定字段后检查它的值是不是被加了引号以及字段本身是不是需要布尔值。最后改完保存重启 codex 再测。这类错误不会因为多运行几次自己消失必须手动修正文件内容。5.2 ChatGPT 提示 cant load config.toml对话无法继续这个报错的完整文本是chatgpt cant load config.toml, so this thread cant resume. fix config.toml意思是 Codex 在恢复某个会话线程时发现 config.toml 加载失败于是拒绝继续。出现这个问题的前提通常是配置之前是好的后来改了 config.toml 引入语法错误或字段缺失然后你又回头尝试恢复旧会话就撞上了这个报错。它本质上和 5.1 是同一类问题只是触发场景不同。处理思路是先恢复可用状态再慢慢修配置。最简单的办法是把当前的 config.toml 备份并移走mv ~/.codex/config.toml ~/.codex/config.toml.bak没有配置文件的情况下Codex 会用内置默认配置尝试启动。如果能正常跑说明确实是自定义配置写坏了。这时再用最小配置重建 config.toml逐步添加功能而不是一次性把原来的复杂配置恢复回去。另外提一句如果文件里有中文字符且编码不对也可能导致解析失败。确保 config.toml 是 UTF-8 无 BOM 编码这一点在 Windows 上尤其重要。5.3 cc switch local proxy failed 网络端点报错这个报错最近也很多人问完整信息大概长这样cc switch local proxy failed while handling codex endpoint /responses。它定位的层面不是配置语法而是网络请求阶段。出现这个报错首先要明确一个事实Codex 要访问模型服务商的 API 端点可能是/responses也可能是/chat/completions如果请求发不出去就会在端点处理阶段抛出各种奇怪的网络层错误。常见原因有三个。第一环境变量里设置了 HTTP_PROXY / HTTPS_PROXY指向一个本地代理地址但那个代理服务根本没在运行。Codex 会遵循这些代理变量代理连不上就直接报 proxy failed。解决方法很简单先确认自己是不是真的需要代理不需要就清掉这两个变量再测试。macOS/Linux 执行unset HTTP_PROXY HTTPS_PROXYWindows PowerShell 执行Remove-Item Env:HTTP_PROXY, Env:HTTPS_PROXY。第二config.toml 里的 base_url 写错了。比如有些人会把https://api.deepseek.com/v1写成https://api.deepseek.com/v1/chat/completionsCodex 拿到这个地址再拼一次路径就拼出了一个根本不存在的端点请求自然失败。正确的写法是只写 API 根地址不要带具体接口路径。第三你所在网络的防火墙或安全策略拦截了请求。这种情况一般发生在公司网络环境表现为同样的配置在家能跑、在公司就报错。解决方法属于网络策略层面建议先确认目标 API 站点能不能通过常规方式访问到。排查这个报错的快速命令是先测端点通不通curl https://api.deepseek.com/v1/models能正常返回 JSON说明网络路径没问题问题大概率在代理变量或 base_url 拼写上回去逐个排查即可。5.4 高频报错速查表把这段时间高频出现的问题整理成速查表方便你直接定位报错信息可能原因解决方向error loading config.toml: invalid type: string live, expected a booleanTOML 字段类型错误检查布尔值是否加了引号用二分注释法定位cant load config.toml, so this thread cant resume配置文件解析失败或字段缺失备份并移走配置重建最小配置cc switch local proxy failed while handling endpoint代理变量指向不可用代理或 base_url 写错清理代理变量修正 base_urlcommand not found: codex安装未完成或 PATH 未生效重开终端检查 npm 全局目录是否在 PATH401 Unauthorized / auth token missing环境变量没设或设错名字确认 env_key 与真实环境变量一致echo 验证model not found / 404模型名不存在或服务商不支持该模型换成账号可用模型名确认服务商能力这张表覆盖了绝大多数“配置总报错”的场景。还有一条万能兜底如果实在排查不出来把~/.codex目录整个改名备份比如改成~/.codex_backup然后重新创建配置从头来一遍。这个方法看起来粗暴但效率惊人能绕开所有历史包袱。6. 我踩过坑后的配置心得与最终建议6.1 从零到跑通的完整操作顺序如果你现在已经被报错折腾得没脾气了干脆全部推倒重来严格按下面的顺序走一遍第一步确认 Node.js 版本npm 全局安装openai/codex执行codex --version确认装好。第二步创建~/.codex/config.toml写入最小配置model 你的模型名和model_provider openai。第三步设置环境变量OPENAI_API_KEY重开终端用echo $OPENAI_API_KEY确认生效。第四步执行codex exec 你好跑通基础链路。第五步确认没问题后再往 config.toml 里加自定义 provider或者调整其他参数。每加一个配置项就跑一次codex exec冒烟测试确认没有引入新问题。这套流程看起来慢实际上是最快的。每一次改动都建立在“当前状态完全正常”的基础上出问题能立刻定位到刚改的那一行而不是在几十行配置里大海捞针。6.2 日常维护与备份建议配置一旦调通第一个动作就是备份。把 config.toml 复制一份存好比如cp ~/.codex/config.toml ~/.codex/config.toml.bak。后面再改配置也保留这个习惯改出一版能用的就备份一版折腾坏了一秒钟回滚。还有两个我个人的习惯分享给同路人。一是千万不要在 config.toml 里写任何真实的密钥所有密钥都走环境变量而且环境变量设置完一定要先 echo 验证再跑 Codex省得你以为配好了其实没生效。二是平时多熟悉codex exec这个非交互命令它是所有配置和连接问题的最佳试金石一条命令就能判断配置到底通没通比反复开关交互式会话高效太多。配置这件事说白了就是三板斧装对、按顺序配、学会看报错。Codex 本身的逻辑并不复杂绝大多数问题都出在安装没完成就开始配、配置和实际环境对不上、以及改完配置不重启这三件套上。按照这篇文章的顺序走一遍你应该也能顺利跑通自己的 Codex 环境。