Codex CLI下载与本地部署：接入Ollama本地大模型实战

本地跑AI编程助手这件事，我从去年就开始折腾，前后在Windows、macOS和一台Ubuntu服务器上都部署过一遍。标题里说的"Codex下载与本地部署"，核心其实就是把Codex这个命令行编程代理装到自己的机器上，再决定是接云端模型还是接本地模型，最后跑通一个真实任务。很多人卡在第一步——不知道装哪个版本、装完连不上模型、报错看不懂，这篇就把从下载到跑通的完整链路摊开讲，顺带把踩过的坑一次性说清楚。适合想省API费用、对代码隐私有要求、或者单纯想学本地大模型部署的开发者，基础薄弱也能跟着做下来。

1. 先弄清楚Codex本地部署的真正价值

1.1 Codex这个词到底指什么

聊部署之前得先把概念对齐，不然网上搜出来的东西会把你绕晕。Codex这个词在当前语境下主要指向两个东西，一个是OpenAI推出的命令行编程代理工具Codex CLI，它是一个跑在你终端里的智能助手，能读代码、改文件、执行命令、跑测试；另一个是早年OpenAI那个已经下线的代码补全模型，那个东西现在基本只存在于历史文章里。你搜"Codex本地部署"，绝大多数人指的都是前者，也就是那个用Rust写的、可以通过npm或者Homebrew装的CLI工具。

搞清楚这一点很重要，因为它的部署逻辑和传统的"下载一个软件双击安装"完全不一样。Codex CLI本质上是个客户端，它自己不带模型，所有的推理能力都得靠外部的模型服务提供。你可以把它理解成一个特别聪明的遥控器，遥控器本身不会思考，真正干活的是电视那头的大脑。这个大脑可以是OpenAI官方的云端服务，也可以是你自己用Ollama、vLLM之类工具在本机跑起来的大模型。

所以"Codex本地部署"这个说法其实包含两层含义：一是把Codex CLI这个客户端装到本地，二是把模型服务也搬到本地，让整条链路都不出你的机器。只装客户端而接云端API，那叫"本地使用"；客户端和模型都在本地，才叫真正意义上的本地部署。这两者的配置差别很大，后面会分别讲。

1.2 为什么要折腾本地部署

有人会问，直接用官方云端服务不香吗，为什么非要本地部署。这个问题我被问过太多次，答案其实取决于你的实际处境。如果你只是偶尔用用，代码也没什么敏感内容，那确实没必要折腾，云端模型的智力水平目前还是碾压本地小模型的。但如果你符合下面几种情况，本地部署的价值就体现出来了。

第一种是对代码隐私有硬性要求。有些团队的项目代码不允许上传到任何第三方服务器，这时候你必须保证从输入到输出整条链路都在自己的可控范围内。本地部署模型之后，你的代码片段、项目结构、甚至调试日志都不会离开本机，这对合规敏感的团队来说是刚需。第二种是网络环境不稳定或者API费用敏感。长期高频使用云端API，成本会累积得很快，而本地模型跑起来之后，除了电费基本没有边际成本。第三种是断网环境或者离线办公，比如在飞机上、在隔离网络里，本地部署能让你照样用上AI辅助编程。

当然也要说清楚代价。本地能跑起来的模型，参数量通常远小于云端模型，代码理解能力和复杂任务的处理能力会有明显差距。一个7B到14B参数的本地模型，处理简单的代码补全、函数改写、单元测试生成还行，但让它独立完成跨多文件的重构，基本会翻车。所以我个人的定位是：把本地部署当成一个"保底方案"和"隐私场景专用通道"，而不是完全替代云端。日常复杂任务走云端，敏感任务和离线场景走本地，两条腿走路最实际。

1.3 部署路线的三种选择

在动手之前，你需要先决定走哪条路线，因为不同路线的准备工作完全不同。我把常见的组合整理成下面这张表，你可以对号入座。

