Add OpenClaw gateway auth, config persistence, and handshake updates by BunsDev · Pull Request #395 · OpenKnots/okcode

BunsDev · 2026-04-10T08:45:01Z

Summary

Wire the server to OpenClaw gateway auth with device identity generation, stored device token support, and modern connect handshake handling.
Persist gateway configuration in vault-backed storage and migrate existing environment-variable settings into the new config layer.
Update gateway health/test flows and related UI/contracts to understand the new protocol, error details, and session identity handling.
Remove the old Solar Witch theme wiring from the web app settings path.

Testing

Not run (no bun fmt, bun lint, or bun typecheck executed in this turn).
Added and updated gateway handshake tests for successful connect and pairing-required failure detail propagation.
Updated server-side OpenClaw gateway test coverage to validate the modern WebSocket handshake path.

- Replace legacy auth/session RPC flow with connect challenge handling - Surface gateway error details and pairing hints in diagnostics - Update contract and settings UI to show the new handshake fields

- Document planned sidebar metadata and branch picker improvements - Add design guidance for dense, inline state visibility

- Increase the width of the viewport width and height inputs - Prevent clipped values in the preview panel

- Add gateway client handshake with signed device identity - Persist encrypted gateway config, device keys, and tokens - Thread OpenClaw auth state through server and UI

- Add `OpenclawGatewayConfigLive` to the server runtime layer - Remove the Solar Witch theme definitions from the web styles

vercel · 2026-04-10T08:45:06Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
okcode-marketing	Ready	Preview	Apr 13, 2026 3:19am
v0-compute-the-platform-to-build	Ready	Preview, Open in v0	Apr 13, 2026 3:19am

Copilot

Pull request overview

This PR wires OK Code’s server and UI to a modern OpenClaw gateway authentication flow, adds vault-backed persistence for gateway configuration (including device identity + token caching), and updates handshake/health/test flows to align with the new protocol.

Changes:

Added new WS/IPC contracts + client wiring for getting/saving OpenClaw gateway config and resetting device state.
Implemented vault-encrypted persistence + migration for OpenClaw gateway config (URL, shared secret, device identity, cached device token).
Updated server/provider health checks and gateway test tooling to use the modern connect handshake shape and propagate richer error details; removed legacy Solar Witch theme CSS wiring.

Reviewed changes

Copilot reviewed 32 out of 32 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
packages/contracts/src/ws.ts	Adds WS method names + request-body schema entries for OpenClaw gateway config APIs.
packages/contracts/src/server.ts	Introduces OpenClaw gateway config schemas and expands gateway test diagnostics fields.
packages/contracts/src/providerRuntime.ts	Extends runtime event source literals for new OpenClaw event/response streams.
packages/contracts/src/ipc.ts	Extends NativeApi server surface with OpenClaw gateway config methods.
DESIGN.md	Adds a design-system reference document (incl. theme list).
apps/web/src/wsNativeApi.ts	Wires new OpenClaw gateway config RPC calls through the WS native API transport.
apps/web/src/themes.css	Removes Solar Witch theme CSS variables and leaves other premium themes intact.
apps/web/src/routes/_chat.settings.tsx	Reworks Settings UI to use server-persisted OpenClaw gateway config + reset/import flows and richer diagnostics output.
apps/web/src/routes/__root.tsx	Broadens server config update invalidation to `serverQueryKeys.all`.
apps/web/src/lib/serverReactQuery.ts	Adds query key + queryOptions for fetching OpenClaw gateway config summary.
apps/web/src/components/PreviewPanel.tsx	Minor layout tweak to viewport input widths.
apps/web/src/appSettings.ts	Removes legacy browser-local OpenClaw provider start options from app settings.
apps/server/src/wsServer.ts	Adds WS routes for OpenClaw gateway config APIs; updates test flow to resolve persisted config; publishes updated provider status on config changes.
apps/server/src/sme/Layers/SmeChatServiceLive.ts	Validates OpenClaw SME setup against persisted gateway config + provider health status.
apps/server/src/sme/Layers/SmeChatServiceLive.test.ts	Updates SME service tests with OpenClaw gateway config + ProviderHealth service stubs.
apps/server/src/sme/authValidation.ts	Updates OpenClaw setup validation to reflect shared-secret + device token + provider health signals.
apps/server/src/serverLayers.ts	Provides OpenclawGatewayConfig layer where needed; injects into OpenClaw adapter; updates SME wiring.
apps/server/src/provider/Layers/ProviderHealth.ts	Replaces OpenClaw HTTP health probing with a full gateway `connect` handshake probe and device-token persistence.
apps/server/src/persistence/vault.ts	Introduces shared AES-256-GCM vault helpers + key creation/reading logic.
apps/server/src/persistence/Services/OpenclawGatewayConfig.ts	Defines the OpenclawGatewayConfig service interface and types.
apps/server/src/persistence/Services/EnvironmentVariables.ts	Refactors env-var secret encryption to use the shared vault helpers.
apps/server/src/persistence/Migrations/021_OpenclawGatewayConfig.ts	Adds DB table for persisted OpenClaw gateway config.
apps/server/src/persistence/Migrations.ts	Registers migration 21.
apps/server/src/persistence/Layers/OpenclawGatewayConfig.ts	Implements OpenClaw gateway config persistence (vault-encrypted secret/private key/device token).
apps/server/src/openclawGatewayTest.ts	Updates gateway test runner to the modern handshake framing + richer diagnostics/hints.
apps/server/src/openclawGatewayTest.test.ts	Updates/extends tests for modern handshake success + pairing-required error detail propagation.
apps/server/src/openclaw/sessionIdentity.ts	Adds helper to normalize session identity fields coming back from gateway payloads.
apps/server/src/openclaw/protocol.ts	Adds shared protocol parsing/helpers for gateway frames, errors, and hello payload extraction.
apps/server/src/openclaw/GatewayClient.ts	Adds a gateway client implementing modern handshake (challenge wait, device signing, connect, method assertions).
apps/server/src/openclaw/deviceAuth.ts	Adds device identity generation + challenge signing for OpenClaw device auth.
.plans/sidebar-branch-enhancements.md	Adds a planned UI enhancement document referencing DESIGN.md rules.
.plans/README.md	Adds the new plan doc to the index.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

