Codex这个词，最近在我常逛的几个技术社区里几乎天天出现。它本质上是一个AI编程助手，OpenAI出的，和你在网页里聊代码不同，Codex是直接嵌进终端的，你给它一句自然语言任务，它就能在当前工程目录里读文件、改文件、执行命令，像个随时待命的结对程序员。我一开始直接用官方云端接入，确实省心，但用了两个星期之后，几个坎实实在在摆在我面前：代码内容全部传到云端，有些项目不敢放进去；云端服务的计费方式对频繁的小任务不友好；另外就是网络环境时好时坏，严重影响交付节奏。所以我决定彻底折腾一遍本地部署——把Codex这个壳装好，再把推理底座换成自己能控制的大模型，整套方案跑通了之后，确实顺心了很多。
这篇文章不是官方文档的翻译，而是我实际部署过程的完整记录。会从环境的检查讲起，覆盖Codex命令行工具的下载安装、登录认证、配置文件解析、如何接入Ollama和DeepSeek这类本地模型服务，最后再把我撞过的墙都整理出来。只要你有一台能跑得动大模型的电脑，哪怕没有高端显卡，也有办法用轻量模型先跑通全流程。如果你想在隐私、成本和可控性之间找到平衡，这篇文章应该能帮你少走不少弯路。
1. 为什么要把Codex部署到本地
1.1 Codex到底是什么，能帮你做什么
Codex是OpenAI推出的智能编程工具，核心是一个CLI（命令行接口）以及配套的桌面应用。它和普通的代码补全不一样：你告诉它“帮我修一下登录接口的边界条件”，它能自己定位相关文件、生成补丁、执行测试，把改动的结果反馈回来。它支持的场景包括修复bug、写单元测试、批量重构、解释陌生项目、自动生成提交信息等，基本覆盖了日常开发里那些机械化又费时间的环节。
对喜欢在终端工作的开发者来说，Codex的高频使用方式有两种。一种是交互模式，进入一个类似会话的界面，像和同事对话一样描述需求；另一种是一次性执行模式，通过codex exec把任务描述直接传给它，适合集成到脚本和CI流水线里。这两种模式在后面实操章节里我会分别演示。
1.2 为什么要本地部署，而不是直接用云端
我总结了三条理由。
第一，数据隐私。公司项目和个人代码里有大量不想外传的内容，云端模式等于把整个仓库交给别人，这在不少开发场景里是不可接受的。本地部署之后，模型推理在你的机器上完成，代码不出本机，心里踏实很多。
第二，费用可控。云端按token计费，看起来单价不高，但真实开发中一个会话动辄消耗几十万token，长期下来中高强度使用一个月几百块很常见。本地部署后，模型本身免费，电费成了主要成本，这对个人开发者和独立工作室尤其友好。
第三，调试自由。你可以随时换模型、调参数、改提示词模板，没有平台限制。想从qwen2.5-coder切到DeepSeek，改几行配置就行，这种灵活度是云端方案给不了的。
当然，本地部署也有代价。没有云端那么强的硬件能力，小显存只能跑小模型，跑大任务的响应速度和生成质量会打折。所以我的定位是：本地模型处理日常任务，云端模型留给特别复杂的任务。
1.3 总体架构选型：Codex CLI + Ollama + DeepSeek
整个本地部署方案由三层组成：交互控制层、模型调度层、推理引擎层。
交互控制层就是Codex CLI，负责接收你的自然语言指令，维护会话上下文，调用底层模型，把代码改动展示出来。模型调度层我用的是Ollama。Ollama是一个本地大模型运行工具，安装之后一句命令就能把模型拉下来跑起来，而且自带了兼容OpenAI的接口，这样Codex不需要任何额外开发就能连上它。推理引擎层我主要跑两类模型：一类是通用编码模型，比如qwen2.5-coder系列；另一类是DeepSeek的编码模型，可以通过Ollama运行开源权重，也可以调用DeepSeek的云端API作为后备。
我选Ollama而不是手动部署推理服务，图的是省事。它的模型管理做得很好，模型文件、量化版本、上下文长度都封装好了，适合不打算研究底层推理细节的人。如果你之后想上vLLM这样的高性能推理框架，Codex的配置方式也是一样的，只要把base_url换掉即可。
2. 下载安装与环境准备
2.1 检查你的机器够不够格
在动手下载Codex之前，我强烈建议你先花两分钟检查环境。Codex CLI本身基于Node.js，所以第一步是确认Node版本。我用的是Node 20，跑在Windows和Linux上都正常。如果你的Node版本低于18，官方会直接拒绝安装或运行时报语法错误，我建议直接升级。
接下来看硬件。模型推理是吃显存的大户，这里我给一个大概的参考线：
- 纯看流程跑通：8GB显存或16GB内存，推荐qwen2.5-coder:7b、deepseek-coder-v2:lite这类轻量模型。
- 日常轻量开发：12-16GB显存，推荐qwen2.5-coder:14b，性价比最高。
- 要求较高：24GB显存或更高，可以上32B级别的量化模型。
如果用的是Mac，统一内存16GB起步，M系列芯片跑14B量化模型是可行的，就是速度不要指望太快。16G显存这个配置在社区里讨论很多，实际体验下来，跑14B模型刚好卡在“能用”和“舒服”的分界线上，既能处理中等复杂度的代码任务，又不会把显存占满导致其他程序没法用。
另外提醒一个容易踩的坑：Ollama默认会把模型常驻显存，如果连续跑好几个不同的模型，显存可能不够。建议在配置里设置OLLAMA_MAX_LOADED_MODELS=1，或者手动调用ollama stop把不用的模型卸载。
2.2 Codex命令行工具安装
Codex的安装方式根据平台略有区别。官方推荐使用npm全局安装，命令很简单：
npm install -g @openai/codex安装完成后，执行codex --version确认版本号。我装的是0.3.x，后面的配置说明都以这个版本为例。
这里提醒一下，如果你的npm配置了比较严格的镜像源，装完后可能发现codex命令找不到。这种情况通常需要把npm的bin目录加到PATH里，Windows上一般会自动处理，Linux下可能要手动加一下。还有，如果之前装过旧版本的codex，建议先卸载干净再装新版，我遇到过旧配置文件和新版不兼容导致启动卡住的问题。
如果在Windows上想用得更顺手，可以关注一下官方提供的桌面版和Linux子系统版本。我个人更推荐在Linux子系统里部署，因为Linux环境下面命令行的体验更完整，很多开发者本来就在里面做开发，Codex直接装在同一环境里，读写文件、执行命令都没有跨系统的别扭感。
2.3 登录与账号认证
安装好之后，第一步登录。执行codex login，它会打开浏览器让你授权，用GitHub账号或者OpenAI账号都可以。授权成功之后，本地会保存一份凭据文件，后续请求会自动带上。
这个环节我遇到的坑主要有两个。一个是在无桌面环境的服务器上登录，浏览器弹不出来。解决方法是执行codex login --headless，它会输出一个URL，你手动在任意一台电脑的浏览器里打开、授权，再把回调码贴回终端。另一个是授权成功后codex还是提示未登录，通常是本机时间不准导致令牌校验失败，校准系统时间后重新登录就好了。
登录这一步的目的是拿到官方服务的使用权限。如果你后面只打算用本地模型，仍然建议先用官方账号登录一次，把Codex的初始化流程走通，后面的配置对比起来也更清晰。
3. 核心配置：让Codex认识你的本地模型
3.1 配置目录与文件结构
Codex的配置放在用户目录下的.codex文件夹里，里面核心就两个文件：config.toml是全局配置，config.local.toml是本地覆盖配置，一般放个人私有的密钥和偏好。后面还有AGENTS.md这类文件用来指导模型行为，属于进阶玩法，先放到一边。
我建议修改配置前先备份原始的config.toml，因为你不知道自己会改出什么问题来。Codex对配置格式比较敏感，少一个引号、多一个括号，启动时都会直接报错，而且报错信息有时候很隐晦，备份能让你快速回滚。
用文本编辑器打开config.toml，你会看到类似这样的基础结构：
model = "gpt-5-codex" model_provider = "openai"这两行定义了默认模型和模型提供方。我们本地化要做的事情，就是新增一个model_provider指向本地服务，然后把默认model换成本地模型的名字。
3.2 多Provider配置解析
Codex在较新的版本里支持配置多个模型提供方（Provider），这是本地部署的关键。每个Provider由四部分组成：名称、接口地址、密钥读取方式和接口协议类型。
我实际使用的provider配置是这样的：
[model_providers.ollama] name = "Ollama Local" base_url = "http://localhost:11434/v1" env_key = "OLLAMA_API_KEY" wire_api = "chat"解释一下这四个字段：
base_url是本地推理服务的OpenAI兼容接口地址，Ollama默认跑在11434端口，路径统一是/v1。env_key告诉Codex从哪里读取API密钥。本地服务其实不需要真实密钥，但Codex会强制校验环境变量是否存在，所以随便设一个变量名，比如OLLAMA_API_KEY，给它赋一个任意值就行。wire_api指定Codex用哪种协议和模型服务通信。可选值一般是responses或chat。强烈建议这里写chat，因为Ollama只实现了OpenAI的chat补全接口，Codex默认的responses协议在本地模型上跑不通。
设置好provider之后，再修改默认模型配置：
model = "qwen2.5-coder:14b" model_provider = "ollama"然后执行codex，你会发现它开始向本地11434端口发请求了。整个本地接入的核心就是这四行配置，没有多复杂，关键是理解base_url和wire_api的作用。
3.3 用Ollama搭一个本地推理服务
Ollama的安装本身很简单，Windows和macOS直接下载安装包，Linux用官方脚本。装完后执行：
ollama pull qwen2.5-coder:14b这条命令会把模型从模型仓库拉到本地。模型仓库的下载速度在不同网络环境下差异很大，如果拉取卡住，建议配置镜像源，或者直接去ModelScope拉取Ollama格式的模型包手动导入。我最初就是卡在模型下载这一步，换了镜像源之后速度快了非常多。
模型拉取完成后，运行服务：
ollama serveOllama默认监听127.0.0.1:11434。因为Codex和Ollama在同一台机器上，这个默认地址就够了，不需要改监听配置。如果你的Codex装在容器里而Ollama在宿主机上，要设置OLLAMA_HOST为0.0.0.0并且在容器里用宿主机IP访问，但这属于进阶场景，普通用户不要贸然把服务暴露到局域网，有安全隐患。
验证服务是否正常，可以用curl看接口：
curl http://localhost:11434/v1/models如果返回了模型列表JSON，说明推理服务已经就绪。
3.4 接入DeepSeek：两种方式对比
DeepSeek可以走两种接入方式，我建议两个都配置好，平时切换用。
第一种，本地跑DeepSeek的开源编码模型。通过Ollama拉取deepseek-coder-v2:16b这类中尺寸模型，配置方法和上面完全一样，只需要把model字段改掉。这种方式的优点和所有本地部署一样，数据不出本机；缺点是模型规模受限，复杂代码理解能力和云端大模型比还是有差距。
第二种，调用DeepSeek官方API。DeepSeek的接口兼容OpenAI格式，所以可以直接作为一个远程provider接入Codex，配置写法如下：
[model_providers.deepseek] name = "DeepSeek API" base_url = "https://api.deepseek.com/v1" env_key = "DEEPSEEK_API_KEY" wire_api = "chat"然后在环境变量里填入DEEPSEEK_API_KEY，再把model设为deepseek-chat。这种方式不用本地显卡，速度和响应质量都接近云端大模型，但会产生API费用，并且代码会经过第三方服务器，隐私级别和完全本地部署不一样。
我个人的用法很明确：日常快速改脚本、调路径这种任务，切到本地模型；遇到复杂的架构调整、重构、需要深度理解项目上下文的任务，临时切到DeepSeek API。一个值得说的体验是，本地跑14B模型虽然绝对能力不如云端，但配合Codex的上下文管理，很多日常任务完成得像模像样，毕竟Codex的工程能力很大程度上来自工具链本身，模型只负责生成代码片段，对推理能力的敏感度并没有想象中那么高。
4. 实操：从第一句提示词到完成一个真实任务
4.1 首次对话与基本参数说明
配置全部就位之后，在项目目录下直接执行codex，进入交互模式。你会看到一个对话输入框，可以开始提需求。
第一个建议是先问一个简单问题来验证链路是否通，比如“这个项目的入口文件是哪个？”。如果模型正常响应，说明Codex、Ollama、模型之间的链路全部打通。如果在这个环节就出现超时或者报错，大概率是配置里的base_url或者wire_api不对，先回到上一章的配置检查。
Codex交互模式里有两个参数我希望你一开始就知道。一是--model可以临时指定本次会话的模型，比如codex --model deepseek-chat，用于偶尔跳到云端模型而不改配置文件；二是-c参数进入简洁的一次性问答模式，适合快速验证一个想法，不保留会话上下文。这两个参数配合起来，日常开发和调试的效率会高很多。
4.2 实际演示：修复一个真实的Bug
我拿自己项目里的一个真实案例来说明整体工作流。假设某个接口偶尔报500，页面提示“request body is empty”。按照以前的流程，我得打开日志看报错，再进代码里找请求体校验逻辑，可能还要查上下游调用方，前后少说二十分钟。
用Codex就简单多了。我在项目目录下执行codex，输入提示词：
“排查这个接口偶尔返回500的问题，提示request body is empty，重点检查参数校验和中间件，查出原因后直接修复，并补上对应的单测。”
Codex会自己去读相关文件，搜索关键代码，然后生成修改方案。在交互模式下，它可以调用终端来运行测试，看到测试结果之后继续调整，直到把问题解决。这种“读代码→改代码→跑测试→看结果→再改”的循环，是Codex最值钱的工作模式。用官方云端模型时这个循环执行得特别流畅，切换到本地14B模型后也能完成，但复杂逻辑修改时可能需要你多给几轮反馈。
4.3 把Codex装进VSCode
如果你习惯图形界面，Codex的VSCode扩展值得装一下。安装扩展之后，它能直接读取你当前打开的项目，在侧边栏开一个会话窗口，选中代码片段即可右键发送给Codex，要求解释、重构或补测试。VSCode扩展底层还是调用同一个Codex配置，所以本地模型的配置完全通用，不用重复设置。
我用下来觉得，VSCode侧边栏模式特别适合两种场景。一种是看陌生项目的代码，选中一段直接问“这段逻辑在做什么，有哪些边界情况”，比我自己慢慢读快得多；另一种是代码评审，让它从性能、安全、可读性三个维度挑问题，经常能指出一些我容易忽略的细节。但真正的大批量文件修改，我还是推荐回到终端里用codex exec，因为终端模式下的文件操作和命令执行能力更强，不会受编辑器插件上下文的限制。
4.4 中文对话设置与工作流建议
关于中文界面，Codex的新版本已经有语言设置，在配置文件里加一行：
lang = "zh-CN"重启之后界面提示会变成中文。不过我要提醒你，模型输出什么语言主要取决于提示词，跟界面语言是两回事。想让模型用中文解释，就在提示词里明确说“请用中文回答”，尤其在模型默认的英文思维下，不指定的话它经常给你回英文。
工作流上，我发现一个非常顺手的分层做法。简单明确的问答放到交互模式里，配合本地模型，速度快、零成本；中等规模的编码任务用codex exec跑，它能在一次执行里完成多文件修改，适合日常重构；最高难度的任务才切DeepSeek API。这样既控制了成本，又保证了每个场景的响应速度和隐私边界。
实际操作中还有一个建议：在项目根目录放一个AGENTS.md文件，把项目的技术栈、目录结构、代码规范写清楚。Codex在每次执行任务时都会自动读取这个文件，作为上下文约束模型行为。这个小投入的回报非常大，我第一次写完之后，模型生成的代码明显更贴合项目原有风格，不需要反复纠正。
5. 高频问题排查与避坑记录
5.1 登录不上、验证失败
登录问题是我被问到最多的。典型表现是执行codex login后浏览器没反应，或者授权成功后命令行依旧提示未登录。前者一般发生在没有图形界面的服务器环境，解决办法是用codex login --headless流程，获取一次性授权链接，在任意设备浏览器上完成授权。后者大概率是系统时间不同步导致令牌校验失败，校准时间再重新登录。另外Windows平台如果安全软件拦截了本地凭据写入，也会出现“明明登录了但每次都要重新授权”的现象，把.codex目录加入信任列表可以解决。
5.2 模型请求超时或一直转圈
Codex启动后输入问题，光标一直在转，最后报超时。这通常有三个原因：一是本地模型还在加载，第一次请求要把权重从磁盘读入显存，慢一点的机器等半分钟都正常，这不算故障；二是base_url端口写错，比如Ollama实际监听的是127.0.0.1:11434，而你写成了11435；三是服务根本没启动，执行ollama serve即可。还有一个小技巧：先手动调用一次接口确认服务正常，再回到Codex排查，别把两个问题搅在一起。
5.3 配置切换后端点请求失败
很多人在接本地模型时见过这样一个报错：Codex默认会请求/responses这个端点，而Ollama这类本地服务只实现了/v1/chat/completions，于是请求直接失败。这个问题的根因就是我前面反复强调的wire_api字段。默认的responses协议是官方云服务专用的，本地第三方服务基本都不支持。把provider里的wire_api从responses改成chat，问题立刻消失。如果你换了一个模型服务商，先确认它文档里写的是兼容chat接口还是responses接口，再决定这个字段。
5.4 无法加载组织设置
桌面版偶尔会报“无法加载组织设置”，通常发生在账号登录过期或者网络请求被拦截时。我遇到的情况是长时间挂着Codex桌面版，会话令牌失效，重新用codex login登录一次就能恢复。如果重登无效，把本地的.codex缓存清理掉再重新认证，也可以解决。这里要提醒的是，清理缓存前先备份配置文件，避免把自定义的本地模型配置一起删掉。
5.5 本地模型推理慢或显存不足
16G显存跑14B量化模型，体验大概是每秒生成十几二十个token，能接受但不快。如果觉得太慢，检查一下是不是上下文窗口开得太大。Ollama的环境变量OLLAMA_CONTEXT_LENGTH控制上下文长度，默认值设置过大时显存占用爆炸。可以先用小上下文跑通，再逐步加长。发现显存不足时，优先换更小的量化版本，比如从14B换成7B，而不是关掉其他所有程序。模型加载速度也受硬盘影响，把模型放在固态硬盘上会明显加快冷启动。
5.6 几条独家避坑经验
最后把我踩过、也看别人踩过的重复性最高的坑集中列一下。
第一，不要混用全局模型版本。之前我装过旧版Codex，配置目录里留了一些废弃字段，新版启动时直接忽略还好，怕的是解析器报错。升级前把旧配置全部清掉重新生成是最稳的。
第二，本地模型和云端模型切换时，注意确认当前provider。我经常切完之后忘了改设置，任务跑完才发现用的是云端，该保密的代码已经传出去了。建议在config.toml里把默认provider固定为ollama，云端调用用--model临时指定，从机制上避免误用。
第三，Ollama拉模型卡住不要反复重试，先看日志。很多时候是网络抖动导致的断点续传失败，删掉临时文件重新拉可能比重试十次都快。还可以考虑先通过ModelScope下载好模型文件再手动导入，一整条链路走下来体验会稳定很多。
最后说一点个人体会。我折腾这套本地部署方案，最大的收获其实不是省了多少钱，而是重新拿回了对工具链的控制感。以前我依赖云端AI编程助手时，模型更新、接口变动、限流规则，全都由服务商说了算，我只能被动适应；本地部署之后，模型想换就换，参数想调就调，连配置文件里每一行都是自己写明白的。当然，本地模型的能力天花板就在那里，我不建议一上来就把全部开发任务都压给它。更务实的做法是把它当作一个随时可用的基础助手，处理日常杂活，重要的架构决策仍然自己把控。这条路走起来不算轻松，但走通之后，你会发现自己对AI编程的理解会深一个层次。
