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 August 11, 2026, 9:54 PM ET / August 12, 2026, 01:54 UTC.

ClawSweeper review

What this changes

Adds a draft RFC for openclaw commands list and openclaw commands inspect, a read-only inventory joining existing command metadata sources.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep open for maintainer design review: this is a new cross-cutting CLI and metadata contract, current main does not implement it, and the required discussion thread is still not linked.

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

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is detailed and bounded, but acceptance confidence is limited until the required maintainer discussion resolves its public-contract and trust-boundary choices.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only an RFC; real behavior proof belongs with any implementation PR, not the design document.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only an RFC; real behavior proof belongs with any implementation PR, not the design document.
Evidence reviewed	5 items	RFC source and proposed surface: The submitted RFC defines a new commands CLI group and a versioned JSON stability boundary, so it is a new public product contract rather than a documentation correction. RFC lifecycle requirement: Current repository guidance requires every new RFC to have a maintainer-discussion thread and to remain unmerged while its status is draft. Outstanding discussion prerequisite: The RFC itself says the required maintainer-discussion thread must be linked before acceptance; no thread URL is present in the document.
Findings	1 actionable finding	[P3] Link the required maintainer-discussion thread
Security	None	None.

How this fits together

The proposed catalog collects static CLI, runtime, opt-in plugin, and paired-node command observations into an operator-facing inventory. It leaves command registration, authorization, and execution with their existing owners.

flowchart LR
A[Static CLI and routes] --> E[Read-only command catalog]
B[Runtime registrations] --> E
C[Opt-in plugin descriptors] --> E
D[Paired node observations] --> E
E --> F[Commands list and inspect]
F --> G[Operator tools and documentation]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt a core commands inventory with a versioned JSON contract while keeping Gateway discovery separate and plugin metadata collection explicitly opt-in?	Discuss and sponsor the narrow contract: Link the required maintainer discussion and approve or amend the CLI, Gateway, plugin-execution, and node-authentication boundaries before acceptance.

Why: This choice creates new CLI, compatibility, and security-boundary commitments that source inspection cannot resolve without maintainer product intent.

Before merge

• Add real behavior proof - Not applicable: This PR changes only an RFC; real behavior proof belongs with any implementation PR, not the design document.
• Link the required maintainer-discussion thread (P3) - The repository RFC lifecycle requires a maintainer-discussion thread before acceptance, and the RFC still records that prerequisite without linking it. Add the discussion URL and its resulting direction before this draft can merge.
• Resolve merge risk (P1) - Accepting this RFC would reserve a core CLI root and establish a versioned external inventory contract without maintainer agreement on its compatibility policy.
• Resolve merge risk (P1) - The proposed plugin and paired-node collection paths cross execution and authentication boundaries; their documented guardrails need explicit design approval before implementation.
• Complete next step (P2) - A linked maintainer discussion and explicit product decisions are required before any implementation or acceptance action.

Findings

• [P3] Link the required maintainer-discussion thread — rfcs/0017-command-catalog.md:314-315

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC scope	1 RFC file added, 315 lines	The branch is document-only, so review should focus on the proposed public contract and RFC acceptance prerequisites.

Merge-risk options

Maintainer options:

1. Resolve the contract in maintainer discussion (recommended)
   Link the required discussion and record decisions on CLI compatibility, Gateway separation, plugin execution, and paired-node authentication before merging.
2. Accept the proposed boundaries
   Maintainership can explicitly accept the versioned CLI contract and its documented plugin and node guardrails as the basis for later implementation.
3. Pause the RFC
   Keep the proposal unmerged if no owner is ready to make the public-contract and trust-boundary decisions.

Technical review

Best possible solution:

Record a maintainer decision on the operator catalog boundary, then link the required discussion and narrow the first implementation slice to an upgrade-safe, explicitly opt-in inventory contract.

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

Not applicable: this PR is an RFC, and its claimed runtime behavior belongs to the separately linked implementation work.

Is this the best way to solve the issue?

Unclear: the RFC is a coherent narrow design, but its public CLI and trust-boundary choices require the missing maintainer discussion before it can be accepted.

Full review comments:

• [P3] Link the required maintainer-discussion thread — rfcs/0017-command-catalog.md:314-315
  The repository RFC lifecycle requires a maintainer-discussion thread before acceptance, and the RFC still records that prerequisite without linking it. Add the discussion URL and its resulting direction before this draft can merge.
  Confidence: 0.99

Overall correctness: patch is correct
Overall confidence: 0.92

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P3: This is a non-urgent design proposal requiring maintainer direction before implementation.
• merge-risk: 🚨 compatibility: The RFC proposes a reserved CLI root and a stable versioned JSON interface that later implementations must preserve.
• merge-risk: 🚨 security-boundary: The proposal includes opt-in execution of trusted plugin modules and paired-node authenticated observations.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. A single owner-preserving command inventory could unlock consistent operator, documentation, diagnostics, and localization views without adding another dispatcher.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This PR changes only an RFC; real behavior proof belongs with any implementation PR, not the design document.

Evidence

What I checked:

• RFC source and proposed surface: The submitted RFC defines a new commands CLI group and a versioned JSON stability boundary, so it is a new public product contract rather than a documentation correction. (rfcs/0017-command-catalog.md:98, de477188c9e6)
• RFC lifecycle requirement: Current repository guidance requires every new RFC to have a maintainer-discussion thread and to remain unmerged while its status is draft. (README.md:80, af708f0ddb6f)
• Outstanding discussion prerequisite: The RFC itself says the required maintainer-discussion thread must be linked before acceptance; no thread URL is present in the document. (rfcs/0017-command-catalog.md:314, de477188c9e6)
• Current-main dependency: Current main calls the proposed RFC 0017 catalog the preferred owner for command identity and descriptions, confirming that the catalog is future architecture rather than an already-landed implementation. (rfcs/0024-localization-runtime-and-coverage.md:814, faf2a3a5b1ac)
• RFC-process provenance: The current RFC lifecycle was introduced by the repository-history commit titled docs: update rfc process. (README.md:78, e366ea9825a4)

Likely related people:

• kevinlin-openai: Authored the repository-history change that established the current RFC lifecycle and discussion requirement. (role: RFC lifecycle author; confidence: medium; commits: e366ea9825a4; files: README.md, rfcs/0000-template.md)
• giodl73-repo: Authored the submitted RFC and current-main RFC 0024, which identifies this catalog as the preferred metadata owner. (role: adjacent RFC author; confidence: high; commits: de477188c9e6, faf2a3a5b1ac; files: rfcs/0017-command-catalog.md, rfcs/0024-localization-runtime-and-coverage.md)

Rank-up moves

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

• Link the maintainer-discussion thread and record its decisions on the CLI, Gateway, plugin, and node boundaries.

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 (69 earlier review cycles; latest 8 shown)

• reviewed 2026-08-08T22:12:51.237Z sha de47718 :: needs real behavior proof before merge. :: [P3] Link the required maintainer discussion
• 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

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