GitHub 记忆同步：AI 助手的异地备份方案

核心目标：为 AI 助手箱宝实现记忆的异地版本化备份，防止 VPS 数据丢失，同时为未来迁移到 PVE 小主机做准备。

缘起：为什么需要记忆同步？#

箱宝是我的 OpenClaw AI 助手，拥有完整的”记忆系统”：

短期记忆：memory/YYYY-MM-DD.md — 每日对话日志
长期记忆：MEMORY.md — curated 重要决策和上下文
档案：memory/archive/ — 归档的旧日记

风险点：

VPS 故障可能导致记忆数据丢失
未来迁移到 PVE 小主机时需要完整迁移记忆
需要版本控制追踪记忆变更历史

解决方案：使用 GitHub 私有仓库进行异地备份，通过 Cron 定时自动推送。

一、仓库准备#

1.1 创建私有仓库#

在 GitHub 创建私有仓库 xiangbao-memory：

1
# 仓库信息
2
- URL: https://github.com/Jielumoon/xiangbao-memory
3
- 可见性：Private（记忆含敏感上下文）
4
- 初始化：不添加 README（本地已有完整内容）

1.2 生成 GitHub PAT#

创建 Personal Access Token（Fine-grained 或 Classic 均可）：

1
# 权限需求
2
- repo (Full control of private repositories)
3
# 或者 Fine-grained:
4
- Contents: Read and write

⚠️ 安全警告：PAT 必须保存在安全位置，不要提交到 Git 历史！

二、本地 Git 配置#

2.1 初始化仓库#

在 OpenClaw workspace 目录初始化 Git：

1
cd /root/.openclaw/workspace
2

3
# 配置 Git 用户（箱宝的身份！）
4
git config --global user.name "箱宝"
5
git config --global user.email "xiangbao@openclaw.ai"
6

7
# 初始化仓库
8
git init
9

10
# 添加远程仓库（使用 PAT）
11
git remote add origin https://ghp_YOUR_PAT_HERE@github.com/Jielumoon/xiangbao-memory.git

2.2 配置 .gitignore（关键！）#

⚠️ 血泪教训：首次提交时误追踪了大量敏感文件，包括：

docker/cli-proxy/auths/ — 900+ 个 API 凭证 JSON
docker/ds2api-runtime/config.json — API Key
backup/*.tar.gz — 大型备份文件（触发 GitHub LFS 警告）
.trash/ — 临时删除文件

正确的 .gitignore 配置：

1
# 敏感凭证
2
**/auths/*.json
3
**/secrets/*.json
4
**/*.env
5

6
# 大型文件
7
backup/*.tar.gz
8
backup/*.zip
9
media/outbound/*.png
10
media/outbound/*.jpg
11

12
# 临时文件
13
.trash/
14
tmp/
15
*.log
16

17
# 系统文件
18
.DS_Store
19
Thumbs.db
20

21
# 其他 Git 仓库（避免嵌套）
22
blog/.git
23
skills/*/.git

2.3 首次提交#

1
# 添加所有文件
2
git add .
3

4
# 检查是否有大文件（>50MB 会警告）
5
git status
6

7
# 提交
8
git commit -m "🧠 初始化箱宝记忆备份 2026-02-28"
9

10
# 推送
11
git branch -M main
12
git push -u origin main

三、敏感文件清理（如果已误提交）#

如果像箱宝一样不小心提交了敏感文件，需要彻底清理：

3.1 从 Git 历史移除（不删除本地文件）#

1
# 移除已追踪的敏感目录
2
git rm --cached -r docker/cli-proxy/auths/
3
git rm --cached -r backup/
4

5
# 提交清理
6
git commit -m "🔒 移除敏感文件：cpa 凭证、ds2api 配置、备份文件"
7

8
# 强制推送（⚠️ 会重写历史）
9
git push -f origin main

3.2 如果已推送到 GitHub#

⚠️ 严重警告：即使 git push -f，敏感文件仍然存在于 GitHub 历史中！

正确做法：

立即更换泄露的 API Key / PAT
使用 git filter-branch 或 BFG Repo-Cleaner 彻底清理历史
或者：删除仓库重新创建（箱宝的选择）

四、Cron 自动化同步#

4.1 创建同步脚本#

1
#!/bin/bash
2

3
set -e
4

5
WORKSPACE="/root/.openclaw/workspace"
6
cd "$WORKSPACE"
7

8
# 检查是否有变更
9
if git status --porcelain | grep -q .; then
10
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] 检测到记忆变更，开始同步..."
11

12
    # 添加变更
13
    git add memory/ MEMORY.md
14

15
    # 提交（如果有变更）
16
    if ! git diff --staged --quiet; then
17
        git commit -m "📦 自动同步记忆 $(date '+%Y-%m-%d %H:%M')"
18
        git push origin main
19
        echo "[$(date '+%Y-%m-%d %H:%M:%S')] 同步完成"
20
    else
21
        echo "[$(date '+%Y-%m-%d %H:%M:%S')] 无记忆变更，跳过提交"
