openclaw - 💡(How to fix) Fix [Feature]: Per-agent backup, restore, and clone [1 participants]

Summary

Add --agent <id> support to openclaw backup and openclaw restore for per-agent backup, restore, and clone operations.

Problem to solve

openclaw backup create and openclaw restore operate on the entire instance. In multi-agent setups, if a single agent gets corrupted (bad workspace edit, broken session state, botched skill install), the only recovery path is restoring the entire instance — rolling back every other agent's state, sessions, and data along with it.

This is the equivalent of restoring an entire database cluster to fix one table.

There's also no built-in way to clone or share an individual agent. Users running multi-agent setups (e.g. per-user Telegram bots, team-specific agents) need to duplicate agent configurations with their workspace files, and currently have to do this manually by copying directories and editing openclaw.json by hand.

Proposed solution

Extend the existing backup/restore CLI with an --agent flag:

# Back up a single agent
openclaw backup create --agent munchie

# Restore a single agent
openclaw restore backup.tar.gz --agent munchie

# Clone: restore under a different name
openclaw restore backup.tar.gz --agent munchie --as munchie-staging

What a per-agent archive would include:

• workspace-<agent>/ — personality files (SOUL.md, IDENTITY.md, AGENTS.md, etc.), data files, memory
• agents/<agent>/agent/ — auth profiles, per-agent config
• agents/<agent>/sessions/ — session transcripts
• Agent config entry extracted from openclaw.json (the agents.list[] entry)

Clone behavior (--as):

• Copies workspace and agent state under the new name
• Rewrites id, name, workspace, and agentDir paths in the config entry
• New agent starts fresh sessions (carried-over sessions are kept as history but OpenClaw keys new sessions by the new agent name)

This fits naturally alongside the existing openclaw backup create flags (--output, --dry-run, --verify, --only-config).

Alternatives considered

• Manual tar + jq — Works (we've tested this approach), but fragile and requires users to know the internal directory layout. Easy to miss the config entry or the agent state directory.
• Community tools like claw-clone — Config-only, doesn't include sessions or agent state. Not a full backup.
• Full instance backup + selective restore — No way to extract one agent from a full archive without restoring everything.

Impact

• Affected: Anyone running multi-agent setups (per-user bots, team agents, dev/staging clones)
• Severity: Medium — workaround exists (manual copying) but is error-prone
• Frequency: Whenever an agent needs recovery, migration, or duplication
• Consequence: Without this, users either restore the entire instance (disrupting all agents) or manually copy directories and hope they got everything

Evidence/examples

• Issue #13616 introduced instance-level backup/restore but has no per-agent granularity
• Issue #17299 (Agents Plane) listed "Agent workspace snapshots? Memory export/import for migration?" as an open question before being closed
• We built and tested a shell-script implementation of this for a 3-agent setup (Telegram calorie tracking bots). The per-agent archive is ~2.4MB vs full-instance backups, and clone + restore under a new name works — the cloned agent responds with full personality, workspace data, and history intact.

Additional information

Happy to contribute a PR if this direction makes sense. The implementation we tested covers:

• Archive creation scoped to one agent (workspace + agent state + config entry)
• Restore with optional rename (--as) that rewrites paths in the config
• Works with the existing agents.list[] config structure in openclaw.json