feat(windows): add Gateway Tool Runtime Bridge shared profiles

[MythiliMur]

Summary

Add the package-owned Gateway Tool Runtime Bridge: a generic, controlled execution and managed-profile layer for user-installed command-line tools that must later run under the isolated Gateway-agent identity.

A user installs a tool independently and explicitly registers an installed executable. The bridge validates and records the approved absolute target; the Gateway later invokes only that approved target through a controlled launch policy.

The bridge does not implement, inspect, or automate an external service's authorization protocol. It starts the registered tool's normal interactive setup in the human desktop session, applying a managed profile through that tool's documented configuration mechanism.

What this adds

• A package-managed persistent profile root:

  C:\ProgramData\OpenClaw\GatewayTools\profiles\<opaque-profile-id>\

• Opaque registration and profile IDs.

• A Gateway Tool Runtime Bridge responsible for:

  • approved executable registration and launch policy;
  • managed-profile lifecycle;
  • scoped ACL policy;
  • protected per-profile secret handles when required;
  • process-scoped configuration and protected-secret injection;
  • desktop-session interactive tool setup launch;
  • constrained verification from the real Gateway-agent identity;
  • bounded, redacted operation results.

• Migration from workspace-owned runtime profiles.

• A package-owned Control UI Adapter contract with a fixed allowlist of browser-facing broker operations.

• Tests for profile location, opaque IDs, redaction, ACL intent, migration, approved-target invocation, and bounded result mapping.

Managed Tool Profile Contract

A tool can use the Runtime Bridge only when it documents a supported way to redirect its own profile/configuration/state location.

The per-tool contract declares one supported profile mechanism, for example:

• a process-scoped environment variable;
• a command-line configuration/profile directory option; or
• another documented tool-specific state-root override.

When the Runtime Bridge starts the registered tool, it supplies that setting only to the approved child process:

<tool-supported-profile-setting>=
  C:\ProgramData\OpenClaw\GatewayTools\profiles\<opaque-profile-id>\

The tool—not the bridge—then writes its own configuration and credential state to the managed profile rather than its normal per-user default location.

The bridge does not use filesystem redirection, change global environment variables, alter the tool's normal user profile, or import existing desktop state.

User flow

1. The user installs the tool independently.
2. The user explicitly selects an installed executable, or requests a bounded scan of an approved installation location.
3. The Gateway Tools Broker validates and records the exact approved target.
4. The user explicitly chooses to start managed setup.
5. The Runtime Bridge provisions the persistent managed profile and launches the approved executable in the human desktop session with the tool's declared managed-profile configuration.
6. The user completes the tool's normal documented interactive setup.
7. The tool writes its own state into the managed profile.
8. The Runtime Bridge launches and verifies the same approved executable from the actual Gateway-agent identity.
9. The UI receives only bounded setup/runtime state.

Security model

The managed profile is intentional shared integration state, not a hard security boundary between the desktop user and Gateway-agent identity.

Its ACL permits only:

• package owner / SYSTEM: profile lifecycle and protected-secret handling;
• authenticated interactive desktop identity: approved setup access;
• Gateway-agent identity: approved runtime access;
• all other identities: no access.

A protected secret, when a reviewed contract requires one, is injected only into approved child processes. It must not appear in shims, registry JSON, ordinary configuration, User/Machine environment variables, browser responses, plugin responses, logs, diagnostics, or model context.

Explicit non-goals

• Installing, downloading, updating, or silently auto-registering tools.
• Changing User or Machine PATH.
• Importing desktop credential stores, AppData, browser profiles/cookies, or existing user token files.
• Broad filesystem ACLs, including Everyone:F.
• Arbitrary command execution or arbitrary environment injection.
• Implementing, inspecting, proxying, or storing an external-service login flow or its data.
• Supporting tools that lack a reviewed, documented profile/state override.
• Direct isolated-Gateway/plugin access to the desktop-user broker.

Follow-up package UI

The dependent package-owned Control UI implementation is tracked in #94. #94 depends on this PR and must not merge first. It consumes the constrained Control UI Adapter contract and does not duplicate broker or runtime-bridge authority.

Status and validation

This draft includes the initial package implementation: a provider-neutral registry, canonical executable registration, Gateway-only shims, per-registration runtime profile directories, and a Gateway-only PATH prefix. The authenticated broker, package-managed profile provisioning, protected-secret mechanism, and package Control UI Adapter remain subsequent implementation slices.

