ClawDNA -- Identity Backup & Sync

CLI tool to version, snapshot, and sync your OpenClaw agent identity files, ensuring backup and preventing data loss or identity drift.

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

Command	What it does
clawdna init	Interactive setup -- detects your workspace and configures the hub (Cloud, Git, or local)
clawdna snapshot [--name <name>]	Creates a timestamped .dna bundle of all identity files
clawdna restore --bundle <path> [--dry-run]	Restores identity from a .dna bundle; use --dry-run to preview
clawdna diff [--local | --hub]	Shows changes between local identity and hub, or since last sync
clawdna log	Displays identity change history with timestamps

Sync Commands

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

Management Commands

Command	What it does
clawdna env add|list|switch	Manages environment profiles (per-machine tokens and overrides)
clawdna memory distill [--dry-run]	Uses an LLM to extract key facts from session memory into core identity
clawdna memory show	Displays the current contents of MEMORY.md
clawdna daemon start|stop|status	Background sync daemon -- watches for changes and auto-pushes
clawdna doctor	Health check -- verifies config, permissions, hub connectivity, and OpenClaw state
clawdna 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:

File	Purpose
SOUL.md	Personality, values, and behavioral rules
AGENTS.md	Workspace conventions and operating rules
IDENTITY.md	How the agent presents itself
MEMORY.md	Accumulated knowledge about the user
TOOLS.md	Installed skills and tool configurations
USER.md	User-specific context and preferences
openclaw.json	Runtime 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:

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/.