@gguf/claw 2026.2.1 → 2026.2.3

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

@@ -0,0 +1,127 @@
+---
+read_when:
+  - 实现 macOS Canvas 面板
+  - 为可视化工作区添加智能体控制
+  - 调试 WKWebView canvas 加载问题
+summary: 智能体控制的 Canvas 面板，通过 WKWebView + 自定义 URL scheme 嵌入
+title: Canvas
+x-i18n:
+  generated_at: "2026-02-01T21:32:34Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: e39caa21542e839d9f59ad0bf7ecefb379225ed7e8f00cd59131d188f193bec6
+  source_path: platforms/mac/canvas.md
+  workflow: 15
+---
+
+# Canvas（macOS 应用）
+
+macOS 应用使用 `WKWebView` 嵌入了一个智能体控制的 **Canvas 面板**。它是一个轻量级的可视化工作区，用于 HTML/CSS/JS、A2UI 以及小型交互式 UI 界面。
+
+## Canvas 的存储位置
+
+Canvas 状态存储在 Application Support 目录下：
+
+- `~/Library/Application Support/OpenClaw/canvas/<session>/...`
+
+Canvas 面板通过**自定义 URL scheme** 提供这些文件：
+
+- `openclaw-canvas://<session>/<path>`
+
+示例：
+
+- `openclaw-canvas://main/` → `<canvasRoot>/main/index.html`
+- `openclaw-canvas://main/assets/app.css` → `<canvasRoot>/main/assets/app.css`
+- `openclaw-canvas://main/widgets/todo/` → `<canvasRoot>/main/widgets/todo/index.html`
+
+如果根目录下不存在 `index.html`，应用会显示一个**内置脚手架页面**。
+
+## 面板行为
+
+- 无边框、可调整大小的面板，锚定在菜单栏（或鼠标光标）附近。
+- 按会话记忆大小/位置。
+- 本地 canvas 文件变更时自动重新加载。
+- 同一时间只显示一个 Canvas 面板（根据需要切换会话）。
+
+可以在设置 → **允许 Canvas** 中禁用 Canvas。禁用后，canvas 节点命令返回 `CANVAS_DISABLED`。
+
+## 智能体 API 接口
+
+Canvas 通过 **Gateway网关 WebSocket** 暴露，因此智能体可以：
+
+- 显示/隐藏面板
+- 导航到路径或 URL
+- 执行 JavaScript
+- 捕获快照图像
+
+CLI 示例：
+
+```bash
+openclaw nodes canvas present --node <id>
+openclaw nodes canvas navigate --node <id> --url "/"
+openclaw nodes canvas eval --node <id> --js "document.title"
+openclaw nodes canvas snapshot --node <id>
+```
+
+注意事项：
+
+- `canvas.navigate` 接受**本地 canvas 路径**、`http(s)` URL 和 `file://` URL。
+- 如果传入 `"/"`，Canvas 会显示本地脚手架或 `index.html`。
+
+## Canvas 中的 A2UI
+
+A2UI 由 Gateway网关 canvas 主机托管，并在 Canvas 面板内渲染。当 Gateway网关广播 Canvas 主机时，macOS 应用在首次打开时会自动导航到 A2UI 主机页面。
+
+默认 A2UI 主机 URL：
+
+```
+http://<gateway-host>:18793/__openclaw__/a2ui/
+```
+
+### A2UI 命令（v0.8）
+
+Canvas 当前接受 **A2UI v0.8** 服务端→客户端消息：
+
+- `beginRendering`
+- `surfaceUpdate`
+- `dataModelUpdate`
+- `deleteSurface`
+
+不支持 `createSurface`（v0.9）。
+
+CLI 示例：
+
+```bash
+cat > /tmp/a2ui-v0.8.jsonl <<'EOFA2'
+{"surfaceUpdate":{"surfaceId":"main","components":[{"id":"root","component":{"Column":{"children":{"explicitList":["title","content"]}}}},{"id":"title","component":{"Text":{"text":{"literalString":"Canvas (A2UI v0.8)"},"usageHint":"h1"}}},{"id":"content","component":{"Text":{"text":{"literalString":"If you can read this, A2UI push works."},"usageHint":"body"}}}]}}
+{"beginRendering":{"surfaceId":"main","root":"root"}}
+EOFA2
+
+openclaw nodes canvas a2ui push --jsonl /tmp/a2ui-v0.8.jsonl --node <id>
+```
+
+快速冒烟测试：
+
+```bash
+openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"
+```
+
+## 从 Canvas 触发智能体运行
+
+Canvas 可以通过深层链接触发新的智能体运行：
+
+- `openclaw://agent?...`
+
+示例（在 JS 中）：
+
+```js
+window.location.href = "openclaw://agent?message=Review%20this%20design";
+```
+
+除非提供有效密钥，否则应用会提示确认。
+
+## 安全注意事项
+
+- Canvas scheme 阻止目录遍历；文件必须位于会话根目录下。
+- 本地 Canvas 内容使用自定义 scheme（无需 local loopback 服务器）。
+- 仅在显式导航时才允许外部 `http(s)` URL。

