你花了大半个下午照着一篇标题写得很香的教程在终端里敲完了安装命令。Codex 版本号也打出来了看起来一切正常。可等你输入第一句话屏幕忽然跳出一行错误the gpt-5.6-sol model is not supported when using codex with a...。我见过太多人卡在这一步。他们不是在安装 Codex 时卡住而是在“安装完之后怎么让它真正工作”这一步卡住。所以这篇我不想再复述一条 npm install 命令而是想从头讲清楚一个判断Codex 的价值不在某个玄乎的版本号而在于你能否把环境、认证、模型名、服务地址这几件事配成一个能跑通的最小系统。把这个系统跑通你后续加模型、换服务商、批量处理都会很顺跑不通你换十个教程也没用。1. 先搞明白Codex 装好了不等于它能干活1.1 Codex CLI 到底是什么它不是“装完即用”的桌面软件Codex CLI 是由 OpenAI 提供的命令行编程助手。你可以把它理解成一个跑在终端里的结对程序员你告诉它当前项目在做什么它会读取相关文件给出修改建议甚至在你允许的情况下直接改代码、跑命令。它和你常用的 IDE 插件不同没有图形界面所有的交互都发生在终端。它更接近一个“连接层”。本地 CLI 负责读取你的项目、接收你的指令、组装请求云端模型负责理解语义并生成回复CLI 再把回复呈现出来或应用到文件。理解这个链路很重要因为绝大多数安装失败都不是 Codex 本身坏了而是这个链路的某一环断了。要么是本地的 Node 跑不动要么是身份认证没通过要么是模型名不对要么是服务地址压根不可达。很多人以为装 Codex 像装一个普通的.exe安装包双击后就有图标。但 Codex 的常态是你面对一串命令、一个配置文件、一组环境变量。它的安装路径不是“点击下一步”而是“确认链路通”。1.2 一条命令装完 ≠ 能用真正要匹配的是三件事你可能会看到很多教程告诉你“npm install -g openai/codex”就够了。这只是一半。要让 Codex 真正干活至少需要三件事同时成立本地环境可以运行 Codex CLI你有合法可用的身份凭证并已正确注入你配置的模型名和接口地址与你实际连的服务商匹配。这三个条件任何一环出错都会表现为“Codex 装好了但用不了”。而且这三个问题表现都很像终端报错、没有输出、提示模型不支持。所以排查时不建议直接重装而应该先确定自己卡在哪一环。这里有一个很常见的误判看到报错就怀疑“是不是我装的版本不对”。其实大多数错误跟安装命令无关。比如你配置里写了一个不存在的模型名它会报错你环境变量没导出它会报错你服务商只支持/chat/completions而 Codex 默认请求/responses它也会报错。这些错再怎么重装都解决不了。1.3 为什么搜索词里总是跟着 Git、VS Code、Node.js 安装教程翻了一圈大家在搜什么发现很多人并不是卡在 Codex 本身的安装而是卡在前置环境。比如还没装 Node.js或者 Git 版本太老又或者 VS Code 插件连不上终端。于是“Codex 安装教程”就常常和“Git 安装及配置教程”“Node.js 安装教程”“VSCode codex”绑在一起。我建议你在安装 Codex 之前花三分钟做一个环境自检。通常打开终端输入node -v npm -v git --version如果这三条命令都能正常输出版本号说明基础环境基本没问题。如果哪条提示 command not found就先解决对应工具不要急着装 Codex。Git 之所以需要是因为 Codex 通常跑在 Git 仓库里它要识别项目结构也需要你在改动后 review diff。没有 Git 也能读文件但代码版本管理和回滚会非常痛苦。另外如果你主要使用 VS Code 或 PyCharm可以先在终端里把 Codex CLI 跑通再考虑插件。插件通常只是换个界面入口底层还是要复用同一套命令行工具和认证备份。终端里跑不通插件大概率也连不上。2. 从零开始把 Codex CLI 装好最小可运行流程2.1 安装前先确认 Node 版本别用太老的版本Codex CLI 是用 Node.js 生态分发的所以 Node 版本直接决定你能不能装上。常见安装命令是 npm 全局安装但如果你的 Node 版本太老npm 会报各种看不懂的模块错误。我的建议是如果还没装 Node选择当前 LTS 版本不要贪新如果已经装了但版本很老先升级 Node再试安装如果日常用 nvm 管理 Node安装全局包时注意当前 nvm 目录避免权限错乱。确认完版本再执行安装。不同版本、不同操作系统的安装命令会有细微差别最终以官方 README 为准。常见写法是npm install -g openai/codex安装完成后确认一下命令行工具是否可用codex --version如果这里能输出版本号说明安装本身没有断。如果出现命令找不到先确认 npm 全局目录是否在 PATH 里而不是急着重新安装。2.2 身份认证登录 ChatGPT 还是使用 API KeyCodex 官方支持两种认证方式很多人在这两种之间来回横跳反而搞混。第一种直接在终端登录codex login这个命令会引导你打开浏览器授权当前设备。适合个人电脑上交互式使用简单直接。第二种通过 API Key 认证。API Key 是给程序用的适合脚本、CI 或远程环境。常见做法是把密钥放进环境变量export OPENAI_API_KEYsk-...然后启动 codex。如果是 Windows可以根据你的 shell 改成set或setx。要注意环境变量只在当前终端进程里有效如果你新开一个窗口需要重新导出或者把它写进 shell profile。我更建议只是想体验先用codex login要接入自动化流程再用 API Key。不要两种方式混着配否则排查责任难以分清。这里还有一个常见权限问题。如果你用 npm 全局安装时遇到EACCES权限错误先不要急着加sudo。更常见的原因是你用系统 Node 目录安装全局包而当前用户没有写权限。用 nvm 管理 Node 的环境通常不会遇到如果遇到参考 nvm 或 Node 官方文档调整全局目录。加sudo虽然能装上但后续升级和卸载都可能留下权限混乱。2.3 第一次对话先跑一个只读任务别让它直接改代码装完并认证成功后先别急着让它“帮我写一个完整项目”。第一句话最好做只读验证。比如进入一个项目目录然后问codex 列出当前目录下的文件并简单说明这个项目的结构这句话不涉及写文件也不执行高风险命令。如果它能正常回答说明认证、模型、文件读取都通。如果这一句就报错不建议继续。先停下来看报错类型查配置。如果你配置的是第三方服务比如 DeepSeek可能需要在命令里指定模型名。不同版本支持的命令参数不完全一样可以先用codex --help查看当前版本的说明。总之第一次对话的目的不是追求输出多惊艳而是确认链路是通的。只有链路通了后面调模型、换服务商才有意义。3. 接入第三方兼容服务时最常见的坑在“模型名”和“接口地址”3.1 为什么会有人研究接入第三方不只是省钱Codex CLI 通过 provider 机制支持接入不同的模型服务。你既可以连 OpenAI 官方接口也可以连兼容 OpenAI 接口的第三方服务或企业内部部署的合规模型入口。这也是为什么网上会出现“Codex 接入 DeepSeek”“CC Switch 配置 Codex”这类话题。选择第三方服务常见动机有三类某些场景下需要特定模型能力而官方接口不提供企业内部数据合规要求模型必须走内部网关团队已经买了其他模型服务希望统一到同一个本地工具里。这些需求本身没问题。但要注意每个服务商的模型名单、鉴权方式、接口路径并不完全一样。教程里写“把这段配置复制过去就能用”时往往省略了服务商支持的前提。如果你直接复制一个陌生模型名比如网上流传的gpt-5.6-sol而服务商根本没这个模型Codex 就会抛错。3.2 自定义 provider 的常见写法config.toml 和环境变量Codex CLI 通常会在用户目录下生成配置文件常见路径是~/.codex/config.toml。如果你通过第三方兼容服务接入需要在这里指定模型名、provider 名称和地址。以下是一段常见写法的示意具体字段以你用的服务商文档为准model your-model-name model_provider example [model_providers.example] name Example Provider base_url https://api.example.com/v1 env_key EXAMPLE_API_KEY设置环境变量export EXAMPLE_API_KEYsk-...这里最容易翻车的是base_url。有的服务商要求你填写完整的/v1后缀有的会自动拼接有的还区分/chat/completions与/responses。在不确定的情况下先查服务商提供给 Codex 或 OpenAI SDK 的配置示例不要凭感觉少写一个斜杠。另外有一些本地配置管理工具比如热词里的 CC Switch会帮你维护多个服务商配置在界面上切换。这类工具减少手改配置的麻烦但本质还是在生成同样的配置内容。使用前要理解它到底改了什么文件、改了什么环境变量否则出了问题仍然一头雾水。3.3 最容易翻车的三个错误模型名不对、鉴权不通、接口路径不一致我自己见过最多的问题不是工具安装失败而是下面的组合。第一模型名完全不匹配。你看到一个教程里写着gpt-5.6-sol就原样复制到配置文件里但你的服务商稳定模型列表里根本没有这个名字。Codex 可能直接提示模型不支持或者等请求发出去后才报错。处理办法很简单去服务商官网看模型列表把model改成真实存在的名字。第二鉴权字段不对。你已经配置了环境变量也写了env_key但服务商返回 401。这时候要检查两点环境变量是否真的导出成功服务商要求的是不是标准 Bearer 鉴权头。如果 shell 里 echo 环境变量是空的说明你根本没导出或者导出到了错误的终端窗口。可以这样验证echo $EXAMPLE_API_KEYWindows 命令提示符下可以用echo %EXAMPLE_API_KEY%如果输出为空环境变量就是没生效。第三接口路径不一致。Codex 某些版本默认调用/responses接口但很多服务商兼容层只实现了/chat/completions。于是出现 endpoint 相关报错。这种情况要在 provider 配置里显式声明使用什么接口或对准服务商支持的兼容模式。不同工具版本支持的字段不同最终以服务商和 Codex 官方文档交叉验证为准。3.4 报错排查链路不要一上来就重装如果遇到问题我建议按这个顺序排查而不是马上卸载重装先看报错发生在哪个阶段。是认证失败、模型拒绝还是连接失败再看配置文件。模型名、provider、base_url 是否来自当前服务商再看环境。API Key 是否存在未过期的密钥有没有写错再看接口。你的服务商是否支持 Codex 默认使用的接口路径最后看版本。Node、Codex CLI、配置管理工具是否过旧。可以整理成一张快速对照表报错表现优先排查处理建议model is not supported模型名查看服务商模型列表改为支持的模型401 UnauthorizedAPI Key / env_key检查密钥和环境变量是否有效403或连接超时base_url / 网络确认地址正确且服务商当前可用endpoint 相关报错接口路径确认服务商支持的接口模式并修正命令无输出输入/权限/资源查看日志检查项目目录权限和系统资源只有当你把每一步都确认过仍然复现同样问题时才考虑是 Codex 自身版本的缺陷。否则重装只是把同样的问题再走一遍。4. 从“能跑通”到“真正能放进项目里用”边界、权限与工程化4.1 不要一上来就跑大任务小步慢走的放量框架Codex 能做的事情越强越不要一次性给它过大的授权。我的建议是把使用过程分成四步第一步只读任务。让它分析仓库、解释逻辑不产生任何修改。这一步验证理解能力。第二步改一个小文件。比如修一个明显的 bug或补一个注释。改完马上看 diff。第三步多文件改动。让它修改相互关联的模块逐文件 review确认没有引入无关改动。第四步执行命令。只有前几步都稳定后才允许它运行测试、安装依赖等操作而且尽量保持确认模式。这个框架的核心不是限制 Codex而是让你第一次和它协作时所有动作都可控、可回滚。它能解决“它到底靠不靠谱”的疑虑。我刚接触这类工具时也犯过一个错第一次对话就让它“帮我重构一个模块”。结果它一次性改了五六个文件里面混着无关的格式调整和命名替换。最后我花在 review 上的时间比自己改还多。从那以后我固定为先跑一个小任务确认改动风格再逐步放量。4.2 权限、日志、版本管理是三个长期护栏从长期使用角度看有三个东西比“会不会写代码”更重要。第一权限。不要用管理员身份跑 Codex也不要让它在整个文件系统里随便读写。给它配置的工作目录最好是当前项目目录。如果配置文件里有 API Key还要注意文件权限避免别人通过配置漏洞拿到你的敏感信息。在 Linux 或 macOS 下可以定期检查配置文件的权限ls -l ~/.codex/config.toml如果权限是-rw-r--r--说明同机其他用户也能读。如果里面包含密钥建议收紧权限chmod 600 ~/.codex/config.toml第二日志。遇到问题要能定位到底是哪一层出错。打开调试日志看请求发到哪个地址、模型名是什么、服务商返回了什么。没有日志你只能靠猜。第三版本管理。所有由 Codex 产生的改动都要拿 Git 管起来。先用git status看它改了哪些文件再用git diff看具体内容。不要因为代码是自动生成的就跳过审查。自动生成代码也要纳入正常的代码评审流程。4.3 它适合谁不适合谁我把适用场景写得明确一些避免你误判适合不适合熟悉 Git 的开发者完全不懂命令行的人作为首个编程入口个人项目维护者涉及生产敏感数据的自动修改快速原型验证要求每次输出都精确一致的场景将重复性代码改动沉淀成可复用流程把 Codex 当搜索引擎代替思考如果你只是想把 Codex 当作“问问题的搜索框”也可以但那就没必要折腾自定义 provider。它真正值得投入的地方是在可控的工程环境里把一个需要多次手动完成的开发流程变成能被你审查的协作过程。这里还要说一句当你接入第三方服务时能力边界不是由 Codex 决定的而是由服务商提供的模型决定的。同一个 Codex 界面接不同模型产出的代码质量、上下文理解能力、指令遵循程度都不一样。不要因为一个服务商表现不佳就否定 Codex 本身也不要因为教程里写“某个新模型很强”就以为所有任务都能无脑跑。4.4 固定一个最小检查表而不是背命令长期下来你不需要记住每个版本的所有参数但需要沉淀一个自己的检查表。我的建议是这样环境确认node、npm、git、codex 版本都正常。身份确认当前是登录态还是 API Key环境变量有没有生效。模型确认model 名在服务商支持列表里严格匹配。范围确认Codex 只运行在当前项目目录不越界。变更确认每次改动都进 Git先 diff 再合入。日志确认出现异常先看日志从报错阶段反推配置问题。