Skip to main content

​
openclaw browser

Керуйте інтерфейсом керування браузером OpenClaw і виконуйте дії в браузері: керування життєвим циклом, профілями, вкладками, знімками, знімками екрана, навігацією, введенням, емуляцією стану та налагодженням. Пов’язане: Інструмент браузера

​
Загальні прапорці

  • --url <gatewayWsUrl>: URL WebSocket Gateway (типово береться з конфігурації).
  • --token <token>: токен Gateway (якщо потрібен).
  • --timeout <ms>: час очікування запиту в мс (типово: 30000).
  • --expect-final: очікувати на остаточну відповідь Gateway.
  • --browser-profile <name>: вибрати профіль браузера (типово: openclaw або browser.defaultProfile).
  • --json: машинозчитуваний формат виведення (де підтримується). Це параметр рівня браузера, тому для однозначності розміщуйте його перед підкомандою, наприклад openclaw browser --json status. Розміщення в кінці, наприклад openclaw browser status --json, також працює, якщо вибрана дочірня команда не визначає власний параметр --json.

​
Швидкий початок роботи (локально)

Агенти можуть виконувати таку саму перевірку готовності за допомогою browser({ action: "doctor" }).

​
Швидке усунення несправностей

Якщо start завершується помилкою not reachable after start, спочатку перевірте готовність CDP. Якщо start і tabs виконуються успішно, але open або navigate завершується помилкою, рівень керування браузером справний, а причиною збою зазвичай є блокування політикою SSRF для навігації. Мінімальна послідовність:
Докладні вказівки: Усунення несправностей браузера

​
Життєвий цикл

  • doctor --deep додає активну перевірку знімка: це корисно, коли базова готовність CDP підтверджена, але потрібно довести, що поточну вкладку можна перевірити.
  • Для запущеного локального керованого профілю status і doctor повертають кешовані діагностичні дані графічної підсистеми Chrome: класифікацію апаратного й програмного забезпечення, засіб візуалізації, бекенд, пристрій і драйвер, відомості про функції та стан їх вимкнення, а також можливості апаратно прискореного відео. openclaw browser --json status повертає повне структуроване корисне навантаження. Пасивна перевірка стану ніколи не запускає Chrome лише для збирання цих даних.
  • stop закриває активний сеанс керування та очищає тимчасові перевизначення емуляції навіть для attachOnly і віддалених профілів CDP, у яких OpenClaw не запускав сам процес браузера. Для локальних керованих профілів stop також зупиняє породжений процес браузера.
  • start --headless застосовується лише до цього запиту запуску й лише тоді, коли OpenClaw запускає локальний керований браузер. Він не змінює browser.headless або конфігурацію профілю й не виконує жодних дій для вже запущеного браузера.
  • На хостах Linux без DISPLAY або WAYLAND_DISPLAY локальні керовані профілі автоматично запускаються в безголовому режимі, якщо OPENCLAW_BROWSER_HEADLESS=0, browser.headless=false або browser.profiles.<name>.headless=false явно не вимагає браузер із видимим інтерфейсом.

​
Якщо команда відсутня

Якщо openclaw browser є невідомою командою, перевірте plugins.allow у ~/.openclaw/openclaw.json. Якщо наявний plugins.allow, явно додайте вбудований Plugin браузера до списку, якщо конфігурація ще не містить кореневого блоку browser:
Явний кореневий блок browser (наприклад, browser.enabled=true або browser.profiles.<name>) також активує вбудований Plugin браузера за обмежувального списку дозволених плагінів. Пов’язане: Інструмент браузера

​
Профілі

Профілі — це іменовані конфігурації маршрутизації браузера:
  • openclaw (типово): запускає виділений екземпляр Chrome під керуванням OpenClaw або під’єднується до нього (ізольований каталог даних користувача).
  • user: керує наявним сеансом Chrome із виконаним входом через Chrome DevTools MCP.
  • власні профілі CDP: указують на локальну або віддалену кінцеву точку CDP.
