OpenClaw Memory 插件完全指南：从理论到实践

版本: 1.0
最后更新: 2026-04-09
适用版本: OpenClaw 2026.4.2+
作者: AI-Note Community
状态: ✅ 生产环境验证

📊 执行摘要

OpenClaw 提供 5 种 memory 插件方案，每种适用于不同场景。本文基于真实生产环境部署（4 个 Docker 容器 + 多 Telegram Bot），提供从理论对比到实践部署的完整指南。

快速推荐

用户类型	推荐方案	理由
🟢 新手/个人使用	Memory Core	简单、稳定、无依赖
🟡 需要更强检索	Memory Core + QMD	Reranking 提升 8%
🟠 企业/多 Agent	Memory Core + Honcho	跨会话 + 用户建模
🔴 完全自动化	LanceDB Pro	自动捕获 + 智能遗忘

5 种插件对比总览

插件	推荐度	检索质量	响应时间	内存占用	难度
Memory Core	⭐⭐⭐⭐⭐	0.72 (基线)	~50ms	~50MB	简单
QMD	⭐⭐⭐⭐	0.78 (+8%)	~500ms	~500MB	中等
Honcho	⭐⭐⭐⭐	0.74 (+3%)	~150ms	~100MB	中等
LanceDB Pro	⭐⭐⭐⭐	0.82 (+15%)	~150ms	~200MB	复杂
LanceDB 基础	⭐⭐	0.70 (-3%)	~100ms	~150MB	中等

🔍 插件详细对比

1. Memory Core (Builtin) - 默认推荐 ⭐⭐⭐⭐⭐

插件名称: memory-core
状态: ✅ 内置（默认启用）
生产验证: ✅ 已在 4 容器部署中稳定运行

核心特性

特性	说明
存储格式	Markdown 文件（人类可读）✅
索引后端	SQLite + FTS5 + sqlite-vec
搜索方式	混合搜索（向量 + 关键词）
工具	`memory_search`, `memory_get`
自动索引	✅ 1.5s 防抖
依赖	无

生产环境配置示例

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "ollama",
        "sync": {
          "watch": true,
          "watchDebounceMs": 1500
        },
        "query": {
          "maxResults": 8,
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4,
            "mmr": {
              "enabled": true,
              "lambda": 0.7
            }
          }
        }
      }
    }
  }
}

优点 ✅

开箱即用，无需额外依赖
Markdown 文件人类可读、可编辑、可版本控制
支持所有 embedding provider
混合搜索效果好（Recall@5 = 0.72）
CJK（中日韩）支持良好
生产验证：在多容器部署中稳定运行

缺点 ❌

无 reranking（重排序）
无法索引 workspace 外文件
无会话转录索引
手动写入记忆（无自动捕获）

适用场景

✅ 推荐使用：

个人知识库管理
长期记忆存储
需要人类可读的记忆文件
简单部署（无额外依赖）
多容器/Docker 部署（已验证）

❌ 不推荐：

需要搜索项目文档（workspace 外）
需要会话历史检索
需要 reranking 提升检索质量
完全自动化需求

2. QMD Memory Engine - 增强检索 ⭐⭐⭐⭐

插件名称: qmd (通过 memory.backend 配置)
状态: ✅ 官方支持

核心特性

特性	说明
存储格式	Markdown 文件 + QMD 索引
索引后端	QMD Sidecar (Bun + node-llama-cpp)
搜索方式	BM25 + 向量 + Rerank
工具	`memory_search`, `memory_get`
自动索引	✅ 5 分钟周期更新
依赖	QMD binary (~2GB GGUF 模型)

配置示例

{
  "memory": {
    "backend": "qmd",
    "qmd": {
      "paths": [
        {
          "name": "docs",
          "path": "~/notes",
          "pattern": "**/*.md"
        }
      ],
      "sessions": {
        "enabled": true
      }
    }
  }
}

优点 ✅

Reranking 提升检索质量 (+8%)
Query Expansion 查询扩展
可索引 workspace 外文件
可索引会话转录
完全本地运行（无 API Key）
自动 fallback 到 Builtin

缺点 ❌

需要安装 QMD binary
首次搜索慢（下载 ~2GB 模型）
配置复杂度增加
占用更多磁盘空间和内存 (~500MB)

适用场景

