1. OpenClaw Memory 到底解决了什么问题从「聊完就忘」到可检索的长期记忆如果你用过一段时间的 AI Agent大概率会遇到同一个尴尬昨天刚跟它确认过项目用 PostgreSQL 15、代码规范走 ESLint Prettier今天开个新会话它又一脸无辜地问你「请问您想用什么数据库」。这不是模型笨而是它的记忆没有落到磁盘上。OpenClaw 的 Memory 系统本质上就是把「记忆」这件事从模型参数里拿出来变成一堆你能用编辑器打开、能用 git diff 追溯的 Markdown 文件再叠一层向量索引做混合检索。先说清楚它是什么、能做什么、适合谁。OpenClaw Memory 是一套以纯 Markdown 文件为唯一事实来源的 Agent 长期记忆方案核心公式是「Markdown 文本 向量索引 混合检索」。它能做到三件事第一把 Agent 的人格、用户偏好、项目事实、每日交互日志分别写进不同层级的文件第二用 Embedding 向量检索和 BM25 关键词检索两路召回再融合打分第三在会话 Token 快满时自动做一次静默记忆保存把关键信息刷进 MEMORY.md 或当日日志。适合谁适合正在做 AI Agent 落地、被「上下文窗口一滑就丢信息」折磨的开发者尤其是想让 Agent 记住跨会话事实、又不想上重型向量数据库的人。我先把它的目录结构摆出来这是理解一切的地基。默认工作区在~/.openclaw/workspace每个 Agent 一个独立目录workspace/ ├── AGENTS.md # Agent 行为规则、优先级、记忆使用方式 ├── SOUL.md # 不可变人格内核语气、边界、价值观 ├── USER.md # 用户称呼、偏好、关系等结构化信息 ├── IDENTITY.md # Agent 名称、vibe、emoji 标识 ├── TOOLS.md # 本地工具使用约定仅指导不控制可用性 ├── HEARTBEAT.md # 心跳配置定时任务 ├── MEMORY.md # 精选长期记忆仅 main session 加载 ├── memory/ # 每日记忆日志目录 │ └── YYYY-MM-DD.md # append-only 格式建议加载今日昨日 ├── skills/ # 工作区专属技能优先级 全局/内置技能 └── sessions.json # 会话元数据按需读取这里有个关键认知模型只「记住」写进磁盘的内容。SOUL.md 定义 Agent 是谁每次 Session 启动加载创建后不应被对话修改USER.md 和 MEMORY.md 承载语义长期记忆只在 main/private session 加载群组会话隔离看不到memory/ 下的每日日志是 append-only 的Session 启动时自动读今天和昨天两份给对话提供连续性。四层架构——SOUL 不可变内核、TOOLS 动态工具层、USER 语义长期记忆、Session 实时情景——各管一段生命周期互不越界。为什么非要 Markdown 而不是直接塞数据库因为可编辑、可版本管理、可人工介入。你可以直接打开 MEMORY.md 手动改一条偏好也可以把它纳入 Git用git diff看 Agent 这周到底记住了什么。这种「人类可读可改」的特性是纯向量库给不了的。理解了这层后面讲向量索引和混合检索才有落点——索引是加速器Markdown 才是事实源。2. 接入前的准备把 endpoint 统一到 TaoToken 并拿到调用凭证在动手配记忆检索之前得先把模型调用这条链路理顺。OpenClaw 的 Memory 检索里向量化那一路需要调用 Embedding 接口Agent 主对话也需要模型接口。与其到处散落不同的 key 和 base url不如统一走一个入口。我实测下来把 endpoint 收敛到 TaoToken 会省掉很多切换成本——它兼容主流接口格式Base URL 固定换模型只改 Model ID 就行。先明确三个必须对齐的东西缺一个都会在后面的验证里报错Base URL、API Key、Model ID。这三件套是接入任何 OpenAI 兼容接口的通用前提OpenClaw 的 Memory 向量化配置也不例外。Base URL 用https://taotoken.net/api注意这里不加任何查询参数保持干净。API Key 需要你去控制台生成入口在 https://taotoken.net/api-keys 登录后新建一个 key复制出来妥善保存它只完整显示一次。Model ID 则取决于你打算用哪个模型做对话、哪个做 Embedding比如对话可以用claude-sonnet-4-5这类Embedding 用对应的向量模型 ID具体以你账号下可用的模型列表为准。如果你用的是 Claude Code 这类工具配置方式略有不同需要设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个环境变量指向同一个入口。这一步的细节可以对照接入文档 https://taotoken.net/doc 来核对文档里对每种客户端的字段名写得比较清楚避免你把api_key和auth_token搞混。这里插一句踩过的坑很多人第一次配的时候只填了 Base URL 和 Key忘了 Model ID结果请求发出去返回一个模型不存在的错误然后开始怀疑是不是 key 失效。其实不是是模型名没对上。三件套必须同时正确这是后面所有验证的前提。准备工作做完你应该手上有一个可用的 API Key、确认过的 Base URLhttps://taotoken.net/api、以及至少一个对话模型 ID 和一个 Embedding 模型 ID。把这些记在一个临时文件里下一步配置记忆目录和检索参数时直接引用。别小看这一步后面排查 401 和模型报错时你会发现大部分问题都出在这三件套没对齐而不是 OpenClaw 本身的问题。3. 可复制的记忆目录与混合检索配置settings 片段逐字段说明现在进入正题把记忆目录和混合检索参数落到可复制的配置上。OpenClaw 的配置通常放在工作区或全局配置目录下我用一个settings.json片段来演示字段名和路径保持和实际一致你直接改路径和 key 就能用。先建目录结构这一步用命令完成mkdir -p ~/.openclaw/workspace/memory mkdir -p ~/.openclaw/workspace/skills touch ~/.openclaw/workspace/MEMORY.md touch ~/.openclaw/workspace/SOUL.md touch ~/.openclaw/workspace/USER.md然后是核心的settings.json重点看 memory 和 embedding 两段{ workspace: ~/.openclaw/workspace, model: { base_url: https://taotoken.net/api, api_key: sk-你的TaoToken密钥, chat_model: claude-sonnet-4-5, embedding_model: text-embedding-3-small }, memory: { enabled: true, long_term_file: MEMORY.md, daily_log_dir: memory, load_today_and_yesterday: true, compaction_threshold_tokens: 4000, silent_flush: true }, retrieval: { mode: hybrid, vector_weight: 0.6, bm25_weight: 0.4, top_k: 8, chunk_tokens: 400, mmr_dedup: true, time_decay: true } }逐字段拆一下。model.base_url指向 TaoToken 的 API 入口api_key填你上一步生成的 keychat_model和embedding_model分别对应对话和向量化这两个 ID 必须是你账号下真实可用的。memory.compaction_threshold_tokens设成 4000意思是会话 Token 接近这个值时触发预压缩Agent 会执行一个隐藏的 Silent Turn 把重要记忆写进 MEMORY.md 或当日日志用户端只看到NO_REPLY。retrieval.mode设成hybrid就是开启混合检索vector_weight和bm25_weight是两路召回的融合权重我默认给 0.6 和 0.4语义为主、关键词为辅。如果你更习惯 TOML 风格等价写法是这样[model] base_url https://taotoken.net/api api_key sk-你的TaoToken密钥 chat_model claude-sonnet-4-5 embedding_model text-embedding-3-small [retrieval] mode hybrid vector_weight 0.6 bm25_weight 0.4 top_k 8配置里mmr_dedup和time_decay是可选项。MMR 去重能避免召回一堆语义重复的片段时间衰减让近期记忆权重更高——比如你上周改过的偏好应该比三个月前的旧决策更容易被召回。这两个开关在长对话场景里效果明显建议先开着觉得召回太激进再关。配完记得检查路径展开。~在部分运行环境里不会自动展开如果启动时报找不到 workspace把~换成绝对路径/home/你的用户名/.openclaw/workspace。这个坑很隐蔽因为配置文件本身语法没错错的是路径解析。4. 验证一次混合检索从写入记忆到命中结果的完整请求配置写完不能只看不跑得实际验证一次混合检索是否生效。我设计一个最小验证流程先往记忆里写一条带精确关键词的事实再写一条语义相关但用词不同的内容然后发一个查询看两路召回能不能都命中。第一步写入记忆。往 MEMORY.md 追加一条## 项目事实 - 项目根目录: ~/projects/my-app - 数据库: PostgreSQL 15 - 部署方案: Docker Compose再往当日日志memory/2026-03-10.md写一条语义相关但关键词不同的## 14:05 - 架构讨论 用户提到容器编排的选型最终倾向用 compose 方式管理多服务 避免引入过重的编排组件。注意第二条里没有出现「Docker」这个词只有「容器编排」「compose」。如果只靠 BM25 关键词检索查「Docker 部署」可能命中不了第二条但向量检索能靠语义把「容器编排」和「Docker」关联起来。这正是混合检索的价值。第二步发起检索请求。OpenClaw 提供memory_search做语义召回返回约 400 token 的 chunks带文件路径、行号和相似度分数。用 curl 模拟一次底层调用验证 embedding 接口通不通curl https://taotoken.net/api/v1/embeddings \ -H Authorization: Bearer sk-你的TaoToken密钥 \ -H Content-Type: application/json \ -d { model: text-embedding-3-small, input: Docker 部署方案是什么 }正常返回会是一个包含data[0].embedding的 JSON向量维度取决于模型。如果这一步返回 401说明 key 有问题返回模型不存在说明model字段的 ID 写错了。这一步单独验证 embedding能把问题从混合检索里隔离出来。第三步在 Agent 会话里触发一次memory_search查询「之前定的部署方案」。预期结果是MEMORY.md 里那条「Docker Compose」因为关键词和语义双命中分数最高当日日志里那条「容器编排」靠向量路召回排在第二梯队。如果只返回了第一条说明向量路没生效回去检查embedding_model和vector_weight。第四步用memory_get做精确读取验证。它按文件路径 起始行 行数读取适合已知位置的场景memory_get(pathMEMORY.md, start_line1, lines10)这一步验证的是「精确读取」能力和memory_search的模糊召回互补。两个工具配合才是完整的检索闭环。跑通这四步你就有了一个可复现的混合检索验证动作以后改权重、换模型都拿这套流程回归测试。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth 逐条对照配置和验证过程中报错是必然的。我把几类高频错误按现象、原因、解法列出来你对着改就行。401 Unauthorized。最常见几乎都是 key 的问题。要么 key 复制时带了空格要么 key 已经失效要么Authorization头格式写错。正确格式是Bearer sk-xxxBearer 和 key 之间一个空格。如果你用的是 Claude Code 那类工具注意它读的是ANTHROPIC_AUTH_TOKEN而不是OPENAI_API_KEY字段名搞混也会 401。排查方法拿同一个 key 单独跑一次第 4 节的 curl能通说明 key 没问题问题在客户端配置。local proxy failed。这个报错通常出现在客户端试图走本地代理但代理没起来或者环境变量里残留了HTTP_PROXY/HTTPS_PROXY指向一个不存在的端口。解法是检查环境变量把不该有的代理配置清掉让请求直连https://taotoken.net/api。注意这里说的是清理本地无效代理配置不是让你去搭什么通道直连即可。reading choices 相关报错。典型信息是Cannot read properties of undefined (reading choices)意思是代码期望响应里有choices字段但实际返回的结构不是标准格式。原因通常是 Base URL 写成了带路径的形式比如多加了/v1/chat/completions导致拼接后路径重复。Base URL 保持https://taotoken.net/api就好具体路径由客户端自己拼。另一个可能是模型 ID 不存在返回了错误对象而非正常响应。OAuth 相关报错。如果你在 Claude Code 里看到 OAuth 或登录态相关的提示多半是它默认想走账号登录流程而你要用的是 API Key 模式。这时候需要显式设置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN让它走 key 认证而不是 OAuth。三件套里的 Base URL 和 Key 在这里同样适用Model ID 则通过ANTHROPIC_MODEL指定。再补一个隐蔽的检索返回空结果但没报错。这通常不是接口问题而是索引没建。OpenClaw 的向量索引需要先对 Markdown 文件做一次 embedding 并落库如果你刚写完 MEMORY.md 就立刻查询索引可能还没更新。触发一次重建或者等下一次 Session 启动时的扫描。另外确认memory.enabled是true这个开关关了的话检索直接短路。排查顺序建议固定下来先 curl 验证 key 和 Base URL再验证 Model ID最后才怀疑 OpenClaw 的检索逻辑。大部分问题在前两步就能定位别一上来就翻源码。6. 把记忆检索接到长期编码与 Agent 工作流跑通单次验证只是起点真正有价值的是把这套记忆检索嵌进日常的编码和 Agent 工作流里。当你确认混合检索稳定后可以考虑几个进阶方向。第一把 MEMORY.md 纳入 Git 管理。每次 Agent 写入新记忆你都能通过git diff看到它记住了什么、改了什么。这对调试「Agent 为什么突然改了行为」特别有用——往往就是某条记忆被写歪了。第二调整vector_weight和bm25_weight。如果你的场景里错误码、文件名、命令这类精确匹配需求多把 bm25 权重调高如果是「之前讨论过的那个方案」这种模糊指代多就加大 vector 权重。这个比例没有标准答案靠你自己的查询日志调。第三如果你在跑长期的编码 Agent比如让它持续维护一个仓库记忆的连续性直接决定它会不会重复踩坑。这时候可以考虑用 Coding Plan 这类面向长期编码场景的方案配合统一的 endpoint让对话模型和 embedding 模型都走同一个入口减少配置漂移。入口在 https://taotoken.net/coding-plan 适合需要稳定长期调用的场景。第四验证模型本身的能力时可以先用模型对话快速试一下不同模型对同一段记忆的理解差异入口 https://taotoken.net/chat 。有时候换个模型同样的记忆召回质量会明显不同这能帮你判断是检索层的问题还是模型层的问题。最后回到一个实操建议每次改完检索配置都拿第 4 节那套「写两条记忆 发一个查询」的流程回归一遍。混合检索的参数很敏感权重动一点召回结果可能就变了。把这套验证动作脚本化比凭感觉调参靠谱得多。记忆系统的价值不在于配置多花哨而在于它能不能稳定地在该想起的时候想起——这一点只有反复验证才能保证。