Перейти до основного вмісту
Для налаштування, конфігурації та усунення несправностей див. Browser. Ця сторінка є довідником для локального HTTP API керування, CLI openclaw browser і шаблонів написання сценаріїв (знімки, refs, очікування, потоки налагодження).

​
API керування (необов’язково)

Лише для локальних інтеграцій Gateway надає невеликий loopback HTTP API:
  • Стан/запуск/зупинка: 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
  • Налагодження: 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
Усі кінцеві точки приймають ?profile=<name>. Якщо налаштовано автентифікацію Gateway зі спільним секретом, HTTP-маршрути браузера також потребують автентифікації:
  • Authorization: Bearer <gateway token>
  • x-openclaw-password: <gateway password> або HTTP Basic auth із цим паролем
Примітки:
  • Цей окремий loopback API браузера не використовує заголовки ідентифікації trusted-proxy або Tailscale Serve.
  • Якщо gateway.auth.mode має значення none або trusted-proxy, ці loopback-маршрути браузера не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback.

​
Контракт помилок /act

POST /act використовує структуровану відповідь про помилку для перевірки на рівні маршруту та збоїв політик: 
{ "error": "<message>", "code": "ACT_*" }
Поточні значення code:
  • 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_EXISTING_SESSION_UNSUPPORTED (HTTP 501): дія не підтримується для профілів existing-session.
Інші збої під час виконання все ще можуть повертати { "error": "<message>" } без поля code.

​
Вимога Playwright

Для деяких можливостей (navigate/act/AI snapshot/role snapshot, скриншоти елементів, PDF) потрібен Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають зрозумілу помилку 501. Що все ще працює без Playwright:
  • ARIA-знімки
  • Скриншоти сторінки для керованого браузера openclaw, коли доступний WebSocket CDP для окремої вкладки
  • Скриншоти сторінки для профілів existing-session / Chrome MCP
  • Скриншоти на основі refs для existing-session (--ref) із виводу snapshot
Що все ще потребує Playwright:
  • navigate
  • act
  • AI-знімки / role snapshots
  • Скриншоти елементів за CSS-селектором (--element)
  • повний експорт 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. Для Docker також встановіть двійкові файли браузера Chromium, як показано нижче.

​
Встановлення Playwright у Docker

Якщо ваш Gateway працює в Docker, уникайте npx playwright (конфлікти перевизначення npm). Натомість використовуйте вбудований CLI: 
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. Див. Docker.

​
Як це працює (внутрішньо)

Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери та профілі вільно змінюються під ним.

​
Короткий довідник CLI

Усі команди приймають --browser-profile <name> для націлювання на конкретний профіль і --json для машинозчитуваного виводу. 
openclaw browser status
openclaw browser start
openclaw browser stop            # також очищає емуляцію для attach-only/remote CDP
openclaw browser tabs
openclaw browser 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

openclaw browser screenshot
openclaw browser screenshot --full-page
openclaw browser screenshot --ref 12        # або --ref e12
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 --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

openclaw browser navigate https://example.com
openclaw browser resize 1280 720
openclaw browser click 12 --double           # або e12 для role refs
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 fill --fields '[{"ref":"1","type":"text","value":"Ada"}]'
openclaw browser dialog --accept
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 highlight e12
openclaw browser trace start
openclaw browser trace stop

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 для видалення
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 — це виклики підготовки; запускайте їх перед click/press, що викликає вибір файлу або діалог.
  • click/type/тощо потребують ref із snapshot (числовий 12 або role ref e12). CSS-селектори навмисно не підтримуються для дій.
  • Шляхи download, trace і upload обмежені тимчасовими кореневими каталогами OpenClaw: /tmp/openclaw{,/downloads,/uploads} (резервний варіант: ${os.tmpdir()}/openclaw/...).
  • upload також може напряму встановлювати file input через --input-ref або --element.
Прапорці snapshot коротко:
  • --format ai (типово з Playwright): AI-знімок із числовими refs (aria-ref="<n>").
  • --format aria: дерево доступності, без refs; лише для інспекції.
  • --efficient (або --mode efficient): компактний preset role snapshot. Установіть browser.snapshotDefaults.mode: "efficient", щоб зробити це типовим значенням (див. Конфігурація Gateway).
  • --interactive, --compact, --depth, --selector примусово вмикають role snapshot із refs ref=e12. --frame "<iframe>" обмежує role snapshots цим iframe.
  • --labels додає скриншот лише видимої області з накладеними мітками ref (виводить MEDIA:<path>).

​
Знімки та refs

