14.18 Peekaboo Bridge

macOS伴侣应用macOS伴侣应用

Peekaboo Bridge 是由 OpenClaw.app 托管的 macOS UI 自动化代理,使 peekaboo CLI 能够复用应用的 TCC 权限。

概述

OpenClaw.app 可以充当 PeekabooBridge 主机,为命令行工具提供 UI 自动化权限的桥接服务。这使得 peekaboo CLI 无需单独申请权限,即可复用 OpenClaw 应用已获得的 TCC(透明同意与控制)权限。

核心特性

安全机制

  • 代码签名验证: 验证客户端的代码签名
  • 超时保护: 10 秒操作超时
  • 内存快照: 使用内存中的快照,不写入磁盘
  • TeamID 白名单: 强制执行 TeamID 允许列表

权限复用

Peekaboo CLI 通过桥接访问以下权限:

  • 屏幕录制
  • 辅助功能
  • UI 元素访问

启用 Peekaboo Bridge

在 OpenClaw 中启用

  1. 打开 OpenClaw 应用
  2. 进入设置(Settings)
  3. 找到并启用 "Enable Peekaboo Bridge" 选项

主机发现顺序

Peekaboo CLI 按以下顺序查找可用的桥接主机:

  1. Peekaboo.app
  2. Claude.app
  3. OpenClaw.app

使用方法

检查桥接状态

# 查看桥接状态
peekaboo bridge status

# 查看详细信息
peekaboo bridge status --verbose

基本操作

# 捕获屏幕快照
peekaboo capture

# 获取 UI 元素树
peekaboo tree

# 点击指定元素
peekaboo click --element "Button Name"

错误处理

权限错误

如果遇到权限问题,不会弹出系统设置提示,而是显示清晰的错误信息:

  • 检查 OpenClaw.app 是否已授予必要权限
  • 确认已在设置中启用 Peekaboo Bridge
  • 验证客户端的代码签名

"bridge client is not authorized"

此错误表示客户端未被授权。解决方法:

  • 验证客户端代码签名: codesign -dv /path/to/peekaboo
  • 确认 TeamID 在白名单中
  • 调试模式: 设置环境变量(仅限调试): 
    export PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1
安全警告
仅在调试环境中使用 PEEKABOO_ALLOW_UNSIGNED_SOCKET_CLIENTS=1。在生产环境中启用此选项会降低安全性。

常见问题排查

找不到桥接主机

  • 确认 OpenClaw.app 正在运行
  • 检查设置中是否启用了 Peekaboo Bridge
  • 使用 --verbose 查看详细的连接信息

连接超时

  • 操作超时时间为 10 秒
  • 检查网络连接和进程间通信
  • 查看系统日志获取详细错误

权限被拒绝

  • 打开系统设置 → 隐私与安全性
  • 确认 OpenClaw.app 已获得:
    • 辅助功能权限
    • 屏幕录制权限
  • 重启 OpenClaw.app 使权限生效

开发指南

集成到自定义应用

如果要在自己的应用中集成 Peekaboo Bridge:

  • 实现 PeekabooBridge 协议
  • 配置代码签名和 TeamID
  • 实现超时和安全检查
  • 参考 OpenClaw 的实现示例

安全最佳实践

  • 始终验证客户端代码签名
  • 使用 TeamID 白名单限制访问
  • 实施操作超时保护
  • 使用内存快照,避免敏感数据落盘
  • 记录所有桥接操作用于审计
相关资源