Sage Router

核心用法

Sage Router 是一个运行在 :8790 的 HTTP 服务，提供 OpenAI 和 Anthropic 兼容的 API 端点。开发者只需将客户端（Cursor、Aider、Claude Code、Zed、Continue、OpenHands 等）的 API base URL 指向 http://localhost:8790，即可通过单一入口访问多个 AI 提供商。

主要端点：

• POST /v1/chat/completions — OpenAI 兼容，自动路由
• POST /v1/responses — OpenAI Responses API 兼容，支持 Codex 自定义流量
• POST /v1/messages — Anthropic Messages API 兼容，内部转译为 OpenAI 格式
• GET /health — 提供商状态、模型列表、路由调试信息

路由机制

路由器基于意图检测和复杂度估计进行智能决策：

• 从最新用户消息提取关键词判断意图（代码、分析、通用、实时）
• 根据词数估算提示复杂度
• 全局评分所有可达的（提供商, 模型）组合
• 按 API 类型、模型名称、复杂度、实测延迟排序候选
• 顺序尝试最多 SAGE_ROUTER_MAX_PROVIDER_ATTEMPTS 个候选

关键限制：不支持流式切换。一旦请求发送至某提供商，必须返回完整响应或失败后才尝试下一个，不存在部分输出回退。

本地优先模式 (`local-first`)

严格模式：拒绝中心化互联网 API，仅允许本地/LAN/Tailnet 端点及批准的分布式提供商（如 Darkbloom），排除 Ollama :cloud 模型。

路由配置

通过 router-profiles.json 定义命名配置文件，支持多种路由策略：

• route: fast | balanced | best | local-first | realtime
• thinking: low | medium | high
• 能力标志：requiresQuality, requiresReasoning, requiresTools, vision, longContext 等
• 约束：allowProviders, denyProviders, allowModels, denyModels, minParamsB

预设配置：frontier（默认高质量）、frontier-large（仅前沿大模型）、fast-local（低延迟本地优先）、coding-max（高思考代码路由）。

提供商发现

启动时从 OpenClaw 配置自动发现提供商：

• 支持环境变量替换 ${ENV_VAR}
• 自动识别 Google Gemini 端点
• Anthropic 提供商通过本地 Dario 代理（localhost:3456）路由
• 支持通过 SAGE_ROUTER_DISABLED_PROVIDERS 临时抑制故障提供商

---

显著优点

1. 协议统一：同时兼容 OpenAI 和 Anthropic API，消除工具链碎片化
2. 智能路由：基于意图和复杂度动态选择最优模型，非简单轮询
3. 经验学习：持久化存储各提供商/模型的实测延迟，持续优化决策
4. 本地优先架构：支持完全离线运行，保护数据主权
5. 灵活配置：丰富的路由配置文件，满足从实时响应到深度推理的多样需求
6. 容器化就绪：Docker 镜像内置 Node、Python、Dario，支持 llama.cpp 分类器 sidecar
7. 故障隔离：环境变量快速禁用故障提供商，无需重启服务

---

潜在缺点与局限性

1. 无流式故障转移：单请求中途失败需完整重试，无法无缝切换至其他提供商继续生成
2. 关键词意图检测：简单的关键词匹配可能误判复杂语义场景
3. 延迟数据冷启动：新提供商/模型缺乏历史数据时依赖静态启发式
4. Anthropic 依赖 Dario：需额外维护 Dario 代理服务，增加架构复杂度
5. 配置门槛：router-profiles.json 和 OpenClaw 配置需一定学习成本
6. 生态锁定：深度整合 OpenClaw/Dario 生态，与其他配置管理工具集成需适配

---

适合人群

• 严肃 AI Agent 开发者：需要稳定、可预测的多模型后端基础设施
• 数据敏感型用户：本地优先模式满足隐私合规要求
• 多工具用户：同时使用 Cursor、Aider、Claude Code 等工具，希望统一后端配置
• 自托管爱好者：偏好 Docker/Umbrel 部署，追求基础设施可控
• 成本优化用户：通过智能路由自动选择性价比最优的模型/提供商组合

---

常规风险

• 单点故障：Sage Router 本身成为流量枢纽，需监控其健康状态
• 配置泄露：API Key 通过环境变量或配置文件传递，需妥善保管 openclaw.json
• 递归风险：sage-router 作为低优先级回退，配置错误可能导致循环调用
• 供应商依赖：尽管支持本地优先，但前沿模型仍依赖特定提供商（Anthropic/OpenAI）
• 版本漂移：多语言实现（Python + JavaScript）增加维护一致性挑战
• 延迟统计持久化：~/.cache/sage-router/latency-stats.json 可能积累敏感的使用模式数据