最近 Codex 的热度确实高社区里讨论最多的问题从“怎么下载”慢慢变成了“怎么本地部署”“怎么接入自己的模型跑起来”。我花了两天时间从零折腾了一遍把下载、安装、接本地模型、调配置到踩坑排查的完整过程都走通了。这篇就按我实际操作的顺序来写不绕弯子直接把能用、能跑的方案和路径分享出来尤其适合想让 Codex 配合本地大模型比如 Ollama 里的 DeepSeek使用的人参考。1. 先搞清楚 Codex 是哪个 Codex以及本地部署到底解决什么问题先说个容易混淆的点。大家口中的 Codex 现在有两个常见指向一个是 ChatGPT 里的代码生成能力另一个是 OpenAI 开源出来的终端编程代理工具通常以codexCLI 的形式跑在本地命令行里后面也可以接各种兼容接口的模型服务。这篇讲的是后者——本地能装、能配置、能当 AI 编程助手用的这个。为什么要把 Codex 部署到本地而不是直接用云端网页我实际体验下来主要有三个原因数据隐私代码是你最敏感的东西之一很多项目代码根本不适合贴到云端对话里。本地部署后请求可以在可控环境内完成代码内容不必上传到第三方服务。离线可用配合本地模型比如 Ollama 跑的 DeepSeek 量化版后即使网络环境不稳定核心的代码生成、解释、重构功能依然能用这在远程开发或者内网环境里价值很大。成本可控按 API 调用付费的云端方案在长时间、多轮、大批量代码任务下费用涨得很快本地部署一次投入硬件成本后面跑起来基本没有边际费用。此外还有一层“学习价值”。部署 Codex 等于把 AI 编程助手的“前端交互层”和“后端模型层”拆开来看前端负责理解你的自然语言、拼接上下文、组织代码修改后端负责真正生成 Token。搞明白这两层的关系之后想接 DeepSeek、Qwen、Llama 或者其他模型都只是改配置的事。在动手之前先明确一下 Codex 本身的核心机制它是一个跑在终端的编程代理不是简单的“聊天窗口”。它会读取你当前项目的文件结构、Git 状态、文件内容自己规划修改步骤然后直接操作文件、运行命令、检查结果。这意味着它对本地环境Shell、路径、权限、Node 运行时等的依赖非常高很多报错其实不是 Codex 的问题而是本地环境和它之间的配合问题。这也是为什么“本地部署”这件事比单纯“装个软件”要稍微复杂一点——你是在搭一套工具链而不是双击安装一个 App。2. 下载与安装CLI、桌面版和代码解释器到底该选哪一个2.1 原生安装器与手动安装的取舍现在 Codex 的安装方式主要有两类一类是官方提供的安装脚本自动帮你把命令行工具装好另一类是直接通过包管理器比如 npm安装适用于已经有 Node.js 环境的开发者。安装脚本适合第一次接触、不想折腾环境的人npm 方式适合本来就在用 Node 的开发者能更清楚地看到依赖和版本。我试下来npm 方式的可控性更高因为 Codex 本质上是 Node 写的 CLI 工具npm 装完后能直接看到它依赖了哪些包、版本是多少后续升级也方便。如果你对命令行还不太熟用官方安装脚本会更省事。# 官方脚本方式 curl -fsSL https://codex.com/install.sh | sh # npm 方式需要 Node.js 18 npm install -g openai/codex装完之后验证一下版本确认安装没有静默失败codex --version如果提示找不到命令多半是安装路径没进PATH。官方脚本一般会装到~/.codex/bin你要把这个目录加到你的 Shell 配置里.zshrc或.bashrcexport PATH$HOME/.codex/bin:$PATH2.2 Windows 桌面版和 WSL 的选择问题很多人在 Windows 上纠结是装桌面版还是用 WSL我的建议是如果要做正经项目优先 WSL。原因很简单Codex 的很多操作涉及文件路径、Shell 命令、Git 钩子WSL 提供一个完整的 Linux 环境兼容性远比 Windows 原生环境好。桌面版适合尝鲜、看效果但一旦遇到路径拼接、权限模型、符号链接这些坑Linux 环境会省心很多。具体到 Windows 上装 WSL 后再装 Codex和 Linux 上完全一样还是上面那两条命令。唯一要注意的是 WSL 和 Windows 之间的文件互通问题把项目放在 WSL 内部文件系统~/project而不是/mnt/c/...否则文件读写性能会差很多Codex 在大量读取项目文件时会有明显卡顿。2.3 代码解释器模式一个被很多人忽略的入口Codex 除了标准的“自主代理”模式还有一个代码解释器模式codex exec适合你只想让它“执行一个明确任务”而不是“自己规划全流程”的场景。比如你想让它“把这个目录下所有 Python 文件的空行去掉”用解释器模式会更快、更可控它不会自作主张去改别的文件。codex exec 把当前目录下所有 .py 文件的空行去掉这个模式在踩坑时特别好用当标准模式行为诡异你可以先用解释器模式做单点测试快速确认是模型理解问题还是工具链问题不用每次跑完整流程。2.4 安装过程中最常见的失败点安装时最容易出问题的其实不在 Codex 本身而在前置依赖。我列一下真实遇到过的失败原因和对应解法失败现象根因解法npm 安装超时网络源较慢换 npm 镜像源后再装codex 命令找不到PATH 未包含安装目录手动添加 export PATH启动后秒退Node 版本过低升级 Node 到 18WSL 内无法启动缺少必要系统库sudo apt update sudo apt install -y build-essential这些坑基本都是环境问题不是 Codex 代码问题所以排查思路要放在“环境是否满足要求”而不是“Codex 哪里坏了”。3. 本地模型接入让 Codex 用上 Ollama 里的 DeepSeek3.1 为什么要“绕一圈”接入本地模型Codex 默认是连云端模型服务的你需要 API Key 并且按量付费。本地部署的核心诉求就是摆脱这个限制。我们可以在中间加一层兼容接口的服务把 Codex 发出的请求转给本地模型来跑。这里说的“兼容接口”指的是 OpenAI 的 API 格式。Codex 只知道按这个格式发请求、收响应只要模型后端能听懂这个格式Codex 压根不管后面是云端的还是本地跑出来的。所以在本地先起一个“兼容服务”模型用本地大模型就能实现 Codex 界面不变、模型本地化。实际部署中大多数人选择的方案是Codex CLI Ollama本地模型运行时 一个兼容接口层把 OpenAI API 格式转成 Ollama 能懂的格式模型用 DeepSeek 的量化版本显存压力小效果也不错。3.2 Ollama 的安装与模型选择Ollama 是目前本地跑模型最省心的工具之一。它的核心价值在于把模型下载、量化、加载、推理封装得很简单一条命令就能跑起一个大模型不用自己处理显卡驱动、推理框架、依赖库这些问题。安装 Ollama# Linux / WSL curl -fsSL https://ollama.com/install.sh | sh # macOS brew install ollama装好后拉取模型。我没有选最大的版本而是选了量化版本主要考虑是消费级显卡的显存实在有限模型越大加载越慢编程场景下响应速度比绝对精度更重要。ollama pull deepseek-r1:7b这里解释一下量化模型概念大模型训练完的原始参数通常占空间很大比如 70B 模型要 140GB 显存量化相当于把参数精度降低用更少的位来存每个权重换来体积骤减和速度提升。代价是精度轻微下降。对代码生成这个场景来说7B 量化模型的水平足够处理日常的代码解释、改 bug、写脚本这类任务。拉完验证一下能不能正常对话ollama run deepseek-r1:7b 用 python 写一个快速排序看到正常的代码输出说明本地模型已经就绪可以进入下一步配置。3.3 配置 Codex 指向本地模型这一步是核心。Codex 的所有配置都集中在~/.codex/config.toml我的配置做完之后长这样model_provider ollama [model_providers.ollama] name ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat requires_openai_auth false [model] model deepseek-r1:7b provider ollama这里解释三个关键字段也是所有坑里最容易出问题的三个点base_url必须指向 Ollama 的兼容接口地址。Ollama 默认端口是 11434但如果你的 Ollama 跑了不同的端口这里要跟着改。/v1路径别漏漏了之后 Codex 发请求会 404。wire_api chat指定用 chat 格式的接口协议。有些模型或服务只支持 completions 格式就要改成completions。这个是 Codex 和模型服务之间能不能握上手的关键。env_key的值是环境变量名也就是说 Codex 会从环境变量里读这个值作为 API Key。本地 Ollama 其实不校验 Key但你得设置一个否则 Codex 会一直报鉴权失败。随便设一个字符串就能过export OLLAMA_API_KEYollama3.4 启动验证与性能预期配好后启动看 Codex 是否能正常和本地模型对话codex 解释一下当前目录下的 main.py 在做什么如果通了你会看到 Codex 开始读取文件、把内容发给本地模型、接收回复、然后一步步执行。我实测下来的感受7B 量化模型在代码解释、单函数生成、简单重构这些场景下是够用的但复杂多文件任务的理解能力确实不如云端大模型。这是硬件限制不是配置问题。性能参数参考一下我机器是 RTX 4060 8G 显存场景首 Token 延迟单次完整回复耗时单函数生成约 1s5-10s多文件项目理解约 2-3s15-30s复杂重构任务约 2s可能超过 60s如果觉得速度太慢优先检查是不是加载了过大的模型8G 显存跑 14B 模型会吃紧或者 Ollama 的并发设置是否合理。4. 踩坑实录配置文件的报错排查链路与登录问题处理4.1 那个著名的“proxy failed”报错到底怎么回事很多人在配置阶段会遇到一个很头痛的报错文字长这样cc switch local proxy failed while handling codex endpoint /responses。我第一次遇到时也很懵因为报错里出现了“proxy”这个词第一反应是网络代理配置出问题了。排查了很久才发现这其实是 Codex 内部请求处理链路的报错根源不在网络的“代理”而是 Codex 在向模型后端endpoint发请求时中间某个环节没接上。根据我的排查经验这个报错通常对应三种根因配置文件的 base_url 写错最常见。比如少写了/v1或者端口不对Codex 发请求时找不到 endpoint就会在内部转发环节报这个错。模型服务没有启动Ollama 没开或者 Ollama 端口被占用Codex 连不上后端也会在本地转发层报这个错。wire_api 和实际服务不匹配服务端是 chat 接口你配成了 completions或者反过来了请求格式不对报错信息就可能很隐晦地出现在这个环节。排查顺序我自己总结成一个固定流程遇到就直接按这个来# 第一步确认 Ollama 在跑 ollama list # 第二步确认兼容接口能访问 curl http://localhost:11434/v1/models # 第三步用 curl 手动发一个聊天请求模拟 Codex 的行为 curl http://localhost:11434/v1/chat/completions \ -H Content-Type: application/json \ -d {model:deepseek-r1:7b,messages:[{role:user,content:hi}]} # 第四步确认 Codex 本身没坏 codex --version第三步是最关键的。如果 curl 返回正常的 JSON 响应说明模型后端没问题如果 curl 都报错那问题必然在 Ollama 或网络层跟 Codex 无关。先把自己手上的环节验证完再去怀疑 Codex这样排查效率最高。4.2 “无法加载组织设置”和登录不上另一个高频报错是codex启动后提示无法加载组织设置或者直接卡在登录界面打不开。这里要分两类情况用云端官方服务这种情况确实需要登录和授权加载组织设置需要网络能正常连上服务端。如果一直失败大概率是网络连接不稳定或者服务端响应超时换个网络环境试试或者等一段时间再试。本地部署模式如果你已经改成走本地模型requires_openai_auth false那理论上不应该再请求组织设置。但 Codex 的某些版本在启动时仍然会尝试拉取一次远程配置失败后就报这个提示。遇到这种情况检查一下配置里是否还有残留的鉴权相关设置比如requires_openai_auth是否真的设成了false以及环境变量里是否有旧的 API Key 干扰。如果是旧版本残留的登录态导致的问题可以清理一下本地的认证缓存Codex 的认证信息一般存放在~/.codex/auth.json把这个文件备份后删掉重新启动让 Codex 重新走配置逻辑mv ~/.codex/auth.json ~/.codex/auth.json.bak然后重启 codex。注意仅限你确认不是官方付费账号、只是本地部署的情况如果是正规付费用户保留这个文件会更省事不用重新登录。4.3 配置文件解析每个字段的用途与常见的坑config.toml是 Codex 的灵魂文件我把它拆开逐个讲清楚避免你以后不知道改哪里字段作用常见坑model_provider指定默认使用的模型供应商名字必须和下面定义的 provider 名称一致model_providers.*.base_url模型服务的接口地址漏/v1、端口号错误model_providers.*.wire_api指定使用 chat 还是 completions 接口和实际后端不匹配会报奇奇怪怪的错误model_providers.*.env_key指定从哪个环境变量读 API Key环境变量不存在时 Codex 误报鉴权失败model_providers.*.requires_openai_auth是否还需要 OpenAI 平台鉴权本地部署没设 false 会导致一直尝试连官方model.model实际使用的模型名模型名必须和 Ollama 里 pull 的名字一致model.provider该模型使用哪个供应商要和model_provider保持一致这里面最隐蔽的坑是model.model和ollama pull的名字不一致。比如你ollama pull deepseek-r1:7b但配置文件里写的是deepseek-r1Codex 发请求时模型名对不上Ollama 会返回 404。这事排查起来最恼火因为报错不一定直接说“模型不存在”可能显示成其他格式错误。4.4 一个真实排查案例我遇到的一个实际问题配置完所有内容之后启动 Codex 还是报了“cc switch local proxy failed”错误。当时我看配置没问题Ollama 也正常后来一步步排查发现是base_url里漏了/v1。原因在于Ollama 的默认 API 端口虽然监听了但根路径/是不处理 chat/completions 请求的只有/v1/chat/completions才走兼容逻辑。Codex 发出的 endpoint 路径里有/responses但没有正确的/v1前缀转发时就失败。改成http://localhost:11434/v1后这个报错立刻消失了。后来我又在社区里看到很多人遇到同样的问题基本都是这个原因。所以如果你也卡在这一步先检查你的base_url结尾是不是/v1。5. 中文配置与日常使用体验让 Codex 真正好用起来5.1 怎么把 Codex 设置成中文官方软件默认界面是英文但对很多开发者来说中文交互更顺手。Codex 本身没有专门的“语言选项”开关它的回复语言主要受两个因素影响你提问用的语言以及模型本身的回复倾向。如果你用中文提问模型大概率会用中文回复这是最直接的方式。你也可以在系统级配置里注入一个“语言偏好”提示让模型在每次回复时都默认使用中文。方法是在config.toml的顶层加一个指令设置或者更简单的在.codex/下的说明文件AGENTS.md里写明“请始终使用中文回复”# AGENTS.md 请始终使用中文回复所有内容。代码本身保持英文解释、建议、总结使用中文。Codex 在启动时会读取项目目录下的AGENTS.md作为行为约束配合模型本身的中文能力基本能做到全中文交互。实测下来 DeepSeek 的中文理解比英文模型好很多用中文描述需求时生成代码的准确性反而更高。5.2 日常使用的三个高效姿势本地部署完成后在日常使用中我有几个习惯能明显提升体验和准确率任务拆细不要一次丢给 Codex 一个很大的任务比如“帮我写一个完整的电商系统”。本地模型上下文窗口有限任务太大容易丢失前面的信息生成结果会比较泛。拆成“先创建项目结构”“再实现用户登录接口”“再设计数据库表”这样的小步骤效果会好很多。利用 Git 做护栏Codex 操作文件时是有风险的尤其在自主代理模式下它可能改了不该改的文件。我的做法是操作前先git stash或者提交一次让 Codex 在一个可回滚的状态下工作。出问题一条命令恢复git add -A git commit -m before codex changes # 如果 Codex 改出问题 git checkout .用持续集成验证结果Codex 改完代码后强烈建议原地跑一遍测试、lint、构建。很多时候它自己改完是“看起来对”但实际跑不通的。我在AGENTS.md里加了一条规则“每次修改完成后运行npm test验证结果”。这样它每次改动完毕会自动跑测试省掉我自己手动验证的时间。5.3 性能与体验的综合评估本地部署 Codex DeepSeek 之后的整体体验我用一个表来总结维度体验评价说明代码生成能力良好单函数、脚本、常见算法生成准确率高代码解释能力优秀对已有代码的理解和解释非常清晰多文件重构能力一般上下文窗口限制大项目理解有限响应速度良好首 Token 延迟 1s 左右可用稳定性良好配置正确后基本不会崩偶发超时成本极佳无 API 费用仅耗电如果你觉得 7B 模型的能力不太够建议下一步试试 14B 或 32B 的量化版本前提是显存够。显存不够时可以调低上下文长度num_ctx牺牲一些“记忆力”换取更流畅的响应。5.4 如果要接回云端服务怎么无缝切换本地部署做好之后你可能会遇到“有些任务本地模型搞不定想临时切回云端大模型”的情况。Codex 的配置支持多供应商并存你可以在config.toml里同时定义本地和云端两套 provider需要切换时改一行model_provider即可不用大改配置。model_provider ollama [model_providers.ollama] name ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat requires_openai_auth false [model_providers.openai] name openai base_url https://api.openai.com/v1 env_key OPENAI_API_KEY wire_api responses requires_openai_auth true [model] model deepseek-r1:7b provider ollama切回云端时把model_provider改为openai、模型名改成对应的模型 ID 就行。实测这个切换过程在几秒内就能完成基本不影响工作流。6. 从本地部署到日常可用的最后一步部署完成后最后一步也最容易忽略验证整条链路在重启电脑之后还能不能正常工作。因为 Codex 依赖 Ollama 服务如果 Ollama 没有设置开机自启每次开机都要手动启动。WSL 或 Linux 下可以用 systemd 管理systemctl enable ollamamacOS 上安装 Ollama 时会默认注册为自启服务一般不用额外配置。还有一个建议把 Codex 的配置目录纳入你的 dotfiles 管理。~/.codex/config.toml里面的所有配置都是文字文件完全可以跟着你的备份系统走换电脑时一条命令就能还原整个环境。最后分享一个小技巧如果你不确定当前 Codex 到底用的是哪个模型、哪个接口最简单的方式是打开调试日志。Codex CLI 一般可以用--debug或者设置环境变量CODEX_DEBUG1查看每次请求的目标地址和模型名屏幕会直接打印出请求日志。看到日志里写着http://localhost:11434/v1且模型名是deepseek-r1:7b说明请求已经成功发给了本地 Ollama整条链路就没问题了。这一步能帮你排除 90% 的“是不是还在连云端”的疑惑。