✅ 推荐使用：

需要搜索项目文档
需要会话历史检索
需要更高检索质量（rerank）
完全本地化部署

❌ 不推荐：

简单个人使用
磁盘空间有限
不想安装额外依赖

3. Honcho Memory - 跨会话记忆 ⭐⭐⭐⭐

插件名称: @honcho-ai/openclaw-honcho
状态: ✅ 第三方插件（官方推荐）

核心特性

特性	说明
存储格式	Honcho Service (本地或云端)
索引后端	Honcho 专用数据库
搜索方式	语义搜索 + 用户建模
工具	`honcho_context`, `honcho_ask`, `honcho_search_*`
自动捕获	✅ 每轮对话后持久化
依赖	Honcho 插件 + Service

配置示例

{
  "plugins": {
    "entries": {
      "openclaw-honcho": {
        "config": {
          "apiKey": "your-api-key",
          "workspaceId": "openclaw",
          "baseUrl": "https://api.honcho.dev"
        }
      }
    }
  }
}

优点 ✅

跨会话记忆 自动持久化
用户建模 自动维护用户画像
多 Agent 感知 父子 Agent 追踪
可与 Memory Core 共存
支持自托管

缺点 ❌

需要额外插件安装
需要 Honcho Service（本地或云端）
学习曲线较陡
与 Markdown 文件不同步

适用场景

✅ 推荐使用：

多 Agent 协作场景
需要跨会话记忆
需要用户建模
企业级部署

❌ 不推荐：

单 Agent 简单使用
不想维护额外服务
偏好 Markdown 文件

4. LanceDB Pro Memory - 自动捕获 + 高性能检索 ⭐⭐⭐⭐

插件名称: memory-lancedb-pro
状态: ✅ 社区插件（活跃维护）
官方文档: https://github.com/CortexReach/memory-lancedb-pro

核心特性

特性	说明
存储格式	LanceDB 向量数据库
索引后端	LanceDB + FTS5 + Cross-Encoder
搜索方式	向量 + BM25 + Rerank (RRF 融合)
工具	`memory_recall`, `memory_store`, `memory_forget`, `memory-pro` CLI
自动捕获	✅ autoCapture + smartExtraction (LLM 6 分类)
自动遗忘	✅ Weibull 衰减模型
依赖	LanceDB binary + Node.js + AVX/AVX2 CPU

配置示例

{
  "plugins": {
    "slots": {
      "memory": "memory-lancedb-pro"
    },
    "entries": {
      "memory-lancedb-pro": {
        "enabled": true,
        "config": {
          "embedding": {
            "provider": "openai-compatible",
            "apiKey": "${OPENAI_API_KEY}",
            "model": "text-embedding-3-small"
          },
          "autoCapture": true,
          "autoRecall": true,
          "smartExtraction": true,
          "extractMinMessages": 2,
          "extractMaxChars": 8000,
          "retrieval": {
            "mode": "hybrid",
            "vectorWeight": 0.7,
            "bm25Weight": 0.3,
            "candidatePoolSize": 12,
            "minScore": 0.6,
            "hardMinScore": 0.62
          },
          "rerank": {
            "enabled": true,
            "provider": "jina",
            "model": "jina-reranker-v2-base-multilingual"
          },
          "sessionMemory": {
            "enabled": false
          }
        }
      }
    }
  }
}

优点 ✅

自动捕获 - 无需手动 memory_store，从对话自动学习
智能提取 - LLM 驱动的 6 类别分类
智能遗忘 - Weibull 衰减模型，重要记忆保留，噪音自然消失
混合检索 - Vector + BM25 + Cross-Encoder Rerank (+15% 质量提升)
多范围隔离 - Per-agent/per-user/per-project 记忆边界
完整工具链 - CLI, backup, migration, export/import
任何 Provider - OpenAI, Jina, Gemini, Ollama 等

缺点 ❌

不存储 Markdown - LanceDB 二进制存储，人类不可读
CPU 要求 - 需要 AVX/AVX2 指令集 (2011+ CPU)
与 Memory Core 互斥 - 不能同时使用
不与 Markdown 同步 - MEMORY.md 内容不会被 memory_recall 检索
复杂度 - 配置参数多，学习曲线陡
依赖多 - 需要 LanceDB binary + Node.js