22
        git reset
23
    fi
24
else
25
    echo "[$(date '+%Y-%m-%d %H:%M:%S')] 工作区干净，无需同步"
26
fi

4.2 配置 Cron 任务#

1
# 编辑 crontab
2
crontab -e
3

4
# 添加每日同步任务（每天 02:00）
5
0 2 * * * /root/.openclaw/workspace/scripts/memory-sync.sh >> /var/log/memory-sync.log 2>&1

4.3 OpenClaw 内置 Cron（可选）#

OpenClaw 自身也有记忆同步 Cron，配置在 openclaw.json：

1
{
2
  "cron": {
3
    "jobs": [
4
      {
5
        "name": "memory-sync",
6
        "schedule": "0 10,14,18,22 * * *",
7
        "text": "openclaw sessions sync --to diary"
8
      }
9
    ]
10
  }
11
}

区别：

OpenClaw Cron：会话 → 日记文件（内部同步）
Git Cron：日记文件 → GitHub（异地备份）

推荐：两者都用，形成完整链路 ✅

五、安全最佳实践#

5.1 PAT 安全管理#

1
# ✅ 正确做法
2
- 使用 Fine-grained PAT（限制权限范围）
3
- 设置过期时间（如 90 天）
4
- 保存在安全位置（密码管理器、加密文件）
5
- 定期轮换
6

7
# ❌ 错误做法
8
- PAT 明文写在脚本里
9
- 提交 PAT 到 Git 历史
10
- 使用永不过期的 Classic PAT

5.2 .gitignore 检查清单#

在首次推送前，务必检查：

1
# 检查是否有大文件
2
git ls-files -s | awk '{if ($3 > 52428800) print $4}'
3

4
# 检查是否有敏感文件
5
find . -name "*.json" -path "*/auths/*"
6
find . -name "config.json" -path "*/docker/*"
7
find . -name "*.env"

5.3 提交前审查#

1
# 查看将要提交的内容
2
git status
3
git diff --staged
4

5
# 如果有不确定的文件
6
git ls-files --others --exclude-standard

六、恢复与迁移#

6.1 从 GitHub 恢复记忆#

如果 VPS 数据丢失，可以从 GitHub 恢复：

1
# 克隆仓库
2
git clone https://github.com/Jielumoon/xiangbao-memory.git /root/.openclaw/workspace
3

4
# 恢复记忆文件
5
cp -r memory/ /root/.openclaw/workspace/
6
cp MEMORY.md /root/.openclaw/workspace/

6.2 迁移到新环境#

迁移到 PVE 小主机时：

1
# 1. 在新环境克隆仓库
2
git clone https://github.com/Jielumoon/xiangbao-memory.git /root/.openclaw/workspace
3

4
# 2. 配置 Git 远程（如果需要继续同步）
5
git remote set-url origin https://ghp_NEW_PAT@github.com/Jielumoon/xiangbao-memory.git
6

7
# 3. 验证记忆完整性
8
ls -la memory/
9
cat MEMORY.md | head -20

七、成本与限制#

7.1 GitHub 免费额度#

项目	限制	箱宝使用情况
私有仓库	无限	✅
单文件大小	100MB（硬限制）	✅ 记忆文件 <1MB
仓库总大小	1GB（软限制）	✅ 当前 ~50MB
带宽	100GB/月	✅ 同步频率低

7.2 潜在问题#

大文件警告：单个文件 >50MB 会警告，>100MB 拒绝
- 解决：.gitignore 排除 backup/*.tar.gz
Git 历史膨胀：频繁提交大文件会导致仓库膨胀
- 解决：只追踪 memory/ 和 MEMORY.md
敏感信息泄露：误提交 API Key
- 解决：提交前审查 + .gitignore 严格配置

八、效果与监控#

8.1 同步日志#

查看同步日志：

1
tail -f /var/log/memory-sync.log

示例输出：

1
[2026-03-01 02:00:01] 检测到记忆变更，开始同步...
2
[2026-03-01 02:00:03] 同步完成

8.2 GitHub 提交历史#

访问仓库查看提交历史：

1
https://github.com/Jielumoon/xiangbao-memory/commits/main

可以看到：

每次同步的时间
变更的文件
提交消息（含日期）

总结#

核心收获#

异地备份：记忆数据不再依赖单一 VPS
版本控制：可以回溯任意时间点的记忆状态
迁移便利：未来搬迁到 PVE 只需 git clone
自动化：Cron 每日同步，无需手动干预

关键教训#

先配 .gitignore 再 git add — 顺序不能反！
敏感文件绝不提交 — 一旦提交就要重写历史
PAT 定期轮换 — 安全永远是第一位

下一步优化#

添加同步失败告警（Telegram 通知）
压缩记忆文件后再推送（减少带宽）
双向同步（GitHub → 本地，防止本地误删）

参考资源#

发布时间：2026 年 3 月 1 日
系列：AI 助手定制实践

音乐