openclaw-openclaw/docs/platforms/mac/webchat.md at main

mirror of https://github.com/openclaw/openclaw.git synced 2026-07-06 19:32:58 +08:00

Files

Peter Steinberger d537139521 feat(macos): adopt the shared read-only chat transcript cache (#100275 )

* feat(macos): adopt shared read-only chat transcript cache

Cache-first cold open for the macOS chat window/panel: the last known
transcript and session list paint immediately from the shared SQLite
transcript cache, then live gateway history replaces them wholesale.
Recent chats stay browsable read-only while the gateway is unreachable;
sending remains gated by connection state.

- Wires OpenClawChatSQLiteTranscriptCache into WebChatSwiftUIWindowController;
  DB at ~/Library/Application Support/OpenClaw/chat-cache.sqlite.
- Gateway identity (MacChatTranscriptCache.gatewayID), derivable offline:
  local keys on the canonical gateway state dir; remote/direct keys on the
  full canonical URL (scheme, host, resolved port, percent-encoded
  path/query); remote/ssh keys on the SSH target plus the resolved remote
  gateway port, mirroring the tunnel port resolution. Unconfigured mode
  gets no cache.
- macOS file protection: no per-file Data Protection classes; iOS-only
  attribute stays gated behind #if os(iOS) in the shared store, and the
  per-user container plus FileVault protect at rest.
- Onboarding chat stays uncached (transient guided setup session).

Part of #100194

* feat(macos): wire the offline command outbox into chat windows

* style(macos): fix orphaned doc comment; regenerate docs map

* style(macos): doc-comment lint fix; regenerate docs map on current main

2026-07-06 05:57:16 +01:00

2.2 KiB

Raw Permalink 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), 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.
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.

2.2 KiB Raw Permalink Blame History

Launch and debugging

How it is wired

Security surface

Known limitations

Related

2.2 KiB

Raw Permalink Blame History