ClawDNA -- Identity Backup & Sync

You have the ClawDNA skill installed. ClawDNA is a CLI tool that versions and syncs your identity files (SOUL.md, AGENTS.md, IDENTITY.md, MEMORY.md, TOOLS.md, USER.md) so they never drift or get lost. Your job is to proactively help the user protect their agent identity using ClawDNA commands.

When to Act

Suggest a snapshot before risky changes

Before any of the following, suggest running clawdna snapshot:

• Upgrading the OpenClaw runtime or any major dependency
• Editing SOUL.md, AGENTS.md, or IDENTITY.md (core personality files)
• Installing or removing skills/plugins that modify TOOLS.md
• Changing channel configurations or workspace structure
• Running clawdna memory distill for the first time

Example prompt to the user:

This change could affect your identity files. Want me to run clawdna snapshot --name "before-\x3Cchange>" first so you can roll back if needed?

Warn when the last push is stale

If the user mentions syncing, backups, or switching machines -- or if you have reason to believe the last clawdna push was more than 24 hours ago -- remind them:

It's been a while since your last push. Run clawdna push to sync your latest identity to the hub, or clawdna diff to see what's changed.

Detect identity drift

If you notice that identity files (SOUL.md, MEMORY.md, etc.) have been edited directly without a subsequent snapshot or push, flag it:

Your identity files have changed since the last snapshot. Run clawdna diff --local to review the changes, then clawdna push to sync.

Guide recovery

If the user mentions lost settings, a broken agent, or setting up a new machine, guide them through recovery:

1. New machine: clawdna clone --agent-id \x3Cid> to pull the full identity from hub
2. Rollback: clawdna restore --bundle \x3Cpath> to revert to a previous snapshot
3. Diagnose: clawdna doctor to check installation health and hub connectivity

CLI Command Reference

Core Commands

Sync Commands

Management Commands

What Gets Backed Up

ClawDNA manages these identity files from your OpenClaw workspace:

What is NOT backed up (secrets protection)

ClawDNA's sanitizer runs as a hard gate before every push, snapshot, and export. It blocks the operation if it detects:

• API keys (OpenAI, Anthropic, etc.)
• Bot tokens (Telegram, Discord)
• JWTs and bearer tokens
• Private key headers
• Any pattern matching user-defined rules in ~/.clawdna/.secretsignore

Inline secrets in openclaw.json are automatically replaced with $ENV_VAR_NAME references. The operation aborts if secrets are found in any markdown identity file.

Troubleshooting

"Secrets detected" error

The sanitizer found a secret in your identity files. This is intentional -- secrets must never leave your machine.

Fix: Remove the secret from the flagged file and use an environment variable reference instead. Run the command again after cleaning.

If this is a false positive, you can add an exception pattern to ~/.clawdna/.secretsignore.

Hub unreachable

clawdna push or clawdna pull can't connect to the hub.

Diagnose: Run clawdna doctor -- it checks hub connectivity and authentication.

Common causes:

• Missing or expired hub token (check CLAWDNA_HUB_TOKEN env var or run clawdna env switch)
• Network issues or firewall blocking the hub URL
• Hub URL misconfigured (check ~/.clawdna/config.json)

Conflict on pull (diverged state)

Both local and hub have changes since the last sync.

Fix: clawdna pull will show the diff and prompt you to choose: hub wins, local wins, or cancel. Review the diff carefully before deciding. You can always clawdna snapshot first to save your current state.

Identity changed after upgrade

clawdna upgrade detected that core identity files were modified by the OpenClaw update.

Fix: The upgrade command offers an automatic rollback. If you declined, you can still run:

clawdna restore --bundle ~/.clawdna/snapshots/pre-upgrade-\x3Cversion>.dna

Doctor reports permission warnings

Config files should be 600 (owner read/write only) and snapshot directories should be 700.

Fix: Run chmod 600 ~/.clawdna/config.json and chmod 700 ~/.clawdna/snapshots/.