RFC 0019: Managed Configuration

[giodl73-repo]

Decision requested

Should OpenClaw provide an opt-in, startup-only way to compose independently
authored configuration sources while preserving field authority?

Why

Hosts often combine deployment defaults, tenant connectivity, and
operator-local settings. Lobster currently demonstrates the cost of flattening
those sources outside OpenClaw: source boundaries disappear, launchers must
approximate OpenClaw config behavior, and a later overlay can silently replace
an earlier security boundary.

RFC 0019 keeps the values in the ordinary OpenClaw schema and adds one generic
composition seam around them. It does not create a hosted-config schema,
control plane, policy language, or set of built-in host/tenant/operator roles.

Ownership model

• Existing OpenClaw subsystems continue to own field meaning, defaults,
  validation, runtime behavior, and the two schema-specific bounded rules.
• The invoker or host owns source contents, secure materialization, permissions,
  order, rollout, and process replacement.
• OpenClaw config bootstrap owns source preparation, recursive composition,
  authority admission, and fail-closed startup.
• The existing Gateway config lifecycle owns the one accepted runtime snapshot.
• Runtime consumers use that ordinary snapshot and never interpret layer ids.

The first declaring layer has authority over a path only within the evaluated
candidate and accepted process activation. Layer ids are diagnostic labels,
not principals or durable owner identities. A full process restart recomputes
authority from current sources; an in-process Gateway restart reuses the
accepted snapshot.

This gives OCC, Fleet, Lobster, or another host a clean caller boundary: they
may compile desired state and select sources without taking ownership of
OpenClaw config semantics.

Normative contract

The Managed Configuration V1 sidecar
is normative. The RFC supplies motivation, examples, evidence, and migration
guidance.

V1 is deliberately narrow:

• repeated ordered --config-layer <id=path> startup inputs;
• native JSON5, include, environment, schema, and plugin processing;
• recursive first-declaration exact authority;
• conservative tools.allow narrowing and tools.deny broadening;
• one startup-only, read-only Gateway snapshot;
• path-scoped mutation exclusion;
• no reload, write routing, provenance API, generations, or rollback.

No flag preserves ordinary OpenClaw config behavior.

Example

openclaw gateway run \
  --config-layer scout=./scout-global.json5 \
  --config-layer tenant=./tenant-network.json5 \
  --config-layer operator=./operator-local.json5

ordered sources
  -> independent native preparation
  -> recursive authority fold
  -> final schema and plugin validation
  -> one immutable runtime snapshot

A later exact-path replacement rejects with ControlledByEarlierLayer. A
later bounded tool-policy declaration is accepted only when OpenClaw can prove
that it tightens the earlier value.

Implementation and evidence

• Simplified implementation: openclaw/openclaw#107026
• Broad exploratory prototype: giodl73-repo/openclaw#33
• Lobster adoption evidence: giodl/lobster#12
• 101 exact-head focused tests plus type, lint, documentation, build, security,
  and QA checks on the current implementation review head
• Foreground proofs cover successful composition, conflict rejection, mutation
  rejection, and no canonical config creation or modification

Delivery

1. Land the OpenClaw core after maintainer agreement and a coordinated rebase
   onto current main.
2. Adopt a released conformant OpenClaw version behind a host rollout switch.
3. Prove representative source sets through real process startup.
4. Delete Lobster's legacy overlay writer and stale-value cleanup only after
   rollout and rollback evidence.

The RFC remains draft while maintainers review the ownership boundary and
bounded V1 contract.

[giodl73-repo]

Closing because this RFC is still being developed on the fork and was opened upstream prematurely.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 1, 2026, 4:35 PM ET / 20:35 UTC.

ClawSweeper review

What this changes

This branch adds an RFC and normative sidecar specifying opt-in, startup-only Gateway configuration layers that compose ordinary config files while rejecting conflicting or policy-weakening values.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

