项目定位与作用

ClawRouter 是 BlockRunAI 推出的智能模型路由代理（Model Router），运行在本地与 OpenClaw / Hermes 等客户端之间，对外暴露兼容 OpenAI /v1/chat/completions 的接口。客户端只需把 base_url 指向 ClawRouter，它就会按照用户请求的模型名、Token 上限与策略，转发到 BlockRun 上游目录中对应的模型，并在出站阶段按实际用量完成 x402 链上结算。

flowchart LR
    A[客户端<br/>OpenAI/Hermes] -->|HTTP /v1/chat/completions| B[ClawRouter 本地代理]
    B -->|model + max_tokens| C{路由策略}
    C -->|cheap tier| D[blockrun 模型目录]
    C -->|pro tier| D
    D -->|x402 402 Payment Required| B
    B -->|链上签名结算| E[Solana / Base]
    E -->|已支付| B
    B --> A

资料来源：README.md:1-30、openclaw.plugin.json:1-20

安装与发布形态

仓库以标准 npm 包形式发布，package.json 中声明了 bin、main、types 与 files 字段，安装后即可作为本地 CLI 或插件宿主运行：

• 名称：clawrouter，版本与最新 Release v0.12.232 保持一致
• 可执行入口：bin/clawrouter.js，提供 clawrouter 子命令
• 资源：仅打包 dist/ 与必要的 schema，避免将 node_modules 一同分发

安装完成后，ClawRouter 同时承担 OpenClaw 插件的角色（openclaw.plugin.json 声明），被宿主加载后接管模型解析、付款回执和路由策略。

资料来源：package.json:1-40、openclaw.plugin.json:1-25

配置与本地启动

docs/configuration.md 描述了最小化配置集合，主要包含：

启动命令 clawrouter start 会先加载 src/top-models.json 作为 /model 选择器的数据源，再读取上述环境变量，最后注册 chat/completions、models、/model 三个 HTTP 端点。

资料来源：docs/configuration.md:1-60、src/top-models.json:1-30

免费层与配额机制

社区讨论中频繁出现的「ClawRouter 一直在扣费」「能不能用本地模型先跑」等问题，根源在于 ClawRouter 自身并不分发免费配额：

• 真实计费发生在上游：BlockRun 目录按 token 计费，ClawRouter 仅代为签名 x402 支付并把 payment-required 头回传给客户端。docs/features.md 明确说明，免费模型仅指 BlockRun 上游目录中 price = 0 的若干条目（如 blockrun/free-*），并非 ClawRouter 路由器本身的额度。
• Token 计费的字段修复：最新 v0.12.232 修复了 max_completion_tokens 字段未被识别的问题——此前客户端用新字段时，整次请求会被当作「没设上限」，导致上游按最大上下文计费。这是社区报告的「credits 持续消耗」类问题（如 #23）的重要成因。
• 二级模型兜底：issue #83 讨论过的「先用完 OpenAI 余额再走 Solana 结算」属于客户端策略，不在 ClawRouter 路由层。社区期待后续在 src/router/ 下引入 BYOK 链路。
• 本地推理：issue #2 提出的 Ollama 支持尚未合入主线；目前 ClawRouter 仍以 BlockRun 上游为唯一出口。

资料来源：docs/features.md:1-50、CHANGELOG.md:1-20、#23、#83、#2

升级与安全基线

部署 ClawRouter 时建议同时确认：

• 锁版本到 v0.12.232 或更新，以便获得 max_completion_tokens 修复；
• npm audit 应为 0 漏洞（自 v0.12.216 起清理了 22 个 Dependabot 告警）；
• ERC-8021 builder-code 默认开启，便于在 x402 链上追溯每一笔请求。

资料来源：CHANGELOG.md:1-30

相关社区问题

• #23 主模型仍走付费通道：通常因为客户端 max_completion_tokens 未生效，请求被上游放大计费。
• #83 二级模型兜底：建议先在客户端侧用环境变量 BLOCKRUN_FALLBACK_OPENAI_KEY 做 BYOK 切换。
• #2 Ollama / 本地推理：目前需自行 fork src/router/ 实现，本版本不内置。

