OpenClaw 智能路由系统

English Documentation | 中文文档

⚠️ 注意：本项目仅用于个人体验交流学习 原项目地址：openclaw/openclaw

---

🤖 什么是智能路由？

OpenClaw 智能路由系统是一个基于语义相似度的AI模型自动选择引擎，能够：

• 🎯 自动分类查询：根据语义自动识别查询类型（代码、闲聊、推理、写作等）
• 💰 成本优化：简单查询用轻量模型，复杂查询用旗舰模型，节省60-80%成本
• 📚 持续学习：根据用户使用习惯自动优化路由决策
• ⚡ 实时响应：基于向量相似度的毫秒级路由决策

核心价值

传统方式：所有查询 → 旗舰模型 → 高成本 💸
智能路由：
  ├─ 简单查询（60%） → 轻量模型 → 省钱 ✅
  ├─ 代码查询（20%） → 旗舰模型 → 质量 ✅
  ├─ 推理查询（15%） → 旗舰模型 → 质量 ✅
  └─ 其他查询（5%） → 轻量模型 → 省钱 ✅

---

🚀 快速开始

第一步：安装和启用

# 1. Clone 项目
git clone https://github.com/serenez/openclaw.git
cd openclaw

# 2. 安装依赖
pnpm install
pnpm build

# 3. 安装到系统
pnpm link

# 4. ⚠️ 重要：必须启用智能路由（复制种子文件到用户目录）
openclaw smart-router enable

为什么必须执行 openclaw smart-router enable？

• 启用命令会自动复制种子文件到 ~/.openclaw/smart-router/
• 如果不启用，需要手动复制（不推荐）
• 种子文件包括：DNA意图分类 + 默认用户学习数据

第二步：配置模型（必须！）

⚠️ 重要：检查并修改路由配置！

# 查看当前配置
openclaw config get

# 编辑配置文件
~/.openclaw/config.json

必须确认的配置项：

{
  "smartRouting": {
    "enabled": true,
    "lightweightModels": ["你的轻量模型"],
    "flagshipModels": ["你的旗舰模型"],
    "embedding": {
      "model": "Qwen/Qwen3-Embedding-0.6B",
      "apiKey": "你的千问API密钥"
    }
  }
}

⚠️ 关键警告：模型一致性！

生成种子数据的模型  必须等于  运行时使用的模型
│                              │
│     Qwen/Qwen3-Embedding-0.6B    │
└────────────────────────────────┘

• 项目默认使用 千问 Qwen3-Embedding-0.6B 模型
• 如果使用项目自带的数据 → 必须配置千问模型
• 如果使用自己的数据 → 必须用千问模型重新生成

第三步：验证配置

# 发送一个测试查询
echo "测试智能路由"

# 查看路由日志（应该看到路由决策）
# 日志位置：根据你的系统配置

---

📚 自定义种子数据

DNA 分类说明

系统包含 6 个预定义语义类别：

类别	说明	优先级	示例查询
CHAT	日常闲聊	轻量	"你好", "天气怎么样"
CODE	代码相关	旗舰	"写个函数", "帮我debug"
FACT	事实查询	轻量	"1+1等于几", "首都在哪"
REASON	推理分析	旗舰	"分析问题", "比较方案"
TRANS	翻译转换	轻量	"翻译", "总结"
WRITE	写作生成	轻量	"写首诗", "写文章"

JSON数据格式

[
  {
    "text": "你的查询文本",
    "label": "类别名称"
  }
]

示例数据

[
  {"text": "帮我写一个Python函数", "label": "CODE"},
  {"text": "今天天气怎么样", "label": "CHAT"},
  {"text": "1加1等于几", "label": "FACT"},
  {"text": "分析一下这两个方案的优缺点", "label": "REASON"},
  {"text": "把这段话翻译成英文", "label": "TRANS"},
  {"text": "帮我写一首关于春天的诗", "label": "WRITE"}
]

生成种子文件

重要：生成前配置 API 密钥！

# 设置千问 API 密钥
export SILICONFLOW_API_KEY="sk-你的密钥"

# 或者在代码中直接配置（参考下方）

生成命令：

# 生成 DNA 意图文件（6个分类的代表点）
pnpm smart-router:generate-dna

# 生成用户学习数据文件
pnpm smart-router:generate-user-memory

# 或一次性生成所有
pnpm smart-router:generate-all

生成脚本位置：

scripts/generate-dna-seeds.ts     # DNA生成脚本
scripts/generate-user-memory.ts  # 用户库生成脚本

输出文件：

src/smart-router/dna/base_dna.bin              # DNA意图分类
src/smart-router/dna/default_user_memory.bin  # 用户学习数据

---

🔧 核心特性

1. Medoid算法代替Centroid

优势：

• Medoid永远是真实的样本向量
• 不会被"平均化"抹除特征
• 对离群值更鲁棒

