Визуальные AI-агенты вроде Browser-Use или Stagehand удобны для разовых задач, но в регулярных процессах быстро упираются в стоимость и скорость. На один типовой сценарий уходит до 50 тысяч токенов и минута ожидания. Любое изменение верстки ломает цепочку шагов. Вторая проблема — авторизация: передавать логины, пароли и сессионные куки во внешние облачные песочницы рискованно.
Разработчик Jack Wener предложил другую логику: превратить нужные действия на сайтах в обычные консольные команды (CLI), которые выполняются через ваш локальный браузер Chrome с уже сохраненной сессией.
Для повторяющихся задач агент получает не визуальный кликер, а быстрый консольный интерфейс с нулевым расходом токенов и структурированным выводом в JSON, Markdown или таблицу.
Суть подхода: OpenCLI заменяет ресурсоемкое визуальное сканирование страниц детерминированными консольными командами, передавая нативные события мыши и клавиатуры в уже авторизованный профиль браузера.
Почему визуальный браузинг ломается в продакшене
Когда агенту нужно регулярно взаимодействовать с веб-сервисами, разработчики обычно выбирают один из трех путей:
- Официальные API. Надежный вариант, но у большинства платформ API закрыт, урезан или требует дорогой подписки.
- Облачные скрейперы (Firecrawl, Crawl4AI). Хорошо собирают публичные страницы, но спотыкаются о двухфакторную аутентификацию, SSO и закрытые личные кабинеты.
- Визуальные агенты (Browser-Use). Модель изучает скриншоты и пытается попасть курсором по кнопкам. Это медленно, дорого и чувствительно к случайным попапам.
OpenCLI использует другую связку: детерминированные TypeScript-адаптеры поверх активного сеанса Chrome. Вы один раз входите в аккаунт через браузер руками, а OpenCLI выполняет команды через локальное расширение-мост. Повторяющаяся операция отрабатывает за пару секунд локально и не тратит токены языковой модели.
Внутреннее устройство: от расширения Chrome до CDP
Система разделена на четыре уровня:
| Компонент | Роль | Принцип работы |
|---|---|---|
| Browser Bridge Extension | Мост к авторизации | Расширение для Chrome из Web Store. Подключается к локальному демону и передает команды активным вкладкам |
| Local Daemon | Фоновый диспетчер | Процесс на рабочей машине. Принимает вызовы из терминала и связывает их с нужным профилем браузера |
| Native Input Backend (CDP) | Нативный ввод | Отправка реальных системных событий мыши и клавиатуры через Chrome DevTools Protocol вместо синтетических JS-кликов |
| Accessibility Tree (AX) | Устойчивое зрение | Снятие компактных снимков дерева доступности вместо сырого DOM, что исключает сбои при перерисовках в React |
Почему реальный ввод через CDP надежнее element.click()
Обычные скрипты автоматизации находят элемент в DOM и вызывают метод .click(). В современных веб-приложениях на базе React, Radix UI или shadcn/ui это приводит к скрытым ошибкам: выпадающие списки и модальные окна часто слушают события pointerdown, mousedown или mouseup. Скрипт считает, что клик прошел, но интерфейс не реагирует.
OpenCLI находит точные координаты центра элемента и передает через CDP низкоуровневые события Input.dispatchMouseEvent (mousePressed и mouseReleased). Для страницы это полноценный клик реального пользователя, поэтому кастомные меню открываются стабильно.
Снимки дерева доступности (AX Tree)
Вместо тяжелых скриншотов OpenCLI собирает для агента компактное дерево доступности (Accessibility.getFullAXTree).
Каждый элемент получает идентификатор ссылки (@ref). Если компонент на странице перерисовывается при открытии диалогового окна, OpenCLI находит потерянный элемент по роли (role), имени (name) и порядковому номеру (nth). Агенту не нужно повторно сканировать весь экран и тратить контекст.
Десктопный слой: OpenCLIApp и Electron-приложения
Для повседневной работы на macOS и Windows доступно приложение OpenCLIApp (https://opencli.info/download). Оно работает в системном трее и решает практические задачи:
- Диагностика окружения: утилита
opencliподключается в систему в один клик, а встроенныйdoctorсразу проверяет статус демона и расширения Chrome. - Продление сессий (Keepalive): фоновый опрос открытых вкладок защищает корпоративные токены и сессионные куки от сброса по таймауту.
- Конвертер Web в Markdown: очищает текущую веб-страницу от визуального шума и отдает чистый текст для контекста локальных LLM.
- Контроль Electron-приложений: через CDP и AppleScript OpenCLI отправляет команды в Cursor, Codex, ChatGPT Desktop и Antigravity прямо из терминала.
Агентный контур: навыки для Claude Code, Cursor и терминала
OpenCLI задумывался как рабочий инструмент для внешних кодинг-агентов. В репозитории есть готовый набор навыков, который ставится одной командой:
npx skills add jackwener/opencliКомплект навыков распределяет задачи агента по отдельным модулям:
| Навык | Назначение и сценарий использования |
|---|---|
opencli-browser | Интерактивное управление живой страницей: переходы, клики по @ref, ввод текста и чтение снимка DOM. |
opencli-adapter-author | Разработка нового повторяемого адаптера: отслеживание сетевых запросов и генерация TypeScript-кода. |
opencli-autofix | Автоматическая корректировка селекторов и структуры данных адаптера после обновления верстки сайта. |
opencli-browser-sitemap | Навигация по проверенной структуре сайта без блуждания по посторонним ссылкам. |
opencli-sitemap-author | Составление и валидация стабильных маршрутов по ключевым разделам сервиса. |
opencli-usage | Встроенный справочник по готовым командам и поддерживаемым площадкам. |
Модель не тратит контекстное окно на изучение документации сайта, а сразу вызывает нужную утилиту через консоль.
Сравнение подходов к автоматизации
| Инструмент | Основной подход | Расход токенов | Скорость ответа | Работа с авторизацией |
|---|---|---|---|---|
| OpenCLI | Детерминированные TS-адаптеры + CDP | 0 токенов для адаптеров | 1–3 секунды | Сессия вашего профиля Chrome |
| Browser-Use | Визуальный LLM-агент по скриншотам | Высокий (на каждый шаг) | 15–60 секунд | Ручной перенос куки или профиля |
| Stagehand | Обертка над Playwright (act, extract) | Средний / высокий | 5–20 секунд | Программная настройка контекста |
| Firecrawl | Облачный API выгрузки в Markdown | По тарифам сервиса | 3–10 секунд | Только открытые страницы |
| agent-browser | Примитивы на базе Accessibility Tree | Средний (нужен план модели) | 3–10 секунд | Отдельный инстанс Chromium |
Быстрый старт и практическое применение
1. Установка и подключение
Для десктопа проще всего скачать приложение с официального сайта https://opencli.info/download, запустить OpenCLIApp и подтвердить установку команды в систему.
Для серверов и CI доступна установка через npm (нужен Node.js не ниже 20.18.1):
npm install -g @jackwener/opencliПосле этого установите расширение OpenCLI из Chrome Web Store и проверьте связь:
opencli doctor2. Работа с несколькими профилями Chrome
Если вы разделяете личный и рабочий браузеры, OpenCLI умеет переключаться между ними:
# Список подключенных профилей браузера
opencli profile list
# Назначение имени рабочему профилю
opencli profile rename <contextId> work
opencli profile use work
# Проверка состояния браузера в выбранном профиле
opencli --profile work browser main state3. Управление сессиями и вкладками браузера
Для прямого взаимодействия со страницей OpenCLI использует концепцию именованных сессий. Это исключает коллизии, когда агент одновременно обращается к разным сайтам.
⚖️ Правило сессий: Команды группы
opencli browserтребуют обязательного указания имени сессии:opencli browser <session> <action>. Сессия сохраняет привязку к вкладке до командыcloseили автоматического сброса по таймауту неактивности.
# Открытие целевой страницы в сессии "work"
opencli browser work open https://github.com
# Просмотр открытых вкладок и выбор целевой страницы
opencli browser work tab list
opencli browser work tab select <targetId>
# Получение компактного снимка дерева доступности
opencli browser work state4. Вызов встроенных адаптеров
В репозитории есть больше сотни адаптеров под популярные платформы:
# Топ записей HackerNews в формате JSON
opencli hackernews top --limit 5 -f json
# Поиск постов в Twitter с выводом в таблицу
opencli twitter search "AI agents" --limit 10 -f table5. Создание собственного адаптера и способы расширения
Если нужного внутреннего сервиса нет в списке, создание адаптера занимает несколько минут:
# Каркас адаптера в ~/.opencli/clis/
opencli browser init myportal/reports
# Проверка работы адаптера на живой странице
opencli browser verify myportal/reports
# Вызов новой команды
opencli myportal reportsДля командной и локальной разработки предусмотрено несколько сценариев расширения:
| Сценарий | Команда и механизм |
|---|---|
| Создание изолированного плагина | opencli plugin create с подключением локального или Git-репозитория (opencli plugin install file://...) |
| Локальный адаптер под закрытый сервис | opencli browser init <site>/<cmd> с сохранением в каталоге ~/.opencli/clis/ |
| Модификация официального адаптера | opencli adapter eject (откат к исходной версии через opencli adapter reset) |
| Установка сторонних расширений | opencli plugin install github:user/repo |
| Регистрация внешних CLI-утилит | opencli external register (объединение в общий интерфейс с gh, docker, vercel) |
Справочник: форматы вывода, коды завершения и переменные окружения
Форматы вывода данных
Встроенные команды по умолчанию выводят результат в виде терминальной таблицы (table), но для интеграции в цепочки скриптов и агентные контуры поддерживают форматы json, yaml, md и csv:
# Вывод в формате JSON для программного парсинга
opencli bilibili hot -f json
# Вывод в Markdown для передачи в контекст LLM
opencli bilibili hot -f mdКоды завершения (Exit Codes)
Для надежной обработки ошибок агентом команды OpenCLI возвращают стандартизированные коды завершения:
| Код | Статус | Значение для скрипта или агента |
|---|---|---|
| 0 | Успех | Команда выполнена штатно, данные получены. |
| 66 | Пустой результат | Запрос отработал, но целевых элементов на странице не найдено. |
| 69 | Мост недоступен | Browser Bridge не отвечает (расширение выключено или закрыт Chrome). |
| 75 | Превышен таймаут | Сервис не успел отдать данные за отведенное время ожидания. |
| 77 | Нужна авторизация | Сессия истекла, требуется повторный вход в браузере. |
| 78 | Ошибка параметров | Некорректные флаги или аргументы командной строки. |
| 130 | Прервано | Выполнение остановлено сигналом пользователя (Ctrl+C). |
Переменные окружения
Поведение OpenCLI на серверах и в CI настраивается через системные переменные:
| Переменная | Назначение |
|---|---|
OPENCLI\_PROFILE | Имя профиля Chrome по умолчанию при наличии нескольких подключений. |
OPENCLI\_WINDOW | Режим отображения окна браузера: foreground (активное) или background (фоновое). |
OPENCLI\_SITE\_SESSION | Режим сессии адаптера: ephemeral (разовая) или persistent (сохраняемая). |
OPENCLI\_BROWSER\_CONNECT\_TIMEOUT | Таймаут ожидания подключения браузерного моста (по умолчанию 45 секунд). |
OPENCLI\_BROWSER\_COMMAND\_TIMEOUT | Таймаут выполнения отдельной команды браузера (по умолчанию 60 секунд). |
OPENCLI\_CDP\_ENDPOINT | Адрес подключения к удаленному порту CDP или запущенному Electron-приложению. |
OPENCLI\_CDP\_TARGET | Фильтрация целевых вкладок CDP по подстроке в URL. |
OPENCLI\_VERBOSE | Включение подробного журнала отладки (аналог флага -v). |
DEBUG\_SNAPSHOT | Вывод сырого снимка дерева доступности при значении 1. |
Безопасность профиля: Автоматизацию следует запускать в изолированном профиле Chrome без сохраненных банковских карт, личной переписки и критичных прав администратора.
Ограничения
Ограничения
Привязка к Chrome: Для работы авторизованных команд нужен запущенный браузер с расширением.
На сервере без графической оболочки придется поднимать headless-режим и вручную настраивать порт CDP.
Зависимость от верстки сервисов:
Если сайт полностью переписывает фронтенд или меняет приватные API, адаптер потребует обновления (навык opencli-autofix берет часть правок на себя).
Специализация вместо универсальности: Инструмент решает задачи с повторяющейся структурой.
Для исследовательского серфинга по незнакомым сайтам лучше оставить Stagehand или Browser-Use.
Контроль прав доступа: Агент с доступом к opencli оперирует реальными сессиями пользователя.
Не стоит давать модели бесконтрольный доступ к профилю с почтой или финансами.
Антипаттерны
Антипаттерны
Сжигать токены на рутинный сбор данных:
Гонять мультимодальные модели по скриншотам каждые полчаса вместо того, чтобы один раз зафиксировать сценарий в адаптере.
Хранить сессионные куки в открытом коде:
Складывать cookies в файлы проекта вместо безопасной передачи через локальный мост расширения.
Использовать синтетические клики в сложных UI:
Вызывать .click() на нестандартных выпадающих списках вместо передачи нативных CDP-событий мыши.
Пускать агента в основной профиль браузера:
Запускать автоматизацию под личным профилем Chrome без изоляции рабочих задач.
Чеклист
Чеклист
Проверьте статус моста:
Команда opencli doctor подтверждает связь демона с расширением Chrome.
Изолируйте рабочий профиль:
Для автоматизации создан отдельный профиль Chrome (opencli profile rename ...), не связанный с личными аккаунтами.
Зафиксируйте формат вывода:
В скриптах агента явно указан флаг -f json или -f md для предсказуемой обработки данных.
Протестируйте адаптер перед запуском:
Новая команда проверена через opencli browser verify <site>/<cmd> на реальной странице.
Подключите навыки к агенту:
Пакет jackwener/opencli добавлен в рабочий кодинг-агент через npx skills add.
Ссылки
Ссылки
- Репозиторий: GitHub jackwener/OpenCLI
- Загрузка приложения: OpenCLIApp Download
- Расширение браузера: OpenCLI в Chrome Web Store