openclaw/docs/platforms/mac/webchat.md

summary, read_when, title

summary	read_when	title
How the mac app embeds the gateway WebChat and how to debug it	Debugging mac WebChat view or loopback port	WebChat (macOS)

The macOS menu bar app embeds the WebChat UI as a native SwiftUI view. It connects to the Gateway and defaults to the primary session for the selected agent (main, or global when session.scope is global), with a session switcher for other sessions.

• Local mode: connects directly to the local Gateway WebSocket.
• Remote mode: forwards the Gateway control port over SSH and uses that tunnel as the data plane.

Launch and debugging

• Manual: Lobster menu -> "Open Chat".

• Auto-open for testing:

  dist/OpenClaw.app/Contents/MacOS/OpenClaw --chat
  

  (--webchat is accepted as a legacy alias.)

• Logs: ./scripts/clawlog.sh (subsystem ai.openclaw, category WebChatSwiftUI).

How it is wired

• Data plane: Gateway WS methods chat.history, chat.send, chat.abort, chat.inject, and events chat, agent, presence, tick, health.
• chat.history returns a display-normalized transcript: inline directive tags are stripped from visible text, plain-text tool-call XML payloads (<tool_call>, <function_call>, <tool_calls>, <function_calls>, including truncated blocks) and leaked model control tokens are stripped, pure silent-token assistant rows such as exact NO_REPLY/no_reply are omitted, and oversized rows can be replaced with a truncated placeholder.
• Session: defaults to the primary session as above; the UI can switch between sessions.
• Onboarding uses a dedicated session to keep first-run setup separate.

Security surface

• Remote mode forwards only the Gateway WebSocket control port over SSH.

Known limitations

• The UI is optimized for chat sessions, not a full browser sandbox.

Related

• WebChat
• macOS app