Автоматизируйте интерфейс macOS с помощью CLI-инструмента Peekaboo

Как применить

Примеры используют синтаксис версии 4, в котором удалены старые корневые команды: команда screenshot заменена на see, захват изображения без распознавания элементов имеет собственный режим, для кликов используется команда press с комбинациями клавиш, а управление окнами и меню перенесено в команду see. При ошибке, связанной с удалённой командой, используйте её заменитель, указанный в установленном CLI. При проблемах с хостом или разрешениями проверьте статус моста и его JSON-вывод для выбранного хоста. При неудачном выборе цели прочитайте справку по конкретному элементу и получите актуальное состояние интерфейса с помощью новой команды see. На macOS 15+ запрос на выбор окна отображается отдельно от основного разрешения на запись экрана и может появляться даже при корректных разрешениях Bridge.

Ознакомьтесь с актуальной документацией и справкой установленной команды; для старых версий следуйте инструкциям соответствующей версии.

В версии 4 удалены старые корневые команды, перечисленные в таблице миграции.

В версии 4 старые команды screenshot, click и управления окнами заменены на новые команды see, press и связанные с ними; для работы с пикселями без распознавания элементов используйте режим screen, а для кликов — комбинации клавиш, такие как cmd+shift+t.

При ошибке, связанной с удалённой командой, используйте её заменитель, указанный в установленном CLI.

При проблемах с хостом или разрешениями проверьте вывод статуса моста.

Проверьте JSON-вывод статуса для выбранного хоста.

При неудачном выборе цели прочитайте справку по конкретному элементу и получите актуальное состояние интерфейса с помощью новой команды see.

На macOS 15+ запрос на выбор окна отображается отдельно от основного разрешения на запись экрана.

Запрос на выбор окна может появляться даже при корректных разрешениях Bridge.

Приложение OpenClaw для macOS размещает Peekaboo Bridge, когда включён режим управления компьютером, провайдером выступает Peekaboo, а сам Peekaboo Bridge активирован.

При работе через этот хост сохраняйте существующий выбор сокета OpenClaw.

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

Убедитесь, что выбранный хост и сокет соответствуют ожидаемым, и сохраняйте любой явный выбор хоста или сокета. Если требуемый хост недоступен, сообщите об этом; не стоит сбрасывать выбор или менять провайдера режима управления компьютером, чтобы команда выполнилась.

Разрешения принадлежат процессу или хосту Bridge, выполняющему операцию; поэтому не передавайте флаг переопределения разрешений, если у вызывающего нет необходимых прав.

Используйте справку каждой команды, чтобы узнать о её флагах и требованиях к выбору цели, вместо того чтобы копировать флаги между командами.

Используйте справку корневого уровня, чтобы увидеть доступные команды, а справку по конкретному элементу — для получения информации о флагах и требованиях к выбору цели.

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

Для других операций, включая клики, ввод текста, прокрутку, управление окнами или меню, используйте соответствующую команду, размещайте параметры команды после неё и применяйте флаг структурированного вывода для получения структурированных данных.

Начните с инвентаризации приложений и получения актуального представления о целевом объекте перед выполнением действий.

Составьте список запущенных приложений и сделайте новый, аннотированный снимок экрана нужного приложения и окна.

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

Прочитайте возвращаемые элементы перед выполнением действий. Связывайте действия с конкретным приложением, окном и актуальным снимком экрана; не используйте идентификаторы элементов из примеров повторно. После действия снова проверьте интерфейс и убедитесь в достижении желаемого результата, обновляя данные при изменении окна или устаревании цели.

Для создания снимка экрана без распознавания элементов используйте режим screen с отключённым распознаванием элементов.

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

Для сырых комбинаций клавиш требуется явное взаимодействие в переднем плане или новая информация о точном окне, принимаемая командой нажатия. Перетаскивание всегда перемещает общий курсор и требует установки флага переднего плана, поэтому используйте их только при наличии разрешения на взаимодействие в переднем плане.

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

Используйте фактическую цель и координаты из текущего наблюдения, предпочтительно указывайте явные единицы времени для действий с таймером, а также ознакомьтесь со справкой каждой команды, чтобы узнать о её параметрах и требованиях.