释放OpenClaw潜能:RDS插件解决外源知识与长期记忆痛点

使用阿里云RDS插件扩展OpenClaw,解决外源知识使用和长期记忆管理难题,释放全部潜能。

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

原文作者:阿里云开发者

冷月清谈:

本文深入探讨了如何使用阿里云RDS插件来扩展OpenClaw的功能,解决原生OpenClaw在外源知识使用和长期记忆管理方面的痛点。文章首先对比了Skill、Tool和Plugin三种扩展机制,强调了Plugin在Agent生命周期深度介入方面的优势。接着,详细介绍了OpenClaw插件的核心概念、在Agent生命周期中的作用点以及两种角色(通用插件和插槽插件)。

文章重点介绍了两个最佳实践案例:一是利用RDS MySQL生态插件实现世界经济新闻知识库,通过知识生成和检索插件,结合新闻采集Agent和新闻对话Agent,实现新闻的自动采集、存储、检索和注入;二是将OpenClaw的长期记忆从默认的本地文件系统迁移到阿里云RDS MySQL,实现记忆数据的云端持久化、多Agent/多设备共享以及自动备份与高可用。

通过这两个实践案例,文章展示了如何利用RDS插件解决OpenClaw原生方案在知识获取和记忆管理方面的局限性,如AI决策依赖、无法预加载、无结构化存储、数据绑定宿主机、无备份与高可用等问题,从而释放OpenClaw的全部潜能。

怜星夜思:

1、文章提到了OpenClaw默认的记忆方案是基于本地文件系统的,这种方案有哪些潜在的风险?除了文章中提到的数据绑定宿主机和无备份高可用之外,还有其他的吗?
2、文章中提到了使用向量数据库来存储和检索知识,这个向量数据库的具体作用是什么?为什么不用传统的关键词搜索?
3、文章提到了OpenClaw插件的两种角色:通用插件和插槽插件。那么,如果我想修改OpenClaw的默认提示词(Prompt),应该使用哪种插件?为什么?

原文内容

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

