1. 为什么要在本地折腾一个 AI 编程助手
1.1 从“云端对话”到“本地常驻”的动机转变
最开始我用 AI 辅助写代码，基本就是浏览器开个标签页，把报错信息复制进去，等它吐一段建议出来，再手动贴回编辑器。这个流程在写小脚本时还能忍，一旦进入多文件、跨模块的真实项目，来回切换窗口的割裂感就非常明显了。你正在专注地追一个调用链，突然要跳出去描述上下文，思路断掉之后再接回来，成本比想象中高得多。
后来我开始关注能在本地跑起来的编程助手方案，核心诉求其实就三条：第一，它得能常驻在我的开发机上，随叫随到，不用等网页加载；第二，它要能直接读写我项目目录里的文件，而不是让我手动搬运代码片段；第三，网络波动或者服务端限流的时候，我手头的活儿不能直接停摆。Codex 这类工具吸引我的地方，正是它把“对话”和“操作文件系统”这两件事捏在了一起，你可以让它读某个文件、改某段逻辑、跑一条命令，整个交互是贴着项目本身走的。
这里要先说清楚一个概念上的区分，免得后面绕晕。很多人嘴里的“Codex”其实指两个层面的东西：一个是模型能力本身，另一个是承载这套能力的命令行工具或者说客户端。我们这篇要做的“下载与本地部署”，重点落在客户端工具的安装配置，以及如何把它接到一个可用的模型服务上。至于模型是跑在本地还是走远端接口，这是后面配置环节要单独决策的事，两条路我都会讲到。
适合读这篇的人大概是这样几类：一是天天写代码、想把手头的 AI 辅助流程固定下来的开发者；二是对本地部署这套东西感兴趣，但被 Docker、环境变量、配置文件这些名词劝退过的朋友；三是已经在用某个 AI 编程工具，但想换一套更可控方案的人。不管你之前有没有碰过容器化部署，我都会尽量把每一步的“为什么”讲透，让你不是照着敲命令，而是知道自己在干什么。
1.2 本地部署到底解决了哪些真实痛点
先泼一盆冷水，本地部署不是银弹，它解决的是特定场景下的特定问题。我把它拆成几个维度来看，你对号入座就行。
响应延迟与稳定性。走远端服务时，你的每一次请求都要经过网络往返，高峰期排队、超时、偶发 5xx 都是家常便饭。本地部署之后，请求路径缩短到本机进程之间，延迟基本稳定在毫秒级，不会因为外部服务抖动而中断。对于需要频繁交互的场景，这个体感差异非常大。
数据边界。有些项目代码不方便往外发，这时候把模型和工具都放在本机，数据不出机器，心里踏实。这一点对做企业项目或者涉及内部逻辑的开发者尤其重要。
可定制性。本地部署意味着配置文件在你手里，你可以改超时时间、改并发数、改模型参数、换接入的后端。云端服务给你什么你就用什么，本地这套是你说了算。
成本可控。如果你有一台配置还行的机器，本地跑推理的边际成本接近于零。当然前提是硬件扛得住，这个后面会细说。
反过来说，本地部署也有它的代价：初次配置有学习成本，硬件有门槛，模型效果可能不如顶级云端服务。所以我的建议是，先想清楚自己最在意哪一点，再决定投入多少精力。
1.3 整体方案的全景图
在动手之前，先把整条链路在脑子里过一遍，这样后面每一步你都知道它处在哪个位置。
整条链路大致是这样：最底层是运行环境，也就是你的操作系统加上容器运行时；往上一层是 Codex 客户端工具本身，它负责接收你的指令、组织上下文、调用模型；再往上是模型服务层，可能是本机跑的一个推理服务，也可能是一个兼容接口的远端地址；最上面是你实际的项目目录，工具通过文件系统读写和命令执行跟它交互。
[你的项目目录] | v [Codex 客户端工具] <---> [模型服务层] | | v v [命令执行/文件读写] [本地推理 或 远端接口] | v [容器运行时 / 系统环境]理解这张图之后，你会发现所谓“部署”其实就是把中间这几层接通，让指令能从你的键盘一路走到模型再走回来。下面我按这个顺序，一层一层拆开讲。
2. 动手前的环境盘点与工具选型
2.1 硬件与系统的最低门槛
在下载任何东西之前，先确认你的机器能不能扛。这一步很多人跳过，结果装到一半发现跑不动，白折腾。
如果你打算让模型也跑在本地，那硬件就是硬指标。以常见的 7B 到 14B 参数量模型为例，量化之后大概需要 6GB 到 12GB 显存，加上系统占用，一张 12GB 显存的卡是比较舒服的起点。内存方面建议 16GB 起步，32GB 更稳。硬盘留出至少 50GB 给模型文件和容器镜像，SSD 是必须的，机械盘加载模型会让你怀疑人生。
如果你只是把 Codex 客户端装在本地，模型走远端接口，那门槛就低很多。一台普通的开发机，8GB 内存、能跑 Docker 就行。这种情况下本地部署的意义主要在于工具链的稳定和配置的自主，而不是算力。
操作系统方面，macOS、Linux、Windows 三条路我都试过。macOS 上 Docker Desktop 体验最顺，Linux 上原生 Docker 最省资源，Windows 稍微麻烦一点，需要确认虚拟化支持是否打开。这里有个高频报错要提前说：Windows 上启动 Docker Desktop 时如果提示虚拟化未检测到，八成是 BIOS 里的虚拟化开关没开，或者跟 Hyper-V、WSL2 的配置有冲突。这个后面排查章节会专门讲。
2.2 容器运行时：为什么绕不开 Docker
很多人会问，我就装个命令行工具，为什么非得用 Docker？直接下载二进制不行吗？
能行，但 Docker 有它的好处。第一是环境隔离，Codex 依赖的运行时、系统库版本可能跟你本机已有的东西打架，容器把这层隔离掉了。第二是可复现，你今天在这台机器上跑通的配置，换台机器把镜像和配置一拉就能复现，不用重新踩一遍依赖的坑。第三是清理方便，不想要了直接把容器和镜像删掉，不留残留。
Docker 的安装本身不复杂，但有几个点值得注意。安装包去官网下对应平台的版本，Windows 和 macOS 是图形化安装，Linux 走包管理器。装完之后第一件事是验证：
docker --version docker run hello-world第二条命令能正常输出一段欢迎信息，说明容器运行时是通的。如果卡在拉取镜像那一步，多半是网络或者镜像源的问题，这个属于常见情况，换个镜像源或者稍后再试通常能解决。
提示：Docker Desktop 在 Windows 和 macOS 上是带图形界面的，Linux 上通常是纯命令行。如果你在 Linux 上想要图形界面，那是另一套东西，本文不展开。
2.3 模型服务层的两条路线
这是整个方案里最需要你提前做决策的地方，因为它直接决定了后面的配置走向。
路线一：本地推理。你在本机跑一个推理服务，Codex 通过本地地址访问它。常见的做法是用 Ollama 这类工具把模型拉下来跑起来，它会暴露一个兼容接口。这条路的好处是数据不出机器、延迟低、不依赖外部服务。代价是吃硬件，而且模型效果受限于你能跑动的参数量。
路线二：远端接口。你有一个可用的模型服务地址和密钥，Codex 通过它来调用模型。这条路对硬件没要求，模型效果通常更好，但依赖网络，且数据会离开本机。
我的建议是，如果你机器够用，先走路线一把流程跑通，理解每一层在干什么；如果硬件一般，直接走路线二，把 Codex 客户端配好就行。两条路在 Codex 这一层的配置差异其实不大，主要就是接口地址和密钥的不同。
2.4 版本与依赖的对应关系
这里有个容易被忽略的坑：Codex 客户端、容器运行时、模型服务这三者的版本之间是有兼容性要求的。我遇到过好几次“明明按教程做了却报错”，最后发现是某一层版本太新或太旧。
一个稳妥的做法是，先把每一层的版本号记下来，出问题的时候方便对照。比如容器运行时用docker --version看，模型服务用它的版本命令看，Codex 客户端用--version看。把它们记在一个小本子上，或者写进项目的 README 里。
另外，配置文件里的模型名称一定要跟模型服务实际提供的名称对得上。我见过一个典型报错，大意是“某个模型名不被支持”，原因就是配置文件里写的名字跟服务端注册的名字不一致。这种问题排查起来很快，但不知道方向的话能卡很久。
3. Codex 客户端的下载与安装实操
3.1 获取安装包的几个正规渠道
下载这一步，核心原则是走正规渠道，别去来路不明的第三方站点抓安装包。原因很简单，这类工具会读写你的项目文件、执行命令，来源不明的包风险太高。
常见的获取方式有这么几种。一是官方发布页，通常会提供各平台的安装包或者安装脚本。二是包管理器，比如 macOS 上的 Homebrew、Linux 上的发行版仓库，这种方式的好处是升级方便。三是源码构建，适合想深度定制的人，但对普通用户来说没必要。
我个人的习惯是优先用包管理器，因为它把安装和后续升级都管了。如果包管理器里没有，再去官方发布页下。下载的时候留意一下校验信息，很多发布页会提供哈希值，对一下能确认文件没被篡改。
安装完成后，第一件事是验证命令能不能跑起来：
codex --version codex --help第一条看版本，第二条看它支持哪些子命令。如果第一条就报“command not found”，说明可执行文件没进 PATH，需要手动加一下或者重新走一遍安装流程。
3.2 首次启动的配置向导
第一次运行 Codex 的时候，它一般会引导你做一轮初始配置。这一步别急着跳过，认真填，因为后面改起来虽然不难，但不如一次到位省事。
配置向导通常会问这么几件事：用哪种认证方式、模型服务地址是什么、默认用哪个模型、工作目录在哪。认证方式取决于你走哪条路线，本地推理一般不需要密钥，远端接口需要填密钥。模型服务地址就是前面说的那一层，本地推理填本机地址加端口，远端填服务商给的地址。
工作目录这一项值得多说一句。它决定了 Codex 默认在哪个范围内读写文件。我的建议是把它设成你当前项目的根目录，而不是整个用户目录。范围收窄之后，一是更安全，二是它组织上下文的时候不会把无关文件也扫进去，响应更快也更准。
配置完成后，配置文件一般会落在用户目录下的某个隐藏目录里，具体路径因平台而异。找到它，打开看一眼，理解每一项的含义，后面调优全靠它。
3.3 配置文件逐项拆解
配置文件是这套东西的大脑，我把常见的几类配置项拆开讲。
模型相关。包括模型名称、接口地址、密钥、超时时间、最大 token 数。模型名称必须跟服务端一致，这个前面强调过了。超时时间本地推理可以设短一点，远端接口设长一点，因为网络往返本身就有开销。最大 token 数决定了单次交互能处理多长的上下文，设太小会导致长文件被截断，设太大又可能超出模型能力。
行为相关。包括是否自动执行命令、是否允许写文件、交互确认的粒度。这几项直接关系到安全。我的建议是初次使用时把自动执行关掉，每一步都手动确认，等你摸清它的行为模式之后再逐步放开。尤其是写文件和执行命令这两项，放开之前一定要想清楚后果。
日志相关。包括日志级别、日志路径、是否记录完整请求。排查问题的时候把日志级别调高，平时调低省资源。日志里可能包含你的代码内容，所以日志文件的存放位置和清理策略也要考虑。
下面是一个配置文件的示意结构，字段名以你实际使用的版本为准：
model: name: "your-model-name" base_url: "http://127.0.0.1:11434/v1" api_key: "not-needed-for-local" timeout: 120 max_tokens: 8192 behavior: auto_execute: false allow_write: false confirm_level: "high" logging: level: "info" path: "./logs/codex.log"注意：上面这段只是结构示意，字段名和取值一定要以你所用版本的官方说明为准，照抄可能不生效。
3.4 安装后的连通性自检
装完配完，别急着上真实项目，先做一轮连通性自检。这一步能帮你把问题挡在真正干活之前。
自检分三层。第一层，Codex 客户端本身能不能跑，前面--version已经验证过了。第二层，模型服务能不能通，用一个最简单的请求测一下：
curl http://127.0.0.1:11434/v1/models如果返回一个模型列表，说明服务是活的。第三层，Codex 能不能成功调用模型，发一句最简单的指令，比如让它解释一段三行的代码，看它能不能正常返回。
这三层任何一层不通，问题范围就缩小到那一层，排查起来有的放矢。我见过很多人跳过自检直接上项目，结果报错之后分不清是客户端的问题、服务的问题还是配置的问题，白白浪费时间。
4. 本地模型服务的搭建与对接
4.1 用容器方式跑起推理服务
如果你走本地推理这条路线，用容器跑是最省心的方式之一。以常见的推理工具为例，拉镜像、起容器、拉模型，三步走。
docker pull your-inference-image docker run -d --name inference \ -p 11434:11434 \ -v /path/to/models:/models \ your-inference-image这里几个参数解释一下。-d是后台运行，-p把容器端口映射到本机，-v把模型目录挂载进去，这样模型文件存在宿主机上，容器删了模型还在，不用重新下。端口号按你实际用的工具来，我这里用 11434 只是举例。
容器起来之后，进去拉模型：
docker exec -it inference your-pull-command model-name模型文件通常有几个 GB，下载时间取决于网速。下完之后验证一下服务是否正常响应，用前面那个curl命令测。
提示：挂载模型目录这一步别省。我一开始没挂载，容器一删模型全没了，重新下了一遍，血的教训。
4.2 模型选择与显存占用的估算
选哪个模型，取决于你的硬件和需求。这里给一个粗略的估算方法，帮你判断能不能跑得动。
模型显存占用大致等于参数量乘以每个参数的字节数。以 FP16 精度为例，每个参数占 2 字节，一个 7B 模型就是 14GB 左右，这还没算推理过程中的中间激活值。所以 7B 模型 FP16 大概需要 16GB 以上显存才舒服。如果显存不够，就得用量化，比如 4-bit 量化把每个参数压到 0.5 字节左右，7B 模型就降到 4GB 上下，一张 8GB 的卡就能跑。
FP16: 参数量 x 2 字节 INT8: 参数量 x 1 字节 INT4: 参数量 x 0.5 字节量化会损失一点效果，但换来的是能跑起来。我的经验是，如果硬件卡在临界点，宁可上量化也别硬上大模型，跑不动的模型等于没有。
代码场景对模型的要求跟闲聊不一样，它更看重对编程语言的理解和长上下文的处理能力。选模型的时候优先看它在代码任务上的表现，而不是通用对话能力。
4.3 把 Codex 接到本地服务上
服务跑起来之后，回到 Codex 的配置文件，把模型服务地址指向本地。
model: name: "your-local-model" base_url: "http://127.0.0.1:11434/v1" api_key: "local"这里base_url的路径要跟服务实际暴露的接口路径对上，很多工具是/v1结尾，也有的是别的。api_key本地服务通常不校验，随便填一个占位就行，但字段不能缺，缺了有些客户端会报错。
配好之后重启 Codex，发一条测试指令。如果它能正常返回，说明整条链路通了。如果报连接错误，先确认服务是不是还在跑，再确认端口和路径对不对。
4.4 远端接口的对接差异
如果你走远端接口，配置上的差异主要在两处：base_url换成服务商给的地址，api_key填真实的密钥。
model: name: "your-remote-model" base_url: "https://your-provider-endpoint/v1" api_key: "your-real-key" timeout: 300超时时间这里建议设长一点，因为远端接口的响应时间受网络影响大。另外远端接口通常有速率限制，如果你发现请求偶尔失败，可能是触发了限流，需要控制一下请求频率。
密钥的管理要上心。别把密钥硬编码在会提交到版本库的文件里，用环境变量或者单独的密钥文件，并且把密钥文件加进忽略列表。这个习惯能帮你避免很多麻烦。
5. 跑通第一个真实任务
5.1 从只读任务开始建立信任
链路通了之后，别一上来就让它改代码。先用只读任务观察它的行为，建立你对它的信任。
一个合适的起点是让它解释一段代码。挑一个你项目里逻辑稍微绕一点的函数，让它逐行说明在干什么。这个任务不涉及写操作，风险为零，同时你能看出它对代码的理解程度。
请阅读 src/utils/parser.js，逐行解释这个文件的逻辑， 重点说明第 30 到 50 行的状态机是怎么流转的。观察它的回答，如果解释得靠谱，说明模型能力够用，可以进入下一步。如果答得离谱，可能是模型选得不对，或者上下文没喂够，需要调整。
5.2 让工具参与一次小范围修改
只读任务没问题之后，可以试一次小范围修改。挑一个独立的、影响面小的函数，让它改。
把 src/utils/format.js 里的 formatDate 函数改成支持传入时区参数， 默认行为保持不变。改完告诉我改了哪几行。这里的关键是“影响面小”和“默认行为不变”。前者保证改坏了容易回滚，后者保证不会牵连其他调用方。改完之后一定要自己 review 一遍 diff，别直接信它。
我一般会配合版本控制来做这件事。改之前确保工作区是干净的，改完之后用git diff看改动，不满意直接git checkout回滚。这样试错成本极低。
5.3 命令执行的安全边界
Codex 这类工具通常能执行 shell 命令，这是它强大的地方，也是风险最大的地方。我的原则是，命令执行必须手动确认，绝不放开自动执行。
原因很直接，模型可能会生成一些你意想不到的命令，比如删除文件、修改系统配置、发起网络请求。这些操作一旦自动执行，后果可能不可逆。手动确认给了你一个拦截的机会。
配置里那个auto_execute开关，我建议长期保持关闭。哪怕你觉得麻烦，这个麻烦是值得的。真到了需要批量执行的时候，你可以把命令先让它生成出来，自己检查一遍再手动跑，效果一样，风险可控。
注意：任何涉及删除、覆盖、权限变更的命令，执行前都要多看一眼。模型不知道你的文件有多重要，你知道。
5.4 上下文管理的实用技巧
用久了你会发现，上下文管理是决定体验好坏的关键。喂太多无关内容，响应慢且容易跑偏；喂太少，它又理解不了你的意图。
我的做法是，每次任务开始前，明确告诉它要看哪些文件。不要让它自己去猜，也不要一次性把整个项目丢给它。比如你要改一个模块，就指定这个模块的文件加上它的直接依赖，范围清晰。
本次任务只涉及 src/service/ 目录下的文件， 以及 src/types/index.ts 里的类型定义，其他文件不用看。另外，长对话要及时清理。一个会话里聊了太多不相关的事，上下文会变得很乱，它的表现也会下降。做完一个任务就开新会话，保持每个会话的聚焦。
6. 常见故障与排查实录
6.1 容器启动失败的几类原因
容器起不来是最常见的拦路虎，我把遇到过的几类整理成表，方便对照。
| 现象 | 可能原因 | 排查方向 |
|---|---|---|
| 提示虚拟化未检测到 | BIOS 虚拟化开关未开，或与系统虚拟化组件冲突 | 进 BIOS 开启虚拟化，检查系统虚拟化功能状态 |
| 容器启动后立即退出 | 启动命令有误，或端口被占用 | 看容器日志，换端口重试 |
| 拉取镜像卡住 | 网络问题或镜像源不可达 | 换镜像源，或稍后重试 |
| 端口映射不生效 | 端口写错，或防火墙拦截 | 确认映射配置，检查本机防火墙 |
排查容器问题的第一招永远是看日志：
docker logs container-name日志里通常有明确的错误信息，比瞎猜快得多。
6.2 模型服务连不上的排查路径
Codex 报连接错误时，按这个顺序排查。
第一步，确认服务进程还在。docker ps看容器状态，如果是退出状态，看日志找原因。第二步，确认端口通不通。在本机用curl直接打服务地址，能返回说明服务是活的。第三步，确认 Codex 配置里的地址和端口跟服务实际监听的一致。第四步，如果服务在容器里，确认端口映射配置正确。
这四步走下来，绝大多数连接问题都能定位。我遇到过一次，服务明明在跑，Codex 就是连不上，最后发现是配置文件里端口写错了一位，这种低级错误反而最容易忽略。
6.3 模型名称不匹配的典型报错
有一类报错很典型，大意是“某个模型名不被支持”。这个几乎百分百是配置里的模型名跟服务端注册的名字对不上。
解决办法很简单，先查服务端有哪些模型：
curl http://127.0.0.1:11434/v1/models返回的列表里挑一个，把名字原样复制到配置文件里。注意大小写和连字符，这些细节很容易出错。
6.4 响应慢或超时的调优思路
响应慢分两种情况，一种是首次请求慢，一种是持续慢。
首次请求慢通常是模型加载导致的，模型第一次被调用时要加载进显存，这个过程可能几十秒。加载完之后后续请求就快了。这种情况不用管，等第一次过去就好。
持续慢就要找原因了。可能是模型太大硬件扛不住，可能是上下文喂太多导致处理时间长，也可能是远端接口网络延迟高。对应地，换小模型、精简上下文、或者换更近的服务节点。
超时的话，先把配置里的超时时间调大试试，如果调大之后能返回，说明只是慢不是断。如果调大也没用，那就是真的连不上，回到连接排查那一步。
6.5 一份速查表收尾
把上面这些整理成一张速查表，出问题的时候直接对照。
| 报错关键词 | 大概率原因 | 快速处理 |
|---|---|---|
| 虚拟化未检测到 | BIOS 虚拟化未开 | 进 BIOS 开启 |
| 模型名不被支持 | 配置名与服务端不一致 | 查服务端模型列表，改配置 |
| 连接被拒绝 | 服务未启动或端口错 | 查进程状态，核对端口 |
| 请求超时 | 超时设置过短或网络慢 | 调大超时，检查网络 |
| 上下文被截断 | 最大 token 设置过小 | 调大 max_tokens |
这张表我贴在显示器边上，出问题先扫一眼，能省不少时间。
7. 长期使用中的经验沉淀
7.1 配置的版本化管理
用了一段时间之后，你会发现配置文件改来改去，改乱了想回退都难。我的做法是把配置文件也纳入版本管理，用一个单独的私有仓库或者本地 git 仓库管起来。
每次改动之前先提交一次，改坏了直接回退。配置文件里如果有密钥，用占位符代替，真实密钥放在环境变量或者单独的、不进版本库的文件里。这样既保留了变更历史，又不会泄露敏感信息。
7.2 把常用任务固化成模板
天天重复的指令，没必要每次重新组织语言。我把常用的几类任务写成了模板，用的时候改几个参数就行。
比如“解释文件”“重构函数”“补测试”“查 bug”这几类，各写一个模板，把文件路径和具体要求留成占位。这样既省时间，又能保证每次喂给模型的上下文结构一致，输出质量更稳定。
7.3 定期清理与资源回收
容器和模型文件很占空间，用久了磁盘会告急。定期清理是必要的。
docker system prune -a这条命令会清理掉没用的镜像、容器、网络，释放空间。执行前确认一下没有正在用的东西，别把还在跑的容器删了。模型文件如果不用了，也及时删掉，一个模型动辄几个 GB。
7.4 关于这套方案后续的扩展方向
这套东西跑通之后，能扩展的方向其实不少。比如把 Codex 接到你的编辑器里，做成一个插件式的体验，省去切窗口的麻烦。比如给它配一套自定义的提示词模板库，针对你常用的技术栈做优化。再比如把多个模型服务配在一起，按任务类型切换，简单任务用快的小模型，复杂任务用强的大模型。
我自己目前是把本地推理和远端接口都配着，日常小改动走本地，遇到硬骨头切远端。两套配置在文件里并存，切换就是改一行的事。这种灵活性是本地部署带来的最大好处之一，你不再被单一服务绑定，而是根据自己的需求随时调整。
最后分享一个我踩过的坑：别在配置还没稳定的时候就急着上真实项目。我一开始图快，配置随便填了填就开干，结果改到一半工具报错，代码处于半改不改的状态，回滚都费劲。后来我养成了习惯，每次调整配置之后，先用一个测试项目跑一遍完整流程，确认没问题再上真实项目。这个习惯帮我省了很多次麻烦。