第一条路线最简单，装个客户端配个API Key就完事，十分钟搞定。第二条路线和第一条差不多，只是多了一层配置自由度，可以随时切换不同的模型提供商。第三条才是真正费劲的那条，需要你有足够的显存、正确的推理引擎、还要调通客户端和本地服务之间的对接。

我这里主要讲第三条，但前两条的安装步骤是共用的，因为Codex CLI本身只有一个安装流程，区别只在配置文件怎么写。所以哪怕你暂时不打算本地跑模型，把客户端装好也是有用的，后面想切本地随时能切。

2. 本地部署前的硬件与软件环境盘点

2.1 硬件门槛：显存到底该怎么算

本地跑大模型，硬件里最关键的指标是显存，其次是内存和存储。很多人上来就问"我要装哪个模型"，其实顺序反了，应该先看自己有什么卡，再决定模型规模。显存不够，再好的模型也跑不动，强行跑量化版体验也会很差。

显存占用主要由三部分组成：模型权重、KV Cache、以及推理框架的运行时开销。模型权重这一块有简单的估算公式，参数量乘以每个参数的字节数。FP16精度下每个参数占2字节，INT8占1字节，INT4占0.5字节。举个例子，一个7B参数的模型，FP16精度需要约14GB显存，INT8约7GB，INT4约3.5GB。这就解释了为什么量化这么重要，它能让同样的卡跑起更大的模型。

KV Cache是很多人忽略的部分，它和上下文长度直接相关。上下文越长，KV Cache占用越大。粗略估算的话，它和模型的层数、注意力头数、序列长度都成正比。一个7B模型在8K上下文下，KV Cache可能占用1到2GB，开到32K上下文可能就到4到8GB了。所以你在配置里把上下文拉满，很可能反而导致显存溢出。

我的经验是这样配置比较稳：8GB显存可以跑7B的INT4量化模型，上下文控制在8K以内；16GB显存可以跑14B的INT4，或者7B的INT8；24GB显存能跑32B的INT4，这是目前性价比比较高的档位；如果只有纯CPU和内存没有独显，那只能跑7B以下的模型，速度会比较感人，用来做简单补全勉强够用。买卡之前建议先去模型页面看别人实测的显存占用，比自己算更靠谱。

2.2 基础软件栈：Node.js、Python、Git三件套

硬件确认之后，接下来装基础软件。这套工具链里有三个东西是绕不开的：Node.js用来装Codex CLI，Python用来跑一些辅助脚本和部分推理工具，Git用来管理配置和拉取项目。这三个的安装顺序无所谓，但版本要选对。

Node.js是重点，因为Codex CLI是通过npm分发的。它的较新版本对Node版本有要求，建议直接上Node 20以上的LTS版本，太老的版本会导致安装报错或者运行异常。安装方式我推荐用nvm或者fnm这类版本管理工具，而不是直接下安装包。原因是版本管理工具能让你在多个Node版本之间自由切换，不至于为了一个工具把整个系统的Node版本锁死。Linux和macOS上用nvm很顺，Windows上现在fnm的体验也不错。

安装完记得验证一下，终端里敲node -v和npm -v，能正常输出版本号就说明装好了。如果提示找不到命令，多半是环境变量没配好，Windows用户尤其容易遇到，装完之后要重开终端或者手动把安装路径加到PATH里。

Python这边，建议装3.10以上的版本。虽然Codex CLI本身不依赖Python，但你在部署本地模型、写自动化脚本、或者用一些辅助工具的时候会用到。装Python的时候记得勾选"Add to PATH"，Windows上这一步漏了后面会很麻烦。Git的话，装完除了配置用户名邮箱之外，建议顺手把换行符的处理配好，不然后面拉取项目可能出现行尾混乱的问题，具体命令后面第4节会讲。

2.3 Ollama本地推理引擎安装

本地跑模型，你得有个推理引擎，它负责加载模型权重、处理请求、返回结果。目前对新手最友好的选择是Ollama，它把模型下载、量化、服务化都打包好了，一条命令就能跑起来一个模型，省去了自己配环境的痛苦。当然它也有局限，后面会提。

