Harness 与 Agent 工程 · 上下文与记忆 · 2026-03-09

OpenClaw怎么可能没痛点?用RDS插件来释放OpenClaw全部潜力

解锁OpenClaw隐藏力量:RDS插件如何解决深度定制难题,让你的AI助手更智能。

核心内容:

  1. 插件机制对比:Skill、Tool与Plugin的本质差异与应用场景
  2. OpenClaw插件架构解析:从npm包结构到生命周期钩子机制
  3. RDS插件实战:知识注入、记忆持久化等四大典型应用场景

一、为什么你需要关注插件

大多数 OpenClaw 用户在实现自定义功能时,第一反应是编写 Skill 或注册自定义 Tool。这两种方式简单直接,但在面对需要深度介入 Agent 生命周期的场景时,往往力不从心。

1.1 三种扩展机制对比

维度 Skill Tool Plugin
本质 Markdown 文本,注入到系统提示词 一个可被 AI 调用的函数 完整的扩展程序,可访问 Agent 全生命周期
执行时机 系统提示词构建阶段被注入 AI 主动决策调用 可以借助“钩子”在任意生命周期中执行
能否主动介入 否,只能被动提供指令 否,依赖 AI 判断是否调用 是,依赖钩子机制主动介入
适用场景 行为指导、回答风格、领域知识补充 搜索、计算、文件操作等工具性任务 记忆管理、知识注入、数据持久化、多 Agent 协作

1.2 关键差异:被动 vs 主动

当你的需求是「在生命周期中某个阶段总应该自动发生某件事」(而非等 AI 判断后才执行),插件是唯一选择。

1.3 应用插件的常见场景


二、深入理解 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 从以下位置按优先级发现插件:

  1. 配置路径 (plugins.load.paths):指向本地目录,适合开发调试
  2. 工作区目录 (.openclaw/extensions/):项目级插件
  3. 内置插件目录:OpenClaw 自带的插件
  4. 全局扩展目录 (~/.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 新闻对话官,与用户交…
— 以上为试看内容(约 40%),开通会员后阅读全文 —

原文出处:https://www.53ai.com/news/Openclaw/2026030924610.html