本文由 辛梓煜@词元二号站（www.ciyuanerhao.com）撰写，内容基于我个人的折腾实践整理，转载请注明出处。

快速摘要（只想要结论的，先看这段）： 现在不用一分钱、不用任何境外接口密钥、不用流量计费，甚至断网都行，你就能在自己的电脑上跑起一个"会干活"的 AI 编程代理。 核心思路只有一句话：用本地推理引擎（Ollama 或 llama.cpp）把一个开源大模型跑在你自己的显卡上，再把命令行编程代理 Codex CLI 指向这个本地模型。这样它就能读你的项目、改你的代码、建文件、修 Bug，全程在本地完成，代码一个字节都不往外传。门槛比想象中低：8G 显存能跑得动小模型做日常任务，16G～24G 显存就能上 Qwen3.6 / Gemma 4 / gpt-oss 这类当下最能打的开源模型。最容易踩的一个坑是上下文长度没设好——设太小代理会"失忆"卡死，设太大又会爆显存让速度掉到几乎不可用，这篇我会把怎么算、怎么调讲透。想看完整拆解（含每一步命令、选型表、调优公式和我自己踩过的坑），往下翻。

一、先把话说清楚：本地编程代理到底是个什么东西

很多人第一次听到"本地 AI 编程"会有点懵，所以我先用大白话把几个概念摆平。

我们平时用的那种云端 AI，本质是你把问题发到别人服务器上的大模型，它算完再把结果传回来。好处是模型大、效果好；坏处也很直白：要联网、要计费、有速率限制，而且你的代码得交到对方手里。

本地编程代理，就是把这套流程整个搬回你自己的机器上。 大模型的"大脑"装在你的显卡里，调度它干活的"手脚"是一个跑在终端里的代理程序。你让它"把这个游戏的报错修好"，它会自己去翻文件、定位问题、改代码、再跑一遍验证——这一连串动作里没有一步需要联网，也没有一步在花钱。

我自己折腾下来，最直观的感受是它已经不是那种你问一句它答一句的聊天机器人了，而是一个能接管一整段工作流的助理。下面这张图，是我理解的整套系统是怎么咬合在一起的：

flowchart LR
    A[你<br/>下达任务] --> B[编程代理<br/>Codex CLI]
    B -->|调用本地接口| C[推理引擎<br/>Ollama / llama.cpp]
    C -->|占用显存运算| D[开源大模型<br/>Qwen3.6 / Gemma 4 / gpt-oss]
    D -->|返回结果| C
    C --> B
    B -->|读写文件 / 跑命令| E[你的项目目录]
    B -->|自动操作| F[浏览器 / 桌面]

记住这三个角色：代理（指挥）、引擎（搬运）、模型（大脑）。后面所有的部署和调优，都是围绕这三层在拧螺丝。把它们的关系想明白，后面就不会乱。

之所以一开始就花力气把这三层掰开，是因为我见过太多人把它们搅在一起，结果出了问题不知道该查哪儿。举个例子：速度慢，到底是模型选大了、引擎没调好、还是代理给的任务太碎？接不通，是引擎服务没起、还是代理地址填错？只要你心里有这张"三层结构图"，遇到任何毛病都能先定位到是哪一层的事，再有的放矢地解决，而不是抓瞎乱试。这套"分层排查"的思路，比记住任何一条具体命令都更管用，也是我希望你读完这篇能带走的第一件东西。

二、我为什么开始折腾这件事

说点真实的动机。我并不是一上来就冲着"本地"去的。最早我也用云端的编程助手，体验确实顺滑。但有几件事慢慢把我推到了本地这条路上。

第一是数据。我手上有些项目代码是不太方便往外传的，云端再方便，"代码离开我这台机器"这个事实本身就让我别扭。第二是调用量。编程代理这种东西特别耗 token——它读一次文件、跑一次测试、来回纠错好几轮，消耗量是普通聊天的几十倍。一个长会话下来计费很可观，而且偶尔会撞上速率限制，正干到一半被打断，上下文一乱就得重来。第三是纯粹想搞明白原理。我这人有个毛病，越是被包装得"开箱即用"的东西，越想拆开看看里面到底怎么转的。

