¿Qué hace peekaboo?
Usa Peekaboo para inspeccionar la UI de macOS, actuar sobre el objetivo deseado y verificar el resultado.
Los ejemplos a continuación usan la sintaxis v4. Consulta peekaboo --version y el
--help del comando instalado; para versiones anteriores, sigue la ayuda de esa versión.
Puente OpenClaw
La aplicación macOS OpenClaw aloja Peekaboo Bridge cuando el Control del Equipo está habilitado, su proveedor es Peekaboo y Peekaboo Bridge está habilitado. Mantén la selección actual del socket de OpenClaw cuando ejecutes a través de ese host:
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json
Confirma que el host y el socket seleccionados sean los correctos. Conserva un
PEEKABOO_BRIDGE_SOCKET o --bridge-socket explícito. Si el host requerido
no está disponible, informa ese resultado; no limpies la selección ni cambies
el proveedor de Control del Equipo para que un comando tenga éxito.
Los permisos pertenecen al proceso o al host Bridge que realiza la operación.
No pases --no-remote a menos que el llamante tenga los permisos necesarios.
Encontrar el comando instalado
Usa la ayuda de cada comando hoja para conocer sus banderas y requisitos de destino en lugar de copiar una bandera entre comandos. Usa la ayuda raíz para descubrir los comandos disponibles:
peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help
V4 eliminó estas raíces de comandos antiguas:
| Comando antiguo | Comando V4 |
|---|---|
list apps | app list |
image | see --no-elements para píxeles sin detección de elementos |
hotkey | press con acordes como cmd+shift+t |
swipe | drag --from … --to … |
Para otras operaciones, incluyendo clics, escritura, desplazamiento y gestión de ventanas
o menús, usa peekaboo <comando> --help. Coloca las opciones del comando después del
comando hoja; --json solicita salida estructurada.
Inspeccionar, actuar, verificar
Comienza con el inventario de aplicaciones y una vista fresca del destino:
peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
--path /tmp/peekaboo-example.png --json
Lee los elementos devueltos antes de actuar. Mantén las acciones vinculadas a la aplicación, ventana y captura reciente; no reutilices identificadores de elementos de ejemplo. Después de una acción, inspecciona la UI nuevamente y verifica el resultado solicitado. Actualiza la observación cuando la ventana cambie o un destino quede obsoleto.
Para una captura de pantalla sin detección de elementos:
peekaboo see --mode screen --screen-index 0 --no-elements --retina \
--path /tmp/peekaboo-screen.png --json
Los acordes de teclado sin procesar requieren interacción explícita en primer plano o un
recibo de ventana exacta recién aceptado por press. Arrastrar siempre mueve el cursor
compartido y requiere --foreground. Cuando la interacción en primer plano está autorizada:
peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json
Usa el destino real y las coordenadas de la observación actual. Prefiere
unidades de duración explícitas como 800ms; consulta la ayuda de cada comando para conocer
sus opciones y requisitos previos.
Solución de problemas
- Para un error de comando eliminado, usa el reemplazo nombrado por la CLI instalada.
- Para fallos de host o permisos, inspecciona
peekaboo bridge status --jsonypeekaboo permissions status --jsonpara el host seleccionado. - Para fallos de destino, lee la ayuda del comando hoja y obtén un estado actualizado de la UI con
see. - En macOS 15+, el diálogo privado del selector de ventanas es independiente de la concesión básica de Grabación de Pantalla y puede aparecer incluso cuando los permisos de Bridge son correctos.