内容
# claw-tsaver
> 为 OpenClaw 用户设计的节省令牌的 MCP 代理，通过延迟扩展将工具调用的负载减少 90%+。
## 为什么
MCP 工具调用通常在一次响应中返回数千个令牌的 HTML 或 JSON，但模型通常只使用其中大约 5% 的内容。剩余的 95% 静默地消耗上下文窗口并增加成本。claw-tsaver 位于 OpenClaw 和下游 MCP 服务器之间，拦截超大响应，并为模型提供紧凑的预览 + 按需句柄，而不是直接传递大响应。
## 如何工作
```mermaid
sequenceDiagram
participant U as OpenClaw (Claude)
participant C as claw-tsaver 代理
participant F as fetch / puppeteer / 等
U->>C: 调用工具("fetch", url)
C->>F: 转发调用
F-->>C: 11,507 个令牌的 HTML
Note over C: token 计数 > 阈值
C->>C: 将完整内容存储在 SQLite 中
C-->>U: {预览头部, 预览尾部, 扩展句柄}<br/>(仅 104 个令牌)
Note over U: 模型决定是否需要全文
U->>C: 扩展内容(句柄)
C-->>U: 完整的 11,507 个令牌
```
## 实际测量
| 测试 | 原始令牌数 | 返回令牌数 | 节省 |
|---|---|---|---|
| 获取维基百科 "Tokenization (data security)" | 11,507 | 104 | **99.1%** |
在 OpenClaw + Claude Sonnet 4.6 + mcp-server-fetch 上测试，2026-04-25。
原始数据：`benchmarks/mvp-day1-fetch.jsonl`。
## 快速开始
### 1. 前置条件
安装 [uv](https://docs.astral.sh/uv/)（一次性设置）：
```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```
不需要单独安装 claw-tsaver - `uvx` 将按需获取并运行它。
### 2. 配置下游 MCP 服务器
编辑 `~/.claw-tsaver/config.json`（`claw-tsaver-mcp` 的首次运行将自动创建一个模板）：
```json
{
"downstream_servers": [
{"name": "fetch", "command": "uvx", "args": ["mcp-server-fetch"]}
],
"compression_threshold_tokens": 500
}
```
### 3. 在 OpenClaw 中注册
在 `~/.openclaw/openclaw.json` 的顶层添加以下内容：
```json
"mcp": {
"servers": {
"claw-tsaver": {
"command": "uvx",
"args": ["--from", "git+https://github.com/Yang1Bai/claw-tsaver",
"claw-tsaver-mcp"]
}
}
}
```
然后重启 OpenClaw 网关：`openclaw gateway restart`
## 仪表盘
可选：用于实时令牌节省统计的本地 Web UI。
```bash
uvx --from git+https://github.com/Yang1Bai/claw-tsaver claw-tsaver-dashboard
```
在浏览器中打开 <http://localhost:7878>。
## 路线图
- [x] **模块 A**：延迟扩展代理（此版本）
- [x] **模块 D**：本地仪表盘（此版本）
- [ ] **模块 B**：工具路由（按回合自动加载相关 MCP）
- [ ] **模块 C**：对话历史压缩（原子事实卡）
## 许可证
MIT — 请参阅 LICENSE 文件。
## 贡献
欢迎提出问题和 PR。
---
## 🇨🇳 中文说明
### 什么是 claw-tsaver？
**claw-tsaver** 是一个为 OpenClaw 用户设计的 MCP 代理，通过懒加载扩展机制将工具调用的令牌消耗削减 **90%+**。
### 问题背景
MCP 工具调用（如 fetch、puppeteer）经常在单次响应中返回数千个令牌的 HTML 或 JSON，但模型通常只使用其中约 5% 的内容。剩余 95% 悄悄消耗上下文窗口并增加费用。
### 解决方案
claw-tsaver 作为 OpenClaw 与下游 MCP 服务器之间的代理：
1. 拦截过大的响应（超过可配置的令牌阈值）
2. 将完整内容存储到本地 SQLite 数据库
3. 返回给模型一个**紧凑预览 + 按需扩展句柄**
4. 模型需要更多内容时，调用 `expand_content` 工具按需获取
