夜雨聆风如果你也遇到过这种情况：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/memory2.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.md2. SOUL.md3. USER.md4. 今日日志 + 昨日日志 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":true5.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 '"memorySearch"' ~/.openclaw/openclaw.jsongrep -A 10 '"compaction"' ~/.openclaw/openclaw.jsongrep -A 5 '"blockStreaming"' ~/.openclaw/openclaw.jsongrep '"ackReaction"' ~/.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.gateway2) 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相关链接
🔗 Gravatar：https://gravatar.com/mswnlz
🔗 SiliconFlow：https://siliconflow.cn
🔗 SiliconFlow API：https://api.siliconflow.cn/v1
🔗 OpenClaw 文档：https://docs.openclaw.ai
欢迎大家关注，持续分享 AI 前沿资讯、实用玩法和踩坑避坑经验。
