diff --git a/docs/uk/tools/browser-control.md b/docs/uk/tools/browser-control.md index adfdcc91e..913711902 100644 --- a/docs/uk/tools/browser-control.md +++ b/docs/uk/tools/browser-control.md @@ -1,22 +1,22 @@ --- read_when: - - Створення сценаріїв або налагодження браузера агента через локальний API керування - - Шукаєте довідник CLI `openclaw browser` - - Додавання власної автоматизації браузера за допомогою знімків і посилань -summary: API керування браузером OpenClaw, довідник CLI та дії сценаріїв + - Написання сценаріїв або налагодження браузера агента через локальний API керування + - Шукаєте довідку CLI `openclaw browser` + - Додавання власної автоматизації браузера зі знімками та посиланнями ref +summary: API керування браузером OpenClaw, довідка CLI та дії сценаріїв title: API керування браузером x-i18n: - generated_at: "2026-04-25T06:34:51Z" + generated_at: "2026-04-25T08:55:03Z" model: gpt-5.4 provider: openai - source_hash: e9d18da48dfb6cf127fabbaa056411162640ab62e15690617138af3c23ee19c9 + source_hash: 179d2422fa5db219a81486ad6e0d34a79cfb08a3f827c69cba8f6578a00fb2c0 source_path: tools/browser-control.md workflow: 15 --- Для налаштування, конфігурації та усунення несправностей див. [Browser](/uk/tools/browser). Ця сторінка є довідником для локального HTTP API керування, CLI `openclaw browser` -та шаблонів сценаріїв (знімки, посилання, очікування, потоки налагодження). +та шаблонів написання сценаріїв (знімки, ref, очікування, потоки налагодження). ## API керування (необов’язково) @@ -37,19 +37,19 @@ x-i18n: Усі кінцеві точки приймають `?profile=`. -Якщо налаштовано автентифікацію Gateway зі спільним секретом, HTTP-маршрути браузера також вимагають автентифікації: +Якщо налаштовано автентифікацію gateway зі спільним секретом, HTTP-маршрути браузера також потребують автентифікації: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей окремий loopback API браузера **не** використовує заголовки trusted-proxy або заголовки ідентичності Tailscale Serve. +- Цей окремий loopback API браузера **не** використовує заголовки ідентифікації trusted-proxy або Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback. ### Контракт помилок `/act` -`POST /act` використовує структуровану відповідь про помилку для перевірки на рівні маршруту та збоїв політики: +`POST /act` використовує структуровану відповідь про помилку для валідації на рівні маршруту та збоїв політик: ```json { "error": "", "code": "ACT_*" } @@ -57,28 +57,28 @@ x-i18n: Поточні значення `code`: -- `ACT_KIND_REQUIRED` (HTTP 400): відсутній `kind` або його не розпізнано. -- `ACT_INVALID_REQUEST` (HTTP 400): не вдалося нормалізувати або перевірити корисне навантаження дії. +- `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнається. +- `ACT_INVALID_REQUEST` (HTTP 400): корисне навантаження дії не пройшло нормалізацію або валідацію. - `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` було використано з непідтримуваним типом дії. - `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено конфігурацією. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з ціллю запиту. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з цільовим об’єктом запиту. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session. -Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без поля `code`. +Інші збої виконання все ще можуть повертати `{ "error": "" }` без поля `code`. ### Вимога Playwright -Деякі можливості (`navigate`/`act`/AI snapshot/role snapshot, скриншоти елементів, +Деякі можливості (navigate/act/AI snapshot/role snapshot, скриншоти елементів, PDF) потребують Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають зрозумілу помилку 501. Що все ще працює без Playwright: -- Знімки ARIA -- Скриншоти сторінки для керованого браузера `openclaw`, коли доступний - WebSocket CDP для окремої вкладки +- ARIA snapshots +- Скриншоти сторінки для керованого браузера `openclaw`, коли доступний WebSocket + CDP для окремої вкладки - Скриншоти сторінки для профілів `existing-session` / Chrome MCP -- Скриншоти за посиланням для `existing-session` (`--ref`) з виводу snapshot +- Скриншоти на основі ref для `existing-session` (`--ref`) із виводу snapshot Що все ще потребує Playwright: @@ -86,37 +86,37 @@ PDF) потребують Playwright. Якщо Playwright не встановл - `act` - AI snapshots / role snapshots - Скриншоти елементів за CSS-селекторами (`--element`) -- Експорт повного PDF браузера +- Повний експорт PDF браузера Скриншоти елементів також відхиляють `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. Якщо ви бачите `Playwright is not available in this gateway build`, відновіть -залежності середовища виконання комплектного browser Plugin, щоб було встановлено -`playwright-core`, а потім перезапустіть Gateway. Для пакетних установок виконайте `openclaw doctor --fix`. +залежності середовища виконання вбудованого браузерного Plugin, щоб було встановлено `playwright-core`, +а потім перезапустіть Gateway. Для пакетних установок виконайте `openclaw doctor --fix`. Для Docker також установіть двійкові файли браузера Chromium, як показано нижче. #### Установлення Playwright у Docker Якщо ваш Gateway працює в Docker, уникайте `npx playwright` (конфлікти перевизначення npm). -Натомість використовуйте комплектний CLI: +Натомість використовуйте вбудований CLI: ```bash docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Щоб зберігати завантаження браузера, задайте `PLAYWRIGHT_BROWSERS_PATH` (наприклад, +Щоб зберігати завантаження браузера, установіть `PLAYWRIGHT_BROWSERS_PATH` (наприклад, `/home/node/.cache/ms-playwright`) і переконайтеся, що `/home/node` зберігається через `OPENCLAW_HOME_VOLUME` або bind mount. Див. [Docker](/uk/install/docker). ## Як це працює (внутрішньо) -Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на основі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери та профілі вільно змінюються під ним. +Невеликий loopback-сервер керування приймає HTTP-запити й підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери та профілі вільно змінюються під ним. ## Короткий довідник CLI -Усі команди приймають `--browser-profile ` для націлювання на конкретний профіль і `--json` для машинозчитуваного виводу. +Усі команди приймають `--browser-profile ` для націлювання на певний профіль і `--json` для машиночитаного виводу. @@ -125,9 +125,9 @@ docker compose run --rm openclaw-cli \ ```bash openclaw browser status openclaw browser start -openclaw browser stop # також очищає емуляцію для attach-only/remote CDP +openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser tabs -openclaw browser tab # скорочення для поточної вкладки +openclaw browser tab # shortcut for current tab openclaw browser tab new openclaw browser tab select 2 openclaw browser tab close 2 @@ -143,7 +143,7 @@ openclaw browser close abcd1234 ```bash openclaw browser screenshot openclaw browser screenshot --full-page -openclaw browser screenshot --ref 12 # або --ref e12 для role refs +openclaw browser screenshot --ref 12 # or --ref e12 openclaw browser screenshot --labels openclaw browser snapshot openclaw browser snapshot --format aria --limit 200 @@ -167,8 +167,8 @@ openclaw browser responsebody "**/api" --max-chars 5000 ```bash openclaw browser navigate https://example.com openclaw browser resize 1280 720 -openclaw browser click 12 --double # або e12 для role refs -openclaw browser click-coords 120 340 # координати області перегляду +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 @@ -201,7 +201,7 @@ 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 для видалення +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 @@ -215,56 +215,66 @@ openclaw browser set device "iPhone 14" Примітки: -- `upload` і `dialog` — це виклики **підготовки**; виконайте їх перед click/press, що запускає file chooser або dialog. -- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12` або role ref `e12`). CSS-селектори навмисно не підтримуються для дій. Використовуйте `click-coords`, коли єдиною надійною ціллю є видима позиція в області перегляду. -- Шляхи для download, trace і upload обмежені тимчасовими коренями OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`). +- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед click/press, що ініціює вибір файлу/діалог. +- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12`, role ref `e12` або actionable ARIA ref `ax12`). CSS-селектори навмисно не підтримуються для дій. Використовуйте `click-coords`, коли видима позиція у viewport є єдиною надійною ціллю. +- Шляхи для download, trace і upload обмежені тимчасовими кореневими каталогами OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`). - `upload` також може напряму задавати file input через `--input-ref` або `--element`. -Коротко про прапорці snapshot: +Прапорці snapshot коротко: -- `--format ai` (типово з Playwright): AI snapshot із числовими посиланнями (`aria-ref=""`). -- `--format aria`: дерево доступності, без посилань; лише для інспекції. -- `--efficient` (або `--mode efficient`): компактний пресет role snapshot. Установіть `browser.snapshotDefaults.mode: "efficient"`, щоб зробити його типовим (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)). -- `--interactive`, `--compact`, `--depth`, `--selector` примусово використовують role snapshot із посиланнями `ref=e12`. `--frame "