--- read_when: - Написання сценаріїв або налагодження браузера агента через локальний API керування - Шукаєте довідку CLI для `openclaw browser` - Додавання користувацької автоматизації браузера зі знімками та refs summary: Довідник API керування браузером OpenClaw, CLI та сценарних дій title: API керування браузером x-i18n: generated_at: "2026-06-27T18:23:22Z" model: gpt-5.5 postprocess_version: locale-links-v1 provider: openai source_hash: ccfd1ec996b0fc211e2aefa0554e0fa5c7b0899ca981836134a3741b38bf7600 source_path: tools/browser-control.md workflow: 16 --- Для налаштування, конфігурації та усунення несправностей див. [Браузер](/uk/tools/browser). Ця сторінка є довідником для локального керівного HTTP API, CLI `openclaw browser` і шаблонів скриптів (знімки, посилання, очікування, потоки налагодження). ## Керівний API (необов’язково) Лише для локальних інтеграцій Gateway надає невеликий loopback HTTP API. Цей окремий сервер є opt-in — задайте змінну середовища `OPENCLAW_EAGER_BROWSER_CONTROL_SERVER=1` у середовищі сервісу gateway і перезапустіть gateway, перш ніж HTTP endpoint-и стануть доступними. Без цієї змінної браузерний runtime керування все одно працює через CLI та інструменти агента, але ніщо не слухає керівний loopback-порт. - Статус/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` - Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` - Знімок/скриншот: `GET /snapshot`, `POST /screenshot` - Дії: `POST /navigate`, `POST /act` - Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Завантаження: `POST /download`, `POST /wait/download` - Дозволи: `POST /permissions/grant` - Налагодження: `GET /console`, `POST /pdf` - Налагодження: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight` - Мережа: `POST /response/body` - Стан: `GET /cookies`, `POST /cookies/set`, `POST /cookies/clear` - Стан: `GET /storage/:kind`, `POST /storage/:kind/set`, `POST /storage/:kind/clear` - Налаштування: `POST /set/offline`, `POST /set/headers`, `POST /set/credentials`, `POST /set/geolocation`, `POST /set/media`, `POST /set/timezone`, `POST /set/locale`, `POST /set/device` Усі endpoint-и приймають `?profile=`. `POST /start?headless=true` запитує одноразовий headless-запуск для локальних керованих профілів без зміни збереженої конфігурації браузера; профілі attach-only, remote CDP і existing-session відхиляють це перевизначення, бо OpenClaw не запускає ці процеси браузера. Для endpoint-ів вкладок `targetId` є назвою поля сумісності. Надавайте перевагу передаванню `suggestedTargetId` з `GET /tabs` або `POST /tabs/open`; мітки та handle-и `tabId`, як-от `t1`, також приймаються. Сирі target id CDP і унікальні сирі префікси target-id досі працюють, але це несталі діагностичні handle-и. Якщо налаштовано автентифікацію gateway зі спільним секретом, браузерні HTTP-маршрути також потребують автентифікації: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: - Цей окремий loopback браузерний API **не** споживає trusted-proxy або заголовки ідентичності Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback браузерні маршрути не успадковують ці режими з ідентичністю; тримайте їх лише loopback. ### Контракт помилок `/act` `POST /act` використовує структуровану відповідь про помилку для перевірки на рівні маршруту та збоїв політики: ```json { "error": "", "code": "ACT_*" } ``` Поточні значення `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний. - `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або перевірку. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з непідтримуваним типом дії. - `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено конфігурацією. - `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з ціллю запиту. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session. Інші runtime-збої все ще можуть повертати `{ "error": "" }` без поля `code`. ### Вимога Playwright Деякі функції (navigate/act/AI snapshot/role snapshot, скриншоти елементів, PDF) потребують Playwright. Якщо Playwright не встановлено, ці endpoint-и повертають чітку помилку 501. Що все ще працює без Playwright: - ARIA snapshots - Role-style знімки доступності (`--interactive`, `--compact`, `--depth`, `--efficient`), коли доступний WebSocket CDP для окремої вкладки. Це fallback для інспекції та виявлення refs; Playwright залишається основним рушієм дій. - Скриншоти сторінок для керованого браузера `openclaw`, коли доступний WebSocket CDP для окремої вкладки - Скриншоти сторінок для профілів `existing-session` / Chrome MCP - Ref-based скриншоти `existing-session` (`--ref`) з виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` - AI snapshots, що залежать від нативного формату AI snapshot Playwright - Скриншоти елементів за CSS-селектором (`--element`) - Повний експорт браузера в PDF Скриншоти елементів також відхиляють `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. Якщо ви бачите `Playwright is not available in this gateway build`, у запакованому Gateway бракує основної браузерної runtime-залежності. Перевстановіть або оновіть OpenClaw, а потім перезапустіть gateway. Для Docker також установіть браузерні бінарні файли Chromium, як показано нижче. #### Встановлення Playwright у Docker Якщо ваш Gateway працює в Docker, уникайте `npx playwright` (конфлікти npm override). Для власних образів вбудуйте Chromium в образ: ```bash OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh ``` Для наявного образу натомість установіть через bundled CLI: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` Щоб зберігати завантаження браузера, задайте `PLAYWRIGHT_BROWSERS_PATH` (наприклад, `/home/node/.cache/ms-playwright`) і переконайтеся, що `/home/node` зберігається через `OPENCLAW_HOME_VOLUME` або bind mount. OpenClaw автоматично виявляє збережений Chromium у Linux. Див. [Docker](/uk/install/docker). ## Як це працює (внутрішньо) Невеликий loopback керівний сервер приймає HTTP-запити й підключається до браузерів на основі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) проходять через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери й профілі вільно змінюються під ним. ## Короткий довідник CLI Усі команди приймають `--browser-profile ` для вибору конкретного профілю та `--json` для машиночитного виводу. ```bash openclaw browser status openclaw browser start openclaw browser start --headless # one-shot local managed headless launch openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser tabs openclaw browser tab # shortcut for current tab openclaw browser tab new openclaw browser tab select 2 openclaw browser tab close 2 openclaw browser open https://example.com openclaw browser focus abcd1234 openclaw browser close abcd1234 ``` ```bash openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref 12 # or --ref e12 openclaw browser screenshot --labels openclaw browser snapshot openclaw browser snapshot --format aria --limit 200 openclaw browser snapshot --interactive --compact --depth 6 openclaw browser snapshot --efficient openclaw browser snapshot --labels openclaw browser snapshot --urls openclaw browser snapshot --selector "#main" --interactive openclaw browser snapshot --frame "iframe#main" --interactive openclaw browser console --level error openclaw browser errors --clear openclaw browser requests --filter api --clear openclaw browser pdf openclaw browser responsebody "**/api" --max-chars 5000 ``` ```bash openclaw browser navigate https://example.com openclaw browser resize 1280 720 openclaw browser click 12 --double # or e12 for role refs openclaw browser click-coords 120 340 # viewport coordinates openclaw browser type 23 "hello" --submit openclaw browser press Enter openclaw browser hover 44 openclaw browser scrollintoview e12 openclaw browser drag 10 11 openclaw browser select 9 OptionA OptionB openclaw browser download e12 report.pdf openclaw browser waitfordownload report.pdf openclaw browser upload /tmp/openclaw/uploads/file.pdf openclaw browser upload media://inbound/file.pdf openclaw browser fill --fields '[{"ref":"1","type":"text","value":"Ada"}]' openclaw browser dialog --accept openclaw browser dialog --dismiss --dialog-id d1 openclaw browser wait --text "Done" openclaw browser wait "#main" --url "**/dash" --load networkidle --fn "window.ready===true" openclaw browser evaluate --fn '(el) => el.textContent' --ref 7 openclaw browser evaluate --fn 'const title = document.title; return title;' openclaw browser evaluate --timeout-ms 30000 --fn 'async () => { await window.ready; return true; }' openclaw browser highlight e12 openclaw browser trace start openclaw browser trace stop ``` ```bash openclaw browser cookies openclaw browser cookies set session abc123 --url "https://example.com" openclaw browser cookies clear openclaw browser storage local get openclaw browser storage local set theme dark openclaw browser storage session clear openclaw browser set offline on openclaw browser set headers --headers-json '{"X-Debug":"1"}' openclaw browser set credentials user pass # --clear to remove openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" openclaw browser set media dark openclaw browser set timezone America/New_York openclaw browser set locale en-US openclaw browser set device "iPhone 14" ``` Примітки: - `upload` і `dialog` — це виклики **arming**; запускайте їх перед кліком/натисканням, яке відкриває chooser/dialog. Якщо дія відкриває модальне вікно, відповідь дії містить `blockedByDialog` і `browserState.dialogs.pending`; передайте цей `dialogId`, щоб відповісти напряму. Діалоги, оброблені поза OpenClaw, з’являються в `browserState.dialogs.recent`. - `click`/`type`/тощо потребують `ref` зі `snapshot` (числовий `12`, role ref `e12` або actionable ARIA ref `ax12`). CSS-селектори навмисно не підтримуються для дій. Використовуйте `click-coords`, коли видима позиція у viewport є єдиною надійною ціллю. - Шляхи завантаження й трасування обмежені тимчасовими коренями OpenClaw: `/tmp/openclaw{,/downloads}` (fallback: `${os.tmpdir()}/openclaw/...`). - `upload` приймає файли з тимчасового кореня завантажень OpenClaw і керовані OpenClaw inbound media. На керовані inbound media можна посилатися як `media://inbound/`, sandbox-relative `media/inbound/` або resolved path усередині керованого каталогу inbound media. Вкладені media refs, traversal, symlinks, hardlinks і довільні локальні шляхи все ще відхиляються. - `upload` також може встановлювати файлові input-и напряму через `--input-ref` або `--element`. Стабільні id вкладок і мітки переживають заміну сирого target Chromium, коли OpenClaw може довести вкладку-заміну, наприклад та сама URL-адреса або одна стара вкладка стає однією новою вкладкою після надсилання форми. Сирі target ids усе ще несталі; у скриптах надавайте перевагу `suggestedTargetId` з `tabs`. Коротко про прапорці snapshot: - `--format ai` (типово з Playwright): AI-знімок із числовими refs (`aria-ref=""`). - `--format aria`: дерево доступності з refs `axN`. Коли Playwright доступний, OpenClaw прив’язує refs із backend DOM ids до активної сторінки, щоб подальші дії могли їх використовувати; інакше вважайте вивід призначеним лише для інспекції. - `--efficient` (або `--mode efficient`): компактний пресет знімка ролей. Установіть `browser.snapshotDefaults.mode: "efficient"`, щоб зробити це типовим режимом (див. [конфігурацію Gateway](/uk/gateway/configuration-reference#browser)). - `--interactive`, `--compact`, `--depth`, `--selector` примусово вмикають знімок ролей із refs `ref=e12`. `--frame "