RFC 0020: OpenShell Worker Provider and Credential-Brokered Session Sandboxes

[sallyom]

Summary

Proposes an optional OpenShell WorkerProvider for Cloud Worker sessions. Each explicitly selected Cloud/OpenShell session receives a disposable child sandbox while OpenClaw retains placement, recovery, transcripts, and session ownership.

Motivation

The existing OpenShell SandboxBackend isolates selected tools but leaves the session agent loop in the Gateway. This RFC defines the narrower delegated control path required to isolate a selected session's complete worker runtime without exposing OpenShell client mTLS, the supervisor JWT, or model-provider credentials.

Scope

• Add the optional openshell WorkerProvider.
• Use parent-bound delegation credentials to create and relay only server-owned child sandboxes.
• Keep provider credentials in OpenShell through workspace-scoped inference.local.
• Preserve explicit Cloud/OpenShell placement; automatically sandboxing every new session remains a non-goal.

Implementation status

The accompanying OpenClaw and OpenShell branches implement the proposal. The OpenClaw branch has been rebased on current origin/main; OpenShell restricts delegated child shape to the parent-owned template and permits read-only inference-route metadata.

Validation

• Focused OpenClaw OpenShell worker-provider tests pass (26 tests).
• Focused OpenShell delegation authorization and child-template inheritance tests pass.
• RFC and implementation diffs pass whitespace checks.
• A full local plugin/session E2E retest remains planned before the implementation PRs are opened.

Follow-up

An OpenShell issue will be opened to track the delegated worker capability and cross-repository implementation work.

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed August 2, 2026, 1:06 PM ET / 17:06 UTC.

ClawSweeper review

What this changes

The draft RFC proposes an optional OpenShell WorkerProvider that runs explicitly selected cloud sessions in credential-brokered child sandboxes.

Merge readiness

⚠️ Ready for maintainer review - 6 items remain

Keep this draft RFC open: it proposes a new optional worker-runtime and credential-boundary model that requires maintainer product and security-direction review, and its required rfc_pr metadata is still blank. Likely related person: sallyom (medium confidence), as proposal and proof-of-concept author.

Priority: P3
Reviewed head: 302accf512f269791dba880c3e339f26cb3d5c10
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🦐 gold shrimp (3/6)	The RFC is a substantive scoped design proposal, but required lifecycle metadata and maintainer direction remain outstanding.
Proof confidence	🌊 off-meta tidepool	Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
Patch quality	🦐 gold shrimp (3/6)	1 actionable review finding remain.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
Evidence reviewed	5 items	RFC lifecycle policy: The repository README requires a new draft RFC to set rfc_pr to its pull-request URL. This PR leaves that value blank in its frontmatter. Consistent current RFC convention: Recent draft RFCs on current history populate rfc_pr with the canonical pull-request URL, confirming this is an established repository convention rather than an unused template field. New unresolved cross-repository direction: The proposal creates a new WorkerProvider, parent-bound delegation credential, and OpenShell credential-brokered inference route, but leaves the final delegated API and authorization model as open questions.
Findings	1 actionable finding	[P2] Set the RFC pull-request URL in frontmatter
Security	None	None.

How this fits together

OpenClaw’s Gateway currently owns session placement, recovery, transcripts, and agent execution. The proposed OpenShell provider would move explicitly selected Cloud/OpenShell session runtimes into disposable child sandboxes while the Gateway retains session ownership and OpenShell brokers provider credentials.

flowchart LR
  Request[Cloud session request] --> Gateway[OpenClaw Gateway]
  Gateway --> Placement[Explicit OpenShell placement]
  Placement --> Delegation[Parent-bound delegation]
  Delegation --> Worker[Disposable worker sandbox]
  Worker --> Broker[OpenShell inference route]
  Worker --> Runtime[Session runtime and tools]
  Gateway --> Recovery[Transcript and recovery ownership]

Loading

Decision needed

Question	Recommendation
Should OpenClaw accept the proposed optional OpenShell WorkerProvider direction, including parent-bound delegated sandbox creation and OpenShell-brokered inference credentials, as the contract for cross-repository implementation?	Sponsor a bounded RFC revision: Approve the direction in principle, contingent on completing the RFC metadata and documenting the final authorization, upgrade, and compatibility contract before acceptance.

Why: The RFC adds a new session-placement mode and explicitly leaves the final delegated API and authorization model unresolved. Choosing the permanent authority boundary, credential exposure guarantees, and compatibility contract requires maintainer intent.

Before merge

