fix: use consistent fallback for pickle_key derivation

Address review: _pickle_key now uses _acct_id (which has the 'hermes'
fallback) instead of raw self._user_id, so both values stay consistent
when user_id is empty.

docs/migration/openclaw.md

@@ -11,14 +11,12 @@ When you run `hermes setup` for the first time and Hermes detects `~/.openclaw`,
 ### 2. CLI Command (quick, scriptable)
 
 ```bash
-hermes claw migrate                      # Preview then migrate (always shows preview first)
-hermes claw migrate --dry-run            # Preview only, no changes
+hermes claw migrate                      # Full migration with confirmation prompt
+hermes claw migrate --dry-run            # Preview what would happen
 hermes claw migrate --preset user-data   # Migrate without API keys/secrets
 hermes claw migrate --yes                # Skip confirmation prompt
 ```
 
-The migration always shows a full preview of what will be imported before making any changes. You review the preview and confirm before anything is written.
-
 **All options:**
 
 | Flag | Description |
@@ -41,7 +39,7 @@ Ask the agent to run the migration for you:
 ```
 
 The agent will use the `openclaw-migration` skill to:
-1. Run a preview first to show what would change
+1. Run a dry-run first to preview changes
 2. Ask about conflict resolution (SOUL.md, skills, etc.)
 3. Let you choose between `user-data` and `full` presets
 4. Execute the migration with your choices
@@ -60,31 +58,16 @@ The agent will use the `openclaw-migration` skill to:
 | Messaging settings | `~/.openclaw/config.yaml` (TELEGRAM_ALLOWED_USERS, MESSAGING_CWD) | `~/.hermes/.env` |
 | TTS assets | `~/.openclaw/workspace/tts/` | `~/.hermes/tts/` |
 
-Workspace files are also checked at `workspace.default/` and `workspace-main/` as fallback paths (OpenClaw renamed `workspace/` to `workspace-main/` in recent versions).
-
 ### `full` preset (adds to `user-data`)
 | Item | Source | Destination |
 |------|--------|-------------|
-| Telegram bot token | `openclaw.json` channels config | `~/.hermes/.env` |
-| OpenRouter API key | `.env`, `openclaw.json`, or `openclaw.json["env"]` | `~/.hermes/.env` |
-| OpenAI API key | `.env`, `openclaw.json`, or `openclaw.json["env"]` | `~/.hermes/.env` |
-| Anthropic API key | `.env`, `openclaw.json`, or `openclaw.json["env"]` | `~/.hermes/.env` |
-| ElevenLabs API key | `.env`, `openclaw.json`, or `openclaw.json["env"]` | `~/.hermes/.env` |
+| Telegram bot token | `~/.openclaw/config.yaml` | `~/.hermes/.env` |
+| OpenRouter API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
+| OpenAI API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
+| Anthropic API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
+| ElevenLabs API key | `~/.openclaw/.env` or config | `~/.hermes/.env` |
 
-API keys are searched across four sources: inline config values, `~/.openclaw/.env`, the `openclaw.json` `"env"` sub-object, and per-agent auth profiles.
-
-Only allowlisted secrets are ever imported. Other credentials are skipped and reported.
-
-## OpenClaw Schema Compatibility
-
-The migration handles both old and current OpenClaw config layouts:
-
-- **Channel tokens**: Reads from flat paths (`channels.telegram.botToken`) and the newer `accounts.default` layout (`channels.telegram.accounts.default.botToken`)
-- **TTS provider**: OpenClaw renamed "edge" to "microsoft" — both are recognized and mapped to Hermes' "edge"
-- **Provider API types**: Both short (`openai`, `anthropic`) and hyphenated (`openai-completions`, `anthropic-messages`, `google-generative-ai`) values are mapped correctly
-- **thinkingDefault**: All enum values are handled including newer ones (`minimal`, `xhigh`, `adaptive`)
-- **Matrix**: Uses `accessToken` field (not `botToken`)
-- **SecretRef formats**: Plain strings, env templates (`${VAR}`), and `source: "env"` SecretRefs are resolved. `source: "file"` and `source: "exec"` SecretRefs produce a warning — add those keys manually after migration.
+Only these 6 allowlisted secrets are ever imported. Other credentials are skipped and reported.
 
 ## Conflict Handling
 
@@ -101,24 +84,18 @@ For skills, you can also use `--skill-conflict rename` to import conflicting ski
 
 ## Migration Report
 
-Every migration produces a report showing:
+Every migration (including dry runs) produces a report showing:
 - **Migrated items** — what was successfully imported
 - **Conflicts** — items skipped because they already exist
 - **Skipped items** — items not found in the source
 - **Errors** — items that failed to import
 
-For executed migrations, the full report is saved to `~/.hermes/migration/openclaw/<timestamp>/`.
-
-## Post-Migration Notes
-
-- **Skills require a new session** — imported skills take effect after restarting your agent or starting a new chat.
-- **WhatsApp requires re-pairing** — WhatsApp uses QR-code pairing, not token-based auth. Run `hermes whatsapp` to pair.
-- **Archive cleanup** — after migration, you'll be offered to rename `~/.openclaw/` to `.openclaw.pre-migration/` to prevent state confusion. You can also run `hermes claw cleanup` later.
+For execute runs, the full report is saved to `~/.hermes/migration/openclaw/<timestamp>/`.
 
 ## Troubleshooting
 
 ### "OpenClaw directory not found"
-The migration looks for `~/.openclaw` by default, then tries `~/.clawdbot` and `~/.moldbot`. If your OpenClaw is installed elsewhere, use `--source`:
+The migration looks for `~/.openclaw` by default. If your OpenClaw is installed elsewhere, use `--source`:
 ```bash
 hermes claw migrate --source /path/to/.openclaw
 ```
@@ -131,12 +108,3 @@ hermes skills install openclaw-migration
 
 ### Memory overflow
 If your OpenClaw MEMORY.md or USER.md exceeds Hermes' character limits, excess entries are exported to an overflow file in the migration report directory. You can manually review and add the most important ones.
-
-### API keys not found
-Keys might be stored in different places depending on your OpenClaw setup:
-- `~/.openclaw/.env` file
-- Inline in `openclaw.json` under `models.providers.*.apiKey`
-- In `openclaw.json` under the `"env"` or `"env.vars"` sub-objects
-- In `~/.openclaw/agents/main/agent/auth-profiles.json`
-
-The migration checks all four. If keys use `source: "file"` or `source: "exec"` SecretRefs, they can't be resolved automatically — add them via `hermes config set`.

gateway/config.py

@@ -190,7 +190,7 @@ class StreamingConfig:
     """Configuration for real-time token streaming to messaging platforms."""
     enabled: bool = False
     transport: str = "edit"       # "edit" (progressive editMessageText) or "off"
-    edit_interval: float = 1.0    # Seconds between message edits (Telegram rate-limits at ~1/s)
+    edit_interval: float = 0.3    # Seconds between message edits
     buffer_threshold: int = 40    # Chars before forcing an edit
     cursor: str = " ▉"           # Cursor shown during streaming
 
@@ -210,7 +210,7 @@ class StreamingConfig:
         return cls(
             enabled=data.get("enabled", False),
             transport=data.get("transport", "edit"),
-            edit_interval=float(data.get("edit_interval", 1.0)),
+            edit_interval=float(data.get("edit_interval", 0.3)),
             buffer_threshold=int(data.get("buffer_threshold", 40)),
             cursor=data.get("cursor", " ▉"),
         )

gateway/stream_consumer.py

@@ -36,7 +36,7 @@ _NEW_SEGMENT = object()
 @dataclass
 class StreamConsumerConfig:
     """Runtime config for a single stream consumer instance."""
-    edit_interval: float = 1.0
+    edit_interval: float = 0.3
     buffer_threshold: int = 40
     cursor: str = " ▉"
 
@@ -56,10 +56,6 @@ class GatewayStreamConsumer:
         await task         # wait for final edit
     """
 
-    # After this many consecutive flood-control failures, permanently disable
-    # progressive edits for the remainder of the stream.
-    _MAX_FLOOD_STRIKES = 3
-
     def __init__(
         self,
         adapter: Any,
@@ -80,8 +76,6 @@ class GatewayStreamConsumer:
         self._last_sent_text = ""   # Track last-sent text to skip redundant edits
         self._fallback_final_send = False
         self._fallback_prefix = ""
-        self._flood_strikes = 0         # Consecutive flood-control edit failures
-        self._current_edit_interval = self.cfg.edit_interval  # Adaptive backoff
 
     @property
     def already_sent(self) -> bool:
@@ -135,7 +129,7 @@ class GatewayStreamConsumer:
                 should_edit = (
                     got_done
                     or got_segment_break
-                    or (elapsed >= self._current_edit_interval
+                    or (elapsed >= self.cfg.edit_interval
                         and self._accumulated)
                     or len(self._accumulated) >= self.cfg.buffer_threshold
                 )
@@ -179,13 +173,12 @@ class GatewayStreamConsumer:
                         if split_at < _safe_limit // 2:
                             split_at = _safe_limit
                         chunk = self._accumulated[:split_at]
-                        ok = await self._send_or_edit(chunk)
-                        if self._fallback_final_send or not ok:
-                            # Edit failed (or backed off due to flood control)
-                            # while attempting to split an oversized message.
-                            # Keep the full accumulated text intact so the
-                            # fallback final-send path can deliver the remaining
-                            # continuation without dropping content.
+                        await self._send_or_edit(chunk)
+                        if self._fallback_final_send:
+                            # Edit failed while attempting to split an oversized
+                            # message. Keep the full accumulated text intact so
+                            # the fallback final-send path can deliver the
+                            # remaining continuation without dropping content.
                             break
                         self._accumulated = self._accumulated[split_at:].lstrip("\n")
                         self._message_id = None
@@ -329,10 +322,7 @@ class GatewayStreamConsumer:
         return chunks
 
     async def _send_fallback_final(self, text: str) -> None:
-        """Send the final continuation after streaming edits stop working.
-
-        Retries each chunk once on flood-control failures with a short delay.
-        """
+        """Send the final continuation after streaming edits stop working."""
         final_text = self._clean_for_display(text)
         continuation = self._continuation_text(final_text)
         self._fallback_final_send = False
@@ -349,25 +339,12 @@ class GatewayStreamConsumer:
         last_successful_chunk = ""
         sent_any_chunk = False
         for chunk in chunks:
-            # Try sending with one retry on flood-control errors.
-            result = None
-            for attempt in range(2):
-                result = await self.adapter.send(
-                    chat_id=self.chat_id,
-                    content=chunk,
-                    metadata=self.metadata,
-                )
-                if result.success:
-                    break
-                if attempt == 0 and self._is_flood_error(result):
-                    logger.debug(
-                        "Flood control on fallback send, retrying in 3s"
-                    )
-                    await asyncio.sleep(3.0)
-                else:
-                    break  # non-flood error or second attempt failed
-
-            if not result or not result.success:
+            result = await self.adapter.send(
+                chat_id=self.chat_id,
+                content=chunk,
+                metadata=self.metadata,
+            )
+            if not result.success:
                 if sent_any_chunk:
                     # Some continuation text already reached the user. Suppress
                     # the base gateway final-send path so we don't resend the
@@ -393,52 +370,20 @@ class GatewayStreamConsumer:
         self._last_sent_text = chunks[-1]
         self._fallback_prefix = ""
 
-    def _is_flood_error(self, result) -> bool:
-        """Check if a SendResult failure is due to flood control / rate limiting."""
-        err = getattr(result, "error", "") or ""
-        err_lower = err.lower()
-        return "flood" in err_lower or "retry after" in err_lower or "rate" in err_lower
-
-    async def _try_strip_cursor(self) -> None:
-        """Best-effort edit to remove the cursor from the last visible message.
-
-        Called when entering fallback mode so the user doesn't see a stuck
-        cursor (▉) in the partial message.
-        """
-        if not self._message_id or self._message_id == "__no_edit__":
-            return
-        prefix = self._visible_prefix()
-        if not prefix or not prefix.strip():
-            return
-        try:
-            await self.adapter.edit_message(
-                chat_id=self.chat_id,
-                message_id=self._message_id,
-                content=prefix,
-            )
-            self._last_sent_text = prefix
-        except Exception:
-            pass  # best-effort — don't let this block the fallback path
-
-    async def _send_or_edit(self, text: str) -> bool:
-        """Send or edit the streaming message.
-
-        Returns True if the text was successfully delivered (sent or edited),
-        False otherwise.  Callers like the overflow split loop use this to
-        decide whether to advance past the delivered chunk.
-        """
+    async def _send_or_edit(self, text: str) -> None:
+        """Send or edit the streaming message."""
         # Strip MEDIA: directives so they don't appear as visible text.
         # Media files are delivered as native attachments after the stream
         # finishes (via _deliver_media_from_response in gateway/run.py).
         text = self._clean_for_display(text)
         if not text.strip():
-            return True  # nothing to send is "success"
+            return
         try:
             if self._message_id is not None:
                 if self._edit_supported:
                     # Skip if text is identical to what we last sent
                     if text == self._last_sent_text:
-                        return True
+                        return
                     # Edit existing message
                     result = await self.adapter.edit_message(
                         chat_id=self.chat_id,
@@ -448,52 +393,19 @@ class GatewayStreamConsumer:
                     if result.success:
                         self._already_sent = True
                         self._last_sent_text = text
-                        # Successful edit — reset flood strike counter
-                        self._flood_strikes = 0
-                        return True
                     else:
-                        # Edit failed.  If this looks like flood control / rate
-                        # limiting, use adaptive backoff: double the edit interval
-                        # and retry on the next cycle.  Only permanently disable
-                        # edits after _MAX_FLOOD_STRIKES consecutive failures.
-                        if self._is_flood_error(result):
-                            self._flood_strikes += 1
-                            self._current_edit_interval = min(
-                                self._current_edit_interval * 2, 10.0,
-                            )
-                            logger.debug(
-                                "Flood control on edit (strike %d/%d), "
-                                "backoff interval → %.1fs",
-                                self._flood_strikes,
-                                self._MAX_FLOOD_STRIKES,
-                                self._current_edit_interval,
-                            )
-                            if self._flood_strikes < self._MAX_FLOOD_STRIKES:
-                                # Don't disable edits yet — just slow down.
-                                # Update _last_edit_time so the next edit
-                                # respects the new interval.
-                                self._last_edit_time = time.monotonic()
-                                return False
-
-                        # Non-flood error OR flood strikes exhausted: enter
-                        # fallback mode — send only the missing tail once the
+                        # If an edit fails mid-stream (especially Telegram flood control),
+                        # stop progressive edits and send only the missing tail once the
                         # final response is available.
-                        logger.debug(
-                            "Edit failed (strikes=%d), entering fallback mode",
-                            self._flood_strikes,
-                        )
+                        logger.debug("Edit failed, disabling streaming for this adapter")
                         self._fallback_prefix = self._visible_prefix()
                         self._fallback_final_send = True
                         self._edit_supported = False
                         self._already_sent = True
-                        # Best-effort: strip the cursor from the last visible
-                        # message so the user doesn't see a stuck ▉.
-                        await self._try_strip_cursor()
-                        return False
                 else:
                     # Editing not supported — skip intermediate updates.
                     # The final response will be sent by the fallback path.
-                    return False
+                    pass
             else:
                 # First message — send new
                 result = await self.adapter.send(
@@ -505,7 +417,6 @@ class GatewayStreamConsumer:
                     self._message_id = result.message_id
                     self._already_sent = True
                     self._last_sent_text = text
-                    return True
                 elif result.success:
                     # Platform accepted the message but returned no message_id
                     # (e.g. Signal).  Can't edit without an ID — switch to
@@ -517,11 +428,8 @@ class GatewayStreamConsumer:
                     self._fallback_final_send = True
                     # Sentinel prevents re-entering this branch on every delta
                     self._message_id = "__no_edit__"
-                    return True  # platform accepted, just can't edit
                 else:
                     # Initial send failed — disable streaming for this session
                     self._edit_supported = False
-                    return False
         except Exception as e:
             logger.error("Stream send/edit error: %s", e)
-            return False

hermes_cli/claw.py

@@ -1,9 +1,8 @@
 """hermes claw — OpenClaw migration commands.
 
 Usage:
-    hermes claw migrate              # Preview then migrate (always shows preview first)
-    hermes claw migrate --dry-run    # Preview only, no changes
-    hermes claw migrate --yes        # Skip confirmation prompt
+    hermes claw migrate              # Interactive migration from ~/.openclaw
+    hermes claw migrate --dry-run    # Preview what would be migrated
     hermes claw migrate --preset full --overwrite  # Full migration, overwrite conflicts
     hermes claw cleanup              # Archive leftover OpenClaw directories
     hermes claw cleanup --dry-run    # Preview what would be archived
@@ -238,12 +237,12 @@ def _cmd_migrate(args):
 
     # Show what we're doing
     hermes_home = get_hermes_home()
-    auto_yes = getattr(args, "yes", False)
     print()
     print_header("Migration Settings")
     print_info(f"Source:      {source_dir}")
     print_info(f"Target:      {hermes_home}")
     print_info(f"Preset:      {preset}")
+    print_info(f"Mode:        {'dry run (preview only)' if dry_run else 'execute'}")
     print_info(f"Overwrite:   {'yes' if overwrite else 'no (skip conflicts)'}")
     print_info(f"Secrets:     {'yes (allowlisted only)' if migrate_secrets else 'no'}")
     if skill_conflict != "skip":
@@ -252,81 +251,31 @@ def _cmd_migrate(args):
         print_info(f"Workspace:   {workspace_target}")
     print()
 
+    # For execute mode (non-dry-run), confirm unless --yes was passed
+    if not dry_run and not getattr(args, "yes", False):
+        if not prompt_yes_no("Proceed with migration?", default=True):
+            print_info("Migration cancelled.")
+            return
+
     # Ensure config.yaml exists before migration tries to read it
     config_path = get_config_path()
     if not config_path.exists():
         save_config(load_config())
 
-    # Load the migration module
+    # Load and run the migration
     try:
         mod = _load_migration_module(script_path)
         if mod is None:
             print_error("Could not load migration script.")
             return
-    except Exception as e:
-        print()
-        print_error(f"Could not load migration script: {e}")
-        logger.debug("OpenClaw migration error", exc_info=True)
-        return
 
-    selected = mod.resolve_selected_options(None, None, preset=preset)
-    ws_target = Path(workspace_target).resolve() if workspace_target else None
+        selected = mod.resolve_selected_options(None, None, preset=preset)
+        ws_target = Path(workspace_target).resolve() if workspace_target else None
 
-    # ── Phase 1: Always preview first ──────────────────────────
-    try:
-        preview = mod.Migrator(
-            source_root=source_dir.resolve(),
-            target_root=hermes_home.resolve(),
-            execute=False,
-            workspace_target=ws_target,
-            overwrite=overwrite,
-            migrate_secrets=migrate_secrets,
-            output_dir=None,
-            selected_options=selected,
-            preset_name=preset,
-            skill_conflict_mode=skill_conflict,
-        )
-        preview_report = preview.migrate()
-    except Exception as e:
-        print()
-        print_error(f"Migration preview failed: {e}")
-        logger.debug("OpenClaw migration preview error", exc_info=True)
-        return
-
-    preview_summary = preview_report.get("summary", {})
-    preview_count = preview_summary.get("migrated", 0)
-
-    if preview_count == 0:
-        print()
-        print_info("Nothing to migrate from OpenClaw.")
-        _print_migration_report(preview_report, dry_run=True)
-        return
-
-    print()
-    print_header(f"Migration Preview — {preview_count} item(s) would be imported")
-    print_info("No changes have been made yet. Review the list below:")
-    _print_migration_report(preview_report, dry_run=True)
-
-    # If --dry-run, stop here
-    if dry_run:
-        return
-
-    # ── Phase 2: Confirm and execute ───────────────────────────
-    print()
-    if not auto_yes:
-        if not sys.stdin.isatty():
-            print_info("Non-interactive session — preview only.")
-            print_info("To execute, re-run with: hermes claw migrate --yes")
-            return
-        if not prompt_yes_no("Proceed with migration?", default=True):
-            print_info("Migration cancelled.")
-            return
-
-    try:
         migrator = mod.Migrator(
             source_root=source_dir.resolve(),
             target_root=hermes_home.resolve(),
-            execute=True,
+            execute=not dry_run,
             workspace_target=ws_target,
             overwrite=overwrite,
             migrate_secrets=migrate_secrets,
@@ -343,11 +292,11 @@ def _cmd_migrate(args):
         return
 
     # Print results
-    _print_migration_report(report, dry_run=False)
+    _print_migration_report(report, dry_run)
 
-    # After successful migration, offer to archive the source directory
-    if report.get("summary", {}).get("migrated", 0) > 0:
-        _offer_source_archival(source_dir, auto_yes)
+    # After successful non-dry-run migration, offer to archive the source directory
+    if not dry_run and report.get("summary", {}).get("migrated", 0) > 0:
+        _offer_source_archival(source_dir, getattr(args, "yes", False))
 
 
 def _offer_source_archival(source_dir: Path, auto_yes: bool = False):
@@ -381,11 +330,6 @@ def _offer_source_archival(source_dir: Path, auto_yes: bool = False):
     print_info("You can always rename it back if needed.")
     print()
 
-    if not auto_yes and not sys.stdin.isatty():
-        print_info("Non-interactive session — skipping archival.")
-        print_info("Run later with: hermes claw cleanup")
-        return
-
     if auto_yes or prompt_yes_no(f"Archive {source_dir} now?", default=True):
         try:
             archive_path = _archive_directory(source_dir)
@@ -489,9 +433,6 @@ def _cmd_cleanup(args):
         if dry_run:
             archive_path = _archive_directory(source_dir, dry_run=True)
             print_info(f"Would archive: {source_dir} → {archive_path}")
-        elif not auto_yes and not sys.stdin.isatty():
-            print_info(f"Non-interactive session — would archive: {source_dir}")
-            print_info("To execute, re-run with: hermes claw cleanup --yes")
         else:
             if auto_yes or prompt_yes_no(f"Archive {source_dir}?", default=True):
                 try:

hermes_cli/main.py

@@ -5411,8 +5411,7 @@ For more help on a command:
     claw_migrate = claw_subparsers.add_parser(
         "migrate",
         help="Migrate from OpenClaw to Hermes",
-        description="Import settings, memories, skills, and API keys from an OpenClaw installation. "
-                    "Always shows a preview before making changes."
+        description="Import settings, memories, skills, and API keys from an OpenClaw installation"
     )
     claw_migrate.add_argument(
         "--source",
@@ -5421,7 +5420,7 @@ For more help on a command:
     claw_migrate.add_argument(
         "--dry-run",
         action="store_true",
-        help="Preview only — stop after showing what would be migrated"
+        help="Preview what would be migrated without making changes"
     )
     claw_migrate.add_argument(
         "--preset",

hermes_cli/models.py

@@ -56,18 +56,6 @@ OPENROUTER_MODELS: list[tuple[str, str]] = [
 
 _openrouter_catalog_cache: list[tuple[str, str]] | None = None
 
-
-def _codex_curated_models() -> list[str]:
-    """Derive the openai-codex curated list from codex_models.py.
-
-    Single source of truth: DEFAULT_CODEX_MODELS + forward-compat synthesis.
-    This keeps the gateway /model picker in sync with the CLI `hermes model`
-    flow without maintaining a separate static list.
-    """
-    from hermes_cli.codex_models import DEFAULT_CODEX_MODELS, _add_forward_compat_models
-    return _add_forward_compat_models(list(DEFAULT_CODEX_MODELS))
-
-
 _PROVIDER_MODELS: dict[str, list[str]] = {
     "nous": [
         "anthropic/claude-opus-4.6",
@@ -98,7 +86,14 @@ _PROVIDER_MODELS: dict[str, list[str]] = {
         "openai/gpt-5.4-pro",
         "openai/gpt-5.4-nano",
     ],
-    "openai-codex": _codex_curated_models(),
+    "openai-codex": [
+        "gpt-5.4",
+        "gpt-5.4-mini",
+        "gpt-5.3-codex",
+        "gpt-5.2-codex",
+        "gpt-5.1-codex-mini",
+        "gpt-5.1-codex-max",
+    ],
     "copilot-acp": [
         "copilot-acp",
     ],

optional-skills/migration/openclaw-migration/scripts/openclaw_to_hermes.py

@@ -617,19 +617,6 @@ class Migrator:
             candidate = self.source_root / rel
             if candidate.exists():
                 return candidate
-            # OpenClaw renamed workspace/ to workspace-main/ (and workspace-{agentId}
-            # for multi-agent).  Try the new path as a fallback.
-            if rel.startswith("workspace/"):
-                suffix = rel[len("workspace/"):]
-                for variant in ("workspace-main", "workspace-assistant"):
-                    alt = self.source_root / variant / suffix
-                    if alt.exists():
-                        return alt
-            elif rel.startswith("workspace.default/"):
-                suffix = rel[len("workspace.default/"):]
-                alt = self.source_root / "workspace-main" / suffix
-                if alt.exists():
-                    return alt
         return None
 
     def resolve_skill_destination(self, destination: Path) -> Path:
@@ -1046,8 +1033,11 @@ class Migrator:
     def migrate_secret_settings(self, config: Dict[str, Any]) -> None:
         secret_additions: Dict[str, str] = {}
 
-        tg_cfg = config.get("channels", {}).get("telegram", {})
-        telegram_token = self._get_channel_field(tg_cfg, "botToken") if isinstance(tg_cfg, dict) else None
+        telegram_token = (
+            config.get("channels", {})
+            .get("telegram", {})
+            .get("botToken")
+        )
         if isinstance(telegram_token, str) and telegram_token.strip():
             secret_additions["TELEGRAM_BOT_TOKEN"] = telegram_token.strip()
 
@@ -1067,28 +1057,15 @@ class Migrator:
         """Resolve a channel config value that may be a SecretRef."""
         return resolve_secret_input(value, self.load_openclaw_env())
 
-    @staticmethod
-    def _get_channel_field(ch_cfg: Dict[str, Any], field: str) -> Any:
-        """Get a field from channel config, checking both flat and accounts.default layout."""
-        val = ch_cfg.get(field)
-        if val is not None:
-            return val
-        accounts = ch_cfg.get("accounts")
-        if isinstance(accounts, dict):
-            default = accounts.get("default")
-            if isinstance(default, dict):
-                return default.get(field)
-        return None
-
     def migrate_discord_settings(self, config: Optional[Dict[str, Any]] = None) -> None:
         config = config or self.load_openclaw_config()
         additions: Dict[str, str] = {}
         discord = config.get("channels", {}).get("discord", {})
         if isinstance(discord, dict):
-            token = self._get_channel_field(discord, "token")
+            token = discord.get("token")
             if isinstance(token, str) and token.strip():
                 additions["DISCORD_BOT_TOKEN"] = token.strip()
-            allow_from = self._get_channel_field(discord, "allowFrom") or []
+            allow_from = discord.get("allowFrom", [])
             if isinstance(allow_from, list):
                 users = [str(u).strip() for u in allow_from if str(u).strip()]
                 if users:
@@ -1103,13 +1080,13 @@ class Migrator:
         additions: Dict[str, str] = {}
         slack = config.get("channels", {}).get("slack", {})
         if isinstance(slack, dict):
-            bot_token = self._get_channel_field(slack, "botToken")
+            bot_token = slack.get("botToken")
             if isinstance(bot_token, str) and bot_token.strip():
                 additions["SLACK_BOT_TOKEN"] = bot_token.strip()
-            app_token = self._get_channel_field(slack, "appToken")
+            app_token = slack.get("appToken")
             if isinstance(app_token, str) and app_token.strip():
                 additions["SLACK_APP_TOKEN"] = app_token.strip()
-            allow_from = self._get_channel_field(slack, "allowFrom") or []
+            allow_from = slack.get("allowFrom", [])
             if isinstance(allow_from, list):
                 users = [str(u).strip() for u in allow_from if str(u).strip()]
                 if users:
@@ -1124,7 +1101,7 @@ class Migrator:
         additions: Dict[str, str] = {}
         whatsapp = config.get("channels", {}).get("whatsapp", {})
         if isinstance(whatsapp, dict):
-            allow_from = self._get_channel_field(whatsapp, "allowFrom") or []
+            allow_from = whatsapp.get("allowFrom", [])
             if isinstance(allow_from, list):
                 users = [str(u).strip() for u in allow_from if str(u).strip()]
                 if users:
@@ -1139,13 +1116,13 @@ class Migrator:
         additions: Dict[str, str] = {}
         signal = config.get("channels", {}).get("signal", {})
         if isinstance(signal, dict):
-            account = self._get_channel_field(signal, "account")
+            account = signal.get("account")
             if isinstance(account, str) and account.strip():
                 additions["SIGNAL_ACCOUNT"] = account.strip()
-            http_url = self._get_channel_field(signal, "httpUrl")
+            http_url = signal.get("httpUrl")
             if isinstance(http_url, str) and http_url.strip():
                 additions["SIGNAL_HTTP_URL"] = http_url.strip()
-            allow_from = self._get_channel_field(signal, "allowFrom") or []
+            allow_from = signal.get("allowFrom", [])
             if isinstance(allow_from, list):
                 users = [str(u).strip() for u in allow_from if str(u).strip()]
                 if users:
@@ -1184,16 +1161,6 @@ class Migrator:
                 raw_key = provider_cfg.get("apiKey")
                 api_key = resolve_secret_input(raw_key, openclaw_env)
                 if not api_key:
-                    # Warn if a SecretRef with file/exec source was silently unresolvable
-                    if isinstance(raw_key, dict) and raw_key.get("source") in ("file", "exec"):
-                        self.record(
-                            "provider-keys",
-                            self.source_root / "openclaw.json",
-                            None,
-                            "skipped",
-                            f"Provider '{provider_name}' uses a {raw_key['source']}-backed SecretRef "
-                            f"that cannot be auto-migrated. Add this key manually via: hermes config set",
-                        )
                     continue
 
                 base_url = provider_cfg.get("baseUrl", "")
@@ -1257,21 +1224,6 @@ class Migrator:
             if val and hermes_key not in secret_additions:
                 secret_additions[hermes_key] = val
 
-        # Check the openclaw.json "env" sub-object — some OpenClaw setups
-        # store API keys here instead of in a separate .env file.
-        # Keys can be at env.<KEY> or env.vars.<KEY>.
-        json_env = config.get("env")
-        if isinstance(json_env, dict):
-            env_vars = json_env.get("vars")
-            sources = [json_env]
-            if isinstance(env_vars, dict):
-                sources.append(env_vars)
-            for src in sources:
-                for oc_key, hermes_key in env_key_mapping.items():
-                    val = src.get(oc_key)
-                    if isinstance(val, str) and val.strip() and hermes_key not in secret_additions:
-                        secret_additions[hermes_key] = val.strip()
-
         # Check per-agent auth-profiles.json for additional credentials
         auth_profiles_path = self.source_root / "agents" / "main" / "agent" / "auth-profiles.json"
         if auth_profiles_path.exists():
@@ -1372,9 +1324,8 @@ class Migrator:
         tts_data: Dict[str, Any] = {}
 
         provider = tts.get("provider")
-        if isinstance(provider, str) and provider in ("elevenlabs", "openai", "edge", "microsoft"):
-            # OpenClaw renamed "edge" to "microsoft"; Hermes still uses "edge"
-            tts_data["provider"] = "edge" if provider == "microsoft" else provider
+        if isinstance(provider, str) and provider in ("elevenlabs", "openai", "edge"):
+            tts_data["provider"] = provider
 
         # TTS provider settings live under messages.tts.providers.{provider}
         # in OpenClaw (not messages.tts.elevenlabs directly)
@@ -1423,9 +1374,9 @@ class Migrator:
                 tts_data["openai"] = oai_settings
 
         edge_tts = (
-            (providers.get("edge") or providers.get("microsoft") or {})
-            if isinstance(providers.get("edge"), dict) or isinstance(providers.get("microsoft"), dict) else
-            (tts.get("edge") or tts.get("microsoft") or {})
+            (providers.get("edge") or {})
+            if isinstance(providers.get("edge"), dict) else
+            (tts.get("edge") or {})
         )
         if isinstance(edge_tts, dict):
             edge_voice = edge_tts.get("voice")
@@ -1939,11 +1890,11 @@ class Migrator:
         if defaults.get("thinkingDefault"):
             # Map OpenClaw thinking -> Hermes reasoning_effort
             thinking = defaults["thinkingDefault"]
-            if thinking in ("always", "high", "xhigh"):
+            if thinking in ("always", "high"):
                 agent_cfg["reasoning_effort"] = "high"
-            elif thinking in ("auto", "medium", "adaptive"):
+            elif thinking in ("auto", "medium"):
                 agent_cfg["reasoning_effort"] = "medium"
-            elif thinking in ("off", "low", "none", "minimal"):
+            elif thinking in ("off", "low", "none"):
                 agent_cfg["reasoning_effort"] = "low"
             changes = True
 
@@ -2148,14 +2099,10 @@ class Migrator:
                                 f"Provider '{prov_name}' already exists")
                     continue
 
-                api_type = prov_cfg.get("apiType") or prov_cfg.get("api") or prov_cfg.get("type") or "openai"
+                api_type = prov_cfg.get("apiType") or prov_cfg.get("type") or "openai"
                 api_mode_map = {
                     "openai": "chat_completions",
-                    "openai-completions": "chat_completions",
-                    "openai-responses": "chat_completions",
                     "anthropic": "anthropic_messages",
-                    "anthropic-messages": "anthropic_messages",
-                    "google-generative-ai": "chat_completions",
                     "cohere": "chat_completions",
                 }
                 entry = {
@@ -2195,7 +2142,7 @@ class Migrator:
 
         # Extended channel token/allowlist mapping
         CHANNEL_ENV_MAP = {
-            "matrix": {"token": "MATRIX...OKEN", "tokenField": "accessToken", "allowFrom": "MATRIX_ALLOWED_USERS",
+            "matrix": {"token": "MATRIX_ACCESS_TOKEN", "allowFrom": "MATRIX_ALLOWED_USERS",
                         "extras": {"homeserverUrl": "MATRIX_HOMESERVER_URL", "userId": "MATRIX_USER_ID"}},
             "mattermost": {"token": "MATTERMOST_BOT_TOKEN", "allowFrom": "MATTERMOST_ALLOWED_USERS",
                            "extras": {"url": "MATTERMOST_URL", "teamId": "MATTERMOST_TEAM_ID"}},
@@ -2213,21 +2160,19 @@ class Migrator:
             if not ch_cfg:
                 continue
 
-            # Extract tokens (check flat path, then accounts.default)
-            token_field = ch_mapping.get("tokenField", "botToken")
-            bot_token = self._get_channel_field(ch_cfg, token_field)
-            if ch_mapping.get("token") and bot_token and self.migrate_secrets:
-                self._set_env_var(ch_mapping["token"], str(bot_token),
-                                  f"channels.{ch_name}.{token_field}")
-            allow_val = self._get_channel_field(ch_cfg, "allowFrom")
-            if ch_mapping.get("allowFrom") and allow_val:
+            # Extract tokens
+            if ch_mapping.get("token") and ch_cfg.get("botToken") and self.migrate_secrets:
+                self._set_env_var(ch_mapping["token"], ch_cfg["botToken"],
+                                  f"channels.{ch_name}.botToken")
+            if ch_mapping.get("allowFrom") and ch_cfg.get("allowFrom"):
+                allow_val = ch_cfg["allowFrom"]
                 if isinstance(allow_val, list):
                     allow_val = ",".join(str(x) for x in allow_val)
                 self._set_env_var(ch_mapping["allowFrom"], str(allow_val),
                                   f"channels.{ch_name}.allowFrom")
             # Extra fields
             for oc_key, env_key in (ch_mapping.get("extras") or {}).items():
-                val = self._get_channel_field(ch_cfg, oc_key)
+                val = ch_cfg.get(oc_key)
                 if val:
                     if isinstance(val, list):
                         val = ",".join(str(x) for x in val)
@@ -2550,33 +2495,6 @@ class Migrator:
         elif has_cron_store_archive:
             notes.append("- Run `hermes cron` to recreate scheduled tasks (see archived cron-store)")
 
-        # Check if skills were imported
-        has_skills = any(i.kind == "skills" and i.status == "migrated" for i in self.items)
-        if has_skills:
-            notes.extend([
-                "",
-                "## Imported Skills",
-                "",
-                "Imported skills require a new session to take effect. After migration,",
-                "restart your agent or start a new chat session, then run `/skills`",
-                "to verify they loaded correctly.",
-                "",
-            ])
-
-        # Check if WhatsApp was detected
-        has_whatsapp = any(i.kind == "whatsapp-settings" and i.status == "migrated" for i in self.items)
-        if has_whatsapp:
-            notes.extend([
-                "",
-                "## WhatsApp Requires Re-Pairing",
-                "",
-                "WhatsApp uses QR-code pairing, not token-based auth. Your allowlist",
-                "was migrated, but you must re-pair the device by running:",
-                "",
-                "    hermes whatsapp",
-                "",
-            ])
-
         notes.extend([
             "- Run `hermes gateway install` if you need the gateway service",
             "- Review `~/.hermes/config.yaml` for any adjustments",

tests/hermes_cli/test_claw.py

@@ -289,16 +289,12 @@ class TestCmdMigrate:
             skill_conflict="skip", yes=False,
         )
 
-        mock_stdin = MagicMock()
-        mock_stdin.isatty.return_value = True
-
         with (
             patch.object(claw_mod, "_find_migration_script", return_value=tmp_path / "s.py"),
             patch.object(claw_mod, "_load_migration_module", return_value=fake_mod),
             patch.object(claw_mod, "get_config_path", return_value=config_path),
             patch.object(claw_mod, "prompt_yes_no", return_value=True),
             patch.object(claw_mod, "_offer_source_archival"),
-            patch("sys.stdin", mock_stdin),
         ):
             claw_mod._cmd_migrate(args)
 
@@ -381,16 +377,6 @@ class TestCmdMigrate:
         config_path = tmp_path / "config.yaml"
         config_path.write_text("")
 
-        # Preview must succeed before the confirmation prompt is shown
-        fake_mod = ModuleType("openclaw_to_hermes")
-        fake_mod.resolve_selected_options = MagicMock(return_value=set())
-        fake_migrator = MagicMock()
-        fake_migrator.migrate.return_value = {
-            "summary": {"migrated": 1, "skipped": 0, "conflict": 0, "error": 0},
-            "items": [{"kind": "soul", "status": "migrated", "source": "s", "destination": "d", "reason": ""}],
-        }
-        fake_mod.Migrator = MagicMock(return_value=fake_migrator)
-
         args = Namespace(
             source=str(openclaw_dir),
             dry_run=False, preset="full", overwrite=False,
@@ -398,15 +384,9 @@ class TestCmdMigrate:
             skill_conflict="skip", yes=False,
         )
 
-        mock_stdin = MagicMock()
-        mock_stdin.isatty.return_value = True
-
         with (
             patch.object(claw_mod, "_find_migration_script", return_value=tmp_path / "s.py"),
-            patch.object(claw_mod, "_load_migration_module", return_value=fake_mod),
-            patch.object(claw_mod, "get_config_path", return_value=config_path),
             patch.object(claw_mod, "prompt_yes_no", return_value=False),
-            patch("sys.stdin", mock_stdin),
         ):
             claw_mod._cmd_migrate(args)
 
@@ -468,7 +448,7 @@ class TestCmdMigrate:
             claw_mod._cmd_migrate(args)
 
         captured = capsys.readouterr()
-        assert "Could not load migration script" in captured.out
+        assert "Migration failed" in captured.out
 
     def test_full_preset_enables_secrets(self, tmp_path, capsys):
         """The 'full' preset should set migrate_secrets=True automatically."""
@@ -531,13 +511,7 @@ class TestOfferSourceArchival:
         source = tmp_path / ".openclaw"
         source.mkdir()
 
-        mock_stdin = MagicMock()
-        mock_stdin.isatty.return_value = True
-
-        with (
-            patch.object(claw_mod, "prompt_yes_no", return_value=False),
-            patch("sys.stdin", mock_stdin),
-        ):
+        with patch.object(claw_mod, "prompt_yes_no", return_value=False):
             claw_mod._offer_source_archival(source, auto_yes=False)
 
         captured = capsys.readouterr()
@@ -623,14 +597,10 @@ class TestCmdCleanup:
         openclaw = tmp_path / ".openclaw"
         openclaw.mkdir()
 
-        mock_stdin = MagicMock()
-        mock_stdin.isatty.return_value = True
-
         args = Namespace(source=None, dry_run=False, yes=False)
         with (
             patch.object(claw_mod, "_find_openclaw_dirs", return_value=[openclaw]),
             patch.object(claw_mod, "prompt_yes_no", return_value=False),
-            patch("sys.stdin", mock_stdin),
         ):
             claw_mod._cmd_cleanup(args)
 

website/docs/guides/migrate-from-openclaw.md

@@ -11,32 +11,30 @@ description: "Complete guide to migrating your OpenClaw / Clawdbot setup to Herm
 ## Quick start
 
 ```bash
