Инструменты Автоматизации Браузера: Управление Web и Автоматизация UI

Что вы сможете сделать после завершения

Запускать и управлять браузерами, управляемыми Clawdbot
Использовать ретранслятор расширения Chrome для перехвата управления ваших существующих вкладок Chrome
Создавать моментальные снимки страниц (формат AI/ARIA) и снимки экрана (PNG/JPEG)
Выполнять операции автоматизации UI: клик, ввод текста, перетаскивание, выбор, заполнение форм
Обрабатывать загрузку файлов и диалоги (alert/confirm/prompt)
Управлять распределенными браузерами через удаленный сервер управления браузером
Выполнять операции браузера на устройствах iOS/Android, используя прокси узла

Ваша текущая ситуация

Вы уже запустили Gateway и настроили модели ИИ, но у вас всё ещё есть вопросы об использовании инструментов браузера:

ИИ не может получить доступ к содержимому веб-страницы, и вам нужно описывать структуру страницы?
Вы хотите, чтобы ИИ автоматически заполнял формы и нажимал кнопки, но не знаете как это сделать?
Вы хотите делать снимки экрана или сохранять веб-страницы, но каждый раз приходится делать это вручную?
Вы хотите использовать свои собственные вкладки Chrome (с активным сеансом) вместо запуска нового браузера?
Вы хотите выполнять операции браузера на удалённых устройствах, таких как узлы iOS/Android?

Когда использовать

Сценарии использования инструментов браузера:

Сценарий	Action	Пример
Автоматизация форм	`act` + `fill`	Заполнение регистрационных форм, отправка заказов
Веб-скрапинг	`snapshot`	Извлечение структуры страницы, сбор данных
Сохранение снимков экрана	`screenshot`	Сохранение снимков экрана страниц, сохранение доказательств
Загрузка файлов	`upload`	Загрузка резюме, загрузка вложений
Обработка диалогов	`dialog`	Принятие/отклонение alert/confirm
Использование существующего сеанса	`profile="chrome"`	Работа на вкладках Chrome с активным сеансом
Удалённое управление	`target="node"`	Выполнение на узлах iOS/Android

🎒 Подготовка перед началом

Предварительная проверка

Перед использованием инструментов браузера убедитесь:

✅ Gateway запущен (clawdbot gateway start)
✅ Модели ИИ настроены (Anthropic / OpenAI / OpenRouter и т.д.)
✅ Инструменты браузера включены (browser.enabled=true)
✅ Вы понимаете целевой параметр, который собираетесь использовать (sandbox/host/custom/node)
✅ Если вы используете ретранслятор расширения Chrome, вы установили и включили расширение

Основная концепция

Что такое инструменты браузера?

Инструменты браузера — это встроенные инструменты автоматизации в Clawdbot, которые позволяют ИИ управлять браузерами через CDP (Chrome DevTools Protocol):

Сервер управления: http://127.0.0.1:18791 (по умолчанию)
Автоматизация UI: Локализация и манипуляция элементами на основе Playwright
Механизм моментальных снимков: Формат AI или ARIA, возвращает структуру страницы и ссылки на элементы
Поддержка нескольких целей: sandbox (по умолчанию), host (ретранслятор Chrome), custom (удалённый), node (узел устройства)

Два режима браузера:

Режим	Profile	Драйвер	Описание
Автономный браузер	`clawd` (по умолчанию)	clawd	Clawdbot запускает независимый экземпляр Chrome/Chromium
Ретранслятор Chrome	`chrome`	extension	Перехватывает управление вашими существующими вкладками Chrome (требует установки расширения)

Рабочий процесс:

1. Запуск браузера (start)
   ↓
2. Открытие вкладки (open)
   ↓
3. Получение моментального снимка страницы (snapshot) → получение ссылок на элементы (ref)
   ↓
4. Выполнение операций UI (act: click/type/fill/drag)
   ↓
5. Проверка результатов (screenshot/snapshot)

Следуйте шагам

Шаг 1: Запуск браузера

Почему

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

bash

# В чате попросите ИИ запустить браузер
Пожалуйста, запустите браузер

# Или используйте инструмент браузера
action: start
profile: clawd  # или chrome (ретранслятор расширения Chrome)
target: sandbox

Вы должны увидеть:

