diff --git a/.openclaw-sync/source.json b/.openclaw-sync/source.json index 0ea34a231..5c3736639 100644 --- a/.openclaw-sync/source.json +++ b/.openclaw-sync/source.json @@ -1,5 +1,5 @@ { "repository": "openclaw/openclaw", - "sha": "cf499101a28e05c25225bdf9d3584d3d660f3e38", - "syncedAt": "2026-04-27T09:35:28.826Z" + "sha": "600df95c8ca8745aa73c8bc406723a0869b61f87", + "syncedAt": "2026-04-27T09:36:42.208Z" } diff --git a/docs/.i18n/glossary.zh-CN.json b/docs/.i18n/glossary.zh-CN.json index a62ac11e1..c8dc75257 100644 --- a/docs/.i18n/glossary.zh-CN.json +++ b/docs/.i18n/glossary.zh-CN.json @@ -451,6 +451,14 @@ "source": "Migrating from Hermes", "target": "从 Hermes 迁移" }, + { + "source": "Migrating from Claude", + "target": "从 Claude 迁移" + }, + { + "source": "Agent workspace", + "target": "Agent 工作区" + }, { "source": "Migration", "target": "迁移" diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md index 6fcca6d8c..92a0f3d3d 100644 --- a/docs/cli/migrate.md +++ b/docs/cli/migrate.md @@ -18,11 +18,14 @@ For a user-facing walkthrough of moving from Hermes, see [Migrating from Hermes] ```bash openclaw migrate list +openclaw migrate claude --dry-run openclaw migrate hermes --dry-run openclaw migrate hermes +openclaw migrate apply claude --yes openclaw migrate apply hermes --yes openclaw migrate apply hermes --include-secrets --yes openclaw onboard --flow import +openclaw onboard --import-from claude --import-source ~/.claude openclaw onboard --import-from hermes --import-source ~/.hermes ``` @@ -76,6 +79,26 @@ openclaw onboard --import-from hermes --import-source ~/.hermes +## Claude provider + +The bundled Claude provider detects Claude Code state at `~/.claude` by default. Use `--from ` to import a specific Claude Code home or project root. + + +For a user-facing walkthrough, see [Migrating from Claude](/install/migrating-claude). + + +### What gets imported + +- Project `CLAUDE.md` and `.claude/CLAUDE.md` into the OpenClaw agent workspace. +- User `~/.claude/CLAUDE.md` appended to workspace `USER.md`. +- MCP server definitions from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json`. +- Claude skill directories that include `SKILL.md`. +- Claude command Markdown files converted into OpenClaw skills with manual invocation only. + +### Archive and manual-review state + +Claude hooks, permissions, environment defaults, local memory, path-scoped rules, subagents, caches, plans, and project history are preserved in the migration report or reported as manual-review items. OpenClaw does not execute hooks, copy broad allowlists, or import OAuth/Desktop credential state automatically. + ## Hermes provider The bundled Hermes provider detects state at `~/.hermes` by default. Use `--from ` when Hermes lives elsewhere. @@ -141,6 +164,7 @@ Onboarding imports require a fresh OpenClaw setup. Reset config, credentials, se ## Related - [Migrating from Hermes](/install/migrating-hermes): user-facing walkthrough. +- [Migrating from Claude](/install/migrating-claude): user-facing walkthrough. - [Migrating](/install/migrating): move OpenClaw to a new machine. - [Doctor](/gateway/doctor): health check after applying a migration. - [Plugins](/tools/plugin): plugin install and registration. diff --git a/docs/docs.json b/docs/docs.json index ba40f197b..f500758c1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1020,6 +1020,7 @@ "pages": [ "install/updating", "install/migrating", + "install/migrating-claude", "install/migrating-hermes", "install/migrating-matrix", "install/uninstall", @@ -2476,6 +2477,7 @@ "pages": [ "ja-JP/install/updating", "ja-JP/install/migrating", + "ja-JP/install/migrating-claude", "ja-JP/install/migrating-hermes", "ja-JP/install/migrating-matrix", "ja-JP/install/uninstall", @@ -3317,6 +3319,7 @@ "pages": [ "es/install/updating", "es/install/migrating", + "es/install/migrating-claude", "es/install/migrating-hermes", "es/install/migrating-matrix", "es/install/uninstall", @@ -4158,6 +4161,7 @@ "pages": [ "pt-BR/install/updating", "pt-BR/install/migrating", + "pt-BR/install/migrating-claude", "pt-BR/install/migrating-hermes", "pt-BR/install/migrating-matrix", "pt-BR/install/uninstall", @@ -4999,6 +5003,7 @@ "pages": [ "ko/install/updating", "ko/install/migrating", + "ko/install/migrating-claude", "ko/install/migrating-hermes", "ko/install/migrating-matrix", "ko/install/uninstall", @@ -5840,6 +5845,7 @@ "pages": [ "de/install/updating", "de/install/migrating", + "de/install/migrating-claude", "de/install/migrating-hermes", "de/install/migrating-matrix", "de/install/uninstall", @@ -6681,6 +6687,7 @@ "pages": [ "fr/install/updating", "fr/install/migrating", + "fr/install/migrating-claude", "fr/install/migrating-hermes", "fr/install/migrating-matrix", "fr/install/uninstall", @@ -7522,6 +7529,7 @@ "pages": [ "ar/install/updating", "ar/install/migrating", + "ar/install/migrating-claude", "ar/install/migrating-hermes", "ar/install/migrating-matrix", "ar/install/uninstall", @@ -8363,6 +8371,7 @@ "pages": [ "it/install/updating", "it/install/migrating", + "it/install/migrating-claude", "it/install/migrating-hermes", "it/install/migrating-matrix", "it/install/uninstall", @@ -9204,6 +9213,7 @@ "pages": [ "tr/install/updating", "tr/install/migrating", + "tr/install/migrating-claude", "tr/install/migrating-hermes", "tr/install/migrating-matrix", "tr/install/uninstall", @@ -10045,6 +10055,7 @@ "pages": [ "uk/install/updating", "uk/install/migrating", + "uk/install/migrating-claude", "uk/install/migrating-hermes", "uk/install/migrating-matrix", "uk/install/uninstall", @@ -10886,6 +10897,7 @@ "pages": [ "id/install/updating", "id/install/migrating", + "id/install/migrating-claude", "id/install/migrating-hermes", "id/install/migrating-matrix", "id/install/uninstall", @@ -11727,6 +11739,7 @@ "pages": [ "pl/install/updating", "pl/install/migrating", + "pl/install/migrating-claude", "pl/install/migrating-hermes", "pl/install/migrating-matrix", "pl/install/uninstall", diff --git a/docs/install/migrating-claude.md b/docs/install/migrating-claude.md new file mode 100644 index 000000000..dd96848a2 --- /dev/null +++ b/docs/install/migrating-claude.md @@ -0,0 +1,124 @@ +--- +summary: "Move Claude Code and Claude Desktop local state into OpenClaw with a previewed import" +read_when: + - You are coming from Claude Code or Claude Desktop and want to keep instructions, MCP servers, and skills + - You need to understand what OpenClaw imports automatically and what stays archive-only +title: "Migrating from Claude" +--- + +OpenClaw imports local Claude state through the bundled Claude migration provider. The provider previews every item before changing state, redacts secrets in plans and reports, and creates a verified backup before apply. + + +Onboarding imports require a fresh OpenClaw setup. If you already have local OpenClaw state, reset config, credentials, sessions, and the workspace first, or use `openclaw migrate` directly with `--overwrite` after reviewing the plan. + + +## Two ways to import + + + + The wizard can offer Claude when it detects local Claude state. + + ```bash + openclaw onboard --flow import + ``` + + Or point at a specific source: + + ```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. + + ```bash + openclaw migrate claude --dry-run + openclaw migrate apply claude --yes + ``` + + Add `--from ` to import a specific Claude Code home or project root. + + + + +## What gets imported + + + + - Project `CLAUDE.md` and `.claude/CLAUDE.md` content is copied or appended into the OpenClaw agent workspace `AGENTS.md`. + - User `~/.claude/CLAUDE.md` content is appended into workspace `USER.md`. + + + MCP server definitions are imported from project `.mcp.json`, Claude Code `~/.claude.json`, and Claude Desktop `claude_desktop_config.json` when present. + + + - Claude skills with a `SKILL.md` file are copied into the OpenClaw workspace skills directory. + - Claude command Markdown files under `.claude/commands/` or `~/.claude/commands/` are converted into OpenClaw skills with `disable-model-invocation: true`. + + + +## What stays archive-only + +The provider copies these into the migration report for manual review, but does **not** load them into live OpenClaw config: + +- Claude hooks +- Claude permissions and broad tool allowlists +- Claude environment defaults +- `CLAUDE.local.md` +- `.claude/rules/` +- Claude subagents under `.claude/agents/` or `~/.claude/agents/` +- 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. + +## Recommended flow + + + + ```bash + openclaw migrate claude --dry-run + ``` + + The plan lists everything that will change, including conflicts, skipped items, and sensitive values redacted from nested MCP `env` or `headers` fields. + + + + ```bash + openclaw migrate apply claude --yes + ``` + + OpenClaw creates and verifies a backup before applying. + + + + ```bash + openclaw doctor + ``` + + [Doctor](/gateway/doctor) checks for config or state issues after the import. + + + + +## 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. + + +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. + + +## Related + +- [`openclaw migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes. +- [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.