Validation completed for the existing implementation:

• git diff --check
• focused Gateway registry tests

[clawsweeper]

Codex review: needs real behavior proof before merge. Reviewed September 22, 2026, 1:10 AM ET / 05:10 UTC (Revision 3).

ClawSweeper review

What this changes

Adds persistent executable registrations, a local Windows broker, workspace profiles, and command shims that expose selected tools to the isolated Gateway.

Merge readiness

⛔ Blocked before merge - 17 items remain

Keep open: the contribution remains distinct from main, but all six prior correctness findings remain unresolved. The latest design revision does not repair the runtime implementation, and the changed authority boundary still lacks production-path proof.

Priority: P2
Reviewed head: 1630fb534ee93aab612d7a1fc90a97459f10e00c
Owner decision: Required. See Decision needed.

Review scores

Measure	Result	What it means
Overall readiness	🧂 unranked krab (1/6)	The idea is coherent, but unchanged security and native-runtime defects prevent this implementation from being quality-ready.
Proof confidence	🦪 silver shellfish (2/6)	Needs real behavior proof before merge: Authority-chain proof required: the registry/service fixtures bypass the production pipe and isolated identity. After repair, provide redacted native-path evidence of authorized registration/execution, cross-user and guest rejection before effects, junction rejection before host writes/deletes, and invalidation after executable or session replacement. Terminal traces or diagnostic recordings are suitable; redact private paths, endpoints, credentials, and account details. The collaborator exemption remains intact for unrelated proof. Native persistence and fresh-install/existing-session compatibility also remain unproven. Update the PR body with evidence to trigger review; otherwise ask a maintainer for @clawsweeper re-review.
Patch quality	🧂 unranked krab (1/6)	Security review found an item that needs attention.

Verification

Check	Result	Evidence
Real behavior	Needs proof	Needs real behavior proof before merge: Authority-chain proof required: the registry/service fixtures bypass the production pipe and isolated identity. After repair, provide redacted native-path evidence of authorized registration/execution, cross-user and guest rejection before effects, junction rejection before host writes/deletes, and invalidation after executable or session replacement. Terminal traces or diagnostic recordings are suitable; redact private paths, endpoints, credentials, and account details. The collaborator exemption remains intact for unrelated proof. Native persistence and fresh-install/existing-session compatibility also remain unproven. Update the PR body with evidence to trigger review; otherwise ask a maintainer for @clawsweeper re-review.
Evidence reviewed	10 items	Review continuity: The source and tests have no changes since the previously reviewed head c2774a6. Each of the six retained findings was checked against the current implementation and remains applicable. Host filesystem effects bypass the existing trusted owner: PrepareRuntime creates directories, overwrites shims, and deletes unexpected .cmd files using ordinary path-based filesystem operations. SessionWorkspaceOperation explicitly identifies the workspace as guest-writable and provides generation checks and handle-bound operations; the new code does not use them. Verification does not exercise the isolated identity: Registrations default to enabled; availability is only File.Exists under the desktop host identity. Broker verification and enablement consume that result without executing a bounded check inside the recorded agent session or binding approval to executable identity.
Findings	6 actionable findings	[P1] Bind shim filesystem effects to the trusted workspace owner [P1] Use generated JSON metadata throughout the native broker and store [P1] Require isolated verification before enabling registrations
Security	Needs attention	Guest-controlled paths redirect host filesystem effects: The new preparation path follows workspace child paths while writing and deleting as the desktop user, bypassing the repository's trusted filesystem owner. Executable approval is not bound to the invoked target: Readiness depends only on desktop file existence, and the generated batch file can expand characters in the stored path. The implementation does not establish isolated verification or invalidate authority after executable replacement.

How this fits together

The Windows package launches OpenClaw inside a separate agent session. This bridge accepts desktop tool registrations and prepares commands that the Gateway can discover through its process PATH.

flowchart LR
    A[Desktop caller] --> B[Local pipe authorization]
    B --> C[Tool registration store]
    C --> D[Workspace profiles and shims]
    D --> E[Gateway process PATH]
    E --> F[Registered executable]

Loading

Decision needed

Question	Recommendation
Should this land only as a complete, verified shared-profile bridge, or should the current submission be narrowed to an inactive design foundation?	Complete the boundary before activation: Keep the implementation open until its filesystem authority, isolated verification, profile lifecycle, and native proof satisfy the stated contract.