apps/server/src/openclawGatewayTest.ts

apps/server/src/provider/Layers/ProviderHealth.ts

apps/web/src/themes.css

DESIGN.md

apps/web/src/routes/_chat.settings.tsx

BunsDev · 2026-04-13T00:00:48Z

@copilot apply changes based on the comments in this thread

…, Solar Witch theme, and legacy import banner gating Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

Copilot · 2026-04-13T00:09:32Z

@copilot apply changes based on the comments in this thread

Applied all five review comments in commits 6de978d and 8d1b6fe:

openclawGatewayTest.ts — buildConnectParams now generates a temporary device identity, waits for the connect.challenge nonce/ts, signs it via signOpenclawDeviceChallenge, and sends auth: { token } + a device payload matching the protocol used by OpenclawGatewayClient. Added explicit nonce validation that fails the handshake step early with a clear message if the challenge is malformed.
ProviderHealth.ts — Replaced Effect.orElseSucceed(() => null) with Effect.match to return status: "error", authStatus: "unknown", and a descriptive message when the config cannot be read (vault key mismatch, corrupted row, etc.), clearly distinguishing it from "URL not configured".
themes.css — Restored the Solar Witch CSS theme block (light + dark variants).
DESIGN.md — No change needed; Solar Witch remains in the table now that the CSS is restored.
_chat.settings.tsx — canImportLegacyOpenclawSettings now gates on openclawGatewayConfigQuery.isSuccess to prevent the legacy import banner from flashing during load and potentially overwriting persisted gateway config.

BunsDev · 2026-04-13T00:58:06Z

@copilot apply changes based on the comments in this thread

Copilot · 2026-04-13T00:59:03Z

@copilot apply changes based on the comments in this thread

All five changes are already applied in commits 6de978d and 8d1b6fe from the previous session — no additional work needed.

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

* Add OpenClaw gateway auth and device token persistence - Add gateway client handshake with signed device identity - Persist encrypted gateway config, device keys, and tokens - Thread OpenClaw auth state through server and UI * Wire in Openclaw gateway config and drop Solar Witch theme - Add `OpenclawGatewayConfigLive` to the server runtime layer - Remove the Solar Witch theme definitions from the web styles * Apply reviewer feedback: fix connect handshake, config error handling, Solar Witch theme, and legacy import banner gating Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> * Add nonce validation in test handshake for clearer error reporting Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> * Update DESIGN.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/web/src/themes.css Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Route Claude chats through provider runtime - Remove Anthropic env-based chat handling - Validate Claude against provider health and new provider options - Update migrations and theme docs --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 32 out of 32 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

apps/web/src/themes.css

apps/web/src/routes/_chat.settings.tsx

Copilot · 2026-04-13T02:15:15Z

apps/server/src/wsServer.ts

+        const result = yield* testOpenclawGateway({
+          gatewayUrl: resolvedConfig.gatewayUrl,
+          password: body.password ?? resolvedConfig.sharedSecret,
+        });


