docs(rfc): propose external-supervisor operator guidance

[paulcam206]

What Problem This Solves

Externally supervised OpenClaw installations correctly keep Gateway lifecycle
authority outside OpenClaw, but current onboarding, CLI, Doctor, update, and
Control UI recovery paths can only tell operators to "use that supervisor."
They cannot name the supervisor or show the deployment-specific command that
will actually resolve the blocked action.

Why This Change Was Made

RFC 0066 proposes a bounded, versioned, display-only guidance contract carried
with OPENCLAW_SUPERVISOR_MODE=external. It keeps lifecycle authority unchanged,
uses surface-native OpenClaw wording, and adds only a narrow authenticated
action-specific projection where an out-of-process UI needs to render the same
guidance.

User Impact

This draft has no immediate product impact. If accepted and implemented,
operators using clawctl, Docker Compose, or another external supervisor will
see the exact start, stop, repair, or update command at the OpenClaw surface
where action is required, without OpenClaw executing or treating that command
as authority.

Evidence

• Lifecycle: Draft RFC; leave the implementation issue blank until
  acceptance.
• RFC document: rfcs/0066-external-supervisor-guidance.md
• Rendered sidecar: Current behavior proof and illustrative
  mocks
• Maintainer discussion: Required maintainer-discussion thread is pending.
• Decision requested: Should OpenClaw adopt the v1 external-supervisor
  operator-guidance contract and its authenticated display-only projection?
• The proposal is grounded in current external-supervisor ownership, onboarding,
  lifecycle, Doctor, update, and Control UI behavior.
• It cites existing JSON-in-environment precedents:
  OPENCLAW_CUA_DRIVER_ENDPOINT and
  OPENCLAW_PLUGIN_INSTALL_OVERRIDES.
• Two review passes covered product/contract completeness, current OpenClaw
  design language, Control UI behavior, compatibility, security, RFC numbering,
  duplicates, and publication requirements.
• Executed unit proof: node scripts/run-vitest.mjs run src/infra/gateway-supervision.test.ts — 1 test file, 16 tests passed.
• Executed unit proof: node scripts/run-vitest.mjs run ui/src/app/update-overlay-helpers.test.ts — 1 test file, 24 tests passed.
• Unrun browser lane: Two local attempts to run the
  external-supervisor Control UI
  E2E
  each stalled for 300 seconds during Vitest startup/global setup and were
  stopped. This lane is not counted as passing.
• Root README compliance: RFC-specific supporting material uses the stable
  rfcs/0066/current-behavior-and-mocks.md sidecar path; frontmatter and
  required top-level headings remain present; Summary remains one paragraph;
  Motivation, Goals, Non-Goals, Proposal, Rationale, and Unresolved questions
  retain their prescribed responsibilities.
• git diff --check origin/main..HEAD
• git show --check for every RFC commit
• Committed RFC blobs verified as LF-only with required frontmatter, heading
  order, balanced fences, bounded schemas, and resolvable pinned source links.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 22, 2026, 8:16 PM ET / September 23, 2026, 00:16 UTC (Revision 3).

ClawSweeper review

What this changes

Adds an RFC and supporting examples for supervisor-specific commands that OpenClaw would display when operators must manage an externally supervised Gateway.

Merge readiness

⛔ Blocked before merge - 3 items remain

Keep open: this is a coherent, distinct proposal that is absent from the default branch. RFC acceptance remains unresolved; no actionable defect was found in the proposal.

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

Review scores

Measure	Result	What it means
Overall readiness	🦪 silver shellfish (2/6)	The proposal is coherent and carefully bounded, but the available artifacts do not satisfy the applicable real-behavior proof gate.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: The sidecar supplies baseline unit results and illustrative CLI/UI output, not after-fix runtime evidence; no production owner changes in this RFC. Because the files are under rfcs/ rather than the explicit docs/ exemption, the ordinary external-PR proof gate remains unresolved. An explicit proof override is appropriate to consider for this design-only submission; implementation need not precede RFC acceptance. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: The sidecar supplies baseline unit results and illustrative CLI/UI output, not after-fix runtime evidence; no production owner changes in this RFC. Because the files are under rfcs/ rather than the explicit docs/ exemption, the ordinary external-PR proof gate remains unresolved. An explicit proof override is appropriate to consider for this design-only submission; implementation need not precede RFC acceptance. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed	9 items	Verified introduced scope: The pinned merge-base-to-head delta adds two Markdown files, totaling 912 lines, with no executable implementation, dependencies, or workflow changes. The complete proposal and sidecar were inspected through the diff and subsequent file reads. RFC acceptance remains required: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted metadata before merge. The RFC still has draft status and a blank issue; the captured PR body explicitly says the discussion is pending. Becoming ready for review does not satisfy this lifecycle. Default-branch necessity check: The live default-branch SHA matches the supplied main revision. Searching its RFC tree found no supervisor-guidance proposal, and the same-repository supervisor search did not identify a merged replacement. The releases/latest endpoint returned no release; no implementation or release-completion claim is made.
Findings	None	None.
Security	None	None.

How this fits together

External supervisors own Gateway installation, lifecycle, and updates. The proposed guidance layer would turn supervisor-supplied environment data into operator instructions in CLI and authenticated Control UI responses without executing commands.

flowchart TD
  A[External supervisor] --> B[Process environment guidance]
  B --> C[External mode and validation]
  C -->|Valid requested action| D[Display-only command]
  C -->|Absent or invalid| E[Generic guidance]
  D --> F[CLI or authenticated Control UI]
  E --> F
  F --> G[Operator acts through supervisor]

