diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md index bc00772e89b..24f44d0bea5 100644 --- a/docs/cli/migrate.md +++ b/docs/cli/migrate.md @@ -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. -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. ## Commands diff --git a/docs/docs.json b/docs/docs.json index c479f5edde1..3cb57853e7d 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -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"] diff --git a/docs/install/migrating-claude.md b/docs/install/migrating-claude.md index dd96848a2a6..a2eb05ac5c6 100644 --- a/docs/install/migrating-claude.md +++ b/docs/install/migrating-claude.md @@ -16,7 +16,7 @@ Onboarding imports require a fresh OpenClaw setup. If you already have local Ope - 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 ``` - 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 ` to import a specific Claude Code home or project root. - @@ -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. - ```bash @@ -90,7 +93,6 @@ OpenClaw refuses to execute hooks, trust permission allowlists, or decode opaque ``` OpenClaw creates and verifies a backup before applying. - ```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. + + + ```bash + openclaw gateway restart + openclaw status + ``` + Confirm the gateway is healthy and your imported instructions, MCP servers, and skills are loaded. -## 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). 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. +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 + + + + Pass `--from /actual/path` (CLI) or `--import-source /actual/path` (onboarding). + + + 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. + + + 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. + + + 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. + + + ## 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. diff --git a/docs/install/migrating.md b/docs/install/migrating.md index e970de30d20..f74e64181a1 100644 --- a/docs/install/migrating.md +++ b/docs/install/migrating.md @@ -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: + + + Import Claude Code and Claude Desktop state, including `CLAUDE.md`, MCP servers, skills, and project commands. + + + Import Hermes config, providers, MCP servers, memory, skills, and supported `.env` keys. + + + +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. -Run `openclaw status` on the old machine to confirm your state directory path. -Custom profiles use `~/.openclaw-/` 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-/` or a path set via `OPENCLAW_STATE_DIR`. -## Migration steps +### Migration steps @@ -37,13 +50,11 @@ Custom profiles use `~/.openclaw-/` 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. - [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. @@ -55,7 +66,6 @@ Custom profiles use `~/.openclaw-/` or a path set via `OPENCLAW_STATE_D ``` Ensure hidden directories were included and file ownership matches the user that will run the gateway. - @@ -66,53 +76,55 @@ Custom profiles use `~/.openclaw-/` or a path set via `OPENCLAW_STATE_D openclaw gateway restart openclaw status ``` - -## Common pitfalls +### Common pitfalls - 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`. - The config file alone is not enough. Model auth profiles live under - `agents//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//agent/auth-profiles.json`, and channel and provider state lives under `credentials/`. Always migrate the **entire** state directory. - 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. - 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). - 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. -## 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. + + + + Encrypted-state recovery limits, automatic snapshot behavior, and manual recovery commands for the Matrix plugin. + + ## 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.