> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.zhcndoc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# WebChat（macOS）

macOS 菜单栏应用将 WebChat UI 作为原生 SwiftUI 视图嵌入。它连接到 Gateway，并默认使用所选 agent 的主会话（`main`，或者当 `session.scope` 为 `global` 时使用 `global`）。

完整的聊天窗口是一个原生分栏视图：

* **Sessions sidebar**: 可搜索的会话列表，包含置顶、gateway 支持的分组以及最近使用等区段。生成的子会话会在各区段内嵌套显示在其父会话下方；折叠的父会话会汇总正在运行、失败和未读的后代会话。上下文菜单支持会话信息、重命名、置顶、分叉、已读/未读、归档/恢复、复制会话键以及删除。主要的新会话操作（或 Shift-Cmd-N）会通过 `sessions.create` 立即创建；其旁边的选项弹出层可以选择 agent，并请求一个受管理的 worktree，以及可选的基础 ref。
* **Window toolbar**: 上下文用量环（token 和会话费用，以及一个紧凑操作）、模型控制项，以及会话操作菜单。模型按提供方分组，默认提供方排在最前，而已置顶和最近使用的模型保持在顶部。控制项可以继承或覆盖模型的思考级别、选择工具调用详细程度，并切换 Fast 响应。菜单可以重命名或分叉当前会话，并更新其置顶、已读或归档状态。**Sessions…**（Shift-Cmd-S）会打开 Active/Archived 管理器，用于 gateway 搜索、分组管理、会话检查、重命名、置顶、归档和恢复。选择模式可对多个活跃会话执行置顶、取消置顶、归档或删除，同时保持各个失败项可见。独立的菜单勾选项用于显示或隐藏助手推理和工具活动；这两项默认开启，并会在跨次启动之间记住。
* **Transcript and composer**: 助手消息以带头像的纯文本形式渲染，用户消息则显示为强调色气泡。待处理的 agent 问题会以原生卡片形式渲染，支持单选或多选选项、自由文本 **Other** 回答、到期倒计时以及共享终端状态。空聊天会提供桌面起始提示。输入 `/` 会打开由 `commands.list` 支持的斜杠命令自动补全，并支持方向键/Tab/回车/Escape 键盘导航。右键点击消息可复制其可见 Markdown，而不会包含隐藏的推理内容。被截断的助手消息还提供 **Open Full Message**，可加载一个可选择文本的 Markdown 阅读器。使用 **Listen** 可通过 gateway TTS 并带有本地语音回退。
* **Voice controls**: 撰写框可以启动或停止现有的 macOS Talk Mode，而不会替换其菜单栏浮层。Talk Mode 激活时，撰写框会显示其监听/思考/说话状态、实时音频活动以及可展开的滚动转录。右键点击 Talk 按钮可选择 **System Default** 或已连接的麦克风；这与 Voice Wake 和按住说话所使用的麦克风选择相同。如果所选麦克风断开连接，当前 Talk 会话会回退到系统默认麦克风，并在下次 Talk Mode 启动时再次尝试该选择。另一个麦克风操作会在 Talk Mode 不占用音频采集时录制语音笔记。

从菜单栏锚定的紧凑聊天面板保持紧凑的单栏布局，并在同一行内提供相同的模型、思考、详细程度和 Fast 控制项，同时还包含起始提示、Talk Mode、语音笔记和 Listen。助手推理和工具活动在这个紧凑界面中仍然保持隐藏。

## 多个 Gateway 窗口

打开 **设置 → Gateways** 可添加或移除可复用的 Gateway 配置文件。每个配置文件都包含一个私有网络的 `ws://` 或安全的 `wss://` 端点，以及其可选的令牌或密码；凭据存储在 macOS 钥匙串中。安全配置文件会保留各自基于系统信任的首次使用证书绑定策略，并且不会从主 Gateway 继承 `gateway.remote.tlsFingerprint`。仪表板窗口会强制执行相同的已保存配置文件绑定策略。移除配置文件还会关闭其已打开的窗口并关闭其次级连接。

选择 **文件 → 新建 Gateway 窗口…** 或按 Cmd-N，然后选择这些已保存配置文件之一。选择器会记住最近使用的配置文件。每次选择都会创建一个新的独立窗口，因此同一个 Gateway 可以出现在多个窗口中，并具有不同的活动会话和导航状态。

每个已保存配置文件拥有一个共享的 Gateway 连接、设备认证作用域、会话记录缓存、离线发件箱和路由租约。该配置文件的窗口会复用这些资源，同时仍可独立导航。不同配置文件的窗口会保持连接并同时运行聊天。

菜单栏应用中配置的 Gateway 仍然是 Mac 节点能力和对话模式的所有者。其他 Gateway 窗口仅限操作员使用，因此第二个 Gateway 不能在不提示的情况下重新指定全局麦克风或设备控制。监听/TTS 和普通聊天操作使用窗口自己的 Gateway 连接。

### Gateway 选择器

当 Mac 应用至少配置了两个 Gateway 时，仪表板标题栏会显示一个 Gateway 选择器。选择一个 Gateway 可在同一窗口中替换当前仪表板，按住 Option 点击可在单独的仪表板窗口中打开它。**设为主项…** 会在确认后将当前查看的已令牌认证配置文件设为 Mac 应用的主 Gateway；这会重置对话模式、画布和聊天连接。在连接期间，侧边栏底部也会显示当前 Gateway，并在其为主项时进行标记。仅密码的配置文件可以查看，但不能设为主项。

## 快速聊天栏

按下 Option-Space（⌥Space）或从菜单栏菜单中选择 **快速聊天**，即可为主会话打开一个浮动编辑器。可在 **设置 → 通用 → 快速聊天快捷键** 中使用录制器更改全局快捷键。

