本文档汇总了 OpenClaw 官方文档站 平台 > macOS 配套应用 子模块下的全部 17 篇内容，源自 docs.openclaw.ai/zh-CN。

📄 macOS 开发环境设置

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/dev-setup

macOS 开发者设置

从源码构建并运行 OpenClaw macOS 应用程序。

前提条件

在构建应用前，请确保已安装以下内容：

1. Xcode 26.2+：Swift 开发所需。
2. Node.js 24 和 pnpm：推荐用于 Gateway 网关、CLI 和打包脚本。为保持兼容性，仍支持 Node 22 LTS，目前为 22.16+。

1. 安装依赖项

安装整个项目的依赖项：

pnpm install

2. 构建并打包应用

要构建 macOS 应用并将其打包到 dist/OpenClaw.app，运行：

./scripts/package-mac-app.sh

如果你没有 Apple Developer ID 证书，该脚本会自动使用 ad-hoc 签名（-）。

关于开发运行模式、签名标志和 Team ID 故障排除，请参阅 macOS 应用 README：
https://github.com/openclaw/openclaw/blob/main/apps/macos/README.md

注意：ad-hoc 签名的应用可能会触发安全提示。如果应用立即崩溃并显示 "Abort trap 6"，请参阅故障排除部分。

3. 安装 CLI

macOS 应用需要全局安装 openclaw CLI 来管理后台任务。

安装方式（推荐）：

1. 打开 OpenClaw 应用。
2. 前往 General 设置标签页。
3. 点击 “安装 CLI”。

或者，也可以手动安装：

npm install -g openclaw@<version>

pnpm add -g openclaw@<version> 和 bun add -g openclaw@<version> 也可以使用。
对于 Gateway 网关运行时，Node 仍是推荐路径。

故障排除

构建失败：工具链或 SDK 不匹配

macOS 应用构建需要最新的 macOS SDK 和 Swift 6.2 工具链。

系统依赖项（必需）：

• Software Update 中可用的最新 macOS 版本（Xcode 26.2 SDK 必需）
• Xcode 26.2（Swift 6.2 工具链）

检查：

xcodebuild -version
xcrun swift --version

如果版本不匹配，请更新 macOS/Xcode，然后重新运行构建。

授予权限时应用崩溃

如果你尝试允许 Speech Recognition 或 Microphone 访问权限时应用崩溃，可能是 TCC 缓存损坏或签名不匹配导致的。

修复：

1. 重置 TCC 权限：

bash
tccutil reset All ai.openclaw.mac.debug

2. 如果仍然失败，请临时更改 scripts/package-mac-app.sh 中的 BUNDLE_ID，以强制 macOS 从“干净状态”开始。

Gateway 网关一直停留在 "Starting..."

如果 Gateway 网关状态一直停留在 "Starting..."，请检查是否有僵尸进程占用了端口：

openclaw gateway status
openclaw gateway stop

# If you're not using a LaunchAgent (dev mode / manual runs), find the listener:
lsof -nP -iTCP:18789 -sTCP:LISTEN

如果手动运行的进程占用了端口，请停止该进程（Ctrl+C）。作为最后手段，请终止上面找到的 PID。

相关

• macOS 应用
• 安装概览

📄 菜单栏

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/menu-bar

显示内容

• 我们会在菜单栏图标和菜单的第一行状态中显示当前智能体工作状态。
• 工作处于活动状态时隐藏健康状态；当所有会话都空闲时恢复显示。
• 根级“上下文”子菜单包含最近的会话，而不是直接在根菜单中展开它们。
• 根菜单中的“节点”区块仅列出设备（通过 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：无论活动如何，都使用选定的字形/着色。

上下文子菜单

• 根菜单显示一行“上下文”，带有会话数量/状态，并打开一个子菜单。
• 上下文子菜单标题显示过去 24 小时内的活动会话数量。
• 每个会话行都会保留其令牌条、时间、预览、思考/详细、重置、压缩和删除操作。
• 加载中、已断开连接和会话加载错误消息会显示在上下文子菜单内。
• 提供商用量和用量成本详情保持在上下文下方的根级位置，这样无需打开子菜单也能快速查看。

状态行文本（菜单）

• 工作处于活动状态时：<Session role> · <activity label>
• 示例：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 计数推断出的变更类型。
• 回退：工具名称。

调试覆盖

• 设置 ▸ 调试 ▸ “图标覆盖”选择器：
• System (auto)（默认）
• Working: main（按工具类型）
• Working: other（按工具类型）
• Idle
• 通过 @AppStorage("iconOverride") 存储；映射到 IconState.overridden。

测试检查清单

• 触发 main 会话任务：验证图标立即切换，且状态行显示 main 标签。
• main 空闲时触发非 main 会话任务：图标/状态显示非 main；保持稳定直到其完成。
• 其他会话活动时启动 main：图标立即切换到 main。
• 快速工具突发：确保徽章不闪烁（工具结果上有 TTL 宽限）。
• 所有会话空闲后，健康行重新出现。

相关

• macOS 应用
• 菜单栏图标

📄 语音唤醒（macOS）

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/voicewake

语音唤醒与按键通话

模式

• 唤醒词模式（默认）：始终开启的 Speech 识别器会等待触发词（swabbleTriggerWords）。匹配后开始采集，显示带有部分文本的浮层，并在静音后自动发送。
• 按键通话（按住右 Option 键）：按住右 Option 键即可立即采集，无需触发词。按住时会显示浮层；松开后会完成采集，并在短暂延迟后转发，方便你微调文本。

