mirror of
https://github.com/openclaw/openclaw.git
synced 2026-07-10 01:03:54 +00:00
f7d7148cf0
Source-grounded rewrite of 529 published docs pages with per-unit information-loss verification: 1,713 factual corrections cited to src/**, generated surfaces regenerated, frontmatter titles preserved for i18n, release notes pages untouched. All docs gates green. Closes #100141
45 lines
1.9 KiB
Markdown
45 lines
1.9 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.
|
|
|
|
## 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)
|