@gguf/claw 2026.2.1 → 2026.2.2

package/docs/zh-CN/platforms/mac/release.md

@@ -0,0 +1,92 @@
+---
+read_when:
+  - 制作或验证 OpenClaw macOS 发布版本
+  - 更新 Sparkle appcast 或订阅源资源
+summary: OpenClaw macOS 发布清单（Sparkle 订阅源、打包、签名）
+title: macOS 发布
+x-i18n:
+  generated_at: "2026-02-01T21:33:17Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 703c08c13793cd8c96bd4c31fb4904cdf4ffff35576e7ea48a362560d371cb30
+  source_path: platforms/mac/release.md
+  workflow: 15
+---
+
+# OpenClaw macOS 发布（Sparkle）
+
+本应用现已支持 Sparkle 自动更新。发布构建必须经过 Developer ID 签名、压缩，并发布包含签名的 appcast 条目。
+
+## 前提条件
+
+- 已安装 Developer ID Application 证书（示例：`Developer ID Application: <Developer Name> (<TEAMID>)`）。
+- 环境变量 `SPARKLE_PRIVATE_KEY_FILE` 已设置为 Sparkle ed25519 私钥路径（公钥已嵌入 Info.plist）。如果缺失，请检查 `~/.profile`。
+- 用于 `xcrun notarytool` 的公证凭据（钥匙串配置文件或 API 密钥），以实现通过 Gatekeeper 安全分发的 DMG/zip。
+  - 我们使用名为 `openclaw-notary` 的钥匙串配置文件，由 shell 配置文件中的 App Store Connect API 密钥环境变量创建：
+    - `APP_STORE_CONNECT_API_KEY_P8`、`APP_STORE_CONNECT_KEY_ID`、`APP_STORE_CONNECT_ISSUER_ID`
+    - `echo "$APP_STORE_CONNECT_API_KEY_P8" | sed 's/\\n/\n/g' > /tmp/openclaw-notary.p8`
+    - `xcrun notarytool store-credentials "openclaw-notary" --key /tmp/openclaw-notary.p8 --key-id "$APP_STORE_CONNECT_KEY_ID" --issuer "$APP_STORE_CONNECT_ISSUER_ID"`
+- 已安装 `pnpm` 依赖（`pnpm install --config.node-linker=hoisted`）。
+- Sparkle 工具通过 SwiftPM 自动获取，位于 `apps/macos/.build/artifacts/sparkle/Sparkle/bin/`（`sign_update`、`generate_appcast` 等）。
+
+## 构建与打包
+
+注意事项：
+
+- `APP_BUILD` 映射到 `CFBundleVersion`/`sparkle:version`；保持纯数字且单调递增（不含 `-beta`），否则 Sparkle 会将其视为相同版本。
+- 默认为当前架构（`$(uname -m)`）。对于发布/通用构建，设置 `BUILD_ARCHS="arm64 x86_64"`（或 `BUILD_ARCHS=all`）。
+- 使用 `scripts/package-mac-dist.sh` 生成发布产物（zip + DMG + 公证）。使用 `scripts/package-mac-app.sh` 进行本地/开发打包。
+
+```bash
+# 从仓库根目录运行；设置发布 ID 以启用 Sparkle 订阅源。
+# APP_BUILD 必须为纯数字且单调递增，以便 Sparkle 正确比较。
+BUNDLE_ID=bot.molt.mac \
+APP_VERSION=2026.1.27-beta.1 \
+APP_BUILD="$(git rev-list --count HEAD)" \
+BUILD_CONFIG=release \
+SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
+scripts/package-mac-app.sh
+
+# 打包用于分发的 zip（包含资源分支以支持 Sparkle 增量更新）
+ditto -c -k --sequesterRsrc --keepParent dist/OpenClaw.app dist/OpenClaw-2026.1.27-beta.1.zip
+
+# 可选：同时构建适合用户使用的样式化 DMG（拖拽到 /Applications）
+scripts/create-dmg.sh dist/OpenClaw.app dist/OpenClaw-2026.1.27-beta.1.dmg
+
+# 推荐：构建 + 公证/装订 zip + DMG
+# 首先，创建一次钥匙串配置文件：
+#   xcrun notarytool store-credentials "openclaw-notary" \
+#     --apple-id "<apple-id>" --team-id "<team-id>" --password "<app-specific-password>"
+NOTARIZE=1 NOTARYTOOL_PROFILE=openclaw-notary \
+BUNDLE_ID=bot.molt.mac \
+APP_VERSION=2026.1.27-beta.1 \
+APP_BUILD="$(git rev-list --count HEAD)" \
+BUILD_CONFIG=release \
+SIGN_IDENTITY="Developer ID Application: <Developer Name> (<TEAMID>)" \
+scripts/package-mac-dist.sh
+
+# 可选：随发布一起提供 dSYM
+ditto -c -k --keepParent apps/macos/.build/release/OpenClaw.app.dSYM dist/OpenClaw-2026.1.27-beta.1.dSYM.zip
+```
+
+## Appcast 条目
+
+使用发布说明生成器，以便 Sparkle 渲染格式化的 HTML 说明：
+
+```bash
+SPARKLE_PRIVATE_KEY_FILE=/path/to/ed25519-private-key scripts/make_appcast.sh dist/OpenClaw-2026.1.27-beta.1.zip https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml
+```
+
+从 `CHANGELOG.md`（通过 [`scripts/changelog-to-html.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/changelog-to-html.sh)）生成 HTML 发布说明，并将其嵌入 appcast 条目。
+发布时，将更新后的 `appcast.xml` 与发布资源（zip + dSYM）一起提交。
+
+## 发布与验证
+
+- 将 `OpenClaw-2026.1.27-beta.1.zip`（和 `OpenClaw-2026.1.27-beta.1.dSYM.zip`）上传到标签 `v2026.1.27-beta.1` 对应的 GitHub 发布。
+- 确保原始 appcast URL 与内置的订阅源匹配：`https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml`。
+- 完整性检查：
+  - `curl -I https://raw.githubusercontent.com/openclaw/openclaw/main/appcast.xml` 返回 200。
+  - `curl -I <enclosure url>` 在资源上传后返回 200。
+  - 在之前的公开构建版本上，从 About 选项卡运行"Check for Updates…"，验证 Sparkle 能正常安装新构建。
+
+完成定义：已签名的应用 + appcast 已发布，从旧版本的更新流程正常工作，且发布资源已附加到 GitHub 发布。

package/docs/zh-CN/platforms/mac/remote.md

@@ -0,0 +1,90 @@
+---
+read_when:
+  - 设置或调试远程 Mac 控制
+summary: macOS 应用通过 SSH 远程控制 OpenClaw Gateway网关的流程
+title: 远程控制
+x-i18n:
+  generated_at: "2026-02-01T21:33:20Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 61b43707250d5515fd0f85f092bdde24598f14904398ff3fca3736bcc48d72f8
+  source_path: platforms/mac/remote.md
+  workflow: 15
+---
+
+# 远程 OpenClaw（macOS ⇄ 远程主机）
+
+此流程让 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 反向代理）。
+
+## 远程传输方式
+
+远程模式支持两种传输方式：
+
+- **SSH 隧道**（默认）：使用 `ssh -N -L ...` 将 Gateway网关端口转发到 localhost。由于隧道是 local loopback 的，Gateway网关会将节点 IP 识别为 `127.0.0.1`。
+- **Direct (ws/wss)**：直接连接到 Gateway网关 URL。Gateway网关会看到真实的客户端 IP。
+
+## 远程主机的前提条件
+
+1. 安装 Node + pnpm 并构建/安装 OpenClaw CLI（`pnpm install && pnpm build && pnpm link --global`）。
+2. 确保 `openclaw` 在非交互式 shell 的 PATH 中（如有需要，创建符号链接到 `/usr/local/bin` 或 `/opt/homebrew/bin`）。
+3. 开启 SSH 密钥认证。我们建议使用 **Tailscale** IP 以实现局域网外的稳定可达性。
+
+## macOS 应用设置
+
+1. 打开 _设置 → 通用_。
+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://...`）。
+   - **身份文件**（高级）：密钥路径。
+   - **项目根目录**（高级）：用于命令执行的远程代码仓库路径。
+   - **CLI 路径**（高级）：可选的 `openclaw` 可执行入口/二进制文件路径（广播时自动填充）。
+3. 点击 **测试远程连接**。成功表示远程 `openclaw status --json` 正常运行。失败通常意味着 PATH/CLI 问题；exit 127 表示远程未找到 CLI。
+4. 健康检查和 Web Chat 现在会自动通过此 SSH 隧道运行。
+
+## Web Chat
+
+- **SSH 隧道**：Web Chat 通过转发的 WebSocket 控制端口（默认 18789）连接到 Gateway网关。
+- **Direct (ws/wss)**：Web Chat 直接连接到配置的 Gateway网关 URL。
+- 不再有单独的 WebChat HTTP 服务器。
+
+## 权限
+
+- 远程主机需要与本地相同的 TCC 授权（自动化、辅助功能、屏幕录制、麦克风、语音识别、通知）。在该机器上运行新手引导以一次性授予权限。
+- 节点通过 `node.list` / `node.describe` 广播其权限状态，以便智能体了解可用功能。
+
+## 安全注意事项
+
+- 建议在远程主机上绑定 local loopback，并通过 SSH 或 Tailscale 连接。
+- 如果将 Gateway网关绑定到非 local loopback 接口，请要求令牌/密码认证。
+- 参阅 [安全](/gateway/security) 和 [Tailscale](/gateway/tailscale)。
+
+## WhatsApp 登录流程（远程）
+
+- 在**远程主机**上运行 `openclaw channels login --verbose`。用手机上的 WhatsApp 扫描二维码。
+- 如果认证过期，在该主机上重新运行登录。健康检查会显示链接问题。
+
+## 故障排除
+
+- **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)**。
+- **语音唤醒**：触发短语在远程模式下会自动转发；无需单独的转发器。
+
+## 通知声音
+
+通过 `openclaw` 和 `node.invoke` 在脚本中为每个通知选择声音，例如：
+
+```bash
+openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass
+```
+
+应用中不再有全局"默认声音"开关；调用方按请求选择声音（或不使用声音）。

