Codex 是 OpenAI 开源的命令行编程代理coding agent它的工作方式是直接在终端里接收你的中文或英文任务自己读项目文件、修改代码、执行命令并在关键动作前请求你确认。安装 Codex 本身并不复杂真正让新手卡住的往往是环境错位CLI 明明装好了桌面端却提示 unable to locate the codex cli binary模型配置好后被上游拒绝报 the gpt-5.6-sol model is not supported使用本地代理切换工具时又出现 cc switch local proxy failed while handling codex endpoint /responses。这篇文章按一条完整链路组织先从环境检查开始在终端安装并验证 Codex CLI接着配置国内可直连的 OpenAI 兼容模型服务以 DeepSeek 为例跑通一个最小开发任务最后按报错顺序整理排查路径和可直接复用的检查清单。学完这套流程你至少能在任何一台干净电脑上用命令行把 Codex 用起来而不是只会照抄安装截图。1. 先弄清 Codex 的几种安装形态避免装错东西很多人安装失败不是因为操作步骤少而是把不同入口的依赖关系搞混了。Codex 的资料分散在多个入口命令行工具、IDE 插件、桌面 App、网页版以及 codex harness 这类术语。在开始安装前先把这些概念理清后面每个报错都能对应到具体环节。1.1 CLI、IDE 插件、桌面端与 harness 的分工Codex CLI 是整个生态的核心它通过 npm 包openai/codex发布负责读取项目文件、调用模型、生成补丁、执行命令。IDE 插件和桌面 App 本质上是一个图形外壳它们把终端交互包装成按钮和对话框但底层仍然依赖命令行工具。这也是为什么桌面端报unable to locate the codex cli binary时终端里的codex --version可能完全正常——图形程序没有找到 CLI不是代码环境坏了。搜索材料里经常出现 codex harness。在 Codex 的语境里harness 指承载智能体循环的环境负责把模型输出变成具体动作比如改文件、跑测试。普通使用者不需要单独安装 harness只要知道它存在于 CLI 的运行链路里即可。真正要你手动操作的只有 Node.js、Git、npm 包和 API 凭证这几样。1.2 安装前需要确认的环境清单Codex 的前置环境并不复杂但每一项都有明确用途建议在安装前先逐条确认。环境项要求验证命令Node.js建议使用官方 LTS 版本常见版本要求不低于 18/20node -vnpm随 Node.js 一起安装npm -vGit建议安装Codex 查看 diff、生成补丁时更好用git --version终端Windows 用 PowerShell 或 Windows TerminalmacOS/Linux 用系统终端无模型凭证官方 OpenAI API Key或 OpenAI 兼容平台的 API Key按服务商控制台配置Node.js 是 npm 包运行环境没有 Node 就无法安装 Codex。Git 虽然不是所有操作都强制需要但 Codex 在处理代码变更时经常依赖 Git 的 diff 能力强烈建议保持可用。终端类型本身不影响安装但 Windows 老式 CMD 在处理脚本输出时体验较差推荐换成 Windows Terminal 或 PowerShell。模型凭证决定的是“Codex 调用谁家的模型”这一步最容易被人忽略而它恰好是报错最集中的区域。1.3 “免费使用”应该怎么理解Codex CLI 本身是开源工具安装不收费。但代码生成必然要调用模型费用由模型服务商决定。对国内用户来说更常见的选择是使用本地网络可直连、且兼容 OpenAI API 的大模型平台这类平台通常会提供体验额度或按量计费。教程可以帮助你把这些配置跑通但“免费额度有多少、是否过期、是否收费”要以平台控制台显示为准不要相信任何“永久全免费”的宣传。开源工具免费模型调用按量付费这是理解 Codex 使用成本的一条底线。2. 从零安装 Codex CLInpm 安装、PATH 与版本验证2.1 安装 Node.js 和 Git 的推荐做法Node.js 建议从官网下载 LTS 版本不要使用仍在快速迭代的奇数版本。Windows 安装时注意安装路径不要带中文或空格否则后续全局包路径容易出问题。Git 安装时在调整 PATH 的选项里选择 “Git from the command line and also from 3rd-party software”保证命令行和 IDE 都能找到 Git。安装完成后打开新的终端窗口执行验证node -v npm -v git --version这里最容易踩的第一个坑是安装完 Node 或 Git 之后没有重启终端。终端在启动时会读取当时的 PATH 环境变量安装程序修改 PATH 后已经打开的窗口不会自动更新。遇到node: command not found或npm: command not found第一反应不是重装而是先关闭终端重新开一个。2.2 全局安装 Codex 包确认 Node 和 Git 可用后执行全局安装npm install -g openai/codex-g表示全局安装安装后的命令对所有目录可用。安装过程中会输出包的下载和写入信息最后通常显示 added 多少 packages并给出全局安装路径。在 Linux 或 macOS 上如果使用系统自带的 Node可能会遇到EACCES权限错误。此时优先用 nvm 等版本管理工具重新安装 Node而不是直接加sudo。原因很简单用 sudo 修改系统级 npm 目录可能造成后续其他包也出现权限混乱。如果确实已经使用了 nvm则全局包通常会安装在用户目录下不需要 sudo。2.3 验证安装结果安装完成后继续在同一个终端里验证命令是否可用codex --version codex --help正常情况下codex --version会输出版本号codex --help会输出支持的命令和参数。如果提示command not found说明 npm 全局包的 bin 目录不在 PATH 里。先查全局安装路径npm prefix -gWindows 常见路径是C:\Users\你的用户名\AppData\Roaming\npm里面应当有codex.cmd。macOS 或 Linux 常见路径是/usr/local/bin或 nvm 管理的~/.nvm/versions/node/v某版本/bin。把该目录加入系统的 PATH 后关闭并重新打开终端。还需要拿到 Codex 的绝对路径后面配置桌面端会用到# Linux / macOS which codex # Windows where codex2.4 认证方式登录还是 API KeyCodex 需要模型服务的认证。使用官方 OpenAI 服务时可以直接执行codex login该命令会打开浏览器引导你用 ChatGPT 账号完成授权。另一种方式是设置环境变量OPENAI_API_KEY# Linux / macOS export OPENAI_API_KEYsk-你的key # Windows PowerShell $env:OPENAI_API_KEYsk-你的key使用第三方兼容服务时环境变量名由后面的配置文件指定不一定是OPENAI_API_KEY。接下来就以 DeepSeek 为例说明配置文件怎么写。3. 配置国内可直连的模型服务以 DeepSeek 接入为例3.1 为什么需要自定义 model_providerCodex 默认配置指向 OpenAI 的接口。国内使用时如果网络或账号条件不允许直接访问官方服务切换到兼容 OpenAI API 的国内模型平台是更稳妥的路线。Codex 的配置文件支持自定义 provider把base_url指向目标平台再指定一个该平台支持的模型名就能把 Codex 的调度能力接到国内模型上。搜索热词里出现“codex接入deepseek”正是因为这种接入方式在成本和可用性上都有明显优势。DeepSeek 平台提供 OpenAI 兼容接口接入逻辑与官方差异很小适合作为国内使用的首选练习对象。3.2 创建 config.toml配置文件路径为~/.codex/config.toml。Windows 下通常是C:\Users\你的用户名\.codex\config.toml。如果文件不存在手动创建即可。# ~/.codex/config.toml 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配置完成后在终端里设置密钥export DEEPSEEK_API_KEYsk-从DeepSeek控制台复制如果你同时保留官方 OpenAI 配置也可以这样写[model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses注意不同版本的 Codex 对配置字段的支持可能略有差异保存文件后先跑一个小任务验证而不是直接开始大项目。3.3 关键参数说明表配置文件的字段并不复杂但每个字段错误都会带来不同方向的报错值得单独整理。| 参数 | 含义 | 常见值 | 配置错误时的表现