vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 16:40:49 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(migration): convert migrating.md to a hub, nest per-source guides, reorder nav

Browse Source 
- install/migrating: convert to a hub page with three clear paths (CardGroup for cross-system imports linking Claude+Hermes, machine-to-machine move with Steps and AccordionGroup, plugin upgrade Card linking Matrix)
- install/migrating-claude: align with Hermes page structure (add Restart-and-verify Step, JSON output for automation, Troubleshooting AccordionGroup with 4 entries, cross-link to Hermes guide)
- cli/migrate: tighten intro to mention both bundled providers and link the migration hub
- docs.json: move Maintenance group to immediately after Install overview, nest the four migrating pages (migrating, migrating-claude, migrating-hermes, migrating-matrix) under a 'Migrating' subgroup so they collapse into a dropdown
This commit is contained in:
Vincent Koc
2026-04-27 02:57:11 -07:00
parent a0023f4978
commit a6eb051b3a
4 changed files with 115 additions and 65 deletions
Download Patch File Download Diff File Expand all files Collapse all files

88
docs/install/migrating.md
View File

@@ -1,18 +1,32 @@
---
summary: "Move (migrate) an OpenClaw install from one machine to another"
summary: "Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades"
read_when:
- You are moving OpenClaw to a new laptop/server
- You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
- You are moving OpenClaw to a new laptop or server
- You are coming from another agent system and want to keep state
- You are upgrading an in-place plugin
title: "Migration guide"
---
# Migrating OpenClaw to a new machine
OpenClaw supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.
Move an OpenClaw gateway to a new machine without redoing onboarding.
## Import from another agent system
## What gets migrated
Use the bundled migration providers to bring instructions, MCP servers, skills, model config, and (opt-in) API keys into OpenClaw. Plans are previewed before any change, secrets are redacted in reports, and apply is backed by a verified backup.
When you copy the **state directory** (`~/.openclaw/` by default) and your **workspace**, you preserve:
<CardGroup cols={2}>
<Card title="Migrating from Claude" href="/install/migrating-claude" icon="brain">
Import Claude Code and Claude Desktop state, including `CLAUDE.md`, MCP servers, skills, and project commands.
</Card>
<Card title="Migrating from Hermes" href="/install/migrating-hermes" icon="feather">
Import Hermes config, providers, MCP servers, memory, skills, and supported `.env` keys.
</Card>
</CardGroup>
The CLI entry point is [`openclaw migrate`](/cli/migrate). Onboarding can also offer migration when it detects a known source (`openclaw onboard --flow import`).
## Move OpenClaw to a new machine
Copy the **state directory** (`~/.openclaw/` by default) and your **workspace** to preserve:
- **Config** — `openclaw.json` and all gateway settings.
- **Auth** — per-agent `auth-profiles.json` (API keys plus OAuth), plus any channel or provider state under `credentials/`.
@@ -21,11 +35,10 @@ When you copy the **state directory** (`~/.openclaw/` by default) and your **wor
- **Workspace files** — `MEMORY.md`, `USER.md`, skills, and prompts.
<Tip>
Run `openclaw status` on the old machine to confirm your state directory path.
Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_DIR`.
Run `openclaw status` on the old machine to confirm your state directory path. Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_DIR`.
</Tip>
## Migration steps
### Migration steps
<Steps>
<Step title="Stop the gateway and back up">
@@ -37,13 +50,11 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
tar -czf openclaw-state.tgz .openclaw
```
If you use multiple profiles (e.g. `~/.openclaw-work`), archive each separately.
If you use multiple profiles (for example `~/.openclaw-work`), archive each separately.
</Step>
<Step title="Install OpenClaw on the new machine">
[Install](/install) the CLI (and Node if needed) on the new machine.
It is fine if onboarding creates a fresh `~/.openclaw/` -- you will overwrite it next.
[Install](/install) the CLI (and Node if needed) on the new machine. It is fine if onboarding creates a fresh `~/.openclaw/`. You will overwrite it next.
</Step>
<Step title="Copy state directory and workspace">
@@ -55,7 +66,6 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
```
Ensure hidden directories were included and file ownership matches the user that will run the gateway.
</Step>
<Step title="Run doctor and verify">
@@ -66,53 +76,55 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
openclaw gateway restart
openclaw status
```
</Step>
</Steps>
## Common pitfalls
### Common pitfalls
<AccordionGroup>
<Accordion title="Profile or state-dir mismatch">
If the old gateway used `--profile` or `OPENCLAW_STATE_DIR` and the new one does not,
channels will appear logged out and sessions will be empty.
Launch the gateway with the **same** profile or state-dir you migrated, then rerun `openclaw doctor`.
If the old gateway used `--profile` or `OPENCLAW_STATE_DIR` and the new one does not, channels will appear logged out and sessions will be empty. Launch the gateway with the **same** profile or state-dir you migrated, then rerun `openclaw doctor`.
</Accordion>
<Accordion title="Copying only openclaw.json">
The config file alone is not enough. Model auth profiles live under
`agents/<agentId>/agent/auth-profiles.json`, and channel/provider state still
lives under `credentials/`. Always migrate the **entire** state directory.
The config file alone is not enough. Model auth profiles live under `agents/<agentId>/agent/auth-profiles.json`, and channel and provider state lives under `credentials/`. Always migrate the **entire** state directory.
</Accordion>
<Accordion title="Permissions and ownership">
If you copied as root or switched users, the gateway may fail to read credentials.
Ensure the state directory and workspace are owned by the user running the gateway.
If you copied as root or switched users, the gateway may fail to read credentials. Ensure the state directory and workspace are owned by the user running the gateway.
</Accordion>
<Accordion title="Remote mode">
If your UI points at a **remote** gateway, the remote host owns sessions and workspace.
Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-things-live-on-disk).
If your UI points at a **remote** gateway, the remote host owns sessions and workspace. Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-things-live-on-disk).
</Accordion>
<Accordion title="Secrets in backups">
The state directory contains auth profiles, channel credentials, and other
provider state.
Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.
The state directory contains auth profiles, channel credentials, and other provider state. Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.
</Accordion>
</AccordionGroup>
## Verification checklist
### Verification checklist
On the new machine, confirm:
- [ ] `openclaw status` shows the gateway running
- [ ] Channels are still connected (no re-pairing needed)
- [ ] The dashboard opens and shows existing sessions
- [ ] Workspace files (memory, configs) are present
- [ ] `openclaw status` shows the gateway running.
- [ ] Channels are still connected (no re-pairing needed).
- [ ] The dashboard opens and shows existing sessions.
- [ ] Workspace files (memory, configs) are present.
## Upgrade a plugin in place
In-place plugin upgrades preserve the same plugin id and config keys but may move on-disk state into the current layout. The Matrix plugin is the largest example because of its encrypted-state recovery requirements.
<CardGroup cols={1}>
<Card title="Matrix plugin migration" href="/install/migrating-matrix" icon="key">
Encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands for the Matrix plugin.
</Card>
</CardGroup>
## Related
- [Install overview](/install)
- [Matrix migration](/install/migrating-matrix)
- [Uninstall](/install/uninstall)
- [`openclaw migrate`](/cli/migrate): CLI reference for cross-system imports.
- [Install overview](/install): all installation methods.
- [Doctor](/gateway/doctor): post-migration health check.
- [Uninstall](/install/uninstall): removing OpenClaw cleanly.