ClawVault

ClawVault 核心评估

核心用法

ClawVault 是一款专为 OpenClaw 生态设计的Agent 记忆系统 CLI 工具，提供从会话恢复到知识图谱构建的全套记忆管理能力。核心工作流遵循 wake → checkpoint → sleep 周期：clawvault wake 在会话开始时恢复上下文并生成摘要；clawvault checkpoint 每10-15分钟保存工作状态；clawvault sleep 在会话结束时捕获交接信息。所有记忆以 Markdown 文件形式本地存储，支持八类结构化类型（decision、lesson、relationship 等），并通过 wiki-link 自动构建知识图谱。

搜索能力由语义引擎 qmd 驱动，提供关键词搜索 (clawvault search) 与语义搜索 (clawvault vsearch) 双模式。上下文检索支持五种场景化 Profile（planning、incident、handoff 等），可根据任务类型动态调整召回策略。repair-session 功能可修复 Anthropic API 报错导致的损坏会话转录，自动备份原始文件。

显著优点

1. 上下文死亡免疫：通过 checkpoint/recover/handoff 机制，彻底解决长会话中断后的状态丢失问题
2. 本地优先架构：零云同步，所有数据驻留本地文件系统，隐私可控
3. 知识图谱原生：wiki-link 自动关联生成图索引，支持图感知检索
4. OpenClaw 深度集成：提供官方 hook pack，支持生命周期事件自动触发（启动、心跳、内存压缩等）
5. 可审计透明：hook 源码随 skill 分发，用户需显式 review 后启用
6. 跨平台稳定：449项测试通过，Windows 路径处理已加固

潜在局限

• 外部依赖重：核心搜索功能依赖 qmd（非 npm 官方包，需从 GitHub 安装），安装链路较长
• Gemini 依赖可选但关键：observe --compress 功能需 GEMINI_API_KEY，否则无法使用 LLM 压缩能力
• 学习曲线陡峭：八类记忆类型、五种 context profile、hook 生命周期等概念需要用户建立使用习惯
• 修复功能侵入性：repair-session 直接修改 OpenClaw 会话转录，虽自动备份但仍属高风险操作
• 生态锁定：为 OpenClaw 深度优化，脱离该生态后价值显著降低

适合人群

• 长期运行 OpenClaw Agent 的开发者与团队
• 需要维护跨会话项目上下文的复杂工作流用户
• 对数据本地存储有强隐私要求的场景
• 愿意投入时间建立记忆管理纪律的进阶用户

常规风险

• 文件系统风险：CLI 直接读写用户目录文件，误操作可能导致数据覆盖（虽有备份机制）
• Hook 权限风险：启用 hook 后，ClawVault 可响应 OpenClaw 生命周期事件，需信任 hook 源码
• API 密钥泄露：GEMINI_API_KEY 需配置在环境变量，共享环境可能暴露
• 依赖供应链：qmd 从 GitHub 直接安装，缺少 npm 的完整性校验机制

核心用法

ClawVault 是专为 OpenClaw 设计的结构化记忆系统，解决 AI 助手对话中的"上下文死亡"问题。核心工作流围绕 Wake → Checkpoint → Sleep 循环构建：

• `clawvault wake`：会话启动时恢复上下文，聚合近期交接记录、活跃项目和待办承诺
• `clawvault checkpoint`：每10-15分钟保存工作状态快照，记录当前任务、专注点和阻塞项
• `clawvault sleep`：会话结束时捕获工作成果、下一步计划和阻塞状态

记忆存储采用类型化设计，支持 8 种记忆类型：fact、feeling、decision、lesson、commitment、preference、relationship、project。通过 clawvault remember <type> <title> --content "..." 结构化存储，配合 Wiki 链接（[[person-name]]）自动构建知识图谱。

搜索功能依赖 qmd 后端，支持关键词搜索（clawvault search）和语义搜索（clawvault vsearch）。上下文检索支持 5 种场景配置（default/planning/incident/handoff/auto），可根据任务类型动态调整召回策略。

显著优点

1. 上下文死亡免疫机制