password: body.password ?? resolvedConfig.sharedSecret will treat an empty string password override ("") as intentional and override the stored shared secret, even though resolveForConnect ignores empty strings. This can cause tests/clients that send an empty string to unexpectedly fail auth. Normalize before passing to the test (e.g., use body.password?.trim() and fall back to resolvedConfig.sharedSecret when blank).

@copilot apply changes based on this feedback

apps/server/src/wsServer.ts

Copilot · 2026-04-13T02:15:15Z

packages/contracts/src/server.ts

+export const SaveOpenclawGatewayConfigInput = Schema.Struct({
+  gatewayUrl: TrimmedNonEmptyString,
+  sharedSecret: Schema.optional(Schema.String),
+  clearSharedSecret: Schema.optional(Schema.Boolean),
+});


SaveOpenclawGatewayConfigInput allows both sharedSecret and clearSharedSecret to be set at the same time, which is ambiguous for API consumers. Consider making these mutually exclusive at the schema level (e.g., a union of {gatewayUrl, sharedSecret} | {gatewayUrl, clearSharedSecret:true}) or explicitly documenting/validating precedence.

@copilot apply changes based on this feedback

apps/server/src/persistence/Layers/OpenclawGatewayConfig.ts

Copilot · 2026-04-13T02:15:16Z

apps/server/src/provider/Layers/ProviderHealth.ts