package/docs/zh-CN/platforms/mac/signing.md

@@ -0,0 +1,54 @@
+---
+read_when:
+  - 构建或签名 Mac 调试构建
+summary: 打包脚本生成的 macOS 调试构建的签名步骤
+title: macOS 签名
+x-i18n:
+  generated_at: "2026-02-01T21:33:15Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 403b92f9a0ecdb7cb42ec097c684b7a696be3696d6eece747314a4dc90d8797e
+  source_path: platforms/mac/signing.md
+  workflow: 15
+---
+
+# Mac 签名（调试构建）
+
+此应用通常从 [`scripts/package-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-app.sh) 构建，该脚本目前会：
+
+- 设置稳定的调试 Bundle 标识符：`ai.openclaw.mac.debug`
+- 使用该 Bundle ID 写入 Info.plist（可通过 `BUNDLE_ID=...` 覆盖）
+- 调用 [`scripts/codesign-mac-app.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/codesign-mac-app.sh) 对主二进制文件和应用包进行签名，使 macOS 将每次重新构建视为相同的已签名包，并保留 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音）。要获得稳定的权限，请使用真实签名身份；临时签名是可选的且不稳定（参阅 [macOS 权限](/platforms/mac/permissions)）。
+- 默认使用 `CODESIGN_TIMESTAMP=auto`；为 Developer ID 签名启用受信任的时间戳。设置 `CODESIGN_TIMESTAMP=off` 可跳过时间戳（离线调试构建）。
+- 将构建元数据注入 Info.plist：`OpenClawBuildTimestamp`（UTC）和 `OpenClawGitCommit`（短哈希），以便"关于"面板可以显示构建信息、git 信息和调试/发布渠道。
+- **打包需要 Node 22+**：脚本会运行 TS 构建和 Control UI 构建。
+- 从环境变量中读取 `SIGN_IDENTITY`。将 `export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"`（或你的 Developer ID Application 证书）添加到 shell 配置文件中，以始终使用你的证书签名。临时签名需要通过 `ALLOW_ADHOC_SIGNING=1` 或 `SIGN_IDENTITY="-"` 显式启用（不建议用于权限测试）。
+- 签名后运行 Team ID 审计，如果应用包内的任何 Mach-O 文件由不同的 Team ID 签名则会失败。设置 `SKIP_TEAM_ID_CHECK=1` 可跳过此检查。
+
+## 用法
+
+```bash
+# 从仓库根目录
+scripts/package-mac-app.sh               # 自动选择身份；未找到时报错
+SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # 真实证书
+ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # 临时签名（权限不会持久化）
+SIGN_IDENTITY="-" scripts/package-mac-app.sh        # 显式临时签名（同样的限制）
+DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # 仅限开发的 Sparkle Team ID 不匹配解决方案
+```
+
+### 临时签名注意事项
+
+使用 `SIGN_IDENTITY="-"`（临时签名）签名时，脚本会自动禁用**强化运行时**（`--options runtime`）。这是为了防止应用在尝试加载不共享相同 Team ID 的嵌入式框架（如 Sparkle）时崩溃。临时签名还会破坏 TCC 权限持久化；参阅 [macOS 权限](/platforms/mac/permissions) 了解恢复步骤。
+
+## 关于面板的构建元数据
+
+`package-mac-app.sh` 会在包中标记以下信息：
+
+- `OpenClawBuildTimestamp`：打包时的 ISO8601 UTC 时间
+- `OpenClawGitCommit`：短 git 哈希（不可用时为 `unknown`）
+
+"关于"选项卡读取这些键以显示版本、构建日期、git 提交以及是否为调试构建（通过 `#if DEBUG`）。代码更改后运行打包程序以刷新这些值。
+
+## 原因
+
+TCC 权限与 Bundle 标识符*和*代码签名绑定。使用不断变化的 UUID 的未签名调试构建会导致 macOS 在每次重新构建后忘记授权。对二进制文件进行签名（默认临时签名）并保持固定的 Bundle ID/路径（`dist/OpenClaw.app`）可以在构建之间保留授权，与 VibeTunnel 的方案一致。