运行时行为（唤醒词）

• Speech 识别器位于 VoiceWakeRuntime。
• 只有在唤醒词和下一个词之间存在有意义的停顿（约 0.55 秒间隔）时才会触发。即使命令尚未开始，浮层/提示音也可以在停顿时启动。
• 静音窗口：语音连续输入时为 2.0 秒；如果只听到触发词，则为 5.0 秒。
• 硬停止：120 秒，用于防止失控会话。
• 会话之间的防抖：350 毫秒。
• 浮层通过 VoiceWakeOverlayController 驱动，并使用已提交/易变着色。
• 发送后，识别器会干净地重启，以监听下一个触发词。

生命周期不变量

• 如果语音唤醒已启用且权限已授予，唤醒词识别器应处于监听状态（显式按键通话采集期间除外）。
• 浮层可见性（包括通过 X 按钮手动关闭）绝不能阻止识别器恢复。

粘滞浮层故障模式（以前）

以前，如果浮层卡住并保持可见，而你手动关闭了它，语音唤醒可能会看起来“失效”，因为运行时的重启尝试可能会被浮层可见性阻塞，并且不会安排后续重启。

加固：

• 唤醒运行时重启不再被浮层可见性阻塞。
• 浮层关闭完成后会通过 VoiceSessionCoordinator 触发 VoiceWakeRuntime.refresh(...)，因此手动点击 X 关闭始终会恢复监听。

按键通话细节

• 热键检测使用全局 .flagsChanged 监视器监听右 Option（keyCode 61 + .option）。我们只观察事件（不吞掉事件）。
• 采集管线位于 VoicePushToTalk：立即启动 Speech，将部分结果流式传输到浮层，并在松开时调用 VoiceWakeForwarder。
• 按键通话开始时，我们会暂停唤醒词运行时，以避免音频 tap 相互竞争；松开后它会自动重启。
• 权限：需要麦克风 + Speech；看到事件需要辅助功能/输入监控批准。
• 外接键盘：某些键盘可能不会按预期暴露右 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)）；松开后它们会恢复。

相关内容

• 语音唤醒
• 语音浮层
• macOS 应用

📄 语音叠加层

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/voice-overlay

语音浮层生命周期（macOS）

受众：macOS 应用贡献者。目标：在唤醒词和按住说话重叠时，让语音浮层保持可预测。

当前意图

• 如果浮层已经因唤醒词而可见，且用户按下热键，热键会话会_接管_现有文本，而不是重置它。按住热键期间，浮层保持显示。用户松开时：如果有裁剪后的文本则发送，否则关闭。
• 仅唤醒词仍会在静音时自动发送；按住说话会在松开时立即发送。

已实现（2025 年 12 月 9 日）

• 浮层会话现在为每次捕获（唤醒词或按住说话）携带一个 token。当 token 不匹配时，会丢弃 partial/final/send/dismiss/level 更新，避免过期回调。
• 按住说话会接管任何可见浮层文本作为前缀（因此在唤醒浮层显示时按下热键会保留文本并追加新的语音）。它最多等待 1.5 秒获取最终转录，然后回退到当前文本。
• 铃声/浮层日志会以 info 级别输出到 voicewake.overlay、voicewake.ptt 和 voicewake.chime 类别（会话开始、partial、final、send、dismiss、铃声原因）。

后续步骤

1. VoiceSessionCoordinator（actor）
   - 同一时间仅拥有一个 VoiceSession。
   - API（基于 token）：beginWakeCapture、beginPushToTalk、updatePartial、endCapture、cancel、applyCooldown。
   - 丢弃携带过期 token 的回调（防止旧识别器重新打开浮层）。
2. VoiceSession（模型）
   - 字段：token、source（wakeWord|pushToTalk）、已提交/易变文本、铃声标志、定时器（自动发送、空闲）、overlayMode（display|editing|sending）、冷却截止时间。
3. 浮层绑定
   - VoiceSessionPublisher（ObservableObject）将活跃会话镜像到 SwiftUI。
   - VoiceWakeOverlayView 只通过发布器渲染；它绝不直接修改全局单例。
   - 浮层用户操作（sendNow、dismiss、edit）会携带会话 token 回调到协调器。
4. 统一发送路径
   - 在 endCapture 时：如果裁剪后的文本为空 → 关闭；否则 performSend(session:)（仅播放一次发送铃声、转发、关闭）。
   - 按住说话：无延迟；唤醒词：可选择延迟以便自动发送。
   - 按住说话结束后，对唤醒运行时应用短暂冷却，避免唤醒词立即再次触发。
5. 日志
   - 协调器在子系统 ai.openclaw、类别 voicewake.overlay 和 voicewake.chime 中输出 .info 日志。
   - 关键事件：session_started、adopted_by_push_to_talk、partial、finalized、send、dismiss、cancel、cooldown。

调试检查清单

• 复现粘滞浮层时流式查看日志：

bash
sudo log stream --predicate 'subsystem == "ai.openclaw" AND category CONTAINS "voicewake"' --level info --style compact

• 验证只有一个活跃会话 token；过期回调应由协调器丢弃。
• 确保按住说话松开时始终使用活跃 token 调用 endCapture；如果文本为空，预期会 dismiss，且不会播放铃声或发送。

