Tools
Router
By Local main-model router plugin for OpenClaw
Install
npm install -gConfiguration Example
{
"ok": true,
"provider": "openclaw-router",
"listen": "127.0.0.1:43111"
}README
# OpenClaw Router
本仓库提供一套本地化的 OpenClaw 主模型请求路由插件。它借鉴了 ClawRouter 的核心思路，但不复制其支付链路或外部代理体系，而是直接复用本机 OpenClaw 已配置好的模型、OAuth 凭据和鉴权能力。
目标是把默认主模型从“单模型 + 固定 fallback”升级为“按请求复杂度分类 + 分层候选链 + 自动回退”，同时保持：
- 对 OpenClaw 现有配置尽量透明
- 对已有 OAuth 登录链路零重复配置
- 对后续 OpenClaw 升级尽量低侵入
## 设计概览
插件启动后会完成三件事：
1. 注册一个本地 provider：`openclaw-router`
2. 在本机启动一个 OpenAI-compatible 本地服务，默认监听 `127.0.0.1:43111`
3. 把 OpenClaw 默认主模型切到虚拟模型 `openclaw-router/auto`
实际请求路径如下：
`OpenClaw agent -> openclaw-router/auto -> 本地 /v1/chat/completions -> 请求分类 -> 候选模型链 -> 调用 OpenClaw 内部模型执行器 -> 返回 OpenAI-compatible 响应`
核心模块：
- `index.js`: 插件入口，注册 provider，并在 gateway 模式下拉起本地路由服务
- `lib/runtime-state.js`: 接管 OpenClaw 默认主模型，写入虚拟 provider，并维护路由状态文件
- `lib/router-service.js`: 提供 `/health`、`/v1/models`、`/v1/chat/completions`
- `lib/routing-engine.js`: 对请求进行 `SIMPLE / MEDIUM / COMPLEX / REASONING` 分类
- `lib/model-executor.js`: 复用 OpenClaw 内部模型解析与执行链路
- `lib/openclaw-internals.js`: 兼容 OpenClaw 内部模块变化，动态发现所需内部能力
- `lib/stats-store.js`: 记录路由成功请求，聚合 tier / model / token / 费用统计
## 全局接管范围
当前插件会接管 OpenClaw 的默认文本模型入口，包括：
- `agents.defaults.model`
- `agents.defaults.subagents.model`
- `heartbeat` 这类继承默认 agent 文本模型的系统轮询
- `cron` 中未显式指定模型、且 `sessionTarget` 指向默认 agent 的任务
这意味着常规文本请求、heartbeat、cron、subagent 文本请求都会进入本地代理，再由路由器决定最终上游模型。
当前仍保留一个例外：
- 如果请求显式指定具体模型，例如 `anthropic/claude-sonnet-4-6`，则跳过自动分类与 tier 路由，直接走指定模型
## 认证与安全边界
这个插件不保存厂商 API Key，也不要求为 Claude / Codex / Gemini 单独再配一套秘钥。
它直接复用本机 OpenClaw 已经可用的认证体系，包括：
- OpenClaw 已保存的 OAuth profile
- OpenClaw 内部 model resolver
- OpenClaw 内部 credential/token exchange
仓库内不包含以下内容：
- `~/.openclaw/openclaw.json`
- `~/.openclaw/router/main-router/state.json`
- `~/.openclaw/agents/.../auth-profiles.json`
- Bitwarden 缓存、日志、运行态文件、真实 token
`.gitignore` 已额外排除 `state.json`、日志、临时目录和依赖目录，避免把本机运行态推到仓库。
## 默认路由策略
当前代码默认策略定义在 `lib/constants.js`：
### SIMPLE
- `bailian/qwen3-max-2026-01-23`
- `kimi-coding/k2p5`
- `bailian/qwen3.5-plus`
- `openai-codex/gpt-5.3-codex`
### MEDIUM
- `openai-codex/gpt-5.3-codex`
- `anthropic/claude-sonnet-4-6`
- `github-copilot/claude-sonnet-4.6`
- `google/gemini-3.1-pro-preview`
- `bailian/qwen3.5-plus`
### COMPLEX
- `openai-codex/gpt-5.4`
- `anthropic/claude-opus-4-6`
- `bailian/qwen3.5-plus`
### REASONING
- `openai-codex/gpt-5.4`
- `anthropic/claude-opus-4-6`
- `bailian/qwen3.5-plus`
候选链只在当前 tier 内执行，不会跨 tier 扩散。某个候选在输出前失败时，才会自动尝试下一个候选。
如果请求里显式指定了具体模型，比如 `anthropic/claude-sonnet-4-6`，则跳过自动分类，直接使用该模型。
## 分类规则
分类逻辑位于 `lib/routing-engine.js`，当前启发式如下：
- 默认分档为 `MEDIUM`
- 存在 tools：加权上调
- 上下文更长：加权上调
- 命中代码关键词：上调
- 命中架构、改造、回归等复杂任务关键词：上调
- 命中 `prove`、`derive`、`逐步`、`严谨` 等推理信号：直接推向 `REASONING`
- 命中简答、翻译、摘要等简单任务关键词且无 tools：下调
- 结构化输出、明显多步骤格式：进一步上调
这套规则是无状态、低成本启发式，目标不是绝对精确分类，而是把明显简单和明显复杂的请求尽量分开。
## 运行时文件
插件运行后会在本机写入和维护以下文件：
- `~/.openclaw/router/main-router/state.json`
- `~/.openclaw/router/main-router/stats/requests.jsonl`
- `~/.openclaw/router/main-router/stats/summary.json`
- `~/.openclaw/openclaw.json`
- `~/.openclaw/agents/main/agent/models.json`
其中：
- `state.json` 保存监听地址、tier upstreams、原始 primary/fallback 捕获结果
- `stats/requests.jsonl` 保存成功请求的事件日志
- `stats/summary.json` 保存增量聚合结果
- `openclaw.json` 和 `models.json` 会被补充一个虚拟 provider `openclaw-router`
- OpenClaw 默认主模型和 subagent 默认模型都会被切换到 `openclaw-router/auto`
## 安装
要求：
- OpenClaw `>= 2026.3.7`
- Node.js `>= 22`
- 本机 OpenClaw 已经有可用的模型认证配置，尤其是 OAuth 模型链
### 方式一：通过 npm 直接安装
推荐直接使用官方 npm 包：
```bash
npx local-openclaw-router install
```
也可以先全局安装，再执行安装命令：
```bash
npm install -g local-openclaw-router
local-openclaw-router install
```
这个安装器会自动完成以下动作：
- 复制插件到 `~/.openclaw/local-plugins/openclaw-router`
- 同步到 `~/.openclaw/extensions/openclaw-router`
- 移除旧的 `openclaw-main-router` 扩展副本
- 更新 `~/.openclaw/openclaw.json` 中的 `plugins.allow`、`plugins.entries`、`plugins.installs`
- 运行 `node --test`
- 刷新运行时接管状态
- 尝试重启本地 OpenClaw gateway
如果你只想把 npm 包解出来自己处理，也可以：
```bash
npm pack local-openclaw-router
tar -xzf local-openclaw-router-0.2.1.tgz
```
### 方式二：通过 ClawHub 安装
如果你仍然想通过 ClawHub 安装：
```bash
npx -y clawhub install local-openclaw-router
```
说明：
- GitHub 仓库名是 `openclaw-router`
- ClawHub 上的安装 slug 是 `local-openclaw-router`
- 之所以和仓库名不完全一致，是因为 ClawHub 上已经存在另一个第三方 `openclaw-router` skill slug
### 方式三：直接从 GitHub 仓库安装
也可以直接作为本地插件目录使用：
```bash
mkdir -p ~/.openclaw/local-plugins
git clone [email protected]:xucheng/openclaw-router.git ~/.openclaw/local-plugins/openclaw-router
cd ~/.openclaw/local-plugins/openclaw-router
node --test
```
完成后重启 OpenClaw gateway，使插件重新加载。
### 手动安装后的最低配置要求
如果你是手动复制目录，而不是走 npm 安装器，请至少确认：
- `~/.openclaw/openclaw.json` 里 `plugins.allow` 包含 `openclaw-router`
- `plugins.entries.openclaw-router.enabled = true`
- `plugins.installs.openclaw-router` 指向正确的 `local-plugins` 和 `extensions` 路径
- 已删除或替换旧的 `openclaw-main-router` 安装记录
## 验证
基础验证：
```bash
curl http://127.0.0.1:43111/health
```
应返回类似：
```json
{
"ok": true,
"provider": "openclaw-router",
"listen": "127.0.0.1:43111"
}
```
也可以直接做一次 agent smoke test：
```bash
openclaw agent --message "Reply with exactly: ok" --json
```
如果默认模型已接管成功，返回元数据中的 provider 会是 `openclaw-router`。
如果要查看调用统计：
```bash
~/.openclaw/scripts/openclaw-router-stats.sh
```
脚本会输出：
- 各 tier 的请求数、token 总量、费用估算
- 各 model 的请求数、输入输出 token、总 token、费用估算
- 总请求数、attempts、streamed requests、最后一次请求时间
脚本默认优先从 `requests.jsonl` 重算，避免旧 summary 缓存影响统计结果。传 `--json` 可输出 JSON，传 `--cached` 可直接读取 `summary.json`。
## 命令控制
插件现在同时支持：
- OpenClaw CLI：`openclaw router ...`
- 聊天通道 slash/text 命令：`/router ...`
两者共享同一套后台逻辑，修改会直接写入 `state.json`，并在 gateway 进程内立即更新当前 tier 链顺序。
支持的命令：
```bash
openclaw router show [tier]
openclaw router set <tier> <model1> <model2> ...
openclaw router move <tier> <model> <position>
openclaw router add <tier> <model> [position]
openclaw router remove <tier> <model>
openclaw router reset [tier]
openclaw router stats [--json] [--cached]
```
聊天里对应写法：
```text
/router show medium
/router move medium google/gemini-3.1-pro-preview 2
/router stats
```
## 费用估算
统计服务优先使用 OpenClaw 返回的 usage/cost 数据；如果上游模型未返回成本信息，则按已内置的价格兜底规则估算。
当前已内置兜底的主路由模型包括：
- `openai-codex/gpt-5.4`
- `openai-codex/gpt-5.3-codex`
- `anthropic/claude-sonnet-4-6`
- `anthropic/claude-opus-4-6`
其中 `openai-codex/gpt-5.4` 的费用是基于 `GPT-5.4` 官方定价做的推断。像 `github-copilot` 这类订阅制或没有公开 token 价的 provider，费用可能仍为 `0`，但 token 统计仍然有效。
## 测试
仓库内包含基础回归测试：
```bash
node --test
```
覆盖范围包括：
- 请求分类
- tier 候选链构建
- fallback 行为
- OpenAI-compatible 输出
- 运行时接管逻辑幂等性
- 成功请求统计与聚合
## 为什么采用这种方案
相对于直接改 OpenClaw 核心代码，这种方案的优点是：
- 升级面更小，插件可独立迭代
- 不需要为不同 provider 维护多套外部代理
- 对已有模型配置透明，尤其适合继续沿用本机 OAuth 登录态
- 路由策略可以独立演进，不绑死在主程序里
相对于把所有流量都发给单一主模型，这种方案的优点是：
- 简单任务可以优先落到更便宜或更高吞吐的模型
- 中复杂任务可以稳定优先走 Codex / Claude
- 某个 provider 抖动时可以在本地快速回退
## 变更边界
当前仓库只包含插件代码和测试，不包含以下环境修复脚本：
- Bitwarden resolver 缓存兜底脚本
- 本机 LaunchAgent / gateway service 修复
- 私有运行态配置与本机 secrets
这些内容属于主机环境治理，不应与插件仓库混在一起。
tools
Comments
Sign in to leave a comment