Перейти до основного вмісту

Documentation Index

Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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

​
Керівний API (необов’язково)

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

​
Контракт помилок /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): дія не підтримується для профілів наявних сеансів.
Інші помилки під час виконання все ще можуть повертати { "error": "<message>" } без поля code.

​
Вимога Playwright

Деякі функції (навігація/дія/знімок AI/рольовий знімок, знімки елементів екрана, PDF) потребують Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають чітку помилку 501. Що все ще працює без Playwright:
  • Знімки ARIA
  • Рольові знімки доступності (--interactive, --compact, --depth, --efficient), коли доступний CDP WebSocket для вкладки. Це резервний варіант для інспекції та виявлення посилань; Playwright залишається основним рушієм дій.
  • Знімки сторінок екрана для керованого браузера openclaw, коли доступний CDP WebSocket для вкладки
  • Знімки сторінок екрана для профілів existing-session / Chrome MCP
  • Знімки екрана на основі посилань existing-session (--ref) з виводу знімка
Що все ще потребує Playwright:
  • navigate
  • act
  • Знімки AI, які залежать від нативного формату знімків AI у Playwright
  • Знімки елементів екрана за CSS-селектором (--element)
  • повний експорт браузера в PDF
Знімки елементів екрана також відхиляють --full-page; маршрут повертає fullPage is not supported for element screenshots. Якщо бачите Playwright is not available in this gateway build, у запакованому Gateway відсутня основна залежність середовища виконання браузера. Перевстановіть або оновіть OpenClaw, а потім перезапустіть Gateway. Для Docker також установіть бінарні файли браузера Chromium, як показано нижче.

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

Якщо ваш Gateway працює в Docker, уникайте npx playwright (конфлікти перевизначень npm). Для власних образів вбудуйте Chromium в образ: 
OPENCLAW_INSTALL_BROWSER=1 ./scripts/docker/setup.sh
Для наявного образу натомість установіть через вбудований 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. OpenClaw автоматично виявляє збережений Chromium у Linux. Див. Docker.

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

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

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

Усі команди приймають --browser-profile <name> для вибору конкретного профілю та --json для машинозчитуваного виводу. 
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

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

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 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
Примітки:
  • upload і dialog є викликами підготовки; запускайте їх перед клацанням/натисканням, що спричиняє вибір файлу/діалог.
  • click/type/тощо потребують ref зі snapshot (числовий 12, рольове посилання e12 або дієве ARIA-посилання ax12). CSS-селектори навмисно не підтримуються для дій. Використовуйте click-coords, коли видима позиція у viewport є єдиною надійною ціллю.
  • Шляхи завантаження, трасування та вивантаження обмежені тимчасовими коренями OpenClaw: /tmp/openclaw{,/downloads,/uploads} (резервний варіант: ${os.tmpdir()}/openclaw/...).
  • upload також може напряму задавати файлові поля введення через --input-ref або --element.
Стабільні ідентифікатори та мітки вкладок переживають заміну необробленої цілі Chromium, коли OpenClaw може довести вкладку-заміну, наприклад ту саму URL-адресу або перетворення однієї старої вкладки на одну нову вкладку після надсилання форми. Необроблені ідентифікатори цілей усе ще мінливі; у сценаріях надавайте перевагу suggestedTargetId із tabs. Короткий огляд прапорців знімків:
  • --format ai (типово з Playwright): знімок AI з числовими посиланнями (aria-ref="<n>").
  • --format aria: дерево доступності з посиланнями axN. Коли Playwright доступний, OpenClaw прив’язує посилання з backend DOM ids до живої сторінки, щоб наступні дії могли їх використовувати; інакше вважайте вивід лише інспекційним.
  • --efficient (або --mode efficient): компактний пресет рольового знімка. Задайте browser.snapshotDefaults.mode: "efficient", щоб зробити це типовим значенням (див. конфігурацію Gateway).
  • --interactive, --compact, --depth, --selector примусово вмикають рольовий знімок із посиланнями ref=e12. --frame "<iframe>" обмежує рольові знімки iframe.
  • --labels додає знімок екрана лише viewport з накладеними мітками посилань (друкує MEDIA:<path>).
  • --urls додає виявлені призначення посилань до знімків AI.