package/docs/zh-CN/platforms/mac/skills.md

@@ -0,0 +1,40 @@
+---
+read_when:
+  - 更新 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
+  provider: pi
+  source_hash: ecd5286bbe49eed89319686c4f7d6da55ef7b0d3952656ba98ef5e769f3fbf79
+  source_path: platforms/mac/skills.md
+  workflow: 15
+---
+
+# Skills（macOS）
+
+macOS 应用通过 Gateway网关展示 OpenClaw Skills；不会在本地解析 Skills。
+
+## 数据来源
+
+- `skills.status`（Gateway网关）返回所有 Skills 及其资格和缺失的依赖项
+  （包括内置 Skills 的白名单限制）。
+- 依赖项来源于每个 `SKILL.md` 中的 `metadata.openclaw.requires`。
+
+## 安装操作
+
+- `metadata.openclaw.install` 定义安装选项（brew/node/go/uv）。
+- 应用调用 `skills.install` 在 Gateway网关主机上运行安装程序。
+- 当提供多个安装程序时，Gateway网关仅展示一个首选安装程序
+  （优先使用 brew，否则使用 `skills.install` 中的 node 管理器，默认为 npm）。
+
+## 环境变量/API 密钥
+
+- 应用将密钥存储在 `~/.openclaw/openclaw.json` 的 `skills.entries.<skillKey>` 下。
+- `skills.update` 可修改 `enabled`、`apiKey` 和 `env`。
+
+## 远程模式
+
+- 安装和配置更新在 Gateway网关主机上执行（而非本地 Mac）。