适用场景

✅ 推荐使用：

需要完全自动化的记忆捕获
不需要人类可读的记忆文件
需要高性能混合检索
需要智能遗忘机制

❌ 不推荐：

需要 Markdown 文件（人类可读）
需要手动编辑记忆
CPU 不支持 AVX/AVX2
简单个人使用

⚠️ 重要警告：双重记忆层不同步

当 memory-lancedb-pro 激活时，系统有两个独立的记忆层：

记忆层	存储	用途	可检索？
Plugin Memory	LanceDB	`memory_recall` / auto-recall	✅
Markdown Memory	`MEMORY.md`, `memory/*.md`	启动上下文，人类可读日记	❌

关键原则：

写入 memory/YYYY-MM-DD.md 的事实会在启动时可见，但 memory_recall 不会找到它，除非它也是通过 memory_store 写入或被插件自动捕获的。

这意味着：

✅ 需要语义检索？→ 使用 memory_store 或让 auto-capture 完成
📔 memory/YYYY-MM-DD.md → 视为日记/日志，不是检索源
📖 MEMORY.md → 人类可读参考，不是检索源
🧠 Plugin memory → memory_recall 和 auto-recall 的主要检索源

5. LanceDB (基础版) - 简单向量存储 ⭐⭐

插件名称: memory-lancedb
状态: ⚠️ 官方基础版（功能有限）

与 LanceDB Pro 的区别

特性	基础版	Pro 版
混合检索	❌	✅ Vector + BM25
Rerank	❌	✅ Cross-Encoder
智能提取	❌	✅ LLM 6 分类
智能遗忘	❌	✅ Weibull 衰减
CLI 工具	基础	完整
维护状态	⚠️ 缓慢	✅ 活跃

推荐: 直接使用 LanceDB Pro，基础版功能有限且不活跃维护。

📈 性能对比（生产环境数据）

检索质量 benchmark（基于 LOCOMO 数据集）

插件	Recall@5	Recall@10	MRR	提升
Memory Core	0.72	0.81	0.65	基线
QMD	0.78	0.86	0.71	+8%
LanceDB Pro	0.82	0.89	0.75	+15% ⭐
LanceDB (基础)	0.70	0.79	0.63	-3%
Honcho	0.74	0.83	0.67	+3%

数据来源：https://www.lancedb.com/blog/openclaw-memory-from-zero-to-lancedb-pro

关键发现：

LanceDB Pro 的 Cross-Encoder Rerank 提升最显著 (+15%)
QMD 的 reranking 也有显著提升 (+8%)
Memory Core 作为基线已经提供 90% 的效果
LanceDB 基础版无 rerank，效果略差于 Memory Core

响应时间对比（生产环境）

插件	首次搜索	后续搜索	索引更新	内存占用
Memory Core	~100ms	~50ms	1.5s (防抖)	~50MB ⭐
QMD	~5s*	~500ms	5min 周期	~500MB
LanceDB Pro	~300ms	~150ms	实时	~200MB
LanceDB (基础)	~200ms	~100ms	实时	~150MB
Honcho	~300ms	~150ms	每轮对话	~100MB

*QMD 首次搜索需要下载 GGUF 模型（~2GB）

关键发现：

Memory Core 最快且最轻量
LanceDB Pro 因 rerank 增加 ~100ms 延迟
QMD 首次搜索慢（模型下载），后续正常

🎯 生产环境部署案例

案例：4 容器多 Agent 部署

场景：个人开发者，需要多个专用 Agent 处理不同任务

架构设计

宿主机 (macOS)
├── Main Agent (native) - 协调中心
│   └── Port: 18789
│
Docker Containers:
├── hermes (port 9996) - Hermes 项目 AI 编程
├── coding (port 9997) - GitHub/PR 管理
├── alone (port 9998) - 独立任务
└── stock (port 9999) - 股票监控

Telegram Bots:
├── @one_hope_hermes_bot (hermes)
├── @one_asset_coding_bot (coding)
├── @one_asset_alone_bot (alone)
└── @one_asset_bot (stock)

容器配置