-# Preview then migrate (always shows a preview first, then asks to confirm)
-hermes claw migrate
-
-# Preview only, no changes
+# Preview what would happen (no files changed)
 hermes claw migrate --dry-run
 
-# Full migration including API keys, skip confirmation
-hermes claw migrate --preset full --yes
+# Run the migration (secrets excluded by default)
+hermes claw migrate
+
+# Full migration including API keys
+hermes claw migrate --preset full
 ```
 
-The migration always shows a full preview of what will be imported before making any changes. Review the list, then confirm to proceed.
-
-Reads from `~/.openclaw/` by default. Legacy `~/.clawdbot/` or `~/.moldbot/` directories are detected automatically. Same for legacy config filenames (`clawdbot.json`, `moldbot.json`).
+The migration reads from `~/.openclaw/` by default. If you still have a legacy `~/.clawdbot/` or `~/.moldbot/` directory, it's detected automatically. Same for legacy config filenames (`clawdbot.json`, `moldbot.json`).
 
 ## Options
 
 | Option | Description |
 |--------|-------------|
-| `--dry-run` | Preview only — stop after showing what would be migrated. |
+| `--dry-run` | Preview what would be migrated without writing anything. |
 | `--preset <name>` | `full` (default, includes secrets) or `user-data` (excludes API keys). |
 | `--overwrite` | Overwrite existing Hermes files on conflicts (default: skip). |
 | `--migrate-secrets` | Include API keys (on by default with `--preset full`). |
 | `--source <path>` | Custom OpenClaw directory. |
 | `--workspace-target <path>` | Where to place `AGENTS.md`. |
 | `--skill-conflict <mode>` | `skip` (default), `overwrite`, or `rename`. |
-| `--yes` | Skip the confirmation prompt after preview. |
+| `--yes` | Skip confirmation prompt. |
 
 ## What gets migrated
 
@@ -50,7 +48,7 @@ Reads from `~/.openclaw/` by default. Legacy `~/.clawdbot/` or `~/.moldbot/` dir
 | User profile | `workspace/USER.md` | `~/.hermes/memories/USER.md` | Same entry-merge logic as memory. |
 | Daily memory files | `workspace/memory/*.md` | `~/.hermes/memories/MEMORY.md` | All daily files merged into main memory. |
 
-Workspace files are also checked at `workspace.default/` and `workspace-main/` as fallback paths (OpenClaw renamed `workspace/` to `workspace-main/` in recent versions, and uses `workspace-{agentId}` for multi-agent setups).
+All workspace files also check `workspace.default/` as a fallback path.
 
 ### Skills (4 sources)
 
@@ -68,7 +66,7 @@ Skill conflicts are handled by `--skill-conflict`: `skip` leaves the existing He
 | What | OpenClaw config path | Hermes destination | Notes |
 |------|---------------------|-------------------|-------|
 | Default model | `agents.defaults.model` | `config.yaml` → `model` | Can be a string or `{primary, fallbacks}` object |
-| Custom providers | `models.providers.*` | `config.yaml` → `custom_providers` | Maps `baseUrl`, `apiType`/`api` — handles both short ("openai", "anthropic") and hyphenated ("openai-completions", "anthropic-messages", "google-generative-ai") values |
+| Custom providers | `models.providers.*` | `config.yaml` → `custom_providers` | Maps `baseUrl`, `apiType` ("openai"→"chat_completions", "anthropic"→"anthropic_messages") |
 | Provider API keys | `models.providers.*.apiKey` | `~/.hermes/.env` | Requires `--migrate-secrets`. See [API key resolution](#api-key-resolution) below. |
 
 ### Agent behavior
@@ -77,7 +75,7 @@ Skill conflicts are handled by `--skill-conflict`: `skip` leaves the existing He
 |------|---------------------|-------------------|---------|
 | Max turns | `agents.defaults.timeoutSeconds` | `agent.max_turns` | `timeoutSeconds / 10`, capped at 200 |
 | Verbose mode | `agents.defaults.verboseDefault` | `agent.verbose` | "off" / "on" / "full" |
-| Reasoning effort | `agents.defaults.thinkingDefault` | `agent.reasoning_effort` | "always"/"high"/"xhigh" → "high", "auto"/"medium"/"adaptive" → "medium", "off"/"low"/"none"/"minimal" → "low" |
+| Reasoning effort | `agents.defaults.thinkingDefault` | `agent.reasoning_effort` | "always"/"high" → "high", "auto"/"medium" → "medium", "off"/"low"/"none"/"minimal" → "low" |
 | Compression | `agents.defaults.compaction.mode` | `compression.enabled` | "off" → false, anything else → true |
 | Compression model | `agents.defaults.compaction.model` | `compression.summary_model` | Direct string copy |
 | Human delay | `agents.defaults.humanDelay.mode` | `human_delay.mode` | "natural" / "custom" / "off" |
@@ -124,26 +122,26 @@ TTS settings are read from **two** OpenClaw config locations with this priority:
 | ElevenLabs model ID | `config.yaml` → `tts.elevenlabs.model_id` |
 | OpenAI model | `config.yaml` → `tts.openai.model` |
 | OpenAI voice | `config.yaml` → `tts.openai.voice` |
-| Edge TTS voice | `config.yaml` → `tts.edge.voice` (OpenClaw renamed "edge" to "microsoft" — both are recognized) |
+| Edge TTS voice | `config.yaml` → `tts.edge.voice` |
 | TTS assets | `~/.hermes/tts/` (file copy) |
 
 ### Messaging platforms
 
 | Platform | OpenClaw config path | Hermes `.env` variable | Notes |
 |----------|---------------------|----------------------|-------|
-| Telegram | `channels.telegram.botToken` or `.accounts.default.botToken` | `TELEGRAM_BOT_TOKEN` | Token can be string or [SecretRef](#secretref-handling). Both flat and accounts layout supported. |
+| Telegram | `channels.telegram.botToken` | `TELEGRAM_BOT_TOKEN` | Token can be string or [SecretRef](#secretref-handling) |
 | Telegram | `credentials/telegram-default-allowFrom.json` | `TELEGRAM_ALLOWED_USERS` | Comma-joined from `allowFrom[]` array |
-| Discord | `channels.discord.token` or `.accounts.default.token` | `DISCORD_BOT_TOKEN` | |
-| Discord | `channels.discord.allowFrom` or `.accounts.default.allowFrom` | `DISCORD_ALLOWED_USERS` | |
-| Slack | `channels.slack.botToken` or `.accounts.default.botToken` | `SLACK_BOT_TOKEN` | |
-| Slack | `channels.slack.appToken` or `.accounts.default.appToken` | `SLACK_APP_TOKEN` | |
-| Slack | `channels.slack.allowFrom` or `.accounts.default.allowFrom` | `SLACK_ALLOWED_USERS` | |
-| WhatsApp | `channels.whatsapp.allowFrom` or `.accounts.default.allowFrom` | `WHATSAPP_ALLOWED_USERS` | Auth via Baileys QR pairing — requires re-pairing after migration |
-| Signal | `channels.signal.account` or `.accounts.default.account` | `SIGNAL_ACCOUNT` | |
-| Signal | `channels.signal.httpUrl` or `.accounts.default.httpUrl` | `SIGNAL_HTTP_URL` | |
-| Signal | `channels.signal.allowFrom` or `.accounts.default.allowFrom` | `SIGNAL_ALLOWED_USERS` | |
-| Matrix | `channels.matrix.accessToken` or `.accounts.default.accessToken` | `MATRIX_ACCESS_TOKEN` | Uses `accessToken` (not `botToken`) |
-| Mattermost | `channels.mattermost.botToken` or `.accounts.default.botToken` | `MATTERMOST_BOT_TOKEN` | |
+| Discord | `channels.discord.token` | `DISCORD_BOT_TOKEN` | |
+| Discord | `channels.discord.allowFrom` | `DISCORD_ALLOWED_USERS` | |
+| Slack | `channels.slack.botToken` | `SLACK_BOT_TOKEN` | |
+| Slack | `channels.slack.appToken` | `SLACK_APP_TOKEN` | |
+| Slack | `channels.slack.allowFrom` | `SLACK_ALLOWED_USERS` | |
+| WhatsApp | `channels.whatsapp.allowFrom` | `WHATSAPP_ALLOWED_USERS` | Auth via Baileys QR pairing (not a token) |
+| Signal | `channels.signal.account` | `SIGNAL_ACCOUNT` | |
+| Signal | `channels.signal.httpUrl` | `SIGNAL_HTTP_URL` | |
+| Signal | `channels.signal.allowFrom` | `SIGNAL_ALLOWED_USERS` | |
+| Matrix | `channels.matrix.botToken` | `MATRIX_ACCESS_TOKEN` | Via deep-channels migration |
+| Mattermost | `channels.mattermost.botToken` | `MATTERMOST_BOT_TOKEN` | Via deep-channels migration |
 
 ### Other config
 
@@ -180,14 +178,13 @@ These are saved to `~/.hermes/migration/openclaw/<timestamp>/archive/` for manua
 
 ## API key resolution
 
-When `--migrate-secrets` is enabled, API keys are collected from **four sources** in priority order:
+When `--migrate-secrets` is enabled, API keys are collected from **three sources** in priority order:
 
 1. **Config values** — `models.providers.*.apiKey` and TTS provider keys in `openclaw.json`
 2. **Environment file** — `~/.openclaw/.env` (keys like `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, etc.)
-3. **Config env sub-object** — `openclaw.json` → `"env"` or `"env"."vars"` (some setups store keys here instead of a separate `.env` file)
-4. **Auth profiles** — `~/.openclaw/agents/main/agent/auth-profiles.json` (per-agent credentials)
+3. **Auth profiles** — `~/.openclaw/agents/main/agent/auth-profiles.json` (per-agent credentials)
 
-Config values take priority. Each subsequent source fills any remaining gaps.
+Config values take priority. The `.env` fills any gaps. Auth profiles fill whatever remains.
 
 ### Supported key targets
 
@@ -210,7 +207,7 @@ OpenClaw config values for tokens and API keys can be in three formats:
 "channels": { "telegram": { "botToken": { "source": "env", "id": "TELEGRAM_BOT_TOKEN" } } }
 ```
 
-The migration resolves all three formats. For env templates and SecretRef objects with `source: "env"`, it looks up the value in `~/.openclaw/.env` and the `openclaw.json` env sub-object. SecretRef objects with `source: "file"` or `source: "exec"` can't be resolved automatically — the migration warns about these, and those values must be added to Hermes manually via `hermes config set`.
+The migration resolves all three formats. For env templates and SecretRef objects with `source: "env"`, it looks up the value in `~/.openclaw/.env`. SecretRef objects with `source: "file"` or `source: "exec"` can't be resolved automatically — those values must be added to Hermes manually after migration.
 
 ## After migration
 
@@ -218,17 +215,13 @@ The migration resolves all three formats. For env templates and SecretRef object
 
 2. **Review archived files** — anything in `~/.hermes/migration/openclaw/<timestamp>/archive/` needs manual attention.
 
-3. **Start a new session** — imported skills and memory entries take effect in new sessions, not the current one.
+3. **Verify API keys** — run `hermes status` to check provider authentication.
 
-4. **Verify API keys** — run `hermes status` to check provider authentication.
+4. **Test messaging** — if you migrated platform tokens, restart the gateway: `systemctl --user restart hermes-gateway`
 
-5. **Test messaging** — if you migrated platform tokens, restart the gateway: `systemctl --user restart hermes-gateway`
+5. **Check session policies** — verify `hermes config get session_reset` matches your expectations.
 
-6. **Check session policies** — verify `hermes config get session_reset` matches your expectations.
-
-7. **Re-pair WhatsApp** — WhatsApp uses QR code pairing (Baileys), not token migration. Run `hermes whatsapp` to pair.
-
-8. **Archive cleanup** — after confirming everything works, run `hermes claw cleanup` to rename leftover OpenClaw directories to `.pre-migration/` (prevents state confusion).
+6. **Re-pair WhatsApp** — WhatsApp uses QR code pairing (Baileys), not token migration. Run `hermes whatsapp` to pair.
 
 ## Troubleshooting
 
@@ -238,7 +231,7 @@ The migration checks `~/.openclaw/`, then `~/.clawdbot/`, then `~/.moldbot/`. If
 
 ### "No provider API keys found"
 
-Keys might be stored in several places depending on your OpenClaw version: inline in `openclaw.json` under `models.providers.*.apiKey`, in `~/.openclaw/.env`, in the `openclaw.json` `"env"` sub-object, or in `agents/main/agent/auth-profiles.json`. The migration checks all four. If keys use `source: "file"` or `source: "exec"` SecretRefs, they can't be resolved automatically — add them via `hermes config set`.
+Keys might be in your `.env` file instead of `openclaw.json`. The migration checks both — make sure `~/.openclaw/.env` exists and has the keys. If keys use `source: "file"` or `source: "exec"` SecretRefs, they can't be resolved automatically.
 
 ### Skills not appearing after migration