迁移步骤（建议）

1. 添加 VoiceSessionCoordinator、VoiceSession 和 VoiceSessionPublisher。
2. 重构 VoiceWakeRuntime，改为创建/更新/结束会话，而不是直接触碰 VoiceWakeOverlayController。
3. 重构 VoicePushToTalk，以接管现有会话并在松开时调用 endCapture；应用运行时冷却。
4. 将 VoiceWakeOverlayController 接线到发布器；移除运行时/PTT 的直接调用。
5. 为会话接管、冷却和空文本关闭添加集成测试。

相关

• macOS 应用
• 语音唤醒（macOS）
• Talk 模式

📄 WebChat（macOS）

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/webchat

macOS 菜单栏应用将 WebChat 界面嵌入为原生 SwiftUI 视图。它会连接到 Gateway 网关，并默认使用所选智能体的 main 会话（也提供用于其他会话的会话切换器）。

• 本地模式：直接连接到本地 Gateway 网关 WebSocket。
• 远程模式：通过 SSH 转发 Gateway 网关控制端口，并将该隧道用作数据平面。

启动和调试

• 手动：Lobster 菜单 → “打开聊天”。
• 测试时自动打开：

bash
dist/OpenClaw.app/Contents/MacOS/OpenClaw --webchat

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

接线方式

• 数据平面：Gateway 网关 WS 方法 chat.history、chat.send、chat.abort、chat.inject，以及事件 chat、agent、presence、tick、health。
• chat.history 返回按显示规范化的转录行：内联指令标签会从可见文本中剥离，纯文本工具调用 XML 载荷（包括 <tool_call>...</tool_call>、<function_call>...</function_call>、<tool_calls>...</tool_calls>、<function_calls>...</function_calls>，以及被截断的工具调用块）和泄漏的 ASCII/全角模型控制令牌会被剥离，精确匹配 NO_REPLY / no_reply 等纯静默令牌助手行会被省略，过大的行可替换为占位符。
• 会话：默认使用主会话（main，或范围为全局时使用 global）。界面可以在会话之间切换。
• 新手引导使用专用会话，以便将首次运行设置分隔开。

安全面

• 远程模式仅通过 SSH 转发 Gateway 网关 WebSocket 控制端口。

已知限制

• 该界面针对聊天会话优化（不是完整的浏览器沙箱）。

相关内容

• WebChat
• macOS 应用

📄 画布

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/canvas

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 面板（会按需切换会话）。

可以在 Settings → Allow Canvas 中禁用 Canvas。禁用后，canvas
节点命令会返回 CANVAS_DISABLED。

智能体 API 表面

Canvas 通过 Gateway 网关 WebSocket 暴露，因此智能体可以：

• 显示/隐藏面板
• 导航到路径或 URL
• 执行 JavaScript
• 捕获快照图像

CLI 示例：

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 host 托管，并在 Canvas 面板内渲染。
当 Gateway 网关公布 Canvas host 时，macOS 应用首次打开时会自动导航到
A2UI host 页面。

默认 A2UI host URL：

http://<gateway-host>:18789/__openclaw__/a2ui/

A2UI 命令（v0.8）

Canvas 当前接受 A2UI v0.8 服务端→客户端消息：

• beginRendering
• surfaceUpdate
• dataModelUpdate
• deleteSurface

不支持 createSurface（v0.9）。

CLI 示例：

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>

快速冒烟测试：

openclaw nodes canvas a2ui push --node <id> --text "Hello from A2UI"

从 Canvas 触发智能体运行

Canvas 可以通过深层链接触发新的智能体运行：

• openclaw://agent?...

示例（在 JS 中）：

window.location.href = "openclaw://agent?message=Review%20this%20design";

除非提供了有效密钥，否则应用会提示确认。

安全说明

• Canvas scheme 会阻止目录遍历；文件必须位于会话根目录下。
• 本地 Canvas 内容使用自定义 scheme（不需要 loopback 服务器）。
• 外部 http(s) URL 只有在显式导航时才允许访问。

相关

• macOS 应用
• WebChat

📄 macOS 上的 Gateway 网关生命周期

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/child-process

macOS 应用默认通过 launchd 管理 Gateway 网关，不会将 Gateway 网关作为子进程启动。它会先尝试连接到配置端口上已在运行的 Gateway 网关；如果没有可访问的 Gateway 网关，它会通过外部 openclaw CLI 启用 launchd 服务（不嵌入运行时）。这让你获得可靠的登录时自动启动和崩溃后重启。

子进程模式（由应用直接启动 Gateway 网关）目前未使用。如果你需要与 UI 更紧密地耦合，请在终端中手动运行 Gateway 网关。

默认行为（launchd）

• 应用会安装一个按用户划分的 LaunchAgent，标签为 ai.openclaw.gateway
  （使用 --profile/OPENCLAW_PROFILE 时为 ai.openclaw.<profile>；也支持旧版 com.openclaw.*）。
• 启用本地模式时，应用会确保 LaunchAgent 已加载，并在需要时启动 Gateway 网关。
• 日志会写入 launchd gateway 日志路径（可在调试设置中查看）。

常用命令：

launchctl kickstart -k gui/$UID/ai.openclaw.gateway
launchctl bootout gui/$UID/ai.openclaw.gateway

