最近我把 Codex 从单纯的网页聊天界面搬到了本地终端里折腾了一圈才发现真正意义上的“ Codex 本地部署”其实包含两件事一是把 Codex 这个编程助手本体装到你自己的机器上二是让它能调用本地的大语言模型。这两件事分开做都不难合在一起就容易踩坑。这篇文章把我从下载安装、配置本地模型到排查各种报错的完整经历写出来给想搭一个不依赖云端、随时能改代码的 AI 编程助手的读者一个可以直接照做的方案。先说明一下我这边的基本情况主力机是 Windows还有一台装 Ubuntu 的旧笔记本专门负责跑模型。所以下面的步骤兼顾 Windows 和 Linux/macOS 两种路径能覆盖大多数人的使用场景。如果你只是想尽快跑通那我建议你直接按第 2 节的安装步骤走然后在第 3 节把本地模型接上基本 20 分钟就能看到一个能干活的 Codex。1. 为什么要本地化部署 Codex而不是只用网页版1.1 Codex 在开发链路里到底解决什么问题Codex 不是传统意义上的“帮你补全代码”的插件它更像是一个住在终端里的智能体你给它一个任务描述它会自己去读项目文件、执行命令、编辑代码然后把改动结果告诉你。这和平时我们在 IDE 里按 Tab 补全、或者复制报错信息去问聊天机器人完全不是一回事。我最早用 Codex 是让它帮我重构一个 Python 的报表模块。那模块有 2000 多行逻辑散落在三四个文件里。我给的指令是“把数据库连接抽出来统一走连接池同时把查询里所有硬编码的表名改成配置读取”。Codex 不是只给我一段建议代码而是真的把文件打开、逐段改完、再跑了一遍测试命令最后把 diff 摆在我面前。这种“会动手”的工作方式才是最吸引我把它部署到本地的核心原因。1.2 本地部署换来的三项实际收益把 Codex 从云端聊天界面搬到本地终端不只是“换了个入口”它实际改写了三条使用逻辑数据和代码不出内网。你可以直接让它处理有保密要求的业务代码无需担心代码文本被发送到云端模型服务做上下文分析。只要模型运行在本地代码流全程在自己机器上这对企业项目和技术预研来说尤其重要。切断对单一云端服务的依赖。Codex 默认会走 OpenAI 的接口但本地部署后可以接 Ollama、DeepSeek 或者其他兼容接口。也就是说你可以在断网环境、内网隔离环境甚至只有 CPU 的机器上继续用“会动手”的编程助手。更细的调试粒度。终端版本的输出、日志、配置文件都是明文我能清楚地看到它每一步调了哪个模型、传了哪些参数、在哪个环节报错。相比之下网页版更像一个黑盒出了问题只能干瞪眼。1.3 什么情况不适合本地部署我不太建议完全零基础的读者一上来就搞纯本地部署。原因不是安装多难而是后面“调模型”这件事很吃经验本地模型选小了Codex 会表现得像个刚学编程的新手选大了显存不够又卡成幻灯片。如果只是想在 IDE 里体验 AI 编程直接用官方已经封装好的桌面版就好。本地部署更适合这三类人一是对数据出境敏感的开发者二是想把编程助手集成到 CI/CD 或内网环境里的运维工程师三是想深入研究 Codex 智能体机制、搞清楚模型调用链路的爱好者。你属于哪一类就去选对应的路线别硬扛。2. 下载安装从零到能跑通一条命令的完整过程2.1 先把 Node、Git 和环境变量理顺Codex 的 CLI 主要走 npm 分发所以第一步是把 Node.js 装好。注意版本要求Codex 对 Node 版本有硬性下限我建议装 Node.js 20 LTS 以上因为部分依赖在新版本里才会正常加载。装完后打开终端依次确认三个命令能正常回显版本号node -v npm -v git --version如果git没有安装也用下面的命令补上。Windows 用户建议用 wingetmacOS 用户建议用 Homebrew# Windows winget install Git.Git # macOS brew install git这里面有一个很容易被忽略的点安装完 Node 和 Git 后必须重新打开一个新的终端窗口。因为 PATH 环境变量不会在已经打开的窗口里自动刷新我和不少人都栽在这一步——装完一切正常但新终端里一敲node就提示“不是内部或外部命令”白白浪费十几分钟。2.2 用 npm 安装 Codex CLI环境确认无误后执行全局安装命令npm install -g openai/codex装完以后验证版本codex --version正常情况下你会看到类似codex/0.1.0的版本输出。安装后Codex 会在用户目录下创建一个.codex文件夹用来放配置、日志和会话数据。Windows 上这个路径是C:\Users\你的用户名\.codexLinux/macOS 是~/.codex。注意如果你的npm全局包安装目录不在 PATH 里命令行会提示找不到codex。Windows 上可以通过npm config get prefix查看路径然后把那个目录加到用户 PATHLinux/macOS 一般不用额外设置但如果用的是 nvm需要确保软链正常。如果你想用官方桌面版而不是纯命令行可以去 Codex 官网下载 Windows 桌面安装包。桌面版的底层和 CLI 是同一套运行时只是外面包了一层图形界面适合喜欢窗口操作的读者。2.3 登录与授权个人账号、组织账号怎么选安装只是开始要让 Codex 真正连上 OpenAI 的服务还需要完成身份认证。在终端输入codex login此时终端会打开一个浏览器页面让你选择登录方式。日常玩玩的个人用户直接用你的 ChatGPT 账号授权就行这种方式的优点是会自动刷新令牌你不需要自己管 API Key。如果是企业里用那就用组织账号登录Organization ID 会在登录后自动关联。需要注意如果你用的是 API Key 方式就不要把 Key 写在任何命令行参数里正确的做法是把它放到环境变量中# Windows PowerShell $env:OPENAI_API_KEYsk-你的key # Linux/macOS export OPENAI_API_KEYsk-你的key我把一次真实的报错经历放在这里作提醒我第一次登录时用的是个人账号但在公司电脑上又绑定了组织账号结果 Codex 始终提示“无法加载组织设置”。后来才发现是因为~/.codex/auth.json里同时存在两套凭据Codex 默认取了旧的那一套。处理办法是把 auth.json 备份后删掉重新执行codex login让它只保留一份校验信息。2.4 安装阶段最容易出的三个错按我帮同事排查的经验安装阶段的高频错误基本就是三类certificate verify failed或网络证书报错。这是本地网络环境跟 npm 源的 TLS 握手出了问题。如果是公司内网先问清楚网管有没有专用的 npm 私服地址有就把 registry 切到私服如果只是家用网络偶发不稳定重试一般就能恢复不要盲目去加strict-sslfalse。npm 安装超时。Codex 的依赖包不少网络不好时很常见 5 分钟还没装完。可以先把 npm 的超时时间适当调大或者换一个非高峰时段再跑。我不建议为了图快而用那些来路不明的加速工具安全风险大于收益。PowerShell 脚本执行策略限制。Windows 上如果报“无法加载文件因为在此系统上禁止运行脚本”需要用管理员身份打开 PowerShell 执行一次Set-ExecutionPolicy RemoteSigned -Scope CurrentUser。这一步没有副作用是 Windows 官方推荐的安全策略调整方式。安装这块没什么玄学核心就一句话环境变量、网络连通性、脚本执行权限三样理顺了codex命令必然能起来。3. 接入本地模型让 Codex 调用 Ollama 与 DeepSeek3.1 Codex 的模型路由机制和执行流程很多读者搜索“Codex 接入 DeepSeek”或“Ollama 本地部署”其实想要的是同一个结果让 Codex 这个智能体外壳驱动本地的大模型来干活。要做到这一点先要理解 Codex 的模型路由逻辑。Codex 的所有模型请求都会经过一个叫model_providers的配置区。Codex 的配置中心是~/.codex/config.toml默认情况下它只有一个指向 OpenAI 官方服务的 provider。你可以在这个文件里追加一个本地 provider指向 Ollama 或者任何兼容 OpenAI API 格式的本地服务。之后在启动 Codex 时用一个--model参数指定“用哪个 provider 下的哪个模型”即可。不同模型提供者还有一个关键区别wire_api。Codex 官方默认用的是 Responses API对应/responses端点Ollama 和一些私有化部署模型用的是 Chat Completions 模式对应/v1/chat/completions。你在配置里必须明确告诉 Codex 用哪种协议否则请求会全部打到错误的路径上。3.2 config.toml 关键字段逐一解释我用一份实际可用的配置做例子不展开高大上的概念model ollama/qwen2.5-coder:14b model_provider ollama [model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 wire_api chat env_key NO_KEY逐行解释一下model默认使用的模型标识。格式是provider名称/模型名称这里指 ollama provider 下面名为qwen2.5-coder:14b的模型。model_provider指定默认 provider和上面的 model 前缀对应。[model_providers.ollama]定义名为 ollama 的 provider。name显示名称随意取。base_url本地模型服务的地址。Ollama 默认监听 11434OpenAI 兼容接口要加/v1后缀。注意我用的是127.0.0.1而不是localhost因为有些系统会把 localhost 解析成 IPv6 的::1而 Ollama 只监听了 IPv4导致连接被拒绝。wire_api设为chat表示走 Chat Completions 协议。如果保留默认的responsesCodex 请求时会出现路由错误。env_key告诉 Codex 读取哪个环境变量作为 API Key。本地 Ollama 不需要钥匙填一个不存在或无所谓的值比如NO_KEYCodex 就会跳过鉴权。如果你需要通过兼容 OpenAI API 的 DeepSeek 官方接口而不是本地 Ollama那么配置思路完全一样只是把base_url换成服务商提供的地址env_key换成你自己的密钥变量名。3.3 本地模型下载与会话联调写完配置文件接下来启动本地模型服务。先在 Ollama 官网下载对应系统的安装包装好然后拉取你想要的代码模型。这里给几个经过我验证的推荐# 代码能力较强的通用模型 ollama pull qwen2.5-coder:14b # 逻辑推理型适合代码 review 和架构分析 ollama pull deepseek-r1:14b拉取完成后在另一个终端里启动服务新版 Ollama 装完会自动常驻但手动启动更直观ollama serve然后验证一下本地接口是否真的通了curl http://127.0.0.1:11434/v1/models能看到模型列表 JSON就说明服务正常。最后回到 Codex 终端敲下面这行命令进入会话codex --model ollama/qwen2.5-coder:14b进去后随便让它写一段冒泡排序如果能正常生成代码并保存成文件就说明本地链路完全打通了。我第一次打通的时候还特意把网线拔了测试Codex 依然能完成代码修改那一刻才真正感觉到“本地部署”四个字的分量。3.4 常见本地组合的性能对比本地模型不是越大越好得看你机器的配置。我把自己试过的几组组合放进表格方便你做选择模型组合适合任务最低内存/显存建议实测体验qwen2.5-coder:7b补全、格式化、写小工具函数8GB 内存可跑16GB 更稳响应快但复杂重构容易丢上下文qwen2.5-coder:14b中等规模项目重构、单文件级修改16GB 内存或 8GB 显存综合性价比最高我日常主力deepseek-r1:14b代码 review、设计模式建议16GB 内存推理痕迹明显有时“想太多”70b 级别以上大模型跨多文件的大型重构建议 2 张 24GB 显存或纯 CPU 集群效果好但普通机器基本跑不动如果你只是想体验“会动手的 AI 编程助手”先用 qwen2.5-coder:7b 打通流程就够了如果是要真正用于项目开发我建议至少上 14b。再往上除非你手头有不错的 GPU 资源否则等待时间会让写代码的流畅感大打折扣。4. 真实使用中的高频故障与完整排查链路跑通不代表能稳定用这一段写的是我实际使用两周后遇到的高频故障和完整排查链路。我不会只给你结论而是把排查思路也一并写出来遇到类似问题时你可以顺着走。4.1 cc switch 报本地链路切换失败导致 /responses 端点阻塞先描述症状装了 cc switch 这类本地切换工具的用户在 Codex 使用过程中会突然看到类似cc switch ... local ... failed while handling codex endpoint /responses的错误。这个错误的字面意思是本地切换工具在处理 Codex 的 /responses 请求时没能成功完成链路切换所以请求被中断。它通常不是 Codex 本身的问题而是本地多服务并发时端口或宿主解析被抢占导致的。我的排查链路如下先看 Codex 能不能独立运行。把 cc switch 退掉单独启动 Codex如果能正常请求说明冲突源来自切换工具残留。检查本地端口监听状态。用netstat -ano | findstr 11434Windows或netstat -an | grep 11434Linux确认本地模型服务的端口只被一个进程占用。清理 cc switch 的缓存和日志。这类工具一般会在用户目录下保存历史会话状态把它的缓存目录改名后重启让工具重新初始化。最后再重新执行codex login让 Codex 重新走一遍 token 校验。注意遇到这类错误时不要反复重试很容易把本地会话文件写坏。正确操作是先退出所有第三方工具再启动 Codex 验证最后再逐步把工具加回来。4.2 模型不支持提示“gpt-5.6-sol”时该怎么解有读者私信问我在配置里填了gpt-5.6-solCodex 报the gpt-5.6-sol model is not supported when using codex with a ...。这个问题分两层看。第一层Codex 在通过本地 provider 走 Chat 接口时会检查模型名称是否在其支持前缀列表内防止有人胡乱指定模型导致协议不匹配。第二层gpt-5.6-sol根本不是当前 Codex 内置的模型标识可能是你从某个渠道看到了未发布的模型名或者单纯笔误。正确解法是用codex models命令列出当前可用的模型标识codex models看到输出后选择其中带ollama/前缀的本地模型或用codex --help查看当前版本支持的默认模型。如果你确定要用某个不在列表里的模型正确做法是在本地 provider 的配置里给它取一个别名让 Codex 认为它是合规模型具体字段是[model_providers.ollama] name Ollama Local base_url http://127.0.0.1:11434/v1 wire_api chat env_key NO_KEY includes_model_ids [qwen2.5-coder:14b]给 provider 加上includes_model_ids白名单后Codex 就会把这个模型视为可用项不再报 not supported。4.3 Windows 桌面版设置一直转圈 / “设置未完成”Windows 桌面版有它自己的脾气。最常见的是安装完打开设置页面一直转圈或者显示“设置未完成”。这个问题的根因通常不是软件坏了而是桌面版在初始化时依赖的三个基础项没对齐用户目录下的.codex文件夹首次创建失败Windows 没有开启开发者模式影响符号链接创建终端模拟器的权限不足。排查顺序是打开设置 - 隐私和安全性 - 开发者选项确认“开发人员模式”开关是打开的这一步影响 Codex 在 Windows 上创建模拟终端和链接的能力。手动进入%USERPROFILE%\.codex确认目录存在且不是被同步盘如 OneDrive重定向的路径。有很多人把用户目录同步到了云盘结果 Codex 写配置时被云盘锁定设置页就永远转圈。右键桌面版图标选择“以管理员身份运行”等设置页正常后再退出以后用普通方式启动即可。如果你遇到的是“无法加载组织设置”处理思路也在这附近删掉~/.codex下的会话缓存后重启。注意删之前把config.toml和auth.json备份出来只清缓存文件。4.4 组织设置加载失败的处理组织设置加载失败我遇到过两种形态。一种是登录后 Codex 完全读不到组织的任何配置另一种是能读到一部分但模型列表和权限策略缺失。第一种形态的根源通常是登录凭据混乱。我前面说过~/.codex/auth.json里如果有多份凭据Codex 会优先读取错误的那个。处理办法只有一个备份后清掉执行codex login重新登录登录时注意在浏览器里切换到目标组织身份。第二种形态多半是企业自己搭了模型网关组织管理员把模型列表下发逻辑改了。这个你本地没法绕只能找到管理员让网关接口返回完整的模型清单。如果你只是自己搭着玩遇到组织设置加载错误直接忽略组织相关的设置项用--model参数显式指定模型即可这个参数优先于所有组织策略。5. 把本地 Codex 用好的经验与底线5.1 密钥与凭据管理本地部署最大的风险不是模型跑得慢而是凭据泄露。特别是接远程服务商的 API 时Key 一旦被误传到代码仓库或者日志系统里损失很难估。我给自己定了几条死规矩环境变量优先配置文件尽量不写env_key对应的明文值。auth.json和所有含密钥的文件加入.gitignore并单独备份到一个离线位置。定期检查~/.codex/logs目录确认没有把模型的 system prompt 或 API Key 打印在日志里。如果你要给团队用建议不要把配置文件直接发给每个人而是用环境变量注入的方式让每个人的 token 都保持独立出问题也方便单独回收。5.2 沙箱边界与权限收敛Codex 既然能自己执行命令就意味着它有“破坏性”的一面。我看过有人在生产服务器上直接把--sandbox参数关掉让它以完全权限运行结果 Codex 一个误操作把构建目录清空了。正确的做法是本地测试时保留 Codex 默认的沙箱模式甚至故意给它一个只读的测试目录让它在里面跑破坏性命令。必须执行高风险命令如git push时先按Esc中断自动执行手工确认命令内容后再放行。不要用 root 或管理员账号跑 Codex给它建一个低权限用户哪怕它把项目删了也不至于伤到系统。我这里特别强调这一点是因为“会动手”的智能体比“只会聊天”的机器人危险得多权限边界是你能控制它的最后一道闸门。5.3 日志、缓存与日常清理Codex 的日志和缓存会随着使用迅速膨胀尤其是跑长会话时切换过多个模型的话日志里会积累大量请求详情。我建议每周做两次清理rm -rf ~/.codex/logs/* 2/dev/null rm -rf ~/.codex/sessions/*.json 2/dev/null注意 sessions 文件里有全部对话上下文如果你有需要保留的项目建议先单独导出备份再清理否则一个误删就直接丢掉了历史思考链路。清理完记得重启 Codex。如果后续出现莫名其妙的内存飙升先看看日志文件是不是撑爆了磁盘再怀疑模型本身的问题。这个顺序别搞反我排那个内存问题时一直怀疑是本地模型加载了太多参数最后发现是日志积累了 6 个 G浪费了两个小时。我个人现在的习惯是日常写业务代码用 Ollama 的 qwen2.5-coder:14b碰到底层逻辑分析和架构设计时临时切到 DeepSeek 系列模型。整个过程都是在这台本地机器上完成的不拖云端不打断思路改代码就像跟一个坐在旁边的同事协作。如果你也想试我建议你从最小的模型开始跑通流程再逐步换大模型这条路走一遍后面所有报错你都能自己判断是模型问题、配置问题还是网络问题。