openclaw-ledger

OpenClaw Ledger 是一款专为 Agent 工作空间设计的防篡改审计追踪工具，通过构建基于 SHA-256 的哈希链日志系统，为每一次文件变更、命令执行和技能安装提供不可篡改的可验证记录。该工具解决了传统 Agent 操作无留痕、难追溯的痛点，确保所有工作空间变更均可被完整记录并在事后验证其真实性。

核心用法方面，用户首先通过 init 命令在指定工作目录初始化账本，创建初始快照；随后使用 record 命令定期记录变更，支持添加自定义消息注释；通过 verify 命令可随时验证哈希链的完整性，一旦任何条目被修改、插入或删除，链条断裂将立即被检测；log 和 status 命令则用于查看历史记录和当前状态。整个过程基于 Python 3 标准库实现，无需额外安装依赖。

显著优点包括：首先是防篡改保证，利用区块链类似的哈希链技术，确保日志条目无法被事后修改而不被发现；其次是零依赖架构，仅使用 Python 标准库，无 pip 安装需求，无网络调用，杜绝了供应链攻击风险；第三是隐私安全，所有数据完全本地存储在 .ledger 目录，不上传云端，用户拥有数据的完全控制权；第四是跨平台兼容，支持 OpenClaw、Claude Code、Cursor 等主流 Agent 工具，适用于 macOS、Linux 和 Windows。

潜在缺点与局限性主要在于：该工具仅提供完整性校验而非加密存储，若工作目录本身被未授权访问，攻击者虽会留下篡改痕迹，但仍可能读取敏感文件；其次，纯本地化设计意味着无法实现多设备同步或云端备份，若本地存储损坏且未手动备份，审计记录可能丢失；此外，对于包含大量文件的大型工作空间，定期计算 SHA-256 哈希可能带来一定的性能开销；最后，工具要求目标环境必须预装 Python 3.8+，在极简容器中可能需要额外配置。

适合的目标群体主要包括：需要满足合规性审计要求的企业开发团队；对操作可追溯性有严格要求的 DevOps 和运维工程师；多人协作场景下需要验证工作空间变更完整性的项目组；以及安全研究人员和需要对 Agent 行为进行取证分析的高级用户。

使用风险方面，常规风险包括：随着操作次数增加，.ledger 目录的日志文件将持续增长，长期运行可能占用显著磁盘空间；频繁的文件扫描和哈希计算在机械硬盘或高负载系统上可能影响性能；虽然工具本身安全，但若赋予其对敏感系统目录的访问权限，可能因路径遍历（尽管已实现防护）或误操作导致意外文件扫描。建议仅在必要时授予特定工作目录的访问权限，并定期使用 freeze 命令创建只读备份。