安装方式按系统分。macOS上可以直接从官网下dmg安装包，也可以用Homebrew装。Windows上有官方的安装程序，双击一路下一步就行，装完它会自动在后台注册成服务，开机自启。Linux上最方便的是用一行安装脚本，不过国内网络环境下这个脚本拉取可能会慢，需要有点耐心，或者配置镜像源。

装好之后验证，终端里敲ollama --version，有版本输出就对了。然后敲ollama list看看当前有哪些模型，刚装完一般是空的。Ollama默认监听在11434端口，你可以用curl http://localhost:11434测试服务是否在跑，返回一句"Ollama is running"就说明服务正常。

提示：Ollama的模型默认存在用户目录下的.ollama文件夹里，模型文件动辄几个G，如果你的系统盘空间紧张，建议通过环境变量把模型存储路径改到大容量磁盘上，不然很快就会把C盘或系统盘塞满。

这里要提前说一个坑，Ollama虽然方便，但它对并发请求和超长上下文的支持比较有限，主要用于单用户本地场景。如果你要做团队共享或者高并发，那得上vLLM、LM Studio的服务端模式或者llama.cpp的服务模式。不过对个人本地部署Codex这种场景，Ollama完全够用。

3. Codex CLI的下载与安装实操

3.1 三种安装方式对比与选择

Codex CLI支持好几种安装方式，我挨个试过，各自的适用场景不太一样。第一种是npm全局安装，命令是npm install -g @openai/codex，这是最通用的方式，三个平台都能用，只要你装了Node就能装。缺点是npm的全局安装有时会遇到权限问题，Linux和macOS上可能需要加sudo，或者把npm的全局目录配到用户目录下。

第二种是Homebrew，macOS和Linux上都能用，命令是brew install codex。这种方式的好处是升级方便，brew upgrade一条命令就搞定，而且它会把依赖也一并处理好。缺点是Homebrew本身的安装和网络配置对新手有点门槛，而且Windows上用不了。

第三种是直接下载预编译的二进制文件。GitHub Releases页面会提供各平台的压缩包，下载解压后把可执行文件放到PATH里就能用。这种方式适合没有Node环境、或者网络受限装不了npm的场景。缺点是手动升级麻烦，每次更新都要重新下载。

我个人的建议是：如果你已经有Node环境，直接npm装最省事；macOS重度用户用Homebrew；网络环境特殊或者想控制版本就用二进制。不管哪种方式，装完都用codex --version验证一下，能出版本号就算成功。如果报"command not found"，八成是PATH问题，找到可执行文件的实际位置，把它所在的目录加到PATH里重启终端即可。

3.2 首次运行与认证流程

装好之后第一次运行codex，它会引导你做认证。认证有两条路，一条是用ChatGPT账号登录，一条是填API Key。这两条路对应的计费和权限模型不一样，选哪个看你的账号情况。

如果选账号登录，终端里会弹出一个链接，你在浏览器里打开、登录、授权，然后把回调信息粘贴回终端。整个过程和很多CLI工具的OAuth流程类似。如果选API Key，你需要去模型提供商的平台后台生成一个Key，然后按提示填进去，或者手动写进配置文件。

这里有个实操细节值得说。认证信息默认存在用户目录下的配置文件夹里，Windows是%USERPROFILE%\.codex，macOS和Linux是~/.codex。这个目录里除了认证信息，还有配置文件config.toml。建议你搞清楚这个目录的位置，因为后面所有的模型切换、提供商配置都在这里改。如果你之前认证过又想换账号，直接把这个目录里的认证相关文件删掉再重新运行即可，不用重装整个工具。

注意：认证文件里包含你的凭证信息，不要把它提交到Git仓库，也不要在截图里暴露。如果你要分享配置给别人参考，记得先把Key相关的字段抹掉。

3.3 目录结构与关键文件说明

把配置目录摸清楚能省很多事。~/.codex目录下通常有这么几个东西：config.toml是主配置文件，认证相关的文件存Key或Token，还有历史记录、日志之类的文件。项目层面，Codex CLI会读取你当前项目根目录下的AGENTS.md文件，这个文件用来给Agent提供项目级的指令，比如代码规范、构建命令、测试命令等。

