文件层：记忆的第一现场

OpenClaw 的记忆本体就是一堆 Markdown，按热度分层：

workspace/
├── MEMORY.md            # 长期精炼记忆（画像/项目/待办/钦定规则）——主会话每次注入
└── memory/
    ├── daily/           # 每日原始日志 YYYY-MM-DD.md——当天事实随手写
    ├── projects/        # 专项档案（某条业务线的完整历史）
    ├── profiles/ contacts/ schedules/ context/   # 人物/日程/上下文档案
    └── ── 结构化知识 → ~/.openclaw/wiki/main/（entities/concepts/syntheses/sources）

运转节奏：当天事写 daily，定期（我放在每天 23:56 的 cron 维护班）把 daily 提炼进 MEMORY.md，过时内容清理或迁 projects 档案。主人说"记住这个"，必须立刻落文件——没有"心里记一下"这回事，因为每次会话都是全新醒来。关联信息用 [[双向链接]]，这玩法直接抄 Obsidian。

这条路上我交过的学费是体积：这些文件每次会话都注入，就是持续的 token 成本。9/25 大瘦身，TOOLS.md 12.6KB→3.7KB、开机注入总量 42KB→20KB，手法就一招——细节全部下沉到 projects 档案，常驻只留指针。

索引层：坏过三次的位置

文件多了要找回来，靠内置 memory_search（向量语义+关键词两路并行，和我做 RAG 项目的混合检索同一个架构）。它的三次事故：

事故一（6/19）：一个反斜杠消失在搜索里。 现象：前一天的发布记录搜不到。根因：openclaw.json 里 memorySearch.extraPaths 写了单反斜杠路径，JSON 未转义，自定义目录（profiles/projects 等）全部加载失败。修复：改双反斜杠 \\，重启网关。附带发现：session-memory hook 也没把旧会话落盘——从此我定了规矩：重要对话手动写 daily，不赌自动 hook。

事故二（9/3 起，瘫了近 50 天）：语义那条腿断了。 现象：memory_search 持续不可用。当时定位到"openai provider 无 API key"，先拿 qmd CLI 和直接读文件兜底，业务照常跑——检索坏了不等于记忆丢了，文件才是事实源，这是这个架构最让我安心的一点。

事故三（10/21 根治）：根因查实。 配置里只有 extraPaths 没写 embedding provider → 系统默认走 OpenAI 的 embeddings 接口要 OPENAI_API_KEY → 本机没这个 key → 语义检索废了，qmd 也是同一个死因。当天修复：

// agents.defaults.memorySearch
"provider": "openai-compatible",
"model": "BAAI/bge-m3",
"remote": { "baseUrl": "https://api.siliconflow.cn/v1", "apiKey": "<复用我 .env 里的 SILICONFLOW key>" }

然后 openclaw memory index --force 全量重建索引，config validate 通过，实测查询返回正常（vectorScore 有值了）。选 bge-m3 是因为它本来就是我 RAG 学习项目的同款，硅基流动免费档够用，同路还有 bge-reranker-v2-m3 以后精排可以直接复用。成本：零（key 现成，模型白嫖）。

验收记忆是否真的在

openclaw memory status      # 索引状态
openclaw memory index --force  # 重建
qmd update && qmd embed --no-gpu  # 备用 CLI 索引

再加一条行为层的验收：隔几天新开一个会话，问它"我 9 月干过什么"——能从 daily 和 MEMORY.md 里答对，这套记忆才算活着。

「OpenClaw 实战」系列（随我用随更）：① Windows 安装上线篇 · ② 架构扫盲 · ③ 控制台与日常使用 · ④ 模型接入 · ⑤ 记忆系统 · ⑥ 定时任务与降本 · ⑦ 增加依赖

四层结构

聊天渠道(微信/网页/…) ──> Gateway(常驻网关进程) ──> Agent(模型+工具) ──> Workspace(Markdown 文件们)

1. Gateway 网关。 本机常驻的 WebSocket 服务，一切的中枢：渠道消息进它，Agent 调用经它，定时任务、日志都归它管。CLI 里 openclaw gateway 一族负责起停查。我 5 月第一次升级时就是 CLI 升到 2026.5.18 后网关服务没对齐，重装服务才恢复——它是独立于 CLI 的常驻进程，这个认知能解释一大半"明明改了为什么不生效"（配置热改后多数要重启网关加载，我 9/25 那次 thinkingDefault 改完就是 15:56 重启才生效）。

2. Sessions 会话。 每条聊天线都是一个持久会话，key 长这样（我自己的）：

agent:main:openclaw-weixin:direct:o9cq…@im.wechat

读法：哪个agent : 哪条渠道 : 私聊还是群聊 : 对方是谁。每个会话有独立的历史与上下文，openclaw sessions list、openclaw transcripts 可以直接翻存储的会话和转录——透明，没有黑盒。

3. Agent 与工具。 模型负责想，工具负责做：exec（shell）、read/write/edit、browser、cron、web_search 这些，按策略过滤后授权给会话。工具清单不是背出来的，是每次运行时注入的元数据——所以"我的工具箱"里我能干啥，取决于配置，不取决于传说。子 agent（sessions_spawn）用来把长任务丢后台，跑完把结果推回来，主会话不陪着卡死。

4. Workspace 工作区。 这是 OpenClaw 最有味道的设计：人格和记忆全是 Markdown 文件。我的 D:\openClaw\workspace 根目录：

每次会话开始，这几个文件被注入进上下文——所以"每次都是全新醒来，文件即记忆"。会话之间它什么都不记得，但读完文件它就知道我是谁、进度到哪、哪些事不能干。

两个值得聊的设计取舍

取舍一：记忆在文件，也在索引。 注入的只有那几份 bootstrap 文件（我 9/25 降本时把这块从 42KB 瘦到 20KB，因为每次会话都背着它们跑 token）。历史日志靠 memory_search 语义检索按需捞回，另有 wiki 知识库目录（~\.openclaw\wiki\）。文件是事实源，索引是加速层——索引坏了数据不丢，这个架构对我这种要长期攒记忆的人很关键，具体故事见系列第五篇。

取舍二：上下文是成本，也是纪律。 大模型按 token 计费，注入越多越贵越慢。所以我把"详细操作手册"都沉到 projects 档案里，常驻的只留高频守则和指针；心跳（heartbeat，每 30 分钟自动唤醒跑一轮模型）直接禁用，用便宜的 cron + 纯脚本接管。这套账算下来是第六篇的主题。

架构层自查命令

openclaw status          # 网关/渠道/模型/最近会话总览
openclaw sessions list   # 存量会话
openclaw agents list     # 隔离 agent（工作区+路由）
openclaw channels list   # 接了哪些聊天渠道
openclaw config get      # 当前配置

一句话总结架构：网关是身体，会话是神经，工具是手，Markdown 文件是记忆。搞清楚这四层，后面装模型、接微信、修记忆、排任务都是按图索骥。

「OpenClaw 实战」系列（随我用随更）：① Windows 安装上线篇 · ② 架构扫盲 · ③ 控制台与日常使用 · ④ 模型接入 · ⑤ 记忆系统 · ⑥ 定时任务与降本 · ⑦ 增加依赖