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
Skills	All from $OPENCLAW/skills/	See notes below
Scripts	All from $OPENCLAW/scripts/	See notes below
Project Code	All from $OPENCLAW/workspace/projects/	Excluding credentials

What It Does NOT Back Up (Personal/Workspace-Specific)

These files are explicitly excluded as they are personal or workspace-specific: - AGENTS.md, SOUL.md, USER.md, TOOLS.md, IDENTITY.md, HEARTBEAT.md — Personal agent configuration - SITES.md — May contain API keys/secrets - MEMORY.md — Contains sensitive conversation data - Any file in credentials/, .env, node_modules/

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)

export GITHUB_TOKEN="ghp_xxxx"
export BACKUP_REPO="username/repo-name"
export OPENCLAW_WORKSPACE="${HOME}/openclaw-workspace"

🔐 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 2. Create new token with: - Repository access: Only $BACKUP_REPO - Permissions: Contents: Write 3. Use this token as GITHUB_TOKEN

Quick Start

git clone https://github.com/your-username/clawsync.git ~/clawsync
cp .env.example .env
# Edit .env with your values
bash sync.sh

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

# With confirmation (default)
bash restore.sh

# Force mode (no prompt)
bash restore.sh --force

Auth

Uses gh CLI if available, falls back to token auth.

Files

• sync.sh - Backup script (ShellCheck compliant)
• restore.sh - Restore script
• .env_example - Template
• .gitignore - Blocks secrets

Development & Release

Running Tests Locally

# Set up test workspace
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

# Run integration test
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

Testing Secret Detection

# Create a test file with a fake secret
echo "My API key is ghp_test1234567890abcdefghijklmnopqrstuvwxyz" > /tmp/test-workspace/AGENTS.md

# Run sync - should abort with error
bash sync.sh

# Expected output: "Error: Potential secret detected..."

Security Audit Test (Proves Non-Staged Detection)

This test verifies the script catches secrets BEFORE they are staged:

# Set up test workspace
export BACKUP_REPO="test/repo"
export OPENCLAW_WORKSPACE="/tmp/test-workspace"
export GITHUB_TOKEN="dummy"

# Create workspace with secret in a non-staged file
mkdir -p /tmp/test-workspace
echo "Real API key: sk-realapikey12345678901234567890" > /tmp/test-workspace/AGENTS.md

# Copy sync.sh to temp backup dir
cd /tmp && rm -rf audit-test && mkdir audit-test && cd audit-test
git init
cp ~/clawsync/sync.sh .

# Run sync - should FAIL (catches non-staged secret)
bash sync.sh

# Expected: "Error: Potential secret detected in backup directory!"
# This proves the pre-git-add scanning works

Publishing to ClawHub

The CI runs on every push and pull request: 1. ShellCheck - Lints bash scripts 2. Integration test - Verifies backup/restore works

To publish a new version:

git add -A
git commit -m "Release v1.0.x"
git tag v1.0.x
git push origin master --tags

CI will automatically: - Run tests - If tests pass and tag starts with v*, publish to ClawHub