Codex安装 是最近一段时间检索热度很高的词。搜索它的人通常带着一个具体任务在本地终端装好 OpenAI 开源的 Codex CLI让它能读项目、写代码、跑命令顺带还希望把模型配置成自己当前账号真正能用、用得起的那个。围绕这个需求网上出现了大量标题夸张的教程比如“安装后免费使用某新模型”“五分钟速通”。这里先说明一个容易被忽略的事实Codex 命令行程序本身是开源且免费的但当你调用模型时模型服务按 token 计费ChatGPT 账号登录也只是把计费绑定到订阅配额上不存在真正绕开计费的稳定路径。本文只做合规的安装、配置和排错。这篇教程从环境检查开始带你完成 Codex CLI 的安装、登录、最小运行验证再讲清楚config.toml里model、model_provider、base_url之间的关系并给出接入 DeepSeek 这类 OpenAI 兼容 API 的配置模板最后把安装和排错过程中最常遇到的坑整理成排查清单。读完以后你可以自己判断网上任何一个“Codex 安装 模型配置”类教程是否靠谱。1. 先搞清楚 Codex 是什么动手安装前要校准预期1.1 Codex 不是网页聊天框而是终端里的编码智能体可以把 Codex 理解成一个跑在终端里的 AI 开发助手。它能看到你当前工作目录下的文件能读取 Git 状态能执行命令也能在你允许的范围内修改文件。和网页版 ChatGPT 最大的区别是Codex 拥有一个明确的工作目录并且能在这个目录里真实地行动创建文件、改代码、跑测试、根据报错继续修。技术上OpenAI Codex CLI 是一个开源命令行程序源码托管在 GitHub 的openai/codex仓库。安装后终端里会多出codex命令。它支持交互式会话也支持codex exec这种一次性执行任务的方式。很多教程里说的“Codex 自动化改代码”实际就是在终端里启动一个 Codex 会话让它基于当前仓库内容完成需求。为什么这个工具值得单独学习因为它和普通聊天工具的使用习惯完全不同你需要关注工作目录、权限确认、Git 分支、配置文件路径和 API 服务地址。这些问题在网页聊天里不存在但在终端编码智能体里都是核心问题。1.2 “免费使用最新模型”类标题为什么不可靠网上很多教程会把 Codex 和“某个新模型”绑在一起标题里经常出现“白嫖”“破解”“免费用新模型”等说法。这类说法至少存在三个问题第一Codex 程序是免费开源的但模型服务不是免费的。你通过 ChatGPT 账号登录后使用的是账号订阅套餐内的配额通过 API Key 使用时OpenAI 按 token 计费。所谓“免费”最多指“程序本身不要钱”不意味着“模型调用不要钱”。第二网上流传的模型名不一定是官方真实存在的模型。比如“gpt-5.6-sol”这类配置在很多人的机器上跑起来就会立刻报错模型不被支持。原因可能是模型名写错、模型尚未对当前账号开放或者模型只在某一种 API 类型下可用。模型名必须以服务商官方模型列表为准。第三打着“绕过计费”“中转站”旗号的方案稳定性、隐私性和合规性都很差。轻则配置经常失效重则泄露 API Key。这类路径不适合写进正经技术教程也不建议在真实项目里使用。1.3 适合本文的读者和场景本文适合以下读者已经会使用终端、npm 和 Git 的开发者。想给本地项目接入一个能改代码、能跑命令的 AI 工具的开发者。在配置 Codex 时遇到“模型不支持”“登录失败”“本地服务连不上”等报错需要系统排查的人。想了解如何把 Codex 指向 DeepSeek 等 OpenAI 兼容 API 服务的人。如果你只是想找一个网页聊天工具完全不想碰终端那 Codex CLI 暂时不适合你。如果你是零基础请先花一点时间熟悉终端基本操作再继续往下读。2. 环境准备安装前先检查 Node、系统、终端和 Git2.1 基础环境要求安装 Codex CLI 对环境的要求并不高但有一个前提Node.js 环境要可用因为最常见的安装方式是通过 npm 全局安装。下面是常见环境要求检查项常见要求说明操作系统macOS / Linux / WindowsWindows 建议优先使用 WSL2 中的 Ubuntu工程命令更完整Node.js18 及以上以官方 README 标注的版本为准npm随 Node.js 自带即可建议保持 npm 版本不要太旧Git建议安装并配置好 user.name / user.emailCodex 在 Git 仓库内体验最完整终端Bash / Zsh / PowerShell 等WSL 内使用 Bash 最常见网络能正常访问 npm 源和模型服务安装依赖失败时先检查网络连通性这里要注意网上很多教程写“Node 16 也没问题”但 Codex CLI 的依赖和安装脚本迭代比较快版本过低会出现安装失败或运行时语法错误。如果团队里已经有 Node 版本规范先确认是否满足官方要求再继续。2.2 安装 Codex CLI 的推荐方式最通用的安装命令是 npm 全局安装node -v npm -v git --version npm install -g openai/codex安装完成后用版本命令验证codex --version如果显示类似0.x.x的版本号说明安装成功。codex --help可以查看子命令列表常见的有login、logout、exec等。除了 npm官方仓库还会提供其他安装渠道比如部分包管理器或发行版安装包。不同渠道的更新节奏不完全一致具体以你看到官方仓库或文档时标注的方式为准。对绝大多数开发者来说npm 全局安装最直接也最容易卸载和升级。2.3 Windows 用户建议先装 WSLCodex CLI 可以在 Windows 上运行但很多功能依赖类 Unix 环境。比如沙箱限制、命令执行、路径处理在原生 Windows 终端里表现会不一样。社区里大量使用 Codex 的 Windows 用户最终都选择了 WSL2。推荐顺序是在 Windows 上安装 WSL2并安装 Ubuntu。在 WSL 的 Ubuntu 里安装 Node.js 和 npm。在 WSL 终端里执行npm install -g openai/codex。直接进入项目目录运行codex。在 WSL 中访问 Windows 盘符下的项目是可行的路径类似/mnt/c/Users/你的用户名/项目目录。不过跨盘操作时权限和命令行为会有差异建议把项目放到 WSL 自己的文件系统里路径类似~/projects/your-project体验更稳定。2.4 安装后 command not found 的常见原因很多新手装完以后执行codex --version会看到command not found。这不是安装失败而是 npm 全局安装的目录不在 PATH 里。可以先查看 npm 全局安装路径npm config get prefix显示的路径下的bin目录在 Windows 下通常是%APPDATA%\npm需要加入 PATH。如果你是用 nvm 管理 Node 版本一般不需要手动配置 PATH因为 nvm 会自动处理。这里不建议直接使用sudo npm install -g那样会把全局包装到系统目录后续升级和权限管理都会很麻烦。3. 登录认证两种方式各有各的坑3.1 方式一使用 codex login 走浏览器授权如果你有 ChatGPT 账号并且已经开通了相关订阅可以运行codex login命令会在终端输出一个本地授权地址浏览器打开后登录 ChatGPT 账号并完成授权。授权成功后Codex 会把凭据写到本机配置目录后续运行就不需要重复登录了。这个流程常见的坑有两个一是终端无法自动打开浏览器。此时手动复制终端里显示的地址在浏览器打开即可。个别环境还需要在打开地址前确认本机时间和系统时间同步时间偏差过大会导致授权回调失败。二是登录后 Codex 仍然报未认证。可以先执行codex login --help看看当前版本的参数也可以直接重新登录一次。反复失败时检查浏览器是否拦截了跳转或者是否使用了多个 ChatGPT 账号导致授权了错误的账号。3.2 方式二使用 API Key 和 OPENAI_API_KEY如果你更希望用 API Key 的方式调用模型可以不登录账号直接设置环境变量export OPENAI_API_KEY你的 API Key codex exec 简单描述当前目录内容把 API Key 放在环境变量里比写进配置文件更安全。注意export只在当前终端会话生效关闭终端就失效。想长期使用可以把这一行写进~/.bashrc、~/.zshrc或者使用专门的密钥管理工具。需要特别注意的是不要把 API Key 提交到 Git 仓库也不要复制到任何在线聊天工具里。一旦泄露别人就可以用你的额度调用模型产生费用。3.3 第一次运行用最小任务验证安装是否真正可用安装和登录不是终点真正重要的是“安装、登录、模型调用、文件写入”这条链路是否全部通。建议先建一个空白目录做最小验证mkdir -p ~/codex-demo cd ~/codex-demo codex exec 创建一个 README.md内容为这是一个 Codex 演示项目正常情况下Codex 会在当前目录生成README.md。然后用命令确认cat README.md如果文件存在并且内容符合要求说明安装和认证都正常。如果报错先看报错信息再回到下一章的配置说明去检查。3.4 关于额度程序免费但模型调用计费这里再强调一次Codex 程序免费不代表模型调用免费。ChatGPT 账号登录后调用模型会消耗账号订阅套餐内的配额API Key 方式则按 token 计费。当你看到类似余额不足、配额超限的报错时正确的做法是检查账号余额或订阅状态而不是寻找“绕过计费”的工具。一个稳定的使用习惯是单独创建一个 API Key 用于 Codex在服务商后台设置预算上限并定期查看用量。这样即使 Key 出现异常调用也能及时发现和控制。4. config.toml 与模型路由model、model_provider、base_url 是关键4.1 先理解三个核心概念Codex 的配置文件路径是~/.codex/config.toml。部分版本还会读取项目目录下的.codex/config.toml优先级更高具体以你的codex --help和官方文档为准。配置文件里最核心的是三个概念model模型名称字符串比如deepseek-chat。Codex 会把请求发到指定模型。model_provider当前使用哪一个“模型提供商”。提供商在配置文件里用[model_providers.xxx]定义。base_urlAPI 请求的基础地址。OpenAI 官方有一套地址DeepSeek 等兼容服务各有各的地址。可以这样理解model决定用哪个模型model_provider决定找哪一家服务商base_url决定请求发到哪里。三者必须匹配否则就会报错。4.2 官方 OpenAI provider 不需要特别配置如果你直接使用 OpenAI 官方模型通常不需要自己写base_url。只要安装了 Codex通过codex login登录或者设置了OPENAI_API_KEYCodex 就会使用内置的官方配置。这里有一个常见的错误认知看到别人的配置写了base_url就把它复制过来结果自己的请求被发到了别人的服务商地址上。官方场景下不要随便改base_url第三方场景下base_url必须和模型服务商对应。4.3 接入 DeepSeek 这类 OpenAI 兼容 API 的配置模板“Codex 接入 DeepSeek”是很多开发者关注的方向因为 DeepSeek 提供 OpenAI 兼容的 API。要完成接入首先在 DeepSeek 开放平台创建 API Key然后设置环境变量export DEEPSEEK_API_KEY你的 DeepSeek API Key接着在~/.codex/config.toml中写入model deepseek-chat model_provider deepseek [model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com env_key DEEPSEEK_API_KEY wire_api chat配置完成后重新启动 Codex 或新开会话再用一个简单任务验证cd ~/codex-demo codex exec 读取当前目录所有文件并说明每个文件的作用如果输出正常说明 DeepSeek 接入成功。这里要注意wire_api。Codex 默认走 OpenAI 的 Responses API而 DeepSeek 等大量兼容服务只实现了 Chat Completions API因此需要显式指定wire_api chat。如果你的 Codex 版本不认识这个字段会提示 provider 配置解析失败此时删除这一行重试具体字段以你安装版本的配置说明为准。4.4 常用参数速查表参数作用常见取值注意事项model调用的模型名称deepseek-chat、deepseek-reasoner等必须以服务商支持列表为准model_provider使用哪个提供商对应[model_providers.xxx]的名字写错会找不到提供商base_urlAPI 根地址https://api.deepseek.com等不要随意加额外路径env_key从哪个环境变量读取 KeyDEEPSEEK_API_KEY环境变量未设置会报缺少 Keywire_api使用 responses 还是 chat 协议chat/responses第三方兼容服务大多需要chat一个比较容易被忽视的问题修改config.toml或环境变量后配置不会热更新。必须重启 Codex 会话或者在新终端里重新运行配置才会生效。如果改完配置后发现行为没变先确认是否重启了会话。5. 常见报错与排查链路从“模型不支持”到“本地服务连不上”5.1 “model is not supported”类报错先查模型名网上很多人反馈把某个模型名写进配置后Codex 报错类似the gpt-5.6-sol model is not supported when using Codex with a ...这个报错的核心信息是你配置的模型