PR #64859: fix(cli): stop misclassifying help/tool as plugin-gated

• Repository: openclaw/openclaw
• Author: briandevans
• State: closed | merged: False
• Link: https://github.com/openclaw/openclaw/pull/64859

Description (problem / solution / changelog)

Summary

• Problem: resolveMissingPluginCommandMessage() treated any missing primary token as plugin-backed under restrictive plugins.allow.
• Why it matters: openclaw help broke outright, and openclaw tool ... returned a misleading allowlist error even though tool is not a manifest-backed plugin command on current main.
• What changed: the missing-command guidance now only triggers for real plugin ids or manifest-backed aliases, and regression tests lock in the help/tool cases.
• What did NOT change (scope boundary): this PR does not restore a tool CLI surface; it only stops blaming plugins.allow for non-plugin tokens.

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 #64732
• Related #48919
• This PR fixes a bug or regression

Root Cause (if applicable)

• Root cause: the CLI only checked whether the primary token was still absent after lazy plugin registration, then assumed it must be a plugin-backed command.
• Missing detection / guardrail: there was no manifest-backed existence check before emitting plugins.allow / plugins.entries.*.enabled guidance.
• Contributing context (if known): Commander’s built-in help command is not represented in program.commands, and tool is also not a manifest-backed plugin id or alias on current main.

Regression Test Plan (if applicable)

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
  • Existing coverage already sufficient
• Target test or file: src/cli/run-main.test.ts
• Scenario the test should lock in: restrictive plugins.allow must not report help or tool as excluded plugins, while real plugin commands and manifest aliases still do.
• Why this is the smallest reliable guardrail: resolveMissingPluginCommandMessage() is the exact decision point that converts a missing primary token into the startup error.
• Existing test that already covers this (if any): the existing browser and dreaming cases already cover direct plugin ids and manifest-backed aliases.
• If no new test is added, why not: N/A

User-visible / Behavior Changes

• openclaw help works again under restrictive plugins.allow configs.
• Non-plugin tokens like openclaw tool ... now fall through to Commander’s normal unknown-command handling instead of a false plugins.allow error.
• Real plugin commands and manifest-backed aliases still return the existing allowlist guidance.

Diagram (if applicable)

Before:
[user types help/tool] -> [primary missing after lazy registration] -> [generic plugin-gated error]

After:
[user types command] -> [check manifest-backed plugin/alias?]
  -> yes -> [existing plugin guidance]
  -> no  -> [normal Commander parse/help path]

Security Impact (required)

• New permissions/capabilities? (Yes/No) No
• Secrets/tokens handling changed? (Yes/No) No
• New/changed network calls? (Yes/No) No
• Command/tool execution surface changed? (Yes/No) No
• Data access scope changed? (Yes/No) No
• If any Yes, explain risk + mitigation:

Repro + Verification

Environment

• OS: macOS
• Runtime/container: local checkout via node scripts/run-node.mjs
• Model/provider: N/A
• Integration/channel (if any): none
• Relevant config (redacted):

  {
    "plugins": {
      "allow": ["telegram", "matrix", "anthropic", "openai", "openrouter"]
    }
  }

Steps

1. Use a restrictive plugins.allow that omits help / tool and excludes a real plugin command such as browser.
2. Run openclaw help, openclaw tool image_generate --prompt test --filename test.png, and openclaw browser --help.
3. Compare the startup behavior before and after this patch.

Expected

• openclaw help should still print help.
• Non-plugin tokens should not claim they were excluded by plugins.allow.
• Real plugin commands should keep their existing allowlist guidance.

Actual

• Before this PR, both help and tool failed with plugins.allow excludes "...".
• After this PR, help prints root help, tool falls through to unknown command 'tool', and excluded real plugin commands like browser still surface the allowlist error.

Evidence

Attach at least one:

• Failing test/log before + passing after
• Trace/log snippets
• Screenshot/recording
• Perf numbers (if relevant)

Human Verification (required)

What you personally verified (not just CI), and how:

• Verified scenarios: added the unit regression first, then reran it; manually reproed openclaw help under a restrictive allowlist; manually reproed openclaw tool image_generate ...; manually confirmed openclaw browser --help still reports the allowlist error when browser is excluded.
• Edge cases checked: existing dreaming alias coverage still points at memory-core; direct bundled plugin ids like browser still return the plugin guidance path.
• What you did not verify: I did not rerun the full pnpm test suite. The local pre-commit pnpm check hook still fails in unrelated extension lint surfaces (extensions/feishu/**, extensions/codex/**, extensions/msteams/**) on my checkout, both before and after this change.

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.

If a bot review conversation is addressed by this PR, resolve that conversation yourself. Do not leave bot review conversation cleanup for maintainers.

Compatibility / Migration

• Backward compatible? (Yes/No) Yes
• Config/env changes? (Yes/No) No
• Migration needed? (Yes/No) No
• If yes, exact upgrade steps:

Risks and Mitigations

• Risk: a workflow that depended on the old, misleading plugins.allow excludes "tool" text will now see Commander’s normal unknown command output instead.
  • Mitigation: actual plugin and alias cases still use the old guidance path; only non-plugin tokens change behavior.

AI Assistance

• AI-assisted: Yes (Codex)
• Testing degree: targeted unit + live CLI verification + build
• Prompt/session summary: triaged recent issues and merged PRs for fit, reproduced #64732 on 2026-04-11, narrowed the bug to the missing-plugin guidance path, added the smallest regression coverage, verified the live CLI behavior, and attempted the repo’s local pnpm check / codex review protocol steps.
• Understanding confirmation: I understand this only narrows when the CLI emits plugin-gating guidance; it does not add or restore a tool command surface.
• Codex review note: I attempted codex review --base origin/main, but the local Codex CLI failed before review with invalid_grant during token refresh.

Verification Commands

• pnpm exec vitest run src/cli/run-main.test.ts
• pnpm exec oxlint src/cli/run-main.ts src/cli/run-main.test.ts
• pnpm build
• OPENCLAW_CONFIG_PATH=<tmp-config> OPENCLAW_STATE_DIR=<tmp-state> node scripts/run-node.mjs help
• OPENCLAW_CONFIG_PATH=<tmp-config> OPENCLAW_STATE_DIR=<tmp-state> node scripts/run-node.mjs tool image_generate --prompt test --filename test.png
• OPENCLAW_CONFIG_PATH=<tmp-config> OPENCLAW_STATE_DIR=<tmp-state> node scripts/run-node.mjs browser --help
• Attempted: pre-commit pnpm check hook (failed in unrelated extension lint files already failing locally on 2026-04-11)

Changed files

• src/cli/run-main.test.ts (modified, +20/-0)
• src/cli/run-main.ts (modified, +9/-0)