RFC 0017: Command Catalog

[giodl73-repo]

Why this exists

Compliance and enterprise operations need a dependable answer to a basic question: what command surfaces can this OpenClaw deployment expose? Today that information is spread across core CLI descriptors, routed commands, the live Commander tree, plugins, and paired nodes.

A shared, read-only inventory would let operators and automation enumerate those surfaces and consistently report provenance, read versus mutation effects, confirmation requirements, and elevated risk where the owning registry knows them. It would not execute commands or become a policy engine.

Existing issues show demand for parts of this capability, though none is an exact duplicate:

• #52919: runtime command discovery for remote clients
• #77943: inconsistent machine-readable list output
• #50011: node policy names that do not match known commands
• #77730: configured plugin node commands diverging from runtime advertisement

Prompt-related requests provide evidence for one future consumer: #14619 covers duplicated tool-list prompt text, #14785 covers tool-schema token overhead, and #41417 requests assembled-prompt inspection. The same inventory could later support generated docs, compatibility fixtures, diagnostics, policy checks, and scoped operator/model views. The initial CLI does not claim prompt-token savings.

What this RFC proposes

A read-only Command Catalog built from command information OpenClaw already owns.

Option A: commands list and inspect (recommended)

openclaw commands list
openclaw commands inspect <command-path...>

This option follows noun-based groups such as plugins and skills, stays command-owned, and excludes ownerless tool adapters and aggregate audit/test/summary reports.

• Upstream draft
• PR1: commands list
• PR2: commands inspect
• Optional PR3: scoped command prompt projection

PR3 is a separately reviewed follow-up on the fork. It is not included in the initial upstream draft.

Option B: broader catalog

openclaw catalog list
openclaw catalog audit
openclaw catalog test-matrix
openclaw catalog summary

This remains available as a concrete alternative with command-like tool adapters and operational lenses.

• Catalog foundation
• Dynamic/operator lenses

Existing Gateway surface

Gateway commands.list remains the agent-facing chat/native/skill/plugin inventory. Option A adds an operator/developer CLI inventory; it does not replace or change that RPC. Future convergence is a maintainer decision.

ClawSweeper follow-up completed

The linked implementation now:

• fails closed on plugin loader exceptions and error-level plugin diagnostics;
• emits no valid-looking JSON when a requested plugin scan is incomplete;
• documents effectProfile, commandExposure, and hidden, including defaults and an external-plugin example; and
• includes latest-head terminal proof for core-only, plugin-enabled, and controlled plugin-failure paths.

Proof summary from 90a7b1ca2b:

core:    descriptors=61 runtime=26 plugins=0
plugins: descriptors=61 runtime=26 plugins=3
failure: exit=1 stdoutBytes=0 expectedError=true

Lifecycle boundary

The RFC remains draft. The required OpenClaw maintainer-discussion thread still must be created and linked before acceptance. Namespace, stable schema, plugin metadata, and Gateway convergence are maintainer decisions rather than contributor-declared contracts.

Feedback requested

• Is the recommended openclaw commands boundary clear and useful?
• How should it eventually relate to Gateway commands.list and live paired-node command declarations?
• Which JSON fields should be stable beyond schema version, identity, and provenance?

[clawsweeper]

Codex review: found issues before merge. Reviewed July 11, 2026, 5:20 PM ET / 21:20 UTC.

Summary
Adds a 414-line draft RFC defining a read-only command catalog, recommending openclaw commands list/inspect, and specifying cross-registry metadata, plugin, node, and future documentation boundaries.

Reproducibility: not applicable. This PR proposes a new architecture and CLI contract rather than reporting broken existing behavior.

Review metrics: 2 noteworthy metrics.

• RFC scope: 1 file, 414 lines added. A documentation-only diff nevertheless defines a cross-registry interface with substantial downstream compatibility implications.
• Review continuity: 1 prior finding still open. The latest head only renumbers the RFC, so the required discussion-link finding remains unchanged.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

• [P2] Create and link the required maintainer-discussion thread before acceptance.

Risk before merge

• [P1] Merging while the document remains draft and unlinked from maintainer discussion would bypass the repository's acceptance lifecycle.
• [P1] Acceptance would create a new CLI namespace and machine-readable schema that plugins, nodes, documentation generators, and downstream automation may treat as stable.
• [P1] The permanent relationship between this inventory and Gateway commands.list remains unresolved, creating a risk of overlapping discovery contracts.

Maintainer options:

1. Complete lifecycle and contract decisions (recommended)
   Link the maintainer discussion and amend the RFC with the accepted namespace, stable fields, plugin metadata rules, and Gateway relationship before merge.
2. Keep it as draft exploration
   Leave the clean PR open and unmerged while maintainers compare the narrow and broad catalog directions.
3. Pause the core proposal
   Close or defer the RFC if maintainers do not want to establish another public command-discovery contract.

Next step before merge

• [P2] Maintainers need to sponsor the required discussion and choose the durable CLI and schema contract; no automated document repair can make those product decisions.

Maintainer decision needed