✓ Browser control server: http://127.0.0.1:18791
✓ Profile: clawd
✓ CDP endpoint: http://127.0.0.1:18792
✓ Headless: false
✓ Color: #FF4500

Контрольная точка

Видеть Browser control server означает успешный запуск
По умолчанию используется профиль clawd (автономный браузер)
Если вам нужно использовать ретранслятор расширения Chrome, используйте profile="chrome"
Окно браузера откроется автоматически (не headless режим)

Шаг 2: Открытие веб-страницы

Почему

Откройте целевую веб-страницу для подготовки к автоматизации.

bash

# В чате
Пожалуйста, откройте https://example.com

# Или используйте инструмент браузера
action: open
targetUrl: https://example.com
profile: clawd
target: sandbox

Вы должны увидеть:

✓ Tab opened: https://example.com
targetId: tab_abc123
url: https://example.com

Ссылка на элемент (targetId)

Каждый раз, когда вы открываете или фокусируете вкладку, возвращается targetId. Этот ID используется для последующих операций (snapshot/act/screenshot).

Шаг 3: Получение моментального снимка страницы

Почему

Моментальный снимок позволяет ИИ понять структуру страницы и возвращает ссылки на управляемые элементы (ref).

bash

# Получить моментальный снимок в формате AI (по умолчанию)
action: snapshot
profile: clawd
targetId: tab_abc123
snapshotFormat: ai
refs: aria  # Использует Playwright aria-ref ids (стабильно между вызовами)

# Или получить моментальный снимок в формате ARIA (структурированный вывод)
action: snapshot
profile: clawd
targetId: tab_abc123
snapshotFormat: aria

Вы должны увидеть (формат AI):

Page snapshot:

[header]
  Logo [aria-label="Example Logo"]
  Navigation [role="navigation"]
    Home [href="/"] [ref="e1"]
    About [href="/about"] [ref="e2"]
    Contact [href="/contact"] [ref="e3"]

[main]
  Hero section
    Title: "Welcome to Example" [ref="e4"]
    Button: "Get Started" [ref="e5"] [type="primary"]

[form section]
  Login form
    Input: Email [type="email"] [ref="e6"]
    Input: Password [type="password"] [ref="e7"]
    Button: "Sign In" [ref="e8"]

Выбор формата моментального снимка

Формат	Использование	Характеристики
`ai`	По умолчанию, для ИИ	Хорошая читаемость, подходит для анализа ИИ
`aria`	Структурированный вывод	Подходит для сценариев, требующих точной структуры
`refs="aria"`	Стабильно между вызовами	Рекомендуется для многошаговых операций (snapshot → act)

Шаг 4: Выполнение операций UI (act)

Почему

Используйте ссылки на элементы (ref), возвращённые в моментальном снимке, для выполнения операций автоматизации.

bash

# Кликнуть по кнопке
action: act
request: {
  kind: "click",
  ref: "e5",
  targetId: "tab_abc123"
}
profile: clawd
target: sandbox

# Ввести текст
action: act
request: {
  kind: "type",
  ref: "e6",
  text: "user@example.com",
  targetId: "tab_abc123"
}
profile: clawd
target: sandbox

# Заполнить форму (несколько полей)
action: act
request: {
  kind: "fill",
  fields: [
    { ref: "e6", value: "user@example.com" },
    { ref: "e7", value: "password123" }
  ],
  targetId: "tab_abc123"
}
profile: clawd
target: sandbox

# Кликнуть по кнопке отправки
action: act
request: {
  kind: "click",
  ref: "e8",
  targetId: "tab_abc123"
}
profile: clawd
target: sandbox

Вы должны увидеть:

✓ Clicked ref=e5
✓ Typed "user@example.com" into ref=e6
✓ Typed "password123" into ref=e7
✓ Clicked ref=e8
✓ Form submitted successfully

Распространённые операции UI

Операция	Kind	Параметры
Клик	`click`	`ref`, `doubleClick`, `button`, `modifiers`
Ввод текста	`type`	`ref`, `text`, `submit`, `slowly`
Нажатие клавиши	`press`	`key`, `targetId`
Наведение курсора	`hover`	`ref`, `targetId`
Перетаскивание	`drag`	`startRef`, `endRef`, `targetId`
Выбор	`select`	`ref`, `values`
Заполнение формы	`fill`	`fields` (массив)
Ожидание	`wait`	`timeMs`, `text`, `textGone`, `selector`
Выполнение JS	`evaluate`	`fn`, `ref`, `targetId`