AGENTS.md这个设计我觉得挺聪明，它相当于给AI助手写了一份项目说明书。你可以在里面写清楚这个项目用什么语言、怎么跑测试、有哪些约定俗成的规则、哪些目录不要动。写得好能显著提升Agent的表现，因为它在动手之前就知道这个项目的脾气。建议每个稍微大点的项目都维护一份，内容不用长，几行到几十行就够。

config.toml是另一个核心文件，模型选择、提供商配置、审批策略、沙箱策略都在这里定义。它的语法是TOML，结构清晰，后面第4节会给出完整的配置示例。初始状态下这个文件可能不存在或者只有很少内容，你完全可以手写，不用依赖初始化命令。

4. 接入本地大模型：让Codex跑在自己的机器上

4.1 本地模型选型与拉取

要让Codex接本地模型，先得有个能用的本地模型。选模型的时候主要看两点，一是参数量要和你的显存匹配，二是模型的代码能力要过关。不是所有大模型都擅长写代码，有些模型通用对话很强，但在代码任务上表现平平。专门做代码的模型通常在代码理解和生成上更有优势，但也有些通用模型在代码任务上表现意外地好。

对本地部署来说，参数量的选择直接决定体验。7B级别的模型适合快速补全和简单任务，反应快但能力有限；14B级别是个甜点区，能力有明显提升，显存要求还能接受；32B级别能力更强，但需要较高配置。我一般建议从7B开始，跑通整个链路之后再根据体验升级，不要一上来就挑战大模型，容易被各种环境问题劝退。

拉取模型用Ollama的命令就行，比如ollama pull 模型名:标签。标签里通常带参数量和量化等级，比如7b、14b、q4_K_M这种。拉取过程会下载几个G的文件，网络好的话几分钟到十几分钟。拉完之后用ollama run 模型名可以交互测试，确认模型能正常对话再往下配。

这里有个我踩过的坑：不同模型的标签命名规则不统一，有些用冒号加版本号，有些直接是模型名。下载之前最好去模型页面确认准确的标签名，输错了会提示找不到模型。另外，同一个模型可能有多个量化版本，量化等级越高越精确但越占显存，越低越省显存但质量下降，选Q4或Q5这种中等量化通常比较平衡。

4.2 配置文件改写详解

模型就绪之后，改config.toml让它指向本地服务。关键是要理解配置文件里的provider概念。provider就是模型服务的来源，官方云端是一个provider，你本地跑的Ollama是另一个provider。通过定义自定义provider，就能让Codex把请求发到你本地的端口。

下面是一个接入Ollama的配置样例，你可以直接参考：

model = "你的模型名:标签" model_provider = "ollama" [model_providers.ollama] name = "Ollama Local" base_url = "http://localhost:11434/v1" env_key = "OLLAMA_API_KEY" wire_api = "chat"

逐行解释一下。第一行model指定默认使用的模型名，必须和Ollama里的模型名完全一致，大小写和标签都不能错。第二行model_provider指定用哪个provider，对应下面定义的那一段。方括号那行定义了一个名为ollama的provider，name是显示用的名字随便起，base_url指向Ollama的OpenAI兼容端点，注意结尾的/v1不能少，少了会对接失败。env_key是环境变量名，Ollama本身不校验Key，随便设个环境变量占位就行，但字段不能缺。wire_api指定用chat接口，这是目前兼容性最好的方式。

提示：配置字段会随Codex CLI版本更新而变化，我上面写的是通用结构。如果你升级后发现配置不生效，先去官方仓库看最新的配置文档，重点确认字段名有没有变。

改完配置保存，重新运行codex，如果一切正常，它就会把请求发到本地Ollama。你可以在另一个终端敲ollama ps看有没有请求进来，来确认是不是真的连上了。如果启动就报错，先看错误信息里的关键词，八成是base_url写错或者模型名对不上。

