Soul Archive

Soul Archive

The Soul Archive lets you save a configured instance's entire state and clone it to new instances. Think of it as preserving an employee's expertise so you can onboard identical new hires instantly.

Overview

When you nurture an OpenClaw instance — configuring its model, training its personality, building up conversation history — that instance develops a unique "soul." The Soul Archive captures this soul so it can be replicated.

What gets saved

Data	Path	Purpose
Personality	workspace/SOUL.md	Who the claw is — behavior, tone, boundaries
Identity	workspace/IDENTITY.md	Self-awareness and role definition
Owner memory	workspace/USER.md	What the claw knows about its owner
Agent config	workspace/AGENTS.md, workspace/TOOLS.md	Collaboration and tool capabilities
API keys	agents/main/agent/auth-profiles.json	LLM provider credentials
Conversation history	agents/main/sessions/	Full dialogue memory
Model config	openclaw.json	Provider, model, and settings (channel config stripped)
Auto-recovery marker	.configured	Ensures gateway auto-starts on resume
Workspace state	workspace/.git/, workspace/.openclaw/	Git history and workspace metadata

What is NOT saved

• Channel assignments — channels are exclusive (one bot token = one instance). You must assign channels separately after cloning.
• Root-level sessions — ephemeral session data outside the agent directory.

Save a soul (Dashboard)

1. On any configured, running instance card, click Save Soul
2. Enter a soul name (supports English, Chinese, spaces, hyphens, underscores — max 64 chars)
3. Optionally add a description
4. Click Save Soul

Load a soul (Dashboard)

1. Click + Create Instances
2. In the Load Soul dropdown, select a saved soul
3. Click Create
4. The new instance starts with the cloned soul — gateway auto-starts, model is pre-configured
5. Assign a channel to the new instance if needed

Manage souls (Dashboard)

Navigate to Fleet → Soul Archive in the sidebar to see all saved souls. Each entry shows:

• Soul name and description
• Source instance
• Creation timestamp
• Archive size

Click Delete to permanently remove a soul.

CLI commands

# Save a soul
clawfleet snapshot save openclaw-1 --name "Desmond The Engineer"
clawfleet snapshot save openclaw-1 --name "工程师之魂" --description "Senior engineer config"

# List all souls
clawfleet snapshot list

# Create an instance from a soul
clawfleet create 1 --from-snapshot "Desmond The Engineer"

# Delete a soul
clawfleet snapshot delete "Desmond The Engineer"

How it works

Souls are stored on disk at ~/.clawfleet/snapshots/<name>/openclaw/. Metadata (name, source, timestamp, size, model asset reference) is persisted in ~/.clawfleet/snapshots.json.

When loading a soul into a new instance, all files are copied into the instance's data directory before the container starts. The .configured marker triggers the entrypoint script to enable gateway autostart, so the instance comes up fully operational.