# https://github.com/BlockRunAI/ClawRouter 项目说明书

生成时间：2026-07-21 16:08:35 UTC

## 目录

- [项目概览、安装与免费层](#page-1)
- [智能路由架构：15 维评分与本地代理](#page-2)
- [x402 支付、钱包与身份验证系统](#page-3)
- [模型目录与高级集成（图像/视频/电话/Polymarket/Surf）](#page-4)

<a id='page-1'></a>

## 项目概览、安装与免费层

### 相关页面

相关主题：[智能路由架构：15 维评分与本地代理](#page-2), [x402 支付、钱包与身份验证系统](#page-3), [模型目录与高级集成（图像/视频/电话/Polymarket/Surf）](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/BlockRunAI/ClawRouter/blob/main/README.md)
- [package.json](https://github.com/BlockRunAI/ClawRouter/blob/main/package.json)
- [openclaw.plugin.json](https://github.com/BlockRunAI/ClawRouter/blob/main/openclaw.plugin.json)
- [docs/configuration.md](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/configuration.md)
- [docs/features.md](https://github.com/BlockRunAI/ClawRouter/blob/main/docs/features.md)
- [src/top-models.json](https://github.com/BlockRunAI/ClawRouter/blob/main/src/top-models.json)
- [CHANGELOG.md](https://github.com/BlockRunAI/ClawRouter/blob/main/CHANGELOG.md)
</details>

# 项目概览、安装与免费层

## 项目定位与作用

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

```mermaid
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_PORT` | 本地监听端口（默认 8417） |
| `BLOCKRUN_BASE_URL` | 上游 `https://api.blockrun.ai` |
| `CLAWROUTER_MODEL` | 默认回退模型，例如 `blockrun/auto` |
| `x402` 段 | 控制出站钱包、链（Solana/Base）与 builder-code |

启动命令 `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](https://github.com/BlockRunAI/ClawRouter/issues/23)、[#83](https://github.com/BlockRunAI/ClawRouter/issues/83)、[#2](https://github.com/BlockRunAI/ClawRouter/issues/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/` 实现，本版本不内置。

---

<a id='page-2'></a>

## 智能路由架构：15 维评分与本地代理

### 相关页面

相关主题：[项目概览、安装与免费层](#page-1), [x402 支付、钱包与身份验证系统](#page-3), [模型目录与高级集成（图像/视频/电话/Polymarket/Surf）](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/proxy.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/proxy.ts)
- [src/router/index.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/index.ts)
- [src/router/selector.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/selector.ts)
- [src/router/strategy.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/strategy.ts)
- [src/router/rules.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/rules.ts)
- [src/router/types.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/types.ts)
</details>

# 智能路由架构：15 维评分与本地代理

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

## 路由管线总览

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

```mermaid
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](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/index.ts)、[src/router/types.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/types.ts)

## 15 维评分系统

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

| 维度类别 | 代表性指标 | 作用 |
|---------|-----------|------|
| 能力类 | 编码、推理、长上下文、工具调用 | 评估模型能否胜任当前任务 |
| 成本类 | 输入价、输出价、单次最小结算 | 在 x402 微支付场景下保证可控 |
| 延迟类 | 首发 token 时延、吞吐、可用区 | 影响交互体验 |
| 健壮性 | 失败率、限流阈值、降级路径 | 触发兜底策略的依据 |

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

这种细粒度评分直接回应了社区 #83 的诉求：用户希望 ClawRouter 能"先用完现有余额，再走 Solana 微支付"。评分器把"成本"维度独立成多项后，未来扩展"先用外部账户、再走 x402"的兜底链只需新增一个打分维度即可，无需重写选择逻辑。资料来源：[issues/83](https://github.com/BlockRunAI/ClawRouter/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](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/strategy.ts)、[src/router/rules.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/router/rules.ts)、[issues/23](https://github.com/BlockRunAI/ClawRouter/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](https://github.com/BlockRunAI/ClawRouter/blob/main/src/proxy.ts)、[releases/v0.12.218](https://github.com/BlockRunAI/ClawRouter/releases/tag/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](https://github.com/BlockRunAI/ClawRouter/issues/2)、[issues/14](https://github.com/BlockRunAI/ClawRouter/issues/14)、[issues/29](https://github.com/BlockRunAI/ClawRouter/issues/29)

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

---

<a id='page-3'></a>

## x402 支付、钱包与身份验证系统

### 相关页面

相关主题：[项目概览、安装与免费层](#page-1), [智能路由架构：15 维评分与本地代理](#page-2), [模型目录与高级集成（图像/视频/电话/Polymarket/Surf）](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/auth.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/auth.ts)
- [src/wallet.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/wallet.ts)
- [src/balance.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/balance.ts)
- [src/solana-balance.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/solana-balance.ts)
- [src/payment-preauth.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/payment-preauth.ts)
- [src/builder-code.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/builder-code.ts)
</details>

# x402 支付、钱包与身份验证系统

## 系统概述与角色

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 差异。

| 模块 | 主要职责 | 关联链 / 协议 |
|------|----------|---------------|
| `src/wallet.ts` | 加载、解析、缓存 `BLOCKRUN_WALLET` / `BLOCKRUN_PRIVATE_KEY` 等本地钱包环境变量,统一处理 EVM 与 Solana 地址格式 资料来源：[src/wallet.ts:10-80]() | EVM / Solana 双栈 |
| `src/balance.ts` | 聚合 Base 链 x402 通道的本地 ETH / USDC 余额,在内存中缓存上一次 on-chain 查询结果 资料来源：[src/balance.ts:20-95]() | Base (x402) |
| `src/solana-balance.ts` | 读取 SOL 与 SPL 代币余额,并在余额不足时计算滑点友好的最低补仓额 资料来源：[src/solana-balance.ts:15-75]() | Solana |

三个模块通过 `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](https://github.com/BlockRunAI/ClawRouter/issues/14)、[#83](https://github.com/BlockRunAI/ClawRouter/issues/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]()。

```mermaid
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 级别的可验证结算。

---

<a id='page-4'></a>

## 模型目录与高级集成（图像/视频/电话/Polymarket/Surf）

### 相关页面

相关主题：[项目概览、安装与免费层](#page-1), [智能路由架构：15 维评分与本地代理](#page-2), [x402 支付、钱包与身份验证系统](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [src/models.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/models.ts)
- [src/top-models.json](https://github.com/BlockRunAI/ClawRouter/blob/main/src/top-models.json)
- [src/textual-tool-calls.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/textual-tool-calls.ts)
- [src/web-search-provider.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/web-search-provider.ts)
- [src/partners/index.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/partners/index.ts)
- [src/partners/registry.ts](https://github.com/BlockRunAI/ClawRouter/blob/main/src/partners/registry.ts)
</details>

# 模型目录与高级集成（图像/视频/电话/Polymarket/Surf）

## 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 节）扩展。

### 目录对齐数据流

```mermaid
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`。

| 模型族 | 触发症状 | 触发版本 |
| --- | --- | --- |
| GPT-5.4 | 纯 JSON / 函数调用风格文本 | v0.12.215 (#193) |
| Gemini 3.5 Flash | `[Called function "…" with args: {…}]` 转录 | v0.12.214 (#189) |

该模块按"症状→正则/解析器→标准化 `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，但属于该层可扩展的设计目标。

### 合作伙伴解析流程

```mermaid
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]()

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：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

<!-- canonical_name: BlockRunAI/ClawRouter; human_manual_source: deepwiki_human_wiki -->