# WebChat（macOS） > macOS 应用如何嵌入 Gateway 网关 WebChat，以及如何进行调试 - 网址：https://funcoding.ai/agents/openclaw/platforms/mac/webchat/ - 来源：OpenClaw 官方文档原文（中文），MIT 许可，同步于 2026-10-11 - 官方原文：https://docs.openclaw.ai/zh-CN/platforms/mac/webchat --- macOS 菜单栏应用将 WebChat UI 作为原生 SwiftUI 视图嵌入。它连接到 Gateway 网关，并默认使用所选智能体的主会话（`main`；当 `session.scope` 为 `global` 时，则为 `global`）。 完整聊天窗口采用原生分栏视图： - **会话侧边栏**：可搜索的会话列表，包含已固定、Gateway 网关支持的分组和最近使用部分。在每个部分中，派生的子会话嵌套在其父会话下；折叠的父会话会汇总正在运行、失败和未读的后代会话。上下文菜单支持查看会话信息、重命名、固定、分叉、标记已读/未读、归档/恢复、复制会话键和删除。主新建会话操作（或 Shift-Cmd-N）通过 `sessions.create` 立即创建会话；相邻的选项弹出框可选择智能体，并请求一个可选指定基础引用的托管工作树。 - **窗口工具栏**：上下文用量环（令牌和会话成本，并带有紧凑操作）、模型控件和会话操作菜单。模型按提供商分组，默认提供商排在最前，而已固定和最近使用的模型始终置顶。控件可继承或覆盖模型的思考级别、选择工具调用的详细程度，并切换快速响应。菜单可重命名或分叉当前会话，并更新其固定、已读或归档状态。**会话…**（Shift-Cmd-S）会打开“活跃/已归档”管理器，用于 Gateway 网关搜索、分组管理、会话检查、重命名、固定、归档和恢复。选择模式可对多个活跃会话执行固定、取消固定、归档或删除，同时保持各项失败清晰可见。单独的菜单勾选项可显示或隐藏助手推理和工具活动；两者默认开启，并会在重新启动后保留设置。 - **对话记录和输入框**：助手消息以带头像的纯文本呈现，用户消息以强调色气泡呈现。待处理的智能体问题以原生卡片呈现，支持单选或多选选项、自由文本的**其他**答案、到期倒计时和共享终止状态。空白聊天会提供桌面端入门提示。输入 `/` 会打开由 `commands.list` 支持的斜杠命令自动补全，并可使用方向键/Tab/Return/Escape 进行键盘导航。右键单击消息可复制其可见 Markdown，不包含隐藏的推理内容。被截断的助手消息还会提供**打开完整消息**，用于加载可选择文本的 Markdown 阅读器。使用**朗读**可通过 Gateway 网关进行 TTS，并在不可用时回退到本地语音。 - **语音控件**：输入框可以启动或停止现有的 macOS Talk 模式，而不会取代其菜单栏浮层。Talk 模式处于活动状态时，输入框会显示其聆听、思考和说话状态、实时音频活动，以及可展开的滚动对话记录。右键单击 Talk 按钮可选择**系统默认**或已连接的麦克风；Voice Wake 和按住说话功能也使用同一麦克风选择。如果所选麦克风断开连接，活动的 Talk 会话将回退到系统默认麦克风，并在下次启动 Talk 模式时再次尝试使用该选择。当 Talk 模式未占用音频采集时，可通过单独的麦克风操作录制语音留言。 菜单栏中的锚定式紧凑聊天面板保留紧凑的单栏布局，在行内提供相同的模型、思考、详细程度和快速响应控件，并包含入门提示、Talk 模式、语音留言和朗读功能。助手推理和工具活动在此紧凑界面中保持隐藏。 ## 多个 Gateway 网关窗口 打开**设置 → Gateway 网关**以添加或移除可重复使用的 Gateway 网关配置文件。每个 配置文件包含一个专用网络 `ws://` 或安全的 `wss://` 端点及其 可选令牌或密码；凭据存储在 macOS 钥匙串中。 安全配置文件各自维护首次使用时受系统信任机制保护的证书固定信息， 并且不会从主 Gateway 网关继承 `gateway.remote.tlsFingerprint`。 移除配置文件还会关闭其已打开的窗口，并终止其次要 连接。 选择**文件 → 新建 Gateway 网关窗口…**或按 Cmd-N，然后选择其中一个 已保存的配置文件。选择器会记住最近使用的配置文件。每次 选择都会创建一个新的独立窗口，因此同一个 Gateway 网关可以出现在 多个窗口中，并分别具有不同的活动会话和导航状态。 每个已保存的配置文件拥有一个共享的 Gateway 网关连接、设备身份验证范围、 对话记录缓存、离线发件箱和路由租约。该配置文件的窗口 会复用这些资源，同时保持导航相互独立。使用 不同配置文件的窗口会保持连接并同时运行聊天。 菜单栏应用所配置的 Gateway 网关仍负责 Mac 节点 能力和 Talk 模式。其他 Gateway 网关窗口仅供操作员使用，因此 第二个 Gateway 网关无法在未提示的情况下重新指定全局麦克风或设备控件。 朗读/TTS 和普通聊天操作使用窗口自身的 Gateway 网关连接。 ## 快速聊天栏 按 Option-Space（⌥Space）或从菜单栏菜单中选择**快速聊天**，可为主会话打开浮动输入框。可使用**设置 → 通用 → 快速聊天快捷键**中的录制器更改全局快捷键。 快速聊天会显示目标智能体（头像或表情符号，并以智能体名称作为占位文本），并将消息发送到该智能体的主会话。Return 接受发送后，聊天栏会保持打开，并向下展开以显示流式 Markdown 回复和最近的对话记录。聊天栏输入区域仍作为输入框。按 Command-Return 可发送消息并在完整聊天窗口中打开同一目标，按 Shift-Return 可换行，按 Escape 可关闭整个聊天栏和回复区域。单击外部区域也会将其关闭。如果缺少相关的 macOS 权限，附加的信息条会提供**授予**和**暂不**操作。 使用麦克风按钮可向输入框听写。部分语音识别结果会实时替换听写范围，同时保留输入框中已有的文本。再次按下该按钮、Return 或 Escape 可停止；发送、隐藏快速聊天或使其失去焦点也会释放麦克风。首次使用时会请求 macOS 麦克风和语音识别访问权限。快速聊天使用 Apple 语音识别，并可能使用其网络服务；只有被动 Voice Wake 要求设备端识别。 紧凑模型控件会显示目标会话当前的模型和推理级别。模型选择会更新该会话，因此会在其中持久保留；推理选择则仅应用于从当前快速聊天界面发送的每条消息。聊天栏隐藏时，本地选择会重置。切换智能体或选择最近的会话会保留显式选择，但会重新加载新目标会话的底层模型状态。 单击历史记录按钮可从最近更新的五个会话中选择，或返回**发送新消息给 <agent>**。选择最近会话后，消息将发送到该确切会话，并将占位文本更改为**在 <session> 中回复**。隐藏快速聊天会将此临时目标重置为所选智能体的主会话；从头像菜单切换智能体也会将其清除。 Command-Return 会打开接收该消息的智能体的对话，包括会话范围为全局时。 相机按钮会打开一个菜单，其中包含**捕获窗口…**或**捕获区域…**。窗口捕获会为每个可见窗口添加标签；区域捕获会在拖动选择区域时调暗每个显示器，并显示其实时尺寸。所选屏幕截图会连同任何输入的文本作为说明发送给所选智能体。首次使用时会请求 macOS 屏幕录制访问权限。按 Escape、单击空白区域或未有效拖出区域便单击，都会取消操作。 使用文本文档按钮可附加当前聚焦应用中聚焦窗口的文本。快速聊天会将结果显示为可移除的上下文标签，而不是将捕获的文本放入输入框；发送时会将标签中的文本追加到传出消息，然后将其清除。此功能需要 macOS 辅助功能权限。每当快速聊天关闭时，附加文本也会被清除，因此一次界面显示中的上下文不会泄漏到之后的发送操作中。 回复完成后，选择**粘贴到 <app>**，可将其可见的助手文本复制到通用剪贴板并粘贴到之前位于最前方的应用中，其中不包含隐藏的推理内容。此功能需要 macOS 辅助功能权限。该操作会替换剪贴板的当前内容，然后隐藏快速聊天。 可通过**设置 → 通用 → 快速聊天**完全禁用此功能；同一部分还包含快捷键录制器。 - **本地模式**：直接连接到本地 Gateway 网关 WebSocket。 - **远程模式**：使用已配置的直接 `ws://`/`wss://` 路由或由应用管理的 SSH 隧道作为数据平面。 ## 启动和调试 - 手动：Lobster 菜单 -> “打开聊天”。 - 测试时自动打开： ```bash 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 载荷（``、``、``、``，包括被截断的块）和泄漏的模型控制令牌，省略仅包含静默令牌的助手行，例如完全等于 `NO_REPLY`/`no_reply` 的行，并可将过大的行替换为截断占位内容。 - 会话：默认使用上述主会话；UI 可在会话之间切换。 - 会话组：`sessions.groups.list`、`sessions.groups.put`、`sessions.groups.rename` 和 `sessions.groups.delete` 负责管理分组目录。成员关系由会话的 `category` 表示，并通过 `sessions.patch` 更新。 - 未读状态：会话激活且其实时历史记录成功加载后，应用会清除该会话的未读标记。历史记录加载失败时不会清除；临时补丁失败会在下次激活时重试。 - 新手引导使用专用会话，将首次运行设置与其他会话分开。 - 离线缓存：应用会按 Gateway 网关保留少量只读的最近聊天会话和对话记录缓存（`~/Library/Application Support/OpenClaw/chat-cache.sqlite`）：冷启动时会立即呈现最后已知的对话记录，并在 Gateway 网关响应后刷新；断开连接时仍可浏览最近的聊天（在连接恢复之前，发送功能保持禁用）。 ## 安全边界 - 远程模式仅通过 SSH 转发 Gateway 网关 WebSocket 控制端口。 ## 已知限制 - 此 UI 针对聊天会话进行了优化，而不是完整的浏览器沙箱。 ## 相关内容 - [WebChat](https://funcoding.ai/agents/openclaw/web/webchat/) - [macOS 应用](https://funcoding.ai/agents/openclaw/platforms/macos/)