package/docs/zh-CN/platforms/mac/voice-overlay.md

@@ -0,0 +1,67 @@
+---
+read_when:
+  - 调整语音浮层行为
+summary: 唤醒词与按键说话重叠时的语音浮层生命周期
+title: 语音浮层
+x-i18n:
+  generated_at: "2026-02-01T21:33:26Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 3be1a60aa7940b2368ff62cd49f04b2b8422876030e8ea206b467f66a5a6bd4d
+  source_path: platforms/mac/voice-overlay.md
+  workflow: 15
+---
+
+# 语音浮层生命周期（macOS）
+
+受众：macOS 应用贡献者。目标：在唤醒词与按键说话重叠时保持语音浮层行为可预测。
+
+### 当前意图
+
+- 如果浮层已因唤醒词显示，此时用户按下热键，热键会话会*接管*现有文本而非重置。浮层在热键按住期间保持显示。用户松开时：如果有去除空白后的文本则发送，否则关闭。
+- 单独使用唤醒词时仍在静音后自动发送；按键说话在松开时立即发送。
+
+### 已实现（2025 年 12 月 9 日）
+
+- 浮层会话现在为每次捕获（唤醒词或按键说话）携带一个令牌。当令牌不匹配时，部分/最终/发送/关闭/音量更新会被丢弃，避免过时回调。
+- 按键说话会接管任何可见的浮层文本作为前缀（因此在唤醒浮层显示时按下热键会保留文本并追加新语音）。它最多等待 1.5 秒获取最终转录结果，然后回退到当前文本。
+- 提示音/浮层日志以 `info` 级别输出，分类为 `voicewake.overlay`、`voicewake.ptt` 和 `voicewake.chime`（会话开始、部分、最终、发送、关闭、提示音原因）。
+
+### 后续步骤
+
+1. **VoiceSessionCoordinator（actor）**
+   - 同一时间只拥有一个 `VoiceSession`。
+   - API（基于令牌）：`beginWakeCapture`、`beginPushToTalk`、`updatePartial`、`endCapture`、`cancel`、`applyCooldown`。
+   - 丢弃携带过时令牌的回调（防止旧识别器重新打开浮层）。
+2. **VoiceSession（模型）**
+   - 字段：`token`、`source`（wakeWord|pushToTalk）、已提交/临时文本、提示音标志、计时器（自动发送、空闲）、`overlayMode`（display|editing|sending）、冷却截止时间。
+3. **浮层绑定**
+   - `VoiceSessionPublisher`（`ObservableObject`）将活跃会话镜像到 SwiftUI。
+   - `VoiceWakeOverlayView` 仅通过 publisher 渲染；绝不直接修改全局单例。
+   - 浮层用户操作（`sendNow`、`dismiss`、`edit`）携带会话令牌回调到 coordinator。
+4. **统一发送路径**
+   - `endCapture` 时：如果去除空白后文本为空 → 关闭；否则 `performSend(session:)`（播放一次发送提示音、转发、关闭）。
+   - 按键说话：无延迟；唤醒词：可选自动发送延迟。
+   - 按键说话结束后对唤醒运行时施加短暂冷却，防止唤醒词立即重新触发。
+5. **日志**
+   - Coordinator 在子系统 `bot.molt`、分类 `voicewake.overlay` 和 `voicewake.chime` 下输出 `.info` 级别日志。
+   - 关键事件：`session_started`、`adopted_by_push_to_talk`、`partial`、`finalized`、`send`、`dismiss`、`cancel`、`cooldown`。
+
+### 调试清单
+
+- 复现浮层粘滞问题时流式查看日志：
+
+  ```bash
+  sudo log stream --predicate 'subsystem == "bot.molt" AND category CONTAINS "voicewake"' --level info --style compact
+  ```
+
+- 验证只有一个活跃会话令牌；过时回调应被 coordinator 丢弃。
+- 确保按键说话松开时始终使用活跃令牌调用 `endCapture`；如果文本为空，预期 `dismiss` 且不播放提示音或发送。
+
+### 迁移步骤（建议）
+
+1. 添加 `VoiceSessionCoordinator`、`VoiceSession` 和 `VoiceSessionPublisher`。
+2. 重构 `VoiceWakeRuntime`，使其创建/更新/结束会话，而非直接操作 `VoiceWakeOverlayController`。
+3. 重构 `VoicePushToTalk`，使其接管现有会话并在松开时调用 `endCapture`；施加运行时冷却。
+4. 将 `VoiceWakeOverlayController` 连接到 publisher；移除来自 runtime/PTT 的直接调用。
+5. 添加会话接管、冷却和空文本关闭的集成测试。