• Add real behavior proof - Not applicable: This PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.
• Set the RFC pull-request URL in frontmatter (P2) - The RFC lifecycle requires rfc_pr to point to this pull request, but the submitted frontmatter leaves it blank. Set the canonical URL so the draft is traceable through acceptance.
• Resolve merge risk (P1) - The proposal introduces a new delegated sandbox-control and credential-brokering contract; accepting it before resolving authorization scope, recovery semantics, and compatibility behavior could create an unsafe or incompatible cross-repository boundary.
• Resolve merge risk (P1) - The required rfc_pr field is blank, so the RFC lifecycle lacks its canonical review link.
• Complete next step (P2) - A maintainer must choose the product and security direction before the RFC can be accepted; filling the frontmatter URL is a small contributor follow-up, not a repair-lane task.

Findings

• [P2] Set the RFC pull-request URL in frontmatter — rfcs/0020-openshell-session-workers.md:9

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
RFC surface	1 added document; 377 lines	The change is documentation-only but specifies a new cross-repository worker and credential-boundary contract.
Open design questions	3 listed	The unresolved API and policy questions show this remains a proposal rather than an acceptance-ready contract.

Merge-risk options

Maintainer options:

1. Resolve the RFC contract before acceptance (recommended)
   Document the delegated authorization scope, credential-exposure guarantees, and explicit placement and upgrade behavior, then fill in metadata and request maintainer review.
2. Defer the cross-repository proposal
   Keep this draft open until the OpenShell delegated-worker API and its owner review are available.

Technical review

Best possible solution:

Keep the RFC draft open, set rfc_pr to its canonical URL, and accept it only after maintainers agree on the delegated authorization contract, upgrade and compatibility behavior, and ownership of the OpenShell counterpart.

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

Not applicable: this is a design RFC, not a report of broken existing behavior. It supplies a future smoke-test outline rather than a current-main defect reproduction.

Is this the best way to solve the issue?

Unclear: a dedicated OpenShell WorkerProvider may be a viable direction, but the RFC deliberately leaves its permanent delegation API and authorization model unresolved, so acceptance requires maintainer confirmation.

Full review comments:

• [P2] Set the RFC pull-request URL in frontmatter — rfcs/0020-openshell-session-workers.md:9
  The RFC lifecycle requires rfc_pr to point to this pull request, but the submitted frontmatter leaves it blank. Set the canonical URL so the draft is traceable through acceptance.
  Confidence: 0.99

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:

• P3: This is a draft architecture proposal with no demonstrated current user regression or release-blocking failure.
• merge-risk: 🚨 compatibility: The RFC proposes a new optional WorkerProvider and session-placement contract that affects future deployment and plugin compatibility.
• merge-risk: 🚨 security-boundary: The proposal delegates child-sandbox control while constraining access to mTLS, supervisor, and model-provider credentials.
• 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 PR changes only an RFC document, so runtime proof is not a merge gate; follow-on implementation PRs should provide redacted evidence for delegation scope, credential isolation, recovery, and session isolation.

Evidence

What I checked:

• RFC lifecycle policy: The repository README requires a new draft RFC to set rfc_pr to its pull-request URL. This PR leaves that value blank in its frontmatter. (README.md:74, af708f0ddb6f)
• Consistent current RFC convention: Recent draft RFCs on current history populate rfc_pr with the canonical pull-request URL, confirming this is an established repository convention rather than an unused template field. (rfcs/0026-automations-terminology.md:8, c876de6210bf)
• New unresolved cross-repository direction: The proposal creates a new WorkerProvider, parent-bound delegation credential, and OpenShell credential-brokered inference route, but leaves the final delegated API and authorization model as open questions. (rfcs/0020-openshell-session-workers.md:16, 302accf512f2)
• Current main has not adopted the RFC: The current-main comparison has no corresponding proposal file; the PR file is absent from current main, so this RFC is neither implemented nor superseded in the checked-out repository. (rfcs/0020-openshell-session-workers.md:1, af708f0ddb6f)
• Current proposal provenance: The unmerged RFC was introduced by sallyom on July 31, 2026; local Git history could not provide a broader owner trail because this proposal has not landed on main. (rfcs/0020-openshell-session-workers.md:1, 302accf512f2)

Likely related people:

• sallyom: The RFC frontmatter and the only local commit identify sallyom; it also names sallyom’s OpenShell and OpenClaw proof-of-concept branches. There is no merged current-main history for this unaccepted design. (role: proposal and proof-of-concept author; confidence: medium; commits: 302accf512f2; files: rfcs/0020-openshell-session-workers.md)

Rank-up moves

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

• Set rfc_pr to the canonical pull-request URL.
• Obtain maintainer agreement on the delegated authorization and credential-isolation contract before changing the RFC status.

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

• reviewed 2026-07-31T13:34:40.785Z sha 302accf :: needs real behavior proof before merge. :: none
• reviewed 2026-07-31T17:57:57.442Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-07-31T19:46:25.839Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-08-01T06:13:31.030Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-08-01T07:20:01.095Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-08-01T10:56:34.295Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-08-01T15:20:01.945Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter
• reviewed 2026-08-01T20:35:35.323Z sha 302accf :: needs real behavior proof before merge. :: [P2] Set the RFC pull-request URL in frontmatter