skill-auto-loader-hook

这是一个 OpenClaw 钩子插件，用来在每次用户发送消息时，自动判断是否需要优先使用某个 skill，并把“本轮应优先考虑哪些 skill、适用范围是什么”注入到 prompt 构建阶段。

这个插件解决什么问题

适合下面这类需求：

1. 用户一发消息，就自动判断要不要优先走某个 skill。
2. 不同场景要命中不同 skill。
3. skill 的“适用范围”需要自定义，而不是全局写死。
4. 规则应该放在一个单独配置文件里，而不是挤在 openclaw.json 里。
5. 插件要自动读取本地已安装 skill 的 name 和 description。
6. 插件要自动读取 ~/.openclaw/openclaw.json 中的默认模型信息。

例如：

1. 用户提到“知识库、公司规定、查文档”，优先用 company-knowledge-base
2. 用户提到“日报、工时、工作记录”，优先用 daily-report
3. 用户提到“飞书插件、飞书配置”，优先用 openclaw-feishu-plugin

官方设计依据

根据 OpenClaw 官方插件文档：

1. 原生插件通过 openclaw.plugin.json + 运行时模块工作。
2. 这类“每次消息到来时做动态判断”的需求，最合适的钩子是 before_prompt_build。
3. 该钩子运行时已经拿得到 messages，适合做本轮 skill 路由判断。

插件目录结构

skill-auto-loader-hook/
├── openclaw.plugin.json
├── index.ts
├── skill-router.config.json
└── README.md

安装方式

本地开发推荐：

openclaw plugins install -l D:/project/openclaw-skill-2/openclaw-skills/plugins/skill-auto-loader-hook

安装后重启 Gateway。

如果你已经发布到 npm，则可以直接安装：

openclaw plugins install skill-auto-loader-hook-paperfly777

更新方式

如果你在 Linux / 虚拟机里更新插件，推荐直接使用一键更新脚本：

chmod +x ./update-plugin.sh
./update-plugin.sh

默认行为：

1. 从 npm 拉取最新版本
2. 解压到临时目录
3. 删除旧插件目录
4. 覆盖到 ~/.openclaw/extensions/skill-auto-loader-hook
5. 自动执行 openclaw gateway restart

如果你要安装指定版本：

./update-plugin.sh 0.1.7

说明：

1. 这个脚本会随 npm 包一起发布。
2. 也就是说，别人安装了你的插件后，在插件目录里同样可以直接执行它。
3. 如果当前已安装版本目录里还没有这个脚本，说明那个版本还没把脚本打包进去，需要升级到新发布版本后才会有。

安装方式：

openclaw plugins install skill-auto-loader-hook-paperfly777

说明：

1. 当前包名我先给你定成了 skill-auto-loader-hook-paperfly777，如果你后面有自己的 npm scope，再改 package.json 即可。
2. 该插件按 OpenClaw 官方方式，通过 package.json -> openclaw.extensions -> index.ts 暴露入口。

配置方式

这个插件分两层配置：

1. openclaw.json 里只放插件基础入口配置
2. skill-router.config.json 里放独立的技能路由规则

路径说明：

1. routerConfigPath 如果写相对路径，则相对于插件目录解析。
2. skillsScanDirs 如果写相对路径，也相对于插件目录解析。
3. openclawConfigPath 建议使用 ~/.openclaw/openclaw.json。

使用说明（重点）

1) 怎么使用

1. 安装插件后，确保 plugins.entries.skill-auto-loader-hook.enabled=true。
2. 配置好 routerConfigPath 指向 skill-router.config.json。
3. 重启 gateway：openclaw gateway restart。
4. 之后每次用户发消息，插件会在 before_prompt_build 自动执行 skill 路由判断。

2) 配置文件在哪里

• OpenClaw 主配置：~/.openclaw/openclaw.json
• 插件路由配置：skill-router.config.json（默认按插件目录相对路径读取）

推荐写法：

1. 先写使用范围（scopeNote）
2. 再写执行约束（prompt）
3. 避免只写关键词，不写动作规则

3) 白名单和黑名单怎么配

• 全局白名单：includeSkills
• 全局黑名单：excludeSkills

示例：

{
  "includeSkills": ["company-knowledge-base", "daily-report", "openclaw-feishu-plugin"],
  "excludeSkills": ["remotion"]
}

说明：

1. includeSkills 不为空时，候选技能会先被限制在白名单内。
2. excludeSkills 会在全局层面直接排除。
3. 规则命中后会叠加 preferSkills/excludeSkills 做本轮精细路由。

参数说明（完整）

A. openclaw.json -> plugins.entries.skill-auto-loader-hook

