diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index 13054c84a..42754668a 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,14 +1,14 @@ --- read_when: - - Центр усунення несправностей спрямував вас сюди для глибшої діагностики + - Центр усунення несправностей направив вас сюди для глибшої діагностики - Вам потрібні стабільні розділи посібника на основі симптомів із точними командами summary: Детальний посібник з усунення несправностей для Gateway, каналів, автоматизації, Node і браузера title: Усунення несправностей x-i18n: - generated_at: "2026-04-21T07:13:40Z" + generated_at: "2026-04-22T20:50:00Z" model: gpt-5.4 provider: openai - source_hash: add7625785e3b78897c750b4785b7fe84a3d91c23c4175de750c4834272967f9 + source_hash: 6df9cfcce30542401fc3d815781e226d45bb5462580722fa5353e404eef28ee6 source_path: gateway/troubleshooting.md workflow: 15 --- @@ -16,11 +16,11 @@ x-i18n: # Усунення несправностей Gateway Ця сторінка — детальний посібник. -Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете швидкий сценарій первинної діагностики. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете швидкий сценарій діагностики. ## Послідовність команд -Спочатку виконайте це, саме в такому порядку: +Спочатку виконайте ці команди в такому порядку: ```bash openclaw status @@ -33,11 +33,11 @@ openclaw channels status --probe Очікувані ознаки справного стану: - `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. -- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/служби. -- `openclaw channels status --probe` показує живий стан транспорту для кожного акаунта і, +- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу. +- `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису та, де це підтримується, результати probe/audit, такі як `works` або `audit ok`. -## Додаткове використання Anthropic 429 потрібне для довгого контексту +## Anthropic 429: для довгого контексту потрібне додаткове використання Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -50,14 +50,14 @@ openclaw config get agents.defaults.models Зверніть увагу на таке: -- Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. -- Поточні облікові дані Anthropic не мають права на використання довгого контексту. -- Запити падають лише на довгих сесіях/запусках моделі, яким потрібен шлях 1M beta. +- Для вибраної моделі Anthropic Opus/Sonnet встановлено `params.context1m: true`. +- Поточні облікові дані Anthropic не дають права на використання довгого контексту. +- Запити не вдаються лише для довгих сесій/запусків моделі, яким потрібен beta-шлях 1M. Варіанти виправлення: 1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. -2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на ключ Anthropic API. +2. Використайте облікові дані Anthropic, які мають право на запити з довгим контекстом, або перейдіть на Anthropic API key. 3. Налаштуйте резервні моделі, щоб запуски продовжувалися, коли запити Anthropic із довгим контекстом відхиляються. Пов’язане: @@ -66,13 +66,13 @@ openclaw config get agents.defaults.models - [/reference/token-use](/uk/reference/token-use) - [/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-сумісний бекенд проходить прямі probe, але запуски агента падають +## Локальний OpenAI-compatible backend проходить прямі probe, але запуски агента не вдаються Використовуйте це, коли: - `curl ... /v1/models` працює - малі прямі виклики `/v1/chat/completions` працюють -- запуски моделі OpenClaw падають лише під час звичайних ходів агента +- запуски моделей OpenClaw не вдаються лише під час звичайних ходів агента ```bash curl http://127.0.0.1:1234/v1/models @@ -85,33 +85,31 @@ openclaw logs --follow Зверніть увагу на таке: -- прямі малі виклики успішні, але запуски OpenClaw падають лише на більших prompt -- помилки бекенда про те, що `messages[].content` очікує рядок -- збої бекенда, які з’являються лише за більших підрахунків prompt-token або повних prompt середовища виконання агента +- прямі малі виклики успішні, але запуски OpenClaw не вдаються лише на більших prompt +- backend повертає помилки про те, що `messages[].content` очікує рядок +- backend аварійно завершується лише за більшої кількості токенів у prompt або з повними prompt середовища виконання агента Поширені ознаки: -- `messages[...].content: invalid type: sequence, expected a string` → бекенд - не приймає структуровані частини вмісту Chat Completions. Виправлення: установіть +- `messages[...].content: invalid type: sequence, expected a string` → backend + відхиляє структуровані частини вмісту Chat Completions. Виправлення: установіть `models.providers..models[].compat.requiresStringContent: true`. -- прямі малі запити успішні, але запуски агента OpenClaw падають через збої - бекенда/моделі (наприклад, Gemma на деяких збірках `inferrs`) → транспорт OpenClaw, - імовірно, уже налаштований правильно; збій відбувається в бекенді через більшу форму - prompt середовища виконання агента. +- прямі малі запити успішні, але запуски агентів OpenClaw не вдаються через аварії backend/моделі + (наприклад, Gemma у деяких збірках `inferrs`) → транспорт OpenClaw, + імовірно, уже налаштований правильно; проблема в тому, що backend не справляється з більшою формою prompt середовища агента. - збої зменшуються після вимкнення інструментів, але не зникають → схеми інструментів - були частиною навантаження, але решта проблеми все одно полягає в обмеженнях моделі/сервера - вищого рівня або в багу бекенда. + були частиною навантаження, але решта проблеми все ще пов’язана з upstream-обмеженнями моделі/сервера або помилкою backend. Варіанти виправлення: -1. Установіть `compat.requiresStringContent: true` для бекендів Chat Completions, що підтримують лише рядки. -2. Установіть `compat.supportsTools: false` для моделей/бекендів, які не можуть - надійно обробляти поверхню схем інструментів OpenClaw. -3. Де можливо, зменште навантаження prompt: менший bootstrap робочого простору, коротша - історія сесії, легша локальна модель або бекенд із кращою підтримкою довгого контексту. -4. Якщо малі прямі запити й надалі проходять, а ходи агента OpenClaw все одно падають - усередині бекенда, вважайте це обмеженням сервера/моделі вищого рівня та створіть - там repro з прийнятою формою payload. +1. Установіть `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядковий вміст. +2. Установіть `compat.supportsTools: false` для моделей/backend, які не можуть надійно обробляти + поверхню схем інструментів OpenClaw. +3. Де можливо, зменште навантаження від prompt: менший bootstrap робочого простору, коротша + історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту. +4. Якщо прямі малі запити й далі успішні, а ходи агента OpenClaw все одно аварійно завершуються + всередині backend, вважайте це обмеженням upstream-сервера/моделі й подайте туди + відтворюваний приклад із прийнятною формою payload. Пов’язане: @@ -121,7 +119,7 @@ openclaw logs --follow ## Немає відповідей -Якщо канали працюють, але відповіді немає, перш ніж щось перепідключати, перевірте маршрутизацію та політику. +Якщо канали працюють, але відповідей немає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. ```bash openclaw status @@ -133,14 +131,14 @@ openclaw logs --follow Зверніть увагу на таке: -- Очікує підтвердження pairing для відправників у DM. -- Обмеження згадування в групі (`requireMention`, `mentionPatterns`). +- Для відправників у DM pairing очікує підтвердження. +- Обмеження згадування для груп (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. Поширені ознаки: -- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадки. -- `pairing request` → відправника потрібно схвалити. +- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадування. +- `pairing request` → відправнику потрібне схвалення. - `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. Пов’язане: @@ -149,7 +147,7 @@ openclaw logs --follow - [/channels/pairing](/uk/channels/pairing) - [/channels/groups](/uk/channels/groups) -## Підключення dashboard/control UI +## Підключення UI dashboard/control Коли dashboard/control UI не підключається, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. @@ -163,48 +161,48 @@ openclaw gateway status --json Зверніть увагу на таке: -- Правильний URL probe і URL dashboard. -- Невідповідність режиму автентифікації/токена між клієнтом і Gateway. +- Правильний probe URL і URL dashboard. +- Невідповідність режиму автентифікації/токена між клієнтом і gateway. - Використання HTTP там, де потрібна ідентичність пристрою. Поширені ознаки: - `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. -- `origin not allowed` → браузерний `Origin` відсутній у `gateway.controlUi.allowedOrigins` - (або ви підключаєтеся з браузерного origin не з loopback без явного +- `origin not allowed` → `Origin` браузера не входить до `gateway.controlUi.allowedOrigins` + (або ви підключаєтеся з browser origin не на loopback без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). + автентифікацію пристрою на основі challenge (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний - payload (або payload із застарілою часовою міткою) для поточного handshake. -- `AUTH_TOKEN_MISMATCH` із `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. -- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений із paired - токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` натомість зберігають - свій запитаний набір scope. -- Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: спочатку явний спільний - token/password, потім явний `deviceToken`, потім збережений токен пристрою, + payload (або використав застарілу часову позначку) для поточного handshake. +- `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений із прив’язаним + токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` зберігають + запитаний ними набір scope. +- Поза цим шляхом повторної спроби пріоритет автентифікації connect такий: явний спільний + token/password спочатку, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. -- На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як лімітер зафіксує помилку. Тому дві неправильні +- У шляху async Tailscale Serve Control UI невдалі спроби для одного й того самого + `{scope, ip}` серіалізуються до того, як limiter зафіксує збій. Тому дві хибні одночасні повторні спроби від того самого клієнта можуть показати `retry later` у другій спробі замість двох звичайних невідповідностей. -- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin - → повторні помилки від того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. -- повторюваний `unauthorized` після цієї повторної спроби → дрейф shared token/device token; оновіть конфігурацію токена та за потреби повторно схваліть/перевипустіть токен пристрою. +- `too many failed authentication attempts (retry later)` від loopback-клієнта з browser origin + → повторні збої з того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. +- повторюване `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та повторно схваліть/перевипустіть токен пристрою за потреби. - `gateway connect failed:` → неправильна ціль host/port/url. -### Швидка мапа детальних кодів автентифікації +### Коротка карта кодів деталей автентифікації -Використовуйте `error.details.code` із невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: -| Detail code | Значення | Рекомендована дія | +| Код деталей | Значення | Рекомендована дія | | ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний токен. | Вставте/установіть токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Спільний токен не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явним `deviceToken` / `scopes` зберігають запитаний набір scope. Якщо помилка лишається, виконайте [контрольний список відновлення після дрейфу токена](/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або був відкликаний. | Перевипустіть/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/cli/devices), а потім підключіться знову. | -| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` для `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть запит, що очікує розгляду: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/role використовують той самий потік після того, як ви перевірите запитаний доступ. | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий спільний token. | Вставте/установіть token у клієнті й повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | +| `AUTH_TOKEN_MISMATCH` | Спільний token не збігся з токеном автентифікації gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явними `deviceToken` / `scopes` зберігають запитані scope. Якщо збій повторюється, виконайте [контрольний список відновлення розсинхронізації токенів](/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або відкликаний. | Перевипустіть/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/cli/devices), а потім підключіться знову. | +| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason`: `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Підвищення scope/ролей використовує той самий процес після перевірки запитаного доступу. | -Перевірка міграції автентифікації пристрою v2: +Перевірка міграції device auth v2: ```bash openclaw --version @@ -212,16 +210,16 @@ openclaw doctor openclaw gateway status ``` -Якщо журнали показують помилки nonce/signature, оновіть клієнт, що підключається, і переконайтеся, що він: +Якщо журнали показують помилки nonce/signature, оновіть клієнт, який підключається, і переконайтеся, що він: 1. чекає на `connect.challenge` 2. підписує payload, прив’язаний до challenge -3. надсилає `connect.params.device.nonce` із тим самим nonce challenge +3. надсилає `connect.params.device.nonce` з тим самим nonce challenge -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляється: +Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано заборонено: -- сесії токенів paired-device можуть керувати лише **власним** пристроєм, якщо - виклик не має також `operator.admin` +- сесії з токеном прив’язаного пристрою можуть керувати лише **власним** пристроєм, якщо + виклик також не має `operator.admin` - `openclaw devices rotate --scope ...` може запитувати лише ті operator scope, які сесія виклику вже має @@ -233,32 +231,32 @@ openclaw gateway status - [/gateway/remote](/uk/gateway/remote) - [/cli/devices](/cli/devices) -## Служба Gateway не запущена +## Сервіс Gateway не запущений -Використовуйте це, коли службу встановлено, але процес не утримується в робочому стані. +Використовуйте це, коли сервіс установлено, але процес не залишається запущеним. ```bash openclaw gateway status openclaw status openclaw logs --follow openclaw doctor -openclaw gateway status --deep # також сканувати системні служби +openclaw gateway status --deep # also scan system-level services ``` Зверніть увагу на таке: - `Runtime: stopped` із підказками щодо завершення. -- Невідповідність конфігурації служби (`Config (cli)` проти `Config (service)`). -- Конфлікти портів/слухачів. +- Невідповідність конфігурації сервісу (`Config (cli)` проти `Config (service)`). +- Конфлікти порту/слухача. - Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. -- Підказки з очищення `Other gateway-like services detected (best effort)`. +- Підказки очищення `Other gateway-like services detected (best effort)`. Поширені ознаки: -- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим Gateway не ввімкнено, або файл конфігурації було перезаписано/пошкоджено і він втратив `gateway.mode`. Виправлення: установіть `gateway.mode="local"` у своїй конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації — `~/.openclaw/openclaw.json`. +- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим gateway не ввімкнено, або файл конфігурації було пошкоджено і він втратив `gateway.mode`. Виправлення: установіть `gateway.mode="local"` у своїй конфігурації або повторно виконайте `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікувану конфігурацію локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до конфігурації: `~/.openclaw/openclaw.json`. - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway (token/password або trusted-proxy, якщо налаштовано). - `another gateway instance is already listening` / `EADDRINUSE` → конфлікт порту. -- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні модулі launchd/systemd/schtasks. У більшості налаштувань на одній машині має бути один Gateway; якщо вам справді потрібно більше одного, ізолюйте порти + конфігурацію/стан/робочий простір. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks unit. У більшості конфігурацій на одну машину має бути один gateway; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). Пов’язане: @@ -282,17 +280,17 @@ openclaw doctor - `Config auto-restored from last-known-good` - `gateway: invalid config was restored from last-known-good backup` - `config reload restored last-known-good config after invalid-config` -- Файл із часовою міткою `openclaw.json.clobbered.*` поруч з активною конфігурацією -- Системна подія головного агента, що починається з `Config recovery warning` +- Файл `openclaw.json.clobbered.*` з часовою позначкою поруч з активною конфігурацією +- Системну подію головного агента, що починається з `Config recovery warning` Що сталося: - Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження. - OpenClaw зберіг відхилений payload як `.clobbered.*`. -- Активну конфігурацію було відновлено з останньої перевіреної останньої відомої справної копії. -- На наступному ході головного агента з’явиться попередження не переписувати відхилену конфігурацію всліпу. +- Активну конфігурацію було відновлено з останньої валідованої останньої відомої справної копії. +- Наступний хід головного агента отримує попередження не переписувати сліпо відхилену конфігурацію. -Перевірка і виправлення: +Перевірка й виправлення: ```bash CONFIG="$(openclaw config file)" @@ -304,8 +302,8 @@ openclaw doctor Поширені ознаки: -- існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або читання під час запуску. -- існує `.rejected.*` → запис конфігурації, яким керував OpenClaw, не пройшов перевірки схеми або перевірки clobber перед підтвердженням. +- Існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або зчитування під час запуску. +- Існує `.rejected.*` → запис конфігурації, виконаний OpenClaw, не пройшов перевірки схеми або цілісності перед commit. - `Config write rejected:` → запис намагався прибрати обов’язкову структуру, різко зменшити файл або зберегти невалідну конфігурацію. - `Config last-known-good promotion skipped` → кандидат містив замасковані placeholder секретів, наприклад `***`. @@ -325,7 +323,7 @@ openclaw doctor ## Попередження probe Gateway -Використовуйте це, коли `openclaw gateway probe` щось досягає, але все одно виводить блок попереджень. +Використовуйте це, коли `openclaw gateway probe` до чогось доходить, але все одно виводить блок попередження. ```bash openclaw gateway probe @@ -336,15 +334,15 @@ openclaw gateway probe --ssh user@gateway-host Зверніть увагу на таке: - `warnings[].code` і `primaryTargetId` у виводі JSON. -- Чи стосується попередження SSH fallback, кількох Gateway, відсутніх scope або нерозв’язаних посилань auth. +- Чи стосується попередження SSH fallback, кількох gateway, відсутніх scope або нерозв’язаних auth ref. Поширені ознаки: -- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не спрацювало, але команда все одно спробувала прямі налаштовані/loopback цілі. -- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисну конфігурацію з кількома Gateway або застарілі/дубльовані слухачі. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежено scope; виконайте pairing ідентичності пристрою або використайте облікові дані з `operator.read`. -- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним доступом оператора. -- нерозв’язане попередження SecretRef у тексті `gateway.auth.*` / `gateway.remote.*` → матеріал автентифікації був недоступний у цьому шляху команди для цілі, що не вдалася. +- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback-цілі. +- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисну конфігурацію з кількома gateway або застарілі/дубльовані listener. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але деталізований RPC обмежено scope; прив’яжіть ідентичність пристрою або використайте облікові дані з `operator.read`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним доступом оператора. +- нерозв’язане попередження SecretRef для `gateway.auth.*` / `gateway.remote.*` → auth-матеріал був недоступний у цьому шляху команди для цілі, що завершилась невдачею. Пов’язане: @@ -354,7 +352,7 @@ openclaw gateway probe --ssh user@gateway-host ## Канал підключений, але повідомлення не проходять -Якщо стан каналу показує підключення, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. ```bash openclaw channels status --probe @@ -366,13 +364,13 @@ openclaw config get channels Зверніть увагу на таке: -- Політика DM (`pairing`, `allowlist`, `open`, `disabled`). -- Груповий allowlist і вимоги до згадувань. +- Політику DM (`pairing`, `allowlist`, `open`, `disabled`). +- Allowlist групи та вимоги до згадувань. - Відсутні дозволи/scopes API каналу. Поширені ознаки: -- `mention required` → повідомлення ігнорується через політику згадувань у групі. +- `mention required` → повідомлення ігнорується політикою згадування в групі. - `pairing` / сліди очікування схвалення → відправника не схвалено. - `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема з автентифікацією/дозволами каналу. @@ -385,7 +383,7 @@ openclaw config get channels ## Доставка Cron і Heartbeat -Якщо Cron або Heartbeat не запустився чи не доставився, спочатку перевірте стан планувальника, а потім ціль доставки. +Якщо Cron або Heartbeat не запустилися чи не доставили результат, спочатку перевірте стан scheduler, а потім ціль доставки. ```bash openclaw cron status @@ -397,19 +395,19 @@ openclaw logs --follow Зверніть увагу на таке: -- Cron увімкнено і є наступне пробудження. -- Статус історії запусків завдання (`ok`, `skipped`, `error`). +- Cron увімкнено, і присутнє наступне пробудження. +- Статус історії виконання завдань (`ok`, `skipped`, `error`). - Причини пропуску Heartbeat (`quiet-hours`, `requests-in-flight`, `alerts-disabled`, `empty-heartbeat-file`, `no-tasks-due`). Поширені ознаки: - `cron: scheduler disabled; jobs will not run automatically` → Cron вимкнено. -- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/журналів/середовища виконання. +- `cron: timer tick failed` → збій тіку scheduler; перевірте помилки файлів/журналів/середовища виконання. - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. -- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки markdown, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися на цьому тіку. -- `heartbeat: unknown accountId` → недійсний id акаунта для цілі доставки Heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначилась як пункт призначення в стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) має значення `block`. +- `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / markdown-заголовки, тому OpenClaw пропускає виклик моделі. +- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися під час цього тіку. +- `heartbeat: unknown accountId` → недійсний account id для цілі доставки Heartbeat. +- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat була визначена як пункт призначення стилю DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для конкретного агента) встановлено в `block`. Пов’язане: @@ -417,9 +415,9 @@ openclaw logs --follow - [/automation/cron-jobs](/uk/automation/cron-jobs) - [/gateway/heartbeat](/uk/gateway/heartbeat) -## Збій інструмента paired Node +## Збій інструмента прив’язаного Node -Якщо Node paired, але інструменти не працюють, ізолюйте стан переднього плану, дозволів і схвалення. +Якщо Node прив’язано, але інструменти не працюють, ізолюйте стан foreground, дозволів і схвалення. ```bash openclaw nodes status @@ -432,14 +430,14 @@ openclaw status Зверніть увагу на таке: - Node онлайн з очікуваними можливостями. -- Дозволи ОС для камери/мікрофона/геолокації/екрана. -- Стан схвалень exec і allowlist. +- Надані дозволи ОС для камери/мікрофона/геолокації/екрана. +- Стан схвалення exec і allowlist. Поширені ознаки: - `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → бракує дозволу ОС. -- `SYSTEM_RUN_DENIED: approval required` → схвалення exec очікує. +- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. - `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано allowlist. Пов’язане: @@ -448,9 +446,9 @@ openclaw status - [/nodes/index](/uk/nodes/index) - [/tools/exec-approvals](/uk/tools/exec-approvals) -## Збій інструмента браузера +## Збій browser tool -Використовуйте це, коли дії інструмента браузера не вдаються, хоча сам Gateway справний. +Використовуйте це, коли дії browser tool не вдаються, хоча сам gateway справний. ```bash openclaw browser status @@ -463,30 +461,30 @@ openclaw doctor Зверніть увагу на таке: - Чи встановлено `plugins.allow` і чи містить він `browser`. -- Чинний шлях до виконуваного файла браузера. +- Валідний шлях до виконуваного файла браузера. - Досяжність профілю CDP. -- Доступність локального Chrome для профілів `existing-session` / `user`. +- Наявність локального Chrome для профілів `existing-session` / `user`. Поширені ознаки: -- `unknown command "browser"` або `unknown command 'browser'` → вбудований Plugin браузера виключено через `plugins.allow`. -- інструмент браузера відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажувався. -- `Failed to start Chrome CDP on port` → процес браузера не вдалося запустити. +- `unknown command "browser"` або `unknown command 'browser'` → вбудований browser Plugin виключено через `plugins.allow`. +- browser tool відсутній / недоступний, хоча `browser.enabled=true` → `plugins.allow` виключає `browser`, тому Plugin ніколи не завантажився. +- `Failed to start Chrome CDP on port` → не вдалося запустити процес браузера. - `browser.executablePath not found` → налаштований шлях недійсний. -- `browser.cdpUrl must be http(s) or ws(s)` → налаштований URL CDP використовує непідтримувану схему, таку як `file:` або `ftp:`. -- `browser.cdpUrl has invalid port` → налаштований URL CDP має некоректний або неприпустимий порт. -- `Could not find DevToolsActivePort for chrome` → наявна сесія Chrome MCP `existing-session` ще не змогла приєднатися до вибраного каталогу даних браузера. Відкрийте сторінку inspect браузера, увімкніть віддалене налагодження, залиште браузер відкритим, схваліть перший запит на приєднання, а потім повторіть спробу. Якщо стан входу не потрібен, надайте перевагу керованому профілю `openclaw`. -- `No Chrome tabs found for profile="user"` → профіль приєднання Chrome MCP не має відкритих локальних вкладок Chrome. -- `Remote CDP for profile "" is not reachable` → налаштована віддалена кінцева точка CDP недосяжна з хоста Gateway. -- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише для приєднання не має досяжної цілі, або HTTP endpoint відповів, але WebSocket CDP усе одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → у поточному встановленні Gateway немає повного пакета Playwright; ARIA-знімки й базові знімки сторінки все ще можуть працювати, але навігація, AI-знімки, знімки елементів за CSS-селекторами й експорт PDF залишаються недоступними. +- `browser.cdpUrl must be http(s) or ws(s)` → налаштований CDP URL використовує непідтримувану схему, таку як `file:` або `ftp:`. +- `browser.cdpUrl has invalid port` → налаштований CDP URL має помилковий або неприпустимий порт. +- `Could not find DevToolsActivePort for chrome` → Chrome MCP existing-session ще не зміг під’єднатися до вибраного каталогу даних браузера. Відкрийте сторінку inspect браузера, увімкніть remote debugging, тримайте браузер відкритим, схваліть перший запит на підключення, а потім повторіть спробу. Якщо стан входу не потрібен, віддайте перевагу керованому профілю `openclaw`. +- `No Chrome tabs found for profile="user"` → профіль підключення Chrome MCP не має відкритих локальних вкладок Chrome. +- `Remote CDP for profile "" is not reachable` → налаштований віддалений endpoint CDP недосяжний із хоста gateway. +- `Browser attachOnly is enabled ... not reachable` або `Browser attachOnly is enabled and CDP websocket ... is not reachable` → профіль лише з attach не має досяжної цілі, або HTTP endpoint відповів, але CDP WebSocket все одно не вдалося відкрити. +- `Playwright is not available in this gateway build; '' is unsupported.` → у поточній інсталяції gateway бракує вбудованої залежності середовища виконання `playwright-core` для browser Plugin; виконайте `openclaw doctor --fix`, потім перезапустіть gateway. Знімки ARIA та базові знімки сторінок усе ще можуть працювати, але навігація, AI snapshots, знімки елементів за CSS-селекторами та експорт PDF залишаться недоступними. - `fullPage is not supported for element screenshots` → запит на знімок екрана поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` мають використовувати захоплення сторінки або `--ref` зі snapshot, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів Chrome MCP потребують посилань snapshot, а не CSS-селекторів. -- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. +- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики знімків екрана Chrome MCP / `existing-session` повинні використовувати захоплення сторінки або `--ref` зі snapshot, а не CSS `--element`. +- `existing-session file uploads do not support element selectors; use ref/inputRef.` → хуки завантаження файлів у Chrome MCP потребують snapshot ref, а не CSS-селекторів. +- `existing-session file uploads currently support one file at a time.` → для профілів Chrome MCP надсилайте по одному файлу за виклик. - `existing-session dialog handling does not support timeoutMs.` → хуки діалогів у профілях Chrome MCP не підтримують перевизначення timeout. -- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що вимагає керований браузер або профіль raw CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline у профілях лише для приєднання або віддалених CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну контрольну сесію та звільнити стан емуляції Playwright/CDP без перезапуску всього Gateway. +- `response body is not supported for existing-session profiles yet.` → `responsebody` поки що потребує керованого браузера або сирого профілю CDP. +- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → виконайте `openclaw browser stop --browser-profile `, щоб закрити активну керовану сесію й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. Пов’язане: @@ -495,9 +493,9 @@ openclaw doctor ## Якщо ви оновилися і щось раптово зламалося -Більшість збоїв після оновлення — це дрейф конфігурації або суворіші типові значення, які тепер примусово застосовуються. +Більшість збоїв після оновлення — це дрейф конфігурації або жорсткіші типові значення, які тепер примусово застосовуються. -### 1) Поведінка автентифікації та перевизначення URL змінилася +### 1) Змінилася поведінка автентифікації та перевизначення URL ```bash openclaw gateway status @@ -508,15 +506,15 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на віддалений Gateway, тоді як ваша локальна служба справна. -- Явні виклики з `--url` не повертаються до збережених облікових даних. +- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на віддалений Gateway, тоді як ваш локальний сервіс справний. +- Явні виклики `--url` не повертаються до збережених облікових даних. Поширені ознаки: - `gateway connect failed:` → неправильна ціль URL. - `unauthorized` → endpoint досяжний, але автентифікація неправильна. -### 2) Обмеження bind і auth стали суворішими +### 2) Обмеження прив’язки та автентифікації стали жорсткішими ```bash openclaw config get gateway.bind @@ -528,15 +526,15 @@ openclaw logs --follow Що перевірити: -- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації gateway: спільна автентифікація token/password або правильно налаштоване розгортання `trusted-proxy` не для loopback. -- Старі ключі, такі як `gateway.token`, не замінюють `gateway.auth.token`. +- Прив’язки не до loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації Gateway: спільна автентифікація token/password або правильно налаштоване розгортання `trusted-proxy` не на loopback. +- Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. Поширені ознаки: - `refusing to bind gateway ... without auth` → прив’язка не до loopback без дійсного шляху автентифікації gateway. -- `Connectivity probe: failed` коли середовище виконання працює → Gateway живий, але недоступний із поточними auth/url. +- `Connectivity probe: failed`, тоді як runtime запущено → gateway живий, але недоступний із поточною auth/url. -### 3) Стан pairing та ідентичності пристрою змінився +### 3) Змінився стан pairing та ідентичності пристрою ```bash openclaw devices list @@ -547,15 +545,15 @@ openclaw doctor Що перевірити: -- Незавершені схвалення пристроїв для dashboard/nodes. -- Незавершені схвалення pairing у DM після змін політики або ідентичності. +- Очікувані схвалення пристроїв для dashboard/nodes. +- Очікувані схвалення pairing у DM після змін політики або ідентичності. Поширені ознаки: - `device identity required` → автентифікацію пристрою не виконано. - `pairing required` → відправника/пристрій потрібно схвалити. -Якщо після перевірок конфігурація служби і середовище виконання все ще не збігаються, перевстановіть метадані служби з того самого каталогу профілю/стану: +Якщо після перевірок конфігурація сервісу та runtime все ще не збігаються, перевстановіть метадані сервісу з того самого каталогу profile/state: ```bash openclaw gateway install --force diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index 1d5d5ed1f..a9b7467f3 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - Додавання автоматизації браузера, керованої агентом - - Налагодження того, чому openclaw заважає вашому власному Chrome - - Реалізація налаштувань браузера та його життєвого циклу в застосунку macOS + - Налагодження причин, через які openclaw заважає вашому власному Chrome + - Реалізація налаштувань браузера та життєвого циклу в застосунку macOS summary: Інтегрований сервіс керування браузером + команди дій title: Браузер (керований OpenClaw) x-i18n: - generated_at: "2026-04-19T10:22:58Z" + generated_at: "2026-04-22T20:49:59Z" model: gpt-5.4 provider: openai - source_hash: 3f7d37b34ba48dc7c38f8c2e77f8bb97af987eac6a874ebfc921f950fb59de4b + source_hash: 865b0020d66366a62939f8ed28b9cda88d56ee7f5245b1b24a4e804ce55ea42d source_path: tools/browser.md workflow: 15 --- @@ -20,19 +20,19 @@ OpenClaw може запускати **окремий профіль Chrome/Brav Він ізольований від вашого особистого браузера та керується через невеликий локальний сервіс керування всередині Gateway (лише loopback). -Погляд для початківців: +Пояснення для початківців: - Думайте про це як про **окремий браузер лише для агента**. -- Профіль `openclaw` **не** торкається вашого особистого профілю браузера. +- Профіль `openclaw` **не** торкається профілю вашого особистого браузера. - Агент може **відкривати вкладки, читати сторінки, натискати та вводити текст** у безпечному середовищі. -- Вбудований профіль `user` підключається до вашої справжньої сесії Chrome, у якій ви вже ввійшли, через Chrome MCP. +- Вбудований профіль `user` підключається до вашої реальної сесії Chrome, у якій виконано вхід, через Chrome MCP. ## Що ви отримуєте - Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). -- Детерміноване керування вкладками (список/відкрити/фокус/закрити). +- Детерміноване керування вкладками (перелік/відкриття/фокусування/закриття). - Дії агента (натискання/введення/перетягування/вибір), знімки, скриншоти, PDF. -- Необов’язкова підтримка кількох профілів (`openclaw`, `work`, `remote`, ...). +- Необов’язкову підтримку кількох профілів (`openclaw`, `work`, `remote`, ...). Цей браузер **не** призначений для вашого щоденного використання. Це безпечна, ізольована поверхня для автоматизації та перевірки агентом. @@ -46,17 +46,17 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -Якщо ви отримуєте “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть +Якщо ви отримуєте повідомлення “Browser disabled”, увімкніть його в конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` повністю відсутня або агент каже, що інструмент браузера +Якщо `openclaw browser` узагалі відсутня або агент каже, що інструмент браузера недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool). ## Керування Plugin -Типовий інструмент `browser` тепер є вбудованим Plugin, який постачається увімкненим -типово. Це означає, що ви можете вимкнути або замінити його, не видаляючи решту -системи Plugin у OpenClaw: +Типовий інструмент `browser` тепер є вбудованим Plugin, який постачається +увімкненим за замовчуванням. Це означає, що ви можете вимкнути або замінити його, не видаляючи решту +системи Plugin OpenClaw: ```json5 { @@ -71,31 +71,32 @@ Gateway. ``` Вимкніть вбудований Plugin перед встановленням іншого Plugin, який надає -те саме ім’я інструмента `browser`. Типовому режиму браузера потрібні обидва параметри: +те саме ім’я інструмента `browser`. Типовий режим роботи браузера потребує обох умов: - `plugins.entries.browser.enabled` не вимкнено - `browser.enabled=true` Якщо ви вимкнете лише Plugin, вбудований CLI браузера (`openclaw browser`), метод gateway (`browser.request`), інструмент агента та типовий сервіс керування браузером -усі зникнуть разом. Ваша конфігурація `browser.*` залишиться недоторканою, щоб її міг повторно використати +зникнуть одночасно. Ваш конфіг `browser.*` залишиться недоторканим, щоб його міг повторно використати Plugin-замінник. -Вбудований Plugin браузера тепер також володіє реалізацією runtime браузера. -У core залишаються лише спільні допоміжні компоненти Plugin SDK плюс сумісні повторні експорти для +Вбудований Plugin браузера тепер також володіє реалізацією середовища виконання браузера. +У core залишаються лише спільні допоміжні засоби Plugin SDK плюс сумісні повторні експорти для старих внутрішніх шляхів імпорту. На практиці видалення або заміна пакета Plugin браузера -прибирає функціональність браузера, а не залишає позаду другу runtime-реалізацію, що належить core. +прибирає набір можливостей браузера замість того, щоб залишати позаду друге середовище виконання, +яким володіє core. Зміни конфігурації браузера все ще потребують перезапуску Gateway, щоб вбудований Plugin міг повторно зареєструвати свій сервіс браузера з новими налаштуваннями. ## Відсутня команда браузера або інструмент -Якщо `openclaw browser` раптово стає невідомою командою після оновлення або +Якщо після оновлення `openclaw browser` раптово стала невідомою командою або агент повідомляє, що інструмент браузера відсутній, найпоширенішою причиною є обмежувальний список `plugins.allow`, який не містить `browser`. -Приклад зламаної конфігурації: +Приклад некоректної конфігурації: ```json5 { @@ -117,9 +118,9 @@ Plugin-замінник. Важливі примітки: -- Самого `browser.enabled=true` недостатньо, якщо встановлено `plugins.allow`. -- Самого `plugins.entries.browser.enabled=true` також недостатньо, якщо встановлено `plugins.allow`. -- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований Plugin браузера. Він лише коригує політику інструментів після того, як Plugin уже завантажено. +- `browser.enabled=true` саме по собі недостатньо, коли встановлено `plugins.allow`. +- `plugins.entries.browser.enabled=true` саме по собі також недостатньо, коли встановлено `plugins.allow`. +- `tools.alsoAllow: ["browser"]` **не** завантажує вбудований Plugin браузера. Це лише коригує політику інструментів після того, як Plugin уже завантажено. - Якщо вам не потрібен обмежувальний список дозволених Plugin, видалення `plugins.allow` також відновлює типову поведінку вбудованого браузера. Типові симптоми: @@ -128,38 +129,38 @@ Plugin-замінник. - `browser.request` відсутній. - Агент повідомляє, що інструмент браузера недоступний або відсутній. -## Профілі: `openclaw` vs `user` +## Профілі: `openclaw` і `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль підключення Chrome MCP до вашої **справжньої сесії Chrome** +- `user`: вбудований профіль підключення Chrome MCP до вашої **реальної сесії Chrome** із виконаним входом. Для викликів інструмента браузера агентом: -- Типово: використовується ізольований браузер `openclaw`. +- Типово: використовувати ізольований браузер `openclaw`. - Надавайте перевагу `profile="user"`, коли важливі наявні сесії з виконаним входом і користувач перебуває за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення. -- `profile` — це явний спосіб перевизначення, коли вам потрібен конкретний режим браузера. +- `profile` є явним перевизначенням, коли ви хочете конкретний режим браузера. -Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб типово використовувався керований режим. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. ## Конфігурація -Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`. +Налаштування браузера містяться в `~/.openclaw/openclaw.json`. ```json5 { browser: { - enabled: true, // типово: true + enabled: true, // default: true ssrfPolicy: { - // dangerouslyAllowPrivateNetwork: true, // вмикайте лише для довіреного доступу до приватної мережі - // allowPrivateNetwork: true, // застарілий псевдонім + // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access + // allowPrivateNetwork: true, // legacy alias // hostnameAllowlist: ["*.example.com", "example.com"], // allowedHostnames: ["localhost"], }, - // cdpUrl: "http://127.0.0.1:18792", // застаріле перевизначення одного профілю - remoteCdpTimeoutMs: 1500, // тайм-аут HTTP віддаленого CDP (мс) - remoteCdpHandshakeTimeoutMs: 3000, // тайм-аут рукостискання WebSocket віддаленого CDP (мс) + // cdpUrl: "http://127.0.0.1:18792", // legacy single-profile override + remoteCdpTimeoutMs: 1500, // remote CDP HTTP timeout (ms) + remoteCdpHandshakeTimeoutMs: 3000, // remote CDP WebSocket handshake timeout (ms) defaultProfile: "openclaw", color: "#FF4500", headless: false, @@ -188,32 +189,32 @@ Plugin-замінник. Примітки: -- Сервіс керування браузером прив’язується до loopback на порту, похідному від `gateway.port` +- Сервіс керування браузером прив’язується до loopback на порті, похідному від `gateway.port` (типово: `18791`, тобто gateway + 2). - Якщо ви перевизначаєте порт Gateway (`gateway.port` або `OPENCLAW_GATEWAY_PORT`), - похідні порти браузера зміщуються, щоб залишатися в тій самій “сім’ї”. -- `cdpUrl` типово вказує на керований локальний CDP-порт, якщо його не задано. + похідні порти браузера зміщуються, щоб залишатися в тій самій «родині». +- Якщо `cdpUrl` не задано, типово використовується керований локальний порт CDP. - `remoteCdpTimeoutMs` застосовується до перевірок доступності віддаленого (не-loopback) CDP. - `remoteCdpHandshakeTimeoutMs` застосовується до перевірок доступності рукостискання WebSocket віддаленого CDP. -- Навігація браузера/відкриття вкладок захищені SSRF-перевіркою до навігації та за можливості повторно перевіряються для фінального URL `http(s)` після навігації. -- У строгому режимі SSRF перевіряються також виявлення/проби віддалених кінцевих точок CDP (`cdpUrl`, включно з пошуками `/json/version`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнений. Установлюйте його в `true` лише тоді, коли ви навмисно довіряєте доступу браузера до приватної мережі. +- Навігація/відкриття вкладок у браузері захищені від SSRF перед навігацією та повторно перевіряються за принципом best-effort на фінальному `http(s)` URL після навігації. +- У строгому режимі SSRF також перевіряються виявлення/проби віддалених кінцевих точок CDP (`cdpUrl`, включно з пошуками `/json/version`). +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено. Установлюйте `true` лише тоді, коли ви свідомо довіряєте доступу браузера до приватної мережі. - `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім для сумісності. -- `attachOnly: true` означає “ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений”. -- `color` та `color` для кожного профілю тонують інтерфейс браузера, щоб ви могли бачити, який профіль активний. -- Типовий профіль — `openclaw` (окремий браузер, керований OpenClaw). Використовуйте `defaultProfile: "user"`, щоб перейти на браузер користувача з виконаним входом. -- Порядок автовизначення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. -- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl` — задавайте їх лише для віддаленого CDP. +- `attachOnly: true` означає «ніколи не запускати локальний браузер; лише підключатися, якщо він уже працює». +- `color` і `color` для окремого профілю тонують інтерфейс браузера, щоб ви могли бачити, який профіль активний. +- Типовим профілем є `openclaw` (окремий браузер, яким керує OpenClaw). Використовуйте `defaultProfile: "user"`, щоб перейти на браузер користувача з виконаним входом. +- Порядок автовиявлення: системний типовий браузер, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. +- Локальним профілям `openclaw` автоматично призначаються `cdpPort`/`cdpUrl` — задавайте їх лише для віддаленого CDP. - `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не - встановлюйте `cdpUrl` для цього драйвера. + задавайте `cdpUrl` для цього драйвера. - Установіть `browser.profiles..userDataDir`, коли профіль existing-session - має підключатися до нестандартного профілю користувача Chromium, наприклад Brave або Edge. + має підключатися до нетипового профілю користувача Chromium, наприклад Brave або Edge. ## Використання Brave (або іншого браузера на базі Chromium) -Якщо ваш **системний браузер за замовчуванням** базується на Chromium (Chrome/Brave/Edge тощо), +Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо), OpenClaw використовує його автоматично. Установіть `browser.executablePath`, щоб перевизначити -автовизначення: +автовиявлення: Приклад CLI: @@ -246,21 +247,21 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Локальне та віддалене керування -- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування та може запускати локальний браузер. -- **Віддалене керування (вузол-хост):** запустіть вузол-хост на машині, де є браузер; Gateway проксуватиме до нього дії браузера. +- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. +- **Віддалене керування (хост Node):** запустіть хост Node на машині, де є браузер; Gateway проксуватиме до нього дії браузера. - **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - підключитися до віддаленого браузера на базі Chromium. У такому разі OpenClaw не запускатиме локальний браузер. + підключитися до віддаленого браузера на базі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. Поведінка під час зупинки відрізняється залежно від режиму профілю: - локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який запустив OpenClaw -- профілі лише з підключенням та профілі віддаленого CDP: `openclaw browser stop` закриває активну +- профілі лише для підключення та профілі віддаленого CDP: `openclaw browser stop` закриває активну сесію керування та скидає перевизначення емуляції Playwright/CDP (viewport, колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть якщо OpenClaw не запускав жодного процесу браузера -Віддалені URL CDP можуть містити автентифікацію: +URL віддаленого CDP можуть містити автентифікацію: - Токени в параметрах запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) @@ -269,27 +270,27 @@ OpenClaw зберігає автентифікацію під час викли до WebSocket CDP. Для токенів краще використовувати змінні середовища або менеджери секретів, а не зберігати їх у файлах конфігурації. -## Проксі браузера Node (нульова конфігурація типово) +## Проксі браузера Node (типовий режим без конфігурації) -Якщо ви запускаєте **вузол-хост** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера до цього вузла без жодної додаткової конфігурації браузера. -Це типовий шлях для віддалених Gateway. +Якщо ви запускаєте **хост Node** на машині, де знаходиться ваш браузер, OpenClaw може +автоматично спрямовувати виклики інструмента браузера до цього node без будь-якої додаткової конфігурації браузера. +Це типовий шлях для віддалених gateway. Примітки: -- Вузол-хост надає свій локальний сервер керування браузером через **проксі-команду**. -- Профілі беруться з власної конфігурації вузла `browser.profiles` (так само, як локально). +- Хост Node надає свій локальний сервер керування браузером через **проксі-команду**. +- Профілі беруться з власного конфігу `browser.profiles` node (так само, як локально). - `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. -- Якщо ви встановите `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядатиме це як межу найменших привілеїв: можна буде звертатися лише до профілів зі списку дозволених, а маршрути створення/видалення постійних профілів будуть заблоковані на поверхні проксі. -- Вимкніть це, якщо воно вам не потрібне: - - На вузлі: `nodeHost.browserProxy.enabled=false` +- Якщо ви встановлюєте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядає це як межу принципу найменших привілеїв: лише профілі зі списку дозволених можуть бути цільовими, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі. +- Вимкніть це, якщо не хочете використовувати: + - На node: `nodeHost.browserProxy.enabled=false` - На gateway: `gateway.nodes.browser.mode="off"` ## Browserless (розміщений віддалений CDP) [Browserless](https://browserless.io) — це розміщений сервіс Chromium, який надає URL підключення CDP через HTTPS і WebSocket. OpenClaw може використовувати будь-яку форму, але -для віддаленого профілю браузера найпростішим варіантом є прямий URL WebSocket +для профілю віддаленого браузера найпростішим варіантом є прямий URL WebSocket з документації підключення Browserless. Приклад: @@ -313,43 +314,43 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може Примітки: -- Замініть `` на ваш справжній токен Browserless. -- Виберіть кінцеву точку регіону, що відповідає вашому обліковому запису Browserless (див. їхню документацію). +- Замініть `` на ваш реальний токен Browserless. +- Виберіть регіональну кінцеву точку, яка відповідає вашому обліковому запису Browserless (див. їхню документацію). - Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw виявити `/json/version`. -## Прямі постачальники WebSocket CDP +## Провайдери прямого WebSocket CDP -Деякі розміщені сервіси браузерів надають **пряму** кінцеву точку WebSocket замість +Деякі розміщені сервіси браузера надають **пряму кінцеву точку WebSocket** замість стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три форми URL CDP і автоматично вибирає правильну стратегію підключення: -- **Виявлення через HTTP(S)** — `http://host[:port]` або `https://host[:port]`. - OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім +- **Виявлення HTTP(S)** — `http://host[:port]` або `https://host[:port]`. + OpenClaw викликає `/json/version`, щоб виявити URL налагоджувача WebSocket, а потім підключається. Резервного переходу на WebSocket немає. - **Прямі кінцеві точки WebSocket** — `ws://host[:port]/devtools//` або `wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`. OpenClaw підключається напряму через рукостискання WebSocket і повністю пропускає `/json/version`. -- **Базові корені WebSocket** — `ws://host[:port]` або `wss://host[:port]` без +- **Кореневі адреси WebSocket без шляху** — `ws://host[:port]` або `wss://host[:port]` без шляху `/devtools/...` (наприклад, [Browserless](https://browserless.io), - [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує виявлення через HTTP - `/json/version` (нормалізуючи схему до `http`/`https`); + [Browserbase](https://www.browserbase.com)). OpenClaw спочатку пробує HTTP + виявлення через `/json/version` (нормалізуючи схему до `http`/`https`); якщо виявлення повертає `webSocketDebuggerUrl`, він використовується, інакше OpenClaw - переходить до прямого рукостискання WebSocket на базовому корені. Це охоплює - як віддалені порти налагодження в стилі Chrome, так і постачальників лише з WebSocket. + переходить до прямого рукостискання WebSocket на корені без шляху. Це покриває + як віддалені порти налагодження у стилі Chrome, так і провайдерів лише з WebSocket. -Звичайний `ws://host:port` / `wss://host:port` без шляху `/devtools/...`, -спрямований на локальний екземпляр Chrome, підтримується через резервний механізм -із пріоритетом виявлення — Chrome приймає оновлення до WebSocket лише на конкретному шляху -для браузера або цілі, який повертає `/json/version`, тому лише рукостискання на базовому корені -завершиться невдачею. +Звичайні `ws://host:port` / `wss://host:port` без шляху `/devtools/...`, +спрямовані на локальний екземпляр Chrome, підтримуються через резервну схему +«спочатку виявлення» — Chrome приймає WebSocket upgrades лише на конкретному шляху +для браузера або цілі, який повертає `/json/version`, тому одного лише рукостискання +на корені без шляху буде недостатньо. ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -браузерів у режимі headless із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними +headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та резидентними проксі. ```json5 @@ -373,51 +374,51 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може - [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** з [панелі Overview](https://www.browserbase.com/overview). -- Замініть `` на ваш справжній API-ключ Browserbase. +- Замініть `` на ваш справжній API key Browserbase. - Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому - окремий ручний етап створення сесії не потрібен. -- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. - Ліміти платних планів дивіться в [pricing](https://www.browserbase.com/pricing). -- Дивіться [документацію Browserbase](https://docs.browserbase.com) для повного - довідника API, посібників з SDK та прикладів інтеграції. + ручний етап створення сесії не потрібен. +- Безкоштовний рівень дозволяє одну одночасну сесію та одну браузерну годину на місяць. + Обмеження платних планів дивіться в [pricing](https://www.browserbase.com/pricing). +- Повний довідник API, + посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). ## Безпека Ключові ідеї: -- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або спарювання вузлів. -- Автономний loopback HTTP API браузера використовує **лише автентифікацію через спільний секрет**: - bearer-автентифікацію за токеном gateway, `x-openclaw-password` або HTTP Basic auth із +- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairинг node. +- Окремий loopback HTTP API браузера використовує **лише автентифікацію через shared secret**: + bearer auth із токеном gateway, `x-openclaw-password` або HTTP Basic auth із налаштованим паролем gateway. -- Заголовки ідентичності Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` - **не** автентифікують цей автономний loopback API браузера. -- Якщо керування браузером увімкнено й не налаштовано жодної автентифікації через спільний секрет, OpenClaw +- Заголовки ідентичності Tailscale Serve і `gateway.auth.mode: "trusted-proxy"` + **не** автентифікують цей окремий loopback API браузера. +- Якщо керування браузером увімкнено й не налаштовано жодної shared-secret автентифікації, OpenClaw автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації. - OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway та будь-які вузли-хости в приватній мережі (Tailscale); уникайте публічного доступу. -- Ставтеся до віддалених URL/tокенів CDP як до секретів; надавайте перевагу змінним середовища або менеджеру секретів. +- Тримайте Gateway і будь-які хости node у приватній мережі (Tailscale); уникайте публічної доступності. +- Ставтеся до URL/токенів віддаленого CDP як до секретів; надавайте перевагу змінним середовища або менеджеру секретів. Поради щодо віддаленого CDP: -- За можливості надавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і токенам із коротким строком життя. +- За можливості використовуйте зашифровані кінцеві точки (HTTPS або WSS) і короткоживучі токени. - Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. ## Профілі (кілька браузерів) OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: -- **керовані openclaw**: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних та портом CDP -- **віддалені**: явно заданий URL CDP (браузер на базі Chromium, що працює деінде) -- **наявна сесія**: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP +- **openclaw-managed**: окремий екземпляр браузера на базі Chromium із власним каталогом користувацьких даних і портом CDP +- **remote**: явний URL CDP (браузер на базі Chromium, запущений деінде) +- **existing session**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP Типові значення: -- Профіль `openclaw` автоматично створюється, якщо відсутній. -- Профіль `user` вбудований для підключення наявної сесії Chrome MCP. -- Профілі existing-session, окрім `user`, є необов’язковими; створюйте їх за допомогою `--driver existing-session`. +- Профіль `openclaw` створюється автоматично, якщо його немає. +- Профіль `user` вбудований для existing-session підключення Chrome MCP. +- Профілі existing-session, окрім `user`, є добровільними; створюйте їх за допомогою `--driver existing-session`. - Локальні порти CDP типово виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних до Кошика. +- Видалення профілю переміщує його локальний каталог даних до Trash. Усі кінцеві точки керування приймають `?profile=`; CLI використовує `--browser-profile`. @@ -427,21 +428,21 @@ OpenClaw також може підключатися до запущеного офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу, які вже відкриті в цьому профілі браузера. -Офіційні довідкові матеріали та посилання з налаштування: +Офіційні довідкові матеріали та інструкції з налаштування: -- [Chrome for Developers: Використання Chrome DevTools MCP із вашою сесією браузера](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) +- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) - [README Chrome DevTools MCP](https://github.com/ChromeDevTools/chrome-devtools-mcp) Вбудований профіль: - `user` -Необов’язково: створіть власний профіль existing-session, якщо вам потрібні +Необов’язково: створіть власний custom existing-session профіль, якщо вам потрібні інша назва, колір або каталог даних браузера. Типова поведінка: -- Вбудований профіль `user` використовує автоматичне підключення Chrome MCP, яке націлюється на +- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке спрямоване на типовий локальний профіль Google Chrome. Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome: @@ -465,7 +466,7 @@ OpenClaw також може підключатися до запущеного 1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. 2. Увімкніть віддалене налагодження. -3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. +3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw приєднається. Поширені сторінки inspect: @@ -482,70 +483,69 @@ openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot --format ai ``` -Як виглядає успіх: +Ознаки успішного підключення: - `status` показує `driver: existing-session` - `status` показує `transport: chrome-mcp` - `status` показує `running: true` -- `tabs` перелічує вже відкриті у вашому браузері вкладки -- `snapshot` повертає refs із вибраної live-вкладки +- `tabs` перелічує вже відкриті у вас вкладки браузера +- `snapshot` повертає refs із вибраної активної вкладки Що перевірити, якщо підключення не працює: - цільовий браузер на базі Chromium має версію `144+` -- у сторінці inspect цього браузера ввімкнено віддалене налагодження -- браузер показав запит на підключення, і ви його прийняли -- `openclaw doctor` мігрує стару конфігурацію браузера на основі розширення та перевіряє, що - Chrome встановлено локально для типових профілів автоматичного підключення, але він не може - увімкнути віддалене налагодження в самому браузері за вас +- на сторінці inspect цього браузера увімкнено віддалене налагодження +- браузер показав запит на згоду на підключення, і ви його підтвердили +- `openclaw doctor` переносить старий конфіг браузера на основі розширення та перевіряє, що + Chrome встановлено локально для типових профілів автопідключення, але не може + увімкнути віддалене налагодження на стороні браузера за вас Використання агентом: - Використовуйте `profile="user"`, коли вам потрібен стан браузера користувача з виконаним входом. -- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. -- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити +- Якщо ви використовуєте custom existing-session профіль, передайте явну назву цього профілю. +- Вибирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити запит на підключення. -- Gateway або вузол-хост можуть запускати `npx chrome-devtools-mcp@latest --autoConnect` +- Gateway або хост node може запускати `npx chrome-devtools-mcp@latest --autoConnect` Примітки: -- Цей шлях має вищий ризик, ніж ізольований профіль `openclaw`, оскільки він може - виконувати дії у вашій сесії браузера, де вже виконано вхід. +- Цей шлях є ризикованішим, ніж ізольований профіль `openclaw`, оскільки він може + діяти всередині вашої сесії браузера, у якій виконано вхід. - OpenClaw не запускає браузер для цього драйвера; він підключається лише до наявної сесії. - Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо встановлено `userDataDir`, OpenClaw передає його далі, щоб націлитися на цей явний каталог користувацьких даних Chromium. -- Скриншоти existing-session підтримують захоплення сторінки та захоплення елементів через `--ref` - зі знімків, але не CSS-селектори `--element`. -- Скриншоти сторінок existing-session працюють без Playwright через Chrome MCP. - Скриншоти елементів за ref (`--ref`) також працюють там, але `--full-page` +- Скріншоти existing-session підтримують знімки сторінки та знімки елементів через `--ref` + зі snapshot, але не CSS-селектори `--element`. +- Скріншоти сторінок existing-session працюють без Playwright через Chrome MCP. + Скріншоти елементів за ref (`--ref`) там також працюють, але `--full-page` не можна поєднувати з `--ref` або `--element`. -- Дії existing-session усе ще більш обмежені, ніж у режимі - керованого браузера: +- Дії existing-session усе ще більш обмежені, ніж у режимі керованого браузера: - `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують snapshot refs замість CSS-селекторів - - `click` підтримує лише ліву кнопку (без перевизначення кнопки чи модифікаторів) + - `click` підтримує лише ліву кнопку миші (без перевизначення кнопки або модифікаторів) - `type` не підтримує `slowly=true`; використовуйте `fill` або `press` - `press` не підтримує `delayMs` - `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не - підтримують перевизначення тайм-ауту для окремого виклику + підтримують перевизначення timeout для окремого виклику - `select` наразі підтримує лише одне значення -- Existing-session `wait --url` підтримує точні, підрядкові та glob-шаблони - так само, як і інші драйвери браузера. `wait --load networkidle` поки не підтримується. -- Хуки вивантаження в existing-session потребують `ref` або `inputRef`, підтримують по одному файлу за раз і не підтримують націлювання на CSS `element`. -- Хуки діалогів existing-session не підтримують перевизначення тайм-ауту. -- Деякі можливості все ще потребують керованого шляху браузера, зокрема пакетні +- Existing-session `wait --url` підтримує точні, часткові та glob-шаблони, + як і інші драйвери браузера. `wait --load networkidle` поки не підтримується. +- Хуки завантаження файлів existing-session вимагають `ref` або `inputRef`, підтримують по одному файлу за раз і не підтримують націлювання через CSS `element`. +- Хуки діалогів existing-session не підтримують перевизначення timeout. +- Деякі можливості все ще потребують режиму керованого браузера, зокрема пакетні дії, експорт PDF, перехоплення завантажень і `responsebody`. - Existing-session може підключатися на вибраному хості або через підключений - вузол браузера. Якщо Chrome розташований деінде й вузол браузера не підключений, використовуйте - віддалений CDP або вузол-хост. + browser node. Якщо Chrome працює деінде й browser node не підключено, використовуйте + віддалений CDP або хост node. ## Гарантії ізоляції -- **Окремий каталог користувацьких даних**: ніколи не торкається вашого особистого профілю браузера. -- **Окремі порти**: уникає `9222`, щоб запобігти конфліктам із робочими процесами розробки. -- **Детерміноване керування вкладками**: націлення на вкладки за `targetId`, а не за принципом “остання вкладка”. +- **Окремий каталог користувацьких даних**: ніколи не торкається профілю вашого особистого браузера. +- **Окремі порти**: уникає `9222`, щоб не створювати конфліктів із робочими процесами розробки. +- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за принципом «остання вкладка». ## Вибір браузера @@ -561,19 +561,19 @@ openclaw browser --browser-profile user snapshot --format ai Платформи: -- macOS: перевіряє `/Applications` і `~/Applications`. -- Linux: шукає `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. -- Windows: перевіряє поширені каталоги встановлення. +- macOS: перевіряються `/Applications` і `~/Applications`. +- Linux: шукаються `google-chrome`, `brave`, `microsoft-edge`, `chromium` тощо. +- Windows: перевіряються типові місця встановлення. ## API керування (необов’язково) Лише для локальних інтеграцій Gateway надає невеликий loopback HTTP API: -- Стан/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` +- Status/start/stop: `GET /`, `POST /start`, `POST /stop` - Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Знімок/скриншот: `GET /snapshot`, `POST /screenshot` +- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot` - Дії: `POST /navigate`, `POST /act` -- Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog` +- Hooks: `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` @@ -584,21 +584,21 @@ openclaw browser --browser-profile user snapshot --format ai Усі кінцеві точки приймають `?profile=`. -Якщо налаштовано автентифікацію gateway через спільний секрет, HTTP-маршрути браузера також потребують автентифікації: +Якщо налаштовано shared-secret автентифікацію gateway, маршрути HTTP браузера також вимагають автентифікації: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей автономний loopback API браузера **не** використовує trusted-proxy або +- Цей окремий loopback API браузера **не** використовує trusted-proxy або заголовки ідентичності Tailscale Serve. - Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера - не успадковують ці режими з перенесенням ідентичності; тримайте їх доступними лише через loopback. + не успадковують режими з передаванням ідентичності; залишайте їх доступними лише через loopback. ### Контракт помилок `/act` -`POST /act` використовує структуровану відповідь помилки для валідації на рівні маршруту та +`POST /act` використовує структуровану відповідь про помилку для валідації на рівні маршруту та збоїв політики: ```json @@ -608,13 +608,13 @@ openclaw browser --browser-profile user snapshot --format ai Поточні значення `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): top-level `targetId` або `targetId` у пакеті конфліктує з ціллю запиту. +- `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": "" }` без +Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без поля `code`. ### Вимога Playwright @@ -625,31 +625,32 @@ PDF) потребують Playwright. Якщо Playwright не встановл Що все ще працює без Playwright: -- ARIA snapshots -- Скриншоти сторінок для керованого браузера `openclaw`, коли для вкладки доступний CDP - WebSocket -- Скриншоти сторінок для профілів `existing-session` / Chrome MCP -- Скриншоти existing-session на основі ref (`--ref`) з виводу snapshot +- ARIA snapshot +- Скриншоти сторінки для керованого браузера `openclaw`, коли доступний WebSocket + CDP для окремої вкладки +- Скриншоти сторінки для профілів `existing-session` / Chrome MCP +- Скриншоти existing-session за ref (`--ref`) з виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` -- AI snapshots / role snapshots +- AI snapshot / role snapshot - Скриншоти елементів за CSS-селектором (`--element`) -- Повний експорт PDF браузера +- повний експорт PDF браузера -Скриншоти елементів також відхиляють `--full-page`; маршрут повертає `fullPage is +Скриншоти елементів також не приймають `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. -Якщо ви бачите `Playwright is not available in this gateway build`, установіть повний -пакет Playwright (не `playwright-core`) і перезапустіть gateway або перевстановіть -OpenClaw із підтримкою браузера. +Якщо ви бачите `Playwright is not available in this gateway build`, відновіть залежності середовища виконання +вбудованого Plugin браузера, щоб було встановлено `playwright-core`, +а потім перезапустіть gateway. Для пакетних установок виконайте `openclaw doctor --fix`. +Для Docker також установіть двійкові файли браузера Chromium, як показано нижче. #### Установлення Playwright у Docker Якщо ваш Gateway працює в Docker, уникайте `npx playwright` (конфлікти npm override). -Замість цього використовуйте вбудований CLI: +Натомість використовуйте вбудований CLI: ```bash docker compose run --rm openclaw-cli \ @@ -662,23 +663,23 @@ docker compose run --rm openclaw-cli \ ## Як це працює (внутрішньо) -Потік високого рівня: +Потік на високому рівні: - Невеликий **сервер керування** приймає HTTP-запити. - Він підключається до браузерів на базі Chromium (Chrome/Brave/Edge/Chromium) через **CDP**. - Для розширених дій (click/type/snapshot/PDF) він використовує **Playwright** поверх CDP. -- Коли Playwright відсутній, доступні лише операції без Playwright. +- Якщо Playwright відсутній, доступні лише операції без Playwright. -Ця архітектура забезпечує для агента стабільний, детермінований інтерфейс, водночас дозволяючи -вам замінювати локальні/віддалені браузери та профілі. +Такий дизайн зберігає для агента стабільний, детермінований інтерфейс і водночас дає +змогу змінювати локальні/віддалені браузери та профілі. -## Короткий довідник CLI +## Швидкий довідник CLI -Усі команди приймають `--browser-profile ` для націлення на конкретний профіль. -Усі команди також приймають `--json` для машинозчитуваного виводу (стабільні payload). +Усі команди приймають `--browser-profile ` для націлювання на конкретний профіль. +Усі команди також приймають `--json` для машиночитного виводу (стабільні payload). -Основи: +Основне: - `openclaw browser status` - `openclaw browser start` @@ -707,11 +708,11 @@ docker compose run --rm openclaw-cli \ - `openclaw browser snapshot --frame "iframe#main" --interactive` - `openclaw browser console --level error` -Примітка щодо життєвого циклу: +Примітка про життєвий цикл: -- Для профілів лише з підключенням і віддаленим CDP `openclaw browser stop` усе ще є +- Для профілів лише для підключення та профілів віддаленого CDP `openclaw browser stop` усе ще є правильною командою очищення після тестів. Вона закриває активну сесію керування та - очищає тимчасові перевизначення емуляції замість завершення базового + прибирає тимчасові перевизначення емуляції замість завершення базового браузера. - `openclaw browser errors --clear` - `openclaw browser requests --filter api --clear` @@ -763,57 +764,57 @@ docker compose run --rm openclaw-cli \ Примітки: -- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед натисканням/клавішею, - що викликає chooser/dialog. -- Шляхи виводу для download і trace обмежені тимчасовими коренями OpenClaw: +- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед click/press, + що відкриває file chooser/діалог. +- Шляхи виводу download і trace обмежені тимчасовими коренями OpenClaw: - traces: `/tmp/openclaw` (резервний варіант: `${os.tmpdir()}/openclaw`) - downloads: `/tmp/openclaw/downloads` (резервний варіант: `${os.tmpdir()}/openclaw/downloads`) -- Шляхи upload обмежені тимчасовим коренем завантажень OpenClaw: +- Шляхи upload обмежені тимчасовим коренем upload OpenClaw: - uploads: `/tmp/openclaw/uploads` (резервний варіант: `${os.tmpdir()}/openclaw/uploads`) -- `upload` також може напряму встановлювати file input через `--input-ref` або `--element`. +- `upload` також може безпосередньо задавати file input через `--input-ref` або `--element`. - `snapshot`: - `--format ai` (типово, коли встановлено Playwright): повертає AI snapshot із числовими refs (`aria-ref=""`). - `--format aria`: повертає дерево доступності (без refs; лише для перевірки). - - `--efficient` (або `--mode efficient`): компактний preset role snapshot (interactive + compact + depth + lower maxChars). - - Типове значення конфігурації (лише tool/CLI): установіть `browser.snapshotDefaults.mode: "efficient"`, щоб використовувати efficient snapshots, коли викликач не передає режим (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)). - - Параметри role snapshot (`--interactive`, `--compact`, `--depth`, `--selector`) примусово вмикають snapshot на основі ролей із refs на кшталт `ref=e12`. - - `--frame "