快速聊天会显示目标代理（头像或表情符号，代理名称作为占位符），并发送到该代理的主会话。按下 Return 确认发送后，栏会保持打开，并向下展开显示流式 Markdown 回复和最近的对话记录。栏内输入框仍然是编辑器。按 Command-Return 可发送并在完整聊天窗口中打开相同目标，按 Shift-Return 插入换行，或按 Escape 关闭整个栏和回复区域。点击外部也会将其关闭。当相关 macOS 权限缺失时，附加条带会提供 **Grant** 和 **Not now** 操作。

使用麦克风按钮可对编辑器进行语音输入。部分语音识别结果会实时替换已听写的片段，同时保留编辑器中已存在的文本。再次按下该按钮、Return 或 Escape 可停止；发送、隐藏或取消聚焦快速聊天也会释放麦克风。首次使用时会请求 macOS 麦克风和语音识别访问权限。快速聊天使用 Apple Speech，并可能使用其网络服务；只有被动的 Voice Wake 才需要设备端识别。

紧凑型模型控制项会显示目标会话当前使用的模型和推理级别。模型选择会更新该会话，因此会保留在那里，而推理选择仅应用于当前快速聊天呈现中发送的每条消息。栏隐藏时，本地选择会重置。切换代理或选择最近会话会保留显式选择，但会重新加载新目标会话底层的模型状态。

点击历史记录按钮，可从最近更新的五个会话中进行选择，或返回到 **New message to \<agent>**。选择最近的会话会发送到该准确会话，并将占位符更改为 **Reply in \<session>**。隐藏快速聊天会将这个临时目标重置为所选代理的主会话；从头像菜单切换代理也会清除它。

Command-Return 会打开接收到发送的那个代理的对话，包括会话作用域为全局时的情况。

相机按钮会打开一个菜单，提供 **Capture Window…** 或 **Capture Area…**。窗口捕获会标记每个可见窗口；区域捕获会在你拖动选区时使每个显示器变暗，并显示其实时尺寸。所选截图会连同任何输入文本作为说明一起发送给选定的代理。首次使用时会请求 macOS 屏幕录制访问权限。按 Escape、点击空白处，或在未进行有意义的区域拖动时点击，都会取消操作。

使用 document-text 按钮可从当前应用的聚焦窗口附加文本。快速聊天会将结果显示为可移除的上下文标签，而不是把捕获的文本放入编辑器；发送时会将该标签的文本追加到外发消息中，然后清除它。这需要 macOS 辅助功能权限。只要快速聊天关闭，附加文本也会被清除，因此某次呈现中的上下文不会泄露到后续发送中。

回复完成后，选择 **Paste to \<app>** 可将其可见的助手文本（不包括隐藏推理）复制到通用剪贴板，并粘贴到当前前台应用中。这需要 macOS 辅助功能权限。该操作会替换当前剪贴板内容，然后隐藏快速聊天。

可通过 **设置 → 通用 → 快速聊天** 完全禁用该功能；同一部分还包含快捷键录制器。

* **本地模式**：直接连接到本地 Gateway WebSocket。
* **远程模式**：使用已配置的直接 `ws://`/`wss://` 路由，或使用应用管理的 SSH 隧道作为数据平面。

## 启动与调试

* 手动：Lobster 菜单 -> “打开聊天”。

* 测试时自动打开：

  ```bash theme={"theme":{"light":"min-light","dark":"min-dark"}}
  dist/OpenClaw.app/Contents/MacOS/OpenClaw --chat
  ```

  （`--webchat` 作为旧版别名也可接受。）

* 日志：`./scripts/clawlog.sh`（子系统 `ai.openclaw`，类别 `WebChatSwiftUI`）。

## 它是如何连接的

* 数据平面：Gateway WS 方法 `chat.history`、`chat.message.get`、`chat.send`、`chat.abort`、`chat.inject`，以及 `question.list` 和 `question.resolve`，还有事件 `chat`、`agent`、`presence`、`tick`、`health`；问题卡片遵循 `question.requested` 和 `question.resolved` 事件，并在重新连接后从 `question.list` 刷新。
* `chat.history` 返回经过显示标准化的记录：可见文本中的行内指令标签会被剥离，纯文本工具调用 XML 负载（`<tool_call>`、`<function_call>`、`<tool_calls>`、`<function_calls>`，包括被截断的块）以及泄漏的模型控制 token 会被剥离，纯静默 token 的助手行（例如精确的 `NO_REPLY`/`no_reply`）会被省略，过大的行可能会被替换为截断占位符。
* 会话：默认使用上述主会话；UI 可以在会话之间切换。
* 会话组：`sessions.groups.list`、`sessions.groups.put`、`sessions.groups.rename` 和 `sessions.groups.delete` 负责组目录。成员关系是通过 `sessions.patch` 更新的会话 `category`。
* 未读状态：当某个会话被激活且其实时历史成功加载后，应用会清除该会话的未读标记。历史加载失败不会清除它；临时性的 patch 失败会在下次激活时重试。
* 新手引导使用一个专用会话，以便将首次运行设置与其他内容分离。
* 离线缓存：应用会为每个 Gateway 保留一个小型只读缓存，保存最近的聊天会话和记录（`~/Library/Application Support/OpenClaw/chat-cache.sqlite`）：冷启动时会立即渲染上次已知的记录，并在 Gateway 响应后刷新；在断开连接时，最近的聊天仍可浏览（在连接恢复之前发送功能保持禁用）。

## 安全部分

* 远程模式只通过 SSH 转发 Gateway WebSocket 控制端口。

## 已知限制

* 该 UI 针对聊天会话进行了优化，而不是完整的浏览器沙箱。

## 相关内容

* [WebChat](/web/webchat)
* [macOS 应用](/platforms/macos)