mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-10 18:16:12 +00:00
d537139521
* 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
46 lines
2.2 KiB
Markdown
46 lines
2.2 KiB
Markdown
---
|
|
summary: "How the mac app embeds the gateway WebChat and how to debug it"
|
|
read_when:
|
|
- Debugging mac WebChat view or loopback port
|
|
title: "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:
|
|
|
|
```bash
|
|
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.
|
|
|
|
## Related
|
|
|
|
- [WebChat](/web/webchat)
|
|
- [macOS app](/platforms/macos)
|