折腾完之后我的结论是：本地方案不是要取代云端，而是给你多一个选择。日常那七八成的活儿——补全、重构、写测试、查文档、修常见 Bug——本地模型完全扛得住，零成本、不限量、还断网可用。真正硬核的、需要顶级模型啃的难题，再切回云端不迟。这种"能本地就本地，搞不定再上云"的混合用法，是我现在最舒服的状态。

还有个心理层面的变化值得一提。用云端的时候，我潜意识里总在"省着用"——这次调用值不值、会不会又烧 token，多少有点束手束脚。换到本地之后这种顾虑直接消失了：反正不花钱、不限量，我可以放开了让它反复试、反复改，哪怕一个小功能让它推翻重来五遍也无所谓。这种"敢浪费"的心态，反而让我更愿意去试探它的能力边界，干活的节奏也更松弛。工具的成本结构变了，使用它的方式跟着就变了，这是我没料到的一个收获。

三、三个关键角色，逐个讲明白

3.1 编程代理：Codex CLI 与它的桌面端

我这次用的指挥层是 Codex。它有两种形态：一个是装在终端里的命令行版本 Codex CLI，一个是带界面的桌面应用。命令行版安装极简，如果你机器上有 Node.js 环境，一行就装好：

npm install -g @openai/codex

装完之后，进到任意一个项目目录，敲一个 codex 就能把它唤起来。它的设计目标是"在哪儿写代码就在哪儿用"，所以你不需要再开一个笨重的集成开发环境，终端里就能跟它对话、让它动手。

这里有个对新手特别友好的点值得划重点：Codex 并不绑死在某一家的云端模型上。它支持把模型来源切到"开源本地"这一档——命令行里就是那个 --oss 参数。换句话说，它天生就是设计成能同时管云端和本地模型的，这正是我们这篇能玩起来的前提。

为什么要专门挑一个"代理"而不是直接跟模型对话？因为代理干的是"调度"这件脏活累活。你给一句模糊的目标，它会自己拆解成一连串具体动作：读哪个文件、改哪一行、跑哪条命令验证、结果不对再回头修。模型只负责"想"，代理负责把"想"变成对你项目实打实的操作。这一层调度能力，正是"会干活的助理"和"会聊天的机器人"之间的分水岭，也是本地大模型能从玩具变成生产力工具的关键。

3.2 推理引擎：Ollama 是搬运工，llama.cpp 是底层发动机

光有模型文件没用，得有个程序把它装进显存、接收请求、吐出结果，这个程序就是推理引擎。

Ollama 是上手最快的那个。它把"下载模型、加载模型、起一个本地服务"这几件事打包成了几条命令，几乎不用配置。对绝大多数人来说，想今天就把东西跑起来，选它准没错。它起服务后默认监听本机的一个端口（http://localhost:11434），对外提供的是一套与主流接口兼容的调用方式，所以 Codex 才能无缝接上去。

llama.cpp 则更偏底层，是很多上层工具（包括一部分 Ollama 的能力）背后真正干活的发动机。它给你的控制粒度更细、调优空间更大、在同样硬件上往往能压出更高的速度。代价是配置更繁琐一点。我的建议是：先用 Ollama 把整条链路跑通、确认能用，等你对自己想要什么有数了，再考虑切到 llama.cpp 去抠性能。 这篇我两个都会讲。

两者的取舍，用一张小表更直观：

我自己的路径就是先 Ollama 跑顺了，确认这套思路对我有用，过了一阵才把推理层换成 llama.cpp 去压速度。强烈不建议新手一上来就硬刚底层，很容易在配置上把热情耗光。

3.3 开源大模型：当下该选哪一个

这是大家最关心、也最容易选花眼的一层。模型迭代太快，我把现在（2026 年这个时间点）适合本地编程的几款主力梳理成一张表，按"消费级显卡能不能带得动"来排：

