打造 OpenClaw 成可持续演化的 AI 记忆系统操作手册

如果你也遇到过这种情况：AI 今天聊得很懂你，明天又像失忆一样从零开始，那这篇就是给你的。

这份手册会手把手带你搭一套“能持续积累、能定期维护、能不断进化”的 OpenClaw 记忆系统。照着做，30~45 分钟就能跑起来。

前置条件

开始前确认这几项：

• 已安装 OpenClaw Gateway
• 已有可用的 workspace 目录
• 具备基础命令行操作能力
• 已配置 Telegram Bot（可选，用于 ackReaction）

第一步：先把助手“人设”立起来

创建 `IDENTITY.md`

位置：workspace/IDENTITY.md

# IDENTITY.md - Who Am I?- **Name:** 你的助手名- **Creature:** 你的角色定位- **Vibe:** 风格描述- **Emoji:** 💻- **Avatar:** 头像链接

建议：名字和风格尽量稳定，不要频繁改。这样助手在长期对话里的“人格连续性”会更好。

验证：

cat ~/workspace/IDENTITY.md

第二步：建立记忆分层（核心）

AI 记忆要可维护，关键就是分层。别把所有内容都塞一个文件里。

2.1 先建目录

mkdir -p ~/workspace/memory

2.2 推荐结构

MEMORY.md                 ← 索引层：总览与跳转├── memory/projects.md    ← 项目层：项目状态与待办├── memory/infra.md       ← 基础设施层：配置速查├── memory/lessons.md     ← 教训层：踩坑记录└── memory/YYYY-MM-DD.md  ← 日志层：每日结论

2.3 各层怎么写

• 索引层（MEMORY.md）：写“当前状态 + 快速跳转”
• 项目层（projects.md）：写“项目状态、最近进展、待办”
• 教训层（lessons.md）：按严重程度记录问题和解决方案
• 基础设施层（infra.md）：写配置速查，不写敏感明文
• 日志层（每日）：只记结论，不记冗长过程

第三步：让系统自己定期体检

创建 HEARTBEAT.md，定义周期任务：

• 每次心跳：服务在线检查（异常仅通知，不自动重启）
• 每天一次：检查待办是否 stale（超过 3 天没更新）
• 每周一次：记忆维护（提炼、压缩、清理）

再配一个状态文件：memory/heartbeat-state.json，记录上次维护时间。

第四步：明确 Agent 的工作规矩

在 AGENTS.md 里规定“每次会话先读什么、发生变化写到哪里”。

推荐启动读取顺序：

1. IDENTITY.md
2. SOUL.md
3. USER.md
4. 今日日志 + 昨日日志
5. 主会话再读 MEMORY.md

写入规则建议固定：

• 日常结论 → memory/YYYY-MM-DD.md
• 项目进展 → memory/projects.md
• 踩坑经验 → memory/lessons.md
• 配置变化 → memory/infra.md

第五步：改 OpenClaw 核心配置

配置文件（macOS）：

~/.openclaw/openclaw.json

先备份（非常重要）：

cp ~/.openclaw/openclaw.json ~/.openclaw/openclaw.json.backup-$(date +%Y%m%d%H%M%S)

5.1 开启 memorySearch（语义检索）

在 agents.defaults 里添加：

"memorySearch": {  "enabled":true,  "provider": "openai",  "remote": {    "baseUrl": "https://api.siliconflow.cn/v1",    "apiKey": "你的 API Key"  },  "model": "BAAI/bge-m3"}

5.2 开启 compaction + memoryFlush（压缩前持久化）

"compaction": {  "reserveTokensFloor": 20000,  "memoryFlush": {    "enabled":true,    "softThresholdTokens": 4000,    "systemPrompt": "会话接近压缩。现在存储持久的记忆。",    "prompt": "将持久的笔记写入 memory/YYYY-MM-DD.md；如果没有要存储的，回复 NO_REPLY。"  }}

5.3 开启 blockStreaming（分段输出）

"blockStreamingDefault": "on","blockStreamingBreak": "text_end","blockStreamingChunk": {  "minChars": 200,  "maxChars": 1500}

在 channels.telegram 里再加：

"blockStreaming":true

5.4 开启 ackReaction（收到即反馈）

在 messages：

"ackReactionScope": "all"

在 channels.telegram：

"ackReaction": "👀"

第六步：重启 Gateway

launchctl list | grep openclawlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gatewaysleep 3 && launchctl list | grep openclaw

看日志确认：

tail -20 ~/.openclaw/logs/gateway.logtail -20 ~/.openclaw/logs/gateway.err.log

第七步：逐项验证配置生效

grep -A 8 &#x27;"memorySearch"&#x27; ~/.openclaw/openclaw.jsongrep -A 10 &#x27;"compaction"&#x27; ~/.openclaw/openclaw.jsongrep -A 5 &#x27;"blockStreaming"&#x27; ~/.openclaw/openclaw.jsongrep &#x27;"ackReaction"&#x27; ~/.openclaw/openclaw.json

第八步：实测关键功能

测试 ackReaction

给 Bot 发消息，预期 1 秒内看到 👀。

测试 blockStreaming

发一个需要长回复的问题，预期是分段返回，而不是憋很久一口气输出。

常见故障排查

1) Gateway 启动失败

tail -50 ~/.openclaw/logs/gateway.err.log

典型问题：

• Invalid config：JSON 语法错误
• Unrecognized key：字段放错位置
• expected boolean, received string：类型错误

必要时恢复备份：

cp ~/.openclaw/openclaw.json.backup-YYYYMMDDHHMMSS ~/.openclaw/openclaw.jsonlaunchctl kickstart -k gui/$(id -u)/ai.openclaw.gateway

2) memorySearch 不工作

优先检查：API Key、baseUrl、model 名称。

3) ackReaction 不显示

检查 scope、机器人权限、群聊权限限制。

4) blockStreaming 不生效

检查全局默认、渠道开关、以及回复内容是否足够长。

文件结构总览

workspace/├── IDENTITY.md├── AGENTS.md├── SOUL.md├── USER.md├── HEARTBEAT.md├── MEMORY.md├── TOOLS.md└── memory/    ├── projects.md    ├── lessons.md    ├── infra.md    ├── heartbeat-state.json    └── YYYY-MM-DD.md