RFC 0018: Readiness Conditions and Providers

[giodl73-repo]

Decision Requested

Should OpenClaw add an opt-in, structured, subject-aware readiness contract around its existing Gateway checker?

This RFC covers Readiness Conditions and Providers. Standard Hosting Profiles remain a separate product/support decision in RFC 0023.

Why

OpenClaw already exposes /ready and /readyz, but their evaluator is purpose-built around fixed Gateway observations. Operators cannot select which known runtime facts their deployment requires, plugins cannot contribute bounded observations, and a single result cannot identify the different runtime subjects those observations describe.

Proposed V1

Each condition has stable type, subjectRef, status, requirement, reason, and message fields, with optional bounded related subjects. Required False or Unknown conditions fail readiness; advisory conditions remain visible. Activated /ready, /readyz, Gateway health/status projections, and openclaw ready consume the same canonical result. HTTP /health and /healthz remain shallow liveness.

The result declares its producer and a versioned reconciled subject package once. IDs renew at the lifecycle boundary owned by each subject: optional host workload, process, Gateway serving lifecycle, config, plugin, node, or another resource. A generation revises the same object. Operators can therefore diff (subjectRef, type) and distinguish a condition transition from replacement or revision.

OpenClaw retains no history. Hosts and telemetry systems may store and diff the bounded result. This gives Docker, Kubernetes, OCC, and other operators enough attribution to explain a readiness transition without turning readiness into a resource store or control plane.

Operators select reusable criteria through gateway.readiness. Registering a criterion never selects it. Plugin providers are namespaced, enumerable, observational, advisory by default, and receive a subject collector. Core owns deadlines, cancellation, coalescing, caching, output bounds, redaction, reconciliation, deterministic ordering, and fail-closed projection.

This PR includes the normative Readiness v1 and Readiness Subjects v1 sidecars. Its non-normative platform comparison maps the design to Kubernetes, Docker, systemd, ASP.NET Core, Spring Boot, and OpenTelemetry.

Proposed Condition Catalog

The initial catalog makes the concrete runtime coverage visible:

Area	Conditions	How they participate
Gateway serving baseline	GatewayStartupComplete, GatewayAcceptingWork, ChannelRuntimeReady, ConfigLoaded	Universal required conditions that modernize existing Gateway observations.
Gateway diagnostics	ChannelRuntimeSuppressed, EventLoopHealthy, PluginsLoaded	Visible advisories; the selectable conditions may be promoted to required.
Runtime activation	WorkspaceWritable, ConfigCurrent, ModelRouteReady, SecretsReady	Selectable checks for the active workspace, config, model/auth route, and secret owners.
Agent execution	ContextEngineReady, ToolCatalogReady, McpRuntimeReady, SandboxReady, HarnessReady	Selectable observations from the OpenClaw owners of each execution capability.
State and background services	SessionStorageReady, StateReady, DeliveryRuntimeReady, SchedulerReady	Selectable storage, state, delivery, and scheduler lifecycle observations.
Plugin dependencies	plugin.<plugin-id>.<criterion-id>	Activated plugins may register bounded, namespaced observations; they remain advisory unless selected as required.

ReadinessEvaluationComplete and remote GatewayResponding guard failures keep incomplete evaluation or an unreachable Gateway explicit. Merely implementing or registering a condition never selects it. Outside the universal baseline, only gateway.readiness configuration or a separately accepted Hosting Profile changes what must pass.

Compatibility Boundary

• Without gateway.readiness or another accepted activation contract, /ready and /readyz use the legacy checker.
• Presence of gateway.readiness, including {}, activates bounded canonical evaluation.
• Selected but unobserved facts remain explicit Unknown conditions.
• A separately accepted Standard Hosting Profile may activate the same evaluator by selecting a named condition set.

Implementation Stack

The complete upstream implementation for RFC 0018 is:

1. PR 104018 adds the readiness framework, providers, canonical projections, CLI, and subject identity at exact head 2f131c6e220.
2. PR 113421 adds reusable OpenClaw-owned conditions for core runtime owners at exact head c1d7f394f86. It depends on PR 104018.

Both PRs are profile-free and independently adoptable. Owner criteria observe existing snapshots. Readiness does not make model calls, acquire credentials, connect MCP servers, start sandboxes or harnesses, open databases, or start schedulers. Active filesystem checks and provider calls are bounded.

Operator Facilities

• Validated follow-up work demonstrates openclaw ready --watch with bounded semantic transitions, recovery, and subject-lifetime replacement without changing one-shot behavior.
• Validated follow-up work demonstrates an inert readiness catalog and openclaw ready criteria list|inspect without invoking providers.
• Validated follow-up work demonstrates openclaw ready --wait [duration] as a bounded startup gate over the canonical ready RPC.
• Validated follow-up work demonstrates human explanations for the identity, generation, parent, and lifetime of subjects behind non-passing conditions.
• Doctor, telemetry, support bundles, and updates consume readiness evidence through their existing owners.

