PR #63512: fix(CLI): disable help on lazy placeholders so --help triggers lazy-load reparse

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

Description (problem / solution / changelog)

Summary

• Lazy-loaded CLI commands (config, models, gateway, cron, channels, agents, etc.) with subcommands showed an empty help when invoked with --help, because Commander.js does not call the .action() handler for --help, so subcommands were never registered before help rendered.
• Adding placeholder.helpOption(false) to the placeholder command removes the --help flag intercept on the placeholder, causing Commander to fall through and re-trigger the lazy-load action handler which then registers real subcommands and re-parses --help against the fully loaded command tree.
• Root help continued to work because it reads from precomputed cli-startup-metadata.json.
• Includes 3 unit tests covering help bypass, allowUnknownOption/allowExcessArguments flags, and register invocation on action.

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

Root Cause (if applicable)

• Root cause: registerLazyCommand creates a placeholder sub-command with Commander's default --help option enabled. When the user runs openclaw <command> --help, Commander intercepts --help on the placeholder and renders help before the .action() handler fires, so subcommands are never registered and help appears empty.
• Missing detection / guardrail: No test verifying that --help on a lazy placeholder triggers the full command registration path rather than showing empty help.
• Contributing context: The lazy-registration pattern was introduced to speed up CLI startup; the shouldRegisterPrimaryCommandOnly() function correctly skips eager registration for help, but the placeholder itself was still capturing --help.

Regression Test Plan

• Coverage level that should have caught this:
  • Unit test
  • Seam / integration test
  • End-to-end test
• Target test or file: src/cli/program/register-lazy-command.test.ts
• Scenario the test should lock in: A lazy placeholder command with --help does not show empty help; instead help is deferred to the real action handler after lazy registration.
• Why this is the smallest reliable guardrail: The bug is in Commander.js option handling on the placeholder, and a unit test on registerLazyCommand directly asserts helpOption(false) and that no --help option remains on the placeholder — the minimal contract that prevents the regression.

User-visible / Behavior Changes

• openclaw <command> --help now correctly lists available subcommands for all lazy-loaded command groups (config, models, gateway, cron, channels, agents, etc.). Previously showed empty help.

Diagram

Before:
openclaw config --help → Commander intercepts --help on placeholder → shows empty help (no subcommands)

After:
openclaw config --help → placeholder has helpOption(false) → --help not intercepted → action handler fires → subcommands registered → re-parse shows full help with subcommands

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

Repro + Verification

Environment

• OS: macOS (darwin)
• OpenClaw 2026.4.8

Steps

1. Run openclaw config --help
2. Observe: only "Usage: openclaw config [options]" with no subcommands listed
3. After fix: openclaw config --help shows get, set, unset, file, validate subcommands

Expected

All subcommands listed under parent command help.

Actual (before fix)

Empty help — no subcommands shown.

Evidence

• Failing test/log before + passing after
  • New test in register-lazy-command.test.ts asserts placeholder._helpOption === null and placeholder.options.find(opt => opt.long === "--help") === undefined, which would have caught this bug.

Human Verification (required)

• Verified scenarios: Placeholder .helpOption(false) correctly disables help intercept; --help falls through to action handler; subcommands appear in help output.
• Edge cases checked: allowUnknownOption and allowExcessArguments flags still set correctly; register callback still invoked on action.
• What I did not verify: Full CLI integration test with all command groups (covered by existing e2e tests).

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

Risks and Mitigations

• Risk: Commands that intentionally relied on placeholder --help showing only placeholder-level help (no subcommands) will now show full help.
  • Mitigation: This is the desired behavior and matches pre-2026.4.8 behavior. No known use case for wanting empty help.

Changed files

• src/cli/program/register-lazy-command.test.ts (added, +103/-0)
• src/cli/program/register-lazy-command.ts (modified, +1/-0)