容器	端口	挂载卷	Telegram Bot	职责
hermes	9996	`~/.openclaw-hermes`	`@one_hope_hermes_bot`	AI 编程
coding	9997	`~/.openclaw-coding`	`@one_asset_coding_bot`	GitHub
alone	9998	`~/.openclaw-alone`	`@one_asset_alone_bot`	独立任务
stock	9999	`~/.openclaw-stock`	`@one_asset_bot`	股票监控

记忆架构决策

选择: Memory Core (所有容器)

理由:

✅ Markdown 文件人类可读、可编辑
✅ 无额外依赖，容器启动快
✅ 每个容器独立 SQLite 数据库
✅ 低内存占用 (~50MB/容器)
✅ 配置简单，维护成本低

配置 (所有容器相同):

{
  "agents": {
    "defaults": {
      "memorySearch": {
        "enabled": true,
        "provider": "ollama",
        "sync": {
          "watch": true,
          "watchDebounceMs": 1500
        }
      }
    }
  }
}

环境配置管理

最佳实践: 使用 ~/.env 集中管理所有密钥

# ~/.env (权限 600)

# AI Model Providers
BAILIAN_API_KEY=sk-sp-xxxxxxxxxxxx
OLLAMA_BASE_URL=http://127.0.0.1:11434/v1

# Telegram Bot Tokens
TELEGRAM_CORE_BOT_TOKEN=[TELEGRAM_CORE_TOKEN_REDACTED]...
TELEGRAM_CODING_BOT_TOKEN=[TELEGRAM_CODING_TOKEN_REDACTED]...
TELEGRAM_STOCK_BOT_TOKEN=[TELEGRAM_STOCK_TOKEN_REDACTED]...
TELEGRAM_HERMES_BOT_TOKEN=[TELEGRAM_HERMES_TOKEN_REDACTED]...

# GitHub
GH_TOKEN=[GITHUB_TOKEN_REDACTED]

# OpenClaw Gateway
GATEWAY_AUTH_TOKEN=4fc9d7ebcc3d406503f41be97352cc214b56dcc55d8c4e72

# Proxy
HTTP_PROXY=http://127.0.0.1:7897
HTTPS_PROXY=http://127.0.0.1:7897

# Container Ports
HERMES_PORT=9996
CODING_PORT=9997
ALONE_PORT=9998
STOCK_PORT=9999

# User
TELEGRAM_USER_ID=5520269161
TZ=Asia/Shanghai

安全: chmod 600 ~/.env

⚠️ 生产环境教训（血泪经验）

1. Docker 卷安全

问题: 删除运行中容器的卷目录导致配置丢失

# ❌ 错误操作
docker rm stock
rm -rf ~/.openclaw-stock  # 如果容器还在运行，配置会丢失！

# ✅ 正确操作
docker stop stock
docker rm stock
# 备份后再删除
cp -r ~/.openclaw-stock ~/backups/
rm -rf ~/.openclaw-stock

教训: 永远不要在容器运行时删除卷目录！

2. Telegram Bot 冲突

问题: 同一个 Bot Token 在多个实例运行

错误日志:
409: Conflict: terminated by other getUpdates request;
make sure that only one bot instance is running

原因: Telegram 不允许同一个 bot 在多处同时 polling

解决方案:

✅ 每个容器使用独立的 Bot Token
✅ 或者只在一个实例中启用 Telegram

生产配置:

Main Agent (native): @one_asset_core_bot
Hermes Container:    @one_hope_hermes_bot
Coding Container:    @one_asset_coding_bot
Stock Container:     @one_asset_bot

3. Gateway Auth 模式错误

问题: 使用了无效的 auth mode

// ❌ 错误配置
{
  "gateway": {
    "auth": {
      "mode": "disabled"  // 无效值！
    }
  }
}

// ✅ 正确配置
{
  "gateway": {
    "auth": {
      "mode": "token",
      "token": "hope"
    }
  }
}

有效值: none, token, password, trusted-proxy

错误日志:

Invalid config at /home/node/.openclaw/openclaw.json:
- gateway.auth.mode: Invalid input
(allowed: "none", "token", "password", "trusted-proxy")

4. Memory Core vs LanceDB 决策

问题: 是否需要切换到 LanceDB Pro？

分析:

维度	Memory Core	LanceDB Pro	结论
检索质量	0.72	0.82 (+15%)	LanceDB 胜
响应时间	~50ms	~150ms	Memory Core 快 3 倍
人类可读	✅	❌	Memory Core 胜
自动捕获	❌	✅	LanceDB 胜
内存占用	~50MB	~200MB	Memory Core 轻 4 倍
配置复杂度	简单	复杂	Memory Core 胜

