Codex本地部署实战：接入DeepSeek与Ollama完整指南

最近一段时间，技术圈里讨论度最高的几个关键词，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 会随附安装；第二是 Git，Codex 依赖 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.toml，macOS 和 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 响应快、省 Token；high 更深入但慢。日常改 Bug 用 medium 就够，复杂架构调整再切 high。别全局锁死一个档位，按任务性质动态调整才是最经济的用法。

3.4 第一次运行一个真实任务

认证和基础配置都完成之后，找一个你有读权限的 Git 仓库，执行：

codex exec "看看这个项目的 README，然后告诉我这个项目是做什么的"

注意观察它的输出形式：先是计划，然后调用工具读取文件，最后给出结论。这个过程如果顺畅，说明核心链路已经没问题，可以进入本地部署的环节了。如果它半天不动，先检查上面说的四件事：命令入口、网络、认证、模型。

4. 本地部署实战：接入 DeepSeek、Ollama 与 vLLM

4.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 用 export，Windows 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 = "chat"

OLLAMA_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:7b	Q4	5~7 GB	8 GB 显存
qwen2.5-coder:14b	Q4	9~12 GB	16 GB 显存
deepseek-coder-v2:16b	Q4	10~13 GB	16 GB 显存
qwen2.5-coder:32b	Q4	20~23 GB	24 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 Key	env_key 指定的环境变量没设置	设置对应环境变量后重新打开终端

5.2 我实际踩过的三个坑

第一个坑是 unrecognized configuration setting。当时我从网上抄了一段配置，里面多了一个已经废弃的键，Codex 反复提示，但是不崩溃，很长一段时间我都没注意到，直到某次排查才发现它一直在无视那段配置。所以看到这种提示千万别忽略，它的含义是“有配置根本没生效”。

第二个坑是模型名写错。当时有人把 model 写成 gpt-5.6-sol 这种名字，直接报了 model is not supported。这类报错 90% 是名字写错或服务商根本没这个型号。不要去记网上流传的模型名，以服务商官方文档为准，这是最稳妥的做法。

第三个坑是本地模型拉好了，Codex 却一直报端点错误。排查了半天发现是 wire_api 没改成 chat，Codex 默认用 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 编程助手的理解变了——它不再是一个聊天窗口，而是一个可以随你调配大脑的自动化工作台。这套东西最迷人的地方不在于某个模型多聪明，而在于你把所有零件拼起来那一刻，它真的能开始帮你干活了。