ClawRouter 的核心价值在于把"调用任意 LLM"这件事封装成一个 OpenAI 兼容的本地代理端口：客户端无感、模型选择有据、付款走 x402。整个智能路由层由 src/router/ 子树驱动，HTTP 边界由 src/proxy.ts 承担，客户端只需把 base_url 指向本地端口即可享受自动选模、按需结算的能力。本页聚焦于两个核心机制：15 维评分系统与本地代理架构。

路由管线总览

本地代理接收到 OpenAI 格式的请求后，会沿着一条固定的管线进行处理：解析请求体 → 提取意图与约束（任务类型、最大 token、价格上限等） → 调用评分器对候选模型打分 → 选出最优模型 → 注入计费上下文 → 通过 x402 微支付通道转发到上游 provider。

flowchart LR
    A[Client / OpenAI SDK] --> B[src/proxy.ts<br/>本地代理入口]
    B --> C[src/router/index.ts<br/>路由协调器]
    C --> D[src/router/selector.ts<br/>15 维评分器]
    D --> E[src/router/strategy.ts<br/>策略与兜底]
    E --> F[src/router/rules.ts<br/>规则匹配]
    F --> G[upstream provider<br/>OpenAI / Anthropic / Gemini]
    G --> H[x402 结算<br/>Solana / Base]
    H --> A

src/router/index.ts 是路由协调器，它把"打分—选模—结算"三件事拆成可插拔的步骤；src/router/types.ts 定义了请求特征、候选模型、评分项等共享类型。资料来源：src/router/index.ts、src/router/types.ts

15 维评分系统

评分器位于 src/router/selector.ts，它对每一个候选模型计算一个加权总分。15 个维度大致分为四类：

打分时，先按用户传来的 max_tokens / max_completion_tokens（v0.12.232 已修复现代字段读取）估出请求规模，再按任务特征（从 system prompt 与工具描述推断）施加权重。资料来源：src/router/selector.ts、src/router/types.ts

这种细粒度评分直接回应了社区 #83 的诉求：用户希望 ClawRouter 能"先用完现有余额，再走 Solana 微支付"。评分器把"成本"维度独立成多项后，未来扩展"先用外部账户、再走 x402"的兜底链只需新增一个打分维度即可，无需重写选择逻辑。资料来源：issues/83

策略、规则与兜底

评分结果只是推荐，最终路由由 src/router/strategy.ts 与 src/router/rules.ts 协同决定。规则层负责硬性约束：例如 top-models.json 中标记的模型必须出现在候选集、特定 alias（如 gpt-5.6 通用别名）必须落到稳定档位（v0.12.219 已把通用 alias 路由到 Terra 而非 Sol）。策略层负责软性兜底：评分最高的模型不可用时，按"次优 + 同 provider"顺序回退。

社区里讨论最多的兜底场景是 #23：用户在 Codex CLI 中将主模型设为 Codex，但 ClawRouter 仍在消耗积分。该问题的根源不在评分器，而在策略层未把"用户已显式指定模型"作为最高优先级规则——这是路由架构里"硬约束"与"软推荐"边界的一个典型权衡。资料来源：src/router/strategy.ts、src/router/rules.ts、issues/23

本地代理边界

src/proxy.ts 是对外唯一暴露的 HTTP 入口，它完成三件事：把任意 OpenAI 兼容请求归一化为内部表示；把上游响应（包含 GPT-5.4 / Gemini 3.5 Flash 的 plain-text 工具调用文本，见 v0.12.214、v0.12.215）恢复为标准 tool_calls 结构；以及按 ERC-8021 builder-code 把 x402 付款归属到 ClawRouter 服务（v0.12.218）。这套归一化让上层评分器和策略层永远面对"干净的"OpenAI 格式，下游 provider 的怪癖被本地代理屏蔽掉。资料来源：src/proxy.ts、releases/v0.12.218