几句白话帮你快速定位：显存只有 8G 左右，老老实实从 Gemma 4 12B 这类小模型起步，别贪大，模型一旦塞不进显存反而会慢到怀疑人生。有 16G，gpt-oss-20b 是个舒服的全能位。有 24G（比如一张 3090），Qwen3.6-27B 是我个人比较推荐的智能体编程选择。显存特别紧张，就用 Qwen3.6-35B-A3B 这种"混合专家"结构的——它总参数虽大，但每次推理只激活一小部分参数，能用比预期更省的资源跑出不错的质量。

这里插一个新手常踩的认知误区：模型不是越大越好，而是"能完整塞进你显存的、尽量大的那个"最好。 一个 27B 的模型如果你显存只够塞一半，剩下一半被挤到内存里让 CPU 处理，速度会从每秒几十个字直接掉到每秒两三个字——这是后面调优章节会反复出现的核心矛盾，先记住。

3.4 顺带说清"量化"：本地跑大模型的省显存魔法

聊本地部署，"量化"这个词你早晚会撞上，第一次见容易被唬住，其实道理很朴素。

一个模型的"知识"是存在一堆数字（权重）里的。原始模型里每个数字往往用 16 位甚至更高精度来存，精确是精确，就是占地方。量化，就是把这些数字用更少的位数来近似表示——比如压成 8 位（Q8）、甚至 4 位（Q4）。位数少了，整个模型文件就小了，装进显存占的地方也跟着小。

打个比方：原始精度像是把每个数字都精确到小数点后好多位，量化则是适当四舍五入。听起来会损失精度，但实践证明，对大多数任务来说，Q4、Q5 这种量化版的质量损失非常有限，省下来的显存却很可观——同一个模型，四位量化后的体积大约能压到原来的四分之一上下。所以你在 Ollama 上拉模型，默认拉到的基本就是量化好的版本，名字里常带 Q4_K_M 之类的标记，这就是在告诉你它的量化档位。

给新手一条实用经验：显存紧张时，优先靠"选更激进的量化档"来把模型塞进显存，而不是直接换成参数量小一大截的模型。 因为一个大模型的 Q4 版，质量往往仍然胜过一个小模型的高精度版。当然量化也不是越狠越好，压到极低位数（比如两位、三位）时质量会明显掉，所以 Q4 到 Q6 通常是本地编程比较甜的区间。把这个概念吃透，你在那张选型表和显存账之间就能自如换算了。再给一句压箱底的经验：遇到一个新模型先别急着拉最高精度版，从 Q4 起步跑跑看，绝大多数日常编程任务你根本感觉不出它和高精度版的差别，却能多省出一大块显存留给上下文。 显存这东西在本地永远是稀缺资源，能省一点是一点，省下来的每一个 GB，都能换成更长的上下文或者更大一号的模型，实打实地提升你的使用体验。把这套省显存的思路用顺了，你就算只有一张普通显卡，也能把它的潜力压榨到极致。

四、硬件门槛：6G、8G 到底能不能玩

我知道很多人卡在这一关：是不是得有张很贵的显卡才行？答案是——不一定，但显存大小确实决定了你的体验上限。 这一节我尽量把话说实在，不夸大也不劝退，让你对自己的机器能玩到什么程度心里有底。

判断能不能跑、跑得爽不爽，主要看一个数：显存（VRAM）够不够装下"模型本体 + 上下文缓存"。 模型本体的大小，跟它的参数量和量化精度有关——同一个模型，用 Q4 这种四位量化压一下，体积能砍到接近原来的四分之一，质量损失却很有限，所以本地跑基本都会用量化版。

我整理了一个粗略的对照，给你一个心理预期：

所以 6G、8G 显存"能不能跑"？能。 只是你得把预期放在"小模型做日常辅助"这个定位上，别指望它一口气重构一个大型项目。我自己的体会是，哪怕只是 8G 显存配个小模型，光是"断网也能随时帮我改代码"这一点，日常省下来的功夫就已经很值了。

4.1 手把手算一笔显存账

光看档位表还是有点虚，我带你算一遍，以后你拿到任意一个模型都能自己估。显存的占用主要是两块相加：模型本体 + 上下文缓存（KV 缓存）。

模型本体怎么估？一个粗暴但够用的算法：参数量（按 B 为单位）× 量化系数 ≈ 占用显存（GB）。 四位量化（Q4）的系数大约是 0.5～0.6，八位（Q8）大约是 1。举例：

