1. OpenClaw 分层记忆架构到底解决什么问题OpenClaw 分层记忆架构是一套让 AI 助手跨会话记住用户偏好的本地记忆系统它把记忆拆成短期上下文、会话摘要、长期知识库三层分别对应“正在做的事”“最近做过的事”“永远要遵守的规则”。如果你正在用 OpenClaw 做自动化办公、定时任务或者多轮 Agent 协作最痛的场景一定是昨天刚教会它周报模板放在 D 盘哪个目录今天新开一个对话它又一脸茫然或者长对话跑到一半早期说过的约束被窗口截断AI 开始胡编文件路径。分层记忆架构就是冲着这两个问题来的。它的核心设计思想可以概括成一句话文件即记忆。所有记忆的真实数据源是本地明文 Markdown 文件向量数据库只做检索加速索引损坏也不会丢原文。存储根目录固定在~/.openclaw/workspace/你可以直接用记事本打开、编辑、备份、删除全部记忆没有加密黑盒也不上传云端。配合 Ollama 本地模型整套记忆链路可以全程断网运行。三层主记忆按存活周期和加载规则严格隔离。L1 是运行时瞬时记忆活在 RAM 里只服务当前会话关网页或新建对话就清空L2 是中期时效日志按天写成workspace/memory/YYYY-MM-DD.md带遗忘曲线权重衰减30 天后权重减半L3 是长期常青记忆全局唯一文件workspace/MEMORY.md每次新建会话强制完整注入系统提示词永久生效。除此之外还有四类辅助记忆SOUL.md 人格底层、DREAMS.md 梦境复盘、sessions/*.jsonl 全量归档、SQLite 向量索引层。这套架构适合谁一是需要 AI 跨会话记住固定偏好的普通用户比如常用目录、周报模板、命名规范二是要控制上下文长度、避免 Token 爆炸的开发者三是对数据隐私敏感、要求本地离线运行的团队。下面我会按“前置准备 → 可复制配置 → 验证请求 → 常见报错”的顺序把每一层的存储选型、写入触发条件、召回触发条件讲清楚并给出可以直接粘贴的配置片段。2. TaoToken 前置准备与 OpenClaw 记忆层接入在动手配置分层记忆之前先把模型接入这一层理顺。OpenClaw 的记忆摘要、梦境复盘、语义检索都需要调用 LLM 和 Embedding 模型我用的是 TaoToken 作为统一接入入口官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。它的好处是一个 Key 同时覆盖对话模型和嵌入模型省得在 OpenClaw 里配多套凭证。第一步去控制台创建 API Key。打开 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 在 API Keys 页面新建一个密钥复制出来先存到临时文件。注意 Key 只在创建时完整显示一次关掉页面就看不到了。第二步确认你要用的模型 ID。OpenClaw 的记忆压缩和摘要建议用长上下文对话模型向量检索需要嵌入模型。你可以在模型对话页面 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 先试跑一轮确认模型能正常返回再写进配置。实测下来摘要任务用中等尺寸模型就够嵌入模型选支持中文的版本检索命中率会明显更好。第三步把 Base URL、Key、Model ID 三件套写进 OpenClaw 配置。OpenClaw 的模型配置支持 OpenAI 兼容协议所以 Base URL 填https://taotoken.net/api不要带 UTM 参数。Key 填刚才复制的Model ID 填你在模型对话里验证过的那个。如果你用的是 Claude Code 类接入方式配置结构类似把ANTHROPIC_BASE_URL指向同一个 API 地址即可具体字段参考接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。这里有个容易踩的坑很多人把 Base URL 写成带/v1或者带查询参数的完整地址结果 OpenClaw 拼接路径时出现双斜杠报 404。正确做法是只写到/api让框架自己拼/chat/completions和/embeddings。另外如果你打算长期跑编码类 Agent 任务可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 额度模型更适合高频调用记忆摘要的场景。前置准备做完后先别急着配三层记忆用一条最小请求验证模型通路。打开终端执行curl https://taotoken.net/api/chat/completions \ -H Authorization: Bearer $TAOTOKEN_API_KEY \ -H Content-Type: application/json \ -d { model: 你的模型ID, messages: [{role: user, content: 回复 OK}] }返回里能看到choices[0].message.content就说明通路正常。这一步过了再往下配记忆层否则后面报错你分不清是记忆配置问题还是模型接入问题。3. 三层记忆的可复制配置与写入召回规则这一节是全文的核心我会给出可以直接粘贴的 JSON 和 TOML 片段路径和字段名与 OpenClaw 实际配置保持一致。先看整体配置文件位置OpenClaw 的 Agent 配置通常在~/.openclaw/config/agents.defaults.json记忆插件配置在~/.openclaw/config/memory.json。如果你用的是 TOML 风格对应~/.openclaw/config/openclaw.toml。先配 L1 瞬时记忆的压缩阈值。L1 活在内存里关键参数是上下文压缩触发点和保护区轮数{ memory: { l1: { type: runtime, storage: ram, archivePath: ~/.openclaw/workspace/sessions, compactThreshold: 0.85, protectRounds: 4, idleTimeoutMinutes: 120, toolCallKeepIntact: true } } }compactThreshold: 0.85表示 Token 占用达到模型窗口 85% 时自动触发压缩protectRounds: 4表示最近 4 轮对话完整保留toolCallKeepIntact: true保证工具调用记录不被拆分避免 Agent 执行到一半丢失中间状态。手动触发压缩用/compact指令。再配 L2 时效日志的写入和衰减规则{ memory: { l2: { type: daily-log, path: ~/.openclaw/workspace/memory/{date}.md, autoWriteOn: [task_complete, session_compact, skill_finish], decay: { enabled: true, halfLifeDays: 30, minWeight: 0.25 }, autoLoadDays: [today, yesterday] } } }autoWriteOn定义了三个写入触发条件任务完成、会话压缩、技能执行结束。halfLifeDays: 30就是遗忘曲线30 天权重减半60 天剩 1/4。autoLoadDays控制新建会话自动加载今天和昨天两份日志更早的只能靠语义检索手动调取。L3 长期记忆的配置最简单但加载规则最关键{ memory: { l3: { type: evergreen, path: ~/.openclaw/workspace/MEMORY.md, injectOnSessionStart: true, decay: { enabled: false }, hotReload: true, hotReloadDebounceMs: 2000 } } }injectOnSessionStart: true是 L3 区别于 L1/L2 的核心特征——每次新建会话强制完整注入系统提示词。hotReload: true配合 2 秒防抖意味着你手动编辑 MEMORY.md 后不用重启等两秒就生效。向量检索层单独配{ memory: { vector: { dbPath: ~/.openclaw/workspace/memory/vector.db, embeddingModel: 你的嵌入模型ID, embeddingBaseUrl: https://taotoken.net/api, hybridSearch: true, bm25Weight: 0.3, vectorWeight: 0.7 } } }hybridSearch: true开启向量语义匹配加 BM25 关键词匹配的混合检索bm25Weight和vectorWeight控制两者权重。实测下来中文场景把 BM25 权重调到 0.3 到 0.4 之间专有名词和文件路径的召回更准。如果你用 TOML 风格等价写法是[memory.l1] type runtime compactThreshold 0.85 protectRounds 4 [memory.l2] type daily-log path ~/.openclaw/workspace/memory/{date}.md autoLoadDays [today, yesterday] [memory.l3] type evergreen path ~/.openclaw/workspace/MEMORY.md injectOnSessionStart true配完之后写入和召回的完整链路是这样的你在对话里说“每周五抓取行业资讯生成周报存到 D 盘归档”L1 先接住指令Agent 拆解任务调用技能任务完成后自动追加到当日 L2 日志你再说一句“把这套周报流程永久记住”系统把规则追加进 L3 的 MEMORY.md后台 DREAMS 机制定时扫描 L2识别高频任务提示你是否晋升到 L3。次日新会话L1 清空但 L3 强制加载AI 不用你重复描述就知道周报规则。4. 验证请求多轮对话测记忆命中率与上下文长度配置写完必须验证否则你不知道记忆到底有没有生效。我设计了一组三轮验证法分别测 L3 跨会话命中、L2 日志召回、L1 压缩后上下文长度变化。第一轮测 L3 长期记忆。先在一个会话里写入规则openclaw chat --message 把这条规则永久存入长期记忆所有周报文件保存到 D:/archive/weekly命名格式 YYYY-WW.md然后关闭会话新建一个对话直接问openclaw chat --message 我的周报文件应该存到哪个目录命名格式是什么如果 L3 配置正确AI 应该直接答出D:/archive/weekly和YYYY-WW.md不需要你重新说明。这一步验证的是injectOnSessionStart是否真的把 MEMORY.md 注入了系统提示词。你也可以直接查看文件确认cat ~/.openclaw/workspace/MEMORY.md应该能看到刚写入的规则条目。第二轮测 L2 日志召回。先执行一个任务让系统自动写日志比如让 AI 抓取一条资讯并保存。然后执行语义检索openclaw memory search 资讯抓取保存路径返回结果里应该包含当日YYYY-MM-DD.md的片段。如果搜不到先检查autoWriteOn是否包含task_complete再检查向量索引是否需要重建。第三轮测 L1 压缩与上下文长度变化。开一个长对话连续发 20 轮以上消息观察 Token 占用。当达到 85% 阈值时系统自动压缩你可以用指令查看当前上下文状态openclaw memory status --conversation current输出会显示当前 Token 数、保护区轮数、已摘要的远期轮数。压缩后 Token 应该明显下降但最近 4 轮完整保留。手动压缩用openclaw memory compact --conversation current为了量化记忆命中率我建议做一个简单对照准备 10 个跨会话问题其中 5 个涉及 L3 固定规则5 个涉及 L2 近期任务。新建会话逐个提问统计答对数量。实测下来L3 规则类问题命中率接近 100%L2 近期任务在 24 小时内命中率也很高超过 30 天的日志因为权重衰减需要显式检索才能调出。验证过程中常用的运维命令还有# 查看记忆根目录 openclaw config get agents.defaults.workspace # 重建向量检索索引修改大量记忆文件后执行 openclaw memory reindex # 将当日高频日志沉淀至长期 MEMORY.md openclaw memory promote --apply # 清空当日 L2 时效日志保留 L3 长期记忆 openclaw memory clear-daily # 清空当前会话 L1 瞬时记忆 openclaw memory clear assistant --conversation current # 记忆系统分层自检修复索引和文件权限异常 openclaw doctor memoryopenclaw doctor memory这个命令特别值得记住它会逐层检查 L1 内存状态、L2 文件权限、L3 注入配置、向量索引完整性输出一份体检报告。每次改完配置跑一遍能提前发现大部分问题。5. 常见报错排查401、local proxy failed、reading choices、OAuth这一节对照真实报错给出定位思路。记忆层的问题往往不是记忆本身而是模型接入或索引状态引起的连锁反应。报错一401 Unauthorized。最常见的原因是 API Key 没生效或者 Base URL 写错。先确认环境变量echo $TAOTOKEN_API_KEY如果为空说明 Key 没导出。如果 Key 正常检查配置文件里的embeddingBaseUrl和对话模型的 Base URL 是否都是https://taotoken.net/api不要带多余路径。还有一种情况是 Key 复制时带了空格或换行重新去 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 复制一次。报错二local proxy failed。这个报错通常出现在 OpenClaw 尝试连接本地 Ollama 嵌入模型时。如果你用的是云端嵌入模型检查embeddingBaseUrl是否指向了http://localhost:11434这类本地地址。如果你确实要用 Ollama 离线模式确认 Ollama 服务已启动ollama list并且嵌入模型已经拉取。离线模式下检索失效多半是嵌入模型没配好重新执行openclaw onboard配置记忆插件。报错三reading choices 相关错误。这类报错说明模型返回结构不符合预期常见于 Base URL 拼接错误导致返回了 HTML 错误页而不是 JSON。检查你的请求地址是不是变成了https://taotoken.net/api/v1/chat/completions这种双路径。正确做法是 Base URL 只写到/api。另外确认 Model ID 拼写正确模型不存在时也可能返回非标准结构。报错四OAuth 相关错误。如果你用 Claude Code 类接入方式OAuth 报错通常是凭证过期或配置字段不匹配。检查~/.claude/settings.json或对应的 auth 配置文件确认ANTHROPIC_BASE_URL指向https://taotoken.net/apiKey 字段填写正确。如果你用的是 Codex 的auth.json确认里面的 Base URL、Key、Model ID 三件套齐全缺一不可。报错五修改 MEMORY.md 后 AI 无变化。这不是报错但很常见。原因是热加载有 2 秒防抖或者向量索引没更新。等两秒再试如果还不行执行openclaw memory reindex报错六记忆检索不到历史任务。先跑openclaw doctor memory看索引状态。如果是久远日志权重衰减导致属于正常行为用openclaw memory search显式检索可以强制调出。如果索引损坏doctor会提示重建。报错七隔天 AI 忘记工作流程。这是最典型的记忆晋升缺失。检查当日 L2 日志是否写入了流程再确认是否执行过openclaw memory promote --apply把规则沉淀到 L3。如果只存在 L1 或 L2新会话不会自动继承。排查时记住一个原则先验证模型通路再验证记忆文件最后验证索引。模型通路用 curl 测记忆文件用 cat 看索引用 doctor 查。三层都过了记忆命中率自然就上来了。6. 把记忆层用顺手的几个实操建议最后分享几个我在实际使用中总结的技巧不搞总结陈词直接说能落地的。第一MEMORY.md 不要什么都往里塞。它每次会话都强制注入内容越多 Token 消耗越大。只放高频复用的固定规则常用目录、命名规范、禁止操作、业务流程。临时任务和一次性路径留给 L2 日志。第二L2 日志的自动加载只开今天和昨天。更早的日志靠检索这样既保证近期连贯又不会让上下文膨胀。如果你发现某类任务每周都重复直接用openclaw memory promote --apply晋升到 L3比每次检索更省事。第三向量索引重建不用太频繁。只有当你批量修改了记忆文件或者检索结果明显不准时才执行openclaw memory reindex。日常写入是增量的不需要每次重建。第四多 Agent 场景下记忆目录要隔离。每个 Agent 用独立的 workspace避免财务 Agent 的记忆被办公 Agent 检索到。配置里通过agents.defaults.workspace分别指定。第五离线场景提前把嵌入模型拉好。Ollama 本地嵌入模型第一次拉取需要时间别等到断网了才发现没下载。拉好之后跑一次openclaw doctor memory确认离线检索通路正常。第六定期备份~/.openclaw/workspace/整个目录。因为记忆是明文 Markdown直接复制文件夹就是完整备份比任何导出功能都可靠。恢复时覆盖回去执行一次 reindex 即可。如果你还没开始配建议先从 L3 的 MEMORY.md 入手写三条你最常重复的规则新建会话验证注入是否生效。这一步跑通再往下配 L2 和向量检索循序渐进比一次性全配完更容易定位问题。模型接入和 Key 管理统一走 TaoToken对话模型和嵌入模型一个入口省去多套凭证的麻烦。