码耕记

耕码记

OpenClaw 每日笔记生成故障排查与配置指南

2026/07/16
#openclaw
3
0

OpenClaw 每日笔记生成故障排查与配置指南

📌 文档说明

本文档旨在解决 OpenClaw 中 memory/YYYY-MM-DD.md 每日笔记无法自动生成的问题。涵盖从核心机制解释、配置详解、故障排查到常见问题的完整指南。

一、核心机制理解

1.1 每日笔记的生成原理

memory/YYYY-MM-DD.md 的生成不是定时任务，而是由 memoryFlush 机制在特定条件下触发的：

触发条件说明
上下文接近上限会话使用的 token 数量达到压缩阈值
压缩模式为 safeguardcompaction.mode 必须为 "safeguard"
memoryFlush 已启用memoryFlush.enabled 必须为 true
工作区可写workspaceAccess 为 "rw"

触发流程：

上下文接近上限 → 触发 memoryFlush → 写入 memory/YYYY-MM-DD.md → 执行上下文压缩

1.2 重要概念区分

概念说明是否必须
memoryFlush压缩前触发的同步写入机制✅ 生成每日笔记必须
Dreaming（梦境）后台异步总结任务❌ 非必须，可关闭
compaction.mode压缩模式控制✅ 必须为 safeguard

二、完整配置方案

2.1 最小必需配置

这是生成每日笔记最低要求的配置：

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 40000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true
      }
    }
  }
}

2.2 推荐完整配置（含明确指令）

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 40000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000,
          "prompt": "将当前会话的关键信息、待办事项和重要结论，以简洁的要点形式写入 memory/YYYY-MM-DD.md 文件。如果文件已存在，追加内容。如果没有值得记录的内容，回复 SKIP。不要创建带时间戳的变体文件。"
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true,
        "config": {
          "dreaming": {
            "enabled": false
          }
        }
      }
    }
  },
  "workspaceAccess": "rw"
}

2.3 配置参数详解

参数说明建议值
compaction.mode压缩模式，safeguard 是唯一能触发 memoryFlush 的模式"safeguard"
reserveTokensFloor触发压缩前的预留 token 空间40000（轻量使用）或 60000（大量操作）
softThresholdTokensmemoryFlush 的软触发阈值4000
softThresholdPercent百分比阈值（与上者二选一，适用于超大上下文模型）2（代表 2%）
memoryFlush.prompt自定义提示词，指导模型如何写入见上方示例
workspaceAccess工作区访问权限"rw"

三、故障排查步骤

3.1 快速检查清单

按顺序确认以下项目：

  • compaction.mode 是否为 "safeguard"？
  • memoryFlush.enabled 是否为 true？
  • memory-core 插件是否已启用？
  • workspaceAccess 是否为 "rw"？
  • 会话上下文是否达到了压缩阈值？（用 /context 查看）
  • 日志中是否有报错信息？

3.2 强制触发测试

如果自然会话无法触发，可手动制造上下文压力：

  1. 开启新会话：/new 或 /reset

  2. 输入大量文本填充上下文：

    请逐字重复以下内容 100 遍：[粘贴一篇长文章]

  3. 持续对话直到接近上下文上限

  4. 检查 memory/ 目录下是否生成当天 .md 文件

3.3 日志排查

查看网关日志，搜索关键字：

# 查看最近日志
openclaw logs --tail 100 | grep -i "memory"

# 或直接查看日志文件
tail -100 /tmp/openclaw/gateway.log | grep -i "memory"

日志含义对照表：

日志内容含义解决方案
memoryFlush enabled but workspace is read-only工作区只读将 workspaceAccess 改为 "rw"
skipping memory flush, context not compressed未达到压缩阈值正常，继续对话直到触发
narrative generation produced no text模型生成空内容添加明确的 prompt 或更换模型
failed to write diary entry写入文件失败检查文件系统权限和磁盘空间
memoryFlush triggered成功触发正常，检查文件是否生成

四、关于 Dreaming（梦境）

4.1 Dreaming 与每日笔记的关系

功能作用是否影响每日笔记
Dreaming后台异步总结任务❌ 不影响
memoryFlush同步写入机制✅ 直接负责生成

结论：生成每日笔记不依赖 Dreaming，可以安全关闭。

4.2 关闭 Dreaming 的配置

{
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true,
        "config": {
          "dreaming": {
            "enabled": false
          }
        }
      }
    }
  }
}

五、关于 openclaw-hyperspell

5.1 这是什么？

openclaw-hyperspell 是一个第三方记忆插件，提供比默认 memory-core 更强大的记忆能力：

  • 知识图谱：按需检索，不占上下文
  • 外部集成：支持 Notion、Slack、Google Drive、Gmail、GitHub 等
  • 自动同步：可将本地 memory/ 文件夹的笔记同步到其系统

5.2 与每日笔记的兼容性

Hyperspell 会占用记忆插槽（memory slot），但不影响 memoryFlush 机制。配置方式：

{
  "plugins": {
    "slots": {
      "memory": "openclaw-hyperspell"
    },
    "entries": {
      "openclaw-hyperspell": {
        "enabled": true,
        "config": {
          "dreaming": { "enabled": true }
        }
      },
      "memory-core": {
        "enabled": true
      }
    }
  }
}

六、常见问题解答

Q1: 配置都正确，但文件还是不生成？

A: 最常见的原因是会话上下文未达到压缩阈值。确认方法：

  • 使用 /context 命令查看当前使用量
  • 对比 reserveTokensFloor 设置
  • 如果会话很短，自然不会触发

Q2: 文件生成了但内容为空？

A: 可能是模型的默认行为问题，添加明确的 prompt 解决（见 2.2 节）。

Q3: 开启了 Dreaming 会冲突吗？

A: 不会。Dreaming 和 memoryFlush 是两个独立的机制，可以同时运行。

Q4: 我用了 Hyperspell，还能用每日笔记吗？

A: 可以。确保 memory-core 保持启用状态，memoryFlush 机制不受影响。

Q5: 如何手动生成每日笔记？

A: 在会话中直接输入：

请将今天的对话总结写入 memory/YYYY-MM-DD.md

这是绕过自动机制的临时方案。

七、快速参考

7.1 配置检查命令

# 查看当前配置
cat ~/.openclaw/openclaw.json | grep -A 10 "compaction"

# 查看插件状态
openclaw plugins list

# 查看会话上下文
# 在会话中运行
/context
/context list

7.2 配置文件路径

项目路径
主配置文件~/.openclaw/openclaw.json
工作区目录~/.openclaw/workspace/
每日笔记目录~/.openclaw/workspace/memory/
网关日志/tmp/openclaw/gateway.log

7.3 最小配置模板

{
  "agents": {
    "defaults": {
      "compaction": {
        "mode": "safeguard",
        "reserveTokensFloor": 40000,
        "memoryFlush": {
          "enabled": true,
          "softThresholdTokens": 4000
        }
      }
    }
  },
  "plugins": {
    "entries": {
      "memory-core": {
        "enabled": true
      }
    }
  },
  "workspaceAccess": "rw"
}

八、总结

生成每日笔记的核心三要素：

  1. 配置正确：compaction.mode = "safeguard" + memoryFlush.enabled = true
  2. 条件满足：会话上下文达到压缩阈值
  3. 权限到位：工作区可写（workspaceAccess = "rw"）

如果三要素都满足但仍不生效，请查看日志定位具体问题。大多数情况下，问题出在配置不完整或会话太短未触发。