📝 将 OpenClaw 的 完整工作空间配置 同步到 GitHub 仓库进行备份和版本控制，支持跨服务器迁移。

同步范围

核心记忆文件（必须同步）

文件	路径	说明	敏感度
SOUL.md	/	AI 人格定义	🔒 高
IDENTITY.md	/	AI 身份定义（名字、emoji 等）	🔒 高
USER.md	/	用户信息	🔒 高
MEMORY.md	/	长期记忆	🔒 高
TOOLS.md	/	工具配置（SSH、摄像头等）	🔒 高
HEARTBEAT.md	/	心跳任务配置	🟡 中
*memory/.md	memory/	日常记忆文件	🔒 高

可选配置文件

文件	路径	说明	建议
AGENTS.md	/	工作空间指南	✅ 推荐
BOOTSTRAP.md	/	初始化脚本（如有）	⚪ 可选
skills/	skills/	自定义技能	✅ 推荐
avatars/*	avatars/	头像图片	⚪ 可选

排除文件（不同步）

• .git/ - Git 元数据
• node_modules/ - 依赖包
• .log - 日志文件
• .tmp, .bak - 临时文件
• sessions/ - 会话数据（可能很大）

功能特性

• 📤 完整备份 - 将所有记忆和配置文件推送到 GitHub
• 📥 一键恢复 - 从 GitHub 拉取配置到新服务器
• 📊 查看状态 - 检查本地和远程的差异
• 📋 列出文件 - 显示所有同步的文件
• 🔧 初始化仓库 - 首次设置 GitHub 仓库连接
• 🔄 增量同步 - 只同步变化的文件
• 📦 迁移模式 - 支持完整工作空间迁移到新服务器

配置要求

必需配置

GitHub Token:

• 需要一个 Personal Access Token
• 权限要求：repo（仓库读写权限）
• 生成地址：https://github.com/settings/tokens/new

GitHub 仓库:

• 格式：username/repository-name
• 示例：myusername/openclaw-memory-backup
• 建议设为 Private（私有仓库），因为 memory 可能包含敏感信息

配置方式

方案 A：使用环境变量（推荐用于测试）

export GITHUBTOKEN="ghp_xxxxxxxxxxxxxxxxx"
export GITHUB_REPO="yourusername/your-repo"

方案 B：配置文件（推荐用于生产）

在 ~/.openclaw/openclaw.json 中添加：

{
  "skills": {
    "entries": {
      "github-memory-sync": {
        "enabled": true,
        "apiKey": "ghp_xxxxxxxxxxxxxxxxx",
        "env": {
          "GITHUBTOKEN": "ghp_xxxxxxxxxxxxxxxxx",
          "GITHUB_REPO": "username/memory-backup",
          "GITHUB_BRANCH": "main",
          "WORKSPACE_DIR": "/root/.openclaw/workspace"
        }
      }
    }
  }
}

使用示例

首次初始化

用户："初始化 GitHub memory 仓库"
AI: [获取 Token 和仓库信息后执行初始化]

推送更新（备份）

用户："同步到 GitHub" / "备份配置"
AI: [执行推送操作，同步所有记忆和配置文件]

拉取更新（恢复）

用户："从 GitHub 拉取配置" / "恢复备份"
AI: [执行拉取操作，恢复所有文件]

查看状态

用户："检查同步状态"
AI: [显示本地和远程的差异]

🚀 服务器迁移（完整流程）

在原服务器上：

用户："备份所有配置到 GitHub"
AI: [执行完整推送，包括 SOUL.md, IDENTITY.md, USER.md, MEMORY.md, TOOLS.md, memory/ 等]

在新服务器上：

用户："从 GitHub 恢复配置"
AI: [执行以下步骤]
克隆 GitHub 仓库到临时目录
复制所有记忆和配置文件到 workspace
保留新服务器的通道配置（不覆盖 openclaw.json 中的通道凭证）
验证文件完整性

部分恢复

用户："只恢复 MEMORY.md"
AI: [仅拉取指定文件]
用户："恢复 memory 目录"
AI: [仅拉取 memory/.md 文件]

安全提醒

⚠️ 重要安全注意事项：

• Token 保护

- ❌ 不要把 Token 发送到任何公开渠道 - ❌ 不要在代码中硬编码 Token - ✅ 使用环境变量或配置文件 - ✅ 定期轮换 Token

• 仓库隐私

- 🔒 建议将 GitHub 仓库设为 Private（私有） - 👁 memory 可能包含敏感信息 - 📝 审查 memory 内容再上传

• 权限最小化

- 只给 Token 必要的权限（repo） - 避免使用具有广泛权限的 Token - 设置 Token 过期时间（不要永不过期）

激活技能

当用户提到以下关键词时激活此技能：

• "GitHub memory"
• "同步 memory"
• "备份 memory"
• "GitHub 备份"
• "memory 同步"
• "github-memory-sync"

配置流程

1. 获取配置信息

• 向用户询问 GitHub Token
• 向用户询问 GitHub 仓库地址（或帮其创建）

2. 保存配置

• 将 Token 和仓库信息保存到配置文件或环境变量
• 提醒用户注意安全事项

3. 执行操作

• 根据用户请求执行 init/push/pull/status/migrate 操作
• 显示操作结果

4. 验证同步

• 推送后验证远程仓库文件完整性
• 拉取后验证本地文件完整性

注意事项

• 首次使用必须先执行 init 初始化
• 推送前建议先拉取，避免冲突
• 定期检查 Token 是否过期
• 建议启用 GitHub 的两因素认证
• 通道凭证不同步 - openclaw.json 中的 tokens/secrets 不应上传到 GitHub
• 迁移模式 - 使用 migrate 命令可安全恢复到新服务器

相关文件

• scripts/sync_to_github.py - 同步脚本
• references/migration-guide.md - 完整服务器迁移指南
• references/backup-policy.md - 备份策略和安全建议

快速参考

常用命令

# 初始化（首次使用）
python scripts/sync_to_github.py init
# 备份
python scripts/sync_to_github.py push
# 恢复
python scripts/sync_to_github.py pull
# 查看状态
python scripts/sync_to_github.py status
# 迁移到新服务器
BACKUP_DIR=/tmp/openclaw-restore python scripts/sync_to_github.py migrate

对话触发词

• "备份到 GitHub"
• "同步配置"
• "恢复备份"
• "迁移到新服务器"
• "检查同步状态"
• "github-memory-sync"