RFC 0017: Command Catalog

[giodl73-repo]

Summary

Proposes a read-only Command Catalog through openclaw commands list and openclaw commands inspect. OpenClaw command facts currently live across static CLI descriptors, command routes, routed operations, the runtime Commander tree, opt-in plugin CLI descriptors, and paired-node observations. The RFC joins those existing owners into one machine-readable view without adding a dispatcher, policy engine, runtime hook, or alternate execution path.

This is intended to answer operator and compliance inventory questions consistently while also giving later documentation, diagnostics, scoped prompt, drift, and search consumers one normalized input.

Key boundaries

• The contributing registry or runtime remains the owner of command names, semantics, registration lifetime, and execution behavior.
• Each result is a source-scoped observation snapshot. Record identity supports comparison but is not a capability token or proof that an implementation remains registered.
• Reports which sources were collected; a missing or failed source is unknown, not evidence that its commands were removed.
• Preserves missing effects, risk, and confirmation as unknown.
• Adds only two optional owner concepts: effectProfile and commandExposure; plugin descriptors may also use existing-style hidden metadata.
• Keeps plugin collection explicit because enabled trusted modules are imported/executed even in restricted metadata-registration mode.
• Treats live node handshake data as bounded identifiers only, using existing pairing-aware diagnostics authentication.
• Keeps Gateway commands.list as the separate agent/provider-scoped command view.
• Makes prompt and visibility projections explicit views that neither grant nor revoke execution authority.
• Defines a versioned JSON stability boundary without freezing command counts.

Implementation drafts

• Foundation #100960
• Live node inventory #104158
• Scoped prompt projection #104159
• Generated reference #104160

Fork PRs #30-#32 are explicitly labeled internal consumer prototypes, not required public surfaces. Historical broader catalog drafts remain alternatives, not normative specification.

Review requested

1. Is openclaw commands the right operator/developer surface alongside the narrower Gateway commands.list RPC?
2. Are source-scoped snapshots, unknown preservation, and owner-bound registration lifetimes the right evidence boundary?
3. Should trusted plugin descriptor collection remain explicit until lifecycle-owned metadata can avoid repeated module execution?

The required maintainer-discussion thread still needs to be linked before acceptance.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 9, 2026, 1:25 AM ET / 05:25 UTC (Revision 71).

ClawSweeper review

What this changes

Adds a draft RFC for a read-only command inventory that combines existing command metadata while preserving source ownership, collection scope, and unknown effects.

Merge readiness

⛔ Blocked before merge - 3 items remain

The proposal remains distinct and absent from main; its four upstream implementation PRs are still open. The earlier discussion requirement remains unresolved, and the repository requires explicit acceptance before merging a draft RFC.

Priority: P3
Reviewed head: a6cdc070bed0819586aebd4b0d4d7d56268ccec1
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The proposal is coherent and narrowly scoped, but supplied evidence does not satisfy the external-PR proof requirement.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The supplied evidence covers whitespace validation but not the rendered RFC after the change; the literal docs/ exemption does not cover rfcs/. A rendered-document screenshot or observation would address this document-only proof gap without requiring execution of the proposed catalog. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The supplied evidence covers whitespace validation but not the rendered RFC after the change; the literal docs/ exemption does not cover rfcs/. A rendered-document screenshot or observation would address this document-only proof gap without requiring execution of the proposed catalog. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	8 items	Verified patch scope: The pinned base-to-head delta adds one 315-line RFC and no executable files; git diff --check passed and the final checkout status was clean. RFC acceptance contract: README requires a maintainer-discussion thread, prohibits merging draft RFCs, and requires accepted status plus an implementation issue after acceptance. Review continuity: The retained earlier review requested the discussion link. The current RFC and the author's September 9 comment explicitly acknowledge that it remains pending. This remains an acceptance prerequisite rather than a runtime defect. The earlier reviewed commit was unavailable locally, so no unchanged-code attribution was inferred.
Findings	None	None.
Security	None	None.

How this fits together

This repository stores OpenClaw design proposals rather than executable product code. The proposed catalog would combine CLI, plugin, and selected node metadata into operator-facing inventory and inspection output.

flowchart LR
  A[CLI metadata] --> D[Proposed command catalog]
  B[Opt-in plugin metadata] --> D
  C[Selected node observation] --> D
  D --> E[Preserve provenance and unknowns]
  E --> F[List and inspect output]
  E --> G[Future documentation consumers]

