Codex CLI装好之后我第一周的体验其实是能用但处处别扭。模型总要用参数临时指定审批策略该拦的不拦、不该拦的拦得特别勤换到Windows目录环境下又开始报错最让人头大的是那个unable to locate the codex CLI binary搜索半天都得不到一个像样的排查思路。后来花了一个周末把Codex CLI的配置体系从文件位置、认证方式、模型参数到环境变量、报错日志完整捋了一遍才摸清楚它整个配置机制。这篇Codex CLI教程的第二篇配置指南就是把这段时间沉淀下来的东西做一个完整的整理。如果你也是刚装完Codex CLI正在纠结为什么我的环境这么难用为什么老是报错这篇应该能帮你省不少事。1. 为什么单独把配置拎出来写一篇很多工具的安装教程止步于装好能跑但Codex CLI这种工具装好和用好之间还差着一大截配置工作。默认配置下它确实能启动、能对话、能帮你改代码但用几天你就会发现几个很现实的问题一是模型写死了一种想切换得反复敲参数很烦二是审批策略太保守或太激进要么每步都打断你要么在你没准备好的时候悄悄执行了命令三是换一台机器、换一个终端环境又不一样了特别是Windows下经常出现明明安装了、却提示找不到命令的情况。所以这篇配置指南我打算把配置拆成几个层面来讲配置文件在哪儿、认证怎么做、核心参数怎么设、环境变量怎么配合最后再单独用一整节排查unable to locate the codex CLI binary这个高频报错。配置文章最容易写成官方文档翻译我想尽量避免这个毛病多讲一些我实际踩过、验证过的经验。还有一个容易被忽略的点Codex CLI的配置项不是一层不变的。它更新频率很高新版本可能调整字段名、新增provider、改变优先级逻辑。所以这篇不会把每个字段罗列得面面俱到而是帮你建立一套配置思维——知道什么东西应该去哪里配、遇到问题往哪个方向查。这个框架建立起来之后就算官方文档变了你也能跟得上。1.1 配置体系的四个层次Codex CLI的配置体系可以分成四个层次理解这四个层次后续所有问题都好办了。第一个层次是配置文件本身也就是全局目录下的config.toml这是最核心的入口模型、策略、输出格式、自定义指令都从这里读。第二个层次是认证信息账号登录后生成的token或者你填写的API Key它不放在config.toml里而是单独放在auth.json这类文件中避免权限滥用和误分享。第三个层次是环境变量它可以在进程启动时覆盖或者补充配置文件里的项常用于密钥注入、CI/CD场景。第四个层次是运行时参数也就是你在终端里执行codex命令时附加的参数它的优先级通常最高。这四个层次其实对应了不同的使用场景普通交互用配置文件敏感信息走环境变量或认证文件临时需求用命令行参数。理清这个优先级关系之后很多为什么我改了配置没生效的问题都能自己找到答案。1.2 这篇指南的讲解思路与使用建议后面的篇幅我会按文件位置 → 认证 → 核心参数 → 环境变量 → 报错排查 → 综合示例的顺序展开。你拿到这篇指南之后有两种读法如果Codex CLI已经能跑只是想优化体验可以按顺序通读把配置项一个个过一遍如果正被某个报错卡住比如Windows下找不到codex命令可以直接跳到第6节按照排查链路走一遍往往能解决问题。我个人的建议是不管哪种读法手里最好准备一个能开终端的环境边看边验证。配置这东西光看不练过两天就忘了而且不同版本之间细节差异很大只有自己跑一遍确认过的配置才真正算数。2. 配置文件的存放位置与加载逻辑2.1 全局配置目录和config.tomlCodex CLI沿用了很经典的Unix工具风格把用户级配置放在用户主目录下的一个点开头文件夹里。macOS / Linux~/.codex/Windows%USERPROFILE%.codex\这里面最核心的是config.tomlTOML格式简单直观用编辑器打开就能改。它管的事情包括默认模型、模型供应商、审批策略、自定义提示词、终端输出行为、日志级别等。需要注意Codex CLI通常是启动时一次性读取配置改了文件之后已经打开的会话不会立刻感知稳妥的做法是重开一个终端会话或者重启Codex CLI。我在Windows上第一次找这个目录时还愣了一下因为资源管理器默认不显示隐藏文件夹。直接在地址栏输入%USERPROFILE%.codex就能跳进去。如果你也使用Windows系统这个细节可以少走点弯路。2.2 登录信息为什么单独存放在.codex目录下你还会看到auth.json这样的认证文件。我刚开始不理解为什么要拆成两个文件后来想明白了config.toml往往是你愿意分享给同事、放进dotfiles仓库管理的配置而auth.json里面是真实凭据是绝对不能泄露的。拆开存放你的配置可以公开密钥却不需要跟着暴露。这也带来一个安全习惯如果你把配置目录纳入Git仓库统管一定要在.gitignore里把auth.json排除掉。我自己吃过一次亏——把整个.codex目录丢进自己的dotfiles仓库差点把API Key一起传上去。好在推送到远程之前发现了但那次之后我把dotfiles仓库的过滤规则单独检查了一遍。这个提醒希望你先看到。2.3 配置加载的顺序和版本差异Codex CLI加载配置时大体逻辑是先读config.toml里的默认值再用环境变量做覆盖最后用命令行参数覆盖。这是很多CLI工具的通用约定Codex CLI也没有跳出这个框架。不过具体到每个字段是否支持环境变量覆盖要去看当前版本的帮助文档不同项目的实现深度不一样。所以如果你改了config.toml但没生效排查顺序应该是先确认是否改对文件——是用户目录那个而不是安装目录里的内置配置再确认是否有环境变量抢先覆盖了它最后看命令行参数有没有设置。这个思路适用于绝大多数配置问题。3. 认证配置让Codex CLI真正跑起来的前提Codex CLI不像普通编辑器那样装好就能用它需要连接模型服务而这一步绕不开认证。认证有两种主流方式一种是ChatGPT账号登录走OAuth流程另一种是直接提供API Key。这两种方式的适用场景很不一样下面分开说。3.1 ChatGPT账号登录适合个人交互使用在终端里执行codex login它会打开一个浏览器页面让你用ChatGPT账号授权。授权成功后Codex CLI会拿到访问凭据并保存到auth.json文件中之后在终端敲codex就能直接工作。这种方式的好处是没有额外的API费用逻辑用的是你账号的额度对普通个人用户来说最省事。坏处是它绑定了一个交互式授权流程在无人值守的服务器上不太好用。如果你在自动构建或远程开发机上跑Codex CLI需要一个不用交互的认证方式那就得上API Key。还有一个细节登录成功之后不要随意删除.auth目录下的文件也不要手动改里面的内容。那个文件是Codex CLI自己维护的你手动编辑很容易把结构弄坏弄坏之后它可能报一些莫名其妙的错误排查半天才发现是认证文件格式不对。3.2 API Key方式适合自动化与远程环境在Codex CLI的较新版本中可以通过类似codex login --api-key sk-xxx的方式直接用API Key完成认证或者把OPENAI_API_KEY环境变量注入到当前Shell环境里。后者在CI/CD、Docker、云主机上更常见——你不需要在每台机器上跑一次登录只要在启动进程的环境变量里带上密钥就行。我个人的习惯是本地日常使用用ChatGPT登录碰CI/CD或临时服务器时用环境变量注入API Key。这样本地上不需要维护额外的密钥文件自动化环境也不依赖交互流程两头都稳。要注意的是API Key本身有费用和权限边界不要把具备完整权限的Key散落到公共仓库或聊天记录里。3.3 认证状态的验证与常见失败原因配好认证之后如何确认它真的有效最直接的方法是执行codex whoami能看到当前登录账号的信息说明认证是通的如果提示未认证或401错误说明密钥失效或授权过期重新登录即可。也有的版本在认证相关命令上做了调整或者用codex --help就可以看到当前支持哪些认证子命令这个以你的版本信息为准。在网络环境比较复杂的办公场景里认证失败还有一个常见原因网络无法连通认证服务器。这种情况下既不是密钥错误也不是账号问题而是网络连通性问题。判断方法很简单浏览器能不能正常打开登录页面能打开而终端认证失败多半就是端口或网络策略层面的问题。4. 核心配置项详解模型、指令、权限与输出认证搞定之后Codex CLI已经可以跑了。但好不好用全看config.toml里这些核心参数怎么设计。我按影响面从大到小的顺序逐一拆解。4.1 模型选择与Provider切换config.toml里最值得关注的一个字段就是model。Codex CLI支持的模型集合是动态变化的具体型号名称要看官方列表。但配置逻辑是固定的指定一个默认model这样每次启动它就直接用这个模型干活不用每次临时敲参数。如果你接入了其他模型服务商或者自建的兼容网关一般还会有model_provider这类字段来切换供应商。配置Provider的动机五花八门有的人是想用更合适的渠道有的人是为了统一内部API网关还有人是出于统一的网关策略或网络合规要求。这里我不展开某个具体厂商的做法但你要记住一个原则Provider切换往往不仅改一个字段还通常伴随base_url、api_key_env_var等配套参数。改完必须重启会话验证连通性别只改model字段就以为万事大吉了。4.2 自定义指令与系统提示词Codex CLI允许你通过配置文件注入自定义指令相当于给它一套行为准则。比如可以要求它默认用中文回复代码注释用中文提交信息按团队规范写或者对输出格式提出具体要求。这些内容既可以在系统级配置里设置也可以做成项目级配置。项目级配置的思路和.gitignore类似——把规范带进仓库团队成员各自clone即可生效。我自己会在系统级配置里放通用偏好比如解释代码时保持简洁生成的代码要包含边缘情况处理在项目级配置里放与本项目相关的约束比如后端代码用Go不要引入Python脚本。这样分开管理既不会让通用配置过长也不会让项目级配置丢失普适性。4.3 审批策略给AI多少动手权Codex CLI最核心的能力是替你真执行命令、真修改文件所以指挥权怎么分很重要。审批策略一般有这样的倾向有的策略偏向稳妥每个关键操作都要你点头有的策略偏向效率只有涉及高风险操作时才提醒还有的策略等于彻底放权让它自己干。不同版本的字段定义可能不一样但本质上都是在安全和效率之间取平衡。我建议在开始阶段先用保守策略观察它到底会触发哪些审批熟悉之后再把策略放宽到适合自己的节奏。过早放开权限而不了解它的行为边界容易出现它擅自改了不该改的文件这种事故。配置里有个思路很实用可以结合工作目录的风险等级来选择策略。在个人实验目录里放权没问题在公司的核心仓库里还是保守一点好。4.4 输出风格与终端体验模型能力再强输出体验不好也是白搭。Codex CLI的配置里通常有一些控制输出行为的选项比如是否启用流式输出、日志级别、终端是否显示完整工具调用过程等。流式输出打开后你能像看AI对话一样实时看到内容流出来对于长任务来说心理感受好很多也能更早发现方向跑偏及时中断。日志级别则决定了你调试问题时能拿到多少线索。默认INFO级别适合日常使用一旦遇到报错或者行为异常把日志级别调高去.codex目录下的日志文件里翻线索往往会比搜索引擎里的通用答案更贴合你的问题。学会看日志是配置和排错能力的一个重要分水岭。5. 环境变量藏在配置体系里的第二入口配置文件不是唯一入口。环境变量在许多场景下甚至比配置文件还要重要尤其是自动化、容器化、还有Windows下各种诡异的PATH问题。5.1 几个关键环境变量与Windows的坑最常碰到的环境变量是OPENAI_API_KEY。有些版本里只要你设置了它Codex CLI就会优先拿它去认证而不是去读auth.json。这样做的好处是密钥管理集中化在部署场景中特别方便。另一些环境变量可能用来覆盖API地址、日志路径、临时目录等具体变量名要看版本文档。一个注意事项在Windows里环境变量分为用户级和系统级。给当前Shell设置环境变量用$env:VARxxxPowerShell或set VARxxxCMD但这些设置只对当前终端会话有效新开一个终端就没了。要永久生效可以用setx VAR xxx但setx有一个很隐蔽的坑——它写入的是注册表里的用户环境变量已经打开的所有终端都不会立即读到必须新开终端窗口才能生效。我因为这个原因曾经在终端里找不到环境变量找了很久其实是setx执行后当前窗口没有刷新。5.2 环境变量与config.toml的优先级回到前面提到的优先级框架命令行参数 环境变量 配置文件。这意味着如果你在config.toml里设置了model又在环境变量里设置了另一个model实际生效的会是环境变量那个。这个特性对自动化部署很友好同一个配置文件可以塞进多台机器再通过环境变量注入不同的model或密钥实现一配多用。不过这里也有一个容易误判的地方并非config.toml里的所有字段都支持环境变量覆盖。有些字段只接受配置文件有些只接受环境变量。如果你发现改了环境变量没生效大概率是那个字段压根不走环境变量这条通道。这时去查一下该版本的文档就好了不用怀疑人生。5.3 PATH是最常见的隐形杀手Windows上还有一个绕不开的话题就是PATH。很多人的Codex CLI是用npm全局安装的npm会把它装到某个全局目录这个目录必须出现在PATH里才能随时随地调起codex命令。问题是不同的Node.js版本管理器比如nvm-windows切换Node版本后全局目录会跟着变PATH里的路径可能仍然指向旧的Node目录于是codex就凭空消失了。明明前几分钟还能用切了一次版本就不见了这种诡异经历多半就是这个原因。我建议Windows用户在配置Codex CLI时先跑一句where codex看一下真实路径然后把这个路径对应的目录手动确认是否在PATH里。如果用的是nvm-windows最好把npm的全局目录统一设到一个固定位置比如把prefix指定到一个固定目录这样即使切换Node版本全局工具也不会换个地方躲猫猫。6. unable to locate the codex CLI binary完整排查实录这个报错被提到的频率非常之高值得单独写一整节。它的字面意思是找不到codex CLI的二进制文件但实际触发场景不止一种。下面按我遇到过的两种典型场景分别走一遍排查流程。6.1 场景一ChatGPT桌面应用本地功能报错如果你在ChatGPT桌面应用里使用了需要调用Codex CLI的功能提示“ChatGPT failed to start. unable to locate the codex CLI binary or required runtime components”意思是它在配置的路径下找不到Codex CLI的二进制或相关运行时组件。这种情况和终端里执行codex找不到命令是两码事但根因相似应用需要一个明确路径去启动Codex CLI而它没有找到。排查思路分三步。第一步打开终端执行codex --version。如果这一步就报not recognized说明Codex CLI本身就没进入PATH问题出在安装配置层。第二步如果终端能用执行where codex拿到完整路径把这个路径填到ChatGPT桌面应用对应的设置项里。第三步重启应用看报错是否消失。大多数情况下问题出在应用里填的路径与实际安装目录不一致。6.2 场景二能装能用但换终端就找不到热词里有一条很典型的描述Windows命令行安装了codex clicodex --version也能查看版本但是用Windows Terminal就是不行。这是Windows用户特别容易踩的坑。原因通常是安装时使用的Shell比如CMD和后来使用的Shell比如Windows Terminal里的PowerShell环境变量不共享或者安装后没有重启终端导致PATH没有刷新。排查链路我一步一步说在能正常使用codex的终端里执行where codex拿到完整安装路径记录下来。在打不开codex的终端里执行where codex看结果是否为空。为空说明这个终端环境的PATH里没有codex目录。打开系统环境变量设置界面检查PATH里是否包含第二步记录的目录。如果没有点编辑把那目录手工加进去。保存后一定要重新启动终端。不是新开一个标签页有些终端应用不会自动继承新的环境变量最好完全退出再打开一次。再次在之前的终端里执行codex --version。如果成功问题解决如果仍然失败检查你是不是用了nvm-windows切Node版本导致全局路径变了需要把新的Node全局目录加入PATH或固定npm prefix。这套链路走完绝大多数这个终端能、那个终端不能的问题都能解决。它还能反向暴露另一个问题你的PATH里可能同时存在两个版本不同的codexwhere codex只显示第一个匹配到的。这种时候要注意排查顺序优先清理掉旧版本。6.3 更多根因和通用解法除了路径问题required runtime components这个说法还暗示了运行时组件缺失的可能。Codex CLI依赖Node.js运行时如果Node.js版本过低或安装损坏也会出现类似报错。建议检查node --version尽量使用LTS版本必要时重装Node.js后再重新安装Codex CLI。如果上述步骤都排查过还不行最后的手段是卸载重装。别小看这种笨办法很多时候npm全局包安装一半失败、残留文件冲突重装一次反而最快。安装完成后重复一遍where codex验证。能用一句话总结的就是先确认路径存在再确认PATH包含该路径再确认运行时可用最后考虑重装。7. 从零到可用的完整配置示例与避坑清单最后给一份我自己实测过的配置参考和一套按顺序执行的清单。再次强调Codex CLI版本更新很快字段名和默认值可能变化下面的示例重点在配置思路而不是逐字照抄。7.1 一份可作为起点的config.toml示例# 默认模型按当前版本支持的型号填写 model 你使用的模型名称 # 模型供应商使用OpenAI官方服务时填openai model_provider openai # 审批策略按需确认还是自动放行按你的风险偏好来 approval_policy on_request # 流式输出 stream true # 自定义系统提示词 system_prompt 请用中文回答代码注释使用中文输出保持简洁。 # 日志级别info / debug [logs] level info以上只是骨架。你在实际使用时建议先跑一次codex --help或者查看官方文档看当前版本支持哪些字段再照着填。很多字段在更新时会改名或增删硬套旧配置容易导致新版本不识别。7.2 我推荐的配置顺序不要一次性把所有配置项都填满。我踩过几次全量配置的坑字段填得越多出错时越难定位。更好的顺序是先保证认证通过用codex whoami确认账号有效。只设置model和model_provider跑通一次基础对话。确认正常后再加approval_policy根据工作效率和安全感调整。再加system_prompt和输出行为配置。最后处理环境变量、PATH、日志等周边设置。每次改完配置立即验证不要攒一堆改动再一起测。这个顺序的核心思想是验证一个前进一步。每一步出问题你都清楚地知道是刚改的部分导致的而不是在一大堆改动里大海捞针。7.3 扩展场景接入飞书等IM通知有朋友问过Codex CLI怎么接入飞书。配置层面来说CLI本身不需要为飞书做什么特殊配置更常见的做法是在Codex CLI外面包一层脚本任务结束后把结果抓取下来通过飞书Webhook推送到群里。实现方式可以是简单脚本也可以是CI流水线。但无论上层怎么封装底层前提都是Codex CLI已经通过配置文件认证、设置好了模型和权限策略能稳定地以非交互方式运行。所以我给这类需求的第一条建议总是先把本地配置调到能跑自动化的程度再去做通知集成否则上面接得再花哨底层一报错全白搭。7.4 一份避坑清单配置文件改在用户目录的config.toml不要在安装包里乱改。认证信息单独存放别把auth.json或API Key提交到Git仓库。修改配置后重开终端不要用旧的Shell会话验证。Windows下where codex找不到路径优先检查PATH和nvm-windows的全局目录。报错信息里带binary的基本都和路径、运行时组件有关先别怀疑模型或密钥。升级Codex CLI或者Node.js后重新验证一次配置是否仍然生效。参数优先级是命令行 环境变量 配置文件排查改了没生效就按这个顺序查。日志是排错的好帮手遇到异常先把日志级别调高再复现一次。根据我个人的经验配置Codex CLI这件事最忌讳一上来就追求完美配置。先把认证跑通再慢慢调整模型和策略让它在你的工作流里长出最适合的形状。碰上unable to locate the codex CLI binary这类报错别慌按路径和运行时这个方向去查绝大多数都能在十分钟内解决。