Why: The branch activates host-to-agent authority while its stated profile, setup, and verification contracts remain unfinished; choosing the supported landing boundary requires owner intent.

Before merge

• Add real behavior proof - Needs real behavior proof before merge: Authority-chain proof required: the registry/service fixtures bypass the production pipe and isolated identity. After repair, provide redacted native-path evidence of authorized registration/execution, cross-user and guest rejection before effects, junction rejection before host writes/deletes, and invalidation after executable or session replacement. Terminal traces or diagnostic recordings are suitable; redact private paths, endpoints, credentials, and account details. The collaborator exemption remains intact for unrelated proof. Native persistence and fresh-install/existing-session compatibility also remain unproven. Update the PR body with evidence to trigger review; otherwise ask a maintainer for @clawsweeper re-review.
• Bind shim filesystem effects to the trusted workspace owner (P1) - The workspace is writable by the isolated agent. A junction beneath .openclaw/gateway-tools can redirect these host-side directory creations, shim overwrites, and stale-file deletions outside the workspace. Holding a separate workspace operation in the caller does not validate these child paths. Route every effect through the existing generation-checked, handle-bound filesystem owner.
• Use generated JSON metadata throughout the native broker and store (P1) - These reflection-based serializer overloads have no generated metadata resolver. The shipped launcher uses NativeAOT, so registry persistence and broker request/response handling cannot rely on the JIT tests' reflection support. Supply contract-specific generated metadata for every shape, including the response's runtime value types.
• Require isolated verification before enabling registrations (P1) - A newly registered executable is immediately enabled, and runtime preparation treats desktop-side File.Exists as readiness. verifyTool repeats that same check, so an executable inaccessible to the agent still becomes a Gateway command without verification. Default to disabled and require a successful bounded check under the recorded agent identity, invalidated when the executable or session changes.
• Apply a deadline to each connected pipe exchange (P2) - The idle token only covers WaitForConnectionAsync; connected reads and writes use the outer token, which production supplies as CancellationToken.None. An authorized client that connects but never finishes its request can occupy the sole server instance indefinitely. Bound the complete exchange and recover the accept loop after timeout or disconnect.
• Return the runtime profile state that was actually created (P2) - createRuntimeProfile reports success after preparing all enabled registrations, even when the requested registration is disabled or unavailable and therefore received no directory. Subsequent summaries also always report notCreated. Create or inspect the selected registration's profile and derive the response and list status from the actual result.
• Preserve literal executable paths in generated batch files (P2) - Quoting does not prevent %NAME% expansion in a batch file. A valid registered path containing literal percent-delimited text can therefore execute a different path or fail when the shim runs; delayed expansion can similarly affect exclamation marks. Use a launch mechanism that preserves the approved literal target, with regression coverage for these valid filename characters.
• Resolve security concern: Guest-controlled paths redirect host filesystem effects - The new preparation path follows workspace child paths while writing and deleting as the desktop user, bypassing the repository's trusted filesystem owner.
• Resolve security concern: Executable approval is not bound to the invoked target - Readiness depends only on desktop file existence, and the generated batch file can expand characters in the stored path. The implementation does not establish isolated verification or invalidate authority after executable replacement.
• Resolve merge risk (P1) - Guest-writable paths currently control desktop-host writes and deletions; allowed, forbidden, and stale-authority cases need final-effect proof after repair.
• Resolve merge risk (P1) - The active implementation does not provide the proposed persistent shared-profile lifecycle or controlled profile injection; the landing scope and authority owner need an explicit decision.
• Resolve merge risk (P1) - The new persistent registry and unconditional preparation during Gateway startup lack native serialization and fresh-install/existing-session upgrade evidence.
• Complete next step (P2) - Resolve the retained findings and confirm whether this slice will deliver the complete shared-profile boundary or remain inactive, then satisfy the scoped authority and upgrade proof gates.
• Improve patch quality - Resolve all six retained findings using the existing trusted filesystem and session owners.
• Improve patch quality - Provide final-effect proof for allowed, forbidden, and stale executable/session authority through the native production boundary.
• Improve patch quality - Align the implemented landing scope with the shared-profile contract and demonstrate native persistence plus existing-session upgrade compatibility.
• Resolve maintainer decision - Resolve the maintainer decision shown above before merge.

Findings

