ClawSync
Backup and restore your OpenClaw workspace to GitHub.
⚠️ Security First
This skill is designed with defense-in-depth. Please read carefully.
What It Backs Up
| Category | Files | Status |
|---|
| Identity Files | AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md | ✅ Safe |
| Skills |
All from
$OPENCLAW/skills/ | ⚠️ Manual review |
|
Scripts | All from
$OPENCLAW/scripts/ | ⚠️ Manual review |
Why Some Files Are Not Backed Up
The following files are NOT backed up by design:
- - SITES.md — May contain API keys/secrets
- MEMORY.md — May contain sensitive conversation data
- Any file in
credentials/, .env, INLINECODE4
What It Excludes
- - ❌ API keys and tokens (any format)
- ❌ Credentials folder
- ❌ .env files
- ❌ node_modules
- ❌ .git directories
- ❌ Nested git repositories
- ❌ Files containing secrets (detected by regex)
Secret Detection
ClawSync scans for these secret patterns:
- - GitHub tokens (
ghp_*) - OpenAI keys (
sk-*) - Google API keys (
AIza*) - Slack tokens (
xoxb-*, xoxp-*) - AWS access keys (
AKIA*) - JWTs and bearer tokens
- Private keys (
-----BEGIN * PRIVATE KEY-----) - High-entropy strings
If any are detected → backup aborts before push.
Environment Variables (Required)
CODEBLOCK0
🔐 Recommended: Fine-Grained PAT
For least privilege, use a GitHub Fine-Grained PAT:
- 1. Go to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens
- Create new token with:
-
Repository access: Only
$BACKUP_REPO
-
Permissions: Contents: Write
- 3. Use this token as INLINECODE13
Quick Start
CODEBLOCK1
Features
- - Pre-flight Check: Validates required env vars before running
- Strict Whitelist: Only copies explicitly allowed files
- Deny List: Filters out .git, credentials, node_modules
- Secret Scrubbing: Detects 100+ secret patterns, aborts if found
- Safe Restore: Requires --force or confirmation before overwriting
Safe Restore
CODEBLOCK2
Auth
Uses gh CLI if available, falls back to token auth.
Files
- -
sync.sh - Backup script (ShellCheck compliant) - INLINECODE15 - Restore script
- INLINECODE16 - Template
- INLINECODE17 - Blocks secrets
Development & Release
Running Tests Locally
CODEBLOCK3
Testing Secret Detection
CODEBLOCK4
Security Audit Test (Proves Non-Staged Detection)
This test verifies the script catches secrets BEFORE they are staged:
CODEBLOCK5
Publishing to ClawHub
The CI runs on every push and pull request:
- 1. ShellCheck - Lints bash scripts
- Integration test - Verifies backup/restore works
To publish a new version:
CODEBLOCK6
CI will automatically:
- - Run tests
- If tests pass and tag starts with
v*, publish to ClawHub
技能名称: clawback
详细描述:
ClawSync
将您的OpenClaw工作区备份并恢复到GitHub。
⚠️ 安全优先
本技能采用纵深防御设计。请仔细阅读。
备份内容
| 类别 | 文件 | 状态 |
|---|
| 身份文件 | AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md | ✅ 安全 |
| 技能 |
来自 $OPENCLAW/skills/ 的所有文件 | ⚠️ 需手动审查 |
|
脚本 | 来自 $OPENCLAW/scripts/ 的所有文件 | ⚠️ 需手动审查 |
某些文件不备份的原因
以下文件不进行备份（设计如此）：
- - SITES.md — 可能包含API密钥/机密
- MEMORY.md — 可能包含敏感对话数据
- credentials/、.env、node_modules/ 中的任何文件
排除项
- - ❌ API密钥和令牌（任何格式）
- ❌ 凭据文件夹
- ❌ .env文件
- ❌ node_modules
- ❌ .git目录
- ❌ 嵌套的git仓库
- ❌ 包含机密的文件（通过正则表达式检测）
机密检测
ClawSync扫描以下机密模式：
- - GitHub令牌（ghp_）
- OpenAI密钥（sk-）
- Google API密钥（AIza）
- Slack令牌（xoxb-、xoxp-）
- AWS访问密钥（AKIA）
- JWT和Bearer令牌
- 私钥（-----BEGIN * PRIVATE KEY-----）
- 高熵字符串
如果检测到任何内容 → 备份在推送前中止。
环境变量（必需）
bash
export GITHUBTOKEN=ghpxxxx
export BACKUP_REPO=username/repo-name
export OPENCLAW_WORKSPACE=${HOME}/openclaw-workspace
🔐 推荐：细粒度PAT
为遵循最小权限原则，请使用GitHub细粒度PAT：
- 1. 前往GitHub → 设置 → 开发者设置 → 个人访问令牌 → 细粒度令牌
- 创建新令牌，设置：
-
仓库访问权限：仅 $BACKUP_REPO
-
权限：内容：写入
- 3. 将此令牌用作 GITHUB_TOKEN
快速开始
bash
git clone https://github.com/your-username/clawsync.git ~/clawsync
cp .env.example .env
使用您的值编辑.env
bash sync.sh
功能特性
- - 预检检查：运行前验证必需的环境变量
- 严格白名单：仅复制明确允许的文件
- 拒绝列表：过滤掉.git、credentials、node_modules
- 机密擦除：检测100多种机密模式，发现即中止
- 安全恢复：覆盖前需要--force或确认
安全恢复
bash
带确认（默认）
bash restore.sh
强制模式（无提示）
bash restore.sh --force
认证
如果可用，使用gh CLI，否则回退到令牌认证。
文件
- - sync.sh - 备份脚本（符合ShellCheck规范）
- restore.sh - 恢复脚本
- .env_example - 模板
- .gitignore - 阻止机密
开发与发布
本地运行测试
bash
设置测试工作区
mkdir -p /tmp/test-workspace
echo test > /tmp/test-workspace/AGENTS.md
echo test > /tmp/test-workspace/USER.md
mkdir -p /tmp/test-workspace/skills /tmp/test-workspace/scripts
运行集成测试
export BACKUP_REPO=test/repo
export OPENCLAW_WORKSPACE=/tmp/test-workspace
export GITHUB_TOKEN=dummy
cd /tmp && rm -rf test-backup-repo && mkdir test-backup-repo
cd test-backup-repo && git init
cp ~/clawsync/sync.sh .
bash sync.sh
测试机密检测
bash
创建一个包含假机密的测试文件
echo My API key is ghp_test1234567890abcdefghijklmnopqrstuvwxyz > /tmp/test-workspace/AGENTS.md
运行同步 - 应中止并报错
bash sync.sh
预期输出：Error: Potential secret detected...
安全审计测试（证明非暂存检测）
此测试验证脚本在文件被暂存之前捕获机密：
bash
设置测试工作区
export BACKUP_REPO=test/repo
export OPENCLAW_WORKSPACE=/tmp/test-workspace
export GITHUB_TOKEN=dummy
在非暂存文件中创建包含机密的工作区
mkdir -p /tmp/test-workspace
echo Real API key: sk-realapikey12345678901234567890 > /tmp/test-workspace/AGENTS.md
将sync.sh复制到临时备份目录
cd /tmp && rm -rf audit-test && mkdir audit-test && cd audit-test
git init
cp ~/clawsync/sync.sh .
运行同步 - 应失败（捕获非暂存机密）
bash sync.sh
预期：Error: Potential secret detected in backup directory!
这证明了git-add前扫描功能有效
发布到ClawHub
CI在每次推送和拉取请求时运行：
- 1. ShellCheck - 检查bash脚本语法
- 集成测试 - 验证备份/恢复功能
发布新版本：
bash
git add -A
git commit -m Release v1.0.x
git tag v1.0.x
git push origin master --tags
CI将自动：
- - 运行测试
- 如果测试通过且标签以v*开头，则发布到ClawHub