决策: 继续使用 Memory Core

理由:

✅ Markdown 文件人类可读、可编辑
✅ 无额外依赖，稳定性高
✅ 最快响应时间 (~50ms)
✅ 最低内存占用 (~50MB)
✅ 检索质量已满足 90% 需求
✅ 已配置好 Ollama embedding

LanceDB Pro 仅适用于:

需要完全自动化记忆捕获
不需要人类可读记忆文件
需要最高检索质量 (+15%)
CPU 支持 AVX/AVX2 (2011+)

🎯 最佳实践总结

1. 文件组织

workspace/
├── MEMORY.md              # 长期记忆（持久化事实、偏好、决策）
├── AGENTS.md              # Agent 行为规则
├── SOUL.md                # Agent 人格定义
├── TOOLS.md               # 工具配置
├── memory/
│   ├── YYYY-MM-DD.md      # 每日笔记（自动加载今天 + 昨天）
│   ├── projects/          # 项目相关记忆
│   ├── knowledge/         # 知识点整理
│   └── reference/         # 参考资料
└── DREAMS.md              # （可选）梦境日记

2. 混合搜索调优

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "enabled": true,
        "vectorWeight": 0.7,    // 70% 语义相似度
        "textWeight": 0.3,      // 30% 关键词匹配
        "candidateMultiplier": 4, // 扩大搜索池（关键！）
        "mmr": {                // 最大边际相关性
          "enabled": true,
          "lambda": 0.7         // 多样性权重
        },
        "temporalDecay": {      // 时间衰减
          "enabled": true,
          "halfLifeDays": 30    // 30 天半衰期
        }
      }
    }
  }
}

关键参数:

candidateMultiplier: 设置为 4 可显著提升结果质量
mmr.lambda: 0.7 平衡相关性和多样性
halfLifeDays: 30 天让新记忆优先级更高

3. Embedding Provider 选择

Provider	自动检测	成本	质量	推荐场景
`ollama`	❌	免费	⭐⭐⭐	本地部署、隐私敏感
`gemini`	✅	免费额度足	⭐⭐⭐⭐	默认推荐
`openai`	✅	$0.02/1K tokens	⭐⭐⭐⭐⭐	生产环境
`voyage`	✅	中等	⭐⭐⭐⭐⭐	专业检索
`mistral`	✅	中等	⭐⭐⭐⭐	欧洲服务器

推荐配置:

{
  "memorySearch": {
    "provider": "gemini",
    "model": "gemini-embedding-001"
  }
}

4. 三个关键实践

✅ 实践 1：把持久化规则写入文件，而不是聊天

# MEMORY.md

## 用户偏好
- 偏好 TypeScript 而非 JavaScript
- 喜欢简洁的代码风格
- 工作时间：9:00-18:00 (Asia/Shanghai)

## 重要规则
- 执行批量操作前必须获得明确批准
- 删除文件前必须确认
- 敏感信息必须加密存储

为什么: 聊天中的指令在 compaction 后会丢失，文件中的规则永久保存。

✅ 实践 2：确保 memory flush 已启用

检查配置:

{
  "agents": {
    "defaults": {
      "contextPruning": {
        "mode": "cache-ttl",
        "ttl": "5m"
      }
    }
  }
}

为什么: OpenClaw 在 compaction 前有安全网，但需要足够缓冲触发。

✅ 实践 3：强制检索

在 AGENTS.md 中添加:

## 记忆使用规则

1. **搜索记忆后再行动** - 执行任何操作前必须调用 `memory_search`
2. **记录重要决策** - 每个重要决定必须写入 `MEMORY.md`
3. **每日总结** - 每天结束时总结关键信息到当日笔记

为什么: 避免 AI 猜测而不是查阅笔记。

🔧 故障排查

问题 1：记忆搜索不工作

症状: memory_search 返回空结果

排查步骤:

# 1. 检查索引状态
openclaw memory status

# 2. 检查 provider 配置
openclaw config get agents.defaults.memorySearch

# 3. 手动重建索引
openclaw memory index --force

# 4. 查看日志
openclaw logs --follow --plain | grep memory

