Peekaboo 是做什么的？
使用 Peekaboo 检查 macOS UI，对预期目标执行操作，并验证结果。
以下示例使用 v4 语法。请检查 peekaboo --version 和已安装命令的 --help；对于旧版本，请遵循该版本的帮助。
OpenClaw Bridge
当启用计算机控制且其提供者为 Peekaboo 且 Peekaboo Bridge 已启用时，OpenClaw macOS 应用会托管 Peekaboo Bridge。通过该主机运行时，请保留现有的 OpenClaw 套接字选择：
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json
确认所选主机和套接字是预期的。保留显式的 PEEKABOO_BRIDGE_SOCKET 或 --bridge-socket 选择。如果所需主机不可用，请报告该结果；不要清除选择或切换计算机控制提供者以使命令成功。
权限属于执行操作的进程或 Bridge 主机。
除非调用方具有所需权限，否则不要传递 --no-remote。
查找已安装的命令
使用叶子命令的帮助来获取标志和定位要求，而不是在命令之间复制标志。使用根命令帮助来发现可用命令：
peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help
V4 移除了这些旧命令根：
| 旧命令 | V4 命令 |
|---|---|
list apps | app list |
image | see --no-elements 用于无元素检测的像素 |
hotkey | press 使用和弦，例如 cmd+shift+t |
swipe | drag --from … --to … |
对于其他操作，包括点击、输入、滚动以及管理窗口或菜单，请使用 peekaboo <command> --help。将命令选项放在叶子命令之后；--json 请求结构化输出。
检查、执行、验证
从应用程序清单和目标的新鲜视图开始：
peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
--path /tmp/peekaboo-example.png --json
在执行操作之前读取返回的元素。将操作绑定到预期的应用程序、窗口和新鲜快照上；不要重复使用示例元素 ID。执行操作后，再次检查 UI 并验证请求的结果。当窗口发生变化或目标过时时，刷新观察。
对于无元素检测的屏幕截图：
peekaboo see --mode screen --screen-index 0 --no-elements --retina \
--path /tmp/peekaboo-screen.png --json
原始键盘和弦需要显式的前景交互或被 press 接受的精确窗口凭证。拖拽总是移动共享光标并且需要 --foreground。当前景交互被授权时：
peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json
使用来自当前观察的实际目标和坐标。首选显式持续时间单位，例如 800ms；查阅每个命令的帮助以了解其选项和先决条件。
故障排除
- 对于已移除命令的错误，请使用已安装 CLI 指定的替代命令。
- 对于主机或权限失败，请检查所选主机的
peekaboo bridge status --json和peekaboo permissions status --json。 - 对于定位失败，请阅读叶子命令的帮助并使用
see获取新的 UI 状态。 - 在 macOS 15+ 上，私有窗口选择器提示与基本的屏幕录制授权是分开的，即使 Bridge 权限正确，也可能会出现。