运行命名 profile 时，将标签替换为 ai.openclaw.<profile>。

未签名的开发构建

scripts/restart-mac.sh --no-sign 用于没有签名密钥时的快速本地构建。为防止 launchd 指向未签名的中继二进制文件，它会：

• 写入 ~/.openclaw/disable-launchagent。

如果该标记存在，签名运行 scripts/restart-mac.sh 会清除此覆盖。要手动重置：

rm ~/.openclaw/disable-launchagent

仅连接模式

要强制 macOS 应用永不安装或管理 launchd，请使用 --attach-only（或 --no-launchd）启动它。这会设置 ~/.openclaw/disable-launchagent，因此应用只会连接到已在运行的 Gateway 网关。你也可以在调试设置中切换相同行为。

远程模式

远程模式永远不会启动本地 Gateway 网关。应用会使用 SSH 隧道连接到远程主机，并通过该隧道建立连接。

为什么我们偏好 launchd

• 登录时自动启动。
• 内置重启/KeepAlive 语义。
• 可预测的日志和监督机制。

如果将来再次需要真正的子进程模式，应将其记录为单独、明确的仅开发模式。

相关内容

• macOS 应用
• Gateway 网关运行手册

📄 健康检查（macOS）

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/health

macOS 上的健康检查

如何在菜单栏应用中查看已连接渠道是否健康。

菜单栏

• 状态圆点现在会反映 Baileys 健康状态：
• 绿色：已连接 + 最近已打开套接字。
• 橙色：正在连接 / 重试。
• 红色：已登出或探测失败。
• 次要一行会显示“linked · auth 12m”，或显示失败原因。
• “Run Health Check”菜单项会触发按需探测。

设置

• “General”标签页新增了一个 Health 卡片，显示：已连接认证时长、会话存储路径 / 数量、上次检查时间、上次错误 / 状态码，以及“Run Health Check” / “Reveal Logs”按钮。
• 使用缓存快照，因此 UI 可以即时加载，并在离线时优雅回退。
• Channels 标签页会显示 WhatsApp / Telegram 的渠道状态 + 控件（登录二维码、登出、探测、上次断开连接 / 错误）。

探测的工作方式

• 应用会通过 ShellExecutor 每约 60 秒运行一次 openclaw health --json，也可按需运行。该探测会加载凭证并报告状态，而不发送消息。
• 分别缓存最近一次成功快照和最近一次错误，以避免闪烁；并显示各自的时间戳。

如有疑问

• 你仍可以使用Gateway 网关健康状态中的 CLI 流程（openclaw status、openclaw status --deep、openclaw health --json），并查看 /tmp/openclaw/openclaw-*.log 中的 web-heartbeat / web-reconnect。

相关内容

• Gateway 网关健康状态
• macOS 应用

📄 菜单栏图标

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/icon

菜单栏图标状态

作者：steipete · 更新：2025-12-06 · 范围：macOS 应用（apps/macos）

• 空闲： 正常图标动画（眨眼、偶尔摆动）。
• 已暂停： Status 项使用 appearsDisabled；无动作。
• 语音触发（大耳朵）： 听到唤醒词时，语音唤醒检测器会调用 AppState.triggerVoiceEars(ttl: nil)，在采集话语期间保持 earBoostActive=true。耳朵会放大（1.9x），并出现圆形耳孔以提高可读性，然后在静默 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/broker 开关；保持为应用自身信号的内部行为，以避免意外反复切换。
• 保持 TTL 较短（<10s），这样如果任务挂起，图标也能快速回到基线状态。

相关内容

• 菜单栏
• macOS 应用

📄 macOS 日志记录

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/logging

日志记录（macOS）

滚动诊断文件日志（调试面板）

OpenClaw 通过 swift-log 路由 macOS 应用日志（默认使用统一日志记录），并且在你需要持久捕获时，可以将本地滚动文件日志写入磁盘。

• 详细程度：调试面板 → 日志 → 应用日志记录 → 详细程度
• 启用：调试面板 → 日志 → 应用日志记录 → “写入滚动诊断日志（JSONL）”
• 位置：~/Library/Logs/OpenClaw/diagnostics.jsonl（自动轮转；旧文件会添加 .1、.2、… 后缀）
• 清除：调试面板 → 日志 → 应用日志记录 → “清除”

注意：

• 这项功能默认关闭。仅在主动调试时启用。
• 请将该文件视为敏感内容；未经审阅不要分享。

macOS 上的统一日志记录私有数据

统一日志记录会编辑隐藏大多数载荷，除非某个子系统选择启用 privacy -off。根据 Peter 关于 macOS 日志隐私混乱现象（2025）的文章，这是由 /Library/Preferences/Logging/Subsystems/ 中按子系统名称作为键名的 plist 控制的。只有新的日志条目会应用该标志，因此请在复现问题前启用它。

为 OpenClaw (ai.openclaw) 启用

• 先将 plist 写入临时文件，然后以 root 身份原子安装：

cat <<'EOF' >/tmp/ai.openclaw.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/ai.openclaw.plist /Library/Preferences/Logging/Subsystems/ai.openclaw.plist

• 不需要重启；logd 会很快发现该文件，但只有新的日志行会包含私有载荷。
• 使用现有辅助脚本查看更丰富的输出，例如 ./scripts/clawlog.sh --category WebChat --last 5m。

调试后禁用

