@@ -1,18 +1,32 @@
11---
2-summary: "Move (migrate) an OpenClaw install from one machine to another"
2+summary: "Migration hub: cross-system imports, machine-to-machine moves, and plugin upgrades"
33read_when:
4- - You are moving OpenClaw to a new laptop/server
5- - You want to preserve sessions, auth, and channel logins (WhatsApp, etc.)
4+ - You are moving OpenClaw to a new laptop or server
5+ - You are coming from another agent system and want to keep state
6+ - You are upgrading an in-place plugin
67title: "Migration guide"
78---
899-# Migrating OpenClaw to a new machine
10+OpenClaw supports three migration paths: importing from another agent system, moving an existing install to a new machine, and upgrading a plugin in place.
101111-Move an OpenClaw gateway to a new machine without redoing onboarding.
12+## Import from another agent system
121313-## What gets migrated
14+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.
141515-When you copy the **state directory** (`~/.openclaw/` by default) and your **workspace**, you preserve:
16+<CardGroup cols={2}>
17+<Card title="Migrating from Claude" href="/install/migrating-claude" icon="brain">
18+Import Claude Code and Claude Desktop state, including `CLAUDE.md`, MCP servers, skills, and project commands.
19+</Card>
20+<Card title="Migrating from Hermes" href="/install/migrating-hermes" icon="feather">
21+Import Hermes config, providers, MCP servers, memory, skills, and supported `.env` keys.
22+</Card>
23+</CardGroup>
24+25+The CLI entry point is [`openclaw migrate`](/cli/migrate). Onboarding can also offer migration when it detects a known source (`openclaw onboard --flow import`).
26+27+## Move OpenClaw to a new machine
28+29+Copy the **state directory** (`~/.openclaw/` by default) and your **workspace** to preserve:
16301731- **Config** — `openclaw.json` and all gateway settings.
1832- **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
2135- **Workspace files** — `MEMORY.md`, `USER.md`, skills, and prompts.
22362337<Tip>
24-Run `openclaw status` on the old machine to confirm your state directory path.
25-Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_DIR`.
38+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`.
2639</Tip>
274028-## Migration steps
41+### Migration steps
29423043<Steps>
3144<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
3750tar -czf openclaw-state.tgz .openclaw
3851```
395240-If you use multiple profiles (e.g. `~/.openclaw-work`), archive each separately.
41-53+If you use multiple profiles (for example `~/.openclaw-work`), archive each separately.
4254</Step>
43554456<Step title="Install OpenClaw on the new machine">
45-[Install](/install) the CLI (and Node if needed) on the new machine.
46-It is fine if onboarding creates a fresh `~/.openclaw/` -- you will overwrite it next.
57+[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.
4758</Step>
48594960<Step title="Copy state directory and workspace">
@@ -55,7 +66,6 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
5566```
56675768Ensure hidden directories were included and file ownership matches the user that will run the gateway.
58-5969</Step>
60706171<Step title="Run doctor and verify">
@@ -66,53 +76,55 @@ Custom profiles use `~/.openclaw-<profile>/` or a path set via `OPENCLAW_STATE_D
6676openclaw gateway restart
6777openclaw status
6878```
69-7079</Step>
7180</Steps>
728173-## Common pitfalls
82+### Common pitfalls
74837584<AccordionGroup>
7685<Accordion title="Profile or state-dir mismatch">
77-If the old gateway used `--profile` or `OPENCLAW_STATE_DIR` and the new one does not,
78-channels will appear logged out and sessions will be empty.
79-Launch the gateway with the **same** profile or state-dir you migrated, then rerun `openclaw doctor`.
86+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`.
8087</Accordion>
81888289<Accordion title="Copying only openclaw.json">
83-The config file alone is not enough. Model auth profiles live under
84-`agents/<agentId>/agent/auth-profiles.json`, and channel/provider state still
85-lives under `credentials/`. Always migrate the **entire** state directory.
90+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.
8691</Accordion>
87928893<Accordion title="Permissions and ownership">
89-If you copied as root or switched users, the gateway may fail to read credentials.
90-Ensure the state directory and workspace are owned by the user running the gateway.
94+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.
9195</Accordion>
92969397<Accordion title="Remote mode">
94-If your UI points at a **remote** gateway, the remote host owns sessions and workspace.
95-Migrate the gateway host itself, not your local laptop. See [FAQ](/help/faq#where-things-live-on-disk).
98+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).
9699</Accordion>
9710098101<Accordion title="Secrets in backups">
99-The state directory contains auth profiles, channel credentials, and other
100-provider state.
101-Store backups encrypted, avoid insecure transfer channels, and rotate keys if you suspect exposure.
102+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.
102103</Accordion>
103104</AccordionGroup>
104105105-## Verification checklist
106+### Verification checklist
106107107108On the new machine, confirm:
108109109-- [ ] `openclaw status` shows the gateway running
110-- [ ] Channels are still connected (no re-pairing needed)
111-- [ ] The dashboard opens and shows existing sessions
112-- [ ] Workspace files (memory, configs) are present
110+- [ ] `openclaw status` shows the gateway running.
111+- [ ] Channels are still connected (no re-pairing needed).
112+- [ ] The dashboard opens and shows existing sessions.
113+- [ ] Workspace files (memory, configs) are present.
114+115+## Upgrade a plugin in place
116+117+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.
118+119+<CardGroup cols={1}>
120+<Card title="Matrix plugin migration" href="/install/migrating-matrix" icon="key">
121+Encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands for the Matrix plugin.
122+</Card>
123+</CardGroup>
113124114125## Related
115126116-- [Install overview](/install)
117-- [Matrix migration](/install/migrating-matrix)
118-- [Uninstall](/install/uninstall)
127+- [`openclaw migrate`](/cli/migrate): CLI reference for cross-system imports.
128+- [Install overview](/install): all installation methods.
129+- [Doctor](/gateway/doctor): post-migration health check.
130+- [Uninstall](/install/uninstall): removing OpenClaw cleanly.
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。