Peekaboo

Was macht Peekaboo?

Verwende Peekaboo, um die macOS-Benutzeroberfläche zu inspizieren, auf das beabsichtigte Ziel zu wirken und das Ergebnis zu überprüfen. Die folgenden Beispiele verwenden die v4-Syntax. Überprüfe peekaboo --version und die installierte Befehls --help; für ältere Versionen folge der Hilfe dieser Version.

OpenClaw Bridge

Die OpenClaw-macOS-App hostet Peekaboo Bridge, wenn die Computersteuerung aktiviert ist, der Anbieter Peekaboo ist und Peekaboo Bridge aktiviert ist. Behalte die vorhandene OpenClaw-Socket-Auswahl bei, wenn du über diesen Host läufst:

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

Bestätige, dass der ausgewählte Host und Socket die beabsichtigten sind. Behalte eine explizite PEEKABOO_BRIDGE_SOCKET- oder --bridge-socket-Auswahl bei. Wenn der erforderliche Host nicht verfügbar ist, melde dieses Ergebnis; setze die Auswahl nicht zurück oder wechsle Computersteuerungsanbieter, um einen Befehl erfolgreich auszuführen.

Berechtigungen gehören dem Prozess oder Bridge-Host, der die Operation durchführt. Übergib --no-remote nur, wenn der Aufrufer die erforderlichen Berechtigungen hat.

Finde den installierten Befehl

Verwende die Blatthilfe für Flags und Targeting-Anforderungen, anstatt ein Flag zwischen Befehlen zu kopieren. Verwende die Stammhilfe, um die verfügbaren Befehle zu entdecken:

peekaboo --help
peekaboo app list --help
peekaboo see --help
peekaboo press --help
peekaboo drag --help

V4 hat diese alten Befehlsstämme entfernt:

Alter Befehl	V4-Befehl
list apps	app list
image	see --no-elements für Pixel ohne Elementerkennung
hotkey	press mit Akkorden wie cmd+shift+t
swipe	drag --from … --to …

Für andere Operationen, einschließlich Klicken, Tippen, Scrollen und Verwalten von Fenstern oder Menüs, verwende peekaboo <command> --help. Setze Befehlsoptionen nach dem Blattbefehl; --json fordert strukturierte Ausgabe an.

Inspizieren, handeln, überprüfen

Beginne mit der Anwendungsinventur und einer frischen Ansicht des Ziels:

peekaboo app list --json
peekaboo see --app Safari --window-title "Example" --annotate \
  --path /tmp/peekaboo-example.png --json

Lies die zurückgegebenen Elemente, bevor du handelst. Halte Aktionen an die beabsichtigte App, das Fenster und den aktuellen Schnappschuss gebunden; verwende keine Beispiel-Element-IDs erneut. Nach einer Aktion inspiziere die UI erneut und überprüfe das angeforderte Ergebnis. Aktualisiere die Beobachtung, wenn sich das Fenster ändert oder ein Ziel veraltet ist.

Für einen Screenshot ohne Elementerkennung:

peekaboo see --mode screen --screen-index 0 --no-elements --retina \
  --path /tmp/peekaboo-screen.png --json

Rohe Tastaturkürzel erfordern explizite Vordergrundinteraktion oder einen frischen Exakt-Fenster-Empfang, der von press akzeptiert wird. Ziehen bewegt immer den geteilten Cursor und erfordert --foreground. Wenn Vordergrundinteraktion autorisiert ist:

peekaboo press cmd+shift+t --app Safari --foreground --json
peekaboo drag --from 100,500 --to 100,200 --duration 800ms --foreground --json

Verwende das tatsächliche Ziel und die Koordinaten aus der aktuellen Beobachtung. Bevorzuge explizite Dauereinheiten wie 800ms; konsultiere die Hilfe jedes Befehls für seine Optionen und Voraussetzungen.

Fehlerbehebung

• Bei einem Fehler wegen entfernten Befehls verwende den vom installierten CLI benannten Ersatz.
• Bei Host- oder Berechtigungsfehlern inspiziere peekaboo bridge status --json und peekaboo permissions status --json für den ausgewählten Host.
• Bei Targeting-Fehlern lies die Blatthilfe und rufe mit see einen frischen UI-Status ab.
• Unter macOS 15+ ist die private Fensterauswahlaufforderung von der Basis-Bildschirmaufnahme-Berechtigung getrennt und kann auch dann erscheinen, wenn Bridge-Berechtigungen korrekt sind.