常见原因:

❌ 未配置 embedding provider
❌ 索引未建立
❌ 文件路径不正确

问题 2：搜索结果不相关

症状: memory_search 返回不相关内容

解决方案:

{
  "memorySearch": {
    "query": {
      "hybrid": {
        "candidateMultiplier": 4,  // 扩大候选池
        "mmr": {
          "enabled": true,        // 启用多样性
          "lambda": 0.7
        }
      },
      "maxResults": 8              // 增加返回数量
    }
  }
}

问题 3：记忆在 compaction 后丢失

症状: 长对话后 AI 忘记之前的指令

根本原因: 指令只存在于聊天中，未写入文件

解决方案:

将重要规则写入 MEMORY.md 或 AGENTS.md
启用 memory flush
使用 memory_get 主动读取记忆

问题 4：Docker 容器 Telegram 冲突

症状:

409: Conflict: terminated by other getUpdates request;
make sure that only one bot instance is running

解决方案:

为每个容器创建独立的 Telegram Bot
或者只在一个容器中启用 Telegram
检查是否有重复的 bot token

📊 配置检查清单

Memory Core 配置

memorySearch.enabled: true
memorySearch.provider 已配置（或使用自动检测）
sync.watch: true（自动索引）
sync.watchDebounceMs: 1500（防抖）
query.maxResults: 8（返回数量）
query.hybrid.enabled: true（混合搜索）
query.hybrid.candidateMultiplier: 4（扩大候选池）

Docker 部署配置

每个容器独立的 Bot Token
每个容器独立的卷目录 (~/.openclaw-*)
端口不冲突 (9996, 9997, 9998, 9999)
Gateway auth mode 正确 (token)
容器健康检查启用

环境安全

~/.env 权限 600
API keys 未提交到版本控制
Docker secrets 用于敏感配置
定期轮换 Bot Token

🎓 学习资源

官方文档

社区资源

GitHub Repos

openclaw/openclaw - 主仓库
CortexReach/memory-lancedb-pro - LanceDB Pro 插件
plastic-labs/openclaw-honcho - Honcho 插件
tobi/qmd - QMD 搜索引擎

📝 版本历史

版本	日期	更新内容
1.0	2026-04-09	初始版本，基于生产环境 4 容器部署验证

📧 反馈与贡献

本文档基于真实生产环境经验编写。欢迎贡献：

📝 提交 PR 到 ai-note
💬 在 OpenClaw Discord 社区讨论
🐛 报告问题或分享经验

本文档遵循 MIT 许可证。

附录 A: 完整配置示例

{
  "agents": {
    "defaults": {
      "model": "bailian/qwen3.5-plus",
      "memorySearch": {
        "enabled": true,
        "provider": "ollama",
        "sync": {
          "watch": true,
          "watchDebounceMs": 1500
        },
        "query": {
          "maxResults": 8,
          "hybrid": {
            "enabled": true,
            "vectorWeight": 0.7,
            "textWeight": 0.3,
            "candidateMultiplier": 4,
            "mmr": {
              "enabled": true,
              "lambda": 0.7
            },
            "temporalDecay": {
              "enabled": true,
              "halfLifeDays": 30
            }
          }
        }
      },
      "maxConcurrent": 4,
      "subagents": {
        "maxConcurrent": 8
      }
    },
    "list": [
      {
        "id": "main",
        "workspace": "/Users/hope/.openclaw/agents/main/workspace",
        "heartbeat": {
          "every": "4h",
          "activeHours": {
            "start": "08:00",
            "end": "23:00",
            "timezone": "Asia/Shanghai"
          },
          "target": "telegram",
          "to": "5520269161"
        }
      }
    ]
  },
  "channels": {
    "telegram": {
      "enabled": true,
      "dmPolicy": "pairing",
      "groupPolicy": "allowlist",
      "proxy": "http://host.docker.internal:7897",
      "accounts": {
        "core": {
          "dmPolicy": "pairing",
          "botToken": "[TELEGRAM_CORE_TOKEN_REDACTED]",
          "allowFrom": [5520269161],
          "groupPolicy": "allowlist"
        }
      }
    }
  },
  "gateway": {
    "port": 18789,
    "bind": "0.0.0.0",
    "auth": {
      "mode": "token",
      "token": "your-gateway-token"
    }
  },
  "models": {
    "providers": {
      "bailian": {
        "baseUrl": "https://coding.dashscope.aliyuncs.com/v1",
        "apiKey": "sk-sp-xxxxxxxxxxxx",
        "api": "openai-completions"
      }
    }
  },
  "plugins": {
    "entries": {
      "telegram": {
        "enabled": true
      },
      "brave": {
        "enabled": true,
        "config": {
          "webSearch": {
            "apiKey": "BSAvz5qVl_e9NBYmxURAWXmOAm42_GZ"
          }
        }
      }
    }
  }
}

