OmniRoute Auto Combo 预算路由教程：2026 Agent

请求明明设置了预算，首选模型不可用后却仍然继续执行，费用也没有被真正挡住。

最快的处理方式是：先建立候选模型白名单，再设置请求级预算，并把 X-OmniRoute-Budget-Fallback 明确设为 strict；完成预算拦截、供应故障、凭据失效和无可用候选四类测试后，才把规则交给团队使用。默认的 cheapest 回退并不等于严格预算控制。

这篇文章适合想用 OmniRoute Auto Combo 控制单次 Agent 请求成本的开发者，需要为多个代码 Agent 客户端建立统一路由规则的平台工程师，以及准备把本地网关迁移到持续在线环境的远程团队。

先分清三种预算，否则配置一定会失真

OmniRoute 的请求级预算、API Key 的 Token 限额和团队周期预算，控制的是不同层面。把它们写进同一条规则，常见结果是“单次请求没有超支，但周期额度很快耗尽”，或者“周期额度还有余额，某一次请求却直接使用了超出预期的模型”。

OmniRoute API Reference 明确区分了 USD 预算和 Token 限额；Token 限额还可以按 model、provider 或 global 作用域设置，多个限制同时命中时，以更严格的限制为准。预算接口则支持日、周、月周期以及告警阈值。

动手前先写下三项内容：

• 单次 Agent 请求的成本上限；
• 每个 API Key 的 Token 限额和重置周期；
• 超预算时的处理方式：阻断、降级，还是只告警。

如果是生产 Agent，默认建议选择“阻断”；如果是内部探索任务，可以选择“降级”；只告警适合已经有人工审核和费用追踪的团队，不适合无人值守任务。

第一阶段：只把健康候选加入 Auto Combo

Auto Combo 的候选池越大，路由选择越灵活，但排查成本也越高。预算路由不应一开始就加入所有已连接模型，而应先放入已经完成凭据验证、基础请求、流式输出和工具调用测试的候选。

候选记录至少包含以下字段：

{
  "provider": "PROVIDER_PLACEHOLDER",
  "model": "MODEL_PLACEHOLDER",
  "purpose": "coding_or_general_agent",
  "fallback": "BACKUP_MODEL_PLACEHOLDER",
  "credentialStatus": "verified",
  "streamingTest": "passed",
  "toolCallTest": "pending"
}

其中，provider、model、内部地址和账户标识都应使用实际环境中的安全变量，不要把密钥直接写入组合配置或教程命令。

Auto Combo 官方文档说明，auto 可以通过虚拟组合动态选择目标，也可以创建持久化组合并使用 strategy: "auto"；多轮任务若需要保持供应商黏性，可以使用已保存的组合，而不是每次重新生成候选池。

⚠️ 经验提醒：候选模型“能返回文本”不代表它适合 Agent。工具调用格式、流式结束标记、长上下文行为和错误响应结构，只要有一项不稳定，就不应直接放进生产白名单。

第二阶段：OmniRoute Auto Combo 预算路由的关键配置

OmniRoute Auto Combo 的请求级控制重点是三个请求头：X-OmniRoute-Mode、X-OmniRoute-Budget 和 X-OmniRoute-Budget-Fallback；其中预算值表示单次请求允许的最高成本，候选会在选择前按预算进行过滤。字段名称和状态码应以正在运行的版本为准，配置前应同时核对对应版本的路由文档。

下面的命令可以作为测试模板，预算值必须替换成团队内部经过审批的占位配置：

curl -sS "${OMNIROUTE_BASE_URL}/v1/chat/completions" \
  -H "Authorization: Bearer ${OMNIROUTE_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "X-OmniRoute-Mode: balanced" \
  -H "X-OmniRoute-Budget: ${REQUEST_BUDGET_PLACEHOLDER}" \
  -H "X-OmniRoute-Budget-Fallback: strict" \
  -d '{
    "model": "auto",
    "messages": [
      {
        "role": "user",
        "content": "请执行一项非生产测试任务"
      }
    ]
  }'

需要特别注意：cheapest 的含义不是“永远不超过预算”。当前 Auto Combo 行为说明描述的是，如果所有候选都超过预算，cheapest 仍可能选择全局最便宜的候选，即使它依然超出请求上限；strict 则拒绝选择，并以 HTTP 402 快速失败。

因此，针对长尾问题可以直接给出判断：

• 如果要求超预算后直接阻止请求，使用 strict 或其阻断别名；
• 如果允许任务继续，但必须降低模型档位，先把低成本模型加入白名单，再选择降级策略；
• 如果不能接受切换到更贵的模型，不能只设置 cheapest，必须同时限制候选池；
• 如果不同 Agent 需要不同预算，应为不同 API Key、不同请求头注入规则或不同持久化组合分别配置，不要依赖一个全局默认值。

第三阶段：四类故障模拟决定能不能上线

配置完成后，不要马上接入真实团队任务。最少要模拟以下四类结果，并保存请求 ID、预算配置、候选列表、路由解释、错误响应和最终模型。

这里要区分 HTTP 402 和 HTTP 429：前者用于请求级预算策略拒绝，后者通常对应 Token 限额或上游限流。API Reference 的限额说明显示，达到 Token 限额窗口后，请求会被拒绝为 429 Too Many Requests。

可用下面的顺序验收：

1. 先用极低的占位预算发送一条短请求；
2. 确认 strict 触发时没有静默切换到更贵目标；
3. 暂时禁用首选供应，确认备用目标来自白名单；
4. 使用失效凭据，确认日志中能看到失败原因；
5. 模拟限流后，检查客户端自身重试是否重新发起了绕过预算的请求。

如何确认一次请求为什么被路由到某个模型

