Peekaboo CLI

macOS UI 自动化命令行工具，提供完整的桌面控制能力。

安装

将此技能复制到你的代理技能目录：

bash

Claude Code

mkdir -p ~/.claude/skills/peekaboo-cli
cp -r . ~/.claude/skills/peekaboo-cli/

OpenClaw

mkdir -p ~/.openclaw/skills/peekaboo-cli cp -r . ~/.openclaw/skills/peekaboo-cli/

前置条件

• - 已安装 Peekaboo CLI (brew install steipete/tap/peekaboo)
• 已授予 macOS 屏幕录制和辅助功能权限

执行前验证

在执行任何 CLI 命令之前，请先验证权限状态。

1. 检查权限状态

bash
peekaboo permissions status

2. 授予权限（如需要）

如果权限未授予，请引导用户启用：

Peekaboo 需要以下 macOS 权限：

• - 屏幕录制：用于捕获 UI 截图
• 辅助功能：用于控制 UI 元素

系统设置 → 隐私与安全性 → 屏幕录制/辅助功能 → 添加终端应用

然后验证：

bash
peekaboo permissions grant

3. 验证配置

bash
peekaboo list apps

快速开始

bash

列出正在运行的应用程序

peekaboo list apps

捕获当前窗口 UI 并标注元素

peekaboo see --annotate --path /tmp/ui.png

点击特定元素（ID 来自 see 命令）

peekaboo click --on elem_42

输入文本

peekaboo type Hello World --return

核心命令

UI 捕获与分析

bash

捕获 UI 元素映射（建议在点击/输入前使用）

peekaboo see --json --annotate --path /tmp/ui.png

定位特定应用/窗口

peekaboo see --app Safari --window-title GitHub

捕获菜单栏弹出项

peekaboo see --menubar

捕获整个屏幕

peekaboo see --mode screen

元素交互

bash

按 ID 点击元素

peekaboo click --on elem_42
peekaboo click Submit --wait-for 8000

基于坐标点击

peekaboo click --coords 100,200

双击 / 右键点击

peekaboo click --on elem_42 --double peekaboo click --coords 100,200 --right

输入文本

peekaboo type user@example.com --return peekaboo type --clear new text # 先清空字段

按键和快捷键

peekaboo press return peekaboo hotkey cmd,w # Cmd+W

应用管理

bash

启动应用

peekaboo app launch Safari
peekaboo app launch Xcode --open ~/Projects/MyApp.xcodeproj

退出应用

peekaboo app quit --app Safari peekaboo app quit --all --except Finder,Terminal

切换焦点

peekaboo app switch --to Safari --verify

窗口管理

bash

列出窗口

peekaboo list windows --app Safari --include-details bounds,ids

移动/调整窗口大小

peekaboo window move --app Safari -x 100 -y 100 peekaboo window resize --app Safari -w 1200 --height 800

聚焦/关闭/最小化/最大化

peekaboo window focus --app Terminal --space-switch peekaboo window close --app Safari

菜单操作

bash

点击菜单项

peekaboo menu click --app Safari --path File,New Tab

列出菜单栏状态项

peekaboo list menubar

滚动与拖拽

bash

滚动

peekaboo scroll --direction down --amount 3

拖拽

peekaboo drag --from 100,100 --to 300,300

移动鼠标

peekaboo move --coords 500,500

常见工作流程

表单填写

bash

1. 捕获 UI 以获取元素 ID

peekaboo see --json --annotate --path /tmp/form.png

2. 点击输入字段并输入

peekaboo click --on elem_10 peekaboo type username --tab peekaboo type password --return

应用自动化

bash

1. 启动应用

peekaboo app launch Safari --wait-until-ready

2. 等待并执行操作

peekaboo sleep 2 peekaboo hotkey cmd,l # 聚焦地址栏 peekaboo type https://github.com --return

输出格式

大多数命令支持 --json 输出：

bash
peekaboo see --json | jq .data.ui_elements[] | {id, label, role}
peekaboo list apps --json | jq .data[] | select(.frontmost == true)

故障排除

权限错误

bash
peekaboo permissions status
peekaboo permissions grant

元素未找到

1. 1. 重新捕获 UI：peekaboo see --json
2. 使用 --wait-for 增加等待时间
3. 使用 --coords 进行基于坐标的定位

焦点问题

1. 1. 跨空间窗口使用 --space-switch
2. 使用 peekaboo app switch --to --verify 确认焦点
3. 手动聚焦后使用 --no-auto-focus

详细文档

• * UI 捕获 references/see.md
• 元素点击 references/click.md
• 文本输入 references/type.md
• 按键 references/press.md
• 快捷键 references/hotkey.md
• 应用管理 references/app.md
• 窗口管理 references/window.md
• 菜单操作 references/menu.md
• 菜单栏 references/menubar.md
• 滚动 references/scroll.md
• 拖拽 references/drag.md
• 鼠标移动 references/move.md
• 滑动手势 references/swipe.md
• 长时间捕获 references/capture.md
• 图像处理 references/image.md
• 自主代理 references/agent.md
• MCP 服务器 references/mcp.md
• 配置管理 references/config.md
• 权限 references/permissions.md
• 剪贴板 references/clipboard.md
• 列表查询 references/list.md
• 打开文件 references/open.md
• 休眠 references/sleep.md
• 空间管理 references/space.md
• 对话框 references/dialog.md
• 程序坞 references/dock.md
• 清理缓存 references/clean.md
• 桥接服务 references/bridge.md
• 守护进程 references/daemon.md
• 工具 references/tools.md
• 学习 references/learn.md
• 运行 references/run.md
• MCP 捕获元数据 references/mcp-capture-meta.md
• 可视化工具 references/visualizer.md