Використовуйте певний профіль із --browser-profile <name> у будь-якій підкоманді, наприклад openclaw browser --browser-profile work tabs. У macOS команда system-profiles виводить реальні профілі Chrome, Brave, Edge або Chromium, доступні на хості. import-profile розшифровує їхні файли cookie після одноразового запиту згоди через macOS Keychain/Touch ID і вставляє їх у новий профіль під керуванням OpenClaw. Імпортуються лише файли cookie; локальне сховище та IndexedDB не змінюються. Деякі сеанси Google використовують прив’язані до пристрою облікові дані сеансу (DBSC), тому після імпорту може все одно знадобитися повторна автентифікація. Коли застосунок macOS використовує локальний Gateway, він може один раз запропонувати цей імпорт і зробити ізольований імпортований профіль типовим для роботи агентів у браузері. Імпорт завжди потребує явного клацання; успішний імпорт або відхилення пропозиції запобігає подальшим автоматичним запитам, а пункт Settings → General → Browser login залишається доступним для повторного імпорту. Імпорт системного профілю типово ввімкнений. Установіть browser.allowSystemProfileImport=false, щоб вимкнути імпорти як із CLI, так і запущені агентом. Імпорт виконується лише локально на хості й не може працювати через проксі браузерного вузла.

​
Вкладки

tabs спочатку повертає suggestedTargetId, потім стабільний tabId (наприклад, t1), необов’язкову мітку та необроблений targetId. Передавайте suggestedTargetId назад до focus, close, знімків і дій. Призначайте мітку за допомогою open --label, tab new --label або tab label; приймаються мітки, ідентифікатори вкладок, необроблені ідентифікатори цілей і унікальні префікси ідентифікаторів цілей. Для сумісності поле запиту досі має назву targetId, але приймає будь-яке з цих посилань на вкладку. Необроблені ідентифікатори цілей — це мінливі діагностичні дескриптори, а не довготривала пам’ять агента: коли Chromium замінює базову необроблену ціль під час навігації або надсилання форми, OpenClaw зберігає стабільний tabId/мітку, пов’язану з новою вкладкою, якщо може достовірно встановити відповідність. Надавайте перевагу suggestedTargetId.

​
Знімок / знімок екрана / дії

Знімок:
Знімок екрана:
  • --full-page призначений лише для знімків сторінки; його не можна поєднувати з --ref або --element.
  • Профілі existing-session / user підтримують знімки екрана сторінки та знімки екрана --ref із результатів знімка, але не знімки екрана за CSS --element.
  • --labels накладає посилання поточного знімка на знімок екрана. У профілях на основі Playwright він працює з --full-page (накладання на всю сторінку), --ref (накладання на обрізану ділянку елемента за посиланням ARIA) і --element (накладання на обрізану ділянку елемента за селектором CSS); у режимах обрізання за елементом мітки проєктуються відносно елемента. Відповідь також містить масив annotations (пропускається, якщо порожній) з обмежувальною рамкою кожного посилання: ref, number, role, необов’язковий name і box: {x, y, width, height} у системі координат захопленого зображення (область перегляду / повна сторінка / відносно елемента). Профілі existing-session відображають накладання chrome-mcp на знімках екрана сторінки, але не використовують допоміжний засіб проєкції Playwright і не містять annotations; знімки екрана за CSS --element там не підтримуються. Без Playwright або chrome-mcp знімки екрана з мітками недоступні.
  • snapshot --urls додає знайдені адреси посилань до знімків для ШІ, щоб агенти могли вибирати безпосередні цілі навігації замість припущень лише на основі тексту посилання.
