# 安装最新版
openclaw plugins install clawhub:@liwmj/openclaw-gh-sync

# 安装指定版本
openclaw plugins install clawhub:@liwmj/openclaw-gh-sync@0.1.1

openclaw gh-sync setup

# 先预览
openclaw gh-sync restore --dry-run

# 确认无误后恢复
openclaw gh-sync restore --yes

# 拉取旧智能体（如之前用的 coding-assistant）的最新备份
openclaw gh-sync restore --from-instance coding-assistant --dry-run

# 确认后执行
openclaw gh-sync restore --from-instance coding-assistant --yes

openclaw gh-sync restore backup-2026-08-10.tar.gz --yes

{
  "repo": "https://github.com/用户名/仓库名", // 同步目标仓库（必填，仅支持 HTTPS）
  "branch": "instances/coding-assistant", // 当前实例分支，由实例名自动生成
  "instanceName": "coding-assistant", // 当前实例/智能体标识
  "include": ["."], // 要同步的目录，相对于 OpenClaw 数据目录
  "exclude": [
    // 排除同步的 glob 模式
    "gh-sync/**", //   插件自身的缓存和数据不参与同步
    "logs/**",
    "**/*.log",
    "**/*.tmp",
    "**/*.pid",
    "**/*.sock",
    "delivery-queue/**",
    "session-delivery-queue/**",
    "cron/runs/**",
    "**/node_modules/**",
    "**/.git/**",
  ],
  "pushDebounceMs": 2000, // 文件变更后等待多久再提交推送（毫秒）
  "pollIntervalSec": 60, // 远程拉取间隔（秒），最小 5 秒
  "backupIntervalH": 0, // 定时备份间隔（小时），默认 0 = 停用定时备份
  "backupRetain": 6, // 保留最近多少个备份存档（超出自动删除）
  "gitCryptEnabled": false, // 是否启用 git-crypt 加密（默认关闭）
  "gitTimeoutMs": 60000, // git 操作超时（毫秒）；慢网络可调大，restore 跨实例 fetch 自动放宽至 max(gitTimeoutMs, 180000)
  "gitignoreExtras": [], // 追加到 .gitignore 的忽略规则，如 ["*.tmp"]
  "forceInclude": [], // 强制放行同步的 glob，如 ["**/*.jsonl"] 可同步会话文件
}

仓库根目录/
├── instances/
│   └── coding-assistant/            # 以你的实例名称命名
│       ├── config.json              # 本实例同步配置
│       ├── instance.json            # 实例元数据（名称、主机名、创建时间）
│       ├── .git-credentials         # PAT 凭证文件（不会被提交）
│       ├── openclaw/                # 镜像工作区
│       │   └── workspace/           # 你的 OpenClaw 工作区文件
│       └── backups/                 # 备份存档（.tar.gz）
└── instances/
    └── writing-tutor/               # 另一个智能体的实例分支
        └── ...

每个实例拥有独立分支，互不干扰。备份存档统一存放在各自分支的 `backups/` 目录中。

## 架构与模块

```
openclaw-gh-sync/
├── src/
│   ├── index.ts          # 插件入口：注册 gateway 钩子 + gh-sync 命令树
│   ├── realtime.ts       # 同步引擎：监视器/拉取器/备份三循环调度（核心）
│   ├── gitops.ts         # Git 操作封装：init/commit/push/pull/冲突处理/aheadBehind
│   ├── mirror.ts         # 镜像同步：工作区 ↔ 镜像目录双向复制
│   ├── backup.ts         # 备份引擎：openclaw backup 调用 + 存档轮转
│   ├── restore.ts        # 恢复：dry-run 预览 / 指定快照 / 跨实例
│   ├── setup.ts          # 初始化向导（交互式配置）
│   ├── config.ts         # 配置读写（config.json）
│   ├── credentials.ts    # PAT 凭证管理（.git-credentials 0600）
│   ├── gitcrypt.ts       # 可选 git-crypt 加密
│   ├── conflicts.ts      # 冲突副件命名与清理
│   ├── watcher.ts        # chokidar 文件监视器封装
│   ├── poller.ts         # 定时轮询器
│   ├── exclude.ts        # exclude glob 编译
│   ├── paths.ts          # 路径与镜像条目构建
│   ├── fsutil.ts         # 文件系统工具
│   ├── status.ts         # 状态输出
│   ├── cli.ts            # CLI 命令实现
│   └── types.ts          # 类型定义
├── tests/                # vitest 测试（单元 + e2e，92 用例）
├── docs/                 # 产品文档 / 测试覆盖矩阵 / 设计笔记
└── scripts/              # 发布前检查脚本
```

详细设计见 [docs/PRODUCT.md](docs/PRODUCT.md)。

## 测试与验证

- **单元 + 集成测试**：vitest，92 用例全绿（模块层全覆盖 + 命令层 e2e + 边界场景）
- **CI 门禁**：GitHub Actions 每次 push/PR 跑 typecheck + lint + test + build（[查看状态](https://github.com/liwmj/openclaw-gh-sync/actions)）
- **代码规范**：ESLint（TS 推荐配置 + Prettier 协同）+ Prettier 格式化，lint 不过 CI 不过
- **测试覆盖矩阵**：见 [docs/TEST_COVERAGE_MATRIX.md](docs/TEST_COVERAGE_MATRIX.md)（命令层 × 模块层 × 场景层三重对照）
- **冒烟结论**：setup → 首次同步 → 变更推送 → 远端拉取 → 备份 → 恢复 全链路冒烟通过

## 文档

| 文档 | 说明 |
|------|------|
| [docs/PRODUCT.md](docs/PRODUCT.md) | 产品文档：概述 / 快速开始 / 配置参考 / 设计原则 |
| [docs/TEST_COVERAGE_MATRIX.md](docs/TEST_COVERAGE_MATRIX.md) | 测试覆盖矩阵：命令层 × 模块层 × 场景层 |
| [README.md](README.md) | 本文件：安装 / 使用 / 常见问题 |

## 安全说明

- **PAT 凭证**：存储在 `.git-credentials` 文件中，权限 0600（仅所有者可读写），已加入 `.gitignore`，不会被提交到远程仓库
- **仓库 URL**：强制要求 `https://github.com/*` 格式，不允许 SSH 地址或明文密码
- **git-crypt 加密**：默认关闭。如需启用，所有同步设备必须安装 git-crypt 并共享同一把密钥，否则加密文件无法解密。导出并备份密钥：
  ```bash
  cd ~/.openclaw/gh-sync
  git-crypt export-key /安全位置/gh-sync.key

openclaw gh-sync status   # 查看 lastError / lastPushAt / ahead 字段

# 全局配置：把所有 https://github.com/ 请求改走镜像
git config --global url."https://gh-proxy.com/https://github.com/".insteadOf "https://github.com/"

# 还原
git config --global --unset url."https://gh-proxy.com/https://github.com/".insteadOf

# 查看当前 url 重写规则
git config --global --get-regexp "url\."

# 实测连接走哪个主机（gh-proxy.com=生效，github.com=未生效）
GIT_CURL_VERBOSE=1 git ls-remote <repo-url> 2>&1 | grep "Connected to"