From 1bedc836b5f4d15715c4f59f036cb0b649939b97 Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 29 Apr 2026 08:08:36 -0700 Subject: [PATCH] docs(onboarding): lead OpenClaw residue banner with migrate, warn that cleanup breaks OpenClaw (#17507) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The ~/.openclaw/ detection banner (#16327) had two problems flagged in #16629: 1. It only pitched 'hermes claw cleanup' (destructive archive) and never mentioned 'hermes claw migrate' — the actual non-destructive path that ports config/memory/skills into Hermes. 2. The copy anthropomorphized the bug ('the agent can still get confused', 'dutifully reads') and framed OpenClaw as a competitor to eliminate ('instead of Hermes's'). Rewrite so migrate leads, cleanup is a clearly-labelled follow-up with a warning that archiving breaks OpenClaw for users still running it. Closes #16629 --- agent/onboarding.py | 20 +++++++++++--------- tests/agent/test_onboarding.py | 15 +++++++++++++-- 2 files changed, 24 insertions(+), 11 deletions(-) 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()