最近我把 Codex 桌面端和 WorkBuddy CLI 串在一起用了一套组合方案，折腾了一个多星期，终于把调用积分的消耗压到了几乎为零。这套搭配解决的问题很直接：桌面端适合交互式生成、看上下文、即时改代码；CLI 适合批量任务、无人值守、定时触发。可问题是，每次请求都会消耗远端服务配额，如果团队里多人共用还好说，个人开发者拿免费额度跑的话，几天就见底了。下面把完整配置思路、实操步骤和踩坑记录整理出来，给同在做方案选型的开发者做个参考。
这个配置思路适合三类人：一是用 Codex 桌面端做辅助编程、但不想频繁为积分付费的个人开发者；二是有批量代码注释生成、文档整理、审批文本生成等任务，希望用 CLI 全自动跑完的团队；三是想搭一套“本地模型优先 + 云端兜底”的资源控制方案，把不同工具统一收口到本地的技术负责人。如果你只是想随便问两句话，那直接开桌面端即可，不需要这套玩法；但如果你和我一样，每天的任务量在几十次到上百次请求，那这套配置是真的能帮你把配额省下来。
1. 为什么要把桌面端和 CLI 搭在一起用
1.1 桌面端适合什么场景
Codex 桌面端核心优势是对话式交互。你可以把整个工程目录挂进去，让它读文件、改文件、给出 diff，甚至围绕某一段报错来回追问。这个模式对需求探索、代码审查、疑难 Bug 定位特别友好，因为每次追问都带着完整上下文，人和模型之间能互相校准。
但桌面端有两个天然的短板。一是所有请求默认走远端服务，每次交互都在消耗配额；二是交互本身就要求人坐在电脑前，没法把“处理 100 个文件”这种任务丢给它自己跑。换句话说，桌面端是手工工具，适合思考密集、轮次多、需要人工判断的工作。
1.2 CLI 补充了什么能力
WorkBuddy CLI 正好补上自动化这一环。它是一个典型的命令行任务执行器，支持把任务定义成 YAML 或 JSON 配置，再通过命令行触发。我在项目里通常这样用：
- 把几十个代码文件统一交给它生成文档注释；
- 批量生成测试用例初稿；
- 定时执行代码审查报告；
- 把结构化数据转换成固定格式的文本模板。
CLI 的好处是稳定、可控、可挂到 CI 流水线里。它自己不生成内容，只负责任务调度、参数拼接、结果收集。那么真正决定“积分消耗多少”的，是它把请求转发到哪里，以及转发前后做了什么处理。
1.3 积分消耗到底发生在哪个环节
先说一个容易混淆的点：积分消耗发生在模型推理服务的请求环节，而不是工具本身的调用环节。无论是桌面端还是 CLI，最终都会把 prompt 打包成一个 API 请求，发给模型服务商，服务商按 token 或按请求次数计费。
所以，要实现“积分零消耗”，核心只有一条：让尽可能多的请求不发到计费服务上，或让请求在到达计费服务前就被本地逻辑消化掉。这不等于白嫖，而是有几种常见做法：
- 请求全部走本地模型推理，完全不发远端；
- 相同或相似的 prompt 命中本地缓存，直接返回历史结果；
- 请求通过网关转发到本地模型，只有在本地模型置信度不够时才调远端；
- 不调用付费模型，而是用免费额度的服务端点来承载任务。
我的方案是后三者的组合，通过本地网关把桌面端和 CLI 统一收口，从源头上控制请求出口。这样积分消耗不是“碰运气省下来”，而是“配置上就不允许过量消耗”。
1.4 方案整体架构
架构可以用文字简单描述，不需要画图也能说清：
Codex 桌面端 --> 本地网关 --> 缓存层 --> 本地模型引擎 --> （可选）远端兜底服务 WorkBuddy CLI --> 本地网关 --> 缓存层 --> 本地模型引擎 --> （可选）远端兜底服务本地网关是关键节点。它统一监听桌面端和 CLI 发出的请求，先查缓存，再尝试本地模型，最后才考虑远端服务。远端兜底默认关闭，需要显式配置才会放开。也就是说，即使桌面端或 CLI 天生习惯把请求发到云端，经过网关后也会被强制改道。
这套方案我实测整体体验很好，缺点是需要花点时间做初次配置。下面把每一步拆开讲。
2. 环境准备与安装配置
2.1 桌面端安装与环境依赖
Codex 桌面端安装本身不复杂，下载安装包、按提示完成初始化即可。真正要注意的是依赖项。
我的环境是 Windows 11，日常也偶尔切到 Linux 服务器上跑重任务，两者配置思路一致，差异只在路径写法上。安装前先确认下面几项：
- 操作系统为 64 位；
- 已安装 Git，并配置好 SSH 密钥；
- 有 Python 3.10 或更高版本，且
python命令可用； - 有 Node.js 16 以上版本，WorkBuddy CLI 的部分插件依赖它；
- 磁盘剩余空间至少 8GB，如果后面要放本地模型，建议预留 20GB。
这些依赖不一定全都要用到，但先装齐能避免后面排查半天结果卡在环境变量上。安装完桌面端后，先不做任何代码仓库关联，等 CLI 和网关都配好再接入。
2.2 WorkBuddy CLI 安装
WorkBuddy CLI 是独立于桌面端的命令行程序，安装方式很简单，我用的是包管理器一键安装，也可以从内部源直接拉取二进制包。
安装完成后，建议先把命令加入 PATH。在 Linux 或 macOS 下，我习惯写入 shell 配置文件；在 Windows 下则通过系统环境变量窗口追加。加入后新开一个终端，输入命令验证版本：
workbuddy --version如果输出版本号，说明安装成功。如果提示找不到命令，八成是 PATH 没生效，重新打开终端或手动刷新环境变量即可。
WorkBuddy CLI 的配置目录默认在用户目录下的.workbuddy文件夹中，后续所有配置项都会集中在这里：
config.yaml：主配置文件，包含网络端点、模型路由、缓存策略；tasks/：存放任务定义文件；cache/：请求缓存数据库；logs/：运行日志。
建议先看一下默认生成的config.yaml长什么样，再动手改。
2.3 完成首次连接
安装完成后，需要让 WorkBuddy CLI 能“看到” Codex 桌面端。其实这里的连接不是指两个软件直接点对点通信，而是让它们都指向同一个本地网关地址。
默认情况下，桌面端监听在127.0.0.1:7860，WorkBuddy CLI 的默认配置是走命令行直连远端。我们需要把它们都拉到同一个局域网地址上。我的实际操作是：
- 先启动本地网关服务（下一节详细写）；
- 在桌面端设置页面把服务地址改成
http://127.0.0.1:9100/v1； - 在 WorkBuddy CLI 的
config.yaml中把endpoint改成同一个地址：
endpoint: http://127.0.0.1:9100/v1 api_key: local-gateway-key注意，api_key这一项即使在纯本地模式下也要填一个值，否则客户端会报鉴权失败。这个 key 不是远端服务的密钥，而是本地网关用来识别来源的简单口令，可以自己自定义一串随机字符串。
这样做的价值在于：桌面端和 CLI 虽然功能不同、入口不同，但它们的所有 API 请求都汇聚到本地网关，策略就能收口了。
2.4 验证环境是否正常
配置改完别急着跑大任务，先用一条轻量请求验证链路。在 WorkBuddy CLI 里执行：
workbuddy run --task simple-test其中simple-test是一个最简单的任务，比如让模型输出“hello”三个字母。如果配置正确，桌面端同样会在这个网关看到请求记录。查看日志：
workbuddy logs --tail 20日志里会显示请求到达时间、路由目标、token 消耗等关键信息。看到[cache miss]或[local]标记就说明链路通了。
3. 零积分消耗的核心配置
3.1 流量代理网关：把云端调用换成可控本地出口
本地网关是整个方案的心脏。它可以理解成一个反向代理服务，负责接收来自桌面端和 CLI 的请求，再按配置路由到不同后端。我选择用 Go 写的一个轻量级开源网关程序，单二进制文件，内存占用低，自带日志和统计面板。
网关配置的核心是一份路由规则，示例：
routes: - match: "*" cache: true local_model: true remote_fallback: falseremote_fallback: false这一条极其重要，它表示所有请求都走本地，拒绝远端。这也是实现积分零消耗的最强保证。如果某天你需要部分请求走远端，再把这条改成true，并配置远端服务地址。
我见过不少人的配置失败是因为这里写反了：他们把远端地址写成默认兜底，结果网关恢复正常时远端请求量也跟着恢复，积分消耗依然压不住。先关掉远端，再逐步放开，才是稳妥的顺序。
3.2 本地模型兜底策略
只做代理还不够，还得有真正能接住请求的本地模型。我目前用的是量化版的对话模型，部署在本地推理引擎里，通过一个 HTTP 接口提供 OpenAI 兼容的 API 输出。
选择本地模型时要考虑几个关键参数：
| 参数 | 推荐值 | 说明 |
|---|---|---|
| 参数量 | 7B 到 14B | 通用代码任务够用，再大对显存压力大 |
| 量化方式 | Q4_K_M | 质量和体积平衡较好 |
| 上下文长度 | 8K 以上 | 桌面端常需要塞整段代码 |
| 推理引擎 | 支持 GPU 加速即可 | CPU 也能跑，但速度慢 |
本地模型地址我配置为http://127.0.0.1:11434/v1，兼容标准和 OpenAI 类似的请求格式。这样桌面端和 CLI 不用感知背后是本地还是云端，它们只是看到一个标准 API 端点。
网关与本地模型的联动规则：
- 如果请求的 prompt 缓存命中，直接返回，不进入模型；
- 如果未命中，交给本地模型处理；
- 如果本地模型请求失败，默认记录错误并返回失败，而不是贸然转远端。
3.3 请求缓存与结果复用
请求缓存是另一个省积分的利器，尤其是在团队或单人多轮迭代场景下收益非常可观。
缓存原理简单：把输入 prompt 作哈希，映射到结果。相同或高度相似的请求直接返回历史值，不重复调用模型。我的缓存配置如下：
cache: enabled: true type: sqlite path: /home/user/.workbuddy/cache/requests.db ttl: 604800 similarity_threshold: 0.92ttl是缓存有效期，单位秒，604800 就是一周。similarity_threshold表示相似度超过 0.92 就算命中，这个值需要通过实际任务调。设太高命中率低；设太低会把不相关的内容误判为同一请求，导致结果张冠李戴。
我自己调下来的经验是：代码生成类任务，0.92 以上比较稳；文档总结类任务可以放到 0.88 左右。缓存命中后，日志里会出现[cache hit]，统计面板中积分数为 0。
另外，缓存目录建议定期归档，不要一直无限膨胀。sqlite 在几十万条记录后查询性能会下降，我一般每个月清理一次超过 30 天的过期数据。
3.4 批量任务与低峰调度
批量任务做得越多，越能感受到这套配置的好处。
以前我直接用命令行逐个调模型时，每个文件都是一次独立请求，光网络握手和鉴权就消耗不少时间。现在到了 WorkBuddy CLI 里，我会把任务写成批处理文件。
举一个实际例子：我要给 200 个 Python 文件生成函数级注释。任务定义大致如下：
name: batch-docstring type: code concurrency: 4 input: dir: ./src pattern: "*.py" steps: - prompt_template: "请为以下代码生成简洁的 docstring：\n{{file_content}}" - output_dir: ./docs关键参数是concurrency。一开始我以为并发越高越快，结果把 GPU 显存打满，速度反而下降。后来锁定在 4 到 6 之间最优。因为是本地模型，并发不会消耗积分，但如果模型加载了多个实例，内存会被撑爆，所以并发数要结合本地资源来定。
低峰调度也很实用。桌面端白天用的人多，本地模型也在承担交互请求；而批量任务占用资源大，我把它安排到凌晨 2 点到 6 点执行。WorkBuddy CLI 支持调度表达式，启动命令加上时间窗口参数即可：
workbuddy schedule --task batch-docstring --cron "0 2 * * *"这个时间窗口内的请求基本都能命中本地模型，且桌面端交互不受影响。
3.5 配额预算控制
即使配置了本地优先，也要给“预算控制”上一道保险。我对预算的控制不是靠手动记账，而是用网关里加的一组数值限制，超过就直接拒绝或延迟处理。
budget: enabled: true daily_request_limit: 1000 daily_token_limit: 1200000 weekly_request_limit: 6000 action: delay当请求量达到每日限额的 80% 时，网关开始返回提示；达到 100% 时，按action字段处理。delay是延迟排队，等下一分钟窗口重置配额；reject是直接拒绝请求。
这不直接产生积分消耗，但能避免一些极端情况。比如某次批量任务配置写错，递归调用了 3 万次；或者某个插件内部重复循环。没有预算控制的话，就算网关把远端关闭了，本地模型也会被高负载拖垮。
3.6 完整配置清单示例
把所有核心配置拼到一起，我的config.yaml大概是这样的：
endpoint: http://127.0.0.1:9100/v1 api_key: local-gateway-key router: cache_first: true local_model: enabled: true base_url: http://127.0.0.1:11434/v1 model_name: code-local-q4 remote: enabled: false base_url: "" api_key: "" cache: enabled: true type: sqlite path: /home/user/.workbuddy/cache/requests.db ttl: 604800 similarity_threshold: 0.92 budget: enabled: true daily_request_limit: 1000 daily_token_limit: 1200000 weekly_request_limit: 6000 action: delay logging: level: info path: /home/user/.workbuddy/logs/gateway.log代码块里已经展示了一个可直接复用的配置模板。下次新环境部署，我通常就是把这套配置复制过去，改一下路径和 key 即可。
4. 实操案例：用 WorkBuddy CLI 执行一次完整任务
4.1 任务定义与排队
纸上谈兵没有说服力，我拿最近做的一个实际任务演示完整过程。
需求是给一套旧系统生成接口变更说明文档，源目录里有 86 个 JavaScript 文件，每个文件里都有若干接口定义。如果手动写，至少要两三个小时；用人工去复制粘贴逐条调模型，又费积分又费时间。
我在 WorkBuddy CLI 中这样定义任务：
name: api-change-docs type: code concurrency: 6 input: dir: ./legacy-system/src pattern: "*.js" exclude: "*.test.js" steps: - prompt: | 你是资深前端工程师。请分析下面的代码中包含的 API 接口定义， 输出一个 markdown 表格，包含接口名、请求方法、参数列表、返回值、变更影响。 只输出表格，不要额外解释。 source: "{{file_content}}" - output: ./docs/api-changes/{{file_name}}.md任务写好之后通过命令行提交：
workbuddy run --task api-change-docs --tag legacy-systemCLI 会扫描输入目录，逐个生成待处理队列。这一步本身不产生模型请求，只是把文件路径和 prompt 模板组合好放入队列。
4.2 任务执行与积分统计
执行过程中，我通过两个渠道观察状态。一是 CLI 自带的实时进度条，可以看到已完成、执行中、失败三个数字；二是网关的统计面板，可以查询每个请求的具体路由目标。
最终结果：
- 任务总数：86；
- 成功：84；
- 失败：2；
- 缓存命中：37；
- 本地模型请求：47；
- 远端请求：0；
- 消耗积分：0。
86 个文件里，有 37 个直接命中缓存，因为其中不少接口函数在之前的任务里已经生成过文档，相似度超过了 0.92。另外 47 次请求全部走了本地模型，远端请求为 0，所以本批任务的积分消耗是 0。
那两个失败任务，一个是文件编码格式不是 UTF-8，另一个是文件体积太大被任务级max_input_size拦下。前者重新转码后通过；后者拆成两个子任务后也通过了。
4.3 使用效果复盘
这个案例让我对整套方案有了更直观的体感。
算一笔账：如果 86 次请求全走远端付费端点，按每次请求约消耗 3000 token 计算，差不多是 25 万 token，一个月来几次这种任务，免费额度基本清零。而走本地模型后，唯一变化是生成速度比高端云端模型慢一些，大约慢 2 到 3 倍，但胜在稳定零计费。
我个人的经验是：把“必须高质量回答”的任务留给桌面端或云端，把“量大、重复、结果可校验”的任务全部交给 CLI 批跑。这个边界划清楚之后，积分消耗基本不会失控。
5. 常见问题与排查实录
5.1 连接失败：桌面端显示“无法连接到服务”
最常见原因是桌面端配置的服务地址和网关实际监听地址不一致。检查一下三个地方：
- 网关是否真的在运行；
- 桌面端设置里的地址有没有写错端口；
- WorkBuddy CLI 的
endpoint是否与桌面端共用同一地址。
我踩过的一个典型坑是在 Windows 下把localhost和127.0.0.1混用。某些组件解析localhost时会走 IPv6::1，但网关只监听了 IPv4，连接就会失败。统一改成127.0.0.1通常能解决。
5.2 请求超时：本地模型处理时间太长
本地模型处理长 prompt 时，速度确实比云端慢，尤其 CPU 推理更是肉眼可见的慢。桌面端默认超时时间可能只有几十秒，长任务很容易超时。
解决办法有两个方向：一是调高桌面端和 CLI 的请求超时时间，我通常设为 300 秒；二是优化 prompt，减少上下文长度。用 WorkBuddy CLI 批量处理时，我会把文件预处理一下，删除无关 import 和空行，缩短输入文本。
网关日志里如果看到大量deadline exceeded，优先怀疑超时配置，其次检查模型负载。
5.3 配额统计不准确
有时打开网关统计面板，发现请求数和我自己计算的对不上。排查后发现是缓存命中的请求也被统计进了总请求数，但 token 消耗是 0。
这个不算 Bug，只是统计口径问题。所以后来我在看数据时区分两个指标：总请求数和计费请求数。缓存命中不应该和远端消耗混在一起看，否则会误判优化效果。
5.4 缓存未命中：相似请求没复用结果
缓存未命中通常有三种原因：
- prompt 模板中带时间戳或随机数，导致每次请求内容不同；
similarity_threshold设得太高；- 相同请求分散在不同任务的 prompt 里，但模板措辞有细微差别。
第一种最隐蔽。我最初在 prompt 里加了系统当前时间，结果同一任务里的 86 个请求几乎全部 cache miss。去掉时间变量后，命中率立刻上升。
5.5 避坑清单
最后整理一份避坑清单，这些都是我自己真实踩过的坑，每条对应的都是一个星期的排查成本：
- 不要一开始就追求零消耗。先把链路跑通、把请求日志看明白，再一步步关远端、开缓存，否则出了问题时连问题定位都难。
- 本地模型要用稳定的运行版本。升级模型文件后要重新跑一次完整测试，确认输出格式没变化。我曾经升级后输出里多了很多解释性文字，导致后续脚本解析全部失败。
- 并发数别盲目调高。本地推理引擎的并发设置要和显存大小匹配，不然会频繁触发内存换出，整体吞吐反而下降。
- 定期备份缓存数据库。缓存积累越多，价值越大。如果硬盘故障或误删目录，之前的请求缓存全部丢失，积分消耗会重新暴露出来。
- 任务输出一定要可校验。无论模型是本地还是云端，都有概率生成错误内容。批量任务前，至少要准备一个针对输出格式的校验脚本，能自动标记异常文件。
另外，桌面端和 CLI 的搭配，我建议你在小范围内先跑两周，记录每天的请求量、缓存命中率和耗时，用数据判断这套方案是否适合自己。不要因为“积分零消耗”这个目标，就把所有请求都强行关进本地模型，那样可能在结果质量上付出隐性代价。某些高难度推理任务，该走云端就让它走；优先把重复性、机械性任务留在本地，才是长期可持续的平衡。
经历了这一轮配置，我再也不担心桌面端和 CLI 之间“各算各的账”了。哪怕以后模型服务商调整了积分规则，只要本地网关这一层还在，资源控制权就始终在自己手上。这就是我目前觉得最踏实的地方。
