Spewer：为Codex CLI与Claude Code添加智能模型路由，降低Token成本

在实际使用 Codex CLI 和 Claude Code 时，成本问题往往比“哪个模型能力更强”更早摆在面前。Codex CLI 默认走 OpenAI 的旗舰模型，Claude Code 默认走 Anthropic 的高端模型，一次涉及多文件重构的会话，可能消耗数万甚至数十万 token。而会话里真正需要旗舰模型的任务并不占全部：补注释、写单测、改文案、格式化代码、解释报错，这些任务用便宜模型也能完成。Spewer 这类工具的核心思路，就是在 Codex CLI / Claude Code 与模型服务之间插入一个本地调度层，让简单任务自动委托给更便宜的模型，真正复杂的任务才放行到旗舰模型。

下面按四个部分展开：先讲为什么需要这一层调度，再把 Codex CLI 和 Claude Code 环境跑稳，然后配置模型路由规则并跑通最小案例，最后处理部署后最常见的报错。文末会给出可直接用到生产环境的检查清单。适合已经在用 Codex 或 Claude Code、并且对 token 费用敏感的开发者和团队阅读。

1. 先理解为什么要在 Codex/Claude 与模型之间加一层调度

1.1 旗舰模型的成本压力在哪里

模型 API 的计费一般按输入 token 和输出 token 分开计算，输入侧又分普通输入和缓存命中输入。AI 编程助手的使用方式会放大两个成本因素。

第一是上下文累积。Codex CLI 和 Claude Code 为了保持对项目的理解，会把文件内容、命令行输出、历史对话一起放进上下文。一个中型项目排查问题时，上下文长度很容易超过几万 token，即使没有新的代码生成，每次请求都在为这些输入 token 付费。

第二是高频小任务。AI 编程助手里有大量“低难度问答”，例如“这个函数哪里写错了”“帮我把这段代码格式化成符合规范的写法”“给这个方法补 Javadoc”。这些任务用旗舰模型执行当然没问题，但性价比很低。在多数模型提供商的计费表中，旗舰模型与轻量模型的单 token 价格差异可以达到一个数量级甚至更高。

如果所有请求都固定走旗舰模型，费用会随会话次数线性上升，而且很难通过“少用几次”来缓解，因为开发者不会因为费用放弃日常辅助。

1.2 Codex CLI 与 Claude Code 的执行链路

理解 Spewer 之前，要先看这两个 CLI 的工作链路。

Codex CLI 是 OpenAI 提供的终端编程助手，它启动后读取系统提示、项目文件和相关工具输出，向模型服务发起对话补全请求，再把模型返回的代码块或命令执行结果呈现给用户。Claude Code 类似，是 Anthropic 提供的终端代理，它同样依赖一个命令行入口与远程模型服务通信。

两者都有一个共同结构：CLI 进程负责“感知与执行”，模型服务负责“推理与生成”。CLI 进程通过配置拿到模型服务的地址（base URL）、模型名称（model）和认证密钥（API key），然后按照协议发起请求。

Spewer 的切入点就在这里。只要让 CLI 进程把请求发到本地一个监听地址，由这个本地服务按规则决定转发到哪个模型，就能在不改变 CLI 使用习惯的前提下，改变每次请求背后的模型选择。

1.3 委托调度的三条核心规则

一个可用的委托调度器，至少要有三条规则可配置。

• 按任务类型路由：判断任务是代码生成、问题解释、代码评审还是命令执行辅助，不同任务分配给不同模型。
• 按上下文复杂度路由：请求的 token 数低于阈值时走便宜模型，超过阈值或上下文很长时走旗舰模型，避免旗舰模型处理海量输入。
• 按结果兜底：便宜模型返回低质量结果或触发错误时，自动重试一次旗舰模型。

这三条规则对应的是同一个目标：在不明显降低用户体验的前提下，把占用成本的大头从“每个请求都是旗舰模型”改成“只有真正需要时才使用旗舰模型”。

2. 准备环境：让 Codex CLI 和 Claude Code 先能稳定运行

