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.

Health/status consumers can derive one selected-condition state without changing or re-evaluating conditions:

• required False -> failing
• required Unknown without a required failure -> unknown
• advisory non-True with all required conditions true -> degraded
• every selected condition true -> passing

Detailed local or authenticated status reuses each condition's stable reason, bounded redacted message, and subject references. Unauthenticated remote output exposes only the aggregate status and readiness boolean. A separate /statusz may expose this diagnostic projection while /healthz remains liveness and /readyz remains traffic admission.

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

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.
• Selected-condition health is a projection outside CanonicalReadinessResult; it does not change readiness contract version 1.
• /health and /healthz remain shallow liveness. /statusz is diagnostic and returns 200 after successful evaluation regardless of condition-health state.

Implementation Stack

1. PR 104018 adds the readiness framework, providers, canonical projections, CLI, and subject identity at exact head abbdfa0876f.
2. PR 113421 adds reusable OpenClaw-owned conditions for core runtime owners at exact head a7e0df75ff2. It depends on PR 104018.
3. PR 121355 derives condition health for Gateway health/status and adds /statusz at exact head 8cb054a8f47. It is stacked after PR 114636 to avoid reopening the rebased implementation/profile stack, but it has no runtime dependency on Hosting Profiles.

The framework and owner 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 the profile and release-artifact stack. 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?
5. Is a derived selected-condition health state plus separate /statusz the right diagnostic projection while /healthz remains shallow?

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 15, 2026, 4:45 AM ET / 08:45 UTC.

ClawSweeper review

What this changes

Adds RFC 0018 and three sidecar specifications for an opt-in, structured Gateway readiness contract with selectable conditions, plugin providers, subject identity, and shared endpoint and CLI projections.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open for maintainer product review: this RFC proposes new configuration, plugin-provider, endpoint, and CLI contracts, and its required maintainer-discussion record is not linked.

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

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is substantial and coherent, but it remains blocked on the required maintainer product-discussion record.
Proof confidence	🌊 off-meta tidepool	Not applicable: All four changed files are documentation, so external real-behavior proof is not required for this RFC-only PR.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: All four changed files are documentation, so external real-behavior proof is not required for this RFC-only PR.
Evidence reviewed	4 items	RFC lifecycle requirement: The checked-out RFC repository requires each new draft RFC to have a maintainer-discussion thread before it proceeds through review. Current-main check: Current main contains neither the proposed RFC 0018 document nor its readiness sidecars, so the exact documentation change is not already implemented on the default branch. RFC-process provenance: The lifecycle text dates to the RFC-process update, which is the relevant history for the required discussion-thread gate.
Findings	1 actionable finding	[P2] Link the required maintainer-discussion thread
Security	None	None.

How this fits together

Gateway readiness determines whether OpenClaw is ready to accept work. Runtime owners and activated plugins would contribute bounded observations, configuration would select requirements, and Gateway HTTP/status/CLI consumers would project one canonical result.

flowchart LR
  A[Runtime owners] --> C[Readiness conditions]
  B[Activated plugins] --> C
  D[Operator readiness configuration] --> E[Condition selection]
  C --> F[Canonical readiness result]
  E --> F
  F --> G[Gateway ready endpoints]
  F --> H[Health status and CLI]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt the proposed opt-in canonical readiness contract, including gateway.readiness selection, plugin providers, subject identity, and health/status projections?	Sponsor the bounded v1: Confirm the proposed activation and compatibility boundaries in a maintainer-discussion thread, then link that record from the RFC.

Why: These are new public configuration and plugin API commitments; repository policy requires a maintainer-discussion record for a draft RFC, and the RFC cannot choose their long-term product direction on its own.

Before merge

• Add real behavior proof - Not applicable: All four changed files are documentation, so external real-behavior proof is not required for this RFC-only PR.
• Link the required maintainer-discussion thread (P2) - The RFC is marked draft, but the repository lifecycle requires every new draft RFC to have a maintainer-discussion thread. Neither the submitted RFC context nor PR body links that decision record, leaving the proposed public compatibility contract without its required review forum.
• Resolve merge risk (P1) - Adopting this RFC would create compatibility-sensitive readiness configuration, plugin-provider, endpoint, and CLI contracts without a recorded maintainer decision on their public shape.
• Complete next step (P2) - A maintainer must first decide whether to adopt this new public readiness and plugin-extension contract and record that discussion; there is no narrow repair PR to automate.

