AI Skills
peekaboo

peekaboo

热门

使用 Peekaboo CLI 捕获并自动化 macOS 界面。

38万Star
8.1万Fork
更新于 2026/7/22
获取 Skill源代码

相关 Skills

seo-sxo1.2万ui-to-vue24万frontend-skill8.4万
SKILL.md
readonly只读
name
peekaboo
description

使用 Peekaboo CLI 捕获并自动化 macOS 界面。

Peekaboo

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

OpenClaw 桥接

OpenClaw macOS 应用在 ~/Library/Application Support/OpenClaw/bridge.sock 托管 Peekaboo Bridge。从 OpenClaw 运行 Peekaboo 之前，选择该套接字，以便 CLI 使用应用的屏幕录制和辅助功能授权，而不是启动独立的守护进程：

export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"

通过 peekaboo bridge status --json 确认路由；hostKind 必须为 gui，且套接字路径必须以 OpenClaw/bridge.sock 结尾。

功能（所有 CLI 能力，不包括 agent/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：列出/切换/移动窗口（Spaces）
  • 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\nLine 2" --delay 10

注意事项

  • 需要屏幕录制和辅助功能权限。
  • 在 OpenClaw 子进程中，按上述方式设置 PEEKABOO_BRIDGE_SOCKET。除非调用进程自身拥有屏幕录制授权，否则不要传递 --no-remote。
  • 诊断子进程捕获失败：先运行 peekaboo bridge status --json，然后 peekaboo permissions status --json，最后执行一个正常的桥接路由捕获，例如 peekaboo image --mode screen --json。
  • 在 macOS 15+ 上，“绕过隐私窗口选择器”提示与基础屏幕录制授权是分开的；即使桥接权限其他方面正确，也可能出现该提示。
  • 在点击之前，使用 peekaboo see --annotate 识别目标。