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.tomlCodex 的所有关键配置都集中在~/.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 插件除了命令行 CLICodex 还有 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 文件需要做编码转换我直接在项目目录启动 Codexcodex然后输入写一个 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{})这种坑然后改成bNone内部处理None逻辑最后还给函数补了测试用例。重点是这个过程中它没有只输出修改建议而是直接改了文件、跑了测试、确认通过。对一个程序员来说这省掉的是不断复制粘贴代码、开终端跑测试的整段重复劳动。这一步里有一个实用技巧描述任务时尽量带上文件路径和你怀疑的方向Codex 的检索效率会高很多。它虽然能自己找文件但你的领域知识能帮它少走弯路这在大型仓库里尤其明显。4.4 接入 MCP 扩展工具Codex 支持 MCPModel 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 foundnpm 全局装完却找不到命令绝大多数情况是 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报错信息看起来高深莫测实际原因说出来都嫌丢人——服务端根本不提供对应接口。希望这篇文章能帮你把这条链路一次跑通少走几个小时弯路。