Security

Clawon is designed to back up your workspace content while keeping credentials and sensitive data safely on your machine.

What Gets Backed Up

Clawon uses an allowlist — only files matching these patterns are included:

Pattern	What it captures
`workspace/*.md`	Workspace markdown (memory, notes, identity)
`workspace/memory/*.md`	Daily memory files
`workspace/memory/*/.md`	Nested memory (projects, workflows, experiments)
`workspace/skills/**`	Custom skills
`workspace/canvas/**`	Canvas data
`skills/**`	Top-level skills
`agents/*/config.json`	Agent configurations
`agents/*/models.json`	Model preferences
`agents//agent/*`	Agent config data
`cron/runs/*.jsonl`	Cron run logs

Run npx clawon discover to see the exact file list for your instance.

What's Excluded

These are always excluded, even if they match an include pattern:

Pattern	Why
`credentials/**`	API keys, tokens, auth files
`openclaw.json`	May contain credentials
`agents/*/agent/auth.json`	Authentication data
`agents/*/agent/auth-profiles.json`	Auth profiles
`agents//sessions/*`	Chat history (large, use `--include-sessions` to include)
`memory/lancedb/**`	Vector database (binary, large)
`memory/*.sqlite`	SQLite databases
`.lock`, `.wal`, `*.shm`	Database lock files
`node_modules/**`	Dependencies

Secret Scanning

Every backup is pre-scanned for leaked secrets using 221 detection rules ported from gitleaks. This catches API keys, tokens, private keys, JWTs, and more — before they leave your machine.

How it works: keyword pre-filtering narrows candidates, then regex matching and Shannon entropy checks confirm real secrets. No new dependencies — it's pure regex matching built into the CLI.

Interactive prompt: when secrets are found during a manual backup, you'll see a prompt with three options:

[s] — Skip flagged files (default)
[a] — Abort the backup entirely
[i] — Ignore findings and back up anyway

Scheduled backups automatically skip flagged files — no prompt needed.

To disable scanning, use --no-secret-scan. To preview findings without backing up, run:

npx clawon discover --scan

SQLite Memory Index

The memory/*.sqlite pattern is excluded by default because OpenClaw rebuilds the search index from your markdown files on startup. However, the rebuild process has had reliability issues — only the active session was reindexed, while historical sessions were skipped.

Use the --include-memory-db flag to include the SQLite index in local backups as insurance:

npx clawon local backup --include-memory-db
npx clawon discover --include-memory-db

WAL and SHM files (*.wal, *.shm) remain excluded — they are ephemeral runtime artifacts.

Chat History (Sessions)

The agents/*/sessions/** pattern is excluded by default because session files can be large (~30 MB typical). Use the --include-sessions flag to include chat history when migrating between machines:

npx clawon local backup --include-sessions
npx clawon discover --include-sessions

For cloud backups, both --include-sessions and --include-memory-db require a Hobby or Pro account. Local backups with either flag are free. See the Migration guide for when to use these flags.

Credentials (--include-secrets)

The credential patterns (credentials/**, openclaw.json, agents/*/agent/auth.json, agents/*/agent/auth-profiles.json) are excluded by default. Use the --include-secrets flag to include them in local backups only — useful when migrating between machines:

npx clawon local backup --include-secrets
npx clawon discover --include-secrets

Manual backups with --include-secrets prompt for confirmation before proceeding. Scheduled backups skip the prompt since the user explicitly configured the flag.

For cloud backups, --include-secrets requires --encrypt to ensure credentials are encrypted before leaving your machine:

npx clawon backup --include-secrets --encrypt

Encryption (--encrypt)

The --encrypt flag encrypts your backup with AES-256-GCM using a passphrase you provide. Encryption is available for both local and cloud backups.

How it works: your passphrase is run through PBKDF2 (100,000 iterations, SHA-512) to derive a 256-bit encryption key. Each backup uses a unique random salt and IV.

# Local encrypted backup
npx clawon local backup --encrypt

# Cloud encrypted backup
npx clawon backup --encrypt

# Cloud backup with secrets (requires --encrypt)
npx clawon backup --include-secrets --encrypt

# Restore detects encryption automatically
npx clawon local restore    # prompts for passphrase if encrypted
npx clawon restore           # prompts for passphrase if encrypted

Local format: encrypted archives use the .tar.gz.enc extension with a binary header (CLWN magic bytes, version, salt, IV, ciphertext, auth tag).

Cloud format: each file is encrypted individually before upload. The encryption salt is stored in the backup manifest, and per-file IVs are recorded at confirm time.

Scheduled backups: set the CLAWON_ENCRYPT_PASSPHRASE environment variable for cron-based encrypted backups. Interactive prompts are not available in scheduled mode.

Warning: no passphrase recovery. If you forget your passphrase, encrypted backups cannot be recovered. Store your passphrase securely.

Credentials are excluded by default. The entire credentials/ directory, openclaw.json, and agent auth files are excluded unless you use --include-secrets. For cloud backups, --include-secrets requires --encrypt. Every backup is also scanned for leaked secrets using 221 detection rules. Verify what gets included by running npx clawon discover, or npx clawon discover --scan to preview secret findings.

Having trouble? Check the Troubleshooting guide.