mirror of
https://github.com/farcasclaudiu/openclaw.git
synced 2026-06-29 01:02:03 +03:00
Docs: normalize zh-CN terminology + tone
What: switch to 你/你的 tone; standardize Skills/Gateway网关/local loopback/私信 wording Why: align zh-CN docs with issue 6995 feedback + idiomatic tech style Tests: pnpm docs:build
This commit is contained in:
Josh Palmer
@@ -3,8 +3,8 @@ read_when:
|
||||
- 打包 OpenClaw.app
|
||||
- 调试 macOS gateway launchd 服务
|
||||
- 为 macOS 安装 gateway CLI
|
||||
summary: macOS 上的 Gateway 运行时（外部 launchd 服务）
|
||||
title: macOS 上的 Gateway
|
||||
summary: macOS 上的 Gateway网关运行时（外部 launchd 服务）
|
||||
title: macOS 上的 Gateway网关
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:27Z"
|
||||
model: claude-opus-4-5
|
||||
@@ -14,11 +14,11 @@ x-i18n:
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 上的 Gateway（外部 launchd）
|
||||
# macOS 上的 Gateway网关（外部 launchd）
|
||||
|
||||
OpenClaw.app 不再捆绑 Node/Bun 或 Gateway 运行时。macOS 应用
|
||||
要求**外部**安装 `openclaw` CLI，不会将 Gateway 作为子进程启动，而是管理一个
|
||||
按用户配置的 launchd 服务来保持 Gateway 运行（如果本地已有 Gateway 在运行，则会连接到现有实例）。
|
||||
OpenClaw.app 不再捆绑 Node/Bun 或 Gateway网关运行时。macOS 应用
|
||||
要求**外部**安装 `openclaw` CLI，不会将 Gateway网关作为子进程启动，而是管理一个
|
||||
按用户配置的 launchd 服务来保持 Gateway网关运行（如果本地已有 Gateway网关在运行，则会连接到现有实例）。
|
||||
|
||||
## 安装 CLI（本地模式必需）
|
||||
|
||||
@@ -28,9 +28,9 @@ Mac 上需要 Node 22+，然后全局安装 `openclaw`：
|
||||
npm install -g openclaw@<version>
|
||||
```
|
||||
|
||||
macOS 应用的 **Install CLI** 按钮通过 npm/pnpm 执行相同的安装流程（不建议使用 bun 作为 Gateway 运行时）。
|
||||
macOS 应用的 **Install CLI** 按钮通过 npm/pnpm 执行相同的安装流程（不建议使用 bun 作为 Gateway网关运行时）。
|
||||
|
||||
## Launchd（Gateway 作为 LaunchAgent）
|
||||
## Launchd（Gateway网关作为 LaunchAgent）
|
||||
|
||||
标签：
|
||||
|
||||
@@ -49,8 +49,8 @@ Plist 位置（按用户）：
|
||||
行为：
|
||||
|
||||
- "OpenClaw Active" 启用/禁用 LaunchAgent。
|
||||
- 退出应用**不会**停止 Gateway（launchd 会保持其运行）。
|
||||
- 如果配置端口上已有 Gateway 在运行，应用会连接到该实例，而不是启动新的。
|
||||
- 退出应用**不会**停止 Gateway网关（launchd 会保持其运行）。
|
||||
- 如果配置端口上已有 Gateway网关在运行，应用会连接到该实例，而不是启动新的。
|
||||
|
||||
日志：
|
||||
|
||||
@@ -58,7 +58,7 @@ Plist 位置（按用户）：
|
||||
|
||||
## 版本兼容性
|
||||
|
||||
macOS 应用会将 Gateway 版本与自身版本进行比对。如果不兼容，请更新全局 CLI 以匹配应用版本。
|
||||
macOS 应用会将 Gateway网关版本与自身版本进行比对。如果不兼容，请更新全局 CLI 以匹配应用版本。
|
||||
|
||||
## 冒烟测试
|
||||
|
||||
|
||||
@@ -47,7 +47,7 @@ Canvas 面板通过**自定义 URL scheme** 提供这些文件：
|
||||
|
||||
## 智能体 API 接口
|
||||
|
||||
Canvas 通过 **Gateway WebSocket** 暴露，因此智能体可以：
|
||||
Canvas 通过 **Gateway网关 WebSocket** 暴露，因此智能体可以：
|
||||
|
||||
- 显示/隐藏面板
|
||||
- 导航到路径或 URL
|
||||
@@ -70,7 +70,7 @@ openclaw nodes canvas snapshot --node <id>
|
||||
|
||||
## Canvas 中的 A2UI
|
||||
|
||||
A2UI 由 Gateway canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway 广播 Canvas 主机时，macOS 应用在首次打开时会自动导航到 A2UI 主机页面。
|
||||
A2UI 由 Gateway网关 canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway网关广播 Canvas 主机时，macOS 应用在首次打开时会自动导航到 A2UI 主机页面。
|
||||
|
||||
默认 A2UI 主机 URL：
|
||||
|
||||
@@ -123,5 +123,5 @@ window.location.href = "openclaw://agent?message=Review%20this%20design";
|
||||
## 安全注意事项
|
||||
|
||||
- Canvas scheme 阻止目录遍历；文件必须位于会话根目录下。
|
||||
- 本地 Canvas 内容使用自定义 scheme（无需回环服务器）。
|
||||
- 本地 Canvas 内容使用自定义 scheme（无需 local loopback 服务器）。
|
||||
- 仅在显式导航时才允许外部 `http(s)` URL。
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
---
|
||||
read_when:
|
||||
- 将 Mac 应用与 Gateway 生命周期集成
|
||||
summary: macOS 上的 Gateway 生命周期（launchd）
|
||||
title: Gateway 生命周期
|
||||
- 将 Mac 应用与 Gateway网关生命周期集成
|
||||
summary: macOS 上的 Gateway网关生命周期（launchd）
|
||||
title: Gateway网关生命周期
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:36Z"
|
||||
model: claude-opus-4-5
|
||||
@@ -12,17 +12,17 @@ x-i18n:
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# macOS 上的 Gateway 生命周期
|
||||
# macOS 上的 Gateway网关生命周期
|
||||
|
||||
macOS 应用默认**通过 launchd 管理 Gateway**，不会将 Gateway 作为子进程启动。它首先尝试连接到已在配置端口上运行的 Gateway；如果无法连接，则通过外部 `openclaw` CLI（无内嵌运行时）启用 launchd 服务。这为你提供了可靠的登录自启动和崩溃后自动重启。
|
||||
macOS 应用默认**通过 launchd 管理 Gateway网关**，不会将 Gateway网关作为子进程启动。它首先尝试连接到已在配置端口上运行的 Gateway网关；如果无法连接，则通过外部 `openclaw` CLI（无内嵌运行时）启用 launchd 服务。这为你提供了可靠的登录自启动和崩溃后自动重启。
|
||||
|
||||
子进程模式（由应用直接启动 Gateway）**目前未使用**。如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway。
|
||||
子进程模式（由应用直接启动 Gateway网关）**目前未使用**。如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway网关。
|
||||
|
||||
## 默认行为（launchd）
|
||||
|
||||
- 应用安装一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；兼容旧版 `com.openclaw.*`）。
|
||||
- 当启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway。
|
||||
- 日志写入 launchd Gateway 日志路径（可在调试设置中查看）。
|
||||
- 当启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway网关。
|
||||
- 日志写入 launchd Gateway网关日志路径（可在调试设置中查看）。
|
||||
|
||||
常用命令：
|
||||
|
||||
@@ -47,11 +47,11 @@ rm ~/.openclaw/disable-launchagent
|
||||
|
||||
## 仅连接模式
|
||||
|
||||
要强制 macOS 应用**永不安装或管理 launchd**，请使用 `--attach-only`（或 `--no-launchd`）启动。这会设置 `~/.openclaw/disable-launchagent`，使应用仅连接到已运行的 Gateway。你也可以在调试设置中切换相同的行为。
|
||||
要强制 macOS 应用**永不安装或管理 launchd**，请使用 `--attach-only`（或 `--no-launchd`）启动。这会设置 `~/.openclaw/disable-launchagent`，使应用仅连接到已运行的 Gateway网关。你也可以在调试设置中切换相同的行为。
|
||||
|
||||
## 远程模式
|
||||
|
||||
远程模式不会启动本地 Gateway。应用使用 SSH 隧道连接到远程主机，并通过该隧道进行通信。
|
||||
远程模式不会启动本地 Gateway网关。应用使用 SSH 隧道连接到远程主机，并通过该隧道进行通信。
|
||||
|
||||
## 为何优先选择 launchd
|
||||
|
||||
|
||||
@@ -21,7 +21,7 @@ x-i18n:
|
||||
在构建应用之前，请确保已安装以下内容：
|
||||
|
||||
1. **Xcode 26.2+**：Swift 开发所需。
|
||||
2. **Node.js 22+ & pnpm**：Gateway、CLI 和打包脚本所需。
|
||||
2. **Node.js 22+ & pnpm**：Gateway网关、CLI 和打包脚本所需。
|
||||
|
||||
## 1. 安装依赖
|
||||
|
||||
@@ -94,9 +94,9 @@ xcrun swift --version
|
||||
```
|
||||
2. 如果仍然无效，在 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 中临时更改 `BUNDLE_ID`，以强制 macOS 使用"全新状态"。
|
||||
|
||||
### Gateway 持续显示"Starting..."
|
||||
### Gateway网关持续显示"Starting..."
|
||||
|
||||
如果 Gateway 状态一直停留在"Starting..."，请检查是否有僵尸进程占用了端口：
|
||||
如果 Gateway网关状态一直停留在"Starting..."，请检查是否有僵尸进程占用了端口：
|
||||
|
||||
```bash
|
||||
openclaw gateway status
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试 Mac 应用健康指示器
|
||||
summary: macOS 应用如何报告 Gateway/Baileys 健康状态
|
||||
summary: macOS 应用如何报告 Gateway网关/Baileys 健康状态
|
||||
title: 健康检查
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:32:43Z"
|
||||
@@ -38,4 +38,4 @@ x-i18n:
|
||||
|
||||
## 不确定时
|
||||
|
||||
- 您仍然可以使用 [Gateway 健康检查](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并跟踪 `/tmp/openclaw/openclaw-*.log` 中的 `web-heartbeat` / `web-reconnect`。
|
||||
- 你仍然可以使用 [Gateway网关健康检查](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并跟踪 `/tmp/openclaw/openclaw-*.log` 中的 `web-heartbeat` / `web-reconnect`。
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
read_when:
|
||||
- 设置或调试远程 Mac 控制
|
||||
summary: macOS 应用通过 SSH 远程控制 OpenClaw Gateway 的流程
|
||||
summary: macOS 应用通过 SSH 远程控制 OpenClaw Gateway网关的流程
|
||||
title: 远程控制
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:20Z"
|
||||
@@ -14,20 +14,20 @@ x-i18n:
|
||||
|
||||
# 远程 OpenClaw（macOS ⇄ 远程主机）
|
||||
|
||||
此流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway 的完整远程控制器。这是应用的 **Remote over SSH**（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都复用 _设置 → 通用_ 中相同的远程 SSH 配置。
|
||||
此流程让 macOS 应用充当运行在另一台主机（桌面/服务器）上的 OpenClaw Gateway网关的完整远程控制器。这是应用的 **Remote over SSH**（远程运行）功能。所有功能——健康检查、语音唤醒转发和 Web Chat——都复用 _设置 → 通用_ 中相同的远程 SSH 配置。
|
||||
|
||||
## 模式
|
||||
|
||||
- **本地（此 Mac）**：所有内容在笔记本电脑上运行，无需 SSH。
|
||||
- **Remote over SSH（默认）**：OpenClaw 命令在远程主机上执行。Mac 应用使用 `-o BatchMode` 加上你选择的身份/密钥打开 SSH 连接，并进行本地端口转发。
|
||||
- **Remote direct (ws/wss)**：无 SSH 隧道。Mac 应用直接连接到 Gateway URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。
|
||||
- **Remote direct (ws/wss)**：无 SSH 隧道。Mac 应用直接连接到 Gateway网关 URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。
|
||||
|
||||
## 远程传输方式
|
||||
|
||||
远程模式支持两种传输方式：
|
||||
|
||||
- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway 端口转发到 localhost。由于隧道是回环的，Gateway 会将节点 IP 识别为 `127.0.0.1`。
|
||||
- **Direct (ws/wss)**：直接连接到 Gateway URL。Gateway 会看到真实的客户端 IP。
|
||||
- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway网关端口转发到 localhost。由于隧道是 local loopback 的，Gateway网关会将节点 IP 识别为 `127.0.0.1`。
|
||||
- **Direct (ws/wss)**：直接连接到 Gateway网关 URL。Gateway网关会看到真实的客户端 IP。
|
||||
|
||||
## 远程主机的前提条件
|
||||
|
||||
@@ -41,8 +41,8 @@ x-i18n:
|
||||
2. 在 **OpenClaw runs** 下，选择 **Remote over SSH** 并设置：
|
||||
- **传输方式**：**SSH 隧道** 或 **Direct (ws/wss)**。
|
||||
- **SSH 目标**：`user@host`（可选 `:port`）。
|
||||
- 如果 Gateway 在同一局域网中并通过 Bonjour 广播，可从发现列表中选择以自动填充此字段。
|
||||
- **Gateway URL**（仅 Direct 模式）：`wss://gateway.example.ts.net`（或局域网使用 `ws://...`）。
|
||||
- 如果 Gateway网关在同一局域网中并通过 Bonjour 广播，可从发现列表中选择以自动填充此字段。
|
||||
- **Gateway网关 URL**（仅 Direct 模式）：`wss://gateway.example.ts.net`（或局域网使用 `ws://...`）。
|
||||
- **身份文件**（高级）：密钥路径。
|
||||
- **项目根目录**（高级）：用于命令执行的远程代码仓库路径。
|
||||
- **CLI 路径**（高级）：可选的 `openclaw` 可执行入口/二进制文件路径（广播时自动填充）。
|
||||
@@ -51,19 +51,19 @@ x-i18n:
|
||||
|
||||
## Web Chat
|
||||
|
||||
- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway。
|
||||
- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway URL。
|
||||
- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway网关。
|
||||
- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway网关 URL。
|
||||
- 不再有单独的 WebChat HTTP 服务器。
|
||||
|
||||
## 权限
|
||||
|
||||
- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行上手引导以一次性授予权限。
|
||||
- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行新手引导以一次性授予权限。
|
||||
- 节点通过 `node.list` / `node.describe` 广播其权限状态，以便智能体了解可用功能。
|
||||
|
||||
## 安全注意事项
|
||||
|
||||
- 建议在远程主机上绑定回环地址，并通过 SSH 或 Tailscale 连接。
|
||||
- 如果将 Gateway 绑定到非回环接口，请要求令牌/密码认证。
|
||||
- 建议在远程主机上绑定 local loopback，并通过 SSH 或 Tailscale 连接。
|
||||
- 如果将 Gateway网关绑定到非 local loopback 接口，请要求令牌/密码认证。
|
||||
- 参阅 [安全](/gateway/security) 和 [Tailscale](/gateway/tailscale)。
|
||||
|
||||
## WhatsApp 登录流程（远程）
|
||||
@@ -75,8 +75,8 @@ x-i18n:
|
||||
|
||||
- **exit 127 / not found**：`openclaw` 不在非登录 shell 的 PATH 中。将其添加到 `/etc/paths`、你的 shell rc 文件中，或创建符号链接到 `/usr/local/bin`/`/opt/homebrew/bin`。
|
||||
- **健康探测失败**：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（`openclaw status --json`）。
|
||||
- **Web Chat 卡住**：确认 Gateway 在远程主机上正在运行，且转发端口与 Gateway WS 端口匹配；界面需要健康的 WS 连接。
|
||||
- **节点 IP 显示 127.0.0.1**：使用 SSH 隧道时这是预期行为。如果你希望 Gateway 看到真实客户端 IP，请将**传输方式**切换为 **Direct (ws/wss)**。
|
||||
- **Web Chat 卡住**：确认 Gateway网关在远程主机上正在运行，且转发端口与 Gateway网关 WS 端口匹配；界面需要健康的 WS 连接。
|
||||
- **节点 IP 显示 127.0.0.1**：使用 SSH 隧道时这是预期行为。如果你希望 Gateway网关看到真实客户端 IP，请将**传输方式**切换为 **Direct (ws/wss)**。
|
||||
- **语音唤醒**：触发短语在远程模式下会自动转发；无需单独的转发器。
|
||||
|
||||
## 通知声音
|
||||
|
||||
@@ -1,9 +1,9 @@
|
||||
---
|
||||
read_when:
|
||||
- 更新 macOS 技能设置 UI
|
||||
- 更改技能门控或安装行为
|
||||
summary: macOS 技能设置 UI 及 Gateway 支持的状态
|
||||
title: 技能
|
||||
- 更新 macOS Skills 设置 UI
|
||||
- 更改 Skills 门控或安装行为
|
||||
summary: macOS Skills 设置 UI 及 Gateway网关支持的状态
|
||||
title: Skills
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:07Z"
|
||||
model: claude-opus-4-5
|
||||
@@ -13,21 +13,21 @@ x-i18n:
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
# 技能（macOS）
|
||||
# Skills（macOS）
|
||||
|
||||
macOS 应用通过 Gateway 展示 OpenClaw 技能；不会在本地解析技能。
|
||||
macOS 应用通过 Gateway网关展示 OpenClaw Skills；不会在本地解析 Skills。
|
||||
|
||||
## 数据来源
|
||||
|
||||
- `skills.status`（Gateway）返回所有技能及其资格和缺失的依赖项
|
||||
（包括内置技能的白名单限制）。
|
||||
- `skills.status`（Gateway网关）返回所有 Skills 及其资格和缺失的依赖项
|
||||
（包括内置 Skills 的白名单限制）。
|
||||
- 依赖项来源于每个 `SKILL.md` 中的 `metadata.openclaw.requires`。
|
||||
|
||||
## 安装操作
|
||||
|
||||
- `metadata.openclaw.install` 定义安装选项（brew/node/go/uv）。
|
||||
- 应用调用 `skills.install` 在 Gateway 主机上运行安装程序。
|
||||
- 当提供多个安装程序时，Gateway 仅展示一个首选安装程序
|
||||
- 应用调用 `skills.install` 在 Gateway网关主机上运行安装程序。
|
||||
- 当提供多个安装程序时，Gateway网关仅展示一个首选安装程序
|
||||
（优先使用 brew，否则使用 `skills.install` 中的 node 管理器，默认为 npm）。
|
||||
|
||||
## 环境变量/API 密钥
|
||||
@@ -37,4 +37,4 @@ macOS 应用通过 Gateway 展示 OpenClaw 技能；不会在本地解析技能
|
||||
|
||||
## 远程模式
|
||||
|
||||
- 安装和配置更新在 Gateway 主机上执行（而非本地 Mac）。
|
||||
- 安装和配置更新在 Gateway网关主机上执行（而非本地 Mac）。
|
||||
|
||||
@@ -17,7 +17,7 @@ x-i18n:
|
||||
## 模式
|
||||
|
||||
- **唤醒词模式**（默认）：常驻语音识别器等待触发词（`swabbleTriggerWords`）。匹配后开始采集，显示叠加层并展示部分文本，静默后自动发送。
|
||||
- **按键通话（长按右 Option 键）**：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便您调整文本。
|
||||
- **按键通话（长按右 Option 键）**：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便你调整文本。
|
||||
|
||||
## 运行时行为（唤醒词）
|
||||
|
||||
@@ -36,7 +36,7 @@ x-i18n:
|
||||
|
||||
## 叠加层卡住故障模式（历史问题）
|
||||
|
||||
此前，如果叠加层卡在可见状态并且您手动关闭它，语音唤醒可能表现为"无响应"，因为运行时的重启尝试会被叠加层可见性阻塞，且不会调度后续重启。
|
||||
此前，如果叠加层卡在可见状态并且你手动关闭它，语音唤醒可能表现为"无响应"，因为运行时的重启尝试会被叠加层可见性阻塞，且不会调度后续重启。
|
||||
|
||||
加固措施：
|
||||
|
||||
@@ -57,11 +57,11 @@ x-i18n:
|
||||
- **长按 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
|
||||
- 语言和麦克风选择器、实时电平指示器、触发词表格、测试器（仅本地；不进行转发）。
|
||||
- 麦克风选择器在设备断开时保留上次选择，显示断开提示，并在设备恢复前临时回退到系统默认设备。
|
||||
- **声音**：触发检测和发送时播放提示音；默认使用 macOS "Glass" 系统声音。您可以为每个事件选择任何 `NSSound` 可加载的文件（如 MP3/WAV/AIFF），或选择**无声音**。
|
||||
- **声音**：触发检测和发送时播放提示音；默认使用 macOS "Glass" 系统声音。你可以为每个事件选择任何 `NSSound` 可加载的文件（如 MP3/WAV/AIFF），或选择**无声音**。
|
||||
|
||||
## 转发行为
|
||||
|
||||
- 启用语音唤醒后，转录文本将转发到活跃的 Gateway/智能体（与 Mac 应用其他部分使用的本地/远程模式相同）。
|
||||
- 启用语音唤醒后，转录文本将转发到活跃的 Gateway网关/智能体（与 Mac 应用其他部分使用的本地/远程模式相同）。
|
||||
- 回复将发送到**最近使用的主要提供商**（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，错误会被记录，且运行仍可通过 WebChat/会话日志查看。
|
||||
|
||||
## 转发载荷
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
read_when:
|
||||
- 调试 Mac WebChat 视图或回环端口
|
||||
summary: Mac 应用如何嵌入 Gateway WebChat 以及如何调试
|
||||
- 调试 Mac WebChat 视图或 local loopback 端口
|
||||
summary: Mac 应用如何嵌入 Gateway网关 WebChat 以及如何调试
|
||||
title: WebChat
|
||||
x-i18n:
|
||||
generated_at: "2026-02-01T21:33:23Z"
|
||||
@@ -14,10 +14,10 @@ x-i18n:
|
||||
|
||||
# WebChat（macOS 应用）
|
||||
|
||||
macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway，默认使用所选智能体的**主会话**（通过会话切换器可访问其他会话）。
|
||||
macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway网关，默认使用所选智能体的**主会话**（通过会话切换器可访问其他会话）。
|
||||
|
||||
- **本地模式**：直接连接到本地 Gateway WebSocket。
|
||||
- **远程模式**：通过 SSH 转发 Gateway 控制端口，并使用该隧道作为数据平面。
|
||||
- **本地模式**：直接连接到本地 Gateway网关 WebSocket。
|
||||
- **远程模式**：通过 SSH 转发 Gateway网关控制端口，并使用该隧道作为数据平面。
|
||||
|
||||
## 启动与调试
|
||||
|
||||
@@ -30,13 +30,13 @@ macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接
|
||||
|
||||
## 工作原理
|
||||
|
||||
- 数据平面：Gateway WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 以及事件 `chat`、`agent`、`presence`、`tick`、`health`。
|
||||
- 数据平面：Gateway网关 WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 以及事件 `chat`、`agent`、`presence`、`tick`、`health`。
|
||||
- 会话：默认使用主会话（`main`，或作用域为全局时使用 `global`）。UI 可在会话之间切换。
|
||||
- 上手引导使用专用会话，以将首次运行设置与其他内容分开。
|
||||
- 新手引导使用专用会话，以将首次运行设置与其他内容分开。
|
||||
|
||||
## 安全面
|
||||
|
||||
- 远程模式仅通过 SSH 转发 Gateway WebSocket 控制端口。
|
||||
- 远程模式仅通过 SSH 转发 Gateway网关 WebSocket 控制端口。
|
||||
|
||||
## 已知限制
|
||||
|
||||
|
||||
@@ -14,31 +14,31 @@ x-i18n:
|
||||
|
||||
# OpenClaw macOS IPC 架构
|
||||
|
||||
**当前模型：** 本地 Unix 套接字将**节点宿主服务**连接到 **macOS 应用**，用于执行审批和 `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway WebSocket 和 `node.invoke` 传递。UI 自动化使用 PeekabooBridge。
|
||||
**当前模型：** 本地 Unix 套接字将**节点宿主服务**连接到 **macOS 应用**，用于执行审批和 `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway网关 WebSocket 和 `node.invoke` 传递。UI 自动化使用 PeekabooBridge。
|
||||
|
||||
## 目标
|
||||
|
||||
- 单个 GUI 应用实例负责所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
|
||||
- 精简的自动化接口：Gateway + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
|
||||
- 精简的自动化接口：Gateway网关 + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
|
||||
- 可预测的权限：始终使用相同的已签名 bundle ID，由 launchd 启动，确保 TCC 授权持久有效。
|
||||
|
||||
## 工作原理
|
||||
|
||||
### Gateway + 节点传输
|
||||
### Gateway网关 + 节点传输
|
||||
|
||||
- 应用运行 Gateway（本地模式）并作为节点连接到它。
|
||||
- 应用运行 Gateway网关（本地模式）并作为节点连接到它。
|
||||
- 智能体操作通过 `node.invoke` 执行（例如 `system.run`、`system.notify`、`canvas.*`）。
|
||||
|
||||
### 节点服务 + 应用 IPC
|
||||
|
||||
- 无界面的节点宿主服务通过 WebSocket 连接到 Gateway。
|
||||
- 无界面的节点宿主服务通过 WebSocket 连接到 Gateway网关。
|
||||
- `system.run` 请求通过本地 Unix 套接字转发到 macOS 应用。
|
||||
- 应用在 UI 上下文中执行操作，必要时提示用户确认，并返回输出。
|
||||
|
||||
架构图（SCI）：
|
||||
|
||||
```
|
||||
Agent -> Gateway -> Node Service (WS)
|
||||
Agent -> Gateway网关 -> Node Service (WS)
|
||||
| IPC (UDS + token + HMAC + TTL)
|
||||
v
|
||||
Mac App (UI + TCC + system.run)
|
||||
|
||||
Reference in New Issue
Block a user