| 参数 | 类型 | 可选值/示例 | 默认值 | 作用 | |---|---|---|---|---| | enabled | boolean | true/false | true | 是否启用这个插件入口。 | | config.enabled | boolean | true/false | true | 插件运行时开关。关闭后插件不做任何注入。 | | config.injectMode | string | prependContext / prependSystemContext / appendSystemContext | prependContext | 选择把路由提示注入到哪里。 | | config.routerConfigPath | string | ./skill-router.config.json | ./skill-router.config.json | 独立路由配置文件路径。相对路径按插件目录解析。 | | config.openclawConfigPath | string | ~/.openclaw/openclaw.json | ~/.openclaw/openclaw.json | 读取默认模型信息的配置文件路径。 |

injectMode 选择建议：

1. prependContext：推荐。影响最小，兼容性最好。
2. prependSystemContext：约束最强，适合必须遵守路由的场景。
3. appendSystemContext：权重相对弱，适合补充说明。

injectMode 详细解释（这三个参数到底什么意思）：

1. prependContext

   • 含义：把插件生成的路由提示，放到“普通上下文”的前面。
   • 特点：不会强压系统提示，兼容性最好，不容易和其他系统规则冲突。
   • 适合：大多数场景，尤其是你只希望“引导模型优先用某些 skill”。

2. prependSystemContext

   • 含义：把路由提示放到“系统上下文”最前面。
   • 特点：约束力最强，模型更容易优先执行这段规则。
   • 风险：如果规则写得太死，可能压过原有系统策略，导致回答风格变硬。
   • 适合：强流程场景（例如必须先知识库检索、必须二次确认写操作）。

3. appendSystemContext

   • 含义：把路由提示放到“系统上下文”末尾。
   • 特点：仍在系统层，但通常权重低于前置系统上下文。
   • 适合：你想补充一层路由提醒，但不想强覆盖原系统策略时使用。

B. skill-router.config.json 顶层参数

| 参数 | 类型 | 可选值/示例 | 默认值 | 作用 | |---|---|---|---|---| | enabled | boolean | true/false | true | 路由配置总开关。 | | skillsScanDirs | string[] | ["~/.openclaw/workspace/skills"] | 自动推断目录 | 扫描已安装 skill 的目录列表。 | | includeSkills | string[] | ["company-knowledge-base"] | [] | 全局白名单。非空时仅这些 skill 参与候选。 | | excludeSkills | string[] | ["remotion"] | [] | 全局黑名单。始终排除这些 skill。 | | maxSkillsInPrompt | number | 10 / 20 | 20 | 注入提示中最多携带多少个候选 skill。 |

1. openclaw.json 中的插件入口配置

{
  "plugins": {
    "entries": {
      "skill-auto-loader-hook": {
        "enabled": true,
        "hooks": {
          "allowPromptInjection": true
        },
        "config": {
          "enabled": true,
          "injectMode": "prependContext",
          "routerConfigPath": "./skill-router.config.json",
          "openclawConfigPath": "~/.openclaw/openclaw.json"
        }
      }
    }
  }
}

2. 独立路由配置文件 skill-router.config.json

{
  "enabled": true,
  "skillsScanDirs": [
    "~/.openclaw/workspace/skills"
  ],
  "includeSkills": [],
  "excludeSkills": [],
  "maxSkillsInPrompt": 20
}

运行逻辑

每次用户发消息时：

1. before_prompt_build 读取本轮用户消息。
2. 自动读取 skill-router.config.json。
3. 自动扫描本地已安装的 skill，提取 SKILL.md 里的 name 和 description。
4. 自动读取 ~/.openclaw/openclaw.json，拿到当前默认模型信息。
5. 用自定义规则先做范围收缩。
6. 把“用户消息 + 候选 skills + 规则提示 + 默认模型”一起注入当前轮 prompt。
7. 再由当前默认大模型判断：本轮是否需要 skill、优先用哪个 skill。

这个插件和大模型的关系

这个插件不是自己在本地写死判断逻辑，而是：

1. 插件负责收集上下文
2. 插件负责收窄可选 skill 范围
3. 插件会主动调用一次当前默认大模型，在候选 skill 中做最终路由判断

这样后面你增加新 skill，不需要改核心判断逻辑，只要：

1. skill 已安装
2. skill 有 name 和 description
3. 在独立配置文件里补规则

重要边界

这个插件做的是“动态路由和提示注入”，不是“运行时热安装 skill”。

也就是说：

1. 它可以引导 OpenClaw 本轮优先考虑哪些已安装 skill。
2. 它不能替代 skill 本身的安装和发现机制。
3. 所有要被路由的 skill，仍然需要先安装到 OpenClaw 可发现的位置。
4. 它当前做的是“把 skill 判断交给默认模型”，不是在插件里直接调用第二个独立模型 API。