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-<change>" 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 <id> to pull the full identity from hub
2. Rollback: clawdna restore --bundle <path> to revert to a previous snapshot
3. Diagnose: clawdna doctor to check installation health and hub connectivity

---

CLI Command Reference#

Core Commands#

CommandWhat it doesclawdna initInteractive setup -- detects your workspace and configures the hub (Cloud, Git, or local)clawdna snapshot [--name <name>]Creates a timestamped .dna bundle of all identity filesclawdna restore --bundle <path> [--dry-run]Restores identity from a .dna bundle; use --dry-run to previewclawdna diff [--local | --hub]Shows changes between local identity and hub, or since last syncclawdna logDisplays identity change history with timestamps

Sync Commands#

CommandWhat it doesclawdna push [--message <msg>]Pushes current identity to the configured hubclawdna pull [--dry-run]Pulls latest identity from hub; shows diff before applyingclawdna clone --agent-id <id>Bootstraps a new machine by downloading identity from hubclawdna fleet [--env-ids <ids...>]Pushes identity to multiple environments simultaneously

Management Commands#

CommandWhat it doesclawdna env add|list|switchManages environment profiles (per-machine tokens and overrides)clawdna memory distill [--dry-run]Uses an LLM to extract key facts from session memory into core identityclawdna memory showDisplays the current contents of MEMORY.mdclawdna daemon start|stop|statusBackground sync daemon -- watches for changes and auto-pushesclawdna doctorHealth check -- verifies config, permissions, hub connectivity, and OpenClaw stateclawdna upgrade [--channel <ch>]Safe OpenClaw upgrade -- snapshots before, verifies identity after, offers rollback

---

What Gets Backed Up#

ClawDNA manages these identity files from your OpenClaw workspace:

FilePurposeSOUL.mdPersonality, values, and behavioral rulesAGENTS.mdWorkspace conventions and operating rulesIDENTITY.mdHow the agent presents itselfMEMORY.mdAccumulated knowledge about the userTOOLS.mdInstalled skills and tool configurationsUSER.mdUser-specific context and preferencesopenclaw.jsonRuntime configuration (secrets are stripped automatically)

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:

text

clawdna restore --bundle ~/.clawdna/snapshots/pre-upgrade-<version>.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/.