最近Codex的讨论量一下子就上来了作为OpenAI推出的AI编程助手它最大的卖点不是在聊天框里给你抄代码而是直接在终端里读项目、改文件、执行命令用法更像一个能动手干活的远程实习生。不过很多朋友卡在第一步下载完了登不上、组织设置加载失败、装了CLI不知道怎么配模型。这篇文章就把“下载、安装、配置、跑通”整条链路拆开讲核心重点是很多人真正关心的本地部署方向——把Codex的上游模型换成DeepSeek或者Ollama本地大模型让它成为一个完全可控的AI编程助手。1. 先搞懂Codex是什么再决定怎么装1.1 它不是“聊天窗口”是一个会动手的终端Agent先说一个最常见的误解。有人以为Codex是另一个ChatGPT网页版打开之后输入问题等答案。实际上Codex的核心形态是CLI命令行工具它以一种Agent的方式工作你给它一个任务描述它会先分析当前目录的代码结构、读取相关文件、生成修改计划然后直接改代码、跑测试、执行shell命令整个过程都在终端里可视化成一条条操作记录。这意味着什么意味着它的使用场景不是“问答”而是“执行”。比如你说“把登录接口的超时时间从5秒改成10秒并补充单元测试”它会自己去找到相关文件、定位代码、修改、运行测试然后给你看结果。如果你不满意某一步它还能基于历史记录回滚。这种工作流和传统的AI代码补全工具比如自动补全、聊天问答完全是两个维度。从架构上看Codex可以拆成两层上层是“操作框架”前端CLI、权限控制、命令执行、文件管理下层是“模型服务”真正负责理解和生成代码的大模型。官方默认接的是OpenAI自家的Codex系列模型但下层模型服务是可以通过配置替换的这就是本地部署所有可能性的来源。1.2 桌面版、CLI版和VS Code扩展怎么选Codex目前有好几种使用形态很多人下了一堆版本之后反而乱了。我用下来之后建议按下面这个表来选形态适合谁特点我的建议桌面版不熟悉命令行的用户图形界面、直观登录后直接用官方模型想快速体验可以用但可配置性最弱本地部署基本绕开它CLI版开发者、需要脚本化/远程SSH的用户核心形态支持自定义模型Provider配置项最全本地部署必选强烈推荐主力使用VS Code扩展IDE重度用户在编辑器侧边栏用能看到diff集成度好适合辅助模型切换和配置继承自CLI配置如果你的目标是本地部署我个人建议直接以CLI版为主。原因很简单桌面版把模型配置、数据目录、鉴权流程都封装在界面里你很难去干预而CLI版的所有配置都落在~/.codex/config.toml这个文件里改起来透明直接。VS Code扩展虽然也能用但很多功能依赖于CLI的配置结果属于“锦上添花”不是必需品。另外要强调一点Codex默认需要OpenAI账号或API Key才能跑官方模型。如果你被登录问题卡住也别急着放弃先看第3节把模型切换到DeepSeek或Ollama之后Codex的核心能力照样能用而且不再依赖OpenAI账号。2. Codex下载与安装桌面版和CLI版都给你跑一遍2.1 桌面版官网下载装完就能看到界面桌面版的安装非常简单。去OpenAI官网的Codex下载页面挑对应系统的安装包Windows是exe/setupmacOS是dmg下载后一路下一步装完就行。启动之后会进入登录界面需要用ChatGPT账号登录。这里有个很现实的提醒Codex桌面版的登录依赖OpenAI的账号体系而OpenAI对账号归属区域和服务支持范围有限制。如果你的账号归属地不在支持范围内桌面版会频繁出现“无法加载组织设置”、登录转圈、无法进入主界面这些现象。这种情况再去重装、清理缓存基本没用因为问题在账号侧不在本地。我的建议是与其卡在这里反复试不如直接转用CLI版用API Key或者第三方模型的方式跑通。这也是后面第3节的重点。桌面版装好之后一般会自动更新不用手动管版本。它的界面默认跟随系统语言如果你的系统是中文界面基本能用中文看但这不等于所有模型配置项都能在界面里找到。2.2 CLI版npm一条命令装完支持自托管模型CLI版才是玩本地部署的主战场。安装需要Node.js环境建议装LTS版本18或20均可。然后用npm全局安装npm install -g openai/codex装完验证一下codex --version如果能输出版本号说明安装成功。CLI首次运行会在你的用户目录下创建~/.codex/文件夹里面会存放配置文件、历史会话记录后续我们要改的模型配置就在这里。有几个安装阶段容易踩的坑npm下载慢或者直接超时。这通常是网络环境对npm默认源访问不理想。我习惯先切换到国内镜像源速度明显改善npm config set registry https://registry.npmmirror.comWindows用户装完npm全局包之后找不到codex命令。这是因为npm全局bin目录不在你的PATH环境变量里。检查npm全局路径npm prefix -g把这个路径加入到系统PATH重新打开终端就好。别用老旧的cmd窗口跑Codex很多交互按键会失灵我后面细说。2.3 终端准备别让交互体验输在第一步Codex CLI是交互式终端工具对终端本身是有要求的。Windows上强烈建议用Windows Terminal别用传统cmd。传统cmd对ANSI色彩支持差而且很多快捷键比如上下键选择项目、CtrlC中断、滚轮浏览长输出都会出问题。macOS直接用自带的Terminal或者iTerm2都行。另外在Linux/Windows WSL环境里用Codex时注意终端字体要支持等宽字体和常用Unicode符号否则输出对齐会很难看。我不建议一上来就折腾各种zsh主题先把终端基础环境弄干净后面排查问题会轻松很多。3. Codex本地部署的本质把上游模型换成你的模型3.1 先拆清楚Codex能本地部署的边界到底在哪很多搜“Codex本地部署”的朋友第一反应是“我要把Codex完整装到我自己的服务器上”。这里必须澄清一个边界问题Codex这个CLI前端本身是闭源的你没法像部署开源项目那样把整个Codex服务端搬到自己机器上。你能本地部署的是它背后的“模型服务”。Codex CLI采用了标准的OpenAI兼容接口协议去访问模型。默认请求目标是OpenAI官方端点但是通过配置文件你可以把它指向任何实现了OpenAI兼容协议的服务。也就是说Codex保留了自己作为“AI编程助手前端”的全部能力——文件感知、命令执行、计划生成、会话回滚——只是把决定“用哪个模型来理解代码”这件事交给了你。这也是本地部署大模型玩法里最实际的一条路径用一个强大的闭源前端配一个完全可控的开源模型后端。模型可以是Ollama拉下来的本地模型也可以是DeepSeek这类第三方开放API两者在Codex眼里都是同一个东西一个支持OpenAI风格接口的模型服务。3.2 核心配置文件config.toml先读懂再改Codex CLI的所有模型相关配置都集中在~/.codex/config.toml。这个文件用TOML格式最常见的本地部署配置包含三个关键部分model默认使用的模型名字。model_provider默认使用的模型供应商名字。model_providers供应商的具体参数表包括服务地址、接口协议、鉴权方式等。一个最基础的Ollama自托管配置长这样model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 wire_api chat_completions逐行解释一下参数含义base_url模型服务的HTTP入口。Ollama默认监听127.0.0.1:11434它的OpenAI兼容端点是/v1。wire_api这是最关键的参数很多报错都出在这里。Codex默认走/responses这个新版接口而Ollama和DeepSeek这类第三方服务通常只实现了/chat/completions接口。所以必须显式写成wire_api chat_completions让Codex改用大家都能识别的协议格式。如果漏掉这一行最常见的报错就是404、400、route not found或者模型完全不理你。本地模型不需要鉴权所以不用配env_key。如果是DeepSeek API这种云端第三方服务配置结构类似只是多了API Key字段。DeepSeek官方接口和OpenAI的旧版chat/completions协议高度兼容Codex可以直接看懂它。具体配置我建议按下面来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_completions这里要注意env_key指的是环境变量名不是直接把Key写在配置文件里。实际使用前需要先把Key设置到系统环境变量中或者每次在终端里导出export DEEPSEEK_API_KEYsk-你的key把Key写死在config.toml里不是不行但有泄露风险尤其是当你把配置文件传到公开仓库时Key会跟着一起泄露不建议这么干。3.3 接入DeepSeek API最省心的第三方模型路线为什么先说DeepSeek因为它的接口兼容性在第三方API里是数一数二的不需要本地显存、不需要装Ollama注册开放平台、拿API Key、改配置就能跑。完整流程是这样的去DeepSeek开放平台注册账号创建一个API Key记下Key字符串。设置环境变量DEEPSEEK_API_KEY。把上面的DeepSeek配置写进~/.codex/config.toml。启动Codex并显式指定模型codex --model deepseek-chat这里有个需要注意的细节model_provider里配置的模型名字如deepseek-chat必须和DeepSeek官方接口返回的模型标识完全一致。Codex在启动时会去请求模型列表如果名字对不上会直接报“模型不存在”之类的错误。你可以先用curl验证curl https://api.deepseek.com/v1/models -H Authorization: Bearer $DEEPSEEK_API_KEY看到返回的模型标识之后再回填到config.toml里。这一步能省下很多排错时间。3.4 接入Ollama真正的全本地模型不依赖外网如果你想让Codex变成一个完全离线的编程助手那就上Ollama。Ollama是目前本地部署大模型最顺手的工具安装、拉模型、起服务三步走。先装Ollama。Windows/macOS都有安装包Linux用一键脚本。装完确认服务在跑ollama --version ollama serve如果ollama serve没有自动跑起来就手动在另一个终端窗口拉起来。默认监听地址是127.0.0.1:11434。然后拉一个适合Codex的代码模型。我最常用的是qwen2.5-coder系列特别推荐qwen2.5-coder:14b。这个模型在编码、工具调用、指令跟随几个维度上比较均衡ollama pull qwen2.5-coder:14b拉完确认模型存在ollama list接着把config.toml按前面Ollama配置写好运行codex --model qwen2.5-coder:14b此时Codex发出的所有请求都打到本地Ollama服务上整个过程不访问任何外部厂商API。断网状态下也能干活的“AI编程助手”就这么搭出来了。Ollama还有一个很实用的点OpenAI兼容端点在/v1下但底层还是走Ollama自己的接口。如果你在测试中发现400错误优先检查base_url最后面的路径是不是/v1很多手误都出在这。3.5 16GB显存能跑什么模型选型参考很多朋友问“16G显存本地部署AI到底能跑多大模型”放到Codex场景里其实很清晰Codex对模型的工具调用能力要求很高选模型时优先看重能写代码、能理解JSON格式工具调用而不是单纯追求参数量大。以常见的Ollama量化版模型为例显存推荐模型上下文建议说明8Gqwen2.5-coder:7b8K-16K适合简单任务重活容易力不从心12Gqwen2.5-coder:7b / deepseek-coder-v2:16b16K小团队够用16Gqwen2.5-coder:14b16K-32K本地体验和效果比较平衡的点强烈推荐24Gqwen2.5-coder:32b32K已经很接近可用的生产辅助水平16G显存跑14B的qwen2.5-coder量化版是比较典型的组合显存能装下推理速度能接受Codex这类Agent对单轮工具的依赖也能满足。上下文不要无脑调到64K本地模型在长上下文下性能衰减明显内存占用也涨得厉害。把上下文控制在16K到32K之间体验更稳妥。4. 实战操作从初始化到跑通第一个代码任务4.1 鉴权方式怎么选OpenAI登录、API Key还是本地模型配置好模型Provider之后还要想清楚鉴权方式。Codex CLI支持两大流派ChatGPT账号登录模式执行codex login浏览器弹出登录用账号授权之后Codex会使用账号的订阅权限调用官方模型。这种模式适合主要用官方模型的人组织设置加载不出来的问题也常出现在这个模式下。API Key模式设置OPENAI_API_KEY环境变量Codex会拿这个Key去请求官方API。适合按量付费的用户。第三方模型模式也就是上面第3节配置的DeepSeek/Ollama Provider。这种模式不需要执行codex login也不需要OPENAI_API_KEY直接把模型参数指向第三方即可。我特别想强调如果OpenAI官方账号登录始终过不去别死磕。Codex的工具价值在于前端操作框架模型可以被替换。用DeepSeek去走通Codex已经能覆盖绝大多数编程辅助场景。这也算是在账号限制下找到的一条合规、官方的使用路径。4.2 初始化Codex并设置权限先把安全边界划好Codex CLI可以直接用codex exec 任务描述以非交互模式执行单次任务也可以直接输入codex进入交互式会话。第一次跑任务时它会请求操作系统权限比如“能否读取某个目录”“能否执行curl命令”“能否修改某个文件”。这些权限控制由approval_mode管理官方给的选项大致是模式行为适用场景read_only只看不写、不执行让AI帮你分析代码结构、写方案on_request每次写文件/执行命令都问你最推荐的新手模式accept_edits文件修改自动批准命令仍需确认初步信任阶段full_auto一切都自动执行你非常熟悉项目且信任AI时我的经验第一天用Codex永远不要开full_auto。它跑git clean、删缓存、改配置这些操作你根本来不及反应。先用on_request跑两周看过它哪些操作可靠、哪些操作离谱再逐步放开权限。4.3 实战案例让Codex跑一个CSV聚合任务理论说再多不如跑一遍。假设你手上有一个sales.csv字段是region, product, amount想让代码统计每个区域的销售总额。直接用本地模型跑codex --model qwen2.5-coder:14b然后在交互界面里输入读取当前目录下的sales.csv按region列分组计算每组的amount总和把结果保存到summary.csv并打印前5行。你会看到Codex的行为大约是先列出目录文件确认CSV存在然后思考用什么库大概率是pandas如果没有pandas它就改用csv模块接着写代码到临时文件或目标脚本里再请求执行权限。你批准后它会运行脚本、读取输出、告知结果。这个过程中最有价值的观察点不是代码本身正不正确而是“它有没有进行足够的信息确认”。好的Agent在动手前会先看一眼前几行数据确认列名版本弱的模型可能直接按猜测字段处理导致跑挂。如果发现本地模型在猜字段下一步就把任务描述加细明确列名和类型。4.4 小步迭代本地模型比GPT-5更需要任务拆分用本地模型跑Codex一定要调整预期。14B的模型在单点修改、小脚本生成上表现很好但让它一口气完成“重构整个模块写全套测试改文档”这种大任务很容易输出一半就断掉或者过度简化。我的做法是把它当成“结对编程里的执行者”一个子任务一个子任务地下达第一步“分析src/utils.py里parse_config函数的输入输出描述潜在问题。”第二步“在保留原有接口的前提下把错误处理改成抛出统一异常。”第三步“为这个函数补充3个单元测试。”每步之间等它完成并确认再给下一步。这种方式下哪怕模型推理能力不算顶级也能稳定交出可用结果。任务拆得越细出错越容易发现回滚也越精准。5. 高频问题排查实录5.1 登录不上、组织设置加载失败这是桌面版用户最常撞的墙。表现是登录按钮点了无数次浏览器授权后回到桌面版还是转圈或者干脆提示“无法加载组织设置”。原因基本指向账号归属地不在官方服务支持范围内或者账号类型受限。除了确认是否用了官方支持的账号区域之外这个问题没有太多本地手段可以解决。重装、换终端、清缓存我都试过都没用。这里我建议换个思路绕开登录流程直接用CLI版接第三方模型。Codex核心前端能力不依赖OpenAI账号把模型切到DeepSeek或Ollama之后照样能在终端里干活。这是最干净、也完全合规的路径。5.2 Codex请求时报“本地转发失败 while handling codex endpoint /responses”这个报错经常出现在使用“模型切换工具”比如CC Switch这类的场景。这类工具的工作原理是在本地开一个端口把Codex发出的请求拦截后转发到某个自定义网关再路由到不同厂商模型。看起来很方便但在转发过程中经常只实现了/chat/completions接口没有实现Codex默认请求的/responses接口。于是Codex按照默认协议去请求转发端点时就出现类似“本地转发失败 while handling codex endpoint /responses”的报错。解决办法有两个方向在Codex配置中显式设置wire_api chat_completions让请求走旧版补全接口这样大多数转发端点就能识别。如果转发工具本身只对某些场景生效干脆关掉对Codex的接管让Codex直连模型服务的原始地址。少一层中间转发就少一类问题这是后期排查故障时最立竿见影的做法。5.3 接入Ollama之后报404/400或者模型完全不说话出现这种问题按下面的顺序检查检查点应当如何验证常见错误Ollama服务是否在运行执行ollama list服务没启动base_url路径必须包含/v1写成http://localhost:11434少了v1wire_api必须为chat_completions漏配Codex按responses请求模型名是否一致ollama list里的name要和config一致tag写错如14b写成14B协议是否用http本地服务用 http不要写 https写https导致握手失败还有个很隐蔽的问题如果config.toml里同时配置了多个provider但启动时没有用--model指定Codex会走model字段的默认值有可能模型和provider不匹配。建议每个自定义provider都在启动时显式带上--model参数减少混乱。5.4 工具调用失效模型总在“复读”代码Codex依赖模型具备函数调用/工具调用能力。模型的输出需要严格遵循工具调用格式如果模型不具备这个能力Codex就会频繁“复读”代码、输出假象计划甚至循环请求工具而毫无动作。本地模型里qwen2.5-coder系列对工具调用的支持在开源编码模型里属于比较稳的。如果你换了其他模型发现工具调用稀烂不要试图通过改提示词来弥补直接换回工具调用能力扎实的模型。注意很多通用聊天模型在工具调用上与Codex协议不兼容即使它能写代码也不代表它能当好Agent。5.5 常见错误速查表报错/现象原因解决codex命令找不到npm全局路径不在PATH执行npm prefix -g把目录加入PATHnpm安装超时默认源访问慢切换npmmirror源无法加载组织设置账号归属限制转API Key模式或自定义模型Provider404 route not foundbase_url漏了/v1或wire_api不对改base_url加wire_api400 Bad Request请求格式与服务端不兼容确认wire_api为chat_completions密钥不存在环境变量没设置export对应的env_key界面乱码终端对Unicode支持差换Windows Terminal/iTerm2本地模型无响应显存/内存不足模型占满换更小模型降低上下文最后再分享一个小习惯不管是接DeepSeek还是Ollama只要改了配置我先用curl直接打一遍base_url/v1/models接口确认服务和鉴权都正常再启动Codex。这一步能过滤掉大概一半的配置错误。Codex这个工具我用了这段时间最大的感受是它给了AI编程一个更接近“真实协作”的形态而本地模型给了它更大的自由度。希望这篇文章能让你少走点弯路顺利把属于你自己的AI编程助手跑起来。 最近Codex的讨论量一下子就上来了作为OpenAI推出的AI编程助手它最大的卖点不是在聊天框里给你抄代码而是直接在终端里读项目、改文件、执行命令用法更像一个能动手干活的远程实习生。不过很多朋友卡在第一步下载完了登不上、组织设置加载失败、装了CLI不知道怎么配模型。这篇文章就把“下载、安装、配置、跑通”整条链路拆开讲核心重点是很多人真正关心的本地部署方向——把Codex的上游模型换成DeepSeek或者Ollama本地大模型让它成为一个完全可控的AI编程助手。1. 先搞懂Codex是什么再决定怎么装1.1 它不是“聊天窗口”是一个会动手的终端Agent先说一个最常见的误解。有人以为Codex是另一个ChatGPT网页版打开之后输入问题等答案。实际上Codex的核心形态是CLI命令行工具它以一种Agent的方式工作你给它一个任务描述它会先分析当前目录的代码结构、读取相关文件、生成修改计划然后直接改代码、跑测试、执行shell命令整个过程都在终端里可视化成一条条操作记录。这意味着什么意味着它的使用场景不是“问答”而是“执行”。比如你说“把登录接口的超时时间从5秒改成10秒并补充单元测试”它会自己去找到相关文件、定位代码、修改、运行测试然后给你看结果。如果你不满意某一步它还能基于历史记录回滚。这种工作流和传统的AI代码补全工具比如自动补全、聊天问答完全是两个维度。从架构上看Codex可以拆成两层上层是“操作框架”前端CLI、权限控制、命令执行、文件管理下层是“模型服务”真正负责理解和生成代码的大模型。官方默认接的是OpenAI自家的Codex系列模型但下层模型服务是可以通过配置替换的这就是本地部署所有可能性的来源。1.2 桌面版、CLI版和VS Code扩展怎么选Codex目前有好几种使用形态很多人下了一堆版本之后反而乱了。我用下来之后建议按下面这个表来选形态适合谁特点我的建议桌面版不熟悉命令行的用户图形界面、直观登录后直接用官方模型想快速体验可以用但可配置性最弱本地部署基本绕开它CLI版开发者、需要脚本化/远程SSH的用户核心形态支持自定义模型Provider配置项最全本地部署必选强烈推荐主力使用VS Code扩展IDE重度用户在编辑器侧边栏用能看到diff集成度好适合辅助模型切换和配置继承自CLI配置如果你的目标是本地部署我个人建议直接以CLI版为主。原因很简单桌面版把模型配置、数据目录、鉴权流程都封装在界面里你很难去干预而CLI版的所有配置都落在~/.codex/config.toml这个文件里改起来透明直接。VS Code扩展虽然也能用但很多功能依赖于CLI的配置结果属于“锦上添花”不是必需品。另外要强调一点Codex默认需要OpenAI账号或API Key才能跑官方模型。如果你被登录问题卡住也别急着放弃先看第3节把模型切换到DeepSeek或Ollama之后Codex的核心能力照样能用而且不再依赖OpenAI账号。2. Codex下载与安装桌面版和CLI版都给你跑一遍2.1 桌面版官网下载装完就能看到界面桌面版的安装非常简单。去OpenAI官网的Codex下载页面挑对应系统的安装包Windows是exe/setupmacOS是dmg下载后一路下一步装完就行。启动之后会进入登录界面需要用ChatGPT账号登录。这里有个很现实的提醒Codex桌面版的登录依赖OpenAI的账号体系而OpenAI对账号归属区域和服务支持范围有限制。如果你的账号归属地不在支持范围内桌面版会频繁出现“无法加载组织设置”、登录转圈、无法进入主界面这些现象。这种情况再去重装、清理缓存基本没用因为问题在账号侧不在本地。我的建议是与其卡在这里反复试不如直接转用CLI版用API Key或者第三方模型的方式跑通。这也是后面第3节的重点。桌面版装好之后一般会自动更新不用手动管版本。它的界面默认跟随系统语言如果你的系统是中文界面基本能用中文看但这不等于所有模型配置项都能在界面里找到。2.2 CLI版npm一条命令装完支持自托管模型CLI版才是玩本地部署的主战场。安装需要Node.js环境建议装LTS版本18或20均可。然后用npm全局安装npm install -g openai/codex装完验证一下codex --version如果能输出版本号说明安装成功。CLI首次运行会在你的用户目录下创建~/.codex/文件夹里面会存放配置文件、历史会话记录后续我们要改的模型配置就在这里。有几个安装阶段容易踩的坑npm下载慢或者直接超时。这通常是网络环境对npm默认源访问不理想。我习惯先切换到国内镜像源速度明显改善npm config set registry https://registry.npmmirror.comWindows用户装完npm全局包之后找不到codex命令。这是因为npm全局bin目录不在你的PATH环境变量里。检查npm全局路径npm prefix -g把这个路径加入到系统PATH重新打开终端就好。别用老旧的cmd窗口跑Codex很多交互按键会失灵我后面细说。2.3 终端准备别让交互体验输在第一步Codex CLI是交互式终端工具对终端本身是有要求的。Windows上强烈建议用Windows Terminal别用传统cmd。传统cmd对ANSI色彩支持差而且很多快捷键比如上下键选择项目、CtrlC中断、滚轮浏览长输出都会出问题。macOS直接用自带的Terminal或者iTerm2都行。另外在Linux/Windows WSL环境里用Codex时注意终端字体要支持等宽字体和常用Unicode符号否则输出对齐会很难看。我不建议一上来就折腾各种zsh主题先把终端基础环境弄干净后面排查问题会轻松很多。3. Codex本地部署的本质把上游模型换成你的模型3.1 先拆清楚Codex能本地部署的边界到底在哪很多搜“Codex本地部署”的朋友第一反应是“我要把Codex完整装到我自己的服务器上”。这里必须澄清一个边界问题Codex这个CLI前端本身是闭源的你没法像部署开源项目那样把整个Codex服务端搬到自己机器上。你能本地部署的是它背后的“模型服务”。Codex CLI采用了标准的OpenAI兼容接口协议去访问模型。默认请求目标是OpenAI官方端点但是通过配置文件你可以把它指向任何实现了OpenAI兼容协议的服务。也就是说Codex保留了自己作为“AI编程助手前端”的全部能力——文件感知、命令执行、计划生成、会话回滚——只是把决定“用哪个模型来理解代码”这件事交给了你。这也是本地部署大模型玩法里最实际的一条路径用一个强大的闭源前端配一个完全可控的开源模型后端。模型可以是Ollama拉下来的本地模型也可以是DeepSeek这类第三方开放API两者在Codex眼里都是同一个东西一个支持OpenAI风格接口的模型服务。3.2 核心配置文件config.toml先读懂再改Codex CLI的所有模型相关配置都集中在~/.codex/config.toml。这个文件用TOML格式最常见的本地部署配置包含三个关键部分model默认使用的模型名字。model_provider默认使用的模型供应商名字。model_providers供应商的具体参数表包括服务地址、接口协议、鉴权方式等。一个最基础的Ollama自托管配置长这样model qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama base_url http://localhost:11434/v1 wire_api chat_completions逐行解释一下参数含义base_url模型服务的HTTP入口。Ollama默认监听127.0.0.1:11434它的OpenAI兼容端点是/v1。wire_api这是最关键的参数很多报错都出在这里。Codex默认走/responses这个新版接口而Ollama和DeepSeek这类第三方服务通常只实现了/chat/completions接口。所以必须显式写成wire_api chat_completions让Codex改用大家都能识别的协议格式。如果漏掉这一行最常见的报错就是404、400、route not found或者模型完全不理你。本地模型不需要鉴权所以不用配env_key。如果是DeepSeek API这种云端第三方服务配置结构类似只是多了API Key字段。DeepSeek官方接口和OpenAI的旧版chat/completions协议高度兼容Codex可以直接看懂它。具体配置我建议按下面来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_completions这里要注意env_key指的是环境变量名不是直接把Key写在配置文件里。实际使用前需要先把Key设置到系统环境变量中或者每次在终端里导出export DEEPSEEK_API_KEYsk-你的key把Key写死在config.toml里不是不行但有泄露风险尤其是当你把配置文件传到公开仓库时Key会跟着一起泄露不建议这么干。3.3 接入DeepSeek API最省心的第三方模型路线为什么先说DeepSeek因为它的接口兼容性在第三方API里是数一数二的不需要本地显存、不需要装Ollama注册开放平台、拿API Key、改配置就能跑。完整流程是这样的去DeepSeek开放平台注册账号创建一个API Key记下Key字符串。设置环境变量DEEPSEEK_API_KEY。把上面的DeepSeek配置写进~/.codex/config.toml。启动Codex并显式指定模型codex --model deepseek-chat这里有个需要注意的细节model_provider里配置的模型名字如deepseek-chat必须和DeepSeek官方接口返回的模型标识完全一致。Codex在启动时会去请求模型列表如果名字对不上会直接报“模型不存在”之类的错误。你可以先用curl验证curl https://api.deepseek.com/v1/models -H Authorization: Bearer $DEEPSEEK_API_KEY看到返回的模型标识之后再回填到config.toml里。这一步能省下很多排错时间。3.4 接入Ollama真正的全本地模型不依赖外网如果你想让Codex变成一个完全离线的编程助手那就上Ollama。Ollama是目前本地部署大模型最顺手的工具安装、拉模型、起服务三步走。先装Ollama。Windows/macOS都有安装包Linux用一键脚本。装完确认服务在跑ollama --version ollama serve如果ollama serve没有自动跑起来就手动在另一个终端窗口拉起来。默认监听地址是127.0.0.1:11434。然后拉一个适合Codex的代码模型。我最常用的是qwen2.5-coder系列特别推荐qwen2.5-coder:14b。这个模型在编码、工具调用、指令跟随几个维度上比较均衡ollama pull qwen2.5-coder:14b拉完确认模型存在ollama list接着把config.toml按前面Ollama配置写好运行codex --model qwen2.5-coder:14b此时Codex发出的所有请求都打到本地Ollama服务上整个过程不访问任何外部厂商API。断网状态下也能干活的“AI编程助手”就这么搭出来了。Ollama还有一个很实用的点OpenAI兼容端点在/v1下但底层还是走Ollama自己的接口。如果你在测试中发现400错误优先检查base_url最后面的路径是不是/v1很多手误都出在这。3.5 16GB显存能跑什么模型选型参考很多朋友问“16G显存本地部署AI到底能跑多大模型”放到Codex场景里其实很清晰Codex对模型的工具调用能力要求很高选模型时优先看重能写代码、能理解JSON格式工具调用而不是单纯追求参数量大。以常见的Ollama量化版模型为例显存推荐模型上下文建议说明8Gqwen2.5-coder:7b8K-16K适合简单任务重活容易力不从心12Gqwen2.5-coder:7b / deepseek-coder-v2:16b16K小团队够用16Gqwen2.5-coder:14b16K-32K本地体验和效果比较平衡的点强烈推荐24Gqwen2.5-coder:32b32K已经很接近可用的生产辅助水平16G显存跑14B的qwen2.5-coder量化版是比较典型的组合显存能装下推理速度能接受Codex这类Agent对单轮工具的依赖也能满足。上下文不要无脑调到64K本地模型在长上下文下性能衰减明显内存占用也涨得厉害。把上下文控制在16K到32K之间体验更稳妥。4. 实战操作从初始化到跑通第一个代码任务4.1 鉴权方式怎么选OpenAI登录、API Key还是本地模型配置好模型Provider之后还要想清楚鉴权方式。Codex CLI支持两大流派ChatGPT账号登录模式执行codex login浏览器弹出登录用账号授权之后Codex会使用账号的订阅权限调用官方模型。这种模式适合主要用官方模型的人组织设置加载不出来的问题也常出现在这个模式下。API Key模式设置OPENAI_API_KEY环境变量Codex会拿这个Key去请求官方API。适合按量付费的用户。第三方模型模式也就是上面第3节配置的DeepSeek/Ollama Provider。这种模式不需要执行codex login也不需要OPENAI_API_KEY直接把模型参数指向第三方即可。我特别想强调如果OpenAI官方账号登录始终过不去别死磕。Codex的工具价值在于前端操作框架模型可以被替换。用DeepSeek去走通Codex已经能覆盖绝大多数编程辅助场景。这也算是在账号限制下找到的一条合规、官方的使用路径。4.2 初始化Codex并设置权限先把安全边界划好Codex CLI可以直接用codex exec 任务描述以非交互模式执行单次任务也可以直接输入codex进入交互式会话。第一次跑任务时它会请求操作系统权限比如“能否读取某个目录”“能否执行curl命令”“能否修改某个文件”。这些权限控制由approval_mode管理官方给的选项大致是模式行为适用场景read_only只看不写、不执行让AI帮你分析代码结构、写方案on_request每次写文件/执行命令都问你最推荐的新手模式accept_edits文件修改自动批准命令仍需确认初步信任阶段full_auto一切都自动执行你非常熟悉项目且信任AI时我的经验第一天用Codex永远不要开full_auto。它跑git clean、删缓存、改配置这些操作你根本来不及反应。先用on_request跑两周看过它哪些操作可靠、哪些操作离谱再逐步放开权限。4.3 实战案例让Codex跑一个CSV聚合任务理论说再多不如跑一遍。假设你手上有一个sales.csv字段是region, product, amount想让代码统计每个区域的销售总额。直接用本地模型跑codex --model qwen2.5-coder:14b然后在交互界面里输入读取当前目录下的sales.csv按region列分组计算每组的amount总和把结果保存到summary.csv并打印前5行。你会看到Codex的行为大约是先列出目录文件确认CSV存在然后思考用什么库大概率是pandas如果没有pandas它就改用csv模块接着写代码到临时文件或目标脚本里再请求执行权限。你批准后它会运行脚本、读取输出、告知结果。这个过程中最有价值的观察点不是代码本身正不正确而是“它有没有进行足够的信息确认”。好的Agent在动手前会先看一眼前几行数据确认列名版本弱的模型可能直接按猜测字段处理导致跑挂。如果发现本地模型在猜字段下一步就把任务描述加细明确列名和类型。4.4 小步迭代本地模型比GPT-5更需要任务拆分用本地模型跑Codex一定要调整预期。14B的模型在单点修改、小脚本生成上表现很好但让它一口气完成“重构整个模块写全套测试改文档”这种大任务很容易输出一半就断掉或者过度简化。我的做法是把它当成“结对编程里的执行者”一个子任务一个子任务地下达第一步“分析src/utils.py里parse_config函数的输入输出描述潜在问题。”第二步“在保留原有接口的前提下把错误处理改成抛出统一异常。”第三步“为这个函数补充3个单元测试。”每步之间等它完成并确认再给下一步。这种方式下哪怕模型推理能力不算顶级也能稳定交出可用结果。任务拆得越细出错越容易发现回滚也越精准。5. 高频问题排查实录5.1 登录不上、组织设置加载失败这是桌面版用户最常撞的墙。表现是登录按钮点了无数次浏览器授权后回到桌面版还是转圈或者干脆提示“无法加载组织设置”。原因基本指向账号归属地不在官方服务支持范围内或者账号类型受限。除了确认是否用了官方支持的账号区域之外这个问题没有太多本地手段可以解决。重装、换终端、清缓存我都试过都没用。这里我建议换个思路绕开登录流程直接用CLI版接第三方模型。Codex核心前端能力不依赖OpenAI账号把模型切到DeepSeek或Ollama之后照样能在终端里干活。这是最干净、也完全合规的路径。5.2 Codex请求时报“本地转发失败 while handling codex endpoint /responses”这个报错经常出现在使用“模型切换工具”比如CC Switch这类的场景。这类工具的工作原理是在本地开一个端口把Codex发出的请求拦截后转发到某个自定义网关再路由到不同厂商模型。看起来很方便但在转发过程中经常只实现了/chat/completions接口没有实现Codex默认请求的/responses接口。于是Codex按照默认协议去请求转发端点时就出现类似“本地转发失败 while handling codex endpoint /responses”的报错。解决办法有两个方向在Codex配置中显式设置wire_api chat_completions让请求走旧版补全接口这样大多数转发端点就能识别。如果转发工具本身只对某些场景生效干脆关掉对Codex的接管让Codex直连模型服务的原始地址。少一层中间转发就少一类问题这是后期排查故障时最立竿见影的做法。5.3 接入Ollama之后报404/400或者模型完全不说话出现这种问题按下面的顺序检查检查点应当如何验证常见错误Ollama服务是否在运行执行ollama list服务没启动base_url路径必须包含/v1写成http://localhost:11434少了v1wire_api必须为chat_completions漏配Codex按responses请求模型名是否一致ollama list里的name要和config一致tag写错如14b写成14B协议是否用http本地服务用 http不要写 https写https导致握手失败还有个很隐蔽的问题如果config.toml里同时配置了多个provider但启动时没有用--model指定Codex会走model字段的默认值有可能模型和provider不匹配。建议每个自定义provider都在启动时显式带上--model参数减少混乱。5.4 工具调用失效模型总在“复读”代码Codex依赖模型具备函数调用/工具调用能力。模型的输出需要严格遵循工具调用格式如果模型不具备这个能力Codex就会频繁“复读”代码、输出假象计划甚至循环请求工具而毫无动作。本地模型里qwen2.5-coder系列对工具调用的支持在开源编码模型里属于比较稳的。如果你换了其他模型发现工具调用稀烂不要试图通过改提示词来弥补直接换回工具调用能力扎实的模型。注意很多通用聊天模型在工具调用上与Codex协议不兼容即使它能写代码也不代表它能当好Agent。5.5 常见错误速查表报错/现象原因解决codex命令找不到npm全局路径不在PATH执行npm prefix -g把目录加入PATHnpm安装超时默认源访问慢切换npmmirror源无法加载组织设置账号归属限制转API Key模式或自定义模型Provider404 route not foundbase_url漏了/v1或wire_api不对改base_url加wire_api400 Bad Request请求格式与服务端不兼容确认wire_api为chat_completions密钥不存在环境变量没设置export对应的env_key界面乱码终端对Unicode支持差换Windows Terminal/iTerm2本地模型无响应显存/内存不足模型占满换更小模型降低上下文最后再分享一个小习惯不管是接DeepSeek还是Ollama只要改了配置我先用curl直接打一遍base_url/v1/models接口确认服务和鉴权都正常再启动Codex。这一步能过滤掉大概一半的配置错误。Codex这个工具我用了这段时间最大的感受是它给了AI编程一个更接近“真实协作”的形态而本地模型给了它更大的自由度。希望这篇文章能让你少走点弯路顺利把属于你自己的AI编程助手跑起来。