package/docs/zh-CN/platforms/mac/voicewake.md

@@ -0,0 +1,74 @@
+---
+read_when:
+  - 正在开发语音唤醒或按键通话相关功能
+summary: Mac 应用中的语音唤醒和按键通话模式及路由详情
+title: 语音唤醒
+x-i18n:
+  generated_at: "2026-02-01T21:33:32Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: f6440bb89f349ba5c1c9aacffe95e568681beb9899ca736dedfe2f4a366cb5e4
+  source_path: platforms/mac/voicewake.md
+  workflow: 15
+---
+
+# 语音唤醒与按键通话
+
+## 模式
+
+- **唤醒词模式**（默认）：常驻语音识别器等待触发词（`swabbleTriggerWords`）。匹配后开始采集，显示叠加层并展示部分文本，静默后自动发送。
+- **按键通话（长按右 Option 键）**：长按右 Option 键立即开始采集——无需触发词。长按期间显示叠加层；松开后完成采集并在短暂延迟后转发，以便你调整文本。
+
+## 运行时行为（唤醒词）
+
+- 语音识别器位于 `VoiceWakeRuntime` 中。
+- 仅当唤醒词和下一个词之间存在**有意义的停顿**（约 0.55 秒间隔）时才会触发。叠加层/提示音可以在停顿时启动，甚至在命令开始之前。
+- 静默窗口：语音持续时为 2.0 秒，仅听到触发词时为 5.0 秒。
+- 硬停止：120 秒，防止会话失控。
+- 会话间去抖：350 毫秒。
+- 叠加层通过 `VoiceWakeOverlayController` 驱动，具有已确认/临时着色。
+- 发送后，识别器干净重启以监听下一个触发词。
+
+## 生命周期不变量
+
+- 如果语音唤醒已启用且权限已授予，唤醒词识别器应保持监听状态（显式按键通话采集期间除外）。
+- 叠加层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。
+
+## 叠加层卡住故障模式（历史问题）
+
+此前，如果叠加层卡在可见状态并且你手动关闭它，语音唤醒可能表现为"无响应"，因为运行时的重启尝试会被叠加层可见性阻塞，且不会调度后续重启。
+
+加固措施：
+
+- 唤醒运行时重启不再被叠加层可见性阻塞。
+- 叠加层关闭完成后通过 `VoiceSessionCoordinator` 触发 `VoiceWakeRuntime.refresh(...)`，因此手动点击 X 关闭始终会恢复监听。
+
+## 按键通话详情
+
+- 热键检测使用全局 `.flagsChanged` 监视器检测**右 Option 键**（`keyCode 61` + `.option`）。我们仅观察事件（不拦截）。
+- 采集管道位于 `VoicePushToTalk` 中：立即启动语音识别，将部分结果流式传输到叠加层，松开时调用 `VoiceWakeForwarder`。
+- 按键通话开始时，我们暂停唤醒词运行时以避免音频输入冲突；松开后自动重启。
+- 权限：需要麦克风 + 语音识别权限；查看事件需要辅助功能/输入监控授权。
+- 外接键盘：某些键盘可能无法按预期暴露右 Option 键——如果用户反馈未响应，请提供备用快捷键。
+
+## 面向用户的设置
+
+- **语音唤醒**开关：启用唤醒词运行时。
+- **长按 Cmd+Fn 说话**：启用按键通话监视器。在 macOS < 26 上禁用。
+- 语言和麦克风选择器、实时电平指示器、触发词表格、测试器（仅本地；不进行转发）。
+- 麦克风选择器在设备断开时保留上次选择，显示断开提示，并在设备恢复前临时回退到系统默认设备。
+- **声音**：触发检测和发送时播放提示音；默认使用 macOS "Glass" 系统声音。你可以为每个事件选择任何 `NSSound` 可加载的文件（如 MP3/WAV/AIFF），或选择**无声音**。
+
+## 转发行为
+
+- 启用语音唤醒后，转录文本将转发到活跃的 Gateway网关/智能体（与 Mac 应用其他部分使用的本地/远程模式相同）。
+- 回复将发送到**最近使用的主要提供商**（WhatsApp/Telegram/Discord/WebChat）。如果发送失败，错误会被记录，且运行仍可通过 WebChat/会话日志查看。
+
+## 转发载荷
+
+- `VoiceWakeForwarder.prefixedTranscript(_:)` 在发送前添加机器提示前缀。唤醒词和按键通话路径共用此逻辑。
+
+## 快速验证
+
+- 开启按键通话，长按 Cmd+Fn，说话，松开：叠加层应显示部分结果然后发送。
+- 长按期间，菜单栏耳朵图标应保持放大状态（使用 `triggerVoiceEars(ttl:nil)`）；松开后恢复。

