WebChat

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

1. Start the gateway.
2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
3. Ensure a valid gateway auth path is configured (shared-secret by default, even on loopback).

How it works (behavior)

• The UI connects to the Gateway WebSocket and uses
  text

  Copy

  chat.history
  ,
  text

  Copy

  chat.send
  , and
  text

  Copy

  chat.inject
  .
• text

  Copy

  chat.history
  is bounded for stability: Gateway may truncate long text fields, omit heavy metadata, and replace oversized entries with
  text

  Copy

  [chat.history omitted: message too large]
  .
• text

  Copy

  chat.history
  follows the active transcript branch for modern append-only session files, so abandoned rewrite branches and superseded prompt copies are not rendered in WebChat.
• Control UI coalesces duplicate in-flight submits for the same session, message, and attachments before generating a new
  text

  Copy

  chat.send
  run id; the Gateway still dedupes repeated requests that reuse the same idempotency key.
• text

  Copy

  chat.history
  is also display-normalized: runtime-only OpenClaw context, inbound envelope wrappers, inline delivery directive tags such as
  text

  Copy

  [[reply_to_*]]
  and
  text

  Copy

  [[audio_as_voice]]
  , plain-text tool-call XML payloads (including
  text

  Copy

  <tool_call>...</tool_call>
  ,
  text

  Copy

  <function_call>...</function_call>
  ,
  text

  Copy

  <tool_calls>...</tool_calls>
  ,
  text

  Copy

  <function_calls>...</function_calls>
  , and truncated tool-call blocks), and leaked ASCII/full-width model control tokens are stripped from visible text, and assistant entries whose whole visible text is only the exact silent token
  text

  Copy

  NO_REPLY
  /
  text

  Copy

  no_reply
  are omitted.
• Reasoning-flagged reply payloads (
  text

  Copy

  isReasoning: true
  ) are excluded from WebChat assistant content, transcript replay text, and audio content blocks, so thinking-only payloads do not surface as visible assistant messages or playable audio.
• text

  Copy

  chat.inject
  appends 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.
• Gateway persists aborted partial assistant text into transcript history when buffered output exists, and marks those entries with abort metadata.
• History is always fetched from the gateway (no local file watching).
• If the gateway is unreachable, WebChat is read-only.

Control UI agents tools panel

• The Control UI
  text

  Copy

  /agents
  Tools panel has two separate views:
  • Available Right Now uses
    text

    Copy

    tools.effective(sessionKey=...)
    and shows what the current session can actually use at runtime, including core, plugin, and channel-owned tools.
  • Tool Configuration uses
    text

    Copy

    tools.catalog
    and stays focused on profiles, overrides, and catalog semantics.
• Runtime availability is session-scoped. Switching sessions on the same agent can change the Available Right Now list.
• The config editor does not imply runtime availability; effective access still follows policy precedence (
  text

  Copy

  allow
  /
  text

  Copy

  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

WebChat options:

• text

  Copy

  gateway.webchat.chatHistoryMaxChars
  : maximum character count for text fields in
  text

  Copy

  chat.history
  responses. When a transcript entry exceeds this limit, Gateway truncates long text fields and may replace oversized messages with a placeholder. Per-request
  text

  Copy

  maxChars
  can also be sent by the client to override this default for a single
  text

  Copy

  chat.history
  call.

Related global options:

• text

  Copy

  gateway.port
  ,
  text

  Copy

  gateway.bind
  : WebSocket host/port.
• text

  Copy

  gateway.auth.mode
  ,
  text

  Copy

  gateway.auth.token
  ,
  text

  Copy

  gateway.auth.password
  : shared-secret WebSocket auth.
• text

  Copy

  gateway.auth.allowTailscale
  : browser Control UI chat tab can use Tailscale Serve identity headers when enabled.
• text

  Copy

  gateway.auth.mode: "trusted-proxy"
  : reverse-proxy auth for browser clients behind an identity-aware non-loopback proxy source (see Trusted Proxy Auth).
• text

  Copy

  gateway.remote.url
  ,
  text

  Copy

  gateway.remote.token
  ,
  text

  Copy

  gateway.remote.password
  : remote gateway target.
• text

  Copy

  session.*
  : session storage and main key defaults.

Related

• Control UI
• Dashboard