WebChat (Gateway WebSocket UI)
Status: the macOS/iOS SwiftUI chat UI talks directly to the Gateway WebSocket.What it is
- A native chat UI for the gateway (no embedded browser and no local static server).
- Uses the same sessions and routing rules as other channels.
- Deterministic routing: replies always go back to WebChat.
Quick start
- Start the gateway.
- Open the WebChat UI (macOS/iOS app) or the web client at
/v2/client/(the default chat surface in a browser). - Ensure gateway auth is configured (required by default, even on loopback).
How it works (behavior)
- The UI connects to the Gateway WebSocket and uses
chat.history,chat.send, andchat.inject. chat.historyis bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with[chat.history omitted: message too large]. Oversized tool calls and tool results keep their call id, tool name and error flag, with only the oversized arguments or output replaced by a marker, or left out when only the bare identities fit the size cap. An entry whose identities alone exceed the cap comes back as several consecutive placeholder rows.chat.injectappends an assistant note directly to the transcript and broadcasts it to the UI (no agent run).- Aborted runs can keep partial assistant output visible in the UI.
- An aborted run’s partial assistant output is saved to transcript history exactly once, as an assistant message with
stopReason: "aborted". The run saves it itself while it stops; theabortedevent and the answer tochat.abortcome only once that is done, so a re-read ofchat.historyon the event already has the partial. Gateway writes the partial itself (withopenclawAbortmetadata, before the event) only for runs that have no embedded agent run. - History is always fetched from the gateway (no local file watching).
- If the gateway is unreachable, WebChat is read-only.
Console agents tools panel
- The console’s Agents → Tools panel (Control UI v2: Configure → Agents → Tools tab)
fetches a runtime catalog via
tools.catalogand labels each tool ascoreorplugin:<id>(plusoptionalfor optional plugin tools). - If
tools.catalogis unavailable, the panel falls back to a built-in static list. - The panel edits profile and override config, but effective runtime access still follows policy
precedence (
allow/deny, per-agent and provider/channel overrides).
Remote use
- Remote mode tunnels the gateway WebSocket over SSH/Tailscale.
- You do not need to run a separate WebChat server.
Configuration reference (WebChat)
Full configuration: Configuration Channel options:- No dedicated
webchat.*block. WebChat uses the gateway endpoint + auth settings below.
gateway.port,gateway.bind: WebSocket host/port.gateway.auth.mode,gateway.auth.token,gateway.auth.password: WebSocket auth (token/password).gateway.auth.mode: "trusted-proxy": reverse-proxy auth for browser clients (see Trusted Proxy Auth).gateway.remote.url,gateway.remote.token,gateway.remote.password: remote gateway target.session.*: session storage and main key defaults.