最近一段时间技术圈里讨论度最高的几个关键词Codex 绝对排得上号。很多人第一次听说它是冲着“OpenAI 开源了 AI 编程助手”这个名头去的但真正用起来才发现这东西的可玩性比想象中大得多。你可以在终端里让它像同事一样帮你改代码、跑测试、查日志更重要的是它支持自定义模型提供方——也就是说你不一定非得用官方模型完全可以把它接到 DeepSeek甚至是你自己本地部署的大模型上。“Codex 下载与本地部署”这个搜索组合最近热度一路飙升正是因为大家既想要一个趁手的 AI 编程助手又不想被单一厂商绑死。这篇文章不是官方文档的翻译而是我从零开始装、配、用、踩坑之后的一份完整实操记录。你会看到下载安装步骤、登录认证方式、config.toml 配置写法以及把 Codex 接到 DeepSeek、Ollama、vLLM 这类第三方或本地模型的具体配置。不管你是刚接触命令行的小白还是已经折腾过不少开源项目的熟手照着这篇走一遍基本都能把 Codex 在本地跑起来。1. Codex 是什么一个能真正干活的 AI 编程助手1.1 它和旧版 Codex 模型、普通 IDE 插件有什么区别这里必须先做一个澄清很多人搜“Codex”会搜到 2021 年那个只存在于论文里的代码生成模型那个模型早就退出历史舞台了。现在大家口里的 Codex是 2025 年随 DevDay 发布的新一代终端编程智能体它是一个开源的 CLI 工具核心能力不是“补全代码”而是“执行任务”。它和你熟悉的 IDE 插件的区别非常大。传统的 Copilot 类插件本质还是“对话框生成代码”你选中一段代码它帮你写注释、补函数它并不会主动去读你整个项目的结构。而 Codex 不一样你给它一个自然语言任务比如“给这个 Python 项目新增一个单元测试”它会自己浏览目录、读取相关文件、制定修改方案然后一步步调用工具把代码改出来并且把每一步的操作理由展示给你。整个过程像带了一个能听懂人话、还会自己动手的实习生。正因为如此用 Codex 写代码核心考验的不是模型“会不会写”而是它对已有工程上下文的理解。它启动后会先把项目的 git 状态、目录结构、关键文件都读一遍所以你的仓库组织得越清晰它干活就越利索。这个特性也决定了它非常适合跑在真实的项目仓库里而不是一个空荡荡的记事本。1.2 为什么“本地部署”会成为一个热点如果你只是想在终端里和一个大模型聊天那本地部署的意义不大。但 Codex 这种“Agent 壳子”出现之后情况就变了官方模型按订阅或按 Token 计费跑一轮大任务可能消耗不少公司代码保密要求高的团队希望数据不出内网也有人单纯想用开源模型来驱动这套 Agent 能力把成本压到最低。Codex CLI 恰好设计了非常开放的 provider 机制。在 config.toml 里写一个 base_url、一个 API Key 环境变量、一个协议类型就能把底层的模型层整个替换掉。这是它比很多闭源 AI 编程助手更进一层的地方别人给的是“一个产品”它给的是“一个可以换大脑的工作躯干”。所以“Codex 接入 DeepSeek”“Codex 本地部署”这些话题才会在开发者社区里被反复讨论。1.3 谁适合用它谁暂时不适合先说适合的日常要写代码、改 Bug 的开发者团队想统一 AI 编程能力、但受数据合规限制的工程负责人手里有本地 GPU、想跑私有模型、又缺一个成熟 Agent 框架的人。这三类人用 Codex 的收益最大。不太建议的只想要“对话补全”功能、完全不用命令行的人Codex 的主战场在终端图形化体验没那么友好以及显存不足、却指望本地小模型达到云端大模型效果的人。本地部署是一条务实路线不是魔法模型本身的能力上限还是要尊重的。2. 下载与安装从零跑起来2.1 系统要求与前置环境官方对系统没有特别苛刻的要求Windows、macOS、Linux 都能跑但有几个前置条件需要先确认。第一是 Node.js 20 及以上版本npm 会随附安装第二是 GitCodex 依赖 Git 来判断仓库状态没有 Git 很多功能会受限第三是网络要能正常访问你计划使用的 API 服务官方模型、DeepSeek 还是本地 Ollama走的是不同的网络路径。Windows 用户尤其建议用 Windows Terminal 来跑 Codex老旧的 cmd 在颜色渲染和交互输出上会出现各种显示异常。macOS 用户如果还在用系统自带的旧终端也建议换一个现代终端模拟器否则 ANSI 转义序列可能显示成一堆乱码很影响看输出。2.2 官方推荐方式npm 全局安装安装方式非常简单官方推荐的是 npm 全局安装npm install -g openai/codex装完之后先验证一下codex --version codex --help如果你输入 codex 提示命令找不到不要急着重装95% 的情况是 npm 的全局目录没有加进系统的 PATH。可以用npm prefix -g查出全局安装目录然后把对应的 bin 目录加进 PATH。这个坑我在 Linux 和 Windows 上都遇到过原因基本一致Node 装好了但 shell 不知道去哪找命令。2.3 Windows 用户特别需要注意的三件事第一不要下载来路不明的“Codex 安装包”。官方分发渠道就两个npm 包和 GitHub 源码仓库。现在网上很多第三方打包的“桌面版安装包”谁也不能保证里面有没有夹带私货供应链风险不值得赌。第二Windows 上目前没有官方沙箱机制。macOS 版有系统级沙箱保护能限制 Codex 对文件系统的访问范围Windows 没有这部分保护所以 approval_policy审批策略就是你唯一的安全护栏。第一次使用务必保持默认的 on-request别一上来就开 full-auto。第三安装完成后先在 PowerShell 或 Windows Terminal 里跑一次codex --version确认版本号能正常输出。如果这一步都过不去后面所有操作都无从谈起。2.4 安装后第一件事先跑一条最简单的命令很多人装完 Codex 第一反应是去改配置其实顺序反了。你应该先跑一次内置的自检任务codex exec 回复 OK 两个字即可这一条命令可以一次性验证命令入口、网络、认证、模型四件事是否都通。如果这条都过不了后面配置得再花哨也没用。实测下来一个全新环境从装 Node 到跑通这条命令正常在 10 分钟以内。先把基础链路打通再谈下一步的定制。3. 登录认证与基础配置3.1 两种官方认证方式使用官方模型时认证有两种方式。第一种是codex login它会拉起浏览器打开 ChatGPT 登录页适合有 ChatGPT 订阅账号的人第二种是codex login --api-key粘贴 OpenAI API Key适合按量付费用户。不过有一点要提前说清楚如果你后面打算接入 DeepSeek 或本地 Ollama这两步认证都不需要。第三方模型的认证靠的是 config.toml 里配置的 API Key 环境变量。但我还是建议第一次运行时先用官方账号走通全流程这样以后出了问题你能快速区分“Codex 本身坏了”和“第三方配置写错了”。登录之后凭据会存在~/.codex/auth.json里。如果哪天登录状态异常删掉这个文件重新登录往往比反复刷新有效得多。3.2 config.toml 长什么样配置文件的位置因系统而异Windows 在%USERPROFILE%\.codex\config.tomlmacOS 和 Linux 在~/.codex/config.toml。没有这个文件就自己新建。Codex 也兼容旧的 config.json但新版本推荐统一使用 toml 格式。一个使用官方模型的最小配置是这样model gpt-5.2-codex model_reasoning_effort medium approval_policy on-request配置文件的加载逻辑很简单启动时读取改完保存后新会话生效。如果你改了配置但死活没效果先检查是不是路径写错了或者文件里藏了一个拼错的键。3.3 三个最核心的配置项新手必须搞懂第一个是 model告诉 Codex 用哪个模型。官方系列一般是带 codex 后缀的型号想换成第三方模型就在这写对方的模型名比如 deepseek-chat 或 qwen2.5-coder:14b。名字写错会直接报 model is not supported这类问题我在后面排错章节会详细说。第二个是 approval_policy也就是执行权限策略。on-request 表示每个需要落盘、执行命令的操作都会先征求你的同意never 表示自动批准所有操作full-auto 是彻底放手模式。新手阶段请老实待在 on-request等你对 Codex 的行为模式熟悉了再考虑放宽。第三个是 model_reasoning_effort思考强度。low 响应快、省 Tokenhigh 更深入但慢。日常改 Bug 用 medium 就够复杂架构调整再切 high。别全局锁死一个档位按任务性质动态调整才是最经济的用法。3.4 第一次运行一个真实任务认证和基础配置都完成之后找一个你有读权限的 Git 仓库执行codex exec 看看这个项目的 README然后告诉我这个项目是做什么的注意观察它的输出形式先是计划然后调用工具读取文件最后给出结论。这个过程如果顺畅说明核心链路已经没问题可以进入本地部署的环节了。如果它半天不动先检查上面说的四件事命令入口、网络、认证、模型。4. 本地部署实战接入 DeepSeek、Ollama 与 vLLM4.1 为什么要把 Codex 接到非官方模型上三个理由成本、隐私、自由度。成本最直观。官方模型按 Token 收费跑一轮大任务可能花掉好几美元DeepSeek 这类服务便宜一个数量级本地模型更是只有电费成本。隐私方面公司代码不能出内网是硬约束本地部署成了唯一选项。自由度则是给喜欢折腾的人准备的想把模型换成 Qwen、DeepSeek 还是 Llama全凭自己喜好而 Codex 恰好补上了一个好用的 Agent 框架。打个比方Codex 是开源的“施工队”模型是“施工员”。施工队不变施工员可以按需换人这个设计思路就是它最大的价值。4.2 理解 wire_api绕不开的协议问题Codex 默认走的是 OpenAI 新一代 Responses API端点是/responses。但并不是所有模型服务商都支持这个新协议绝大多数兼容服务实现的是更通用的 Chat Completions 接口端点是/chat/completions。config.toml 里的 wire_api 字段就是干这个的填 responses 表示服务商支持新协议填 chat 表示走通用接口。本地推理引擎十有八九只支持 chat 协议。所以本地部署时第一件事就是把 wire_api 老老实实写成 chat否则你会看到一个很典型的报错连接端点失败服务端根本不认识你发的请求。这个坑值得记牢它是本地部署和云端官方模型之间最大的差异点。4.3 云端兼容服务DeepSeek 配置示例DeepSeek 是目前接入成本很低的云端模型服务很多国内开发者首选它。在 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然后设置环境变量。macOS/Linux 用 exportWindows PowerShell 用$env:语法export DEEPSEEK_API_KEY你的Key$env:DEEPSEEK_API_KEY你的Key配置完成后跑一句codex exec 用一句话介绍你自己如果返回内容来自 DeepSeek就说明接入成功。这里有个很容易忽略的细节model 字段要写 deepseek-chat 或 deepseek-reasoner这是 DeepSeek 官方定义的模型名不要自己编一个 deepseek-v3 之类的名字写了就是报错的下场。4.4 本地推理引擎Ollama 一轮跑通如果连云端都不想依赖就在本地装 Ollama拉一个代码模型下来ollama pull qwen2.5-coder:14b ollama serve然后 config.toml 改成这样model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chatOLLAMA_API_KEY 填什么值都行本地服务不校验但这个字段必须存在Codex 会去读它。实测下来qwen2.5-coder:14b 这个模型在 16G 显存的显卡上跑常规补全、解释代码、写单元测试效果是可用的如果想更强一点可以上 32B 量化版但对显存的要求会高不少需要 24G 起步。如果你手头有 Jetson Orin 这类边缘设备思路完全一样只要 Ollama 服务能跑起来、暴露一个 OpenAI 兼容端口Codex 就能接。不要被“本地部署”四个字吓到它的本质就是“把模型服务跑在一个你能访问到的地址上”。vLLM 用户同理它本身就提供 OpenAI 兼容接口base_url 写成http://localhost:8000/v1即可配置思路完全一致。4.5 本地模型选型参考这里给一份常见代码模型的显存参考量化级别按 Q4 计算方便你判断自己的显卡能不能带动模型量化级别显存占用约最低建议qwen2.5-coder:7bQ45~7 GB8 GB 显存qwen2.5-coder:14bQ49~12 GB16 GB 显存deepseek-coder-v2:16bQ410~13 GB16 GB 显存qwen2.5-coder:32bQ420~23 GB24 GB 显存给个实在的建议纯体验可以选 7B想在真实项目里干活的至少 14B 起步。本地模型和云端大模型的差距是客观存在的别指望小模型在复杂重构上达到顶级效果但用它跑通自动化流程、完成机械性改动已经完全够用。4.6 配置完成后如何自测自测分两步。第一步是不带文件操作的对话测试确认模型通了第二步是带文件操作的改动测试。做第二步之前一定要先git init并提交一次给 AI 留一个可以回滚的起点。我习惯的测试方式是让它故意改错一个文件然后我用git checkout恢复顺便验证整个流程的安全网是否可靠。这一步非常值得做它能让你直观感受到 Codex 对文件系统的操作方式也会让你对权限策略的重要性有更深的理解。5. 高频报错与排查实录5.1 常见问题速查表现象常见原因处理办法codex is ignoring 1 unrecognized configuration setting...config.toml 里有拼错或不存在的键逐行核对配置项删掉多余键the 某某模型 model is not supported...模型名不存在或当前账号无权限或模型名与提供方不一致去服务商文档查准确的模型名登录后提示无法加载组织设置登录凭据过期或网络无法正常访问认证服务重新执行 codex login必要时删除 auth.json连接本地模型时报端点 /responses 错误服务端不支持 responses 协议或 wire_api 配错把 wire_api 改为 chat 后重启连接本地服务被拒绝connection refused推理服务没启动或端口不对检查 Ollama/vLLM 是否在运行、端口是否监听提示缺少 API Keyenv_key 指定的环境变量没设置设置对应环境变量后重新打开终端5.2 我实际踩过的三个坑第一个坑是 unrecognized configuration setting。当时我从网上抄了一段配置里面多了一个已经废弃的键Codex 反复提示但是不崩溃很长一段时间我都没注意到直到某次排查才发现它一直在无视那段配置。所以看到这种提示千万别忽略它的含义是“有配置根本没生效”。第二个坑是模型名写错。当时有人把 model 写成 gpt-5.6-sol 这种名字直接报了 model is not supported。这类报错 90% 是名字写错或服务商根本没这个型号。不要去记网上流传的模型名以服务商官方文档为准这是最稳妥的做法。第三个坑是本地模型拉好了Codex 却一直报端点错误。排查了半天发现是 wire_api 没改成 chatCodex 默认用 responses 协议去访问一个只支持 chat 的服务当然不通。把协议改对问题立刻消失。这三个坑基本覆盖了新手本地部署时 80% 的报错来源。5.3 排查思路从配置、服务、网络三个层面下手遇到任何连接类问题我有一套固定的排查顺序先看配置再看服务最后看网络。配置层面把 model、model_provider、base_url、wire_api 四个字段逐个核对任何一个写错都会导致连接失败。服务层面确认本地模型服务真的在跑端口真的在监听。网络层面确认目标地址是否能正常访问。有一个很高效的验证手段用 curl 直接探测本地服务curl http://localhost:11434/v1/models能返回模型列表说明服务本身没问题问题一定出在 Codex 的配置层。这一招能帮你快速把“Codex 的问题”和“模型服务的问题”区分开省下大量瞎猜的时间。6. 上强度Codex 的实战使用技巧6.1 权限策略怎么选日常在真实仓库里干活on-request 是安全底线在专门拉出来的沙箱环境或 CI 里跑批处理可以用 full-auto 提效。我见过不少人在个人电脑上开 full-auto结果模型误删文件的情况虽然 Codex 对危险命令有提示但 Windows 和 Linux 没有 macOS 那种系统级沙箱保护时还是要对自己宽容一点。还有个细节full-auto 模式下 Codex 会自动执行命令但它依然会在遇到测试失败时停下来等你看结果。别把它想成失控的机器人它更像一个“作业没写完不睡觉”的同事。6.2 会话与回滚的工作流建议我现在的固定工作流是每个任务开始前先git commit留一个干净的起点任务过程中只给它一个明确、单一的任务描述任务结束后用 git diff 检查所有改动再决定是否提交。Codex 在任务完成后通常会打印一个查看改动页面的链接很多人直接忽略其实那是它留给你的人工检查窗口一定要用。中途被打断就用codex resume恢复会话不用重新描述上下文这点对实际使用非常友好。需要扩展能力时研究一下 MCP。Codex 原生支持 MCP 协议可以挂数据库、知识库、项目管理工具效果比单纯问模型好得多。另外官方还提供 changelog 生成能力让 AI 把 git log 整理成发布说明属于性价比很高的用法适合养成习惯。6.3 一点个人体会我实际用下来的最大感受是Codex 的体验上限取决于你给它清理出来的上下文质量。仓库越整洁、任务描述越具体、权限边界越清晰它干活越接近一个靠谱同事。反过来如果你自己都不知道希望它干什么它也会在一堆无关文件里打转。别把它当搜索引擎把它当新入职的同事来带。第一次跑通“Codex 加本地模型”这个组合之后你会突然发现自己对 AI 编程助手的理解变了——它不再是一个聊天窗口而是一个可以随你调配大脑的自动化工作台。这套东西最迷人的地方不在于某个模型多聪明而在于你把所有零件拼起来那一刻它真的能开始帮你干活了。