• [P1] Bind shim filesystem effects to the trusted workspace owner — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:115-119
• [P1] Use generated JSON metadata throughout the native broker and store — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:223-224
• [P1] Require isolated verification before enabling registrations — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:69-70
• [high] Guest-controlled paths redirect host filesystem effects — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:118
• [medium] Executable approval is not bound to the invoked target — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:203

Agent review details

Security

Needs attention: The patch introduces unsafe desktop-host filesystem effects and does not yet enforce verified executable authority at use.

Review metrics

Metric	Value	Why it matters
Production and test delta	Production +773/-12 lines; tests +183/-0; proposal +169/-0	The new broker and registry explain the production growth, but the tests exercise fixtures rather than the new principal boundary.
Prior findings	6 unresolved; 0 source or test changes since prior review	The latest design revision has not addressed the previously identified implementation defects.

Merge-risk options

Maintainer options:

1. Repair and prove the complete bridge (recommended)
   Resolve the six findings and establish native authority and upgrade behavior before enabling the bridge in Gateway startup.
2. Pause runtime activation
   Keep the proposal available while deferring executable registration and host filesystem effects until the security contract is implementable.

Technical review

Best possible solution:

Use one package-owned, AOT-safe bridge with trusted filesystem operations, verified executable identity, and reviewed per-tool profile configuration, preserving existing Gateway startup through demonstrated upgrade compatibility.

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

Yes, the reported patch defects have direct source paths: redirected workspace entries reach host writes/deletes, registration bypasses verification, and connected pipe I/O has no deadline. These paths were not executed in this read-only review.

Is this the best way to solve the issue?

No, the current implementation activates the bridge before satisfying its own verification and profile contracts; extending the existing trusted workspace and session owners is the narrower safe approach.

Full review comments:

• [P1] Bind shim filesystem effects to the trusted workspace owner — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:115-119
  The workspace is writable by the isolated agent. A junction beneath .openclaw/gateway-tools can redirect these host-side directory creations, shim overwrites, and stale-file deletions outside the workspace. Holding a separate workspace operation in the caller does not validate these child paths. Route every effect through the existing generation-checked, handle-bound filesystem owner.
  Confidence: 0.99
• [P1] Use generated JSON metadata throughout the native broker and store — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:223-224
  These reflection-based serializer overloads have no generated metadata resolver. The shipped launcher uses NativeAOT, so registry persistence and broker request/response handling cannot rely on the JIT tests' reflection support. Supply contract-specific generated metadata for every shape, including the response's runtime value types.
  Confidence: 0.99
• [P1] Require isolated verification before enabling registrations — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:69-70
  A newly registered executable is immediately enabled, and runtime preparation treats desktop-side File.Exists as readiness. verifyTool repeats that same check, so an executable inaccessible to the agent still becomes a Gateway command without verification. Default to disabled and require a successful bounded check under the recorded agent identity, invalidated when the executable or session changes.
  Confidence: 0.99
• [P2] Apply a deadline to each connected pipe exchange — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:57
  The idle token only covers WaitForConnectionAsync; connected reads and writes use the outer token, which production supplies as CancellationToken.None. An authorized client that connects but never finishes its request can occupy the sole server instance indefinitely. Bound the complete exchange and recover the accept loop after timeout or disconnect.
  Confidence: 0.99
• [P2] Return the runtime profile state that was actually created — src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:310-311
createRuntimeProfile reports success after preparing all enabled registrations, even when the requested registration is disabled or unavailable and therefore received no directory. Subsequent summaries also always report notCreated. Create or inspect the selected registration's profile and derive the response and list status from the actual result.
  Confidence: 0.99
• [P2] Preserve literal executable paths in generated batch files — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:212-213
  Quoting does not prevent %NAME% expansion in a batch file. A valid registered path containing literal percent-delimited text can therefore execute a different path or fail when the shim runs; delayed expansion can similarly affect exclamation marks. Use a launch mechanism that preserves the approved literal target, with regression coverage for these valid filename characters.
  Confidence: 0.98

Overall correctness: patch is incorrect
Overall confidence: 0.98

AGENTS.md: found and applied where relevant.

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

Labels

Label justifications:

• P2: This is a new Windows integration capability with substantive merge blockers, without evidence of an urgent shipped regression.
• merge-risk: 🚨 security-boundary: The bridge performs desktop-host filesystem effects through guest-writable paths and enables executable authority without isolated verification.
• merge-risk: 🚨 availability: Reflection-based native serialization and an indefinitely occupied single pipe can make the new bridge unusable.
• merge-risk: 🚨 compatibility: The new persistent store and automatic preparation join existing Gateway startup without demonstrated existing-session upgrade compatibility.
• rating: 🧂 unranked krab: Overall readiness is 🧂 unranked krab; proof is 🦪 silver shellfish and patch quality is 🧂 unranked krab.
• status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs real behavior proof before merge: Authority-chain proof required: the registry/service fixtures bypass the production pipe and isolated identity. After repair, provide redacted native-path evidence of authorized registration/execution, cross-user and guest rejection before effects, junction rejection before host writes/deletes, and invalidation after executable or session replacement. Terminal traces or diagnostic recordings are suitable; redact private paths, endpoints, credentials, and account details. The collaborator exemption remains intact for unrelated proof. Native persistence and fresh-install/existing-session compatibility also remain unproven. Update the PR body with evidence to trigger review; otherwise ask a maintainer for @clawsweeper re-review.

Evidence

Security concerns:

• [high] Guest-controlled paths redirect host filesystem effects — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:118
  The new preparation path follows workspace child paths while writing and deleting as the desktop user, bypassing the repository's trusted filesystem owner.
  Confidence: 0.99
• [medium] Executable approval is not bound to the invoked target — src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:203
  Readiness depends only on desktop file existence, and the generated batch file can expand characters in the stored path. The implementation does not establish isolated verification or invalidate authority after executable replacement.
  Confidence: 0.98

What I checked:

• Review continuity: The source and tests have no changes since the previously reviewed head c2774a6. Each of the six retained findings was checked against the current implementation and remains applicable. (1630fb534ee9)
• Host filesystem effects bypass the existing trusted owner: PrepareRuntime creates directories, overwrites shims, and deletes unexpected .cmd files using ordinary path-based filesystem operations. SessionWorkspaceOperation explicitly identifies the workspace as guest-writable and provides generation checks and handle-bound operations; the new code does not use them. (src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:112, 1630fb534ee9)
• Verification does not exercise the isolated identity: Registrations default to enabled; availability is only File.Exists under the desktop host identity. Broker verification and enablement consume that result without executing a bounded check inside the recorded agent session or binding approval to executable identity. (src/OpenClaw.Launcher/Gateway/GatewayToolRegistry.cs:69, 1630fb534ee9)
• Native serialization and pipe lifetime: The new registry and broker use reflection-based JsonSerializer overloads, including an object-valued response. The launcher publishes with NativeAOT. The single pipe server also applies its timeout only while accepting a connection, then serves the connected client with the uncancelled outer token. (src/OpenClaw.Launcher/Gateway/GatewayToolsBroker.cs:57, 1630fb534ee9)
• Design and implemented scope differ: The proposal specifies persistent ProgramData profiles, reviewed child-process profile configuration, isolated verification, and protected-secret handling. Current code creates workspace directories, never supplies those directories to the tool, and returns an unavailable response for interactive setup. The PR body acknowledges later implementation slices; that is not approval to activate the incomplete boundary. (docs/proposals/gateway-tool-bridge.md:89, 1630fb534ee9)
• Available proof and persistence coverage: The complete supplied body reports focused registry tests and diff checking. The tests create placeholder executable files and call registry/service methods directly; they do not exercise native pipe authorization, isolated execution, forbidden principals, or stale executable/session authority. The new versioned gateway-tools.json store also lacks demonstrated native round-trip and existing-session upgrade compatibility. (tests/OpenClaw.Launcher.Tests/Gateway/GatewayToolsBrokerTests.cs:77, 1630fb534ee9)

Likely related people:

• paulcam206: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• anna-dingler: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

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-22T02:01:01.900Z sha c2774a6 :: needs real behavior proof before merge. :: [P1] Bind shim filesystem effects to the trusted workspace owner | [P1] Use generated JSON metadata throughout the native broker and store | [P1] Require isolated verification before enabling registrations | [P2] Apply a deadline to each connected pipe exchange | [P2] Return the runtime profile state that was actually created | [P2] Preserve literal executable paths in generated batch files
• reviewed 2026-09-22T02:09:26.540Z sha c2774a6 :: needs real behavior proof before merge. :: [P1] Bind shim filesystem effects to the trusted workspace owner | [P1] Use generated JSON metadata throughout the native broker and store | [P1] Require isolated verification before enabling registrations | [P2] Apply a deadline to each connected pipe exchange | [P2] Return the runtime profile state that was actually created | [P2] Preserve literal executable paths in generated batch files