OpenClaw підтримує два стилі “snapshot”:
  • AI snapshot (числові refs): openclaw browser snapshot (типово; --format ai)
    • Вивід: текстовий знімок, що містить числові refs.
    • Дії: openclaw browser click 12, openclaw browser type 23 "hello".
    • Внутрішньо ref визначається через aria-ref у Playwright.
  • Role snapshot (role refs на кшталт e12): openclaw browser snapshot --interactive (або --compact, --depth, --selector, --frame)
    • Вивід: список/дерево на основі ролей із [ref=e12] (і необов’язковим [nth=1]).
    • Дії: openclaw browser click e12, openclaw browser highlight e12.
    • Внутрішньо ref визначається через getByRole(...) (плюс nth() для дублікатів).
    • Додайте --labels, щоб включити скриншот видимої області з накладеними мітками e12.
Поведінка ref:
  • Refs не є стабільними між переходами навігації; якщо щось не спрацювало, повторно виконайте snapshot і використайте новий ref.
  • Якщо role snapshot було зроблено з --frame, role refs обмежуються цим iframe до наступного role snapshot.

​
Розширені можливості wait

Можна чекати не лише на час/текст:
  • Очікування URL (glob-маски підтримуються Playwright):
    • openclaw browser wait --url "**/dash"
  • Очікування стану завантаження:
    • openclaw browser wait --load networkidle
  • Очікування предиката JS:
    • openclaw browser wait --fn "window.ready===true"
  • Очікування, поки селектор стане видимим:
    • openclaw browser wait "#main"
Їх можна поєднувати: 
openclaw browser wait "#main" \
  --url "**/dash" \
  --load networkidle \
  --fn "window.ready===true" \
  --timeout-ms 15000

​
Потоки налагодження

Коли дія завершується помилкою (наприклад, “not visible”, “strict mode violation”, “covered”):
  1. openclaw browser snapshot --interactive
  2. Використайте click <ref> / type <ref> (віддавайте перевагу role refs в interactive mode)
  3. Якщо все одно не працює: openclaw browser highlight <ref>, щоб побачити, на що націлюється Playwright
  4. Якщо сторінка поводиться дивно:
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. Для глибокого налагодження: запишіть trace:
    • openclaw browser trace start
    • відтворіть проблему
    • openclaw browser trace stop (виводить TRACE:<path>)

​
JSON-вивід

--json призначено для сценаріїв і структурованих інструментів. Приклади: 
openclaw browser status --json
openclaw browser snapshot --interactive --json
openclaw browser requests --filter api --json
openclaw browser cookies --json
Role snapshots у JSON містять refs і невеликий блок stats (lines/chars/refs/interactive), щоб інструменти могли оцінювати розмір і щільність корисного навантаження.

​
Параметри стану та середовища

Вони корисні для сценаріїв на кшталт “змусити сайт поводитися як X”:
  • Cookies: cookies, cookies set, cookies clear
  • Storage: storage local|session get|set|clear
  • Офлайн: set offline on|off
  • Заголовки: set headers --headers-json '{"X-Debug":"1"}' (застарілий варіант set headers --json '{"X-Debug":"1"}' і далі підтримується)
  • HTTP Basic auth: set credentials user pass (або --clear)
  • Геолокація: set geo <lat> <lon> --origin "https://example.com" (або --clear)
  • Медіа: set media dark|light|no-preference|none
  • Часовий пояс / locale: set timezone ..., set locale ...
  • Пристрій / viewport:
    • set device "iPhone 14" (preset-и пристроїв Playwright)
    • set viewport 1280 720

​
Безпека та конфіденційність

  • Профіль браузера openclaw може містити сеанси з виконаним входом; ставтеся до нього як до чутливих даних.
  • browser act kind=evaluate / openclaw browser evaluate і wait --fn виконують довільний JavaScript у контексті сторінки. Prompt injection може спрямувати це. Вимкніть це за допомогою browser.evaluateEnabled=false, якщо воно вам не потрібне.
  • Щодо входу на сайти та приміток про anti-bot (X/Twitter тощо), див. Browser login + X/Twitter posting.
  • Тримайте хост Gateway/node приватним (лише loopback або лише tailnet).
  • Віддалені кінцеві точки CDP мають широкі можливості; використовуйте тунелювання та захищайте їх.
Приклад strict-mode (типово блокує приватні/внутрішні адреси призначення): 
{
  browser: {
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: false,
      hostnameAllowlist: ["*.example.com", "example.com"],
      allowedHostnames: ["localhost"], // необов’язковий точний дозвіл
    },
  },
}

​
Пов’язане