vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 12:40:43 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(hermes): rework CLI migrate page and add user-facing migration guide

Browse Source 
- cli/migrate: convert flat reference into structured Mintlify page (Tip pointer, ParamField for flags, AccordionGroup for safety model, sub-sections for Hermes provider with what's imported, .env keys, archive-only state, and plugin contract)
- install/migrating-hermes: new dedicated user guide modeled after migrating-matrix.md (Tabs for onboarding vs CLI, AccordionGroup for what gets imported, Steps for recommended flow, Warning for --overwrite, Troubleshooting accordions)
- docs.json: add install/migrating-hermes to Maintenance group alongside migrating and migrating-matrix
This commit is contained in:
Vincent Koc
2026-04-27 01:03:48 -07:00
parent 184b024fb6
commit 0055e404cf
3 changed files with 261 additions and 23 deletions
Download Patch File Download Diff File Expand all files Collapse all files

116
docs/cli/migrate.md
View File

@@ -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.
<Tip>
For a user-facing walkthrough of moving from Hermes, see [Migrating from Hermes](/install/migrating-hermes).
</Tip>
## 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
```
<ParamField path="<provider>" type="string">
Name of a registered migration provider, for example `hermes`. Run `openclaw migrate list` to see installed providers.
</ParamField>
<ParamField path="--dry-run" type="boolean">
Build the plan and exit without changing state.
</ParamField>
<ParamField path="--from <path>" type="string">
Override the source state directory. Hermes defaults to `~/.hermes`.
</ParamField>
<ParamField path="--include-secrets" type="boolean">
Import supported credentials. Off by default.
</ParamField>
<ParamField path="--overwrite" type="boolean">
Allow apply to replace existing targets when the plan reports conflicts.
</ParamField>
<ParamField path="--yes" type="boolean">
Skip the confirmation prompt. Required in non-interactive mode.
</ParamField>
<ParamField path="--no-backup" type="boolean">
Skip the pre-apply backup. Requires `--force` when local OpenClaw state exists.
</ParamField>
<ParamField path="--force" type="boolean">
Required alongside `--no-backup` when apply would otherwise refuse to skip backup.
</ParamField>
<ParamField path="--json" type="boolean">
Print the plan or apply result as JSON. With `--json` and no `--yes`, apply prints the plan and does not mutate state.
</ParamField>
## 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 <provider>` 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.
<AccordionGroup>
<Accordion title="Preview before apply">
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 <provider>` previews the plan and prompts before changing state unless `--yes` is set. In non-interactive mode, apply requires `--yes`.
</Accordion>
<Accordion title="Backups">
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`.
</Accordion>
<Accordion title="Conflicts">
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.
</Accordion>
<Accordion title="Secrets">
Secrets are never imported by default. Use `--include-secrets` to import supported credentials.
</Accordion>
</AccordionGroup>
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 <path>` when Hermes lives elsewhere.
## Hermes
### What gets imported
The bundled Hermes provider detects Hermes state at `~/.hermes` by default. Use `--from <path>` 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/<name>/`.
- 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/<name>/`
- 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.
<Note>
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.
</Note>
## 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.