Package Proof

Exact-head package-installed Docker proof passes over profile head 18c42a7f26a and release-artifact head 123bae7b876. It exercises RFC 0018 readiness surfaces, stable repeated polls, fail-closed transitions, and host-stable/process-and-Gateway-renewing container restart semantics using an immutable no-push package/image artifact.

Maintainer Questions

1. Is explicit activation the right upgrade boundary?
2. Is required/advisory the right modernization of the existing evaluator?
3. Is the producer/subject identity package the right attribution model?
4. Is activation-scoped plugin registration the right extension boundary?

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed July 27, 2026, 7:04 PM ET / 23:04 UTC.

ClawSweeper review

What this changes

The branch adds RFC 0018 and three supporting specifications for an opt-in Gateway readiness model with structured conditions, runtime subject identity, selectable criteria, and bounded plugin observations.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep this PR open: it is a distinct, documentation-only RFC, but it still needs the repository-required maintainer discussion and an explicit product decision on the proposed public readiness and plugin-provider contract.

Priority: P2
Reviewed head: fae4ea1636c1e0ad08f6bd234cb7e43bab0c984a
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The documentation is substantial and scoped, but the required maintainer decision record is still missing.
Proof confidence	🌊 off-meta tidepool	Not applicable: This branch changes only RFC Markdown files, so external runtime proof is not a merge gate; the linked package-installed run remains useful design context rather than proof required for this documentation PR.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This branch changes only RFC Markdown files, so external runtime proof is not a merge gate; the linked package-installed run remains useful design context rather than proof required for this documentation PR.
Evidence reviewed	4 items	RFC lifecycle requirement: The repository RFC process states that each new RFC needs a discussion thread, and acceptance requires an implementation plan plus maintainer approval. Unrecorded contract decision: The added RFC remains marked draft while proposing new configuration, endpoint, CLI, and plugin-provider contracts; the supplied PR body asks four maintainer questions but provides no maintainer-discussion decision record. Separate related proposal: The linked Standard Hosting Profiles RFC explicitly treats readiness as its prerequisite and covers a separate profile catalog, so it is adjacent work rather than a replacement for this readiness-contract RFC.
Findings	1 actionable finding	[P2] Record the maintainer-contract decision
Security	None	None.

How this fits together

The proposal sits between Gateway runtime facts and the readiness signals consumed by operators. It would combine core and activated-plugin observations into one canonical result that feeds /ready, /readyz, status surfaces, and the openclaw ready CLI.

flowchart LR
  A[Gateway runtime facts] --> D[Readiness evaluation]
  B[Operator readiness settings] --> D
  C[Activated plugin observations] --> D
  D --> E[Canonical readiness result]
  E --> F[Ready endpoints]
  E --> G[Gateway status]
  E --> H[CLI readiness output]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt the proposed opt-in readiness contract, including the legacy fallback and activation-scoped plugin-provider boundary, as the direction for future implementation?	Accept the opt-in readiness direction: Approve the legacy-preserving activation boundary and use the RFC as the contract for an implementation plan.

Why: The PR defines new configuration and extension semantics rather than documenting an already accepted contract, so a contributor review cannot determine the intended long-term public API.

Before merge

• Add real behavior proof - Not applicable: This branch changes only RFC Markdown files, so external runtime proof is not a merge gate; the linked package-installed run remains useful design context rather than proof required for this documentation PR.
• Record the maintainer-contract decision (P2) - The repository RFC lifecycle requires a discussion thread for every new RFC, but this draft still has no linked record resolving its requested decisions about activation, compatibility, subject identity, and plugin providers. Add the maintainer-discussion link and summarize the resulting contract decision before merge.
• Resolve merge risk (P1) - Merging without a recorded maintainer decision would establish an RFC-level compatibility commitment for gateway.readiness, readiness projections, and plugin provider behavior before the contract owners approve its upgrade boundary.
• Complete next step (P2) - A maintainer must choose the readiness API and compatibility direction; this is not a mechanical repair candidate.

Findings

• [P2] Record the maintainer-contract decision — rfcs/0018-readiness-conditions-and-providers.md:1-8

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC surface	4 added Markdown files; 1,701 additions; 0 deletions	The branch establishes one broad readiness contract plus three implementer-facing sidecars, so agreement on scope matters before merging.

Merge-risk options

Maintainer options:

1. Record the contract decision before merge (recommended)
   Add the required maintainer-discussion link and the resulting decision on activation, legacy compatibility, and plugin-provider scope before treating this RFC as accepted.
2. Accept the compatibility commitment explicitly
   Maintainers may merge the RFC if they intentionally approve the stated opt-in boundary and are comfortable making it the basis for future public configuration and plugin behavior.
