skill-router

OpenClaw 插件：在 prompt 构建前通过语义检索动态过滤 Skills 列表，节省 token 开销。

原理

用户发消息 → before_prompt_build 触发
  → 提取用户最新消息
  → 向量检索（COS Vectors + OpenAI Embedding）
  → 返回最相关的 N 个 Skills
  → 通过 prependSystemContext 注入推荐提示
  → （后续）直接过滤 event.sections 中的 skills 段落

每一轮 Agent 调用 LLM 前都会触发，实现"当前轮立即生效"的动态 Skills 过滤。

项目结构

skill-router/
├── openclaw.plugin.json      # 插件清单（配置 Schema、元数据）
├── package.json              # NPM 包配置
├── tsconfig.json             # TypeScript 配置
├── .env.example              # 环境变量示例
├── src/
│   ├── index.ts              # 插件入口（注册 before_prompt_build hook）
│   ├── retrieve.ts           # 向量检索模块
│   ├── filter.ts             # Skills 过滤逻辑（策略 A + 策略 B）
│   ├── debug.ts              # Debug 日志模块
│   └── types/
│       ├── openclaw.d.ts     # OpenClaw Plugin SDK 最小类型声明
│       └── config.ts         # 插件配置和业务类型
└── scripts/                  # Python 脚本（由安装脚本生成）
    ├── build_skill_index.py  # 离线构建向量索引
    └── retrieve_skills.py    # 在线向量检索

快速开始

前置条件

• OpenClaw 已安装并可用
• Python 3 + 依赖已安装（openai, cos-python-sdk-v5, pyyaml）
• 向量索引已构建（运行过 build_skill_index.py）

安装

# 1. 进入插件目录
cd skill-router

# 2. 本地链接安装（开发模式，修改后重启即可生效）
openclaw plugins install -l .

# 3. 重启 Gateway
openclaw gateway restart

配置

在 ~/.openclaw/openclaw.json 中添加插件配置：

{
  "plugins": {
    "entries": {
      "skill-router": {
        "enabled": true,
        "config": {
          "topK": 5,
          "distanceThreshold": 0.72,
          "debug": true
        }
      }
    }
  }
}

或者通过环境变量配置（参见 .env.example）。

验证

# 查看日志，确认插件加载
openclaw gateway logs | grep skill-router

# Debug 模式下，每次发消息都会打印 event/ctx 结构
SKILL_ROUTER_DEBUG=true openclaw gateway restart

开发

Debug 模式

设置 SKILL_ROUTER_DEBUG=true 或在配置中设 debug: true，插件会在每次 before_prompt_build 触发时打印：

• event 的所有字段和完整 JSON
• event.sections 的每个 section 的 id、keys、内容预览
• ctx.messages 的最后 3 条消息
• ctx 的完整 JSON

这些信息用于验证 OpenClaw 的实际 API 结构，以便实现 sections 直接过滤（策略 B）。

过滤策略

| 策略 | 实现位置 | 状态 | 效果 | | --------------------------- | ------------------------------------------ | -------- | ------------------------------------------------------ | | A: prependSystemContext | filter.ts → buildSkillRecommendation() | ✅ 已实现 | 注入推荐提示，引导 LLM 优先使用相关 Skills | | B: sections 过滤 | filter.ts → filterSkillsSections() | ⏳ 待验证 | 直接从 system prompt 中移除不相关 Skills，真正省 token |

策略 B 需要 debug 输出确认 event.sections 的确切结构后再启用。

修改代码后

# OpenClaw 使用 jiti 加载 .ts，修改源码后重启 Gateway 即可
openclaw gateway restart

环境变量

| 变量 | 说明 | 默认值 | | -------------------------- | ------------------ | ---------------------------------------- | | SKILL_ROUTER_DEBUG | 开启 debug 模式 | false | | SKILL_ROUTER_SCRIPT_PATH | 检索脚本路径 | ~/.openclaw/scripts/retrieve_skills.py | | OPENAI_API_KEY | Embedding API Key | — | | EMBEDDING_BASE_URL | Embedding API 地址 | https://api.openai.com/v1 | | EMBEDDING_MODEL | Embedding 模型 | text-embedding-3-small | | COS_VECTORS_SECRET_ID | 腾讯云 SecretId | — | | COS_VECTORS_SECRET_KEY | 腾讯云 SecretKey | — | | COS_VECTORS_BUCKET | COS Bucket | — | | COS_VECTORS_REGION | COS Region | ap-guangzhou | | COS_VECTORS_INDEX | 向量索引名 | skill-index |