大多数 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 从以下位置按优先级发现插件:

  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) => resultctx  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.mdmemory/*.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

新闻对话官,与用户交互,自动获得知识库上下文加持

从零搭建:完整步骤
前置条件

依赖

说明

OpenClaw

已安装并可运行 openclaw --version

阿里云 RDS MySQL

已开通,支持向量引擎(VECTOR 类型)。

开通指南:

https://help.aliyun.com/zh/rds/apsaradb-rds-for-mysql/vector-storage-1

DashScope API Key

用于 Embedding 和 LLM 推理。

开通指南:


https://bailian.console.aliyun.com/cn-beijing/?tab=api#/api/?type=model&url=2712195


Node.js / npm

用于安装插件

第一步:设置环境变量

将敏感信息配置为环境变量,避免硬编码到配置文件中。在 ~/.bashrc(或 ~/.zshrc)中添加:

export MYSQL_HOST="rm-xxxxxxxxxxxx.mysql.rds.aliyuncs.com"
export MYSQL_USER="your_username"
export MYSQL_PASSWORD="your_password"
export DASHSCOPE_API_KEY="sk-xxxxxxxxxxxxxxxx"

执行 source ~/.bashrc 使环境变量生效。

openclaw.json 中通过 ${ENV_VAR} 语法引用这些变量,OpenClaw 会在启动时自动解析替换。

第二步:安装插件
openclaw plugins install openclaw-knowledgebase-generate-alibaba-mysql
openclaw plugins install openclaw-knowledgebase-fetch-alibaba-mysql

安装完成后可验证:

openclaw plugins list
# 应能看到两个插件
第三步:配置 LLM 模型供应商

 ~/.openclaw/openclaw.json 的 models 中注册 DashScope 模型。news-crawler 使用低成本的 qwen-flashnews-chat 使用高质量的 qwen3-max

{
  "models": {
    "mode": "merge",
    "providers": {
      "dashscope": {
        "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
        "api": "openai-completions",
        "apiKey": "${DASHSCOPE_API_KEY}",
        "models": [
          {
            "id": "qwen3-max",
            "name": "Qwen3 Max",
            "input": ["text"],
            "reasoning": false,
            "contextWindow": 128000,
            "maxTokens": 8192
          },
          {
            "id": "qwen-flash",
            "name": "Qwen Flash",
            "input": ["text"],
            "reasoning": false,
            "contextWindow": 128000,
            "maxTokens": 8192
          }
        ]
      }
    }
  }
}
第四步:配置插件

 openclaw.json 的 plugins 中完成三部分配置:加载声明允许列表各插件参数

{
  "plugins": {
    "allow": [
      "openclaw-knowledgebase-generate-alibaba-mysql",
      "openclaw-knowledgebase-fetch-alibaba-mysql"
    ],
    "entries": {
      "openclaw-knowledgebase-generate-alibaba-mysql": {
        "enabled": true,
        "config": {
          "mysql": {
            "host": "${MYSQL_HOST}",
            "port": 3306,
            "user": "${MYSQL_USER}",
            "password": "${MYSQL_PASSWORD}",
            "database": "openclaw_knowledge_base",
            "ssl": false
          },
          "embedding": {
            "apiKey": "${DASHSCOPE_API_KEY}",
            "model": "text-embedding-v3",
            "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "dimensions": 1024
          },
          "defaultTable": "kb_economy_news",
          "chunking": {
            "strategy": "paragraph",
            "maxChunkSize": 500,
            "overlap": 100
          }
        }
      },
      "openclaw-knowledgebase-fetch-alibaba-mysql": {
        "enabled": true,
        "config": {
          "mysql": {
            "host": "${MYSQL_HOST}",
            "port": 3306,
            "user": "${MYSQL_USER}",
            "password": "${MYSQL_PASSWORD}",
            "database": "openclaw_knowledge_base",
            "ssl": false
          },
          "embedding": {
            "apiKey": "${DASHSCOPE_API_KEY}",
            "model": "text-embedding-v3",
            "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "dimensions": 1024
          },
          "sources": [
            {
              "table": "kb_economy_news",
              "label": "世界经济新闻",
              "topK": 5,
              "minScore": 0.3
            }
          ],
          "autoInject": true,
          "injectMaxChars": 3000
        }
      }
    }
  }
}

关键配置说明

配置项

说明

mysql.database

必填。指定 MySQL 数据库名,需提前在 RDS 中创建

embedding.model

Embedding 模型,DashScope 推荐 text-embedding-v3

embedding.dimensions

向量维度,text-embedding-v3 支持 1024(默认)或 768

defaultTable

知识生成插件的默认目标表名,AI 调用 kb_store 时若不指定表名则写入此表

chunking.strategy

分块策略:paragraph(按段落)、fixed(固定长度)、none(不分块)

sources

知识检索插件的数据源列表,支持多个表并行检索

| sources[ ].topK | 每次检索返回的最大条目数 |

| sources[ ].minScore | 最低相似度阈值(0-1),低于此值的结果被过滤 |

| autoInject | 是否在每次对话开始时自动注入知识(before_agent_start 钩子) | | injectMaxChars | 自动注入的最大字符数,防止上下文过长 |

两个插件的 mysql 和 embedding 配置必须一致(指向同一数据库、同一 Embedding 模型和维度),否则写入和检索时的向量空间不匹配。

第五步:定义 Agent

 openclaw.json 的 agents 中定义两个 Agent。核心是通过 tools.allow 工具白名单控制每个 Agent 的能力边界:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "dashscope/qwen3-max"
      }
    },
    "list": [
      {
        "id": "news-chat",
        "name": "新闻对话官",
        "default": true,
        "identity": {
          "name": "NewsBot"
        },
        "model": {
          "primary": "dashscope/qwen3-max"
        },
        "tools": {
          "allow": [
            "memory_recall", "memory_store", "memory_forget",
            "kb_search", "web_fetch"
          ]
        }
      },
      {
        "id": "news-crawler",
        "name": "新闻采集器",
        "identity": {
          "name": "Crawler"
        },
        "model": {
          "primary": "dashscope/qwen-flash"
        },
        "tools": {
          "allow": [
            "web_fetch",
            "kb_store", "kb_store_batch"
          ]
        },
        "heartbeat": {
          "target": "none"
        }
      }
    ]
  }
}

第六步:验证配置

运行配置检查:

openclaw doctor

如果输出无报错,说明配置有效。

第七步:运行 news-crawler 写入知识

手动触发采集 Agent,验证知识写入流程(注意退出需要找到 pid 后 kill,也可以在 Gateway 中测试):

openclaw agent --agent news-crawler --message \
  "使用 web_fetch 访问 https://www.baidu.com/s?wd=世界经济新闻 ,从搜索结果中提取 2 条新闻摘要,然后用 kb_store 逐条存入知识库"

成功时你会看到类似输出:

[plugins] kb-generate: registered (defaultTable=kb_economy_news, ...)
已成功从百度搜索结果中提取并存储两条新闻到知识库...
第八步:运行 news-chat 验证检索

手动触发chat Agent,验证知识写入流程(注意退出需要找到 pid 后 kill,也可以在 Gateway 中测试):

openclaw agent --agent news-chat --message "最近有什么世界经济方面的新闻?"

成功时你会看到类似输出:

[plugins] kb-fetch: registered (sources=世界经济新闻, autoInject=true, ...)
[plugins] kb-fetch: injected 3 entries (294 chars)    ← 自动注入了知识
根据知识库中的信息,以下是近期重要的世界经济新闻...

关键观察点:kb-fetch: injected N entries 表明知识检索插件在 before_agent_start 钩子中成功检索并注入了相关知识。AI 的回答直接引用了知识库中的内容,无需任何人工干预或 AI 主动调用工具

插件工作原理详解
知识生成插件
  • npm:openclaw-knowledgebase-generate-alibaba-mysql

知识生成插件是一个纯工具插件,不使用任何生命周期钩子。它在 Agent 推理过程中被 AI 通过工具调用来使用。注意,MySQL 表在首次写入时自动创建,无需手动建表。

提供的工具:

工具

功能

kb_store

存储单条文本,自动分块和 Embedding

kb_store_batch

批量存储多条文本

kb_scan

查看知识库统计和最近条目

kb_dedupe

时间窗口内语义去重

kb_summarize

获取最近条目,供 AI 生成摘要

kb_archive

软删除过期条目

知识检索插件
  • npm:openclaw-knowledgebase-fetch-alibaba-mysql

知识检索插件通过 before_agent_start 钩子实现自动检索用户和 AI 都不需要做任何事,相关知识已经自动就位,这是它与普通 Tool 的根本区别:

4.3 实践二:

长期记忆云化 — RDS MySQL 替代本地方案

场景描述

将 OpenClaw 的长期记忆从默认的 memory-core(本地文件 + SQLite)迁移到阿里云 RDS MySQL,实现:

  • 记忆数据云端持久化,不受宿主机限制

  • 多 Agent / 多设备共享同一份记忆

  • 自动备份与高可用(依托 RDS 能力)

为什么插件是更好的解决方案

需求

Skill/Tool 方案

插件方案

每次对话自动检索知识

❌ 需要 AI 主动调用

 before_agent_start 钩子自动执行

对话后自动提取记忆

❌ 需要 AI 主动调用

 agent_end 钩子自动执行

替换默认记忆系统

❌ 无法实现

 plugins.slots.memory 插槽机制

多 Agent 共享数据

❌ 无法实现

✅ 多个 Agent 配置同一插件,共享数据库

从零搭建:完整步骤
前置条件

与 4.2 相同:需要 OpenClaw、阿里云 RDS MySQL、DashScope API Key。如果你已经完成了 4.2 的环境搭建,此处可直接复用。

第一步:设置环境变量

如果尚未设置,参照 4.2 第一步配置 MYSQL_HOSTMYSQL_USERMYSQL_PASSWORDDASHSCOPE_API_KEY

第二步:安装插件
openclaw plugins install openclaw-memory-alibaba-mysql
第三步:配置插件并声明插槽

这是记忆云化的关键步骤。需要在 ~/.openclaw/openclaw.json 中完成两件事:

  1.  plugins.entries 中配置插件参数

  2.  plugins.slots.memory 中将该插件声明为记忆插槽

{
  "plugins": {
    "slots": {
      "memory": "openclaw-memory-alibaba-mysql"
    },
    "allow": [
      "openclaw-memory-alibaba-mysql"
    ],
    "entries": {
      "openclaw-memory-alibaba-mysql": {
        "enabled": true,
        "config": {
          "mysql": {
            "host": "${MYSQL_HOST}",
            "port": 3306,
            "user": "${MYSQL_USER}",
            "password": "${MYSQL_PASSWORD}",
            "database": "openclaw_memory",
            "ssl": false
          },
          "embedding": {
            "apiKey": "${DASHSCOPE_API_KEY}",
            "model": "text-embedding-v3",
            "baseUrl": "https://dashscope.aliyuncs.com/compatible-mode/v1",
            "dimensions": 1024
          },
          "autoRecall": true,
          "autoCapture": true,
          "tableName": "openclaw_memories"
        }
      }
    }
  }
}

plugins.slots.memory生效的核心。设置后,OpenClaw 内置的 memory-core 会被完全禁用,所有记忆操作由 MySQL 插件接管。如果不设置此插槽,插件虽然会加载并注册工具,但 OpenClaw 的默认记忆系统仍然是 memory-core

关键配置说明

配置项

必填

说明

mysql.host

RDS MySQL 实例地址

mysql.database

数据库名,需提前在 RDS 中创建

mysql.ssl

是否启用 SSL 连接,默认 false

embedding.apiKey

DashScope API Key

embedding.model

Embedding 模型,默认 text-embedding-v3

embedding.dimensions

向量维度,默认根据模型自动推断(text-embedding-v3 为 1024

autoRecall

每次对话前是否自动检索相关记忆,默认 true

autoCapture

每次对话后是否自动从用户消息中提取并存储记忆,默认 true

tableName

MySQL 表名,默认 openclaw_memories,首次使用时自动创建

第四步:确保 Agent 拥有记忆工具权限

如果你的 Agent 配置了 tools.allow 白名单,需要将记忆工具加入:

{
  "agents": {
    "list": [
      {
        "id": "news-chat",
        "tools": {
          "allow": [
            "memory_recall", "memory_store", "memory_forget",
            "kb_search", "web_fetch"
          ]
        }
      }
    ]
  }
}

如果 Agent 没有设置 tools.allow(即使用默认配置),则所有工具自动可用,无需额外配置。

第五步:验证

运行配置检查:

openclaw doctor

然后在 Gateway 中与 Agent 对话验证记忆功能:

# 第一次对话:告诉 AI 一些信息
openclaw agent --message "我喜欢看科幻电影,最近在追三体电视剧"

观察日志:应出现 auto-capture 相关日志

[plugins] openclaw-memory-alibaba-mysql: captured 1new memory

第二次对话:验证 AI 能自动回忆

openclaw agent --message “你还记得我有什么爱好吗?”

观察日志:应出现 auto-recall 相关日志

[plugins] openclaw-memory-alibaba-mysql: injecting N memories into context

关键观察点:

  • auto-recall(自动召回):第二次对话启动时,日志出现 injecting N memories into context,说明记忆插件在 before_agent_start 钩子中成功检索了相关记忆并注入上下文

  • auto-capture(自动捕获):第一次对话结束后,日志出现 captured N new memory,说明插件在 agent_end 钩子中自动从对话中提取了有价值的信息

  • AI 回答中应能提到"科幻电影"和"三体",尽管第二次对话是一个全新的会话

插件工作原理详解
  • npm:openclaw-memory-alibaba-mysql

提供的工具

工具

功能

memory_recall

向量语义搜索历史记忆

memory_store

存储新记忆(带分类、重要性)

memory_forget

删除指定记忆

自动化行为

记忆插件通过两个生命周期钩子实现全自动记忆管理:

**before_agent_start**自动召回

  • 将用户当前消息生成 Embedding

  • 在 MySQL 中向量检索相关历史记忆

  • 将匹配的记忆注入到 AI 上下文中

  • AI 无需调用任何工具即可获得历史背景

**agent_end**自动捕获

  • 分析当前对话中的用户消息

  • 过滤掉过短、无意义的内容

  • 对有价值的信息生成 Embedding

  • 与已有记忆去重(余弦相似度 > 0.95 则跳过)

  • 存入 MySQL 并标注分类(偏好、事实、决策等)

对比:迁移前后

维度

memory-core (本地)

RDS MySQL (云端)

数据位置

~/.openclaw/ 本地文件

阿里云 RDS 实例

跨设备访问

自动备份

❌ 需手动

✅ RDS 自动备份

多 Agent 共享

❌ 各自本地文件

✅ 同一数据库

检索性能

数据量大时下降

HNSW 索引,稳定高效

可观测性

需读本地文件

SQL 直接查询

运维成本

低(但无保障)

中(但有 SLA)

五、整体总结

如有任何问题,可加入钉钉群,群号174405004201,欢迎进群交流!

可以在插件的配置中增加一些开关选项,通过openclaw.json来控制插件的行为。例如,可以设置一个autoInject参数,让用户决定是否自动注入知识。另外,也可以在插件中使用条件判断语句,根据不同的事件类型或上下文信息,执行不同的逻辑。

如果你的Agent是做内容创作的,云端记忆可以帮助它记住用户的偏好和创作风格,从而生成更符合用户口味的内容。例如,一个写小说的Agent,可以记住用户喜欢什么类型的角色、情节和文风。

替换默认记忆系统肯定会对 Agent 性能产生影响,具体影响取决于你使用的插件的实现方式。如果你的插件用了更高效的数据库和算法,那性能可能会提升;反之,如果插件写得不好,或者数据库配置不合理,那性能就可能会下降。所以,在替换之前一定要做好性能测试,确保插件能够满足你的需求。

我之前也遇到过类似的问题,选择钩子确实需要仔细考虑。我的经验是先梳理清楚业务流程,然后对着 OpenClaw 提供的钩子列表,逐个分析哪个钩子最适合你的需求。还要注意钩子之间的优先级,避免冲突。另外,多看官方文档和示例代码,能帮你更好地理解每个钩子的作用。

我同意楼上的观点。数据库的选择主要取决于你的具体需求和技术栈。PostgreSQL和MongoDB都有各自的优势,比如PostgreSQL在事务处理和数据一致性方面更强,而MongoDB则更适合存储非结构化数据。关键在于找到或开发出能够与OpenClaw良好集成的插件。

这个问题问得好!插件冲突确实是个潜在的问题。我理解OpenClaw是按照一定的优先级顺序执行这些钩子的,但具体哪个插件先执行,以及如何处理冲突,文档里好像没细说。感觉需要深入研究一下源码或者做一些实验才能搞清楚。

替换默认记忆系统确实需要谨慎。稳定性和性能肯定是要考虑的,毕竟记忆系统是Agent的核心组件之一。建议在替换之前 thoroughly 测试,并监控新记忆系统的资源消耗和响应时间。另外,要确保新的记忆系统能够兼容OpenClaw的API和数据格式,避免出现 unexpected 的问题。

从安全的角度考虑,默认将所有记忆以 Markdown 和 SQLite 形式存储在本地,如果电脑丢失或者被入侵,这些信息很容易泄露,存在安全隐患。使用 RDS 至少可以利用云厂商的基础安全能力。

从长远来看,如果数据量非常大,而且需要支持复杂的查询和分析,可以考虑使用 ClickHouse。ClickHouse 是一种高性能的列式数据库,擅长处理大规模的数据分析任务。但是,ClickHouse 的部署和维护相对复杂,需要专业的 DBA 支持。而且它可能更适合用于分析记忆,而不是直接用作记忆的存储。

如果让我来设计,我会在 before_llm_call 之前增加一个 before_prompt_rewrite 钩子。这个钩子允许插件在最终的 Prompt 发送给 LLM 之前对其进行修改和润色,可以用于添加一些自定义的格式化规则或者进行 Prompt 优化,提高 LLM 的输出质量。

我比较关注安全,所以会在 after_llm_output 之后增加一个 after_response_validation 钩子。这个钩子可以对 LLM 的回复进行安全审查,比如检测是否存在敏感信息、恶意代码等,确保回复的安全性。

数据管道感觉就像是搭积木,把各个 Agent 的能力串联起来。比如,Agent A 负责从网上抓取数据,然后把数据“扔”到管道里;Agent B 负责对数据进行清洗和分析,然后把结果再“扔”到管道里;Agent C 负责把分析结果展示给用户。每个 Agent 只需要关注自己的任务,不需要关心数据的来源和去向。这种模式可以极大地提高系统的灵活性和可扩展性。

问:OpenClaw 插件机制中的钩子 (Hooks) 数量很多,有没有一些通用的规则或者模式,可以帮助我们更好地选择和使用合适的钩子?

从架构设计的角度,可以考虑使用观察者模式。将 OpenClaw 的生命周期事件视为主题,插件作为观察者,根据自身需求订阅感兴趣的事件(钩子)。关键在于解耦:插件只关注自己需要处理的事件,无需了解整个流程的细节。 此外,可以参考现有的插件示例,学习它们如何使用钩子实现特定功能。例如,openclaw-knowledgebase-fetch-alibaba-mysql 插件使用 before_agent_start 钩子自动注入知识。

问:文章中提到了使用 RDS MySQL 替代默认的 memory-core, 那么在实际应用中,除了高可用和多 Agent 共享之外,使用 RDS 还能带来哪些潜在的好处?

作为一个DBA,必须说一句,用RDS最爽的就是数据分析!你可以直接用SQL查记忆数据,做各种统计分析,这在本地文件上根本没法搞。而且RDS的权限管理也比本地文件系统靠谱多了,安全性更高。

我个人更看好 agent_end 钩子。在Agent推理完成后,可以进行记忆提取、对话归档和错误追踪等操作。这对于持续优化AI应用、积累知识库、提升服务质量至关重要。而且,结合一些数据分析工具,还能挖掘出用户的潜在需求,实现精准营销。就是不知道会不会涉及到用户隐私问题,需要谨慎处理。

从企业级应用的角度来看,使用数据库存储记忆能够更好地满足合规性要求。我们可以对记忆数据进行加密、审计、备份,确保数据的安全性和完整性。这对于金融、医疗等对数据安全有严格要求的行业来说至关重要。而且,有了数据库,我们还可以方便地进行数据迁移和灾备,保证业务的连续性。

换成向量数据库,比如Milvus或者Pinecone,优点是向量检索性能极佳,特别适合处理大规模的知识库。缺点是可能缺乏关系型数据库的事务支持和复杂查询能力,而且生态不如关系型数据库那么完善。如果新闻量非常大,且主要依赖语义搜索,向量数据库会是更好的选择。但如果还需要进行一些其他的关联查询,可能就需要配合关系型数据库一起使用。

我觉得 before_prompt_build 钩子潜力巨大!它允许我们在系统提示词构建之前注入上下文或覆盖提示词,相当于在AI思考之前就给它塞入了关键信息。比如,可以根据用户画像动态调整提示词,实现千人千面的AI交互体验。想象一下,给一个理财小白的提示词里强调风险控制,给一个投资老手的提示词里突出收益最大化,多智能!

从软件工程的角度来看,插件最大的优势在于解耦。它允许开发者在不修改核心代码的情况下,扩展OpenClaw的功能。这样可以降低维护成本,提高系统的可扩展性。如果你的需求涉及到替换OpenClaw的默认行为,比如替换内置记忆系统,那必须用插件。