• 一个 12B 模型，Q4 量化，本体大约 12 × 0.55 ≈ 6.6 GB；
• 一个 27B 模型，Q4 量化，本体大约 27 × 0.55 ≈ 15 GB。

再加上上下文缓存。缓存的大小跟你设的上下文窗口成正比——窗口越大、缓存越大。一个 27B 模型如果上下文开到 64K，缓存大概要再吃掉几个 GB。所以这台机器想稳跑 27B + 64K 上下文，显存预算大致就是"15 GB 本体 + 几 GB 缓存"，落在 20 GB 出头，一张 24G 的卡刚好罩得住。

这笔账的意义在于：当你发现速度突然崩盘，先别怀疑模型不行，多半是"本体 + 缓存"超了显存。 这时候要么换更激进的量化档把本体压下去，要么把上下文窗口调小一点把缓存压下去，两条路都能救。学会算这笔账，你就从"碰运气"进阶到"心里有数"了。

五、动手部署（一）：把代理和引擎装好

理论讲够了，开始上手。整个部署我拆成五步走，这一节先把"指挥"和"搬运工"装到位。

5.1 安装 Codex

如前面提到的，有 Node.js 环境的话直接：

npm install -g @openai/codex

装完在终端敲 codex --version 验证一下，能打印出版本号就成。如果你更喜欢图形界面，官方也提供桌面应用，去官方网站下载对应你系统的安装包即可——这里要注意：苹果电脑的安装包通常会区分芯片类型，别下错版本，否则装上了也跑不动。 Windows 用户就认准 Windows 版本下载，安装包通常几百兆，装完一般会自动打开。

补一个新手常卡住的点：如果敲 codex 提示找不到命令，多半是 Node.js 没装、或者全局安装的可执行文件没进系统的环境变量路径。先确认 node -v 能正常输出版本，再检查全局 npm 包的安装目录是否在 PATH 里。这类问题搜一下你系统对应的"npm 全局命令找不到"基本都能解决，不必慌。

5.2 安装 Ollama

去 Ollama 官方网站下载最新版客户端。一定要装最新版，老版本对新模型和某些参数的支持是不全的，这点我吃过亏——用旧版怎么调都不对，升级一下问题就没了。安装包视平台不同，大概一到两个 GB，下载好直接装，按提示点完成就行。

装好之后，开一个终端，敲：

ollama --version

能看到版本号，说明引擎就位了。这时候 Ollama 的本地服务通常已经在后台跑起来，监听着 localhost:11434。

六、动手部署（二）：下载并选对本地模型

引擎装好，接下来给它喂一个模型。用 Ollama 拉模型非常省事，一条命令的事。比如想要一个适合编程、显存又友好的，可以先从这类入手：

# 拉一个通用编程都不错的开源模型（按需替换模型名）
ollama pull gpt-oss:20b

# 显存只有 8G 左右，换更小的
ollama pull gemma:12b

# 有 24G 显存，想要更强的智能体编程能力
ollama pull qwen3.6:27b

拉完用 ollama list 看一眼，确认模型已经在本地列表里了。

这里给两条我自己总结的选型纪律，新手照做能少走弯路：

第一，别照抄任何人的模型选择，包括我。要根据你自己的显存来定。看着别人跑 27B 很爽就跟着拉，结果自己显存不够，模型一半在显卡一半在内存，慢到想砸键盘——这种情况太常见了。

第二，苹果芯片的用户要留意模型的适配标识。有些模型针对苹果统一内存架构有专门优化的版本，认准对应标识去拉，速度才能正常发挥。

如果你实在拿不准，Ollama 的客户端界面里通常会根据你的硬件给出推荐尺寸，照着它给的建议选，基本不会出大错。

