说说最近一直在折腾的一个东西Codex。准确讲是 OpenAI 开源的 Codex CLI一个跑在终端里的 AI 编程助手。我把它的下载、认证、接本地模型、日常使用全流程都踩了一遍最折腾的是把 Codex 从只能连云端 API变成可以连本地部署的大模型让整个编程助手真正在本地跑起来。这篇文章把我整套实操记录整理成一份可直接抄作业的部署手册适合三类人买了显卡想跑本地模型但又不想丢掉 AI 编程体验的开发者、不想把代码片段交给外部 API 的隐私敏感型程序员、以及单纯想试试终端里 AI 怎么写代码的折腾型选手。先说结论折腾 Codex 本地部署核心不是装 Codex 本身而是怎么让 Codex 听话地接上你本地的大模型。装 Codex 一条 npm 命令就完事难点在后面的模型接入、配置文件、登录认证和一堆奇奇怪怪的报错。下面的内容我尽量按先想清楚再动手的顺序组织不说废话全是实操记录。1. 先搞清楚 Codex 的部署形态云端、兼容接口、纯本地1.1 三种常见运行形态很多人第一次接触 Codex 会懵这东西到底是本地程序还是纯云服务其实它是个本地客户端 远端大脑的组合大脑可以有不同的后端。目前我实际用下来常见形态就三种。第一种是官方默认形态本地装好 Codex CLI模型跑在 OpenAI 那边你本地负责调用 API、把问题抛过去、再把回答流式打印到终端。这种形态最省心模型能力也最强但前提是你得有一个能正常访问 OpenAI 接口的网络环境并且有对应的账号密钥。第二种是接一个 OpenAI 兼容的第三方 API 服务。现在很多大模型服务商都做了 OpenAI 兼容接口Codex 自己不挑食只要能在配置文件里把它的 base_url 指过去就能把大脑换成另一家。比如博主圈里很多人提到的把 Codex 接入 DeepSeek本质就是改了 base_url 和密钥响应能力依然在线。第三种就是我标题里说的本地部署形态Codex 的推理后端换成 Ollama 这类本地推理服务模型跑在你自己的机器上。中间没有任何外部参与代码、对话记录、生成结果全都留在本机。这种形态能力上限取决于你机器能跑动的模型大小但胜在完全可控、隐私拉满、断网也能玩。1.2 本地模型 vs 云端 API到底图什么我自己把三种形态都试过之后对为什么本地部署心里有了很明确的答案。如果你平时写代码对 AI 依赖特别重又不希望每敲一句话都往外部服务传一次代码片段本地模型就是很自然的选项。尤其是处理公司内部代码、敏感业务细节、未公开的项目结构云端的任何一次调用在心理上都是一道坎而把模型拉到本地后这个问题从根上消失了。当然本地部署的代价你也得认。我实测下来同样一段重构需求云端顶级模型能给一个相当聪明的方案本地 7B 量级的模型给出的代码可能只有能跑的水平。本地模型还需要显存支撑14B 量化模型大概要 10GB 到 12GB 显存7B 也要 6GB 到 8GB。所以如果你是个侧重代码生成的开发者本地部署更适合把它定位成不会泄密的干杂活助手而不是上来就指望它能替代所有云端的判断力。不做选择题的做法是同一台机器同时配置官方 API 和本地 Ollama普通敏感任务走本地复杂逻辑推理走云端用配置文件随时切换。1.3 部署前的准备工作清单这里列一下我实际操作后觉得必须准备好的东西少一样后面都会卡壳。第一是 Node.jsCodex CLI 本身是个 npm 包安装和运行都依赖 Node建议装 18 以上版本。第二是 Git很多被 Codex 管理的项目或者后续提 pr 的流程会用上。第三是终端与基本命令能力Windows 用户建议直接上 Windows Terminal别用老掉牙的 cmd不然输出里的中文和颜色代码都很遭罪。如果你选择本地模型形态还要额外装一个 Ollama 或类似的推理服务。我主力用的是 Ollama因为它跨平台、命令简单、自带 OpenAI 兼容接口跟 Codex 对接时配置量最小。这一套准备好之后整个下载 本地部署的骨架就出来了后面所有步骤都围绕这套骨架展开。2. Codex 下载与安装命令行优先桌面版看情况2.1 npm 一条命令装好 Codex CLICodex CLI 官方推荐的安装方式就是 npm 全局安装。在终端里执行npm install -g openai/codex这条命令会在全局目录里装上 codex 可执行文件。装完先确认版本能正常输出说明安装成功codex --version我第一次装的时候在 mac 上很顺在 Windows 上稍微麻烦点因为 npm 全局路径可能不在 PATH 里。遇到codex不是内部或外部命令的报错时先执行npm config get prefix看看全局安装目录再把那个目录加到系统 PATH。Windows 下我用的实测命令是npm config set prefix $env:APPDATA\npm然后重新开一个终端窗口再执行codex --version。这一步在 Windows 上算是高频坑群里有朋友就卡在这儿半天没进下一步。npm 安装完成后首次运行codex会进入一个引导式登录流程。它会给你一个登录链接跳转到浏览器完成授权再把授权码贴回终端。这个流程本身很傻瓜但我后面会专门讲登录遇到的坑。2.2 桌面版与 Windows 环境注意事项除了命令行版OpenAI 后来也出过 Codex 的桌面应用我身边确实有不少人搜 codex 安装 windows 桌面版。桌面版的好处是自带界面、不用跟终端命令打交道但我的实际感受是命令行版的灵活性和被脚本化的能力是桌面版比不了的。作为 AI 编程助手终端版天然离项目目录更近——你打开终端时本来就已经站在项目里Codex 直接就能看到上下文不用像桌面应用那样去配置打开哪个项目。所以这篇部署实战还是以 CLI 为主桌面版作为补充提一嘴。Windows 下除了 PATH 问题还有两件事值得注意。一是把终端代码页切到 UTF-8不然中文输出大概率乱码二是尽量用普通用户目录下的项目文件夹来跑 Codex放在系统盘根目录或者 Program Files 里经常会碰到写文件权限问题。我踩过一回在C:\Program Files下让 Codex 创建文件直接权限拒绝换个工作目录就没事了。2.3 首次登录认证与组织设置问题Codex 登录主推 OpenAI 账号登录。执行codex login后会生成一条链接浏览器打开后登录授权然后把浏览器里生成的 code 贴回终端。这里我踩到的第一个大坑就是反复提示登录不上浏览器已经授权成功终端却一直卡在等待确认。后来我确认是终端和浏览器之间的 Socket 连接没有建立成功具体表现为codex login长时间无响应。最简单的解法是直接选中生成的登录链接在浏览器里手动完成授权之后看终端有没有新的 URL 提示有时重新执行一次codex login反而更快。另外就是登录后报无法加载组织设置这类提示。这个现象我遇到时第一反应是自己账号有问题但换了个网络环境后很快就加载出来了。如果你只有一个组织账号大概率是会话过期或者网络连通性波动重新登录一遍就能恢复。如果你绑定了多个组织还要注意 Codex 默认加载哪个组织这决定了它读取审批规则、模型策略的归属影响后续使用时的默认行为。还有一点很多用户第一次直接通过export OPENAI_API_KEY...的方式使用绕开登录。这么做理论上也能跑但官方主推的登录方式对组织设置支持更完整。我的建议是把登录流程走完万一哪天脚本需要调用组织级配置不会重新摸索。3. 搭一个本地模型后端从 Ollama 到 Codex 的全部接线3.1 Ollama 装好再拉一个编程专用模型本地部署的核心是把模型推理跑在自己的机器上。我选 Ollama因为它把模型管理、推理服务、OpenAI 兼容接口全包了。安装很简单macOS 和 Linux 直接执行curl -fsSL https://ollama.com/install.sh | shWindows 用户去官网下载安装包双击安装装完在终端验证ollama --version。装完 Ollama 后要拉模型。做 AI 编程助手我强烈建议用代码专项模型。目前我主力用的是qwen2.5-coder:14b这是阿里 Qwen 系列的代码模型代码能力在同体积模型里相当能打而且对中文理解很自然。拉取命令ollama pull qwen2.5-coder:14b如果没有 14B 显存条件的机器也可以降级到qwen2.5-coder:7b效果差一些但胜在跑得动。拉完模型后后台的服务默认会一直在跑Ollama 默认监听本机的 11434 端口这个端口就是后面 Codex 要连的地方。3.2 把 Codex 指向 Ollama 的关键配置Codex 默认只知道怎么连 OpenAI 官方要让它连 Ollama 需要改配置文件。这个文件放在用户目录下Windows 是%USERPROFILE%\.codex\config.tomlmacOS 和 Linux 是~/.codex/config.toml。第一次运行 Codex 后通常会自动生成没有就自己新建。我实际在用的完整配置长这样model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name ollama base_url http://127.0.0.1:11434/v1 env_key OLLAMA_API_KEY wire_api chat逐行说下这几个字段的含义这是整个部署的关键。最上面的model字段值必须和 Ollama 里已有的模型名完全一致我用的是qwen2.5-coder:14b。model_provider字段写的是下面 providers 配置里的名字ollamaCodex 靠这个字段知道你现在想走哪条后端线路。下面[model_providers.ollama]里base_url指 Ollama 的兼容接口地址这里一定要写成http://127.0.0.1:11434/v1。注意/v1这个后缀不能省Codex 会用 OpenAI 的接口路径去拼少了它必然 404。env_key告诉 Codex 用哪个环境变量取密钥。Ollama 本地本身不需要密钥但 Codex 要求必须有这个字段所以我在 shell 里随便设了一个占位值export OLLAMA_API_KEYollamawire_api chat则指定走 chat completions 接口格式Ollama 对这个兼容得很好。配置完保存文件重启终端进入项目目录后直接执行codex。如果一切正常Codex 会基于本地模型开始对话。第一次跑我会建议先用一句最简单的话验证链路通不通比如让它打印 hello world或者直接让它介绍自己是什么模型。能正常回复链路就算打通了。3.3 DeepSeek 等 OpenAI 兼容服务同样很香如果你不执着于内网但对 OpenAI 官方模型的账单有意见接一个兼容服务商是很合理的折中。网上特别多人搜codex 接入 deepseek因为 DeepSeek 的代码能力很强价格也便宜配置方案跟本地 Ollama 几乎一模一样只是把 base_url 换成 DeepSeek 的接口把密钥换成真实密钥。我的配置文件里保留了一段 DeepSeek 配置随时切换[model_providers.deepseek] name deepseek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat切到 DeepSeek 时把最上层的model_provider deepseek并把model改成服务商对应的模型名比如deepseek-chat。然后导出真实的密钥export DEEPSEEK_API_KEY你的真实密钥这里要重点提醒model_provider和model一定得配套好多人本地和云端配置混着用结果 Codex 拿着本地的模型名去请求 DeepSeek 接口自然一路 404。切换后端本质就是改顶层这两个字段环境变量顺手换掉逻辑简单出错基本都出在名字对不上。4. 实操在真实项目里用 Codex 干活4.1 日常最常用的几种调用姿势装好配好之后怎么用得顺手才是重点。我平时最常用的几种方式一是单发指令模式把任务直接写在命令后面比如codex 给这个Python文件写一份完整的单元测试Codex 会先读取当前目录和指定文件结合上下文自动生成测试代码甚至会询问是否直接创建对应文件。二是交互对话模式直接在终端里执行codex进入会话随后想到什么问什么。比如你可以让它 Review 刚写的一段函数也可以让它解释某段晦涩逻辑还可以让它拆解一个复杂需求。三是带参数模式比如codex --verify会在生成代码后用内置沙箱检查代码是否能正确执行codex --write允许它直接修改文件而不用每次都征得同意。这几个参数在你对模型比较信任的时候能明显提升干活速度。交互模式下还可以随时输入/help查看可用指令我记不住的时候全靠它。4.2 一次完整任务演示从需求到收尾我拿一个真实小任务演示完整流程。场景在一个 Python 项目里我需要一个工具函数把多层嵌套的 JSON 拍平成一行便于日志记录。我直接在项目根目录跑codex 写一个函数把嵌套 dict 拍平成带点号的扁平结构值如果是 list 则带索引要求不修改原对象Codex 读完项目后给了我一段还不错的实现但第一次生成里list的处理不如我意我就在交互会话里追加要求list 索引用 [0] 这种写法不要用点号。它立刻改了方案并输出新代码。我在会话里确认没问题后直接说保存为 flatten_json.py它生成了文件。这种多轮修订能力是 CLI 版最大价值。如果说模型是实习生交互会话就是你在实习报告上的批注一套组合下来产出能达到可用的程度。那次任务的收尾阶段我顺手让它给函数补了几条边界测试用例整个过程没有切换过窗口体验还挺流畅的。4.3 让 Codex 更懂你的项目规则文件与上下文策略用久了会发现Codex 默认对项目的理解是散装的除非你主动告诉它项目规范。好在 CLI 支持通过 AGENTS.md 这类规则文件约束行为。我在项目根目录放一个AGENTS.md在里面写清楚代码风格、测试要求、提交信息格式、关键目录作用。Codex 每次启动时会把规则文件作为上下文加载回答风格立刻就正经了不少。另一个重要技巧是缩小上下文。Codex 会读取当前目录的文件列表但不会把整个项目塞进上下文。如果你有特别大的目录不想让它扫描可以在项目里配 ignore 规则把node_modules、dist、.git这类目录排除掉。这能大幅降低本地模型的上下文负担尤其是跑 7B、14B 这类小模型时上下文一旦被无关文件占满回答质量肉眼可见地下降。5. 常见问题与排查速查表我踩过的坑都在这5.1 切换本地模型后报错信息里带 codex endpoint /responses这是我第一次接 Ollama 时遇到的第一个大问题。当时我在 Codex 里切换本地模型然后控制台直接报了一大段错错误信息里反复出现codex endpoint /responses字样同时cc switch本地切换流程失败整个会话直接中断。这个现象看起来吓人但排查半天后发现原因极其朴素我忘了启动 Ollama 服务。Codex 配置写好了但后端根本没人接单自然所有请求都失败。各位记住本地模型形态下Ollama 必须保持运行可以用ollama serve手动拉起。同时还要确认端口没有被占用测试一下curl http://127.0.0.1:11434/v1/models能返回模型列表就说明后端活着。如果 curl 正常但 Codex 依旧报错就要看config.toml里的base_url是否带上了/v1少这个后缀我后来也遇到过经典的 404。5.2 登录不上、组织设置加载不出来登录问题在第一次使用和换设备时特别常见。表现形式有几种浏览器已经授权终端卡住不动登录成功但提示组织设置加载失败或者干脆报一个含糊的网络错误。我的排查顺序是第一步检查网络连通性curl 一下登录相关域名能通再看下一步。第二步清掉本地缓存凭证删掉~/.codex/auth.json或对应登录态文件重新执行codex login。第三步是确认账号是否绑定了多个组织如果绑定多个组织启动时 Codex 需要拉取组织信息网络波动就会卡住。此时重新登录多试一两次基本上就能好。另外有朋友遇到过浏览器授权成功但终端没有反应的情况我试过最简单的办法是断掉终端会话重开再跑一次codex login。这问题多半出在本地一个临时会话状态上重开终端反而比反复等待有效。5.3 本地模型连不上、响应慢、上下文截断本地部署最常见的抱怨是模型回复质量一般响应非常慢。响应慢的原因通常逃不开三个模型太大、上下文太长、显存不够。检查显存占用如果接近上限说明模型在 CPU 和 GPU 之间反复切换速度不可能快。解决办法是换更小的量化版本或者用 7B 模型替代 14B。上下文截断这个问题我之前也遇到过本地模型上下文窗口相对较小一个长文件塞进去再写几轮对话后面的内容直接溢出。我的应对是主动拆任务一次只让 Codex 处理一个文件别拿整个项目去问。这样既能保证质量也不容易被截断算是我用本地模型总结出的第一条经验。还有个小坑本地模型偶尔会把中英文混在一起输出。此时在对话里明确要求全部用中文回答大多数情况下能立刻纠正。如果纠正不了说明模型能力有限那就该考虑换更大模型或者临时切到云端。5.4 高频小坑清单根据我和周围朋友的实际踩坑记录整理了一个速查表按出现频率排现象常见原因解决办法安装后 codex 命令不存在npm 全局目录不在 PATH检查 npm config get prefix把目录加入 PATH中文显示乱码终端代码页或字体问题Windows 切 UTF-8 代码页终端用现代字体配置了本地模型但仍请求外部地址顶层 model_provider 没改成 ollama检查 config.toml 顶层字段模型名错误model 与本地实际模型名不一致ollama list 查看真实名字再改配置权限拒绝在系统目录下运行 Codex换到用户目录下的项目目录找不到配置文件config.toml 没生成先运行一次 codex 让它生成再手动编辑输出总是英文没有声明偏好在 AGENTS.md 里写默认用中文回答这张表基本能覆盖掉绝大多数新手的拦路虎。真遇到表里没有的问题我的通用手段是打开 Codex 的日志输出看它到底报什么协议层面的错误再顺着错误关键词去搜自己多半能定位。6. 一点经验之谈与后续扩展6.1 我实际最推荐的本地配置组合折腾这么多之后说说我现在稳定在用的组合。日常主力是qwen2.5-coder:14b跑在 Ollama 上显存占用约 11GB我用的是 16GB 显存显卡刚好能留出余量跑系统界面。所有非敏感任务都在这个组合上做配合 Codex 的自动写文件和沙箱检查写工具脚本、补测试用例、改配置这类重复劳动已经基本不用自己动手了。遇到特别复杂的架构设计问题我会临时切到 DeepSeek 或者官方 API。用一句话总结我的选择逻辑看数据敏感度和任务难度。数据敏感优先本地任务难度高优先云端两者不冲突时让本地模型先试不行再切。这也算是我对本地部署到底图什么这个问题的最终回答——不是非此即彼而是多一条可控的路线。6.2 有边界意识地用 AI 编程助手最后说个感受层面的体会。本地部署给了我们完全掌控的体验但 AI 编程助手终究只是工具该审的代码还是要审。有一次本地模型帮我写了一段数据库迁移脚本逻辑看着很通畅结果一跑才发现它把索引名拼错了。这类问题在云端大模型上少见但在本地 14B 模型上并不罕见所以别因为在本地部署就觉得绝对安全——安全是数据层面的代码质量依然需要人的判断兜底。后续我打算在这个配置上继续扩展两件事一是尝试接进更多代码专项模型比如把不同模型配置成不同 provider根据任务类型切换二是把 Codex 接入到我自己的自动化脚本里让它在 CI 流程中主动 review 提交的代码。这篇实战就到这儿如果你也在折腾本地部署照着上面流程走顺利的话半小时内就能让 Codex 在你自己的机器上开始干活。