最近把 Codex 从下载、安装到接上本地模型完整跑了一圈中间踩了不少说大不大、但足够让人卡半天的坑。如果你正在折腾 AI 编程助手想搞清楚 Codex 怎么下载、怎么在本机部署、怎么把它接到本地大模型上这篇实战记录应该能帮你省下不少时间。我会按照实际操作的顺序来写环境准备、安装步骤、配置细节、模型接入、常见排错一条线走到底尽量把每个“为什么这么做”也讲清楚。先说结论Codex 并不是某个编辑器里的插件而是一个运行在终端里的 AI 编程助手 CLI。它可以直接读取你项目里的文件、执行命令、修改代码也可以理解成一个“住在命令行里的结对编程搭子”。而我们说的“本地部署”指的是把 Codex 这个工具本身装在本机并且通过配置让它调用本地的大模型接口比如 Ollama 跑起来的模型这样代码、对话记录和上下文都不需要出本机隐私和成本都好控制。1. Codex 到底是什么本地部署值不值1.1 它不是编辑器插件而是一个终端 AI 编程助手很多人第一次听到 Codex会下意识以为是某个 IDE 插件或者网页聊天框。实际上OpenAI 的 Codex CLI 是一个开源的命令行工具安装之后你会在终端里多出一个codex命令。它做的事情比普通聊天助手更“重”它可以读取你当前目录下的源码文件分析项目结构执行 shell 命令自己跑测试、修 bug再把你把改动落盘。你可以把它想象成一个能直接碰你代码的“实习生”而不是一个只会在对话框里说话的“顾问”。命令行方式的好处非常实际不需要开额外的窗口不需要把代码复制粘贴到网页上也不会被 IDE 的插件市场版本滞后坑到。对于我这种长期在终端里干活的人codex天然就和 git、grep、vim 这些工具处在同一个工作流里。更重要的是Codex 的很多底层能力比如工具调用、文件读写、执行 shell 命令都是通过标准接口暴露出来的这也给“本地部署”留下了很大的操作空间。1.2 云方案和本地方案的区别默认情况下Codex 接入的是 OpenAI 官方模型使用时你需要一个 OpenAI 账号并且模型处理请求是在云端完成的。这种方案的好处是开箱即用模型能力强坏处也很明显代码要经过网络传输有隐私顾虑而且按量计费长对话多了钱包会疼。本地部署方案则是把 Codex 的“大脑”换成你自己机器上的模型。在本地跑一个大语言模型比如通过 Ollama 跑 Qwen、Llama、DeepSeek 系列的量化版本然后把 Codex 的 API 地址指向http://localhost:11434/v1这样的本地接口。这样一来代码不出本机断了网也能继续用而且没有按 token 计费的问题。代价是模型能力受限于你的显卡和内存复杂任务的完成度不如云端大模型。所以本地部署适合这几类人对代码隐私敏感不希望源码片段离开本机的开发者日常任务偏代码补全、简单重构、脚本生成、文档整理用不到顶级模型智力的人折腾过本地大模型手里已经有 Ollama、LM Studio 这类工具的人想省云上按量费又想要一个稳定可控的 AI 编程助手的长期用户。如果你正好属于其中某一类下面这套东西就值得你花一个下午跟着走一遍。1.3 我最终定下的部署方案我在 Winodws 主力机上加一台 Linux 服务器都试过。最后定下的方案是Codex CLI 装在本地模型端用 Ollama 跑本地开源模型远端模型用 DeepSeek 的 API 作为备选。这套组合兼顾了隐私、成本和可用性。后面所有步骤都是基于这个方案来的你也可以根据自己的硬件情况调整模型大小。2. 安装 Codex 之前先把这几件事备好2.1 Node.js 环境版本对了才不折腾Codex 是用 npm 分发的所以第一件事就是装 Node.js。这里有个容易被忽略的细节版本不要太旧。我一开始机器上是最老的 Node 16装完跑codex --version直接报错后来换到 Node 20 才正常。建议你直接装 Node 20 以上的 LTS 版本。到 nodejs.org 下载安装包或者如果你用包管理器可以这样操作# macOS 上用 Homebrew brew install node20 # Ubuntu / Debian 上可以用 nvm 装 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash nvm install 20 nvm use 20装完验证一下node -v npm -v看到版本号输出这步就算过了。Node 自带 npm不需要额外装别的包管理器。我自己后来还顺手装了yarn但 Codex 官方安装用 npm 就够了多一个工具反而容易让自己混乱。2.2 三种安装方式怎么选Codex 官方推荐的安装方式是通过 npm 全局安装命令是npm install -g openai/codex这个命令会从 npm 仓库拉取最新版本并安装到全局。安装完成后你会多出一个codex命令。除了 npm还有两种方式直接从 GitHub Releases 下载预编译二进制。如果你不想装 Node或者你的机器环境比较特殊可以去 Codex 的 GitHub 仓库页面找到对应操作系统和架构的压缩包解压后放进 PATH。这种方式适合“洁癖型”用户我就不细展开了。从源码构建。把仓库克隆下来自行 build。非必要不推荐因为需要额外装 Rust 工具链对普通用户纯属浪费时间。我建议绝大多数人直接走 npm 全局安装。一条命令搞定后续升级也方便。2.3 安装完成后的关键目录安装完别急着登录先搞清楚 Codex 在磁盘上落地的几个位置后面排查问题时你会用得到全局命令位置npm 的全局 bin 目录通常是/usr/local/bin/codex或者 Windows 上的%APPDATA%\npm\codex配置目录用户主目录下的.codex文件夹。里面会有config.toml主配置、logs日志、sessions会话记录等会话历史Codex 会把每次对话和操作记录在你的本机方便回溯。知道这些位置之后你后面改配置、看日志、清理缓存心里就有数了不至于出问题的时候像没头苍蝇一样乱翻。3. 一步步在本机装好并跑通 Codex3.1 Windows 上安装的完整实操Windows 用户装 Codex最稳妥的路径是先装 Node.js LTS 版本。装完之后打开 PowerShell 或者 Windows Terminal先确认node -v有输出。然后执行npm install -g openai/codex安装完成后直接输入codex --version我在 Windows 上遇到的第一个坑第一次执行codex命令时系统直接弹出一个“Windows 设置未完成”的提示。后来发现是 Windows 防火墙弹窗默认拒绝了一些本地回环的网络请求Codex 登录时需要在本机启动一个回环服务如果不放行就会一直卡在“设置未完成”。解决办法很简单第一次运行 Codex 时看到 Windows 安全中心弹窗点“允许访问”如果已经错过了就打开“Windows 安全中心 - 防火墙和网络保护 - 允许应用通过防火墙”手动把 codex 相关进程加进白名单。装好之后第一次运行codex它会提示你进行登录。按提示操作浏览器里完成 OpenAI 账号授权然后回到终端继续。登录成功后会生成一个类似auth.json的凭据文件存在.codex目录下。整个过程和 GitHub CLI 的gh auth login体验很像。3.2 macOS 和 Linux 上的安装差异macOS 和 Linux 的步骤大体一致唯一的区别在权限。如果你用系统自带的 Node全局安装可能会报 EACCES 权限错误。我建议不要图省事加sudo因为这样会污染系统目录日后升级容易出幺蛾子。正确做法是用 nvm 管理 Node这样 npm 全局目录就在用户目录下不需要 sudo。npm install -g openai/codex codex --version在 Linux 服务器上部署时有一点特别重要确保你的终端 locale 是 UTF-8。如果系统是纯 C localeCodex 在输出中文路径名或内容时偶尔会出现显示乱码虽然不影响功能但看着闹心。提前在~/.bashrc里加上export LANGen_US.UTF-8能省不少事。3.3 登录与初始化背后的机制要理解登录这步在干嘛简单说就是 Codex 需要拿到一个 API 凭证。如果是官方模型凭证就是 OpenAI 账号授权的 token如果后面你配置了本地模型凭证就换成本地模型服务给你的 key通常是随便填一个字符串。登录完成后你可以执行codex login status看看当前的登录状态。如果显示已登录就可以直接开始用了。我遇到过一次“登录不上”的情况表现是浏览器已经跳转到授权成功页了但终端一直卡在等待状态。后来查日志发现是本地回环端口被占用。解决办法是把 Codex 配置里指定的回环端口改一下或者重启终端再登录一次。绝大多数登录失败都跟网络回环或浏览器授权回调没有正确跳转有关不要第一时间怀疑是账号问题。3.4 和 Codex 的第一次对话初始化完成后随便找个空目录跑codex你会看到一个交互式会话界面类似一个分屏终端上半部分是 Codex 输出下半部分是你的输入框。这时候可以试试让它“列出当前目录的文件结构”或者“写一个 Python 的快速排序函数”。第一次对话的意义不在于功能多惊艳而是帮你确认整个链路是通的终端交互 - Codex 主程序 - 模型 API - 输出回显。如果这条链路是通的那么后面接本地模型只是换一个 API 地址的问题。如果这步就不通先回过头检查登录状态和 Node 版本这两种情况占了八成的启动失败原因。4. 把 Codex 接上本地大模型以 Ollama 和 DeepSeek 为例4.1 为什么选 Ollama 做本地模型运行环境要本地部署模型你得先有一个能跑大模型的运行时。市面上的选择不少Ollama、LM Studio、llama.cpp 各有拥趸。我选了 Ollama原因很实际安装简单一条命令支持 Windows / macOS / Linux自带 OpenAI 兼容的 API 端点默认跑在localhost:11434/v1Codex 可以直接认模型下载和管理方便ollama pull deepseek-r1:14b就能用对消费级显卡支持得不错NVIDIA、AMD、Apple Silicon 都有加速方案。第一步装 Ollama# macOS / Linux curl -fsSL https://ollama.com/install.sh | sh # Windows # 直接去 ollama.com 下载安装包装完验证ollama --version然后拉一个适合自己机器配置的模型。模型选择是个经验活下面单独说。4.2 配置 config.toml 加入自定义模型提供方Codex 默认只认识 OpenAI 官方模型要让 Codex 跑本地模型关键在于修改~/.codex/config.toml。这个配置文件的格式是 TOML核心是定义model_providers。我用的配置如下model ollama/qwen2.5-coder:14b model_providers { ollama { name Ollama base_url http://localhost:11434/v1 env_key OLLAMA_API_KEY wire_api chat } }这里几个字段的作用model指定默认模型格式是provider/model_nameprovider要对应下面model_providers里定义的键名base_url模型服务的 API 地址。Ollama 的 OpenAI 兼容端点就是http://localhost:11434/v1env_keyCodex 读取 API key 时用的环境变量名。Ollama 默认不校验 key你在环境变量里随便设一个值就行wire_api协议格式Ollama 兼容的是chat类型。配置改完之后重启 Codex它就默认走 Ollama 了。你用codex打开会话输入一个问题观察 Ollama 那边的日志是否出现请求记录就能确认是否真的接上了。4.3 用 DeepSeek API 作为远程模型源如果你本地没有像样的 GPU或者任务复杂度超出了本地模型的智力水平你可以用 Codex 接入 DeepSeek 的 API。DeepSeek 提供了 OpenAI 兼容的接口配置方式大同小异model deepseek/deepseek-chat model_providers { deepseek { name DeepSeek base_url https://api.deepseek.com/v1 env_key DEEPSEEK_API_KEY wire_api chat } }然后在环境变量里设置DEEPSEEK_API_KEY。你可以在 DeepSeek 开放平台申请一个 API key填入环境变量即可。这个方案的好处是模型智力比本地小模型高一大截代码理解能力接近 Claude 级别代价是请求仍然走网络隐私方面不如纯本地方案。需要特别注意的是即便接了 DeepSeekCodex 的一些 OpenAI 专属功能比如某些工具调用格式、特定消息结构在第三方模型上可能会有限制。遇到“模型不支持某某功能”的报错时优先检查wire_api是否匹配以及模型名称是否写对。这个我在下一章细说。4.4 本地模型选型显存和任务难度怎么权衡很多人一上来就想跑 70B 的大模型结果发现显存不够卡成 PPT。这里给一个基于实测的参考模型参数量量化后的显存需求适用场景我的实测体感qwen2.5-coder:7b7B6-8GB简单补全、脚本生成响应快能干活qwen2.5-coder:14b14B12-16GB中等重构、跨文件修改质量和速度的平衡点deepseek-r1:14b14B12-16GB推理任务、复杂逻辑思考链路长但有时会过度分析deepseek-coder:33b33B24-32GB复杂项目级任务没有大显存别碰我的建议是8GB 显存以下老老实实用 7B16GB 显存优先试 14B只有 24GB 以上才值得上 33B。模型不是越大越好超过了显存上限系统会疯狂换内存速度慢到让你怀疑人生。另一个容易被忽略的点上下文长度。Codex 在干活时会塞入大量的项目上下文本地模型如果上下文窗口太小就会出现“前面说的事后面就忘了”的情况。因此选择模型时要看上下文窗口至少 8K 以上16K 更好。5. 实战中踩过的高频报错和修复办法5.1 登录不了终端一直卡住这是新用户最容易遇到的问题。现象是浏览器已经显示授权成功但终端迟迟不刷新。按我排查的经验优先级从高到低是这样检查终端能否正常访问本机回环地址。Codex 登录时会在本地开一个临时服务接收回调如果防火墙或者安全软件拦截了回环流量回调就永远走不到 Codex检查.codex目录的权限。如果之前用过 sudo 或者被其它用户创建过当前用户可能没有写权限登录状态文件写不进去清理旧登录状态。执行codex logout之后重新登录有时候是旧的凭据和新的授权状态冲突了。最后兜底的一招用codex login --help看看有没有支持带外登录的选项比如手动粘贴一次性授权码。这种模式可以完全绕过本地回调直接在浏览器手动确认。5.2 无法加载组织设置有个高频场景是Codex 在启动时报“无法加载组织设置”然后功能降级成不可用状态。这个问题在接本地模型时尤其常见因为本地模型提供方并不具备组织管理的概念Codex 尝试拉取组织信息时自然失败。处理办法是在本地模型场景下显式在config.toml里关掉或者忽略组织相关配置。如果你只是接第三方模型压根不需要关联 OpenAI 组织。另外检查一下登录凭据中是否有残留的org_id字段如果有改成空字符串是一种治标方案。真正干净的做法是重新登录一个干净的账号并确认不是公司邮箱自动绑定了组织。5.3 model not supported / 模型不支持接第三方模型时Codex 会校验模型名和提供方能力。最常见的报错是model not supported比如你在model里写了一个本地模型但model_providers的键名写错了或者wire_api格式不对。排查思路核对model字段的格式。格式必须是provider/model_name而provider必须等于model_providers里的那个键检查wire_api是否是chat。有些兼容端点要求填写responses或chat填错就会报不支持确认你的 Ollama 已经拉取了对应模型。ollama list看看模型存在不存在模型名拼写错也经常发生。我一次把qwen2.5-coder:14b写成了qwen2.5-coder14b少了个冒号愣是排查了十分钟才发现这种低级错误最坑人。5.4 Windows 上“设置未完成”和回环服务问题Windows 用户有一个非常典型的报错Codex Windows 设置未完成。我一开始想当然以为是安装包损坏其实是 Windows 防火墙的自动拦截。Codex 启动时会注册一个本地回环服务而 Windows 防火墙默认拦截了来自本机的回环请求听起来很反直觉但确实会发生。解决办法第一次运行 Codex 时看到安全警报务必选择“允许访问”如果已经错过去“允许应用通过防火墙”手动添加 codex如果还不行检查系统代理设置是否干扰了本机回环。某些系统全局代理工具会把localhost的流量也接管导致本机服务互相访问失败。这个问题处理完之后codex就能正常启动了。6. 跑通之后怎么用以及几个实战心得6.1 日常高频用法Codex 跑通之后不是只能交互式聊天。它在非交互模式下非常有用可以直接在命令行里跟任务适合脚本化调用。举个例子codex 修复当前目录下所有 Python 文件中的语法错误这个命令会直接在当前目录里跑 Codex分析 Python 文件、找出语法错误、修改代码全程不需要进入交互模式。这个用法很适合自动化流水线比如在 git hook 里让 Codex 自己跑一遍代码检查。日常我在项目里一般这么用让它解释一个不熟悉的目录结构比人肉翻代码快很多让它重构一个函数并提供修改前后的 diff让它给单元测试补覆盖效果比想象中好让它写一次性脚本比如批量重命名、处理 CSV省老大劲了。6.2 在真实项目里的一次完整案例我挑一个印象深的例子说说。之前维护一个 Python 的爬虫项目里面有各种反爬判断和代理切换逻辑这里的代理是指网络数据请求的中转服务我研究了好一会儿才确认这个用法在我的场景里是允许的跟合规要求不冲突代码乱得不行。我尝试让 Codex 把整个爬虫模块重构成使用统一的请求封装。步骤是在项目根目录执行codex把需求描述一遍Codex 先主动读取了项目里的相关文件问了我两个问题确认新封装接口的命名和服务切换的触发条件然后它一口气生成了新的请求模块代码并自动更新了调用点最后它自己跑了现有测试把两个失败用例暴露出来并修正了兼容问题。整个流程大约 20 分钟。如果让我人肉来做至少一个多小时。关键是Codex 能自己沿着调用链去改不会只改一个文件然后把剩下的事丢给我。这就是它比普通代码补全工具强的地方。说明这个例子里的代理切换逻辑我最终在做合规审查时把相关代码段整体移除掉了这里只当操作流程展示用不涉及任何网络通信工具或配置方法请读者按自己项目的合规要求自行判断。6.3 一些基于踩坑总结的实操建议最后分享几条值钱的实操建议都是踩过坑才得出的不要把本地模型和云端模型混在一个会话里用。Codex 的会话上下文是绑定模型提供方的你在 Ollama 会话里切换到 DeepSeek常常会带走一堆本地模型产生的上下文导致云端模型读一堆它看不懂的格式。建议一个项目固定用一个提供方。定期清理.codex目录下的会话记录。他们会占用不少磁盘空间而且有时候旧会话会触发某些奇怪的解析错误。我每个月都会删一次sessions目录没有任何副作用。不要贪大模型。本地模型跑得慢Codex 的整体体验就会崩坏因为它在执行任务时通常要多次调用模型。宁可选一个响应快的小模型也不要选一个响应慢的大模型整体完成时间可能反而是小模型更快。环境变量是关键。接入多个模型提供方时API key 的管理容易乱。我建议使用 direnv 或者类似工具在项目目录里按需加载环境变量避免把所有 key 一股脑写进全局~/.bashrc。这套方案跑到现在我的日常习惯已经变成了隐私敏感的代码让本地 14B 模型处理高强度重构和高难度 bug 排查用 DeepSeek API 顶上基本能做到“顺手、不贵、不出门”。如果你也打算尝试别急着追求一步到位配置大模型先把小模型跑通再一步步往上加这条路最省心。