需要说明的是，社区 #2 提出的 Ollama 支持、#14 提出的 Claude CLI Pro/Max 订阅、#29 提出的 OpenRouter / BYOK，都属于"扩展候选 provider 池"的需求。在当前架构下，新增一种 provider 只需在 src/router/types.ts 中扩展候选类型、在 src/proxy.ts 中加入对应的响应归一化分支，15 维评分器与策略层无需改动——这正是把"打分"与"执行"解耦带来的可扩展性。资料来源：issues/2、issues/14、issues/29

总结：15 维评分让选模有据可循，本地代理把 OpenAI 协议与 x402 结算粘合成一个无感的产品体验；二者通过 src/router/ 解耦，使得新模型、新 provider、新兜底策略都可以独立演进。

系统概述与角色

ClawRouter 是一个面向多模型 LLM 路由的网关,其核心商业创新是用 x402 微支付协议 取代按月订阅,让用户按请求级别通过链上结算向 BlockRun 上游付费。整个 x402 支付、钱包与身份验证系统 由六个高度内聚的模块组成,分别在 src/auth.ts、src/wallet.ts、src/balance.ts、src/solana-balance.ts、src/payment-preauth.ts、src/builder-code.ts 中实现。该系统需要同时承担三件事:(1) 在不要求用户注册账号的前提下,对每个请求的身份进行无密码验证;(2) 让本地钱包 / 远程钱包与多链余额(Solana、Base)统一对账;(3) 在请求进入上游 LLM 之前完成 x402 付款要求的缓存与签名,并把 ERC-8021 构建者代码注入到链上结算数据中,从而确保后续费用归属与退款追踪的可持续性 资料来源：src/auth.ts:1-40 资料来源：src/wallet.ts:1-30。

钱包与余额管理

钱包与余额模块负责把链上账户状态抽象成 ClawRouter 可读的"信用额度"对象,屏蔽不同链之间的 RPC 差异。

三个模块通过 Wallet 单例与 BalanceProvider 接口解耦,使得上游 LLM 调用者只需要关注"我现在能花多少",而无需关心读哪条链 资料来源：src/balance.ts:5-18。当余额低于下游模型单次调用报价时,系统会以 402 Payment Required 形式把签好名的支付需求返回给客户端,从而触发客户端的钱包自动重发请求 资料来源：src/wallet.ts:120-150。

身份验证与会话

src/auth.ts 实现的是 无密码、基于钱包签名挑战 的轻量身份层:每个新会话开始时网关随机生成一段 nonce,客户端用与钱包绑定的私钥对 nonce 做 personal_sign,网关用同一地址的公钥反算即可得到稳定、无需数据库的用户身份 (walletAddress)。这一身份随后被作为路由键复用到:

• 计费归属:x402 支付需求中的 payer 字段直接使用该地址,保证费用归属与签名身份一致 资料来源：src/auth.ts:60-110。
• 配额与速率限制:每个 (walletAddress, model) 对都维护一份本地滑动窗口,避免单一钱包刷爆上游 资料来源：src/auth.ts:130-160。
• 跨进程去重:同一钱包的并发请求会被去重 token 合并,减少对上游 LLM 的无效重试。

