clawsync 技能

clawsync 为 OpenClaw 提供基于 Git 的备份/迁移工作流，具备原生 Git 同步能力与更安全的恢复行为。

安装

一键安装（GitHub Releases）

curl -fsSL "https://raw.githubusercontent.com/linsheng9731/clawsync/main/scripts/install.sh" | CLAWSYNC_GH_REPO="linsheng9731/clawsync" bash

安装指定版本：

curl -fsSL "https://raw.githubusercontent.com/linsheng9731/clawsync/main/scripts/install.sh" | CLAWSYNC_GH_REPO="linsheng9731/clawsync" bash -s -- v0.1.8

默认安装路径：~/.local/bin/clawsync（可通过 CLAWSYNC_INSTALL_DIR 覆盖）。请确保该路径已加入您的 PATH 环境变量。

本地开发安装

npm install
npm run build
npm link
clawsync --help

功能亮点

• 更完整的 Git 原生工作流：提供一流的 clawsync git init、push、pull 和 merge 命令，支持基于分支的备份与恢复。
• 细粒度备份范围控制：支持 --include、--exclude、--ignore-paths 及 --workspace-include-globs 参数，精确控制归档内容。
• 内置敏感数据脱敏流水线：支持对密钥进行占位符替换，并在恢复后提供环境变量恢复脚本指引。
• 更丰富的恢复策略：支持 overwrite（覆盖）、skip（跳过）及本地优先的 merge（合并）模式，并默认启用多重安全机制（--dry-run、恢复前快照、网关令牌保留等）。

适用场景

当用户提出以下需求时，请使用本技能：

• 将 OpenClaw 状态备份至 Git 或本地归档
• 将 OpenClaw 数据迁移至其他机器
• 从本地归档或 Git 分支中恢复数据
• 执行周期性备份
• 清理旧的远程备份分支（例如仅保留最近 30 天的分支）
• 通过本地 HTTP 服务暴露备份归档

核心命令

1) 本地全量迁移归档（推荐用于机器迁移）

clawsync profile full-migrate --dry-run
clawsync profile full-migrate

默认输出路径：~/.openclaw/migrations
默认行为：完整收集 workspace/ 目录用于迁移。

2) 基于 Git 的同步

clawsync git init --repo-url  --repo-dir ~/.clawsync-repo
clawsync push --repo-dir ~/.clawsync-repo
clawsync pull --repo-dir ~/.clawsync-repo --branch  --dry-run
clawsync pull --repo-dir ~/.clawsync-repo --branch  --yes
clawsync git prune-branches --repo-dir ~/.clawsync-repo --keep-days 30 --dry-run

3) 从本地归档恢复

clawsync unpack --from /path/to/archive.tar.gz --dry-run
clawsync unpack --from /path/to/archive.tar.gz --yes

4) Token 认证的归档服务器

clawsync serve --token "" --port 7373

可用端点：

• GET /health（无需 token）
• GET /（简易 Web UI，需 token）
• GET /archives（需 token）
• GET /download/（需 token）
• POST /upload（需 token）
• POST /backup（仅限 localhost）
• POST /restore/?dry_run=1|confirm=1（仅限 localhost）

恢复安全模型

对于 unpack / pull / merge 操作，CLI 默认启用以下安全机制：

• 高风险恢复操作需显式确认（除非指定 --yes）
• 恢复前自动在 /tmp 创建快照（除非指定 --no-pre-snapshot）
• 保留本地 gateway.auth.token（除非指定 --overwrite-gateway-token）
• 检查缺失的环境变量，并在必要时打印 source env-export.sh 命令

Agent 执行核对清单

为用户执行恢复/迁移操作时，请遵循以下步骤：

1. 始终先运行带 --dry-run 参数的命令。
2. 在实际执行前，向用户展示高风险路径摘要。
3. 仅在获得用户明确确认后，才使用 --yes 参数执行。
4. 若恢复后缺失环境变量，请提示用户运行 CLI 输出的 source 命令。
5. 若环境变量已加载，请报告网关状态并提醒重新连接。

安全注意事项

• 归档文件可能包含敏感数据（如 openclaw.json、凭据、会话信息等）。
• 请确保远程仓库设为私有。
• serve --token 中的 token 属于敏感信息，请勿公开分享。
• 切勿在未启用 TLS 或反向代理的情况下，将 serve 端点直接暴露至公网。