4.3 跑通第一个真实任务与效果验证

配置对了之后，找个真实的小任务验证。我建议从最简单的开始，比如让它解释一个函数的作用、给一段代码加注释、或者写个简单的单元测试。别一上来就让它重构整个项目，本地模型的能力撑不住，容易让你误以为配置有问题。

验证的时候打开终端，进入一个测试项目目录，运行codex，然后输入你的需求。观察它的表现，重点看三件事：它有没有正常读到你的项目文件、有没有发起工具调用、返回的结果是不是针对你的代码。如果它只是泛泛而谈不看你代码，那可能是工具调用没配好；如果它读了文件但回答质量很差，那可能是模型能力问题，换个更大的模型或者专门做代码的模型试试。

跑通之后你会发现一个现实：本地模型在CLI这种需要频繁工具调用的场景下，稳定性不如云端。这是因为工具调用对模型的指令遵循能力要求很高，小模型经常会出现格式错误、参数缺失、或者干脆不调用工具直接瞎编的情况。所以本地部署的定位要放对，它更适合那些简单重复的辅助任务，复杂任务还是交给云端。我自己的用法是日常补全和代码解释用本地，跨文件重构和复杂调试切云端。

5. 常见报错与排查实录

5.1 安装与权限类问题

安装环节最常见的问题集中在权限和环境上。npm全局安装报EACCES错误，是Linux和macOS上的经典问题，原因是npm的全局目录需要root权限，而你用普通用户装的。解决方案有两个，一是用sudo安装，但不推荐，因为这会让全局包归root所有，后面管理麻烦；二是把npm的全局目录改到用户目录下，一劳永逸，改完重新安装即可。

Windows上的典型问题是装完命令找不到。这通常是因为npm的全局路径没加到系统PATH里。你可以用npm config get prefix查看全局目录在哪，然后把这个路径手动加到环境变量。另外Windows上装Node的时候如果用管理员权限装到系统目录，普通终端有时会读不到，建议装到用户目录。

还有一个隐蔽的坑是版本冲突。如果你机器上有多个Node版本，用nvm切换之后，之前全局装的包可能因为属于另一个版本而找不到。这时候需要在当前版本下重新装一次。所以用版本管理工具的时候，要养成"切版本后重装全局工具"的习惯，避免莫名其妙的找不到命令。

5.2 连接与端点类问题

接入本地模型之后，连接问题是最常见的。典型报错是connection refused或者timeout。connection refused一般是Ollama服务没起来，或者端口不对。先在终端确认ollama ps有输出、curl http://localhost:11434能通，再排查Codex这边。端口被占用的话，Ollama可以改默认端口，改完记得同步更新配置文件里的base_url。

timeout通常有两种情况，一种是模型加载太慢。首次调用某个模型时，Ollama要把模型从磁盘加载到显存，这个过程可能要几十秒，如果客户端超时时间短，就会报超时。解决方法是先用ollama run手动触发一次加载，让模型常驻显存，再去调Codex。另一种是上下文太长导致的推理超时，这个只能通过调小上下文或者换更强的硬件来缓解。

还有一种报错是返回格式不对，提示解析失败。这通常是模型不支持标准的工具调用格式导致的。有些模型的chat接口返回结构和OpenAI规范有差异，客户端解析不了。解决办法是换一个对工具调用支持更好的模型，或者调整wire_api的配置试试不同的接口类型。这类兼容性问题在本地部署里很普遍，选模型的时候优先选那些在社区里被验证过能和CLI工具配合的。

5.3 性能与体验优化

跑通之后想让它更好用，有几个方向可以优化。首先是模型加载策略，Ollama默认会在一段时间不活动后卸载模型释放显存，下次调用又要重新加载。如果你频繁使用，可以通过环境变量把保活时间设长一点，让模型常驻，省去反复加载的时间。代价是显存一直被占着，看你取舍。