• 移除覆盖项：sudo rm /Library/Preferences/Logging/Subsystems/ai.openclaw.plist。
• 也可以运行 sudo log config --reload，强制 logd 立即丢弃覆盖项。
• 请记住，该表面可能包含电话号码和消息正文；仅在你确实需要额外细节时保留该 plist。

相关

• macOS 应用
• Gateway 网关日志记录

📄 macOS 权限

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/permissions

macOS 权限授予很脆弱。TCC 会将权限授予与应用的
代码签名、bundle identifier 以及磁盘路径关联起来。如果其中任何一项发生变化，
macOS 都会将该应用视为新应用，并可能丢弃或隐藏提示框。

稳定权限的要求

• 相同路径：从固定位置运行应用（对于 OpenClaw，即 dist/OpenClaw.app）。
• 相同 bundle identifier：更改 bundle ID 会创建新的权限身份。
• 已签名应用：未签名或 ad-hoc 签名的构建不会持久保留权限。
• 一致的签名：使用真实的 Apple Development 或 Developer ID 证书，
  这样签名在多次重建之间才能保持稳定。

ad-hoc 签名每次构建都会生成一个新的身份。macOS 会忘记之前的
授权，而且在清除过期条目之前，提示框甚至可能完全消失。

当提示框消失时的恢复清单

1. 退出应用。
2. 在系统设置 -> 隐私与安全性中移除该应用条目。
3. 从相同路径重新启动应用，并重新授予权限。
4. 如果提示框仍未出现，使用 tccutil 重置 TCC 条目后再试一次。
5. 某些权限只有在 macOS 完全重启后才会再次出现。

重置示例（根据需要替换 bundle ID）：

sudo tccutil reset Accessibility ai.openclaw.mac
sudo tccutil reset ScreenCapture ai.openclaw.mac
sudo tccutil reset AppleEvents

文件与文件夹权限（Desktop/Documents/Downloads）

macOS 也可能会对终端/后台进程访问 Desktop、Documents 和 Downloads 进行限制。如果文件读取或目录列举卡住，请将访问权限授予执行文件操作的同一进程上下文（例如 Terminal/iTerm、由 LaunchAgent 启动的应用，或 SSH 进程）。

变通方法：如果你想避免按文件夹分别授权，可将文件移动到 OpenClaw 工作区（~/.openclaw/workspace）。

如果你在测试权限，请始终使用真实证书签名。ad-hoc
构建只适用于权限无关的快速本地运行。

相关内容

• macOS 应用
• macOS 签名

📄 远程控制

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/remote

此流程让 macOS 应用可以作为运行在另一台主机（台式机/服务器）上的 OpenClaw Gateway 网关的完整远程控制器。这是应用的 Remote over SSH（远程运行）功能。所有功能（健康检查、Voice Wake 转发和 Web Chat）都会复用 Settings → General 中的同一套远程 SSH 配置。

模式

• Local (this Mac)：所有内容都在笔记本电脑上运行。不涉及 SSH。
• Remote over SSH (default)：OpenClaw 命令在远程主机上执行。Mac 应用会使用 -o BatchMode、你选择的身份/密钥以及本地端口转发打开 SSH 连接。
• Remote direct (ws/wss)：没有 SSH 隧道。Mac 应用会直接连接到 Gateway 网关 URL（例如通过 Tailscale Serve 或公共 HTTPS 反向代理）。

远程传输协议

远程模式支持两种传输协议：

• SSH tunnel（默认）：使用 ssh -N -L ... 将 Gateway 网关端口转发到 localhost。由于隧道是 loopback，Gateway 网关会看到节点 IP 为 127.0.0.1。
• Direct (ws/wss)：直接连接到 Gateway 网关 URL。Gateway 网关会看到真实客户端 IP。

在 SSH 隧道模式下，发现到的 LAN/tailnet 主机名会保存为
gateway.remote.sshTarget。应用会将 gateway.remote.url 保持在本地
隧道端点上，例如 ws://127.0.0.1:18789，因此 CLI、Web Chat 和
本地 node-host 服务都会使用同一个安全的 loopback 传输协议。

远程模式下的浏览器自动化由 CLI node host 负责，而不是由原生 macOS
应用节点负责。应用会在可能时启动已安装的 node host 服务；如果你需要从那台 Mac
进行浏览器控制，请使用 openclaw node install ... 和 openclaw node start
安装/启动它（或在前台运行 openclaw node run ...），然后将目标设为那个具备浏览器能力的
节点。

远程主机上的前提条件

1. 安装 Node + pnpm，并构建/安装 OpenClaw CLI（pnpm install && pnpm build && pnpm link --global）。
2. 确保非交互式 shell 的 PATH 中包含 openclaw（如有需要，可符号链接到 /usr/local/bin 或 /opt/homebrew/bin）。
3. 使用密钥认证打开 SSH。我们建议使用 Tailscale IP，以便在 LAN 外保持稳定可达。

macOS 应用设置

1. 打开 Settings → General。
2. 在 OpenClaw runs 下，选择 Remote over SSH 并设置：
   - Transport：SSH tunnel 或 Direct (ws/wss)。
   - SSH target：user@host（可选 :port）。
   • 如果 Gateway 网关位于同一 LAN 并发布 Bonjour，可从发现列表中选择它以自动填充此字段。
   • Gateway URL（仅 Direct）：wss://gateway.example.ts.net（或本地/LAN 使用 ws://...）。
   • Identity file（高级）：你的密钥路径。
   • Project root（高级）：用于命令的远程检出路径。
   • CLI path（高级）：可运行的 openclaw 入口点/二进制文件的可选路径（发布时会自动填充）。