3. Pause the RFC direction
   Leave the proposal as draft or close it if the readiness contract is not a current product priority.

Technical review

Best possible solution:

Open and link the required maintainer discussion, decide whether the opt-in legacy-preserving readiness contract is acceptable, then revise the RFC to record the chosen boundary before merge.

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

Not applicable: this PR proposes a future readiness contract and does not report a currently failing behavior to reproduce.

Is this the best way to solve the issue?

No: the proposed opt-in boundary may be a maintainable approach, but it is not ready to merge until a maintainer discussion records whether this public configuration and plugin contract is wanted.

Full review comments:

• [P2] Record the maintainer-contract decision — rfcs/0018-readiness-conditions-and-providers.md:1-8
  The repository RFC lifecycle requires a discussion thread for every new RFC, but this draft still has no linked record resolving its requested decisions about activation, compatibility, subject identity, and plugin providers. Add the maintainer-discussion link and summarize the resulting contract decision before merge.
  Confidence: 0.95

Overall correctness: patch is incorrect
Overall confidence: 0.9

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a bounded but significant product and compatibility decision rather than an urgent runtime regression.
• merge-risk: 🚨 compatibility: The RFC proposes new readiness configuration, compatibility fallback, and plugin-provider contract semantics that future implementations would need to preserve.
• rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🌊 off-meta tidepool and patch quality is 🦐 gold shrimp.
• status: ⏳ waiting on author: ClawSweeper has contributor-facing work open and is waiting for author action. Not applicable: This branch changes only RFC Markdown files, so external runtime proof is not a merge gate; the linked package-installed run remains useful design context rather than proof required for this documentation PR.

Evidence

What I checked:

• RFC lifecycle requirement: The repository RFC process states that each new RFC needs a discussion thread, and acceptance requires an implementation plan plus maintainer approval. (README.md:281, 593e6e46632b)
• Unrecorded contract decision: The added RFC remains marked draft while proposing new configuration, endpoint, CLI, and plugin-provider contracts; the supplied PR body asks four maintainer questions but provides no maintainer-discussion decision record. (rfcs/0018-readiness-conditions-and-providers.md:1, fae4ea1636c1)
• Separate related proposal: The linked Standard Hosting Profiles RFC explicitly treats readiness as its prerequisite and covers a separate profile catalog, so it is adjacent work rather than a replacement for this readiness-contract RFC. (fae4ea1636c1)
• Related RFC history: The proposal author also has prior merged RFC history in this repository through the hosted-feeds RFC merge, making them the strongest available routing contact for the readiness design context. (89cf322325b0)

Likely related people:

• giodl73-repo: Authored this readiness proposal and previously contributed the merged hosted-feeds RFC, providing the clearest available history connection to this RFC-design surface. (role: related RFC contributor; confidence: medium; commits: 89cf322325b0, fae4ea1636c1; files: rfcs/0018-readiness-conditions-and-providers.md, rfcs/0018/readiness-v1-spec.md)

Rank-up moves

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

• Link the required maintainer-discussion thread and record its decisions on the proposed public contract.

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-07-26T23:53:45.760Z sha 24dcd76 :: needs real behavior proof before merge. :: [P2] Record the required maintainer-contract decision
• reviewed 2026-07-27T00:33:21.466Z sha 24dcd76 :: needs real behavior proof before merge. :: [P2] Record the maintainer-contract decision
• reviewed 2026-07-27T07:37:09.171Z sha 6e50eb4 :: needs real behavior proof before merge. :: [P2] Record the maintainer-contract decision
• reviewed 2026-07-27T13:03:45.986Z sha 5728ffe :: needs real behavior proof before merge. :: [P2] Add the required maintainer-discussion record
• reviewed 2026-07-27T13:11:08.374Z sha 5728ffe :: needs real behavior proof before merge. :: [P2] Record the maintainer-contract decision
• reviewed 2026-07-27T22:08:25.965Z sha 5728ffe :: needs real behavior proof before merge. :: [P2] Record the required maintainer-contract decision
• reviewed 2026-07-27T22:13:51.908Z sha 5728ffe :: needs real behavior proof before merge. :: [P2] Record the required maintainer discussion
• reviewed 2026-07-27T22:38:28.012Z sha fae4ea1 :: needs real behavior proof before merge. :: [P2] Record the required maintainer discussion

[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: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Failed
• Detail: The exact review did not produce a publishable artifact. The durable queue will retry it.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30167416617
• Updated: 2026-07-25T17:20:53.044Z

[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: when the review finishes, ClawSweeper will create the durable review comment if needed or update the existing comment in place.

Re-review progress:

• State: Review in progress
• Detail: The exact-review queue leased this run; Codex is reviewing the item.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/30168884814
• Updated: 2026-07-25T18:04:34.659Z