再补几句下载时的实际经验。模型动辄十几二十个 GB，下载得有点耐心，建议挑网络稳定的时段一次拉完，中途断了有的会得重来。拉之前先用前面那笔显存账估一下你想要的模型本体大概多大，别等下了二十个 GB 才发现根本塞不进显存。另外，同一个模型往往有多个量化版本可选，名字后缀里的 Q4、Q5、Q8 就是档位标记——显存紧就选数字小的（更省、质量略降），显存宽裕就选数字大的（更占、质量更好）。我的习惯是先拉一个中庸的 Q4 版本跑跑看，体验不满意再按需上下调。模型拉到本地之后是可以反复用的，下一次启动不用再下，所以前期多花点时间选对，后面就一劳永逸了。

七、把本地模型接进 Codex：一条命令的事

模型有了、引擎跑着，现在把"指挥"接到"大脑"上。这是整篇最关键的一步，但其实出奇地简单。

7.1 最快的接法：--oss 一把梭

Codex 内置了对本地开源模型的支持，直接用 --oss 参数启动，它就会去找本地的 Ollama 服务：

# 用本地开源模型启动（默认会校验 Ollama 是否在运行）
codex --oss

# 指定用哪个本地模型
codex --oss -m qwen3.6:27b

启动后，Codex 会自动把你本地已经下载好的模型识别出来，让你挑一个用。比如你列表里有 Qwen3.6、有 Gemma 4，选你显存带得动的那个就行。到这一步，理论上你已经有一个能干活的本地编程代理了。

7.2 想固化配置：写进配置文件

每次都敲一长串参数太累。Codex 支持把这些写进配置文件，以后启动自动生效。大致是这样一段（路径和字段以官方文档为准，这里给你一个能看懂结构的示意）：

# 把默认模型来源设为本地开源
model_provider = "oss"
model = "qwen3.6:27b"

# 也可以显式定义一个本地提供方，指向 Ollama 的兼容接口
[model_providers.local]
base_url = "http://localhost:11434/v1"

# 给不同场景建"档案"，随时切换
[profiles.local]
model_provider = "local"
model = "qwen3.6:27b"

配好之后，本地和云端之间切换就是改一个 profile 的事，非常顺手。

7.3 验证它真的在本地跑

接好之后我建议你做个小验证，免得自我感觉良好实际上还在用云端。这个验证不是多此一举——配置一旦哪儿没改干净，代理很可能悄悄还在走云端，你却以为自己已经"本地化"了，白白浪费了折腾的意义。方法很朴素：直接断网。 把网络断开，再让它干一个活，比如"帮我写一个简单的网页小游戏"。如果断网状态下它照样能分析、能写、能跑出结果，那就说明算力确实来自你本机的显卡，而不是偷偷连了云端。

有个细节挺有意思：你问本地模型"你是什么模型"，它有时会一本正经地报出一个云端模型的名字——这是模型自己的"身份认知"问题，不代表它真在调用云端。断网能跑，才是它在本地的硬证据。 你也可以打开任务管理器看显卡占用，干活时 GPU 被吃满，就对了。

如果接不通，按这几步排查基本能定位：先确认 Ollama 服务在跑，浏览器访问 http://localhost:11434 看有没有响应；再确认模型名拼对了，用 ollama list 对一下你在 Codex 里填的名字是否完全一致，差一个字符都连不上；然后看端口，确认 Codex 里配的地址端口和 Ollama 实际监听的一致；最后看接口模式，有些工具对"接口协议版本"有要求，配错了会静默失败或返回乱码，这一项以官方文档当前说明为准去对。我自己接不通时，十有八九栽在前两条——要么服务没起来，要么模型名手滑写错了。

八、关键调优：上下文长度，设错就卡死

这一节是我最想强调的，因为它是新手翻车的重灾区，而且网上很多说法是反的。

8.1 先搞懂"上下文长度"是什么

上下文长度（业内常叫 num_ctx），通俗讲就是模型一次能"记住"多少内容——你的系统提示、对话历史、它读进去的代码文件，全都要塞进这个窗口里。窗口太小，超出的部分会被悄悄截掉，模型就开始"失忆"：你明明刚跟它说过的事，它转头就忘，编程代理这种需要反复读文件、多轮纠错的场景尤其受不了，常常表现为卡在某一步反复重试、绕圈子。

