Openclaw Migrate

Migrate OpenClaw agents across platforms and servers, preserving identity, memory, config, and skills for deployment, backup, syncing, and upgrades.

Security Scan

The skill broadly matches its stated purpose (agent export/import and optional GitHub sync) but its scripts can exfiltrate sensitive agent identity/memory/config to remote Git repos, have incomplete sanitization, undeclared dependencies, and a few surprising behaviors that warrant caution before use.

Purpose & Capability

Name/description (migrate OpenClaw agents, preserve identity/memory/config/skills) align with the shipped scripts and docs: export-agent.sh creates a packaged snapshot and restore.sh reinstalls it; sync-github.sh pushes a minimized backup to GitHub for versioned deployment. Using GitHub for 'versioned deployments' is explicitly recommended in SKILL.md and implemented in code, so capability matches purpose.

Instruction Scope

Scripts copy sensitive files (IDENTITY.md, USER.md, SOUL.md, MEMORY.md, workspace/memory, openclaw.json) and—if run—will push them to a remote Git repo. SKILL.md's security checklist instructs sanitizing openclaw.json, but export-agent.sh copies openclaw.json raw into the export (no sanitization). sync-github.sh attempts a JSON redaction using jq, but that relies on jq being present and uses a heuristic (string contains 'key'/'token'/'secret') which may miss other secrets or structured credentials. The instructions give the agent broad discretion to collect and transmit identity and memory files—exactly the sensitive material a user may not expect to be pushed to external remotes.

Install Mechanism

This is instruction-only plus shipped scripts (no package install). That minimizes install-time risk. However, scripts assume presence of external tools (git, jq, openclaw CLI, tar, scp) and particular filesystem layout (/home/node/.openclaw). Those prerequisites are not declared in SKILL.md or package.json. If these tools are missing the scripts may fail in unsafe ways (partial exports, incomplete redaction).

Credentials

The skill declares no required environment variables, but the code implicitly reads sensitive data from the host filesystem (openclaw.json, workspace files) and may place them on remote Git repositories. README/docker docs reference OPENCLAW_GATEWAY_TOKEN and OPENCLAW_MODEL_API_KEY for runtime containers; these are not declared as required but are relevant to the exported config. The sync script will attempt to push to a repo (including --force fallback) which is disproportionate if a user expects a local-only backup. Overall the data the scripts access (identity, memory, gateway tokens) is high-sensitivity and the skill does not explicitly require or document the credentials/tools it depends on.

Persistence & Privilege

The skill is not force-included (always:false) and does not modify other skills or global agent configuration. When run, scripts create temporary exports in /tmp and may write restore scripts into those export directories. The most significant persistent effect is that sync-github.sh can push (and in some code paths force-push) data to a remote repo, which could permanently expose or overwrite remote content—this is a behavioral privilege to consider but not an automatic platform-level elevation.

What to consider before installing

Do not install and run this skill without reviewing and testing its scripts first. Specific recommendations: - Inspect scripts before use. export-agent.sh copies openclaw.json unchanged; sync-github.sh copies identity and memory files and will push them to whatever repo URL you provide. That can leak agent identity, long-term memory, API tokens, or PII. - If you plan to use the GitHub sync: run it against a disposable/private repo first. Check the created agent-backup contents locally before any git push. Be aware the script will try to initialize and push, and may attempt a force push if the first push fails. - The provided 'redaction' in sync-github.sh relies on jq and a simple string heuristic; do not assume it removes all secrets. Verify openclaw.json and any workspace files are sanitized manually before pushing. - The scripts assume paths like /home/node/.openclaw and tools (git, jq, openclaw CLI). Adjust paths or run inside a container that matches assumptions to avoid accidental reading of the wrong user's files. - Prefer using export-agent.sh to create a local export, review its manifest and restore.sh, and only transfer data after manual inspection and redaction. Rotate any credentials after migration and keep backups. - If you need safer behavior, modify the scripts to: (1) prompt before including MEMORY/IDENTITY files, (2) require an explicit --confirm-github flag before any network push, (3) add stricter redaction rules and fail-safe checks for jq/git availability. Confidence in this assessment is high because the repository and full scripts were available for review.

Agent Migration

Migrate OpenClaw agents across servers and platforms while preserving identity, memory, and configuration.

When to Use

✅ USE this skill when:

• Moving agent from local machine to remote server
• Cloning agent configuration to multiple environments
• Backing up complete agent state for disaster recovery
• Syncing workspace changes between dev/prod
• Upgrading OpenClaw with full rollback capability

❌ DON'T use when:

• Simple file copy operations → use cp/rsync directly
• Database migrations → use database-specific tools
• Non-OpenClaw application deployment

Core Concepts

Agent State Components

Agent State = Identity + Memory + Config + Skills + Extensions
├── workspace/           # Core identity files
│   ├── IDENTITY.md      # Who the agent is
│   ├── USER.md          # Who they serve
│   ├── SOUL.md          # Personality
│   ├── MEMORY.md        # Long-term memory
│   ├── AGENTS.md        # Operational rules
│   ├── TOOLS.md         # Environment notes
│   └── memory/          # Daily logs
├── .openclaw/
│   ├── openclaw.json    # Gateway config
│   ├── agents/          # Session data
│   └── extensions/      # Custom plugins
└── skills/              # Custom skills (if any)

Migration Workflows

1. Export (Source Machine)

# Full agent export
./scripts/export-agent.sh [export-name]

# Creates:
# /tmp/agent-export-[name]/
#   ├── manifest.json      # Export metadata
#   ├── workspace.tar.gz   # Core files
#   ├── config.tar.gz      # OpenClaw config
#   └── restore.sh         # Self-contained restore

2. Transfer

# Via SSH
scp -r /tmp/agent-export-[name] user@new-server:/tmp/

# Via GitHub (recommended for versioned deployments)
# Push to repo, clone on target

3. Import (Target Machine)

# Run self-contained restore
cd /tmp/agent-export-[name] && ./restore.sh

# Or manual:
./scripts/import-agent.sh /tmp/agent-export-[name]

Scripts

Export Agent

scripts/export-agent.sh [name] [--full]

Options:

• name - Export identifier (default: timestamp)
• --full - Include session history and logs

Import Agent

scripts/import-agent.sh <export-path> [--merge|--replace]

Options:

• --merge - Merge with existing agent (default)
• --replace - Wipe existing, clean install

Sync to GitHub

scripts/sync-github.sh <repo-url> [--push|--pull]

Syncs agent state to GitHub for versioned deployment.

Platform-Specific Notes

Linux → Linux

Direct transfer, no conversion needed.

macOS → Linux

• Check for macOS-specific paths in scripts
• Update file watchers if used

Windows WSL → Native Linux

• Line endings auto-handled
• Verify executable permissions

Docker Deployment

See references/docker-deploy.md for containerized deployment.

Security Checklist

• Sanitize openclaw.json (remove sensitive tokens before export)
• Verify target machine permissions
• Rotate any exposed credentials post-migration
• Test agent functionality before production cutover

Rollback

Exports are immutable snapshots. To rollback:

# Re-import previous export
./scripts/import-agent.sh /path/to/previous-export --replace