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 22, 2026, 12:00 PM ET / 16:00 UTC.

ClawSweeper review

What this changes

The PR adds a draft RFC and three sidecars defining opt-in, subject-aware Gateway readiness conditions, plugin providers, and shared HTTP/status/CLI projections.

Merge readiness

⚠️ Ready for maintainer review - 5 items remain

Keep open: this is a substantial product and plugin-contract RFC, not an implemented default-branch change. Its required maintainer-discussion thread is still not linked, so it needs that discussion and an explicit product decision before merge.

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 is not merge-ready until its required maintainer discussion is linked and the product direction is decided.
Proof confidence	🌊 off-meta tidepool	Not applicable: This docs-only RFC does not require external real-behavior proof; implementation proof remains relevant only to any later upstream implementation PRs.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This docs-only RFC does not require external real-behavior proof; implementation proof remains relevant only to any later upstream implementation PRs.
Evidence reviewed	5 items	RFC lifecycle requirement: Current repository guidance requires every new RFC to have a maintainer-discussion thread before acceptance and merge; no such link appears in this RFC or its sidecars. Draft metadata and missing discussion link: The RFC remains a draft with no implementation issue, and its metadata provides only the RFC PR URL; the document contains no required discussion-thread URL. Not implemented on current default branch: The current default branch contains no RFC 0018 or readiness-condition sidecar, so the exact proposed RFC has not already landed.
Findings	1 actionable finding	[P2] Link the required maintainer discussion
Security	None	None.

How this fits together

The RFC repository records proposed OpenClaw contracts before they become implementation work. This proposal would collect Gateway and plugin observations into one readiness result consumed by operator probes, diagnostics, and the CLI.

flowchart LR
A[Gateway runtime facts] --> C[Readiness conditions]
B[Plugin observations] --> C
D[Operator selection] --> E[Canonical readiness result]
C --> E
E --> F[Readiness probes]
E --> G[Status diagnostics]
E --> H[CLI output]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt the opt-in canonical readiness contract, including operator-selected conditions and plugin readiness providers?	Sponsor the RFC direction: Create the required discussion thread, resolve its API and compatibility questions, then accept the RFC with an implementation issue.

Why: The RFC defines new public configuration, HTTP/CLI semantics, and a plugin-facing contract; repository policy requires maintainer discussion before accepting that direction.

Before merge

• Add real behavior proof - Not applicable: This docs-only RFC does not require external real-behavior proof; implementation proof remains relevant only to any later upstream implementation PRs.
• Link the required maintainer discussion (P2) - The repository lifecycle requires each new RFC to have a maintainer-discussion thread, but this draft and its sidecars contain no thread URL. Add and link that thread before merge so the requested compatibility and product decisions have the required review venue. This remains unchanged from the earlier review of the same head.
• Resolve merge risk (P1) - Accepting the proposed public readiness, configuration, and plugin-provider contract before maintainer discussion could create durable compatibility obligations across existing operator integrations.
• Complete next step (P2) - A maintainer must decide the new readiness and plugin API direction; the remaining prerequisite is a required discussion link, not an automatable code repair.

Findings

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

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC scope	4 documentation files, +1,826 lines	The PR establishes a broad cross-surface contract rather than a narrow editorial proposal.

Merge-risk options

Maintainer options:

1. Link and hold maintainer discussion (recommended)
   Add the required maintainer-discussion thread and obtain an explicit decision on the readiness and plugin API boundary before merge.

Technical review

Best possible solution:

Open and link the required maintainer discussion, then decide whether the opt-in readiness and provider contract is an accepted OpenClaw direction before moving its upstream implementation stack forward.

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?

Unclear: the design is detailed, but the repository-required maintainer discussion and product decision must precede acceptance of this public contract.

Full review comments:

• [P2] Link the required maintainer discussion — rfcs/0018-readiness-conditions-and-providers.md:9
  The repository lifecycle requires each new RFC to have a maintainer-discussion thread, but this draft and its sidecars contain no thread URL. Add and link that thread before merge so the requested compatibility and product decisions have the required review venue. This remains unchanged from the earlier review of the same head.
  Confidence: 0.99
  Late finding: first raised on code an earlier review cycle already covered.

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 meaningful product-contract proposal with no demonstrated urgent production regression.
• merge-risk: 🚨 compatibility: The RFC proposes public readiness, configuration, and plugin-provider behavior that could affect existing operator integrations.
• 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 docs-only RFC does not require external real-behavior proof; implementation proof remains relevant only to any later upstream implementation PRs.

Evidence

What I checked:

• RFC lifecycle requirement: Current repository guidance requires every new RFC to have a maintainer-discussion thread before acceptance and merge; no such link appears in this RFC or its sidecars. (README.md:84, af708f0ddb6f)
• Draft metadata and missing discussion link: The RFC remains a draft with no implementation issue, and its metadata provides only the RFC PR URL; the document contains no required discussion-thread URL. (rfcs/0018-readiness-conditions-and-providers.md:7, 247d95203917)
• Not implemented on current default branch: The current default branch contains no RFC 0018 or readiness-condition sidecar, so the exact proposed RFC has not already landed. (af708f0ddb6f)
• Policy provenance: The RFC lifecycle guidance appears in the repository history from the RFC-process update, with later sidecar-layout guidance supporting the PR’s multi-document layout. (README.md:84, e366ea9825a4)
• Compatibility-sensitive proposal scope: The sidecar defines plugin SDK provider registration and preserves unconfigured legacy readiness behavior, making acceptance a public compatibility decision rather than an editorial-only change. (rfcs/0018/readiness-v1-spec.md:255, 247d95203917)

Likely related people:

• kevinlin-openai: Authored the repository RFC-process update that established the discussion-before-acceptance flow. (role: RFC lifecycle guidance author; confidence: high; commits: e366ea9825a4; files: README.md, rfcs/0000-template.md)
• Dallin Romney: Authored the current-main clarification that governs RFC sidecar organization used by this PR. (role: sidecar-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.
• Resolve the public readiness and plugin-provider contract in that thread 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 (131 earlier review cycles; latest 8 shown)

• 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
• reviewed 2026-08-15T08:45:44.414Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Link the required maintainer-discussion thread
• reviewed 2026-08-22T05:02:34.509Z sha 247d952 :: needs real behavior proof before merge. :: [P2] Create and link 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: 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