• 完整的会话生命周期管理，从启动、工作到交接形成闭环
• 自动化的记忆压缩（observe --compress 调用 Gemini Flash）将长会话提炼为可检索的观察记录
• 会话损坏修复工具 repair-session 可处理 Anthropic API 返回的 tool_use_id 错误

2. 图感知的智能检索

• 基于 Wiki 链接和标签构建的增量式知识图谱（.clawvault/graph-index.json）
• 语义+图邻域的混合检索，默认召回相关内容的关联记忆
• 场景化配置支持战略规划、故障响应等不同工作模式

3. OpenClaw 原生集成

• 通过 Hook 机制（gateway:startup、session:start、compaction:memoryFlush 等 6 个生命周期事件）实现自动化上下文注入
• clawvault compat 命令可诊断集成漂移问题

4. 安全编码实践

• 所有外部命令调用使用 execFileSync + shell:false，杜绝命令注入
• 多层输入验证：会话密钥正则校验、Agent ID 验证、路径解析验证、控制字符过滤
• 文件操作前执行 normalizeAbsoluteEnvPath 和 validateVaultPath 校验

潜在缺点与局限性

1. 外部依赖的供应链风险

• 核心功能依赖两个外部 CLI 工具：clawvault（npm 包）和 qmd（GitHub 安装）
• 虽然文档提供了 npm view 验证流程，但依赖更新仍需人工审查
• qmd 通过 github:tobi/qmd 安装，版本锁定和完整性验证难度高于 npm registry

2. 环境配置复杂度

• 需要正确配置 CLAWVAULT_PATH、OPENCLAW_HOME、OPENCLAW_STATE_DIR 等环境变量
• Hook 安装需执行 3 步独立操作（install → enable → restart gateway），流程断裂风险较高
• Windows 路径处理虽已加固，但跨平台兼容性仍需持续关注

3. 功能边界限制

• 明确声明不用于一般文件 I/O，记忆存储需遵循预设类型和目录结构
• 语义搜索依赖 qmd 后端，未安装时降级为关键词搜索
• observe 功能的 LLM 压缩需要 GEMINI_API_KEY，且产生外部 API 调用

4. 数据本地化的双刃剑

• 无云同步意味着数据迁移和备份需用户自行处理
• 记忆库损坏或丢失将导致历史上下文不可恢复

适合人群

• OpenClaw 重度用户：需要从原生 Hook 集成中获得自动化上下文注入
• 多会话长周期项目参与者：需要跨天、跨周保持工作连续性（如复杂系统架构设计、长篇小说创作、长期研究项目）
• 团队协作场景：通过标准化的 handoff 格式实现人机协作中的状态交接
• 隐私敏感型用户：数据完全本地存储，无云端依赖

不适合：轻量级临时对话、单会话即可完成的简单任务、不愿投入配置成本的用户。

常规风险

| 风险类别 | 具体表现 | 缓解措施 |

|---------|---------|---------|

| 供应链攻击 | `clawvault` 或 `qmd` 包被植入恶意代码 | 严格执行 `npm view` 验证，使用 `npm ci` + lockfile，订阅 CVE 通知 |

| 会话数据泄露 | `repair-session` 读取 `~/.openclaw/agents/` 下的会话转录 | 确保目录权限正确（仅用户可读），备份文件自动创建 |

| API 密钥暴露 | `GEMINI_API_KEY` 用于 `observe` 功能 | 使用专用密钥而非生产密钥，限制 API 权限范围 |

| 路径遍历 | 恶意构造的 `CLAWVAULT_PATH` | 代码已实现 `normalizeAbsoluteEnvPath` 验证 |

| 钩子误配置 | Hook 安装但未启用，或启用后未重启 gateway | 使用 `openclaw hooks check` 验证状态 |

| 数据丢失 | 本地存储无自动备份 | 定期手动备份 vault 目录，或使用版本控制 |

建议的安全安装流程：先 npm view 验证包元数据 → 安装 CLI → 安装 Hook（不启用）→ 审查 handler.js 源码 → 启用 Hook → 验证 → 重启 gateway。