Findings

• [P2] Link the required maintainer-discussion thread — rfcs/0018-readiness-conditions-and-providers.md:7

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Documentation scope	4 files affected; +1,826/-0 lines	The PR establishes a large RFC and three linked specifications rather than a small editorial change.
Normative surface	1 RFC plus 2 normative sidecars	The proposed condition and subject specifications would define a broad public implementation contract.

Root-cause cluster

Relationship: canonical
Canonical: #33
Summary: This is the canonical RFC for readiness conditions; the hosting-profile RFC explicitly treats its profile proposal as a separate, dependent product decision.

Members:

• adjacent_distinct: RFC 0023: Standard Hosting Profiles #37 - Its body explicitly describes Standard Hosting Profiles as a separate product/support decision layered on the readiness facility proposed here.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge-risk options

Maintainer options:

1. Establish the maintainer decision record (recommended)
   Open and link the required maintainer-discussion thread resolving the public readiness and plugin-provider boundaries before merge.
2. Pause the RFC
   Keep the proposal as a draft if no maintainer is ready to own the compatibility contract.

Technical review

Best possible solution:

Record a maintainer discussion that decides the opt-in activation boundary, required-versus-advisory semantics, plugin extension contract, and diagnostic endpoint scope before merging the RFC.

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

Not applicable: this is a design RFC, not a report of broken current behavior.

Is this the best way to solve the issue?

No—the RFC needs a recorded maintainer decision before it can be the accepted solution for a new public readiness and plugin-extension contract.

Full review comments:

• [P2] Link the required maintainer-discussion thread — rfcs/0018-readiness-conditions-and-providers.md:7
  The RFC is marked draft, but the repository lifecycle requires every new draft RFC to have a maintainer-discussion thread. Neither the submitted RFC context nor PR body links that decision record, leaving the proposed public compatibility contract without its required review forum.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: not found in the target repository.

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

Labels

Label justifications:

• P2: This is a substantial but non-urgent product and compatibility decision.
• merge-risk: 🚨 compatibility: The RFC proposes new readiness configuration, endpoint, CLI, and plugin-provider contracts that existing deployments and extensions may 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: All four changed files are documentation, so external real-behavior proof is not required for this RFC-only PR.

Evidence

What I checked:

• RFC lifecycle requirement: The checked-out RFC repository requires each new draft RFC to have a maintainer-discussion thread before it proceeds through review. (README.md:84, af708f0ddb6f)
• Current-main check: Current main contains neither the proposed RFC 0018 document nor its readiness sidecars, so the exact documentation change is not already implemented on the default branch. (af708f0ddb6f)
• RFC-process provenance: The lifecycle text dates to the RFC-process update, which is the relevant history for the required discussion-thread gate. (README.md:84, e366ea9825a4)
• Submitted RFC state: The supplied PR diff marks the new RFC as draft while the PR body and supplied discussion context do not link a maintainer-discussion thread. (rfcs/0018-readiness-conditions-and-providers.md:7, 247d95203917)

Likely related people:

• kevinlin-openai: Authored the current RFC-process update that defines the draft RFC discussion requirement. (role: RFC process author; confidence: high; commits: e366ea9825a4, f4fdf38f4717; files: README.md, rfcs/0000-template.md)
• Dallin Romney: Authored the current README clarification for RFC sidecar layout, which this multi-document RFC uses. (role: recent RFC layout contributor; confidence: medium; commits: 3aa7d727383f; files: README.md, rfcs/0000-template.md)

Rank-up moves

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

• Create and link the required maintainer-discussion thread with decisions on the proposed public readiness 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 (129 earlier review cycles; latest 8 shown)

• reviewed 2026-08-10T03:48:48.276Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread | [P3] Remove the Markdown trailing whitespace
• reviewed 2026-08-10T03:56:33.132Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread | [P3] Remove trailing Markdown whitespace
• reviewed 2026-08-11T03:13:27.588Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-11T21:15:38.556Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-12T01:54:31.745Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-14T13:11:20.775Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-14T19:49:54.273Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-15T03:47:40.665Z sha 247d952 :: needs real behavior proof before merge. :: [P2] 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: 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