一、为什么你需要关注插件
大多数 OpenClaw 用户在实现自定义功能时,第一反应是编写 Skill 或注册自定义 Tool。这两种方式简单直接,但在面对需要深度介入 Agent 生命周期的场景时,往往力不从心。
1.1 三种扩展机制对比
| 维度 | Skill | Tool | Plugin |
|---|---|---|---|
| 本质 | Markdown 文本,注入到系统提示词 | 一个可被 AI 调用的函数 | 完整的扩展程序,可访问 Agent 全生命周期 |
| 执行时机 | 系统提示词构建阶段被注入 | AI 主动决策调用 | 可以借助“钩子”在任意生命周期中执行 |
| 能否主动介入 | 否,只能被动提供指令 | 否,依赖 AI 判断是否调用 | 是,依赖钩子机制主动介入 |
| 适用场景 | 行为指导、回答风格、领域知识补充 | 搜索、计算、文件操作等工具性任务 | 记忆管理、知识注入、数据持久化、多 Agent 协作 |
1.2 关键差异:被动 vs 主动
当你的需求是「在生命周期中某个阶段总应该自动发生某件事」(而非等 AI 判断后才执行),插件是唯一选择。
1.3 应用插件的常见场景
- 需要在每次对话开始前自动检索和注入外部知识(RAG)
- 需要在每次对话结束后自动提取和持久化记忆
- 需要替换 OpenClaw 的默认行为(如替换内置记忆系统)
- 需要在多个 Agent 之间共享数据管道
二、深入理解 OpenClaw 插件
2.1 核心概念
OpenClaw 插件是一个 npm 包(或本地目录),包含以下核心文件:
my-plugin/├── package.json # npm 包元数据 + openclaw.extensions 入口声明├── openclaw.plugin.json # 插件清单(id、描述、配置模式)├── index.ts # 插件入口,导出 { id, register } 对象└── ... # 其他源码文件
插件清单 (openclaw.plugin.json) 定义了插件的身份和配置模式:
{ "id": "my-plugin", "name": "My Plugin", "description": "Does something useful", "configSchema": { "type": "object", "required": ["apiKey"], "properties": { "apiKey": { "type": "string" } } }}
包声明 (package.json) 中的 openclaw.extensions 字段告诉 OpenClaw 从哪个文件加载插件逻辑:
{ "openclaw": { "extensions": ["./index.ts"] }}
2.2 插件在 Agent 生命周期中的作用点
OpenClaw 的 Agent 生命周期是一条从消息接收到回复发送的管线。插件可以通过“钩子(Hooks)”在管线的关键节点介入。OpenClaw 共提供 24 个钩子,覆盖 Agent 运行、消息处理、工具调用、会话管理等全部阶段。
核心生命周期流程
钩子分类总览
Agent 阶段钩子:
| 钩子 | 触发时机 | 可干预 | 典型用途 |
|---|---|---|---|
before_model_resolve |
模型选择前 | 是(切换模型/供应商) | 按场景动态路由到不同模型 |
before_prompt_build |
系统提示词构建前 | 是(注入上下文/覆盖提示词) | 知识注入、动态指令生成 |
before_agent_start |
模型解析 + 提示词构建阶段 | 是(注入上下文 + 切换模型) | 向后兼容钩子;模型覆盖优先级低于 before_model_resolve,上下文注入在提示词构建阶段生效 |
llm_input |
LLM 请求发出前 | 仅观测 | 请求日志、审计 |
llm_output |
LLM 响应返回后 | 仅观测 | token 用量统计、质量监控 |
agent_end |
Agent 推理完成 | 仅观测 | 记忆提取、对话归档、错误追踪 |
工具调用钩子:
| 钩子 | 触发时机 | 可干预 | 典型用途 |
|---|---|---|---|
before_tool_call |
工具执行前 | 是(修改参数/拦截调用) | 权限校验、参数审计、敏感操作拦截 |
after_tool_call |
工具执行后 | 仅观测 | 结果日志、耗时统计 |
tool_result_persist |
工具结果写入会话前 | 是(修改或裁剪结果) | 去除冗余字段以节约上下文空间 |
消息与会话钩子:
| 钩子 | 触发时机 | 可干预 | 典型用途 |
|---|---|---|---|
message_received |
消息到达时 | 仅观测 | 消息日志、计数统计 |
message_sending |
回复发送前 | 是(修改内容/取消发送) | 内容审核、格式转换 |
message_sent |
回复发送后 | 仅观测 | 送达确认、失败重试 |
session_start |
新会话创建时(恢复已有会话不触发) | 仅观测 | 会话级资源初始化 |
session_end |
会话结束 | 仅观测 | 会话级资源清理 |
记忆与会话管理钩子:
| 钩子 | 触发时机 | 可干预 | 典型用途 |
|---|---|---|---|
before_compaction |
会话压缩前 | 仅观测 | 压缩前归档完整会话 |
after_compaction |
会话压缩后 | 仅观测 | 压缩效果统计 |
before_reset |
会话重置前 | 仅观测 | 重置前保存状态 |
before_message_write |
消息写入会话记录前 | 是(修改/阻止写入) | 过滤敏感信息、自定义持久化 |
子 Agent 钩子:
| 钩子 | 触发时机 | 典型用途 |
|---|---|---|
subagent_spawning |
子 Agent 创建前 | 控制子 Agent 生成策略 |
subagent_spawned |
子 Agent 创建后 | 跟踪子 Agent 运行 |
subagent_ended |
子 Agent 结束 | 收集子 Agent 执行结果 |
subagent_delivery_target |
子 Agent 回复路由时 | 自定义回复投递目标 |
Gateway 钩子:
| 钩子 | 触发时机 | 典型用途 |
|---|---|---|
gateway_start |
Gateway 启动时 | 初始化外部连接 |
gateway_stop |
Gateway 关闭时 | 清理资源 |
2.3 插件的两种角色
通用插件(General Plugin):提供工具和钩子,与其他插件并行工作。
插槽插件(Slot Plugin):替换 OpenClaw 的某个核心功能。目前支持的插槽:
| 插槽 | 功能 | 默认实现 |
|---|---|---|
memory |
长期记忆存储与检索 | 内置 memory-core(本地文件 + SQLite) |
contextEngine |
上下文引擎(控制上下文编排策略) | 内置默认实现 |
当你在配置中指定 plugins.slots.memory = "your-plugin-id" 时,你的插件将完全替代默认的 memory-core 记忆系统。
2.4 插件的发现与安装
OpenClaw 从以下位置按优先级发现插件:
- 配置路径 (
plugins.load.paths):指向本地目录,适合开发调试 - 工作区目录 (
.openclaw/extensions/):项目级插件 - 内置插件目录:OpenClaw 自带的插件
- 全局扩展目录 (
~/.openclaw/extensions/):通过openclaw plugins install安装
开发阶段推荐使用 plugins.load.paths,直接指向源码目录:
{ "plugins": { "load": { "paths": ["/path/to/your/plugin"] } }}
生产阶段推荐发布到 npm 后通过 CLI 安装:
openclaw plugins install your-plugin-name
2.5 插件配置
每个插件在 openclaw.json 的 plugins.entries 中拥有独立的配置空间:
{ "plugins": { "entries": { "your-plugin-id": { "enabled": true, "config": { "apiKey": "${ENV_VAR}", "option": "value" } } }, "allow": ["your-plugin-id"] }}
配置值支持 ${ENV_VAR} 语法引用环境变量,避免敏感信息硬编码。
三、插件开发范式速览
3.1 最小可用插件示例
import { Type } from "@sinclair/typebox";import type { OpenClawPluginApi } from "openclaw/plugin-sdk";const plugin = { id: "my-plugin", register(api: OpenClawPluginApi) { const config = api.pluginConfig as { greeting: string }; // 注册工具 api.registerTool( { name: "say_hello", label: "Say Hello", description: "Greet the user", parameters: Type.Object({ name: Type.String({ description: "User name" }), }), async execute(_toolCallId, params) { const { name } = params as { name: string }; return { content: [{ type: "text", text: `${config.greeting}, ${name}!` }], }; }, }, { name: "say_hello" }, ); // 注册生命周期钩子 api.on("before_agent_start", async (event, ctx) => { api.logger.info("Agent", ctx.agentId, "starting..."); return { prependContext: "Remember to be friendly!" }; }); // 注册服务(管理资源生命周期) api.registerService({ id: "my-plugin", start: (ctx) => ctx.logger.info("Plugin started"), stop: async (ctx) => ctx.logger.info("Plugin stopped"), }); },};exportdefault plugin;
3.2 核心 API 速查
| API | 用途 |
|---|---|
api.pluginConfig |
获取插件配置(来自 openclaw.json 中的 plugins.entries.<id>.config) |
api.logger |
日志输出(.info(), .warn(), .error()) |
ctx.agentId |
钩子回调第二个参数 ctx 中的当前 Agent ID(非 api 顶层属性) |
api.registerTool(def, opts) |
注册一个可被 AI 调用的工具 |
api.on(hook, handler) |
监听生命周期事件,handler 签名为 (event, ctx) => result,ctx 含 agentId 等上下文 |
api.registerService(svc) |
注册服务(管理启动/停止生命周期) |
四、最佳实践:
用 RDS MySQL 生态插件解决原生 OpenClaw 的两大痛点
4.1 痛点分析:外源知识使用与长期记忆管理
痛点一:外源知识使用 —— AI 只能靠「问」来获取
原生 OpenClaw 获取外部知识的路径是:
用户提问 → AI 判断需要外部信息 → AI 调用 web_search / web_fetch → 获取结果 → 生成回答
这条路径存在三个问题:
| 问题 | 说明 |
|---|---|
| 决策依赖 AI | AI 可能判断「我已经知道答案」而跳过搜索,导致使用过时信息 |
| 无法预加载 | 即使有现成的知识库,也必须等 AI 主动调用工具才能检索 |
| 无结构化存储 | web_search 获取的信息是一次性的,下次对话需要重新搜索 |
用 Skill 指导 AI「每次都先搜索」可以缓解但无法根治 —— 因为 Skill 只是建议,AI 仍可能忽略。
痛点二:长期记忆管理 —— 默认记忆系统的局限
OpenClaw 的默认记忆方案是 memory-core,它基于本地文件系统运作:
所有记忆都以 Markdown 文件(MEMORY.md、memory/*.md)和 SQLite 的形式存储在本地 ~/.openclaw/ 目录下。这套方案在单机个人使用场景下工作良好,但面临以下局限:
| 局限 | 说明 |
|---|---|
| 数据绑定宿主机 | 所有记忆存储在本地文件系统,无法跨设备访问 |
| 无备份与高可用 | 本地文件系统不具备自动备份、故障恢复能力 |
| 检索依赖全文匹配 | memory-core 的检索基于关键词和 Markdown 全文,缺乏语义理解能力 |
| 记忆质量管理缺失 | 没有去重、归档、摘要等主动维护手段 |
4.2 实践一:外源知识注入案例 — 世界经济新闻知识库
场景描述
我们希望构建一个「世界经济新闻顾问」,它能够:
- 每天自动采集最新经济新闻,存入知识库
- 用户提问时,自动从知识库检索相关新闻并注入上下文
- 支持用户主动搜索知识库
这需要两个插件和两个 Agent 协作:
| 组件 | 职责 |
|---|---|
知识生成插件 (openclaw-knowledgebase-generate-alibaba-mysql) |
文本分块 → Embedding → 存入 MySQL 向量表 |
知识检索插件 (openclaw-knowledgebase-fetch-alibaba-mysql) |
每次对话前自动检索 → 注入上下文;提供 kb_search 工具 |
| news-crawler Agent | 新闻采集器,搜索互联网并调用插件存入知识库 |
| news-chat Agent | 新闻对话官,与用户交… |