Codex 最近的讨论热度确实夸张，技术社区里每隔几条就能看到它。我也第一时间把项目下载下来，从零做了一轮完整的本地部署：装 CLI、接 DeepSeek、连 Ollama，中间踩了不少文档里没写的暗坑。这篇文章就把整套流程复盘出来，按照我真实操作的顺序展开，从下载安装到配置模型，从实战演示到报错排查，你照着走一遍基本不会卡壳。
先把最核心的概念掰扯清楚：Codex 是 OpenAI 开源的一款终端 AI 编程助手，CLI 源码和安装包都能从它的官方仓库直接拿到。它本身不携带模型，是一个很薄的客户端，核心价值在"代理"能力——能读项目文件、改代码、执行命令、跑测试，而不是像补全插件那样只给你一段建议。正因为模型默认走云端服务，很多团队才会关心数据隐私和调用成本，这就催生了"本地部署"的玩法。严格来说本地部署有两层含义：第一是把 Codex 客户端装到你自己的机器上，第二是让 Codex 接入本地或私有化的模型服务。这两层本文都会覆盖，重点放在第二层，因为只有把模型链路打通，Codex 才能脱离对外部服务的依赖，成为真正意义上你自己的 AI 编程助手。
1. Codex 到底是什么，为什么值得折腾本地部署
1.1 一个会动手的编程代理
如果你用过 Copilot 或各种 AI 补全插件，请先暂时忘掉那种交互方式。Codex 给你的不是一个打字时自动补代码的输入框，而是一个能在终端里自主工作的 Agent。你用自然语言描述目标，它会自己遍历项目结构、定位相关文件、生成修改方案、写出 diff，甚至替你执行测试命令，再根据报错继续迭代。说直白点，它像一个"能直接用命令行操作你仓库的实习生"——你交代任务，它动手干活，干完给你看结果。
这种模式跟聊天式 AI 有本质区别。普通对话工具只负责生成文本，生成的代码对不对、能不能跑，得你自己复制、粘贴、执行；而 Codex 处于真实的项目环境里，它有你的文件系统上下文，有执行命令的权限，它可以连续多轮地"验证假设"。改了一个函数，它会立刻编译或跑测试，发现有问题就继续修，直到通过。这种闭环能力，才是它作为 AI 编程助手的真正价值所在。
1.2 把模型接到本地的三个理由
Codex 默认连接的是它自己的云端服务，开箱即用。那为什么还有那么多人折腾"本地部署、接入 DeepSeek、接入 Ollama"？原因很实际：
- 数据隐私。公司源码、未公开的业务逻辑、内部文档，很多根本不适合发给外部服务。代码进了别人的日志，谁也说不清会怎么被使用。把模型链路切到内部服务，文件内容只在自己的网络里流转，合规压力小很多。
- 成本控制。云端编程模型的 token 消耗量很大，一个稍复杂的任务可能烧掉几十万 token。换成 DeepSeek 这类性价比更高的兼容接口，或者用本地模型跑一些简单任务，费用能降一个数量级。
- 离线与稳定性。本地模型最大的好处是不依赖公网。网络抖动、服务限流、高峰期排队，这些在断网或内网环境下统统一边待着。
1.3 一个必须先纠正的误区
很多新手以为"Codex 本地部署 = 在自己电脑上装一个大模型"。这是错的。Codex 只是个客户端，你需要决定的是模型从哪里来。模型可以继续用云端，也可以换成私有接口，甚至用 Ollama 在本地跑一个小尺寸模型。这里没有谁优谁劣，只有匹配不匹配。大模型硬塞进个人电脑，8GB 显存跑 70B 模型，体验只会让你怀疑人生；反过来小模型也干不了复杂重构。先搞清楚这个层次，后面配置才不会混乱。
2. 环境准备与安装：三条路选一条
2.1 安装前置依赖
安装 Codex 之前，先确认机器上有 Node.js 环境。npm 安装方式要求 Node.js 18 或更高版本，直接在终端里执行：
node -v npm -v如果 node 命令不存在，去 Node.js 官网下载 LTS 版本装好，Windows 用户记得勾选"添加到 PATH"。macOS 用户也可以用 Homebrew 装。这一步没什么技术含量，但漏掉的人真不少，很多安装报错最后都查出来是 Node 版本太老。
Linux 和 macOS 都支持 Codex CLI。Windows 上我建议优先用 WSL2 跑，因为 Codex 的沙箱和文件系统操作在 Linux 环境下更顺畅。不想用 WSL 的话，也可以直接装官方桌面版，体验差一点但够用。
2.2 通过 npm 全局安装（最推荐）
npm 是最快的路。全局安装@openai/codex包：
npm install -g @openai/codex安装完成后验证版本：
codex --version如果能正常输出版本号，说明装好了。我这边实测装完大概占用不到 200MB 磁盘空间，主要包含可执行文件和相关运行时，比装一个大模型轻太多了。
这里说明一下为什么推荐 npm 而不是源码编译：Codex 的 CLI 是 Rust 写的，源码编译需要完整的 Rust 工具链，第一次构建要拉取几百个 crate，耗时少说五分钟，多则半小时，而且对网络要求高。npm 包是官方预编译好的二进制，装完即用，省心得多。如果你只是想用工具，没必要从源码走。
2.3 通过 Homebrew 安装
macOS 用户也可以走 Homebrew。先添加官方 tap 源，再安装：
brew tap openai/codex brew install codexHomebrew 方式的本质也是拉预编译二进制，和 npm 殊途同归。选哪种看你平时的包管理习惯，两种混着装也没关系，注意别让两个版本互相覆盖就行。如果你在 Linux 上用的是其他发行版，可以先去官方仓库的 Release 页面下载对应架构的安装包，或者直接用 npm，覆盖面最广。
2.4 源码构建：想改代码才需要走的路
只有两种人建议源码构建：一是你想给 Codex 提 PR 改源码，二是你所在环境网络无法方便地使用 npm 或包管理器。源码方式要先装 Rust 工具链：
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh git clone https://github.com/openai/codex.git cd codex cargo build --release -p codex-cli编译产物在target/release/codex下，你可以把它复制到~/.local/bin或/usr/local/bin加入 PATH。整个过程对国内开发者来说耗时偏长，编译期间机器风扇基本满转速，属于"能跑但别轻易选"的方案。
2.5 安装后的状态自查
装完之后别急着用，先做两件事。第一，确认配置文件目录存在，Codex 首次运行时会自动创建~/.codex目录，里面有config.toml配置文件、history.jsonl会话历史等。第二，执行codex --help扫一眼命令说明，了解自己装的版本支持的参数。不同版本参数会有差异，后面讲到的配置项如果在你版本上不认识，大概率需要升级。
codex --help看到输出里包含常用子命令和 flags，说明客户端已经就绪。接下来才是重头戏：告诉 Codex 用哪个模型。
3. 核心配置：把 Codex 接到你的模型上
3.1 读懂 config.toml
Codex 的所有关键配置都集中在~/.codex/config.toml。这个文件是 TOML 格式，结构不复杂。首次运行生成的默认配置大概长这样：
model = "gpt-5.2" model_provider = "openai" approval_policy = "on-request"三个核心字段分别代表：使用哪个模型、从哪个模型服务商获取模型、什么时候需要向你请求批准。另外还有大量的沙箱、网络、MCP 相关配置项。
你完全可以保留默认结构，只改 model 和 model_provider 两个字段来完成"换模型"。但如果你要接的是自定义服务商，比如 DeepSeek、Ollama、或者公司内网自建的兼容接口，那就必须在[model_providers.xxx]节里定义服务商的连接方式。Codex 配置文件是热加载的，改完保存后新起一个会话就生效，不用重启电脑这种玄学操作。
3.2 对接 DeepSeek：性价比极高的云端方案
如果你暂时不想上本地模型，但又不想用官方服务，DeepSeek 是目前最热门的替代接入方式。它提供 OpenAI 兼容接口，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_KEY="你的Key"这段配置里有两个关键点。第一，base_url必须带/v1后缀，Codex 会在这个地址后面拼接具体的 API 路径，漏了/v1会直接报 404。第二，wire_api要写成chat。默认情况下 Codex 使用 OpenAI 较新的 Responses 接口，而 DeepSeek 目前只实现了传统的 Chat Completions 接口，即/chat/completions。你不声明wire_api = "chat"，请求就会打到/responses路径上，然后收到一堆不知所云的报错。
实测下来，DeepSeek 配合 Codex 的体验在代码理解、多轮修改任务上都很能打，响应速度也不错，费用比官方接口便宜很多。这是我个人日常用得最多的组合。
3.3 对接 Ollama：完全离线的本地模型链路
如果你要的是真正的本地部署，Ollama 是最省事的本地模型运行工具。它把模型拉取、启动、暴露 API 这些事情全部封装好了，一条命令就能起服务。
先装 Ollama，然后拉取一个适合编程的模型。以qwen3-coder为例：
ollama pull qwen3-coder:14b确认服务在运行：
curl http://localhost:11434/v1/models接着在config.toml里加：
model = "qwen3-coder:14b" model_provider = "ollama" [model_providers.ollama] name = "Ollama local" base_url = "http://localhost:11434/v1" wire_api = "chat"本地模型不需要 API Key，所以不用配env_key。请求会直接发给localhost:11434，所有代码都不出本机，隐私性直接拉满。
注意一点：本地模型的体量直接决定 Codex 的智商上限。14B 这种量级的模型，处理简单的脚本编写、格式调整、单文件修改完全够用；但让它做跨文件的重构、复杂 bug 定位，推理能力就会露怯。如果你内存和显存都够，可以尝试 32B 或更大尺寸的模型。另外本地模型的上下文窗口如果比较小，遇到长文件容易"失忆"，建议在对话里要求 Codex 分步处理，或者直接喂小文件。
3.4 登录、认证与你可能不需要的组织设置
如果你继续用官方服务，需要登录：
codex login命令会打开浏览器完成账号授权。登录状态可以随时查看，不需要的时候用codex logout退出。
但如果你走的是 DeepSeek、Ollama 这类自定义 Provider，根本不需要也不应该执行codex login。很多人在这一步出问题：既配了第三方 Provider，又跑去登录官方账号，结果界面里看到一堆组织相关设置，加载不出来就开始焦虑。这里给个定心丸——env_key指向的环境变量就是你的认证凭据，Codex 启动时自动读取，与官方登录是两条完全独立的路径。
热搜里有"codex无法加载组织设置"这个问题，多半就发生在官方账号路径上。如果你只用自定义 Provider，这个报错可以直接无视，继续用就行；如果必须用官方服务且组织设置加载失败，先检查账号权限和网络连通性，再确认你所在的组织是否开通了 API 访问权限，这属于账号侧问题，跟本地配置无关。
3.5 也提一下桌面版与 IDE 插件
除了命令行 CLI，Codex 还有 IDE 扩展和桌面应用，底层共用同一套配置。也就是说，你在终端里把config.toml调好，打开 VS Code 里的 Codex 插件，它也会用你配好的 DeepSeek 或 Ollama，不用重复设置。插件适合喜欢在编辑器里看着上下文改代码的人，但 CLI 依然是功能最全、脚本化能力最强的前端。我的建议是先玩 CLI，把工作流跑顺，再考虑插件。
4. 实战：让 Codex 真正帮你干一次活
4.1 两种启动方式与权限模型
Codex 提供两种基本用法。直接在项目目录运行codex，进入交互式会话，像聊天一样持续对话；或者一次性执行：
codex "为 tools/ 目录下所有脚本添加 --verbose 参数"执行完这一条指令就退出，适合脚本化调用和 CI 集成。我日常混合使用：小任务用单次命令，大需求开交互会话，边看它干活边调整方向。
权限模式决定了 Codex 可以动到什么程度，这是新手最容易忽略的安全点。三种常见模式：
| 启动方式 | 行为特征 | 适用场景 |
|---|---|---|
| 默认交互 | 每次执行命令前都询问你 | 刚上手、不熟悉的仓库 |
codex --full-auto | 自动执行，无需逐个批准 | 信任的仓库、重复性任务 |
codex --dangerously-bypass-approvals-and-sandbox | 完全放权且绕过沙箱 | 明确的危险操作，非常不推荐日常使用 |
这就像你雇了个实习生干活。默认模式是它在每个动作前都请示你，不会乱来；完全放权等于把仓库钥匙直接交给它，代码要是被跑坏的脚本清了库，后悔都来不及。我建议默认至少保留询问，让 Codex 在沙箱里执行外部命令。
4.2 第一次会话：让它写个批量脚本
我拿一个实际场景演示。项目里有一批 CSV 文件需要做编码转换，我直接在项目目录启动 Codex：
codex然后输入：
写一个 Python 脚本，把 data 目录下所有 CSV 从 GBK 转成 UTF-8，自动跳过已经是 UTF-8 的文件，输出处理摘要。Codex 会先列出它计划做的事情，比如创建scripts/convert_encoding.py，然后用chardet检测编码，逐个文件转换，最后打印摘要。每一步执行前，默认模式会停下来问我是否同意创建文件和运行命令。我点确认后，它跑了一遍脚本并展示输出。整个过程大概两分钟，脚本逻辑没有问题。这种"计划—执行—反馈"的循环，是 Codex 最典型的用法。
4.3 让它修 bug：真正的价值时刻
Codex 最能体现价值的是修 bug。有一次我故意把一个函数里的空列表默认参数写错，然后让 Codex 修复：
utils/merge.py 里 merge_dicts 有一个可变默认参数问题，修掉并补一个测试。它先读代码，发现我埋的def merge_dicts(a, b={})这种坑，然后改成b=None，内部处理None逻辑，最后还给函数补了测试用例。重点是这个过程中它没有只输出修改建议，而是直接改了文件、跑了测试、确认通过。对一个程序员来说，这省掉的是不断复制粘贴代码、开终端跑测试的整段重复劳动。
这一步里有一个实用技巧：描述任务时尽量带上文件路径和你怀疑的方向，Codex 的检索效率会高很多。它虽然能自己找文件，但你的领域知识能帮它少走弯路，这在大型仓库里尤其明显。
4.4 接入 MCP 扩展工具
Codex 支持 MCP（Model Context Protocol），可以接外部工具扩展能力。配置文件在~/.codex/mcp.json，比如接一个本地部署的抓取 MCP 服务，让 Codex 自己去读在线文档：
{ "mcpServers": { "fetch": { "command": "npx", "args": ["-y", "mcp-server-fetch"] } } }配好之后重启 Codex，它会自动发现这个工具。需要查某个库的用法时，Codex 可以直接调 fetch 工具访问文档页面，而不需要你在对话里手动粘贴内容。这条链路非常适合"本地部署流"的玩家：检索、推理、执行全部在可控范围内完成，遇到信息盲区才用它主动去取外部资料，主动权始终在你手里。
4.5 我常用的参数速查
| 参数 | 作用 |
|---|---|
codex -c <文件> | 指定配置文件，适合多套配置切换 |
codex --full-auto | 自动批准模式，配合 CI 脚本使用 |
codex --model <模型名> | 临时覆盖模型，不修改配置 |
codex --verbose | 输出详细日志，排查问题神器 |
codex --skip-git-repo-check | 在非 git 目录下强制运行 |
这些参数在实际使用中命中率很高，建议先记下--verbose和--model这两个，排错和实验的时候绕不开。
5. 常见问题与排查实录
5.1 安装后提示 command not found
npm 全局装完却找不到命令，绝大多数情况是 npm 全局 bin 目录没在 PATH 里。执行下面命令确认：
npm prefix -g把输出的目录（比如/usr/local/bin或%APPDATA%\npm）加到 PATH 环境变量，重新打开终端即可。macOS 上如果用了 nvm，还要检查 nvm 当前使用的 Node 版本对应的全局 bin 路径。这个问题不只在 Codex 上有，装任何全局 npm 包都会遇到，花两分钟配好一劳永逸。
5.2 codex is ignoring 1 unrecognized configuration setting
这个报错很典型：Codex 在配置里发现了一个它不认识的键名。常见原因是配置文件里残留了旧版本的配置项，或者你从网上抄了一段新版本才支持的配置，本地版本太老不认。遇到后不要慌，日志里会明确告诉你被忽略的是哪个键。
解决思路很简单：打开config.toml，把报错指出的那行注释掉或删除，重启会话。如果想用这个功能，就升级 Codex 到新版本。我这里想强调一句：配置文件不是越多越好。很多复制党从各种教程里攒了一大堆配置项，里面超过一半是冗余的。保持最小配置原则，出问题反而好查。
5.3 local proxy failed while handling codex endpoint /responses
这个报错字面上是"本地代理处理 /responses 端点失败"，实际场景里多发生在你把base_url指向一个本地服务或内网 API 网关时。Codex 默认请求 OpenAI 风格的/responses路径，而你指向的服务只实现了/chat/completions，自然处理不了。
排查步骤就三件事：
- 用
curl直接测试你配置的地址，确认服务本身通不通：
curl http://localhost:11434/v1/models- 确认
wire_api设置是否正确。服务只支持 chat 接口就写chat，支持 responses 就写responses。 - 确认
base_url路径拼写完整，尤其不要漏了/v1。
这个报错跟本地部署场景高度绑定，你只要把模型服务跑起来再按上面三步过一遍，基本五分钟内解决。
5.4 登录不上或组织设置加载失败
如果你走自定义 Provider 路线，请直接跳过codex login，这个报错和你无关。如果是官方账号路线，登录不上先看认证流程是否被浏览器弹窗拦截，再检查账号状态。组织设置加载失败通常和组织的 API 权限配置相关，属于服务端管理问题，本地能做的只有确认账号已在目标组织内。
5.5 模型不支持或 model not supported
见过不少报错长这样：the 'gpt-5.6-sol' model is not supported when using codex with a ...。原因不外乎两种：模型名写错了，或者你配置的 Provider 根本不提供这个模型。官方默认模型名、DeepSeek 模型名、Ollama 模型名是三个完全不同的命名空间，互相不通用。
改法很直接：确认你实际要接的服务商支持什么模型。DeepSeek 侧核对它的模型列表，Ollama 侧用ollama list查看本地已拉取的模型名。模型名写对，90% 的"不支持"都会消失。
5.6 交互界面不是中文
Codex CLI 本身没有独立的语言切换选项，但这不影响中文使用。两种办法：一是直接在对话里要求"用中文回答"，Codex 会遵循；二是把常用指令写成一个启动时的预设提示语，让它始终用中文输出、注释用中文、提交信息用中文。这个在工作流里很实用，相当于给 AI 助手设定语言规范。
实操过程中的个人体会
整套 Codex 下载和本地部署流程走下来，我最大的感受是：接入 AI 编程助手这件事的技术门槛，已经从"会不会用 API"降到了"会不会读配置文件"。真正拉开体验差距的，反而不是工具本身，而是你对模型链路和数据边界的控制能力。
有几个小建议送给想动手的人。第一，先不要把模型服务商换得太复杂，用 DeepSeek 云接口把流程跑通，感受一下 Codex 的代理式工作流，再考虑上 Ollama 本地模型。第二，权限模式一定从保守开始，默认询问模式跑几天，确认 Codex 在你自己仓库里的行为模式后再上自动批准，避免在一个不熟悉的仓库里让它乱跑脚本。第三，遇到诡异报错先开codex --verbose看完整日志，别在精简输出里干猜。我踩过的最深的一个坑就是漏配wire_api，报错信息看起来高深莫测，实际原因说出来都嫌丢人——服务端根本不提供对应接口。希望这篇文章能帮你把这条链路一次跑通，少走几个小时弯路。
