返回主页OpenClaw × Hy-Memory · Quick Start
Guide

在 OpenClaw 中体验
Hy-Memory 插件

通过 OpenClaw 插件市场一行命令安装，并完成 LLM 与 Embedding 服务配置， 即可让你的 Agent 拥有跨会话的长期记忆能力。

Step 01

概览

Hy-Memory 以 OpenClaw 插件形式分发。插件启动时会拉起一个随插件运行的本地 Python 进程，对外提供记忆读写服务，OpenClaw 通过该进程完成自动召回与自动写入。

Step 02

前置条件

  • OpenClaw CLI

    已在本机安装并可执行 openclaw 命令，建议更新到最新版本以获得更好体验。

  • Python 运行环境

    Python >= 3.8。插件依赖 Python，将以子进程形式拉起 hy-memory 服务。

  • LLM 服务

    已申请可用的 LLM API Key，示例使用 Hunyuan 3.0 Preview（通过 OpenRouter 调用）。

  • Embedding 服务

    已申请可用的 Embedding API Key，示例使用 SiliconFlow 提供的 BAAI/bge-m3 模型。

Step 03

安装插件

使用 OpenClaw 插件管理命令完成安装。老用户需要先卸载已有版本，再执行带 force flag 的全新安装。

bash
# 老用户需要先卸载
openclaw plugins uninstall openclaw-hy-memory

# 全新安装
openclaw plugins install openclaw-hy-memory --dangerously-force-unsafe-install
为什么必须加 --dangerously-force-unsafe-install ?
目前 Hy-Memory 以 Python 子进程的方式随插件启动来提供服务。 OpenClaw 出于安全考虑默认拒绝安装会启动外部进程的插件， 因此需要显式加上该参数以确认你知晓并允许此行为。
Step 04

初始化配置（推荐）

运行 init 命令，按交互式提示输入 LLM 与 Embedding 服务的 model、apiKey、endpoint，插件会自动写入配置文件。

bash
openclaw hy-memory init
跟随提示即可
首次接入推荐使用 init 流程，能避免手写 JSON 时的格式错误。 如需调整参数（如 topK、autoRecall 等），可后续直接编辑配置文件。
Step 05

手动配置（可选）

如已熟悉配置结构，也可直接在 OpenClaw 插件配置文件中加入以下片段。下方示例使用 Hunyuan 3.0 Preview（通过 OpenRouter 调用）作为 LLM、SiliconFlow 提供的 BAAI/bge-m3 作为 Embedding。

json
"openclaw-hy-memory": {
  "enabled": true,
  "config": {
    "userId": "tom001",
    "autoRecall": true,
    "autoCapture": true,
    "topK": 10,
    "llm": {
      "provider": "openai",
      "model": "tencent/hy3-preview",
      "apiKey": "YOUR_OPENROUTER_API_KEY",
      "baseUrl": "https://openrouter.ai/api/v1"
    },
    "embedder": {
      "provider": "openai",
      "model": "BAAI/bge-m3",
      "apiKey": "YOUR_SILICONFLOW_API_KEY",
      "baseUrl": "https://api.siliconflow.cn/v1",
      "dims": 1024
    },
    "vectorStore": {
      "provider": "chroma"
    }
  }
}
为什么用 OpenRouter？
Hunyuan 3.0 Preview（tencent/hy3-preview）已上架 OpenRouter， 开箱即用且兼容 OpenAI 协议，最适合快速体验。也可替换为腾讯云托管 API 或本地 vLLM/SGLang 部署的 endpoint。
关于 Embedding 选型
示例使用 SiliconFlow 的 BAAI/bge-m3（OpenAI 兼容协议，输出 1024 维）。 如需改用其他服务（如 OpenAI、阿里 DashScope、本地模型），保持 provider 为openai并替换 model / baseUrl / dims 即可。
Step 06

配置字段说明

字段路径类型必填默认值说明
enabledboolean必填false插件总开关。设为 true 时插件生效。
config.userIdstring必填—用户唯一标识，Hy-Memory 以此区分不同用户的记忆数据。
config.autoRecallboolean可选true是否在每次对话开始前自动召回相关历史记忆作为上下文。
config.autoCaptureboolean可选true是否在每次对话结束后自动抽取与写入新的记忆条目。
config.topKnumber可选10每次召回的相关记忆条目最大数量。
config.llm.providerstring必填—LLM 服务提供方，目前支持 openai 兼容协议。
config.llm.modelstring必填—LLM 模型名称，例如 deepseek-chat。
config.llm.apiKeystring必填—LLM 服务的 API Key。
config.llm.baseUrlstring必填—LLM 服务的 API 端点 URL。
config.embedder.providerstring必填—Embedding 服务提供方，支持 openai 兼容协议。
config.embedder.modelstring必填—Embedding 模型名称，例如 text-embedding-v3。
config.embedder.apiKeystring必填—Embedding 服务的 API Key。
config.embedder.baseUrlstring必填—Embedding 服务的 API 端点 URL。
config.embedder.dimsnumber必填—Embedding 向量维度，需与所选模型保持一致。
config.vectorStore.providerstring可选chroma向量库实现。默认使用 chroma（随插件本地启动，无需额外部署）。
Step 07

重启网关

配置完成后，执行以下命令重启 OpenClaw 网关，Hy-Memory 即可开始为你的 Agent 服务。

bash
openclaw gateway restart
Step 08

验证安装

网关重启后，执行 status 命令检查 Hy-Memory 是否成功注册并连接。看到类似下方的输出即表示插件已就绪。

bash
openclaw hy-memory status
text
 [plugins] openclaw-hy-memory: registered (user: tom001, server: http://127.0.0.1:19527, autoRecall: true, autoCapture: true)

OpenClaw 2026.5.26 (10ad3aa) — Built by lobsters, for humans. Don't question the hierarchy.

HY Memory Server: http://127.0.0.1:19527
  Status:      ✓ healthy
  User ID:     tom001
  VDB:         ok [chroma] (collection: agent_memories_1024, points: 0)
  Embed:       ok (dims: 1024)
  LLM:         ok
  SDK Version: 1.2.5
关键字段含义
  • registered：插件已被 OpenClaw 网关识别并加载。
  • Status: ✓ healthy：Hy-Memory 服务整体健康，所有依赖检查均通过。
  • VDB：向量数据库连接状态。示例中使用本地 chroma，已建立agent_memories_1024集合。
  • Embed / LLM：Embedding 与 LLM 服务可达性检查；dims需与配置一致。
  • User ID / SDK Version：当前生效的 userId 与 SDK 版本，确认与配置和预期一致。