🐾 claw-stack

最后更新：2026 年 3 月 · 源码：openclaw-backup

加密状态存档

将 OpenClaw 工作区和本地项目自动加密、去重备份到 Google Drive——使用 restic 进行加密和快照管理，rclone 进行传输，加密密码存储在 macOS 钥匙串中。

← 模块概览

是什么

openclaw-backup 创建 OpenClaw 工作区和本地项目目录的增量、加密、时间点快照，并将其存储在 Google Drive 上。每次备份运行都会添加一个新快照；未更改的块会被去重，因此只上传更改的数据。保留策略会自动清理旧快照。加密密码永远不会接触磁盘——它在每次运行时从 macOS 钥匙串中检索。

为什么

智能体系统会积累难以重建的状态：经过数月会话建立的记忆文件、进行中的项目代码、花时间调整的配置。没有备份的磁盘故障、意外删除或工作区损坏意味着完全丢失这些状态。

标准云同步工具（iCloud、Dropbox）在上传前不加密，不追踪快照历史，也不去重。用户无法恢复到"三天前的工作区状态"——只能恢复到当前同步状态。restic 解决了这三个问题：客户端加密（Google Drive 只看到密文）、内容寻址去重（快速增量）和具有可配置保留策略的不可变时间点快照。

架构

两个层次在每次备份运行时协作：

restic — 加密 + 去重 + 快照管理

restic 创建内容寻址的加密快照。只存储更改的块；未更改的块引用现有数据。加密密码在每次运行时从 macOS 钥匙串读取——永远不会写入磁盘。

rclone — Google Drive 传输

rclone 提供 restic 写入的后端。它处理 Google Drive OAuth 和文件传输层。OAuth 令牌存储在从 git 中排除的配置文件中。

~/.openclaw/  ──┐
               ├──▶ restic（加密 + 去重）──▶ rclone ──▶ Google Drive
~/projects/   ──┘

备份内容：

路径 大约大小 内容
~/.openclaw/ 约 2.9 GB 配置、工作区、记忆文件、日志、媒体
~/projects/ 约 1.3 GB 源代码、实验

排除项（不备份）：

  • node_modules/ — 可从 package.json 重新安装
  • .venv/ — 可重建的 Python 环境
  • browser/ — Chromium 二进制缓存
  • .git/objects — 已在 GitHub 上

保留策略：

周期 保留
每日 最近 7 天
每周 最近 4 周

较旧的快照在每次备份运行结束时自动清理。

关键设计决策

restic 而非 tar/zip——内容寻址去重

restic 将文件分割成可变大小的块，并通过内容哈希识别它们。只上传仓库中不存在的块。这使得增量备份非常快——只有记忆文件发生变化的会话只上传那些块，而不是整个 4 GB 工作区。

macOS 钥匙串——密码永不落盘

restic 加密密码存储在钥匙串中，使用服务/账户键对。备份脚本在运行时使用 security CLI 检索它。没有明文密码出现在配置文件、环境变量导出或 shell 历史记录中。

test.sh 中的主动密钥扫描

测试脚本主动扫描所有 git 追踪文件中看起来像密钥的模式（API 密钥、令牌、密码）。这在任何备份之前运行，以防止意外将凭据与备份基础设施代码一起提交。

不可变快照——永不覆盖，只清理

每次备份运行都会向仓库添加一个新快照。旧快照只由保留策略清理步骤删除，而不是覆盖。在任何时候，你都可以恢复到保留窗口内的任何快照——而不仅仅是最近的一个。

如何自行构建

1. 将 restic 与任何 rclone 支持的后端一起使用

相同的架构适用于任何 rclone 后端：S3、Backblaze B2、Azure Blob、SFTP。这里使用 Google Drive 是因为它免费提供 15 GB 且不需要信用卡。在备份脚本中更改 rclone 远程名称即可更换后端。

2. 将加密密码存储在系统密钥管理器中

在 macOS 上，钥匙串是正确的选择。在 Linux 上，使用 pass（GPG 支持）或由密钥管理器在运行时设置的 RESTIC_PASSWORD 环境变量。永远不要将密码存储在点文件中。

3. 构建全面的排除列表

node_modules、Python 虚拟环境、浏览器缓存和编译输出很容易添加几 GB 完全可以重新安装的内容。排除它们。一个好规则：如果一个目录可以从提交的源代码重建（package.json、requirements.txt 等），就排除它。

4. 在需要之前测试恢复过程

从未测试过的备份不是备份。在测试清单中包含模拟恢复。恢复到临时目录并验证关键文件是否存在且完整。发现备份恢复过程损坏的最坏时机是在实际恢复期间。

5. 备份失败时触发系统事件通知

静默的备份失败是最危险的。备份脚本应该在备份失败时发送通知（通过 OpenClaw 系统事件、电子邮件或任何你实际上会看到的其他渠道）。成功的备份应该静默记录；失败应该大声报警。

安全性

  • 无硬编码密钥——所有凭据使用 macOS 钥匙串或环境变量
  • restic 在上传前加密所有数据；Google Drive 只存储密文
  • rclone 配置中的 OAuth 令牌通过 .gitignore 从 git 中排除
  • test.sh 主动扫描所有 git 追踪文件中的密钥

常见问题

restic 加密密码存储在哪里？

存储在 macOS 钥匙串中，服务名称为 openclaw-backup，账户为 restic-password。安装脚本会自动生成并存储它。你也可以用 RESTIC_PASSWORD 环境变量覆盖它。

备份会互相覆盖吗？

不会。restic 创建不可变快照。每次备份运行都会添加一个新快照；旧快照只有在保留策略清理时才会被删除。你可以恢复到保留窗口内的任何历史快照。

这在 Linux 上可以使用吗？

钥匙串集成是 macOS 特有的。在 Linux 上你需要替换不同的密钥存储（例如 pass）或直接使用 RESTIC_PASSWORD 环境变量。restic 和 rclone 命令本身是跨平台的。

Authors: Qiushi Wu & Orange 🍊