• Question: Should OpenClaw adopt the narrow openclaw commands list/inspect catalog, and which schema fields and registry relationships should become stable in v1?
• Rationale: The RFC deliberately leaves durable public-contract choices unresolved, and repository policy requires maintainer discussion before acceptance.
• Likely owner: kevinslin — They authored the active RFC acceptance process and are the strongest repository-history owner for the required lifecycle decision.
• Options:
  • Sponsor narrow catalog (recommended): Create the discussion, endorse Option A, and define only the minimum stable v1 fields and registry ownership rules.
  • Adopt broader catalog: Choose Option B and explicitly accept the larger operational and compatibility surface.
  • Decline a unified catalog: Keep command discovery split across existing CLI, Gateway, plugin, and node surfaces.

Security
Cleared: The Markdown-only diff adds no executable code, dependencies, workflow permissions, secrets handling, or supply-chain surface.

Review findings

• [P3] Link the required maintainer discussion before acceptance — rfcs/0017-command-catalog.md:375-376

Review details

Best possible solution:

Keep the RFC open in draft, create and link the required maintainer discussion, then record the sponsored v1 namespace, stable fields, plugin metadata rules, and Gateway boundary before acceptance.

Do we have a high-confidence way to reproduce the issue?

Not applicable; this PR proposes a new architecture and CLI contract rather than reporting broken existing behavior.

Is this the best way to solve the issue?

Unclear pending maintainer direction; the narrow command-owned inventory is the safer option, but its stable fields and relationship to existing discovery surfaces require explicit sponsorship.

Full review comments:

• [P3] Link the required maintainer discussion before acceptance — rfcs/0017-command-catalog.md:375-376
  The repository lifecycle requires every new RFC to have a maintainer-discussion thread, and this draft still says that thread has not been created or linked. Add the discussion URL before changing the RFC to accepted or merging it; this remains the prior review finding.
  Confidence: 0.99

Overall correctness: patch is correct
Overall confidence: 0.9

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning high; reviewed against a8e0ba2701d6.

Label changes

Label changes:

• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• remove rating: 🦞 diamond lobster: Current PR rating is rating: 🐚 platinum hermit, so this older rating label is no longer current.

Label justifications:

• P3: This is a non-urgent draft feature proposal rather than a current production regression.
• merge-risk: 🚨 compatibility: Acceptance would establish a new CLI namespace and machine-readable metadata contract for plugins, nodes, and downstream consumers.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A unified provenance-aware command inventory could unlock compliance checks, diagnostics, generated references, compatibility fixtures, and safer remote command discovery.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes after-fix terminal results for core-only, plugin-enabled, and fail-closed plugin-error paths that directly exercise the linked implementation behavior.
• proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes after-fix terminal results for core-only, plugin-enabled, and fail-closed plugin-error paths that directly exercise the linked implementation behavior.

Evidence reviewed

What I checked:

• RFC lifecycle requires discussion: The target repository says every new RFC needs a maintainer-discussion thread and draft RFCs should not merge until accepted. (README.md:52, e366ea9825a4)
• Required discussion is still absent: The current RFC explicitly says the required maintainer-discussion thread must still be created and linked before acceptance. (rfcs/0017-command-catalog.md:375, 66eb59c98d17)
• Prior finding remains unchanged: Since the last reviewed head, the branch only renamed the RFC from 0016 to 0017 and updated last_updated; the missing-discussion finding was not addressed. (rfcs/0017-command-catalog.md:1, 66eb59c98d17)
• Real implementation proof supplied: The PR body reports latest-head terminal results for core-only, plugin-enabled, and controlled plugin-loader failure paths, including fail-closed output behavior. (rfcs/0017-command-catalog.md:145, 66eb59c98d17)
• Working tree remained clean: Read-only inspection left the target checkout unchanged. (a8e0ba2701d6)

Likely related people:

• kevinslin: Authored the active RFC process and template lifecycle requirements, including the maintainer-discussion gate. (role: RFC lifecycle author; confidence: high; commits: e366ea9825a4, f4fdf38f4717; files: README.md, rfcs/0000-template.md)
• RomneyDa: Recently refined the repository layout and RFC template through merged repository history. (role: recent RFC process contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)
• giodl73-repo: Beyond proposing this branch, they have prior merged current-main RFC history through the feed telemetry addendum and substantial recent work in this repository. (role: recent RFC contributor; confidence: medium; commits: a8844eb53a2b; files: rfcs/0009-hosted-feeds-for-plugins-and-skills.md)

What the crustacean ranks mean

• 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
• 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
• 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
• 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
• 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
• 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
• 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

Review history (20 earlier review cycles; latest 8 shown)

• reviewed 2026-07-10T22:45:41.278Z sha 061c41d :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-10T22:51:42.105Z sha 061c41d :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-10T23:12:27.890Z sha e02dfd5 :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-10T23:46:14.408Z sha 87e401f :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-10T23:57:37.530Z sha c5ef1d7 :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-11T00:28:24.176Z sha 767108a :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-11T01:21:20.325Z sha 67d5851 :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance
• reviewed 2026-07-11T06:05:25.454Z sha ed9e470 :: found issues before merge. :: [P3] Link the required maintainer discussion before acceptance

[giodl73-repo]

@clawsweeper re-review