OpenClaw 记忆系统配置完全指南：从零搭建智能体长期记忆
结论先行
OpenClaw 的记忆系统是其区别于普通 AI 助手的核心能力。通过三层记忆架构（工作区文件 + 向量索引 + 语义搜索），你可以让智能体拥有真正的长期记忆——记住你的偏好、项目上下文、甚至几个月前的对话细节。本文将提供三套可落地的配置方案，覆盖从个人用户到企业级部署的完整场景。
一、核心概念：OpenClaw 记忆系统如何工作
1.1 三层记忆架构
| 层级 | 存储位置 | 用途 | 持久性 |
|---|---|---|---|
| 短期记忆 | 会话上下文 | 当前对话流 | 会话结束即丢失 |
| 日记忆 | memory/YYYY-MM-DD.md |
每日日志、临时笔记 | 永久存储 |
| 长期记忆 | MEMORY.md |
核心偏好、重要决策 | 永久存储 |
关键洞察：OpenClaw 的记忆本质是纯 Markdown 文件。智能体只能”记住”写入磁盘的内容——没有文件，就没有记忆。
1.2 记忆工作流程
用户对话 → 智能体判断 → 写入 memory/ 或 MEMORY.md → 向量索引更新 → 语义搜索可用自动记忆刷新机制：当会话接近压缩阈值时，OpenClaw 会自动触发静默回合，提醒智能体在上下文被压缩前写入持久记忆。
二、基础配置：5 分钟快速上手
2.1 工作区目录结构
~/.openclaw/workspace/
├── AGENTS.md # 智能体行为指南
├── SOUL.md # 智能体人格设定
├── USER.md # 用户信息
├── IDENTITY.md # 智能体身份
├── TOOLS.md # 本地工具笔记
├── MEMORY.md # 长期记忆（核心）
├── HEARTBEAT.md # 心跳任务清单
└── memory/ # 日记忆目录
├── 2026-03-26.md
├── 2026-03-25.md
└── ...2.2 最小可用配置
编辑 ~/.openclaw/openclaw.json：
{
"agents": {
"defaults": {
"workspace": "~/.openclaw/workspace",
"memorySearch": {
"enabled": true,
"provider": "gemini", // 或 "openai"
"model": "gemini-embedding-001",
"remote": {
"apiKey": "${GEMINI_API_KEY}"
}
}
}
}
}环境变量设置（添加到 ~/.zshrc 或 ~/.bashrc）：
export GEMINI_API_KEY="your-gemini-api-key"
# 或
export OPENAI_API_KEY="your-openai-api-key"2.3 验证配置
# 检查记忆系统状态
openclaw config get memory
# 测试记忆搜索（在对话中）
# 输入："记住我喜欢用 Go 语言写后端"
# 然后问："我之前说过喜欢用什么语言？"三、进阶配置：三种生产级方案
方案 A：本地优先（隐私敏感场景）
适用场景：企业内网、隐私敏感数据、无互联网环境
{
"agents": {
"defaults": {
"memorySearch": {
"enabled": true,
"provider": "local",
"local": {
"modelPath": "hf:ggml-org/embeddinggemma-300m-qat-q8_0-GGUF/embeddinggemma-300m-qat-Q8_0.gguf",
"modelCacheDir": "~/.openclaw/models"
},
"fallback": "none" // 禁用远程回退
}
}
}
}安装步骤：
# 1. 安装依赖
pnpm approve-builds
# 选择 node-llama-cpp
# 2. 重建原生模块
pnpm rebuild node-llama-cpp
# 3. 首次运行会自动下载模型（约 600MB）性能数据：
- 模型大小：~600MB
- 内存占用：~1.2GB
- 索引速度：约 1000 tokens/秒（M1 Mac）
- 搜索延迟：< 100ms
方案 B：混合搜索（推荐生产配置）
适用场景：需要兼顾语义理解和精确匹配的通用场景
{
"agents": {
"defaults": {
"memorySearch": {
"enabled": true,
"provider": "gemini",
"model": "gemini-embedding-2-preview",
"outputDimensionality": 3072,
"remote": {
"apiKey": "${GEMINI_API_KEY}"
},
"query": {
"hybrid": {
"enabled": true,
"vectorWeight": 0.7,
"textWeight": 0.3,
"candidateMultiplier": 4,
"mmr": {
"enabled": true,
"lambda": 0.7
},
"temporalDecay": {
"enabled": true,
"halfLifeDays": 30
}
}
}
}
}
}
}核心特性：
| 特性 | 作用 | 配置要点 |
|---|---|---|
| BM25 + 向量混合 | 同时匹配语义相似和关键词精确 | vectorWeight: 0.7, textWeight: 0.3 |
| MMR 重排序 | 避免结果重复，提升多样性 | lambda: 0.7（平衡相关性与多样性） |
| 时间衰减 | 优先返回近期记忆 | halfLifeDays: 30（30 天衰减一半） |
效果对比：
搜索 “home network setup”：
- 纯向量搜索：返回 3 条关于路由器的笔记（内容重复）
- 混合搜索 + MMR：返回路由器配置、DNS 设置、VLAN 规划（覆盖全面）
方案 C：QMD 后端（大规模知识库）
适用场景：需要索引外部文档、大规模知识库、高级检索需求
{
"memory": {
"backend": "qmd",
"citations": "auto",
"qmd": {
"command": "qmd",
"searchMode": "vsearch",
"includeDefaultMemory": true,
"paths": [
{ "name": "docs", "path": "~/notes", "pattern": "**/*.md" },
{ "name": "wiki", "path": "/srv/team-wiki", "pattern": "**/*.md" }
],
"update": {
"interval": "5m",
"debounceMs": 15000,
"onBoot": true,
"waitForBootSync": false
},
"limits": {
"maxResults": 6,
"timeoutMs": 4000
}
}
}
}安装 QMD：
# 方式 1：通过 Bun 安装
bun install -g https://github.com/tobi/qmd
# 方式 2：下载预编译版本
# 访问 https://github.com/tobi/qmd/releases
# 验证安装
qmd --versionQMD vs 内置后端对比：
| 特性 | 内置 SQLite | QMD |
|---|---|---|
| 本地运行 | ✅ | ✅ |
| 外部文档索引 | ❌ | ✅ |
| BM25 + 向量混合 | ✅ | ✅ |
| 重排序 | ✅ | ✅ |
| 查询扩展 | ❌ | ✅ |
| 首次搜索速度 | 快 | 慢（需下载模型） |
四、实战技巧：让记忆系统更智能
4.1 记忆文件组织最佳实践
# MEMORY.md 结构示例
## 用户偏好
### 技术栈
- 后端：Go + Gin
- 前端：React + TypeScript
- 数据库：PostgreSQL
### 沟通风格
- 喜欢先结论后细节
- 讨厌术语堆砌
- 每次给三个可执行方案
## 项目上下文
### 当前项目：AI 助手平台
- 技术栈：Next.js + Python FastAPI
- 截止日期：2026-06-30
- 关键决策：使用 OpenClaw 作为底层框架
## 重要经验
### 2026-03 学到的教训
1. API 配额管理：免费版有严格限制
2. 环境变量：脚本执行需显式加载 ~/.zshrc4.2 自动记忆维护（Heartbeat 配置）
编辑 HEARTBEAT.md：
# 记忆维护清单
## 每日检查
- [ ] 读取 memory/YYYY-MM-DD.md（今天 + 昨天）
- [ ] 检查是否有重要决策需要写入 MEMORY.md
## 每周维护（周日执行）
- [ ] 回顾本周 memory/ 文件
- [ ] 更新 MEMORY.md 长期记忆
- [ ] 清理过时的临时笔记4.3 会话记忆搜索（实验性）
启用历史对话索引：
{
"agents": {
"defaults": {
"memorySearch": {
"experimental": {
"sessionMemory": true
},
"sources": ["memory", "sessions"]
}
}
}
}注意：会话记忆默认关闭，需显式启用。
五、避坑指南：常见问题与解决方案
5.1 记忆搜索返回空结果
排查步骤：
# 1. 检查记忆后端状态
openclaw config get memory
# 2. 验证 API 密钥
openclaw auth list
# 3. 检查记忆文件是否存在
ls -la ~/.openclaw/workspace/memory/
# 4. 查看索引状态（QMD 后端）
qmd collection list常见原因：
- API 密钥未设置或过期
- 记忆文件为空或格式错误
- 索引尚未完成（首次启动需要时间）
5.2 切换嵌入模型后需要重新索引
# 删除旧索引（会自动重建）
rm ~/.openclaw/memory/*.sqlite
# 重启 Gateway
openclaw gateway restart5.3 群聊中记忆搜索不工作
默认情况下，MEMORY.md 只在私聊中加载。如需在群聊中使用记忆搜索：
{
"memory": {
"qmd": {
"scope": {
"default": "allow" // 或配置具体规则
}
}
}
}六、性能优化与监控
6.1 索引性能调优
{
"agents": {
"defaults": {
"memorySearch": {
"sync": {
"watch": true, // 监听文件变化
"debounceMs": 1500 // 防抖延迟
},
"cache": {
"enabled": true,
"maxEntries": 50000 // 嵌入缓存条目数
}
}
}
}
}6.2 批量索引（大规模数据）
{
"agents": {
"defaults": {
"memorySearch": {
"provider": "openai",
"remote": {
"batch": {
"enabled": true,
"concurrency": 2,
"wait": true
}
}
}
}
}
}OpenAI Batch API 优势：
- 价格比同步请求低 50%
- 适合大规模历史数据索引
- 异步处理，不阻塞对话
七、总结与行动清单
三种配置方案速查
| 场景 | 推荐方案 | 关键配置 |
|---|---|---|
| 个人用户快速开始 | 基础配置 | provider: "gemini" |
| 企业隐私敏感 | 本地优先 | provider: "local" |
| 通用生产环境 | 混合搜索 | hybrid.enabled: true |
| 大规模知识库 | QMD 后端 | backend: "qmd" |
立即行动
- 今天：复制基础配置，设置 API 密钥，测试记忆功能
- 本周：整理 MEMORY.md 长期记忆文件
- 本月：根据使用场景选择进阶方案，优化搜索体验
参考资源
