最近 GitHub 上热度最高的 AI 编程项目之一就是 OpenAI 开源的 Codex CLI。简单说它是一个跑在终端里的 AI 编程助手能读你项目里的代码按你的要求改文件、生成新功能、执行命令甚至帮你跑测试。我最初是抱着尝鲜的心态下载的结果用顺手之后本地那台 Windows 电脑几乎被我当成了私人 AI 编程工位——把 Ollama 里的 DeepSeek 和 Qwen2.5-Coder 接进 Codex彻底走上了“所有代码都在本地跑”的路子。这篇文章就是我的完整实战记录从下载安装开始到配置文件逐项解析、接入本地大模型、跑通第一个真实任务再到各种报错的排查过程通通写清楚。适合刚听说 Codex 的新手也适合那些想把本地大模型真正用起来、不想再依赖网页聊天窗口的开发者。1. Codex 到底是个什么东西值得专门写一篇1.1 一个住在终端里的 AI 结对程序员很多朋友一听到“AI 编程助手”第一反应是 GitHub Copilot 那种 IDE 插件你在编辑器里敲代码它帮你补全、生成函数、解释报错。Codex 不太一样它更像一个住在终端里的结对程序员你不光可以和它对话它还能实际操作你的电脑。启动之后它会扫描当前目录的文件结构理解你手头这个项目的代码是怎么组织的然后你要做的就是描述需求。比如“帮我把这个 Python 脚本改成异步版本”“给这段 TypeScript 加上单元测试”“查一下为什么 CI 构建老是失败”它会自己翻代码、写补丁、执行命令、跑验证然后把结果贴给你看。在技术圈里这种能调用工具、能执行动作的 AI 被称为 Agent也就是“智能体”。Codex CLI 正是 OpenAI 把自家 Agent 能力开源落到终端里的产物。它在设计上非常克制没有做一个花哨的 GUI界面上就是一个命令行交互窗口但恰恰是这种克制让它很适合真正干活的场景它就在你的代码旁边工作跟你的开发环境无缝衔接而不是另开一个网页让你手动复制粘贴。1.2 为什么本地部署这个思路突然火了Codex 官方默认情况下是连接 OpenAI 的云端模型使用的需要有 OpenAI 账号和对应的订阅额度。问题在于很多人要么没有订阅要么希望代码完全不离开自己的电脑要么想用咱们自己在本地部署的大语言模型来驱动它。于是“本地部署 Codex”这个组合拳就开始流行了。本地部署这个词听起来有点劝退其实门槛没有想象中那么高。核心思路就一句话Codex 自己不包含模型它只是个壳真正干活的是背后的 LLM。只要让这个壳“说”你本地模型的接口语言它就能用本地模型干活。本地部署的好处非常明显隐私性拉满。代码文件、项目内容不会上传到任何云端全在你的机器里。没有按用量计费的焦虑。本地模型只要部署好怎么调用都不心疼。终端响应更可控。你可以完全掌控模型版本、参数甚至定制 prompt 模板。顺带把本地大模型的用途盘活了。很多人部署了 Ollama 之后发现除了聊天没有其他用武之地接上 Codex 就等于给本地模型找了个正经工作。说白了Codex 本地部署不是让你搞一套多么复杂的工程而是给“本地大模型到底能拿来干嘛”这个老问题提供了一个非常优质的答案拿去写代码。2. 动手之前环境准备与三分钟安装2.1 先看看你的电脑够不够格Codex 本身非常轻量它对电脑硬件的需求低到离谱因为它只是一个 Node.js 写的命令行工具不负责跑模型。真正的硬件要求来自模型那边这部分我放到第四节细说。先说 Codex 本体需要的运行环境Node.js 18 以上版本。官方建议用最新的 LTS实测 20 和 22 都很稳。Git。它不是必选项但 Codex 在操作 git 仓库时会调用系统 git建议提前装好。macOS、Linux、Windows 都支持。Windows 上需要注意一点虽然原生支持但如果你要在终端里跑 bash 命令建议装个 Git Bash或者直接用 WSL否则部分命令执行功能会受限。我自己是在 Windows 11 上操作的用的终端是 Windows Terminal 加 Git Bash全程没有遇到什么环境上的大坑。如果你手头没有 Node.js别用太旧的版本去 nodejs.org 下一个 LTS 安装包一路下一步装完就行。2.2 三分钟安装命令行搞定安装方式很简单npm 全局安装即可npm install -g openai/codex装完之后验证一下codex --version如果能看到类似codex/0.2.2这样的输出说明装好了。注意包名前面有openai/这个命名空间别敲成codex或者openai-codex。npm 上也有一个叫codex的老包那是另一个项目的遗留名字装错的话后面会非常混乱。有一个比较实用的经验如果 npm 下载速度很慢或者超时可以把 npm 源切到国内镜像比如npm config set registry https://registry.npmmirror.com之后再执行安装命令就快多了。这一步纯属加速下载不影响任何后续配置。3. 配置文件是灵魂手把手拆解 config.toml3.1 配置文件到底放在哪里Codex 的所有行为都由一个 TOML 格式的配置文件控制。这个文件路径很好记macOS / Linux~/.codex/config.tomlWindows%USERPROFILE%\.codex\config.toml也就是用户主目录下的.codex文件夹里的config.toml。第一次运行codex时工具会自动创建这个目录。如果你找不到.codex文件夹可以手动建一个再新建一个config.toml文件没问题的。这个文件的优先级非常高启动时它会先读取这里的内容再结合命令行参数决定最终行为。很多朋友说“Codex 登录不上”“Codex 打不开”十有八九就是配置文件里某个字段写错了不是软件坏了。3.2 关键配置项逐个拆解我把一个完整的、可以直接抄走的本地部署配置放在下面然后逐个字段解释model qwen2.5-coder:14b model_provider local [model_providers.local] name Local Ollama base_url http://127.0.0.1:11434/v1 env_key LOCAL_API_KEY wire_api chat先看model字段。这个字段指定 Codex 默认使用的大模型名称。连接云端模型时它的值是类似gpt-5-codex这种官方模型名连接本地模型时填你本地服务里的模型名大小写要和模型服务返回的一致否则会报“model not found”。再看model_provider。这是最核心的配置它决定了 Codex 把请求发到哪个“供应商”。Codex 支持一个[model_providers.xxx]的配置段里面的xxx是你给供应商起的别名然后在顶层model_provider xxx引用这个别名。这种设计非常好理解你可以在同一个配置文件里定义多个供应商比如官方 OpenAI、DeepSeek API、本地 Ollama然后随时切换默认值不需要改来改去。base_url就是供应商接口的地址。官方 OpenAI 的地址是https://api.openai.com/v1本地 Ollama 就是http://127.0.0.1:11434/v1。注意 Ollama 的版本需要比较新否则不提供/v1这个 OpenAI 兼容路径。env_key指定从哪个环境变量读取 API Key。本地模型通常不需要鉴权但这个字段不写的话有些版本会直接报“missing API key”所以最好还是设置一个环境变量占位比如LOCAL_API_KEY随便给个值或者干脆不填取决于你的 Codex 版本。我在 0.2.x 版本上实测不设置env_key也能正常跑本地模型但设置一个也完全无害。wire_api是一个非常容易被忽视的坑。OpenAI 的官方接口有/responses和/chat/completions两套协议CODE CLI 不同版本对它们的支持不一样。本地模型服务尤其是 Ollama通常只实现了/chat/completions也就是 chat 协议所以这里要显式写wire_api chat。如果你发现 Codex 连上了本地模型但每次请求都报“404 Not Found”或者“endpoint not found”先来看这个字段大概率它被默认设成了responses。还有一个常用配置项auto_execute false这个控制 Codex 是否可以自动执行你同意过的命令。建议新手先保持false每条命令执行前它都会问你一遍等你熟悉它的行为习惯了再改成true也不迟。后面我会专门讲这个的坑。4. 接本地大模型Ollama DeepSeek/Qwen 实战4.1 为什么我推荐 Ollama让 Codex 用上本地模型核心是给它接一个兼容 OpenAI 接口的本地推理服务。目前市面上可选的方案有 Ollama、LM Studio、vLLM、llama.cpp 等。我推荐 Ollama原因有三个第一安装极其简单。官网下一个安装包双击装完命令行直接能用不用折腾 Python 虚拟环境、CUDA 依赖这些乱七八糟的东西。第二它对显卡不挑剔。NVIDIA 显卡、AMD 显卡、核显、甚至纯 CPU 都能跑只是速度问题不像 vLLM 那样基本强制要求 NVIDIA GPU 且显存充足。第三模型管理方便ollama pull就能拉模型类似 Docker 的使用体验生态里的模型命名和版本管理都很清晰。当然LM Studio 也是个好选择它的图形界面更友好适合不想敲命令的朋友。但考虑到写代码的场景通常需要频繁调整参数、查看日志我感觉还是 Ollama 更顺手。4.2 拉模型、起服务、验证连通性安装好 Ollama 之后第一步先拉一个适合写代码的大模型。我的选择是qwen2.5-coder:14b这个模型在代码生成、代码理解、代码补全方面的表现非常出色是目前开源模型里最能打的代码模型之一。显存够大可以上 32b显存只有 8G 就用 7b。拉取命令ollama pull qwen2.5-coder:14b如果你想试试 DeepSeek 系列可以拉deepseek-r1:14b或者deepseek-coder。DeepSeek 在数学和逻辑推理上很强生成代码时也更注重解题思路但响应速度比 Qwen 慢一些实测在 Codex 场景下返回 token 数多会显得“话痨”。我个人做常规开发任务更偏好 Qwen2.5-Coder。模型拉好之后确保 Ollama 服务在运行。命令行执行ollama serve如果之前已经作为后台服务安装这一步可以省略。然后另开一个终端测试一下模型服务是否正常响应curl http://127.0.0.1:11434/v1/models能返回一个 JSON 数组说明服务起来了。再进一步直接发起一次对话请求curl http://127.0.0.1:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:qwen2.5-coder:14b,messages:[{role:user,content:say hi}]}如果返回了choices字段说明兼容接口完全正常。这一步非常关键它提前把网络层和服务层的问题隔离了如果 curl 都拿不到正常响应那问题一定出在 Ollama 这边而不是 Codex 配置。4.3 model_provider 配置与模型选型细节在确保 Ollama 服务正常之后把配置写成这样model qwen2.5-coder:14b model_provider local [model_providers.local] name Local Ollama base_url http://127.0.0.1:11434/v1 wire_api chat保存之后进入一个测试目录执行codex进入交互界面后随便问一句“用一个 Python 脚本计算斐波那契数列”。如果 Codex 返回了代码那恭喜整套本地部署链路已经跑通了。从下载安装到这一步全程也就十几分钟。关于模型选型我给一个直观的参考表是我在 16G 显存和 32G 内存的机器上实测的体感模型名称显存建议代码能力响应速度适合场景qwen2.5-coder:7b6G 以上中上快轻量任务、CPU 也能跑qwen2.5-coder:14b12G 以上强中等日常开发主力qwen2.5-coder:32b24G 以上很强较慢高难度重构、复杂算法deepseek-coder:14b12G 以上强慢逻辑推理型任务如果你的机器显存不足又想体验本地部署建议用 7b 模型量化版本可以进一步降低显存占用。Codex 本身对模型大小并不敏感它只会按配置发请求模型小一点、响应慢一点但不影响整套流程跑通。5. 完整实操让它帮你写个脚本5.1 启动与第一次对话环境都备齐之后进入实战。我建议第一次不要直接在项目的根目录启动 Codex因为如果代码量很大它首次加载上下文会有点慢。先建一个空白目录比如test-codex在里面放一个简单的 Python 文件随便写点啥然后打开终端进入这个目录执行codex看到命令提示符就表示它已经就绪。注意它默认会先显示当前目录里的文件结构这就是 Codex 的目录感知能力它知道你在哪个项目里能看到哪些文件。接下来的对话方式跟 ChatGPT 很像但因为你是在终端里建议你用更工程化的语言描述需求。我测试时会让它做这么一件事我写了一个 Python 脚本功能是把一堆 CSV 文件合并成一个 Excel 文件但并发一多就会内存溢出。我向 Codex 提出需求“帮我重写这个脚本用 pandas 的分块读取方式处理避免一次把所有数据都加载到内存里。”Codex 的回复通常分几步先简要说明它的方案然后直接给出修改后的代码块再说明改动了哪些地方。如果你认可它会问你“是否要写入文件”选择确认后它直接把代码写进你的文件完全省去复制粘贴的环节。这个体验说实话第一次用的人会很惊艳它不只是“建议”而是直接动手改。5.2 让 Codex 真正理解项目上下文很多人用 Codex 觉得效果一般可能是因为只把它当聊天窗口用没有充分利用它的目录感知能力。Codex 会看到当前目录的文件列表但不会自动把每个文件的完整内容都硬塞进上下文。文件太多、太大时它只会读取部分关键文件或者等你在对话里提到某个文件时才去读。所以最实用的技巧是在提问时直接指明文件路径。比如“看下src/utils.py里的parse_date函数为什么它处理 2024-02-30 这种日期会出错”。这样 Codex 会主动去读那个文件的对应部分回答更精准。还有一个命令要记住在 REPL 里输入!或/可以执行一些特殊指令。不同版本指令略有差异但/help基本通用可以随时查看当前版本支持哪些快捷操作。实际用下来我还有一个重要心得把需求说得越接近“你在给同事派活”越好。比如不要只说“优化一下这段代码”而是说“这个函数在数据量超过 10 万行时会超时帮我改成流式处理并补一个简单的基准测试”。Codex 在这种具体任务上的完成度比那种模棱两可的“帮我改改”要高好几个档次。5.3 自动执行命令好用但危险Codex 最让我惊讶的功能是它能执行终端命令。比如它写了一个测试脚本然后直接运行测试把测试结果拿回来判断自己写的代码对不对。这个功能在auto_execute true时非常丝滑但风险也不小。有一次它为了确认目录结构打算执行rm -rf删除一个临时目录虽然目标目录是我创建的但它弹出确认框的时候我还是心头一紧。我的建议是新手阶段保持auto_execute false让它每次执行命令前都征求你的同意当你熟悉了它的行为模式再逐步放开。尤其是在有 git 仓库的目录里放开之前一定要确认git status是干净的否则一旦它乱改文件你回滚都麻烦。6. 问题排查与避坑实录6.1 安装与启动阶段的常见报错先整理一份我遇到过的安装、启动阶段问题速查表现象原因解法codex命令找不到npm 全局路径没进 PATH检查 Node.js 安装目录把 npm 全局 bin 目录加入 PATH启动时报Cannot find moduleNode.js 版本太老升级到 Node.js 18推荐 20 LTS提示需要登录 / 登录不上没有配置 provider或 OAuth 流程中断优先用 API Key / 本地 provider 方式绕过登录确认 config.toml 的 base_url 正确提示no model providermodel_provider引用的别名不存在检查[model_providers.xxx]里的别名是否和顶层引用一致每次启动都很慢首次扫描大目录先在小目录里测试熟悉后再切换到真实项目登录问题是很多人卡住的第一道坎。Codex 默认逻辑是先走 OpenAI 账号 OAuth 登录但如果你根本不想用云端账号直接配置一个本地或第三方 provider就不会触发登录流程。我自己在 Windows 上遇到过 OAuth 页面打不开、回调链接无法处理的情况最后就是用本地 provider 绕开的干净利落。6.2 接口对接阶段的常见报错接入本地模型时的报错绝大多数都指向同一个根源base_url 或 wire_api 配置不正确。这里列三个最典型的第一个请求 404。如果你在日志里看到类似 “failed while handling codex endpoint /responses” 的报错多半是 Codex 把请求发到了/responses端点而你的本地服务只支持/chat/completions。解决办法就是在 provider 配置里显式加wire_api chat。这个坑非常隐蔽因为 base_url 看起来完全正常很多教程也不会特意提。第二个401 / 403 鉴权失败。本地 Ollama 默认不鉴权如果你在 base_url 后面多写了一些路径或者 Ollama 开启了 token 校验就会出现这种情况。先确认 curl 直连是通的再排查配置。第三个模型返回空内容。常见原因是模型上下文窗口太小Codex 一次性塞给模型太多内容模型直接吐空。这时候要么换一个上下文窗口更大的模型要么在项目目录里减少无关文件降低上下文压力。6.3 本地模型效果与性能优化建议最后说说效果。必须承认本地模型写代码的能力和 OpenAI 官方模型有差距特别是在复杂架构设计、跨文件重构这种需要很强“全局观”的任务上本地模型会显得保守生成的代码偶尔有啰嗦和重复。但在日常任务上比如写单元测试、写 SQL、做数据清洗、修 bug、解释代码Qwen2.5-Coder 系列的完成度已经非常高。我的经验是把任务拆细一次只让 Codex 做一件事本地模型的效果会明显提升。性能方面也有一些优化空间。Ollama 默认会占用一部分内存做 KV cache如果你的模型运行不稳定可以调整 Ollama 的环境变量控制并发和缓存占用。CPU 推理的朋友建议选量化模型比如qwen2.5-coder:7b-q4_K_M速度会快很多。另外Codex 的交互默认是流式输出的如果你觉得终端滚动太快可以在配置里调整输出方式但这只是观感问题不影响最终结果。最后分享一个我个人用得最舒服的小技巧把 Codex 的配置文件里同时保留官方云端 provider 和本地 provider日常用本地模型省钱省心偶尔碰到特别棘手的难题临时切回云端模型救场。两个 provider 在同一个 config.toml 里互不干扰切换只需要改一行model_provider。这个思路可能是 Codex 本地部署最大价值所在——你既拥有了完全本地、隐私可控的开发助手又没有放弃随时调用更强模型的能力。整个体验下来我觉得 Codex 加上本地大模型这套组合已经是当前开源工具链里最接近“私人编程搭子”的方案了非常值得你花一个下午把它跑通。