无论 Spewer 的调度规则多完善，前提都是两个 CLI 本身能在本机正常启动。这一章先解决命令行入口问题，后续的报错排查会经常回到这里。

2.1 前置依赖与版本检查

Codex CLI 和 Claude Code 都属于 Node.js 生态的命令行工具，通常通过 npm 全局安装。建议先确认本机环境。

检查命令：

node -v npm -v

如果 node 命令不存在，先去对应平台的安装包安装，再重新打开终端。版本太老时，安装 CLI 可能会在依赖编译阶段报错，或者安装后运行时提示不支持的语法。

2.2 安装 Codex CLI 的两种方式

Codex CLI 的安装方式并不唯一，常见有两种。

第一种是通过 npm 全局安装：

npm install -g codex

安装完成后运行版本检查：

codex --version

第二种是直接使用官方提供的可执行文件安装包。这种方式适合不希望依赖 Node 环境的机器，安装后需要把可执行文件目录加入 PATH。

安装后最常见的问题是终端提示找不到 codex 命令。如果 npm 全局安装成功但命令找不到，通常是 npm 的全局 bin 目录不在 PATH 中。可以先查看全局目录，再把对应路径加入 PATH。

npm prefix -g

在 Windows PowerShell 中，可以把 npm prefix 返回的目录下的 node_modules/.bin 加入用户 PATH，然后重新打开终端。

2.3 安装 Claude Code 并解决 PATH 问题

Claude Code 的安装方式类似，也是通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装后运行：

claude --version

Windows 环境下比较常见的错误是 PowerShell 提示“claude 无法识别为 cmdlet、函数、脚本文件或可运行程序的名称”，或者 cmd 提示“claude 不是内部或外部命令”。这两个提示都指向同一个原因：npm 全局 bin 目录没有加入 PATH。

解决方式：

1. 运行npm prefix -g得到全局目录。
2. 把<全局目录>/node_modules/.bin加入用户 PATH。
3. 重新打开终端，再执行claude --version。

macOS 和 Linux 上如果使用 nvm 管理 Node，还要注意 npm 全局目录会随 Node 版本切换而变化，切换 Node 版本后可能再次出现命令找不到的问题。

2.4 用最小命令验证两个 CLI

环境变量配置完成后，用三组命令确认基础链路可用。

codex --version claude --version echo $CODEX_CLI_PATH

如果codex --version能输出版本号，说明 Codex CLI 本体可执行。如果设置了 API Key，可以再做一次极小的对话请求：

codex exec "用一句话解释什么是路由"

这一步验证的是 CLI 到模型服务的真实连通性。如果这一步就报鉴权失败或网络错误，说明问题在 API Key、账号或接入地址，而不是 Spewer 的配置，先不要进入下一步调度。

3. Spewer 的委托机制与核心配置

3.1 Spewer 在链路中的位置

Spewer 可以理解为一个位于 CLI 与模型服务之间的本地调度服务。它监听本机某个端口，接收 Codex CLI 或 Claude Code 发出的模型请求，读取请求内容和上下文信息，按规则选择一个目标模型，再代为请求对应模型服务，最后把结果返回给 CLI。

这样做的价值是：CLI 进程不需要感知模型变化，用户也不需要改工具本身。所有策略都集中在 Spewer 的配置里。

需要特别说明的是，不同项目和不同版本的 Spewer 可能使用不同配置文件格式。下面示例用于说明通用思路，落地前要以你下载到的项目 README 为准，先跑通默认配置，再逐步加规则。

3.2 模型路由规则配置

路由规则通常由一个 YAML 或 JSON 文件描述。以 YAML 为例，一个典型配置可能包含模型列表、任务类型映射、上下文阈值和兜底策略。

server: listen: "127.0.0.1:8787" endpoints: codex: "/responses" claude: "/v1/messages" models: cheap: provider: openai model: gpt-4o-mini base_url: https://api.openai.com api_key_env: OPENAI_API_KEY expensive: provider: openai model: gpt-5 base_url: https://api.openai.com api_key_env: OPENAI_API_KEY deepseek: provider: deepseek model: deepseek-chat base_url: https://api.deepseek.com api_key_env: DEEPSEEK_API_KEY default_to: cheap rules: - task_type: ["explain", "format", "generate-test", "comment"] route_to: cheap - task_type: ["refactor", "architecture", "complex-debug"] route_to: expensive - input_tokens_gt: 30000 route_to: expensive - fallback: expensive