3. 点击 Test remote。成功表示远程 openclaw status --json 可以正确运行。失败通常意味着 PATH/CLI 问题；退出码 127 表示远程找不到 CLI。
4. 健康检查和 Web Chat 现在会自动通过此 SSH 隧道运行。

Web Chat

• SSH tunnel：Web Chat 通过转发后的 WebSocket 控制端口（默认 18789）连接到 Gateway 网关。
• Direct (ws/wss)：Web Chat 直接连接到已配置的 Gateway 网关 URL。
• 不再有单独的 WebChat HTTP 服务器。

权限

• 远程主机需要与本地相同的 TCC 批准（Automation、Accessibility、Screen Recording、Microphone、Speech Recognition、Notifications）。在该机器上运行新手引导以一次性授予这些权限。
• 节点会通过 node.list / node.describe 发布它们的权限状态，以便智能体知道哪些能力可用。

安全注意事项

• 优先在远程主机上使用 loopback 绑定，并通过 SSH 或 Tailscale 连接。
• SSH 隧道使用严格的主机密钥检查；请先信任主机密钥，使其存在于 ~/.ssh/known_hosts 中。
• 如果将 Gateway 网关绑定到非 loopback 接口，请要求有效的 Gateway 网关认证：令牌、密码，或带有 gateway.auth.mode: "trusted-proxy" 的身份感知反向代理。
• 请参阅 安全 和 Tailscale。

WhatsApp 登录流程（远程）

• 在远程主机上运行 openclaw channels login --verbose。用手机上的 WhatsApp 扫描二维码。
• 如果认证过期，请在该主机上重新运行登录。健康检查会暴露链接问题。

故障排除

• exit 127 / not found：非登录 shell 的 PATH 中没有 openclaw。将它添加到 /etc/paths、你的 shell rc，或符号链接到 /usr/local/bin//opt/homebrew/bin。
• Health probe failed：检查 SSH 可达性、PATH，以及 Baileys 是否已登录（openclaw status --json）。
• Web Chat stuck：确认 Gateway 网关正在远程主机上运行，并且转发端口与 Gateway 网关 WS 端口匹配；UI 需要健康的 WS 连接。
• Node IP shows 127.0.0.1：使用 SSH 隧道时这是预期行为。如果你希望 Gateway 网关看到真实客户端 IP，请将 Transport 切换为 Direct (ws/wss)。
• Dashboard works but Mac capabilities are offline：这意味着应用的操作员/控制连接是健康的，但配套节点连接未连接或缺少其命令表面。打开菜单栏设备部分，检查 Mac 是否为 paired · disconnected。对于 wss://*.ts.net Tailscale Serve 端点，应用会在证书轮换后检测陈旧的旧 TLS 叶证书 pin，当 macOS 信任新证书后清除此陈旧 pin，并自动重试。如果证书不被系统信任，或主机不是 Tailscale Serve 名称，请检查证书或切换到 Remote over SSH。
• Voice Wake：在远程模式下，触发短语会自动转发；不需要单独的转发器。

通知声音

使用 openclaw 和 node.invoke 从脚本中为每条通知选择声音，例如：

openclaw nodes notify --node <id> --title "Ping" --body "Remote gateway ready" --sound Glass

应用中不再有全局“默认声音”开关；调用方会按每个请求选择一个声音（或不选择）。

相关

• macOS 应用
• 远程访问

📄 macOS 签名

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/signing

mac 签名（调试构建）

此应用通常通过 scripts/package-mac-app.sh 构建，该脚本现在会：

• 设置稳定的调试 bundle 标识符：ai.openclaw.mac.debug
• 使用该 bundle id 写入 Info.plist（可通过 BUNDLE_ID=... 覆盖）
• 调用 scripts/codesign-mac-app.sh 对主二进制文件和应用 bundle 进行签名，使 macOS 将每次重建都视为同一个已签名 bundle，并保留 TCC 权限（通知、辅助功能、屏幕录制、麦克风、语音）。要获得稳定权限，请使用真实签名身份；临时（ad-hoc）签名需要显式启用且较脆弱（参见 macOS 权限）。
• 默认使用 CODESIGN_TIMESTAMP=auto；它会为 Developer ID 签名启用可信时间戳。设置 CODESIGN_TIMESTAMP=off 可跳过时间戳（离线调试构建）。
• 将构建元数据注入 Info.plist：OpenClawBuildTimestamp（UTC）和 OpenClawGitCommit（短哈希），以便“关于”面板显示构建、git，以及调试/发布频道。
• 打包默认使用 Node 24：该脚本会运行 TS 构建和 Control UI 构建。Node 22 LTS（目前为 22.16+）仍受支持以保持兼容性。
• 从环境中读取 SIGN_IDENTITY。将 export SIGN_IDENTITY="Apple Development: Your Name (TEAMID)"（或你的 Developer ID Application 证书）添加到你的 shell rc 中，即可始终使用你的证书签名。临时（ad-hoc）签名需要通过 ALLOW_ADHOC_SIGNING=1 或 SIGN_IDENTITY="-" 显式启用（不建议用于权限测试）。
• 签名后运行 Team ID 审计；如果应用 bundle 内任何 Mach-O 由不同 Team ID 签名，则失败。设置 SKIP_TEAM_ID_CHECK=1 可绕过。

