Configure OpenClaw WebChat: Native Gateway UI Setup

Ever spent hours fighting with a web-based chat interface that just won’t sync correctly with your backend? It’s a common headache when you’re trying to build something that feels responsive and reliable.

What it is

WebChat is a native SwiftUI chat UI for macOS and iOS that talks directly to the Gateway WebSocket. You won’t find any embedded browsers or local static servers here. It uses the same sessions and routing rules as your other channels, which means routing is deterministic—your replies always go back to WebChat.

Quick start

Getting started is simple and direct:

1. Start the gateway.
2. Open the WebChat UI (macOS/iOS app) or the Control UI chat tab.
3. Ensure gateway auth is configured. This is required by default, even if you are on a loopback connection.

How it works (behavior)

The UI connects to the Gateway WebSocket and uses chat.history, chat.send, and chat.inject. To keep things stable, chat.history is bounded. The Gateway might truncate long text fields and omit heavy metadata, or it might replace oversized entries with a [chat.history omitted: message too large] placeholder.

If you use chat.inject, it appends an assistant note directly to the transcript and broadcasts it to the UI without an agent run. If a run is aborted, any partial assistant output stays visible in the UI. The Gateway saves this partial text into the transcript history if buffered output exists and marks those entries with abort metadata. You’ll always fetch history from the gateway, as there is no local file watching. If the gateway is unreachable, WebChat stays in read-only mode.

Control UI agents tools panel

The Control UI /agents Tools panel gives you two separate views:

• Available Right Now uses tools.effective(sessionKey=...). It shows what the current session can actually use at runtime, including core or plugin tools and channel-owned tools.
• Tool Configuration uses tools.catalog and focuses on profiles and overrides, plus catalog semantics.

Runtime availability is session-scoped. If you switch sessions on the same agent, the Available Right Now list can change. The config editor doesn’t guarantee runtime availability; effective access still follows policy precedence like allow/deny rules and per-agent or provider/channel overrides.

Remote use

For remote setups, you can tunnel the gateway WebSocket over SSH or Tailscale. You don’t need to run a separate WebChat server to make this work.

Configuration reference (WebChat)

Full configuration: Configuration

WebChat options:

• gateway.webchat.chatHistoryMaxChars: maximum character count for text fields in 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 maxChars can also be sent by the client to override this default for a single chat.history call.

Related global options:

• `gateway.port