这个配置表达了几层意思：

• 服务监听本机 8787 端口，同时暴露两个端点，一个给 Codex 的 Responses API 风格请求，一个给 Claude 的 Messages API 风格请求。
• 默认请求走便宜模型gpt-4o-mini。
• 任务类型为解释、格式化、写测试、补注释时走便宜模型。
• 任务类型为重构、架构、复杂调试时走旗舰模型。
• 输入 token 估算值超过 30000 时自动升级到旗舰模型。
• 便宜模型失败时，兜底重试旗舰模型。

需要注意：Codex CLI 和 Claude Code 的 API 协议并不相同。Codex 走 Responses API 风格，请求路径通常是 /responses；Claude Code 走 Anthropic Messages API 风格，请求路径通常是 /v1/messages。如果本地方向要同时服务两个 CLI，调度服务需要分别监听两个端点，并把请求转换为目标模型服务商要求的格式。这也是“委托调度”比“单纯改 base URL”复杂的地方。

3.3 指定 CLI 路径与环境变量

热词搜索中反复出现的 "unable to locate the codex cli binary. set codex cli path or ensure the elec..." 这类报错，通常不是 Spewer 本身的问题，而是宿主程序（例如桌面端 IDE 插件）找不到 Codex CLI 的可执行文件。

如果 Spewer 需要拿到 Codex CLI 的路径来启动子进程，可以显式配置环境变量：

export CODEX_CLI_PATH=/usr/local/bin/codex export CLAUDE_CLI_PATH=/usr/local/bin/claude

Windows PowerShell 下使用：

$env:CODEX_CLI_PATH="C:\Users\你的用户名\AppData\Roaming\npm\codex.cmd" $env:CLAUDE_CLI_PATH="C:\Users\你的用户名\AppData\Roaming\npm\claude.cmd"

配置完成后，再启动 Spewer，避免启动时找不到 CLI 二进制。

3.4 API Key 与模型参数注意事项

在路由配置中，不同模型可能对应不同服务商，因此 API Key 不能只配一个。推荐统一使用环境变量保存，避免把密钥写进 YAML 后提交到代码仓库。

export OPENAI_API_KEY="sk-..." export DEEPSEEK_API_KEY="sk-..." export ANTHROPIC_API_KEY="sk-ant-..."

模型参数部分需要关注几个点：

• temperature 建议区分任务：解释类任务可以低一些，保持稳定；创意类代码生成可以略高。
• max_tokens 建议按任务类型设置上限，避免简单任务产生超长输出，费用被输出 token 放大。
• 上下文阈值要参考目标模型的上下文窗口，不能把 20 万 token 的上下文发送给只支持 16k 的轻量模型。

如果配置文件里设置的模型 ID 与目标服务商支持的模型 ID 不一致，请求会直接失败。这类错误在热词中也很常见，比如 "xxx model is not supported when using codex" 和 "xxx is not a model this version of claude code recognizes"。遇到时要先检查配置文件里的 model 字段，再检查对应服务商当前支持的模型列表。

4. 最小可运行案例：把简单任务交给便宜模型

4.1 设计两个任务等级

为了验证委托机制，先设计一个最简单但能看出效果的两级场景。

• 轻量任务：代码解释、补注释、写简单测试、格式化。
• 重量任务：跨文件重构、架构设计、复杂 bug 排查。

在配置里把轻量任务指向便宜模型，重量任务指向旗舰模型。这样既能验证成本下降，也能验证规则确实生效。

4.2 编写最小化配置

在一个测试目录中创建 spewer.yaml：

server: listen: "127.0.0.1:8787" endpoint: "/responses" models: cheap: provider: openai model: gpt-4o-mini base_url: https://api