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_MODELS1或者手动调用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编程的理解会深一个层次。