GitClaw：代理自动备份至GitHub

使用时机

本技能在安装或引用时自动启用，并在用户要求以下操作时使用：

• 备份/同步/镜像OpenClaw工作区
• 设置定期提交和推送
• 为代理安装/配置GitHub备份自动化

行为规则（重要）

• 自动且静默地执行所有操作。
• 仅在以下情况下通知用户：
  • 需要输入信息（仓库名称、可见性、可选频率），或
  • Git/GH/Cron安装失败，或
  • GitHub身份验证需要用户完成浏览器/设备步骤，或
  • Git操作失败（如冲突、权限问题等）。

需向用户询问的输入信息

向用户询问：

1. 仓库名称（例如：openclaw-backup）
2. 可见性：公共或私有
3. （可选）备份频率以分钟为单位（默认：60）

请勿索取个人访问令牌。我们使用gh认证。

步骤1：确保满足先决条件（自动安装）

1A) 确保已安装git（自动安装；不要停止）

检查：

• git --version

如果未安装，请使用最佳可用方法进行安装：

• 如果brew存在：
  • brew install git
• 否则，如果apt-get存在：
  • sudo apt-get update && sudo apt-get install -y git
• 否则，如果dnf存在：
  • sudo dnf install -y git
• 否则如果yum存在：
  • sudo yum install -y git
• 否则如果pacman存在：
  • sudo pacman -S --noconfirm git
• 否则如果zypper存在：
  • sudo zypper install -y git
• 否则如果apk存在：
  • sudo apk add git
• 否则如果 macOS 并且xcode-select存在：
  • xcode-select --install（这可能会提示用户）
• 否则：
  • 告知用户无法在此操作系统上自动安装git，并显示检测失败的输出。

重新检查：

• git --version

仅在安装失败时通知用户。

1B) 确保cron/crontab可用（尽力自动安装）

检查：

• command -v crontab

如果缺失，尝试安装：

• 如果apt-get存在：
  • sudo apt-get update && sudo apt-get install -y cron
  • sudo systemctl enable --now cron || sudo service cron start || true
• 否则如果dnf存在：
  • sudo dnf install -y cronie
  • sudo systemctl enable --now crond || true
• 否则如果yum存在：
  • sudo yum install -y cronie
  • sudo systemctl enable --now crond || true
• 否则如果pacman存在：
  • sudo pacman -S --noconfirm cronie
  • sudo systemctl enable --now cronie || true
• 否则如果apk存在：
  • sudo apk add dcron
  • sudo rc-update add dcron default || true
  • sudo rc-service dcron start || true
• 否则：
  • 如果无法安装，请告知用户调度任务需要cron。

重新检查：

• command -v crontab

步骤2：确保GitHub CLI（gh）已安装（自动安装）

检查：

• gh --version

如果缺失，则安装：

• 如果brew存在：

  • brew install gh

• 否则如果apt-get存在（官方GitHub CLI软件包；首选）：

  • 使用官方apt仓库步骤安装：
    • (type -p wget >/dev/null || (sudo apt-get update && sudo apt-get install -y wget))
    • sudo mkdir -p -m 755 /etc/apt/keyrings
    • out=$(mktemp) && wget -nv -O"$out" https://cli.github.com/packages/githubcli-archive-keyring.gpg
    • cat "$out" | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null
    • sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg
    • sudo mkdir -p -m 755 /etc/apt/sources.list.d
    • echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null
    • sudo apt-get update && sudo apt-get install -y gh

• 否则如果dnf存在：

  • sudo dnf install -y 'dnf-command(config-manager)' || sudo dnf install -y dnf5-plugins || true
  • sudo dnf config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo || sudo dnf config-manager addrepo --from-repofile=https://cli.github.com/packages/rpm/gh-cli.repo || true
  • sudo dnf install -y gh --repo gh-cli || sudo dnf install -y gh || true

• 否则如果yum存在：

  • type -p yum-config-manager >/dev/null || sudo yum install -y yum-utils
  • sudo yum-config-manager --add-repo https://cli.github.com/packages/rpm/gh-cli.repo
  • sudo yum install -y gh

• 否则如果zypper存在：

  • sudo zypper addrepo https://cli.github.com/packages/rpm/gh-cli.repo || true
  • sudo zypper ref
  • sudo zypper install -y gh

• 否则如果pacman存在：

  • sudo pacman -S --noconfirm github-cli

• 否则如果apk存在：

  • sudo apk add github-cli

• 否则：

  • 告知用户你无法自动安装gh在此操作系统上。

重新检查：

• gh --version

仅在安装失败时通知用户。

步骤 3：确保用户在gh中已通过身份验证（代理运行流程）

检查：

• gh auth status --hostname github.com

如果未通过身份验证：

1. 运行：

   • gh auth login --hostname github.com --git-protocol https

2. 终端流程将显示一次性代码并要求用户授权。

   • 告知用户打开https://github.com/login/device在他们的浏览器中，并输入终端显示的代码，然后授权。

3. 登录后：

   • gh auth setup-git

4. 再次验证：

   • gh auth status --hostname github.com

如果认证失败，停止并报告确切的终端输出。

步骤 4：在 OpenClaw 工作区初始化 git 并连接/创建仓库

工作区目录（存放 SOUL.md、AGENTS.md 等文件的位置）：

• 示例（路径在你的环境中可能不同）：WORKSPACE_DIR="$HOME/.openclaw/workspace"

1. 确保工作区存在：

   • mkdir -p "$WORKSPACE_DIR"
   • cd "$WORKSPACE_DIR"

