1. 为什么智能体需要长期记忆：从会话沙箱到文件系统
OpenClaw 长期记忆机制的核心，是把智能体的状态从内存搬到磁盘，用文件系统做持久化载体。如果你正在用 OpenClaw 做跨天协作、维护业务规则库，或者希望智能体记住你的输出格式偏好，那这套机制就是必须吃透的部分。它适合已经跑通基础对话、准备把智能体接入真实工作流的开发者，也适合想理解"状态持久化"到底怎么落地的人。
会话级 AI 的通病很直接：每个会话是独立沙箱，窗口一关，上下文清空。你花半小时讲清楚项目背景、接口约定、命名规范，第二天再打开，它像第一次见你。对于一次性问答这无所谓，但对于需要持续跟进的任务——比如每天整理会议纪要、按固定规则分类文档、维护一套业务红线——这种"失忆"会让每次交互都变成重复劳动。
OpenClaw 的设计选择很朴素：不引入向量数据库，不依赖外部记忆服务，直接把记忆写成文件，写进磁盘。这套路径的本质是把 AI 从"无状态服务"变成"有状态伙伴"。文件即记忆，记忆即人格。当智能体能记住你是谁、做过什么、偏好什么，它才从工具变成协作者。
三层记忆架构是理解整套机制的钥匙。第一层是MEMORY.md，长期主脑，记录持久偏好、决策习惯、项目上下文，跨会话保留。第二层是memory/目录，按天写入memory/YYYY-MM-DD.md，相当于智能体的每日工作日志，是未经提炼的原始素材。第三层是记忆提炼机制，定期从每日日志中提取有价值的信息，回写到MEMORY.md。就像人的记忆，不是每件事都记住，但重要的决策、偏好和教训要沉淀下来。
我试过把这套结构类比成笔记系统：MEMORY.md是你的长期笔记本，memory/是每天的草稿纸，提炼机制就是你每周回顾草稿、把要点誊抄到长期笔记本的动作。区别在于，OpenClaw 把这个动作自动化了。
2. TaoToken 前置：把模型接入和记忆持久化解耦
在动手配置 OpenClaw 的记忆机制之前，需要先把模型调用这条链路打通。OpenClaw 负责状态持久化和智能体编排，模型推理则通过兼容接口调用。TaoToken 在这里扮演的是模型接入层的角色，它提供 OpenAI 兼容的 API 端点，让 OpenClaw 可以用统一的base_url和api_key去请求不同模型，而不必为每个模型单独改代码。
这样做的好处是解耦。记忆机制关心的是文件读写和状态恢复，模型接入关心的是请求转发和密钥管理，两者互不干扰。你换模型时，记忆目录里的内容原封不动；你调整记忆结构时，模型调用配置也不用动。
具体操作上，你需要先拿到一个可用的 API Key。登录 TaoToken 控制台，在 API Keys 页面创建一个新密钥，复制保存。这个 Key 后面会写进 OpenClaw 的配置文件，用于鉴权。如果你还没创建过，可以直接访问 TaoToken API Keys 管理页 完成创建。
拿到 Key 之后，模型对话能力可以先单独验证一下，确认 Key 有效、端点可达。你可以用 TaoToken 模型对话 页面做一次快速对话测试，或者直接用 curl 请求/v1/chat/completions。这一步的目的是把"模型能不能调通"和"记忆能不能持久化"两个问题分开排查，避免后面出错时不知道是哪一层的问题。
如果你打算长期跑编码类或 Agent 类任务，建议了解一下 TaoToken Coding Plan，它在配额和调用方式上更适合持续性的智能体场景。接入细节和参数说明可以参考 TaoToken 接入文档。
3. 可复制配置：config.toml 骨架与 settings.json 示例
OpenClaw 的记忆持久化配置分两部分：config.toml定义记忆目录、提炼策略和模型接入，settings.json定义运行时行为和状态文件路径。下面给出可直接复制的骨架，你只需要替换api_key和路径。
先看config.toml：
[agent] name = "openclaw-agent" workspace = "/data/openclaw/workspace" [memory] # 长期记忆主文件 long_term_file = "/data/openclaw/workspace/MEMORY.md" # 每日日志目录 daily_dir = "/data/openclaw/workspace/memory" # 日志文件命名格式 daily_pattern = "%Y-%m-%d.md" # 提炼触发：每次会话结束后尝试提炼 refine_on_session_end = true # 提炼时保留的最近日志天数 refine_window_days = 7 # 单条记忆最大字符数，超出截断 max_entry_chars = 2000 [model] provider = "openai-compatible" base_url = "https://taotoken.net/api" api_key = "sk-你的TaoToken密钥" model = "gpt-4o-mini" timeout_seconds = 60 [state] # 状态持久化文件，记录会话指针和记忆索引 state_file = "/data/openclaw/workspace/state.json" # 写入模式：append 追加，overwrite 覆盖 write_mode = "append" # 是否在每次写入后 fsync，保证落盘 fsync_on_write = true几个关键项说明。long_term_file和daily_dir决定了记忆的物理位置，建议放在独立的数据盘或挂载卷上，避免容器重建时丢失。refine_on_session_end控制是否在会话结束时自动提炼，如果你希望手动控制提炼时机，可以设为false，改用定时任务触发。fsync_on_write是保证持久化的关键，开启后每次写入都会调用系统调用把数据刷到磁盘，代价是略微增加延迟，但对状态可靠性要求高的场景值得开。
再看settings.json：
{ "runtime": { "session_id": "default", "load_memory_on_start": true, "memory_inject_position": "system", "max_memory_tokens": 3000 }, "persistence": { "state_file": "/data/openclaw/workspace/state.json", "checkpoint_interval_seconds": 30, "recover_on_restart": true }, "logging": { "level": "info", "file": "/data/openclaw/workspace/logs/agent.log" } }load_memory_on_start决定启动时是否把MEMORY.md注入上下文，这是"重启后还记得"的前提。memory_inject_position设为system表示记忆内容作为系统提示的一部分注入，优先级高于普通对话历史。max_memory_tokens限制注入的记忆长度，避免长期记忆膨胀后挤占上下文窗口。recover_on_restart开启后，进程重启会从state.json恢复会话指针和记忆索引。
目录结构建议这样组织：
/data/openclaw/workspace/ ├── MEMORY.md ├── state.json ├── memory/ │ ├── 2025-01-15.md │ ├── 2025-01-16.md │ └── 2025-01-17.md └── logs/ └── agent.logMEMORY.md是长期主脑，memory/下按天存放日志，state.json记录运行时状态，logs/放日志。这个结构清晰、易备份、易迁移，直接tar打包就能带走全部记忆。
4. 验证请求：一次记忆写入与重启后读取的完整动作
配置写好后，必须验证状态是否真正持久化。验证分三步：写入一条记忆、重启进程、读取记忆确认还在。
第一步，启动 OpenClaw 并让它写入一条记忆。你可以通过对话触发，也可以直接调用记忆写入接口。假设我们用对话方式，发送这样一条消息：
请记住：我的报表输出格式偏好是 Markdown 表格，项目分类规则按"客户-季度"两级，接口对接使用飞书开放平台。OpenClaw 在处理这条消息后，如果refine_on_session_end为true，会在会话结束时把这条信息提炼进MEMORY.md。你也可以手动检查memory/目录下当天的日志文件，应该能看到原始记录。
第二步，确认写入结果。查看MEMORY.md：
cat /data/openclaw/workspace/MEMORY.md预期输出类似：
## 用户偏好 - 报表输出格式：Markdown 表格 - 项目分类规则：客户-季度 两级 - 接口对接：飞书开放平台同时检查state.json是否更新了记忆索引和时间戳：
cat /data/openclaw/workspace/state.json第三步，重启进程并读取。先停掉 OpenClaw：
pkill -f openclaw-agent再重新启动：
openclaw-agent --config /data/openclaw/workspace/config.toml启动后，发送一条不包含任何背景信息的消息：
帮我整理上周的会议纪要。如果记忆持久化生效，OpenClaw 应该能自动关联之前存储的偏好——按"客户-季度"分类、输出 Markdown 表格、从飞书拉取数据。你不需要重新描述这些规则。这就是状态持久化的直接证据。
如果想更严格地验证，可以在重启后直接查询记忆内容：
curl -X POST https://taotoken.net/api/v1/chat/completions \ -H "Authorization: Bearer sk-你的TaoToken密钥" \ -H "Content-Type: application/json" \ -d '{ "model": "gpt-4o-mini", "messages": [ {"role": "system", "content": "你是一个有长期记忆的助手。"}, {"role": "user", "content": "我的报表输出格式偏好是什么？"} ] }'注意，这个请求验证的是模型调用链路，记忆注入由 OpenClaw 在组装请求时完成。如果你直接用 curl 请求，需要手动把MEMORY.md的内容拼进system消息里。更推荐的方式是通过 OpenClaw 自身的对话接口触发，让它自动完成记忆注入。
5. 本篇常见错排查：记忆不持久、路径错、权限与提炼失败
配置过程中最容易踩的坑集中在四类：记忆没落盘、路径写错、权限不足、提炼失败。
记忆没落盘，表现为重启后MEMORY.md内容丢失或回到旧版本。原因通常是fsync_on_write没开，或者进程被kill -9强杀导致缓冲区数据没刷盘。排查方法：写入后立即cat文件确认内容在，然后正常停止进程再重启。如果正常停止后内容还在、强杀后丢失，就是 fsync 的问题。把fsync_on_write设为true可以解决。
路径写错，表现为启动时报file not found或记忆写到了意外位置。常见原因是config.toml里用了相对路径，而进程的工作目录和你想的不一样。排查方法：全部改用绝对路径，启动后用lsof -p <pid>查看进程打开的文件，确认记忆文件路径符合预期。另外注意daily_pattern的格式，%Y-%m-%d.md生成的是2025-01-17.md，如果你写成%Y/%m/%d.md会生成子目录，需要提前创建。
权限不足，表现为写入时报permission denied。如果 OpenClaw 以非 root 用户运行，而/data/openclaw/workspace属于 root，就会写不进去。排查方法：ls -ld /data/openclaw/workspace看属主，用chown -R openclaw:openclaw /data/openclaw/workspace修正。容器场景下还要注意挂载卷的权限映射。
提炼失败，表现为memory/里有日志但MEMORY.md一直不更新。原因可能是refine_on_session_end为false且没有配置定时任务，或者提炼时模型调用失败。排查方法：看logs/agent.log里有没有提炼相关的错误，检查base_url和api_key是否正确，确认模型端点可达。如果用的是 TaoToken 的兼容端点，base_url应该是https://taotoken.net/api，不要多加/v1，具体以 TaoToken 接入文档 为准。
还有一个隐蔽的坑：max_memory_tokens设得太小，导致长期记忆被截断，智能体"记得但不全"。表现是它知道你有格式偏好，但记不清具体是哪种格式。排查方法：看注入上下文时实际用了多少 token，适当调大max_memory_tokens，或者优化MEMORY.md的结构，把最重要的信息放在前面。
6. 从文件系统到智能体：状态持久化的工程取舍
OpenClaw 这套记忆机制的价值，不在于它用了多复杂的技术，而在于它做了一个清晰的工程取舍：用文件系统而不是向量数据库做持久化。这个选择带来几个实际好处。可读性强，你随时可以cat MEMORY.md看智能体记住了什么，不用去查数据库。可迁移性强，打包目录就能带走全部记忆，换机器、换环境都不丢。可版本控制，把 workspace 纳入 git，记忆的每次变更都有记录，出问题能回滚。
代价也有。文件系统不适合做语义检索，当记忆量很大时，靠关键词匹配找相关信息不如向量检索精准。OpenClaw 的应对方式是分层：MEMORY.md只放提炼后的高价值信息，控制体积；memory/放原始日志，需要时再检索。这个分层策略在中小规模场景下足够用，规模再大可以考虑在提炼层引入检索增强。
如果你准备把这套机制用到生产环境，建议做三件事。第一，给 workspace 配定期备份，记忆是智能体的核心资产，丢了很难重建。第二，监控MEMORY.md的体积和state.json的更新时间，异常增长或长时间不更新都可能是问题信号。第三，把记忆提炼的 prompt 调优纳入日常迭代，提炼质量直接决定长期记忆的可用性。
回到最初的问题：为什么 AI 需要长期记忆？因为真正的协作需要连续性。你不需要每次见面都重新自我介绍，智能体也不应该。文件系统给了这套机制一个朴素但可靠的底座，剩下的就是配置、验证、迭代。把config.toml和settings.json配好，跑一次写入和重启读取的验证，你就能确认状态是否真正持久化。确认之后，智能体才真正开始"记住"你。