这里有个新手特别容易栽的暗坑：截断是"静默"发生的，没有任何报错提示。 模型不会跳出来告诉你"你给的内容太长，我只看了前一半"，它就默默把超出的部分丢掉，然后基于残缺的信息硬答。于是你会觉得"这模型怎么这么笨"，其实不是它笨，是它压根没看全。很多人把本地模型用得一肚子火，根子就在这——上下文窗口太小，喂进去的东西被偷偷砍掉了大半。所以这个参数虽然不起眼，却是决定本地代理"能不能用"的命门之一，值得你认真对待。

8.2 关键矛盾：太小会失忆，太大会爆显存

很多教程把因果讲反了，说"默认上下文太长导致很慢，要调小"。实际恰恰相反，需要分两种情况看：

• 设得太小（比如默认才几千 token）：代理读不全代码、记不住上下文，于是失败、重试、死循环。这是"卡住"的常见真因。
• 设得太大、超出显存能装下的范围：上下文缓存（KV 缓存）会从显存溢出到内存，由 CPU 接手处理，速度直接断崖式下跌——从每秒几十个字掉到每秒两三个字，二三十倍的落差。

所以正确的目标不是一味调大或调小，而是：在你显存装得下的前提下，尽量给够。 官方对编程、代理、联网检索这类任务的建议是至少 64000（64K）token。Codex 这类工具也明确推荐上下文窗口不低于 64K，否则代理体验会打折。

这里给一个帮助理解的粗略关系，上下文缓存占的显存大致随窗口线性增长：

[

\text{KV缓存显存} \approx 2 \times n_{\text{层数}} \times n_{\text{上下文}} \times d_{\text{隐藏维度}} \times \text{每数值字节数}

]

不用记公式，记住一句话就行：上下文翻倍，缓存占的显存大约也翻倍。 量化（比如把缓存也压成更低精度）能缓解一部分压力，但根本规律不变。

8.3 怎么改

命令行起 Ollama 服务时，可以用环境变量统一设上下文长度：

# 给所有模型把默认上下文设到 64K（按你的显存量力而行）
export OLLAMA_CONTEXT_LENGTH=65536

如果只想给某个模型固定一个上下文，可以用 Modelfile 派生一个新版本：

# 写一个 Modelfile，从现有模型派生，指定上下文窗口
cat > Modelfile <<'EOF'
FROM qwen3.6:27b
PARAMETER num_ctx 65536
EOF

# 基于它创建一个带大上下文的新模型（不会重新下载，只是叠一层配置）
ollama create qwen3.6:27b-64k -f Modelfile

我的实操建议是：先按显存档位估个安全值（24G 显存配 27B 模型，64K 通常是个比较稳的起点），起服务后边用边观察 GPU 占用。 看到推理时显卡被吃满、内存没怎么动，说明缓存还在显存里，状态健康；一旦发现速度突然变得奇慢、内存占用飙升，那多半是缓存溢出了，把上下文往下调一档即可。这套"看着仪表盘拧旋钮"的笨办法，比死记任何固定数值都靠谱。

给你一张速查，遇到症状直接对号入座：

把这张表存下来，本地调优八成的麻烦都能照着自己解决，不用每次都去翻论坛。

九、实测一：让它修一个跑不起来的小游戏

讲了这么多原理，看一个我自己跑过的场景，体会一下"代理"这个词的分量。

我手头有个写崩了的小游戏（一个简单的射击类网页游戏），点开始按钮没反应，控制台里一堆报错，反正是跑不起来。我把代码文件直接丢给本地代理，就一句话：把这个游戏代码修好。

它的动作链条大概是这样的：

1. 通读项目文件，定位入口和报错点
2. 找出问题（它报告说找到了两处 Bug）
3. 逐个修改对应代码
4. 给出修复说明，告诉我改了哪里、为什么

修完我打开试了试——开始按钮有反应了，发射、转向、射击都正常。整个过程几分钟，全程断网，一分钱没花。 这跟"我问它一段代码怎么写、它给我一段答案让我自己贴回去"是完全不同的体验：它是自己把活儿从头到尾干完的。

我想强调的是：这类"修一个跑不起来的小程序"的活儿，本地小模型就足够胜任。 你完全不用为日常这种