用法

# from repo root
scripts/package-mac-app.sh               # auto-selects identity; errors if none found
SIGN_IDENTITY="Developer ID Application: Your Name" scripts/package-mac-app.sh   # real cert
ALLOW_ADHOC_SIGNING=1 scripts/package-mac-app.sh    # ad-hoc (permissions will not stick)
SIGN_IDENTITY="-" scripts/package-mac-app.sh        # explicit ad-hoc (same caveat)
DISABLE_LIBRARY_VALIDATION=1 scripts/package-mac-app.sh   # dev-only Sparkle Team ID mismatch workaround

临时（Ad-hoc）签名说明

使用 SIGN_IDENTITY="-"（临时签名）签名时，脚本会自动禁用 Hardened Runtime（--options runtime）。这对于防止应用尝试加载未共享同一 Team ID 的嵌入式框架（如 Sparkle）时崩溃是必要的。临时签名还会破坏 TCC 权限持久性；恢复步骤请参见 macOS 权限。

“关于”中的构建元数据

package-mac-app.sh 会在 bundle 中写入：

• OpenClawBuildTimestamp：打包时的 ISO8601 UTC 时间
• OpenClawGitCommit：短 git 哈希（如果不可用则为 unknown）

“关于”标签页会读取这些键，以显示版本、构建日期、git 提交，以及它是否为调试构建（通过 #if DEBUG）。代码变更后运行打包器以刷新这些值。

原因

TCC 权限绑定到 bundle 标识符 和 代码签名。带有变化 UUID 的未签名调试构建会导致 macOS 在每次重建后忘记授权。对二进制文件签名（默认使用临时签名）并保持固定的 bundle id/路径（dist/OpenClaw.app）可在构建之间保留授权，这与 VibeTunnel 的做法一致。

相关内容

• macOS 应用
• macOS 权限

📄 macOS 上的 Gateway 网关

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/bundled-gateway

OpenClaw.app 不再内置 Node/Bun 或 Gateway 网关运行时。macOS 应用需要外部 openclaw CLI 安装，不会将 Gateway 网关作为子进程启动，并会管理每用户的 launchd 服务来保持 Gateway 网关运行（如果已有本地 Gateway 网关正在运行，则附加到现有 Gateway 网关）。

安装 CLI（本地模式必需）

Node 24 是 Mac 上的默认运行时。Node 22 LTS（当前为 22.16+）仍可用于兼容。然后全局安装 openclaw：

npm install -g openclaw@<version>

macOS 应用中的安装 CLI按钮会运行与应用内部使用相同的全局安装流程：它优先使用 npm，其次是 pnpm，如果 bun 是唯一检测到的包管理器，则使用 bun。Node 仍是推荐的 Gateway 网关运行时。

Launchd（作为 LaunchAgent 的 Gateway 网关）

标签：

• ai.openclaw.gateway（或 ai.openclaw.<profile>；旧版 com.openclaw.* 可能仍会保留）

Plist 位置（每用户）：

• ~/Library/LaunchAgents/ai.openclaw.gateway.plist
  （或 ~/Library/LaunchAgents/ai.openclaw.<profile>.plist）

管理器：

• macOS 应用在本地模式下负责 LaunchAgent 的安装/更新。
• CLI 也可以安装它：openclaw gateway install。

行为：

• “OpenClaw 已启用”会启用/停用 LaunchAgent。
• 退出应用不会停止 Gateway 网关（launchd 会保持其存活）。
• 如果 Gateway 网关已在配置的端口上运行，应用会附加到它，而不是启动新的 Gateway 网关。

日志：

• launchd stdout/err：/tmp/openclaw/openclaw-gateway.log

版本兼容性

macOS 应用会检查 Gateway 网关版本是否与自身版本匹配。如果二者不兼容，请更新全局 CLI，使其与应用版本一致。

冒烟检查

openclaw --version

OPENCLAW_SKIP_CHANNELS=1 \
OPENCLAW_SKIP_CANVAS_HOST=1 \
openclaw gateway --port 18999 --bind loopback

然后：

openclaw gateway call health --url ws://127.0.0.1:18999 --timeout 3000

相关内容

• macOS 应用
• Gateway 网关运行手册

📄 macOS IPC

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/xpc

OpenClaw macOS IPC 架构

当前模型：本地 Unix socket 将节点主机服务连接到 macOS 应用，用于 exec 审批和 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

• 无头节点主机服务连接到 Gateway 网关 WebSocket。
• system.run 请求会通过本地 Unix socket 转发到 macOS 应用。
• 应用在 UI 上下文中执行 exec，在需要时提示，然后返回输出。

图示（SCI）：

Agent -> Gateway -> Node Service (WS)
                      |  IPC (UDS + token + HMAC + TTL)
                      v
                  Mac App (UI + TCC + system.run)

PeekabooBridge（UI 自动化）

• UI 自动化使用名为 bridge.sock 的独立 UNIX socket 和 PeekabooBridge JSON 协议。
• 主机偏好顺序（客户端侧）：Peekaboo.app → Claude.app → OpenClaw.app → 本地执行。
• 安全性：bridge 主机要求匹配允许的 TeamID；仅 DEBUG 模式可用的同 UID 逃生舱由 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 保护（Peekaboo 约定）。
• 详情请参阅：PeekabooBridge usage。

