O que peekaboo faz?
Use o Peekaboo para inspecionar a UI do macOS, agir sobre o alvo desejado e verificar o resultado.
Os exemplos abaixo usam a sintaxe v4. Verifique peekaboo --version e o --help do comando instalado; para versões mais antigas, siga a ajuda da respectiva versão.
Ponte OpenClaw
O aplicativo macOS OpenClaw hospeda a Ponte Peekaboo quando o Controle do Computador está ativado, seu provedor é Peekaboo e a Ponte Peekaboo está ativada. Mantenha a seleção existente do socket OpenClaw ao executar através desse host:
export PEEKABOO_BRIDGE_SOCKET="${PEEKABOO_BRIDGE_SOCKET:-$HOME/Library/Application Support/OpenClaw/bridge.sock}"
peekaboo bridge status --json
Confirme que o host e o socket selecionados são os desejados. Preserve uma
seleção explícita de PEEKABOO_BRIDGE_SOCKET ou --bridge-socket. Se o host
necessário não estiver disponível, relate esse resultado; não remova a seleção nem alterne
provedores de Controle do Computador para fazer um comando ser bem-sucedido.
As permissões pertencem ao processo ou ao host da Ponte que realiza a operação.
Não use --no-remote a menos que o chamador tenha as permissões necessárias.
Encontre o comando instalado
Use a ajuda do comando folha para flags e requisitos de segmentação, em vez de copiar uma flag entre comandos. Use a ajuda raiz para descobrir os comandos disponíveis:
peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help
V4 removeu estas raízes de comandos antigas:
| Comando antigo | Comando v4 |
|---|---|
list apps | app list |
image | see --no-elements para pixels sem detecção de elementos |
hotkey | press com acordes como cmd+shift+t |
swipe | drag --from … --to … |
Para outras operações, incluindo clicar, digitar, rolar e gerenciar janelas
ou menus, use peekaboo <comando> --help. Coloque as opções do comando após o
comando folha; --json solicita saída estruturada.
Inspecionar, agir, verificar
Comece com um inventário de aplicativos e uma visão atualizada do alvo:
peekaboo app list --json
peekaboo see --app Safari --window-title "Exemplo" --annotate \
--path /tmp/peekaboo-exemplo.png --json
Leia os elementos retornados antes de agir. Mantenha as ações vinculadas ao aplicativo, janela e captura recente; não reutilize IDs de elemento de exemplo. Após uma ação, inspecione a UI novamente e verifique o resultado solicitado. Atualize a observação quando a janela mudar ou um alvo se tornar obsoleto.
Para uma captura de tela sem detecção de elementos:
peekaboo see --mode screen --screen-index 0 --no-elements --retina \
--path /tmp/peekaboo-tela.png --json
Acordes de teclado brutos exigem interação explícita em primeiro plano ou um
recebimento exato de janela aceito por press. Arrastar sempre move o cursor
compartilhado e requer --foreground. Quando a interação em primeiro plano está autorizada:
peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json
Use o alvo real e as coordenadas da observação atual. Prefira
unidades de duração explícitas como 800ms; consulte a ajuda de cada comando para suas
opções e pré-requisitos.
Solução de problemas
- Para um erro de comando removido, use a substituição nomeada pela CLI instalada.
- Para falhas de host ou permissão, inspecione
peekaboo bridge status --jsonepeekaboo permissions status --jsonpara o host selecionado. - Para falhas de segmentação, leia a ajuda do comando folha e obtenha um estado de UI fresco com
see. - No macOS 15+, o prompt privado do seletor de janelas é separado da concessão base de Gravação de Tela e pode aparecer mesmo quando as permissões da Ponte estão corretas.