package/docs/zh-CN/platforms/mac/webchat.md

@@ -0,0 +1,43 @@
+---
+read_when:
+  - 调试 Mac WebChat 视图或 local loopback 端口
+summary: Mac 应用如何嵌入 Gateway网关 WebChat 以及如何调试
+title: WebChat
+x-i18n:
+  generated_at: "2026-02-01T21:33:23Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 04ff448758e530098e2004625f33e42fc3dbe31137cd3beec2d55590e507de08
+  source_path: platforms/mac/webchat.md
+  workflow: 15
+---
+
+# WebChat（macOS 应用）
+
+macOS 菜单栏应用将 WebChat UI 嵌入为原生 SwiftUI 视图。它连接到 Gateway网关，默认使用所选智能体的**主会话**（通过会话切换器可访问其他会话）。
+
+- **本地模式**：直接连接到本地 Gateway网关 WebSocket。
+- **远程模式**：通过 SSH 转发 Gateway网关控制端口，并使用该隧道作为数据平面。
+
+## 启动与调试
+
+- 手动：Lobster 菜单 → "Open Chat"。
+- 测试时自动打开：
+  ```bash
+  dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat
+  ```
+- 日志：`./scripts/clawlog.sh`（子系统 `bot.molt`，类别 `WebChatSwiftUI`）。
+
+## 工作原理
+
+- 数据平面：Gateway网关 WS 方法 `chat.history`、`chat.send`、`chat.abort`、`chat.inject` 以及事件 `chat`、`agent`、`presence`、`tick`、`health`。
+- 会话：默认使用主会话（`main`，或作用域为全局时使用 `global`）。UI 可在会话之间切换。
+- 新手引导使用专用会话，以将首次运行设置与其他内容分开。
+
+## 安全面
+
+- 远程模式仅通过 SSH 转发 Gateway网关 WebSocket 控制端口。
+
+## 已知限制
+
+- UI 针对聊天会话进行了优化（不是完整的浏览器沙箱）。