package/docs/zh-CN/platforms/mac/child-process.md

@@ -0,0 +1,62 @@
+---
+read_when:
+  - 将 Mac 应用与 Gateway网关生命周期集成
+summary: macOS 上的 Gateway网关生命周期（launchd）
+title: Gateway网关生命周期
+x-i18n:
+  generated_at: "2026-02-01T21:32:36Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 9b910f574b723bc194ac663a5168e48d95f55cb468ce34c595d8ca60d3463c6a
+  source_path: platforms/mac/child-process.md
+  workflow: 15
+---
+
+# macOS 上的 Gateway网关生命周期
+
+macOS 应用默认**通过 launchd 管理 Gateway网关**，不会将 Gateway网关作为子进程启动。它首先尝试连接到已在配置端口上运行的 Gateway网关；如果无法连接，则通过外部 `openclaw` CLI（无内嵌运行时）启用 launchd 服务。这为你提供了可靠的登录自启动和崩溃后自动重启。
+
+子进程模式（由应用直接启动 Gateway网关）**目前未使用**。如果你需要与 UI 更紧密的耦合，请在终端中手动运行 Gateway网关。
+
+## 默认行为（launchd）
+
+- 应用安装一个标签为 `bot.molt.gateway` 的用户级 LaunchAgent（使用 `--profile`/`OPENCLAW_PROFILE` 时为 `bot.molt.<profile>`；兼容旧版 `com.openclaw.*`）。
+- 当启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway网关。
+- 日志写入 launchd Gateway网关日志路径（可在调试设置中查看）。
+
+常用命令：
+
+```bash
+launchctl kickstart -k gui/$UID/bot.molt.gateway
+launchctl bootout gui/$UID/bot.molt.gateway
+```
+
+运行命名配置文件时，请将标签替换为 `bot.molt.<profile>`。
+
+## 未签名的开发构建
+
+`scripts/restart-mac.sh --no-sign` 用于在没有签名密钥时进行快速本地构建。为防止 launchd 指向未签名的中继二进制文件，它会：
+
+- 写入 `~/.openclaw/disable-launchagent`。
+
+已签名的 `scripts/restart-mac.sh` 运行会在检测到该标记文件时清除此覆盖。手动重置方法：
+
+```bash
+rm ~/.openclaw/disable-launchagent
+```
+
+## 仅连接模式
+
+要强制 macOS 应用**永不安装或管理 launchd**，请使用 `--attach-only`（或 `--no-launchd`）启动。这会设置 `~/.openclaw/disable-launchagent`，使应用仅连接到已运行的 Gateway网关。你也可以在调试设置中切换相同的行为。
+
+## 远程模式
+
+远程模式不会启动本地 Gateway网关。应用使用 SSH 隧道连接到远程主机，并通过该隧道进行通信。
+
+## 为何优先选择 launchd
+
+- 登录时自动启动。
+- 内置重启/KeepAlive 语义。
+- 可预测的日志和进程监管。
+
+如果将来再次需要真正的子进程模式，应将其作为独立的、明确的开发专用模式进行文档记录。

