diff --git a/docs/cli/migrate.md b/docs/cli/migrate.md index 635dc6313cb..8968aeb0432 100644 --- a/docs/cli/migrate.md +++ b/docs/cli/migrate.md @@ -1,5 +1,5 @@ --- -summary: "CLI reference for importing state from another agent system" +summary: "CLI reference for `openclaw migrate` (import state from another agent system)" read_when: - You want to migrate from Hermes or another agent system into OpenClaw - You are adding a plugin-owned migration provider @@ -10,6 +10,12 @@ title: "Migrate" Import state from another agent system through a plugin-owned migration provider. + +For a user-facing walkthrough of moving from Hermes, see [Migrating from Hermes](/install/migrating-hermes). + + +## Commands + ```bash openclaw migrate list openclaw migrate hermes --dry-run @@ -20,39 +26,88 @@ openclaw onboard --flow import openclaw onboard --import-from hermes --import-source ~/.hermes ``` + + Name of a registered migration provider, for example `hermes`. Run `openclaw migrate list` to see installed providers. + + + Build the plan and exit without changing state. + + + Override the source state directory. Hermes defaults to `~/.hermes`. + + + Import supported credentials. Off by default. + + + Allow apply to replace existing targets when the plan reports conflicts. + + + Skip the confirmation prompt. Required in non-interactive mode. + + + Skip the pre-apply backup. Requires `--force` when local OpenClaw state exists. + + + Required alongside `--no-backup` when apply would otherwise refuse to skip backup. + + + Print the plan or apply result as JSON. With `--json` and no `--yes`, apply prints the plan and does not mutate state. + + ## Safety model -`openclaw migrate` is preview-first. The provider returns an itemized plan before anything changes, including conflicts, skipped items, and sensitive items. JSON plans, apply output, and migration reports redact nested secret-looking keys such as API keys, tokens, authorization headers, cookies, and passwords. +`openclaw migrate` is preview-first. -`openclaw migrate apply ` previews the plan and prompts before changing state unless `--yes` is set. In non-interactive mode, apply requires `--yes`. With `--json` and no `--yes`, apply prints the JSON plan and does not mutate state. + + + The provider returns an itemized plan before anything changes, including conflicts, skipped items, and sensitive items. JSON plans, apply output, and migration reports redact nested secret-looking keys such as API keys, tokens, authorization headers, cookies, and passwords. -Apply creates and verifies an OpenClaw backup before applying the migration. If no local OpenClaw state exists yet, the backup step is skipped and the migration can continue. To skip a backup when state exists, pass both `--no-backup` and `--force`. + `openclaw migrate apply ` previews the plan and prompts before changing state unless `--yes` is set. In non-interactive mode, apply requires `--yes`. + + + Apply creates and verifies an OpenClaw backup before applying the migration. If no local OpenClaw state exists yet, the backup step is skipped and the migration can continue. To skip a backup when state exists, pass both `--no-backup` and `--force`. + + + Apply refuses to continue when the plan has conflicts. Review the plan, then rerun with `--overwrite` if replacing existing targets is intentional. Providers may still write item-level backups for overwritten files in the migration report directory. + + + Secrets are never imported by default. Use `--include-secrets` to import supported credentials. + + -Apply mode refuses to continue when the plan has conflicts. Review the plan, then rerun with `--overwrite` if replacing existing targets is intentional. Providers may still write item-level backups for overwritten files in the migration report directory. +## Hermes provider -Secrets are never imported by default. Use `--include-secrets` to import supported credentials. +The bundled Hermes provider detects state at `~/.hermes` by default. Use `--from ` when Hermes lives elsewhere. -## Hermes +### What gets imported -The bundled Hermes provider detects Hermes state at `~/.hermes` by default. Use `--from ` when Hermes lives elsewhere. +- Default model configuration from `config.yaml`. +- Configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers`. +- MCP server definitions from `mcp_servers` or `mcp.servers`. +- `SOUL.md` and `AGENTS.md` into the OpenClaw agent workspace. +- `memories/MEMORY.md` and `memories/USER.md` appended to workspace memory files. +- Memory config defaults for OpenClaw file memory, plus archive or manual-review items for external memory providers such as Honcho. +- Skills that include a `SKILL.md` file under `skills//`. +- Per-skill config values from `skills.config`. +- Supported API keys from `.env`, only with `--include-secrets`. -The Hermes migration can import: +### Supported `.env` keys -- default model configuration from `config.yaml` -- configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers` -- MCP server definitions from `mcp_servers` or `mcp.servers` -- `SOUL.md` and `AGENTS.md` into the OpenClaw agent workspace -- `memories/MEMORY.md` and `memories/USER.md` by appending them to workspace memory files -- memory config defaults for OpenClaw file memory, plus archive/manual-review items for external memory providers such as Honcho -- skills with a `SKILL.md` file from `skills//` -- per-skill config values from `skills.config` -- supported API keys from `.env`, only with `--include-secrets` +`OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. -Archive-only Hermes state is copied into the migration report for manual review, but it is not loaded into live OpenClaw config or credentials. This preserves opaque or unsafe state such as `plugins/`, `sessions/`, `logs/`, `cron/`, `mcp-tokens/`, `auth.json`, and `state.db` without pretending OpenClaw can execute or trust it automatically. +### Archive-only state -Supported Hermes `.env` keys include `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, and `DEEPSEEK_API_KEY`. +Hermes state that OpenClaw cannot safely interpret is copied into the migration report for manual review, but it is not loaded into live OpenClaw config or credentials. This preserves opaque or unsafe state without pretending OpenClaw can execute or trust it automatically: -After applying a migration, run: +- `plugins/` +- `sessions/` +- `logs/` +- `cron/` +- `mcp-tokens/` +- `auth.json` +- `state.db` + +### After applying ```bash openclaw doctor @@ -70,6 +125,21 @@ Migration sources are plugins. A plugin declares its provider ids in `openclaw.p } ``` -At runtime the plugin calls `api.registerMigrationProvider(...)`. The provider implements `detect`, `plan`, and `apply`; core owns CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. Core passes the reviewed plan into `apply(ctx, plan)`, and providers may rebuild the plan only when that argument is absent for compatibility. Provider plugins can use `openclaw/plugin-sdk/migration` for item construction and summary counts, plus `openclaw/plugin-sdk/migration-runtime` for conflict-aware file copies, archive-only report copies, and migration reports. +At runtime the plugin calls `api.registerMigrationProvider(...)`. The provider implements `detect`, `plan`, and `apply`. Core owns CLI orchestration, backup policy, prompts, JSON output, and conflict preflight. Core passes the reviewed plan into `apply(ctx, plan)`, and providers may rebuild the plan only when that argument is absent for compatibility. -Onboarding can also offer migration when a provider detects a known source. `openclaw onboard --flow import` and `openclaw setup --wizard --import-from hermes` use the same plugin migration provider and still show a preview before applying. Onboarding imports require a fresh OpenClaw setup; reset config, credentials, sessions, and the workspace first if you already have local state. Backup plus overwrite or merge imports are feature-gated for existing setups. +Provider plugins can use `openclaw/plugin-sdk/migration` for item construction and summary counts, plus `openclaw/plugin-sdk/migration-runtime` for conflict-aware file copies, archive-only report copies, and migration reports. + +## Onboarding integration + +Onboarding can offer migration when a provider detects a known source. Both `openclaw onboard --flow import` and `openclaw setup --wizard --import-from hermes` use the same plugin migration provider and still show a preview before applying. + + +Onboarding imports require a fresh OpenClaw setup. Reset config, credentials, sessions, and the workspace first if you already have local state. Backup-plus-overwrite or merge imports are feature-gated for existing setups. + + +## Related + +- [Migrating from Hermes](/install/migrating-hermes): 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 27e58e0c0c0..406e2f96044 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -1012,6 +1012,7 @@ "pages": [ "install/updating", "install/migrating", + "install/migrating-hermes", "install/migrating-matrix", "install/uninstall", "install/development-channels" diff --git a/docs/install/migrating-hermes.md b/docs/install/migrating-hermes.md new file mode 100644 index 00000000000..51d64c2c763 --- /dev/null +++ b/docs/install/migrating-hermes.md @@ -0,0 +1,167 @@ +--- +summary: "Move from Hermes to OpenClaw with a previewed, reversible import" +read_when: + - You are coming from Hermes and want to keep your model config, prompts, memory, and skills + - You want to know what OpenClaw imports automatically and what stays archive-only + - You need a clean, scripted migration path (CI, fresh laptop, automation) +title: "Migrating from Hermes" +--- + +OpenClaw imports Hermes state through a bundled migration provider. The provider previews everything before changing state, redacts secrets in plans and reports, and creates a verified backup before apply. + + +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 fastest path. The wizard detects Hermes at `~/.hermes` and shows a preview before applying. + + ```bash + openclaw onboard --flow import + ``` + + Or point at a specific source: + + ```bash + openclaw onboard --import-from hermes --import-source ~/.hermes + ``` + + + Use `openclaw migrate` for scripted or repeatable runs. See [`openclaw migrate`](/cli/migrate) for the full reference. + + ```bash + openclaw migrate hermes --dry-run # preview only + openclaw migrate apply hermes --yes # apply with confirmation skipped + ``` + + Add `--from ` when Hermes lives outside `~/.hermes`. + + + +## What gets imported + + + + - Default model selection from Hermes `config.yaml`. + - Configured model providers and custom OpenAI-compatible endpoints from `providers` and `custom_providers`. + + + MCP server definitions from `mcp_servers` or `mcp.servers`. + + + - `SOUL.md` and `AGENTS.md` are copied into the OpenClaw agent workspace. + - `memories/MEMORY.md` and `memories/USER.md` are **appended** to the matching OpenClaw memory files instead of overwriting them. + + + Memory config defaults for OpenClaw file memory. External memory providers such as Honcho are recorded as archive or manual-review items so you can move them deliberately. + + + Skills with a `SKILL.md` file under `skills//` are copied, along with per-skill config values from `skills.config`. + + + Set `--include-secrets` to import supported `.env` keys: `OPENAI_API_KEY`, `ANTHROPIC_API_KEY`, `OPENROUTER_API_KEY`, `GOOGLE_API_KEY`, `GEMINI_API_KEY`, `GROQ_API_KEY`, `XAI_API_KEY`, `MISTRAL_API_KEY`, `DEEPSEEK_API_KEY`. Without the flag, secrets are never copied. + + + +## What stays archive-only + +The provider copies these into the migration report directory for manual review, but does **not** load them into live OpenClaw config or credentials: + +- `plugins/` +- `sessions/` +- `logs/` +- `cron/` +- `mcp-tokens/` +- `auth.json` +- `state.db` + +OpenClaw refuses to execute or trust this state automatically because the formats and trust assumptions can drift between systems. Move what you need by hand after reviewing the archive. + +## Recommended flow + + + + ```bash + openclaw migrate hermes --dry-run + ``` + + The plan lists everything that will change, including conflicts, skipped items, and any sensitive items. Plan output redacts nested secret-looking keys. + + + ```bash + openclaw migrate apply hermes --yes + ``` + + OpenClaw creates and verifies a backup before applying. If you need API keys imported, add `--include-secrets`. + + + ```bash + openclaw doctor + ``` + + [Doctor](/gateway/doctor) reapplies any pending config migrations and checks for issues introduced during the import. + + + ```bash + openclaw gateway restart + openclaw status + ``` + + Confirm the gateway is healthy and your imported model, memory, and skills are loaded. + + + +## Conflict handling + +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. + +## Secrets + +Secrets are never imported by default. + +- Run `openclaw migrate apply hermes --yes` first to import non-secret state. +- If you also want supported `.env` keys copied across, rerun with `--include-secrets`. +- For SecretRef-managed credentials, configure the SecretRef source after the import completes. + +## JSON output for automation + +```bash +openclaw migrate hermes --dry-run --json +openclaw migrate apply hermes --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 + + + + Inspect the plan output. Each conflict identifies the source path and the existing target. Decide per item whether to skip, edit the target, or rerun with `--overwrite`. + + + 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 hermes` directly, which supports `--overwrite` and explicit backup control. + + + `--include-secrets` is required, and only the keys listed above are recognized. Other variables in `.env` are ignored. + + + +## Related + +- [`openclaw migrate`](/cli/migrate): full CLI reference, plugin contract, and JSON shapes. +- [Onboarding](/cli/onboard): wizard flow and non-interactive flags. +- [Migrating](/install/migrating): move an OpenClaw install between machines. +- [Doctor](/gateway/doctor): post-migration health check. +- [Agent workspace](/concepts/agent-workspace): where `SOUL.md`, `AGENTS.md`, and memory files live.