只看最终返回的模型名称不够。平台团队需要同时保存“候选被过滤的原因”和“最终选择的原因”，否则后续只能凭感觉判断成本为什么变化。

官方 Auto Combo 文档描述了动态评分、候选过滤和回退机制；OmniRoute MCP 文档还列出了用于解释路由原因的 omniroute_explain_route，以及可用于预演回退树的 omniroute_simulate_route。

路由日志至少应包含：

{
  "requestId": "REQUEST_ID_PLACEHOLDER",
  "requestedModel": "auto",
  "budget": "REQUEST_BUDGET_PLACEHOLDER",
  "fallbackPolicy": "strict",
  "candidatesConsidered": ["MODEL_A", "MODEL_B"],
  "filteredCandidates": [
    {
      "model": "MODEL_C",
      "reason": "over_budget_or_unavailable"
    }
  ],
  "finalModel": "MODEL_A",
  "routeReason": "ROUTE_REASON_PLACEHOLDER"
}

判断一次路由是否合理，重点看三项：

• 最终模型是否属于允许的候选白名单；
• 被排除的模型是否有可解释原因；
• 失败后是否发生了客户端层面的重复请求。

如果日志只记录了“成功”或“失败”，没有候选和策略信息，就不适合交付给多人共用。

第四阶段：先接入一个非生产 Agent 客户端

第一个客户端不要直接选团队最常用、任务最长的入口。应选择一个可随时停用的非生产客户端，逐项检查模型映射、流式输出、工具调用和长任务。

接入时建议统一使用以下占位变量：

export AGENT_BASE_URL="${OMNIROUTE_BASE_URL}/v1"
export AGENT_API_KEY="${AGENT_KEY_PLACEHOLDER}"
export AGENT_MODEL="auto"

接着执行四组测试：

• 短文本请求：确认地址和密钥生效；
• 流式请求：确认结束标记和中断行为正常；
• 工具调用：确认函数参数没有被路由层改写；
• 长任务：确认客户端重试不会重新创建一条没有预算头的请求。

有些客户端会在网络失败后自动重试。如果预算头只配置在第一次请求，而重试请求没有继承它，就可能出现“首请求被拦截，重试请求继续执行”的成本漏洞。平台工程师应在网关访问日志中按请求 ID 或关联 ID 检查整条重试链。

第五阶段：灰度、告警和团队交付

首周不要一次性把所有成员切到同一个 Auto Combo。更稳妥的方式是按客户端、项目或成员逐步放量，并为每一组设置独立的 API Key 和预算策略。

OmniRoute 的 API 使用与预算接口说明还提供预算状态、使用记录、路由组合和 Webhook 等接口，可用于把预算触发、配额耗尽和请求完成事件接入团队告警流程。

建议至少建立三种告警：

• 单次请求被 strict 拒绝；
• API Key 接近周期 Token 或费用上限；
• 某个候选模型连续出现凭据失败、限流或供应不可用。

决策条件：什么时候选 strict，什么时候允许回退

• 若生产 Agent 的单次请求成本不能突破审批上限，则选 strict；否则回退到带人工审核的降级策略。
• 若候选模型数量少于一个可用主力和一个备用目标，则先补齐健康候选，不要直接扩大 Auto Combo 权限。
• 若不同团队的任务复杂度差异明显，则按 API Key 或持久化组合拆分预算；否则回退到统一低风险预算。
• 若客户端无法保证重试时继承预算头，则先在网关侧统一注入；否则不要把该客户端接入生产。
• 若路由日志无法解释最终模型和被过滤候选，则暂停灰度，先补齐审计字段。

这份条件列表比单纯比较“便宜模型”和“高质量模型”更重要，因为真正的成本风险通常来自候选池失控、重试绕过和故障回退，而不是某个模型目录中的单价。

长期维护：价格、凭据和模型健康状态都要复核

模型价格、上游可用性、凭据有效期和限流策略都可能变化。历史上最便宜的目标，不一定在下一次价格同步后仍然适合承担 Agent 长任务；曾经稳定的供应，也可能因为认证方式或接口版本变化而进入失败状态。

因此，每次 OmniRoute 版本升级、价格目录同步、凭据轮换或候选模型变更后，都应重新执行：

• 候选凭据验证；
• 基础请求和流式测试；
• 预算过滤测试；
• strict 阻断测试；
• 供应故障和限流回退测试；
• 路由解释与日志字段检查。

OmniRoute 版本发布记录显示，组合、预算、供应商和兼容性功能会持续更新；写作时看到的字段和默认行为不能被当作永久规则，生产配置应锁定实际测试版本，并以对应版本的 Auto Combo 文档、API Reference、代码 Schema 和发布记录复核。

如果当前方案仍然运行在个人电脑上，长期在线会遇到机器休眠、家庭网络入站限制、多人共享密钥难隔离，以及升级和故障恢复依赖某一台设备等问题；如果直接把网关迁移到普通云主机，又要额外处理远程访问、日志持久化和环境权限。对于只需要临时算力、测试环境或远程团队共享入口的场景，租赁 Zilmac 的 Mac 环境通常比维护一台长期在线的本地机器更省心，尤其适合先完成四类路由模拟，再把稳定配置迁移到持续在线的远程 Mac 环境或云端 Mac 租用方案。

更稳妥的路径不是立即放大全团队权限，而是先用一个非生产 Agent 验证预算拦截、路由解释和故障回退；确认规则可审计、可回退后，再决定是否需要 Zilmac 承载持续在线的远程网关环境。

• 对比 Claude、GPT-5 与 Gemini 的 API 调用成本
• 配置 Claude Code 接入 Kimi K3 的方法