其次是上下文管理。CLI工具在干活的时候会往上下文里塞不少东西，项目文件、历史对话、系统提示词都算。上下文开太大，推理变慢还容易显存溢出；开太小，模型记不住前面的内容。我的经验是本地模型把上下文控制在8K到16K之间比较平衡，再大收益就不明显了。

第三是任务粒度控制。本地模型不适合长链条的复杂任务，你要主动把大任务拆成小步骤，一次只让它做一件事，做完确认没问题再继续。比如不要让它"重构这个模块"，而是"把这个函数拆成两个更小的函数，保持原有逻辑不变"。任务越具体，本地模型的成功率越高。这个技巧看着简单，但对体验的提升非常明显。

最后是给项目写一份好的AGENTS.md。前面提过，这个文件是给Agent的项目说明书。把构建命令、测试命令、代码风格、禁区都写清楚，能显著减少它瞎试的次数。你写得越明确，它犯错越少，这在本地小模型上体现得尤其明显，因为小模型的纠错能力弱，需要你提前把路铺平。

6. 我的实操心得与进阶玩法

6.1 几个提升体验的实用技巧

折腾了这么多轮，攒了几个挺实用的小技巧，分享出来。第一个是搭一个"模型切换开关"。因为你要在本地和云端之间来回切，每次都手改配置文件很烦。我的做法是准备两套配置片段，用脚本一键替换config.toml，或者在配置里定义多个provider，通过命令行参数指定用哪个。这样切换只要一条命令，效率高很多。

第二个是给本地模型配一个专门的测试项目。不要拿你正在开发的重要项目去试本地模型，容易被它改坏。建一个独立的沙箱项目，放一些典型代码，用来测试新模型、新配置、新提示词。这样既能放心大胆地试，又不影响正常工作，调试的时候心态也好。

第三个是关注模型的工具调用能力而不是单纯看参数。同一个参数量级下，不同模型的工具调用稳定性差异很大。有的模型参数多但工具调用稀烂，有的模型参数少但配合CLI很稳。选模型之前多看看社区里的实测反馈，别只看跑分。跑分高的模型不一定适合Agent场景。

第四个是善用审批和沙箱模式。Codex CLI有审批策略和沙箱策略的配置，可以控制在执行命令前是否需要你确认、能访问哪些目录。本地模型犯错概率高，把审批开严一点，让它每步都问你一下，虽然麻烦但安全。等你对某个模型的表现有把握了，再放宽策略提升效率。

6.2 后续可以这样扩展

链路跑通之后，能玩的方向还挺多。一个方向是把多个本地模型组合起来，简单任务用小模型快速响应，复杂任务路由给大模型，做个本地的模型路由层。另一个方向是接入知识库，把团队文档、项目历史通过检索的方式喂给模型，让它在回答时能引用你内部的资料，这个和Dify那类工具的思路类似，可以在本地搭一套。

还有一个我觉得挺有价值的方向是把这套环境做成可复制的脚本。你在一台机器上配好之后，把安装命令、配置文件模板、AGENTS.md模板整理成脚本，新机器上一条命令就能复现整套环境。这样换电脑或者给团队同事部署的时候省大量时间，也能保证环境一致性。我自己就维护了这么一份脚本，从Node安装到模型拉取到配置生成全自动化，重装系统之后十分钟就能恢复工作环境。

最后提一句网络搜索里那些混进来的奇怪词条，比如各种名不副实的下载站和来路不明的app，这类东西和Codex本地部署没有半点关系，纯属蹭热度的垃圾信息，看到直接忽略。真正的部署只需要用官方渠道的安装命令和公开的模型仓库，任何让你去下"增强版""破解版"工具的都是坑，别碰。老老实实走官方链路，虽然第一次配的时候麻烦点，但胜在稳定可控，后面出问题也好排查。

我在实际使用中最深的体会是：本地部署的价值不在于它能替代云端，而在于它给了你一个完全自主的选项。当隐私、成本、网络这三样里有任意一样成为约束时，手里有一套能自己掌控的AI编程环境，那种踏实感是云端给不了的。至于能力差距，随着开源模型迭代，这个差距正在肉眼可见地缩小，值得持续关注。