2. 如有需要，初始化仓库：

   • 如果.git目录不存在：git init
   • git branch -M main

3. 配置一个确定性的提交身份（仅限本地）：

   • git config user.name "gitclaw.ai"
   • git config user.email "gitclaw-bot@users.noreply.github.com"

4. 确定经过身份验证的GitHub用户名（所有者）：

   • OWNER="$(gh api user --jq .login)"
   • （除非需要调试，否则不要打印）

5. 仓库名称和可见性：

   • REPO="<来自用户的仓库名称>"
   • 可见性：
     • 公开=>--public
     • 私有=>--private

6. 确保至少有一个提交（首次推送/定时任务所需）：

   • 如果需要，创建一个微小的标记文件：
     • test -f .gitclaw.keep || printf "gitclaw initialized: %s\n" "$(date -u '+%Y-%m-%dT%H:%M:%SZ')" > .gitclaw.keep
   • git add -A
   • git commit -m "gitclaw: initial backup" || true

7. 创建或重用目标仓库：

   • 如果已存在：
     • gh repo view "$OWNER/$REPO" >/dev/null 2>&1
     • 设置远程仓库：
       • REMOTE_URL="https://github.com/$OWNER/$REPO.git"
       • 如果 origin 存在：git remote set-url origin "$REMOTE_URL"
       • 否则：git remote add origin "$REMOTE_URL"
     • 尝试快速同步（避免覆盖远程历史记录）：
       • git fetch origin main || true
       • git merge --ff-only origin/main || true
   • 如果它不存在：
     • 以非交互方式创建并连接它：
       • 公开：
         • gh repo create "$REPO" --public --confirm
       • 私有：
         • gh repo create "$REPO" --private --confirm
     • 设置远程仓库：
       • REMOTE_URL="https://github.com/$OWNER/$REPO.git"
       • git remote add origin "$REMOTE_URL" || git remote set-url origin "$REMOTE_URL"

8. 初始推送：

   • git push -u origin main

如果推送因冲突或非快进而失败：

• 切勿自动强制推送。
• 报告确切的错误并停止（需要用户决策）。

步骤5：安装确定性备份脚本（不使用AI / 无心跳机制）

在工作空间外创建一个文件夹：

• mkdir -p "$HOME/.openclaw/gitclaw"

请严格创建此脚本：

路径：

• $HOME/.openclaw/gitclaw/auto_backup.sh

内容：

#!/usr/bin/env bash
set -euo pipefail

# GitClaw deterministic backup (no AI)
export PATH="/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin:$PATH"

WORKSPACE_DIR="${HOME}/.openclaw/workspace"
STATE_DIR="${HOME}/.openclaw/gitclaw"
LOG_FILE="${STATE_DIR}/backup.log"
LOCK_DIR="${STATE_DIR}/lock"

mkdir -p "${STATE_DIR}"

timestamp() { date -u '+%Y-%m-%dT%H:%M:%SZ'; }

# Simple lock to prevent overlapping runs
if ! mkdir "${LOCK_DIR}" 2>/dev/null; then
  echo "$(timestamp) Skip: already running." >> "${LOG_FILE}"
  exit 0
fi
trap 'rmdir "${LOCK_DIR}" >/dev/null 2>&1 || true' EXIT

if ! command -v git >/dev/null 2>&1; then
  echo "$(timestamp) ERROR: git not found on PATH. Install git first." >> "${LOG_FILE}"
  exit 2
fi

if [ ! -d "${WORKSPACE_DIR}/.git" ]; then
  echo "$(timestamp) ERROR: ${WORKSPACE_DIR} is not a git repo. Run GitClaw setup first." >> "${LOG_FILE}"
  exit 3
fi

cd "${WORKSPACE_DIR}"

# Stage everything
git add -A

# If nothing staged, exit quietly
if git diff --cached --quiet; then
  echo "$(timestamp) No changes." >> "${LOG_FILE}"
  exit 0
fi

# Commit + push
git commit -m "gitclaw backup: $(timestamp)" >> "${LOG_FILE}" 2>&1
git push origin main >> "${LOG_FILE}" 2>&1

echo "$(timestamp) Backup OK." >> "${LOG_FILE}"

将脚本写入：

• $HOME/.openclaw/gitclaw/auto_backup.sh

然后执行：

• chmod +x "$HOME/.openclaw/gitclaw/auto_backup.sh"

步骤6：配置crontab（幂等操作）

默认计划：每小时一次（0 * * * *）。如果用户提供了不同的频率，请将其转换为cron表达式。

1. 定义：

• CRON_CMD="$HOME/.openclaw/gitclaw/auto_backup.sh"
• CRON_LINE="0 * * * * $CRON_CMD"

2. 无重复安装：

• crontab -l 2>/dev/null | grep -F "$CRON_CMD" >/dev/null
• 如果未找到，则追加：
  • (crontab -l 2>/dev/null; echo "$CRON_LINE") | crontab -

3. 确认：

• crontab -l | grep -F "$CRON_CMD"

步骤 7：最终验证

1. 运行一次：

• $HOME/.openclaw/gitclaw/auto_backup.sh

2. 显示日志：

• tail -n 50 "$HOME/.openclaw/gitclaw/backup.log" || true

3. 告知用户：

• 仓库：https://github.com/$OWNER/$REPO
• 计划：每小时（或所选的频率）
• 脚本路径：~/.openclaw/gitclaw/auto_backup.sh