diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 0f96f5e1e..f8285bfa2 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,27 +1,27 @@ --- read_when: - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося. - - Ви налагоджуєте збої в перевірках GitHub Actions. -summary: Граф завдань CI, обмежувачі охоплення та локальні еквіваленти команд -title: конвеєр CI + - Ви налагоджуєте збої перевірок GitHub Actions. +summary: Граф завдань CI, шлюзи області дії та локальні еквіваленти команд +title: пайплайн CI x-i18n: - generated_at: "2026-04-24T05:03:58Z" + generated_at: "2026-04-24T07:42:13Z" model: gpt-5.4 provider: openai - source_hash: 8e24efec145ff144b007e248ef0f9c56287619eb9af204d45d49984909a6136b + source_hash: 489ac05725a316b25f56f7f754d6a8652abbd60481fbe6e692572b81581fe405 source_path: ci.md workflow: 15 --- -CI запускається для кожного push до `main` і кожного pull request. Він використовує розумне обмеження охоплення, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. +CI запускається для кожного push у `main` і кожного pull request. Він використовує розумне визначення області дії, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. -QA Lab має окремі доріжки CI поза основним workflow із розумним обмеженням охоплення. Workflow `Parity gate` запускається для відповідних змін у PR і через ручний dispatch; він збирає приватне середовище виконання QA та порівнює agentic-пакети mock GPT-5.4 і Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через ручний dispatch; він розгалужує mock parity gate, live-доріжку Matrix і live-доріжку Telegram як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а доріжка Telegram використовує оренди Convex. `OpenClaw Release Checks` також запускає ті самі доріжки QA Lab перед затвердженням релізу. +QA Lab має окремі доріжки CI поза основним workflow з розумною областю дії. Workflow `Parity gate` запускається для відповідних змін у PR і при ручному запуску; він збирає приватне середовище виконання QA і порівнює агентні набори mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі для `main` і при ручному запуску; він розгалужує mock parity gate, live доріжку Matrix і live доріжку Telegram як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а доріжка Telegram використовує оренди Convex. `OpenClaw Release Checks` також запускає ті самі доріжки QA Lab перед затвердженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для супроводу після злиття, призначений для очищення дублікатів. За замовчуванням він працює в режимі dry-run і закриває лише явно вказані PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді merged і що кожен дублікат має або спільну згадану issue, або перетин змінених hunk-ів. +Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільне згадане issue, або перетин змінених фрагментів. -Workflow `Docs Agent` — це Codex-доріжка супроводу, що запускається за подіями, щоб підтримувати наявну документацію узгодженою з нещодавно злитими змінами. Вона не має окремого запуску за розкладом: її може запустити успішний небоговий запуск push CI на `main`, а ручний dispatch може запускати її безпосередньо. Виклики через workflow-run пропускаються, якщо `main` уже просунувся далі або якщо інший непропущений запуск Docs Agent був створений протягом останньої години. Коли вона запускається, вона переглядає діапазон комітів від попереднього source SHA непропущеного Docs Agent до поточного `main`, тож один погодинний запуск може охопити всі зміни в main, накопичені з часу останнього проходу документації. +Workflow `Docs Agent` — це керована подіями доріжка обслуговування Codex для підтримання наявної документації у відповідності до нещодавно внесених змін. У неї немає окремого запуску за розкладом: її може запустити успішний CI-запуск для небота після push у `main`, а також її можна запустити вручну. Виклики через workflow-run пропускаються, якщо `main` уже просунувся далі або якщо інший непропущений запуск Docs Agent був створений протягом останньої години. Під час виконання він переглядає діапазон комітів від SHA джерела попереднього непропущеного Docs Agent до поточного `main`, тому один щогодинний запуск може охопити всі зміни в main, накопичені з часу останнього проходу документації. -Workflow `Test Performance Agent` — це Codex-доріжка супроводу для повільних тестів, що запускається за подіями. Вона не має окремого запуску за розкладом: її може запустити успішний небоговий запуск push CI на `main`, але вона пропускається, якщо інший виклик через workflow-run уже виконувався або виконується в цю UTC-добу. Ручний dispatch обходить це денне обмеження активності. Доріжка збирає згрупований звіт про продуктивність Vitest для повного набору тестів, дозволяє Codex вносити лише невеликі виправлення продуктивності тестів без втрати покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору та відхиляє зміни, які зменшують кількість тестів, що проходять у базовому стані. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а звіт для повного набору після роботи агента має проходити, перш ніж щось буде закомічено. Коли `main` просувається до того, як бот устигне запушити зміни, доріжка робить rebase перевіреного патча, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну модель drop-sudo, що й docs agent. +Workflow `Test Performance Agent` — це керована подіями доріжка обслуговування Codex для повільних тестів. У нього немає окремого запуску за розкладом: його може запустити успішний CI-запуск для небота після push у `main`, але він пропускається, якщо інший виклик через workflow-run уже виконався або виконується цього дня за UTC. Ручний запуск обходить цю щоденну перевірку активності. Доріжка будує згрупований звіт про продуктивність Vitest для повного набору, дозволяє Codex робити лише невеликі виправлення продуктивності тестів без втрати покриття замість масштабних рефакторингів, потім повторно запускає звіт для повного набору і відхиляє зміни, які зменшують базову кількість тестів, що проходять. Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а повний звіт після роботи агента має пройти до будь-якого коміту. Коли `main` просувається вперед до того, як push бота потрапляє в репозиторій, доріжка перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; застарілі патчі з конфліктами пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й агент документації. ```bash gh workflow run duplicate-after-merge.yml \ @@ -34,83 +34,83 @@ gh workflow run duplicate-after-merge.yml \ | Завдання | Призначення | Коли запускається | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Визначає зміни лише в docs, змінені області охоплення, змінені extensions і будує маніфест CI | Завжди для non-draft push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR | -| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для non-draft push і PR | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-доріжки коректності, як-от bundled/plugin-contract/protocol checks | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extensions | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди core Node tests, за винятком доріжок channel, bundled, contract і extension | Зміни, релевантні для Node | -| `extension-fast` | Точкові тести лише для змінених bundled plugins | Pull request із змінами в extension | -| `check` | Шардований еквівалент основного локального gate: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди архітектури, меж, guards поверхні extension, меж пакетів і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести built-CLI і smoke перевірка пам’яті під час запуску | Зміни, релевантні для Node | -| `checks` | Верифікатор для built-artifact channel tests плюс сумісність Node 22 лише для push | Зміни, релевантні для Node | -| `check-docs` | Форматування docs, lint і перевірки на биті посилання | Docs змінено | -| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні для Python Skills | -| `checks-windows` | Специфічні для Windows тестові доріжки | Зміни, релевантні для Windows | -| `macos-node` | Доріжка тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit tests для обох flavor-ів плюс одна збірка debug APK | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна Codex-оптимізація повільних тестів після довіреної активності | Успіх main CI або ручний dispatch | +| `preflight` | Виявлення змін лише в документації, змінених областей, змінених extensions і побудова CI-маніфесту | Завжди для push і PR не в режимі draft | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для push і PR не в режимі draft | +| `security-dependency-audit` | Аудит production lockfile без залежностей за advisory npm | Завжди для push і PR не в режимі draft | +| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для push і PR не в режимі draft | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовуваних downstream-артефактів | Зміни, пов’язані з Node | +| `checks-fast-core` | Швидкі Linux-доріжки коректності, такі як перевірки bundled/plugin-contract/protocol | Зміни, пов’язані з Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів channel зі стабільним агрегованим результатом | Зміни, пов’язані з Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, пов’язані з Node | +| `checks-node-core-test` | Шарди тестів ядра Node, без доріжок channel, bundled, contract і extension | Зміни, пов’язані з Node | +| `extension-fast` | Сфокусовані тести лише для змінених bundled plugins | Pull request зі змінами в extension | +| `check` | Шардований еквівалент основного локального шлюзу: production-типи, lint, guards, test types і strict smoke | Зміни, пов’язані з Node | +| `check-additional` | Архітектурні перевірки, перевірки меж, guards поверхні extension, меж пакетів і шарди gateway-watch | Зміни, пов’язані з Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка стартової пам’яті | Зміни, пов’язані з Node | +| `checks` | Верифікатор для тестів channel на зібраних артефактах плюс сумісність Node 22 лише для push | Зміни, пов’язані з Node | +| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Змінено документацію | +| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, релевантні Python Skills | +| `checks-windows` | Специфічні для Windows тестові доріжки | Зміни, релевантні Windows | +| `macos-node` | Доріжка тестів TypeScript для macOS з використанням спільних зібраних артефактів | Зміни, релевантні macOS | +| `macos-swift` | Lint, збірка і тести Swift для застосунку macOS | Зміни, релевантні macOS | +| `android` | Юніт-тести Android для обох варіантів плюс одна збірка debug APK | Зміни, релевантні Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний main CI або ручний запуск | ## Порядок Fail-Fast Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запускаються дорогі: -1. `preflight` вирішує, які доріжки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих завдань матриці artifacts і платформ. -3. `build-artifacts` перекривається з швидкими Linux-доріжками, щоб downstream-споживачі могли стартувати, щойно буде готова спільна збірка. -4. Після цього розгалужуються важчі платформні та runtime-доріжки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, PR-only `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` визначає, які доріжки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` падають швидко, не чекаючи важчих завдань із артефактами та платформенних матриць. +3. `build-artifacts` перекривається з швидкими Linux-доріжками, щоб downstream-споживачі могли стартувати, щойно спільна збірка готова. +4. Після цього розгалужуються важчі платформенні й runtime-доріжки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише-PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка охоплення міститься в `scripts/ci-changed-scope.mjs` і покрита unit tests у `src/scripts/ci-changed-scope.test.ts`. -Редагування workflow CI перевіряє граф Node CI плюс lint workflow, але саме по собі не змушує виконувати нативні збірки Windows, Android або macOS; ці платформні доріжки залишаються обмеженими змінами у вихідному коді відповідних платформ. -Перевірки Windows Node обмежені Windows-специфічними wrappers для process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цю доріжку; не пов’язані зміни у source, plugin, install-smoke і зміни лише в tests залишаються на Linux Node-доріжках, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже перевіряється звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий скрипт охоплення через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke jobs. Зміни лише в source bundled plugin, лише в tests і лише в docs не резервують Docker workers. Швидкий шлях один раз збирає образ root Dockerfile, перевіряє CLI, запускає container gateway-network e2e, перевіряє аргумент збірки bundled extension і запускає обмежений Docker profile bundled-plugin з тайм-аутом команди 120 секунд. Повний шлях зберігає покриття QR package install і installer Docker/update для нічних запусків за розкладом, ручних dispatch-ів, workflow-call перевірок релізу і pull request, які справді торкаються поверхонь installer/package/Docker. Push у `main`, включно з merge commits, не змушують повний шлях; коли логіка changed-scope вимагала б повного покриття для push, workflow залишає швидкий Docker smoke, а повний install smoke переносить на нічну або релізну валідацію. Повільний smoke для image-provider із глобальним встановленням Bun окремо обмежується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow перевірок релізу, а ручні dispatch-и `install-smoke` можуть його ввімкнути, але pull request і push у `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Локальний `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-доріжки паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типову паралельність основного пулу 8 через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а паралельність tail-pool, чутливого до provider, теж 8 — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Локальний агрегат за замовчуванням перестає планувати нові доріжки пулу після першого збою, а кожна доріжка має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Повторно використовуваний workflow live/E2E відтворює шаблон спільного image, збираючи й публікуючи один Docker E2E image із тегом SHA в GHCR перед Docker matrix, а потім запускаючи matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker suite для релізного шляху. Повна матриця bundled update/channel залишається ручною/full-suite, оскільки виконує повторні реальні проходи npm update і doctor repair. +Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покривається юніт-тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни в CI workflow перевіряють граф Node CI плюс lint workflow, але самі по собі не змушують запускати нативні збірки Windows, Android або macOS; ці платформенні доріжки й далі залишаються прив’язаними до змін у вихідному коді відповідної платформи. +Перевірки Windows Node обмежуються специфічними для Windows обгортками process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією менеджера пакетів і поверхнями CI workflow, які виконують цю доріжку; не пов’язані зміни у вихідному коді, plugins, install-smoke і зміни лише в тестах залишаються на Linux Node-доріжках, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже перевіряється звичайними шардами тестів. +Окремий workflow `install-smoke` повторно використовує той самий скрипт області дії через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін у package/manifest bundled plugins і поверхонь core plugin/channel/gateway/Plugin SDK, які використовують Docker smoke-завдання. Зміни лише у вихідному коді bundled plugins, зміни лише в тестах і зміни лише в документації не резервують Docker workers. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає container gateway-network e2e, перевіряє build arg bundled extension і запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд. Повний шлях зберігає покриття встановлення QR package і встановлювача Docker/update для нічних запусків за розкладом, ручних запусків, release checks через workflow-call і pull request, які справді зачіпають поверхні installer/package/Docker. Push у `main`, включно з merge-комітами, не примушують повний шлях; коли логіка changed-scope запитує повне покриття під час push, workflow залишає швидкий Docker smoke, а повний install smoke відкладає до нічної або релізної валідації. Повільний smoke глобального встановлення Bun image-provider окремо керується `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow перевірок релізу, а ручні запуски `install-smoke` можуть явно його увімкнути, але pull request і push у `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, зосереджені на встановленні. Локальний `test:docker:all` попередньо збирає один спільний образ live-test і один спільний образ зібраного застосунку `scripts/e2e/Dockerfile`, а потім запускає доріжки live/E2E smoke паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте стандартний паралелізм основного пулу 8 через `OPENCLAW_DOCKER_ALL_PARALLELISM` і паралелізм tail-пулу 8, чутливого до провайдерів, через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Запуски доріжок за замовчуванням зсунуті на 2 секунди, щоб уникати локальних штормів створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегат за замовчуванням припиняє планувати нові pooled-доріжки після першого збою, а кожна доріжка має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Повторно використовуваний workflow live/E2E віддзеркалює шаблон спільного образу, збираючи й публікуючи один Docker E2E-образ GHCR із тегом SHA до запуску матриці Docker, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір релізного шляху. Повна матриця bundled update/channel залишається ручною/full-suite, бо виконує повторні реальні проходи npm update і doctor repair. -Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіше ставиться до архітектурних меж, ніж широке платформне охоплення CI: зміни у production core запускають typecheck prod core плюс core tests, зміни лише в tests core запускають лише typecheck/tests для test-коду core, зміни у production extension запускають typecheck prod extension плюс extension tests, а зміни лише в tests extension запускають лише typecheck/tests для test-коду extension. Зміни в публічному Plugin SDK або plugin-contract розширюють валідацію на extension, тому що extension залежать від цих контрактів core. Зміни лише в release metadata version bump запускають точкові перевірки version/config/root-dependency. Невідомі зміни root/config безпечно переводять виконання на всі доріжки. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний шлюз суворіший щодо архітектурних меж, ніж широка платформенна область дії CI: зміни у production-коді ядра запускають typecheck core prod плюс тести ядра, зміни лише в тестах ядра запускають лише typecheck/tests core test, зміни у production-коді extension запускають typecheck extension prod плюс тести extension, а зміни лише в тестах extension запускають лише typecheck/tests extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють валідацію на extension, бо extension залежать від цих контрактів ядра. Підвищення версії лише в метаданих релізу запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config для безпеки запускають усі доріжки. -Для push матриця `checks` додає доріжку `compat-node22`, що запускається лише для push. Для pull request ця доріжка пропускається, і матриця зосереджується на звичайних test/channel-доріжках. +Для push матриця `checks` додає доріжку `compat-node22`, яка запускається лише для push. Для pull request цю доріжку пропускають, і матриця залишається зосередженою на звичайних доріжках тестів/channel. -Найповільніші сімейства Node tests розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts виконуються у трьох зважених shards, bundled plugin tests балансуються між шістьма worker-ами extension, малі core unit lanes об’єднані в пари, auto-reply працює у трьох збалансованих worker-ах замість шести крихітних worker-ів, а agentic gateway/plugin configs розподілені між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі browser, QA, media та різні plugin tests використовують свої окремі конфігурації Vitest замість спільного універсального plugin catch-all. Завдання shard для extension запускають групи конфігурацій plugin послідовно з одним worker-ом Vitest і більшим Node heap, щоб batch-і plugin з великим обсягом імпортів не перевантажували малі CI runner-и. Широка доріжка agents використовує спільний планувальник файлового паралелізму Vitest, оскільки в ній домінують імпорти/планування, а не один повільний test file. `runtime-config` запускається разом із shard `infra core-runtime`, щоб спільний shard runtime не замикався на хвості. `check-additional` тримає compile/canary-роботи для меж пакетів разом і відокремлює архітектуру топології runtime від покриття gateway watch; shard boundary guard виконує свої малі незалежні guards паралельно всередині одного завдання. Gateway watch, channel tests і shard support-boundary core виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи свої старі назви check як легковагі verifier-завдання й водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів artifacts. +Найповільніші сімейства тестів Node розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти channel запускаються у трьох зважених шардах, тести bundled plugin балансуються між шістьма worker-ами extension, невеликі core unit-доріжки об’єднані в пари, auto-reply виконується у трьох збалансованих worker-ах замість шести дрібних worker-ів, а агентні конфігурації gateway/plugin розподіляються між наявними source-only агентними Node-завданнями замість очікування на зібрані артефакти. Широкі тести browser, QA, media і різних plugins використовують свої окремі конфігурації Vitest замість спільної універсальної конфігурації plugin. Завдання шард extension запускають групи конфігурацій plugin послідовно з одним worker-ом Vitest і більшим heap Node, щоб пакети plugin з великим імпортом не перевантажували невеликі CI runner-и. Широка доріжка agents використовує спільний file-parallel scheduler Vitest, тому що в ній домінують імпорт/планування, а не один повільний тестовий файл. `runtime-config` запускається разом із шардом infra core-runtime, щоб спільний runtime-шард не залишався найповільнішим. `check-additional` тримає compile/canary-роботи меж пакетів разом і відокремлює архітектуру topology runtime від покриття gateway watch; шард boundary guard запускає свої невеликі незалежні guards паралельно в межах одного завдання. Gateway watch, тести channel і core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі імена перевірок як легковагі завдання-верифікатори, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого набору source або manifest; його доріжка unit tests усе одно компілює цей flavor з прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK на кожному push, релевантному для Android. -`extension-fast` є лише для PR, тому що push-запуски вже виконують повні shard-и bundled plugin. Це зберігає швидкий зворотний зв’язок щодо змінених plugin для рев’ю, не резервуючи додатковий Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Варіант third-party не має окремого source set або manifest; його доріжка юніт-тестів усе одно компілює цей варіант із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK для кожного push, релевантного Android. +`extension-fast` доступний лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок для змінених plugins під час review, не резервуючи додатковий Blacksmith worker у `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати замінені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо лише найновіший запуск для того самого ref також не падає. Агреговані shard checks використовують `!cancelled() && always()`, тож вони все ще повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже було замінено. -Ключ concurrency у CI має версіонування (`CI-v7-*`), щоб zombie на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. +GitHub може позначати замінені новішими завдання як `cancelled`, коли новіший push потрапляє в той самий ref PR або `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений новішим. +Ключ паралельності CI має версіонування (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. ## Runner-и -| Runner | Завдання | -| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled checks, шардовані перевірки channel contract, shard-и `check`, крім lint, shard-и та агрегати `check-additional`, aggregate verifier-и Node tests, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard-и Linux Node tests, shard-и bundled plugin tests, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, так що 8 vCPU коштували більше, ніж дали вигоди; Docker builds для install-smoke, де час очікування в черзі для 32 vCPU коштував більше, ніж давав вигоди | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; fork-и повертаються до `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; fork-и повертаються до `macos-latest` | +| Runner | Завдання | +| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів channel, шарди `check`, крім lint, шарди й агрегати `check-additional`, агреговані верифікатори тестів Node, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди тестів Linux Node, шарди тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який і далі достатньо чутливий до CPU, тож 8 vCPU коштували дорожче, ніж дали користі; Docker-збірки install-smoke, де вартість часу очікування в черзі для 32 vCPU була вищою, ніж користь | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; fork-репозиторії повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; fork-репозиторії повертаються до `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane -pnpm check # швидкий локальний gate: production tsgo + шардований lint + паралельні швидкі guards +pnpm check:changed # розумний локальний шлюз: змінені typecheck/lint/tests за доріжкою меж +pnpm check # швидкий локальний шлюз: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # той самий gate з таймінгами для кожного етапу +pnpm check:timed # той самий шлюз із таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування docs + lint + биті посилання -pnpm build # збірка dist, коли мають значення доріжки CI artifact/build-smoke -node scripts/ci-run-timings.mjs # зведення wall time, queue time і найповільніших завдань -node scripts/ci-run-timings.mjs --recent 10 # порівняння недавніх успішних запусків main CI +pnpm check:docs # форматування документації + lint + зламані посилання +pnpm build # зібрати dist, коли важливі доріжки CI artifact/build-smoke +node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі та найповільніші завдання +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні main CI-запуски pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` diff --git a/docs/uk/gateway/troubleshooting.md b/docs/uk/gateway/troubleshooting.md index fdee7e271..ed1ae567c 100644 --- a/docs/uk/gateway/troubleshooting.md +++ b/docs/uk/gateway/troubleshooting.md @@ -1,26 +1,26 @@ --- read_when: - - Центр усунення проблем направив вас сюди для глибшої діагностики - - Вам потрібні стабільні розділи runbook на основі симптомів із точними командами -summary: Докладний runbook з усунення проблем для gateway, каналів, автоматизації, Node і браузера -title: Усунення проблем + - Центр усунення несправностей направив вас сюди для глибшої діагностики + - Вам потрібні стабільні розділи посібника з усунення несправностей, побудовані за симптомами, з точними командами +summary: Поглиблений посібник з усунення несправностей для Gateway, каналів, автоматизації, Node і браузера +title: Усунення несправностей x-i18n: - generated_at: "2026-04-24T03:44:54Z" + generated_at: "2026-04-24T07:42:15Z" model: gpt-5.4 provider: openai - source_hash: 32c4cbbbe8b1cd5eaca34503f4a363d3fa2650e491f83455958eb5725f9d50c5 + source_hash: 20066bdab03f05304b3a620fbadc38e4dc74b740da151c58673dcf5196e5f1e1 source_path: gateway/troubleshooting.md workflow: 15 --- -# Усунення проблем Gateway +# Усунення несправностей Gateway -Ця сторінка — докладний runbook. -Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спершу хочете швидкий потік triage. +Ця сторінка — поглиблений посібник з усунення несправностей. +Почніть із [/help/troubleshooting](/uk/help/troubleshooting), якщо спочатку хочете пройти швидкий потік тріажу. -## Послідовність команд +## Сходинки команд -Запустіть спочатку їх, у такому порядку: +Спочатку виконайте ці команди в такому порядку: ```bash openclaw status @@ -30,14 +30,14 @@ openclaw doctor openclaw channels status --probe ``` -Очікувані ознаки здорового стану: +Очікувані ознаки справного стану: - `openclaw gateway status` показує `Runtime: running`, `Connectivity probe: ok` і рядок `Capability: ...`. -- `openclaw doctor` не повідомляє про блокувальні проблеми config/сервісу. +- `openclaw doctor` не повідомляє про блокувальні проблеми конфігурації/сервісу. - `openclaw channels status --probe` показує живий стан транспорту для кожного облікового запису і, де це підтримується, результати probe/audit, як-от `works` або `audit ok`. -## Anthropic 429: extra usage required for long context +## Додаткове використання Anthropic 429 потрібне для довгого контексту Використовуйте це, коли журнали/помилки містять: `HTTP 429: rate_limit_error: Extra usage is required for long context requests`. @@ -48,17 +48,17 @@ openclaw models status openclaw config get agents.defaults.models ``` -Звертайте увагу на таке: +Шукайте: - Вибрана модель Anthropic Opus/Sonnet має `params.context1m: true`. -- Поточні облікові дані Anthropic не мають права на long-context usage. -- Запити завершуються помилкою лише в довгих сесіях/запусках моделей, яким потрібен шлях 1M beta. +- Поточні облікові дані Anthropic не мають права на використання довгого контексту. +- Запити падають лише під час довгих сесій/запусків моделі, яким потрібен бета-шлях 1M. Варіанти виправлення: -1. Вимкніть `context1m` для цієї моделі, щоб перейти до звичайного вікна контексту. -2. Використайте облікові дані Anthropic, які мають право на long-context requests, або перейдіть на API key Anthropic. -3. Налаштуйте fallback models, щоб запуски тривали, коли Anthropic відхиляє long-context requests. +1. Вимкніть `context1m` для цієї моделі, щоб повернутися до звичайного вікна контексту. +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-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic](/uk/help/faq-first-run#why-am-i-seeing-http-429-ratelimiterror-from-anthropic) -## Локальний OpenAI-compatible backend проходить прямі probes, але запуски агента завершуються помилкою +## Локальний OpenAI-сумісний backend проходить прямі probe, але запуски агентів падають Використовуйте це, коли: - `curl ... /v1/models` працює - малі прямі виклики `/v1/chat/completions` працюють -- запуски моделей OpenClaw завершуються помилкою лише на звичайних ходах агента +- запуски моделей OpenClaw падають лише під час звичайних ходів агента ```bash curl http://127.0.0.1:1234/v1/models @@ -83,35 +83,36 @@ openclaw infer model run --model --prompt "hi" --json openclaw logs --follow ``` -Звертайте увагу на таке: +Шукайте: -- прямі малі виклики успішні, але запуски OpenClaw завершуються помилкою лише на більших prompt +- прямі малі виклики успішні, але запуски OpenClaw падають лише на більших запитах - помилки backend про те, що `messages[].content` очікує рядок -- збої backend, які з’являються лише з більшими значеннями prompt-token або з повними - prompt runtime агента +- збої backend, які з’являються лише з більшою кількістю токенів у запиті або з повними + запитами середовища виконання агента Поширені ознаки: - `messages[...].content: invalid type: sequence, expected a string` → backend - відхиляє структуровані частини content у Chat Completions. Виправлення: задайте + відхиляє структуровані частини вмісту Chat Completions. Виправлення: встановіть `models.providers..models[].compat.requiresStringContent: true`. -- прямі малі запити успішні, але запуски агента OpenClaw завершуються збоями backend/model +- прямі малі запити успішні, але запуски агентів OpenClaw падають через збої backend/моделі (наприклад, Gemma у деяких збірках `inferrs`) → транспорт OpenClaw, - імовірно, уже налаштовано правильно; збій відбувається через більшу форму - prompt runtime агента. -- збої зменшуються після вимкнення tools, але не зникають → схеми tools були - частиною навантаження, але решта проблеми все ще є upstream-обмеженням моделі/сервера - або помилкою backend. + імовірно, уже налаштований правильно; backend падає через форму більшого + запиту середовища виконання агента. +- після вимкнення інструментів збоїв меншає, але вони не зникають → схеми інструментів + були частиною навантаження, але решта проблеми все ще лежить у вищестоячій + місткості моделі/сервера або в помилці backend. Варіанти виправлення: -1. Задайте `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядки. -2. Задайте `compat.supportsTools: false` для моделей/backend, які не можуть надійно - обробляти поверхню схеми tools OpenClaw. -3. Де можливо, зменште навантаження prompt: менший bootstrap workspace, коротша - історія сесії, легша локальна модель або backend із кращою підтримкою long-context. -4. Якщо малі прямі запити й далі проходять, а ходи агента OpenClaw все ще спричиняють збій - усередині backend, вважайте це upstream-обмеженням сервера/моделі й подайте туди repro з прийнятою формою payload. +1. Встановіть `compat.requiresStringContent: true` для backend Chat Completions, які підтримують лише рядки. +2. Встановіть `compat.supportsTools: false` для моделей/backend, які не можуть + надійно обробляти поверхню схем інструментів OpenClaw. +3. За можливості зменште навантаження запиту: менший bootstrap робочого простору, коротша + історія сесії, легша локальна модель або backend із кращою підтримкою довгого контексту. +4. Якщо малі прямі запити й далі проходять, а ходи агентів OpenClaw все ще падають + усередині backend, розглядайте це як обмеження вищестоячого сервера/моделі й + подайте туди відтворюваний приклад із прийнятою формою payload. Пов’язане: @@ -121,7 +122,7 @@ openclaw logs --follow ## Немає відповідей -Якщо канали працюють, але нічого не відповідає, перевірте маршрутизацію та політику, перш ніж щось перепідключати. +Якщо канали підняті, але ніхто не відповідає, перевірте маршрутизацію та політики, перш ніж щось перепідключати. ```bash openclaw status @@ -131,16 +132,16 @@ openclaw config get channels openclaw logs --follow ``` -Звертайте увагу на таке: +Шукайте: -- Для відправників DM очікується pairing. -- Обмеження згадками в групах (`requireMention`, `mentionPatterns`). +- Pairing у стані очікування для відправників у DM. +- Вимогу згадки в групі (`requireMention`, `mentionPatterns`). - Невідповідності allowlist каналу/групи. Поширені ознаки: -- `drop guild message (mention required` → групове повідомлення ігнорується, доки немає згадки. -- `pairing request` → відправник потребує підтвердження. +- `drop guild message (mention required` → повідомлення групи ігнорується, доки немає згадки. +- `pairing request` → відправнику потрібне схвалення. - `blocked` / `allowlist` → відправника/канал було відфільтровано політикою. Пов’язане: @@ -151,7 +152,7 @@ openclaw logs --follow ## Підключення dashboard/control UI -Коли dashboard/control UI не підключається, перевірте URL, режим auth і припущення щодо secure context. +Коли dashboard/control UI не може підключитися, перевірте URL, режим автентифікації та припущення щодо безпечного контексту. ```bash openclaw gateway status @@ -161,48 +162,49 @@ openclaw doctor openclaw gateway status --json ``` -Звертайте увагу на таке: +Шукайте: -- Правильний probe URL і dashboard URL. -- Невідповідність режиму auth/token між клієнтом і gateway. -- Використання HTTP там, де потрібна device identity. +- Правильний URL probe і URL dashboard. +- Невідповідність режиму автентифікації/токена між клієнтом і Gateway. +- Використання HTTP там, де потрібна ідентичність пристрою. Поширені ознаки: -- `device identity required` → non-secure context або відсутня device auth. +- `device identity required` → небезпечний контекст або відсутня автентифікація пристрою. - `origin not allowed` → `Origin` браузера відсутній у `gateway.controlUi.allowedOrigins` - (або ви підключаєтесь із non-loopback browser origin без явного + (або ви підключаєтеся з не-loopback browser origin без явного allowlist). - `device nonce required` / `device nonce mismatch` → клієнт не завершує - challenge-based потік device auth (`connect.challenge` + `device.nonce`). + challenge-based потік автентифікації пристрою (`connect.challenge` + `device.nonce`). - `device signature invalid` / `device signature expired` → клієнт підписав неправильний - payload (або з застарілим timestamp) для поточного handshake. -- `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим device token. -- Ця повторна спроба з кешованим token повторно використовує кешований набір scope, збережений разом із paired - device token. Виклики з явним `deviceToken` / явними `scopes` зберігають свій + payload (або використав застарілу часову мітку) для поточного рукостискання. +- `AUTH_TOKEN_MISMATCH` з `canRetryWithDeviceToken=true` → клієнт може виконати одну довірену повторну спробу з кешованим токеном пристрою. +- Ця повторна спроба з кешованим токеном повторно використовує кешований набір scope, збережений разом + із paired device token. Виклики з явними `deviceToken` / явними `scopes` зберігають свій запитаний набір scope. -- Поза цим шляхом повторної спроби пріоритет connect auth такий: спочатку явний shared - token/password, потім явний `deviceToken`, потім збережений device token, +- Поза цим шляхом повторної спроби пріоритет автентифікації під час підключення такий: спочатку явний shared + token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого - `{scope, ip}` серіалізуються до того, як лімітер зафіксує невдачу. Тому дві некоректні + `{scope, ip}` серіалізуються до того, як обмежувач зафіксує невдачу. Тому дві некоректні одночасні повторні спроби від того самого клієнта можуть дати `retry later` на другій спробі замість двох звичайних невідповідностей. - `too many failed authentication attempts (retry later)` від loopback-клієнта з browser-origin - → повторні невдачі від того самого нормалізованого `Origin` тимчасово блокуються; інший localhost origin використовує окремий bucket. -- повторюване `unauthorized` після такої повторної спроби → розсинхронізація shared token/device token; оновіть config token і повторно підтвердьте/перевипустіть device token за потреби. -- `gateway connect failed:` → неправильний host/port/url цілі. + → повторні невдалі спроби з того самого нормалізованого `Origin` тимчасово + блокуються; інший localhost origin використовує окремий bucket. +- повторюваний `unauthorized` після цієї повторної спроби → розсинхронізація shared token/device token; оновіть конфігурацію токена та за потреби знову схваліть/перевипустіть токен пристрою. +- `gateway connect failed:` → неправильний хост/порт/url призначення. -### Швидка мапа кодів деталей auth +### Швидка мапа кодів деталей автентифікації -Використовуйте `error.details.code` з невдалої відповіді `connect`, щоб вибрати наступну дію: +Використовуйте `error.details.code` із невдалої відповіді `connect`, щоб вибрати наступну дію: -| Код деталей | Значення | Рекомендована дія | -| ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий shared token. | Вставте/задайте token у клієнті й повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, потім вставте його в налаштуваннях Control UI. | -| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з token auth gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим token повторно використовують збережені підтверджені scopes; виклики з явним `deviceToken` / `scopes` зберігають запитаний набір scopes. Якщо збій лишається, виконайте [контрольний список відновлення після розсинхронізації token](/uk/cli/devices#token-drift-recovery-checklist). | -| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований token на пристрої застарів або відкликаний. | Перевипустіть/повторно підтвердьте device token через [CLI devices](/uk/cli/devices), потім підключіться знову. | -| `PAIRING_REQUIRED` | Device identity потребує підтвердження. Перевірте `error.details.reason` на `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade` і використовуйте `requestId` / `remediationHint`, якщо вони присутні. | Підтвердьте очікуваний запит: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/role використовують той самий потік після того, як ви переглянете запитаний доступ. | +| Код деталей | Значення | Рекомендована дія | +| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AUTH_TOKEN_MISSING` | Клієнт не надіслав обов’язковий shared token. | Вставте/задайте токен у клієнті та повторіть спробу. Для шляхів dashboard: `openclaw config get gateway.auth.token`, а потім вставте його в налаштуваннях Control UI. | +| `AUTH_TOKEN_MISMATCH` | Shared token не збігся з токеном автентифікації Gateway. | Якщо `canRetryWithDeviceToken=true`, дозвольте одну довірену повторну спробу. Повторні спроби з кешованим токеном повторно використовують збережені схвалені scope; виклики з явними `deviceToken` / `scopes` зберігають запитаний scope. Якщо все одно не працює, виконайте [контрольний список відновлення після розсинхронізації токена](/uk/cli/devices#token-drift-recovery-checklist). | +| `AUTH_DEVICE_TOKEN_MISMATCH` | Кешований токен для конкретного пристрою застарів або був відкликаний. | Перевипустіть/повторно схваліть токен пристрою за допомогою [CLI пристроїв](/uk/cli/devices), а потім перепідключіться. | +| `PAIRING_REQUIRED` | Ідентичність пристрою потребує схвалення. Перевірте `error.details.reason` для `not-paired`, `scope-upgrade`, `role-upgrade` або `metadata-upgrade`, і використовуйте `requestId` / `remediationHint`, якщо вони є. | Схваліть запит, що очікує: `openclaw devices list`, потім `openclaw devices approve `. Оновлення scope/ролей використовують той самий потік після того, як ви перевірите запитаний доступ. | Перевірка міграції device auth v2: @@ -216,24 +218,24 @@ openclaw gateway status 1. чекає на `connect.challenge` 2. підписує payload, прив’язаний до challenge -3. надсилає `connect.params.device.nonce` з тим самим challenge nonce +3. надсилає `connect.params.device.nonce` з тим самим nonce challenge -Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано відхиляється: +Якщо `openclaw devices rotate` / `revoke` / `remove` неочікувано заборонено: - сесії paired-device token можуть керувати лише **власним** пристроєм, якщо - виклик також не має `operator.admin` -- `openclaw devices rotate --scope ...` може запитувати лише ті operator scopes, - які сесія виклику вже має + викликальник також не має `operator.admin` +- `openclaw devices rotate --scope ...` може запитувати лише ті operator scope, + які сесія викликальника вже має Пов’язане: - [/web/control-ui](/uk/web/control-ui) -- [/gateway/configuration](/uk/gateway/configuration) (режими auth gateway) +- [/gateway/configuration](/uk/gateway/configuration) (режими автентифікації gateway) - [/gateway/trusted-proxy-auth](/uk/gateway/trusted-proxy-auth) - [/gateway/remote](/uk/gateway/remote) - [/cli/devices](/uk/cli/devices) -## Сервіс Gateway не працює +## Сервіс Gateway не запущено Використовуйте це, коли сервіс установлено, але процес не залишається запущеним. @@ -242,23 +244,23 @@ 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 сервісу (`Config (cli)` vs `Config (service)`). -- Конфлікти port/listener. +- `Runtime: stopped` із підказками щодо завершення. +- Невідповідність конфігурації сервісу (`Config (cli)` vs `Config (service)`). +- Конфлікти портів/слухачів. - Додаткові встановлення launchd/systemd/schtasks, коли використовується `--deep`. - Підказки очищення `Other gateway-like services detected (best effort)`. Поширені ознаки: -- `Gateway start blocked: set gateway.mode=local` або `existing config is missing gateway.mode` → локальний режим gateway не ввімкнено, або файл config було пошкоджено й він втратив `gateway.mode`. Виправлення: задайте `gateway.mode="local"` у вашому config або повторно запустіть `openclaw onboard --mode local` / `openclaw setup`, щоб знову проставити очікуваний config локального режиму. Якщо ви запускаєте OpenClaw через Podman, типовий шлях до config — `~/.openclaw/openclaw.json`. -- `refusing to bind gateway ... without auth` → прив’язка до non-loopback без коректного шляху auth gateway (token/password або trusted-proxy, де налаштовано). +- `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)` → існують застарілі або паралельні units launchd/systemd/schtasks. У більшості налаштувань має бути один gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). +- `Other gateway-like services detected (best effort)` → існують застарілі або паралельні launchd/systemd/schtasks units. У більшості конфігурацій слід мати один Gateway на машину; якщо вам справді потрібно більше одного, ізолюйте порти + config/state/workspace. Див. [/gateway#multiple-gateways-same-host](/uk/gateway#multiple-gateways-same-host). Пов’язане: @@ -266,9 +268,9 @@ openclaw gateway status --deep # також сканувати системн - [/gateway/configuration](/uk/gateway/configuration) - [/gateway/doctor](/uk/gateway/doctor) -## Gateway відновив last-known-good config +## Gateway відновив останню відому справну конфігурацію -Використовуйте це, коли Gateway запускається, але журнали повідомляють, що він відновив `openclaw.json`. +Використовуйте це, коли Gateway запускається, але в журналах сказано, що він відновив `openclaw.json`. ```bash openclaw logs --follow @@ -277,22 +279,22 @@ openclaw config validate 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 -- системна подія головного агента, що починається з `Config recovery warning` +- Файл `openclaw.json.clobbered.*` із часовою міткою поруч з активною конфігурацією +- Системну подію головного агента, що починається з `Config recovery warning` Що сталося: -- Відхилений config не пройшов validate під час запуску або hot reload. +- Відхилена конфігурація не пройшла валідацію під час запуску або гарячого перезавантаження. - OpenClaw зберіг відхилений payload як `.clobbered.*`. -- Активний config було відновлено з останньої перевіреної last-known-good копії. -- Наступний хід головного агента отримає попередження не перезаписувати відхилений config бездумно. +- Активну конфігурацію було відновлено з останньої перевіреної справної копії. +- На наступному ході головного агента з’явиться попередження не переписувати відхилену конфігурацію навмання. -Перевірка й виправлення: +Перевірка та виправлення: ```bash CONFIG="$(openclaw config file)" @@ -304,18 +306,18 @@ openclaw doctor Поширені ознаки: -- існує `.clobbered.*` → було відновлено зовнішнє пряме редагування або читання під час запуску. -- існує `.rejected.*` → запис config, ініційований OpenClaw, не пройшов перевірки schema або clobber перед commit. -- `Config write rejected:` → запис намагався прибрати обов’язкову структуру, різко зменшити файл або зберегти невалідний config. -- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → під час запуску поточний файл було розцінено як clobbered, бо він втратив поля або розмір порівняно з резервною last-known-good копією. -- `Config last-known-good promotion skipped` → кандидат містив замасковані placeholders секретів, як-от `***`. +- існує `.clobbered.*` → зовнішнє пряме редагування або читання під час запуску було відновлено. +- існує `.rejected.*` → запис конфігурації, що належав OpenClaw, не пройшов перевірку схеми або clobber-перевірки перед фіксацією. +- `Config write rejected:` → запис намагався прибрати обов’язкову структуру, різко зменшити файл або зберегти недійсну конфігурацію. +- `missing-meta-vs-last-good`, `gateway-mode-missing-vs-last-good` або `size-drop-vs-last-good:*` → під час запуску поточний файл було визнано пошкодженим, оскільки він утратив поля або розмір порівняно з останньою відомою справною резервною копією. +- `Config last-known-good promotion skipped` → кандидат містив замасковані плейсхолдери секретів, як-от `***`. Варіанти виправлення: -1. Залиште відновлений активний config, якщо він правильний. +1. Залиште відновлену активну конфігурацію, якщо вона правильна. 2. Скопіюйте лише потрібні ключі з `.clobbered.*` або `.rejected.*`, а потім застосуйте їх через `openclaw config set` або `config.patch`. 3. Запустіть `openclaw config validate` перед перезапуском. -4. Якщо ви редагуєте вручну, зберігайте повний JSON5 config, а не лише частковий об’єкт, який хотіли змінити. +4. Якщо редагуєте вручну, зберігайте повний JSON5 config, а не лише частковий об’єкт, який хотіли змінити. Пов’язане: @@ -326,7 +328,7 @@ openclaw doctor ## Попередження probe Gateway -Використовуйте це, коли `openclaw gateway probe` до чогось дістається, але все одно друкує блок попередження. +Використовуйте це, коли `openclaw gateway probe` до чогось достукується, але все одно виводить блок попереджень. ```bash openclaw gateway probe @@ -334,18 +336,18 @@ openclaw gateway probe --json openclaw gateway probe --ssh user@gateway-host ``` -Звертайте увагу на таке: +Шукайте: -- `warnings[].code` і `primaryTargetId` у виводі JSON. -- Чи стосується попередження SSH fallback, кількох gateways, відсутніх scopes або невизначених auth refs. +- `warnings[].code` і `primaryTargetId` у JSON-виводі. +- Чи стосується попередження резервного переходу на SSH, кількох Gateway, відсутніх scope або нерозв’язаних auth refs. Поширені ознаки: -- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback targets. -- `multiple reachable gateways detected` → відповіло більше однієї цілі. Зазвичай це означає навмисне налаштування з кількома gateways або застарілі/дубльовані listeners. -- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежено scopes; підключіть device identity або використайте облікові дані з `operator.read`. -- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → gateway відповів, але цьому клієнту все ще потрібні pairing/підтвердження перед звичайним доступом оператора. -- текст попередження про невизначені `gateway.auth.*` / `gateway.remote.*` SecretRef → auth material був недоступний у цьому шляху команди для цілі, що не вдалася. +- `SSH tunnel failed to start; falling back to direct probes.` → налаштування SSH не вдалося, але команда все одно спробувала прямі налаштовані/loopback цілі. +- `multiple reachable gateways detected` → відповіла більше ніж одна ціль. Зазвичай це означає навмисну конфігурацію з кількома Gateway або застарілі/дубльовані listeners. +- `Read-probe diagnostics are limited by gateway scopes (missing operator.read)` → підключення спрацювало, але detail RPC обмежений scope; виконайте pair device identity або використайте облікові дані з `operator.read`. +- `Capability: pairing-pending` або `gateway closed (1008): pairing required` → Gateway відповів, але цьому клієнту все ще потрібне pairing/схвалення перед звичайним operator access. +- нерозв’язаний текст попередження `gateway.auth.*` / `gateway.remote.*` SecretRef → auth material був недоступний у цьому шляху команди для цілі, що не вдалася. Пов’язане: @@ -355,7 +357,7 @@ openclaw gateway probe --ssh user@gateway-host ## Канал підключений, але повідомлення не проходять -Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і правилах доставки, специфічних для каналу. +Якщо стан каналу — connected, але потік повідомлень не працює, зосередьтеся на політиці, дозволах і специфічних для каналу правилах доставки. ```bash openclaw channels status --probe @@ -365,17 +367,17 @@ openclaw logs --follow openclaw config get channels ``` -Звертайте увагу на таке: +Шукайте: -- Політика DM (`pairing`, `allowlist`, `open`, `disabled`). -- Allowlist груп і вимоги до згадок. +- Політику DM (`pairing`, `allowlist`, `open`, `disabled`). +- Allowlist групи та вимоги щодо згадки. - Відсутні дозволи/scopes API каналу. Поширені ознаки: -- `mention required` → повідомлення ігнорується через політику згадок у групі. -- `pairing` / сліди очікуваного підтвердження → відправника не підтверджено. -- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема auth/дозволів каналу. +- `mention required` → повідомлення проігноровано політикою згадок у групі. +- `pairing` / сліди очікування схвалення → відправника не схвалено. +- `missing_scope`, `not_in_channel`, `Forbidden`, `401/403` → проблема автентифікації/дозволів каналу. Пов’язане: @@ -386,7 +388,7 @@ openclaw config get channels ## Доставка Cron і Heartbeat -Якщо Cron або Heartbeat не запустився чи не доставився, спершу перевірте стан scheduler, а потім ціль доставки. +Якщо Cron або Heartbeat не запустився чи не доставився, спочатку перевірте стан планувальника, а потім ціль доставки. ```bash openclaw cron status @@ -396,21 +398,21 @@ openclaw system heartbeat last openclaw logs --follow ``` -Звертайте увагу на таке: +Шукайте: -- Cron увімкнено і присутній наступний wake. -- Статус історії запусків job (`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` → збій tick scheduler; перевірте помилки file/log/runtime. +- `cron: timer tick failed` → збій тіку планувальника; перевірте помилки файлів/журналів/runtime. - `heartbeat skipped` з `reason=quiet-hours` → поза вікном активних годин. - `heartbeat skipped` з `reason=empty-heartbeat-file` → `HEARTBEAT.md` існує, але містить лише порожні рядки / заголовки markdown, тому OpenClaw пропускає виклик моделі. -- `heartbeat skipped` з `reason=no-tasks-due` → `HEARTBEAT.md` містить блок `tasks:`, але жодне із завдань не має виконуватися під час цього tick. -- `heartbeat: unknown accountId` → невалідний account id для цілі доставки Heartbeat. -- `heartbeat skipped` з `reason=dm-blocked` → ціль Heartbeat визначилася як призначення у стилі DM, тоді як `agents.defaults.heartbeat.directPolicy` (або перевизначення для окремого агента) має значення `block`. +- `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`. Пов’язане: @@ -418,9 +420,9 @@ openclaw logs --follow - [/automation/cron-jobs](/uk/automation/cron-jobs) - [/gateway/heartbeat](/uk/gateway/heartbeat) -## Інструмент paired Node завершується помилкою +## Збій інструмента спареного Node -Якщо Node підключений, але tools не працюють, ізолюйте стан foreground, дозволів і підтверджень. +Якщо Node спарено, але інструменти не працюють, ізолюйте стан foreground, дозволів і схвалення. ```bash openclaw nodes status @@ -430,17 +432,17 @@ openclaw logs --follow openclaw status ``` -Звертайте увагу на таке: +Шукайте: -- Node online з очікуваними capabilities. -- Надані дозволи ОС для camera/mic/location/screen. -- Стан exec approvals і allowlist. +- Node онлайн з очікуваними capability. +- Надані на рівні ОС дозволи для camera/mic/location/screen. +- Стан схвалень exec і allowlist. Поширені ознаки: -- `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути на передньому плані. +- `NODE_BACKGROUND_UNAVAILABLE` → застосунок Node має бути у foreground. - `*_PERMISSION_REQUIRED` / `LOCATION_PERMISSION_REQUIRED` → бракує дозволу ОС. -- `SYSTEM_RUN_DENIED: approval required` → очікується exec approval. +- `SYSTEM_RUN_DENIED: approval required` → очікується схвалення exec. - `SYSTEM_RUN_DENIED: allowlist miss` → команду заблоковано через allowlist. Пов’язане: @@ -449,9 +451,9 @@ openclaw status - [/nodes/index](/uk/nodes/index) - [/tools/exec-approvals](/uk/tools/exec-approvals) -## Помилка browser tool +## Збій інструмента браузера -Використовуйте це, коли дії browser tool завершуються помилкою, хоча сам gateway працює нормально. +Використовуйте це, коли дії browser tool не працюють, хоча сам Gateway справний. ```bash openclaw browser status @@ -461,33 +463,35 @@ openclaw logs --follow openclaw doctor ``` -Звертайте увагу на таке: +Шукайте: -- Чи задано `plugins.allow` і чи містить він `browser`. -- Коректний шлях до виконуваного файла браузера. +- Чи встановлено `plugins.allow` і чи містить він `browser`. +- Чинний шлях до виконуваного файла браузера. - Досяжність профілю CDP. - Доступність локального Chrome для профілів `existing-session` / `user`. Поширені ознаки: -- `unknown command "browser"` або `unknown command 'browser'` → вбудований Plugin browser виключено через `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 браузера, увімкніть remote debugging, залиште браузер відкритим, підтвердьте перший запит на приєднання, а потім повторіть спробу. Якщо стан входу не потрібен, віддавайте перевагу керованому профілю `openclaw`. +- `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 браузера, увімкніть 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-only немає досяжної цілі, або HTTP endpoint відповів, але Webhook CDP усе одно не вдалося відкрити. -- `Playwright is not available in this gateway build; '' is unsupported.` → поточне встановлення gateway не має залежності runtime `playwright-core` вбудованого browser Plugin; запустіть `openclaw doctor --fix`, а потім перезапустіть gateway. Знімки ARIA і базові screenshot сторінки все ще можуть працювати, але навігація, AI snapshots, screenshot елементів за CSS-селекторами й експорт PDF залишаться недоступними. -- `fullPage is not supported for element screenshots` → запит screenshot поєднав `--full-page` з `--ref` або `--element`. -- `element screenshots are not supported for existing-session profiles; use ref from snapshot.` → виклики screenshot Chrome MCP / `existing-session` мають використовувати захоплення сторінки або snapshot `--ref`, а не CSS `--element`. -- `existing-session file uploads do not support element selectors; use ref/inputRef.` → hooks завантаження файлів Chrome MCP потребують snapshot refs, а не CSS selectors. -- `existing-session file uploads currently support one file at a time.` → надсилайте одне завантаження за виклик у профілях Chrome MCP. -- `existing-session dialog handling does not support timeoutMs.` → hooks діалогів у профілях Chrome MCP не підтримують перевизначення timeout. -- `response body is not supported for existing-session profiles yet.` → `responsebody` усе ще потребує керованого браузера або профілю raw CDP. -- застарілі перевизначення viewport / dark-mode / locale / offline у профілях attach-only або remote CDP → запустіть `openclaw browser stop --browser-profile `, щоб закрити активну сесію керування й звільнити стан емуляції Playwright/CDP без перезапуску всього gateway. +- `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` → профіль лише для приєднання не має досяжної цілі, або 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 refs, а не 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. +- `existing-session type does not support timeoutMs overrides.` → не вказуйте `timeoutMs` для `act:type` у профілях `profile="user"` / Chrome MCP existing-session, або використайте керований/CDP профіль браузера, коли потрібен власний timeout. +- `existing-session evaluate does not support timeoutMs overrides.` → не вказуйте `timeoutMs` для `act:evaluate` у профілях `profile="user"` / Chrome MCP existing-session, або використайте керований/CDP профіль браузера, коли потрібен власний timeout. +- `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. Пов’язане: @@ -496,9 +500,9 @@ openclaw doctor ## Якщо ви оновилися і щось раптово зламалося -Більшість проблем після оновлення — це дрейф config або застосування суворіших значень за замовчуванням. +Більшість збоїв після оновлення — це розсинхронізація конфігурації або суворіші типові значення, які тепер примусово застосовуються. -### 1) Змінилася поведінка auth і перевизначення URL +### 1) Змінилася поведінка перевизначення auth і URL ```bash openclaw gateway status @@ -509,15 +513,15 @@ openclaw config get gateway.auth.mode Що перевірити: -- Якщо `gateway.mode=remote`, виклики CLI можуть звертатися до remote, тоді як ваш локальний сервіс працює нормально. -- Явні виклики `--url` не використовують резервні збережені облікові дані. +- Якщо `gateway.mode=remote`, виклики CLI можуть бути спрямовані на віддалену ціль, тоді як локальний сервіс працює нормально. +- Явні виклики `--url` не використовують збережені облікові дані як резервний варіант. Поширені ознаки: -- `gateway connect failed:` → неправильна URL-ціль. -- `unauthorized` → endpoint досяжний, але auth неправильна. +- `gateway connect failed:` → неправильний URL цілі. +- `unauthorized` → endpoint досяжний, але auth неправильний. -### 2) Обмеження bind і auth стали суворішими +### 2) Захисні обмеження для bind і auth стали суворішими ```bash openclaw config get gateway.bind @@ -529,15 +533,15 @@ openclaw logs --follow Що перевірити: -- Прив’язки non-loopback (`lan`, `tailnet`, `custom`) потребують коректного шляху auth gateway: auth зі спільним token/password або правильно налаштованого non-loopback розгортання `trusted-proxy`. -- Старі ключі, як-от `gateway.token`, не замінюють `gateway.auth.token`. +- Прив’язки не-loopback (`lan`, `tailnet`, `custom`) потребують дійсного шляху автентифікації gateway: auth за shared token/password або правильно налаштоване розгортання `trusted-proxy` не-loopback. +- Старі ключі на кшталт `gateway.token` не замінюють `gateway.auth.token`. Поширені ознаки: -- `refusing to bind gateway ... without auth` → прив’язка non-loopback без коректного шляху auth gateway. -- `Connectivity probe: failed` while runtime is running → gateway активний, але недоступний з поточними auth/url. +- `refusing to bind gateway ... without auth` → прив’язка не-loopback без дійсного шляху автентифікації gateway. +- `Connectivity probe: failed` коли runtime запущено → gateway працює, але недоступний із поточними auth/url. -### 3) Змінився стан pairing і device identity +### 3) Змінився стан pairing та ідентичності пристрою ```bash openclaw devices list @@ -548,15 +552,15 @@ openclaw doctor Що перевірити: -- Очікувані підтвердження пристроїв для dashboard/nodes. -- Очікувані підтвердження pairing у DM після змін політики або identity. +- Очікують схвалення пристрої для dashboard/nodes. +- Очікують схвалення pairings у DM після змін політики або ідентичності. Поширені ознаки: - `device identity required` → вимоги device auth не виконано. -- `pairing required` → відправника/пристрій потрібно підтвердити. +- `pairing required` → відправника/пристрій потрібно схвалити. -Якщо config сервісу і runtime після перевірок усе ще не збігаються, перевстановіть метадані сервісу з того самого каталогу profile/state: +Якщо після перевірок конфігурація сервісу та runtime все ще не збігаються, перевстановіть метадані сервісу з того самого каталогу профілю/стану: ```bash openclaw gateway install --force @@ -571,6 +575,6 @@ openclaw gateway restart ## Пов’язане -- [Gateway runbook](/uk/gateway) +- [Посібник для Gateway](/uk/gateway) - [Doctor](/uk/gateway/doctor) - [FAQ](/uk/help/faq) diff --git a/docs/uk/plugins/architecture-internals.md b/docs/uk/plugins/architecture-internals.md index 63c67ceac..9f9067f5f 100644 --- a/docs/uk/plugins/architecture-internals.md +++ b/docs/uk/plugins/architecture-internals.md @@ -1,138 +1,139 @@ --- read_when: - Реалізація runtime-хуків провайдера, життєвого циклу каналу або пакетних наборів - - Налагодження порядку завантаження plugin або стану реєстру - - Додавання нової можливості plugin або plugin рушія контексту -summary: 'Внутрішні компоненти архітектури Plugin: конвеєр завантаження, реєстр, runtime-хуки, HTTP-маршрути та довідкові таблиці' -title: Внутрішні компоненти архітектури Plugin + - Налагодження порядку завантаження Plugin або стану реєстру + - Додавання нової можливості Plugin або Plugin рушія контексту +summary: 'Внутрішня архітектура Plugin: конвеєр завантаження, реєстр, runtime-хуки, HTTP-маршрути та довідкові таблиці' +title: Внутрішня архітектура Plugin x-i18n: - generated_at: "2026-04-24T06:33:42Z" + generated_at: "2026-04-24T07:42:14Z" model: gpt-5.4 provider: openai - source_hash: f6a99b7be56b7042a0e58a8119066ccfcb898279e6d6668f2aaa7351b188b88e + source_hash: 9370788c5f986e9205b1108ae633e829edec8890e442a49f80d84bb0098bb393 source_path: plugins/architecture-internals.md workflow: 15 --- -Щодо публічної моделі можливостей, форм plugin та контрактів -володіння/виконання, див. [Архітектура Plugin](/uk/plugins/architecture). Ця сторінка є -довідником щодо внутрішньої механіки: конвеєра завантаження, реєстру, runtime-хуків, -Gateway HTTP-маршрутів, шляхів імпорту та таблиць схем. +Щодо публічної моделі можливостей, форм Plugin, а також контрактів +володіння/виконання див. [Plugin architecture](/uk/plugins/architecture). Ця сторінка — +довідник із внутрішньої механіки: конвеєр завантаження, реєстр, runtime-хуки, +HTTP-маршрути Gateway, шляхи імпорту та таблиці схем. ## Конвеєр завантаження Під час запуску OpenClaw приблизно виконує таке: -1. виявляє корені потенційних plugin -2. зчитує маніфести нативних або сумісних пакетів і метадані package +1. виявляє кандидатні корені Plugin +2. читає маніфести нативних або сумісних збірок і метадані пакетів 3. відхиляє небезпечні кандидати -4. нормалізує конфігурацію plugin (`plugins.enabled`, `allow`, `deny`, `entries`, +4. нормалізує конфігурацію Plugin (`plugins.enabled`, `allow`, `deny`, `entries`, `slots`, `load.paths`) -5. визначає, чи буде увімкнено кожного кандидата -6. завантажує увімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; - незібрані нативні plugins використовують jiti -7. викликає нативні хуки `register(api)` і збирає реєстрації до реєстру plugin +5. визначає, чи буде ввімкнено кожного кандидата +6. завантажує ввімкнені нативні модулі: зібрані вбудовані модулі використовують нативний завантажувач; + незібрані нативні Plugin використовують jiti +7. викликає нативні хуки `register(api)` і збирає реєстрації в реєстр Plugin 8. надає реєстр поверхням команд/runtime -`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані plugins використовують `register`; для нових plugin слід віддавати перевагу `register`. +`activate` — це застарілий псевдонім для `register` — завантажувач визначає, що саме присутнє (`def.register ?? def.activate`), і викликає це в тій самій точці. Усі вбудовані Plugin використовують `register`; для нових Plugin слід надавати перевагу `register`. Перевірки безпеки відбуваються **до** виконання runtime. Кандидати блокуються, -якщо точка входу виходить за межі кореня plugin, шлях доступний для запису всім, або -володіння шляхом виглядає підозріло для невбудованих plugin. +коли точка входу виходить за межі кореня Plugin, шлях доступний для запису всім, +або володіння шляхом виглядає підозрілим для невбудованих Plugin. ### Поведінка з пріоритетом маніфесту -Маніфест є джерелом істини для control plane. OpenClaw використовує його, щоб: +Маніфест є джерелом істини на рівні control plane. OpenClaw використовує його, щоб: -- ідентифікувати plugin -- виявляти оголошені канали/Skills/схему конфігурації або можливості пакета -- валідувати `plugins.entries..config` -- доповнювати мітки/плейсхолдери в UI керування +- ідентифікувати Plugin +- виявляти оголошені канали/Skills/схему конфігурації або можливості збірки +- перевіряти `plugins.entries..config` +- доповнювати підписи/placeholder-и в Control UI - показувати метадані встановлення/каталогу -- зберігати дешеві дескриптори активації та налаштування без завантаження runtime plugin +- зберігати дешеві дескриптори активації та налаштування без завантаження runtime Plugin -Для нативних plugin runtime-модуль є частиною data plane. Він реєструє -фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдерів. +Для нативних Plugin runtime-модуль є частиною data plane. Він реєструє +фактичну поведінку, таку як хуки, інструменти, команди або потоки провайдера. -Необов'язкові блоки маніфесту `activation` і `setup` залишаються в control plane. +Необов’язкові блоки маніфесту `activation` і `setup` залишаються на control plane. Це лише дескриптори метаданих для планування активації та виявлення налаштування; вони не замінюють runtime-реєстрацію, `register(...)` або `setupEntry`. -Перші споживачі живої активації тепер використовують підказки маніфесту щодо команд, каналів і провайдерів, -щоб звузити завантаження plugin до ширшої матеріалізації реєстру: +Перші споживачі живої активації тепер використовують підказки маніфесту для команд, каналів і провайдерів, +щоб звузити завантаження Plugin до ширшої матеріалізації реєстру: -- завантаження CLI звужується до plugin, яким належить запитана основна команда -- налаштування каналу/визначення plugin звужується до plugin, яким належить запитаний - id каналу -- явне визначення налаштування/runtime провайдера звужується до plugin, яким належить - запитаний id провайдера +- завантаження CLI звужується до Plugin, які володіють запитаною основною командою +- налаштування каналу/визначення Plugin звужується до Plugin, які володіють + запитаним id каналу +- явне визначення налаштування/runtime провайдера звужується до Plugin, які володіють + запитаним id провайдера Планувальник активації надає як API лише з id для наявних викликачів, так і -API плану для нової діагностики. Записи плану повідомляють, чому plugin було вибрано, -відокремлюючи явні підказки планувальника `activation.*` від резервного визначення власника з маніфесту, -наприклад `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і hooks. Це розділення причин є межею сумісності: -наявні метадані plugin продовжують працювати, а новий код може виявляти широкі підказки -або резервну поведінку без зміни семантики завантаження runtime. +API плану для нової діагностики. Записи плану повідомляють, чому Plugin було вибрано, +відокремлюючи явні підказки планувальника `activation.*` від резервного варіанта володіння з маніфесту, +такого як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Це розділення причин є межею сумісності: +наявні метадані Plugin і далі працюють, а новий код може виявляти широкі підказки +або резервну поведінку без зміни семантики runtime-завантаження. -Виявлення налаштування тепер надає перевагу id, що належать дескрипторам, таким як `setup.providers` і -`setup.cliBackends`, щоб звузити коло plugin-кандидатів, перш ніж переходити до -`setup-api` для plugin, яким усе ще потрібні runtime-хуки на етапі налаштування. Якщо більше -ніж один виявлений plugin заявляє права на той самий нормалізований id провайдера налаштування або -CLI backend, пошук налаштування відхиляє неоднозначного власника замість того, щоб покладатися на -порядок виявлення. +Виявлення налаштування тепер віддає перевагу id, якими володіють дескриптори, таким як `setup.providers` і +`setup.cliBackends`, щоб звузити коло кандидатних Plugin перед переходом до +`setup-api` для Plugin, яким усе ще потрібні runtime-хуки на етапі налаштування. Якщо +більше ніж один виявлений Plugin заявляє про той самий нормалізований id провайдера налаштування +або CLI backend, пошук налаштування відхиляє неоднозначного власника замість того, +щоб покладатися на порядок виявлення. ### Що кешує завантажувач -OpenClaw зберігає короткочасні кеші в межах процесу для: +OpenClaw зберігає короткочасні внутрішньопроцесні кеші для: - результатів виявлення - даних реєстру маніфестів -- завантажених реєстрів plugin +- завантажених реєстрів Plugin -Ці кеші зменшують стрибкоподібне навантаження під час запуску та повторних викликів команд. Їх безпечно -сприймати як короткочасні кеші продуктивності, а не як постійне збереження. +Ці кеші зменшують стрибкоподібні витрати на запуск і накладні витрати при повторних командах. Їх безпечно +сприймати як короткоживучі кеші продуктивності, а не як сховище. Примітка щодо продуктивності: - Установіть `OPENCLAW_DISABLE_PLUGIN_DISCOVERY_CACHE=1` або `OPENCLAW_DISABLE_PLUGIN_MANIFEST_CACHE=1`, щоб вимкнути ці кеші. -- Налаштовуйте вікна кешу за допомогою `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і +- Налаштуйте вікна кешу через `OPENCLAW_PLUGIN_DISCOVERY_CACHE_MS` і `OPENCLAW_PLUGIN_MANIFEST_CACHE_MS`. ## Модель реєстру -Завантажені plugins не змінюють напряму довільні глобальні об'єкти ядра. Вони реєструються в -центральному реєстрі plugin. +Завантажені Plugin не змінюють напряму довільні глобальні об’єкти ядра. Вони реєструються в +центральному реєстрі Plugin. Реєстр відстежує: -- записи plugin (ідентичність, джерело, походження, статус, діагностика) +- записи Plugin (ідентичність, джерело, походження, статус, діагностика) - інструменти -- застарілі hooks і типізовані hooks +- застарілі хуки і типізовані хуки - канали -- провайдери +- провайдерів - обробники Gateway RPC - HTTP-маршрути -- CLI-реєстратори +- реєстратори CLI - фонові служби -- команди, що належать plugin +- команди, якими володіє Plugin -Потім функції ядра читають із цього реєстру замість прямої взаємодії з модулями plugin. -Це зберігає односпрямованість завантаження: +Функції ядра потім читають із цього реєстру замість того, щоб звертатися до модулів Plugin +напряму. Це зберігає односпрямованість завантаження: -- модуль plugin -> реєстрація в реєстрі +- модуль Plugin -> реєстрація в реєстрі - runtime ядра -> споживання реєстру -Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра потрібна -лише одна точка інтеграції: «прочитати реєстр», а не «окремо обробляти кожен модуль plugin». +Це розділення важливе для підтримуваності. Воно означає, що більшості поверхонь ядра +потрібна лише одна точка інтеграції: «прочитати реєстр», а не «робити окрему обробку для кожного модуля Plugin». -## Колбеки прив'язки розмови +## Зворотні виклики прив’язування розмови -Plugins, які прив'язують розмову, можуть реагувати, коли погодження буде вирішено. +Plugin, які прив’язують розмову, можуть реагувати, коли погодження завершено. -Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати колбек після того, як запит на прив'язку буде схвалено або відхилено: +Використовуйте `api.onConversationBindingResolved(...)`, щоб отримати зворотний виклик після того, +як запит на прив’язування буде схвалено або відхилено: ```ts export default { @@ -140,124 +141,123 @@ export default { register(api) { api.onConversationBindingResolved(async (event) => { if (event.status === "approved") { - // Тепер для цього plugin + розмови існує прив'язка. + // Тепер для цього Plugin + розмови існує прив’язування. console.log(event.binding?.conversationId); return; } - // Запит було відхилено; очистіть будь-який локальний стан очікування. + // Запит було відхилено; очистьте будь-який локальний стан очікування. console.log(event.request.conversation.conversationId); }); }, }; ``` -Поля корисного навантаження колбека: +Поля корисного навантаження зворотного виклику: - `status`: `"approved"` або `"denied"` - `decision`: `"allow-once"`, `"allow-always"` або `"deny"` -- `binding`: вирішена прив'язка для схвалених запитів -- `request`: зведення початкового запиту, підказка від'єднання, id відправника та +- `binding`: розв’язане прив’язування для схвалених запитів +- `request`: початкове зведення запиту, підказка від’єднання, id відправника та метадані розмови -Цей колбек призначений лише для сповіщення. Він не змінює те, кому дозволено прив'язувати -розмову, і виконується після завершення обробки схвалення в ядрі. +Цей зворотний виклик є лише сповіщенням. Він не змінює того, кому дозволено прив’язувати +розмову, і виконується після завершення обробки погодження ядром. ## Runtime-хуки провайдера -Plugins провайдера мають три шари: +Plugin провайдера мають три шари: - **Метадані маніфесту** для дешевого пошуку до runtime: `providerAuthEnvVars`, `providerAuthAliases`, `providerAuthChoices` і `channelEnvVars`. - **Хуки часу конфігурації**: `catalog` (застарілий `discovery`) плюс `applyConfigDefaults`. -- **Runtime-хуки**: понад 40 необов'язкових хуків, що охоплюють auth, визначення моделей, - обгортання потоків, рівні thinking, політику повторного відтворення та - кінцеві точки використання. Повний список див. у [Порядок хуків і використання](#hook-order-and-usage). +- **Runtime-хуки**: понад 40 необов’язкових хуків, що охоплюють auth, визначення моделі, + обгортання потоків, рівні thinking, політику replay та кінцеві точки usage. Див. + повний список у розділі [Порядок і використання хуків](#hook-order-and-usage). -OpenClaw, як і раніше, відповідає за загальний цикл агента, failover, обробку транскриптів і -політику інструментів. Ці hooks є поверхнею розширення для специфічної для провайдера -поведінки без потреби в повністю власному транспорті inference. +OpenClaw і далі володіє загальним циклом агента, failover, обробкою transcript і +політикою інструментів. Ці хуки є поверхнею розширення для поведінки, специфічної для провайдера, +без потреби у повністю власному транспорті inference. Використовуйте маніфест `providerAuthEnvVars`, коли провайдер має облікові дані на основі env, -які загальні шляхи auth/status/model-picker повинні бачити без завантаження runtime plugin. +які загальні шляхи auth/status/model-picker мають бачити без завантаження runtime Plugin. Використовуйте маніфест `providerAuthAliases`, коли один id провайдера має повторно використовувати -env vars, auth-профілі, auth на основі конфігурації та варіант онбордингу API-ключа іншого id провайдера. +env vars, профілі auth, auth на основі config та варіант онбордингу API-ключа іншого id провайдера. Використовуйте маніфест `providerAuthChoices`, коли поверхні CLI онбордингу/вибору auth -мають знати id вибору провайдера, мітки груп і просту auth-обв'язку з одним прапорцем без -завантаження runtime провайдера. Зберігайте runtime `envVars` провайдера для підказок, -орієнтованих на операторів, таких як мітки онбордингу або змінні налаштування -client-id/client-secret для OAuth. +мають знати id варіанта провайдера, мітки груп і просту схему auth з одним прапорцем без +завантаження runtime провайдера. Залишайте runtime `envVars` провайдера для підказок, орієнтованих на оператора, +таких як мітки онбордингу або змінні налаштування OAuth client-id/client-secret. -Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування, керовані env, які -загальний резервний механізм shell-env, перевірки config/status або підказки налаштування повинні бачити +Використовуйте маніфест `channelEnvVars`, коли канал має auth або налаштування на основі env, +які загальні резервні шляхи shell-env, перевірки config/status або запити налаштування мають бачити без завантаження runtime каналу. -### Порядок хуків і використання +### Порядок і використання хуків -Для plugin моделі/провайдера OpenClaw викликає hooks приблизно в такому порядку. -Стовпець «Коли використовувати» — це короткий довідник для ухвалення рішень. +Для Plugin моделей/провайдерів OpenClaw викликає хуки приблизно в такому порядку. +Стовпець «Коли використовувати» — це короткий посібник для вибору. -| # | Hook | Що він робить | Коли використовувати | -| --- | --------------------------------- | -------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | -| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або типовими значеннями `base URL` | -| 2 | `applyConfigDefaults` | Застосовує глобальні типові значення конфігурації, що належать провайдеру, під час матеріалізації конфігурації | Типові значення залежать від режиму auth, env або семантики сімейства моделей провайдера | -| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(це не hook plugin)_ | -| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми model-id перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | -| 4 | `normalizeTransport` | Нормалізує `api` / `baseUrl` сімейства провайдера перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для власних id провайдера в межах того самого сімейства транспорту | -| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із plugin; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | -| 6 | `applyNativeStreamingUsageCompat` | Застосовує compat-переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, що залежать від endpoint | -| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для провайдерів конфігурації до завантаження runtime auth | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований AWS-резолвер env-marker | -| 8 | `resolveSyntheticAuth` | Показує локальну/self-hosted або config-backed auth без збереження відкритого тексту | Провайдер може працювати із synthetic/local маркером облікових даних | -| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, що належать провайдеру; типове значення `persistence` — `runtime-only` для облікових даних, що належать CLI/app | Провайдер повторно використовує зовнішні auth-облікові дані без збереження скопійованих refresh-токенів; оголосіть `contracts.externalAuthProviders` у маніфесті | -| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені synthetic-плейсхолдери профілю нижче за auth на основі env/config | Провайдер зберігає synthetic-профілі-плейсхолдери, які не повинні мати вищий пріоритет | -| 11 | `resolveDynamicModel` | Синхронний fallback для model id, що належать провайдеру, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream model id | -| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` запускається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | -| 13 | `normalizeResolvedModel` | Останнє переписування перед тим, як вбудований runner використовує визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | -| 14 | `contributeResolvedModelCompat` | Додає compat-прапорці для моделей вендора за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | -| 15 | `capabilities` | Метадані транскрипту/інструментів, що належать провайдеру та використовуються спільною логікою ядра | Провайдеру потрібні особливості транскрипту/сімейства провайдера | -| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | -| 17 | `inspectToolSchemas` | Показує діагностику схем, що належить провайдеру, після нормалізації | Провайдер хоче попередження про ключові слова без додавання в ядро правил, специфічних для провайдера | -| 18 | `resolveReasoningOutputMode` | Вибирає native або tagged-контракт reasoning-output | Провайдеру потрібен tagged reasoning/final output замість native-полів | -| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдеру потрібні типові параметри запиту або очищення параметрів для конкретного провайдера | -| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку на власний транспорт | Провайдеру потрібен власний мережевий протокол, а не просто обгортка | -| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без власного транспорту | -| 22 | `resolveTransportTurnState` | Прикріплює native-заголовки або метадані транспорту для кожного ходу | Провайдер хоче, щоб загальні транспорти надсилали native-ідентичність ходу провайдера | -| 23 | `resolveWebSocketSessionPolicy` | Прикріплює native-заголовки WebSocket або політику охолодження сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або fallback-політику | -| 24 | `formatApiKey` | Форматувальник auth-профілю: збережений профіль стає рядком runtime `apiKey` | Провайдер зберігає додаткові auth-метадані й потребує власної форми runtime-токена | -| 25 | `refreshOAuth` | Перевизначення оновлення OAuth для власних endpoint оновлення або політики помилок оновлення | Провайдер не підходить під спільні механізми оновлення `pi-ai` | -| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли оновлення OAuth не вдається | Провайдеру потрібні власні рекомендації з виправлення auth після помилки оновлення | -| 27 | `matchesContextOverflowError` | Власний matcher переповнення контекстного вікна для провайдера | Провайдер має сирі помилки переповнення, які загальні евристики пропустили б | -| 28 | `classifyFailoverReason` | Власна класифікація причин failover для провайдера | Провайдер може зіставляти сирі API/транспортні помилки з rate-limit/overload тощо | -| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | -| 30 | `buildMissingAuthMessage` | Заміна загального повідомлення відновлення для відсутньої auth | Провайдеру потрібна власна підказка відновлення для відсутньої auth | -| 31 | `suppressBuiltInModel` | Приховування застарілих upstream-моделей плюс необов'язкова підказка про помилку для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою вендора | -| 32 | `augmentModelCatalog` | Synthetic/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні synthetic-рядки прямої сумісності в `models list` і селекторах | -| 33 | `resolveThinkingProfile` | Набір рівнів `/think` для конкретної моделі, мітки відображення та типове значення | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей | -| 34 | `isBinaryThinking` | Hook сумісності для перемикача reasoning увімк./вимк. | Провайдер підтримує лише двійкове увімк./вимк. thinking | -| 35 | `supportsXHighThinking` | Hook сумісності для підтримки reasoning `xhigh` | Провайдер хоче `xhigh` лише для підмножини моделей | -| 36 | `resolveDefaultThinkingLevel` | Hook сумісності для типового рівня `/think` | Провайдер володіє типовою політикою `/think` для сімейства моделей | -| 37 | `isModernModelRef` | Matcher сучасних моделей для live-фільтрів профілю та вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | -| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані для запиту | -| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов'язаних поверхонь стану | Провайдеру потрібен власний розбір токена usage/quota або інші облікові дані usage | -| 40 | `fetchUsageSnapshot` | Отримує й нормалізує usage/quota snapshots, специфічні для провайдера, після визначення auth | Провайдеру потрібен endpoint usage, специфічний для провайдера, або парсер корисного навантаження | -| 41 | `createEmbeddingProvider` | Створює embedding-адаптер, що належить провайдеру, для пам'яті/пошуку | Поведінка embedding для пам'яті має належати plugin провайдера | -| 42 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою транскрипту для провайдера | Провайдеру потрібна власна політика транскрипту (наприклад, видалення thinking-блоків) | -| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення транскрипту | Провайдеру потрібні специфічні для провайдера переписування replay понад спільні допоміжні засоби Compaction | -| 44 | `validateReplayTurns` | Фінальна валідація або переформатування ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша валідація ходів після загальної санітизації | -| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, що належать провайдеру | Провайдеру потрібна телеметрія або стан, що належить провайдеру, коли модель стає активною | +| # | Хук | Що він робить | Коли використовувати | +| --- | --------------------------------- | --------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | +| 1 | `catalog` | Публікує конфігурацію провайдера в `models.providers` під час генерації `models.json` | Провайдер володіє каталогом або базовими значеннями `base URL` | +| 2 | `applyConfigDefaults` | Застосовує глобальні значення конфігурації провайдера під час матеріалізації конфігурації | Значення за замовчуванням залежать від режиму auth, env або семантики сімейства моделей провайдера | +| -- | _(вбудований пошук моделі)_ | OpenClaw спочатку пробує звичайний шлях через реєстр/каталог | _(не є хуком Plugin)_ | +| 3 | `normalizeModelId` | Нормалізує застарілі або preview-псевдоніми `model-id` перед пошуком | Провайдер володіє очищенням псевдонімів до канонічного визначення моделі | +| 4 | `normalizeTransport` | Нормалізує сімейні для провайдера `api` / `baseUrl` перед загальним збиранням моделі | Провайдер володіє очищенням транспорту для користувацьких id провайдера в тому самому сімействі транспорту | +| 5 | `normalizeConfig` | Нормалізує `models.providers.` перед визначенням runtime/провайдера | Провайдеру потрібне очищення конфігурації, яке має жити разом із Plugin; вбудовані допоміжні засоби сімейства Google також підстраховують підтримувані записи конфігурації Google | +| 6 | `applyNativeStreamingUsageCompat` | Застосовує сумісні переписування native streaming-usage до провайдерів конфігурації | Провайдеру потрібні виправлення метаданих native streaming usage, керовані кінцевою точкою | +| 7 | `resolveConfigApiKey` | Визначає auth через env-marker для провайдерів конфігурації до завантаження runtime auth | Провайдер має власне визначення API-ключа через env-marker; `amazon-bedrock` також має тут вбудований резолвер AWS env-marker | +| 8 | `resolveSyntheticAuth` | Надає локальну/self-hosted або config-backed auth без збереження відкритого тексту | Провайдер може працювати із синтетичним/локальним маркером облікових даних | +| 9 | `resolveExternalAuthProfiles` | Накладає зовнішні auth-профілі, якими володіє провайдер; типовий `persistence` — `runtime-only` для облікових даних CLI/app | Провайдер повторно використовує зовнішні облікові дані auth без збереження скопійованих refresh token-ів; оголосіть `contracts.externalAuthProviders` у маніфесті | +| 10 | `shouldDeferSyntheticProfileAuth` | Опускає збережені синтетичні placeholder-и профілів нижче за auth на основі env/config | Провайдер зберігає синтетичні placeholder-профілі, які не повинні мати вищий пріоритет | +| 11 | `resolveDynamicModel` | Синхронний fallback для id моделей провайдера, яких ще немає в локальному реєстрі | Провайдер приймає довільні upstream id моделей | +| 12 | `prepareDynamicModel` | Асинхронний прогрів, після чого `resolveDynamicModel` викликається знову | Провайдеру потрібні мережеві метадані перед визначенням невідомих id | +| 13 | `normalizeResolvedModel` | Фінальне переписування перед тим, як вбудований runner використає визначену модель | Провайдеру потрібні переписування транспорту, але він усе ще використовує транспорт ядра | +| 14 | `contributeResolvedModelCompat` | Додає прапорці сумісності для вендорних моделей за іншим сумісним транспортом | Провайдер розпізнає власні моделі на proxy-транспортах, не перебираючи на себе роль провайдера | +| 15 | `capabilities` | Метадані transcript/інструментів, якими володіє провайдер і які використовує спільна логіка ядра | Провайдеру потрібні особливості transcript/сімейства провайдера | +| 16 | `normalizeToolSchemas` | Нормалізує схеми інструментів до того, як їх побачить вбудований runner | Провайдеру потрібне очищення схем для сімейства транспорту | +| 17 | `inspectToolSchemas` | Подає діагностику схем, якими володіє провайдер, після нормалізації | Провайдер хоче попередження щодо ключових слів без навчання ядра правилам, специфічним для провайдера | +| 18 | `resolveReasoningOutputMode` | Вибирає native чи tagged-контракт виводу reasoning | Провайдеру потрібен tagged reasoning/final output замість native-полів | +| 19 | `prepareExtraParams` | Нормалізація параметрів запиту перед загальними обгортками опцій потоку | Провайдеру потрібні параметри запиту за замовчуванням або очищення параметрів для конкретного провайдера | +| 20 | `createStreamFn` | Повністю замінює звичайний шлях потоку користувацьким транспортом | Провайдеру потрібен власний wire protocol, а не просто обгортка | +| 21 | `wrapStreamFn` | Обгортка потоку після застосування загальних обгорток | Провайдеру потрібні обгортки сумісності заголовків/тіла запиту/моделі без користувацького транспорту | +| 22 | `resolveTransportTurnState` | Приєднує native заголовки або метадані транспорту для окремого ходу | Провайдер хоче, щоб загальні транспорти надсилали native ідентичність ходу провайдера | +| 23 | `resolveWebSocketSessionPolicy` | Приєднує native WebSocket-заголовки або політику cooldown сесії | Провайдер хоче, щоб загальні WS-транспорти налаштовували заголовки сесії або fallback-політику | +| 24 | `formatApiKey` | Форматувальник auth-профілю: збережений профіль стає runtime-рядком `apiKey` | Провайдер зберігає додаткові auth-метадані й потребує користувацької форми runtime-токена | +| 25 | `refreshOAuth` | Перевизначення OAuth refresh для користувацьких кінцевих точок refresh або політики помилки refresh | Провайдер не підходить під спільні механізми refresh `pi-ai` | +| 26 | `buildAuthDoctorHint` | Підказка виправлення, що додається, коли OAuth refresh завершується помилкою | Провайдеру потрібні власні вказівки з виправлення auth після помилки refresh | +| 27 | `matchesContextOverflowError` | Відповідник переповнення context window, яким володіє провайдер | Провайдер має сирі помилки переповнення, які загальні евристики не виявлять | +| 28 | `classifyFailoverReason` | Класифікація причин failover, якою володіє провайдер | Провайдер може зіставляти сирі помилки API/транспорту з rate-limit/overload тощо | +| 29 | `isCacheTtlEligible` | Політика prompt-cache для proxy/backhaul-провайдерів | Провайдеру потрібне керування TTL кешу, специфічне для proxy | +| 30 | `buildMissingAuthMessage` | Замінює загальне повідомлення відновлення при відсутній auth | Провайдеру потрібна власна підказка відновлення при відсутній auth | +| 31 | `suppressBuiltInModel` | Пригнічення застарілої upstream-моделі плюс необов’язкова підказка помилки для користувача | Провайдеру потрібно приховати застарілі upstream-рядки або замінити їх підказкою від вендора | +| 32 | `augmentModelCatalog` | Синтетичні/фінальні рядки каталогу, додані після виявлення | Провайдеру потрібні синтетичні рядки forward-compat у `models list` і селекторах | +| 33 | `resolveThinkingProfile` | Набір рівнів `/think`, мітки відображення та значення за замовчуванням для конкретної моделі | Провайдер надає власну шкалу thinking або двійкову мітку для вибраних моделей | +| 34 | `isBinaryThinking` | Хук сумісності для перемикача reasoning увімкнено/вимкнено | Провайдер підтримує лише двійковий режим thinking увімкнено/вимкнено | +| 35 | `supportsXHighThinking` | Хук сумісності підтримки reasoning `xhigh` | Провайдер хоче мати `xhigh` лише для підмножини моделей | +| 36 | `resolveDefaultThinkingLevel` | Хук сумісності рівня `/think` за замовчуванням | Провайдер володіє політикою `/think` за замовчуванням для сімейства моделей | +| 37 | `isModernModelRef` | Відповідник modern-model для фільтрів живих профілів і вибору smoke | Провайдер володіє зіставленням бажаних моделей для live/smoke | +| 38 | `prepareRuntimeAuth` | Обмінює налаштовані облікові дані на фактичний runtime-токен/ключ безпосередньо перед inference | Провайдеру потрібен обмін токена або короткоживучі облікові дані запиту | +| 39 | `resolveUsageAuth` | Визначає облікові дані usage/billing для `/usage` і пов’язаних поверхонь статусу | Провайдеру потрібен користувацький розбір токена usage/quota або інші облікові дані usage | +| 40 | `fetchUsageSnapshot` | Отримує та нормалізує знімки usage/quota, специфічні для провайдера, після визначення auth | Провайдеру потрібна кінцева точка usage або парсер payload, специфічні для провайдера | +| 41 | `createEmbeddingProvider` | Створює адаптер embeddings, яким володіє провайдер, для пам’яті/пошуку | Поведінка embeddings для пам’яті має належати Plugin провайдера | +| 42 | `buildReplayPolicy` | Повертає політику replay, що керує обробкою transcript для провайдера | Провайдеру потрібна користувацька політика transcript (наприклад, вилучення блоків thinking) | +| 43 | `sanitizeReplayHistory` | Переписує історію replay після загального очищення transcript | Провайдеру потрібні переписування replay, специфічні для провайдера, понад спільні допоміжні засоби Compaction | +| 44 | `validateReplayTurns` | Остаточна перевірка або зміна форми ходів replay перед вбудованим runner | Транспорту провайдера потрібна суворіша перевірка ходів після загальної санітизації | +| 45 | `onModelSelected` | Виконує побічні ефекти після вибору моделі, якими володіє провайдер | Провайдеру потрібна телеметрія або стан, яким володіє провайдер, коли модель стає активною | `normalizeModelId`, `normalizeTransport` і `normalizeConfig` спочатку перевіряють -відповідний plugin провайдера, а потім переходять до інших plugin провайдерів, що підтримують hooks, -доки один із них справді не змінить id моделі або транспорт/конфігурацію. Це дозволяє -shim-модулям alias/compat провайдерів працювати без потреби, щоб викликач знав, якому -вбудованому plugin належить переписування. Якщо жоден hook провайдера не переписує підтримуваний -запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google однаково застосує +відповідний Plugin провайдера, а потім переходять до інших Plugin провайдерів, що підтримують хуки, +доки один із них справді не змінить id моделі або transport/config. Це зберігає +працездатність shim-ів провайдерів для alias/compat без потреби, щоб викликач знав, який +саме вбудований Plugin володіє цим переписуванням. Якщо жоден хук провайдера не переписує підтримуваний +запис конфігурації сімейства Google, вбудований нормалізатор конфігурації Google все одно застосовує це очищення сумісності. -Якщо провайдеру потрібен повністю власний мережевий протокол або власний виконавець запитів, -це вже інший клас розширення. Ці hooks призначені для поведінки провайдера, -яка все ще працює на звичайному циклі inference OpenClaw. +Якщо провайдеру потрібен повністю користувацький wire protocol або власний виконавець запитів, +це вже інший клас розширення. Ці хуки призначені для поведінки провайдера, +яка все ще виконується у звичайному циклі inference OpenClaw. ### Приклад провайдера @@ -315,36 +315,36 @@ api.registerProvider({ ### Вбудовані приклади -Вбудовані plugins провайдерів поєднують наведені вище hooks, щоб відповідати потребам кожного вендора щодо каталогу, -auth, thinking, replay і usage. Авторитетний набір hooks знаходиться разом із -кожним plugin у `extensions/`; ця сторінка ілюструє форми, а не -дзеркально повторює список. +Вбудовані Plugin провайдерів поєднують наведені вище хуки, щоб відповідати потребам кожного вендора +щодо каталогу, auth, thinking, replay та usage. Авторитетний набір хуків розміщено разом із +кожним Plugin у `extensions/`; ця сторінка ілюструє форми, а не +дзеркально відтворює список. - - OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` плюс - `resolveDynamicModel` / `prepareDynamicModel`, щоб мати змогу показувати upstream - model id раніше за статичний каталог OpenClaw. + + OpenRouter, Kilocode, Z.AI, xAI реєструють `catalog` разом із + `resolveDynamicModel` / `prepareDynamicModel`, щоб вони могли показувати upstream + id моделей раніше за статичний каталог OpenClaw. - + GitHub Copilot, Gemini CLI, ChatGPT Codex, MiniMax, Xiaomi, z.ai поєднують - `prepareRuntimeAuth` або `formatApiKey` з `resolveUsageAuth` + - `fetchUsageSnapshot`, щоб контролювати обмін токенів та інтеграцію `/usage`. + `prepareRuntimeAuth` або `formatApiKey` із `resolveUsageAuth` + + `fetchUsageSnapshot`, щоб самостійно керувати обміном токенів та інтеграцією `/usage`. - + Спільні іменовані сімейства (`google-gemini`, `passthrough-gemini`, `anthropic-by-model`, `hybrid-anthropic-openai`) дають провайдерам змогу підключатися до - політики транскрипту через `buildReplayPolicy` замість того, щоб кожен plugin - повторно реалізовував очищення. + політики transcript через `buildReplayPolicy` замість того, щоб кожен Plugin + наново реалізовував cleanup. - + `byteplus`, `cloudflare-ai-gateway`, `huggingface`, `kimi-coding`, `nvidia`, `qianfan`, `synthetic`, `together`, `venice`, `vercel-ai-gateway` і - `volcengine` реєструють лише `catalog` і використовують спільний цикл inference. + `volcengine` реєструють лише `catalog` і працюють на спільному циклі inference. - - Beta-заголовки, `/fast` / `serviceTier` і `context1m` знаходяться в - публічному seam `api.ts` / `contract-api.ts` plugin Anthropic + + Бета-заголовки, `/fast` / `serviceTier` і `context1m` живуть усередині + публічної межі `api.ts` / `contract-api.ts` Plugin Anthropic (`wrapAnthropicProviderStream`, `resolveAnthropicBetas`, `resolveAnthropicFastMode`, `resolveAnthropicServiceTier`), а не в загальному SDK. @@ -353,7 +353,7 @@ auth, thinking, replay і usage. Авторитетний набір hooks зн ## Runtime-допоміжні засоби -Plugins можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: +Plugin можуть отримувати доступ до вибраних допоміжних засобів ядра через `api.runtime`. Для TTS: ```ts const clip = await api.runtime.tts.textToSpeech({ @@ -374,14 +374,14 @@ const voices = await api.runtime.tts.listVoices({ Примітки: -- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових нотаток. -- Використовує конфігурацію `messages.tts` ядра та вибір провайдера. -- Повертає буфер PCM-аудіо + частоту дискретизації. Plugins повинні ресемплювати/кодувати для провайдерів. -- `listVoices` є необов'язковим залежно від провайдера. Використовуйте його для селекторів голосу, що належать вендору, або потоків налаштування. -- Списки голосів можуть містити багатші метадані, такі як локаль, стать і теги характеру для селекторів, обізнаних про провайдера. -- OpenAI та ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. +- `textToSpeech` повертає звичайне корисне навантаження виводу TTS ядра для поверхонь файлів/голосових повідомлень. +- Використовує конфігурацію ядра `messages.tts` і вибір провайдера. +- Повертає буфер PCM-аудіо + частоту дискретизації. Plugin мають виконати ресемплінг/кодування для провайдерів. +- `listVoices` є необов’язковим для кожного провайдера. Використовуйте його для селекторів голосів або потоків налаштування, якими володіє вендор. +- Списки голосів можуть містити розширеніші метадані, такі як локаль, стать і теги характеру для селекторів, обізнаних про провайдера. +- OpenAI і ElevenLabs сьогодні підтримують телефонію. Microsoft — ні. -Plugins також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. +Plugin також можуть реєструвати провайдерів мовлення через `api.registerSpeechProvider(...)`. ```ts api.registerSpeechProvider({ @@ -401,15 +401,15 @@ api.registerSpeechProvider({ Примітки: -- Зберігайте політику TTS, fallback і доставку відповідей у ядрі. -- Використовуйте провайдерів мовлення для поведінки синтезу, що належить вендору. -- Застаріле значення вводу Microsoft `edge` нормалізується до id провайдера `microsoft`. -- Бажана модель володіння орієнтована на компанію: один plugin вендора може володіти - провайдерами тексту, мовлення, зображень і майбутніх медіа, коли OpenClaw додаватиме відповідні +- Зберігайте політику TTS, fallback і доставку відповіді в ядрі. +- Використовуйте провайдерів мовлення для поведінки синтезу, якою володіє вендор. +- Застарілий ввід Microsoft `edge` нормалізується до id провайдера `microsoft`. +- Бажана модель володіння є компанієорієнтованою: один вендорський Plugin може володіти + текстовими, мовними, графічними й майбутніми медіапровайдерами в міру того, як OpenClaw додає ці контракти можливостей. -Для розуміння зображень/аудіо/відео plugins реєструють один типізований -провайдер media-understanding замість універсального сховища ключ/значення: +Для розуміння image/audio/video Plugin реєструють один типізований +провайдер media-understanding замість узагальненого набору key/value: ```ts api.registerMediaUnderstandingProvider({ @@ -423,16 +423,16 @@ api.registerMediaUnderstandingProvider({ Примітки: -- Зберігайте оркестрацію, fallback, конфігурацію та wiring каналів у ядрі. -- Зберігайте поведінку вендора в plugin провайдера. -- Адитивне розширення має залишатися типізованим: нові необов'язкові методи, нові необов'язкові - поля результату, нові необов'язкові можливості. -- Генерація відео вже дотримується такого самого шаблону: - - ядро володіє контрактом можливостей і runtime-допоміжним засобом - - plugins вендорів реєструють `api.registerVideoGenerationProvider(...)` - - plugins функцій/каналів споживають `api.runtime.videoGeneration.*` +- Зберігайте orchestration, fallback, config і прив’язування каналу в ядрі. +- Зберігайте поведінку вендора в Plugin провайдера. +- Адитивне розширення має залишатися типізованим: нові необов’язкові методи, нові необов’язкові + поля результату, нові необов’язкові можливості. +- Генерація відео вже дотримується тієї самої схеми: + - ядро володіє контрактом можливості та runtime-допоміжним засобом + - вендорські Plugin реєструють `api.registerVideoGenerationProvider(...)` + - Plugin функцій/каналів споживають `api.runtime.videoGeneration.*` -Для runtime-допоміжних засобів media-understanding plugins можуть викликати: +Для runtime-допоміжних засобів media-understanding Plugin можуть викликати: ```ts const image = await api.runtime.mediaUnderstanding.describeImageFile({ @@ -447,14 +447,14 @@ const video = await api.runtime.mediaUnderstanding.describeVideoFile({ }); ``` -Для транскрибування аудіо plugins можуть використовувати або runtime media-understanding, -або старіший псевдонім STT: +Для транскрибування аудіо Plugin можуть використовувати або runtime +media-understanding, або старіший псевдонім STT: ```ts const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ filePath: "/tmp/inbound-audio.ogg", cfg: api.config, - // Необов'язково, коли MIME не вдається надійно визначити: + // Необов’язково, коли MIME не вдається надійно визначити: mime: "audio/ogg", }); ``` @@ -462,12 +462,12 @@ const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({ Примітки: - `api.runtime.mediaUnderstanding.*` — це бажана спільна поверхня для - розуміння зображень/аудіо/відео. -- Використовує аудіоконфігурацію media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів. -- Повертає `{ text: undefined }`, коли вихід транскрибування не створено (наприклад, якщо вхід пропущено або не підтримується). -- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом для сумісності. + розуміння image/audio/video. +- Використовує конфігурацію аудіо media-understanding ядра (`tools.media.audio`) і порядок fallback провайдерів. +- Повертає `{ text: undefined }`, коли не було згенеровано вихід транскрибування (наприклад, через пропущений/непідтримуваний ввід). +- `api.runtime.stt.transcribeAudioFile(...)` залишається псевдонімом сумісності. -Plugins також можуть запускати фонові виконання субагентів через `api.runtime.subagent`: +Plugin також можуть запускати фонові запуски subagent через `api.runtime.subagent`: ```ts const result = await api.runtime.subagent.run({ @@ -481,14 +481,14 @@ const result = await api.runtime.subagent.run({ Примітки: -- `provider` і `model` — це необов'язкові перевизначення для окремого запуску, а не постійні зміни сесії. +- `provider` і `model` — це необов’язкові перевизначення для окремого запуску, а не постійні зміни сесії. - OpenClaw враховує ці поля перевизначення лише для довірених викликачів. -- Для fallback-запусків, що належать plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. -- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені plugins конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. -- Запуски субагентів із недовірених plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого переходу до fallback. +- Для fallback-запусків, якими володіє Plugin, оператори мають явно дозволити це через `plugins.entries..subagent.allowModelOverride: true`. +- Використовуйте `plugins.entries..subagent.allowedModels`, щоб обмежити довірені Plugin конкретними канонічними цілями `provider/model`, або `"*"`, щоб явно дозволити будь-яку ціль. +- Запуски subagent із недовірених Plugin усе ще працюють, але запити на перевизначення відхиляються замість тихого fallback. -Для вебпошуку plugins можуть використовувати спільний runtime-допоміжний засіб замість -звернення до wiring інструментів агента: +Для вебпошуку Plugin можуть використовувати спільний runtime-допоміжний засіб замість +звернення до прив’язування інструментів агента: ```ts const providers = api.runtime.webSearch.listProviders({ @@ -504,14 +504,14 @@ const result = await api.runtime.webSearch.search({ }); ``` -Plugins також можуть реєструвати провайдерів вебпошуку через +Plugin також можуть реєструвати провайдерів вебпошуку через `api.registerWebSearchProvider(...)`. Примітки: -- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запитів у ядрі. +- Зберігайте вибір провайдера, визначення облікових даних і спільну семантику запиту в ядрі. - Використовуйте провайдерів вебпошуку для транспортів пошуку, специфічних для вендора. -- `api.runtime.webSearch.*` — це бажана спільна поверхня для plugins функцій/каналів, яким потрібна поведінка пошуку без залежності від обгортки інструментів агента. +- `api.runtime.webSearch.*` — це бажана спільна поверхня для Plugin функцій/каналів, яким потрібна пошукова поведінка без залежності від обгортки інструментів агента. ### `api.runtime.imageGeneration` @@ -526,12 +526,12 @@ const providers = api.runtime.imageGeneration.listProviders({ }); ``` -- `generate(...)`: генерує зображення, використовуючи налаштований ланцюжок провайдерів генерації зображень. -- `listProviders(...)`: перелічує доступних провайдерів генерації зображень та їхні можливості. +- `generate(...)`: генерує зображення за допомогою налаштованого ланцюжка провайдерів генерації зображень. +- `listProviders(...)`: перелічує доступних провайдерів генерації зображень і їхні можливості. -## Gateway HTTP-маршрути +## HTTP-маршрути Gateway -Plugins можуть відкривати HTTP endpoint через `api.registerHttpRoute(...)`. +Plugin можуть відкривати HTTP-кінцеві точки за допомогою `api.registerHttpRoute(...)`. ```ts api.registerHttpRoute({ @@ -549,43 +549,43 @@ api.registerHttpRoute({ Поля маршруту: - `path`: шлях маршруту під HTTP-сервером gateway. -- `auth`: обов'язкове. Використовуйте `"gateway"`, щоб вимагати звичайну auth gateway, або `"plugin"` для auth/перевірки Webhook, що керуються plugin. -- `match`: необов'язкове. `"exact"` (типово) або `"prefix"`. -- `replaceExisting`: необов'язкове. Дозволяє тому самому plugin замінити власну наявну реєстрацію маршруту. +- `auth`: обов’язкове поле. Використовуйте `"gateway"`, щоб вимагати звичайну auth Gateway, або `"plugin"` для auth/webhook-перевірки, якими керує Plugin. +- `match`: необов’язкове поле. `"exact"` (типово) або `"prefix"`. +- `replaceExisting`: необов’язкове поле. Дозволяє тому самому Plugin замінити власну наявну реєстрацію маршруту. - `handler`: повертайте `true`, коли маршрут обробив запит. Примітки: -- `api.registerHttpHandler(...)` було видалено, і воно спричинить помилку завантаження plugin. Натомість використовуйте `api.registerHttpRoute(...)`. -- Маршрути plugin повинні явно оголошувати `auth`. -- Конфлікти однакових `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один plugin не може замінити маршрут іншого plugin. -- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Ланцюжки проходження `exact`/`prefix` слід тримати лише в межах одного рівня auth. -- Маршрути `auth: "plugin"` **не** отримують автоматично runtime-scopes оператора. Вони призначені для Webhook або перевірки підписів, що керуються plugin, а не для привілейованих допоміжних викликів Gateway. -- Маршрути `auth: "gateway"` виконуються в межах runtime scope запиту Gateway, але цей scope навмисно є консервативним: - - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) зберігає runtime-scopes маршруту plugin зафіксованими на `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` - - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли цей заголовок явно присутній - - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту plugin з ідентичністю, runtime scope повертається до `operator.write` -- Практичне правило: не припускайте, що маршрут plugin з gateway-auth є неявною адмін-поверхнею. Якщо вашому маршруту потрібна поведінка лише для адміністраторів, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. +- `api.registerHttpHandler(...)` було вилучено і воно спричинить помилку завантаження Plugin. Натомість використовуйте `api.registerHttpRoute(...)`. +- Маршрути Plugin повинні явно оголошувати `auth`. +- Конфлікти точного `path + match` відхиляються, якщо не вказано `replaceExisting: true`, і один Plugin не може замінити маршрут іншого Plugin. +- Маршрути, що перекриваються, з різними рівнями `auth` відхиляються. Тримайте ланцюжки fallthrough `exact`/`prefix` лише в межах одного рівня auth. +- Маршрути `auth: "plugin"` **не** отримують автоматично runtime-скоупи оператора. Вони призначені для webhook-ів/перевірки підписів, якими керує Plugin, а не для привілейованих допоміжних викликів Gateway. +- Маршрути `auth: "gateway"` виконуються всередині runtime-скоупу запиту Gateway, але цей скоуп навмисно консервативний: + - bearer auth зі спільним секретом (`gateway.auth.mode = "token"` / `"password"`) утримує runtime-скоупи маршруту Plugin на рівні `operator.write`, навіть якщо викликач надсилає `x-openclaw-scopes` + - довірені HTTP-режими з ідентичністю (наприклад, `trusted-proxy` або `gateway.auth.mode = "none"` у приватному ingress) враховують `x-openclaw-scopes` лише тоді, коли заголовок явно присутній + - якщо `x-openclaw-scopes` відсутній у таких запитах маршруту Plugin з ідентичністю, runtime-скоуп повертається до `operator.write` +- Практичне правило: не припускайте, що маршрут Plugin з gateway-auth є неявною поверхнею адміністратора. Якщо вашому маршруту потрібна поведінка лише для адміністратора, вимагайте режим auth з ідентичністю та документуйте явний контракт заголовка `x-openclaw-scopes`. ## Шляхи імпорту Plugin SDK -Використовуйте вузькі підшляхи SDK замість монолітного кореневого -barrel `openclaw/plugin-sdk` під час створення нових plugin. Основні підшляхи: +Під час створення нових Plugin використовуйте вузькі підшляхи SDK замість монолітного +кореневого barrel `openclaw/plugin-sdk`. Основні підшляхи: | Підшлях | Призначення | | ---------------------------------- | -------------------------------------------------- | | `openclaw/plugin-sdk/plugin-entry` | Примітиви реєстрації Plugin | -| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби входу/побудови каналу | -| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби та umbrella contract | -| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod для `openclaw.json` (`OpenClawSchema`) | +| `openclaw/plugin-sdk/channel-core` | Допоміжні засоби для входу/побудови каналу | +| `openclaw/plugin-sdk/core` | Загальні спільні допоміжні засоби й umbrella contract | +| `openclaw/plugin-sdk/config-schema` | Коренева схема Zod `openclaw.json` (`OpenClawSchema`) | -Plugins каналів обирають із сімейства вузьких seams — `channel-setup`, +Канальні Plugin обирають із сімейства вузьких меж — `channel-setup`, `setup-runtime`, `setup-adapter-runtime`, `setup-tools`, `channel-pairing`, `channel-contract`, `channel-feedback`, `channel-inbound`, `channel-lifecycle`, `channel-reply-pipeline`, `command-auth`, `secret-input`, `webhook-ingress`, -`channel-targets` і `channel-actions`. Поведінку погодження слід зводити -до одного контракту `approvalCapability`, а не змішувати її між не пов'язаними -полями plugin. Див. [Plugins каналів](/uk/plugins/sdk-channel-plugins). +`channel-targets` і `channel-actions`. Поведінка погодження має зводитися +до одного контракту `approvalCapability`, а не змішуватися між не пов’язаними +полями Plugin. Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). Runtime- і config-допоміжні засоби розміщені у відповідних підшляхах `*-runtime` (`approval-runtime`, `config-runtime`, `infra-runtime`, `agent-runtime`, @@ -593,82 +593,81 @@ Runtime- і config-допоміжні засоби розміщені у від `openclaw/plugin-sdk/channel-runtime` є застарілим — це shim сумісності для -старіших plugin. Новий код має імпортувати натомість вужчі загальні примітиви. +старіших Plugin. Новий код натомість має імпортувати вужчі загальні примітиви. -Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого plugin): +Внутрішні для репозиторію точки входу (для кореня пакета кожного вбудованого Plugin): -- `index.js` — точка входу вбудованого plugin +- `index.js` — точка входу вбудованого Plugin - `api.js` — barrel допоміжних засобів/типів - `runtime-api.js` — barrel лише для runtime -- `setup-entry.js` — точка входу plugin для налаштування +- `setup-entry.js` — точка входу Plugin налаштування -Зовнішні plugins повинні імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи -не імпортуйте `src/*` іншого пакета plugin з ядра або з іншого plugin. -Точки входу, завантажені через facade, віддають перевагу активному знімку конфігурації runtime, коли він існує, -а потім переходять до визначеного файла конфігурації на диску. +Зовнішні Plugin мають імпортувати лише підшляхи `openclaw/plugin-sdk/*`. Ніколи +не імпортуйте `src/*` іншого пакета Plugin із ядра або з іншого Plugin. +Точки входу, завантажені через facade, віддають перевагу активному snapshot runtime-конфігурації, коли він +існує, і лише потім переходять до визначеного config-файла на диску. Підшляхи, специфічні для можливостей, такі як `image-generation`, `media-understanding` -і `speech`, існують, оскільки вбудовані plugins уже використовують їх сьогодні. Вони не є -автоматично назавжди зафіксованими зовнішніми контрактами — перевіряйте відповідну -довідкову сторінку SDK, коли покладаєтеся на них. +і `speech`, існують, тому що вбудовані Plugin використовують їх уже сьогодні. Вони не є +автоматично довгостроково замороженими зовнішніми контрактами — перевіряйте відповідну сторінку +довідки SDK, коли покладаєтеся на них. ## Схеми інструментів повідомлень -Plugins повинні володіти внесками до схеми `describeMessageTool(...)`, специфічними для каналу, -для немеседжних примітивів, таких як реакції, позначки прочитання та опитування. +Plugin мають володіти внесками в схему `describeMessageTool(...)`, специфічними для каналу, +для немеседжевих примітивів, таких як реакції, прочитання та опитування. Спільне представлення надсилання має використовувати загальний контракт `MessagePresentation` -замість полів кнопок, компонентів, блоків або карток, специфічних для провайдера. +замість native-полів кнопок, компонентів, блоків або карток, специфічних для провайдера. Див. [Message Presentation](/uk/plugins/message-presentation), щоб ознайомитися з контрактом, -правилами fallback, відображенням провайдерів і контрольним списком для авторів plugin. +правилами fallback, зіставленням провайдерів і контрольним списком для авторів Plugin. -Plugins, здатні надсилати, оголошують, що саме вони можуть відтворювати, через можливості повідомлень: +Plugin, що підтримують надсилання, оголошують, що саме вони можуть рендерити, через можливості повідомлень: - `presentation` для блоків семантичного представлення (`text`, `context`, `divider`, `buttons`, `select`) - `delivery-pin` для запитів закріпленої доставки -Ядро вирішує, чи відтворювати представлення нативно, чи деградувати його до тексту. -Не відкривайте специфічні для провайдера обхідні шляхи UI через загальний інструмент повідомлень. -Застарілі допоміжні засоби SDK для старих нативних схем залишаються експортованими для наявних -сторонніх plugin, але нові plugins не повинні їх використовувати. +Ядро вирішує, чи рендерити представлення нативно, чи деградувати його до тексту. +Не відкривайте з generic message tool шляхи обходу native UI, специфічні для провайдера. +Застарілі допоміжні засоби SDK для legacy native-схем і далі експортуються для наявних +сторонніх Plugin, але нові Plugin не повинні їх використовувати. -## Визначення цілей каналу +## Визначення цілі каналу -Plugins каналів повинні володіти семантикою цілей, специфічною для каналу. Зберігайте спільний -вихідний host узагальненим і використовуйте поверхню адаптера повідомлень для правил провайдера: +Канальні Plugin мають володіти семантикою цілей, специфічною для каналу. Залишайте спільний +outbound host загальним і використовуйте поверхню messaging adapter для правил провайдера: -- `messaging.inferTargetChatType({ to })` визначає, чи слід розглядати нормалізовану ціль - як `direct`, `group` або `channel` до пошуку в директорії. +- `messaging.inferTargetChatType({ to })` визначає, чи нормалізовану ціль + слід трактувати як `direct`, `group` або `channel` до пошуку в директорії. - `messaging.targetResolver.looksLikeId(raw, normalized)` повідомляє ядру, чи - повинен ввід одразу перейти до визначення, схожого на id, замість пошуку в директорії. -- `messaging.targetResolver.resolveTarget(...)` — це fallback plugin, коли - ядру потрібне остаточне визначення, що належить провайдеру, після нормалізації або після - промаху в директорії. -- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту вихідної сесії, - специфічною для провайдера, після того як ціль визначено. + слід для вводу відразу перейти до визначення id-подібної цілі замість пошуку в директорії. +- `messaging.targetResolver.resolveTarget(...)` — це fallback Plugin, коли + ядру потрібне остаточне визначення, яким володіє провайдер, після нормалізації або після + промаху по директорії. +- `messaging.resolveOutboundSessionRoute(...)` володіє побудовою маршруту сесії, специфічного для провайдера, + щойно ціль визначено. Рекомендований поділ: -- Використовуйте `inferTargetChatType` для категорійних рішень, які мають відбуватися до +- Використовуйте `inferTargetChatType` для рішень щодо категорії, які мають відбуватися до пошуку peer/group. -- Використовуйте `looksLikeId` для перевірок на кшталт «сприймати це як явний/нативний id цілі». -- Використовуйте `resolveTarget` для fallback нормалізації, специфічної для провайдера, а не для +- Використовуйте `looksLikeId` для перевірок на кшталт «трактувати це як явний/native id цілі». +- Використовуйте `resolveTarget` для fallback-нормалізації, специфічної для провайдера, а не для широкого пошуку в директорії. -- Зберігайте нативні для провайдера id, такі як chat id, thread id, JID, handle і room - id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних - полях SDK. +- Зберігайте native id провайдера, такі як chat id, thread id, JID, handles і room + id, усередині значень `target` або параметрів, специфічних для провайдера, а не в загальних полях SDK. -## Директорії на основі конфігурації +## Директорії на основі config -Plugins, які формують записи директорії з конфігурації, повинні зберігати цю логіку в -plugin і повторно використовувати спільні допоміжні засоби з +Plugin, які отримують записи директорії з config, мають тримати цю логіку в +Plugin і повторно використовувати спільні допоміжні засоби з `openclaw/plugin-sdk/directory-runtime`. -Використовуйте це, коли каналу потрібні peer/group на основі конфігурації, наприклад: +Використовуйте це, коли каналу потрібні peer/group на основі config, наприклад: -- peer для DM на основі allowlist -- налаштовані відповідності channel/group -- статичні fallback директорії в межах акаунта +- DM peer, керовані allowlist +- налаштовані мапи channel/group +- статичні fallback-и директорії в межах облікового запису Спільні допоміжні засоби в `directory-runtime` обробляють лише загальні операції: @@ -677,12 +676,12 @@ plugin і повторно використовувати спільні доп - допоміжні засоби дедуплікації/нормалізації - побудову `ChannelDirectoryEntry[]` -Перевірка акаунтів, специфічна для каналу, та нормалізація id повинні залишатися в -реалізації plugin. +Перевірка облікового запису й нормалізація id, специфічні для каналу, мають залишатися в +реалізації Plugin. ## Каталоги провайдерів -Plugins провайдерів можуть визначати каталоги моделей для inference через +Plugin провайдерів можуть визначати каталоги моделей для inference через `registerProvider({ catalog: { run(...) { ... } } })`. `catalog.run(...)` повертає ту саму форму, яку OpenClaw записує в @@ -691,58 +690,60 @@ Plugins провайдерів можуть визначати каталоги - `{ provider }` для одного запису провайдера - `{ providers }` для кількох записів провайдерів -Використовуйте `catalog`, коли plugin володіє model id, специфічними для провайдера, типовими -значеннями base URL або метаданими моделей, закритими auth. +Використовуйте `catalog`, коли Plugin володіє id моделей, специфічними для провайдера, базовими значеннями URL +або метаданими моделей, захищеними auth. -`catalog.order` керує тим, коли каталог plugin зливається відносно вбудованих -неявних провайдерів OpenClaw: +`catalog.order` визначає, коли каталог Plugin зливається відносно неявних +вбудованих провайдерів OpenClaw: - `simple`: звичайні провайдери на основі API-ключа або env -- `profile`: провайдери, що з'являються, коли існують auth-профілі -- `paired`: провайдери, які синтезують кілька пов'язаних записів провайдерів +- `profile`: провайдери, які з’являються, коли існують auth-профілі +- `paired`: провайдери, які синтезують кілька пов’язаних записів провайдерів - `late`: останній прохід, після інших неявних провайдерів -Пізніші провайдери перемагають у разі конфлікту ключів, тому plugins можуть навмисно перевизначати +Пізніші провайдери перемагають при колізії ключів, тому Plugin можуть навмисно перевизначати вбудований запис провайдера з тим самим id провайдера. Сумісність: -- `discovery` усе ще працює як застарілий псевдонім +- `discovery` все ще працює як застарілий псевдонім - якщо зареєстровано і `catalog`, і `discovery`, OpenClaw використовує `catalog` ## Інспекція каналу лише для читання -Якщо ваш plugin реєструє канал, краще реалізувати -`plugin.config.inspectAccount(cfg, accountId)` разом із `resolveAccount(...)`. +Якщо ваш Plugin реєструє канал, краще реалізувати +`plugin.config.inspectAccount(cfg, accountId)` поруч із `resolveAccount(...)`. Чому: -- `resolveAccount(...)` — це шлях runtime. Він може припускати, що облікові дані - повністю матеріалізовані, і може швидко завершитися з помилкою, якщо потрібних секретів бракує. -- Командним шляхам лише для читання, таким як `openclaw status`, `openclaw status --all`, - `openclaw channels status`, `openclaw channels resolve`, а також потокам - відновлення doctor/config, не повинна бути потрібна матеріалізація runtime-облікових даних лише для +- `resolveAccount(...)` — це runtime-шлях. Йому дозволено припускати, що облікові дані + повністю матеріалізовані, і він може швидко завершитися помилкою, якщо потрібні секрети відсутні. +- Шляхи команд лише для читання, такі як `openclaw status`, `openclaw status --all`, + `openclaw channels status`, `openclaw channels resolve` і потоки + doctor/config repair, не повинні вимагати матеріалізації runtime-облікових даних лише для опису конфігурації. Рекомендована поведінка `inspectAccount(...)`: -- Повертає лише описовий стан акаунта. -- Зберігає `enabled` і `configured`. -- Включає поля джерела/стану облікових даних, коли це доречно, наприклад: +- Повертайте лише описовий стан облікового запису. +- Зберігайте `enabled` і `configured`. +- Включайте поля джерела/стану облікових даних, коли це доречно, наприклад: - `tokenSource`, `tokenStatus` - `botTokenSource`, `botTokenStatus` - `appTokenSource`, `appTokenStatus` - `signingSecretSource`, `signingSecretStatus` -- Не потрібно повертати сирі значення токенів лише для звітування про доступність у режимі лише читання. Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) для команд у стилі status. +- Вам не потрібно повертати сирі значення токенів лише для звіту про доступність у режимі лише читання. + Достатньо повернути `tokenStatus: "available"` (і відповідне поле джерела) + для команд у стилі status. - Використовуйте `configured_unavailable`, коли облікові дані налаштовано через SecretRef, але - вони недоступні в поточному командному шляху. + вони недоступні в поточному шляху команди. -Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому командному -шляху» замість аварійного завершення або помилкового повідомлення, що акаунт не налаштовано. +Це дає змогу командам лише для читання повідомляти «налаштовано, але недоступно в цьому шляху команди» +замість аварійного завершення або хибного повідомлення, що обліковий запис не налаштовано. ## Пакетні набори -Каталог plugin може містити `package.json` з `openclaw.extensions`: +Каталог Plugin може містити `package.json` з `openclaw.extensions`: ```json { @@ -754,65 +755,65 @@ Plugins провайдерів можуть визначати каталоги } ``` -Кожен запис стає plugin. Якщо набір містить кілька extensions, id plugin +Кожен запис стає Plugin. Якщо пакетний набір містить кілька extension, id Plugin стає `name/`. -Якщо ваш plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб -`node_modules` було доступним (`npm install` / `pnpm install`). +Якщо ваш Plugin імпортує npm-залежності, установіть їх у цьому каталозі, щоб +`node_modules` був доступний (`npm install` / `pnpm install`). -Захисне обмеження безпеки: кожен запис `openclaw.extensions` повинен залишатися в межах каталогу plugin +Захисне обмеження безпеки: кожен запис `openclaw.extensions` має залишатися в межах каталогу Plugin після визначення symlink. Записи, які виходять за межі каталогу пакета, відхиляються. -Примітка щодо безпеки: `openclaw plugins install` встановлює залежності plugin через -`npm install --omit=dev --ignore-scripts` (без lifecycle-скриптів, без dev-залежностей у runtime). Зберігайте дерево залежностей plugin -«чистим JS/TS» та уникайте пакетів, яким потрібні збірки `postinstall`. +Примітка щодо безпеки: `openclaw plugins install` встановлює залежності Plugin за допомогою +`npm install --omit=dev --ignore-scripts` (без lifecycle scripts, без dev-залежностей у runtime). Зберігайте дерева залежностей Plugin +«чистими JS/TS» і уникайте пакетів, яким потрібні збірки `postinstall`. -Необов'язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. -Коли OpenClaw потребує поверхонь налаштування для вимкненого plugin каналу або -коли plugin каналу увімкнено, але ще не налаштовано, він завантажує `setupEntry` -замість повної точки входу plugin. Це робить запуск і налаштування легшими, -коли основна точка входу plugin також підключає інструменти, hooks або інший код лише для runtime. +Необов’язково: `openclaw.setupEntry` може вказувати на легкий модуль лише для налаштування. +Коли OpenClaw потребує поверхонь налаштування для вимкненого канального Plugin або +коли канальний Plugin увімкнено, але він усе ще не налаштований, OpenClaw завантажує `setupEntry` +замість повної точки входу Plugin. Це робить запуск і налаштування легшими, +коли ваша основна точка входу Plugin також підключає інструменти, хуки або інший код лише для runtime. -Необов'язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` -може перевести plugin каналу на той самий шлях `setupEntry` під час фази -запуску gateway до початку прослуховування, навіть якщо канал уже налаштовано. +Необов’язково: `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` +може перевести канальний Plugin на той самий шлях `setupEntry` під час +фази запуску gateway до початку прослуховування, навіть якщо канал уже налаштовано. Використовуйте це лише тоді, коли `setupEntry` повністю покриває поверхню запуску, яка має існувати до того, як gateway почне прослуховування. На практиці це означає, що точка входу налаштування -повинна реєструвати кожну можливість, що належить каналу й від якої залежить запуск, наприклад: +має реєструвати кожну можливість каналу, від якої залежить запуск, зокрема: - саму реєстрацію каналу -- будь-які HTTP-маршрути, які мають бути доступними до того, як gateway почне прослуховування -- будь-які методи gateway, інструменти або служби, які мають існувати в той самий період +- будь-які HTTP-маршрути, які мають бути доступні до того, як gateway почне прослуховування +- будь-які методи gateway, інструменти чи служби, які мають існувати в той самий проміжок часу Якщо ваша повна точка входу все ще володіє будь-якою необхідною можливістю запуску, не вмикайте -цей прапорець. Залиште plugin із типовою поведінкою й дозвольте OpenClaw завантажити +цей прапорець. Залиште Plugin на типовій поведінці й дозвольте OpenClaw завантажити повну точку входу під час запуску. Вбудовані канали також можуть публікувати допоміжні засоби поверхні контракту лише для налаштування, які ядро -може використовувати до завантаження повного runtime каналу. Поточна поверхня -просування налаштування така: +може використовувати до завантаження повного runtime каналу. Поточна +поверхня просування налаштування така: - `singleAccountKeysToMove` - `namedAccountPromotionKeys` - `resolveSingleAccountPromotionTarget(...)` -Ядро використовує цю поверхню, коли йому потрібно просунути застарілу конфігурацію каналу з одним акаунтом -до `channels..accounts.*` без завантаження повної точки входу plugin. -Matrix — поточний вбудований приклад: він переносить лише ключі auth/bootstrap до -іменованого просунутого акаунта, коли іменовані акаунти вже існують, і може зберегти -налаштований неканонічний ключ акаунта за замовчуванням замість того, щоб завжди створювати +Ядро використовує цю поверхню, коли йому потрібно просунути legacy-конфігурацію каналу з одним обліковим записом +до `channels..accounts.*`, не завантажуючи повну точку входу Plugin. +Matrix є поточним вбудованим прикладом: він переносить лише ключі auth/bootstrap до +іменованого просунутого облікового запису, коли іменовані облікові записи вже існують, і може +зберегти налаштований неканонічний ключ облікового запису за замовчуванням замість того, щоб завжди створювати `accounts.default`. -Ці адаптери патчів налаштування зберігають ліниве виявлення поверхні контракту вбудованих каналів. Час -імпорту залишається малим; поверхня просування завантажується лише при першому використанні замість -повторного входу до запуску вбудованого каналу під час імпорту модуля. +Ці адаптери патчів налаштування зберігають ледаче виявлення поверхні контракту вбудованих каналів. +Час імпорту залишається малим; поверхня просування завантажується лише при першому використанні замість +повторного входу у запуск вбудованого каналу під час імпорту модуля. -Коли ці поверхні запуску включають Gateway RPC-методи, зберігайте їх у префіксі, -специфічному для plugin. Простори назв адміністрування ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди визначаються -як `operator.admin`, навіть якщо plugin запитує вужчий scope. +Коли ці поверхні запуску включають методи Gateway RPC, тримайте їх на +префіксі, специфічному для Plugin. Простори імен адміністратора ядра (`config.*`, +`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими і завжди визначаються +як `operator.admin`, навіть якщо Plugin запитує вужчий скоуп. Приклад: @@ -831,8 +832,8 @@ Matrix — поточний вбудований приклад: він пере ### Метадані каталогу каналів -Plugins каналів можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і -підказки встановлення через `openclaw.install`. Це дозволяє зберігати дані каталогу ядра порожніми. +Канальні Plugin можуть оголошувати метадані налаштування/виявлення через `openclaw.channel` і +підказки встановлення через `openclaw.install`. Це зберігає дані каталогу ядра порожніми. Приклад: @@ -860,53 +861,61 @@ Plugins каналів можуть оголошувати метадані на } ``` -Корисні поля `openclaw.channel`, окрім мінімального прикладу: +Корисні поля `openclaw.channel` понад мінімальний приклад: -- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/status -- `docsLabel`: перевизначає текст посилання для посилання на документацію -- `preferOver`: id plugin/каналу з нижчим пріоритетом, які цей запис каталогу має випереджати -- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом на поверхні вибору -- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо вихідного форматування +- `detailLabel`: вторинна мітка для багатших поверхонь каталогу/статусу +- `docsLabel`: перевизначення тексту посилання для посилання на документацію +- `preferOver`: id Plugin/каналу з нижчим пріоритетом, які цей запис каталогу має перевершувати +- `selectionDocsPrefix`, `selectionDocsOmitLabel`, `selectionExtras`: елементи керування текстом поверхні вибору +- `markdownCapable`: позначає канал як сумісний із markdown для рішень щодо форматування вихідних даних - `exposure.configured`: приховує канал із поверхонь списку налаштованих каналів, якщо встановлено `false` - `exposure.setup`: приховує канал з інтерактивних селекторів налаштування/конфігурації, якщо встановлено `false` - `exposure.docs`: позначає канал як внутрішній/приватний для поверхонь навігації документації -- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; краще використовувати `exposure` -- `quickstartAllowFrom`: додає канал до стандартного потоку quickstart `allowFrom` -- `forceAccountBinding`: вимагає явної прив'язки акаунта, навіть якщо існує лише один акаунт -- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення цілей анонсу +- `showConfigured` / `showInSetup`: застарілі псевдоніми, які все ще приймаються для сумісності; віддавайте перевагу `exposure` +- `quickstartAllowFrom`: включає канал у стандартний потік quickstart `allowFrom` +- `forceAccountBinding`: вимагає явного прив’язування облікового запису, навіть коли існує лише один обліковий запис +- `preferSessionLookupForAnnounceTarget`: надає перевагу пошуку сесії під час визначення announce target -OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт -реєстру MPM). Помістіть JSON-файл в одне з таких місць: +OpenClaw також може зливати **зовнішні каталоги каналів** (наприклад, експорт реєстру MPM). +Помістіть JSON-файл в один із таких шляхів: - `~/.openclaw/mpm/plugins.json` - `~/.openclaw/mpm/catalog.json` - `~/.openclaw/plugins/catalog.json` Або вкажіть `OPENCLAW_PLUGIN_CATALOG_PATHS` (або `OPENCLAW_MPM_CATALOG_PATHS`) на -один або кілька JSON-файлів (розділених комами/крапками з комою/роздільником `PATH`). Кожен файл має +один чи кілька JSON-файлів (розділених комою/крапкою з комою/як у `PATH`). Кожен файл має містити `{ "entries": [ { "name": "@scope/pkg", "openclaw": { "channel": {...}, "install": {...} } } ] }`. Парсер також приймає `"packages"` або `"plugins"` як застарілі псевдоніми для ключа `"entries"`. -Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів надають -нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Ці -нормалізовані факти визначають, чи є npm-специфікація точною версією або плаваючим -селектором, чи присутні очікувані метадані цілісності, а також чи доступний локальний -шлях джерела. Споживачі повинні розглядати `installSource` як адитивне необов'язкове поле, щоб старішим записам, зібраним вручну, і shim-модулям сумісності не доводилося його синтезувати. Це дозволяє онбордингу та діагностиці пояснювати -стан площини джерела без імпорту runtime plugin. +Згенеровані записи каталогу каналів і записи каталогу встановлення провайдерів відкривають +нормалізовані факти про джерело встановлення поруч із сирим блоком `openclaw.install`. Нормалізовані +факти вказують, чи є npm spec точною версією чи плаваючим селектором, +чи присутні очікувані метадані цілісності, і чи доступний також локальний +шлях до джерела. Споживачі мають трактувати `installSource` як адитивне необов’язкове поле, щоб +старіші вручну зібрані записи й shim-и сумісності не мусили його синтезувати. +Це дає змогу онбордингу та діагностиці пояснювати стан source plane без +імпорту runtime Plugin. -Офіційні зовнішні npm-записи повинні надавати перевагу точному `npmSpec` плюс -`expectedIntegrity`. Прості назви пакетів і dist-tag, як і раніше, працюють для -сумісності, але вони показують попередження на рівні площини джерела, тож каталог може рухатися -до закріплених установлень із перевіркою цілісності без порушення роботи наявних plugin. +Офіційні зовнішні npm-записи мають віддавати перевагу точному `npmSpec` разом із +`expectedIntegrity`. Прості назви пакетів і dist-tag-и все ще працюють для +сумісності, але вони показують попередження source plane, щоб каталог міг рухатися +до pinned-установлень із перевіркою цілісності без порушення роботи наявних Plugin. +Коли онбординг виконує встановлення з локального шляху каталогу, він записує +запис `plugins.installs` із `source: "path"` і `sourcePath`, відносним до workspace, +коли це можливо. Абсолютний робочий шлях завантаження залишається в +`plugins.load.paths`; запис встановлення уникає дублювання шляхів локальної робочої станції +в довготривалій конфігурації. Це зберігає видимість локальних встановлень для розробки в +діагностиці source plane без додавання другої сирої поверхні розкриття шляхів файлової системи. -## Plugins рушія контексту +## Plugin рушія контексту -Plugins рушія контексту володіють оркестрацією контексту сесії для інгесту, збирання -та Compaction. Реєструйте їх зі свого plugin через +Plugin рушія контексту володіють orchestration контексту сесії для ingest, assembly +і Compaction. Реєструйте їх зі свого Plugin через `api.registerContextEngine(id, factory)`, а потім вибирайте активний рушій через `plugins.slots.contextEngine`. -Використовуйте це, коли вашому plugin потрібно замінити або розширити типовий -конвеєр контексту, а не просто додати пошук у пам'яті або hooks. +Використовуйте це, коли вашому Plugin потрібно замінити або розширити типовий +конвеєр контексту, а не просто додати пошук у пам’яті чи хуки. ```ts import { buildMemorySystemPromptAddition } from "openclaw/plugin-sdk/core"; @@ -972,60 +981,60 @@ export default function (api) { ## Додавання нової можливості -Коли plugin потребує поведінки, яка не вписується в поточний API, не обходьте -систему plugin через приватне пряме втручання. Додайте відсутню можливість. +Коли Plugin потрібна поведінка, яка не вписується в поточний API, не обходьте +систему Plugin через приватне пряме втручання. Додайте відсутню можливість. Рекомендована послідовність: 1. визначте контракт ядра - Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, злиття конфігурації, - життєвий цикл, семантика для каналів і форма runtime-допоміжного засобу. -2. додайте типізовані поверхні реєстрації plugin/runtime - Розширте `OpenClawPluginApi` та/або `api.runtime` найменшою корисною + Вирішіть, якою спільною поведінкою має володіти ядро: політика, fallback, злиття config, + життєвий цикл, семантика, видима для каналу, і форма runtime-допоміжного засобу. +2. додайте типізовані поверхні реєстрації/runtime Plugin + Розширте `OpenClawPluginApi` і/або `api.runtime` найменшою корисною типізованою поверхнею можливості. -3. підключіть ядро + споживачів каналів/функцій - Канали та plugins функцій повинні споживати нову можливість через ядро, +3. підключіть споживачів ядра + каналів/функцій + Канали та Plugin функцій мають споживати нову можливість через ядро, а не імпортувати реалізацію вендора напряму. 4. зареєструйте реалізації вендорів - Потім plugins вендорів реєструють свої backend для цієї можливості. + Потім вендорські Plugin реєструють свої backends для цієї можливості. 5. додайте покриття контракту - Додайте тести, щоб правила володіння та форма реєстрації з часом залишалися явними. + Додайте тести, щоб володіння й форма реєстрації з часом залишалися явними. -Саме так OpenClaw залишається виразно спроєктованим, не стаючи жорстко прив'язаним до -уявлення одного провайдера. Див. [Посібник із можливостей](/uk/plugins/architecture), -щоб отримати конкретний список файлів і готовий приклад. +Саме так OpenClaw зберігає чітку позицію, не стаючи жорстко прив’язаним до +світогляду одного провайдера. Див. [Capability Cookbook](/uk/plugins/architecture) +для конкретного контрольного списку файлів і опрацьованого прикладу. ### Контрольний список можливості -Коли ви додаєте нову можливість, реалізація зазвичай має одночасно торкатися таких -поверхонь: +Коли ви додаєте нову можливість, реалізація зазвичай має торкатися цих +поверхонь разом: - типи контракту ядра в `src//types.ts` - runner/runtime-допоміжний засіб ядра в `src//runtime.ts` -- поверхня реєстрації API plugin в `src/plugins/types.ts` -- підключення реєстру plugin в `src/plugins/registry.ts` -- надання runtime plugin у `src/plugins/runtime/*`, коли plugins функцій/каналів - мають її споживати -- допоміжні засоби capture/test в `src/test-utils/plugin-registration.ts` -- твердження володіння/контракту в `src/plugins/contracts/registry.ts` -- документація для операторів/plugin у `docs/` +- поверхня реєстрації Plugin API в `src/plugins/types.ts` +- підключення реєстру Plugin у `src/plugins/registry.ts` +- відкриття runtime Plugin у `src/plugins/runtime/*`, коли Plugin функцій/каналів + мають це споживати +- допоміжні засоби capture/test у `src/test-utils/plugin-registration.ts` +- перевірки володіння/контракту в `src/plugins/contracts/registry.ts` +- документація для оператора/Plugin у `docs/` -Якщо однієї з цих поверхонь бракує, зазвичай це ознака того, що можливість -ще не повністю інтегровано. +Якщо одна з цих поверхонь відсутня, це зазвичай ознака того, що можливість +ще не повністю інтегрована. ### Шаблон можливості Мінімальний шаблон: ```ts -// контракт ядра +// core contract export type VideoGenerationProviderPlugin = { id: string; label: string; generateVideo: (req: VideoGenerationRequest) => Promise; }; -// API plugin +// plugin API api.registerVideoGenerationProvider({ id: "openai", label: "OpenAI", @@ -1034,7 +1043,7 @@ api.registerVideoGenerationProvider({ }, }); -// спільний runtime-допоміжний засіб для plugins функцій/каналів +// shared runtime helper for feature/channel plugins const clip = await api.runtime.videoGeneration.generate({ prompt: "Show the robot walking through the lab.", cfg, @@ -1049,14 +1058,14 @@ expect(findVideoGenerationProviderIdsForPlugin("openai")).toEqual(["openai"]); Це зберігає правило простим: -- ядро володіє контрактом можливості + оркестрацією -- plugins вендорів володіють реалізаціями вендорів -- plugins функцій/каналів споживають runtime-допоміжні засоби -- тести контракту зберігають правила володіння явними +- ядро володіє контрактом можливості + orchestration +- вендорські Plugin володіють реалізаціями вендора +- Plugin функцій/каналів споживають runtime-допоміжні засоби +- тести контракту зберігають володіння явним -## Пов'язані матеріали +## Пов’язані матеріали -- [Архітектура Plugin](/uk/plugins/architecture) — публічна модель можливостей і форми -- [Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths) -- [Налаштування Plugin SDK](/uk/plugins/sdk-setup) -- [Створення plugin](/uk/plugins/building-plugins) +- [Plugin architecture](/uk/plugins/architecture) — публічна модель можливостей і форми +- [Plugin SDK subpaths](/uk/plugins/sdk-subpaths) +- [Plugin SDK setup](/uk/plugins/sdk-setup) +- [Building plugins](/uk/plugins/building-plugins) diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 630906291..e9bf4abe3 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -1,51 +1,51 @@ --- read_when: - Запуск або виправлення тестів -summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage +summary: Як запускати тести локально (`vitest`) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-24T05:03:56Z" + generated_at: "2026-04-24T07:42:14Z" model: gpt-5.4 provider: openai - source_hash: df4ad5808ddbc06c704c9bcf9f780b06f9be94ac213ed22e79d880dedcaa6d3b + source_hash: 26cdb5fe005e738ddd00b183e91ccebe08c709bd64eed377d573a37b76e3a3bf source_path: reference/test.md workflow: 15 --- -- Повний набір для тестування (набори, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (набори тестів, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує типовий порт керування, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували з уже запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив порт 18789 зайнятим. -- `pnpm test:coverage`: запускає набір unit-тестів із покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття unit-тестів для завантажених файлів, а не покриття всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка оцінює файли, завантажені набором unit coverage, замість того щоб вважати всі файли вихідного коду в розділених lane-ах непокритими. +- `pnpm test:force`: завершує будь-який завислий процес gateway, який утримує типовий порт керування, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: запускає набір unit-тестів із покриттям V8 (через `vitest.unit.config.ts`). Це поріг покриття unit-тестів для завантажених файлів, а не покриття всіх файлів у всьому репозиторії. Пороги становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, поріг вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен файл вихідного коду з розділених lane непокритим. - `pnpm test:coverage:changed`: запускає unit coverage лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lane-и, коли diff зачіпає лише routable файли коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску кореневих проєктів, щоб зміни wiring за потреби повторно запускали ширший набір. -- `pnpm changed:lanes`: показує архітектурні lane-и, які активує diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумну перевірку змін для diff відносно `origin/main`. Вона запускає core-роботи з core test lane-ами, роботу розширень — з extension test lane-ами, зміни лише в тестах — лише з test typecheck/tests, розширює зміни публічного Plugin SDK або plugin-contract до одного проходу валідації розширень, і залишає зміни лише в release metadata version bumps на цільових перевірках version/config/root-dependency. -- `pnpm test`: спрямовує явні цілі файлів/каталогів через scoped Vitest lane-и. Запуски без цілей використовують фіксовані групи shard-ів і розгортаються до leaf config-ів для локального паралельного виконання; група extension завжди розгортається до per-extension shard config-ів замість одного великого процесу root-project. -- Повні запуски та запуски shard-ів розширень оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги, щоб збалансувати повільні й швидкі shard-и. Встановіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через виділені легкі lane-и, у яких залишається лише `test/setup.ts`, а важкі runtime-кейси залишаються на своїх наявних lane-ах. -- Вибрані допоміжні файли коду `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` із явними сусідніми тестами в цих легких lane-ах, тому невеликі зміни хелперів не змушують повторно запускати важкі набори, що залежать від runtime. -- `auto-reply` тепер також розділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper. +- `pnpm test:changed`: розгортає змінені git-шляхи в scoped Vitest lanes, коли diff торкається лише routable файлів вихідного коду/тестів. Зміни в config/setup усе одно повертаються до нативного запуску кореневих проєктів, щоб зміни в підключенні запускали ширший повторний прогін там, де це потрібно. +- `pnpm changed:lanes`: показує архітектурні lanes, активовані diff відносно `origin/main`. +- `pnpm check:changed`: запускає розумну перевірку changed для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lanes, роботу розширень — разом із extension test lanes, зміни лише в тестах — лише з test typecheck/tests, розгортає зміни в публічному Plugin SDK або plugin-contract до одного проходу валідації розширень і залишає підвищення версій лише в release metadata націленими перевірками version/config/root-dependency. +- `pnpm test`: спрямовує явні цілі file/directory через scoped Vitest lanes. Запуски без цілі використовують фіксовані shard-групи та розгортаються до leaf config для локального паралельного виконання; група extension завжди розгортається до shard config окремих extension/plugin, а не до одного великого процесу root-project. +- Повні запуски та запуски extension shard оновлюють локальні дані таймінгу в `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги, щоб збалансувати повільні й швидкі shard. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгу. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через спеціальні легкі lanes, які зберігають лише `test/setup.ts`, залишаючи runtime-heavy випадки на їхніх наявних lanes. +- Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lanes, щоб малі зміни в helper не примушували повторно запускати важкі набори тестів із підтримкою runtime. +- `auto-reply` тепер також розбивається на три спеціальні config (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper. - Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в конфігураціях усього репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extension/plugin. Важкі channel plugin-и, browser plugin і OpenAI запускаються як окремі shard-и; інші групи plugin-ів залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. -- `pnpm test:perf:imports`: вмикає звітування Vitest про тривалість імпортів і їх розбивку, водночас усе ще використовуючи маршрутизацію scoped lane-ів для явних цілей файлів/каталогів. -- `pnpm test:perf:imports:changed`: такий самий профайлінг імпортів, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` порівнює в режимі benchmark маршрут changed-mode із нативним запуском root-project для того самого закоміченого git diff. -- `pnpm test:perf:changed:bench -- --worktree` порівнює поточний набір змін у worktree без попереднього коміту. -- `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`). +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. +- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та деталізацію імпорту, водночас і далі використовуючи scoped lane routing для явних цілей file/directory. +- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює за бенчмарком routed changed-mode path із нативним запуском root-project для того самого закоміченого git diff. +- `pnpm test:perf:changed:bench -- --worktree` порівнює за бенчмарком поточний набір змін у worktree без попереднього коміту. +- `pnpm test:perf:profile:main`: записує CPU profile для основного потоку Vitest (`.artifacts/vitest-main-profile`). - `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf config повного набору Vitest і записує згруповані дані тривалості разом із JSON/лог-артефактами для кожної конфігурації. Test Performance Agent використовує це як базову лінію перед спробами виправити повільні тести. -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після зміни, зосередженої на продуктивності. -- Інтеграція Gateway: вмикається явно через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (парування multi-instance WS/HTTP/node). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. -- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потрібні API-ключі та `LIVE=1` (або специфічний для провайдера `*_LIVE_TEST=1`) для зняття skip. -- `pnpm test:docker:all`: один раз збирає спільний образ live-тестів і Docker E2E image, а потім запускає Docker smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1` із типовим рівнем паралелізму 8. Налаштовуйте основний пул через `OPENCLAW_DOCKER_ALL_PARALLELISM=`, а хвостовий пул, чутливий до провайдера, через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=`; обидва типово мають значення 8. Runner припиняє планувати нові lane-и в пулі після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а для кожного lane діє тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Логи для кожного lane записуються в `.artifacts/docker-tests//`. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксійований чат через `/api/chat/completions`. Потрібен робочий ключ live model (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і цей сценарій не очікується стабільним у CI так, як звичайні набори unit/e2e. -- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із попереднім заповненням і другий клієнтський контейнер, який піднімає `openclaw mcp serve`, а потім перевіряє виявлення маршрутизованих розмов, читання transcript, метадані вкладень, поведінку черги live-подій, маршрутизацію outbound send, а також сповіщення про channel і permission у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, щоб smoke-тест відображав те, що міст насправді надсилає. +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf config повного набору Vitest і записує згруповані дані тривалості плюс JSON/log артефакти для кожної config. Агент продуктивності тестів використовує це як baseline перед спробами виправити повільні тести. +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність. +- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає smoke-тести end-to-end для gateway (парування кількох екземплярів WS/HTTP/node). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`. +- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потрібні API-ключі та `LIVE=1` (або специфічний для провайдера `*_LIVE_TEST=1`), щоб зняти пропуск. +- `pnpm test:docker:all`: один раз збирає спільний образ live-test і образ Docker E2E, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` з типовим рівнем паралелізму 8. Налаштовуйте основний пул через `OPENCLAW_DOCKER_ALL_PARALLELISM=` і чутливий до провайдера хвостовий пул через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=`; обидва типово дорівнюють 8. Запуски lanes типово зміщуються на 2 секунди, щоб уникнути локальних штормів створення в Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner припиняє планувати нові pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, і кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Логи для кожного lane записуються в `.artifacts/docker-tests//`. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потрібен придатний ключ live model (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і стабільність у CI тут не очікується такою самою, як для звичайних unit/e2e наборів. +- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із підготовленими даними та другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення routed conversation, читання transcript, метадані вкладень, поведінку черги live events, маршрутизацію outbound send, а також сповіщення про channel і permissions у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, тож smoke відображає те, що міст фактично надсилає. ## Локальна PR-перевірка -Для локальних перевірок перед злиттям/gate PR запускайте: +Для локальних перевірок перед злиттям/проходженням PR виконайте: - `pnpm check:changed` - `pnpm check` @@ -54,7 +54,7 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` дає flaky-результат на навантаженому хості, повторіть запуск один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` дає flaky-результат на завантаженій машині, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для машин з обмеженнями пам’яті використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` @@ -66,10 +66,10 @@ x-i18n: Використання: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` -- Необов’язкові змінні середовища: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` -- Типовий prompt: “Reply with a single word: ok. No punctuation or extra text.” +- Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` +- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.” -Останній запуск (2025-12-31, 20 runs): +Останній запуск (2025-12-31, 20 запусків): - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) @@ -95,41 +95,41 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -Presets: +Набори preset: - `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status` - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` -- `all`: обидва presets +- `all`: обидва preset -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8 profiles для кожного запуску, тож вимірювання часу й захоплення профілів використовують той самий harness. +Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8 profiles для кожного запуску, тож вимірювання часу й збирання profiles використовують один і той самий harness. -Умовні позначення для збереженого виводу: +Угоди щодо збережених результатів: -- `pnpm test:startup:bench:smoke` записує артефакт цільового smoke у `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json` з `runs=5` і `warmup=1` +- `pnpm test:startup:bench:smoke` записує цільовий smoke artifact у `.artifacts/cli-startup-bench-smoke.json` +- `pnpm test:startup:bench:save` записує artifact повного набору в `.artifacts/cli-startup-bench-all.json` з `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює зафіксований у репозиторії baseline fixture у `test/fixtures/cli-startup-bench.json` з `runs=5` і `warmup=1` -Закомічений fixture: +Зафіксований у репозиторії fixture: - `test/fixtures/cli-startup-bench.json` -- Оновлення: `pnpm test:startup:bench:update` -- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check` +- Оновлення через `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture через `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) -Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів. +Docker не є обов’язковим; це потрібно лише для контейнеризованих smoke-тестів onboarding. -Повний cold-start flow у чистому Linux-контейнері: +Повний cold-start сценарій у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт проходить інтерактивний майстер через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. -## Smoke-тест QR-імпорту (Docker) +## Smoke-тест імпорту QR (Docker) -Гарантує, що підтримуваний допоміжний QR runtime коректно завантажується в підтримуваних Docker Node runtime-ах (типово Node 24, сумісний Node 22): +Гарантує, що підтримуваний QR runtime helper завантажується в підтримуваних Node runtime у Docker (типово Node 24, сумісність із Node 22): ```bash pnpm test:docker:qr diff --git a/docs/uk/tools/browser.md b/docs/uk/tools/browser.md index b8de5d88c..bd1425850 100644 --- a/docs/uk/tools/browser.md +++ b/docs/uk/tools/browser.md @@ -1,15 +1,15 @@ --- read_when: - Додавання автоматизації браузера, керованої агентом - - Налагодження того, чому openclaw заважає роботі вашого власного Chrome + - Налагодження, чому openclaw заважає вашому власному Chrome - Реалізація налаштувань браузера + життєвого циклу в застосунку macOS -summary: Інтегрований сервіс керування браузером + команди дій +summary: Інтегрована служба керування браузером + команди дій title: Браузер (керований OpenClaw) x-i18n: - generated_at: "2026-04-24T02:43:43Z" + generated_at: "2026-04-24T07:42:12Z" model: gpt-5.4 provider: openai - source_hash: 2fb0fc0b6235fa8a0324b754e247e015d5ca19d114d324d565ed4a19f9313f7e + source_hash: 80805676213ef5195093163874a848955b3c25364b20045a8d759d03ac088e14 source_path: tools/browser.md workflow: 15 --- @@ -21,19 +21,19 @@ OpenClaw може запускати **виділений профіль Chrome/ Погляд для початківців: - Думайте про це як про **окремий браузер лише для агента**. -- Профіль `openclaw` **не** торкається вашого особистого профілю браузера. +- Профіль `openclaw` **не** торкається профілю вашого особистого браузера. - Агент може **відкривати вкладки, читати сторінки, натискати й вводити текст** у безпечному середовищі. -- Вбудований профіль `user` підключається до вашої справжньої сесії Chrome із входом через Chrome MCP. +- Вбудований профіль `user` підключається до вашої реальної сесії Chrome з входом через Chrome MCP. ## Що ви отримуєте -- Окремий профіль браузера з назвою **openclaw** (помаранчевий акцент за замовчуванням). -- Детерміноване керування вкладками (список/відкрити/перемкнути/закрити). -- Дії агента (натискання/введення/перетягування/вибір), знімки, знімки екрана, PDF. +- Окремий профіль браузера з назвою **openclaw** (типово з помаранчевим акцентом). +- Детерміноване керування вкладками (перелік/відкриття/фокус/закриття). +- Дії агента (клік/введення/перетягування/вибір), знімки стану, скриншоти, PDF. - Необов’язкову підтримку кількох профілів (`openclaw`, `work`, `remote`, ...). -Цей браузер **не** є вашим щоденним браузером. Це безпечне, ізольоване середовище для -автоматизації та перевірки агентом. +Цей браузер **не** є вашим основним щоденним браузером. Це безпечна, ізольована поверхня для +автоматизації та перевірки з боку агента. ## Швидкий старт @@ -47,12 +47,12 @@ openclaw browser --browser-profile openclaw snapshot Якщо ви бачите “Browser disabled”, увімкніть це в конфігурації (див. нижче) і перезапустіть Gateway. -Якщо `openclaw browser` повністю відсутній або агент повідомляє, що інструмент браузера +Якщо `openclaw browser` взагалі відсутній або агент каже, що інструмент браузера недоступний, перейдіть до [Відсутня команда браузера або інструмент](/uk/tools/browser#missing-browser-command-or-tool). ## Керування Plugin -Інструмент `browser` за замовчуванням є вбудованим Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє ту саму назву інструмента `browser`: +Типовий інструмент `browser` — це вбудований Plugin. Вимкніть його, щоб замінити іншим Plugin, який реєструє ту саму назву інструмента `browser`: ```json5 { @@ -66,13 +66,13 @@ Gateway. } ``` -Для значень за замовчуванням потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Вимкнення лише Plugin прибирає CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента та сервіс керування як єдиний блок; ваша конфігурація `browser.*` залишається недоторканою для заміни. +Для типових значень потрібні і `plugins.entries.browser.enabled`, і `browser.enabled=true`. Вимкнення лише Plugin прибирає CLI `openclaw browser`, метод Gateway `browser.request`, інструмент агента та сервіс керування як єдине ціле; ваш конфіг `browser.*` залишається недоторканим для заміни. -Зміни конфігурації браузера вимагають перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс. +Зміни конфігурації браузера потребують перезапуску Gateway, щоб Plugin міг повторно зареєструвати свій сервіс. ## Відсутня команда браузера або інструмент -Якщо `openclaw browser` невідомий після оновлення, відсутній `browser.request` або агент повідомляє, що інструмент браузера недоступний, типовою причиною є список `plugins.allow`, у якому немає `browser`. Додайте його: +Якщо `openclaw browser` невідомий після оновлення, `browser.request` відсутній або агент повідомляє, що інструмент браузера недоступний, зазвичай причина — список `plugins.allow`, у якому немає `browser`. Додайте його: ```json5 { @@ -82,26 +82,26 @@ Gateway. } ``` -`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist контролює завантаження Plugin, а політика інструментів застосовується лише після завантаження. Повне видалення `plugins.allow` також відновлює значення за замовчуванням. +`browser.enabled=true`, `plugins.entries.browser.enabled=true` і `tools.alsoAllow: ["browser"]` не замінюють членство в allowlist — allowlist керує завантаженням Plugin, а політика інструментів застосовується лише після завантаження. Видалення `plugins.allow` повністю також відновлює типову поведінку. -## Профілі: `openclaw` проти `user` +## Профілі: `openclaw` vs `user` - `openclaw`: керований, ізольований браузер (розширення не потрібне). -- `user`: вбудований профіль підключення Chrome MCP для вашої **справжньої сесії Chrome** - із входом. +- `user`: вбудований профіль підключення Chrome MCP до вашої **реальної сесії Chrome** + з входом. Для викликів інструмента браузера агентом: -- За замовчуванням: використовується ізольований браузер `openclaw`. -- Віддавайте перевагу `profile="user"`, коли важливі наявні сеанси з входом і користувач - перебуває за комп’ютером, щоб натиснути/схвалити будь-який запит на підключення. +- Типово: використовувати ізольований браузер `openclaw`. +- Віддавайте перевагу `profile="user"`, коли важливі наявні сесії з входом і користувач + знаходиться за комп’ютером, щоб натиснути/підтвердити будь-який запит на підключення. - `profile` — це явне перевизначення, коли вам потрібен конкретний режим браузера. -Встановіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. +Установіть `browser.defaultProfile: "openclaw"`, якщо хочете, щоб керований режим був типовим. ## Конфігурація -Налаштування браузера зберігаються в `~/.openclaw/openclaw.json`. +Налаштування браузера містяться в `~/.openclaw/openclaw.json`. ```json5 { @@ -146,45 +146,45 @@ Gateway. -- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (за замовчуванням `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зміщує похідні порти в тій самій групі. -- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, за замовчуванням використовується керований локальний порт CDP. -- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до рукопотискань WebSocket віддаленого CDP. +- Сервіс керування прив’язується до loopback на порту, похідному від `gateway.port` (типово `18791` = gateway + 2). Перевизначення `gateway.port` або `OPENCLAW_GATEWAY_PORT` зсуває похідні порти в тій самій групі. +- Локальні профілі `openclaw` автоматично призначають `cdpPort`/`cdpUrl`; задавайте їх лише для віддаленого CDP. Якщо `cdpUrl` не задано, типово використовується керований локальний CDP-порт. +- `remoteCdpTimeoutMs` застосовується до перевірок доступності HTTP для віддаленого (не-loopback) CDP; `remoteCdpHandshakeTimeoutMs` застосовується до WebSocket handshake віддаленого CDP. -- Навігація браузера та відкриття вкладок захищені від SSRF перед навігацією і повторно перевіряються, наскільки це можливо, на фінальному URL `http(s)` після неї. -- У строгому режимі SSRF також перевіряються виявлення кінцевих точок віддаленого CDP і запити `/json/version` (`cdpUrl`). -- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено за замовчуванням; вмикайте лише тоді, коли доступ браузера до приватної мережі навмисно вважається довіреним. -- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий псевдонім. +- Навігація браузера та відкриття вкладок захищені від SSRF перед навігацією та, наскільки можливо, повторно перевіряються на фінальному URL `http(s)` після неї. +- У строгому режимі SSRF також перевіряються виявлення віддалених CDP-ендпойнтів і запити `/json/version` (`cdpUrl`). +- `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork` типово вимкнено; вмикайте лише тоді, коли доступ браузера до приватної мережі свідомо вважається довіреним. +- `browser.ssrfPolicy.allowPrivateNetwork` залишається підтримуваним як застарілий синонім. - + -- `attachOnly: true` означає ніколи не запускати локальний браузер; лише підключатися, якщо він уже запущений. +- `attachOnly: true` означає ніколи не запускати локальний браузер; лише підключатися, якщо він уже працює. - `color` (на верхньому рівні та для кожного профілю) тонує інтерфейс браузера, щоб ви могли бачити, який профіль активний. -- Профіль за замовчуванням — `openclaw` (керований автономний). Використайте `defaultProfile: "user"`, щоб перейти на браузер користувача з входом. -- Порядок автовиявлення: системний браузер за замовчуванням, якщо він заснований на Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. +- Типовий профіль — `openclaw` (керований автономний). Використовуйте `defaultProfile: "user"`, щоб вибрати браузер користувача з входом. +- Порядок автовиявлення: системний браузер за замовчуванням, якщо він на базі Chromium; інакше Chrome → Brave → Edge → Chromium → Chrome Canary. - `driver: "existing-session"` використовує Chrome DevTools MCP замість сирого CDP. Не задавайте `cdpUrl` для цього драйвера. -- Задайте `browser.profiles..userDataDir`, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium (Brave, Edge тощо). +- Установіть `browser.profiles..userDataDir`, коли профіль existing-session має підключатися до нестандартного профілю користувача Chromium (Brave, Edge тощо). -## Використання Brave (або іншого браузера на основі Chromium) +## Використання Brave (або іншого браузера на базі Chromium) -Якщо вашим **системним браузером за замовчуванням** є браузер на основі Chromium (Chrome/Brave/Edge тощо), -OpenClaw використовує його автоматично. Задайте `browser.executablePath`, щоб перевизначити +Якщо вашим **системним браузером за замовчуванням** є браузер на базі Chromium (Chrome/Brave/Edge тощо), +OpenClaw автоматично використовує його. Установіть `browser.executablePath`, щоб перевизначити автовиявлення: ```bash openclaw config set browser.executablePath "/usr/bin/google-chrome" ``` -Або задайте його в конфігурації, для кожної платформи окремо: +Або задайте це в конфігурації для кожної платформи: @@ -218,41 +218,41 @@ openclaw config set browser.executablePath "/usr/bin/google-chrome" ## Локальне та віддалене керування -- **Локальне керування (за замовчуванням):** Gateway запускає loopback-сервіс керування і може запустити локальний браузер. -- **Віддалене керування (вузол-host):** запустіть вузол-host на машині, де є браузер; Gateway проксуватиме до нього дії браузера. -- **Віддалений CDP:** задайте `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб - підключитися до віддаленого браузера на основі Chromium. У цьому випадку OpenClaw не запускатиме локальний браузер. +- **Локальне керування (типово):** Gateway запускає loopback-сервіс керування і може запускати локальний браузер. +- **Віддалене керування (хост вузла):** запустіть хост вузла на машині, де є браузер; Gateway проксіює до нього дії браузера. +- **Віддалений CDP:** установіть `browser.profiles..cdpUrl` (або `browser.cdpUrl`), щоб + підключитися до віддаленого браузера на базі Chromium. У такому разі OpenClaw не запускатиме локальний браузер. -Поведінка під час зупинки відрізняється залежно від режиму профілю: +Поведінка зупинки відрізняється залежно від режиму профілю: - локальні керовані профілі: `openclaw browser stop` зупиняє процес браузера, який запустив OpenClaw -- профілі лише для підключення та профілі віддаленого CDP: `openclaw browser stop` закриває активний - сеанс керування та скидає перевизначення емуляції Playwright/CDP (viewport, +- профілі лише для підключення та профілі віддаленого CDP: `openclaw browser stop` закриває активну + сесію керування і скидає перевизначення емуляції Playwright/CDP (viewport, колірну схему, локаль, часовий пояс, офлайн-режим та подібний стан), навіть - якщо жоден процес браузера не був запущений OpenClaw + якщо OpenClaw не запускав жодного процесу браузера URL віддаленого CDP можуть містити автентифікацію: - Токени запиту (наприклад, `https://provider.example?token=`) - HTTP Basic auth (наприклад, `https://user:pass@provider.example`) -OpenClaw зберігає автентифікацію під час виклику кінцевих точок `/json/*` і під час підключення -до CDP WebSocket. Для токенів краще використовувати змінні середовища або менеджери секретів, -а не зберігати їх у файлах конфігурації. +OpenClaw зберігає автентифікацію під час виклику ендпойнтів `/json/*` і під час підключення +до CDP WebSocket. Для токенів віддавайте перевагу змінним середовища або менеджерам секретів +замість коміту їх у конфігураційні файли. -## Проксі браузера вузла (zero-config за замовчуванням) +## Node browser proxy (типово без додаткової конфігурації) -Якщо ви запускаєте **вузол-host** на машині, де є ваш браузер, OpenClaw може -автоматично маршрутизувати виклики інструмента браузера до цього вузла без додаткової конфігурації браузера. -Це типовий шлях для віддалених Gateway. +Якщо ви запускаєте **хост вузла** на машині, де є ваш браузер, OpenClaw може +автоматично маршрутизувати виклики інструмента браузера до цього вузла без жодної додаткової конфігурації браузера. +Це типовий шлях для віддалених gateway. -Примітки: +Нотатки: -- Вузол-host надає доступ до свого локального сервера керування браузером через **команду проксі**. +- Хост вузла надає доступ до свого локального сервера керування браузером через **proxy command**. - Профілі беруться з власної конфігурації `browser.profiles` вузла (так само, як локально). -- `nodeHost.browserProxy.allowProfiles` є необов’язковим. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через проксі, включно з маршрутами створення/видалення профілів. -- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядає це як межу мінімальних привілеїв: можна адресувати лише профілі з allowlist, а маршрути створення/видалення постійних профілів блокуються на поверхні проксі. +- `nodeHost.browserProxy.allowProfiles` — необов’язковий параметр. Залиште його порожнім для застарілої/типової поведінки: усі налаштовані профілі залишаються доступними через proxy, включно з маршрутами створення/видалення профілів. +- Якщо ви задаєте `nodeHost.browserProxy.allowProfiles`, OpenClaw розглядає це як межу мінімальних привілеїв: можна адресувати лише профілі з allowlist, а маршрути створення/видалення постійних профілів блокуються на поверхні proxy. - Вимкніть це, якщо воно вам не потрібне: - На вузлі: `nodeHost.browserProxy.enabled=false` - На gateway: `gateway.nodes.browser.mode="off"` @@ -283,41 +283,41 @@ URL підключення CDP через HTTPS і WebSocket. OpenClaw може } ``` -Примітки: +Нотатки: -- Замініть `` на ваш справжній токен Browserless. -- Виберіть кінцеву точку регіону, яка відповідає вашому обліковому запису Browserless (див. їхню документацію). +- Замініть `` на ваш реальний токен Browserless. +- Виберіть регіональний ендпойнт, який відповідає вашому обліковому запису Browserless (див. їхню документацію). - Якщо Browserless надає вам базовий URL HTTPS, ви можете або перетворити його на `wss://` для прямого підключення CDP, або залишити URL HTTPS і дозволити OpenClaw виявити `/json/version`. -## Постачальники прямого WebSocket CDP +## Провайдери прямого WebSocket CDP -Деякі хостингові сервіси браузерів надають **пряму кінцеву точку WebSocket**, а не -стандартне HTTP-виявлення CDP (`/json/version`). OpenClaw приймає три форми -URL CDP і автоматично вибирає правильну стратегію підключення: +Деякі хостингові браузерні сервіси надають **прямий ендпойнт WebSocket** замість +стандартного виявлення CDP на основі HTTP (`/json/version`). OpenClaw приймає три +форми URL CDP і автоматично вибирає правильну стратегію підключення: -- **HTTP(S)-виявлення** — `http://host[:port]` або `https://host[:port]`. +- **Виявлення HTTP(S)** — `http://host[:port]` або `https://host[:port]`. OpenClaw викликає `/json/version`, щоб виявити URL WebSocket debugger, а потім - підключається. Без резервного варіанта WebSocket. -- **Прямі кінцеві точки WebSocket** — `ws://host[:port]/devtools//` або + підключається. Резервного переходу на WebSocket немає. +- **Прямі ендпойнти WebSocket** — `ws://host[:port]/devtools//` або `wss://...` зі шляхом `/devtools/browser|page|worker|shared_worker|service_worker/`. - OpenClaw підключається напряму через рукопотискання WebSocket і повністю пропускає + OpenClaw підключається безпосередньо через WebSocket handshake і повністю пропускає `/json/version`. -- **Кореневі bare WebSocket** — `ws://host[:port]` або `wss://host[:port]` без +- **Кореневі URL 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 на bare-корені. Це дозволяє - bare `ws://`, спрямованому на локальний Chrome, усе одно підключатися, оскільки Chrome - приймає оновлення WebSocket лише на конкретному шляху для цілі з + переходить до прямого WebSocket handshake на корені без шляху. Це дозволяє + підключатися навіть bare `ws://`, спрямованому на локальний Chrome, оскільки Chrome приймає + WebSocket upgrade лише на конкретному шляху для цілі з `/json/version`. ### Browserbase [Browserbase](https://www.browserbase.com) — це хмарна платформа для запуску -headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode і residential +headless-браузерів із вбудованим розв’язанням CAPTCHA, stealth mode та residential proxy. ```json5 @@ -337,82 +337,81 @@ proxy. } ``` -Примітки: +Нотатки: - [Зареєструйтеся](https://www.browserbase.com/sign-up) і скопіюйте свій **API Key** з [панелі Overview](https://www.browserbase.com/overview). -- Замініть `` на свій справжній API key Browserbase. -- Browserbase автоматично створює сеанс браузера під час WebSocket-підключення, тому - окремий крок ручного створення сеансу не потрібен. -- Безкоштовний тариф дозволяє один одночасний сеанс і одну браузерну годину на місяць. - Обмеження платних планів дивіться в [pricing](https://www.browserbase.com/pricing). -- Повну довідку щодо API, - посібники SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). +- Замініть `` на ваш реальний API key Browserbase. +- Browserbase автоматично створює сесію браузера під час підключення WebSocket, тому + крок ручного створення сесії не потрібен. +- Безкоштовний тариф дозволяє одну одночасну сесію та одну годину браузера на місяць. + Ліміти платних планів дивіться в [pricing](https://www.browserbase.com/pricing). +- Повний довідник API, посібники з SDK та приклади інтеграції дивіться в [документації Browserbase](https://docs.browserbase.com). ## Безпека Ключові ідеї: -- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або сполучення вузлів. +- Керування браузером доступне лише через loopback; доступ проходить через автентифікацію Gateway або pairing з вузлом. - Автономний loopback HTTP API браузера використовує **лише автентифікацію зі спільним секретом**: - bearer-автентифікацію токеном gateway, `x-openclaw-password` або HTTP Basic auth із + bearer auth через токен gateway, `x-openclaw-password` або HTTP Basic auth із налаштованим паролем gateway. -- Заголовки ідентифікації Tailscale Serve і `gateway.auth.mode: "trusted-proxy"` +- Заголовки ідентичності Tailscale Serve та `gateway.auth.mode: "trusted-proxy"` **не** автентифікують цей автономний loopback API браузера. -- Якщо керування браузером увімкнено, але автентифікацію зі спільним секретом не налаштовано, OpenClaw - автоматично генерує `gateway.auth.token` під час запуску й зберігає його в конфігурації. -- OpenClaw **не** генерує цей токен автоматично, якщо `gateway.auth.mode` уже має значення +- Якщо керування браузером увімкнене й не налаштовано автентифікацію зі спільним секретом, OpenClaw + автоматично генерує `gateway.auth.token` під час запуску та зберігає його в конфігурації. +- OpenClaw **не** генерує цей токен автоматично, коли `gateway.auth.mode` уже має значення `password`, `none` або `trusted-proxy`. -- Тримайте Gateway і будь-які вузли-host у приватній мережі (Tailscale); уникайте публічного доступу. -- Вважайте URL/токени віддаленого CDP секретами; віддавайте перевагу змінним середовища або менеджеру секретів. +- Тримайте Gateway та всі хости вузлів у приватній мережі (Tailscale); уникайте публічного доступу. +- Ставтеся до URL/токенів віддаленого CDP як до секретів; віддавайте перевагу env vars або менеджеру секретів. Поради щодо віддаленого CDP: -- За можливості віддавайте перевагу зашифрованим кінцевим точкам (HTTPS або WSS) і короткоживучим токенам. -- Уникайте вбудовування довгоживучих токенів безпосередньо у файли конфігурації. +- За можливості віддавайте перевагу зашифрованим ендпойнтам (HTTPS або WSS) і короткоживучим токенам. +- Уникайте вбудовування довгоживучих токенів безпосередньо в конфігураційні файли. ## Профілі (кілька браузерів) -OpenClaw підтримує кілька іменованих профілів (конфігурацій маршрутизації). Профілі можуть бути: +OpenClaw підтримує кілька іменованих профілів (конфігурації маршрутизації). Профілі можуть бути: -- **керовані OpenClaw**: виділений екземпляр браузера на основі Chromium із власним каталогом користувацьких даних + портом CDP -- **віддалені**: явний URL CDP (браузер на основі Chromium, що працює в іншому місці) -- **наявний сеанс**: ваш наявний профіль Chrome через автоматичне підключення Chrome DevTools MCP +- **керовані OpenClaw**: виділений екземпляр браузера на базі Chromium із власним каталогом даних користувача + портом CDP +- **віддалені**: явний URL CDP (браузер на базі Chromium, що працює деінде) +- **наявна сесія**: ваш наявний профіль Chrome через автопідключення Chrome DevTools MCP -Значення за замовчуванням: +Типові значення: -- Профіль `openclaw` автоматично створюється, якщо його немає. +- Профіль `openclaw` створюється автоматично, якщо його немає. - Профіль `user` вбудований для підключення existing-session через Chrome MCP. -- Профілі existing-session, крім `user`, потрібно вмикати явно; створюйте їх за допомогою `--driver existing-session`. -- Локальні порти CDP за замовчуванням виділяються з діапазону **18800–18899**. -- Видалення профілю переміщує його локальний каталог даних до кошика. +- Профілі existing-session, окрім `user`, вмикаються явно; створюйте їх через `--driver existing-session`. +- Локальні порти CDP типово виділяються з діапазону **18800–18899**. +- Видалення профілю переміщує його локальний каталог даних до Trash. -Усі кінцеві точки керування приймають `?profile=`; CLI використовує `--browser-profile`. +Усі ендпойнти керування приймають `?profile=`; CLI використовує `--browser-profile`. ## Existing-session через Chrome DevTools MCP -OpenClaw також може підключатися до запущеного профілю браузера на основі Chromium через +OpenClaw також може підключатися до запущеного профілю браузера на базі Chromium через офіційний сервер Chrome DevTools MCP. Це повторно використовує вкладки та стан входу, які вже відкриті в цьому профілі браузера. -Офіційні матеріали з поясненням і налаштуванням: +Офіційні довідкові матеріали та налаштування: -- [Chrome for Developers: Use Chrome DevTools MCP with your browser session](https://developer.chrome.com/blog/chrome-devtools-mcp-debug-your-browser-session) -- [Chrome DevTools MCP README](https://github.com/ChromeDevTools/chrome-devtools-mcp) +- [Chrome for Developers: Використання Chrome DevTools MCP із вашою сесією браузера](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, якщо хочете -іншу назву, колір або каталог даних браузера. +Необов’язково: створіть власний користувацький профіль existing-session, якщо вам потрібні +інша назва, колір або каталог даних браузера. -Поведінка за замовчуванням: +Типова поведінка: -- Вбудований профіль `user` використовує авто-підключення Chrome MCP, яке націлюється на - локальний профіль Google Chrome за замовчуванням. +- Вбудований профіль `user` використовує автопідключення Chrome MCP, яке націлюється на + типовий локальний профіль Google Chrome. -Використовуйте `userDataDir` для Brave, Edge, Chromium або профілю Chrome, що не є типовим: +Використовуйте `userDataDir` для Brave, Edge, Chromium або нетипового профілю Chrome: ```json5 { @@ -433,7 +432,7 @@ OpenClaw також може підключатися до запущеного 1. Відкрийте сторінку inspect цього браузера для віддаленого налагодження. 2. Увімкніть віддалене налагодження. -3. Залиште браузер запущеним і схваліть запит на підключення, коли OpenClaw підключатиметься. +3. Залиште браузер запущеним і підтвердьте запит на підключення, коли OpenClaw під’єднається. Поширені сторінки inspect: @@ -441,7 +440,7 @@ OpenClaw також може підключатися до запущеного - Brave: `brave://inspect/#remote-debugging` - Edge: `edge://inspect/#remote-debugging` -Smoke-тест live attach: +Live attach smoke test: ```bash openclaw browser --browser-profile user start @@ -450,58 +449,58 @@ 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` повертає ref із вибраної живої вкладки +- `tabs` перелічує вже відкриті вкладки браузера +- `snapshot` повертає ref з вибраної live-вкладки Що перевірити, якщо підключення не працює: -- цільовий браузер на основі Chromium має версію `144+` -- у сторінці inspect цього браузера ввімкнено віддалене налагодження -- браузер показав запит на згоду на підключення, і ви його прийняли -- `openclaw doctor` переносить стару конфігурацію браузера на основі розширення та перевіряє, - що Chrome локально встановлено для типових профілів авто-підключення, але він не може - увімкнути віддалене налагодження на боці браузера за вас +- цільовий браузер на базі Chromium має версію `144+` +- віддалене налагодження увімкнене на сторінці inspect цього браузера +- браузер показав запит на підключення, і ви його підтвердили +- `openclaw doctor` переносить стару конфігурацію браузера на основі розширення та перевіряє, що + Chrome встановлено локально для типових профілів автопідключення, але він не може + увімкнути віддалене налагодження в браузері за вас Використання агентом: -- Використовуйте `profile="user"`, коли вам потрібен браузер користувача зі станом входу. -- Якщо ви використовуєте власний профіль existing-session, передайте явну назву цього профілю. -- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб схвалити +- Використовуйте `profile="user"`, коли вам потрібен стан браузера користувача з виконаним входом. +- Якщо ви використовуєте власний профіль existing-session, передайте його явну назву профілю. +- Обирайте цей режим лише тоді, коли користувач перебуває за комп’ютером, щоб підтвердити запит на підключення. -- Gateway або вузол-host можуть запускати `npx chrome-devtools-mcp@latest --autoConnect` +- Gateway або хост вузла може запускати `npx chrome-devtools-mcp@latest --autoConnect` -Примітки: +Нотатки: -- Цей шлях є ризикованішим за ізольований профіль `openclaw`, оскільки він може - працювати всередині вашої сесії браузера з виконаним входом. +- Цей шлях є ризикованішим, ніж ізольований профіль `openclaw`, оскільки він може + виконувати дії у вашій сесії браузера з виконаним входом. - OpenClaw не запускає браузер для цього драйвера; він лише підключається. - Тут OpenClaw використовує офіційний потік Chrome DevTools MCP `--autoConnect`. Якщо - задано `userDataDir`, його буде передано далі для націлювання на цей каталог користувацьких даних. -- Existing-session може підключатися на вибраному host або через підключений - вузол браузера. Якщо Chrome розміщено в іншому місці й вузол браузера не підключено, використовуйте - натомість віддалений CDP або вузол-host. + встановлено `userDataDir`, його буде передано далі для націлювання на цей каталог даних користувача. +- Existing-session може підключатися на вибраному хості або через підключений + browser node. Якщо Chrome розташований деінде й browser node не підключений, використовуйте + натомість віддалений CDP або хост вузла. Порівняно з керованим профілем `openclaw`, драйвери existing-session мають більше обмежень: -- **Знімки екрана** — працюють захоплення сторінки та захоплення елемента через `--ref`; CSS-селектори `--element` не підтримуються. `--full-page` не можна поєднувати з `--ref` або `--element`. Для знімків сторінки або елемента на основі ref Playwright не потрібен. -- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` вимагають ref зі snapshot (без CSS-селекторів). `click` підтримує лише ліву кнопку. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `hover`, `scrollIntoView`, `drag`, `select`, `fill` і `evaluate` не підтримують окремі тайм-аути на виклик. `select` приймає одне значення. -- **Очікування / завантаження файлів / діалоги** — `wait --url` підтримує точні, підрядкові та glob-шаблони; `wait --load networkidle` не підтримується. Хуки завантаження файлів вимагають `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки діалогів не підтримують перевизначення тайм-ауту. -- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` усе ще вимагають шляху керованого браузера. +- **Скриншоти** — працюють знімки сторінки та знімки елементів через `--ref`; CSS-селектори `--element` не підтримуються. `--full-page` не можна поєднувати з `--ref` або `--element`. Для скриншотів сторінки або елементів на основі ref Playwright не потрібен. +- **Дії** — `click`, `type`, `hover`, `scrollIntoView`, `drag` і `select` потребують ref зі snapshot (без CSS-селекторів). `click` підтримує лише ліву кнопку. `type` не підтримує `slowly=true`; використовуйте `fill` або `press`. `press` не підтримує `delayMs`. `type`, `hover`, `scrollIntoView`, `drag`, `select`, `fill` та `evaluate` не підтримують тайм-аути для окремих викликів. `select` приймає одне значення. +- **Очікування / upload / dialog** — `wait --url` підтримує точні, часткові та glob-шаблони; `wait --load networkidle` не підтримується. Хуки upload потребують `ref` або `inputRef`, по одному файлу за раз, без CSS `element`. Хуки dialog не підтримують перевизначення тайм-аутів. +- **Функції лише для керованого режиму** — пакетні дії, експорт PDF, перехоплення завантажень і `responsebody` як і раніше потребують шляху керованого браузера. ## Гарантії ізоляції -- **Виділений каталог користувацьких даних**: ніколи не торкається вашого особистого профілю браузера. -- **Виділені порти**: уникає `9222`, щоб не створювати конфліктів із робочими процесами розробки. -- **Детерміноване керування вкладками**: націлювання на вкладки за `targetId`, а не за принципом «остання вкладка». +- **Виділений каталог даних користувача**: ніколи не торкається профілю вашого особистого браузера. +- **Виділені порти**: уникає `9222`, щоб запобігти конфліктам із dev-процесами. +- **Детерміноване керування вкладками**: націлювання на вкладки через `targetId`, а не через “last tab”. ## Вибір браузера @@ -517,41 +516,41 @@ 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 керування (необов’язково) +## Control API (необов’язково) -Для сценаріїв і налагодження Gateway надає невеликий **HTTP API керування, доступний лише через loopback**, -а також відповідний CLI `openclaw browser` (знімки, ref, розширені можливості wait, -JSON-вивід, сценарії налагодження). Повну довідку дивіться в -[API керування браузером](/uk/tools/browser-control). +Для сценаріїв і налагодження Gateway надає невеликий **HTTP Control API лише для loopback** +разом із відповідним CLI `openclaw browser` (знімки стану, ref, розширені можливості wait, +вивід JSON, сценарії налагодження). Повний довідник див. у +[Browser control API](/uk/tools/browser-control). ## Усунення несправностей -Для проблем, специфічних для Linux (особливо snap Chromium), дивіться +Для проблем, специфічних для Linux (особливо snap Chromium), див. [Усунення несправностей браузера](/uk/tools/browser-linux-troubleshooting). -Для конфігурацій із розділеними host WSL2 Gateway + Windows Chrome дивіться +Для конфігурацій із розділеними хостами WSL2 Gateway + Windows Chrome див. [WSL2 + Windows + усунення несправностей віддаленого Chrome CDP](/uk/tools/browser-wsl2-windows-remote-cdp-troubleshooting). -### Помилка запуску CDP проти блокування SSRF навігації +### Помилка запуску CDP vs блокування SSRF під час навігації -Це різні класи помилок, і вони вказують на різні шляхи в коді. +Це різні класи помилок, і вони вказують на різні шляхи виконання коду. - **Помилка запуску або готовності CDP** означає, що OpenClaw не може підтвердити, що площина керування браузером працює справно. -- **Блокування SSRF навігації** означає, що площина керування браузером справна, але ціль навігації сторінки відхиляється політикою. +- **Блокування SSRF під час навігації** означає, що площина керування браузером працює справно, але ціль переходу сторінки відхилена політикою. Поширені приклади: - Помилка запуску або готовності CDP: - `Chrome CDP websocket for profile "openclaw" is not reachable after start` - `Remote CDP for profile "" is not reachable at ` -- Блокування SSRF навігації: +- Блокування SSRF під час навігації: - потоки `open`, `navigate`, snapshot або відкриття вкладок завершуються помилкою політики браузера/мережі, тоді як `start` і `tabs` усе ще працюють -Використайте цю мінімальну послідовність, щоб відрізнити одне від іншого: +Використовуйте цю мінімальну послідовність, щоб розрізнити ці випадки: ```bash openclaw browser --browser-profile openclaw start @@ -561,21 +560,21 @@ openclaw browser --browser-profile openclaw open https://example.com Як читати результати: -- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблему готовності CDP. +- Якщо `start` завершується помилкою `not reachable after start`, спочатку усувайте проблеми готовності CDP. - Якщо `start` успішний, але `tabs` завершується помилкою, площина керування все ще несправна. Розглядайте це як проблему доступності CDP, а не проблему навігації сторінки. - Якщо `start` і `tabs` успішні, але `open` або `navigate` завершуються помилкою, площина керування браузером працює, а проблема в політиці навігації або цільовій сторінці. -- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером справний. +- Якщо `start`, `tabs` і `open` усі успішні, базовий шлях керування керованим браузером працює справно. Важливі деталі поведінки: -- Конфігурація браузера за замовчуванням використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`. -- Для локального керованого профілю loopback `openclaw` перевірки справності CDP навмисно пропускають застосування SSRF-перевірки доступності браузера до власної локальної площини керування OpenClaw. -- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що пізніша ціль `open` або `navigate` буде дозволена. +- Конфігурація браузера типово використовує fail-closed об’єкт політики SSRF, навіть якщо ви не налаштовуєте `browser.ssrfPolicy`. +- Для локального керованого профілю `openclaw` на loopback перевірки справності CDP навмисно пропускають перевірку доступності SSRF браузера для власної локальної площини керування OpenClaw. +- Захист навігації є окремим. Успішний результат `start` або `tabs` не означає, що подальша ціль `open` або `navigate` буде дозволена. -Рекомендації щодо безпеки: +Рекомендації з безпеки: -- **Не** послаблюйте політику SSRF браузера за замовчуванням. -- Віддавайте перевагу вузьким виняткам для host, як-от `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі. +- **Не** послаблюйте політику SSRF браузера типово. +- Віддавайте перевагу вузьким виняткам для хостів, таким як `hostnameAllowlist` або `allowedHostnames`, замість широкого доступу до приватної мережі. - Використовуйте `dangerouslyAllowPrivateNetwork: true` лише в навмисно довірених середовищах, де доступ браузера до приватної мережі потрібен і перевірений. ## Інструменти агента + як працює керування @@ -584,22 +583,22 @@ openclaw browser --browser-profile openclaw open https://example.com - `browser` — status/start/stop/tabs/open/focus/close/snapshot/screenshot/navigate/act -Як це зіставляється: +Як це відображається: -- `browser snapshot` повертає стабільне дерево UI (AI або ARIA). -- `browser act` використовує ідентифікатори `ref` зі snapshot для click/type/drag/select. +- `browser snapshot` повертає стабільне дерево інтерфейсу (AI або ARIA). +- `browser act` використовує ID `ref` зі snapshot для click/type/drag/select. - `browser screenshot` захоплює пікселі (усю сторінку або елемент). - `browser` приймає: - - `profile`, щоб вибрати іменований профіль браузера (openclaw, chrome або remote CDP). - - `target` (`sandbox` | `host` | `node`), щоб вибрати, де знаходиться браузер. - - У sandbox-сеансах `target: "host"` вимагає `agents.defaults.sandbox.browser.allowHostControl=true`. - - Якщо `target` не задано: sandbox-сеанси за замовчуванням використовують `sandbox`, не-sandbox сеанси — `host`. + - `profile` для вибору іменованого профілю браузера (openclaw, chrome або віддалений CDP). + - `target` (`sandbox` | `host` | `node`) для вибору місця розташування браузера. + - У sandbox-сесіях `target: "host"` потребує `agents.defaults.sandbox.browser.allowHostControl=true`. + - Якщо `target` не вказано: sandbox-сесії типово використовують `sandbox`, сесії без sandbox типово використовують `host`. - Якщо підключено вузол із підтримкою браузера, інструмент може автоматично маршрутизуватися до нього, якщо ви явно не зафіксуєте `target="host"` або `target="node"`. -Це зберігає детермінованість агента й дозволяє уникати крихких селекторів. +Це зберігає детермінованість агента й допомагає уникати крихких селекторів. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента -- [Ізоляція](/uk/gateway/sandboxing) — керування браузером в ізольованих середовищах +- [Пісочниця](/uk/gateway/sandboxing) — керування браузером у sandbox-середовищах - [Безпека](/uk/gateway/security) — ризики керування браузером і посилення захисту