This is a well-scoped draft RFC, not an implementation already present on this repository’s current main branch. It should remain open for an explicit maintainer product and security-boundary decision on whether ordered, authoritative Gateway configuration layers belong in core; the linked implementation PR remains open and is not evidence of a shipped solution.

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

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	The RFC is a coherent, narrowly scoped design package, but merge readiness depends on maintainer acceptance of its core compatibility and security contract.
Proof confidence	🌊 off-meta tidepool	Not applicable: This RFC-only branch changes design documentation rather than executable behavior; real Gateway evidence belongs with the linked implementation PR. Any future proof should redact private endpoints, IP addresses, and credentials.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This RFC-only branch changes design documentation rather than executable behavior; real Gateway evidence belongs with the linked implementation PR. Any future proof should redact private endpoints, IP addresses, and credentials.
Evidence reviewed	5 items	Draft RFC conforms to the repository lifecycle shape: The proposed RFC is marked draft, leaves the implementation issue blank, and points its RFC metadata at this pull request; current repository guidance says draft RFCs remain unmerged until acceptance. The branch establishes a new core contract rather than a completed implementation: The sidecar defines a repeated Gateway startup flag, composition authority, mutation restrictions, compatibility behavior, and security requirements; this is a product and security contract that requires maintainer acceptance. Implementation is still tracked separately and remains unlanded: The RFC identifies openclaw/openclaw#107026 as the implementation draft and states that exact-head validation and upstream CI remain required before it can claim conformance.
Findings	None	None.
Security	None	None.

How this fits together

The RFC repository records OpenClaw design decisions before implementation. This proposal would let a host pass ordered configuration sources into Gateway startup, where configuration bootstrap would compose and validate them before Gateway publishes one runtime snapshot.

flowchart LR
  A[Host or operator] --> B[Ordered config files]
  B --> C[Gateway startup]
  C --> D[Prepare each source]
  D --> E[Authority and policy checks]
  E --> F[Schema and plugin validation]
  F --> G[Immutable Gateway snapshot]
  G --> H[Runtime consumers]

Loading

Decision needed

Question	Recommendation
Should OpenClaw adopt an opt-in core Gateway configuration-layer contract with first-declaration authority and startup-only immutable snapshots, rather than leaving composition to hosts?	Accept the narrow V1 direction: Approve the startup-only, no-flag-compatible core contract while requiring the linked implementation to prove its conformance and upgrade behavior separately.

Why: This choice adds a user-visible CLI/configuration surface and defines a long-lived compatibility and security boundary; source review cannot determine whether maintainers want that contract in core.

Before merge

• Add real behavior proof - Not applicable: This RFC-only branch changes design documentation rather than executable behavior; real Gateway evidence belongs with the linked implementation PR. Any future proof should redact private endpoints, IP addresses, and credentials.
• Resolve merge risk (P1) - Accepting the RFC would establish a compatibility-sensitive Gateway CLI and composed-configuration contract before the linked implementation has landed or demonstrated exact-head conformance.
• Resolve merge risk (P1) - The proposed authority and mutation rules affect security boundaries: a mistaken containment comparison or lifecycle exception could let a later source weaken an earlier policy or make operator workflows unexpectedly immutable.
• Resolve merge risk (P1) - The repository workflow expects a maintainer-discussion thread for new RFCs; the provided PR material does not link one, so the acceptance record is not yet auditable from this branch.
• Complete next step (P2) - A human must choose whether this compatibility- and security-sensitive core configuration contract belongs in OpenClaw before any implementation work is promoted.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Normative RFC surface	2 files added, 1,080 lines	The RFC and its sidecar together define the proposed CLI, authority, lifecycle, security, and conformance contract.
Implementation dependency	1 linked open core implementation PR	The proposal’s practical validation and release path depend on a separate, currently unmerged implementation.

Merge-risk options

Maintainer options:

1. Review the V1 contract with the implementation (recommended)
   Keep this RFC draft until maintainers approve the CLI, ordinary-config compatibility, and migration behavior together with the linked implementation PR.
2. Accept the contract boundary now
   Merge the RFC only if maintainers intentionally accept its compatibility and security commitments before implementation validation completes.
3. Pause for a narrower boundary
   Leave the draft open if maintainers do not want core to own ordered-source authority and layered-mode write restrictions.

Technical review

Best possible solution:

Keep the RFC draft open, record a maintainer decision on the narrow V1 core contract, and review the RFC alongside openclaw/openclaw#107026 before accepting the design or scheduling implementation.

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

Not applicable: this PR is an RFC-only design proposal, not a report of broken current behavior. The implementation claims should be evaluated on the separate OpenClaw implementation PR, not by executing this Markdown branch.

Is this the best way to solve the issue?