Loading

Decision needed

Question	Recommendation
Should OpenClaw accept the proposed operator-facing commands catalog, keeping Gateway discovery separate and plugin collection explicitly opt-in?	Resolve the contract in maintainer discussion: Keep the RFC open while the required discussion confirms or narrows the initial inventory surface and records acceptance decisions.

Why: The new CLI and metadata contract require product acceptance; neither implementation drafts nor the localization reference establish that acceptance.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The supplied evidence covers whitespace validation but not the rendered RFC after the change; the literal docs/ exemption does not cover rfcs/. A rendered-document screenshot or observation would address this document-only proof gap without requiring execution of the proposed catalog. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Link the maintainer-discussion thread and obtain explicit acceptance; only then set status to accepted and populate the implementation issue before merging.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Proposal scope	1 RFC added; 315 documentation lines; 0 runtime files	Merging this patch records a design decision without deploying the proposed command behavior.

Technical review

Best possible solution:

Agree on a bounded operator inventory contract that preserves existing registry authority, then record acceptance and track implementation through the repository's RFC lifecycle.

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

Not applicable: the patch proposes a new inventory capability and contains no executable bug fix.

Is this the best way to solve the issue?

Unclear pending product acceptance: joining source-owned metadata is coherent, and the proposal explicitly distinguishes its operator view from existing Gateway discovery.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label justifications:

• P3: This is a design proposal without a demonstrated urgent product failure.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The supplied evidence covers whitespace validation but not the rendered RFC after the change; the literal docs/ exemption does not cover rfcs/. A rendered-document screenshot or observation would address this document-only proof gap without requiring execution of the proposed catalog. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Verified patch scope: The pinned base-to-head delta adds one 315-line RFC and no executable files; git diff --check passed and the final checkout status was clean. (rfcs/0017-command-catalog.md:1, a6cdc070bed0)
• RFC acceptance contract: README requires a maintainer-discussion thread, prohibits merging draft RFCs, and requires accepted status plus an implementation issue after acceptance. (README.md:80, 967d9aac7472)
• Review continuity: The retained earlier review requested the discussion link. The current RFC and the author's September 9 comment explicitly acknowledge that it remains pending. This remains an acceptance prerequisite rather than a runtime defect. The earlier reviewed commit was unavailable locally, so no unchanged-code attribution was inferred. (rfcs/0017-command-catalog.md:314, a6cdc070bed0)
• Current-main necessity: Main lacks the proposed RFC. Its localization RFC refers to the command catalog as proposed future ownership, which establishes an adjacent consumer rather than an implementation. The repository-wide PR listing revealed no merged command-catalog replacement; the releases endpoint returned no releases. (rfcs/0024-localization-runtime-and-coverage.md:814, 967d9aac7472)
• Upstream implementation remains open: GitHub confirms feat: add commands list and inspect inventory openclaw#100960 is open and unmerged. Separate reads also confirmed that feat(cli): collect live paired-node commands openclaw#104158, feat(agents): add scoped command prompt projection openclaw#104159, and docs(cli): generate and guard command reference openclaw#104160 remain open and unmerged. These are implementation proposals in another repository, not merged replacements for this RFC.
• Authority and compatibility scope: The RFC explicitly preserves existing execution authority, distinguishes observations from capabilities, and retains unknown semantics. Its optional plugin metadata and JSON contract are proposals; this patch does not change a running plugin API, authorization check, storage format, or dependency. (rfcs/0017-command-catalog.md:200, a6cdc070bed0)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)
• giodl73-repo: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

• Add a screenshot or recorded observation of the rendered RFC, redacting private information; updating the PR body should trigger review, or a maintainer can request @clawsweeper re-review.
• Link the maintainer discussion and record the resulting scope decision before acceptance.

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

• 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.

History

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

• reviewed 2026-08-09T10:59:36.055Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T11:26:22.998Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T12:42:01.086Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T14:50:58.766Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T19:48:29.856Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T22:01:16.218Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-09T23:10:35.338Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread
• reviewed 2026-08-12T01:54:40.055Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer-discussion thread

[giodl73-repo]

@clawsweeper re-review

[clawsweeper]

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

[giodl73-repo]

Refreshed onto current main at a6cdc07. The RFC remains a one-file documentation-only proposal and git diff --check passes. The required maintainer-discussion link remains the explicit acceptance-process follow-up; this refresh does not claim acceptance. @clawsweeper re-review