package/docs/zh-CN/platforms/mac/xpc.md

@@ -0,0 +1,68 @@
+---
+read_when:
+  - 编辑 IPC 协议或菜单栏应用 IPC
+summary: OpenClaw 应用、gateway 节点传输和 PeekabooBridge 的 macOS IPC 架构
+title: macOS IPC
+x-i18n:
+  generated_at: "2026-02-01T21:33:31Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d0211c334a4a59b71afb29dd7b024778172e529fa618985632d3d11d795ced92
+  source_path: platforms/mac/xpc.md
+  workflow: 15
+---
+
+# OpenClaw macOS IPC 架构
+
+**当前模型：** 本地 Unix 套接字将**节点宿主服务**连接到 **macOS 应用**，用于执行审批和 `system.run`。存在一个 `openclaw-mac` 调试 CLI 用于发现/连接检查；智能体操作仍通过 Gateway网关 WebSocket 和 `node.invoke` 传递。UI 自动化使用 PeekabooBridge。
+
+## 目标
+
+- 单个 GUI 应用实例负责所有面向 TCC 的工作（通知、屏幕录制、麦克风、语音、AppleScript）。
+- 精简的自动化接口：Gateway网关 + 节点命令，加上用于 UI 自动化的 PeekabooBridge。
+- 可预测的权限：始终使用相同的已签名 bundle ID，由 launchd 启动，确保 TCC 授权持久有效。
+
+## 工作原理
+
+### Gateway网关 + 节点传输
+
+- 应用运行 Gateway网关（本地模式）并作为节点连接到它。
+- 智能体操作通过 `node.invoke` 执行（例如 `system.run`、`system.notify`、`canvas.*`）。
+
+### 节点服务 + 应用 IPC
+
+- 无界面的节点宿主服务通过 WebSocket 连接到 Gateway网关。
+- `system.run` 请求通过本地 Unix 套接字转发到 macOS 应用。
+- 应用在 UI 上下文中执行操作，必要时提示用户确认，并返回输出。
+
+架构图（SCI）：
+
+```
+Agent -> Gateway网关 -> Node Service (WS)
+                      |  IPC (UDS + token + HMAC + TTL)
+                      v
+                  Mac App (UI + TCC + system.run)
+```
+
+### PeekabooBridge（UI 自动化）
+
+- UI 自动化使用名为 `bridge.sock` 的独立 UNIX 套接字和 PeekabooBridge JSON 协议。
+- 宿主优先级顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
+- 安全性：bridge 宿主要求允许的 TeamID；仅 DEBUG 模式下的同 UID 回退机制受 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（Peekaboo 约定）保护。
+- 详见：[PeekabooBridge 用法](/platforms/mac/peekaboo)。
+
+## 操作流程
+
+- 重启/重新构建：`SIGN_IDENTITY="Apple Development: <Developer Name> (<TEAMID>)" scripts/restart-mac.sh`
+  - 终止现有实例
+  - Swift 构建 + 打包
+  - 写入/引导/启动 LaunchAgent
+- 单实例：如果另一个具有相同 bundle ID 的实例正在运行，应用会提前退出。
+
+## 安全加固说明
+
+- 优先要求所有特权接口进行 TeamID 匹配。
+- PeekabooBridge：`PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1`（仅 DEBUG 模式）可允许同 UID 调用方用于本地开发。
+- 所有通信仅限本地；不暴露网络套接字。
+- TCC 提示仅来自 GUI 应用 bundle；跨重新构建时保持已签名的 bundle ID 稳定。
+- IPC 加固：套接字模式 `0600`、令牌、对端 UID 检查、HMAC 质询/响应、短 TTL。