diff --git a/agent/onboarding.py b/agent/onboarding.py
index cf66bad1..220b1c60 100644
--- a/agent/onboarding.py
+++ b/agent/onboarding.py
@@ -98,17 +98,19 @@ def tool_progress_hint_cli() -> str:
 def openclaw_residue_hint_cli() -> str:
     """Banner shown the first time Hermes starts and finds ``~/.openclaw/``.
 
-    OpenClaw-era config, memory, and skill paths in ``~/.openclaw/`` will
-    otherwise attract the agent (memory entries like ``~/.openclaw/config.yaml``
-    get carried forward and the agent dutifully reads them). ``hermes claw
-    cleanup`` renames the directory so the agent stops finding it.
+    Points users at ``hermes claw migrate`` (non-destructive port of config,
+    memory, and skills) first. ``hermes claw cleanup`` is mentioned as the
+    follow-up step for users who have already migrated and want to archive
+    the old directory — with a warning that archiving breaks OpenClaw.
     """
     return (
-        "Heads up — an OpenClaw workspace was detected at ~/.openclaw/.\n"
-        "After migrating, the agent can still get confused and read that "
-        "directory's config/memory instead of Hermes's.\n"
-        "Run `hermes claw cleanup` to archive it (rename → .openclaw.pre-migration). "
-        "This tip only shows once; rerun it any time with `hermes claw cleanup`."
+        "A legacy OpenClaw directory was detected at ~/.openclaw/.\n"
+        "To port your config, memory, and skills over to Hermes, run "
+        "`hermes claw migrate`.\n"
+        "If you've already migrated and want to archive the old directory, "
+        "run `hermes claw cleanup` (renames it to ~/.openclaw.pre-migration — "
+        "OpenClaw will stop working after this).\n"
+        "This tip only shows once."
     )
 
 
diff --git a/tests/agent/test_onboarding.py b/tests/agent/test_onboarding.py
index c8869798..1eaf0d01 100644
--- a/tests/agent/test_onboarding.py
+++ b/tests/agent/test_onboarding.py
@@ -205,11 +205,22 @@ class TestDetectOpenclawResidue:
 
 
 class TestOpenclawResidueHint:
-    def test_hint_mentions_cleanup_command(self):
+    def test_hint_mentions_migrate_command(self):
+        # `migrate` is the non-destructive path — should lead the banner.
         msg = openclaw_residue_hint_cli()
-        assert "hermes claw cleanup" in msg
+        assert "hermes claw migrate" in msg
         assert "~/.openclaw" in msg
 
+    def test_hint_mentions_cleanup_command(self):
+        # `cleanup` is mentioned as the follow-up archive step.
+        assert "hermes claw cleanup" in openclaw_residue_hint_cli()
+
+    def test_hint_warns_cleanup_breaks_openclaw(self):
+        # Archiving the directory breaks OpenClaw for users still running it —
+        # the banner must flag that side effect.
+        msg = openclaw_residue_hint_cli().lower()
+        assert "openclaw will stop working" in msg or "stop working" in msg
+
     def test_hint_not_empty(self):
         assert openclaw_residue_hint_cli().strip()