附录 B: Docker Compose 示例

version: '3.8'

services:
  hermes:
    image: ghcr.io/openclaw/openclaw:2026.4.2
    container_name: hermes
    ports:
      - "9996:18789"
    volumes:
      - ~/.openclaw-hermes:/home/node/.openclaw
    environment:
      - OPENCLAW_GATEWAY_PORT=18789
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_HERMES_BOT_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/"]
      interval: 30s
      timeout: 10s
      retries: 3

  coding:
    image: ghcr.io/openclaw/openclaw:2026.4.2
    container_name: coding
    ports:
      - "9997:18789"
    volumes:
      - ~/.openclaw-coding:/home/node/.openclaw
    environment:
      - OPENCLAW_GATEWAY_PORT=18789
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_CODING_BOT_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/"]
      interval: 30s
      timeout: 10s
      retries: 3

  stock:
    image: ghcr.io/openclaw/openclaw:2026.4.2
    container_name: stock
    ports:
      - "9999:18789"
    volumes:
      - ~/.openclaw-stock:/home/node/.openclaw
    environment:
      - OPENCLAW_GATEWAY_PORT=18789
      - TELEGRAM_BOT_TOKEN=${TELEGRAM_STOCK_BOT_TOKEN}
    restart: unless-stopped
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:18789/"]
      interval: 30s
      timeout: 10s
      retries: 3

完

FilesExpand file tree

memory-plugins-complete-guide.md

Latest commit

History

memory-plugins-complete-guide.md

File metadata and controls

OpenClaw Memory 插件完全指南：从理论到实践

📊 执行摘要

快速推荐

5 种插件对比总览

🔍 插件详细对比

1. Memory Core (Builtin) - 默认推荐 ⭐⭐⭐⭐⭐

核心特性

生产环境配置示例

优点 ✅

缺点 ❌

适用场景

2. QMD Memory Engine - 增强检索 ⭐⭐⭐⭐

核心特性

配置示例

优点 ✅

缺点 ❌

适用场景

3. Honcho Memory - 跨会话记忆 ⭐⭐⭐⭐

核心特性

配置示例

优点 ✅

缺点 ❌

适用场景

4. LanceDB Pro Memory - 自动捕获 + 高性能检索 ⭐⭐⭐⭐

核心特性

配置示例

优点 ✅

缺点 ❌

适用场景

⚠️ 重要警告：双重记忆层不同步

5. LanceDB (基础版) - 简单向量存储 ⭐⭐

与 LanceDB Pro 的区别

📈 性能对比（生产环境数据）

检索质量 benchmark（基于 LOCOMO 数据集）

响应时间对比（生产环境）

🎯 生产环境部署案例

案例：4 容器多 Agent 部署

架构设计

容器配置

记忆架构决策

环境配置管理

⚠️ 生产环境教训（血泪经验）

1. Docker 卷安全

2. Telegram Bot 冲突

3. Gateway Auth 模式错误

4. Memory Core vs LanceDB 决策

🎯 最佳实践总结

1. 文件组织

2. 混合搜索调优

3. Embedding Provider 选择

4. 三个关键实践

✅ 实践 1：把持久化规则写入文件，而不是聊天

✅ 实践 2：确保 memory flush 已启用

✅ 实践 3：强制检索

🔧 故障排查

问题 1：记忆搜索不工作

问题 2：搜索结果不相关

问题 3：记忆在 compaction 后丢失

问题 4：Docker 容器 Telegram 冲突

📊 配置检查清单

Memory Core 配置

Docker 部署配置

环境安全

🎓 学习资源

官方文档

社区资源

GitHub Repos

📝 版本历史

📧 反馈与贡献