1. OpenClaw Agent 记忆模块到底解决什么问题OpenClaw 的 Agent 记忆Memory模块简单说就是让 Agent 把「记住的东西」落到磁盘上的 Markdown 文件里而不是只留在当前会话的上下文窗口里。它适合谁适合那些用 OpenClaw 跑长期任务、做个人助理、维护项目笔记或者希望 Agent 跨会话保留决策与偏好的开发者。核心检索词就是 OpenClaw、Agent、Memory、Markdown、memory_search——这几个词贯穿整篇。我先把机制讲清楚OpenClaw 的记忆是 agent 工作区中的纯 Markdown 文件这些文件是事实来源模型只「记住」写入磁盘的内容。也就是说你不写盘它就真的不记得。记忆搜索工具由活动的记忆插件提供默认是 memory-core如果你把plugins.slots.memory设为none记忆插件就被禁用memory_search 和 memory_get 这两个工具也不会启用。默认工作区布局是两层记忆。第一层是memory/YYYY-MM-DD.md日常日志只允许追加会话开始时读取今天和昨天的日志。第二层是MEMORY.md可选的精挑细选的长期记忆。这里有个容易踩的坑如果MEMORY.md和memory.md同时存在于工作区根目录OpenClaw 仅加载MEMORY.md小写的memory.md仅在MEMORY.md不存在时作为后备使用而且只在主要的私有会话中加载绝不在群组上下文中加载。这些文件位于工作区下由agents.defaults.workspace控制默认是~/.openclaw/workspace。面向 agent 的工具有两个memory_search对索引片段做语义召回memory_get针对性地读取特定 Markdown 文件或行范围。值得一提的是memory_get现在在文件不存在时会优雅降级比如首次写入前的日常日志内置管理器和 QMD 后端都会返回{ text: , path }而不是抛 ENOENT 错误这样 agent 就能处理「尚未记录任何内容」的情况不用把工具调用包在 try/catch 里。什么时候写入记忆决策、偏好和持久性事实写入MEMORY.md日常笔记和持续上下文写入memory/YYYY-MM-DD.md。如果有人让你「记住这个」就把它写下来不要留在内存中。这个功能仍在发展中提醒模型存储记忆会有所帮助它会知道该怎么做。如果你想让某些内容被固定下来直接要求机器人将其写入记忆。还有一个自动记忆刷新机制叫预压缩提醒。当会话接近自动压缩时OpenClaw 会触发一个静默的、agent 驱动的回合提醒模型在上下文被压缩之前写入持久性记忆。默认提示明确说明模型可以回复但通常NO_REPLY是正确的响应这样用户永远不会看到这个回合。这由agents.defaults.compaction.memoryFlush控制细节包括软阈值在会话令牌估计值超过contextWindow - reserveTokensFloor - softThresholdTokens时触发刷新默认静默提示包含NO_REPLY两个提示一个用户提示和一个系统提示附加提醒每个压缩周期只刷新一次在sessions.json中跟踪工作区必须可写如果会话在沙箱中以workspaceAccess: ro或none运行则跳过刷新。理解了这些你就明白为什么「记忆」不是玄学而是文件读写加检索。接下来我把 endpoint 改到 TaoToken 统一通道完成调用验证。2. 接入 TaoToken 统一通道的前置准备在动手配置记忆之前先把模型调用通道理顺。OpenClaw 的记忆搜索默认使用远程嵌入而远程嵌入需要嵌入提供方的 API key。OpenClaw 从认证配置文件、models.providers.*.apiKey或环境变量中解析 key。这里有个关键点Codex OAuth 仅涵盖聊天/补全不满足记忆搜索的嵌入要求。所以如果你只配了 Codex OAuthmemory_search 会因为拿不到嵌入 key 而保持禁用。我的做法是把 endpoint 统一改到 TaoToken 通道这样聊天模型和嵌入模型走同一个入口key 管理也集中。TaoToken 官网是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 入口是 https://taotoken.net/api 注意 API 地址不加 UTM 参数。你需要先去控制台创建 API Key控制台地址是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite API Keys 管理页是 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。如果你还没决定用哪个模型可以先去模型对话页试试 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。前置准备分三步。第一步拿到 API Key形如sk-xxxx记下来。第二步确认你的 OpenClaw 版本支持memorySearch.remote.baseUrl和memorySearch.remote.apiKey这两个字段是自定义 OpenAI 兼容端点的关键。第三步确认工作区可写因为记忆文件要落盘沙箱只读模式会跳过刷新。这里要强调一个业务边界TaoToken 是统一调用通道不是让你绕过任何合规要求也不是灰色中转。你用它就是把 baseUrl 指向官方 API 入口key 用自己申请的模型 ID 按文档填。所有配置都走标准 OpenAI 兼容协议没有黑魔法。关于模型选择记忆搜索的嵌入模型和聊天模型可以分开。聊天模型你可以用 Claude 系列或 GPT 系列嵌入模型用text-embedding-3-small这类。如果你长期做编码或 Agent 任务可以考虑 Coding Plan入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。如果你用 Claude Code 做润色或接入参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-codeutm_campaignrewrite 。前置准备做完接下来就是可复制的配置片段。我会把记忆目录结构、memorySearch配置、以及 endpoint 指向 TaoToken 的写法一次给全。3. 可复制的记忆目录结构与配置片段先建目录结构。默认工作区是~/.openclaw/workspace你可以这样初始化mkdir -p ~/.openclaw/workspace/memory touch ~/.openclaw/workspace/MEMORY.md touch ~/.openclaw/workspace/memory/$(date %F).md目录长这样~/.openclaw/workspace/ ├── MEMORY.md └── memory/ ├── 2026-02-10.md └── 2026-02-09.mdMEMORY.md放长期记忆memory/YYYY-MM-DD.md放日常日志。注意大小写MEMORY.md优先于memory.md。接下来是核心配置。OpenClaw 的配置是 JSON 风格记忆搜索在agents.defaults.memorySearch下配置不是顶层的memorySearch这点很多人写错。下面这段把 provider 设为 openai并把 remote 指向 TaoToken 统一通道{ agents: { defaults: { workspace: ~/.openclaw/workspace, memorySearch: { enabled: true, provider: openai, model: text-embedding-3-small, fallback: none, remote: { baseUrl: https://taotoken.net/api/v1/, apiKey: sk-你的_TaoToken_KEY }, extraPaths: [../team-docs], sync: { watch: true }, query: { hybrid: { enabled: true, vectorWeight: 0.7, textWeight: 0.3, candidateMultiplier: 4, mmr: { enabled: true, lambda: 0.7 }, temporalDecay: { enabled: true, halfLifeDays: 30 } } } } } } }如果你用 TOML 风格管理配置等价写法是[agents.defaults] workspace ~/.openclaw/workspace [agents.defaults.memorySearch] enabled true provider openai model text-embedding-3-small fallback none [agents.defaults.memorySearch.remote] baseUrl https://taotoken.net/api/v1/ apiKey sk-你的_TaoToken_KEY [agents.defaults.memorySearch.sync] watch true如果你更习惯用settings.json集中管理把上面 JSON 片段合并进你的 settings 文件即可路径和字段名保持一致。三件套要写全Base URL 是https://taotoken.net/api/v1/Key 是你申请的sk-开头字符串Model ID 是text-embedding-3-small。聊天模型那边同理把models.providers的 baseUrl 也指向 TaoTokenmodel 填你选的聊天模型 ID。再补一个自动记忆刷新的配置放在agents.defaults.compaction下{ agents: { defaults: { compaction: { reserveTokensFloor: 20000, memoryFlush: { enabled: true, softThresholdTokens: 4000, systemPrompt: 会话即将压缩。现在存储持久性记忆。, prompt: 将任何持久的笔记写入 memory/YYYY-MM-DD.md如果没有要存储的内容请回复 NO_REPLY。 } } } } }如果你要索引默认工作区之外的 Markdown用extraPaths路径可以是绝对路径或相对于工作区的路径目录会被递归扫描.md文件符号链接会被忽略。默认只索引 Markdown除非开多模态。配置写完下一步就是验证请求看 memory_search 是否真的能召回。4. 验证 memory_search 与成功结果验证分两步先确认索引建起来了再确认检索能召回。第一步写入一条测试记忆。往MEMORY.md里写# 长期记忆 - 项目代号OpenClaw-Memory-Test - 默认嵌入模型text-embedding-3-small - 统一通道TaoToken再往今天的日志写# 2026-02-10 - 今天把 memorySearch.remote.baseUrl 改到 TaoToken 统一通道 - 验证 memory_search 能召回「统一通道」相关片段第二步触发一次会话让 OpenClaw 在会话启动时同步索引。同步在会话启动时、搜索时或按时间间隔调度并异步运行。你可以直接在对话里让 agent 调用 memory_search请用 memory_search 搜索「统一通道」返回片段和文件路径。成功时你会看到类似结构的结果片段文本、文件路径、行范围、分数、provider/model以及是否从本地嵌入回退到了远程嵌入。片段文本上限约 700 字符不返回完整文件负载。目标块大小约 400 令牌80 令牌重叠。如果你想手动确认索引状态可以检查每个 agent 的 SQLite 数据库默认在~/.openclaw/memory/.sqlite可通过agents.defaults.memorySearch.store.path配置支持{agentId}令牌。索引存储会记录嵌入提供方/模型、端点指纹和分块参数如果其中任何一项变化OpenClaw 会自动重置并重新索引整个存储。再验证 memory_get。让 agent 读取特定文件请用 memory_get 读取 MEMORY.md 的前 10 行。成功时返回文件内容。如果文件不存在会返回{ text: , path }不会抛 ENOENT。注意 memory_get 拒绝MEMORY.md/memory/之外的路径这是安全边界。混合搜索验证。启用query.hybrid后OpenClaw 结合向量相似度和 BM25 关键词相关性。你可以用一个精确 token 查询比如「text-embedding-3-small」看 BM25 是否命中再用一个语义查询比如「我把调用入口换到哪了」看向量是否命中。如果嵌入不可用或提供方返回零向量仍然运行 BM25 并返回关键词匹配结果如果无法创建 FTS5保持纯向量搜索不会硬失败。时间衰减验证。查询「统一通道」时今天的日志应该排在旧日志前面。默认半衰期 30 天今天的笔记 100% 原始分数7 天前约 84%30 天前 50%90 天前 12.5%。永久文件从不衰减包括MEMORY.md和memory/中非日期的文件。MMR 验证。如果你有多条相似日志启用 MMR 后近乎重复的片段会被排除agent 获得更多样化的信息。默认 lambda 0.7平衡相关性和多样性。到这里如果 memory_search 返回了带路径和行范围的片段说明整条链路通了Markdown 落盘、索引构建、TaoToken 嵌入调用、语义召回。5. 本篇常见错误排查第一个高频错误401 Unauthorized。表现是 memory_search 一直禁用或报鉴权失败。原因通常是memorySearch.remote.apiKey没填、填错或者 baseUrl 写成了https://taotoken.net/api而漏了/v1/。排查方法确认 baseUrl 是https://taotoken.net/api/v1/key 是sk-开头且没有多余空格。另外注意Codex OAuth 不满足嵌入要求如果你只配了 OAuth嵌入 key 解析不到记忆搜索会保持禁用直到配置完成。第二个错误local proxy failed。表现是本地嵌入模式启动失败。原因通常是node-llama-cpp原生构建没通过。排查方法运行pnpm approve-builds选择node-llama-cpp然后pnpm rebuild node-llama-cpp。如果你不想折腾本地构建直接把 provider 设为 openai 走 TaoToken 远程嵌入fallback 设为 none。第三个错误reading choices 相关报错。表现是嵌入响应解析失败。原因通常是 baseUrl 指向的端点返回格式不是 OpenAI 兼容结构或者 model ID 填错。排查方法确认 model 是text-embedding-3-small这类标准嵌入模型 IDbaseUrl 末尾带/v1/。如果你用自定义端点memorySearch.remote.headers可以加额外头部。第四个错误OAuth 相关报错。表现是聊天能用但记忆搜索不可用。原因就是前面说的Codex OAuth 仅涵盖聊天/补全不满足嵌入要求。排查方法单独为嵌入配置 API key走memorySearch.remote.apiKey。第五个错误memory_search 返回空结果。原因可能是 scope 拒绝了搜索。默认 scope 仅为 DM拒绝所有允许直接聊天。如果你在群组或频道里搜会被拒绝。OpenClaw 会记录一个包含派生出的 channel/chatType 的警告方便调试。放宽 scope 才能让 QMD 结果在群组显示。第六个错误索引不更新。原因可能是工作区只读沙箱以workspaceAccess: ro或none运行会跳过刷新。排查方法确认工作区可写。另外监视器有 1.5 秒防抖同步是异步的刚写完文件立刻搜可能略有陈旧。第七个错误切换嵌入模型后维度不匹配。从gemini-embedding-001768 维切到gemini-embedding-2-preview3072 维会改变向量大小在 768、1536、3072 之间改outputDimensionality同理。OpenClaw 检测到模型或维度更改会自动重新索引但你要等它跑完。第八个错误QMD 二进制缺失。如果你设了memory.backend qmd但没装 QMD CLIOpenClaw 会自动回退到内置 SQLite 管理器记忆工具继续工作。想用 QMD 就单独安装并确保qmd在网关 PATH 里。排查完这些你的记忆模块基本就稳了。最后把 CTA 分流说清楚排障和接入看 API Keys 和接入文档验证模型去模型对话长期编码和 Agent 任务上 Coding Plan。6. 把记忆模块用起来的下一步配置跑通之后我建议你先别急着堆功能而是把「写记忆」变成习惯。OpenClaw 的记忆是事实来源模型只记住写入磁盘的内容。你可以每天让 agent 把关键决策追加到memory/YYYY-MM-DD.md把长期偏好整理进MEMORY.md。如果有人让你「记住这个」直接要求机器人写入记忆不要留在上下文里。如果你要长期跑编码或 Agent 任务Coding Plan 入口是 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。API Keys 管理在 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 接入文档在 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。验证模型效果去 https://taotoken.net/models?utm_sourcetaotoken_aicg_blog_endutm_contentmodelsutm_campaignrewrite 。Claude Code 接入参考 https://taotoken.net/claude-code?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-codeutm_campaignrewrite 。最后提醒一句会话日志存在于磁盘上任何具有文件系统访问权限的进程或用户都可以读取所以请把磁盘访问视为信任边界。为了更严格的隔离在单独的操作系统用户或主机下运行 agents。记忆模块的价值在于跨会话保留上下文但前提是你把该写的写下来把该配的配正确。