[stevenlee-oai]

Human merge required. Agents must not merge this RFC or enable automatic merging. A human must manually click Merge.

The Gateway managed mode guide explains why OCE enables the mode by default on supported Compute Drivers. A Gateway-local edit leaves OCE’s draft unchanged, so the next deployment overwrites it. The guide shows an admin how to edit, save, and deploy a lasting change from the OCE Console with managed mode on.

The guide identifies the three blocked actions, the exceptions for node terminals and scheduled Agent turns, and what happens to local edits on redeploy in either mode. It links the OpenClaw changes and distinguishes Gateway administration, model tool policy, and filesystem access. RFC 21 points to the guide for shipped behavior.

The docs check validated 296 pages and 4,713 links. The site and search index built, formatting passed, and Chromium rendered the steps and restrictions table and followed the link to the Configuration tab guide.

[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 maintainer review before merge.

What this changes

This PR expands the Gateway managed-mode reference with upstream implementation links, deployment behavior, and enforcement limits.

Example: An operator edits native configuration with gatewayManagedMode=false and then redeploys.

• Before: The reference explicitly described restoring saved configuration when managed mode was re-enabled.
• After: The reference explains that redeployment restores OCE configuration in either mode and Kubernetes Pod replacement also discards local configuration edits.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	Useful, focused documentation supported by current source and passing head checks, with no actionable findings.
Proof confidence	🌊 off-meta tidepool	Not applicable: Documentation-only changes require no new runtime demonstration; the body reports documentation checks, a build, formatting, and rendered-table inspection.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Operators need a precise account of managed-mode restrictions, local-edit persistence, and the difference between administration controls and model tool policy.
Reason: The update makes existing operator-facing boundaries explicit without adding settings or changing platform contracts.

Merge readiness

✅ Ready for maintainer review

Keep this PR open for maintainer triage: it usefully clarifies existing behavior, and review found no actionable defects.

Priority: P3
Reviewed head: c05199c078c1f6539d52563b3b51487f2ae39178

Before merge

None.

Findings

None.

Agent review details

How this fits together

OCC saves the Agent deployment setting, Compute Drivers launch the Gateway with enforcement variables, and OpenClaw accepts or refuses native administration requests.

flowchart LR
  A[Installation administrator] --> B[Agent draft]
  B --> C[Authorized deployment]
  C --> D[Compute Driver]
  D --> E[Gateway controls]
  F[Native administrator] --> E

Loading

Technical review

Best possible solution:

Land the focused reference update when its author marks this PR ready.

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

No runtime bug is claimed; source inspection supports the documented controls and deployment boundaries.

Is this the best way to solve the issue?

The existing feature reference is the appropriate owner, and linking it from the RFC preserves historical decisions without duplicating current behavior.

AGENTS.md: found and applied where relevant.

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

Provenance checked

• Gateway managed-mode reference keeps the original intent (110aea3: Expose deployment-level controls while retaining trusted reloads, node terminals, and separate filesystem protection; subsequent changes clarified local tool edits and supported-Driver defaults.)
• RFC administration companion keeps the original intent (92ee883: Define managed Gateway administration and distinguish the initial restrictions from stronger filesystem guarantees; this PR adds only a link to current supported behavior.)

Security

None.

Evidence

What I checked:

• Verified PR scope: The pinned introduction changes only the managed-mode reference and adds a current-reference link to the RFC companion; it changes no runtime code, configuration schema, or persisted format. (docs/reference/agents/gateway-managed-mode.md:3, c05199c078c1)
• Current-main enforcement: The shared startup owner applies all three documented variables only when managed mode is enabled, after configuration preparation. (apps/controller/src/drivers/compute/runtime-startup.ts:7, a55641b2b163)
• Permission and default provenance: The changes preserve the supported-Driver default from fix(agents): refuse unsupported managed mode and unlisted tool actions at save #3810 and the Installation-administer requirements documented in fix: document Gateway managed mode permissions for Agent requests #3807. (docs/reference/agents/gateway-managed-mode.md:11, 92cc1a89c069)
• Restoration boundary: The existing Kubernetes reference confirms that Pod replacement and Agent redeployment restore the managed configuration snapshot while persistent claims retain Agent data. (docs/reference/drivers/kubernetes-compute/managed-native-configuration.md:24, c05199c078c1)
• Affirmative upstream contract dependency: The changed reference explicitly relies on the pinned OpenClaw implementation; its config-write guard selects Nix guidance when applicable, and error serialization preserves OPENCLAW_CONFIG_READONLY in error.details.code, matching fix: let Gateway clients identify read-only config writes openclaw#185299. (src/gateway/error-shape.ts:22, 762a2fe60cc3)
• Validation and workflow state: CI Required and Suite Audit and Static Checks passed on the reviewed head; git diff --check passed, the checkout remained clean, and this PR is still a draft. (c05199c078c1)

Likely related people:

• stevenlee-oai: Raw commit 110aea3 adds docs/reference/agents/gateway-managed-mode.md:1 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: 110aea3888bb; files: docs/reference/agents/gateway-managed-mode.md)

Labels

Label changes:

• add P3: This is a focused documentation clarification with no runtime behavior change.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: This is a focused documentation clarification with no runtime behavior change.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 28, 2026, 3:20 PM ET / 19:20 UTC.