Шаг 5: Создание снимка экрана веб-страницы

Почему

Проверка результатов операций или сохранение снимков экрана веб-страниц.

bash

# Снять текущую вкладку
action: screenshot
profile: clawd
targetId: tab_abc123
type: png

# Снять всю страницу
action: screenshot
profile: clawd
targetId: tab_abc123
fullPage: true
type: png

# Снять конкретный элемент
action: screenshot
profile: clawd
targetId: tab_abc123
ref: "e4"  # Использует ref из моментального снимка
type: jpeg

Вы должны увидеть:

📸 Screenshot saved: ~/.clawdbot/media/browser-screenshot-12345.png

Форматы снимков экрана

Формат	Использование
`png`	По умолчанию, сжатие без потерь, подходит для документов
`jpeg`	Сжатие с потерями, файлы меньше, подходит для хранения

Шаг 6: Обработка загрузки файлов

Почему

Автоматизация операций загрузки файлов в формах.

bash

# Сначала активировать выбор файлов (кликнуть по кнопке загрузки)
action: act
request: {
  kind: "click",
  ref: "upload_button"
}
profile: clawd
targetId: tab_abc123

# Затем загрузить файлы
action: upload
paths:
  - "/Users/you/Documents/resume.pdf"
  - "/Users/you/Documents/photo.jpg"
ref: "upload_button"  # Необязательно: указать ref выбора файлов
targetId: tab_abc123
profile: clawd

Вы должны увидеть:

✓ Files uploaded: 2
  - /Users/you/Documents/resume.pdf
  - /Users/you/Documents/photo.jpg

Примечание о путях к файлам

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

Шаг 7: Обработка диалогов

Почему

Автоматическая обработка диалогов alert, confirm, prompt на веб-страницах.

bash

# Принять диалог (alert/confirm)
action: dialog
accept: true
targetId: tab_abc123
profile: clawd

# Отклонить диалог (confirm)
action: dialog
accept: false
targetId: tab_abc123
profile: clawd

# Ответить на диалог prompt
action: dialog
accept: true
promptText: "Ответ пользователя"
targetId: tab_abc123
profile: clawd

Вы должны увидеть:

✓ Dialog handled: accepted (prompt: "Ответ пользователя")

Распространённые проблемы

❌ Ошибка: Ретранслятор расширения Chrome не подключён

Сообщение об ошибке:

No Chrome tabs are attached via Clawdbot Browser Relay extension. Click toolbar icon on tab you want to control (badge ON), then retry.

Причина: Вы использовали profile="chrome", но не прикрепили ни одной вкладки

Решение:

Установите расширение Clawdbot Browser Relay (Chrome Web Store)
Нажмите на иконку расширения во вкладке, которой хотите управлять (badge ON)
Повторно выполните action: snapshot profile="chrome"

❌ Ошибка: Ссылка на элемент устарела (stale targetId)

Сообщение об ошибке:

Chrome tab not found (stale targetId?). Run action=tabs profile="chrome" and use one of the returned targetIds.

Причина: Вкладка была закрыта или targetId устарел

Решение:

bash

# Получить снова список вкладок
action: tabs
profile: chrome

# Использовать новый targetId
action: snapshot
targetId: "новый_targetId"
profile: chrome

❌ Ошибка: Сервер управления браузером не запущен

Сообщение об ошибке:

Browser control server not available. Run action=start first.

Причина: Сервер управления браузером не запущен

Решение:

bash

# Запустить браузер
action: start
profile: clawd
target: sandbox

❌ Ошибка: Тайм-аут подключения удалённого браузера

Сообщение об ошибке:

Remote CDP handshake timeout. Check remoteCdpTimeoutMs/remoteCdpHandshakeTimeoutMs.

Причина: Тайм-аут подключения удалённого браузера

Решение:

bash

# Увеличить тайм-аут в файле конфигурации
# ~/.clawdbot/clawdbot.json
{
  "browser": {
    "remoteCdpTimeoutMs": 3000,
    "remoteCdpHandshakeTimeoutMs": 5000
  }
}

❌ Ошибка: Прокси браузера узла недоступен

Сообщение об ошибке:

Node browser proxy is disabled (gateway.nodes.browser.mode=off).

Причина: Прокси браузера узла отключён

Решение:

bash

# Включить браузер узла в файле конфигурации
# ~/.clawdbot/clawdbot.json
{
  "gateway": {
    "nodes": {
      "browser": {
        "mode": "auto"  # или "manual"
      }
    }
  }
}

Резюме урока

На этом уроке вы узнали:

✅ Управление браузером: Запуск/остановка/проверка статуса ✅ Управление вкладками: Открытие/фокусировка/закрытие вкладок ✅ Моментальные снимки страниц: Формат AI/ARIA, получение ссылок на элементы ✅ Автоматизация UI: click/type/drag/fill/wait/evaluate ✅ Снимки экрана: Формат PNG/JPEG, снимки всей страницы или элемента ✅ Загрузка файлов: Обработка выбора файлов, поддержка нескольких файлов ✅ Обработка диалогов: accept/reject/alert/confirm/prompt ✅ Ретранслятор Chrome: Используйте profile="chrome" для управления существующими вкладками ✅ Прокси узла: Выполнение на устройствах через target="node"

Быстрый справочник по ключевым операциям:

Операция	Action	Ключевые параметры
Запуск браузера	`start`	`profile` (clawd/chrome)
Открытие веб-страницы	`open`	`targetUrl`
Получение моментального снимка	`snapshot`	`targetId`, `snapshotFormat`, `refs`
Операция UI	`act`	`request.kind`, `request.ref`
Снимок экрана	`screenshot`	`targetId`, `fullPage`, `ref`
Загрузка файлов	`upload`	`paths`, `ref`
Диалог	`dialog`	`accept`, `promptText`

Следующий урок

На следующем уроке мы изучим Инструменты выполнения команд и утверждения.
Вы узнаете:
Настройка и использование инструмента exec
Понимание механизма утверждения безопасности
Настройка allowlist для управления исполняемыми командами
Использование песочницы для изоляции рискованных операций

Приложение: Справочник по исходному коду

Нажмите, чтобы развернуть местоположение исходного кода

Дата обновления: 2026-01-27

Функциональность	Путь к файлу	Номер строки
Определение инструмента Browser	`src/agents/tools/browser-tool.ts`	269-791
Browser Schema	`src/agents/tools/browser-tool.schema.ts`	1-115
Определение типов Action	`src/browser/client-actions-core.ts`	18-86
Анализ конфигурации браузера	`src/browser/config.ts`	140-231
Константы браузера	`src/browser/constants.ts`	1-9
Клиент CDP	`src/browser/cdp.ts`	1-500
Обнаружение исполняемых файлов Chrome	`src/browser/chrome.executables.ts`	1-500

Ключевые константы:

DEFAULT_CLAWD_BROWSER_CONTROL_URL = "http://127.0.0.1:18791": Адрес сервера управления по умолчанию (источник: src/browser/constants.ts:2)
DEFAULT_AI_SNAPSHOT_MAX_CHARS = 80000: Максимальное количество символов по умолчанию для AI снимков (источник: src/browser/constants.ts:6)
DEFAULT_AI_SNAPSHOT_EFFICIENT_MAX_CHARS = 10000: Максимальное количество символов в режиме efficient (источник: src/browser/constants.ts:7)
DEFAULT_AI_SNAPSHOT_EFFICIENT_DEPTH = 6: Глубина в режиме efficient (источник: src/browser/constants.ts:8)

Ключевые функции:

createBrowserTool(): Создаёт инструмент браузера, определяет все действия и обработку параметров
browserSnapshot(): Получает моментальный снимок страницы, поддерживает формат AI/ARIA
browserScreenshotAction(): Выполняет операцию создания снимка экрана, поддерживает снимки всей страницы и элемента
browserAct(): Выполняет операции автоматизации UI (click/type/drag/fill/wait/evaluate и т.д.)
browserArmFileChooser(): Обрабатывает загрузку файлов, активирует выбор файлов
browserArmDialog(): Обрабатывает диалоги (alert/confirm/prompt)
resolveBrowserConfig(): Анализирует конфигурацию браузера, возвращает адрес и порт сервера управления
resolveProfile(): Анализирует конфигурацию профиля (clawd/chrome)