Навігація/клацання/введення (автоматизація інтерфейсу на основі посилань):
evaluate --fn приймає вихідний код функції, вираз або тіло інструкції. Тіла інструкцій обгортаються в асинхронні функції, тому використовуйте return для значення, яке потрібно отримати. Використовуйте --timeout-ms, якщо функції на боці сторінки може знадобитися більше часу, ніж типовий час очікування обчислення. browser.evaluateEnabled=false (типово: true) вимикає і evaluate, і wait --fn. Відповіді на дії повертають поточний необроблений targetId після спричиненої дією заміни сторінки, якщо OpenClaw може достовірно визначити нову вкладку. Для довготривалих робочих процесів скриптам однаково слід зберігати й передавати suggestedTargetId/мітки. Допоміжні засоби для файлів і діалогових вікон:
Керовані профілі Chrome зберігають звичайні завантаження, ініційовані клацанням, у каталозі завантажень OpenClaw (типово /tmp/openclaw/downloads або налаштований кореневий каталог тимчасових файлів). Використовуйте waitfordownload або download, коли агенту потрібно дочекатися певного файлу й повернути шлях до нього; ці явні засоби очікування отримують наступне завантаження. Для передавання приймаються файли з кореневого каталогу тимчасових передавань OpenClaw і вхідні медіафайли під керуванням OpenClaw, зокрема посилання media://inbound/<id> і media/inbound/<id> із шляхами відносно пісочниці. Вкладені посилання на медіафайли, обхід каталогів і довільні локальні шляхи відхиляються. Коли дія відкриває модальне діалогове вікно, відповідь на дію повертає blockedByDialog з browserState.dialogs.pending; передайте --dialog-id, щоб відповісти на нього безпосередньо. Діалогові вікна, оброблені поза OpenClaw, відображаються в browserState.dialogs.recent.

​
Стан і сховище

Область перегляду й емуляція:
Файли cookie + сховище:

​
Налагодження

​
Наявний Chrome через MCP

Скористайтеся вбудованим профілем user або створіть власний профіль existing-session:
Стандартний шлях existing-session призначений для автоматичного підключення Chrome MCP лише на хості. Якщо браузер уже запущено з кінцевою точкою DevTools, передайте --cdp-url, щоб Chrome MCP натомість підключився до цієї кінцевої точки. Для Docker, Browserless або інших віддалених конфігурацій, де семантика Chrome MCP не потрібна, натомість використовуйте профіль CDP. Поточні обмеження existing-session:
  • Дії на основі знімків використовують посилання, а не селектори CSS.
  • browser.actionTimeoutMs за замовчуванням установлює для підтримуваних запитів act значення 60000 мс, якщо виклики не вказують timeoutMs; значення timeoutMs для окремого виклику все одно має пріоритет.
  • click підтримує лише клацання лівою кнопкою.
  • type не підтримує slowly=true.
  • press не підтримує delayMs.
  • hover, scrollintoview, drag, select і fill відхиляють перевизначення часу очікування для окремих викликів; evaluate приймає --timeout-ms.
  • select підтримує лише одне значення.
  • wait --load networkidle не підтримується (працює з керованими та необробленими/віддаленими профілями CDP).
  • Для завантаження файлів потрібні --ref / --input-ref; селектор CSS --element не підтримується, і одночасно можна завантажити лише один файл.
  • Обробники діалогових вікон не підтримують --timeout.
  • Знімки екрана підтримують захоплення сторінки та --ref, але не селектор CSS --element.
  • Для responsebody, перехоплення завантажень, експорту PDF і пакетних дій усе ще потрібен керований браузер або необроблений профіль CDP.

​
Віддалене керування браузером (проксі хоста Node)

Якщо Gateway працює на іншому комп’ютері, ніж браузер, запустіть хост Node на комп’ютері, де встановлено Chrome/Brave/Edge/Chromium. Gateway пересилає дії браузера на цей вузол через проксі; окремий сервер керування браузером не потрібен. Використовуйте gateway.nodes.browser.mode для керування автоматичною маршрутизацією та gateway.nodes.browser.node, щоб закріпити конкретний вузол, якщо підключено кілька. Безпека + віддалене налаштування: Інструмент браузера, Віддалений доступ, Tailscale, Безпека

​
Пов’язані матеріали