clawdbot/docs/webchat.md

summary, read_when

summary	read_when
Loopback WebChat static host and Gateway WS usage for chat UI	Debugging or configuring WebChat access

WebChat (SwiftUI + Gateway WS)

Updated: 2025-12-17

What it is

• A native SwiftUI chat UI (macOS app / iOS) that talks directly to the Gateway WebSocket.
• No embedded browser/WKWebView and no bundled static WebChat HTTP server.
• Data plane is entirely Gateway WS: methods chat.history, chat.send, chat.abort; events chat, agent, presence, tick, health.

How it connects

• The UI performs Gateway WS connect, then calls chat.history for bootstrap and chat.send for sends; it listens to chat/agent/presence/tick/health events.
• History comes from the Gateway via chat.history (no local session file watching).
• If Gateway WS is unavailable, the UI surfaces the error and blocks send.

Remote use

• In remote mode, the macOS app forwards the Gateway WebSocket control port via SSH and uses that for the SwiftUI chat UI.
• You generally should not need to manage tunnels manually; see RemoteTunnelManager in the app.

Config

• WebChat does not have a separate HTTP port/config anymore.
• Gateway WS is configured via the app’s gateway endpoint settings (GatewayEndpointStore) or clawdbot gateway --port when running locally.

Failure handling

• UI errors when the Gateway handshake fails or the WS drops.
• No fallback transport; the Gateway WS is required.

Dev notes

• macOS glue: apps/macos/Sources/Clawdbot/WebChatSwiftUI.swift + apps/macos/Sources/Clawdbot/WebChatManager.swift.
• Remote tunnel helper: apps/macos/Sources/Clawdbot/RemotePortTunnel.swift.