操作流程

• 重启/重建：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 调用方用于本地开发。
• 所有通信都保持为仅本地；不会暴露网络 socket。
• TCC 提示仅来源于 GUI 应用 bundle；请在重建过程中保持已签名 bundle ID 稳定。
• IPC 加固：socket 模式 0600、token、peer-UID 检查、HMAC 质询/响应、短 TTL。

相关内容

• macOS app
• macOS IPC flow（Exec approvals）

📄 Skills（macOS）

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/skills

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 主机上运行安装器。
• 内置危险代码 critical 发现默认会阻止 skills.install；可疑发现仍然只会发出警告。危险覆盖确实存在于 gateway 请求上，但默认应用流程保持失败关闭。
• 如果每个安装选项都是 download，gateway 会公开所有下载
  选项。
• 否则，gateway 会根据当前安装偏好和主机二进制文件选择一个首选
  安装器：当启用 skills.install.preferBrew 且存在 brew 时优先使用 Homebrew，然后是 uv，接着是
  skills.install.nodeManager 中配置的 node 管理器，最后才是
  go 或 download 等后备选项。
• Node 安装标签会反映已配置的 node 管理器，包括 yarn。

环境变量 / API 密钥

• 应用将密钥存储在 ~/.openclaw/openclaw.json 的 skills.entries.<skillKey> 下。
• skills.update 会对 enabled、apiKey 和 env 进行 patch 更新。

远程模式

• 安装和配置更新都发生在 gateway 主机上（而不是本地 Mac 上）。

相关内容

• Skills
• macOS app

📄 躲猫猫桥接

原文：https://docs.openclaw.ai/zh-CN/platforms/mac/peekaboo

OpenClaw 可以将 PeekabooBridge 托管为一个本地、具备权限感知能力的 UI 自动化代理。这样 peekaboo CLI 就可以驱动 UI 自动化，同时复用 macOS 应用的 TCC 权限。

这是什么（以及不是什么）

• 主机：OpenClaw.app 可以作为 PeekabooBridge 主机。
• 客户端：使用 peekaboo CLI（没有单独的 openclaw ui ... 界面）。
• UI：可视化叠加层保留在 Peekaboo.app 中；OpenClaw 是一个轻量代理主机。

与 Computer Use 的关系

OpenClaw 有三条桌面控制路径，它们有意保持相互独立：

• PeekabooBridge 主机：OpenClaw.app 可以托管本地 PeekabooBridge 套接字。peekaboo CLI 仍然是客户端，并使用 OpenClaw.app 的 macOS 权限来执行 Peekaboo 自动化原语，例如截图、点击、菜单、对话框、Dock 操作和窗口管理。
• Codex Computer Use：内置的 codex 插件会准备 Codex 应用服务器，验证 Codex 的 computer-use MCP 服务器可用，然后让 Codex 在 Codex 模式轮次中拥有原生桌面控制工具调用。OpenClaw 不会通过 PeekabooBridge 代理这些操作。
• 直接 cua-driver MCP：OpenClaw 可以将 TryCua 的上游 cua-driver mcp 服务器注册为普通 MCP 服务器。这样智能体就能使用 CUA 驱动自己的架构以及 pid/窗口/元素索引工作流，而无需经由 Codex marketplace 或 PeekabooBridge 套接字路由。

当你需要广泛的 macOS 自动化能力以及 OpenClaw.app 具备权限感知能力的桥接主机时，请使用 Peekaboo。当 Codex 模式智能体应依赖 Codex 的原生 computer-use 插件时，请使用 Codex Computer Use。当你想将 CUA 驱动作为普通 MCP 服务器暴露给任何由 OpenClaw 管理的运行时时，请使用直接 cua-driver mcp。

启用桥接

在 macOS 应用中：

• Settings → 启用 Peekaboo Bridge

启用后，OpenClaw 会启动一个本地 UNIX 套接字服务器。如果禁用，主机会停止，peekaboo 将回退到其他可用主机。

客户端发现顺序

Peekaboo 客户端通常按以下顺序尝试主机：

1. Peekaboo.app（完整 UX）
2. Claude.app（如果已安装）
3. OpenClaw.app（轻量代理）

使用 peekaboo bridge status --verbose 查看哪个主机处于活动状态，以及正在使用哪个套接字路径。你可以用以下方式覆盖：

export PEEKABOO_BRIDGE_SOCKET=/path/to/bridge.sock

安全和权限

• 桥接会验证调用方代码签名；会强制执行 TeamID 允许列表（Peekaboo 主机 TeamID + OpenClaw 应用 TeamID）。
• 请求会在约 10 秒后超时。
• 如果缺少所需权限，桥接会返回清晰的错误消息，而不是启动系统设置。

快照行为（自动化）

快照存储在内存中，并会在一个很短的窗口期后自动过期。如果你需要更长时间的保留，请从客户端重新捕获。

故障排除

• 如果 peekaboo 报告 “bridge client is not authorized”，请确保客户端已正确签名，或仅在debug模式下使用 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1 运行主机。
• 如果找不到任何主机，请打开其中一个主机应用（Peekaboo.app 或 OpenClaw.app），并确认已授予权限。

相关内容

• macOS 应用
• macOS 权限