Troubleshooting
Common issues and how to fix them. Start with diagnostics, then find your specific problem below.
Diagnostics First
Before diving into specific issues, run these two commands to understand your current state:
# Check connection, workspace, and file count
npx clawon status
# Preview exactly which files would be backed up
npx clawon discoverCommon Issues
"No OpenClaw installation found"
Clawon looks for an OpenClaw installation at ~/.openclaw/. This error means that directory doesn't exist or is empty.
- Verify OpenClaw is installed:
ls ~/.openclaw/ - If you installed OpenClaw to a custom path, Clawon currently only supports the default location
- On a fresh machine, install and run OpenClaw at least once before using Clawon
"Not logged in" / API Key Issues
Cloud commands require authentication. Local commands do not.
- Run
npx clawon loginto authenticate - Check your API key at clawon.io/dashboard
- Use an environment variable to avoid shell history:
export CLAWON_API_KEY=your-key - Run
npx clawon statusto verify you're logged in
"Snapshot limit reached"
Each workspace has a snapshot limit based on your plan (Starter: 2, Hobby: 10, Pro: 20).
- Delete old snapshots:
npx clawon delete --oldest - List snapshots to choose:
npx clawon list, thennpx clawon delete <id> - Upgrade your plan for more snapshots
"Backup is empty"
This means no files matched the allowlist patterns.
- Run
npx clawon discoverto see what files would be included - Verify your OpenClaw workspace has content:
ls ~/.openclaw/workspace/ - If you just installed OpenClaw, create some memory or skills first
"Restore overwrites my files"
Restore extracts files into ~/.openclaw/, overwriting existing files with the same names.
- Use
npx clawon restore --dry-runto preview what will be restored - Create a local backup first:
npx clawon local backup --tag "before restore" - Restore only overwrites files present in the snapshot — other files are left untouched
"Schedule not running"
Scheduled backups use cron (macOS/Linux only).
- Check status:
npx clawon schedule status - Verify cron is active:
crontab -lshould show a Clawon entry - On macOS, ensure cron has full disk access in System Preferences > Privacy
- Re-enable:
npx clawon local schedule offthennpx clawon local schedule on - See the Scheduled Backups guide for details
"Memory index not rebuilding after restore"
OpenClaw's memory reindex process has known reliability issues. To avoid this:
- Include the SQLite index in backups:
--include-memory-db - If you already restored without it, try restarting OpenClaw to trigger a reindex
- See Security for details on what's included and excluded
FAQ
What is a workspace?
A workspace is like a GitHub repo — it holds cloud snapshots for one OpenClaw installation. Create multiple workspaces for different machines. A default workspace is created on signup.
What does Clawon back up?
Workspace markdown (memory, notes), skills, canvas data, and agent configs. Credentials, databases, sessions, and node_modules are excluded by default.
Does Clawon store my secrets?
No. The entire credentials/ directory and openclaw.json are excluded by default. API keys, tokens, and auth files never leave your machine.
Can I back up chat history?
Yes. Use --include-sessions to include chat history in backups. Sessions are excluded by default because they can grow large (~30 MB). Local session backups are free; cloud requires Hobby or Pro.
What if Clawon goes down?
Your data is never locked in. Local backups work without internet, no account required. The cloud is for convenience — you always have a local escape hatch.
How do I opt out of telemetry?
Set DO_NOT_TRACK=1 or CLAWON_NO_TELEMETRY=1 as an environment variable. No file contents, filenames, or personal data are ever sent.
Still stuck? Run npx clawon status and npx clawon discover and include the output when asking for help. File issues at github.com/chelouche9/clawon-cli.