社区用户曾报告 Claude CLI 之类的 Pro/Max 订阅能否作为 fallback 与 x402 钱包共存 (#14、#83),目前 auth.ts 仅识别钱包签名,不接受外部 OAuth token,因此这类 fallback 需要在调用方侧而不是网关内部实现 资料来源：src/auth.ts:40-58。

支付预授权与构建者代码

src/payment-preauth.ts 与 src/builder-code.ts 是把 "402 Challenge → 重新签名 → 上游调用" 这条链串起来的关键胶水层。

payment-preauth.ts 维护一个 LRU 预授权缓存,在每个新请求进来时:

1. 用请求体里的 model + 历史 token 估算费用;
2. 命中缓存且未过期 → 直接放行;
3. 未命中或费用增量超过缓存值 → 重新向 BlockRun /v1/payment 拉取新的付款要求并签名。

v0.12.213 修复的 "小请求种子化大请求导致 500 underpay" 缺陷即在此处——之前的实现把第一次签名的额度写死缓存,从而对后续更大的请求形成 stale underpay。现在缓存键同时包含 model + estimatedCost,确保每次报价变化都会重新签发 资料来源：src/payment-preauth.ts:30-120。

builder-code.ts 实现 ERC-8021 构建者代码归属:在每次 x402 支付的 extra 字段中追加 ClawRouter 的服务标识(clawrouter:clawrouter@v0),从而让上游结算可以把返佣 / 回扣准确归属到 ClawRouter 而不是某个匿名钱包。v0.12.218 加入的 "保留已有 codes" 修复,使得当用户已经在 Authorization 头中注入自有构建者代码时不会被网关覆盖 资料来源：src/builder-code.ts:20-90。

sequenceDiagram
    participant C as Client (钱包)
    participant A as auth.ts
    participant B as balance.ts
    participant P as payment-preauth.ts
    participant U as 上游 LLM

    C->>A: personal_sign(nonce)
    A-->>C: sessionId(walletAddress)
    C->>B: 查价 model=claude-sonnet-5
    B-->>P: estimatedCost
    P->>P: 命中 LRU 预授权?
    alt miss / 金额变化
        P->>P: 重新签 402 + ERC-8021 builder code
    end
    P->>U: 携带 x402-payment 头放行
    U-->>C: 流式响应

整体来看,这六个文件构成 ClawRouter 的"计费基座":auth.ts 决定 *谁*,wallet.ts / balance.ts / solana-balance.ts 决定 *有多少*,payment-preauth.ts / builder-code.ts 决定 *怎么扣*。三者环环相扣,使得按次付费的 LLM 路由在保留 Web2 调用手感的同时,获得了 Web3 级别的可验证结算。

1. 模型目录与目录对齐

src/models.ts 是 BlockRun/ClawRouter 模型注册表的单一事实来源（source of truth），用于描述每个模型的层级、价格（输入/输出每百万 token 美元计费）、能力标签以及在 picker 中的呈现顺序。新增模型（例如 v0.12.217 引入的 anthropic/claude-sonnet-5、v0.12.219 引入的 GPT-5.6 Sol/Terra/Luna）都会先写入该注册表，再被路由器和上游代理消费。 资料来源：src/models.ts:1-120

src/top-models.json 是面向终端用户的"顶层"目录切片，由 src/models.ts 在构建时投影而成，决定 /model picker 的默认顺序与展示条目数。v0.12.227 显式把它与 blockrun.ai 的 /v1/models 列表对齐（条目数从 47 收敛到当前数量），并修复了 picker 不遵循 top-models.json 顺序的回归（#201）。 资料来源：src/top-models.json:1-80

社区关注：用户在 Issue #29 中要求 OpenRouter 支持以满足合规/可及性需求；在 Issue #2 中请求 Ollama 支持。这两类外部目录目前都不在 src/models.ts 的注册范围内，需通过 partner 适配层（见第 4 节）扩展。

目录对齐数据流

flowchart LR
  A[blockrun/src/lib/models.ts<br/>source of truth] --> B[ClawRouter src/models.ts]
  B --> C[src/top-models.json<br/>构建时投影]
  C --> D["/model picker UI"]
  B --> E[路由/计费引擎]

2. 文本式工具调用的恢复

部分模型在结构化 tool_calls 通道之外，会把工具调用写成"看起来像文本"的内容。src/textual-tool-calls.ts 负责把这些转写恢复成真正的 tool_calls。

该模块按"症状→正则/解析器→标准化 tool_calls"的流程工作，确保下游 Agent 框架（不论 Claude Code、Codex 还是 Hermes 插件）看到的是一致的 tool_calls 结构，而不必为每个模型族在客户端做特判。 资料来源：src/textual-tool-calls.ts:1-200

3. Web 搜索与 Surf 集成

src/web-search-provider.ts 提供统一的网络检索能力，供上层模型在需要新鲜信息时调用。它抽象了"谁提供检索"这一细节，使路由器能够在不同检索后端之间切换而不影响调用方契约。Surf 是面向终端用户的产品化包装，底层复用该 provider 的接口，并把搜索结果再喂回 src/models.ts 注册的对话模型。 资料来源：src/web-search-provider.ts:1-160

4. 合作伙伴层：电话、Polymarket 与更多

src/partners/registry.ts 是合作伙伴能力的注册中心；src/partners/index.ts 负责按能力名称解析、实例化并暴露统一接口。每个能力（如 blockrun_polymarket）都是一个独立的 partner 适配器，遵循"读（quote/odds）→ 写（place/redeem）→ 结算（on-chain）"的同构模板。

当前已落地的能力

• blockrun_polymarket（v0.12.220 起）：在 Polygon 上对接 Polymarket CLOB V2，直接以真金白银下单、管理与赎回预测市场头寸；调用方使用 Solana x402 通道签名支付，沿用与 LLM 调用一致的结算路径。
• 图像/视频生成：作为 partner 能力挂接，调用方通过模型目录里的别名（如 openai/sora-2、black-forest-labs/flux-2-pro）路由，由 partner 适配器翻译为对应上游服务的请求体。
• 电话（voice/phone）能力：通过 partner 注册暴露语音通话/电话通道，由路由器作为特殊能力类型路由。

社区关注：Issue #83 询问是否可以把"现有的 OpenAI 余额"作为 ClawRouter 的优先支付源，耗尽后再回退到 Solana 微支付；当前 src/partners/registry.ts 尚未提供"第三方账户额度 → x402 链上支付"的级联 fallback，但属于该层可扩展的设计目标。

合作伙伴解析流程

flowchart TD
  C[客户端调用] --> R[路由器]
  R --> M{模型目录命中?}
  M -- 是 --> L[LLM 上游]
  M -- 否 --> P[src/partners/registry.ts]
  P --> P1[blockrun_polymarket]
  P --> P2[图像/视频]
  P --> P3[电话能力]
  P --> P4[Surf / Web 搜索]

5. 配置与故障排查要点

• 目录与 picker 不同步：核对 src/top-models.json 与 src/models.ts 的条目数与顺序；v0.12.227 已修复 picker 不遵守 top-models.json 顺序的回归。
• 新模型被路由到错误别名：v0.12.219 起，通用别名（如无明确层级指代）默认路由到 Terra（稳定层），不再使用 Sol（实验层）。
• 工具调用丢失：若客户端仅消费结构化 tool_calls，而模型返回纯文本，请确认 src/textual-tool-calls.ts 中对应症状族（GPT-5.4 / Gemini 3.5 Flash）的恢复器已启用。
• 预授权 500：v0.12.213 (#188) 修复了在按请求定价下，因小请求先于大请求写入预授权缓存导致的 Failed to parse payment requirements；若仍出现，请清空 pre-auth 缓存后再观测。

资料来源：src/partners/index.ts:1-120 · src/partners/registry.ts:1-200

Pitfall Log / 踩坑日志

项目：BlockRunAI/ClawRouter

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 来源证据：ClawRouter continues consuming credits despite primary model set to Codex。

1. 配置坑 · 来源证据：ClawRouter continues consuming credits despite primary model set to Codex

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：ClawRouter continues consuming credits despite primary model set to Codex
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 证据：community_evidence:github | https://github.com/BlockRunAI/ClawRouter/issues/23 | 来源类型 github_issue 暴露的待验证使用条件。

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/BlockRunAI/ClawRouter | README/documentation is current enough for a first validation pass.

3. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/BlockRunAI/ClawRouter | no_demo; severity=medium

5. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/BlockRunAI/ClawRouter | no_demo; severity=medium

6. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter | issue_or_pr_quality=unknown

7. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/BlockRunAI/ClawRouter | release_recency=unknown