Loading

Decision needed

Question	Recommendation
Should OpenClaw accept the proposed v1 supervisor-guidance environment contract and authenticated action-specific display projection?	Sponsor the bounded v1 proposal: Use the required maintainer discussion to accept the display-only scope and record implementation ownership before merging.

Why: This establishes a new public producer contract and configuration surface; source review cannot grant the acceptance required by the repository's RFC lifecycle.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: The sidecar supplies baseline unit results and illustrative CLI/UI output, not after-fix runtime evidence; no production owner changes in this RFC. Because the files are under rfcs/ rather than the explicit docs/ exemption, the ordinary external-PR proof gate remains unresolved. An explicit proof override is appropriate to consider for this design-only submission; implementation need not precede RFC acceptance. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• Complete next step (P2) - Create and link the maintainer-discussion thread, obtain RFC acceptance, then create the implementation issue and update accepted metadata before merge.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Change scope	Documentation +912; production +0; tests +0	The branch defines a future contract without introducing executable behavior.

Technical review

Best possible solution:

Adopt a bounded, display-only guidance contract only through RFC acceptance, preserving supervisor authority, generic fallback, and current-command projection without persistence.

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

Not applicable: this proposes new guidance behavior. Current upstream source confirms the generic-message baseline, but no runtime reproduction was executed.

Is this the best way to solve the issue?

Yes, as a design direction: a shared bounded resolver avoids supervisor-specific integrations and preserves existing ownership checks; adoption still requires product acceptance.

AGENTS.md: not found in the target repository.

Codex review notes: model internal, reasoning medium; reviewed against 967d9aac7472.

Labels

Label changes:

• add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The sidecar supplies baseline unit results and illustrative CLI/UI output, not after-fix runtime evidence; no production owner changes in this RFC. Because the files are under rfcs/ rather than the explicit docs/ exemption, the ordinary external-PR proof gate remains unresolved. An explicit proof override is appropriate to consider for this design-only submission; implementation need not precede RFC acceptance. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
• remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.
• remove status: 👀 ready for maintainer look: Current PR status label is status: 📣 needs proof.
• remove proof: sufficient: Current real behavior proof status is mock_only, not sufficient.

Label justifications:

• P3: This is a design proposal with no immediate runtime change or demonstrated urgent regression.
• rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🐚 platinum hermit.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: The sidecar supplies baseline unit results and illustrative CLI/UI output, not after-fix runtime evidence; no production owner changes in this RFC. Because the files are under rfcs/ rather than the explicit docs/ exemption, the ordinary external-PR proof gate remains unresolved. An explicit proof override is appropriate to consider for this design-only submission; implementation need not precede RFC acceptance. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.

Evidence

What I checked:

• Verified introduced scope: The pinned merge-base-to-head delta adds two Markdown files, totaling 912 lines, with no executable implementation, dependencies, or workflow changes. The complete proposal and sidecar were inspected through the diff and subsequent file reads. (rfcs/0066-external-supervisor-guidance.md:1, 4ee4dabc9ee0)
• RFC acceptance remains required: README requires a maintainer-discussion thread, acceptance, an implementation issue, and accepted metadata before merge. The RFC still has draft status and a blank issue; the captured PR body explicitly says the discussion is pending. Becoming ready for review does not satisfy this lifecycle. (README.md:80, 967d9aac7472)
• Default-branch necessity check: The live default-branch SHA matches the supplied main revision. Searching its RFC tree found no supervisor-guidance proposal, and the same-repository supervisor search did not identify a merged replacement. The releases/latest endpoint returned no release; no implementation or release-completion claim is made. (967d9aac7472)
• Explicit OpenClaw implementation dependency: The RFC grounds its compatibility claims in OpenClaw's Gateway supervision implementation and proposes changing its guidance rendering. This establishes the relevant dependency boundary; no Codex dependency is claimed. (rfcs/0066-external-supervisor-guidance.md:28, 4ee4dabc9ee0)
• Current upstream behavior remains generic: At the independently resolved OpenClaw main revision, external-mode service mutation still throws generic supervisor guidance. The formatter does not resolve supervisor names or action commands, supporting the proposal's central motivation. (src/infra/gateway-supervision.ts:14, b8aacfa5b5c8)
• Security and compatibility boundaries: The proposal preserves policy checks and generic fallback, prohibits execution and command probing, limits projection to an authenticated action-specific response, and excludes commands from durable update records. These are proposed implementation requirements; this Markdown patch changes no runtime authority or stored-data contract. (rfcs/0066-external-supervisor-guidance.md:353, 4ee4dabc9ee0)

Likely related people:

• unknown: The claimed source-line change could not be verified from bounded local history. (role: source history unknown; confidence: low)

Rank-up moves

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

• Obtain an explicit proof override for the design-only RFC, or provide qualifying real-setup evidence with private details redacted; updating the PR body triggers re-review, with a maintainer re-review request available if needed.

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 (2 earlier review cycles)

• reviewed 2026-09-22T21:02:29.656Z sha 8bd10b8 :: needs real behavior proof before merge. :: none
• reviewed 2026-09-22T21:58:52.526Z sha 4ee4dab :: blocked before merge. :: none

[paulcam206]

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

[clawsweeper]

🦞👀
Exact review queued.

Re-review progress:

• State: Complete
• Detail: The durable review result and its route handoff completed.
• Run: https://github.com/openclaw/clawsweeper/actions/runs/35789941929
• Updated: 2026-09-22T22:00:54.623Z