name: peekaboo description: 通过Peekaboo CLI捕获和自动化macOS用户界面。 homepage: https://peekaboo.boo metadata: { “openclaw”: { “emoji”: “👀”, “os”: [“darwin”], “requires”: { “bins”: [“peekaboo”] }, “install”: [ { “id”: “brew”, “kind”: “brew”, “formula”: “steipete/tap/peekaboo”, “bins”: [“peekaboo”], “label”: “安装Peekaboo (brew)”, }, ], }, }

Peekaboo

Peekaboo是一个完整的macOS用户界面自动化命令行工具：捕获/检查屏幕、定位UI元素、驱动输入以及管理应用程序/窗口/菜单。命令共享快照缓存并支持--json/-j用于脚本编写。运行peekaboo或peekaboo <cmd> --help查看标志；peekaboo --version打印构建元数据。提示：通过polter peekaboo运行以确保使用最新构建。

功能（所有CLI能力，不包括代理/MCP）

核心

bridge: 检查Peekaboo Bridge主机连接性
capture: 实时捕获或视频摄取 + 帧提取
clean: 清理快照缓存和临时文件
config: 初始化/显示/编辑/验证、提供程序、模型、凭证
image: 捕获屏幕截图（屏幕/窗口/菜单栏区域）
learn: 打印完整的代理指南 + 工具目录
list: 应用程序、窗口、屏幕、菜单栏、权限
permissions: 检查屏幕录制/辅助功能权限状态
run: 执行.peekaboo.json脚本
sleep: 暂停执行一段时间
tools: 列出可用工具，支持过滤/显示选项

交互

click: 通过ID/查询/坐标定位目标，支持智能等待
drag: 在元素/坐标/Dock之间拖放
hotkey: 修饰键组合，如cmd,shift,t
move: 光标定位，可选平滑移动
paste: 设置剪贴板 -> 粘贴 -> 恢复
press: 特殊键序列，支持重复
scroll: 方向性滚动（目标化 + 平滑）
swipe: 手势式在目标之间拖动
type: 文本 + 控制键（--clear、延迟）

系统

app: 启动/退出/重新启动/隐藏/取消隐藏/切换/列出应用程序
clipboard: 读取/写入剪贴板（文本/图像/文件）
dialog: 点击/输入/文件/关闭/列出系统对话框
dock: 启动/右键点击/隐藏/显示/列出Dock项目
menu: 点击/列出应用程序菜单 + 菜单栏额外项
menubar: 列出/点击状态栏项目
open: 增强版open，支持应用定位 + JSON负载
space: 列出/切换/移动窗口（空间）
visualizer: 运行Peekaboo视觉反馈动画
window: 关闭/最小化/最大化/移动/调整大小/聚焦/列出

视觉

see: 带注释的UI地图、快照ID、可选分析

全局运行时标志

--json/-j、--verbose/-v、--log-level <level>
--no-remote、--bridge-socket <path>

快速入门（最佳实践）

peekaboo permissions
peekaboo list apps --json
peekaboo see --annotate --path /tmp/peekaboo-see.png
peekaboo click --on B1
peekaboo type "Hello" --return

常见定位参数（大多数交互命令）

应用程序/窗口：--app、--pid、--window-title、--window-id、--window-index
快照定位：--snapshot（来自see的ID；默认为最新）
元素/坐标：--on/--id（元素ID）、--coords x,y
焦点控制：--no-auto-focus、--space-switch、--bring-to-current-space、--focus-timeout-seconds、--focus-retry-count

常见捕获参数

输出：--path、--format png|jpg、--retina
定位：--mode screen|window|frontmost、--screen-index、--window-title、--window-id
分析：--analyze "prompt"、--annotate
捕获引擎：--capture-engine auto|classic|cg|modern|sckit

常见运动/输入参数

时序：--duration（拖动/滑动）、--steps、--delay（输入/滚动/按键）
类人运动：--profile human|linear、--wpm（输入）
滚动：--direction up|down|left|right、--amount <ticks>、--smooth

示例

查看 -> 点击 -> 输入（最可靠的流程）

peekaboo see --app Safari --window-title "Login" --annotate --path /tmp/see.png
peekaboo click --on B3 --app Safari
peekaboo type "user@example.com" --app Safari
peekaboo press tab --count 1 --app Safari
peekaboo type "supersecret" --app Safari --return

通过窗口ID定位

peekaboo list windows --app "Visual Studio Code" --json
peekaboo click --window-id 12345 --coords 120,160
peekaboo type "Hello from Peekaboo" --window-id 12345

捕获屏幕截图 + 分析

peekaboo image --mode screen --screen-index 0 --retina --path /tmp/screen.png
peekaboo image --app Safari --window-title "Dashboard" --analyze "Summarize KPIs"
peekaboo see --mode screen --screen-index 0 --analyze "Summarize the dashboard"

实时捕获（运动感知）

peekaboo capture live --mode region --region 100,100,800,600 --duration 30 \
  --active-fps 8 --idle-fps 2 --highlight-changes --path /tmp/capture

应用程序 + 窗口管理

peekaboo app launch "Safari" --open https://example.com
peekaboo window focus --app Safari --window-title "Example"
peekaboo window set-bounds --app Safari --x 50 --y 50 --width 1200 --height 800
peekaboo app quit --app Safari

菜单、菜单栏、Dock

peekaboo menu click --app Safari --item "New Window"
peekaboo menu click --app TextEdit --path "Format > Font > Show Fonts"
peekaboo menu click-extra --title "WiFi"
peekaboo dock launch Safari
peekaboo menubar list --json

鼠标 + 手势输入

peekaboo move 500,300 --smooth
peekaboo drag --from B1 --to T2
peekaboo swipe --from-coords 100,500 --to-coords 100,200 --duration 800
peekaboo scroll --direction down --amount 6 --smooth

键盘输入

peekaboo hotkey --keys "cmd,shift,t"
peekaboo press escape
peekaboo type "Line 1
Line 2" --delay 10

注意事项

需要屏幕录制 + 辅助功能权限。
使用peekaboo see --annotate在点击前识别目标。