Export and import OpenClaw agents — workspaces, agent sessions, cron jobs, and credentials — as a single self-contained .zip bundle.
An OpenClaw install spreads an agent's state across several locations:
| Component | Location | Notes |
|---|---|---|
| Workspace | workspace-{name}/ |
memory, brain, scripts, skills |
| Agent runtime + sessions | agents/{name}/ |
chat history (sessions/), agent db |
| Master config | openclaw.json |
agent definitions, identities |
| Crons + runtime state | state/openclaw.sqlite |
all cron jobs, delivery queue |
| Credentials | credentials/ |
API keys, tokens |
| Device auth | identity/, devices/ |
machine-bound — never migrated |
Copying just the workspace folder is not enough. This tool bundles the whole set into one zip and restores it on the target machine.
npm install
npm run build # outputs to dist/
npm link # optional: exposes the `openclaw-migrate` commandRequires Node.js >= 18.
All paths have sensible defaults — the OpenClaw root is auto-detected for your OS (Windows, macOS, Linux) and the export filename defaults to ./openclaw-migrate-<timestamp>.zip:
# List agents in the detected OpenClaw root
openclaw-migrate list
# Export EVERYTHING with zero arguments (interactive prompts on a TTY)
openclaw-migrate export
# Export specific agents to a custom path
openclaw-migrate export --agents alpha,beta --session-limit 50 ~/backup.zip
# Inspect a bundle without extracting
openclaw-migrate inspect <output.zip>
# Dry-run validation of an import
openclaw-migrate import <bundle.zip> --dry-run
# Restore into a target root (defaults to the detected root)
# By default, restores only agents and workspaces; it preserves the target config,
# credentials, runtime state, and any existing files.
openclaw-migrate import <bundle.zip>
# Restore only named agents and their workspaces
openclaw-migrate import <bundle.zip> --agents alpha,beta
# Restore the full bundle into a new OpenClaw installation
openclaw-migrate import <bundle.zip> --full
# Explicitly replace an existing installation's selected files (destructive)
# A restore point is created automatically before anything is changed.
openclaw-migrate import <bundle.zip> --full --overwrite
# Restore the state that existed before an import (use the restore point ID
# shown in the import-complete output).
openclaw-migrate rollback <transaction-id>
# Skip the interactive confirmation on import
openclaw-migrate import <bundle.zip> --yes| Platform | Default root | Override |
|---|---|---|
| macOS / Linux | $HOME/.openclaw |
OPENCLAW_HOME env var |
| Windows | %USERPROFILE%\.openclaw |
OPENCLAW_HOME env var |
| Flag | Description |
|---|---|
--agents a,b |
Comma-separated agent names. Omit to export all discovered agents. |
--session-limit N |
Keep only the last N sessions per agent (-1 = all). Default 50. |
--exclude-openclaw-json |
Omit openclaw.json from the bundle. |
--exclude-credentials |
Omit credentials/ from the bundle. |
--exclude-state-sqlite |
Omit state/openclaw.sqlite (crons + runtime state). |
| Flag | Description |
|---|---|
--dry-run |
Show the full import preview and validate only; write nothing. |
--agents a,b |
Restore only these agents' runtime and workspace files. Defaults to all bundle agents. |
--full |
Include agents, openclaw.json, credentials, and state/openclaw.sqlite. Cannot be combined with --agents. |
--include-config |
Also include openclaw.json. Disabled by default. |
--include-credentials |
Also include credentials/. Disabled by default. |
--include-state |
Also include state/openclaw.sqlite. Disabled by default. |
--overwrite |
Replace existing files in the selected scope. Disabled by default. |
--no-overwrite |
Deprecated compatibility flag; preserving existing files is already the default. |
--force |
Proceed despite a major OpenClaw version mismatch. |
--yes / -y |
Skip the import confirmation prompt. |
Every import that writes files creates a restore point under
<target-root>/.openclaw-migrate/transactions/. It contains copies of files
that will be overwritten and a transaction manifest listing files newly created
by the import. The import-complete output prints its ID.
Run openclaw-migrate rollback <transaction-id> [target-root] to restore the
saved files and remove files created by that import. Rollback asks for
confirmation on a TTY; use --yes in automation. Restore points are retained
after rollback so their history remains inspectable.
When run on a terminal (TTY), export prompts you through a checkbox to pick agents and a numeric input for the session limit. Before every import, the CLI shows the target root, files it will write, and existing files it will preserve. It then asks for confirmation before writing. In scripts or CI (no TTY), prompts are bypassed automatically: export uses every discovered agent, and import proceeds after displaying the preview (use --yes to explicitly skip the confirmation).
- Safe by default — import restores agent runtimes and workspaces only.
openclaw.json, credentials, andstate/openclaw.sqliteare excluded unless you explicitly include them. - Existing installs are protected — selected files are not overwritten unless you pass
--overwrite. The preview shows how many existing files will be preserved. - Imports are reversible — before an import writes, it creates a local restore point for every file it will change. If extraction fails, it automatically rolls that transaction back; use
rollbackto undo a completed import later. - SQLite is never merged —
state/openclaw.sqlitecontains cron jobs and runtime state and is copied wholesale only with--include-stateor--full. Use it for a new installation, or combine it with--overwriteonly when you intend to replace the target state. - Device auth is never migrated — you must re-pair on the target machine. This is intentional: stale device tokens/config don't survive a machine transfer safely.
- Version check — import compares the bundle's OpenClaw version against the target's
openclaw.json. A major mismatch blocks import unless--forceis used, to avoid schema corruption of the target sqlite. - Zip-slip protection — import refuses to write any entry outside the target root.
- Session pruning — groups each session's files by base id (
.jsonl,.trajectory.jsonl,.trajectory-path.json) and keeps the most recent N, so bundles stay small without losing workspace/brain state.
manifest.json # format, version, agents, crons, timestamps
openclaw.json # master config (optional)
credentials/ # secrets (optional)
state/openclaw.sqlite # crons + runtime state (optional)
agents/{name}/ # agent runtime + pruned sessions
workspace-{name}/ # agent workspace
npm test # vitest unit + integration round-trip
npm run typecheck