+      getStatuses: Effect.all(
+        [checkCodexProviderStatus, checkClaudeProviderStatus, checkOpenClawProviderStatus],
+        {
+          concurrency: "unbounded",
+        },


ProviderHealthLive.getStatuses now runs all provider health checks on every call. This includes spawning CLI processes and performing an OpenClaw WebSocket handshake, which can be costly and may run frequently (e.g., on config updates). Consider caching results with a short TTL / memoizing in a Ref, or running checks in a background fiber and serving the latest snapshot to avoid repeated expensive work.

@copilot apply changes based on this feedback

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

BunsDev · 2026-04-13T02:49:07Z

@copilot apply changes based on the comments in this thread

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/fd5aa06f-86c4-4710-b12f-0d87f6a9c8f8 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

* Switch Openclaw gateway test to modern connect handshake - Replace legacy auth/session RPC flow with connect challenge handling - Surface gateway error details and pairing hints in diagnostics - Update contract and settings UI to show the new handshake fields * Add sidebar and branch picker enhancement plan (#391) - Document planned sidebar metadata and branch picker improvements - Add design guidance for dense, inline state visibility * Widen preview viewport inputs (#393) - Increase the width of the viewport width and height inputs - Prevent clipped values in the preview panel * Add OpenClaw gateway auth and device token persistence - Add gateway client handshake with signed device identity - Persist encrypted gateway config, device keys, and tokens - Thread OpenClaw auth state through server and UI * Wire in Openclaw gateway config and drop Solar Witch theme - Add `OpenclawGatewayConfigLive` to the server runtime layer - Remove the Solar Witch theme definitions from the web styles * Apply reviewer feedback: fix connect handshake, config error handling, Solar Witch theme, and legacy import banner gating Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> * Add nonce validation in test handshake for clearer error reporting Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> * Update DESIGN.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/web/src/themes.css Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/web/src/themes.css Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/web/src/routes/_chat.settings.tsx Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/server/src/persistence/Layers/OpenclawGatewayConfig.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update apps/server/src/wsServer.ts Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * chore(deps): bump @pierre/diffs, lucide-react, oxfmt, oxlint, turbo Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/fd5aa06f-86c4-4710-b12f-0d87f6a9c8f8 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> * Polish PR 395 merge resolution Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/de1775b2-7460-4cb0-b19c-512a47ed8242 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com> --------- Co-authored-by: Val Alexander <bunsthedev@gmail.com> Co-authored-by: Val Alexander <68980965+BunsDev@users.noreply.github.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

BunsDev and others added 5 commits April 10, 2026 02:07

Switch Openclaw gateway test to modern connect handshake

03025fd

- Replace legacy auth/session RPC flow with connect challenge handling - Surface gateway error details and pairing hints in diagnostics - Update contract and settings UI to show the new handshake fields

Add sidebar and branch picker enhancement plan (#391)

fd9ea3a

- Document planned sidebar metadata and branch picker improvements - Add design guidance for dense, inline state visibility

Widen preview viewport inputs (#393)

123ac72

- Increase the width of the viewport width and height inputs - Prevent clipped values in the preview panel

Add OpenClaw gateway auth and device token persistence

e085a19

- Add gateway client handshake with signed device identity - Persist encrypted gateway config, device keys, and tokens - Thread OpenClaw auth state through server and UI

Wire in Openclaw gateway config and drop Solar Witch theme

3d64ed6

- Add `OpenclawGatewayConfigLive` to the server runtime layer - Remove the Solar Witch theme definitions from the web styles

vercel bot deployed to Preview – okcode-marketing April 10, 2026 08:45 View deployment

github-actions bot added size:XXL vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. labels Apr 10, 2026

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 10, 2026 08:45 View deployment

BunsDev requested a review from Copilot April 11, 2026 04:47

Copilot started reviewing on behalf of BunsDev April 11, 2026 04:48 View session

Copilot AI reviewed Apr 11, 2026

View reviewed changes

Copilot started work on behalf of BunsDev April 13, 2026 00:00 View session

vercel bot deployed to Preview – okcode-marketing April 13, 2026 00:07 View deployment

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 13, 2026 00:07 View deployment

Add nonce validation in test handshake for clearer error reporting

8d1b6fe

Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/9615af9c-7cb2-409b-93c1-541b906a4a67 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

vercel bot deployed to Preview – okcode-marketing April 13, 2026 00:09 View deployment

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 13, 2026 00:09 View deployment

Copilot finished work on behalf of BunsDev April 13, 2026 00:10

Copilot started work on behalf of BunsDev April 13, 2026 00:58 View session

BunsDev and others added 2 commits April 12, 2026 19:59

Update DESIGN.md

ff500cd

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update apps/web/src/themes.css

8c8ad63

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

vercel bot deployed to Preview – okcode-marketing April 13, 2026 00:59 View deployment

Copilot finished work on behalf of BunsDev April 13, 2026 00:59

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 13, 2026 00:59 View deployment

BunsDev requested a review from Copilot April 13, 2026 02:10

Copilot started reviewing on behalf of BunsDev April 13, 2026 02:11 View session

BunsDev mentioned this pull request Apr 13, 2026

Resolve PR #395 conflicts and integrate pr-365-merge fixes #424

Merged

Copilot AI reviewed Apr 13, 2026

View reviewed changes

Copilot started work on behalf of BunsDev April 13, 2026 02:23 View session

Copilot finished work on behalf of BunsDev April 13, 2026 02:24

BunsDev and others added 2 commits April 12, 2026 21:48

Update apps/web/src/themes.css

14becd4

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update apps/web/src/routes/_chat.settings.tsx

d3f0dec

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot started work on behalf of BunsDev April 13, 2026 02:49 View session

BunsDev and others added 2 commits April 12, 2026 21:49

Update apps/server/src/persistence/Layers/OpenclawGatewayConfig.ts

14c95f7

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Update apps/server/src/wsServer.ts

8ec57a5

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

vercel bot deployed to Preview – okcode-marketing April 13, 2026 02:49 View deployment

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 13, 2026 02:49 View deployment

Copilot stopped work on behalf of BunsDev due to an error April 13, 2026 03:00
The session was cancelled by the user.

Copilot started work on behalf of BunsDev April 13, 2026 03:00 View session

chore(deps): bump @pierre/diffs, lucide-react, oxfmt, oxlint, turbo

a63c46c

Agent-Logs-Url: https://github.com/OpenKnots/okcode/sessions/fd5aa06f-86c4-4710-b12f-0d87f6a9c8f8 Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

vercel bot deployed to Preview – okcode-marketing April 13, 2026 03:18 View deployment

vercel bot deployed to Preview – v0-compute-the-platform-to-build April 13, 2026 03:19 View deployment

Copilot finished work on behalf of BunsDev April 13, 2026 03:19

Copilot AI added a commit that referenced this pull request Apr 13, 2026

Merge PR #395 and resolve conflicts

2337a0e

Co-authored-by: BunsDev <68980965+BunsDev@users.noreply.github.com>

Copilot AI mentioned this pull request Apr 13, 2026

Resolve PR #395 merge conflicts against main #428

Merged

4 tasks

BunsDev closed this Apr 13, 2026

Uh oh!

Conversation

BunsDev commented Apr 10, 2026

Summary

Testing

Uh oh!

vercel bot commented Apr 10, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

BunsDev commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

BunsDev commented Apr 13, 2026

Uh oh!

Copilot AI commented Apr 13, 2026

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

BunsDev Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

BunsDev Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

BunsDev Apr 13, 2026

Choose a reason for hiding this comment

Uh oh!

BunsDev commented Apr 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

vercel bot commented Apr 10, 2026 •

edited

Loading