openclaw/docs/platforms/mac/webchat.md at 4bf70be01a21bbec9dc4dbf60ebaeffb48ef74dd

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-09 16:53:55 +00:00

Files

Peter Steinberger bb658d0a6d feat(macos): redesign chat window as native shell with sessions sidebar, toolbar pickers, slash commands, and context usage (#101103 )

* feat(chat-ui): native macOS chat window shell with sessions sidebar, context usage, and slash commands

* feat(macos): host redesigned chat window shell and complete gateway chat transport

* fix(chat-ui): gate slash panel on catalog support and register window shell shortcuts outside menus

* fix(chat-ui): make sidebar selection tags optional and sync programmatic composer text into the focused NSTextView

* fix(macos): track in-window session switches for chat window reuse

* fix(chat-ui): re-bootstrap in place when deleting the active main session

* docs(macos): describe the redesigned native chat window

* fix(macos): scope bare global session RPCs to the routing default agent

* style(chat-ui): restore blank line between rebased helpers

* fix(macos): scope selected global session actions

* fix(macos): refresh chat routing identity

* fix(chat-ui): hide delete for main sessions

* fix(macos): remove duplicate session patch path

* fix(chat-ui): resolve sidebar session aliases

* fix(chat-ui): isolate sidebar alias resolution

* fix(chat-ui): reconcile active session aliases

* fix(chat-ui): prefer selected session aliases

* chore(i18n): refresh chat window inventory

* fix(chat-ui): return sidebar filter result

* refactor(chat-ui): split session actions

2026-07-07 02:06:10 +01:00

3.1 KiB

Raw Blame History

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).

The full chat window is a native split view:

Sessions sidebar: searchable session list with pinned and recent sections, unread indicators, and context menus for pin/unpin, copy session key, and delete. A toolbar button (or Cmd-N) creates a real new session via sessions.create.
Window toolbar: context-usage ring (tokens and session cost, with a compact action), thinking-level picker, model picker, and a session actions menu (new session, refresh, copy session key, export transcript, compact, clear history).
Transcript and composer: assistant messages render as plain text with an avatar, user messages as accent bubbles. Typing / opens slash-command autocomplete backed by commands.list, with arrow/Tab/Return/Escape keyboard navigation. Right-click a message to copy it.

The anchored quick-chat panel from the menu bar keeps the compact single-column layout with inline pickers.

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.
Offline cache: the app keeps a small read-only cache of recent chat sessions and transcripts per gateway (~/Library/Application Support/OpenClaw/chat-cache.sqlite): cold opens paint the last known transcript immediately and refresh once the Gateway responds, and recent chats stay browsable while disconnected (sending stays disabled until the connection is back).

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.

3.1 KiB Raw Blame History

Launch and debugging

How it is wired

Security surface

Known limitations

Related

3.1 KiB

Raw Blame History