mirror of
https://github.com/openclaw/openclaw.git
synced 2026-05-06 12:10:42 +00:00
feat(migrations): add plugin-owned Hermes import
* feat: add migration providers * feat: offer Hermes migration during onboarding * feat(hermes): map imported config surfaces * feat(onboard): require fresh migration imports * docs(cli): clarify Hermes import coverage * chore(migrations): rename Hermes importer package * chore(migrations): rewire Hermes importer id * fix(migrations): redact migration JSON details * fix(hermes): use provider runtime for config imports * test(hermes): cover missing source planning --------- Co-authored-by: Peter Steinberger <steipete@gmail.com>
This commit is contained in:
Vincent Koc
75
docs/cli/migrate.md
Normal file
75
docs/cli/migrate.md
Normal file
@@ -0,0 +1,75 @@
|
||||
---
|
||||
summary: "CLI reference for importing 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
|
||||
title: "Migrate"
|
||||
---
|
||||
|
||||
# `openclaw migrate`
|
||||
|
||||
Import state from another agent system through a plugin-owned migration provider.
|
||||
|
||||
```bash
|
||||
openclaw migrate list
|
||||
openclaw migrate hermes --dry-run
|
||||
openclaw migrate hermes
|
||||
openclaw migrate apply hermes --yes
|
||||
openclaw migrate apply hermes --include-secrets --yes
|
||||
openclaw onboard --flow import
|
||||
openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
```
|
||||
|
||||
## 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 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.
|
||||
|
||||
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 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.
|
||||
|
||||
Secrets are never imported by default. Use `--include-secrets` to import supported credentials.
|
||||
|
||||
## Hermes
|
||||
|
||||
The bundled Hermes provider detects Hermes state at `~/.hermes` by default. Use `--from <path>` when Hermes lives elsewhere.
|
||||
|
||||
The Hermes migration can import:
|
||||
|
||||
- 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`
|
||||
|
||||
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.
|
||||
|
||||
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`.
|
||||
|
||||
After applying a migration, run:
|
||||
|
||||
```bash
|
||||
openclaw doctor
|
||||
```
|
||||
|
||||
## Plugin contract
|
||||
|
||||
Migration sources are plugins. A plugin declares its provider ids in `openclaw.plugin.json`:
|
||||
|
||||
```json
|
||||
{
|
||||
"contracts": {
|
||||
"migrationProviders": ["hermes"]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
@@ -36,10 +36,14 @@ openclaw onboard
|
||||
openclaw onboard --modern
|
||||
openclaw onboard --flow quickstart
|
||||
openclaw onboard --flow manual
|
||||
openclaw onboard --flow import
|
||||
openclaw onboard --import-from hermes --import-source ~/.hermes
|
||||
openclaw onboard --skip-bootstrap
|
||||
openclaw onboard --mode remote --remote-url wss://gateway-host:18789
|
||||
```
|
||||
|
||||
`--flow import` uses plugin-owned migration providers such as Hermes. It only runs against a fresh OpenClaw setup; if existing config, credentials, sessions, or workspace memory/identity files are present, reset or choose a fresh setup before importing.
|
||||
|
||||
`--modern` starts the Crestodian conversational onboarding preview. Without
|
||||
`--modern`, `openclaw onboard` keeps the classic onboarding flow.
|
||||
|
||||
@@ -176,6 +180,7 @@ openclaw onboard --non-interactive \
|
||||
<Accordion title="Flow types">
|
||||
- `quickstart`: minimal prompts, auto-generates a gateway token.
|
||||
- `manual`: full prompts for port, bind, and auth (alias of `advanced`).
|
||||
- `import`: runs a detected migration provider, previews the plan, then applies after confirmation.
|
||||
</Accordion>
|
||||
<Accordion title="Provider prefiltering">
|
||||
When an auth choice implies a preferred provider, onboarding prefilters the default-model and allowlist pickers to that provider. For Volcengine and BytePlus, this also matches the coding-plan variants (`volcengine-plan/*`, `byteplus-plan/*`).
|
||||
@@ -194,6 +199,7 @@ openclaw onboard --non-interactive \
|
||||
- Local onboarding DM scope behavior: [CLI setup reference](/start/wizard-cli-reference#outputs-and-internals).
|
||||
- Fastest first chat: `openclaw dashboard` (Control UI, no channel setup).
|
||||
- Custom provider: connect any OpenAI or Anthropic compatible endpoint, including hosted providers not listed. Use Unknown to auto-detect.
|
||||
- If Hermes state is detected, onboarding offers a migration flow. Use [Migrate](/cli/migrate) for dry-run plans, overwrite mode, reports, and exact mappings.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
|
||||
@@ -21,6 +21,7 @@ Related:
|
||||
openclaw setup
|
||||
openclaw setup --workspace ~/.openclaw/workspace
|
||||
openclaw setup --wizard
|
||||
openclaw setup --wizard --import-from hermes --import-source ~/.hermes
|
||||
openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:18789 --remote-token <token>
|
||||
```
|
||||
|
||||
@@ -30,6 +31,9 @@ openclaw setup --non-interactive --mode remote --remote-url wss://gateway-host:1
|
||||
- `--wizard`: run onboarding
|
||||
- `--non-interactive`: run onboarding without prompts
|
||||
- `--mode <local|remote>`: onboarding mode
|
||||
- `--import-from <provider>`: migration provider to run during onboarding
|
||||
- `--import-source <path>`: source agent home for `--import-from`
|
||||
- `--import-secrets`: import supported secrets during onboarding migration
|
||||
- `--remote-url <url>`: remote Gateway WebSocket URL
|
||||
- `--remote-token <token>`: remote Gateway token
|
||||
|
||||
@@ -42,7 +46,8 @@ openclaw setup --wizard
|
||||
Notes:
|
||||
|
||||
- Plain `openclaw setup` initializes config + workspace without the full onboarding flow.
|
||||
- Onboarding auto-runs when any onboarding flags are present (`--wizard`, `--non-interactive`, `--mode`, `--remote-url`, `--remote-token`).
|
||||
- Onboarding auto-runs when any onboarding flags are present (`--wizard`, `--non-interactive`, `--mode`, `--import-from`, `--import-source`, `--import-secrets`, `--remote-url`, `--remote-token`).
|
||||
- If Hermes state is detected, interactive onboarding can offer migration automatically. Import onboarding requires a fresh setup; use [Migrate](/cli/migrate) for dry-run plans, backups, and overwrite mode outside onboarding.
|
||||
|
||||
## Related
|
||||
|
||||
|
||||
Reference in New Issue
Block a user