feature: Add new functionality to connect options

[xrow]

I can`t use the direct connect option to connect to my instance. I do not want a local setup. I do not have SSH available, because I am behind a layer 7 LB.

I need either the option to auth via oauth2 since I have a oauth2-proxy infront or I need to add a script like

kubectl port-forward --address 127.0.0.1 -n openclaw deployment/openclaw 18789:18790

to run before the connection starts. Maybe a stop script is needed too. Is it powershell? Maybe. Or do we just point to some file?

[clawsweeper]

Codex review: keeping this open for maintainer follow-up; there is still a little grit to resolve. Reviewed August 1, 2026, 12:41 PM ET / 16:41 UTC.

Summary
This remains necessary. Current main supports direct gateway URLs, shared-token or setup-code pairing, and a constrained SSH local-forward lifecycle, but it does not offer OAuth2-proxy authentication or a configurable pre-connect command. Either requested path creates a new authentication or local-process security boundary, so maintainer direction is required before implementation.

Reproducibility: no. The report describes a deployment behind a layer-7 load balancer but provides no current connection transcript or proxy configuration; source confirms that the requested OAuth and generic-command options do not exist.

Ways to help us reproduce this

• Add a screenshot or short recording showing the behavior.
• Add expected vs actual behavior.

Maintainer decision needed

Question	Recommendation
Which remote-access contract should OpenClaw Windows support for gateways behind a layer-7 OAuth2 proxy without SSH: OAuth2-proxy authentication, a constrained managed port-forward provider, or neither?	Specify OAuth2 gateway authentication: Define the supported OAuth2-proxy flow, browser handoff, secret persistence, refresh, revocation, and recovery before a focused implementation.

Why: The requested alternatives add incompatible credential and process-lifecycle semantics that current source does not define; selecting either cannot safely be inferred from one deployment scenario.

Next step
A maintainer must choose the authentication or constrained forwarding contract before a safe, bounded implementation can be planned.

Security
Needs attention: The requested OAuth and pre-connect-command paths affect credential handling or local process execution and need an explicit security contract before implementation.

Review details

Best possible solution:

Define one supported remote-access contract: either an OAuth-aware gateway authentication flow or a narrowly typed port-forward provider with fixed arguments, ownership, health checks, cleanup, and end-to-end proof.

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

No. The report describes a deployment behind a layer-7 load balancer but provides no current connection transcript or proxy configuration; source confirms that the requested OAuth and generic-command options do not exist.

Is this the best way to solve the issue?

No. A generic pre-connect script would bypass the current typed SSH process boundary; the maintainable path is a maintainer-selected OAuth or narrowly managed-forward contract.

AGENTS.md: found and applied where relevant.

Remaining risk / open question:

• Allowing arbitrary lifecycle commands would broaden the constrained SSH-forward model into a local process-execution, argument-safety, cleanup, and diagnostics boundary.
• OAuth2-proxy support needs an explicit browser handoff, token storage, refresh, revocation, and recovery contract before credentials can be persisted or sent to a remote gateway.
• The report does not include a current connection transcript or proxy configuration, so the exact OAuth2-proxy behavior and gateway expectations remain unverified.

Codex review notes: model internal, reasoning high; reviewed against 8ac00c5f4977.

Label changes

Label changes:

• add issue-rating: 🦪 silver shellfish: Current issue advisory state selects this label.
• remove issue-rating: 🌊 off-meta tidepool: Current issue advisory state no longer selects this label.

Label justifications:

• P2: This is a bounded remote-connectivity improvement, not a confirmed regression or outage in the supported direct URL and SSH paths.
• impact:security: The proposal changes gateway authentication or locally executed forwarding-process behavior.
• impact:auth-provider: OAuth2-proxy access would add a gateway authentication-provider flow.

Evidence reviewed

Security concerns:

• [medium] Define the remote-authentication boundary — src/OpenClaw.Connection/CredentialResolver.cs:1
  OAuth2-proxy support needs a specified token acquisition, storage, refresh, revocation, and diagnostic-redaction model before gateway credentials can cross the connection boundary.
  Confidence: 0.93
• [medium] Avoid arbitrary command lifecycle hooks — src/OpenClaw.Connection/SshTunnelService.cs:255
  A generic pre-connect script would introduce user-controlled process execution outside the existing typed SSH tunnel lifecycle, including safe argument handling, ownership, cleanup, and failure recovery.
  Confidence: 0.96

What I checked:

• Direct-connect record boundary: The saved gateway model contains a WebSocket URL, shared/bootstrap tokens, and one typed SSH-tunnel configuration. It has no OAuth-proxy credential or generic command-lifecycle field. (src/OpenClaw.Connection/GatewayRecord.cs:12, 8ac00c5f4977)
• Controlled port-forward implementation: The SSH tunnel service invokes only the fixed ssh executable with generated arguments from typed tunnel inputs, rather than executing a user-provided pre-connect command. (src/OpenClaw.Connection/SshTunnelService.cs:255, 8ac00c5f4977)
• Current UI and runtime behavior: The direct-connect form saves only a shared token and typed SshTunnelConfig; its parser accepts SSH user, host, SSH port, remote port, and local port. The connection test proves that the manager starts that tunnel and connects through its localhost endpoint. (src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs:2873, 8ac00c5f4977)
• Documented architecture boundary: The architecture documentation assigns connection lifecycle ownership to GatewayConnectionManager and describes only managed SSH local forwarding for remote gateways. (docs/CONNECTION_ARCHITECTURE.md:27, 8ac00c5f4977)
• Repository review policy: The full repository policy assigns gateway lifecycle ownership to GatewayConnectionManager and requires explicit security, proof, and architecture review for connection and pairing changes. (AGENTS.md:49, 8ac00c5f4977)
• Maturity and history limitation: The maturity helper could not find qa/maturity-scores.yaml. Deeper history and blame needed missing promisor objects, but the checkout could not fetch them because the GitHub hostname was unavailable; available file history still identifies recent SSH-tunnel work. (src/OpenClaw.Connection/SshTunnelService.cs:8, d7d153ca5d40)

Likely related people:

• Vincent Koc: Available history shows a recent connection fix specifically for recovering saved SSH tunnels, the closest existing implementation path to a managed port-forward contract. (role: recent SSH tunnel contributor; confidence: medium; commits: d7d153ca5d40; files: src/OpenClaw.Connection/SshTunnelService.cs, src/OpenClaw.Connection/GatewayConnectionManager.cs)
• Jeremy McKeehen: Current-main history shows recent work on browser control when a shared gateway token is absent, which is adjacent to the credential-resolution boundary this request would extend. (role: recent gateway credential contributor; confidence: medium; commits: 8ac00c5f4977; files: src/OpenClaw.Connection/CredentialResolver.cs, src/OpenClaw.Tray.WinUI/Pages/ConnectionPage.xaml.cs)
• Scott Hanselman: Available history identifies recent work on connection dispatch and lifecycle invariants near the manager-owned gateway path. (role: recent connection lifecycle contributor; confidence: low; commits: 15ed439dc5a3; files: src/OpenClaw.Connection/GatewayConnectionManager.cs)

How this review workflow works

• 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.

[xrow]

I looked at the issue again. Meaning the device flow. The OAuth2-proxy is nice, but the generic command lifecycle hook is needed as a must to pass in a secure way.