​
Знімки та посилання

OpenClaw підтримує два стилі “знімків”:
  • Знімок AI (числові посилання): openclaw browser snapshot (типово; --format ai)
    • Вивід: текстовий знімок, який містить числові посилання.
    • Дії: openclaw browser click 12, openclaw browser type 23 "hello".
    • Внутрішньо посилання розв’язується через aria-ref Playwright.
  • Рольовий знімок (рольові посилання на кшталт e12): openclaw browser snapshot --interactive (або --compact, --depth, --selector, --frame)
    • Вивід: рольовий список/дерево з [ref=e12] (і необов’язковим [nth=1]).
    • Дії: openclaw browser click e12, openclaw browser highlight e12.
    • Внутрішньо посилання розв’язується через getByRole(...) (плюс nth() для дублікатів).
    • Додайте --labels, щоб включити знімок екрана viewport з накладеними мітками e12.
    • Додайте --urls, коли текст посилання неоднозначний і агенту потрібні конкретні цілі навігації.
  • Знімок ARIA (ARIA-посилання, як-от ax12): openclaw browser snapshot --format aria
    • Вивід: дерево доступності як структуровані вузли.
    • Дії: openclaw browser click ax12 працює, коли шлях знімка може прив’язати посилання через DOM-ідентифікатори бекенду Playwright і Chrome.
  • Якщо Playwright недоступний, знімки ARIA все одно можуть бути корисними для інспектування, але посилання можуть бути непридатними для дій. Повторно зробіть знімок із --format ai або --interactive, коли потрібні посилання для дій.
  • Docker-доказ для резервного шляху raw-CDP: pnpm test:docker:browser-cdp-snapshot запускає Chromium із CDP, виконує browser doctor --deep і перевіряє, що рольові знімки містять URL посилань, клікабельні елементи, підвищені курсором, і метадані iframe.
Поведінка посилань:
  • Посилання не стабільні між навігаціями; якщо щось не спрацьовує, повторно запустіть snapshot і використайте свіже посилання.
  • /act повертає поточний raw targetId після заміни, спричиненої дією, коли може довести вкладку заміни. Продовжуйте використовувати стабільні ідентифікатори/мітки вкладок для наступних команд.
  • Якщо рольовий знімок було зроблено з --frame, рольові посилання обмежені цим iframe до наступного рольового знімка.
  • Невідомі або застарілі посилання axN швидко завершуються помилкою замість переходу до селектора Playwright aria-ref. Коли це трапляється, зробіть свіжий знімок на тій самій вкладці.

​
Розширені можливості очікування

Можна чекати не лише на час/текст:
  • Очікувати URL (глоби підтримуються 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> (віддавайте перевагу рольовим посиланням в інтерактивному режимі)
  3. Якщо все ще не вдається: openclaw browser highlight <ref>, щоб побачити, на що націлюється Playwright
  4. Якщо сторінка поводиться дивно:
    • openclaw browser errors --clear
    • openclaw browser requests --filter api --clear
  5. Для глибокого налагодження: запишіть трасу:
    • 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
Рольові знімки в JSON містять refs плюс невеликий блок stats (lines/chars/refs/interactive), щоб інструменти могли оцінювати розмір і щільність payload.

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

Вони корисні для робочих процесів на кшталт “зробити так, щоб сайт поводився як X”:
  • Cookies: cookies, cookies set, cookies clear
  • Сховище: 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)
  • Media: set media dark|light|no-preference|none
  • Часовий пояс / локаль: set timezone ..., set locale ...
  • Пристрій / viewport:
    • set device "iPhone 14" (пресети пристроїв Playwright)
    • set viewport 1280 720

​
Безпека та приватність

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

​
Пов’язане