Unclear. The proposal is internally narrow and explicitly preserves ordinary no-flag behavior, but whether OpenClaw should own this new configuration authority and lifecycle contract is a maintainer product decision.

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 normal-priority core configuration design decision with a bounded but cross-cutting impact.
• merge-risk: 🚨 compatibility: The RFC defines a new Gateway flag and acceptance/rejection behavior that must preserve ordinary no-flag configuration behavior.
• merge-risk: 🚨 security-boundary: The proposed first-declaration and policy-tightening rules are intended to prevent later configuration sources from weakening security controls.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• feature: ✨ showcase: ClawSweeper spotlight: unusually compelling feature idea for maintainer attention. The proposal offers a focused way for deployment hosts to compose ordinary OpenClaw configuration without creating host-specific configuration semantics in core.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: This RFC-only branch changes design documentation rather than executable behavior; real Gateway evidence belongs with the linked implementation PR. Any future proof should redact private endpoints, IP addresses, and credentials.

Evidence

What I checked:

• Draft RFC conforms to the repository lifecycle shape: The proposed RFC is marked draft, leaves the implementation issue blank, and points its RFC metadata at this pull request; current repository guidance says draft RFCs remain unmerged until acceptance. (rfcs/0019-managed-configuration.md:1, 5b33475052c6)
• The branch establishes a new core contract rather than a completed implementation: The sidecar defines a repeated Gateway startup flag, composition authority, mutation restrictions, compatibility behavior, and security requirements; this is a product and security contract that requires maintainer acceptance. (rfcs/0019/managed-configuration-v1-spec.md:11, 5b33475052c6)
• Implementation is still tracked separately and remains unlanded: The RFC identifies feat(config): add ordered config layers openclaw#107026 as the implementation draft and states that exact-head validation and upstream CI remain required before it can claim conformance. (rfcs/0019-managed-configuration.md:504, 5b33475052c6)
• Current main does not contain this RFC: A current-main search found no Managed Configuration RFC, config-layer flag, authority finding, or equivalent RFC content outside the proposed branch, so there is no current-main implementation or accepted RFC to close against. (af708f0ddb6f)
• RFC workflow provenance: The current RFC lifecycle guidance, including the requirement for a maintainer-discussion thread and draft-before-acceptance flow, was introduced by the RFC-process update. (README.md:62, e366ea9825a4)

Likely related people:

• kevinlin-openai: Introduced the current RFC lifecycle guidance that governs draft acceptance, implementation-issue creation, and merge sequencing. (role: RFC workflow contributor; confidence: high; commits: e366ea9825a4; files: README.md)
• Dallin Romney: Added the repository guidance for RFC sidecar material, directly relevant to this branch’s RFC-plus-normative-spec structure. (role: RFC sidecar-layout contributor; confidence: medium; commits: 3aa7d727383f; files: README.md)

Rank-up moves

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

• Record the required maintainer-discussion thread and decision for the proposed core boundary.
• Review the linked implementation against the RFC’s exact-head conformance and upgrade claims before accepting the design.

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

• reviewed 2026-07-28T15:01:55.996Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T07:39:07.778Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T08:38:27.083Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T14:34:49.539Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-30T19:00:25.293Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T17:58:45.031Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T19:46:31.327Z sha 5b33475 :: needs real behavior proof before merge. :: none
• reviewed 2026-08-01T15:20:23.184Z sha 5b33475 :: needs real behavior proof before merge. :: none

[giodl73-repo]

Closing for now while we finish the implementation plan, role review, and supporting prototype proof on the fork. We will revisit upstream submission when the RFC and delivery slices are ready for maintainer review.

[giodl73-repo]

Rebased RFC 0019 onto current openclaw/rfcs:main at 13819ef73d3ae980b362e2a88ccb3cba90faa21d; the draft head is now 481116b135790390da82a519e03f84ad7ad770b8.

The rebase does not expand or change the V1 contract. The paired implementation has also been rebased onto current OpenClaw main. Its historical 63-test and live-Gateway evidence remains documented, while exact-head post-rebase validation is explicitly pending rather than overstated.

ClawSweeper reports no automated repair item here. The remaining question is the expected maintainer decision on the core ownership/security boundary and RFC-to-implementation acceptance.

[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/30020892494
• Updated: 2026-07-23T15:31:18.567Z