最近很多朋友都在问同一个问题Codex 到底怎么部署天天刷到“Codex 完整部署”这个关键词结果一搜教程全是碎片要么只讲安装不讲配置要么一上来就是一堆术语。我把 Codex 从环境准备到跑通任务用 2026 年 9 月这个时间点亲测可用的完整流程捋了一遍零基础也能直接跟着做。Codex 是 OpenAI 推出的编程智能体跟普通代码补全工具不是一个物种。它能理解你的自然语言描述在真实项目目录里读代码、改文件、执行命令、跑测试甚至根据执行结果反复调整方案直到把任务做完。这篇教程会从最基础的环境准备开始带你安装 Codex CLI配置官方 API、DeepSeek 或本地 Ollama 模型完整走一遍“从零到跑通”的部署流程同时把我踩过的坑和排查思路全部写出来。不管你是第一次接触还是已经卡了大半天都建议完整看一遍。1. 先搞清楚Codex 部署到底部署的是什么1.1 Codex 不是简单插件而是一套完整开发链路很多人的第一个误区是把 Codex 理解成“装个插件就能在 IDE 里聊天”。实际上Codex 的产品形态是“客户端 模型服务”的组合。你安装的是 Codex CLI一个开源的命令行程序它负责跟代码仓库、终端环境打交道真正干活的是大模型你需要通过配置决定模型从哪里来。Codex CLI 启动后会开启一个交互式会话读取当前目录下文件的状态把你的指令拆解成一系列待执行动作。它可以读文件、修改文件、运行 shell 命令、运行测试并且根据执行结果自主迭代修改。这意味着它天生就有能力改动你的真实环境所以权限配置和安全意识非常重要。我用一句话总结部署的本质让终端里的代码助手能够正确连接你指定的模型服务并在一个受控的代码仓库里执行任务。很多人卡住不是因为安装而是因为没搞懂“客户端”和“模型服务”之间这个连接关系结果配置乱了模型连不上后面全崩。1.2 三种部署方案选型官方、第三方、本地模型目前主流有三大类方案各有各的适用场景我列个对比表方便你选方案类型代表优点缺点典型场景官方 APIOpenAI Codex 系列模型兼容性最好、功能最完整、几乎零配置需要 API Key、按量计费正式开发、生产辅助第三方兼容端点DeepSeek、MiniMax 等成本低、国内访问友好、部分模型很强工具调用能力参差不齐日常任务、预算有限本地模型Ollama Qwen2.5-Coder 等完全离线、数据不出机器吃硬件、速度慢、能力上限低隐私敏感、学习实验我建议第一次部署先用官方 API 把流程跑通。为什么因为 Codex CLI 的排错链路是所有方案共通的官方 API 出问题最少。如果一开始就接第三方或本地模型出了报错你很难判断是 CLI 的问题、网络的问题还是模型能力的问题。先确认工具本身没问题再做方案切换这是我反复验证过的顺序。2. 环境准备零基础也能搞定的前置条件2.1 Node.js 与 npm 安装与避坑Codex CLI 目前最主流的安装方式是 npm 全局安装所以 Node.js 是硬性依赖。这个环节看起来简单实际坑不少。第一不要把 Node.js 装在中文路径或带空格的系统路径下。很多 CLI 工具遇到中文路径会出各种莫名其妙的权限和编码问题Codex 也不例外。第二版本别太老建议 18.17 以上最好用 LTS 版。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号说明 Node 环境基本可用。如果你电脑里同时管理多个 Node 版本建议用 nvm。我见过太多人因为 Node 版本太旧Codex 的依赖装到一半开始报语法错误最后整个 node_modules 目录残留一堆垃圾文件清理起来非常痛苦。nvm 的好处是随时切换版本每个版本的全局包互相隔离不会污染系统。安装完 Node 后顺手把 npm 的 registry 改成国内镜像。这一步不是必须的但能显著加快依赖下载速度npm config set registry https://registry.npmmirror.com这个操作只影响包下载源不会改变 Codex 的合法使用官方源也能装就是慢一些。2.2 Git 与项目目录的准备工作Codex 的使用场景基本都依托代码仓库所以 Git 不只是版本管理工具它还是 Codex 的“安全边界”。Codex 在读取文件、生成补丁之前会参考当前目录的 Git 状态很多权限策略也跟仓库绑定。建议提前装好 Git版本最好在 2.30 以上用git --version可以确认。接下来准备一个专门的工作目录。千万不要直接用系统盘根目录或用户主目录当 Codex 的项目目录。因为 Codex 启动时会扫描当前目录结构如果目录里堆了一堆无关文件它会把这些文件全部纳入上下文计算既慢又容易误改甚至可能因为扫描范围过大触发意外修改。我自己的习惯是建一个~/codex-labs里面再放独立的测试仓库比如codex-demo。目录准备好了执行git init初始化仓库。如果是从已有项目开始就git clone到本地。Codex 并不要求仓库必须干净但脏仓库会显著影响它的执行效率。大量未提交、未跟踪的文件会让 Codex 在审批动作时更加谨慎很多朋友反馈“Codex 半天不动手”其实就是仓库太乱导致的。2.3 基础环境自检清单环境装完别急着装 Codex先做一次快速自检确认三件事Node 可用、npm 可用、Git 仓库可用。我习惯用一条组合命令node -v npm -v git --version三条命令都正常输出就说明基础环境没问题。接下来才是 Codex 安装。这里还有一个容易被忽略的点终端类型。Codex 是交互式终端工具建议使用支持 ANSI 颜色和宽度控制的现代终端。Windows 上优先用 Windows TerminalmacOS 用默认 Terminal 或 iTerm2 都行。老旧的 cmd 窗口或 PowerShell 5.1 在渲染和交互体验上会差一些但不会导致安装失败。真正会让安装失败的是下一步的全局目录权限问题。3. Codex CLI 安装与基础配置3.1 用 npm 安装 Codex CLI环境准备好后运行下面的命令全局安装 Codex CLInpm install -g openai/codex安装过程会下载 CLI 本体和依赖用了国内镜像一般一两分钟完成。安装完成后先跑一下版本号codex --version能输出版本号说明安装成功。如果提示command not found大概率是 Node 的全局 bin 目录没有加入 PATH。这个问题的排查方式macOS 和 Linux 看/usr/local/bin或 npm 的 prefix 目录Windows 则确认%APPDATA%\npm在用户 PATH 里。这里有一条我劝过很多人的经验不管系统怎么提示都不要用 sudo 或管理员权限强行装到系统目录。全局安装路径应该属于当前用户否则后续升级、卸载都会遇到权限问题。如果安装时报 EACCES 一类的权限错误优先修复 npm 全局目录归属而不是硬着头皮加 sudo。3.2 配置文件 config.toml 详解安装完成只代表程序到位了真正决定 Codex 能不能跑的是模型供应商配置。Codex 的配置入口在~/.codex/config.toml这是一个 TOML 格式的文本文件。默认情况下如果你已经有OPENAI_API_KEY环境变量Codex 会自动使用 OpenAI 官方端点不需要额外写配置。但我建议手动创建配置文件明确写清楚用哪个模型、哪个供应商方便后面切换和排错。以官方 OpenAI 为例配置如下model gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY字段含义不难理解model是模型名称model_provider指定使用哪个供应商块base_url是 API 根地址env_key是环境变量名Codex 在运行时从这个环境变量读取密钥不会把密钥写进配置文件。这种方式更安全也方便你在不同机器上复用同一份配置。要注意部分第三方供应商的base_url末尾不带/v1但这不代表它可以省。Codex 请求模型的时候会按照 OpenAI 兼容格式拼接路径很多 404 错误都是因为这里少写了一个/v1。3.3 用只读任务验证配置是否生效配置写完后先别急着让它改代码。在 demo 仓库里执行一个只读任务确认连接和鉴权都正常。比如codex exec 读取当前目录的文件列表并告诉我项目的整体结构如果 Codex 能正常响应并输出项目结构说明安装和配置链路已经打通。我会反复强调这步因为只读任务不会对仓库造成破坏即使配置有误最坏也就是报错不会产生额外风险。很多人一上来就丢一个“帮我重构一下这个模块”的指令结果 Codex 改到一半连不上模型留下一个改坏的仓库非常难受。如果这步就报错优先检查两点环境变量名是否和配置里的env_key一致、base_url是否完整。这两点解决了大约七成问题剩下三成会在后面的常见问题章节展开。4. 从配置到跑通完整实操流程4.1 初始化认证API Key 与登录方式首次运行 Codex 时会要求认证官方提供了浏览器登录和 API Key 两种方式。对于自动化部署和脚本集成场景API Key 方式更合适。把 API Key 交给环境变量macOS 和 Linuxexport OPENAI_API_KEYsk-你的密钥Windows PowerShell 里语法略有不同$env:OPENAI_API_KEYsk-你的密钥如果你不想每次开终端都重新设置可以把这行命令写进 shell 的配置文件中比如.bashrc、.zshrc或 PowerShell 的PROFILE脚本。但要注意密钥属于敏感信息不要把包含密钥的配置文件推到公开仓库里。接下来运行codex login或者在首次执行时按照提示完成认证跳转。Codex 会把登录凭据保存在本地配置目录后续使用无需重复登录。4.2 第一个完整开发任务从需求到代码认证通过后找一个小而完整的任务来练手。我建议选一个“用脚本解决明确问题”的任务比如“写一个 Python 脚本批量重命名当前目录下所有 jpg 文件按时间排序加序号”。在 demo 仓库里执行codex exec 写一个 Python 脚本批量重命名当前目录下所有 jpg 文件按创建时间排序生成新的文件名并添加序号Codex 会开始解析需求读取当前目录结构生成一个计划列出要创建哪些文件、执行哪些命令。确认计划后它会创建脚本、运行测试、检查结果。整个过程你会看到终端里不断滚动操作日志就像看一个真实工程师在替你干活。第一次跑通这个任务基本就代表整套部署成功了。之后你可以逐步增加任务复杂度比如“给这个项目加一个单元测试”“帮我修复这个函数的边界条件”让 Codex 慢慢熟悉你的代码风格。4.3 权限模型与审批机制Codex 对系统操作有明确的权限控制这是很多人忽略但非常关键的一环。Codex 会区分三类操作读文件、写文件、执行命令。读文件一般直接放行写文件和执行命令需要根据审批策略决定。审批策略通常有三种模式全自动、计划后确认、每次都确认。全自动模式适合你充分信任任务范围和仓库状态的情况计划后确认是最推荐的模式Codex 先生成计划你审一遍确认后再执行每次都确认最安全但效率低。首次使用建议用计划后确认既能看到 Codex 的思路又不会让整个流程变得繁琐。配置文件中可以设置默认的审批模式也可以针对特定命令类型单独设置。比如允许自动执行只读命令但写文件和删除操作必须人工确认。这个粒度设置能大幅提升日常使用体验建议花点时间研究一下。5. 接入 DeepSeek 或本地模型把部署成本降下来5.1 通过兼容端点接入 DeepSeek官方 API 稳定性好但按量计费对预算敏感的朋友不太友好。目前很多模型服务商都提供 OpenAI 格式兼容的 APIDeepSeek 就是其中比较有代表性的一个。接入方式不复杂在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然后设置环境变量export DEEPSEEK_API_KEY你的DeepSeek密钥运行 Codex 时通过--provider参数切换到 DeepSeekcodex --provider deepseek这里要特别提醒第三方模型能不能在 Codex 里正常工作关键在于模型是否具备工具调用能力。Codex 的工作链路不只是“生成代码”它需要根据执行结果决定下一步动作这依赖模型的 function calling 能力。如果模型不具备或实现不完善就会出现“模型回复了但 Codex 不执行后续动作”的诡异现象。DeepSeek 目前的兼容性还不错但如果你换别的服务商最好先查一下这个模型是否支持工具调用。5.2 用 Ollama 跑本地模型如果你的数据隐私要求高或者纯粹想免费体验可以在本地用 Ollama 跑开源模型再让 Codex 接入。Ollama 提供了 OpenAI 兼容的本地 API默认地址是http://localhost:11434/v1。先安装 Ollama 并拉取一个代码模型。以 Qwen2.5-Coder 为例ollama pull qwen2.5-coder:14b ollama serve然后给 Codex 配置 Ollama 供应商model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEYOllama 本身不需要鉴权但 Codex 的配置要求必须有env_key所以我们可以随便设置一个比如export OLLAMA_API_KEYollama然后运行codex --provider ollama本地模型最大的问题是推理速度和模型能力上限。我实测下来7B 到 14B 的模型能执行简单任务但遇到复杂重构就有点吃力。如果机器配置不够强不建议把本地模型当作主力它可以作为离线环境下的备用方案或学习工具。还有一点Codex 对上下文窗口长度有要求本地模型如果窗口太小任务稍微复杂一点就会报错。选择本地模型时要关注上下文长度参数尽量选 32K 以上版本的模型。5.3 多供应商切换与日常管理配置多个供应商后日常切换主要通过两种方式命令行--provider参数或者直接改配置文件里的默认model_provider。我个人的习惯是把官方 API 作为默认DeepSeek 作为日常主力Ollama 作为离线兜底三套配置都写在同一个config.toml里想用哪个就用哪个。切换时要注意环境变量不能混。如果你同时保留了OPENAI_API_KEY和DEEPSEEK_API_KEYCodex 默认只会使用当前model_provider对应的env_key。如果我切到 DeepSeek但终端里忘了设置DEEPSEEK_API_KEY运行时会提示找不到密钥。排查这类问题最快的方式是确认当前 shell 的环境变量列表再对照配置文件。另外使用第三方供应商时不要把模型名称写错。有些供应商的模型名称带日期版本比如deepseek-chat和deepseek-reasoner两个模型的能力和定价都不一样。建议先去供应商官网查清楚最新模型 ID再写进配置。6. 常见问题与排查技巧实录6.1 安装阶段常见问题安装阶段最集中的问题就是环境变量和权限。第一类是npm install -g openai/codex卡住不动绝大多数是网络问题换成国内镜像或者稍后重试就能解决。第二类是安装完成后codex命令找不到这属于 PATH 没配置好而不是安装失败。第三类是权限报错表现为 npm 写入系统目录失败解决思路是调整 npm 全局目录而不是用 sudo。还有一位朋友遇到过很奇怪的现象codex --version能输出版本号但codex exec启动后立刻闪退。最后发现是他的终端环境缺少某个动态库重新安装 Xcode Command Line Tools 后恢复正常。遇到闪退不要急着卸载先看终端有没有报错信息一般都能定位到具体依赖。我建议养成一个好习惯安装和升级 Codex 后先跑一次只读验证任务再进入真实项目。这一步能挡掉大量环境差异导致的问题。6.2 运行时连接与鉴权报错运行时最闹心的是连接类报错常见特征是一执行任务就报类似cc switch local failed while handling codex endpoint /responses的错误。这个报错看起来吓人实际上按我排查的经验90% 是三个原因模型服务地址配置错误、环境变量没生效、密钥格式不对。第一步检查config.toml里的base_url确认是否带了/v1域名有没有拼错。第二步检查环境变量在终端里运行echo $DEEPSEEK_API_KEYmacOS/Linux或者echo $env:DEEPSEEK_API_KEYWindows确认密钥能正常读取。第三步确认密钥本身没有多余空格或换行很多人从网页复制密钥时会把行尾空格带进去导致鉴权失败。如果配置没问题可以尝试临时增加日志输出定位是连接阶段还是协议解析阶段出了问题。Codex 支持调试日志查看日志里实际请求的 URL 和响应状态码通常一眼就能看出问题。6.3 模型响应异常与代码质量问题连接正常但 Codex 回答得莫名其妙这种情况多半不是部署问题而是模型选型或上下文管理出了问题。比如选择了不支持工具调用的模型Codex 可能只输出文字不执行任何操作又比如模型上下文窗口较小任务太长导致中间内容被截断Codex 就会“失忆”胡写一气。排查思路是按层切分先确认换回官方模型后一切正常那就说明是第三方模型兼容性问题如果官方模型也有问题再检查任务复杂度是不是超过模型能力或者仓库文件太多导致上下文爆炸。我建议在使用 Codex 时保持项目目录精简无关文件不要堆在同一目录下。代码质量问题还有一个常见原因用户没有在指令里明确验收标准。Codex 很擅长执行“我说什么你做什么”但它不会替你想清楚“什么叫做好了”。指令越明确输出越可控。6.4 升级、回滚与日志查看Codex 更新迭代很快升级很简单npm update -g openai/codex升级后如果发现行为变化想回滚到旧版本可以指定版本号安装npm install -g openai/codex具体版本号升级前建议先把当前的config.toml备份一份虽然一般来说配置文件是向前兼容的但备份一下总不会有坏处。我也遇到过升级后某个模型供应商配置失效的情况备份能让你快速恢复。日志查看方面Codex 会把运行日志写到本地配置目录下的 log 文件夹。遇到不明报错时去日志里搜error关键字基本能找到具体是哪一步出的问题。日志信息通常比终端输出详细得多排错时优先看日志不要反复瞎试。最后说几句这套流程我前前后后跑了十几遍从最初的懵圈到现在的顺手最大的体会是Codex 部署本身的难度其实很低难的是理解“客户端连接模型服务”这条链路。只要把环境准备、配置文件和权限模型这三件事吃透剩下就是水到渠成的事。最后再分享一个小技巧在正式项目里用 Codex 之前先给项目写一个CODEX.md之类的说明文档把项目的目录结构、技术栈、常用命令写清楚。Codex 启动任务时会读取这些上下文任务成功率会明显不一样。这也是很多团队把 Codex 用好的隐藏关键你试过就会回来感谢我。
Codex 完整部署指南：从环境准备到跑通官方、DeepSeek 与本地模型
最近很多朋友都在问同一个问题Codex 到底怎么部署天天刷到“Codex 完整部署”这个关键词结果一搜教程全是碎片要么只讲安装不讲配置要么一上来就是一堆术语。我把 Codex 从环境准备到跑通任务用 2026 年 9 月这个时间点亲测可用的完整流程捋了一遍零基础也能直接跟着做。Codex 是 OpenAI 推出的编程智能体跟普通代码补全工具不是一个物种。它能理解你的自然语言描述在真实项目目录里读代码、改文件、执行命令、跑测试甚至根据执行结果反复调整方案直到把任务做完。这篇教程会从最基础的环境准备开始带你安装 Codex CLI配置官方 API、DeepSeek 或本地 Ollama 模型完整走一遍“从零到跑通”的部署流程同时把我踩过的坑和排查思路全部写出来。不管你是第一次接触还是已经卡了大半天都建议完整看一遍。1. 先搞清楚Codex 部署到底部署的是什么1.1 Codex 不是简单插件而是一套完整开发链路很多人的第一个误区是把 Codex 理解成“装个插件就能在 IDE 里聊天”。实际上Codex 的产品形态是“客户端 模型服务”的组合。你安装的是 Codex CLI一个开源的命令行程序它负责跟代码仓库、终端环境打交道真正干活的是大模型你需要通过配置决定模型从哪里来。Codex CLI 启动后会开启一个交互式会话读取当前目录下文件的状态把你的指令拆解成一系列待执行动作。它可以读文件、修改文件、运行 shell 命令、运行测试并且根据执行结果自主迭代修改。这意味着它天生就有能力改动你的真实环境所以权限配置和安全意识非常重要。我用一句话总结部署的本质让终端里的代码助手能够正确连接你指定的模型服务并在一个受控的代码仓库里执行任务。很多人卡住不是因为安装而是因为没搞懂“客户端”和“模型服务”之间这个连接关系结果配置乱了模型连不上后面全崩。1.2 三种部署方案选型官方、第三方、本地模型目前主流有三大类方案各有各的适用场景我列个对比表方便你选方案类型代表优点缺点典型场景官方 APIOpenAI Codex 系列模型兼容性最好、功能最完整、几乎零配置需要 API Key、按量计费正式开发、生产辅助第三方兼容端点DeepSeek、MiniMax 等成本低、国内访问友好、部分模型很强工具调用能力参差不齐日常任务、预算有限本地模型Ollama Qwen2.5-Coder 等完全离线、数据不出机器吃硬件、速度慢、能力上限低隐私敏感、学习实验我建议第一次部署先用官方 API 把流程跑通。为什么因为 Codex CLI 的排错链路是所有方案共通的官方 API 出问题最少。如果一开始就接第三方或本地模型出了报错你很难判断是 CLI 的问题、网络的问题还是模型能力的问题。先确认工具本身没问题再做方案切换这是我反复验证过的顺序。2. 环境准备零基础也能搞定的前置条件2.1 Node.js 与 npm 安装与避坑Codex CLI 目前最主流的安装方式是 npm 全局安装所以 Node.js 是硬性依赖。这个环节看起来简单实际坑不少。第一不要把 Node.js 装在中文路径或带空格的系统路径下。很多 CLI 工具遇到中文路径会出各种莫名其妙的权限和编码问题Codex 也不例外。第二版本别太老建议 18.17 以上最好用 LTS 版。安装完成后打开终端验证node -v npm -v两条命令都能输出版本号说明 Node 环境基本可用。如果你电脑里同时管理多个 Node 版本建议用 nvm。我见过太多人因为 Node 版本太旧Codex 的依赖装到一半开始报语法错误最后整个 node_modules 目录残留一堆垃圾文件清理起来非常痛苦。nvm 的好处是随时切换版本每个版本的全局包互相隔离不会污染系统。安装完 Node 后顺手把 npm 的 registry 改成国内镜像。这一步不是必须的但能显著加快依赖下载速度npm config set registry https://registry.npmmirror.com这个操作只影响包下载源不会改变 Codex 的合法使用官方源也能装就是慢一些。2.2 Git 与项目目录的准备工作Codex 的使用场景基本都依托代码仓库所以 Git 不只是版本管理工具它还是 Codex 的“安全边界”。Codex 在读取文件、生成补丁之前会参考当前目录的 Git 状态很多权限策略也跟仓库绑定。建议提前装好 Git版本最好在 2.30 以上用git --version可以确认。接下来准备一个专门的工作目录。千万不要直接用系统盘根目录或用户主目录当 Codex 的项目目录。因为 Codex 启动时会扫描当前目录结构如果目录里堆了一堆无关文件它会把这些文件全部纳入上下文计算既慢又容易误改甚至可能因为扫描范围过大触发意外修改。我自己的习惯是建一个~/codex-labs里面再放独立的测试仓库比如codex-demo。目录准备好了执行git init初始化仓库。如果是从已有项目开始就git clone到本地。Codex 并不要求仓库必须干净但脏仓库会显著影响它的执行效率。大量未提交、未跟踪的文件会让 Codex 在审批动作时更加谨慎很多朋友反馈“Codex 半天不动手”其实就是仓库太乱导致的。2.3 基础环境自检清单环境装完别急着装 Codex先做一次快速自检确认三件事Node 可用、npm 可用、Git 仓库可用。我习惯用一条组合命令node -v npm -v git --version三条命令都正常输出就说明基础环境没问题。接下来才是 Codex 安装。这里还有一个容易被忽略的点终端类型。Codex 是交互式终端工具建议使用支持 ANSI 颜色和宽度控制的现代终端。Windows 上优先用 Windows TerminalmacOS 用默认 Terminal 或 iTerm2 都行。老旧的 cmd 窗口或 PowerShell 5.1 在渲染和交互体验上会差一些但不会导致安装失败。真正会让安装失败的是下一步的全局目录权限问题。3. Codex CLI 安装与基础配置3.1 用 npm 安装 Codex CLI环境准备好后运行下面的命令全局安装 Codex CLInpm install -g openai/codex安装过程会下载 CLI 本体和依赖用了国内镜像一般一两分钟完成。安装完成后先跑一下版本号codex --version能输出版本号说明安装成功。如果提示command not found大概率是 Node 的全局 bin 目录没有加入 PATH。这个问题的排查方式macOS 和 Linux 看/usr/local/bin或 npm 的 prefix 目录Windows 则确认%APPDATA%\npm在用户 PATH 里。这里有一条我劝过很多人的经验不管系统怎么提示都不要用 sudo 或管理员权限强行装到系统目录。全局安装路径应该属于当前用户否则后续升级、卸载都会遇到权限问题。如果安装时报 EACCES 一类的权限错误优先修复 npm 全局目录归属而不是硬着头皮加 sudo。3.2 配置文件 config.toml 详解安装完成只代表程序到位了真正决定 Codex 能不能跑的是模型供应商配置。Codex 的配置入口在~/.codex/config.toml这是一个 TOML 格式的文本文件。默认情况下如果你已经有OPENAI_API_KEY环境变量Codex 会自动使用 OpenAI 官方端点不需要额外写配置。但我建议手动创建配置文件明确写清楚用哪个模型、哪个供应商方便后面切换和排错。以官方 OpenAI 为例配置如下model gpt-5-codex model_provider openai [model_providers.openai] name OpenAI base_url https://api.openai.com/v1 env_key OPENAI_API_KEY字段含义不难理解model是模型名称model_provider指定使用哪个供应商块base_url是 API 根地址env_key是环境变量名Codex 在运行时从这个环境变量读取密钥不会把密钥写进配置文件。这种方式更安全也方便你在不同机器上复用同一份配置。要注意部分第三方供应商的base_url末尾不带/v1但这不代表它可以省。Codex 请求模型的时候会按照 OpenAI 兼容格式拼接路径很多 404 错误都是因为这里少写了一个/v1。3.3 用只读任务验证配置是否生效配置写完后先别急着让它改代码。在 demo 仓库里执行一个只读任务确认连接和鉴权都正常。比如codex exec 读取当前目录的文件列表并告诉我项目的整体结构如果 Codex 能正常响应并输出项目结构说明安装和配置链路已经打通。我会反复强调这步因为只读任务不会对仓库造成破坏即使配置有误最坏也就是报错不会产生额外风险。很多人一上来就丢一个“帮我重构一下这个模块”的指令结果 Codex 改到一半连不上模型留下一个改坏的仓库非常难受。如果这步就报错优先检查两点环境变量名是否和配置里的env_key一致、base_url是否完整。这两点解决了大约七成问题剩下三成会在后面的常见问题章节展开。4. 从配置到跑通完整实操流程4.1 初始化认证API Key 与登录方式首次运行 Codex 时会要求认证官方提供了浏览器登录和 API Key 两种方式。对于自动化部署和脚本集成场景API Key 方式更合适。把 API Key 交给环境变量macOS 和 Linuxexport OPENAI_API_KEYsk-你的密钥Windows PowerShell 里语法略有不同$env:OPENAI_API_KEYsk-你的密钥如果你不想每次开终端都重新设置可以把这行命令写进 shell 的配置文件中比如.bashrc、.zshrc或 PowerShell 的PROFILE脚本。但要注意密钥属于敏感信息不要把包含密钥的配置文件推到公开仓库里。接下来运行codex login或者在首次执行时按照提示完成认证跳转。Codex 会把登录凭据保存在本地配置目录后续使用无需重复登录。4.2 第一个完整开发任务从需求到代码认证通过后找一个小而完整的任务来练手。我建议选一个“用脚本解决明确问题”的任务比如“写一个 Python 脚本批量重命名当前目录下所有 jpg 文件按时间排序加序号”。在 demo 仓库里执行codex exec 写一个 Python 脚本批量重命名当前目录下所有 jpg 文件按创建时间排序生成新的文件名并添加序号Codex 会开始解析需求读取当前目录结构生成一个计划列出要创建哪些文件、执行哪些命令。确认计划后它会创建脚本、运行测试、检查结果。整个过程你会看到终端里不断滚动操作日志就像看一个真实工程师在替你干活。第一次跑通这个任务基本就代表整套部署成功了。之后你可以逐步增加任务复杂度比如“给这个项目加一个单元测试”“帮我修复这个函数的边界条件”让 Codex 慢慢熟悉你的代码风格。4.3 权限模型与审批机制Codex 对系统操作有明确的权限控制这是很多人忽略但非常关键的一环。Codex 会区分三类操作读文件、写文件、执行命令。读文件一般直接放行写文件和执行命令需要根据审批策略决定。审批策略通常有三种模式全自动、计划后确认、每次都确认。全自动模式适合你充分信任任务范围和仓库状态的情况计划后确认是最推荐的模式Codex 先生成计划你审一遍确认后再执行每次都确认最安全但效率低。首次使用建议用计划后确认既能看到 Codex 的思路又不会让整个流程变得繁琐。配置文件中可以设置默认的审批模式也可以针对特定命令类型单独设置。比如允许自动执行只读命令但写文件和删除操作必须人工确认。这个粒度设置能大幅提升日常使用体验建议花点时间研究一下。5. 接入 DeepSeek 或本地模型把部署成本降下来5.1 通过兼容端点接入 DeepSeek官方 API 稳定性好但按量计费对预算敏感的朋友不太友好。目前很多模型服务商都提供 OpenAI 格式兼容的 APIDeepSeek 就是其中比较有代表性的一个。接入方式不复杂在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然后设置环境变量export DEEPSEEK_API_KEY你的DeepSeek密钥运行 Codex 时通过--provider参数切换到 DeepSeekcodex --provider deepseek这里要特别提醒第三方模型能不能在 Codex 里正常工作关键在于模型是否具备工具调用能力。Codex 的工作链路不只是“生成代码”它需要根据执行结果决定下一步动作这依赖模型的 function calling 能力。如果模型不具备或实现不完善就会出现“模型回复了但 Codex 不执行后续动作”的诡异现象。DeepSeek 目前的兼容性还不错但如果你换别的服务商最好先查一下这个模型是否支持工具调用。5.2 用 Ollama 跑本地模型如果你的数据隐私要求高或者纯粹想免费体验可以在本地用 Ollama 跑开源模型再让 Codex 接入。Ollama 提供了 OpenAI 兼容的本地 API默认地址是http://localhost:11434/v1。先安装 Ollama 并拉取一个代码模型。以 Qwen2.5-Coder 为例ollama pull qwen2.5-coder:14b ollama serve然后给 Codex 配置 Ollama 供应商model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEYOllama 本身不需要鉴权但 Codex 的配置要求必须有env_key所以我们可以随便设置一个比如export OLLAMA_API_KEYollama然后运行codex --provider ollama本地模型最大的问题是推理速度和模型能力上限。我实测下来7B 到 14B 的模型能执行简单任务但遇到复杂重构就有点吃力。如果机器配置不够强不建议把本地模型当作主力它可以作为离线环境下的备用方案或学习工具。还有一点Codex 对上下文窗口长度有要求本地模型如果窗口太小任务稍微复杂一点就会报错。选择本地模型时要关注上下文长度参数尽量选 32K 以上版本的模型。5.3 多供应商切换与日常管理配置多个供应商后日常切换主要通过两种方式命令行--provider参数或者直接改配置文件里的默认model_provider。我个人的习惯是把官方 API 作为默认DeepSeek 作为日常主力Ollama 作为离线兜底三套配置都写在同一个config.toml里想用哪个就用哪个。切换时要注意环境变量不能混。如果你同时保留了OPENAI_API_KEY和DEEPSEEK_API_KEYCodex 默认只会使用当前model_provider对应的env_key。如果我切到 DeepSeek但终端里忘了设置DEEPSEEK_API_KEY运行时会提示找不到密钥。排查这类问题最快的方式是确认当前 shell 的环境变量列表再对照配置文件。另外使用第三方供应商时不要把模型名称写错。有些供应商的模型名称带日期版本比如deepseek-chat和deepseek-reasoner两个模型的能力和定价都不一样。建议先去供应商官网查清楚最新模型 ID再写进配置。6. 常见问题与排查技巧实录6.1 安装阶段常见问题安装阶段最集中的问题就是环境变量和权限。第一类是npm install -g openai/codex卡住不动绝大多数是网络问题换成国内镜像或者稍后重试就能解决。第二类是安装完成后codex命令找不到这属于 PATH 没配置好而不是安装失败。第三类是权限报错表现为 npm 写入系统目录失败解决思路是调整 npm 全局目录而不是用 sudo。还有一位朋友遇到过很奇怪的现象codex --version能输出版本号但codex exec启动后立刻闪退。最后发现是他的终端环境缺少某个动态库重新安装 Xcode Command Line Tools 后恢复正常。遇到闪退不要急着卸载先看终端有没有报错信息一般都能定位到具体依赖。我建议养成一个好习惯安装和升级 Codex 后先跑一次只读验证任务再进入真实项目。这一步能挡掉大量环境差异导致的问题。6.2 运行时连接与鉴权报错运行时最闹心的是连接类报错常见特征是一执行任务就报类似cc switch local failed while handling codex endpoint /responses的错误。这个报错看起来吓人实际上按我排查的经验90% 是三个原因模型服务地址配置错误、环境变量没生效、密钥格式不对。第一步检查config.toml里的base_url确认是否带了/v1域名有没有拼错。第二步检查环境变量在终端里运行echo $DEEPSEEK_API_KEYmacOS/Linux或者echo $env:DEEPSEEK_API_KEYWindows确认密钥能正常读取。第三步确认密钥本身没有多余空格或换行很多人从网页复制密钥时会把行尾空格带进去导致鉴权失败。如果配置没问题可以尝试临时增加日志输出定位是连接阶段还是协议解析阶段出了问题。Codex 支持调试日志查看日志里实际请求的 URL 和响应状态码通常一眼就能看出问题。6.3 模型响应异常与代码质量问题连接正常但 Codex 回答得莫名其妙这种情况多半不是部署问题而是模型选型或上下文管理出了问题。比如选择了不支持工具调用的模型Codex 可能只输出文字不执行任何操作又比如模型上下文窗口较小任务太长导致中间内容被截断Codex 就会“失忆”胡写一气。排查思路是按层切分先确认换回官方模型后一切正常那就说明是第三方模型兼容性问题如果官方模型也有问题再检查任务复杂度是不是超过模型能力或者仓库文件太多导致上下文爆炸。我建议在使用 Codex 时保持项目目录精简无关文件不要堆在同一目录下。代码质量问题还有一个常见原因用户没有在指令里明确验收标准。Codex 很擅长执行“我说什么你做什么”但它不会替你想清楚“什么叫做好了”。指令越明确输出越可控。6.4 升级、回滚与日志查看Codex 更新迭代很快升级很简单npm update -g openai/codex升级后如果发现行为变化想回滚到旧版本可以指定版本号安装npm install -g openai/codex具体版本号升级前建议先把当前的config.toml备份一份虽然一般来说配置文件是向前兼容的但备份一下总不会有坏处。我也遇到过升级后某个模型供应商配置失效的情况备份能让你快速恢复。日志查看方面Codex 会把运行日志写到本地配置目录下的 log 文件夹。遇到不明报错时去日志里搜error关键字基本能找到具体是哪一步出的问题。日志信息通常比终端输出详细得多排错时优先看日志不要反复瞎试。最后说几句这套流程我前前后后跑了十几遍从最初的懵圈到现在的顺手最大的体会是Codex 部署本身的难度其实很低难的是理解“客户端连接模型服务”这条链路。只要把环境准备、配置文件和权限模型这三件事吃透剩下就是水到渠成的事。最后再分享一个小技巧在正式项目里用 Codex 之前先给项目写一个CODEX.md之类的说明文档把项目的目录结构、技术栈、常用命令写清楚。Codex 启动任务时会读取这些上下文任务成功率会明显不一样。这也是很多团队把 Codex 用好的隐藏关键你试过就会回来感谢我。