package/docs/zh-CN/platforms/mac/dev-setup.md

@@ -0,0 +1,109 @@
+---
+read_when:
+  - 设置 macOS 开发环境
+summary: 面向 OpenClaw macOS 应用开发者的设置指南
+title: macOS 开发环境设置
+x-i18n:
+  generated_at: "2026-02-01T21:32:41Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 4ea67701bd58b7512f945fce58d79e1b3d990fbf45183323a1e3ab9688827623
+  source_path: platforms/mac/dev-setup.md
+  workflow: 15
+---
+
+# macOS 开发者设置
+
+本指南介绍从源代码构建和运行 OpenClaw macOS 应用的必要步骤。
+
+## 前提条件
+
+在构建应用之前，请确保已安装以下内容：
+
+1.  **Xcode 26.2+**：Swift 开发所需。
+2.  **Node.js 22+ & pnpm**：Gateway网关、CLI 和打包脚本所需。
+
+## 1. 安装依赖
+
+安装项目的全部依赖：
+
+```bash
+pnpm install
+```
+
+## 2. 构建和打包应用
+
+要构建 macOS 应用并将其打包为 `dist/OpenClaw.app`，请运行：
+
+```bash
+./scripts/package-mac-app.sh
+```
+
+如果你没有 Apple Developer ID 证书，脚本将自动使用**临时签名**（`-`）。
+
+有关开发运行模式、签名选项和 Team ID 故障排除，请参阅 macOS 应用 README：
+https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md
+
+> **注意**：临时签名的应用可能会触发安全提示。如果应用立即崩溃并显示 "Abort trap 6"，请参阅[故障排除](#troubleshooting)部分。
+
+## 3. 安装 CLI
+
+macOS 应用需要全局安装 `openclaw` CLI 来管理后台任务。
+
+**安装方式（推荐）：**
+
+1.  打开 OpenClaw 应用。
+2.  进入 **General** 设置选项卡。
+3.  点击 **"Install CLI"**。
+
+或者手动安装：
+
+```bash
+npm install -g openclaw@<version>
+```
+
+## 故障排除
+
+### 构建失败：工具链或 SDK 不匹配
+
+macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。
+
+**系统依赖（必需）：**
+
+- **软件更新中可用的最新 macOS 版本**（Xcode 26.2 SDK 要求）
+- **Xcode 26.2**（Swift 6.2 工具链）
+
+**检查：**
+
+```bash
+xcodebuild -version
+xcrun swift --version
+```
+
+如果版本不匹配，请更新 macOS/Xcode 并重新运行构建。
+
+### 授权时应用崩溃
+
+如果在尝试允许**语音识别**或**麦克风**访问时应用崩溃，可能是由于 TCC 缓存损坏或签名不匹配。
+
+**修复方法：**
+
+1. 重置 TCC 权限：
+   ```bash
+   tccutil reset All bot.molt.mac.debug
+   ```
+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..."，请检查是否有僵尸进程占用了端口：
+
+```bash
+openclaw gateway status
+openclaw gateway stop
+
+# 如果你没有使用 LaunchAgent（开发模式/手动运行），查找监听进程：
+lsof -nP -iTCP:18789 -sTCP:LISTEN
+```
+
+如果是手动运行的进程占用了端口，请停止该进程（Ctrl+C）。作为最后手段，终止上面找到的 PID。

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

@@ -0,0 +1,41 @@
+---
+read_when:
+  - 调试 Mac 应用健康指示器
+summary: macOS 应用如何报告 Gateway网关/Baileys 健康状态
+title: 健康检查
+x-i18n:
+  generated_at: "2026-02-01T21:32:43Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 0560e96501ddf53a499f8960cfcf11c2622fcb9056bfd1bcc57876e955cab03d
+  source_path: platforms/mac/health.md
+  workflow: 15
+---
+
+# macOS 上的健康检查
+
+如何从菜单栏应用查看已关联渠道的健康状态。
+
+## 菜单栏
+
+- 状态圆点现在反映 Baileys 健康状态：
+  - 绿色：已关联 + socket 近期已打开。
+  - 橙色：正在连接/重试中。
+  - 红色：已登出或探测失败。
+- 次要行显示 "linked · auth 12m" 或显示失败原因。
+- "运行健康检查" 菜单项可触发按需探测。
+
+## 设置
+
+- 通用选项卡新增健康卡片，显示：已关联认证时长、会话存储路径/数量、上次检查时间、上次错误/状态码，以及"运行健康检查"/"显示日志"按钮。
+- 使用缓存快照，使 UI 即时加载，离线时优雅降级。
+- **渠道选项卡**展示渠道状态 + WhatsApp/Telegram 的控制项（登录二维码、登出、探测、上次断连/错误）。
+
+## 探测工作原理
+
+- 应用每约 60 秒以及按需通过 `ShellExecutor` 运行 `openclaw health --json`。探测会加载凭据并报告状态，不会发送消息。
+- 分别缓存上次成功的快照和上次错误，以避免闪烁；显示各自的时间戳。
+
+## 不确定时
+
+- 你仍然可以使用 [Gateway网关健康检查](/gateway/health) 中的 CLI 流程（`openclaw status`、`openclaw status --deep`、`openclaw health --json`），并跟踪 `/tmp/openclaw/openclaw-*.log` 中的 `web-heartbeat` / `web-reconnect`。

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

@@ -0,0 +1,38 @@
+---
+read_when:
+  - 更改菜单栏图标行为
+summary: macOS 上 OpenClaw 菜单栏图标的状态和动画
+title: 菜单栏图标
+x-i18n:
+  generated_at: "2026-02-01T21:32:49Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: a67a6e6bbdc2b611ba365d3be3dd83f9e24025d02366bc35ffcce9f0b121872b
+  source_path: platforms/mac/icon.md
+  workflow: 15
+---
+
+# 菜单栏图标状态
+
+作者：steipete · 更新时间：2025-12-06 · 范围：macOS 应用（`apps/macos`）
+
+- **空闲：** 正常图标动画（眨眼、偶尔摆动）。
+- **暂停：** 状态项使用 `appearsDisabled`；无动画。
+- **语音触发（大耳朵）：** 语音唤醒检测器在听到唤醒词时调用 `AppState.triggerVoiceEars(ttl: nil)`，在捕获语音期间保持 `earBoostActive=true`。耳朵放大（1.9 倍），显示圆形耳孔以提高可读性，然后在 1 秒静音后通过 `stopVoiceEars()` 恢复。仅由应用内语音管道触发。
+- **工作中（智能体运行中）：** `AppState.isWorking=true` 驱动"尾巴/腿部快速摆动"微动画：工作进行中腿部摆动加快并略有偏移。目前在 WebChat 智能体运行时切换；在接入其他长时间任务时请添加相同的切换逻辑。
+
+接入点
+
+- 语音唤醒：运行时/测试器在触发时调用 `AppState.triggerVoiceEars(ttl: nil)`，在 1 秒静音后调用 `stopVoiceEars()` 以匹配捕获窗口。
+- 智能体活动：在工作区间前后设置 `AppStateStore.shared.setWorking(true/false)`（已在 WebChat 智能体调用中完成）。保持区间简短，并在 `defer` 块中重置以避免动画卡住。
+
+形状与尺寸
+
+- 基础图标在 `CritterIconRenderer.makeIcon(blink:legWiggle:earWiggle:earScale:earHoles:)` 中绘制。
+- 耳朵缩放默认为 `1.0`；语音增强时设置 `earScale=1.9` 并切换 `earHoles=true`，不改变整体框架（18×18 pt 模板图像渲染到 36×36 px Retina 后备存储）。
+- 快速摆动使用最高约 1.0 的腿部摆幅并带有轻微的水平抖动；它与现有的空闲摆动叠加。
+
+行为说明
+
+- 耳朵/工作状态没有外部 CLI/代理切换；保持仅由应用自身信号控制，以避免意外的状态抖动。
+- 保持 TTL 较短（<10 秒），以便在任务挂起时图标能快速恢复到基准状态。

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

@@ -0,0 +1,64 @@
+---
+read_when:
+  - 捕获 macOS 日志或调查隐私数据日志记录
+  - 调试语音唤醒/会话生命周期问题
+summary: OpenClaw 日志：滚动诊断文件日志 + 统一日志隐私标志
+title: macOS 日志
+x-i18n:
+  generated_at: "2026-02-01T21:32:54Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: c4c201d154915e0eb08bf5e32bac98fa93766f50f2a24bf56ab4424eb7781526
+  source_path: platforms/mac/logging.md
+  workflow: 15
+---
+
+# 日志（macOS）
+
+## 滚动诊断文件日志（Debug 面板）
+
+OpenClaw 通过 swift-log（默认使用统一日志）路由 macOS 应用日志，并且在需要持久化捕获时可以将本地轮转文件日志写入磁盘。
+
+- 详细级别：**Debug 面板 → Logs → App logging → Verbosity**
+- 启用：**Debug 面板 → Logs → App logging → "Write rolling diagnostics log (JSONL)"**
+- 位置：`~/Library/Logs/OpenClaw/diagnostics.jsonl`（自动轮转；旧文件以 `.1`、`.2`、… 为后缀）
+- 清除：**Debug 面板 → Logs → App logging → "Clear"**
+
+注意事项：
+
+- 此功能**默认关闭**。仅在主动调试时启用。
+- 该文件包含敏感信息；分享前请先审查内容。
+
+## macOS 上统一日志的隐私数据
+
+统一日志会屏蔽大部分负载内容，除非子系统选择启用 `privacy -off`。根据 Peter 关于 macOS [日志隐私机制](https://steipete.me/posts/2025/logging-privacy-shenanigans)（2025）的文章，这通过 `/Library/Preferences/Logging/Subsystems/` 中以子系统名称为键的 plist 文件来控制。只有新的日志条目才会应用该标志，因此请在复现问题之前启用它。
+
+## 为 OpenClaw 启用（`bot.molt`）
+
+- 先将 plist 写入临时文件，然后以 root 身份原子性地安装：
+
+```bash
+cat <<'EOF' >/tmp/bot.molt.plist
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+    <key>DEFAULT-OPTIONS</key>
+    <dict>
+        <key>Enable-Private-Data</key>
+        <true/>
+    </dict>
+</dict>
+</plist>
+EOF
+sudo install -m 644 -o root -g wheel /tmp/bot.molt.plist /Library/Preferences/Logging/Subsystems/bot.molt.plist
+```
+
+- 无需重启；logd 会很快检测到该文件，但只有新的日志行才会包含隐私负载。
+- 使用现有的辅助脚本查看更丰富的输出，例如 `./scripts/clawlog.sh --category WebChat --last 5m`。
+
+## 调试后禁用
+
+- 移除覆盖配置：`sudo rm /Library/Preferences/Logging/Subsystems/bot.molt.plist`。
+- 可选择运行 `sudo log config --reload` 强制 logd 立即丢弃覆盖配置。
+- 请注意此数据可能包含电话号码和消息正文；仅在确实需要额外详细信息时才保留该 plist 文件。

package/docs/zh-CN/platforms/mac/menu-bar.md

@@ -0,0 +1,88 @@
+---
+read_when:
+  - 调整 Mac 菜单 UI 或状态逻辑
+summary: 菜单栏状态逻辑及向用户展示的内容
+title: 菜单栏
+x-i18n:
+  generated_at: "2026-02-01T21:33:00Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: 8eb73c0e671a76aae4ebb653c65147610bf3e6d3c9c0943d150e292e7761d16d
+  source_path: platforms/mac/menu-bar.md
+  workflow: 15
+---
+
+# 菜单栏状态逻辑
+
+## 显示内容
+
+- 我们在菜单栏图标和菜单的第一行状态行中展示当前智能体的工作状态。
+- 工作活跃时隐藏健康状态；当所有会话空闲时恢复显示。
+- 菜单中的"节点"区块仅列出**设备**（通过 `node.list` 配对的节点），不包括客户端/在线状态条目。
+- 当提供商用量快照可用时，"用量"部分会显示在上下文下方。
+
+## 状态模型
+
+- 会话：事件携带 `runId`（每次运行）以及载荷中的 `sessionKey`。"main" 会话的键为 `main`；如果不存在，则回退到最近更新的会话。
+- 优先级：main 始终优先。如果 main 处于活跃状态，立即显示其状态。如果 main 空闲，则显示最近活跃的非 main 会话。活动进行中不会来回切换；仅在当前会话进入空闲或 main 变为活跃时才切换。
+- 活动类型：
+  - `job`：高层命令执行（`state: started|streaming|done|error`）。
+  - `tool`：`phase: start|result`，包含 `toolName` 和 `meta/args`。
+
+## IconState 枚举（Swift）
+
+- `idle`
+- `workingMain(ActivityKind)`
+- `workingOther(ActivityKind)`
+- `overridden(ActivityKind)`（调试覆盖）
+
+### ActivityKind → 图标符号
+
+- `exec` → 💻
+- `read` → 📄
+- `write` → ✍️
+- `edit` → 📝
+- `attach` → 📎
+- 默认 → 🛠️
+
+### 视觉映射
+
+- `idle`：正常小动物图标。
+- `workingMain`：带图标符号的徽章，完整色调，腿部"工作"动画。
+- `workingOther`：带图标符号的徽章，柔和色调，无快跑动画。
+- `overridden`：无论活动状态如何，使用所选的图标符号/色调。
+
+## 状态行文本（菜单）
+
+- 工作活跃时：`<会话角色> · <活动标签>`
+  - 示例：`Main · exec: pnpm test`、`Other · read: apps/macos/Sources/OpenClaw/AppState.swift`。
+- 空闲时：回退显示健康摘要。
+
+## 事件接收
+
+- 来源：控制渠道 `agent` 事件（`ControlChannel.handleAgentEvent`）。
+- 解析字段：
+  - `stream: "job"`，包含 `data.state` 用于启动/停止。
+  - `stream: "tool"`，包含 `data.phase`、`name`，可选 `meta`/`args`。
+- 标签：
+  - `exec`：`args.command` 的第一行。
+  - `read`/`write`：缩短的路径。
+  - `edit`：路径加上从 `meta`/diff 计数推断的变更类型。
+  - 回退：工具名称。
+
+## 调试覆盖
+
+- 设置 ▸ 调试 ▸ "图标覆盖" 选择器：
+  - `系统（自动）`（默认）
+  - `工作中：main`（按工具类型）
+  - `工作中：other`（按工具类型）
+  - `空闲`
+- 通过 `@AppStorage("iconOverride")` 存储；映射到 `IconState.overridden`。
+
+## 测试清单
+
+- 触发 main 会话任务：验证图标立即切换且状态行显示 main 标签。
+- main 空闲时触发非 main 会话任务：图标/状态显示非 main；保持稳定直到完成。
+- 在 other 活跃时启动 main：图标立即切换到 main。
+- 快速连续工具调用：确保徽章不会闪烁（工具结果的 TTL 宽限期）。
+- 所有会话空闲后健康行重新出现。

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

@@ -0,0 +1,62 @@
+---
+read_when:
+  - 在 OpenClaw.app 中托管 PeekabooBridge
+  - 通过 Swift Package Manager 集成 Peekaboo
+  - 更改 PeekabooBridge 协议/路径
+summary: 用于 macOS UI 自动化的 PeekabooBridge 集成
+title: Peekaboo Bridge
+x-i18n:
+  generated_at: "2026-02-01T21:32:57Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: b5b9ddb9a7c59e153a1d5d23c33616bb1542b5c7dadedc3af340aeee9ba03487
+  source_path: platforms/mac/peekaboo.md
+  workflow: 15
+---
+
+# Peekaboo Bridge（macOS UI 自动化）
+
+OpenClaw 可以将 **PeekabooBridge** 作为本地的、权限感知的 UI 自动化代理进行托管。这使得 `peekaboo` CLI 能够驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。
+
+## 这是什么（以及不是什么）
+
+- **宿主**：OpenClaw.app 可以作为 PeekabooBridge 宿主。
+- **客户端**：使用 `peekaboo` CLI（无需单独的 `openclaw ui ...` 界面）。
+- **界面**：视觉叠加层保留在 Peekaboo.app 中；OpenClaw 只是一个轻量代理宿主。
+
+## 启用桥接
+
+在 macOS 应用中：
+
+- 设置 → **启用 Peekaboo Bridge**
+
+启用后，OpenClaw 会启动一个本地 UNIX 套接字服务器。如果禁用，宿主会停止，`peekaboo` 将回退到其他可用宿主。
+
+## 客户端发现顺序
+
+Peekaboo 客户端通常按以下顺序尝试宿主：
+
+1. Peekaboo.app（完整用户体验）
+2. Claude.app（如已安装）
+3. OpenClaw.app（轻量代理）
+
+使用 `peekaboo bridge status --verbose` 查看当前活跃的宿主及使用的套接字路径。你可以通过以下方式覆盖：
+
+```bash
+export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock
+```
+
+## 安全与权限
+
+- 桥接会验证**调用方的代码签名**；强制执行 TeamID 白名单（Peekaboo 宿主 TeamID + OpenClaw 应用 TeamID）。
+- 请求在约 10 秒后超时。
+- 如果缺少所需权限，桥接会返回清晰的错误信息，而不是启动系统设置。
+
+## 快照行为（自动化）
+
+快照存储在内存中，并在短暂窗口期后自动过期。如果需要更长的保留时间，请从客户端重新捕获。
+
+## 故障排除
+
+- 如果 `peekaboo` 报告"bridge client is not authorized"，请确保客户端已正确签名，或仅在**调试**模式下使用 `PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1` 运行宿主。
+- 如果未找到宿主，请打开其中一个宿主应用（Peekaboo.app 或 OpenClaw.app）并确认已授予权限。

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

@@ -0,0 +1,46 @@
+---
+read_when:
+  - 调试缺失或卡住的 macOS 权限提示
+  - 打包或签名 macOS 应用
+  - 更改 Bundle ID 或应用安装路径
+summary: macOS 权限持久化（TCC）和签名要求
+title: macOS 权限
+x-i18n:
+  generated_at: "2026-02-01T21:32:58Z"
+  model: claude-opus-4-5
+  provider: pi
+  source_hash: d012589c0583dd0b3792d695f3f71a6ff265704cf02a3b79f8c4a5b14712e6aa
+  source_path: platforms/mac/permissions.md
+  workflow: 15
+---
+
+# macOS 权限（TCC）
+
+macOS 权限授予是脆弱的。TCC 将权限授予与应用的代码签名、Bundle 标识符和磁盘路径关联。如果其中任何一项发生变化，macOS 会将该应用视为新应用，可能会丢弃或隐藏权限提示。
+
+## 稳定权限的要求
+
+- 相同路径：从固定位置运行应用（对于 OpenClaw，为 `dist/OpenClaw.app`）。
+- 相同 Bundle 标识符：更改 Bundle ID 会创建新的权限身份。
+- 已签名的应用：未签名或临时签名的构建不会持久化权限。
+- 一致的签名：使用真实的 Apple Development 或 Developer ID 证书，以确保签名在多次构建之间保持稳定。
+
+临时签名每次构建都会生成新的身份。macOS 会忘记之前的授权，提示可能完全消失，直到清除过期条目为止。
+
+## 权限提示消失时的恢复清单
+
+1. 退出应用。
+2. 在系统设置 -> 隐私与安全性中移除该应用条目。
+3. 从相同路径重新启动应用并重新授予权限。
+4. 如果提示仍未出现，使用 `tccutil` 重置 TCC 条目后重试。
+5. 某些权限仅在完全重启 macOS 后才会重新出现。
+
+重置示例（根据需要替换 Bundle ID）：
+
+```bash
+sudo tccutil reset Accessibility bot.molt.mac
+sudo tccutil reset ScreenCapture bot.molt.mac
+sudo tccutil reset AppleEvents
+```
+
+如果你正在测试权限，请始终使用真实证书签名。临时签名的构建仅适用于不需要权限的快速本地运行。