1. 从积分焦虑说起：这套方案的适用场景与选型逻辑
先说个让我印象挺深的事。有位朋友做一个小工具的原型验证，需求不复杂，就是用对话界面让 AI 帮忙写点胶水代码、调一调脚本。结果一周下来，后台账单跑出去不少零花钱。他跑来问我：有没有办法把 Codex 桌面端这种好用的交互体验保留下来，但不要再按次扣积分？
我当时就意识到，他需要的不是一个“白嫖技巧”，而是一套真正能落地的本地化配置方案。Codex 桌面端强在把对话、代码编辑、终端命令执行整合在一个界面里，操作路径短，反馈直接。但它默认走云端 API，每一次请求都会消耗额度。积分这东西，单看一次对话好像不心疼，真到批量重构、反复调试的时候，消耗速度比想象中快得多。
我最终给他搭了一套组合：Codex 桌面端负责交互，WorkBuddy CLI 在中间做模型路由和请求转发，后端接本地推理引擎。整套链路里，外部 API 额度是零消耗，所有对话请求都在本机完成。这套方案我自己的环境里跑了几个月，中间踩过不少坑，也总结出了一些相对稳定的配置细节。
这套方案适合谁？首先是经常用 Codex 桌面端做日常开发、但不想被 API 配额牵着走的人；其次是隐私敏感的场景，代码片段不出本机，心理上踏实很多；再就是对响应速度有要求的人，本地小模型虽然智力不如顶级云端模型，但胜在延迟低、不限量。
不过我也得泼一盆冷水。如果你需要的是最强的代码理解能力、最长的上下文记忆，本地模型短期内确实还比不过云端大参数模型。这套“零消耗方案”的正确用法，是把日常琐碎任务分流到本地，把真正困难的架构设计留在云端。想明白这一点，你才知道下面的配置该往哪个方向调。
2. 环境准备：Codex 桌面端与 WorkBuddy CLI 的安装细节
2.1 Codex 桌面端安装：注意安装包的运行时依赖
Codex 桌面端的安装本身没什么好说的，官网下载对应系统的安装包，一路下一步就行。但有几个细节值得注意。
第一个是运行时依赖。部分 Linux 发行版上，Codex 桌面端依赖的一些系统库不会自动装上，比如 WebKit 相关的图形库、音频服务组件。我一开始在某个精简版系统上装完直接打不开，报错信息又特别隐晦，最后是补了缺失的动态库才解决的。Windows 和 macOS 上基本没有这个问题。
第二个是版本。Codex 桌面端的自动更新策略在不同版本上有差异，有些版本会自动升级，有些版本则需要手动触发。自动升级本身不坏，但如果你同时改了配置文件，升级后某些设置项可能被重置。我后面会讲到，关键的代理配置最好单独放一个文件，这样即使主配置被重置，恢复起来也快。
2.2 WorkBuddy CLI 安装：把它当成一个独立网关服务
WorkBuddy CLI 是我在社区里发现的一个辅助工具，本质是一个命令行程序，作用是监听本地端口，接收上游客户端发来的 OpenAI 兼容格式请求，再按规则转发到不同的后端服务。它可以转给本地推理引擎，也可以转给特定的云端接口，相当于在客户端和后端之间加了一层“路由网关”。
安装方式很简单，通过包管理器直接装，装完命令行里敲workbuddy --version能正常输出版本号就算成功。但这里有个关键认知：WorkBuddy CLI 不是一次性执行完就退出的工具，它需要常驻后台，持续监听端口。所以安装完之后，你还要考虑怎么让它开机自启、崩溃后自动重启。我在 Linux 上是用 systemd 管理的，在 macOS 上用 launchd，Windows 上可以用计划任务或 NSSM。
你可以把 WorkBuddy CLI 理解成一个“看门大爷”——它不产生模型回答，但所有请求都要从它这里过。它稳不稳定，直接决定后续链路稳不稳定。
2.3 本地推理引擎：Ollama 是我目前用下来最省心的选择
后端必须有真正干活的人，也就是本地推理引擎。我用的是 Ollama，主要是因为它对 OpenAI 兼容接口的支持比较成熟，安装也简单，跨平台都行。
装完之后拉取模型。代码生成场景我最常用的是 Qwen2.5-Coder 系列和 DeepSeek-Coder-V2 系列，前者偏轻量、速度快，后者代码能力更强但吃显存。具体怎么选择，看你的机器配置：
| 模型 | 量化版本 | 显存需求 | 适合场景 |
|---|---|---|---|
| Qwen2.5-Coder 7B | Q4_K_M | 约 6GB | 日常脚本、代码解释、简单重构 |
| Qwen2.5-Coder 14B | Q4_K_M | 约 10GB | 中等复杂度任务、单元测试生成 |
| DeepSeek-Coder-V2 16B | Q4_K_M | 约 12GB | 跨文件重构、复杂逻辑实现 |
显存不够硬跑大模型，会出现显存溢出，最典型的表现是开始回答之后突然断开连接，或者在日志里看到 CUDA out of memory。我自己的显卡是 12GB 显存，长期稳定运行的配置是 14B 量化版，实测响应速度在 30 到 60 token 每秒之间，体感上和云端接口差别不大。
2.4 最容易翻车的 PATH 与版本检查方法
环境准备阶段最容易被忽略的，是 PATH 优先级问题。如果你电脑上同时存在多个 Python 环境、多个 Node 版本，或者之前装过其他版本的 Codex 桌面端，新装的工具可能被旧版本顶掉。
我的习惯是装完每个组件之后，先做一次“三连检查”：
codex --version workbuddy --version ollama --version三条命令的输出里，确认版本号符合预期。如果发现版本不对，优先检查当前 shell 的 PATH 顺序：
which codex which workbuddy which ollama看这几个命令指向的路径是否和你安装的位置一致。很多所谓的“装完不能用”，其实就是 PATH 指向了旧版本。
另外一个容易被忽略的点是环境变量。Codex 桌面端在读取配置时，有些设置项会优先读环境变量，环境变量没设置就读取配置文件。如果你之前配置过指向旧服务的环境变量，新配置可能根本不生效。我建议在测试之前，先检查一下当前环境里有没有残留的OPENAI_BASE_URL、CODEX_API_KEY这类变量，有的话先清掉。
3. 核心配置链路：Codex 如何把请求交给 WorkBuddy，再由 WorkBuddy 路由到本地模型
3.1 Codex 的自定义模型端点：把“云端地址”换成“本地地址”
Codex 桌面端支持自定义模型供应商，默认配置指向的是官方 API 地址。我们要做的事情很简单：把请求地址改成本地 WorkBuddy CLI 监听的地址。
以 Codex 桌面端为例，它的配置文件里有类似这样的结构：
[model_providers.workbuddy] name = "WorkBuddy Local Gateway" base_url = "http://127.0.0.1:8324/v1" env_key = "WORKBUDDY_API_KEY" wire_api = "chat"base_url就是最关键的一行，它决定了所有请求往哪里发。env_key指定一个环境变量名，WorkBuddy CLI 会用它来校验请求来源，你在本地随便设一个值就行，比如说local-test-key，能起到最基本的隔离作用。
然后在配置里指定模型名：
model = "workbuddy/qwen2.5-coder-14b"注意这个模型名的写法，前面带上了 provider 前缀，这样 Codex 桌面端就知道要找workbuddy这个供应商，而不是默认的官方供应商。
3.2 WorkBuddy 的路由规则：从模型名到实际后端的映射
WorkBuddy CLI 的配置文件里，核心是一张路由表。它负责回答一个问题：收到一个带模型名的请求，应该转发给谁？
我用的配置思路是这样：
gateway: port: 8324 api_key: local-test-key routes: - model_pattern: "qwen2.5-coder:14b" backend: type: openai_compatible base_url: "http://127.0.0.1:11434/v1" api_key: ollama-local - model_pattern: "deepseek-coder-v2:16b" backend: type: openai_compatible base_url: "http://127.0.0.1:11434/v1" api_key: ollama-local这个配置的意思是：把 Codex 桌面端发来的qwen2.5-coder:14b这个模型名，映射到本地 Ollama 的 OpenAI 兼容接口。
实际执行时，Codex 桌面端发送的模型名是我们在 3.1 里配置的workbuddy/qwen2.5-coder-14b，WorkBuddy 会把前缀剥掉，剩下qwen2.5-coder-14b，再去和路由表里的model_pattern做匹配。匹配的规则可以是精确匹配，也可以是通配符匹配。比如我想让所有qwen*开头的模型都走本地 Ollama，就写model_pattern: "qwen*"。
这里有个设计细节值得说。为什么不让 Codex 直接连 Ollama，非要中间加一个 WorkBuddy？因为 Ollama 只能承担“生成回答”这一件事，而 WorkBuddy 还能做缓存、限流、日志记录、多后端切换。比如某一天你觉得本地模型不够聪明，想临时切到云端模型，只需要改 WorkBuddy 的路由表，重启服务，Codex 桌面端一行配置都不用动。
3.3 验证链路是否走通的三个测试命令
配置写完之后，第一件事不是打开 Codex 桌面端，而是先用命令行验证整条链路是否通畅。
第一步，验证 WorkBuddy 网关本身在运行：
curl http://127.0.0.1:8324/v1/models如果 WorkBuddy 配置里的 API Key 设置了校验，这个请求需要带上 Header：
curl -H "Authorization: Bearer local-test-key" http://127.0.0.1:8324/v1/models正常情况下，返回结果里应该有一份模型列表，这个列表来自 WorkBuddy 路由表里配置的后端。换句话说，如果 Ollama 没启动，这里可能返回空列表或者直接报错。
第二步，验证模型生成接口：
curl http://127.0.0.1:8324/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer local-test-key" \ -d '{ "model": "qwen2.5-coder:14b", "messages": [{"role": "user", "content": "用一句话解释什么是哈希表"}] }'如果这个请求能正常返回带content的响应，说明模型生成链路是通的。
第三步，验证 Codex 桌面端能正确识别。这一步需要在 Codex 桌面端手动发起一条消息，观察 WorkBuddy 的日志。WorkBuddy CLI 启动时加上--log-level debug，然后在 Codex 里发消息，看日志里有没有请求进入。如果没有任何请求进来，说明 Codex 的配置还是指向了老地址，回去检查 3.1 里的base_url。
我在最开始配置的时候，就栽在第三步上。curl 测试一切正常，但 Codex 桌面端里怎么都连不上。后来才发现，Codex 桌面端的配置文件读的是用户目录下的一个.codex文件夹，而我当时改的是项目目录下的本地配置。两个配置文件互相覆盖，请求始终没有走 WorkBuddy。所以这里也提醒一下：配置修改后，确认你改的是 Codex 桌面端真正读取的那份文件。
4. 关键参数解析：Temperature、上下文窗口、并发连接数这些细节怎么调
4.1 上下文窗口与显存的关系：本地模型不像云端那样“无限续杯”
用过云端 API 的朋友都知道，上下文是可以传很长一段的，只要在模型支持范围内，服务端会帮你处理。本地推理则不一样，上下文窗口的长度会直接变成显存开销的一部分。
原理上，Transformer 模型的 KV Cache 会随着序列长度线性增长，序列越长，显存占用越高。Ollama 默认的上下文长度只有 2048 个 token，这个长度用于日常问答还行，用于代码生成就太局促了——你给 Codex 桌面端粘贴一段 500 行的代码文件，可能光输入就超过了 2048 token，模型还没开始写代码就先截断了。
我在配置里是这样设置的：
OLLAMA_CONTEXT_LENGTH=8192但要注意，8192 这个数字不是随便写的，它直接决定了显存占用。以 Qwen2.5-Coder 14B Q4 量化版为例，模型权重本身占大约 9GB，8192 上下文的 KV Cache 额外占用约 2GB，合起来接近 12GB。如果你的显卡只有 10GB 显存，这个配置十有八九会溢出。这时候要么降上下文到 4096，要么换 7B 模型，要么用更激进的量化等级。
个人建议是：先从 4096 开始，跑通之后再逐步往上加，观察显存占用曲线。不要一上来就贪大，否则你会反复遇到“生成到一半崩溃”的问题。
4.2 响应超时和重试参数：本地模型“思考”得比云端久
这是一个特别容易让人误会的点。Codex 桌面端的默认超时设置是按云端服务的响应速度来设计的，云端模型通常一两秒就开始吐字，最多十来秒也出结果了。但本地模型不同，尤其是在 CPU 推理、或者模型排队等待显存时，可能要等二三十秒才开始返回第一个 token。
如果 Codex 桌面端的超时时间设置得太短，你会看到的现象是：Codex 里明明显示请求已发送，但是过了一会儿提示失败，而 WorkBuddy 日志里显示请求其实还在处理中。
解决办法是调大超时时间。Codex 桌面端的模型供应商配置里，有一个时间相关的参数，我把它设置成了 300 秒。这个数字听着很大，实际上是为了覆盖“模型排队 + 首次响应 + 完整生成”的全过程。对于本地 14B 模型，生成一个 500 行的代码片段可能要几分钟，超时设置小了根本扛不住。
还有一个相关的参数是重试次数。重试机制本身是好的，但本地模型场景下需要小心。因为重试会重新发送整个请求，而生成任务如果已经执行了一半，重试很可能造成重复输出。我建议把自动重试次数设置为 0 或者 1，宁可在失败后手动重新发起，也不要让它在后台自动重试三次。
4.3 日志级别：排查问题时最好用的设置
WorkBuddy CLI 的日志级别设置，我强烈建议在生产使用中保持在 info 级别，排查问题时临时切到 debug。
debug 级别的日志会记录每一条请求的完整内容、路由匹配结果、后端响应耗时，这些信息对于定位问题非常有价值。但 debug 日志量巨大，如果长期开启，几天就能积攒几个 GB 的日志文件。
我在 WorkBuddy 的配置里单独设置了访问日志和错误日志分离，访问日志记录请求的基本信息和耗时，错误日志记录异常堆栈。这样日常运行时看错误日志就够了，不用淹没在大量 debug 信息里。
日志级别的另外一个隐藏好处是：它能把路由匹配过程暴露出来。有时候你以为某个请求会走本地模型，结果它跑到云端的免费接口上去了，这种“意外消耗”很难从用户界面察觉，但在日志里一目了然。我后来养成一个习惯，每周查一次 WorkBuddy 的访问日志，看一眼这周消耗了多少请求、都走了哪些后端。有一阵子发现某个自动化脚本在频繁触发请求，工作流走了本地后端，但请求量异常大，这才定位到问题是 Codex 桌面端的某个后台同步功能在反复调用模型。
5. 实测场景与踩坑记录：从配置成功到连续运行一周
5.1 场景一：重构一个 Python 模块，观察交互体验
配置好之后，我先拿一个真实项目做了测试。项目是一个 API 服务的核心模块，大概 800 行，逻辑集中在数据处理和接口调度上。我的目标是让 Codex 桌面端帮我拆成多个小文件，并补上单元测试。
在 Codex 桌面端里，我描述了重构思路和约束条件，然后让它生成代码。整个过程的交互体验很顺畅，消息发送之后大概 3 到 5 秒开始有响应，后续每秒钟能生成几十个 token，体感和云端服务几乎一样。
但有个细节值得注意：Codex 桌面端本身带有代码库索引功能，它会扫描项目目录、构建代码语义索引，这个功能在较大项目里非常消耗资源。我第一次运行时没意识到这个功能的存在，导致本地推理的同时还在跑索引，CPU 被打满，响应速度明显下降。
解决办法是在 Codex 桌面端的设置里，把项目索引的自动构建关掉，或者把索引触发方式改成手动。对于那些需要在启动时自动打开项目代码库的用法，这一点尤其重要。
5.2 场景二：生成 SQL 并调试，暴露了一个提示词习惯问题
另一个测试是让 Codex 桌面端帮我生成一份 SQL 查询，用来分析订单数据。本地模型在处理这种有明确输入输出规范的请求时表现尚可，但暴露了一个问题：提示词里的格式要求，本地模型的遵循程度远不如云端模型。
同样是要求“输出结果必须包含创建时间和更新时间”，云端模型能准确理解字段含义并保持格式，本地 14B 模型偶尔会自己发挥，比如漏掉字段或者加上无关的条件。
我后来调整了提示词策略，把复杂任务拆成小步骤，每个步骤给出明确的输入输出示例。比如：
- 先生成表结构说明，让模型理解有哪些字段。
- 再让它写查询，限定只使用第一步里出现的字段。
- 最后检查生成的 SQL 是否可以执行。
本地模型擅长执行“清晰的子任务”，不擅长在模糊需求里自己猜。这和人的协作方式其实很像——交代得越清楚，交付质量越高。如果你的工作流里经常有模糊的、探索性的需求，建议把这类任务留给更聪明的 AI 服务，把琐碎的、跑通的任务交给本地模型。
5.3 踩坑一：Codex 桌面端偶发断连，根因竟然是端口冲突
运行到第三天，Codex 桌面端开始出现偶发性断连。表现是消息发出去之后一直没有响应，过一会儿提示连接失败。手动重试又能成功，但过一阵又断。
排查过程如下：我先看 WorkBuddy 的日志，发现断连发生时日志里没有任何请求记录，说明请求根本没到 WorkBuddy。再看 Codex 桌面端的日志，发现是它自己抛出了连接异常。
接着检查 WorkBuddy 监听的端口，发现 8324 端口实际上被两个进程占用了——WorkBuddy 监听了一部分，另一个程序抢占了同一端口的某些连接。这是因为当时我另一个开发项目里用了一个调试代理服务，它默认占用了 8324 端口。
处理办法是给 WorkBuddy 换了一个不常用的端口，比如 18324，然后在 Codex 桌面端的配置里同步修改地址。换完端口之后运行了一周，再没出现过断连。
这个坑的教训是：本地工具链用的端口号太常见，容易被其他服务抢占。建议你一上来就选一个非常见端口，别用那些开发工具默认爱占用的区间，能少一件糟心事。
5.4 踩坑二：WorkBuddy 缓存导致上下文混乱，回答张冠李戴
另一个比较隐蔽的问题，出现在长期使用之后。某次我在 Codex 桌面端里问一个问题，它给出的回答明显是另一个无关话题的延展，完全没有围绕我当前的问题。
一开始我以为是模型出问题了，后来发现是 WorkBuddy 的缓存机制在捣乱。WorkBuddy 为了节省重复请求的开销，对相同模型、相同参数、相同消息内容的请求会直接返回缓存的响应。这个机制在稳定场景下效率很高，但如果你在 Codex 桌面端里频繁修改代码、反复提问类似的问题，缓存命中时返回的可能是一个过期的回答。
WorkBuddy 的缓存设置里有两个关键参数：一个是缓存过期时间，另一个是缓存命中的判定条件。我在配置里把缓存过期时间从默认的 10 分钟改成了 60 秒，同时关闭了在代码生成场景下的缓存——因为代码生成的输入输出可能有细微变化，缓存的价值不大，反而更容易造成困惑。
如果你依赖缓存来提升响应速度，至少要做到：在修改代码文件之后，手动清理一次缓存，或者等缓存过期。Codex 桌面端的交互习惯是“改完代码再提问”，这两步之间的缓存策略一定要想清楚。
6. 局限性与扩展思路：零消耗不等于万能
6.1 本地小模型的能力边界：别拿它做架构设计
这套方案运行一周之后，我对它的优缺点有了更清晰的认识。
本地小模型最强的场景是：需求明确、输入输出边界清晰、代码量适中。比如给函数补注释、写单元测试、把一段代码改成某种风格、生成满足条件的 SQL，这些任务本地 14B 模型完成得很好，速度和稳定性都在线。
它最不擅长的是：跨文件的架构重构、抽象设计、模糊需求的探索、长文档的深层次理解。这些任务需要模型在全局视角下做权衡。本地模型的上下文有限，显存不足，强行处理的结果是顾此失彼，生成的代码质量不如云端模型。
所以我把这套方案的定位明确为“日常开发分流器”，而不是“全能替代者”。我的工作流是：日常琐碎任务默认走本地，遇到真正的设计难题再切到云端模型。这种“双轨模式”兼顾了效率和成本。
6.2 混合路由的思路：一个网关调用不同后端
WorkBuddy 的路由能力让我看到一种更灵活的用法：同一个 Codex 桌面端里，可以根据任务类型自动选择不同后端。
最简单的配置是按模型名区分。比如用qwen2.5-coder:14b这个模型名发请求，默认走本地。我再在路由表里加了一条规则，把deepseek-coder-v2:16b映射到一个付费云端接口，这样平时用本地模型，遇到困难任务时在 Codex 桌面端里手动切换模型名，就能临时用上云端能力。
这种混合路由还有一个好处：它把“切换”这个动作从配置管理转移到了操作习惯。你不需要改配置文件、不需要重启服务，只需要在会话里换一下模型名。我自己用这种方式做了两周实验，发现切换频率和项目复杂度直接相关。项目上手阶段，几乎全部走云端；进入稳定迭代阶段，90% 的请求都走本地。
6.3 日常维护：让整套链路长期稳定
最后分享几个日常维护的习惯，它们让我这套环境少出了很多问题。
模型更新。Ollama 的模型更新频繁，新版本出来之后我会先跑一轮回归测试，用固定的测试集比较新旧版本的效果。如果新版效果明显更好，就切换过去；如果差异不明显，就继续用旧版。
日志检查。每周看一下 WorkBuddy 的访问日志，留意异常请求和异常耗时。这一步能帮你提前发现磁盘空间不足、端口冲突、缓存命中率异常等问题。
配置备份。Codex 桌面端和 WorkBuddy 的配置文件我都放在一个单独的目录里，用版本管理工具做跟踪。每次改配置必然留下记录，出问题的时候能快速回滚。这个方法帮我避免了好几次“配置改坏了但不知道怎么改回去”的尴尬。
显存监控。在 Linux 上我习惯用nvidia-smi定时记录显存占用，把长期走势画出来，能直观看到哪个模型的 KV Cache 在偷偷膨胀。
这套方案到目前为止已经跑了几个月，整体稳定性我很满意。日常编码任务基本不依赖云端额度，响应速度和隐私性都远优于云端方案。当然它也不是没有代价——你需要花一点时间做配置，需要习惯“本地模型没有云端聪明”这个事实，需要定期做维护。但如果你也受够了积分消耗的速度，这个代价其实很划算。
