vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 05:30:42 +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

4
docs/cli/migrate.md
View File

@@ -8,10 +8,10 @@ title: "Migrate"
# `openclaw migrate`
Import state from another agent system through a plugin-owned migration provider.
Import state from another agent system through a plugin-owned migration provider. Bundled providers cover [Claude](/install/migrating-claude) and [Hermes](/install/migrating-hermes); third-party plugins can register additional providers.
<Tip>
For a user-facing walkthrough of moving from Hermes, see [Migrating from Hermes](/install/migrating-hermes).
For user-facing walkthroughs, see [Migrating from Claude](/install/migrating-claude) and [Migrating from Hermes](/install/migrating-hermes). The [migration hub](/install/migrating) lists all paths.
</Tip>
## Commands

29
docs/docs.json
View File

@@ -975,6 +975,23 @@
"group": "Install overview",
"pages": ["install/index", "install/installer", "install/node"]
},
{
"group": "Maintenance",
"pages": [
"install/updating",
{
"group": "Migrating",
"pages": [
"install/migrating",
"install/migrating-claude",
"install/migrating-hermes",
"install/migrating-matrix"
]
},
"install/uninstall",
"install/development-channels"
]
},
{
"group": "Containers",
"pages": [
@@ -1007,18 +1024,6 @@
"install/render"
]
},
{
"group": "Maintenance",
"pages": [
"install/updating",
"install/migrating",
"install/migrating-claude",
"install/migrating-hermes",
"install/migrating-matrix",
"install/uninstall",
"install/development-channels"
]
},
{
"group": "Advanced setup",
"pages": ["start/setup", "pi-dev"]

59
docs/install/migrating-claude.md
View File

@@ -16,7 +16,7 @@ Onboarding imports require a fresh OpenClaw setup. If you already have local Ope
<Tabs>
<Tab title="Onboarding wizard">
The wizard can offer Claude when it detects local Claude state.
The wizard offers Claude when it detects local Claude state.
```bash
openclaw onboard --flow import
@@ -27,7 +27,6 @@ Onboarding imports require a fresh OpenClaw setup. If you already have local Ope
```bash
openclaw onboard --import-from claude --import-source ~/.claude
```
</Tab>
<Tab title="CLI">
Use `openclaw migrate` for scripted or repeatable runs. See [`openclaw migrate`](/cli/migrate) for the full reference.
@@ -38,7 +37,6 @@ Onboarding imports require a fresh OpenClaw setup. If you already have local Ope
```
Add `--from <path>` to import a specific Claude Code home or project root.
</Tab>
</Tabs>
@@ -71,7 +69,13 @@ The provider copies these into the migration report for manual review, but does
- Claude Code caches, plans, and project history directories
- Claude Desktop extensions and OS-stored credentials
OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque OAuth and Desktop credential state automatically.
OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque OAuth and Desktop credential state automatically. Move what you need by hand after reviewing the archive.
## Source selection
Without `--from`, OpenClaw inspects the default Claude Code home at `~/.claude`, the sampled Claude Code `~/.claude.json` state file, and the Claude Desktop MCP config on macOS.
When `--from` points at a project root, OpenClaw imports only that project's Claude files such as `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, `.claude/skills/`, and `.mcp.json`. It does not read your global Claude home during a project-root import.
## Recommended flow
@@ -82,7 +86,6 @@ OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque
```
The plan lists everything that will change, including conflicts, skipped items, and sensitive values redacted from nested MCP `env` or `headers` fields.
</Step>
<Step title="Apply with backup">
```bash
@@ -90,7 +93,6 @@ OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque
```
OpenClaw creates and verifies a backup before applying.
</Step>
<Step title="Run doctor">
```bash
@@ -98,27 +100,58 @@ OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque
```
[Doctor](/gateway/doctor) checks for config or state issues after the import.
</Step>
<Step title="Restart and verify">
```bash
openclaw gateway restart
openclaw status
```
Confirm the gateway is healthy and your imported instructions, MCP servers, and skills are loaded.
</Step>
</Steps>
## Source selection
Without `--from`, OpenClaw inspects the default Claude Code home at `~/.claude`, the sampled Claude Code `~/.claude.json` state file, and the Claude Desktop MCP config on macOS.
When `--from` points at a project root, OpenClaw imports only that project's Claude files such as `CLAUDE.md`, `.claude/settings.json`, `.claude/commands/`, `.claude/skills/`, and `.mcp.json`. It does not read your global Claude home during a project-root import.
## Conflict handling
Apply refuses to continue when the plan reports conflicts.
Apply refuses to continue when the plan reports conflicts (a file or config value already exists at the target).
<Warning>
Rerun with `--overwrite` only when replacing the existing target is intentional. Providers may still write item-level backups for overwritten files in the migration report directory.
</Warning>
For a fresh OpenClaw install, conflicts are unusual. They typically appear when you re-run the import on a setup that already has user edits.
## JSON output for automation
```bash
openclaw migrate claude --dry-run --json
openclaw migrate apply claude --json --yes
```
With `--json` and no `--yes`, apply prints the plan and does not mutate state. This is the safest mode for CI and shared scripts.
## Troubleshooting
<AccordionGroup>
<Accordion title="Claude state lives outside ~/.claude">
Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding).
</Accordion>
<Accordion title="Onboarding refuses to import on an existing setup">
Onboarding imports require a fresh setup. Either reset state and re-onboard, or use `openclaw migrate apply claude` directly, which supports `--overwrite` and explicit backup control.
</Accordion>
<Accordion title="MCP servers from Claude Desktop did not import">
Claude Desktop reads `claude_desktop_config.json` from a platform-specific path. Point `--from` at that file's directory if OpenClaw did not detect it automatically.
</Accordion>
<Accordion title="Claude commands became skills with model invocation disabled">
By design. Claude commands are user-triggered, so OpenClaw imports them as skills with `disable-model-invocation: true`. Edit each skill's frontmatter if you want the agent to invoke them automatically.
</Accordion>
</AccordionGroup>
## Related
- [`openclaw migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes.
- [Migration guide](/install/migrating): all migration paths.
- [Migrating from Hermes](/install/migrating-hermes): the other cross-system import path.
- [Onboarding](/cli/onboard): wizard flow and non-interactive flags.
- [Doctor](/gateway/doctor): post-migration health check.
- [Agent workspace](/concepts/agent-workspace): where `AGENTS.md`, `USER.md`, and skills live.

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.