把 AI 编程助手 Codex 装在本地、接入自己下载的模型这个组合我实际用了一个多月越用越觉得顺手。这篇文章就从零开始把 Codex 下载安装、本地部署、模型接入的完整过程拆开讲清楚文里所有步骤我都亲自跑过也会把踩坑的点单独列出来。适合想通过命令行真正掌握 AI 编程助手、又不愿意把数据和代码全部交给网页版工具的开发者也适合那些打算把本地大模型和编程场景结合起来折腾的人。1. Codex 到底是什么先搞清楚要搭的是什么1.1 Codex 与普通 AI 编程插件的区别很多人第一反应是Codex 不就是像 GitHub Copilot 那样的自动补全插件吗我一开始也这么想实际用下来发现完全不是一回事。Codex 更像是一个住在终端里的编程代理你给它一句自然语言描述比如“帮我写一个批量重命名图片文件的脚本”它不只是给你一段代码而是会在沙箱环境里真的去创建文件、安装依赖、运行命令、看报错、改代码直到任务完成或者它自己觉得需要找你确认。这种“代理式”的工作流和我以前用的补全式插件有本质区别。自动补全解决的是“下一个字符是什么”Codex 解决的是“接下来这个子任务怎么完成”。它会把一个大需求拆成多个步骤每一步都尝试在本地执行并验证结果。这种模式最大的价值在于它知道你写出来的代码能不能跑而不是只帮你把代码“写完”。1.2 本地部署的两层含义说到“本地部署”很多人会混淆两个完全不同的概念。第一层意思是Codex 客户端本身跑在本地命令行工具也好、桌面应用也好都装在你自己的电脑上。第二层意思是Codex 背后推理所用的大语言模型也跑在本地常见方案就是搭配 Ollama 这类工具来跑开源模型。我这次要讲的“从零搭建”两层都覆盖。也就是说你最终得到的效果是终端里敲codex就能启动一个 AI 编程助手而它背后工作的模型是你自己从模型仓库拉下来、跑在你自己机器上的。这样做的好处很明显数据不出本机不依赖外部 API 的额度也不存在云端把代码拿去训练的问题。坏处也不是没有本地模型的推理速度、复杂代码理解能力跟顶级云端模型还是有差距。所以我把官方模型的接入方式也一并写了方便你两种方案来回切换。1.3 适合谁、不适合谁以我这一个多月的使用体验来看Codex 最适合的是这几类人日常要写大量脚本的运维和开发、喜欢折腾工具链的技术爱好者、以及有隐私敏感代码需求但不想用网页版 AI 的开发者。不太适合的是完全没接触过命令行的小白以及只想要“一句话自动生成整个项目”的偷懒型用户。Codex 能帮你干活但它不是魔法它还是需要你理解自己要做什么只是在“怎么写、怎么改、怎么验证”这些环节上替你省了大量体力劳动。2. 部署前的环境盘点与方案选型2.1 硬件配置只跑 CLI 和同时跑本地模型的差别先把结论放前面如果只用 Codex CLI、不跑本地模型对硬件几乎没有要求。我手上一台 8GB 内存的旧笔记本跑 Codex CLI 加官方模型终端操作完全流畅。因为生成代码的推理任务主要在云端完成本机只是发送请求和展示结果。但如果要把本地模型也跑起来配置就要认真考虑了。以我常用的 qwen2.5-coder 7B 模型为例量化版本占磁盘大概 4.7GB运行时内存占用在 6GB 到 8GB 之间。想要跑 14B 模型内存 32GB 起步。至于显卡有 NVIDIA 显卡且显存在 6GB 以上推理速度会明显提升没有显卡CPU 硬扛 7B 量化模型生成速度大概是每秒 5 到 10 个 token简单任务能忍大段代码会等得比较焦躁。我的建议是如果你想长期把 Codex 当主力工具用内存比显卡更重要。因为很多编码场景是多个会话并行模型本身占内存系统也要留余量。我试过在 16GB 内存的机器上同时开 Codex 会话和浏览器已经能感到明显压力。32GB 内存加一张 8GB 显存的显卡是比较舒服的分界线。2.2 必备软件与基础环境先把软件清单列出来后面逐个讲怎么装软件作用安装建议Node.js 18Codex CLI 依赖 npm 安装推荐用官方 LTS 版本Git项目初始化、代码版本管理按系统默认方式安装Ollama可选本地大模型推理服务官网下载或脚本安装Codex CLI核心编程代理工具npm 全局安装这里有个优先级问题。Node.js 必须先装因为 Codex CLI 最常用、最省事的安装方式就是npm install -g openai/codex。如果你已经装了 Node.js先检查一下版本在终端里执行node --version至少要在 18 以上太老的版本会导致 npm 安装时直接报错。Git 在大多数场景下也是必需品因为codex init会创建和读取项目配置很多代码操作也天然依赖 Git 工作区。2.3 CLI 和桌面客户端到底怎么选Codex 现在主要有两种形态命令行工具和桌面客户端。我个人的使用习惯是主力用 CLI因为它的工作流最透明运行了什么命令、改了哪些文件、每一步经历了什么都在终端日志里看得清清楚楚。桌面客户端胜在界面友好、安装门槛低适合不习惯终端的用户。需要特别提醒的是桌面客户端和 CLI 在某些场景下的配置不一定互通。如果你先装了桌面版、登录了账号再装 CLI不要默认 CLI 就自动继承登录状态。实际情况是两个工具各自独立维护配置需要分别在各自界面里完成登录。所以我的建议是先想清楚你的主要使用场景再决定装哪一种不要两种都装然后配置得云里雾里。如果拿不准先装 CLI它覆盖的场景更全面也更容易排查问题。3. Codex 下载安装与账号认证新手照做版3.1 用 npm 安装 Codex CLI 的完整过程安装过程其实只有四条命令但每一步都可能出幺蛾子我按顺序拆开讲。第一步确认 Node.js 环境node --version npm --version如果系统提示“command not found”就去 Node.js 官网下载 LTS 版本一路下一步安装就好。装完再开一个新的终端窗口否则 PATH 不会刷新。第二步全局安装 Codex CLInpm install -g openai/codex这一步如果网速慢npm 会卡很久。建议先配置国内 npm 镜像源或者耐心等它跑完。安装成功后会有类似“added X packages”的输出。如果出现权限报错通常是因为全局目录没有写权限不要在命令前盲目加sudo更好的做法是检查 npm 的全局目录配置。第三步验证安装结果codex --version能输出版本号说明安装成功了。如果提示“codex: command not found”大概率是 npm 的全局 bin 目录没有加入系统 PATH。用npm config get prefix查看全局目录把它加到你的 shell 配置文件的 PATH 里。这个问题在 Windows 上尤其常见。3.2 登录认证三种方式选一种Codex CLI 首次运行codex命令时会引导你完成登录。我实际试过三种认证方式各自的特点整理如下认证方式场景优点注意点GitHub 授权登录个人开发者常用一次授权长期有效需要浏览器弹出授权页面ChatGPT 账号登录已购买相应套餐的用户与网页端使用同一账号需要保持网络连通API Key 认证脚本化、自动化环境适合 CI 场景Key 需要妥善保管手动触发登录的方式也很简单codex login github执行后终端会输出一个授权链接复制到浏览器打开、确认授权再回到终端看登录就完成了。这里有个很容易踩的坑如果在浏览器里授权之后终端一直没有反应不要反复执行codex login先等十几秒授权回调可能需要一点时间还是不行的话检查一下系统默认浏览器是不是被某些策略拦截了弹窗。API Key 方式相对简单粗暴。在环境变量里设置OPENAI_API_KEY然后直接运行codex它检测到有效 key 就会跳过交互式登录。这种方式我建议只在自动化脚本里用本地日常开发还是用 GitHub 登录更省心。3.3 登录状态与配置文件的生成登录完成后Codex 会在你的用户目录下生成配置文件目录。Linux 和 macOS 的路径是~/.codex/Windows 是%USERPROFILE%\.codex\。在这个目录里最核心的文件是config.toml后面接本地模型、切换模型提供方都要改这个文件。首次运行后如果没找到这个文件可以手动创建一个不影响使用。我想强调的是这个配置文件是 Codex 本地部署真正的“总开关”。很多人登录都成功了但接本地模型怎么也接不上问题几乎都出在 config.toml 的字段写错了。下一章我把完整的配置模板给出来。4. 把 Codex 接到本地模型Ollama 实战4.1 为什么要费劲接本地模型有人可能会问已经能正常用官方模型了为什么还非要接本地模型我的理由有三个。第一隐私和合规。有些项目代码是客户资产甚至签过保密协议我不能把这些代码通过聊天工具发到外部服务去。接本地模型之后整个 Codex 流程从头到尾都在本机完成代码不出网。第二成本可控。云端 API 是按 token 计费的长时间开着会话、反复让 AI 改代码token 消耗很快。本地模型是固定成本电费加硬件折旧怎么算都比 API 便宜。第三断网可用的安全感。当然本地模型也有明显短板。最直观的差距是逻辑复杂的长链条任务比如“重构这个模块并补充所有边界情况的单元测试”本地 7B 模型生成的代码质量明显不如官方大模型容易出现逻辑偏差。所以我的策略是日常简单脚本、批量修改、代码解释这类任务用本地模型复杂架构设计再切回云端模型。两者并不冲突。4.2 安装 Ollama 并拉取代码模型Ollama 是目前最简单好用的本地大模型运行工具iOS 风格不重要关键是它把“下载模型、启动服务、提供接口”这三件事封装得非常干净。安装方式很简单去官网下载对应系统的安装包或者用官方脚本安装。装完在终端里验证ollama --version然后拉取一个适合编程的模型。我常用的是qwen2.5-coder它在代码补全、代码解释、脚本生成方面表现均衡而且有不同尺寸版本ollama pull qwen2.5-coder:7b拉取模型的时候不用担心它会立刻占用大量内存Ollama 是按需加载的。拉完之后可以确认一下ollama list如果列表里能看到你拉取的模型就说明模型就绪了。Ollama 启动服务一般不用手动管安装后它通常已经在后台运行默认监听 11434 端口。验证服务是否正常直接请求它的 OpenAI 兼容接口curl http://127.0.0.1:11434/v1/models能返回模型列表 JSON就说明服务完全可用。4.3 修改 config.toml把 Codex 指向本地模型这一步是本篇文章的核心。先找到用户的配置文件Linux/macOS 在~/.codex/config.tomlWindows 在%USERPROFILE%\.codex\config.toml。我当前使用的配置模板如下# ~/.codex/config.toml model qwen2.5-coder:7b model_provider ollama [model_providers.ollama] name Ollama base_url http://127.0.0.1:11434/v1 wire_api chat env_key OLLAMA_API_KEY然后设置一个环境变量随便填一个值即可因为本地服务不做真实鉴权export OLLAMA_API_KEYollama完成之后重新启动 Codexcodex如果能正常进入对话界面说明本地模型已经接通。怎么确认当前生效的是本地模型而不是云端模型两个方法一是看对话的响应速度本地模型生成代码时会有持续输出的感觉而不是云端那种“等一会突然整段出现”二是看 Ollama 的后台日志当请求过来时会有模型推理记录。这里必须提醒几个常见坑。第一个坑wire_api chat是最重要的字段。Codex 原本用的是 responses 协议但 Ollama 兼容的是 chat 协议这个字段写错请求会一直卡住或者报格式错误。第二个坑base_url一定要写完整路径有些教程写http://localhost:11434不带/v1必挂。第三个坑env_key对应的环境变量必须设置虽然本地服务不校验 key但 Codex 客户端会因为你没设置而直接拒绝启动请求。4.4 补充方案接入 OpenAI 兼容 API以 DeepSeek 为例如果你的机器跑不动本地模型或者想要比本地开源模型更强的推理能力还有一条折中路线把 Codex 接到其他兼容 OpenAI 接口的大模型服务上DeepSeek 是目前很流行的选择。在 config.toml 里增加一个模型提供方[model_providers.deepseek] name DeepSeek base_url https://api.deepseek.com/v1 wire_api chat env_key DEEPSEEK_API_KEY然后设置环境变量export DEEPSEEK_API_KEYsk-你的key启动时指定提供方codex --model-provider deepseek这样做的本质是利用 Codex 对 OpenAI 兼容接口的适配能力让你在不用换工具的前提下自由切换不同的模型后端。我把它放在“本地部署”的主题里说是因为这套配置思路和本地模型完全一致区别只是 base_url 指向的是外部 API 还是本地端口。理解了这个本质以后无论出现什么新模型你都可以用同样的方式接进来。5. 实际项目里的用法会话、审批与代码执行5.1 用 codex init 初始化一个项目Codex 不是那种让你在空目录里瞎问的聊天工具更好的用法是先让它在项目里建立上下文。进入你的项目目录执行cd my-project codex init这个命令会在项目根目录生成配置文件包括AGENTS.md之类用于告诉 AI 项目背景和约定的文件。初始化之后Codex 会按照这个文件里的说明来理解项目结构、编码规范、构建方式。这一步很多人会跳过但实际体验差别非常大。做过初始化的项目Codex 生成的代码明显更贴近项目的既有框架和风格没做的它经常给出与项目结构格格不入的解决方案。5.2 三种运行模式全自动、逐条确认、只读Codex 执行任务时有不同的权限模式我用表格说明模式命令适用场景风险全自动codex --full-auto信任的、低风险的批量改动高它会自作主张执行命令逐条确认默认模式日常开发中每步询问是否执行只读codex --sandbox read-only代码分析、讲解低不能改动文件我强烈建议新手一开始不要用--full-auto至少等到你把一个项目完整跑通过、知道它会在什么情况下执行什么命令再用全自动。我吃过一次亏让它重构一个函数的调用方式它为了验证结果直接执行了测试脚本结果测试脚本本身有副作用把本地临时数据给清了。从那以后我对全自动模式保持高度警惕。默认模式虽然每步都要确认但那种“看它一步步干活”的掌控感才是把 Codex 当伙伴而不是当工具的正确姿势。5.3 多会话管理与日常使用细节Codex 支持多个会话并行。这个功能非常实用我通常一个项目开一个会话互不干扰。常用命令codex 修复 README 里的所有死链 codex resume # 恢复最近一次会话 codex resume 2 # 恢复指定编号的会话还有一个容易被忽略的细节Codex 执行代码是在本地沙箱环境里进行的。默认情况下它会限制对文件系统的写操作范围和命令执行权限。如果你确实需要它安装依赖、修改全局配置文件可以通过--sandbox danger-full-access放开限制但代价是它会完全以你的权限去执行命令。这个开关我建议只在临时需要时使用用完就关。6. 高频问题排查与避坑经验6.1 问题速查表这一节我把实际遇到过的、以及社区里高频出现的问题集中列出来。这些坑都是真金白银换来的经验。现象可能原因解决办法codex: command not foundnpm 全局目录不在 PATH执行npm config get prefix把 bin 目录加入 PATH登录时浏览器没反应授权弹窗被拦截复制终端里的授权链接手动打开本地模型发请求一直卡住配置文件里wire_api或base_url写错核对wire_api chatbase_url 带/v1Ollama 已安装但请求报连接失败Ollama 服务没启动执行ollama serve再请求一次Codex 无法加载组织设置登录缓存过期或组织权限变更codex logout后重新登录cc switch local proxy failed while handling codex endpoint /responses请求链路中配置的本地转发服务未正常运行检查本地转发服务状态、地址和端口确保与配置一致确认后重试请求Windows 桌面版打不开缺运行库或权限不足以管理员身份运行安装最新 VC 运行库界面提示语言是英文无语言设置在项目约定的指导文件里写明“请始终用中文回复”关于最后一条“中文回复”我多解释一句。Codex 的界面元素本身没有独立的中英文语言开关但你可以通过两种方式让它用中文一是在对话里直接说“之后请始终用中文回复”这只会影响当前会话二是把这一条写进项目指导文件里这样每次新会话它都会读到中文要求。我见过有人在配置层面折腾语言开关最后发现还是指导文件里写一句最靠谱。6.2 几个值得长期记住的实操习惯第一全局模型配置尽量保持“默认官方模型为主本地模型按项目切换”的方案。你可以在项目自己的配置文件里单独指定 model_provider这样进不同项目自动用不同模型。第二运行 Codex 前先看一遍它即将执行的命令列表特别是删除和覆盖类操作不要闭眼按回车。第三本地模型拉取到新版本后记得重启 Codex 会话否则它可能还拿着旧模型的缓存上下文在跑。最后分享一个我自己的使用心得。这套 Codex 加本地模型方案跑通之后真正的收益不在于“免费”或者“不用上云”而在于我开始重新审视 AI 编程助手到底应该怎么融入我的工作流。以前用网页版工具我只敢把零碎的、不敏感的问题丢给它现在本地部署之后我敢把整个模块的雏形交给它写因为我知道代码文件不会离开这台机器。这种心理上的安全感带来的效率提升远比模型本身的能力差距重要。如果你也在纠结要不要折腾本地部署我的建议很直接先拿一台 16GB 内存以上的普通电脑按这篇文章的步骤跑通一遍你会很快判断出这套方案适不适合自己。