2. 动态置信度惩罚

平滑的惩罚曲线：

confidence >= 0.15 → 无惩罚 (factor = 1.0)
confidence = 0.10  → 轻微惩罚 (factor = 0.98)
confidence = 0.05  → 中度惩罚 (factor = 0.95)
confidence = 0.00  → 重度惩罚 (factor = 0.90)

3. 短查询增强

检测： 字符数 < 6 增强： 阈值降低0.05

4. 软分区双重检测

触发条件： 最佳DNA和第二DNA得分差 < 0.1 行为： 同时搜索两个分区的Patches

5. 查询结果缓存

LRU缓存：

• 最大1000条目
• 60秒TTL
• 向量哈希作为key

---

📊 系统架构

┌─────────────────────────────────────────────────────────┐
│                    用户查询输入                            │
│              "帮我写一个Python正则表达式"                │
└─────────────────────┬───────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│              SmartRouter.decide()                        │
│                                                         │
│  1. 前缀检测 → "flagship:" prefix                     │
│  2. 关键词匹配 → 正则、代码关键词                       │
│  3. Embedding API → 1024维向量                        │
│  4. LayeredIndex搜索 → Patches + DNA                    │
│  5. 决策输出 → tier + model + confidence               │
└─────────────────────┬───────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│               LayeredIndex.search()                      │
│                                                         │
│  ┌───────────────────────────────────────────────┐    │
│  │ 查询缓存 (LRU)                               │    │
│  │ - 向量哈希作为key                             │    │
│  │ - 60秒TTL                                    │    │
│  └─────────────────┬─────────────────────────────┘    │
│                    ↓ 缓存未命中                        │
│  ┌───────────────────────────────────────────────┐    │
│  │ searchPatches() - 软分区双重检测             │    │
│  │ - DNA确定tier                               │    │
│  │ - 搜索对应tier的patches                      │    │
│  │ - 阈值: 0.55                                │    │
│  └─────────────────┬─────────────────────────────┘    │
│                    ↓ 未匹配                            │
│  ┌───────────────────────────────────────────────┐    │
│  │ searchDNA() - Top-K置信度检查               │    │
│  │ - 计算6个DNA相似度                          │    │
│  │ - 动态置信度惩罚                            │    │
│  │ - 阈值: 0.60                                │    │
│  └───────────────────────────────────────────────┘    │
└─────────────────────┬───────────────────────────────────┘
                      ↓
┌─────────────────────────────────────────────────────────┐
│              RoutingDecision 输出                         │
│                                                         │
│  {                                                     │
│    modelTier: "flagship",                             │
│    selectedModel: "zai/glm-4.7",                      │
│    confidence: 0.65,                                   │
│    reasoning: "Patch hit (similarity 0.65)"           │
│  }                                                     │
└─────────────────────────────────────────────────────────┘

---

📖 完整文档

• 🇨🇳 中文完整指南 - 使用教程、配置说明、故障排查
• 🇬🇸 English Complete Guide - Usage guide, configuration, troubleshooting
• 🔍 技术审查文档 - 算法分析、问题记录、改进方向

---

⚠️ 常见问题

问题1：没有启用智能路由

症状： 路由不工作，所有查询都用同一个模型

解决：

openclaw smart-router enable

问题2：模型配置错误

症状： 查询报错或路由决策不合理

解决：

1. 检查 ~/.openclaw/config.json
2. 确保 lightweightModels 和 flagshipModels 配置正确
3. 确保 embedding.model 是千问模型

问题3：向量质量差

症状： 相似度得分普遍很低（< 0.6）

可能原因：

• 种子数据模型 ≠ 运行时模型
• API 密钥错误或配额用完

解决：

1. 确认模型一致
2. 检查 API 密钥
3. 重新生成种子文件

---

🔧 配置示例

完整配置

{
  "smartRouting": {
    "enabled": true,
    "lightweightModels": ["zai/glm-4.5-air", "claude-3-5-haiku"],
    "flagshipModels": ["zai/glm-4.7", "claude-3-7-sonnet"],
    "embedding": {
      "model": "Qwen/Qwen3-Embedding-0.6B",
      "timeoutMs": 5000,
      "apiKey": "your-api-key"
    },
    "patchSimilarityThreshold": 0.55,
    "dnaSimilarityThreshold": 0.60,
    "softPartitionThreshold": 0.1
  }
}

---

📊 技术栈

• 语言： TypeScript/Node.js
• 向量维度： 1024
• 相似度算法： 余弦相似度（点积优化）
• Embedding模型： Qwen/Qwen3-Embedding-0.6B
• 向量存储： 自定义二进制格式（VectorStore）
• DNA格式： VCTR (Vector Centroid)

---

📝 许可证

MIT License

---

📧 联系方式

• 原项目： openclaw/openclaw
• 问题反馈： GitHub Issues