PR #59575: feat(plugins): add plugins clean command to remove stale plugin config refs

• Repository: openclaw/openclaw
• Author: rrrrrredy
• State: open | merged: False
• Link: https://github.com/openclaw/openclaw/pull/59575

Description (problem / solution / changelog)

Summary

• Problem: Removing stale or orphaned plugin entries required manual config edits; there was no dedicated user-facing command.
• Why it matters: Stale plugin entries can cause confusion and unexpected behaviour; a clean command gives users a safe, discoverable way to remove them without touching config files directly.
• What changed: Added openclaw plugins clean command that identifies stale/orphaned plugin entries, shows a before/after diff, guards against empty change sets, and applies changes using sourceConfig as the base (not the potentially-mutated in-memory config).
• What did NOT change (scope boundary): Existing plugins list, plugins add, plugins remove commands are unaffected. No changes to plugin loading logic.

Change Type (select all)

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope (select all touched areas)

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue/PR

• Closes #59448
• Related #59455
• This PR fixes a bug or regression

Root Cause / Regression History (if applicable)

• Root cause: N/A – new feature, not a regression.
• Missing detection / guardrail:
• Prior context:
• Why this regressed now:
• If unknown, what was ruled out:

Regression Test Plan (if applicable)

• Coverage level:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/cli/plugins-cli/
• Scenario the test should lock in: Clean command with stale entries produces correct diff; empty-changes guard prevents no-op write.
• Why this is the smallest reliable guardrail: Unit tests on the clean command logic with mock config; no filesystem side effects.
• Existing test that already covers this: N/A
• If no new test is added, why not: N/A — unit tests cover the new command.

User-visible / Behavior Changes

New openclaw plugins clean command available. Removes stale plugin entries with a confirmation diff.

Security Impact (required)

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? No
• Command/tool execution surface changed? No
• Data access scope changed? No

Human Verification (required)

• Verified scenarios: openclaw plugins clean with stale entries shows diff and removes them. Running with no stale entries exits cleanly with no config write.
• Edge cases checked: Empty changes array is guarded; no spurious config write occurs.
• What you did not verify: Behavior with a very large number of plugin entries; concurrent access to the config file.

Review Conversations

• I replied to or resolved every bot review conversation I addressed in this PR.
• I left unresolved only the conversations that still need reviewer or maintainer judgment.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No
• Migration needed? No

Summary

Adds openclaw plugins clean as a focused, discoverable alternative to openclaw doctor --fix for clearing leftover plugin entries after uninstalling a plugin.

Problem

When users uninstall a plugin, stale references can remain in plugins.allow and plugins.entries. The fix existed (openclaw doctor --fix) but was buried — users had to know to run doctor just for this cleanup.

Solution

$ openclaw plugins clean
Found 2 stale plugin references:
  - plugins.allow: "weixin"
  - plugins.entries.weixin: "weixin"

Removed:
  - plugins.allow: removed 1 stale plugin id (weixin)
  - plugins.entries: removed 1 stale plugin entry (weixin)

Supports --dry-run to preview without writing:

$ openclaw plugins clean --dry-run
Found 2 stale plugin references:
  - plugins.allow: "weixin"
  - plugins.entries.weixin: "weixin"

(dry run — no changes written; rerun without --dry-run to apply)

Design Decision: Option A (explicit command) vs Option C (auto-clean on startup)

Two approaches were considered for fixing stale plugin references:

Option A (this PR): explicit plugins clean command

• User explicitly runs the command — full control and visibility
• Supports --dry-run to preview before committing
• plugins clean is discoverable via openclaw plugins --help
• No surprises: config is never modified without the user's knowledge

Option C: auto-fix on startup

• Would silently modify openclaw.json at boot time without user awareness
• Violates the principle of least surprise — config changes should be intentional
• openclaw doctor --fix already provides an auto-fix path for those who want it, but as a deliberate opt-in, not a side effect of startup

Why Option A was chosen: Config files are the user's source of truth. Auto-mutating them on startup (Option C) can mask bugs, cause confusion during debugging, and erode user trust. An explicit command preserves auditability and control. The --dry-run flag further lowers the barrier to adoption by letting users preview changes safely.

Implementation Notes

• Reuses existing maybeRepairStalePluginConfig() from doctor/shared/stale-plugin-config.ts — no new logic
• Blocks removal if plugin discovery has errors (same guard as doctor --fix)
• This is entirely a CLI-side change — no Gateway/server API changes needed

Testing

• Added unit tests in plugins-cli.clean.test.ts covering: no stale entries (noop), stale entries found + removed, --dry-run mode (no write), and blocked removal on discovery error
• Tests use the existing plugins-cli-test-helpers.ts mock infrastructure
• Ran pnpm test src/cli/plugins-cli locally — all tests pass

Related

Closes #59448

Changed files

• .github/actions/setup-node-env/action.yml (modified, +1/-1)
• .github/actions/setup-pnpm-store-cache/action.yml (modified, +1/-1)
• .github/labeler.yml (modified, +0/-27)
• .github/pr-assets/compaction-checkpoints/sessions-checkpoints-inline.png (removed, +0/-0)
• .github/pr-assets/compaction-checkpoints/sessions-overview-inline.png (removed, +0/-0)
• .github/pull_request_template.md (modified, +5/-3)
• .github/workflows/auto-response.yml (modified, +2/-6)
• .github/workflows/ci.yml (modified, +19/-2)
• .github/workflows/control-ui-locale-refresh.yml (removed, +0/-172)
• .github/workflows/docs-sync-publish.yml (removed, +0/-70)
• .github/workflows/docs-translate-trigger-release.yml (removed, +0/-42)
• .github/workflows/macos-release.yml (modified, +1/-1)
• .github/workflows/openclaw-npm-release.yml (modified, +9/-162)
• .github/workflows/plugin-clawhub-release.yml (removed, +0/-276)
• .github/workflows/plugin-npm-release.yml (modified, +1/-1)
• src/cli/plugins-cli.clean.test.ts (added, +121/-0)
• src/cli/plugins-cli.ts (modified, +67/-0)