Browser Actions Kind (источник: src/agents/tools/browser-tool.schema.ts:5-17):

click: Клик по элементу
type: Ввод текста
press: Нажатие клавиши
hover: Наведение курсора
drag: Перетаскивание
select: Выбор выпадающего параметра
fill: Заполнение формы (несколько полей)
resize: Изменение размера окна
wait: Ожидание
evaluate: Выполнение JavaScript
close: Закрытие вкладки

Browser Tool Actions (источник: src/agents/tools/browser-tool.schema.ts:19-36):

status: Получение статуса браузера
start: Запуск браузера
stop: Остановка браузера
profiles: Список всех профилей
tabs: Список всех вкладок
open: Открытие новой вкладки
focus: Фокусировка вкладки
close: Закрытие вкладки
snapshot: Получение моментального снимка страницы
screenshot: Создание снимка экрана
navigate: Навигация к указанному URL
console: Получение сообщений консоли
pdf: Сохранение страницы как PDF
upload: Загрузка файлов
dialog: Обработка диалогов
act: Выполнение операций UI

Начало работы с нуля

Интеграция с популярными мессенджерами

Разблокируйте сверхспособности AI

Что делать при возникновении проблем

Конфигурация, развертывание, разработка

Инструменты Автоматизации Браузера: Управление Web и Автоматизация UI

Что вы сможете сделать после завершения

Ваша текущая ситуация

Когда использовать

🎒 Подготовка перед началом

Основная концепция

Следуйте шагам

Шаг 1: Запуск браузера

Шаг 2: Открытие веб-страницы

Шаг 3: Получение моментального снимка страницы

Шаг 4: Выполнение операций UI (act)

Шаг 5: Создание снимка экрана веб-страницы

Шаг 6: Обработка загрузки файлов

Шаг 7: Обработка диалогов

Распространённые проблемы

❌ Ошибка: Ретранслятор расширения Chrome не подключён

❌ Ошибка: Ссылка на элемент устарела (stale targetId)

❌ Ошибка: Сервер управления браузером не запущен

❌ Ошибка: Тайм-аут подключения удалённого браузера

❌ Ошибка: Прокси браузера узла недоступен

Резюме урока

Следующий урок

Приложение: Справочник по исходному коду

Инструменты Автоматизации Браузера: Управление Web и Автоматизация UI ​

Что вы сможете сделать после завершения ​

Ваша текущая ситуация ​

Когда использовать ​

🎒 Подготовка перед началом ​

Основная концепция ​

Следуйте шагам ​

Шаг 1: Запуск браузера ​

Шаг 2: Открытие веб-страницы ​

Шаг 3: Получение моментального снимка страницы ​

Шаг 4: Выполнение операций UI (act) ​

Шаг 5: Создание снимка экрана веб-страницы ​

Шаг 6: Обработка загрузки файлов ​

Шаг 7: Обработка диалогов ​

Распространённые проблемы ​

❌ Ошибка: Ретранслятор расширения Chrome не подключён ​

❌ Ошибка: Ссылка на элемент устарела (stale targetId) ​

❌ Ошибка: Сервер управления браузером не запущен ​

❌ Ошибка: Тайм-аут подключения удалённого браузера ​

❌ Ошибка: Прокси браузера узла недоступен ​

Резюме урока ​

Следующий урок ​

Приложение: Справочник по исходному коду ​

Инструменты Автоматизации Браузера: Управление Web и Автоматизация UI

Что вы сможете сделать после завершения

Ваша текущая ситуация

Когда использовать

🎒 Подготовка перед началом

Основная концепция

Следуйте шагам

Шаг 1: Запуск браузера

Шаг 2: Открытие веб-страницы

Шаг 3: Получение моментального снимка страницы

Шаг 4: Выполнение операций UI (act)

Шаг 5: Создание снимка экрана веб-страницы

Шаг 6: Обработка загрузки файлов

Шаг 7: Обработка диалогов

Распространённые проблемы

❌ Ошибка: Ретранслятор расширения Chrome не подключён

❌ Ошибка: Ссылка на элемент устарела (stale targetId)

❌ Ошибка: Сервер управления браузером не запущен

❌ Ошибка: Тайм-аут подключения удалённого браузера

❌ Ошибка: Прокси браузера узла недоступен

Резюме урока

Следующий урок

Приложение: Справочник по исходному коду