From 4cdfe83ae50d38ef8d835930fc34a452e470f6af Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 20:14:57 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/ci.md | 152 +- docs/uk/cli/config.md | 142 +- docs/uk/concepts/model-providers.md | 306 ++- docs/uk/concepts/models.md | 193 +- docs/uk/gateway/configuration-reference.md | 1610 +++++++-------- docs/uk/help/faq.md | 2166 ++++++++++---------- docs/uk/help/testing.md | 1052 +++++----- docs/uk/plugins/codex-harness.md | 294 ++- docs/uk/plugins/sdk-agent-harness.md | 217 +- docs/uk/providers/openai.md | 421 ++-- docs/uk/reference/wizard.md | 196 +- docs/uk/start/wizard-cli-reference.md | 252 +-- docs/uk/tools/llm-task.md | 34 +- 13 files changed, 3520 insertions(+), 3515 deletions(-) diff --git a/docs/uk/ci.md b/docs/uk/ci.md index cfd4b8e46..d80cafb57 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,48 +1,44 @@ --- read_when: - - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Вам потрібно зрозуміти, чому завдання CI було або не було запущене - Ви налагоджуєте збої перевірок GitHub Actions -summary: Граф завдань CI, обмежувальні перевірки за областю змін і локальні еквіваленти команд +summary: Граф завдань CI, шлюзи областей дії та локальні еквіваленти команд title: Конвеєр CI x-i18n: - generated_at: "2026-04-23T19:48:40Z" + generated_at: "2026-04-23T20:05:14Z" model: gpt-5.4 provider: openai - source_hash: 3e250c90d9be13dc25a0b028de5d72cf821387e33c0965cac7b935579e3c6ae7 + source_hash: 601bd170afc217e7e9841c3cc358b941c9706b2cec57f568c0b583888ac0b4e7 source_path: ci.md workflow: 15 --- # Конвеєр CI -CI запускається при кожному push у `main` і для кожного pull request. Він використовує розумне обмеження за областю змін, щоб пропускати дорогі завдання, коли змінилися лише не пов’язані частини. +CI запускається під час кожного пушу до `main` і кожного pull request. Він використовує розумне обмеження за областю дії, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. -QA Lab має окремі смуги CI поза основним workflow з розумним обмеженням за областю змін. Workflow -`Parity gate` запускається для відповідних змін у PR і через ручний запуск; він -збирає приватне QA runtime і порівнює agentic-набори mock GPT-5.4 і Opus 4.6. -Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через -ручний запуск; він розгалужує mock parity gate, live Matrix lane і live -Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, -а Telegram lane використовує Convex leases. `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, живу доріжку Matrix і живу +доріжку Telegram як паралельні завдання. Живі завдання використовують середовище `qa-live-shared`, +а доріжка Telegram використовує оренди Convex. `OpenClaw Release +Checks` також запускає ті самі доріжки QA Lab перед погодженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний maintainer-workflow для -очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і -закриває лише явно перелічені PR, коли `apply=true`. Перш ніж змінювати GitHub, -він перевіряє, що злитий PR справді змерджено і що кожен дублікат має або -спільну згадану issue, або перетин змінених фрагментів. +Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для очищення дублікатів після приземлення змін. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед змінами на GitHub він перевіряє, що +приземлений PR змерджено, і що кожен дублікат має або спільне пов’язане issue, +або перетин змінених фрагментів. -Workflow `Test Performance Agent` — це подієва службова смуга Codex -для повільних тестів. Вона не має окремого запуску лише за розкладом: -її може запустити успішний не-ботовий push CI у `main`, але вона пропускається, -якщо інший запуск workflow-run уже відбувся або виконується в той самий UTC-день. -Ручний запуск обходить це денне обмеження активності. Ця смуга будує -групований звіт продуктивності Vitest для повного набору тестів, дозволяє Codex -вносити лише невеликі виправлення продуктивності тестів без втрати покриття, а потім -повторно запускає звіт для повного набору тестів і відхиляє зміни, які зменшують -кількість базових тестів, що проходять. Якщо в базовому стані є тести, що падають, -Codex може виправляти лише очевидні збої, а звіт для повного набору після роботи агента -має пройти повністю, перш ніж щось буде закомічено. +Workflow `Test Performance Agent` — це керована подіями службова доріжка Codex +для повільних тестів. Вона не має окремого розкладу: її може запустити +успішний запуск CI після пушу не від бота на `main`, але вона пропускається, якщо того UTC-дня вже був або виконується інший запуск цього workflow. +Ручний запуск оминає це денне обмеження активності. Доріжка будує згрупований звіт про продуктивність Vitest для повного набору тестів, дозволяє Codex +вносити лише невеликі зміни продуктивності тестів без втрати покриття, потім повторно запускає звіт для повного набору +і відхиляє зміни, які зменшують базову кількість тестів, що проходять. +Якщо в базовому стані є тести, що падають, Codex може виправляти лише очевидні збої, а звіт для повного набору після роботи агента має проходити, перш ніж щось буде закомічено. +Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпекову модель drop-sudo, +що й агент документації. ```bash gh workflow run duplicate-after-merge.yml \ @@ -55,83 +51,83 @@ gh workflow run duplicate-after-merge.yml \ | Завдання | Призначення | Коли запускається | | -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | -| `preflight` | Визначає зміни лише в docs, змінені області, змінені extensions і будує маніфест CI | Завжди для не-чернеткових push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для не-чернеткових push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisories npm | Завжди для не-чернеткових push і PR | -| `security-fast` | Обов’язковий агрегатор для швидких security-завдань | Завжди для не-чернеткових push і PR | -| `build-artifacts` | Збирає `dist/`, Control UI, перевірки build-артефактів і повторно використовувані downstream-артефакти | Зміни, релевантні для Node | -| `checks-fast-core` | Швидкі Linux-смуги коректності, такі як bundled/plugin-contract/protocol перевірки | Зміни, релевантні для Node | -| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, релевантні для Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, релевантні для Node | -| `checks-node-core-test` | Шарди core Node-тестів, окрім channel, bundled, contract та extension-смуг | Зміни, релевантні для Node | -| `extension-fast` | Сфокусовані тести лише для змінених bundled plugins | Pull request із змінами в extension | -| `check` | Шардований еквівалент основної локальної перевірки: prod types, lint, guards, test types і strict smoke | Зміни, релевантні для Node | -| `check-additional` | Шарди для перевірок архітектури, меж, extension-surface guards, package-boundary і gateway-watch | Зміни, релевантні для Node | -| `build-smoke` | Smoke-тести зібраного CLI і smoke перевірка пам’яті на старті | Зміни, релевантні для Node | -| `checks` | Засіб перевірки для channel-тестів build-артефактів плюс сумісність 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 із використанням спільних build-артефактів | Зміни, релевантні для macOS | -| `macos-swift` | Swift lint, build і тести для застосунку macOS | Зміни, релевантні для macOS | -| `android` | Android unit-тести для обох flavor плюс одна debug APK-збірка | Зміни, релевантні для Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх main CI або ручний запуск | +| `preflight` | Виявлення змін лише в документації, змінених областей дії, змінених розширень і побудова маніфесту CI | Завжди для нечернеткових пушів і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для нечернеткових пушів і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо попереджень npm | Завжди для нечернеткових пушів і PR | +| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для нечернеткових пушів і PR | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і повторно використовувані downstream-артефакти | Зміни, пов’язані з Node | +| `checks-fast-core` | Швидкі доріжки коректності на Linux, як-от перевірки bundled/plugin-contract/protocol | Зміни, пов’язані з Node | +| `checks-fast-contracts-channels` | Шардовані перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, пов’язані з Node | +| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору розширень | Зміни, пов’язані з Node | +| `checks-node-core-test` | Шарди основних Node-тестів, без доріжок channel, bundled, contract і extension | Зміни, пов’язані з Node | +| `extension-fast` | Прицільні тести лише для змінених bundled plugins | Pull request зі змінами в розширеннях | +| `check` | Шардований еквівалент основного локального шлюзу: production types, lint, guards, test types і strict smoke | Зміни, пов’язані з Node | +| `check-additional` | Шарди перевірок архітектури, меж, поверхні розширень, меж пакетів і gateway-watch | Зміни, пов’язані з Node | +| `build-smoke` | Smoke-тести зібраного CLI та smoke перевірка пам’яті під час запуску | Зміни, пов’язані з Node | +| `checks` | Верифікатор для channel-тестів зібраних артефактів плюс сумісність з Node 22 лише для пушів | Зміни, пов’язані з Node | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Документацію змінено | +| `skills-python` | Ruff + pytest для Skills на основі Python | Зміни, релевантні Python Skills | +| `checks-windows` | Специфічні для Windows тестові доріжки | Зміни, релевантні Windows | +| `macos-node` | Доріжка тестів TypeScript на macOS із використанням спільних зібраних артефактів | Зміни, релевантні macOS | +| `macos-swift` | Swift lint, збірка та тести для застосунку macOS | Зміни, релевантні macOS | +| `android` | Android unit-тести для обох варіантів плюс одна 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` швидко падають, не чекаючи важчих матричних завдань для артефактів і платформ. -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. Після цього розгалужуються важчі платформені доріжки та доріжки середовища виконання: `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`. -Логіка області змін міститься в `scripts/ci-changed-scope.mjs` і покрита unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Зміни в workflow CI перевіряють граф Node CI та lint workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформені смуги й далі обмежуються змінами у вихідному коді відповідних платформ. -Перевірки Windows Node обмежені специфічними для Windows обгортками process/path, допоміжними засобами для npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цю смугу; не пов’язані зміни у вихідному коді, plugin, install-smoke і зміни лише в тестах залишаються на Linux Node-смугах, щоб не займати Windows worker із 16 vCPU для покриття, яке вже забезпечується звичайними шардами тестів. -Окремий workflow `install-smoke` повторно використовує той самий script області змін через власне завдання `preflight`. Він обчислює `run_install_smoke` на основі вужчого сигналу changed-smoke, тому Docker/install smoke запускається для змін, пов’язаних з install, packaging, container, production-змін bundled extension і core-поверхонь plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише в тестах і лише в docs не займають Docker workers. Його QR package smoke примушує Docker-шар `pnpm install` виконатися повторно, зберігаючи кеш BuildKit pnpm store, тому інсталяція все одно перевіряється без повторного завантаження залежностей при кожному запуску. Його gateway-network e2e повторно використовує runtime image, зібраний раніше в межах завдання, тому додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локальна команда `test:docker:all` попередньо збирає один спільний live-test image і один спільний образ зібраного застосунку `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke-смуги паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартну паралельність 4 можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled-смуги після першого збою, а кожна смуга має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Смуги, чутливі до старту або провайдера, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний live/E2E workflow відтворює шаблон спільного image, збираючи й публікуючи один GHCR Docker E2E image з тегом SHA перед Docker-матрицею, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований live/E2E workflow щодня запускає повний Docker-набір для release-path. Тести QR і installer Docker зберігають власні Dockerfile, зосереджені на інсталяції. Окреме завдання `docker-e2e-fast` запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд: repair залежностей setup-entry і синтетичну ізоляцію збоїв bundled-loader. Повна матриця bundled update/channel лишається manual/full-suite, оскільки виконує повторні реальні проходи npm update і doctor repair. +Логіка області дії міститься в `scripts/ci-changed-scope.mjs` і покривається unit-тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни workflow CI перевіряють граф Node CI плюс linting workflow, але самі по собі не примушують запускати нативні збірки Windows, Android або macOS; ці платформені доріжки залишаються обмеженими змінами у вихідному коді платформи. +Перевірки Windows Node обмежені специфічними для Windows обгортками process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які виконують цю доріжку; не пов’язані зміни вихідного коду, plugins, install-smoke та лише тестів залишаються на Linux Node-доріжках, щоб вони не резервували 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними тестовими шардами. +Окремий workflow `install-smoke` повторно використовує той самий скрипт області дії через власне завдання `preflight`. Він обчислює `run_install_smoke` з вужчого сигналу changed-smoke, тож Docker/install smoke запускається для змін, пов’язаних із встановленням, пакуванням, контейнерами, production-змін bundled extension і поверхнями core plugin/channel/gateway/Plugin SDK, які перевіряють Docker smoke-завдання. Зміни лише тестів і лише документації не резервують Docker workers. Його QR package smoke примушує Docker-шар `pnpm install` запускатися повторно, зберігаючи кеш BuildKit pnpm store, тож він усе ще перевіряє встановлення без повторного завантаження залежностей під час кожного запуску. Його gateway-network e2e повторно використовує образ runtime, зібраний раніше в цьому завданні, тож додає реальне покриття WebSocket між контейнерами без додавання ще однієї Docker-збірки. Локальна команда `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, потім запускає доріжки live/E2E smoke паралельно з `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштуйте типове значення паралелізму 4 через `OPENCLAW_DOCKER_ALL_PARALLELISM`. Локальний агрегатор за замовчуванням припиняє планувати нові pooled-доріжки після першої помилки, а кожна доріжка має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Доріжки, чутливі до запуску або провайдера, виконуються ексклюзивно після паралельного пулу. Повторно використовуваний workflow live/E2E відтворює шаблон спільного образу, збираючи й публікуючи один SHA-тегований образ Docker E2E у GHCR перед матрицею Docker, а потім запускаючи матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір для шляху релізу. Docker-тести QR та installer зберігають власні Dockerfile, орієнтовані на встановлення. Окреме завдання `docker-e2e-fast` запускає обмежений Docker-профіль bundled-plugin із тайм-аутом команди 120 секунд: відновлення залежностей setup-entry плюс ізоляція синтетичного збою bundled-loader. Повна матриця bundled update/channel залишається ручною/для повного набору, оскільки вона виконує повторні реальні проходи npm update і doctor repair. -Логіка локальних changed-lanes міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіше ставиться до архітектурних меж, ніж широке платформене обмеження в CI: production-зміни core запускають typecheck core prod плюс тести core, зміни лише в тестах core запускають лише typecheck/tests для тестів core, production-зміни extension запускають typecheck extension prod плюс тести extension, а зміни лише в тестах extension запускають лише typecheck/tests для тестів 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: зміни core production запускають перевірку типів core prod плюс core-тести, зміни лише core-тестів запускають лише перевірку типів/тести core test, зміни extension production запускають перевірку типів extension prod плюс extension-тести, а зміни лише extension-тестів запускають лише перевірку типів/тести extension test. Зміни в публічному Plugin SDK або plugin-contract розширюють валідацію до extension, оскільки розширення залежать від цих core-контрактів. Оновлення версій лише в метаданих релізу запускають прицільні перевірки version/config/root-dependency. Невідомі зміни root/config у безпечному режимі призводять до запуску всіх доріжок. -Для push матриця `checks` додає смугу `compat-node22`, яка виконується лише для push. Для pull request ця смуга пропускається, і матриця залишається зосередженою на звичайних тестових/channel-смугах. +Під час пушів матриця `checks` додає доріжку `compat-node22`, що запускається лише для пушів. Для pull request ця доріжка пропускається, і матриця залишається зосередженою на звичайних доріжках тестів/каналів. -Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання лишалося невеликим без надмірного резервування runner-ів: channel contracts виконуються як три зважені шарди, тести bundled plugin збалансовані між шістьма extension worker-ами, малі core unit-смуги об’єднані попарно, auto-reply виконується як три збалансовані worker-и замість шести дрібних worker-ів, а конфігурації agentic gateway/plugin розподілені по наявних source-only agentic Node-завданнях замість очікування build-артефактів. Широкі browser-, QA-, media- і miscellaneous plugin-тести використовують власні конфігурації Vitest замість спільного універсального plugin catch-all. Завдання extension shard виконують групи конфігурацій plugin послідовно з одним Vitest worker і більшим Node heap, щоб import-важкі пакети plugin не перевантажували малі CI runner-и. Широка smуга agents використовує спільний файл-паралельний планувальник Vitest, оскільки в ній домінують imports/планування, а не один окремий повільний тестовий файл. `runtime-config` виконується разом із шардом infra core-runtime, щоб спільний runtime-shard не залишався найдовшим. `check-additional` тримає разом package-boundary compile/canary-роботи й відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard виконує свої малі незалежні guards паралельно в межах одного завдання. Gateway watch, channel-тести й shard core support-boundary виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрано, зберігаючи старі назви перевірок як легкі завдання-верифікатори й водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. +Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування раннерів: channel contracts виконуються у трьох зважених шардах, тести bundled plugin збалансовані між шістьма workers розширень, невеликі core unit-доріжки спарені, auto-reply виконується у трьох збалансованих workers замість шести дрібних workers, а agentic gateway/plugin configs розподілені між наявними Node-завданнями agentic лише з вихідним кодом замість очікування зібраних артефактів. Широкі browser-, QA-, media- та різні plugin-тести використовують власні конфігурації Vitest замість спільного універсального plugin-набору. Завдання шардів розширень запускають групи конфігурацій plugin послідовно з одним Vitest worker і більшим heap Node, щоб важкі за імпортами пакети plugin не перевантажували малі CI-раннери. Широка доріжка agents використовує спільний файлово-паралельний планувальник Vitest, тому що в ній домінують імпорти/планування, а не один повільний тестовий файл. `runtime-config` виконується разом із шардом infra core-runtime, щоб спільний runtime-шард не тримав хвіст. `check-additional` тримає разом роботу compile/canary для package-boundary і відокремлює архітектуру топології runtime від покриття gateway watch; шард boundary guard запускає свої невеликі незалежні guards паралельно в межах одного завдання. Gateway watch, channel-тести та core support-boundary shard виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі назви перевірок як легкі завдання-верифікатори, але без двох додаткових Blacksmith workers і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його смуга unit-тестів усе одно компілює цей flavor із прапорцями SMS/call-log у BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK при кожному push, релевантному для Android. -`extension-fast` є лише для PR, тому що push-запуски вже виконують повні шарди bundled plugin. Це зберігає швидкий зворотний зв’язок для reviews щодо змінених plugin без резервування додаткового Blacksmith worker у `main` для покриття, яке вже є в `checks-node-extensions`. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Варіант third-party не має окремого набору вихідного коду чи маніфесту; його доріжка unit-тестів усе одно компілює цей варіант із прапорцями SMS/call-log у BuildConfig, водночас уникаючи дубльованого завдання пакування debug APK при кожному Android-релевантному пуші. +`extension-fast` працює лише для PR, оскільки запуски для push уже виконують повні шарди bundled plugin. Це зберігає зворотний зв’язок щодо змінених plugins для рев’ю без резервування додаткового Blacksmith worker на `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати замінені новішими завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані shard-перевірки використовують `!cancelled() && always()`, тож вони й далі повідомляють про звичайні збої shard-ів, але не стають у чергу після того, як увесь workflow уже був замінений новішим. +GitHub може позначати витіснені завдання як `cancelled`, коли новіший пуш потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не падає. Агреговані перевірки шардів використовують `!cancelled() && always()`, тож вони все одно повідомляють про звичайні збої шардів, але не стають у чергу після того, як увесь workflow уже був витіснений. Ключ конкурентності CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. -## Runner-и +## Раннери -| Runner | Завдання | +| Раннер | Завдання | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі security-завдання та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі protocol/contract/bundled-перевірки, шардовані перевірки channel contract, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори Node-тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла стати в чергу раніше | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегатори (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки channel contract, шарди `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-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` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; для форків використовується резервний `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; для форків використовується резервний `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумна локальна перевірка: changed typecheck/lint/tests за boundary lane -pnpm check # швидка локальна перевірка: production tsgo + sharded lint + parallel fast guards +pnpm check:changed # розумний локальний шлюз: змінені typecheck/lint/тести за boundary lane +pnpm check # швидкий локальний шлюз: production tsgo + шардований lint + паралельні швидкі guards pnpm check:test-types -pnpm check:timed # та сама перевірка з таймінгами для кожного етапу +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 +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 +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/cli/config.md b/docs/uk/cli/config.md index 93881a8e8..ea598a435 100644 --- a/docs/uk/cli/config.md +++ b/docs/uk/cli/config.md @@ -4,19 +4,19 @@ read_when: summary: Довідка CLI для `openclaw config` (get/set/unset/file/schema/validate) title: config x-i18n: - generated_at: "2026-04-23T19:23:54Z" + generated_at: "2026-04-23T20:05:10Z" model: gpt-5.4 provider: openai - source_hash: ec16221cc977eb2108c4310eab6b49e74220de50425ab12201cf97d275ab5a65 + source_hash: 19858f9becd98a56f4d993f1630b14c5f533121d3eaf8c37df9d39b0c8a41365 source_path: cli/config.md workflow: 15 --- # `openclaw config` -Допоміжні команди config для невзаємодіючих змін у `openclaw.json`: отримання/встановлення/видалення/файл/схема/перевірка +Допоміжні команди config для невзаємодіючих редагувань у `openclaw.json`: get/set/unset/file/schema/validate значень за шляхом і виведення активного файла config. Запустіть без підкоманди, щоб -відкрити майстер налаштування (так само, як `openclaw configure`). +відкрити майстер налаштування (те саме, що `openclaw configure`). Кореневі параметри: @@ -45,7 +45,7 @@ openclaw config get browser.executablePath openclaw config set browser.executablePath "/usr/bin/google-chrome" openclaw config set agents.defaults.heartbeat.every "2h" openclaw config set agents.list[0].tools.exec.node "node-id-or-name" -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge openclaw config set channels.discord.token --ref-provider default --ref-source env --ref-id DISCORD_BOT_TOKEN openclaw config set secrets.providers.vaultfile --provider-source file --provider-path /etc/openclaw/secrets.json --provider-mode json openclaw config unset plugins.entries.brave.config.webSearch.apiKey @@ -60,25 +60,25 @@ openclaw config validate --json Що вона містить: -- Поточну схему кореневого config, а також кореневе рядкове поле `$schema` для інструментів редактора -- Метадані документації полів `title` і `description`, які використовує інтерфейс Control UI -- Вкладені об’єкти, вузли-підстановки (`*`) і вузли елементів масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля +- Поточну кореневу схему config, а також кореневе строкове поле `$schema` для інструментів редактора +- Метадані документації полів `title` і `description`, що використовуються UI Control +- Вкладені об’єкти, вузли wildcard (`*`) і елементи масиву (`[]`) успадковують ті самі метадані `title` / `description`, коли існує відповідна документація поля - Гілки `anyOf` / `oneOf` / `allOf` також успадковують ті самі метадані документації, коли існує відповідна документація поля -- Метадані схем Plugin і channel у режимі best-effort, якщо можна завантажити runtime-маніфести -- Чисту резервну схему, навіть коли поточний config є невалідним +- Метадані схем live Plugin + channel за принципом best-effort, коли можна завантажити runtime-маніфести +- Чисту резервну схему навіть тоді, коли поточний config є невалідним Пов’язаний runtime RPC: -- `config.schema.lookup` повертає один нормалізований шлях config із поверхневим - вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені межі), - відповідними метаданими підказок UI та зведеннями безпосередніх дочірніх елементів. Використовуйте це для - деталізації в межах шляху в Control UI або у власних клієнтах. +- `config.schema.lookup` повертає один нормалізований шлях config з неглибоким + вузлом схеми (`title`, `description`, `type`, `enum`, `const`, поширені обмеження), + метаданими підказок UI, що збіглися, і зведеннями безпосередніх дочірніх елементів. Використовуйте це для + деталізації за шляхом у UI Control або в custom-клієнтах. ```bash openclaw config schema ``` -Спрямуйте вивід у файл, якщо хочете переглянути або перевірити його іншими інструментами: +Передайте в файл, якщо хочете переглянути або перевірити її іншими інструментами: ```bash openclaw config schema > openclaw.schema.json @@ -86,7 +86,7 @@ openclaw config schema > openclaw.schema.json ### Шляхи -Шляхи використовують крапкову або дужкову нотацію: +Шляхи використовують нотацію з крапками або дужками: ```bash openclaw config get agents.defaults.workspace @@ -102,8 +102,8 @@ openclaw config set agents.list[1].tools.exec.node "node-id-or-name" ## Значення -Значення аналізуються як JSON5, якщо це можливо; інакше вони трактуються як рядки. -Використовуйте `--strict-json`, щоб вимагати аналіз JSON5. `--json` і надалі підтримується як застарілий псевдонім. +Значення розбираються як JSON5, коли це можливо; інакше вони обробляються як рядки. +Використовуйте `--strict-json`, щоб вимагати розбір JSON5. `--json` і далі підтримується як застарілий псевдонім. ```bash openclaw config set agents.defaults.heartbeat.every "0m" @@ -116,17 +116,17 @@ openclaw config set channels.whatsapp.groups '["*"]' --strict-json Присвоєння об’єкта за замовчуванням замінює цільовий шлях. Захищені шляхи map/list, які часто містять записи, додані користувачем, наприклад `agents.defaults.models`, `models.providers`, `models.providers..models`, `plugins.entries` і -`auth.profiles`, відхиляють заміни, які видалили б наявні записи, якщо +`auth.profiles`, відмовляються від замін, які видалили б наявні записи, якщо ви не передасте `--replace`. Використовуйте `--merge`, коли додаєте записи до цих map: ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Llama 3.2"}]' --strict-json --merge ``` -Використовуйте `--replace` лише тоді, коли ви навмисно хочете, щоб надане значення +Використовуйте `--replace` лише тоді, коли ви свідомо хочете, щоб надане значення стало повним цільовим значенням. ## Режими `config set` @@ -134,7 +134,7 @@ openclaw config set models.providers.ollama.models '[{"id":"llama3.2","name":"Ll `openclaw config set` підтримує чотири стилі присвоєння: 1. Режим значення: `openclaw config set ` -2. Режим побудови SecretRef: +2. Режим конструктора SecretRef: ```bash openclaw config set channels.discord.token \ @@ -143,7 +143,7 @@ openclaw config set channels.discord.token \ --ref-id DISCORD_BOT_TOKEN ``` -3. Режим побудови provider (лише для шляху `secrets.providers.`): +3. Режим конструктора provider (лише для шляху `secrets.providers.`): ```bash openclaw config set secrets.providers.vault \ @@ -175,12 +175,12 @@ openclaw config set --batch-file ./config-set.batch.json --dry-run Примітка щодо політики: -- Присвоєння SecretRef відхиляються на непідтримуваних поверхнях runtime-змінюваності (наприклад, `hooks.token`, `commands.ownerDisplaySecret`, токени Webhook прив’язки тредів Discord і JSON-облікові дані WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). +- Присвоєння SecretRef відхиляються на непідтримуваних runtime-mutable поверхнях (наприклад, `hooks.token`, `commands.ownerDisplaySecret`, токенах Webhook прив’язки гілок Discord і JSON облікових даних WhatsApp). Див. [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface). -Пакетний аналіз завжди використовує пакетне навантаження (`--batch-json`/`--batch-file`) як джерело істини. -`--strict-json` / `--json` не змінюють поведінку пакетного аналізу. +Пакетний розбір завжди використовує пакетне корисне навантаження (`--batch-json`/`--batch-file`) як джерело істини. +`--strict-json` / `--json` не змінюють поведінку пакетного розбору. -Режим JSON path/value і надалі підтримується як для SecretRef, так і для provider: +Режим JSON path/value і далі підтримується як для SecretRef, так і для provider: ```bash openclaw config set channels.discord.token \ @@ -192,11 +192,11 @@ openclaw config set secrets.providers.vaultfile \ --strict-json ``` -## Прапорці побудови provider +## Прапорці конструктора provider -Цілі побудови provider мають використовувати `secrets.providers.` як шлях. +Цілі конструктора provider мають використовувати `secrets.providers.` як шлях. -Поширені прапорці: +Загальні прапорці: - `--provider-source ` - `--provider-timeout-ms ` (`file`, `exec`) @@ -239,9 +239,9 @@ openclaw config set secrets.providers.vault \ --provider-timeout-ms 5000 ``` -## Сухий запуск +## Пробний запуск -Використовуйте `--dry-run`, щоб перевірити зміни без запису в `openclaw.json`. +Використовуйте `--dry-run`, щоб перевірити зміни без запису до `openclaw.json`. ```bash openclaw config set channels.discord.token \ @@ -265,24 +265,24 @@ openclaw config set channels.discord.token \ --allow-exec ``` -Поведінка сухого запуску: +Поведінка пробного запуску: -- Режим побудови: виконує перевірки можливості розв’язання SecretRef для змінених refs/providers. -- Режим JSON (`--strict-json`, `--json` або пакетний режим): виконує перевірку схеми, а також перевірки можливості розв’язання SecretRef. -- Також виконується перевірка політики для відомих непідтримуваних цільових поверхонь SecretRef. -- Перевірки політики оцінюють повний config після змін, тому записи батьківського об’єкта (наприклад, встановлення `hooks` як об’єкта) не можуть обійти перевірку непідтримуваних поверхонь. -- Перевірки exec SecretRef під час сухого запуску за замовчуванням пропускаються, щоб уникнути побічних ефектів виконання команд. +- Режим конструктора: запускає перевірки можливості розв’язання SecretRef для змінених ref/provider. +- Режим JSON (`--strict-json`, `--json` або пакетний режим): запускає перевірку схеми, а також перевірки можливості розв’язання SecretRef. +- Також запускається перевірка політики для відомих непідтримуваних цільових поверхонь SecretRef. +- Перевірки політики оцінюють повний config після змін, тому записи батьківських об’єктів (наприклад, встановлення `hooks` як об’єкта) не можуть обійти перевірку непідтримуваних поверхонь. +- Перевірки exec SecretRef під час пробного запуску за замовчуванням пропускаються, щоб уникнути побічних ефектів команд. - Використовуйте `--allow-exec` разом із `--dry-run`, щоб увімкнути перевірки exec SecretRef (це може виконати команди provider). -- `--allow-exec` працює лише для сухого запуску й спричиняє помилку, якщо використовується без `--dry-run`. +- `--allow-exec` призначений лише для пробного запуску й спричиняє помилку, якщо використовується без `--dry-run`. -`--dry-run --json` виводить машиночитний звіт: +`--dry-run --json` виводить машинозчитуваний звіт: -- `ok`: чи пройшов сухий запуск -- `operations`: кількість оцінених присвоєнь -- `checks`: чи виконувалися перевірки схеми/можливості розв’язання -- `checks.resolvabilityComplete`: чи були перевірки можливості розв’язання виконані до завершення (`false`, коли exec refs пропущено) -- `refsChecked`: кількість refs, фактично розв’язаних під час сухого запуску -- `skippedExecRefs`: кількість exec refs, пропущених через те, що не було встановлено `--allow-exec` +- `ok`: чи пройшов пробний запуск +- `operations`: кількість перевірених присвоєнь +- `checks`: чи запускалися перевірки схеми/можливості розв’язання +- `checks.resolvabilityComplete`: чи були перевірки можливості розв’язання виконані до завершення (`false`, коли exec ref пропускаються) +- `refsChecked`: кількість ref, фактично розв’язаних під час пробного запуску +- `skippedExecRefs`: кількість exec ref, пропущених через те, що `--allow-exec` не було встановлено - `errors`: структуровані збої схеми/можливості розв’язання, коли `ok=false` ### Форма виводу JSON @@ -310,7 +310,7 @@ openclaw config set channels.discord.token \ } ``` -Приклад успішного виконання: +Приклад успіху: ```json { @@ -353,25 +353,25 @@ openclaw config set channels.discord.token \ } ``` -Якщо сухий запуск не вдався: +Якщо пробний запуск не вдається: -- `config schema validation failed`: форма вашого config після змін є невалідною; виправте шлях/значення або форму об’єкта provider/ref. -- `Config policy validation failed: unsupported SecretRef usage`: поверніть цей обліковий запис до plaintext/string-введення і залишайте SecretRefs лише на підтримуваних поверхнях. -- `SecretRef assignment(s) could not be resolved`: зазначений provider/ref наразі не може бути розв’язаний (відсутня env-змінна, недійсний вказівник на файл, збій exec provider або невідповідність provider/source). -- `Dry run note: skipped exec SecretRef resolvability check(s)`: сухий запуск пропустив exec refs; перезапустіть з `--allow-exec`, якщо вам потрібна перевірка можливості розв’язання exec. +- `config schema validation failed`: форма вашого config після змін невалідна; виправте шлях/значення або форму об’єкта provider/ref. +- `Config policy validation failed: unsupported SecretRef usage`: поверніть ці облікові дані до простого тексту/рядкового вводу й залишайте SecretRef лише на підтримуваних поверхнях. +- `SecretRef assignment(s) could not be resolved`: на цей момент неможливо розв’язати вказаний provider/ref (відсутня змінна env, невалідне посилання на файл, збій exec provider або невідповідність provider/source). +- `Dry run note: skipped exec SecretRef resolvability check(s)`: пробний запуск пропустив exec ref; повторіть із `--allow-exec`, якщо вам потрібна перевірка можливості розв’язання exec. - Для пакетного режиму виправте записи, що не пройшли перевірку, і повторно запустіть `--dry-run` перед записом. ## Безпека запису -`openclaw config set` та інші засоби запису config, якими керує OpenClaw, перевіряють повний -config після змін перед тим, як фіксувати його на диску. Якщо нове корисне навантаження не проходить перевірку схеми +`openclaw config set` та інші засоби запису config, що належать OpenClaw, перевіряють увесь +config після змін перед збереженням його на диск. Якщо нове корисне навантаження не проходить перевірку схеми або виглядає як руйнівне перезаписування, активний config залишається без змін, а відхилене корисне навантаження зберігається поруч із ним як `openclaw.json.rejected.*`. -Шлях до активного config має вказувати на звичайний файл. Макети `openclaw.json` -із символічними посиланнями не підтримуються для запису; натомість використовуйте `OPENCLAW_CONFIG_PATH`, щоб вказати безпосередньо -на реальний файл. +Шлях активного config має вказувати на звичайний файл. Компонування з `openclaw.json`, +що використовує symlink, не підтримується для записів; натомість використовуйте `OPENCLAW_CONFIG_PATH`, +щоб вказати безпосередньо на реальний файл. -Віддавайте перевагу записам через CLI для невеликих змін: +Надавайте перевагу запису через CLI для невеликих змін: ```bash openclaw config set gateway.reload.mode hybrid --dry-run @@ -387,20 +387,20 @@ ls -lt "$CONFIG".rejected.* 2>/dev/null | head openclaw config validate ``` -Прямі записи через редактор і надалі дозволені, але запущений Gateway вважає їх -ненадійними, доки вони не пройдуть перевірку. Невалідні прямі зміни можна відновити з +Прямий запис через редактор і далі дозволений, але запущений Gateway вважає такі зміни +ненадійними, доки вони не пройдуть перевірку. Невалідні прямі редагування можна відновити з резервної копії останнього відомого коректного стану під час запуску або гарячого перезавантаження. Див. [усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config). ## Підкоманди -- `config file`: Вивести шлях до активного файла config (визначений з `OPENCLAW_CONFIG_PATH` або зі стандартного розташування). Шлях має вказувати на звичайний файл, а не на символічне посилання. +- `config file`: Вивести шлях до активного файла config (визначеного з `OPENCLAW_CONFIG_PATH` або стандартного розташування). Шлях має вказувати на звичайний файл, а не на symlink. -Перезапустіть gateway після змін. +Перезапустіть gateway після редагувань. -## Перевірка +## Validate -Перевіряє поточний config на відповідність активній схемі без запуску +Перевірити поточний config за активною схемою без запуску gateway. ```bash @@ -408,13 +408,13 @@ openclaw config validate openclaw config validate --json ``` -Після того як `openclaw config validate` проходить успішно, ви можете використати локальний TUI, щоб -вбудований агент порівняв активний config з документацією, поки ви перевіряєте +Після того як `openclaw config validate` проходить успішно, ви можете використовувати локальний TUI, щоб +вбудований агент порівняв активний config із документацією, поки ви перевіряєте кожну зміну в тому самому терміналі: -Якщо перевірка вже не проходить, почніть з `openclaw configure` або -`openclaw doctor --fix`. `openclaw chat` не обходить захист -від невалідного config. +Якщо перевірка вже завершується помилкою, почніть з `openclaw configure` або +`openclaw doctor --fix`. `openclaw chat` не обходить +захист від невалідного config. ```bash openclaw chat @@ -431,7 +431,7 @@ openclaw chat Типовий цикл виправлення: -- Попросіть агента порівняти ваш поточний config із відповідною сторінкою документації та запропонувати найменше виправлення. +- Попросіть агента порівняти ваш поточний config з відповідною сторінкою документації та запропонувати найменше виправлення. - Застосуйте точкові зміни за допомогою `openclaw config set` або `openclaw configure`. - Повторно запускайте `openclaw config validate` після кожної зміни. -- Якщо перевірка проходить, але runtime усе ще працює некоректно, запустіть `openclaw doctor` або `openclaw doctor --fix`, щоб отримати допомогу з міграцією та виправленням. +- Якщо перевірка проходить, але runtime і далі працює нездорово, запустіть `openclaw doctor` або `openclaw doctor --fix`, щоб отримати допомогу з міграцією та виправленням. diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index b768cf02f..9cabd5254 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,63 +1,62 @@ --- read_when: - - Вам потрібен довідник з налаштування моделей для кожного провайдера окремо - - Вам потрібні приклади конфігурацій або команд онбордингу CLI для провайдерів моделей -summary: Огляд провайдерів моделей із прикладами конфігурацій + потоками CLI + - Вам потрібен довідник із налаштування моделей для кожного провайдера окремо + - Ви хочете приклади конфігурацій або команд онбордингу CLI для провайдерів моделей +summary: Огляд провайдера моделей із прикладами конфігурацій + потоками CLI title: Провайдери моделей x-i18n: - generated_at: "2026-04-23T19:23:53Z" + generated_at: "2026-04-23T20:05:12Z" model: gpt-5.4 provider: openai - source_hash: bdbb8deae102c8e55d4535ddb14b8eadb999c123cb6d188ebe563971bed762fc + source_hash: bfe692175a2f2d5fb5d79fee13ddf612c776269c7938e9a4234765ab0063940d source_path: concepts/model-providers.md workflow: 15 --- # Провайдери моделей -Ця сторінка охоплює **LLM/провайдерів моделей** (а не чат-канали на кшталт WhatsApp/Telegram). +На цій сторінці розглядаються **провайдери LLM/моделей** (а не канали чату на кшталт WhatsApp/Telegram). Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила - Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). -- `agents.defaults.models` діє як allowlist, якщо його задано. +- `agents.defaults.models` працює як список дозволених значень, якщо його задано. - Допоміжні команди CLI: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- `models.providers.*.models[].contextWindow` — це нативні метадані моделі; `contextTokens` — це фактичне обмеження під час виконання. -- Правила fallback, проби cooldown і збереження перевизначень сесії: [Відмовостійкість моделей](/uk/concepts/model-failover). -- Вбудований `codex` поєднано з harness агента Codex — використовуйте `codex/gpt-*` для входу, виявлення, нативного відновлення потоків і виконання app-server, якими керує Codex. Звичайний `openai/gpt-*` використовує провайдера OpenAI і стандартний транспорт. Вимкніть автоматичний fallback до PI для розгортань лише з Codex через `agents.defaults.embeddedHarness.fallback: "none"` — див. [Codex harness](/uk/plugins/codex-harness). +- `models.providers.*.models[].contextWindow` — це рідні метадані моделі; `contextTokens` — це фактичне обмеження під час виконання. +- Правила резервного перемикання, перевірки cooldown і збереження session-override: [Failover моделі](/uk/concepts/model-failover). +- Канонічні посилання на моделі OpenAI GPT мають формат `openai/`. Застарілі посилання `openai-codex/` і `codex/` залишаються сумісними псевдонімами для старіших конфігурацій і тестів. Для нативного виконання Codex app-server зберігайте посилання на модель як `openai/gpt-*` і примусово задавайте `agents.defaults.embeddedHarness.runtime: "codex"` — див. [Codex harness](/uk/plugins/codex-harness). -## Поведінка провайдерів, якою керують Plugin +## Поведінка провайдерів, що належить Plugin -Більшість логіки, специфічної для провайдерів, живе у Plugin провайдерів (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugin керують онбордингом, каталогами моделей, мапінгом auth env var, нормалізацією транспорту/конфігурації, очищенням схем інструментів, класифікацією failover, оновленням OAuth, звітністю про використання, профілями thinking/reasoning тощо. +Більшість специфічної для провайдера логіки живе в Plugin провайдера (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugin відповідають за онбординг, каталоги моделей, відображення auth env-var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. -Повний список хуків provider-SDK і прикладів вбудованих Plugin наведено в [Plugin провайдерів](/uk/plugins/sdk-provider-plugins). Якщо провайдеру потрібен повністю кастомний виконавець запитів, це вже окрема, глибша поверхня розширення. +Повний список хуків provider-SDK і приклади вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Провайдеру, якому потрібен повністю кастомний виконавець запитів, потрібна окрема, глибша поверхня розширення. -Під час виконання `capabilities` провайдера — це спільні метадані раннера (сімейство провайдера, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель можливостей](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). +`capabilities` середовища виконання провайдера — це спільні метадані раннера (сімейство провайдера, особливості transcript/tooling, підказки для транспорту/кешу). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). ## Ротація API-ключів -- Підтримується загальна ротація ключів провайдерів для вибраних провайдерів. +- Підтримує загальну ротацію ключів провайдера для вибраних провайдерів. - Налаштуйте кілька ключів через: - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) -- Для провайдерів Google як fallback також включається `GOOGLE_API_KEY`. +- Для провайдерів Google як резервний варіант також використовується `GOOGLE_API_KEY`. - Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. -- Запити повторюються з наступним ключем лише у відповідь на rate-limit - (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Запити повторюються з наступним ключем лише у відповідь на rate-limit помилки (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Помилки, не пов’язані з rate-limit, одразу завершуються збоєм; ротація ключів не виконується. -- Коли всі кандидатні ключі не спрацювали, повертається фінальна помилка з останньої спроби. +- Помилки, не пов’язані з rate-limit, завершуються одразу; ротація ключів не виконується. +- Коли всі можливі ключі завершуються помилкою, повертається фінальна помилка з останньої спроби. ## Вбудовані провайдери (каталог pi-ai) -OpenClaw постачається з каталогом pi-ai. Для цих провайдерів **не** -потрібна конфігурація `models.providers`; достатньо задати auth + вибрати модель. +OpenClaw постачається з каталогом pi‑ai. Для цих провайдерів **не потрібна** +конфігурація `models.providers`; достатньо налаштувати auth і вибрати модель. ### OpenAI @@ -66,18 +65,17 @@ OpenClaw постачається з каталогом pi-ai. Для цих п - Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.5`, `openai/gpt-5.5-pro` - CLI: `openclaw onboard --auth-choice openai-api-key` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, fallback на SSE) -- Перевизначення для моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Warm-up для OpenAI Responses WebSocket за замовчуванням увімкнено через `params.openaiWsWarmup` (`true`/`false`) +- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант — SSE) +- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Типово прогрівання OpenAI Responses WebSocket увімкнене через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` напряму маплять запити `openai/*` Responses на `service_tier=priority` у `api.openai.com` -- Використовуйте `params.serviceTier`, якщо вам потрібен явний tier замість спільного перемикача `/fast` +- `/fast` і `params.fastMode` напряму зіставляють запити `openai/*` Responses із `service_tier=priority` на `api.openai.com` +- Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, - `User-Agent`) застосовуються лише до нативного трафіку OpenAI до `api.openai.com`, а не - до загальних OpenAI-сумісних proxy + `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі - Нативні маршрути OpenAI також зберігають `store` для Responses, підказки prompt-cache і - формування payload для сумісності з OpenAI reasoning; proxy-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live OpenAI API його відхиляє; Spark вважається доступним лише для Codex + формування payload із сумісністю reasoning OpenAI; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live API OpenAI його відхиляє; Spark вважається доступним лише через Codex ```json5 { @@ -92,9 +90,9 @@ OpenClaw постачається з каталогом pi-ai. Для цих п - Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема для трафіку з API-ключем та OAuth-аутентифікацією, надісланого до `api.anthropic.com`; OpenClaw мапить це на Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- Setup-token Anthropic залишається доступним як підтримуваний шлях токена в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо вони доступні. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік з auth через API-ключ і OAuth, що надсилається на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволено, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, якщо це доступно. ```json5 { @@ -102,26 +100,27 @@ OpenClaw постачається з каталогом pi-ai. Для цих п } ``` -### OpenAI Code (Codex) +### OpenAI Codex OAuth - Провайдер: `openai-codex` - Auth: OAuth (ChatGPT) -- Приклад моделі: `openai-codex/gpt-5.5` +- Канонічне посилання на модель: `openai/gpt-5.5` +- Застарілі посилання на моделі: `openai-codex/gpt-*`, `codex/gpt-*` - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Транспорт за замовчуванням — `auto` (спочатку WebSocket, fallback на SSE) -- Перевизначення для моделі через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) +- Типовий транспорт — `auto` (спочатку WebSocket, запасний варіант — SSE) +- Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) - `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на - `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних proxy -- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw мапить це на `service_tier=priority` -- `openai-codex/gpt-5.3-codex-spark` залишається доступною, коли її надає каталог Codex OAuth; залежить від entitlement -- `openai-codex/gpt-5.5` зберігає нативний `contextWindow = 1000000` і стандартний runtime `contextTokens = 272000`; перевизначте runtime-обмеження через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OAuth OpenAI Codex явно підтримується для зовнішніх інструментів/процесів, таких як OpenClaw. + `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі +- Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` +- `openai/gpt-5.3-codex-spark` залишається доступним через Codex OAuth, коли каталог його показує; залежить від entitlement +- `openai/gpt-5.5` зберігає нативні `contextWindow = 1000000` і типове обмеження під час виконання `contextTokens = 272000`; перевизначайте обмеження виконання через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OpenAI Codex OAuth офіційно підтримується для зовнішніх інструментів і робочих процесів, таких як OpenClaw. ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` @@ -139,15 +138,15 @@ OpenClaw постачається з каталогом pi-ai. Для цих п ### Інші розміщені варіанти у стилі підписки -- [Qwen Cloud](/uk/providers/qwen): поверхня провайдера Qwen Cloud, а також мапінг endpoint для Alibaba DashScope і Coding Plan -- [MiniMax](/uk/providers/minimax): доступ MiniMax Coding Plan через OAuth або API key -- [GLM Models](/uk/providers/glm): endpoint Z.AI Coding Plan або загального API +- [Qwen Cloud](/uk/providers/qwen): поверхня провайдера Qwen Cloud, а також зіставлення endpoint для Alibaba DashScope і Coding Plan +- [MiniMax](/uk/providers/minimax): доступ через OAuth або API-ключ MiniMax Coding Plan +- [GLM Models](/uk/providers/glm): endpoint Z.AI Coding Plan або загальні API endpoint ### OpenCode - Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Провайдер Zen runtime: `opencode` -- Провайдер Go runtime: `opencode-go` +- Провайдер середовища виконання Zen: `opencode` +- Провайдер середовища виконання Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -157,23 +156,23 @@ OpenClaw постачається з каталогом pi-ai. Для цих п } ``` -### Google Gemini (API key) +### Google Gemini (API-ключ) - Провайдер: `google` - Auth: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, fallback `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` -- Сумісність: застарілу конфігурацію OpenClaw із `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` +- Сумісність: застаріла конфігурація OpenClaw з `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для передавання нативного - дескриптора `cachedContents/...`; збіги кешу Gemini відображаються як OpenClaw `cacheRead` + (або застаріле `cached_content`) для передавання рідного для провайдера + дескриптора `cachedContents/...`; влучання в кеш Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Провайдери: `google-vertex`, `google-gemini-cli` -- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth -- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження акаунта Google після використання сторонніх клієнтів. Перегляньте умови Google і використовуйте некритичний акаунт, якщо вирішите продовжити. +- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує свій потік OAuth +- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. - OAuth Gemini CLI постачається як частина вбудованого Plugin `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` @@ -181,10 +180,10 @@ OpenClaw постачається з каталогом pi-ai. Для цих п - Увімкнення: `openclaw plugins enable google` - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: вам **не потрібно** вставляти client id або secret у `openclaw.json`. Потік входу CLI зберігає - токени в auth profiles на хості gateway. - - Якщо після входу запити не працюють, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. - - JSON-відповіді Gemini CLI розбираються з `response`; використання береться з fallback на + - Примітка: ви **не** вставляєте client id або secret у `openclaw.json`. Потік входу CLI зберігає + токени в auth profile на хості Gateway. + - Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway. + - JSON-відповіді Gemini CLI розбираються з `response`; дані про використання беруться з резервного `stats`, а `stats.cached` нормалізується в OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -194,7 +193,7 @@ OpenClaw постачається з каталогом pi-ai. Для цих п - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню + - `zai-api-key` автоматично визначає відповідний endpoint Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово задають конкретну поверхню ### Vercel AI Gateway @@ -210,62 +209,62 @@ OpenClaw постачається з каталогом pi-ai. Для цих п - Auth: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Base URL: `https://api.kilo.ai/api/gateway/` -- Статичний fallback-каталог постачається з `kilocode/kilo/auto`; live - виявлення через `https://api.kilo.ai/api/gateway/models` може додатково розширити runtime-каталог. -- Точна маршрутизація вгору за течією для `kilocode/kilo/auto` визначається Kilo Gateway, +- Базовий URL: `https://api.kilo.ai/api/gateway/` +- Статичний резервний каталог постачається з `kilocode/kilo/auto`; live + виявлення через `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог під час виконання. +- Точна маршрутизація на upstream за `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). ### Інші вбудовані Plugin провайдерів -| Провайдер | Id | Auth env | Приклад моделі | -| ------------------------ | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | -| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| Провайдер | Id | Auth env | Приклад моделі | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | -Варто знати про такі особливості: +Варто знати такі особливості: -- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на підтверджених маршрутах `openrouter.ai`. Як OpenAI-сумісний шлях у стилі proxy, він пропускає shaping, доступний лише для нативного OpenAI (`serviceTier`, `store` для Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання з бекендом Gemini зберігають лише очищення thought-signature для proxy-Gemini. -- **Kilo Gateway** для посилань із бекендом Gemini використовує той самий шлях очищення proxy-Gemini; `kilocode/kilo/auto` та інші посилання, де proxy reasoning не підтримується, пропускають ін’єкцію proxy reasoning. -- **MiniMax** під час онбордингу через API key записує явні визначення моделі M2.7 з `input: ["text", "image"]`; вбудований каталог залишає chat-посилання лише текстовими, доки ця конфігурація не буде матеріалізована. -- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` увімкнено за замовчуванням; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний base URL — `https://api.cerebras.ai/v1`. +- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-шлях у стилі OpenAI-compatible, він пропускає формування, притаманне лише нативному OpenAI (`serviceTier`, `store` у Responses, підказки prompt-cache, сумісність reasoning OpenAI). Посилання на Gemini зберігають лише санітизацію thought-signature для проксі-Gemini. +- **Kilo Gateway** для посилань Gemini дотримується того самого шляху санітизації проксі-Gemini; `kilocode/kilo/auto` та інші посилання, де reasoning через проксі не підтримується, пропускають ін’єкцію reasoning для проксі. +- **MiniMax** онбординг через API-ключ записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки ця конфігурація не буде матеріалізована. +- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово увімкнено; вимкнення через `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базовий URL у форматі OpenAI-compatible: `https://api.cerebras.ai/v1`. -## Провайдери через `models.providers` (власний/base URL) +## Провайдери через `models.providers` (кастомний/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додати **власні** провайдери або -OpenAI/Anthropic-сумісні proxy. +Використовуйте `models.providers` (або `models.json`) для додавання **кастомних** провайдерів або +OpenAI/Anthropic-сумісних проксі. -Багато з наведених нижче вбудованих Plugin провайдерів уже публікують каталог за замовчуванням. -Явні записи `models.providers.` потрібні лише тоді, коли ви хочете перевизначити -стандартний base URL, заголовки або список моделей. +Багато з наведених нижче вбудованих Plugin провайдерів уже публікують типовий каталог. +Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin провайдера. За -замовчуванням використовуйте вбудованого провайдера, а явний запис `models.providers.moonshot` додавайте лише тоді, коли +Moonshot постачається як вбудований Plugin провайдера. Використовуйте вбудований провайдер +типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли потрібно перевизначити base URL або метадані моделі: - Провайдер: `moonshot` @@ -327,7 +326,7 @@ Kimi Coding використовує Anthropic-сумісний endpoint Moonsho Volcano Engine (火山引擎) надає доступ до Doubao та інших моделей у Китаї. -- Провайдер: `volcengine` (coding: `volcengine-plan`) +- Провайдер: `volcengine` (для coding: `volcengine-plan`) - Auth: `VOLCANO_ENGINE_API_KEY` - Приклад моделі: `volcengine-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice volcengine-api-key` @@ -340,13 +339,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу за замовчуванням використовується поверхня coding, але загальний каталог `volcengine/*` +Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*` реєструється одночасно. -У пікерах моделей для онбордингу/налаштування вибір auth Volcengine надає перевагу як рядкам -`volcengine/*`, так і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, +У селекторах моделей під час онбордингу/налаштування вибір auth для Volcengine надає перевагу рядкам +`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -пікера, обмеженого провайдером. +селектора в межах провайдера. Доступні моделі: @@ -368,7 +367,7 @@ OpenClaw повертається до нефільтрованого катал BytePlus ARK надає міжнародним користувачам доступ до тих самих моделей, що й Volcano Engine. -- Провайдер: `byteplus` (coding: `byteplus-plan`) +- Провайдер: `byteplus` (для coding: `byteplus-plan`) - Auth: `BYTEPLUS_API_KEY` - Приклад моделі: `byteplus-plan/ark-code-latest` - CLI: `openclaw onboard --auth-choice byteplus-api-key` @@ -381,13 +380,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Під час онбордингу за замовчуванням використовується поверхня coding, але загальний каталог `byteplus/*` +Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*` реєструється одночасно. -У пікерах моделей для онбордингу/налаштування вибір auth BytePlus надає перевагу як рядкам -`byteplus/*`, так і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, +У селекторах моделей під час онбордингу/налаштування вибір auth для BytePlus надає перевагу обом +рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -пікера, обмеженого провайдером. +селектора в межах провайдера. Доступні моделі: @@ -405,7 +404,7 @@ OpenClaw повертається до нефільтрованого катал ### Synthetic -Synthetic надає Anthropic-сумісні моделі через провайдера `synthetic`: +Synthetic надає Anthropic-сумісні моделі через провайдер `synthetic`: - Провайдер: `synthetic` - Auth: `SYNTHETIC_API_KEY` @@ -433,26 +432,26 @@ Synthetic надає Anthropic-сумісні моделі через прова ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint: +MiniMax налаштовується через `models.providers`, оскільки використовує кастомні endpoint: -- MiniMax OAuth (глобальний): `--auth-choice minimax-global-oauth` +- MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- API key MiniMax (глобальний): `--auth-choice minimax-global-api` -- API key MiniMax (CN): `--auth-choice minimax-cn-api` +- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` +- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` - Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-сумісному streaming-шляху MiniMax OpenClaw за замовчуванням вимикає thinking, -якщо ви явно його не задасте, а `/fast on` переписує +У Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, +якщо ви явно його не задаєте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розподіл можливостей, яким керує Plugin: +Розподіл capability, що належить Plugin: -- Значення за замовчуванням для тексту/чату залишаються на `minimax/MiniMax-M2.7` +- Типові значення для тексту/чату залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це `MiniMax-VL-01`, яким на обох auth-шляхах MiniMax керує Plugin +- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, на обох шляхах auth MiniMax - Вебпошук залишається на id провайдера `minimax` ### LM Studio @@ -461,9 +460,9 @@ LM Studio постачається як вбудований Plugin провай - Провайдер: `lmstudio` - Auth: `LM_API_TOKEN` -- Base URL інференсу за замовчуванням: `http://localhost:1234/v1` +- Типовий base URL для інференсу: `http://localhost:1234/v1` -Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): +Далі задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): ```json5 { @@ -474,8 +473,8 @@ LM Studio постачається як вбудований Plugin провай ``` OpenClaw використовує нативні `LM Studio` `/api/v1/models` і `/api/v1/models/load` -для виявлення + автозавантаження, а `/v1/chat/completions` — для інференсу за замовчуванням. -Налаштування та усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio). +для виявлення + автозавантаження, а `/v1/chat/completions` — типово для інференсу. +Налаштування та усунення неполадок див. у [/providers/lmstudio](/uk/providers/lmstudio). ### Ollama @@ -499,21 +498,20 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, якщо ви ввімкнете це через -`OLLAMA_API_KEY`, а вбудований Plugin провайдера додає Ollama безпосередньо до -`openclaw onboard` і пікера моделей. Див. [/providers/ollama](/uk/providers/ollama) -для відомостей про онбординг, хмарний/локальний режим і власну конфігурацію. +Ollama локально виявляється за адресою `http://127.0.0.1:11434`, якщо ви явно ввімкнете це через +`OLLAMA_API_KEY`, а вбудований Plugin провайдера напряму додає Ollama до +`openclaw onboard` і селектора моделей. Докладніше про онбординг, хмарний/локальний режим і кастомну конфігурацію див. у [/providers/ollama](/uk/providers/ollama). ### vLLM -vLLM постачається як вбудований Plugin провайдера для локальних/self-hosted -OpenAI-сумісних серверів: +vLLM постачається як вбудований Plugin провайдера для локальних/self-hosted OpenAI-compatible +серверів: - Провайдер: `vllm` - Auth: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:8000/v1` +- Типовий base URL: `http://127.0.0.1:8000/v1` -Щоб увімкнути локальне автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): +Щоб явно ввімкнути локальне автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export VLLM_API_KEY="vllm-local" @@ -529,18 +527,18 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі див. у [/providers/vllm](/uk/providers/vllm). +Докладніше див. у [/providers/vllm](/uk/providers/vllm). ### SGLang SGLang постачається як вбудований Plugin провайдера для швидких self-hosted -OpenAI-сумісних серверів: +OpenAI-compatible серверів: - Провайдер: `sglang` - Auth: необов’язкова (залежить від вашого сервера) -- Base URL за замовчуванням: `http://127.0.0.1:30000/v1` +- Типовий base URL: `http://127.0.0.1:30000/v1` -Щоб увімкнути локальне автовиявлення (підійде будь-яке значення, якщо ваш сервер не +Щоб явно ввімкнути локальне автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash @@ -557,11 +555,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі див. у [/providers/sglang](/uk/providers/sglang). +Докладніше див. у [/providers/sglang](/uk/providers/sglang). -### Локальні proxy (LM Studio, vLLM, LiteLLM тощо) +### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI-сумісний): +Приклад (OpenAI-compatible): ```json5 { @@ -596,21 +594,21 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для власних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх не задано, OpenClaw використовує такі значення за замовчуванням: +- Для кастомних провайдерів `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. + Якщо їх не задано, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендація: задавайте явні значення, які відповідають обмеженням вашого proxy/моделі. -- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від провайдера через непідтримувані ролі `developer`. -- OpenAI-сумісні маршрути у стилі proxy також пропускають shaping запитів, доступний лише для нативного OpenAI: - без `service_tier`, без `store` для Responses, без підказок prompt-cache, без - формування payload для сумісності з OpenAI reasoning і без прихованих +- Рекомендовано: задавати явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово задає `compat.supportsDeveloperRole: false`, щоб уникати помилок 400 від провайдера для непідтримуваних ролей `developer`. +- Проксі-маршрути у стилі OpenAI-compatible також пропускають формування запитів, притаманне лише нативному OpenAI: + без `service_tier`, без `store` у Responses, без підказок prompt-cache, без + формування payload із сумісністю reasoning OpenAI та без прихованих заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній або не заданий, OpenClaw зберігає стандартну поведінку OpenAI (яка резолвиться до `api.openai.com`). -- Для безпеки навіть явне `compat.supportsDeveloperRole: true` усе одно перевизначається на ненативних endpoint `openai-completions`. +- Якщо `baseUrl` порожній або не заданий, OpenClaw зберігає типову поведінку OpenAI (яка вказує на `api.openai.com`). +- Для безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`. ## Приклади CLI @@ -625,6 +623,6 @@ openclaw models list ## Пов’язане - [Моделі](/uk/concepts/models) — конфігурація моделей і псевдоніми -- [Відмовостійкість моделей](/uk/concepts/model-failover) — ланцюжки fallback і поведінка повторних спроб -- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей -- [Провайдери](/uk/providers) — посібники з налаштування для кожного провайдера +- [Failover моделі](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб +- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей +- [Провайдери](/uk/providers) — окремі посібники з налаштування провайдерів diff --git a/docs/uk/concepts/models.md b/docs/uk/concepts/models.md index 3dbb621f0..71ff23d02 100644 --- a/docs/uk/concepts/models.md +++ b/docs/uk/concepts/models.md @@ -1,48 +1,47 @@ --- read_when: - - Додавання або змінення CLI моделей (`models list/set/scan/aliases/fallbacks`) + - Додавання або змінення CLI моделей (models list/set/scan/aliases/fallbacks) - Зміна поведінки резервних варіантів моделей або UX вибору - Оновлення перевірок сканування моделей (інструменти/зображення) -summary: 'CLI моделей: список, встановлення, псевдоніми, резервні варіанти, сканування, стан' +summary: 'Моделі CLI: список, встановлення, псевдоніми, резервні варіанти, сканування, статус' title: CLI моделей x-i18n: - generated_at: "2026-04-23T19:23:57Z" + generated_at: "2026-04-23T20:05:14Z" model: gpt-5.4 provider: openai - source_hash: 45ee320df8d49171261cd0a5d42e1c0c39d7ea77d16fd7895ef15b1195d81fb4 + source_hash: eb59d09c6955b95e4cb0dd58e0a2d9b1be19fcb32dbf2040fbc893c32ae1c870 source_path: concepts/models.md workflow: 15 --- # CLI моделей -Див. [/concepts/model-failover](/uk/concepts/model-failover) щодо ротації профілів авторизації, -cooldown-ів і того, як це взаємодіє з резервними варіантами. -Короткий огляд провайдерів + приклади: [/concepts/model-providers](/uk/concepts/model-providers). +Див. [/concepts/model-failover](/uk/concepts/model-failover) щодо ротації профілів автентифікації, періодів очікування та того, як це взаємодіє з резервними варіантами. +Короткий огляд постачальників + приклади: [/concepts/model-providers](/uk/concepts/model-providers). ## Як працює вибір моделі OpenClaw вибирає моделі в такому порядку: 1. **Основна** модель (`agents.defaults.model.primary` або `agents.defaults.model`). -2. **Резервні варіанти** у `agents.defaults.model.fallbacks` (за порядком). -3. **Резервне перемикання авторизації провайдера** відбувається всередині провайдера перед переходом до наступної моделі. +2. **Резервні варіанти** в `agents.defaults.model.fallbacks` (за порядком). +3. **Резервне перемикання автентифікації постачальника** відбувається всередині постачальника перед переходом до наступної моделі. -Пов’язане: +Пов’язано: -- `agents.defaults.models` — це allowlist/каталог моделей, які OpenClaw може використовувати (разом із псевдонімами). +- `agents.defaults.models` — це allowlist/каталог моделей, які може використовувати OpenClaw (разом із псевдонімами). - `agents.defaults.imageModel` використовується **лише тоді**, коли основна модель не може приймати зображення. -- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо його не вказано, інструмент повертається до `agents.defaults.imageModel`, а потім до визначеної для сесії/типової моделі. -- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо його не вказано, `image_generate` усе одно може визначити типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку provider-id. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте авторизацію/API key цього провайдера. -- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо його не вказано, `music_generate` усе одно може визначити типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики у порядку provider-id. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте авторизацію/API key цього провайдера. -- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо його не вказано, `video_generate` усе одно може визначити типове значення провайдера з авторизацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео у порядку provider-id. Якщо ви задаєте конкретний провайдер/модель, також налаштуйте авторизацію/API key цього провайдера. +- `agents.defaults.pdfModel` використовується інструментом `pdf`. Якщо не вказано, інструмент повертається до `agents.defaults.imageModel`, а потім до визначеної моделі сеансу/моделі за замовчуванням. +- `agents.defaults.imageGenerationModel` використовується спільною можливістю генерації зображень. Якщо не вказано, `image_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації зображень у порядку ідентифікаторів постачальників. Якщо ви вказуєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. +- `agents.defaults.musicGenerationModel` використовується спільною можливістю генерації музики. Якщо не вказано, `music_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації музики в порядку ідентифікаторів постачальників. Якщо ви вказуєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. +- `agents.defaults.videoGenerationModel` використовується спільною можливістю генерації відео. Якщо не вказано, `video_generate` усе одно може визначити типове значення постачальника з автентифікацією. Спочатку він пробує поточного постачальника за замовчуванням, потім решту зареєстрованих постачальників генерації відео в порядку ідентифікаторів постачальників. Якщо ви вказуєте конкретного постачальника/модель, також налаштуйте автентифікацію/API key цього постачальника. - Типові значення для окремих агентів можуть перевизначати `agents.defaults.model` через `agents.list[].model` разом із прив’язками (див. [/concepts/multi-agent](/uk/concepts/multi-agent)). -## Швидка політика моделей +## Швидка політика для моделей -- Встановіть як основну найсильнішу модель останнього покоління, яка вам доступна. -- Використовуйте резервні варіанти для чутливих до вартості/затримки завдань і чатів із нижчими вимогами. -- Для агентів з увімкненими інструментами або недовірених входів уникайте старіших/слабших рівнів моделей. +- Встановіть основною найсильнішу модель останнього покоління, яка вам доступна. +- Використовуйте резервні варіанти для завдань, чутливих до вартості/затримки, і для менш важливого чату. +- Для агентів з увімкненими інструментами або ненадійними вхідними даними уникайте старіших/слабших рівнів моделей. ## Онбординг (рекомендовано) @@ -52,8 +51,7 @@ OpenClaw вибирає моделі в такому порядку: openclaw onboard ``` -Він може налаштувати модель + авторизацію для поширених провайдерів, зокрема **OpenAI Code (Codex) -subscription** (OAuth) і **Anthropic** (API key або Claude CLI). +Він може налаштувати модель + автентифікацію для поширених постачальників, зокрема **OpenAI Code (Codex) subscription** (OAuth) та **Anthropic** (API key або Claude CLI). ## Ключі конфігурації (огляд) @@ -62,45 +60,35 @@ subscription** (OAuth) і **Anthropic** (API key або Claude CLI). - `agents.defaults.pdfModel.primary` і `agents.defaults.pdfModel.fallbacks` - `agents.defaults.imageGenerationModel.primary` і `agents.defaults.imageGenerationModel.fallbacks` - `agents.defaults.videoGenerationModel.primary` і `agents.defaults.videoGenerationModel.fallbacks` -- `agents.defaults.models` (allowlist + псевдоніми + параметри провайдера) -- `models.providers` (користувацькі провайдери, записані в `models.json`) +- `agents.defaults.models` (allowlist + псевдоніми + параметри постачальника) +- `models.providers` (власні постачальники, записані до `models.json`) -Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми провайдерів, як-от `z.ai/*`, нормалізуються -до `zai/*`. +Посилання на моделі нормалізуються до нижнього регістру. Псевдоніми постачальників, наприклад `z.ai/*`, нормалізуються до `zai/*`. -Приклади конфігурації провайдерів (зокрема OpenCode) наведено в +Приклади конфігурації постачальників (зокрема OpenCode) наведені в [/providers/opencode](/uk/providers/opencode). ### Безпечне редагування allowlist -Під час ручного оновлення `agents.defaults.models` використовуйте адитивні записи: +Під час ручного оновлення `agents.defaults.models` використовуйте адитивний запис: ```bash -openclaw config set agents.defaults.models '{"openai-codex/gpt-5.5":{}}' --strict-json --merge +openclaw config set agents.defaults.models '{"openai/gpt-5.5":{}}' --strict-json --merge ``` -`openclaw config set` захищає мапи моделей/провайдерів від випадкового перезапису. Звичайне -присвоєння об’єкта до `agents.defaults.models`, `models.providers` або -`models.providers..models` відхиляється, якщо воно призведе до видалення наявних -записів. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли -надане значення має стати повним цільовим значенням. +`openclaw config set` захищає мапи моделей/постачальників від випадкового перезапису. Звичайне присвоєння об’єкта для `agents.defaults.models`, `models.providers` або `models.providers..models` відхиляється, якщо воно видалить наявні записи. Використовуйте `--merge` для адитивних змін; використовуйте `--replace` лише тоді, коли передане значення має стати повним цільовим значенням. -Інтерактивне налаштування провайдера і `openclaw configure --section model` також зливають -вибрані для провайдера значення до наявного allowlist, тож додавання Codex, -Ollama або іншого провайдера не видаляє не пов’язані записи моделей. +Інтерактивне налаштування постачальника та `openclaw configure --section model` також об’єднують вибори в межах постачальника з наявним allowlist, тому додавання Codex, Ollama або іншого постачальника не видаляє не пов’язані записи моделей. -## «Model is not allowed» (і чому відповіді припиняються) +## "Model is not allowed" (і чому відповіді зупиняються) -Якщо задано `agents.defaults.models`, він стає **allowlist** для `/model` і для -перевизначень сесії. Коли користувач вибирає модель, якої немає в цьому allowlist, -OpenClaw повертає: +Якщо встановлено `agents.defaults.models`, він стає **allowlist** для `/model` і для перевизначень сеансу. Коли користувач вибирає модель, якої немає в цьому allowlist, OpenClaw повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` -Це відбувається **до** формування звичайної відповіді, тому може здаватися, що повідомлення -«не отримало відповіді». Виправлення полягає в одному з таких варіантів: +Це відбувається **до** створення звичайної відповіді, тому може здаватися, що повідомлення «не отримало відповіді». Виправити це можна так: - Додати модель до `agents.defaults.models`, або - Очистити allowlist (видалити `agents.defaults.models`), або @@ -122,7 +110,7 @@ Model "provider/model" is not allowed. Use /model to list available models. ## Перемикання моделей у чаті (`/model`) -Ви можете перемикати моделі для поточної сесії без перезапуску: +Ви можете перемикати моделі для поточного сеансу без перезапуску: ``` /model @@ -134,28 +122,26 @@ Model "provider/model" is not allowed. Use /model to list available models. Примітки: -- `/model` (і `/model list`) — це компактний нумерований вибір (сімейство моделей + доступні провайдери). -- У Discord `/model` і `/models` відкривають інтерактивний вибір із випадними списками провайдера та моделі плюс кроком Submit. -- `/models add` доступна типово й може бути вимкнена через `commands.modelsWrite=false`. -- Коли увімкнено, `/models add ` — це найшвидший шлях; проста команда `/models add` запускає керований покроковий процес спочатку з вибором провайдера, де це підтримується. +- `/model` (і `/model list`) — це компактний нумерований вибірник (сімейство моделей + доступні постачальники). +- У Discord `/model` і `/models` відкривають інтерактивний вибірник зі списками постачальників і моделей та кроком Submit. +- `/models add` доступна за замовчуванням і може бути вимкнена через `commands.modelsWrite=false`. +- Якщо увімкнено, `/models add ` є найшвидшим шляхом; простий `/models add` запускає керований процес із вибором постачальника спочатку, де це підтримується. - Після `/models add` нова модель стає доступною в `/models` і `/model` без перезапуску Gateway. -- `/model <#>` вибирає зі списку цього засобу вибору. -- `/model` негайно зберігає новий вибір сесії. +- `/model <#>` вибирає зі списку цього вибірника. +- `/model` негайно зберігає новий вибір сеансу. - Якщо агент неактивний, наступний запуск одразу використовує нову модель. -- Якщо запуск уже активний, OpenClaw позначає живе перемикання як відкладене й перезапускає на новій моделі лише в чистій точці повторної спроби. -- Якщо активність інструментів або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до наступної можливості повторної спроби або до наступного ходу користувача. -- `/model status` — це докладне подання (кандидати авторизації і, коли налаштовано, `baseUrl` кінцевої точки провайдера + режим `api`). +- Якщо виконання вже активне, OpenClaw позначає живе перемикання як відкладене й перезапускає на нову модель лише в чистій точці повторної спроби. +- Якщо активність інструментів або виведення відповіді вже почалися, відкладене перемикання може залишатися в черзі до пізнішої можливості повторної спроби або до наступного ходу користувача. +- `/model status` — це детальне подання (кандидати автентифікації та, якщо налаштовано, `baseUrl` кінцевої точки постачальника + режим `api`). - Посилання на моделі розбираються розділенням за **першим** `/`. Під час введення `/model ` використовуйте `provider/model`. -- Якщо сам ID моделі містить `/` (у стилі OpenRouter), ви повинні включити префікс провайдера (приклад: `/model openrouter/moonshotai/kimi-k2`). -- Якщо ви пропускаєте провайдера, OpenClaw визначає введення в такому порядку: +- Якщо сам ідентифікатор моделі містить `/` (у стилі OpenRouter), ви маєте вказати префікс постачальника (приклад: `/model openrouter/moonshotai/kimi-k2`). +- Якщо ви пропускаєте постачальника, OpenClaw визначає введення в такому порядку: 1. збіг псевдоніма - 2. унікальний збіг налаштованого провайдера для цього точного model id без префікса - 3. застаріле резервне повернення до налаштованого типового провайдера - Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw - натомість повертається до першого налаштованого провайдера/моделі, щоб уникнути - показу застарілого типового значення видаленого провайдера. + 2. унікальний збіг налаштованого постачальника для цього точного ідентифікатора моделі без префікса + 3. застарілий резервний перехід до налаштованого постачальника за замовчуванням + Якщо цей постачальник більше не надає налаштовану модель за замовчуванням, OpenClaw натомість переходить до першого налаштованого постачальника/моделі, щоб не показувати застаріле типове значення видаленого постачальника. -Повна поведінка/конфігурація команд: [Слеш-команди](/uk/tools/slash-commands). +Повна поведінка/конфігурація команди: [Слеш-команди](/uk/tools/slash-commands). Приклади: @@ -195,36 +181,23 @@ openclaw models image-fallbacks clear Типово показує налаштовані моделі. Корисні прапорці: - `--all`: повний каталог -- `--local`: лише локальні провайдери -- `--provider `: фільтр за id провайдера, наприклад `moonshot`; мітки - відображення з інтерактивних засобів вибору не приймаються -- `--plain`: одна модель на рядок -- `--json`: машиночитаний вивід +- `--local`: лише локальні постачальники +- `--provider `: фільтр за ідентифікатором постачальника, наприклад `moonshot`; мітки відображення з інтерактивних вибірників не приймаються +- `--plain`: по одній моделі в рядку +- `--json`: машинозчитуваний вивід -`--all` включає рядки статичного каталогу вбудованих провайдерів ще до -налаштування авторизації, тож представлення лише для виявлення може показувати моделі, які недоступні, доки -ви не додасте відповідні облікові дані провайдера. +`--all` включає рядки статичного каталогу вбудованих постачальників ще до налаштування автентифікації, тому подання лише для виявлення може показувати моделі, недоступні, доки ви не додасте відповідні облікові дані постачальника. ### `models status` -Показує визначену основну модель, резервні варіанти, модель зображень і огляд -авторизації налаштованих провайдерів. Також відображає статус завершення дії OAuth для профілів, знайдених -у сховищі авторизації (типово попереджає за 24 години). `--plain` виводить лише визначену -основну модель. -Статус OAuth показується завжди (і включається до виводу `--json`). Якщо налаштований -провайдер не має облікових даних, `models status` виводить розділ **Missing auth**. -JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers` -(ефективна авторизація для кожного провайдера, включно з обліковими даними з env). `auth.oauth` -стосується лише стану профілів у сховищі авторизації; провайдери лише з env там не з’являються. -Використовуйте `--check` для автоматизації (код виходу `1` для відсутньої/простроченої авторизації, `2` для тієї, що скоро спливає). -Використовуйте `--probe` для живих перевірок авторизації; рядки перевірки можуть надходити з профілів авторизації, облікових даних env -або `models.json`. -Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє -`excluded_by_auth_order` замість спроби його використати. Якщо авторизація існує, але не вдається визначити модель, придатну для probe, для цього провайдера, перевірка повідомляє `status: no_model`. +Показує визначену основну модель, резервні варіанти, модель зображень і огляд автентифікації налаштованих постачальників. Також показує статус завершення дії OAuth для профілів, знайдених у сховищі автентифікації (типово попереджає в межах 24 годин). `--plain` виводить лише визначену основну модель. +Статус OAuth показується завжди (і включається до виводу `--json`). Якщо налаштований постачальник не має облікових даних, `models status` виводить розділ **Missing auth**. +JSON включає `auth.oauth` (вікно попередження + профілі) і `auth.providers` (ефективна автентифікація для кожного постачальника, включно з обліковими даними з env). `auth.oauth` — це лише стан профілів у сховищі автентифікації; постачальники лише з env там не відображаються. +Використовуйте `--check` для автоматизації (код виходу `1` для відсутньої/простроченої автентифікації, `2` — коли строк скоро спливає). +Використовуйте `--probe` для живих перевірок автентифікації; рядки перевірки можуть походити з профілів автентифікації, облікових даних env або `models.json`. +Якщо явний `auth.order.` пропускає збережений профіль, перевірка повідомляє `excluded_by_auth_order` замість спроби його використання. Якщо автентифікація існує, але для цього постачальника не вдається визначити модель, яку можна перевірити, перевірка повідомляє `status: no_model`. -Вибір авторизації залежить від провайдера/акаунта. Для постійно ввімкнених хостів Gateway -API key зазвичай є найпередбачуванішим варіантом; повторне використання Claude CLI та наявні профілі Anthropic -OAuth/token також підтримуються. +Вибір автентифікації залежить від постачальника/акаунта. Для постійно ввімкнених хостів Gateway API key зазвичай є найпередбачуванішим варіантом; також підтримуються повторне використання Claude CLI і наявні профілі Anthropic OAuth/токенів. Приклад (Claude CLI): @@ -235,20 +208,19 @@ openclaw models status ## Сканування (безкоштовні моделі OpenRouter) -`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і може -за бажанням виконувати probe моделей на підтримку інструментів і зображень. +`openclaw models scan` перевіряє **каталог безкоштовних моделей** OpenRouter і за потреби може перевіряти моделі на підтримку інструментів і зображень. Основні прапорці: - `--no-probe`: пропустити живі перевірки (лише метадані) -- `--min-params `: мінімальний розмір параметрів (у мільярдах) +- `--min-params `: мінімальний розмір параметрів (мільярди) - `--max-age-days `: пропускати старіші моделі -- `--provider `: фільтр за префіксом провайдера +- `--provider `: фільтр префікса постачальника - `--max-candidates `: розмір списку резервних варіантів -- `--set-default`: установити `agents.defaults.model.primary` на перший вибір -- `--set-image`: установити `agents.defaults.imageModel.primary` на перший вибір зображень +- `--set-default`: встановити `agents.defaults.model.primary` на перший вибір +- `--set-image`: встановити `agents.defaults.imageModel.primary` на перший вибір зображень -Для перевірок потрібен API key OpenRouter (із профілів авторизації або +Перевірки вимагають API key OpenRouter (із профілів автентифікації або `OPENROUTER_API_KEY`). Без ключа використовуйте `--no-probe`, щоб лише перелічити кандидатів. Результати сканування ранжуються за: @@ -258,39 +230,36 @@ openclaw models status 3. Розміром контексту 4. Кількістю параметрів -Вхід +Вхідні дані - Список OpenRouter `/models` (фільтр `:free`) -- Потрібен API key OpenRouter із профілів авторизації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment)) +- Потрібен API key OpenRouter із профілів автентифікації або `OPENROUTER_API_KEY` (див. [/environment](/uk/help/environment)) - Необов’язкові фільтри: `--max-age-days`, `--min-params`, `--provider`, `--max-candidates` - Керування перевірками: `--timeout`, `--concurrency` -Під час запуску в TTY ви можете інтерактивно вибрати резервні варіанти. У неінтерактивному -режимі передайте `--yes`, щоб прийняти типові значення. +Під час запуску в TTY ви можете інтерактивно вибирати резервні варіанти. У неінтерактивному режимі передайте `--yes`, щоб прийняти типові значення. ## Реєстр моделей (`models.json`) -Користувацькі провайдери в `models.providers` записуються в `models.json` у -каталозі агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл -типово зливається, якщо лише `models.mode` не встановлено в `replace`. +Власні постачальники в `models.providers` записуються до `models.json` у каталозі агента (типово `~/.openclaw/agents//agent/models.json`). Цей файл типово об’єднується, якщо `models.mode` не встановлено в `replace`. -Пріоритет режиму злиття для провайдерів із однаковими ID: +Пріоритет у режимі merge для збіжних ідентифікаторів постачальників: - Непорожній `baseUrl`, уже наявний в агентському `models.json`, має пріоритет. -- Непорожній `apiKey` в агентському `models.json` має пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. -- Значення `apiKey` для провайдерів, керованих через SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження розв’язаних секретів. -- Значення заголовків провайдера, керованих через SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). -- Порожні або відсутні агентські `apiKey`/`baseUrl` повертаються до config `models.providers`. -- Інші поля провайдера оновлюються з config і нормалізованих даних каталогу. +- Непорожній `apiKey` в агентському `models.json` має пріоритет лише тоді, коли цей постачальник не керується через SecretRef у поточному контексті конфігурації/профілю автентифікації. +- Значення `apiKey` для постачальників, керованих SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec) замість збереження розв’язаних секретів. +- Значення заголовків постачальника, керованих SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для посилань env, `secretref-managed` для посилань file/exec). +- Порожній або відсутній агентський `apiKey`/`baseUrl` повертається до конфігурації `models.providers`. +- Інші поля постачальника оновлюються з конфігурації та нормалізованих даних каталогу. -Збереження маркерів є авторитетним на рівні джерела: OpenClaw записує маркери з активного знімка config джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання. +Збереження маркерів є авторитетним щодо джерела: OpenClaw записує маркери з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів під час виконання. Це застосовується щоразу, коли OpenClaw повторно генерує `models.json`, зокрема в шляхах, керованих командами, як-от `openclaw agent`. -## Пов’язане +## Пов’язано -- [Провайдери моделей](/uk/concepts/model-providers) — маршрутизація провайдерів і авторизація -- [Перемикання моделей при збої](/uk/concepts/model-failover) — ланцюжки резервних варіантів -- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделей зображень -- [Генерація музики](/uk/tools/music-generation) — конфігурація моделей музики -- [Генерація відео](/uk/tools/video-generation) — конфігурація моделей відео +- [Постачальники моделей](/uk/concepts/model-providers) — маршрутизація постачальників і автентифікація +- [Резервне перемикання моделей](/uk/concepts/model-failover) — ланцюжки резервних варіантів +- [Генерація зображень](/uk/tools/image-generation) — конфігурація моделі зображень +- [Генерація музики](/uk/tools/music-generation) — конфігурація моделі музики +- [Генерація відео](/uk/tools/video-generation) — конфігурація моделі відео - [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — ключі конфігурації моделей diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index fa3518260..7f192f21a 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,70 +1,70 @@ --- read_when: - - Вам потрібні точні семантики полів config або значення за замовчуванням. - - Ви перевіряєте блоки config channel, model, gateway або tool. -summary: Довідка з config Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідки підсистем -title: Довідка з config + - Вам потрібні точні семантики полів конфігурації або значення за замовчуванням + - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента +summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем +title: Довідник конфігурації x-i18n: - generated_at: "2026-04-23T19:24:46Z" + generated_at: "2026-04-23T20:05:12Z" model: gpt-5.4 provider: openai - source_hash: 2ed93c1439fd26f548a48b2813922bdd7b2344551376eefd7cdde616327b7ca8 + source_hash: 2190dbcd3a72ce62ed862ed3145c60c92fdbbd290ba73c9b7fad7a382a9aa00e source_path: gateway/configuration-reference.md workflow: 15 --- -# Довідка з config +# Довідник конфігурації -Основна довідка з config для `~/.openclaw/openclaw.json`. Огляд, орієнтований на завдання, див. у [Configuration](/uk/gateway/configuration). +Довідник основної конфігурації для `~/.openclaw/openclaw.json`. Щоб переглянути огляд, орієнтований на завдання, див. [Конфігурація](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні config OpenClaw і дає посилання назовні, коли підсистема має власну глибшу довідку. Вона **не** намагається вбудувати на одну сторінку кожен каталог команд, що належить channel/Plugin, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і надає посилання назовні, коли підсистема має власний, глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. Джерело істини в коді: -- `openclaw config schema` виводить живу JSON Schema, яка використовується для перевірки й Control UI, із доданими метаданими bundled/Plugin/channel, якщо вони доступні -- `config.schema.lookup` повертає один вузол схеми в межах шляху для інструментів деталізації -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового рівня документації config щодо поточної поверхні схеми +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та UI керування, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізації +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють хеш базового стану документації конфігурації відносно поточної поверхні схеми -Окремі поглиблені довідки: +Окремі поглиблені довідники: -- [Довідка з config пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і config Dreaming у `plugins.entries.memory-core.config.dreaming` -- [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки відповідних channel/Plugin для поверхонь команд, специфічних для channel +- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` +- [Слеш-команди](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд +- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналу -Формат config — **JSON5** (дозволені коментарі й кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. +Формат конфігурації — **JSON5** (дозволені коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх пропущено. --- -## Channels +## Канали -Кожен channel запускається автоматично, коли існує його розділ config (якщо тільки не встановлено `enabled: false`). +Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не вказано `enabled: false`). ### Доступ до DM і груп -Усі channels підтримують політики DM і групові політики: +Усі канали підтримують політики DM і політики груп: | Політика DM | Поведінка | | ------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має схвалити | -| `allowlist` | Лише відправники з `allowFrom` (або зі сховища paired allow) | -| `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має схвалити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів сполучення) | +| `open` | Дозволити всі вхідні DM (потребує `allowFrom: ["*"]`) | | `disabled` | Ігнорувати всі вхідні DM | -| Групова політика | Поведінка | +| Політика груп | Поведінка | | --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist | -| `open` | Обійти group allowlists (обмеження за згадуванням усе ще діє) | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволених | +| `open` | Обійти списки дозволених для груп (обмеження за згадками все одно застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. -Коди pairing спливають через 1 годину. Кількість очікувальних запитів pairing для DM обмежена **3 на channel**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), групова політика runtime повертається до `allowlist` (fail-closed) із попередженням під час запуску. +`channels.defaults.groupPolicy` задає типове значення, коли `groupPolicy` постачальника не задано. +Коди сполучення спливають через 1 годину. Кількість очікувальних запитів на сполучення DM обмежена до **3 на канал**. +Якщо блок постачальника повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (відмова за замовчуванням) із попередженням під час запуску. -### Перевизначення моделей channel +### Перевизначення моделі каналу -Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID channel за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення channel застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб прив’язати конкретні ідентифікатори каналів до моделі. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, заданого через `/model`). ```json5 { @@ -85,9 +85,9 @@ x-i18n: } ``` -### Значення channel за замовчуванням і Heartbeat +### Типові значення каналів і Heartbeat -Використовуйте `channels.defaults` для спільної поведінки group-policy і Heartbeat у різних provider: +Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat у різних постачальників: ```json5 { @@ -105,15 +105,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: резервна групова політика, коли `groupPolicy` на рівні provider не встановлено. -- `channels.defaults.contextVisibility`: режим видимості додаткового контексту за замовчуванням для всіх channels. Значення: `all` (типово, включати весь контекст із цитат/тредів/історії), `allowlist` (включати контекст лише від відправників із allowlist), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого channel: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати здорові стани channel у вивід Heartbeat. -- `channels.defaults.heartbeat.showAlerts`: включати деградовані/помилкові стани у вивід Heartbeat. +- `channels.defaults.groupPolicy`: резервна політика груп, коли `groupPolicy` на рівні постачальника не задано. +- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/гілок/історії), `allowlist` (включати контекст лише від відправників зі списку дозволених), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для каналу: `channels..contextVisibility`. +- `channels.defaults.heartbeat.showOk`: включати стани здорових каналів у вивід Heartbeat. +- `channels.defaults.heartbeat.showAlerts`: включати стани деградації/помилок у вивід Heartbeat. - `channels.defaults.heartbeat.useIndicator`: відображати компактний вивід Heartbeat у стилі індикатора. ### WhatsApp -WhatsApp працює через web channel gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через вебканал Gateway (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс. ```json5 { @@ -124,7 +124,7 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за textChunkLimit: 4000, chunkMode: "length", // length | newline mediaMaxMb: 50, - sendReadReceipts: true, // blue ticks (false in self-chat mode) + sendReadReceipts: true, // сині галочки (false у режимі чату із самим собою) groups: { "*": { requireMention: true }, }, @@ -164,10 +164,10 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за } ``` -- Вихідні команди типово використовують обліковий запис `default`, якщо він існує; інакше — перший налаштований ID облікового запису (відсортований). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- Застарілий каталог auth Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. -- Перевизначення для окремого облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він присутній; інакше — перший налаштований ідентифікатор облікового запису (у відсортованому порядку). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей типовий вибір резервного облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -225,13 +225,13 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символічні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- У багатооблікових конфігураціях (2+ ID облікових записів) задайте явне значення за замовчуванням (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо цього бракує або значення невалідне. -- `configWrites: false` блокує записи config, ініційовані з Telegram (міграції ID супергруп, `/config set|unset`). -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Попередній перегляд потоків Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; символьні посилання відхиляються), з `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- У конфігураціях із кількома обліковими записами (2+ ідентифікатори облікових записів) задайте явний типовий (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути резервної маршрутизації; `openclaw doctor` попереджає, якщо його немає або він недійсний. +- `configWrites: false` блокує запис конфігурації, ініційований з Telegram (міграції ID супергруп, `/config set|unset`). +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для тем форуму (використовуйте канонічний `chatId:topic:topicId` у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Попередній перегляд потоку Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Політика повторів: див. [Політика повторів](/uk/concepts/retry). ### Discord @@ -333,36 +333,36 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за } ``` -- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для облікового запису за замовчуванням. -- Прямі вихідні виклики, які передають явний Discord `token`, використовують цей токен для виклику; параметри повторних спроб/політики облікового запису й надалі беруться з вибраного облікового запису в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. -- Slug-и guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі channel використовують slug-ім’я (без `#`). Надавайте перевагу ID guild. -- Повідомлення, створені ботом, за замовчуванням ігноруються. `allowBots: true` увімкне їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). -- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення channel) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). +- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які надають явний Discord `token`, використовують цей токен для виклику; налаштування повторів/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку середовища виконання. +- Необов’язковий `channels.discord.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; окремі числові ідентифікатори відхиляються. +- Slug-и guild — у нижньому регістрі, а пробіли замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ідентифікаторам guild. +- Повідомлення, створені ботом, типово ігноруються. `allowBots: true` вмикає їх; використовуйте `allowBots: "mentions"`, щоб приймати лише повідомлення ботів, які згадують бота (власні повідомлення все одно фільтруються). +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення каналів) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (крім @everyone/@here). - `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони коротші за 2000 символів. -- `channels.discord.threadBindings` керує маршрутизацією Discord, прив’язаною до тредів: - - `enabled`: перевизначення Discord для можливостей сесій, прив’язаних до тредів (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age`, а також прив’язана доставка/маршрутизація) +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до гілок Discord: + - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до гілок (`/focus`, `/unfocus`, `/agents`, `/session idle`, `/session max-age` і прив’язана доставка/маршрутизація) - `idleHours`: перевизначення Discord для автоматичного зняття фокуса через неактивність у годинах (`0` вимикає) - `maxAgeHours`: перевизначення Discord для жорсткого максимального віку в годинах (`0` вимикає) - - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язування тредів `sessions_spawn({ thread: true })` -- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і тредів (використовуйте id каналу/треду в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- `channels.discord.ui.components.accentColor` задає акцентний колір для контейнерів Discord components v2. + - `spawnSubagentSessions`: прапорець opt-in для автоматичного створення/прив’язки гілок через `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні ACP-прив’язки для каналів і гілок (використовуйте id каналу/гілки в `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` задає колір акценту для контейнерів компонентів Discord v2. - `channels.discord.voice` вмикає розмови в голосових каналах Discord і необов’язкові перевизначення auto-join + TTS. -- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються в параметри DAVE `@discordjs/voice` (типово `true` і `24`). -- OpenClaw додатково намагається відновити приймання голосу, виходячи й повторно входячи до голосової сесії після повторних збоїв дешифрування. -- `channels.discord.streaming` — канонічний ключ режиму потокової передачі. Застарілі `streamMode` і булеві значення `streaming` мігруються автоматично. -- `channels.discord.autoPresence` відображає доступність runtime у presence бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. -- `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваним ім’ям/тегом (режим аварійної сумісності). -- `channels.discord.execApprovals`: нативна для Discord доставка погоджень exec і авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Discord, яким дозволено погоджувати запити exec. Якщо не задано, використовує резервне значення з `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий allowlist ID агентів. Опустіть, щоб пересилати погодження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM тим, хто погоджує, `"channel"` надсилає у вихідний channel, `"both"` надсилає в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені погоджувачі. - - `cleanupAfterResolve`: коли `true`, видаляє DM із погодженнями після погодження, відхилення або тайм-ауту. +- `channels.discord.voice.daveEncryption` і `channels.discord.voice.decryptionFailureTolerance` напряму передаються до параметрів DAVE у `@discordjs/voice` (типові значення — `true` і `24`). +- OpenClaw додатково намагається відновити приймання голосу, виходячи з голосового сеансу та повторно приєднуючись після повторних збоїв дешифрування. +- `channels.discord.streaming` — канонічний ключ режиму потоку. Застарілі значення `streamMode` і булеві значення `streaming` мігруються автоматично. +- `channels.discord.autoPresence` зіставляє доступність під час виконання зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. +- `channels.discord.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). +- `channels.discord.execApprovals`: нативна для Discord доставка погоджень exec і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли погоджувачів можна визначити через `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ідентифікатори користувачів Discord, яким дозволено погоджувати exec-запити. Якщо не вказано, використовується `commands.ownerAllowFrom`. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex). + - `target`: куди надсилати запити на погодження. `"dm"` (типово) надсилає в DM погоджувачів, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target містить `"channel"`, кнопками можуть користуватися лише визначені погоджувачі. + - `cleanupAfterResolve`: коли `true`, видаляє DM з погодженням після схвалення, відхилення або тайм-ауту. -**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (з `guilds..users` для всіх повідомлень). +**Режими сповіщень про реакції:** `off` (немає), `own` (повідомлення бота, типово), `all` (усі повідомлення), `allowlist` (від `guilds..users` для всіх повідомлень). ### Google Chat @@ -393,11 +393,11 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за } ``` -- JSON облікового запису служби: вбудований (`serviceAccount`) або через файл (`serviceAccountFile`). -- Також підтримується SecretRef для облікового запису служби (`serviceAccountRef`). -- Резервні env-змінні: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- JSON облікового запису служби: inline (`serviceAccount`) або через файл (`serviceAccountFile`). +- Також підтримується SecretRef облікового запису служби (`serviceAccountRef`). +- Резервні значення змінних середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. - Використовуйте `spaces/` або `users/` для цілей доставки. -- `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваним email principal (режим аварійної сумісності). +- `channels.googlechat.dangerouslyAllowNameMatching` знову вмикає зіставлення за змінюваною email-принципальною сутністю (режим сумісності break-glass). ### Slack @@ -464,35 +464,35 @@ WhatsApp працює через web channel gateway (Baileys Web). Він за } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні env-значення для облікового запису за замовчуванням). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого облікового запису). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають plaintext +- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` для резервного отримання зі змінних середовища для типового облікового запису). +- **Режим HTTP** вимагає `botToken` плюс `signingSecret` (у корені або для кожного облікового запису окремо). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають прості текстові рядки або об’єкти SecretRef. -- Знімки облікових записів Slack надають поля джерела/статусу для кожного облікового запису, такі як - `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, в HTTP mode, +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у режимі HTTP, `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис - налаштовано через SecretRef, але поточний шлях команди/runtime не зміг - розв’язати значення секрету. -- `configWrites: false` блокує записи config, ініційовані зі Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- `channels.slack.streaming.mode` — канонічний ключ режиму потокової передачі Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потокової передачі Slack. Застарілі `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. + налаштовано через SecretRef, але поточний шлях команди/середовища виконання не зміг + визначити значення секрету. +- `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. +- Необов’язковий `channels.slack.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним транспортом потоку Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` мігруються автоматично. - Використовуйте `user:` (DM) або `channel:` для цілей доставки. -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -**Ізоляція сесій тредів:** `thread.historyScope` — окремо для кожного треду (типово) або спільно для channel. `thread.inheritParent` копіює стенограму батьківського каналу в нові треди. +**Ізоляція сеансів гілок:** `thread.historyScope` — для кожної гілки окремо (типово) або спільний для каналу. `thread.inheritParent` копіює стенограму батьківського каналу в нові гілки. -- Нативна потокова передача Slack плюс статус треду Slack у стилі асистента "is typing..." вимагають цілі відповіді в треді. DM верхнього рівня за замовчуванням залишаються поза тредом, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі треду. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація тих, хто погоджує. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Нативний потік Slack разом зі статусом гілки Slack у стилі асистента "is typing..." вимагають ціль відповіді у гілці. DM верхнього рівня типово залишаються поза гілками, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі гілки. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а потім видаляє її після завершення. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: нативна для Slack доставка погоджень exec і авторизація погоджувачів. Та сама схема, що й для Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ідентифікатори користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ------------ | ------- | ---------------------- | +| Група дій | Типово | Примітки | +| ------------ | -------- | ---------------------- | | reactions | увімкнено | Реакції + список реакцій | | messages | увімкнено | Читання/надсилання/редагування/видалення | | pins | увімкнено | Закріплення/відкріплення/список | | memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних emoji | +| emojiList | увімкнено | Список користувацьких емодзі | ### Mattermost @@ -526,23 +526,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). -Коли ввімкнені нативні команди Mattermost: +Коли нативні команди Mattermost увімкнено: - `commands.callbackPath` має бути шляхом (наприклад `/api/channels/mattermost/command`), а не повним URL. -- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути доступним із сервера Mattermost. -- Нативні зворотні виклики slash-команд автентифікуються токенами для кожної команди, які Mattermost повертає - під час реєстрації slash-команди. Якщо реєстрація не вдається або жодну - команду не активовано, OpenClaw відхиляє зворотні виклики з повідомленням +- `commands.callbackUrl` має вказувати на endpoint Gateway OpenClaw і бути досяжним із сервера Mattermost. +- Нативні зворотні виклики slash-команд автентифікуються за допомогою токенів + для кожної команди, які Mattermost повертає під час реєстрації slash-команди. Якщо реєстрація не вдається або жодна + команда не активована, OpenClaw відхиляє зворотні виклики з повідомленням `Unauthorized: invalid command token.` -- Для приватних/tailnet/internal хостів зворотного виклику Mattermost може вимагати, +- Для приватних/tailnet/внутрішніх хостів зворотних викликів Mattermost може вимагати, щоб `ServiceSettings.AllowedUntrustedInternalConnections` містив хост/домен зворотного виклику. Використовуйте значення хоста/домену, а не повні URL. -- `channels.mattermost.configWrites`: дозволити або заборонити записи config, ініційовані з Mattermost. -- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в channels. -- `channels.mattermost.groups..requireMention`: перевизначення фільтрації за згадуванням для окремого channel (`"*"` для значення за замовчуванням). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. +- `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. +- `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. ### Signal @@ -563,11 +563,11 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). -- `channels.signal.account`: закріпити запуск channel за конкретною ідентичністю облікового запису Signal. -- `channels.signal.configWrites`: дозволити або заборонити записи config, ініційовані з Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. +- `channels.signal.account`: прив’язати запуск каналу до конкретної ідентичності облікового запису Signal. +- `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Signal. +- Необов’язковий `channels.signal.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. ### BlueBubbles @@ -587,9 +587,9 @@ BlueBubbles — рекомендований шлях для iMessage (на ос ``` - Основні шляхи ключів, охоплені тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. -- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сесій ACP. Використовуйте BlueBubbles handle або цільовий рядок (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). -- Повну конфігурацію channel BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сеансів ACP. Використовуйте дескриптор BlueBubbles або рядок цілі (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- Повну конфігурацію каналу BlueBubbles описано в [BlueBubbles](/uk/channels/bluebubbles). ### iMessage @@ -617,15 +617,15 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон а } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. - Потрібен Full Disk Access до БД Messages. - Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на обгортку SSH; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста реле вже існує в `~/.ssh/known_hosts`. -- `channels.imessage.configWrites`: дозволити або заборонити записи config, ініційовані з iMessage. -- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сесій ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста ретранслятора вже існує в `~/.ssh/known_hosts`. +- `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з iMessage. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сеансів ACP. Використовуйте нормалізований дескриптор або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). @@ -638,7 +638,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює через Plugin і налаштовується в `channels.matrix`. +Matrix працює на основі Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -668,25 +668,25 @@ Matrix працює через Plugin і налаштовується в `channe } ``` -- Автентифікація токеном використовує `accessToken`; автентифікація паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-proxy. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. -- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/internal homeserver. `proxy` і цей opt-in для мережі — незалежні механізми керування. -- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у багатооблікових конфігураціях. -- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не встановите `autoJoin: "allowlist"` разом з `autoJoinAllowlist` або `autoJoin: "always"`. -- `channels.matrix.execApprovals`: нативна для Matrix доставка погоджень exec і авторизація тих, хто погоджує. - - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли тих, хто погоджує, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено погоджувати запити exec. - - `agentFilter`: необов’язковий allowlist ID агентів. Опустіть, щоб пересилати погодження для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). +- Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати його через `channels.matrix.accounts..proxy`. +- `channels.matrix.network.dangerouslyAllowPrivateNetwork` дозволяє приватні/внутрішні homeserver-и. `proxy` і цей opt-in для мережі — незалежні механізми керування. +- `channels.matrix.defaultAccount` вибирає бажаний обліковий запис у конфігураціях із кількома обліковими записами. +- `channels.matrix.autoJoin` типово має значення `off`, тому запрошені кімнати й нові запрошення в стилі DM ігноруються, доки ви не задасте `autoJoin: "allowlist"` разом із `autoJoinAllowlist` або `autoJoin: "always"`. +- `channels.matrix.execApprovals`: нативна для Matrix доставка погоджень exec і авторизація погоджувачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto погодження exec активуються, коли погоджувачів можна визначити через `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено погоджувати exec-запити. + - `agentFilter`: необов’язковий список дозволених ID агентів. Якщо пропустити, погодження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex). - `target`: куди надсилати запити на погодження. `"dm"` (типово), `"channel"` (вихідна кімната) або `"both"`. - - Перевизначення для окремого облікового запису: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як Matrix DM групуються в сесії: `per-user` (типово) спільно використовує їх за маршрутизованим peer, тоді як `per-room` ізолює кожну DM-кімнату. -- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму політику proxy, що й runtime-трафік. -- Повну конфігурацію Matrix, правила націлювання та приклади налаштування описано в [Matrix](/uk/channels/matrix). + - Перевизначення для кожного облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як Matrix DM групуються в сеанси: `per-user` (типово) спільний за маршрутизованим співрозмовником, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки стану Matrix і пошук у живому каталозі використовують ту саму політику проксі, що й трафік середовища виконання. +- Повну конфігурацію Matrix, правила націлювання й приклади налаштування описано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює через Plugin і налаштовується в `channels.msteams`. +Microsoft Teams працює на основі Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -702,11 +702,11 @@ Microsoft Teams працює через Plugin і налаштовується ``` - Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повний config Teams (облікові дані, Webhook, політика DM/груп, перевизначення для окремих team/channel) описано в [Microsoft Teams](/uk/channels/msteams). +- Повну конфігурацію Teams (облікові дані, Webhook, політика DM/груп, перевизначення для кожної команди/каналу) описано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює через Plugin і налаштовується в `channels.irc`. +IRC працює на основі Plugin і налаштовується в `channels.irc`. ```json5 { @@ -728,12 +728,12 @@ IRC працює через Plugin і налаштовується в `channels. ``` - Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір облікового запису за замовчуванням, якщо він відповідає налаштованому ID облікового запису. -- Повну конфігурацію channel IRC (host/port/TLS/channels/allowlists/фільтрація за згадуванням) описано в [IRC](/uk/channels/irc). +- Необов’язковий `channels.irc.defaultAccount` перевизначає типовий вибір облікового запису, якщо він відповідає налаштованому ідентифікатору облікового запису. +- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/обмеження за згадками) описано в [IRC](/uk/channels/irc). -### Багатообліковість (усі channels) +### Кілька облікових записів (усі канали) -Запускайте кілька облікових записів для одного channel (кожен зі своїм `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -755,27 +755,27 @@ IRC працює через Plugin і налаштовується в `channels. ``` - `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). -- Токени env застосовуються лише до облікового запису **default**. -- Базові параметри channel застосовуються до всіх облікових записів, якщо їх не перевизначено для окремого облікового запису. +- Токени зі змінних середовища застосовуються лише до **типового** облікового запису. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо вони не перевизначені для конкретного облікового запису. - Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. -- Якщо ви додаєте обліковий запис, що не є default, через `openclaw channels add` (або onboarding channel), залишаючись при цьому на top-level config channel для одного облікового запису, OpenClaw спочатку підвищує значення top-level для одного облікового запису, що належать до облікового запису, у map облікових записів channel, щоб початковий обліковий запис продовжив працювати. У більшості channels вони переміщуються в `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. -- Наявні прив’язки лише до channel (без `accountId`) і далі збігатимуться з обліковим записом default; прив’язки до окремих облікових записів залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи top-level значення одного облікового запису, що належать до облікового запису, у підвищений обліковий запис, вибраний для цього channel. У більшості channels використовується `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/default ціль. +- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або через онбординг каналу), коли все ще використовується конфігурація каналу верхнього рівня для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у мапу облікових записів каналу, щоб початковий обліковий запис і далі працював. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише до каналу (без `accountId`) і далі відповідають типовому обліковому запису; прив’язки на рівні облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до облікового запису, у вибраний для цього каналу підвищений обліковий запис. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. -### Інші Plugin channels +### Інші канали Plugin -Багато Plugin channels налаштовуються як `channels.` і описані на своїх окремих сторінках channel (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). -Див. повний індекс channels: [Channels](/uk/channels). +Багато каналів Plugin налаштовуються як `channels.` і документовані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Перегляньте повний індекс каналів: [Канали](/uk/channels). -### Фільтрація за згадуванням у групових чатах +### Обмеження за згадками в групових чатах -Для групових повідомлень типово **потрібна згадка** (метадані згадки або безпечні regex-шаблони). Це стосується групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Повідомлення в групах типово **вимагають згадки** (метадані згадки або безпечні regex-патерни). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. **Типи згадок:** -- **Згадки в метаданих**: нативні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Невалідні шаблони й небезпечні вкладені повторення ігноруються. -- Фільтрація за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадки в метаданих**: рідні @-згадки платформи. Ігноруються в режимі self-chat WhatsApp. +- **Текстові патерни**: безпечні regex-патерни в `agents.list[].groupChat.mentionPatterns`. Недійсні патерни та небезпечне вкладене повторення ігноруються. +- Обмеження за згадками застосовується лише тоді, коли виявлення можливе (рідні згадки або принаймні один патерн). ```json5 { @@ -788,9 +788,9 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -`messages.groupChat.historyLimit` задає глобальне значення за замовчуванням. Channels можуть перевизначити його через `channels..historyLimit` (або для окремого облікового запису). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для кожного облікового запису). Установіть `0`, щоб вимкнути. -#### Обмеження історії DM +#### Ліміти історії DM ```json5 { @@ -805,13 +805,13 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -Порядок розв’язання: перевизначення для окремого DM → значення provider за замовчуванням → без обмеження (зберігається все). +Порядок визначення: перевизначення для конкретного DM → типове значення постачальника → без ліміту (зберігається все). -Підтримується для: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. +Підтримуються: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. #### Режим self-chat -Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує рідні @-згадки, відповідає лише на текстові патерни): ```json5 { @@ -832,7 +832,7 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -### Commands (обробка команд чату) +### Команди (обробка команд чату) ```json5 { @@ -859,40 +859,40 @@ IRC працює через Plugin і налаштовується в `channels. } ``` - + -- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + bundled команд див. у [Slash Commands](/uk/tools/slash-commands). -- Ця сторінка є **довідкою за ключами config**, а не повним каталогом команд. Команди, що належать channel/Plugin, наприклад QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, описані на їхніх сторінках channel/Plugin, а також у [Slash Commands](/uk/tools/slash-commands). +- Цей блок налаштовує поверхні команд. Поточний каталог вбудованих + bundled команд див. у [Слеш-команди](/uk/tools/slash-commands). +- Ця сторінка — **довідник ключів конфігурації**, а не повний каталог команд. Команди, що належать каналу/Plugin, як-от QQ Bot `/bot-ping` `/bot-help` `/bot-logs`, LINE `/card`, device-pair `/pair`, memory `/dreaming`, phone-control `/phone` і Talk `/voice`, документовані на сторінках відповідних каналів/Plugin, а також у [Слеш-команди](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. -- `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. -- `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. -- Перевизначення для окремого channel: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначуйте реєстрацію нативних команд Skills для окремого channel через `channels..commands.nativeSkills`. +- `native: "auto"` вмикає рідні команди для Discord/Telegram, залишає Slack вимкненим. +- `nativeSkills: "auto"` вмикає рідні команди Skills для Discord/Telegram, залишає Slack вимкненим. +- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. +- Перевизначайте реєстрацію рідних команд Skills для окремого каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. -- `bash: true` вмикає `! ` для командної оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. -- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів gateway `chat.send` постійні записи `/config set|unset` також вимагають `operator.admin`; доступний лише для читання `/config show` залишається доступним для звичайних клієнтів operator з правом запису. -- `mcp: true` вмикає `/mcp` для config MCP-сервера, яким керує OpenClaw, у `mcp.servers`. -- `plugins: true` вмикає `/plugins` для виявлення Plugin, встановлення та керування ввімкненням/вимкненням. -- `channels..configWrites` керує дозволом мутацій config для кожного channel (типово: true). -- Для багатооблікових channels `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). -- `restart: false` вимикає `/restart` і дії інструмента перезапуску gateway. Типово: `true`. -- `ownerAllowFrom` — це явний allowlist власника для команд/інструментів лише для власника. Він окремий від `allowFrom`. -- `ownerDisplay: "hash"` хешує ID власника в системному запиті. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного provider. Якщо його встановлено, це **єдине** джерело авторизації (allowlists/pairing channel і `useAccessGroups` ігноруються). +- `bash: true` вмикає `! ` для оболонки хоста. Потрібні `tools.elevated.enabled` і відправник у `tools.elevated.allowFrom.`. +- `config: true` вмикає `/config` (читання/запис `openclaw.json`). Для клієнтів Gateway `chat.send` постійні записи `/config set|unset` також потребують `operator.admin`; доступний лише для читання `/config show` лишається доступним звичайним клієнтам-операторам із правом запису. +- `mcp: true` вмикає `/mcp` для конфігурації MCP-серверів, якими керує OpenClaw, у `mcp.servers`. +- `plugins: true` вмикає `/plugins` для виявлення Plugin, інсталяції та керування увімкненням/вимкненням. +- `channels..configWrites` керує мутаціями конфігурації для кожного каналу (типово: true). +- Для каналів із кількома обліковими записами `channels..accounts..configWrites` також керує записами, націленими на цей обліковий запис (наприклад `/allowlist --config --account ` або `/config set channels..accounts....`). +- `restart: false` вимикає `/restart` і дії інструмента перезапуску Gateway. Типово: `true`. +- `ownerAllowFrom` — це явний список дозволених власників для команд/інструментів лише для власника. Він відокремлений від `allowFrom`. +- `ownerDisplay: "hash"` хешує ID власників у системному промпті. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` є для кожного постачальника окремо. Якщо задано, це **єдине** джерело авторизації (списки дозволених каналу/сполучення і `useAccessGroups` ігноруються). - `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не задано. -- Карта документації команд: - - каталог вбудованих + bundled: [Slash Commands](/uk/tools/slash-commands) - - поверхні команд, специфічні для channel: [Channels](/uk/channels) +- Відображення документації команд: + - каталог вбудованих + bundled команд: [Слеш-команди](/uk/tools/slash-commands) + - поверхні команд, специфічні для каналів: [Канали](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди pairing: [Pairing](/uk/channels/pairing) + - команди сполучення: [Сполучення](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - memory Dreaming: [Dreaming](/uk/concepts/dreaming) + - dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) --- -## Значення агентів за замовчуванням +## Типові значення агента ### `agents.defaults.workspace` @@ -906,7 +906,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись вгору від workspace. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного промпту. Якщо не задано, OpenClaw визначає його автоматично, піднімаючись вгору від workspace. ```json5 { @@ -916,7 +916,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.skills` -Необов’язковий allowlist Skills за замовчуванням для агентів, які не задають +Необов’язковий типовий список дозволених Skills для агентів, які не задають `agents.list[].skills`. ```json5 @@ -932,10 +932,10 @@ IRC працює через Plugin і налаштовується в `channels. } ``` -- Не задавайте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. -- Не задавайте `agents.list[].skills`, щоб успадковувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не використовувати Skills. -- Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він +- Пропустіть `agents.defaults.skills`, щоб типово не обмежувати Skills. +- Пропустіть `agents.list[].skills`, щоб успадкувати типові значення. +- Установіть `agents.list[].skills: []`, щоб не було Skills. +- Непорожній список `agents.list[].skills` є фінальним набором для цього агента; він не об’єднується з типовими значеннями. ### `agents.defaults.skipBootstrap` @@ -950,9 +950,9 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли workspace вбудовуються в системний запит. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вбудовуються в системний промпт. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap workspace, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне вбудовування bootstrap-файлів workspace, зменшуючи розмір промпту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. ```json5 { @@ -962,7 +962,7 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл workspace до обрізання. Типове значення: `12000`. +Максимальна кількість символів на bootstrap-файл workspace до обрізання. Типове значення: `12000`. ```json5 { @@ -982,12 +982,12 @@ IRC працює через Plugin і налаштовується в `channels. ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує текстом попередження, видимим агенту, коли bootstrap-контекст обрізається. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. Типове значення: `"once"`. -- `"off"`: ніколи не вбудовувати текст попередження в системний запит. -- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного варіанта обрізання (рекомендовано). -- `"always"`: вбудовувати попередження при кожному запуску, коли є обрізання. +- `"off"`: ніколи не вбудовувати текст попередження в системний промпт. +- `"once"`: вбудовувати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). +- `"always"`: вбудовувати попередження на кожному запуску, коли є обрізання. ```json5 { @@ -997,24 +997,24 @@ IRC працює через Plugin і налаштовується в `channels. ### Карта володіння бюджетом контексту -OpenClaw має кілька великих бюджетів запиту/контексту, і вони +OpenClaw має кілька великих бюджетів промпту/контексту, і вони навмисно розділені за підсистемами, а не проходять через один загальний параметр. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне вбудовування bootstrap workspace. + звичайне вбудовування bootstrap-файлів workspace. - `agents.defaults.startupContext.*`: - одноразовий стартовий пролог для запусків `/new` і `/reset`, включно з нещодавніми + одноразова стартова преамбула для `/new` і `/reset`, включно з недавніми щоденними файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, вбудований у системний запит. + компактний список Skills, вбудований у системний промпт. - `agents.defaults.contextLimits.*`: - обмежені витяги runtime і вбудовані блоки, що належать runtime. + обмежені витяги часу виконання та вбудовані блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів і вбудовування для індексованого пошуку в пам’яті. + фрагменти пошуку в індексованій пам’яті та розміри вбудовування. -Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший +Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1022,7 +1022,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.startupContext` -Керує стартовим прологом першого ходу, який вбудовується при простих запусках `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, яка вбудовується в прості запуски `/new` і `/reset`. ```json5 { @@ -1043,7 +1043,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.contextLimits` -Спільні типові значення для обмежених поверхонь runtime-контексту. +Спільні типові значення для обмежених поверхонь контексту runtime. ```json5 { @@ -1060,18 +1060,19 @@ OpenClaw має кілька великих бюджетів запиту/кон } ``` -- `memoryGetMaxChars`: типове обмеження витягу `memory_get` до того, як буде додано - метадані обрізання і повідомлення про продовження. +- `memoryGetMaxChars`: типове обмеження витягу `memory_get` до додавання метаданих + обрізання та повідомлення про продовження. - `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` - не задано. -- `toolResultMaxChars`: поточне обмеження результатів tool, що використовується для збережених результатів і - відновлення після переповнення. -- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час оновлення ін’єкції після Compaction. + пропущено. +- `toolResultMaxChars`: поточне обмеження результату інструмента, яке використовується для збережених результатів і + відновлення переповнення. +- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вбудовування + оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються -з `agents.defaults.contextLimits`. +Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +від `agents.defaults.contextLimits`. ```json5 { @@ -1097,7 +1098,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, вбудованого в системний запит. Це +Глобальне обмеження для компактного списку Skills, який вбудовується в системний промпт. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -1112,7 +1113,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення бюджету запиту Skills для окремого агента. +Перевизначення для конкретного агента для бюджету промпту Skills. ```json5 { @@ -1131,11 +1132,11 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами provider. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами постачальника. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-token і розмір корисного навантаження запиту для запусків із великою кількістю скриншотів. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для запусків із великою кількістю знімків екрана. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -1145,7 +1146,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не для часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного промпту (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1155,7 +1156,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.timeFormat` -Формат часу в системному запиті. Типове значення: `auto` (налаштування ОС). +Формат часу в системному промпті. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1193,7 +1194,7 @@ OpenClaw має кілька великих бюджетів запиту/кон primary: "anthropic/claude-opus-4-6", fallbacks: ["openai/gpt-5.4-mini"], }, - params: { cacheRetention: "long" }, // глобальні типові параметри provider + params: { cacheRetention: "long" }, // global default provider params embeddedHarness: { runtime: "auto", // auto | pi | registered harness id, e.g. codex fallback: "pi", // pi | none @@ -1214,55 +1215,55 @@ OpenClaw має кілька великих бюджетів запиту/кон - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс упорядковані моделі failover. + - Форма об’єкта задає основну модель плюс упорядковані моделі резервного переходу. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом tool `image` як його config vision-model. + - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви вибираєте provider/model безпосередньо, також налаштуйте відповідну автентифікацію/API key provider (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо значення пропущено, `image_generate` все одно може визначити типове значення provider на основі автентифікації. Спочатку він пробує поточний типовий provider, потім решту зареєстрованих provider генерації зображень у порядку provider-id. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key постачальника (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). + - Якщо пропущено, `image_generate` усе одно може вивести типове значення постачальника з наявною автентифікацією. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації музики і вбудованим tool `music_generate`. + - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо значення пропущено, `music_generate` все одно може визначити типове значення provider на основі автентифікації. Спочатку він пробує поточний типовий provider, потім решту зареєстрованих provider генерації музики в порядку provider-id. - - Якщо ви вибираєте provider/model безпосередньо, також налаштуйте відповідну автентифікацію/API key provider. + - Якщо пропущено, `music_generate` усе одно може вивести типове значення постачальника з наявною автентифікацією. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації музики в порядку provider-id. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key постачальника. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації відео і вбудованим tool `video_generate`. + - Використовується спільною можливістю генерації відео та вбудованим інструментом `video_generate`. - Типові значення: `qwen/wan2.6-t2v`, `qwen/wan2.6-i2v`, `qwen/wan2.6-r2v`, `qwen/wan2.6-r2v-flash` або `qwen/wan2.7-r2v`. - - Якщо значення пропущено, `video_generate` все одно може визначити типове значення provider на основі автентифікації. Спочатку він пробує поточний типовий provider, потім решту зареєстрованих provider генерації відео в порядку provider-id. - - Якщо ви вибираєте provider/model безпосередньо, також налаштуйте відповідну автентифікацію/API key provider. - - Bundled provider генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня provider `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо пропущено, `video_generate` усе одно може вивести типове значення постачальника з наявною автентифікацією. Спочатку він пробує поточного типового постачальника, а потім решту зареєстрованих постачальників генерації відео в порядку provider-id. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API key постачальника. + - Вбудований постачальник генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість 10 секунд і параметри рівня постачальника `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується tool `pdf` для маршрутизації моделі. - - Якщо значення пропущено, tool PDF використовує резервно `imageModel`, а потім визначену модель сесії/типову модель. -- `pdfMaxBytesMb`: типове обмеження розміру PDF для tool `pdf`, коли `maxBytesMb` не передається під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються режимом резервного витягання в tool `pdf`. -- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типово: `"off"`. -- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типово: `"on"`. -- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.5`). Якщо ви пропускаєте provider, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого provider для цього точного model id, і лише після цього використовує типового налаштованого provider (застаріла сумісна поведінка, тому надавайте перевагу явному `provider/model`). Якщо цей provider більше не надає налаштовану типову модель, OpenClaw використовує резервно перший налаштований provider/model замість того, щоб показувати застаріле типове значення видаленого provider. -- `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для provider, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відхиляє заміни, які видалили б наявні записи allowlist, якщо ви не передасте `--replace`. - - Потоки configure/onboarding на рівні provider об’єднують вибрані моделі provider у цю map і зберігають не пов’язані provider, уже налаштовані раніше. -- `params`: глобальні типові параметри provider, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (config): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Подробиці див. у [Prompt Caching](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. -- Засоби запису config, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта і, коли можливо, зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно серіалізується). Типово: 4. + - Використовується інструментом `pdf` для маршрутизації моделі. + - Якщо пропущено, інструмент PDF повертається до `imageModel`, а потім до визначеної моделі сеансу/типової моделі. +- `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. +- `pdfMaxPages`: типова максимальна кількість сторінок, яку враховує режим резервного вилучення в інструменті `pdf`. +- `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. +- `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад `openai/gpt-5.5`). Якщо пропустити постачальника, OpenClaw спочатку пробує alias, потім унікальний збіг exact model id серед налаштованих постачальників і лише після цього повертається до налаштованого типового постачальника (застаріла поведінка сумісності, тому надавайте перевагу явному `provider/model`). Якщо цей постачальник більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення від видаленого постачальника. +- `models`: налаштований каталог моделей і список дозволених моделей для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для постачальника, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених, якщо не передати `--replace`. + - Потоки configure/onboarding з областю дії постачальника об’єднують вибрані моделі постачальника в цю мапу та зберігають уже налаштованих, але не пов’язаних постачальників. +- `params`: глобальні типові параметри постачальника, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). +- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного id агента) перевизначає за ключем. Докладніше див. у [Кешування промптів](/uk/reference/prompt-caching). +- `embeddedHarness`: типова низькорівнева політика runtime для вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим harness Plugin перехоплювати підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований id harness, такий як `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та, де можливо, зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізований). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -Більшість розгортань мають залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте його, коли довірений Plugin надає нативний harness, наприклад bundled +Для більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled harness app-server Codex. ```json5 { agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -1273,13 +1274,13 @@ harness app-server Codex. ``` - `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Bundled Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як сумісний резервний варіант, коли не вибрано жодного harness Plugin. `"none"` змушує помилку при відсутньому або непідтримуваному виборі harness Plugin замість тихого використання PI. Помилки вибраного harness Plugin завжди показуються безпосередньо. -- Перевизначення через середовище: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. -- Для розгортань лише з Codex установіть `model: "codex/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Вибір harness закріплюється за кожним id сесії після першого вбудованого запуску. Зміни config/env впливають на нові або скинуті сесії, а не на наявну стенограму. Застарілі сесії з історією стенограми, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує не-PI id harness, такі як `codex`, поруч із `Fast`. -- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео і TTS усе ще використовують свої параметри provider/model. +- `fallback`: `"pi"` або `"none"`. `"pi"` зберігає вбудований harness PI як резервний варіант сумісності, коли жоден harness Plugin не вибрано. `"none"` призводить до помилки за відсутнього або непідтримуваного вибору harness Plugin замість тихого використання PI. Збої вибраного harness Plugin завжди показуються напряму. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=none` вимикає резервний перехід до PI для цього процесу. +- Для розгортань лише з Codex задайте `model: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Вибір harness закріплюється за id сеансу після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сеанси, а не на наявну стенограму. Застарілі сеанси з історією стенограми, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує не-PI id harness, такі як `codex`, поруч із `Fast`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої параметри provider/model. -**Скорочення для вбудованих alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Скорочення вбудованих alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): | Alias | Модель | | ------------------- | -------------------------------------- | @@ -1294,13 +1295,13 @@ harness app-server Codex. Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не встановите `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. -Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів tool. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Моделі Anthropic Claude 4.6 типово використовують `adaptive` thinking, коли явний рівень thinking не задано. +Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або не визначите `agents.defaults.models["zai/"].params.thinking` самостійно. +Моделі Z.AI типово вмикають `tool_stream` для потокової передачі викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, коли не задано явний рівень thinking. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів tool). Корисно як запасний варіант, коли API provider виходять з ладу. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як резервний варіант, коли API-постачальники відмовляють. ```json5 { @@ -1328,13 +1329,13 @@ harness app-server Codex. } ``` -- CLI-бекенди орієнтовані насамперед на текст; tools завжди вимкнені. -- Сесії підтримуються, коли задано `sessionArg`. +- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. +- Сеанси підтримуються, коли задано `sessionArg`. - Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на рівні типових значень (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний промпт, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє або таке, що містить лише пробіли, значення ігнорується. Корисно для контрольованих експериментів із промптами. ```json5 { @@ -1348,7 +1349,7 @@ harness app-server Codex. ### `agents.defaults.promptOverlays` -Незалежні від provider накладки запитів, що застосовуються за сімейством моделей. ID моделей сімейства GPT-5 отримують спільний контракт поведінки між provider; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від постачальника накладки промптів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між постачальниками; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -1364,9 +1365,9 @@ harness app-server Codex. } ``` -- `"friendly"` (типово) і `"on"` вмикають дружній шар стилю взаємодії. -- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застарілий `plugins.entries.openai.config.personality` усе ще читається, коли це спільне налаштування не задано. +- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії. +- `"off"` вимикає лише дружній шар; тегований контракт поведінки GPT-5 залишається ввімкненим. +- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -1398,14 +1399,14 @@ harness app-server Codex. ``` - `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли `false`, пропускає розділ Heartbeat із системного запиту і не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типово: `true`. -- `suppressToolErrorWarnings`: коли `true`, пригнічує корисні навантаження попереджень про помилки tool під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його переривання. Залиште незаданим, щоб використовувати `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої доставки/доставки в DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` пригнічує доставку до прямої цілі та видає `reason=dm-blocked`. -- `lightContext`: коли `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. -- `isolatedSession`: коли `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Такий самий шаблон ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. -- Heartbeat виконують повні ходи агента — коротші інтервали спалюють більше токенів. +- `includeSystemPromptSection`: коли false, пропускає розділ Heartbeat у системному промпті та не вбудовує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: коли true, пригнічує корисні навантаження попереджень про помилки інструментів під час запусків Heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat до його примусового переривання. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і генерує `reason=dm-blocked`. +- `lightContext`: коли true, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів workspace. +- `isolatedSession`: коли true, кожен Heartbeat запускається в новому сеансі без попередньої історії розмови. Така сама схема ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. +- Для кожного агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, Heartbeat запускається **лише для цих агентів**. +- Heartbeat запускає повні ходи агента — коротші інтервали спалюють більше токенів. ### `agents.defaults.compaction` @@ -1435,19 +1436,19 @@ harness app-server Codex. } ``` -- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin provider Compaction. Якщо задано, викликається `summarize()` цього provider замість вбудованого підсумовування LLM. У разі помилки використовується вбудований варіант. Задання provider примусово встановлює `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction, після чого OpenClaw перериває її. Типово: `900`. -- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. -- `identifierInstructions`: необов’язковий спеціальний текст щодо збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. -- `postCompactionSections`: необов’язкові назви розділів AGENTS.md H2/H3, які повторно вбудовуються після Compaction. Типово `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вбудовування. Коли значення не задано або явно задано цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. -- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction мають виконуватися на іншій; якщо значення не задано, Compaction використовує основну модель сесії. -- `notifyUser`: коли `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і завершується (наприклад, "Compacting context..." і "Compaction complete"). За замовчуванням вимкнено, щоб Compaction залишався безшумним. -- `memoryFlush`: безшумний хід агента перед автоматичним Compaction для збереження довготривалої пам’яті. Пропускається, коли workspace доступний лише для читання. +- `mode`: `default` або `safeguard` (порційне підсумовування для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin постачальника compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` цього постачальника. У разі збою повертається до вбудованого варіанта. Установлення постачальника примусово задає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції compaction, після чого OpenClaw її перериває. Типове значення: `900`. +- `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані інструкції щодо збереження непрозорих ідентифікаторів під час підсумовування compaction. +- `identifierInstructions`: необов’язковий користувацький текст про збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `postCompactionSections`: необов’язкові назви розділів H2/H3 з AGENTS.md, які повторно вбудовуються після compaction. Типово `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вбудовування. Коли не задано або явно задано цю типову пару, старіші заголовки `Every Session`/`Safety` також приймаються як застарілий резервний варіант. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування compaction. Використовуйте це, коли основний сеанс має залишатися на одній моделі, а підсумки compaction — виконуватися на іншій; якщо не задано, compaction використовує основну модель сеансу. +- `notifyUser`: коли `true`, надсилає користувачеві короткі сповіщення, коли compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб compaction залишався безшумним. +- `memoryFlush`: безшумний агентний хід перед автоматичним compaction для збереження тривалої пам’яті. Пропускається, коли workspace доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати tool** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. ```json5 { @@ -1472,22 +1473,22 @@ harness app-server Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко обрізає завеликі результати tool, а потім за потреби повністю очищає старіші результати tool. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього дотику до кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, якщо потрібно, повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат tool на заповнювач. +**Повне очищення** замінює весь результат інструмента на заповнювач. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. -- Співвідношення базуються на символах (приблизно), а не на точних кількостях токенів. -- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. +- Блоки зображень ніколи не обрізаються і не очищаються. +- Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. +- Якщо повідомлень assistant менше, ніж `keepLastAssistants`, обрізання пропускається. -Подробиці поведінки див. у [Session Pruning](/uk/concepts/session-pruning). +Подробиці поведінки див. у [Обрізання сеансів](/uk/concepts/session-pruning). ### Блокова потокова передача @@ -1505,13 +1506,13 @@ harness app-server Codex. } ``` -- Канали, крім Telegram, вимагають явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для channel: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Для каналів, крім Telegram, потрібне явне `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для кожного облікового запису). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для агента: `agents.list[].humanDelay`. -Подробиці поведінки та розбиття на частини див. у [Streaming](/uk/concepts/streaming). +Подробиці про поведінку та порціонування див. у [Потокова передача](/uk/concepts/streaming). -### Індикатори набору тексту +### Індикатори набору ```json5 { @@ -1524,16 +1525,16 @@ harness app-server Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для особистих чатів/згадок, `message` для групових чатів без згадки. +- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Typing Indicators](/uk/concepts/typing-indicators). +Див. [Індикатори набору](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкова ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1628,54 +1629,54 @@ harness app-server Codex. } ``` - + -**Бекенд:** +**Backend:** -- `docker`: локальний runtime Docker (типово) -- `ssh`: загальний віддалений runtime на основі SSH -- `openshell`: runtime OpenShell +- `docker`: локальне середовище виконання Docker (типово) +- `ssh`: універсальне віддалене середовище виконання на основі SSH +- `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, параметри, специфічні для runtime, переміщуються в +Коли вибрано `backend: "openshell"`, специфічні для runtime налаштування переносяться до `plugins.entries.openshell.config`. -**Config бекенда SSH:** +**Конфігурація backend SSH:** -- `target`: ціль SSH у форматі `user@host[:port]` -- `command`: команда клієнта SSH (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace в кожній області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, передані до OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує в тимчасові файли під час runtime +- `target`: SSH-ціль у форматі `user@host[:port]` +- `command`: команда SSH-клієнта (типово: `ssh`) +- `workspaceRoot`: абсолютний віддалений корінь, який використовується для workspace з різною областю дії +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH -**Пріоритет автентифікації SSH:** +**Пріоритет SSH-автентифікації:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на основі SecretRef розв’язуються з активного знімка runtime секретів до початку сесії sandbox +- Значення `*Data`, що працюють через SecretRef, визначаються з активного знімка runtime секретів перед початком сеансу sandbox -**Поведінка бекенда SSH:** +**Поведінка backend SSH:** -- один раз ініціалізує віддалений workspace після створення або перевідтворення -- потім зберігає віддалений workspace SSH як канонічний -- маршрутизує `exec`, файлові tools і шляхи медіа через SSH +- один раз ініціалізує віддалений workspace після створення або повторного створення +- потім зберігає віддалений SSH-workspace як канонічний +- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує browser-контейнери sandbox +- не підтримує браузерні контейнери sandbox **Доступ до workspace:** -- `none`: workspace sandbox для кожної області в `~/.openclaw/sandboxes` +- `none`: workspace sandbox для кожної області дії в `~/.openclaw/sandboxes` - `ro`: workspace sandbox у `/workspace`, workspace агента монтується лише для читання в `/agent` - `rw`: workspace агента монтується для читання/запису в `/workspace` -**Область:** +**Область дії:** -- `session`: окремий контейнер + workspace для кожної сесії -- `agent`: один контейнер + workspace для кожного агента (типово) -- `shared`: спільний контейнер і workspace (без ізоляції між сесіями) +- `session`: окремий контейнер + workspace для кожного сеансу +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без міжсеансової ізоляції) -**Config Plugin OpenShell:** +**Конфігурація Plugin OpenShell:** ```json5 { @@ -1703,30 +1704,30 @@ harness app-server Codex. **Режим OpenShell:** -- `mirror`: перед `exec` ініціалізує віддалене середовище з локального, після `exec` синхронізує назад; локальний workspace залишається канонічним -- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, після чого канонічним залишається віддалений workspace +- `mirror`: перед `exec` віддалений простір синхронізується з локального, після `exec` синхронізується назад; локальний workspace залишається канонічним +- `remote`: під час створення sandbox віддалений простір ініціалізується один раз, після чого канонічним залишається віддалений workspace -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, після кроку початкового заповнення не синхронізуються в sandbox автоматично. -Транспортом є SSH у sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. +У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореневого файлового розділу з можливістю запису та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, записуваного кореня і користувача root. -**Для контейнерів типово встановлено `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). +**Контейнери типово використовують `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не задасте +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). -**Вхідні вкладення** тимчасово розміщуються в `media/inbound/*` в активному workspace. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному workspace. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки й прив’язки для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні та для окремого агента `binds` об’єднуються. -**Ізольований browser** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний запит. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, і OpenClaw видає URL із короткоживучим токеном (замість розкриття пароля в спільному URL). +**Sandbox-браузер** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вбудовується в системний промпт. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує VNC-автентифікацію, і OpenClaw генерує короткоживучий URL із токеном (замість того, щоб відкривати пароль у спільному URL). -- `allowHostControl: false` (типово) блокує для ізольованих сесій націлювання на browser хоста. -- `network` типово має значення `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge` лише тоді, коли вам явно потрібна глобальна bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер browser sandbox. Якщо це значення задано (включно з `[]`), воно замінює `docker.binds` для контейнера browser. -- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для хостів контейнерів: +- `allowHostControl: false` (типово) блокує націлювання sandbox-сеансів на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge`, лише коли вам явно потрібна глобальна bridge-зв’язність. +- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на рівні контейнера до діапазону CIDR (наприклад `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер sandbox-браузера. Якщо задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -1746,21 +1747,21 @@ harness app-server Codex. - `--disable-extensions` (типово ввімкнено) - `--disable-3d-apis`, `--disable-software-rasterizer` і `--disable-gpu` типово ввімкнені, і їх можна вимкнути через - `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо цього потребує використання WebGL/3D. - - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` повторно вмикає розширення, якщо ваш робочий процес + `OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0`, якщо для WebGL/3D це потрібно. + - `OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0` знову вмикає розширення, якщо ваш робочий процес залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; використовуйте власний образ browser із власною - entrypoint, щоб змінити типові значення контейнера. + - Типові значення є базою образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний + образ браузера з власним entrypoint. -Ізоляція browser і `sandbox.docker.binds` працюють лише з Docker. +Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. -Збирання образів: +Зберіть образи: ```bash scripts/sandbox-setup.sh # main sandbox image @@ -1817,26 +1818,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний id агента (обов’язково). -- `default`: коли задано кілька, перше має пріоритет (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. -- `model`: рядкова форма перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Завдання Cron, які перевизначають лише `primary`, усе ще успадковують типові fallback, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень, специфічних для агента, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. -- `skills`: необов’язковий allowlist Skills для окремого агента. Якщо значення не задано, агент успадковує `agents.defaults.skills`, якщо його встановлено; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сесії. -- `reasoningDefault`: необов’язковий типовий режим видимості reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast-mode для повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити одного агента лише для Codex, тоді як інші агенти зберігатимуть типовий fallback PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. +- `default`: якщо задано для кількох, перший має пріоритет (логуватиметься попередження). Якщо не задано ні для кого, типовим стає перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові fallback, якщо ви не задасте `fallbacks: []`. +- `params`: параметри потоку для конкретного агента, які об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. +- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо їх задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сеансу. +- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сеансу. +- `fastModeDefault`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для повідомлення або сеансу. +- `embeddedHarness`: необов’язкове перевизначення низькорівневої політики harness для конкретного агента. Використовуйте `{ runtime: "codex", fallback: "none" }`, щоб зробити один агент лише для Codex, тоді як інші агенти збережуть типовий fallback до PI. +- `runtime`: необов’язковий дескриптор runtime для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати ACP-harness-сеанси. - `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. -- `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача ізольована, `sessions_spawn` відхиляє цілі, які запускалися б без ізоляції. -- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` з `name`/`emoji`. +- `subagents.allowAgents`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сеанс-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. +- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типове значення: false). --- -## Маршрутизація між агентами +## Маршрутизація кількох агентів -Запускайте кілька ізольованих агентів у межах одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кількох ізольованих агентів усередині одного Gateway. Див. [Кілька агентів](/uk/concepts/multi-agent). ```json5 { @@ -1853,13 +1854,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля зіставлення binding +### Поля зіставлення прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типовим є route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній `type` типово означає route), `acp` для постійних ACP-прив’язок розмов. - `match.channel` (обов’язково) - `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; специфічно для channel) +- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` **Детермінований порядок зіставлення:** @@ -1868,12 +1869,12 @@ scripts/sandbox-browser-setup.sh # optional browser image 2. `match.guildId` 3. `match.teamId` 4. `match.accountId` (точний, без peer/guild/team) -5. `match.accountId: "*"` (на рівні всього channel) +5. `match.accountId: "*"` (на рівні всього каналу) 6. Типовий агент -У межах кожного рівня перший відповідний запис `bindings` має пріоритет. +У межах кожного рівня перемагає перший запис `bindings`, що збігся. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route-binding. +Для записів `type: "acp"` OpenClaw визначає збіг за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route-прив’язок. ### Профілі доступу для окремих агентів @@ -1895,7 +1896,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1970,11 +1971,11 @@ scripts/sandbox-browser-setup.sh # optional browser image -Подробиці пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Sandbox і інструменти для кількох агентів](/uk/tools/multi-agent-sandbox-tools). --- -## Сесія +## Сеанс ```json5 { @@ -2021,43 +2022,43 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. - - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту channel. - - `global`: усі учасники в контексті channel спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`scope`**: базова стратегія групування сеансів для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують головну сесію. - - `per-peer`: ізоляція за id відправника між channels. - - `per-channel-peer`: ізоляція для кожної пари channel + відправник (рекомендовано для inbox з багатьма користувачами). - - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + channel + відправник (рекомендовано для багатообліковості). -- **`identityLinks`**: map канонічних id до peer із префіксами provider для спільного використання сесій між channels. -- **`reset`**: основна політика скидання. `daily` скидає в `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва, спрацьовує те, що завершується першим. -- **`resetByType`**: перевизначення для кожного типу (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальний `totalTokens` батьківської сесії, дозволений під час створення форкнутої сесії треду (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw запускає нову сесію треду замість успадкування історії стенограми батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти форк батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного сегмента прямого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. -- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сесій + параметри збереження. - - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: вікове обмеження для застарілих записів (типово `30d`). + - `main`: усі DM спільно використовують головний сеанс. + - `per-peer`: ізоляція за id відправника між каналами. + - `per-channel-peer`: ізоляція для кожної пари канал + відправник (рекомендовано для багатокористувацьких inbox). + - `per-account-channel-peer`: ізоляція для кожної пари обліковий запис + канал + відправник (рекомендовано для кількох облікових записів). +- **`identityLinks`**: мапа канонічних id до peer із префіксом постачальника для спільного використання сеансів між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, перемагає той, що спливає раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як alias для `direct`. +- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу гілки (типово `100000`). + - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс гілки замість успадкування історії стенограми батьківського сеансу. + - Установіть `0`, щоб вимкнути цей запобіжник і завжди дозволяти розгалуження від батьківського сеансу. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного кошика прямого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість ходів відповіді назад між агентами під час обмінів агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжки ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим alias `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: керування очищенням сховища сеансів і політикою зберігання. + - `mode`: `warn` лише генерує попередження; `enforce` застосовує очищення. + - `pruneAfter`: вікова межа для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: строк збереження архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. - - `maxDiskBytes`: необов’язковий жорсткий бюджет диска для каталогу сесій. У режимі `warn` лише записує попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сесії. - - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово `80%` від `maxDiskBytes`. -- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до тредів. - - `enabled`: головний типовий перемикач (provider можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; provider можуть перевизначати) - - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; provider можуть перевизначати) + - `resetArchiveRetention`: строк зберігання архівів стенограм `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` це логуватиме попередження; у режимі `enforce` спочатку видалятимуться найстаріші артефакти/сеанси. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до гілок. + - `enabled`: головний типовий перемикач (постачальники можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) + - `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; постачальники можуть перевизначати) + - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; постачальники можуть перевизначати) --- -## Messages +## Повідомлення ```json5 { @@ -2089,38 +2090,38 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для окремого channel/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок розв’язання (найспецифічніше має пріоритет): обліковий запис → channel → глобальне. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскадування. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ----------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва provider | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва ідентичності агента | (те саме, що `"auto"`) | +| Змінна | Опис | Приклад | +| ---------------- | ---------------------- | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | +| `{provider}` | Назва постачальника | `anthropic` | +| `{thinkingLevel}`| Поточний рівень thinking | `high`, `low`, `off` | +| `{identity.name}`| Назва ідентичності агента | (те саме, що `"auto"`) | -Змінні не залежать від регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` — alias для `{thinkingLevel}`. ### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для окремого channel: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок розв’язання: обліковий запис → channel → `messages.ackReaction` → резервне значення identity. +- Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. - Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord незадане значення зберігає реакції статусу ввімкненими, коли активні реакції підтвердження. - У Telegram задайте його явно як `true`, щоб увімкнути реакції статусу життєвого циклу. +- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. +- `messages.statusReactions.enabled`: вмикає реакції стану життєвого циклу у Slack, Discord і Telegram. + У Slack і Discord, якщо не задано, реакції стану залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram задайте це явно як `true`, щоб увімкнути реакції стану життєвого циклу. -### Вхідний debounce +### Debounce для вхідних повідомлень -Об’єднує швидкі текстові повідомлення від одного й того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Об’єднує швидкі послідовні повідомлення лише з текстом від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. -### TTS (перетворення тексту на мовлення) +### TTS (синтез мовлення) ```json5 { @@ -2161,12 +2162,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує ефективний стан. +- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). -- API keys резервно беруться з `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. -- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок розв’язання: config, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw трактує його як OpenAI-сумісний сервер TTS і послаблює перевірку model/voice. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібне явне ввімкнення). +- API keys використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` та `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює перевірку model/voice. --- @@ -2196,51 +2197,51 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька provider Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються в `talk.providers.`. -- ID голосів резервно беруться з `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. -- `providers.*.apiKey` приймає plaintext-рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API key Talk. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні імена. -- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після мовчання користувача, перш ніж надсилати стенограму. Якщо значення не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). +- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кількох постачальників Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) використовуються лише для сумісності й автоматично мігруються в `talk.providers.`. +- Voice ID використовують резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає прості текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано жодного API key для Talk. +- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. +- `silenceTimeoutMs` керує тим, скільки режим Talk чекає після тиші користувача перед надсиланням стенограми. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- -## Tools +## Інструменти -### Профілі tool +### Профілі інструментів -`tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: +`tools.profile` задає базовий список дозволених інструментів перед `tools.allow`/`tools.deny`: -Локальний onboarding типово встановлює в нових локальних config `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово задає для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не встановлено (наявні явні профілі зберігаються). -| Профіль | Включає | +| Профіль | Містить | | ----------- | ------------------------------------------------------------------------------------------------------------------------------- | | `minimal` | лише `session_status` | | `coding` | `group:fs`, `group:runtime`, `group:web`, `group:sessions`, `group:memory`, `cron`, `image`, `image_generate`, `video_generate` | | `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | -| `full` | Без обмежень (те саме, що й незадане значення) | +| `full` | Без обмежень (те саме, що й без значення) | -### Групи tool +### Групи інструментів -| Група | Tools | -| ------------------ | ----------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як псевдонім для `exec`) | -| `group:fs` | `read`, `write`, `edit`, `apply_patch` | +| Група | Інструменти | +| ------------------ | ------------------------------------------------------------------------------------------------------------------------ | +| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `exec`) | +| `group:fs` | `read`, `write`, `edit`, `apply_patch` | | `group:sessions` | `sessions_list`, `sessions_history`, `sessions_send`, `sessions_spawn`, `sessions_yield`, `subagents`, `session_status` | -| `group:memory` | `memory_search`, `memory_get` | -| `group:web` | `web_search`, `x_search`, `web_fetch` | -| `group:ui` | `browser`, `canvas` | -| `group:automation` | `cron`, `gateway` | -| `group:messaging` | `message` | -| `group:nodes` | `nodes` | -| `group:agents` | `agents_list` | -| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | -| `group:openclaw` | Усі вбудовані tools (без provider Plugin) | +| `group:memory` | `memory_search`, `memory_get` | +| `group:web` | `web_search`, `x_search`, `web_fetch` | +| `group:ui` | `browser`, `canvas` | +| `group:automation` | `cron`, `gateway` | +| `group:messaging` | `message` | +| `group:nodes` | `nodes` | +| `group:agents` | `agents_list` | +| `group:media` | `image`, `image_generate`, `video_generate`, `tts` | +| `group:openclaw` | Усі вбудовані інструменти (крім Plugin постачальників) | ### `tools.allow` / `tools.deny` -Глобальна політика дозволу/заборони tool (заборона має пріоритет). Без урахування регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує шаблони `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. ```json5 { @@ -2250,7 +2251,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.byProvider` -Додатково обмежує tools для конкретних provider або моделей. Порядок: базовий профіль → профіль provider → allow/deny. +Додатково обмежує інструменти для конкретних постачальників або моделей. Порядок: базовий профіль → профіль постачальника → allow/deny. ```json5 { @@ -2266,7 +2267,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує підвищеним доступом exec поза sandbox: +Керує підвищеним доступом до exec поза sandbox: ```json5 { @@ -2282,8 +2283,8 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. -- `/elevated on|off|ask|full` зберігає стан для кожної сесії; вбудовані директиви застосовуються до одного повідомлення. +- Перевизначення для агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. +- `/elevated on|off|ask|full` зберігає стан для кожного сеансу; вбудовані директиви застосовуються до одного повідомлення. - Elevated `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2308,8 +2309,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки циклів tool **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначити глобально в `tools.loopDetection` і перевизначати для кожного агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2330,14 +2331,14 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `historySize`: максимальна історія викликів tool, що зберігається для аналізу циклів. -- `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. +- `historySize`: максимальний обсяг історії викликів інструментів, що зберігається для аналізу циклів. +- `warningThreshold`: поріг повторюваного патерна без прогресу для попереджень. - `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. - `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. -- `detectors.genericRepeat`: попереджати про повторювані виклики однакового tool/однакових args. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-tools (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати шаблони поперемінних пар без прогресу. -- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, перевірка не проходить. +- `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі polling-інструменти (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати чергування парних патернів без прогресу. +- Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2405,30 +2406,30 @@ scripts/sandbox-browser-setup.sh # optional browser image -**Запис provider** (`type: "provider"` або пропущено): +**Запис постачальника** (`type: "provider"` або пропущено): -- `provider`: id API provider (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `provider`: id API-постачальника (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) - `model`: перевизначення id моделі -- `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` +- `profile` / `preferredProfile`: вибір профілю з `auth-profiles.json` **Запис CLI** (`type: "cli"`): - `command`: виконуваний файл для запуску -- `args`: шаблонізовані args (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) +- `args`: шаблонізовані аргументи (підтримує `{{MediaPath}}`, `{{Prompt}}`, `{{MaxChars}}` тощо) **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки використовується наступний запис. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного запису. +- У разі збою використовується наступний запис. -Автентифікація provider дотримується стандартного порядку: `auth-profiles.json` → env vars → `models.providers.*.apiKey`. +Автентифікація постачальника використовує стандартний порядок: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. **Поля асинхронного завершення:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити безпосередньо в channel. Типово: `false` - (застарілий шлях пробудження сесії запитувача/доставки моделі). + і `video_generate` спочатку намагаються доставитися напряму в канал. Типове значення: `false` + (застарілий шлях пробудження сеансу запитувача/доставки моделі). @@ -2447,9 +2448,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, які сесії можуть бути ціллю для tools сесій (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, які сеанси можна націлювати через інструменти сеансів (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, породжені нею, наприклад субагенти). +Типове значення: `tree` (поточний сеанс + сеанси, породжені ним, наприклад субагенти). ```json5 { @@ -2464,11 +2465,11 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, породжені поточною сесією (субагенти). -- `agent`: будь-яка сесія, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим id агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія ізольована й `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `self`: лише ключ поточного сеансу. +- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (субагенти). +- `agent`: будь-який сеанс, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сеанси для кожного відправника в межах того самого id агента). +- `all`: будь-який сеанс. Націлювання між агентами все одно потребує `tools.agentToAgent`. +- Обмеження sandbox: коли поточний сеанс працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` @@ -2492,18 +2493,18 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP відхиляє їх. -- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується при збереженні стенограми. -- Вхідні дані base64 перевіряються суворими перевірками алфавіту/заповнення й попередньою перевіркою розміру до декодування. +- Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. +- Файли матеріалізуються в workspace дочірнього процесу в `.openclaw/attachments//` разом із `.manifest.json`. +- Вміст вкладень автоматично редагується в збереженні стенограми. +- Входи Base64 перевіряються з використанням суворої перевірки алфавіту/відступів і запобіжника розміру до декодування. - Права доступу до файлів: `0700` для каталогів і `0600` для файлів. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. +- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Експериментальні прапорці вбудованих tools. Типово вимкнені, якщо не застосовується правило автоматичного ввімкнення strict-agentic GPT-5. +Прапорці експериментальних вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоувімкнення strict-agentic GPT-5. ```json5 { @@ -2517,9 +2518,9 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `planTool`: вмикає структурований tool `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типово: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути tool поза цим сценарієм, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. -- Коли ввімкнено, системний запит також додає вказівки щодо використання, щоб модель використовувала його лише для суттєвої роботи й тримала не більше одного кроку у стані `in_progress`. +- `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для конкретного агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. +- Коли увімкнено, системний промпт також додає інструкції з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більше одного кроку в стані `in_progress`. ### `agents.defaults.subagents` @@ -2539,16 +2540,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: типова модель для породжених субагентів. Якщо значення не задано, субагенти успадковують модель викликувача. -- `allowAgents`: типовий allowlist цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий тайм-аут (секунди) для `sessions_spawn`, коли виклик tool не задає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. -- Політика tools для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача. +- `allowAgents`: типовий список дозволених цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента пропускає `runTimeoutSeconds`. `0` означає без тайм-ауту. +- Політика інструментів для субагента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні provider і base URL +## Користувацькі постачальники та базові URL -OpenClaw використовує вбудований каталог моделей. Додавайте власні provider через `models.providers` у config або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких постачальників через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2578,50 +2579,50 @@ OpenClaw використовує вбудований каталог модел ``` - Використовуйте `authHeader: true` + `headers` для нестандартних потреб автентифікації. -- Перевизначайте корінь config агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий псевдонім змінної середовища). -- Пріоритет об’єднання для provider ID, що збігаються: - - Непорожні значення `baseUrl` в агентському `models.json` мають пріоритет. - - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей provider не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` provider, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs) замість збереження розв’язаних секретів. - - Значення заголовків provider, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env refs, `secretref-managed` для file/exec refs). - - Порожні або відсутні `apiKey`/`baseUrl` агента резервно беруться з `models.providers` у config. - - Для моделей, що збігаються, `contextWindow`/`maxTokens` використовують більше значення між явним config і неявними значеннями каталогу. - - Для моделей, що збігаються, `contextTokens` зберігає явне обмеження runtime, якщо воно присутнє; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб config повністю переписав `models.json`. - - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка config джерела (до розв’язання), а не з розв’язаних значень секретів runtime. +- Перевизначайте кореневий каталог конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). +- Пріоритет об’єднання для збігів за id постачальника: + - Непорожні значення `baseUrl` з агентського `models.json` мають пріоритет. + - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цим постачальником не керує SecretRef у поточному контексті config/auth-profile. + - Значення `apiKey` постачальника, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань) замість збереження визначених секретів. + - Значення заголовків постачальника, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-посилань, `secretref-managed` для file/exec-посилань). + - Порожні або відсутні `apiKey`/`baseUrl` агента повертаються до `models.providers` у конфігурації. + - Для збіжних моделей `contextWindow`/`maxTokens` використовується більше значення між явною конфігурацією та неявними значеннями каталогу. + - Для збіжних моделей `contextTokens` зберігається явне обмеження runtime, якщо воно задане; використовуйте це, щоб обмежити фактичний контекст без зміни нативних метаданих моделі. + - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. + - Збереження маркерів є джерельно-авторитетним: маркери записуються з активного знімка конфігурації джерела (до визначення значень), а не з визначених значень секретів у runtime. -### Подробиці полів provider +### Подробиці полів постачальника -- `models.mode`: поведінка каталогу provider (`merge` або `replace`). -- `models.providers`: власна map provider, ключована за id provider. - - Безпечні зміни: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відхиляє руйнівні заміни, якщо ви не передасте `--replace`. +- `models.mode`: поведінка каталогу постачальників (`merge` або `replace`). +- `models.providers`: мапа користувацьких постачальників із ключем provider id. + - Безпечне редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для адитивних оновлень. `config set` відмовляє в руйнівних замінах, якщо не передати `--replace`. - `models.providers.*.api`: адаптер запитів (`openai-completions`, `openai-responses`, `anthropic-messages`, `google-generative-ai` тощо). -- `models.providers.*.apiKey`: облікові дані provider (надавайте перевагу SecretRef/env substitution). +- `models.providers.*.apiKey`: облікові дані постачальника (надавайте перевагу SecretRef/env substitution). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions`, додає `options.num_ctx` до запитів (типово: `true`). +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вбудовує `options.num_ctx` у запити (типово: `true`). - `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL API верхнього рівня. +- `models.providers.*.baseUrl`: базовий URL висхідного API. - `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів model-provider. - - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями provider). Значення приймають SecretRef. - - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію provider), `"authorization-bearer"` (разом із `token`), `"header"` (разом із `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати env vars `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (разом із `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. +- `models.providers.*.request`: транспортні перевизначення для HTTP-запитів постачальника моделі. + - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями постачальника). Значення приймають SecretRef. + - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію постачальника), `"authorization-bearer"` (з `token`), `"header"` (з `headerName`, `value`, необов’язковим `prefix`). + - `request.proxy`: перевизначення HTTP-проксі. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (з `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. - `request.tls`: перевизначення TLS для прямих з’єднань. Поля: `ca`, `cert`, `key`, `passphrase` (усі приймають SecretRef), `serverName`, `insecureSkipVerify`. - - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS розв’язується в приватні, CGNAT або подібні діапазони, через захист HTTP fetch provider (opt-in оператора для довірених саморозгорнутих OpenAI-сумісних endpoint). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-захист fetch. Типово `false`. -- `models.providers.*.models`: явні записи каталогу моделей provider. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист SSRF під час HTTP-запиту постачальника (opt-in оператора для довірених self-hosted endpoint OpenAI-compatible). WebSocket використовує той самий `request` для заголовків/TLS, але не цей SSRF-запобіжник fetch. Типове значення `false`. +- `models.providers.*.models`: явні записи каталогу моделей постачальника. - `models.providers.*.models.*.contextWindow`: метадані нативного контекстного вікна моделі. -- `models.providers.*.models.*.contextTokens`: необов’язкове обмеження контексту runtime. Використовуйте це, коли хочете мати менший ефективний бюджет контексту, ніж нативний `contextWindow` моделі. -- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` із непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/пропущений `baseUrl` зберігає типову поведінку OpenAI. -- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-сумісних chat-endpoint, що підтримують лише рядки. Коли `true`, OpenClaw перетворює масиви `messages[].content`, які містять лише текст, у звичайні рядки перед надсиланням запиту. -- `plugins.entries.amazon-bedrock.config.discovery`: корінь параметрів авто-виявлення Bedrock. +- `models.providers.*.models.*.contextTokens`: необов’язкове runtime-обмеження контексту. Використовуйте це, коли хочете менший фактичний бюджет контексту, ніж нативне `contextWindow` моделі. +- `models.providers.*.models.*.compat.supportsDeveloperRole`: необов’язкова підказка сумісності. Для `api: "openai-completions"` з непорожнім ненативним `baseUrl` (хост не `api.openai.com`) OpenClaw примусово встановлює це в `false` під час runtime. Порожній/відсутній `baseUrl` зберігає типову поведінку OpenAI. +- `models.providers.*.models.*.compat.requiresStringContent`: необов’язкова підказка сумісності для OpenAI-compatible chat endpoint, які підтримують лише рядки. Коли `true`, OpenClaw сплющує масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. +- `plugins.entries.amazon-bedrock.config.discovery`: корінь налаштувань автоматичного виявлення Bedrock. - `plugins.entries.amazon-bedrock.config.discovery.enabled`: увімкнути/вимкнути неявне виявлення. - `plugins.entries.amazon-bedrock.config.discovery.region`: регіон AWS для виявлення. - `plugins.entries.amazon-bedrock.config.discovery.providerFilter`: необов’язковий фільтр provider-id для цільового виявлення. - `plugins.entries.amazon-bedrock.config.discovery.refreshInterval`: інтервал опитування для оновлення виявлення. -- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне контекстне вікно для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне context window для виявлених моделей. - `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. -### Приклади provider +### Приклади постачальників @@ -2674,7 +2675,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. +Задайте `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте посилання `opencode/...` для каталогу Zen або посилання `opencode-go/...` для каталогу Go. Скорочення: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go`. @@ -2691,11 +2692,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні псевдоніми. Скорочення: `openclaw onboard --auth-choice zai-api-key`. +Задайте `ZAI_API_KEY`. `z.ai/*` і `z-ai/*` — прийнятні alias. Скорочення: `openclaw onboard --auth-choice zai-api-key`. - Загальний endpoint: `https://api.z.ai/api/paas/v4` - Endpoint для кодування (типовий): `https://api.z.ai/api/coding/paas/v4` -- Для загального endpoint визначте власний provider із перевизначенням base URL. +- Для загального endpoint визначте користувацького постачальника з перевизначенням base URL. @@ -2734,11 +2735,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Для endpoint Китаю: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. +Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному -транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, -а не лише до вбудованого id provider. +Нативні endpoint Moonshot оголошують сумісність зі streaming usage на спільному +транспорті `openai-completions`, і OpenClaw орієнтується на можливості endpoint +а не лише на вбудований provider id. @@ -2756,11 +2757,11 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-сумісний, вбудований provider. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований постачальник. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. - + ```json5 { @@ -2799,7 +2800,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й - + ```json5 { @@ -2835,20 +2836,20 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -Установіть `MINIMAX_API_KEY`. Скорочення: +Задайте `MINIMAX_API_KEY`. Скорочення: `openclaw onboard --auth-choice minimax-global-api` або `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. -На Anthropic-сумісному шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, -якщо ви явно самі не встановите `thinking`. `/fast on` або -`params.fastMode: true` переписує `MiniMax-M2.7` на +На Anthropic-compatible streaming path OpenClaw типово вимикає thinking для MiniMax, +якщо ви явно не задасте `thinking` самостійно. `/fast on` або +`params.fastMode: true` переписує `MiniMax-M2.7` у `MiniMax-M2.7-highspeed`. -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте об’єднаними хостингові моделі для резервного варіанта. +Див. [Локальні моделі](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; залишайте hosted моделі об’єднаними для резервного переходу. @@ -2879,14 +2880,14 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані Skills/Skills workspace не зачіпаються). +- `allowBundled`: необов’язковий список дозволених лише для bundled Skills (керовані/workspace Skills не зачіпаються). - `load.extraDirs`: додаткові спільні корені Skills (найнижчий пріоритет). -- `install.preferBrew`: коли `true`, віддавати перевагу інсталяторам Homebrew, якщо `brew` - доступний, перш ніж переходити до інших типів інсталяторів. -- `install.nodeManager`: пріоритетний менеджер Node для специфікацій `metadata.openclaw.install` +- `install.preferBrew`: коли true, надавати перевагу інсталяторам Homebrew, якщо `brew` + доступний, перед поверненням до інших типів інсталяторів. +- `install.nodeManager`: пріоритет менеджера Node для специфікацій `metadata.openclaw.install` (`npm` | `pnpm` | `yarn` | `bun`). - `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. -- `entries..apiKey`: зручне поле для Skills, що оголошують основну env-змінну (plaintext-рядок або об’єкт SecretRef). +- `entries..apiKey`: зручне поле для Skills, які оголошують основну env-змінну (простий текстовий рядок або об’єкт SecretRef). --- @@ -2915,40 +2916,40 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugins OpenClaw, а також сумісні бандли Codex і Claude, включно з безманіфестними бандлами Claude стандартної структури. -- **Зміни config вимагають перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugins). `deny` має пріоритет. +- Виявлення приймає нативні Plugins OpenClaw, а також сумісні пакунки Codex і Claude, включно з безманіфестними пакунками Claude зі стандартною структурою. +- **Зміни конфігурації потребують перезапуску Gateway.** +- `allow`: необов’язковий список дозволених (завантажуються лише вказані Plugins). `deny` має пріоритет. - `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: map env-змінних в області Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля, що змінюють запит, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих бандлом. -- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків фонових субагентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо ви навмисно хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт config, визначений Plugin (перевіряється нативною схемою Plugin OpenClaw, якщо вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: параметри provider web-fetch Firecrawl. - - `apiKey`: API key Firecrawl (приймає SecretRef). Резервно береться з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env var `FIRECRAWL_API_KEY`. +- `plugins.entries..env`: мапа env-змінних у межах Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля, що змінюють промпт, зі застарілого `before_agent_start`, зберігаючи водночас застарілі `modelOverride` і `providerOverride`. Застосовується до нативних hook Plugin і підтримуваних каталогів hook, наданих пакунками. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для кожного запуску фонових субагентів. +- `plugins.entries..subagent.allowedModels`: необов’язковий список дозволених канонічних цілей `provider/model` для довірених перевизначень субагентів. Використовуйте `"*"`, лише якщо свідомо хочете дозволити будь-яку модель. +- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (валідується схемою нативного Plugin OpenClaw, коли вона доступна). +- `plugins.entries.firecrawl.config.webFetch`: налаштування постачальника web-fetch Firecrawl. + - `apiKey`: API key Firecrawl (приймає SecretRef). Використовує резервне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: тайм-аут запиту на сканування в секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: параметри xAI X Search (вебпошук Grok). - - `enabled`: увімкнути provider X Search. + - `timeoutSeconds`: тайм-аут запиту скрапінгу в секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (вебпошук Grok). + - `enabled`: увімкнути постачальника X Search. - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: параметри memory Dreaming. Див. [Dreaming](/uk/concepts/dreaming) для фаз і порогів. - - `enabled`: головний перемикач Dreaming (типово `false`). - - `frequency`: інтервал Cron для кожного повного циклу Dreaming (типово `"0 3 * * *"`). - - політика фаз і пороги — це деталі реалізації (не ключі config для користувача). -- Повний config memory наведено в [Довідці з config пам’яті](/uk/reference/memory-config): +- `plugins.entries.memory-core.config.dreaming`: налаштування dreaming пам’яті. Деталі фаз і порогів див. у [Dreaming](/uk/concepts/dreaming). + - `enabled`: головний перемикач dreaming (типово `false`). + - `frequency`: Cron-частота для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). +- Повна конфігурація пам’яті міститься в [Довідник конфігурації пам’яті](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені бандл-Plugins Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як очищені налаштування агента, а не як сирі патчі config OpenClaw. -- `plugins.slots.memory`: вибрати id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugins пам’яті. -- `plugins.slots.contextEngine`: вибрати id активного Plugin механізму контексту; типово `"legacy"`, якщо ви не встановили та не вибрали інший механізм. -- `plugins.installs`: метадані встановлення, керовані CLI, які використовує `openclaw plugins update`. +- Увімкнені Plugins-пакунки Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі патчі конфігурації OpenClaw. +- `plugins.slots.memory`: виберіть id активного Plugin пам’яті або `"none"`, щоб вимкнути Plugins пам’яті. +- `plugins.slots.contextEngine`: виберіть id активного Plugin рушія контексту; типово `"legacy"`, якщо ви не встановили й не вибрали інший рушій. +- `plugins.installs`: керовані CLI метадані інсталяції, які використовує `openclaw plugins update`. - Містить `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Сприймайте `plugins.installs.*` як керований стан; віддавайте перевагу командам CLI, а не ручним змінам. + - Вважайте `plugins.installs.*` керованим станом; надавайте перевагу командам CLI замість ручного редагування. Див. [Plugins](/uk/tools/plugin). @@ -2991,29 +2992,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація browser типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви навмисно довіряєте навігації browser у приватній мережі. -- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок доступності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий псевдонім. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація Browser типово залишається суворою. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли свідомо довіряєте навігації Browser у приватній мережі. +- У суворому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок досяжності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` усе ще підтримується як застарілий alias. - У суворому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. -- Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). +- Віддалені профілі є attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш provider дає вам прямий URL DevTools WebSocket. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися - на вибраному хості або через підключений browser Node. + Використовуйте HTTP(S), коли хочете, щоб OpenClaw визначав `/json/version`; використовуйте WS(S), + коли ваш постачальник надає прямий URL DevTools WebSocket. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть підключатися на + вибраному хості або через підключений вузол browser. - Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний - профіль browser на базі Chromium, наприклад Brave або Edge. + профіль Chromium-браузера, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання за CSS-селекторами, hooks - завантаження одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Керовані локальні профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно + дії на основі snapshot/ref замість націлювання CSS-селекторами, хуки + завантаження одного файла, без перевизначення тайм-аутів діалогів, без `wait --load networkidle`, + а також без `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. +- Для локально керованих профілів `openclaw` `cdpPort` і `cdpUrl` призначаються автоматично; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок авто-виявлення: browser за замовчуванням, якщо він на базі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Служба керування: лише loopback (порт похідний від `gateway.port`, типово `18791`). +- Порядок автовиявлення: типовий браузер, якщо на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише local loopback (порт визначається з `gateway.port`, типово `18791`). - `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, розмір вікна або прапорці налагодження). + `--disable-gpu`, розміри вікна або debug-прапорці). --- @@ -3031,8 +3032,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки режиму Talk тощо). -- `assistant`: перевизначення ідентичності Control UI. Резервно береться з ідентичності активного агента. +- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки режиму Talk тощо). +- `assistant`: перевизначення ідентичності UI керування. Якщо не задано, використовується ідентичність активного агента. --- @@ -3101,64 +3102,64 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -- `mode`: `local` (запустити gateway) або `remote` (підключитися до віддаленого gateway). Gateway відмовляється запускатися, якщо не встановлено `local`. -- `port`: єдиний мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. -- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише IP Tailscale) або `custom`. -- **Застарілі псевдоніми bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не псевдоніми хостів (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). -- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` усередині контейнера. При bridge-мережі Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host`, або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Binds, що не є loopback, вимагають auth gateway. На практиці це означає спільний токен/пароль або reverse proxy з контролем ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер onboarding типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Під час запуску й у потоках встановлення/відновлення служби виникає помилка, якщо налаштовано обидва значення, а режим не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних налаштувань local loopback; цей варіант навмисно не пропонується в підказках onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегує auth reverse proxy з контролем ідентичності й довіряє заголовкам ідентичності з `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy loopback на тому самому хості не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). Endpoint HTTP API **не** використовують цю auth через заголовки Tailscale; натомість вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується для кожного IP клієнта і для кожної області auth (спільний секрет і токен пристрою відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Control UI Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні погані спроби від того самого клієнта можуть спрацювати на лімітатор на другому запиті замість того, щоб обидві просто проскочили як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли ви навмисно хочете лімітувати трафік localhost теж (для тестових конфігурацій або суворих розгортань із proxy). -- Спроби WS auth із походження browser завжди обмежуються без винятку для loopback (додатковий захист від brute force localhost із browser). -- На loopback ці блокування для browser-origin ізолюються для кожного нормалізованого - значення `Origin`, тому повторні невдачі з одного localhost origin не - блокують автоматично інше origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічний, вимагає auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень WebSocket до Gateway. Обов’язковий, коли очікуються клієнти browser з origin, що не є loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає резервний варіант origin на основі заголовка Host для розгортань, які навмисно покладаються на політику origin на основі Host-header. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське аварійне перевизначення, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; за замовчуванням plaintext і далі дозволений лише для loopback. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього relay APNs, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у gateway. Цей URL має збігатися з URL relay, вбудованим у збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання від gateway до relay у мілісекундах. Типово `10000`. -- Реєстрації relay-backed делегуються конкретній ідентичності gateway. Спарений застосунок iOS отримує `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і пересилає gateway дозвіл на надсилання в межах цієї реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для вказаного вище config relay. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: аварійний варіант лише для розробки для loopback HTTP relay URL. URL relay для продакшену мають залишатися на HTTPS. -- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я channel у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. -- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета у хвилинах. Тримайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. -- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor для кожного channel/account за ковзну годину. Типово: `10`. -- `channels..healthMonitor.enabled`: відмова від перезапусків health-monitor для окремого channel при збереженні глобального монітора ввімкненим. -- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових channels. Якщо задано, воно має пріоритет над перевизначенням на рівні channel. -- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. -- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і воно не розв’язується, розв’язання завершується за принципом fail-closed (без маскування резервним remote). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки пересланого клієнта. Вказуйте лише proxy, якими ви керуєте. Записи loopback і далі валідні для конфігурацій proxy/локального виявлення на тому самому хості (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. -- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо `X-Forwarded-For` відсутній. Типово `false` для поведінки fail-closed. -- `gateway.tools.deny`: додаткові назви tools, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). -- `gateway.tools.allow`: прибирає назви tools з типового deny list HTTP. +- `mode`: `local` (запустити gateway) або `remote` (під’єднатися до віддаленого gateway). Gateway відмовляється запускатися, якщо не `local`. +- `port`: один мультиплексований порт для WS + HTTP. Пріоритет: `--port` > `OPENCLAW_GATEWAY_PORT` > `gateway.port` > `18789`. +- `bind`: `auto`, `loopback` (типово), `lan` (`0.0.0.0`), `tailnet` (лише Tailscale IP) або `custom`. +- **Застарілі alias bind**: використовуйте значення режиму bind у `gateway.bind` (`auto`, `loopback`, `lan`, `tailnet`, `custom`), а не alias хоста (`0.0.0.0`, `127.0.0.1`, `localhost`, `::`, `::1`). +- **Примітка щодо Docker**: типовий bind `loopback` слухає `127.0.0.1` всередині контейнера. При використанні bridge-мережі Docker (`-p 18789:18789`) трафік надходить через `eth0`, тому gateway недосяжний. Використовуйте `--network host` або задайте `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. +- **Auth**: типово обов’язкова. Bind-и не на loopback вимагають автентифікації gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Майстер онбордингу типово генерує token. +- Якщо налаштовані і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), задайте `gateway.auth.mode` явно як `token` або `password`. Потоки запуску та встановлення/відновлення сервісу завершуються помилкою, якщо налаштовано обидва, а mode не задано. +- `gateway.auth.mode: "none"`: явний режим без автентифікації. Використовуйте лише для довірених локальних local loopback-конфігурацій; цей варіант навмисно не пропонується в запитах онбордингу. +- `gateway.auth.mode: "trusted-proxy"`: делегувати автентифікацію reverse proxy з урахуванням ідентичності та довіряти заголовкам ідентичності від `gateway.trustedProxies` (див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело проксі; reverse proxy на loopback на тому ж хості не задовольняють вимоги trusted-proxy auth. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію UI керування/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint-и **не** використовують цю автентифікацію через заголовки Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей безтокеновий потік припускає, що хост gateway є довіреним. Типово `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий лімітатор невдалих спроб auth. Застосовується для кожного IP клієнта та для кожної області auth окремо (спільний секрет і токен пристрою відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху UI керування Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом невдачі. Тому одночасні невдалі спроби від того самого клієнта можуть спрацювати на ліміті вже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, якщо навмисно хочете також обмежувати localhost-трафік (для тестових конфігурацій або строгих проксі-розгортань). +- Спроби WS auth з походження browser завжди обмежуються без винятку для loopback (додатковий захист від browser-based brute force на localhost). +- На loopback ці блокування для browser-origin ізольовані за нормалізованим значенням `Origin`, + тож повторні збої з одного localhost-origin не призводять автоматично + до блокування іншого origin. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, вимагає auth). +- `controlUi.allowedOrigins`: явний список дозволених browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються browser-клієнти не з loopback-origin. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає fallback походження за заголовком Host для розгортань, що навмисно покладаються на політику походження за заголовком Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське break-glass-перевизначення, яке дозволяє plaintext `ws://` до довірених IP приватної мережі; типово plaintext і далі дозволено лише для loopback. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують auth gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після того, як вони публікують зареєстровані через relay об’єкти в gateway. Цей URL має відповідати URL relay, зібраному в iOS-збірку. +- `gateway.push.apns.relay.timeoutMs`: тайм-аут надсилання gateway-to-relay у мілісекундах. Типове значення `10000`. +- Реєстрації, що працюють через relay, делегуються конкретній ідентичності gateway. Спарений застосунок iOS викликає `gateway.identity.get`, включає цю ідентичність у реєстрацію relay і передає gateway дозвіл на надсилання в межах реєстрації. Інший gateway не може повторно використати цю збережену реєстрацію. +- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові env-перевизначення для наведеної вище конфігурації relay. +- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: резервний варіант лише для розробки для loopback HTTP relay URL. Production relay URL мають залишатися на HTTPS. +- `gateway.channelHealthCheckMinutes`: інтервал моніторингу здоров’я каналів у хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health monitor. Типове значення: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Залишайте його більшим або рівним `gateway.channelHealthCheckMinutes`. Типове значення: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health monitor на канал/обліковий запис у ковзній годині. Типове значення: `10`. +- `channels..healthMonitor.enabled`: opt-out для конкретного каналу від перезапусків health monitor із збереженням увімкненого глобального монітора. +- `channels..accounts..healthMonitor.enabled`: перевизначення для конкретного облікового запису в каналах із кількома обліковими записами. Якщо задано, має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи викликів gateway можуть використовувати `gateway.remote.*` як резервний варіант лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовані через SecretRef і не визначаються, визначення завершується з відмовою за замовчуванням (без маскування через резервний remote fallback). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки перенаправленого клієнта. Вказуйте лише проксі, якими ви керуєте. Записи loopback усе ще дійсні для конфігурацій same-host proxy/local-detection (наприклад Tailscale Serve або локальний reverse proxy), але вони **не** роблять loopback-запити придатними для `gateway.auth.mode: "trusted-proxy"`. +- `allowRealIpFallback`: коли `true`, gateway приймає `X-Real-IP`, якщо відсутній `X-Forwarded-For`. Типове значення `false` для fail-closed-поведінки. +- `gateway.tools.deny`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий список заборон). +- `gateway.tools.allow`: видаляє назви інструментів із типового HTTP-списку заборон. -### OpenAI-сумісні endpoint +### OpenAI-compatible endpoint-и - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Посилене захист URL-входу Responses: +- Захист Responses для URL-входів: - `gateway.http.endpoints.responses.maxUrlParts` - `gateway.http.endpoints.responses.files.urlAllowlist` - `gateway.http.endpoints.responses.images.urlAllowlist` - Порожні allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` - та/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. -- Необов’язковий заголовок посиленого захисту відповіді: - - `gateway.http.securityHeaders.strictTransportSecurity` (установлюйте лише для HTTPS-origin, якими ви керуєте; див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) + Порожні списки allowlist трактуються як незадані; використовуйте `gateway.http.endpoints.responses.files.allowUrl=false` + і/або `gateway.http.endpoints.responses.images.allowUrl=false`, щоб вимкнути отримання URL. +- Необов’язковий заголовок захисту відповіді: + - `gateway.http.securityHeaders.strictTransportSecurity` (задавайте лише для HTTPS-origin, якими ви керуєте; див. [Автентифікація через довірений проксі](/uk/gateway/trusted-proxy-auth#tls-termination-and-hsts)) -### Ізоляція кількох екземплярів +### Ізоляція кількох інстансів -Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3168,7 +3169,7 @@ openclaw gateway --port 19001 Зручні прапорці: `--dev` (використовує `~/.openclaw-dev` + порт `19001`), `--profile ` (використовує `~/.openclaw-`). -Див. [Multiple Gateways](/uk/gateway/multiple-gateways). +Див. [Кілька Gateway](/uk/gateway/multiple-gateways). ### `gateway.tls` @@ -3186,11 +3187,11 @@ openclaw gateway --port 19001 } ``` -- `enabled`: вмикає завершення TLS на listener gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/development використання. -- `certPath`: шлях файлової системи до файла сертифіката TLS. -- `keyPath`: шлях файлової системи до файла приватного ключа TLS; обмежуйте права доступу. -- `caPath`: необов’язковий шлях до набору CA для перевірки клієнта або власних ланцюжків довіри. +- `enabled`: вмикає TLS-термінацію на слухачі gateway (HTTPS/WSS) (типово: `false`). +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовані; лише для локального/dev використання. +- `certPath`: шлях файлової системи до файла TLS-сертифіката. +- `keyPath`: шлях файлової системи до файла приватного TLS-ключа; обмежуйте права доступу. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або власних ланцюгів довіри. ### `gateway.reload` @@ -3206,12 +3207,12 @@ openclaw gateway --port 19001 } ``` -- `mode`: керує тим, як зміни config застосовуються під час runtime. - - `"off"`: ігнорувати живі зміни; потрібен явний перезапуск. - - `"restart"`: завжди перезапускати процес gateway при зміні config. - - `"hot"`: застосовувати зміни в поточному процесі без перезапуску. - - `"hybrid"` (типово): спочатку спробувати hot reload; якщо потрібно, перейти до перезапуску. -- `debounceMs`: вікно debounce в мс перед застосуванням змін config (невід’ємне ціле число). +- `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. + - `"off"`: ігнорувати live-edit; зміни вимагають явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. + - `"hot"`: застосовувати зміни в процесі без перезапуску. + - `"hybrid"` (типово): спочатку пробувати hot reload; за потреби повертатися до перезапуску. +- `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). - `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3250,46 +3251,46 @@ openclaw gateway --port 19001 ``` Auth: `Authorization: Bearer ` або `x-openclaw-token: `. -Токени hook у query-string відхиляються. +Токени hook у рядку запиту відхиляються. -Примітки щодо перевірки та безпеки: +Примітки щодо валідації та безпеки: - `hooks.enabled=true` вимагає непорожній `hooks.token`. -- `hooks.token` має **відрізнятися** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. +- `hooks.token` має бути **відмінним** від `gateway.auth.token`; повторне використання токена Gateway відхиляється. - `hooks.path` не може бути `/`; використовуйте окремий підшлях, наприклад `/hooks`. -- Якщо `hooks.allowRequestSessionKey=true`, обмежте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). -- Якщо mapping або preset використовує шаблонізований `sessionKey`, установіть `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не вимагають цього opt-in. +- Якщо `hooks.allowRequestSessionKey=true`, обмежуйте `hooks.allowedSessionKeyPrefixes` (наприклад `["hook:"]`). +- Якщо mapping або preset використовує шаблонізований `sessionKey`, задайте `hooks.allowedSessionKeyPrefixes` і `hooks.allowRequestSessionKey=true`. Статичні ключі mapping не потребують цього opt-in. -**Endpoint:** +**Endpoint-и:** - `POST /hooks/wake` → `{ text, mode?: "now"|"next-heartbeat" }` - `POST /hooks/agent` → `{ message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }` - - `sessionKey` з корисного навантаження запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). -- `POST /hooks/` → розв’язується через `hooks.mappings` - - Значення `sessionKey` mapping, відрендерені шаблоном, вважаються наданими ззовні й також вимагають `hooks.allowRequestSessionKey=true`. + - `sessionKey` з payload запиту приймається лише коли `hooks.allowRequestSessionKey=true` (типово: `false`). +- `POST /hooks/` → визначається через `hooks.mappings` + - Значення `sessionKey` у mapping, згенеровані з шаблону, вважаються зовнішньо переданими і також потребують `hooks.allowRequestSessionKey=true`. -- `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). -- `match.source` відповідає полю корисного навантаження для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` читають значення з корисного навантаження. +- `match.path` зіставляє підшлях після `/hooks` (наприклад `/hooks/gmail` → `gmail`). +- `match.source` зіставляє поле payload для загальних шляхів. +- Шаблони на кшталт `{{messages[0].subject}}` читають значення з payload. - `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи й traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID резервно переходять до типового. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити все, `[]` = заборонити все). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволяє викликувачам `/hooks/agent` і ключам сесії mapping, керованим шаблонами, задавати `sessionKey` (типово: `false`). -- `allowedSessionKeyPrefixes`: необов’язковий allowlist префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. -- `deliver: true` надсилає фінальну відповідь у channel; `channel` типово має значення `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо каталог моделей задано). + - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та вихід за межі каталогу відхиляються). +- `agentId` маршрутизує до конкретного агента; невідомі ID повертаються до типового агента. +- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або пропущено = дозволити всі, `[]` = заборонити всі). +- `defaultSessionKey`: необов’язковий фіксований ключ сеансу для запусків hook-агента без явного `sessionKey`. +- `allowRequestSessionKey`: дозволяє викликачам `/hooks/agent` і session key у mapping, що керуються шаблонами, задавати `sessionKey` (типово: `false`). +- `allowedSessionKeyPrefixes`: необов’язковий список дозволених префіксів для явних значень `sessionKey` (запит + mapping), наприклад `["hook:"]`. Він стає обов’язковим, коли будь-який mapping або preset використовує шаблонізований `sessionKey`. +- `deliver: true` надсилає фінальну відповідь у канал; `channel` типово дорівнює `last`. +- `model` перевизначає LLM для цього запуску hook (має бути дозволеною, якщо задано каталог моделей). ### Інтеграція Gmail - Вбудований preset Gmail використовує `sessionKey: "hook:gmail:{{messages[0].id}}"`. -- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, установіть `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes`, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. -- Якщо вам потрібно `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. +- Якщо ви зберігаєте цю маршрутизацію для кожного повідомлення, задайте `hooks.allowRequestSessionKey: true` і обмежте `hooks.allowedSessionKeyPrefixes` так, щоб вони відповідали простору імен Gmail, наприклад `["hook:", "hook:gmail:"]`. +- Якщо вам потрібне `hooks.allowRequestSessionKey: false`, перевизначте preset статичним `sessionKey` замість типового шаблонізованого. ```json5 { @@ -3329,17 +3330,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Обслуговує HTML/CSS/JS, які може редагувати агент, і A2UI через HTTP на порту Gateway: +- Обслуговує HTML/CSS/JS та A2UI, які може редагувати агент, через HTTP на порту Gateway: - `http://:/__openclaw__/canvas/` - `http://:/__openclaw__/a2ui/` -- Лише локально: зберігайте `gateway.bind: "loopback"` (типово). -- Для bind, що не є loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- WebView Node зазвичай не надсилають заголовки auth; після спарювання й підключення Node Gateway рекламує URL можливостей у межах Node для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії Node і швидко спливають. Резервний варіант на основі IP не використовується. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для bind не на loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebView зазвичай не надсилають заголовки auth; після сполучення та підключення вузла Gateway рекламує URL можливостей, прив’язані до вузла, для доступу до canvas/A2UI. +- URL можливостей прив’язані до активного WS-сеансу вузла та швидко спливають. Резервний варіант на основі IP не використовується. - Вбудовує клієнт live-reload у HTML, що обслуговується. -- Автоматично створює початковий `index.html`, коли каталог порожній. -- Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни вимагають перезапуску gateway. +- Автоматично створює початковий `index.html`, якщо каталог порожній. +- Також обслуговує A2UI на `/__openclaw__/a2ui/`. +- Зміни потребують перезапуску gateway. - Вимикайте live reload для великих каталогів або при помилках `EMFILE`. --- @@ -3358,11 +3359,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `minimal` (типово): не включає `cliPath` + `sshPort` із TXT-записів. +- `minimal` (типово): не включає `cliPath` + `sshPort` до TXT-записів. - `full`: включає `cliPath` + `sshPort`. -- Ім’я хоста типово `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. +- Ім’я хоста типово дорівнює `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. -### Глобальне виявлення (DNS-SD) +### Wide-area (DNS-SD) ```json5 { @@ -3372,7 +3373,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. +Записує unicast-зону DNS-SD в `~/.openclaw/dns/`. Для виявлення між мережами використовуйте разом із DNS-сервером (рекомендовано CoreDNS) + Tailscale split DNS. Налаштування: `openclaw dns setup --apply`. @@ -3380,7 +3381,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані env vars) +### `env` (вбудовані env-змінні) ```json5 { @@ -3397,14 +3398,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env vars застосовуються лише тоді, коли env процесу не містить цього ключа. -- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні vars). +- Вбудовані env-змінні застосовуються лише тоді, коли у середовищі процесу відсутній цей ключ. +- Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). - `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритету див. у [Environment](/uk/help/environment). +- Повний пріоритет див. у [Середовище](/uk/help/environment). -### Підстановка env vars +### Підстановка env-змінних -Посилайтеся на env vars у будь-якому рядку config через `${VAR_NAME}`: +Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3414,8 +3415,8 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Зіставляються лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. -- Відсутні/порожні vars спричиняють помилку під час завантаження config. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -3423,31 +3424,31 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Секрети -Посилання на секрети є додатковими: plaintext-значення і далі працюють. +Посилання на секрети є адитивними: прості текстові значення теж продовжують працювати. ### `SecretRef` -Використовуйте один формат об’єкта: +Використовуйте одну форму об’єкта: ```json5 { source: "env" | "file" | "exec", provider: "default", id: "..." } ``` -Перевірка: +Валідація: - шаблон `provider`: `^[a-z][a-z0-9_-]{0,63}$` -- шаблон id для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` -- `source: "file"` id: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) -- шаблон id для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` -- `source: "exec"` id не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад `a/../b` відхиляється) +- шаблон `id` для `source: "env"`: `^[A-Z][A-Z0-9_]{0,127}$` +- `id` для `source: "file"`: абсолютний JSON pointer (наприклад `"/providers/openai/apiKey"`) +- шаблон `id` для `source: "exec"`: `^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$` +- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені `/` (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних - Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` входять до покриття runtime-розв’язання й аудиту. +- Посилання в `auth-profiles.json` включаються в визначення runtime і покриття аудиту. -### Config provider секретів +### Конфігурація постачальників секретів ```json5 { @@ -3477,14 +3478,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Provider `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue значення `id` має бути `"value"`). -- Шляхи provider `file` і `exec` працюють за принципом fail-closed, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Provider `exec` вимагає абсолютний шлях `command` і використовує корисні навантаження протоколу через stdin/stdout. -- Типово шляхи команд через символічні посилання відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання, перевіряючи при цьому розв’язаний цільовий шлях. -- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв’язаного цільового шляху. -- Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв’язуються під час активації в знімок у пам’яті, а потім шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на ввімкнених поверхнях спричиняють помилку запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. +- Постачальник `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Шляхи постачальників file і exec завершуються з відмовою за замовчуванням, коли перевірка Windows ACL недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Постачальник `exec` вимагає абсолютний шлях `command` і використовує протокольні payload через stdin/stdout. +- Типово шляхи команд-символічних посилань відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи-символічні посилання з перевіркою визначеного цільового шляху. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до визначеного цільового шляху. +- Дочірнє середовище `exec` типово є мінімальним; передавайте потрібні змінні явно через `passEnv`. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на увімкнених поверхнях призводять до помилки запуску/перезавантаження, а неактивні поверхні пропускаються з діагностикою. --- @@ -3506,13 +3507,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Профілі для окремого агента зберігаються в `/auth-profiles.json`. +- Профілі для кожного агента зберігаються в `/auth-profiles.json`. - `auth-profiles.json` підтримує посилання на рівні значень (`keyRef` для `api_key`, `tokenRef` для `token`) для статичних режимів облікових даних. -- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані auth-profile на основі SecretRef. -- Статичні облікові дані runtime беруться з розв’язаних знімків у пам’яті; застарілі статичні записи `auth.json` очищуються при виявленні. -- Застарілі імпорти OAuth беруться з `~/.openclaw/credentials/oauth.json`. +- Профілі режиму OAuth (`auth.profiles..mode = "oauth"`) не підтримують облікові дані профілів auth на основі SecretRef. +- Статичні облікові дані runtime надходять із визначених знімків у пам’яті; застарілі статичні записи `auth.json` очищуються, якщо їх виявлено. +- Застарілий імпорт OAuth виконується з `~/.openclaw/credentials/oauth.json`. - Див. [OAuth](/uk/concepts/oauth). -- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Secrets Management](/uk/gateway/secrets). +- Поведінка runtime секретів і інструменти `audit/configure/apply`: [Керування секретами](/uk/gateway/secrets). ### `auth.cooldowns` @@ -3534,20 +3535,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає помилки через справжні - billing/insufficient-credit помилки (типово: `5`). Явний текст про billing - усе ще може потрапити сюди навіть для відповідей `401`/`403`, але - текстові зіставлювачі, специфічні для provider, залишаються обмеженими provider, якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані HTTP `402` повідомлення про usage-window або - spend-limit організації/workspace натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для окремих provider. +- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні + billing/insufficient-credit помилки (типово: `5`). Явний billing-текст + усе ще може потрапити сюди навіть у відповідях `401`/`403`, але + зіставлення тексту для конкретного постачальника залишаються в межах + постачальника, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані HTTP `402` usage-window або + повідомлення про ліміти витрат organization/workspace натомість залишаються на шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин billing backoff для кожного постачальника. - `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (типово: `10`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для високовпевнених збоїв `auth_permanent` (типово: `10`). - `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). - `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного provider для помилок перевантаження перед перемиканням на fallback моделі (типово: `1`). Сюди потрапляють форми provider-busy, такі як `ModelNotReadyException`. -- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого provider/profile (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах одного provider для помилок rate-limit перед перемиканням на fallback моделі (типово: `1`). Цей кошик rate-limit включає текстові форми provider, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile того самого постачальника для помилок перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості постачальника на кшталт `ModelNotReadyException`. +- `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого постачальника/профілю (типово: `0`). +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile того самого постачальника для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей bucket rate-limit включає тексти у формі постачальника, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3566,10 +3568,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типовий файл логів: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. +- Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` при `--verbose`. -- `maxFileBytes`: максимальний розмір файла логів у байтах, після якого записи пригнічуються (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію логів. +- `consoleLevel` підвищується до `debug` з `--verbose`. +- `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію логів. --- @@ -3607,19 +3609,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід логів (підтримує шаблони на кшталт `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. +- `flags`: масив рядків-прапорців, що вмикають цільовий вивід логів (підтримуються шаблони на кшталт `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виводу попереджень про завислий сеанс, поки сеанс залишається у стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). - `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. - `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються разом із запитами експорту OTel. -- `otel.serviceName`: ім’я служби для атрибутів ресурсу. -- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або log. -- `otel.sampleRate`: частота вибірки trace `0`–`1`. -- `otel.flushIntervalMs`: періодичний інтервал скидання телеметрії в мс. -- `cacheTrace.enabled`: логувати знімки trace кешу для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для JSONL trace кешу (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). -- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід trace кешу (усі типово: `true`). +- `otel.serviceName`: назва сервісу для атрибутів ресурсу. +- `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт трас, метрик або логів. +- `otel.sampleRate`: частота семплювання трас `0`–`1`. +- `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. +- `cacheTrace.enabled`: логувати знімки cache trace для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається у вивід cache trace (усі типово: `true`). --- @@ -3641,10 +3643,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `channel`: канал релізу для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. +- `channel`: канал релізів для npm/git-інсталяцій — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). -- `auto.enabled`: увімкнути фонове автооновлення для встановлень пакета (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-каналу (типово: `6`; макс.: `168`). +- `auto.enabled`: увімкнути фонове автооновлення для package-інсталяцій (типово: `false`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням для stable-каналу (типово: `6`; макс.: `168`). - `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). - `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; макс.: `24`). @@ -3679,22 +3681,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний перемикач можливості ACP (типово: `false`). -- `dispatch.enabled`: незалежний перемикач для диспетчеризації ходів сесії ACP (типово: `true`). Установіть `false`, щоб зберегти команди ACP доступними, але заблокувати виконання. -- `backend`: id типового backend runtime ACP (має відповідати зареєстрованому Plugin runtime ACP). -- `defaultAgent`: резервний id цільового агента ACP, коли spawn не задають явну ціль. -- `allowedAgents`: allowlist id агентів, дозволених для сесій runtime ACP; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. +- `enabled`: глобальний прапорець функції ACP (типово: `false`). +- `dispatch.enabled`: незалежний прапорець для диспетчеризації ходів ACP-сеансу (типово: `true`). Установіть `false`, щоб залишити ACP-команди доступними, але заблокувати виконання. +- `backend`: id типового ACP runtime backend (має відповідати зареєстрованому Plugin ACP runtime). +- `defaultAgent`: резервний id цільового ACP-агента, коли spawn не задає явну ціль. +- `allowedAgents`: список дозволених id агентів для ACP runtime-сеансів; порожній список означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних ACP-сеансів. - `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір фрагмента перед розбиттям проєкції потокового блока. -- `stream.repeatSuppression`: пригнічувати повторювані рядки status/tool у межах ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій tool (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, спроєктованих для одного ходу ACP. -- `stream.maxSessionUpdateChars`: максимальна кількість символів для спроєктованих рядків status/update ACP. -- `stream.tagVisibility`: запис імен тегів до булевих перевизначень видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників сесії ACP до можливості очищення. -- `runtime.installCommand`: необов’язкова команда встановлення для запуску під час bootstrap середовища runtime ACP. +- `stream.maxChunkChars`: максимальний розмір chunk перед розбиттям проєкції потокового блока. +- `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів для кожного ходу (типово: `true`). +- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу assistant, що проєктується на один ACP-хід. +- `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. +- `stream.tagVisibility`: запис назв тегів у булеві перевизначення видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для робітників ACP-сеансу до моменту, коли вони стають придатними для очищення. +- `runtime.installCommand`: необов’язкова команда інсталяції, яку слід виконати під час bootstrap середовища ACP runtime. --- @@ -3714,7 +3716,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `"random"` (типово): змінні кумедні/сезонні слогани. - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - `"off"`: без тексту слогана (назва/версія банера все одно показуються). -- Щоб приховати весь банер (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- Щоб приховати весь банер (не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. --- @@ -3738,15 +3740,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Identity -Див. поля identity в `agents.list` у розділі [Значення агентів за замовчуванням](#agent-defaults). +Див. поля identity в `agents.list` у розділі [Типові значення агента](#agent-defaults). --- ## Bridge (застарілий, видалений) -Поточні збірки більше не містять TCP bridge. Nodes підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до схеми config (перевірка не проходить, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Nodes підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -3784,10 +3786,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені сесії ізольованих запусків Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типово: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла логів на запуск (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. -- `runLog.keepLines`: найновіші рядки, що зберігаються, коли запускається очищення run-log. Типово: `2000`. -- `webhookToken`: bearer token, що використовується для доставки Cron Webhook POST (`delivery.mode = "webhook"`); якщо значення пропущено, заголовок auth не надсилається. +- `sessionRetention`: скільки часу зберігати завершені ізольовані сеанси виконання Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених стенограм Cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли спрацьовує очищення журналу запуску. Типове значення: `2000`. +- `webhookToken`: bearer token, який використовується для доставлення Cron Webhook POST (`delivery.mode = "webhook"`); якщо пропущено, заголовок auth не надсилається. - `webhook`: застарілий резервний URL Webhook (http/https), що використовується лише для збережених завдань, які все ще мають `notify: true`. ### `cron.retry` @@ -3808,7 +3810,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). - `retryOn`: типи помилок, що запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати всі тимчасові типи. -Застосовується лише до одноразових завдань Cron. Повторювані завдання використовують окрему обробку помилок. +Застосовується лише до одноразових завдань Cron. Повторювані завдання використовують окрему обробку збоїв. ### `cron.failureAlert` @@ -3827,10 +3829,10 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ``` - `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацьовуванням сповіщення (додатне ціле число, мін.: `1`). +- `after`: кількість послідовних збоїв перед надсиланням сповіщення (додатне ціле число, мін.: `1`). - `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` виконує POST до налаштованого Webhook. -- `accountId`: необов’язковий id облікового запису або каналу для обмеження доставки сповіщення. +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` надсилає POST на налаштований Webhook. +- `accountId`: необов’язковий id облікового запису або каналу для визначення області доставки сповіщення. ### `cron.failureDestination` @@ -3847,51 +3849,51 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типова ціль для сповіщень про збої Cron для всіх завдань. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли є достатньо даних цілі. -- `channel`: перевизначення channel для доставки announce. `"last"` повторно використовує останній відомий channel доставки. +- Типова ціль для сповіщень про збої Cron у всіх завданнях. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли достатньо даних про ціль. +- `channel`: перевизначення каналу для announce-доставки. `"last"` повторно використовує останній відомий канал доставки. - `to`: явна ціль announce або URL Webhook. Обов’язково для режиму webhook. - `accountId`: необов’язкове перевизначення облікового запису для доставки. -- Для окремого завдання `delivery.failureDestination` перевизначає це глобальне типове значення. -- Коли не задано ні глобальну, ні для окремого завдання ціль збою, завдання, які вже доставляють через `announce`, у разі збою резервно переходять до цієї основної announce-цілі. +- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне типове значення. +- Коли не задано ні глобальну, ні для конкретного завдання ціль збою, завдання, які вже доставляють через `announce`, при збої повертаються до тієї самої основної announce-цілі. - `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). +Див. [Завдання Cron](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). --- ## Змінні шаблону моделі медіа -Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: +Шаблонні заповнювачі, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ----------------- | -------------------------------------------------- | -| `{{Body}}` | Повне тіло вхідного повідомлення | -| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | -| `{{BodyStripped}}`| Тіло без згадок у групі | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | ID повідомлення channel | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}`| `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіостенограма | -| `{{Prompt}}` | Розв’язаний prompt медіа для записів CLI | -| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}`| Тема групи (best effort) | -| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка provider (whatsapp, telegram, discord тощо) | +| Змінна | Опис | +| ----------------- | ------------------------------------------------ | +| `{{Body}}` | Повне тіло вхідного повідомлення | +| `{{RawBody}}` | Сире тіло (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Тіло без згадок групи | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор цілі | +| `{{MessageSid}}` | ID повідомлення каналу | +| `{{SessionId}}` | UUID поточного сеансу | +| `{{IsNewSession}}`| `"true"`, коли створено новий сеанс | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Аудіостенограма | +| `{{Prompt}}` | Визначений media prompt для CLI-записів | +| `{{MaxChars}}` | Визначена максимальна кількість вихідних символів для CLI-записів | +| `{{ChatType}}` | `"direct"` або `"group"` | +| `{{GroupSubject}}`| Тема групи (best effort) | +| `{{GroupMembers}}`| Попередній перегляд учасників групи (best effort)| +| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | +| `{{SenderE164}}` | Номер телефону відправника (best effort) | +| `{{Provider}}` | Підказка постачальника (whatsapp, telegram, discord тощо) | --- -## Включення config (`$include`) +## Включення конфігурації (`$include`) -Розділяйте config на кілька файлів: +Розділяйте конфігурацію на кілька файлів: ```json5 // ~/.openclaw/openclaw.json @@ -3907,14 +3909,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка об’єднання:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко об’єднується по порядку (пізніші перевизначають попередні). +- Масив файлів: глибоко об’єднується в заданому порядку (пізніші перевизначають попередні). - Сусідні ключі: об’єднуються після include (перевизначають включені значення). -- Вкладені include: до 10 рівнів вкладеності. -- Шляхи: розв’язуються відносно файла, який включає, але мають залишатися в межах каталогу config верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли після розв’язання вони все одно залишаються в межах цього кордону. -- Записи, якими керує OpenClaw і які змінюють лише один top-level розділ, забезпечений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` незмінним. -- Кореневі include, масиви include і include із сусідніми перевизначеннями є лише для читання для записів, якими керує OpenClaw; такі записи завершуються за принципом fail-closed замість сплощення config. -- Помилки: чіткі повідомлення для відсутніх файлів, помилок розбору та циклічних include. +- Вкладені include: до 10 рівнів глибини. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/форми з `../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі. +- Записи, якими керує OpenClaw, що змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` недоторканим. +- Кореневі include, масиви include та include з сусідніми перевизначеннями є лише для читання для записів, якими керує OpenClaw; такі записи завершуються з відмовою за замовчуванням замість сплощення конфігурації. +- Помилки: чіткі повідомлення для відсутніх файлів, помилок парсингу та циклічних include. --- -_Пов’язано: [Configuration](/uk/gateway/configuration) · [Configuration Examples](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ +_Пов’язане: [Конфігурація](/uk/gateway/configuration) · [Приклади конфігурації](/uk/gateway/configuration-examples) · [Doctor](/uk/gateway/doctor)_ diff --git a/docs/uk/help/faq.md b/docs/uk/help/faq.md index 6d92d9737..ce2284064 100644 --- a/docs/uk/help/faq.md +++ b/docs/uk/help/faq.md @@ -1,31 +1,31 @@ --- read_when: - Відповіді на поширені запитання щодо налаштування, встановлення, онбордингу або підтримки під час виконання - - Первинне опрацювання повідомлених користувачами проблем перед глибшим налагодженням + - Тріаж проблем, про які повідомили користувачі, перед глибшим налагодженням summary: Поширені запитання про налаштування, конфігурацію та використання OpenClaw -title: Часті запитання +title: Поширені запитання x-i18n: - generated_at: "2026-04-23T19:25:07Z" + generated_at: "2026-04-23T20:05:11Z" model: gpt-5.4 provider: openai - source_hash: e80ee4444c0bf72ecabe248fdacb9f1f8ee64db46189e37a898a9a1242185f75 + source_hash: e4bad3e6334e6a198f726dfbac1f9bd9d6a293183425216f9c10d1e553be24e4 source_path: help/faq.md workflow: 15 --- -# Часті запитання +# Поширені запитання -Швидкі відповіді та глибше усунення несправностей для реальних середовищ (локальна розробка, VPS, multi-agent, OAuth/API keys, failover моделей). Для діагностики під час виконання див. [Усунення несправностей](/uk/gateway/troubleshooting). Для повного довідника з конфігурації див. [Конфігурація](/uk/gateway/configuration). +Швидкі відповіді та глибше усунення несправностей для реальних середовищ (локальна розробка, VPS, мультиагентність, OAuth/API keys, аварійне перемикання моделей). Для діагностики під час виконання див. [Troubleshooting](/uk/gateway/troubleshooting). Повний довідник із конфігурації див. у [Configuration](/uk/gateway/configuration). ## Перші 60 секунд, якщо щось зламалося -1. **Швидкий стан (перша перевірка)** +1. **Швидкий статус (перша перевірка)** ```bash openclaw status ``` - Швидкий локальний підсумок: ОС + оновлення, доступність gateway/service, agents/sessions, конфігурація provider + проблеми під час виконання (коли gateway доступний). + Швидке локальне зведення: ОС + оновлення, доступність gateway/сервісу, агенти/сесії, конфігурація провайдера + проблеми під час виконання (коли gateway доступний). 2. **Звіт, який можна вставити (безпечний для поширення)** @@ -33,26 +33,26 @@ x-i18n: openclaw status --all ``` - Діагностика лише для читання з хвостом журналу (токени приховано). + Діагностика лише для читання з хвостом журналу (токени замасковані). -3. **Стан daemon + port** +3. **Стан демона + порту** ```bash openclaw gateway status ``` - Показує runtime supervisor порівняно з доступністю RPC, цільовий URL probe і те, яку конфігурацію service, ймовірно, використовував. + Показує runtime супервізора проти доступності RPC, цільову URL-адресу probe та яку конфігурацію сервіс, імовірно, використав. -4. **Глибокі probe** +4. **Глибокі probe-перевірки** ```bash openclaw status --deep ``` - Виконує live-probe стану gateway, включно з probe каналів, коли це підтримується - (потребує доступного gateway). Див. [Health](/uk/gateway/health). + Запускає live probe перевірки стану gateway, включно з probe-перевірками каналів, коли це підтримується + (потрібен доступний gateway). Див. [Health](/uk/gateway/health). -5. **Перегляньте останній журнал у реальному часі** +5. **Переглянути хвіст останнього журналу** ```bash openclaw logs --follow @@ -64,21 +64,21 @@ x-i18n: tail -f "$(ls -t /tmp/openclaw/openclaw-*.log | head -1)" ``` - Файлові журнали відокремлені від журналів service; див. [Журналювання](/uk/logging) і [Усунення несправностей](/uk/gateway/troubleshooting). + Файлові журнали відокремлені від журналів сервісу; див. [Logging](/uk/logging) і [Troubleshooting](/uk/gateway/troubleshooting). -6. **Запустіть doctor (виправлення)** +6. **Запустити doctor (виправлення)** ```bash openclaw doctor ``` - Виправляє/мігрує конфігурацію/стан + виконує перевірки працездатності. Див. [Doctor](/uk/gateway/doctor). + Виправляє/мігрує конфігурацію та стан + запускає перевірки стану. Див. [Doctor](/uk/gateway/doctor). -7. **Знімок Gateway** +7. **Знімок gateway** ```bash openclaw health --json - openclaw health --verbose # shows the target URL + config path on errors + openclaw health --verbose # показує цільову URL-адресу + шлях до конфігурації при помилках ``` Запитує у запущеного gateway повний знімок (лише WS). Див. [Health](/uk/gateway/health). @@ -86,30 +86,30 @@ x-i18n: ## Швидкий старт і початкове налаштування - - Використовуйте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж звертатися - в Discord, тому що більшість випадків «я застряг» — це **локальні проблеми конфігурації або середовища**, + + Використовуйте локального AI-агента, який може **бачити вашу машину**. Це набагато ефективніше, ніж питати + у Discord, тому що більшість випадків «я застряг» — це **локальні проблеми конфігурації або середовища**, які віддалені помічники не можуть перевірити. - **Claude Code**: [https://www.anthropic.com/claude-code/](https://www.anthropic.com/claude-code/) - **OpenAI Codex**: [https://openai.com/codex/](https://openai.com/codex/) - Ці інструменти можуть читати репозиторій, запускати команди, перевіряти журнали та допомагати виправляти - налаштування на рівні машини (PATH, services, permissions, auth files). Надайте їм **повну копію вихідного коду** - через встановлення hackable (git): + Ці інструменти можуть читати репозиторій, виконувати команди, перевіряти журнали та допомагати виправляти + налаштування на рівні машини (PATH, сервіси, дозволи, файли auth). Надайте їм **повну checkout-копію вихідного коду** + через hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Це встановлює OpenClaw **із git checkout**, тож агент може читати код і документацію та - аналізувати точну версію, яку ви використовуєте. Ви завжди можете повернутися до стабільної версії пізніше, - повторно запустивши інсталятор без `--install-method git`. + Це встановлює OpenClaw **із git checkout**, щоб агент міг читати код + документацію та + працювати з точною версією, яку ви запускаєте. Ви завжди можете пізніше повернутися до стабільної версії, + повторно запустивши встановлювач без `--install-method git`. - Порада: попросіть агента **спланувати й контролювати** виправлення (крок за кроком), а потім виконати лише - необхідні команди. Це робить зміни невеликими та полегшує їх аудит. + Порада: попросіть агента **спланувати та контролювати** виправлення (крок за кроком), а потім виконати лише + потрібні команди. Це зберігає зміни невеликими та спрощує аудит. - Якщо ви виявите справжню помилку або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: + Якщо ви виявили справжній баг або виправлення, будь ласка, створіть issue на GitHub або надішліть PR: [https://github.com/openclaw/openclaw/issues](https://github.com/openclaw/openclaw/issues) [https://github.com/openclaw/openclaw/pulls](https://github.com/openclaw/openclaw/pulls) @@ -123,44 +123,44 @@ x-i18n: Що вони роблять: - - `openclaw status`: швидкий знімок стану gateway/agent + базової конфігурації. - - `openclaw models status`: перевіряє автентифікацію provider і доступність моделей. + - `openclaw status`: швидкий знімок стану gateway/агента + базової конфігурації. + - `openclaw models status`: перевіряє auth провайдера + доступність моделей. - `openclaw doctor`: перевіряє та виправляє типові проблеми конфігурації/стану. Інші корисні перевірки CLI: `openclaw status --all`, `openclaw logs --follow`, `openclaw gateway status`, `openclaw health --verbose`. - Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#first-60-seconds-if-something-is-broken). - Документація зі встановлення: [Install](/uk/install), [Прапорці інсталятора](/uk/install/installer), [Оновлення](/uk/install/updating). + Швидкий цикл налагодження: [Перші 60 секунд, якщо щось зламалося](#перші-60-секунд-якщо-щось-зламалося). + Документація зі встановлення: [Install](/uk/install), [Installer flags](/uk/install/installer), [Updating](/uk/install/updating). - + Поширені причини пропуску heartbeat: - - `quiet-hours`: поза межами налаштованого вікна активних годин - - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожній/каркасний вміст із заголовками - - `no-tasks-due`: активний режим завдань `HEARTBEAT.md`, але час жодного з інтервалів завдань ще не настав + - `quiet-hours`: поза налаштованим вікном active-hours + - `empty-heartbeat-file`: `HEARTBEAT.md` існує, але містить лише порожню/лише із заголовком структуру + - `no-tasks-due`: режим завдань `HEARTBEAT.md` активний, але жоден з інтервалів завдань ще не настав - `alerts-disabled`: всю видимість heartbeat вимкнено (`showOk`, `showAlerts` і `useIndicator` усі вимкнені) - У режимі завдань часові позначки настання виконання зсуваються лише після завершення реального запуску heartbeat. - Пропущені запуски не позначають завдання як виконані. + У режимі завдань часові позначки настання оновлюються лише після завершення + реального виконання heartbeat. Пропущені виконання не позначають завдання як завершені. - Документація: [Heartbeat](/uk/gateway/heartbeat), [Автоматизація й завдання](/uk/automation). + Документація: [Heartbeat](/uk/gateway/heartbeat), [Automation & Tasks](/uk/automation). - Репозиторій рекомендує запуск із вихідного коду та використання онбордингу: + У репозиторії рекомендовано запуск із вихідного коду та використання onboarding: ```bash curl -fsSL https://openclaw.ai/install.sh | bash openclaw onboard --install-daemon ``` - Майстер також може автоматично зібрати ресурси UI. Після онбордингу Gateway зазвичай працює на порту **18789**. + Майстер також може автоматично зібрати UI-ресурси. Після onboarding ви зазвичай запускаєте Gateway на порту **18789**. - Із вихідного коду (для контриб’юторів/розробників): + Із вихідного коду (для контриб'юторів/розробників): ```bash git clone https://github.com/openclaw/openclaw.git @@ -171,52 +171,52 @@ x-i18n: openclaw onboard ``` - Якщо у вас ще немає глобального встановлення, запустіть це через `pnpm openclaw onboard`. + Якщо у вас ще немає глобального встановлення, запускайте через `pnpm openclaw onboard`. - - Майстер відкриває ваш браузер із чистим URL dashboard (без токена) одразу після онбордингу, а також виводить посилання в підсумку. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте виведений URL на тій самій машині. + + Майстер відкриває браузер із чистою (без токенів) URL-адресою dashboard одразу після onboarding, а також друкує посилання у зведенні. Залиште цю вкладку відкритою; якщо вона не запустилася, скопіюйте/вставте надруковану URL-адресу на тій самій машині. **Localhost (та сама машина):** - Відкрийте `http://127.0.0.1:18789/`. - - Якщо запитується автентифікація спільним секретом, вставте налаштований токен або пароль у параметрах Control UI. + - Якщо буде запитано auth зі спільним секретом, вставте налаштований токен або пароль у налаштуваннях Control UI. - Джерело токена: `gateway.auth.token` (або `OPENCLAW_GATEWAY_TOKEN`). - Джерело пароля: `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо спільний секрет ще не налаштовано, згенеруйте токен за допомогою `openclaw doctor --generate-gateway-token`. + - Якщо спільний секрет ще не налаштовано, згенеруйте токен через `openclaw doctor --generate-gateway-token`. **Не на localhost:** - - **Tailscale Serve** (рекомендовано): залиште loopback bind, виконайте `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки ідентичності задовольняють автентифікацію Control UI/WebSocket (без вставлення спільного секрету, передбачається довірений хост gateway); API HTTP усе ще вимагають автентифікації спільним секретом, якщо ви свідомо не використовуєте private-ingress `none` або HTTP-автентифікацію trusted-proxy. - Некоректні одночасні спроби автентифікації Serve від того самого клієнта серіалізуються до того, як обмежувач невдалих автентифікацій зафіксує їх, тож друга невдала повторна спроба вже може показувати `retry later`. - - **Tailnet bind**: виконайте `openclaw gateway --bind tailnet --token ""` (або налаштуйте автентифікацію паролем), відкрийте `http://:18789/`, а потім вставте відповідний спільний секрет у параметрах dashboard. - - **Identity-aware reverse proxy**: тримайте Gateway за trusted proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, а потім відкрийте URL proxy. - - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. Автентифікація спільним секретом усе ще застосовується через tunnel; за потреби вставте налаштований токен або пароль. + - **Tailscale Serve** (рекомендовано): залиште прив'язку до loopback, запустіть `openclaw gateway --tailscale serve`, відкрийте `https:///`. Якщо `gateway.auth.allowTailscale` має значення `true`, заголовки identity задовольняють вимоги auth для Control UI/WebSocket (без вставлення спільного секрету, за умови довіреного хоста gateway); HTTP API усе одно вимагають auth зі спільним секретом, якщо ви навмисно не використовуєте private-ingress `none` або HTTP auth через trusted-proxy. + Помилкові одночасні спроби auth через Serve від того самого клієнта серіалізуються до того, як обмежувач failed-auth їх зафіксує, тому вже друга помилкова повторна спроба може показати `retry later`. + - **Прив'язка tailnet**: запустіть `openclaw gateway --bind tailnet --token ""` (або налаштуйте auth через пароль), відкрийте `http://:18789/`, потім вставте відповідний спільний секрет у налаштуваннях dashboard. + - **Identity-aware reverse proxy**: залиште Gateway за trusted proxy без loopback, налаштуйте `gateway.auth.mode: "trusted-proxy"`, потім відкрийте URL-адресу proxy. + - **SSH tunnel**: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. Auth зі спільним секретом усе ще застосовується через тунель; якщо буде запит, вставте налаштований токен або пароль. - Див. [Dashboard](/uk/web/dashboard) і [Web surfaces](/uk/web) для подробиць про режими bind та автентифікацію. + Докладніше див. [Dashboard](/uk/web/dashboard) і [Web surfaces](/uk/web) щодо режимів прив'язки та подробиць auth. - + Вони керують різними рівнями: - - `approvals.exec`: пересилає запити на погодження до чат-призначень - - `channels..execApprovals`: робить цей канал нативним клієнтом погодження для exec approvals + - `approvals.exec`: пересилає запити на схвалення до чат-призначень + - `channels..execApprovals`: робить цей канал нативним клієнтом схвалення для exec approvals - Політика host exec усе ще є справжнім механізмом погодження. Конфігурація чату лише визначає, де з’являються - запити на погодження та як люди можуть на них відповідати. + Політика host exec усе ще є справжнім шлюзом схвалення. Конфігурація чату лише визначає, де + з'являються запити на схвалення та як люди можуть на них відповідати. У більшості середовищ вам **не** потрібні обидві: - - Якщо чат уже підтримує команди та відповіді, `/approve` у тому самому чаті працює через спільний шлях. - - Якщо підтримуваний нативний канал може безпечно визначати тих, хто погоджує, OpenClaw тепер автоматично вмикає нативні погодження DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. - - Коли доступні нативні картки/кнопки погодження, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, що погодження через чат недоступні або ручне погодження є єдиним шляхом. - - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або явні кімнати ops. - - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на погодження публікувалися назад у вихідну кімнату/тему. - - Погодження Plugin — окрема історія: вони типово використовують `/approve` у тому самому чаті, необов’язкове пересилання `approvals.plugin`, і лише деякі нативні канали додатково підтримують нативну обробку plugin-approval. + - Якщо чат уже підтримує команди та відповіді, `/approve` у тому ж чаті працює через спільний шлях. + - Якщо підтримуваний нативний канал може безпечно визначати тих, хто схвалює, OpenClaw тепер автоматично вмикає нативні схвалення DM-first, коли `channels..execApprovals.enabled` не задано або має значення `"auto"`. + - Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним шляхом; агент має включати ручну команду `/approve`, лише якщо результат інструмента вказує, що схвалення через чат недоступні або ручне схвалення — єдиний шлях. + - Використовуйте `approvals.exec` лише тоді, коли запити також потрібно пересилати в інші чати або спеціальні ops-кімнати. + - Використовуйте `channels..execApprovals.target: "channel"` або `"both"` лише тоді, коли ви явно хочете, щоб запити на схвалення поверталися в початкову кімнату/тему. + - Схвалення Plugin — ще окремий випадок: вони за замовчуванням використовують `/approve` у тому ж чаті, необов'язкове пересилання `approvals.plugin`, і лише деякі нативні канали зберігають поверх цього нативну обробку схвалення Plugin. Коротко: пересилання — для маршрутизації, конфігурація нативного клієнта — для багатшого UX, специфічного для каналу. Див. [Exec Approvals](/uk/tools/exec-approvals). @@ -228,14 +228,14 @@ x-i18n: - Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** і приблизно **500MB** + Так. Gateway легкий — у документації вказано, що для особистого використання достатньо **512MB-1GB RAM**, **1 core** і близько **500MB** дискового простору, а також зазначено, що **Raspberry Pi 4 може його запускати**. - Якщо вам потрібен додатковий запас (журнали, медіа, інші services), **рекомендовано 2GB**, але це + Якщо вам потрібен додатковий запас (журнали, медіа, інші сервіси), **рекомендовано 2GB**, але це не жорсткий мінімум. - Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете під’єднати **Node-и** на ноутбуці/телефоні для - локального екрана/камери/canvas або виконання команд. Див. [Node-и](/uk/nodes). + Порада: невеликий Pi/VPS може розміщувати Gateway, а ви можете підключати **nodes** на ноутбуці/телефоні для + локального екрана/камери/canvas або виконання команд. Див. [Nodes](/uk/nodes). @@ -243,18 +243,18 @@ x-i18n: Коротко: це працює, але очікуйте певних шорсткостей. - Використовуйте **64-bit** ОС і Node >= 22. - - Надавайте перевагу встановленню **hackable (git)**, щоб мати доступ до журналів і швидко оновлюватися. - - Починайте без каналів/Skills, а потім додавайте їх по одному. - - Якщо ви натрапляєте на дивні проблеми з бінарними файлами, зазвичай це проблема **сумісності ARM**. + - Віддавайте перевагу **hackable (git) install**, щоб мати доступ до журналів і швидко оновлюватися. + - Починайте без channels/Skills, а потім додавайте їх по одному. + - Якщо ви зіткнулися з дивними проблемами з бінарними файлами, зазвичай це проблема **ARM compatibility**. Документація: [Linux](/uk/platforms/linux), [Install](/uk/install). - - Цей екран залежить від доступності та автентифікації Gateway. TUI також надсилає - "Wake up, my friend!" автоматично під час першого запуску. Якщо ви бачите цей рядок **без відповіді** - і токени залишаються на 0, агент так і не запустився. + + Цей екран залежить від доступності та автентифікації Gateway. TUI також автоматично надсилає + «Wake up, my friend!» під час першого hatch. Якщо ви бачите цей рядок **без відповіді** + і кількість токенів залишається 0, агент так і не запустився. 1. Перезапустіть Gateway: @@ -262,7 +262,7 @@ x-i18n: openclaw gateway restart ``` - 2. Перевірте стан і автентифікацію: + 2. Перевірте статус + auth: ```bash openclaw status @@ -276,31 +276,31 @@ x-i18n: openclaw doctor ``` - Якщо Gateway віддалений, переконайтеся, що з’єднання tunnel/Tailscale активне і що UI - вказує на правильний Gateway. Див. [Віддалений доступ](/uk/gateway/remote). + Якщо Gateway віддалений, переконайтеся, що tunnel/Tailscale-з'єднання працює і що UI + вказує на правильний Gateway. Див. [Remote access](/uk/gateway/remote). - - Так. Скопіюйте **каталог стану** і **робочий простір**, а потім один раз запустіть Doctor. Це - збереже вашого бота «точно таким самим» (пам’ять, історію сесій, автентифікацію та - стан каналу), якщо ви скопіюєте **обидва** розташування: + + Так. Скопіюйте **каталог стану** та **workspace**, а потім один раз запустіть Doctor. Це + збереже вашого бота «точно таким самим» (memory, історія сесій, auth і стан + каналу), якщо ви скопіюєте **обидва** місця: 1. Встановіть OpenClaw на новій машині. 2. Скопіюйте `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`) зі старої машини. - 3. Скопіюйте свій робочий простір (типово: `~/.openclaw/workspace`). - 4. Запустіть `openclaw doctor` і перезапустіть service Gateway. + 3. Скопіюйте ваш workspace (типово: `~/.openclaw/workspace`). + 4. Запустіть `openclaw doctor` і перезапустіть сервіс Gateway. - Це зберігає конфігурацію, профілі автентифікації, облікові дані WhatsApp, сесії та пам’ять. Якщо ви в - віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і робочим простором. + Це зберігає конфігурацію, профілі auth, облікові дані WhatsApp, сесії та memory. Якщо ви працюєте у + віддаленому режимі, пам’ятайте, що хост gateway володіє сховищем сесій і workspace. - **Важливо:** якщо ви лише commit/push свій робочий простір у GitHub, ви створюєте резервну - копію **пам’яті + bootstrap-файлів**, але **не** історії сесій чи автентифікації. Вони містяться - в `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). + **Важливо:** якщо ви лише commit/push ваш workspace до GitHub, ви створюєте резервну копію + **memory + bootstrap-файлів**, але **не** історії сесій чи auth. Вони зберігаються + у `~/.openclaw/` (наприклад, `~/.openclaw/agents//sessions/`). - Пов’язане: [Міграція](/uk/install/migrating), [Де що зберігається на диску](#where-things-live-on-disk), - [Робочий простір агента](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), - [Віддалений режим](/uk/gateway/remote). + Пов’язане: [Migrating](/uk/install/migrating), [Where things live on disk](#where-things-live-on-disk), + [Agent workspace](/uk/concepts/agent-workspace), [Doctor](/uk/gateway/doctor), + [Remote mode](/uk/gateway/remote). @@ -308,16 +308,16 @@ x-i18n: Перевірте changelog на GitHub: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Найновіші записи розташовані вгорі. Якщо верхній розділ позначено як **Unreleased**, наступний датований - розділ — це остання випущена версія. Записи згруповано за **Highlights**, **Changes** і - **Fixes** (а також за розділами документації/іншими за потреби). + Найновіші записи розташовані зверху. Якщо верхній розділ позначений як **Unreleased**, наступний датований + розділ є останньою випущеною версією. Записи згруповані за **Highlights**, **Changes** і + **Fixes** (а також розділами docs/іншими, коли це потрібно). - + Деякі з’єднання Comcast/Xfinity помилково блокують `docs.openclaw.ai` через Xfinity Advanced Security. Вимкніть її або додайте `docs.openclaw.ai` до allowlist, а потім повторіть спробу. - Будь ласка, допоможіть нам розблокувати сайт, повідомивши про це тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). + Будь ласка, допоможіть нам розблокувати сайт, повідомивши тут: [https://spa.xfinity.com/check_url_status](https://spa.xfinity.com/check_url_status). Якщо ви все ще не можете відкрити сайт, документація дзеркалюється на GitHub: [https://github.com/openclaw/openclaw/tree/main/docs](https://github.com/openclaw/openclaw/tree/main/docs) @@ -330,21 +330,21 @@ x-i18n: - `latest` = stable - `beta` = рання збірка для тестування - Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім окремий - крок просування переміщує цю саму версію в `latest`. За потреби мейнтейнери також можуть - публікувати одразу в `latest`. Саме тому beta і stable після просування можуть + Зазвичай stable-реліз спочатку потрапляє в **beta**, а потім явний + крок просування переводить ту саму версію в `latest`. За потреби мейнтейнери також можуть + публікувати одразу в `latest`. Саме тому після просування beta і stable можуть вказувати на **одну й ту саму версію**. - Подивитися, що змінилося: + Подивіться, що змінилося: [https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md](https://github.com/openclaw/openclaw/blob/main/CHANGELOG.md) - Для однорядкових команд встановлення та пояснення різниці між beta і dev див. accordion нижче. + Однорядкові команди для встановлення та різницю між beta і dev див. в accordion нижче. - + **Beta** — це npm dist-tag `beta` (після просування може збігатися з `latest`). - **Dev** — це рухома вершина `main` (git); коли публікується, використовує npm dist-tag `dev`. + **Dev** — це рухома head-версія `main` (git); під час публікації вона використовує npm dist-tag `dev`. Однорядкові команди (macOS/Linux): @@ -356,10 +356,10 @@ x-i18n: curl -fsSL --proto '=https' --tlsv1.2 https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Інсталятор для Windows (PowerShell): + Встановлювач для Windows (PowerShell): [https://openclaw.ai/install.ps1](https://openclaw.ai/install.ps1) - Детальніше: [Канали розробки](/uk/install/development-channels) і [Прапорці інсталятора](/uk/install/installer). + Детальніше: [Development channels](/uk/install/development-channels) і [Installer flags](/uk/install/installer). @@ -374,7 +374,7 @@ x-i18n: Це перемикає на гілку `main` і оновлює з вихідного коду. - 2. **Hackable-встановлення (із сайту інсталятора):** + 2. **Hackable install (із сайту встановлювача):** ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git @@ -382,7 +382,7 @@ x-i18n: Це дає вам локальний репозиторій, який можна редагувати, а потім оновлювати через git. - Якщо ви віддаєте перевагу чистому ручному клонуванню, використовуйте: + Якщо ви надаєте перевагу ручному чистому clone, використовуйте: ```bash git clone https://github.com/openclaw/openclaw.git @@ -391,36 +391,36 @@ x-i18n: pnpm build ``` - Документація: [Оновлення](/uk/cli/update), [Канали розробки](/uk/install/development-channels), - [Встановлення](/uk/install). + Документація: [Update](/uk/cli/update), [Development channels](/uk/install/development-channels), + [Install](/uk/install). - - Орієнтовно: + + Приблизно: - - **Встановлення:** 2–5 хвилин - - **Онбординг:** 5–15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте + - **Встановлення:** 2-5 хвилин + - **Onboarding:** 5-15 хвилин залежно від того, скільки каналів/моделей ви налаштовуєте - Якщо процес зависає, див. [Інсталятор завис?](#quick-start-and-first-run-setup) - і швидкий цикл налагодження в [Я застряг](#quick-start-and-first-run-setup). + Якщо процес зависає, див. [Installer stuck](#quick-start-and-first-run-setup) + і швидкий цикл налагодження в [I am stuck](#quick-start-and-first-run-setup). - - Повторно запустіть інсталятор із **детальним виводом**: + + Повторно запустіть встановлювач із **докладним виводом**: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --verbose ``` - Встановлення beta з детальним виводом: + Встановлення beta з докладним виводом: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --beta --verbose ``` - Для hackable-встановлення (git): + Для hackable (git) install: ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git --verbose @@ -429,48 +429,48 @@ x-i18n: Еквівалент для Windows (PowerShell): ```powershell - # install.ps1 has no dedicated -Verbose flag yet. + # install.ps1 ще не має окремого прапорця -Verbose. Set-PSDebug -Trace 1 & ([scriptblock]::Create((iwr -useb https://openclaw.ai/install.ps1))) -NoOnboard Set-PSDebug -Trace 0 ``` - Більше варіантів: [Прапорці інсталятора](/uk/install/installer). + Інші варіанти: [Installer flags](/uk/install/installer). - - Дві поширені проблеми Windows: + + Дві поширені проблеми у Windows: - **1) помилка npm spawn git / git not found** + **1) npm error spawn git / git not found** - - Установіть **Git for Windows** і переконайтеся, що `git` є у вашому PATH. - - Закрийте й знову відкрийте PowerShell, а потім повторно запустіть інсталятор. + - Встановіть **Git for Windows** і переконайтеся, що `git` є у PATH. + - Закрийте й знову відкрийте PowerShell, потім повторно запустіть встановлювач. - **2) після встановлення `openclaw is not recognized`** + **2) після встановлення openclaw is not recognized** - - Глобальна папка bin npm відсутня у PATH. + - Ваша глобальна папка npm bin відсутня у PATH. - Перевірте шлях: ```powershell npm config get prefix ``` - - Додайте цей каталог до свого PATH користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). - - Після оновлення PATH закрийте й знову відкрийте PowerShell. + - Додайте цей каталог до PATH вашого користувача (суфікс `\bin` у Windows не потрібен; у більшості систем це `%AppData%\npm`). + - Закрийте й знову відкрийте PowerShell після оновлення PATH. - Якщо ви хочете найгладкіше середовище на Windows, використовуйте **WSL2** замість нативного Windows. + Якщо вам потрібне найгладше налаштування у Windows, використовуйте **WSL2** замість нативного Windows. Документація: [Windows](/uk/platforms/windows). - - Зазвичай це невідповідність кодової сторінки консолі в нативних оболонках Windows. + + Зазвичай це невідповідність code page консолі в нативних оболонках Windows. Симптоми: - - вивід `system.run`/`exec` показує китайський текст як mojibake - - та сама команда має нормальний вигляд в іншому профілі термінала + - вивід `system.run`/`exec` відображає китайський текст як mojibake + - та сама команда виглядає нормально в іншому профілі термінала Швидкий обхідний шлях у PowerShell: @@ -487,66 +487,66 @@ x-i18n: openclaw gateway restart ``` - Якщо проблема все ще відтворюється в останній версії OpenClaw, відстежуйте/повідомте про неї тут: + Якщо це й далі відтворюється в останній версії OpenClaw, відстежуйте/повідомляйте тут: - [Issue #30640](https://github.com/openclaw/openclaw/issues/30640) - Використовуйте **hackable-встановлення (git)**, щоб мати повний вихідний код і документацію локально, а потім запитайте - свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і відповісти точно. + Використовуйте **hackable (git) install**, щоб мати повний вихідний код і документацію локально, а потім запитайте + свого бота (або Claude/Codex) _з цієї папки_, щоб він міг прочитати репозиторій і дати точну відповідь. ```bash curl -fsSL https://openclaw.ai/install.sh | bash -s -- --install-method git ``` - Детальніше: [Встановлення](/uk/install) і [Прапорці інсталятора](/uk/install/installer). + Детальніше: [Install](/uk/install) і [Installer flags](/uk/install/installer). - Коротка відповідь: дотримуйтесь інструкції для Linux, а потім запустіть онбординг. + Коротка відповідь: дотримуйтесь керівництва для Linux, а потім запустіть onboarding. - - Швидкий шлях для Linux + встановлення service: [Linux](/uk/platforms/linux). - - Повний покроковий посібник: [Початок роботи](/uk/start/getting-started). - - Інсталятор + оновлення: [Встановлення й оновлення](/uk/install/updating). + - Швидкий шлях для Linux + встановлення сервісу: [Linux](/uk/platforms/linux). + - Повний покроковий посібник: [Getting Started](/uk/start/getting-started). + - Встановлювач + оновлення: [Install & updates](/uk/install/updating). - - Підійде будь-який Linux VPS. Установіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. + + Підійде будь-який Linux VPS. Встановіть на сервері, а потім використовуйте SSH/Tailscale для доступу до Gateway. - Посібники: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). - Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). + Керівництва: [exe.dev](/uk/install/exe-dev), [Hetzner](/uk/install/hetzner), [Fly.io](/uk/install/fly). + Віддалений доступ: [Gateway remote](/uk/gateway/remote). - - Ми підтримуємо **хаб хостингу** з найпоширенішими провайдерами. Виберіть потрібного й дотримуйтесь посібника: + + У нас є **центральна сторінка хостингу** з поширеними провайдерами. Виберіть потрібного й дотримуйтесь посібника: - - [Хостинг VPS](/uk/vps) (усі провайдери в одному місці) + - [VPS hosting](/uk/vps) (усі провайдери в одному місці) - [Fly.io](/uk/install/fly) - [Hetzner](/uk/install/hetzner) - [exe.dev](/uk/install/exe-dev) - Як це працює в хмарі: **Gateway працює на сервері**, а ви звертаєтеся до нього - з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваш стан і робочий простір - живуть на сервері, тож вважайте хост джерелом істини й створюйте його резервні копії. + Як це працює в хмарі: **Gateway працює на сервері**, а ви отримуєте до нього доступ + з ноутбука/телефона через Control UI (або Tailscale/SSH). Ваші state + workspace + живуть на сервері, тож вважайте хост джерелом істини та робіть його резервні копії. - Ви можете під’єднати **Node-и** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб отримати доступ до - локального екрана/камери/canvas або виконувати команди на своєму ноутбуці, зберігаючи + Ви можете підключати **nodes** (Mac/iOS/Android/headless) до цього хмарного Gateway, щоб мати доступ + до локального екрана/камери/canvas або виконувати команди на ноутбуці, залишаючи Gateway у хмарі. - Хаб: [Платформи](/uk/platforms). Віддалений доступ: [Віддалений Gateway](/uk/gateway/remote). - Node-и: [Node-и](/uk/nodes), [CLI Node-ів](/uk/cli/nodes). + Центральна сторінка: [Platforms](/uk/platforms). Віддалений доступ: [Gateway remote](/uk/gateway/remote). + Nodes: [Nodes](/uk/nodes), [Nodes CLI](/uk/cli/nodes). - + Коротка відповідь: **можливо, але не рекомендовано**. Процес оновлення може перезапустити - Gateway (що обриває активну сесію), може потребувати чистого git checkout і - може запросити підтвердження. Безпечніше запускати оновлення з оболонки як оператор. + Gateway (що розірве активну сесію), може вимагати чистий git checkout і + може просити підтвердження. Безпечніше запускати оновлення з оболонки як оператору. Використовуйте CLI: @@ -565,74 +565,74 @@ x-i18n: openclaw gateway restart ``` - Документація: [Оновлення](/uk/cli/update), [Оновлення](/uk/install/updating). + Документація: [Update](/uk/cli/update), [Updating](/uk/install/updating). - - `openclaw onboard` — це рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: + + `openclaw onboard` — рекомендований шлях налаштування. У **локальному режимі** він проводить вас через: - - **Налаштування моделі/автентифікації** (OAuth provider, API keys, Anthropic setup-token, а також варіанти локальних моделей, як-от LM Studio) - - Розташування **робочого простору** + bootstrap-файли + - **Налаштування моделі/auth** (OAuth провайдера, API keys, Anthropic setup-token, а також варіанти локальних моделей, як-от LM Studio) + - Розташування **workspace** + bootstrap-файли - **Налаштування Gateway** (bind/port/auth/tailscale) - - **Канали** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugins, як-от QQ Bot) - - **Встановлення daemon** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) - - **Перевірки працездатності** та вибір **Skills** + - **Channels** (WhatsApp, Telegram, Discord, Mattermost, Signal, iMessage, а також вбудовані channel plugins, як-от QQ Bot) + - **Встановлення демона** (LaunchAgent на macOS; systemd user unit на Linux/WSL2) + - **Перевірки стану** та вибір **Skills** - Він також попереджає, якщо ваша налаштована модель невідома або для неї відсутня автентифікація. + Він також попереджає, якщо ваша налаштована модель невідома або для неї відсутній auth. - + Ні. Ви можете запускати OpenClaw з **API keys** (Anthropic/OpenAI/інші) або з **лише локальними моделями**, щоб ваші дані залишалися на вашому пристрої. Підписки (Claude - Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих provider. + Pro/Max або OpenAI Codex) — це необов’язкові способи автентифікації в цих провайдерів. Для Anthropic в OpenClaw практичний поділ такий: - **Anthropic API key**: звичайна оплата Anthropic API - - **Автентифікація Claude CLI / Claude subscription в OpenClaw**: співробітники Anthropic - повідомили нам, що таке використання знову дозволене, і OpenClaw вважає використання `claude -p` - санкціонованим для цієї інтеграції, якщо Anthropic не опублікує нову + - **Claude CLI / auth підписки Claude в OpenClaw**: співробітники Anthropic + сказали нам, що таке використання знову дозволене, і OpenClaw розглядає використання `claude -p` + як санкціоноване для цієї інтеграції, якщо Anthropic не опублікує нову політику Для довготривалих хостів gateway Anthropic API keys усе ще є більш - передбачуваним налаштуванням. OpenAI Codex OAuth явно підтримується для зовнішніх - інструментів на кшталт OpenClaw. + передбачуваним налаштуванням. OAuth OpenAI Codex явно підтримується для зовнішніх + інструментів, як-от OpenClaw. - OpenClaw також підтримує інші розміщені варіанти у стилі підписки, зокрема + OpenClaw також підтримує інші розміщені варіанти в стилі підписки, зокрема **Qwen Cloud Coding Plan**, **MiniMax Coding Plan** і **Z.AI / GLM Coding Plan**. Документація: [Anthropic](/uk/providers/anthropic), [OpenAI](/uk/providers/openai), [Qwen Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax), [GLM Models](/uk/providers/glm), - [Локальні моделі](/uk/gateway/local-models), [Моделі](/uk/concepts/models). + [Local models](/uk/gateway/local-models), [Models](/uk/concepts/models). Так. - Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому - OpenClaw вважає автентифікацію через підписку Claude і використання `claude -p` санкціонованими + Співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож + OpenClaw вважає auth через підписку Claude та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. Якщо вам потрібне - найпередбачуваніше серверне налаштування, використовуйте натомість Anthropic API key. + найбільш передбачуване налаштування на боці сервера, натомість використовуйте Anthropic API key. - + Так. Співробітники Anthropic повідомили нам, що таке використання знову дозволене, тому OpenClaw вважає повторне використання Claude CLI та використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. - Anthropic setup-token усе ще доступний як підтримуваний шлях токена в OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли це доступно. - Для production або multi-user навантажень автентифікація через Anthropic API key усе ще є - безпечнішим і більш передбачуваним вибором. Якщо вас цікавлять інші розміщені - варіанти у стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model - Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) та [GLM + Anthropic setup-token і далі доступний як підтримуваний шлях токена OpenClaw, але тепер OpenClaw віддає перевагу повторному використанню Claude CLI та `claude -p`, коли це можливо. + Для production або багатокористувацьких навантажень auth через Anthropic API key усе ще є + безпечнішим і передбачуванішим вибором. Якщо вам потрібні інші розміщені + варіанти в стилі підписки в OpenClaw, див. [OpenAI](/uk/providers/openai), [Qwen / Model + Cloud](/uk/providers/qwen), [MiniMax](/uk/providers/minimax) і [GLM Models](/uk/providers/glm). @@ -643,165 +643,166 @@ x-i18n: - Це означає, що вашу **квоту/ліміт швидкості Anthropic** вичерпано для поточного вікна. Якщо ви - використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій тариф. Якщо ви + Це означає, що вашу **квоту/ліміт запитів Anthropic** вичерпано для поточного вікна. Якщо ви + використовуєте **Claude CLI**, дочекайтеся скидання вікна або оновіть свій план. Якщо ви використовуєте **Anthropic API key**, перевірте Anthropic Console - на предмет використання/білінгу та за потреби підвищте ліміти. + щодо використання/білінгу та за потреби підвищте ліміти. - Якщо повідомлення має такий конкретний вигляд: - `Extra usage is required for long context requests`, запит намагається використовувати - 1M context beta від Anthropic (`context1m: true`). Це працює лише тоді, коли ваші - облікові дані мають право на білінг довгого контексту (білінг API key або - шлях входу Claude OpenClaw з увімкненим Extra Usage). + Якщо повідомлення конкретно таке: + `Extra usage is required for long context requests`, запит намагається використати + 1M context beta від Anthropic (`context1m: true`). Це працює, лише коли ваші + облікові дані мають право на білінг long-context (білінг API key або + шлях входу в Claude OpenClaw з увімкненим Extra Usage). - Порада: налаштуйте **fallback model**, щоб OpenClaw міг і далі відповідати, поки provider обмежений за rate limit. + Порада: налаштуйте **fallback model**, щоб OpenClaw міг і надалі відповідати, поки провайдер має обмеження за rate limit. Див. [Models](/uk/cli/models), [OAuth](/uk/concepts/oauth) і [/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context](/uk/gateway/troubleshooting#anthropic-429-extra-usage-required-for-long-context). - Так. OpenClaw має вбудований provider **Amazon Bedrock (Converse)**. За наявності маркерів середовища AWS OpenClaw може автоматично виявити потоковий/текстовий каталог Bedrock і об’єднати його як неявний provider `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис manual provider. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Model providers](/uk/providers/models). Якщо ви віддаєте перевагу керованому шляху з ключем, OpenAI-сумісний proxy перед Bedrock також залишається коректним варіантом. + Так. OpenClaw має вбудований провайдер **Amazon Bedrock (Converse)**. Якщо присутні маркери AWS env, OpenClaw може автоматично виявити каталог Bedrock streaming/text і об’єднати його як неявного провайдера `amazon-bedrock`; інакше ви можете явно ввімкнути `plugins.entries.amazon-bedrock.config.discovery.enabled` або додати запис провайдера вручну. Див. [Amazon Bedrock](/uk/providers/bedrock) і [Model providers](/uk/providers/models). Якщо ви віддаєте перевагу керованому потоку ключів, OpenAI-compatible proxy перед Bedrock також залишається коректним варіантом. - - OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Онбординг може виконати OAuth flow і встановить типову модель на `openai-codex/gpt-5.5`, коли це доречно. Див. [Model providers](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + + OpenClaw підтримує **OpenAI Code (Codex)** через OAuth (вхід через ChatGPT). Нові посилання на моделі мають використовувати канонічний шлях `openai/gpt-5.5`; `openai-codex/gpt-*` залишається застарілим alias сумісності. Див. [Model providers](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). - - OpenClaw розглядає ці два шляхи окремо: + + `openai-codex` усе ще є внутрішнім id провайдера auth/profile для OAuth ChatGPT/Codex. Посилання на модель має бути канонічним OpenAI: - - `openai-codex/gpt-5.5` = OAuth ChatGPT/Codex - - `openai/gpt-5.5` = прямий OpenAI Platform API + - `openai/gpt-5.5` = канонічне посилання на модель GPT-5.5 + - `openai-codex/gpt-5.5` = застарілий alias сумісності + - `openai-codex:...` = id профілю auth, а не посилання на модель - В OpenClaw вхід через ChatGPT/Codex під’єднано до маршруту `openai-codex/*`, - а не до прямого маршруту `openai/*`. Якщо вам потрібен прямий шлях API в - OpenClaw, установіть `OPENAI_API_KEY` (або еквівалентну конфігурацію provider OpenAI). - Якщо вам потрібен вхід через ChatGPT/Codex в OpenClaw, використовуйте `openai-codex/*`. + Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, задайте + `OPENAI_API_KEY`. Якщо вам потрібен auth через підписку ChatGPT/Codex, увійдіть за допомогою + `openclaw models auth login --provider openai-codex` і залишайте посилання на моделі як + `openai/*` у нових конфігураціях. - - `openai-codex/*` використовує маршрут Codex OAuth, а його доступні вікна квоти - керуються OpenAI і залежать від тарифу. На практиці ці ліміти можуть відрізнятися від - досвіду на сайті/в застосунку ChatGPT, навіть якщо обидва прив’язані до того самого облікового запису. + + Codex OAuth використовує керовані OpenAI вікна квот, які залежать від плану. На практиці + ці ліміти можуть відрізнятися від досвіду використання сайту/застосунку ChatGPT, навіть коли + обидва прив’язані до одного облікового запису. - OpenClaw може показувати поточні видимі вікна використання/квоти provider у - `openclaw models status`, але не вигадує й не нормалізує права ChatGPT web + OpenClaw може показувати поточні видимі вікна використання/квот провайдера в + `openclaw models status`, але він не вигадує і не нормалізує права доступу ChatGPT-web у прямий доступ до API. Якщо вам потрібен прямий шлях білінгу/лімітів OpenAI Platform, використовуйте `openai/*` з API key. - - Так. OpenClaw повністю підтримує **OAuth підписки OpenAI Code (Codex)**. - OpenAI прямо дозволяє використання OAuth підписки у зовнішніх інструментах/робочих процесах - на кшталт OpenClaw. Онбординг може виконати OAuth flow за вас. + + Так. OpenClaw повністю підтримує **subscription OAuth OpenAI Code (Codex)**. + OpenAI явно дозволяє використання subscription OAuth у зовнішніх інструментах/робочих процесах + на кшталт OpenClaw. Onboarding може виконати OAuth-потік за вас. - Див. [OAuth](/uk/concepts/oauth), [Model providers](/uk/concepts/model-providers) і [Онбординг (CLI)](/uk/start/wizard). + Див. [OAuth](/uk/concepts/oauth), [Model providers](/uk/concepts/model-providers) і [Onboarding (CLI)](/uk/start/wizard). - Gemini CLI використовує **Plugin auth flow**, а не client id чи secret у `openclaw.json`. + Gemini CLI використовує **потік auth Plugin**, а не client id чи secret у `openclaw.json`. Кроки: - 1. Установіть Gemini CLI локально, щоб `gemini` був у `PATH` + 1. Встановіть Gemini CLI локально, щоб `gemini` був у `PATH` - Homebrew: `brew install gemini-cli` - npm: `npm install -g @google/gemini-cli` 2. Увімкніть Plugin: `openclaw plugins enable google` 3. Увійдіть: `openclaw models auth login --provider google-gemini-cli --set-default` - 4. Типова модель після входу: `google-gemini-cli/gemini-3-flash-preview` - 5. Якщо запити не вдаються, установіть `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway + 4. Модель за замовчуванням після входу: `google-gemini-cli/gemini-3-flash-preview` + 5. Якщо запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway - Це зберігає OAuth tokens у профілях автентифікації на хості gateway. Докладніше: [Model providers](/uk/concepts/model-providers). + Це зберігає OAuth tokens у профілях auth на хості gateway. Докладніше: [Model providers](/uk/concepts/model-providers). - - Зазвичай ні. OpenClaw потребує великого контексту + сильної безпеки; малі картки обрізають і допускають витоки. Якщо вам це все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Безпека](/uk/gateway/security). + + Зазвичай ні. OpenClaw потребує великого контексту + надійного захисту; малі картки обрізають контекст і допускають витоки. Якщо вам це все ж потрібно, запускайте **найбільшу** збірку моделі, яку можете локально (LM Studio), і див. [/gateway/local-models](/uk/gateway/local-models). Менші/квантизовані моделі підвищують ризик prompt injection — див. [Security](/uk/gateway/security). - - Вибирайте endpoint-и, прив’язані до регіону. OpenRouter надає варіанти з розміщенням у США для MiniMax, Kimi і GLM; вибирайте варіант із розміщенням у США, щоб дані залишалися в регіоні. Ви все одно можете вказувати Anthropic/OpenAI поряд із ними, використовуючи `models.mode: "merge"`, щоб fallback лишалися доступними, водночас дотримуючись вибраного вами provider із потрібним регіоном. + + Вибирайте endpoints із прив’язкою до регіону. OpenRouter надає варіанти MiniMax, Kimi та GLM, розміщені у США; виберіть варіант, розміщений у США, щоб зберігати дані в межах регіону. Ви все ще можете перелічувати Anthropic/OpenAI поруч із ними, використовуючи `models.mode: "merge"`, щоб fallback залишалися доступними, одночасно дотримуючись вибраного провайдера з регіональною прив’язкою. - - Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: деякі люди - купують його як хост, що завжди працює, але підійде і невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. + + Ні. OpenClaw працює на macOS або Linux (Windows через WSL2). Mac mini — необов’язковий варіант: + деякі користувачі купують його як хост, що завжди увімкнений, але також підійде невеликий VPS, домашній сервер або пристрій класу Raspberry Pi. - Mac потрібен лише для **інструментів, доступних тільки на macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux або деінде. Якщо вам потрібні інші інструменти, доступні лише на macOS, запускайте Gateway на Mac або під’єднайте Node macOS. + Mac потрібен лише **для інструментів, доступних тільки в macOS**. Для iMessage використовуйте [BlueBubbles](/uk/channels/bluebubbles) (рекомендовано) — сервер BlueBubbles працює на будь-якому Mac, а Gateway може працювати на Linux чи деінде. Якщо вам потрібні інші інструменти лише для macOS, запускайте Gateway на Mac або підключайте macOS Node. - Документація: [BlueBubbles](/uk/channels/bluebubbles), [Node-и](/uk/nodes), [Віддалений режим Mac](/uk/platforms/mac/remote). + Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), [Mac remote mode](/uk/platforms/mac/remote). - Вам потрібен **якийсь пристрій macOS**, на якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — + Вам потрібен **будь-який пристрій з macOS**, у якому виконано вхід у Messages. Це **не обов’язково** має бути Mac mini — підійде будь-який Mac. Для iMessage **використовуйте [BlueBubbles](/uk/channels/bluebubbles)** (рекомендовано) — сервер BlueBubbles працює на macOS, тоді як Gateway може працювати на Linux або деінде. - Типові варіанти налаштування: + Поширені сценарії: - - Запустіть Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac, де виконано вхід у Messages. - - Запустіть усе на Mac, якщо хочете найпростіше середовище з однією машиною. + - Запускайте Gateway на Linux/VPS, а сервер BlueBubbles — на будь-якому Mac із входом у Messages. + - Запускайте все на Mac, якщо хочете найпростішу конфігурацію з однією машиною. - Документація: [BlueBubbles](/uk/channels/bluebubbles), [Node-и](/uk/nodes), - [Віддалений режим Mac](/uk/platforms/mac/remote). + Документація: [BlueBubbles](/uk/channels/bluebubbles), [Nodes](/uk/nodes), + [Mac remote mode](/uk/platforms/mac/remote). - - Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може під’єднатися як - **Node** (супутній пристрій). Node-и не запускають Gateway — вони надають додаткові + + Так. **Mac mini може запускати Gateway**, а ваш MacBook Pro може підключатися як + **Node** (супутній пристрій). Nodes не запускають Gateway — вони надають додаткові можливості, як-от screen/camera/canvas і `system.run` на цьому пристрої. - Типовий шаблон: + Поширений сценарій: - - Gateway на Mac mini (постійно ввімкнений). - - MacBook Pro запускає застосунок macOS або хост Node і з’єднується з Gateway. + - Gateway на Mac mini (завжди увімкнений). + - MacBook Pro запускає macOS-застосунок або хост Node і підключається до Gateway. - Використовуйте `openclaw nodes status` / `openclaw nodes list`, щоб побачити його. - Документація: [Node-и](/uk/nodes), [CLI Node-ів](/uk/cli/nodes). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/uk/cli/nodes). - - Bun **не рекомендовано**. Ми спостерігаємо runtime-помилки, особливо з WhatsApp і Telegram. - Для стабільних Gateway використовуйте **Node**. + + Bun **не рекомендовано**. Ми спостерігаємо помилки runtime, особливо з WhatsApp і Telegram. + Для стабільних gateway використовуйте **Node**. - Якщо ви все ж хочете поекспериментувати з Bun, робіть це на gateway не для production + Якщо ви все ж хочете експериментувати з Bun, робіть це на непродукційному gateway без WhatsApp/Telegram. - + `channels.telegram.allowFrom` — це **Telegram user ID людини-відправника** (числовий). Це не ім’я користувача бота. - Під час налаштування запитуються лише числові user ID. Якщо у вас у конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати їх розв’язати. + Під час налаштування запитуються лише числові user ID. Якщо у вашій конфігурації вже є застарілі записи `@username`, `openclaw doctor --fix` може спробувати їх розв’язати. - Безпечніше (без стороннього бота): + Безпечніший варіант (без стороннього бота): - - Надішліть DM своєму боту, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. + - Напишіть своєму боту в DM, потім виконайте `openclaw logs --follow` і прочитайте `from.id`. Офіційний Bot API: - - Надішліть DM своєму боту, а потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. + - Напишіть своєму боту в DM, потім викличте `https://api.telegram.org/bot/getUpdates` і прочитайте `message.from.id`. - Сторонні варіанти (менше приватності): + Сторонній сервіс (менш приватно): - - Надішліть DM `@userinfobot` або `@getidsbot`. + - Напишіть у DM `@userinfobot` або `@getidsbot`. Див. [/channels/telegram](/uk/channels/telegram#access-control-and-activation). - - Так, через **маршрутизацію multi-agent**. Прив’яжіть WhatsApp **DM** кожного відправника (peer `kind: "direct"`, E.164 відправника на кшталт `+15551234567`) до іншого `agentId`, щоб кожна людина мала власний робочий простір і сховище сесій. Відповіді все одно надходитимуть із **того самого облікового запису WhatsApp**, а контроль доступу для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). + + Так, через **маршрутизацію multi-agent**. Прив’яжіть **DM** WhatsApp кожного відправника (peer `kind: "direct"`, sender E.164 на кшталт `+15551234567`) до різного `agentId`, щоб кожна людина мала власні workspace і сховище сесій. Відповіді все одно надходитимуть з **того самого облікового запису WhatsApp**, а керування доступом для DM (`channels.whatsapp.dmPolicy` / `channels.whatsapp.allowFrom`) є глобальним для кожного облікового запису WhatsApp. Див. [Multi-Agent Routing](/uk/concepts/multi-agent) і [WhatsApp](/uk/channels/whatsapp). - - Так. Використовуйте маршрутизацію multi-agent: задайте кожному агенту власну типову модель, а потім прив’яжіть вхідні маршрути (обліковий запис provider або конкретні peer) до кожного агента. Приклад конфігурації наведено в [Маршрутизація Multi-Agent](/uk/concepts/multi-agent). Див. також [Моделі](/uk/concepts/models) і [Конфігурація](/uk/gateway/configuration). + + Так. Використовуйте маршрутизацію multi-agent: задайте кожному агенту власну модель за замовчуванням, а потім прив’яжіть вхідні маршрути (обліковий запис провайдера або конкретні peers) до кожного агента. Приклад конфігурації наведено в [Multi-Agent Routing](/uk/concepts/multi-agent). Див. також [Models](/uk/concepts/models) і [Configuration](/uk/gateway/configuration). @@ -814,27 +815,27 @@ x-i18n: brew install ``` - Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH service містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, установлені через `brew`, розв’язувалися в оболонках без входу. - Останні збірки також додають на початок поширені каталоги user bin у Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` та `FNM_DIR`, якщо вони задані. + Якщо ви запускаєте OpenClaw через systemd, переконайтеся, що PATH сервісу містить `/home/linuxbrew/.linuxbrew/bin` (або ваш префікс brew), щоб інструменти, встановлені через `brew`, визначалися в non-login оболонках. + Останні збірки також додають на початок PATH поширені користувацькі каталоги bin у Linux systemd services (наприклад `~/.local/bin`, `~/.npm-global/bin`, `~/.local/share/pnpm`, `~/.bun/bin`) і враховують `PNPM_HOME`, `NPM_CONFIG_PREFIX`, `BUN_INSTALL`, `VOLTA_HOME`, `ASDF_DATA_DIR`, `NVM_DIR` і `FNM_DIR`, якщо їх задано. - - **Hackable (git) install:** повний checkout вихідного коду, редагований, найкраще для контриб’юторів. - Ви локально виконуєте збірки й можете вносити зміни в код/документацію. + - **Hackable (git) install:** повний checkout вихідного коду, можливість редагування, найкращий варіант для контриб’юторів. + Ви збираєте все локально й можете вносити зміни до коду/документації. - **npm install:** глобальне встановлення CLI, без репозиторію, найкраще для сценарію «просто запустити». - Оновлення надходять із npm dist-tags. + Оновлення надходять через npm dist-tags. - Документація: [Початок роботи](/uk/start/getting-started), [Оновлення](/uk/install/updating). + Документація: [Getting started](/uk/start/getting-started), [Updating](/uk/install/updating). - - Так. Установіть інший варіант, а потім запустіть Doctor, щоб service gateway вказував на новий entrypoint. - Це **не видаляє ваші дані** — змінюється лише встановлення коду OpenClaw. Ваш стан - (`~/.openclaw`) і робочий простір (`~/.openclaw/workspace`) залишаються недоторканими. + + Так. Встановіть інший варіант, а потім запустіть Doctor, щоб сервіс gateway вказував на нову entrypoint. + Це **не видаляє ваші дані** — змінюється лише спосіб встановлення коду OpenClaw. Ваш state + (`~/.openclaw`) і workspace (`~/.openclaw/workspace`) залишаються недоторканими. - Від npm до git: + З npm на git: ```bash git clone https://github.com/openclaw/openclaw.git @@ -845,7 +846,7 @@ x-i18n: openclaw gateway restart ``` - Від git до npm: + З git на npm: ```bash npm install -g openclaw@latest @@ -853,67 +854,67 @@ x-i18n: openclaw gateway restart ``` - Doctor виявляє невідповідність entrypoint service gateway і пропонує переписати конфігурацію service відповідно до поточного встановлення (в автоматизації використовуйте `--repair`). + Doctor виявляє невідповідність entrypoint сервісу gateway і пропонує переписати конфігурацію сервісу відповідно до поточного install (в automation використовуйте `--repair`). - Поради щодо резервного копіювання: див. [Стратегія резервного копіювання](#where-things-live-on-disk). + Поради щодо резервного копіювання: див. [Backup strategy](#where-things-live-on-disk). - Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібне - найменше тертя і вас влаштовують сон/перезапуски, запускайте локально. + Коротка відповідь: **якщо вам потрібна надійність 24/7, використовуйте VPS**. Якщо вам потрібен + найменший поріг входу і вас влаштовують сон/перезапуски, запускайте локально. **Ноутбук (локальний Gateway)** - - **Переваги:** немає витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера. - - **Недоліки:** сон/втрата мережі = розриви з’єднання, оновлення ОС/перезавантаження переривають роботу, машина має бути активною. + - **Переваги:** без витрат на сервер, прямий доступ до локальних файлів, видиме вікно браузера в реальному часі. + - **Недоліки:** сон/розриви мережі = роз'єднання, оновлення ОС/перезавантаження переривають роботу, пристрій має залишатися увімкненим. **VPS / хмара** - - **Переваги:** постійна робота, стабільна мережа, немає проблем зі сном ноутбука, простіше підтримувати безперервну роботу. - - **Недоліки:** часто headless-режим (використовуйте знімки екрана), лише віддалений доступ до файлів, для оновлень потрібен SSH. + - **Переваги:** завжди увімкнений, стабільна мережа, немає проблем через сон ноутбука, простіше підтримувати безперервну роботу. + - **Недоліки:** часто працює без GUI (використовуйте знімки екрана), віддалений доступ до файлів, для оновлень потрібен SSH. - **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний справжній компроміс — **headless browser** проти видимого вікна. Див. [Browser](/uk/tools/browser). + **Примітка щодо OpenClaw:** WhatsApp/Telegram/Slack/Mattermost/Discord чудово працюють із VPS. Єдиний реальний компроміс — **браузер без GUI** проти видимого вікна. Див. [Browser](/uk/tools/browser). - **Рекомендований варіант за замовчуванням:** VPS, якщо у вас раніше були розриви gateway. Локальний запуск чудово підходить, коли ви активно користуєтеся Mac і хочете мати доступ до локальних файлів або автоматизацію UI з видимим браузером. + **Рекомендовано за замовчуванням:** VPS, якщо у вас раніше були розриви з gateway. Локальний варіант чудовий, коли ви активно користуєтесь Mac і хочете доступ до локальних файлів або UI automation із видимим браузером. Не обов’язково, але **рекомендовано для надійності та ізоляції**. - - **Виділений хост (VPS/Mac mini/Pi):** постійно ввімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати безперервну роботу. - - **Спільний ноутбук/настільний ПК:** цілком підходить для тестування та активного використання, але очікуйте пауз, коли машина засинає або оновлюється. + - **Виділений хост (VPS/Mac mini/Pi):** завжди увімкнений, менше переривань через сон/перезавантаження, чистіші дозволи, простіше підтримувати роботу. + - **Спільний ноутбук/десктоп:** цілком підходить для тестування та активного використання, але очікуйте пауз, коли машина переходить у сон або оновлюється. - Якщо вам потрібне найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук під’єднайте як **Node** для локальних інструментів screen/camera/exec. Див. [Node-и](/uk/nodes). - Для рекомендацій щодо безпеки прочитайте [Безпека](/uk/gateway/security). + Якщо ви хочете найкраще з обох світів, тримайте Gateway на виділеному хості, а ноутбук підключайте як **Node** для локальних інструментів screen/camera/exec. Див. [Nodes](/uk/nodes). + Рекомендації з безпеки див. у [Security](/uk/gateway/security). - OpenClaw є легким. Для базового Gateway + одного чат-каналу: + OpenClaw легкий. Для базового Gateway + одного chat channel: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM, ~500MB диска. - - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше із запасом (журнали, медіа, кілька каналів). Інструменти Node і автоматизація браузера можуть бути ресурсомісткими. + - **Рекомендовано:** 1-2 vCPU, 2GB RAM або більше для запасу (журнали, медіа, кілька каналів). Інструменти Node і browser automation можуть бути ресурсомісткими. ОС: використовуйте **Ubuntu LTS** (або будь-який сучасний Debian/Ubuntu). Шлях встановлення для Linux найкраще протестовано саме там. - Документація: [Linux](/uk/platforms/linux), [Хостинг VPS](/uk/vps). + Документація: [Linux](/uk/platforms/linux), [VPS hosting](/uk/vps). - Так. Ставтеся до VM так само, як до VPS: вона має бути завжди ввімкненою, доступною та мати достатньо - RAM для Gateway і будь-яких каналів, які ви вмикаєте. + Так. Ставтеся до VM так само, як до VPS: вона має бути завжди увімкнена, доступна та мати достатньо + RAM для Gateway і будь-яких channels, які ви вмикаєте. Базові рекомендації: - **Абсолютний мінімум:** 1 vCPU, 1GB RAM. - - **Рекомендовано:** 2GB RAM або більше, якщо ви використовуєте кілька каналів, автоматизацію браузера або інструменти для медіа. + - **Рекомендовано:** 2GB RAM або більше, якщо ви запускаєте кілька каналів, browser automation або медіа-інструменти. - **ОС:** Ubuntu LTS або інший сучасний Debian/Ubuntu. - Якщо ви на Windows, **WSL2 — це найпростіший варіант у стилі VM** і має найкращу - сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [Хостинг VPS](/uk/vps). + Якщо ви використовуєте Windows, **WSL2 — найпростіший варіант налаштування у стилі VM** і має найкращу + сумісність з інструментами. Див. [Windows](/uk/platforms/windows), [VPS hosting](/uk/vps). Якщо ви запускаєте macOS у VM, див. [macOS VM](/uk/install/macos-vm). @@ -922,31 +923,31 @@ x-i18n: ## Що таке OpenClaw? - - OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat і вбудовані channel plugins, такі як QQ Bot), а також може працювати з голосом + live Canvas на підтримуваних платформах. **Gateway** — це контрольна площина, що завжди працює; помічник — це продукт. + + OpenClaw — це персональний AI-помічник, який ви запускаєте на власних пристроях. Він відповідає на поверхнях обміну повідомленнями, якими ви вже користуєтеся (WhatsApp, Telegram, Slack, Mattermost, Discord, Google Chat, Signal, iMessage, WebChat, а також вбудовані channel plugins, наприклад QQ Bot) і також підтримує голос + живий Canvas на підтримуваних платформах. **Gateway** — це завжди увімкнена control plane; помічник — це сам продукт. - OpenClaw — це не «просто обгортка для Claude». Це **локальна контрольна площина** передусім, яка дає змогу запускати - потужного помічника на **власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, зі - станом сесій, пам’яттю та інструментами — без передачі контролю над вашими робочими процесами - розміщеному SaaS. + OpenClaw — це не «просто обгортка над Claude». Це **local-first control plane**, що дозволяє запускати + потужного помічника на **вашому власному обладнанні**, доступного з чат-застосунків, якими ви вже користуєтеся, + зі сесіями зі станом, memory та інструментами — без передачі контролю над вашими робочими процесами + хостинговому SaaS. Основні переваги: - **Ваші пристрої, ваші дані:** запускайте Gateway де завгодно (Mac, Linux, VPS) і зберігайте - робочий простір + історію сесій локально. - - **Реальні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, + workspace + історію сесій локально. + - **Справжні канали, а не веб-пісочниця:** WhatsApp/Telegram/Slack/Discord/Signal/iMessage тощо, а також мобільний голос і Canvas на підтримуваних платформах. - **Незалежність від моделі:** використовуйте Anthropic, OpenAI, MiniMax, OpenRouter тощо, з маршрутизацією - та failover для кожного агента. - - **Лише локальний варіант:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. + та аварійним перемиканням на рівні агента. + - **Варіант лише з локальними моделями:** запускайте локальні моделі, щоб **усі дані могли залишатися на вашому пристрої**, якщо ви цього хочете. - **Маршрутизація multi-agent:** окремі агенти для кожного каналу, облікового запису або завдання, кожен зі своїм - робочим простором і параметрами за замовчуванням. - - **Відкритий код і можливість змінювати:** перевіряйте, розширюйте та самостійно хостіть без vendor lock-in. + workspace і значеннями за замовчуванням. + - **Відкритий код і можливість змін:** перевіряйте, розширюйте й самостійно хостіть без прив’язки до постачальника. - Документація: [Gateway](/uk/gateway), [Канали](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), - [Пам’ять](/uk/concepts/memory). + Документація: [Gateway](/uk/gateway), [Channels](/uk/channels), [Multi-agent](/uk/concepts/multi-agent), + [Memory](/uk/concepts/memory). @@ -954,50 +955,50 @@ x-i18n: Хороші перші проєкти: - Створити сайт (WordPress, Shopify або простий статичний сайт). - - Створити прототип мобільного застосунку (план, екрани, план API). - - Організувати файли та папки (очищення, іменування, теги). - - Підключити Gmail і автоматизувати підсумки або follow-up. + - Прототип мобільного застосунку (структура, екрани, план API). + - Організувати файли та папки (очищення, найменування, тегування). + - Підключити Gmail і автоматизувати підсумки або подальші дії. - Він може виконувати великі завдання, але працює найкраще, коли ви розбиваєте їх на фази і - використовуєте subagent для паралельної роботи. + Він може працювати з великими завданнями, але найкраще працює, коли ви розбиваєте їх на етапи + і використовуєте sub-agents для паралельної роботи. Повсякденна користь зазвичай виглядає так: - - **Персональні брифінги:** підсумки вхідних листів, календаря та важливих для вас новин. - - **Дослідження та чернетки:** швидке дослідження, підсумки та перші чернетки для листів або документів. - - **Нагадування та follow-up:** nudges і чеклісти на основі cron або heartbeat. - - **Автоматизація браузера:** заповнення форм, збирання даних і повторення веб-завдань. - - **Координація між пристроями:** надішліть завдання з телефона, дайте Gateway виконати його на сервері та отримайте результат назад у чаті. + - **Персональні брифінги:** підсумки inbox, календаря та важливих для вас новин. + - **Дослідження та підготовка чернеток:** швидкі дослідження, підсумки та перші чернетки для листів або документів. + - **Нагадування та подальші дії:** підказки та чеклісти на основі Cron або Heartbeat. + - **Browser automation:** заповнення форм, збирання даних і повторення веб-завдань. + - **Координація між пристроями:** надішліть завдання з телефона, дайте Gateway виконати його на сервері й отримайте результат назад у чаті. - - Так — для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, створювати короткі списки, - підсумовувати інформацію про потенційних клієнтів і писати чернетки outreach або рекламних текстів. + + Так — для **дослідження, кваліфікації та підготовки чернеток**. Він може сканувати сайти, складати короткі списки, + підсумовувати інформацію про потенційних клієнтів і писати чернетки для outreach або рекламних текстів. Для **outreach або запуску реклами** залишайте людину в циклі. Уникайте спаму, дотримуйтеся місцевих законів і - політик платформ і перевіряйте все перед надсиланням. Найбезпечніший шаблон — дати - OpenClaw підготувати чернетку, а вам — її погодити. + правил платформ, і перевіряйте все перед відправленням. Найбезпечніший шаблон — дозволити + OpenClaw підготувати чернетку, а вам — її схвалити. - Документація: [Безпека](/uk/gateway/security). + Документація: [Security](/uk/gateway/security). - OpenClaw — це **персональний помічник** і координаційний шар, а не заміна IDE. Використовуйте + OpenClaw — це **персональний помічник** і шар координації, а не заміна IDE. Використовуйте Claude Code або Codex для найшвидшого прямого циклу програмування в репозиторії. Використовуйте OpenClaw, коли вам - потрібні довговічна пам’ять, доступ з різних пристроїв і оркестрація інструментів. + потрібні довготривала memory, доступ із різних пристроїв і оркестрація інструментів. Переваги: - - **Постійна пам’ять + робочий простір** між сесіями + - **Стійка memory + workspace** між сесіями - **Доступ із різних платформ** (WhatsApp, Telegram, TUI, WebChat) - - **Оркестрація інструментів** (browser, files, scheduling, hooks) - - **Gateway, що завжди працює** (запуск на VPS, взаємодія звідусіль) - - **Node-и** для локальних browser/screen/camera/exec + - **Оркестрація інструментів** (браузер, файли, планування, hooks) + - **Завжди увімкнений Gateway** (запуск на VPS, взаємодія звідусіль) + - **Nodes** для локальних браузера/екрана/камери/exec Вітрина: [https://openclaw.ai/showcase](https://openclaw.ai/showcase) @@ -1007,69 +1008,69 @@ x-i18n: ## Skills та автоматизація - - Використовуйте керовані перевизначення замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані перевизначення все одно мають пріоритет над bundled Skills без змін у git. Якщо Skill має бути встановлений глобально, але видимий лише певним агентам, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, гідні включення в upstream, мають жити в репозиторії й надсилатися як PR. + + Використовуйте керовані override замість редагування копії в репозиторії. Розміщуйте свої зміни в `~/.openclaw/skills//SKILL.md` (або додайте папку через `skills.load.extraDirs` у `~/.openclaw/openclaw.json`). Пріоритет такий: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`, тож керовані override все одно мають вищий пріоритет за bundled Skills без змін у git. Якщо вам потрібно встановити skill глобально, але зробити його видимим лише для деяких агентів, тримайте спільну копію в `~/.openclaw/skills` і керуйте видимістю через `agents.defaults.skills` та `agents.list[].skills`. Лише зміни, варті включення в upstream, повинні жити в репозиторії та надсилатися як PR. - Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Пріоритет за замовчуванням: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` типово встановлює в `./skills`, і OpenClaw сприймає це як `/skills` у наступній сесії. Якщо Skill має бути видимий лише певним агентам, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. + Так. Додайте додаткові каталоги через `skills.load.extraDirs` у `~/.openclaw/openclaw.json` (найнижчий пріоритет). Типовий пріоритет: `/skills` → `/.agents/skills` → `~/.agents/skills` → `~/.openclaw/skills` → bundled → `skills.load.extraDirs`. `clawhub` за замовчуванням встановлює в `./skills`, що OpenClaw трактує як `/skills` у наступній сесії. Якщо skill має бути видимим лише для певних агентів, поєднайте це з `agents.defaults.skills` або `agents.list[].skills`. - - Сьогодні підтримуються такі шаблони: + + Наразі підтримуються такі шаблони: - - **Cron-завдання**: ізольовані завдання можуть задавати перевизначення `model` для кожного завдання. - - **Sub-agent**: маршрутизуйте завдання до окремих агентів із різними типовими моделями. + - **Cron jobs**: ізольовані завдання можуть задавати override `model` для кожного завдання. + - **Sub-agents**: маршрутизуйте завдання до окремих агентів з різними моделями за замовчуванням. - **Перемикання на вимогу**: використовуйте `/model`, щоб у будь-який момент змінити модель поточної сесії. - Див. [Cron-завдання](/uk/automation/cron-jobs), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent) і [Слеш-команди](/uk/tools/slash-commands). + Див. [Cron jobs](/uk/automation/cron-jobs), [Multi-Agent Routing](/uk/concepts/multi-agent) і [Slash commands](/uk/tools/slash-commands). - - Використовуйте **subagent** для довгих або паралельних завдань. Subagent працюють у власній сесії, + + Використовуйте **sub-agents** для довгих або паралельних завдань. Sub-agents працюють у власній сесії, повертають підсумок і зберігають чутливість вашого основного чату. - Попросіть бота «spawn a sub-agent for this task» або використайте `/subagents`. - Використовуйте `/status` у чаті, щоб бачити, що Gateway робить прямо зараз (і чи він зайнятий). + Попросіть бота «spawn a sub-agent for this task» або використовуйте `/subagents`. + Використовуйте `/status` у чаті, щоб побачити, що Gateway робить просто зараз (і чи він зайнятий). - Порада щодо токенів: довгі завдання і subagent обидва споживають токени. Якщо важлива - вартість, задайте дешевшу модель для subagent через `agents.defaults.subagents.model`. + Порада щодо токенів: і довгі завдання, і sub-agents споживають токени. Якщо важлива вартість, задайте + дешевшу модель для sub-agents через `agents.defaults.subagents.model`. - Документація: [Sub-agent](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks). + Документація: [Sub-agents](/uk/tools/subagents), [Background Tasks](/uk/automation/tasks). - Використовуйте прив’язки thread. Ви можете прив’язати thread Discord до subagent або до цільової сесії, щоб подальші повідомлення в цьому thread залишалися в межах прив’язаної сесії. + Використовуйте прив’язки thread. Ви можете прив’язати Discord thread до subagent або цілі session, щоб подальші повідомлення в цьому thread залишалися в межах прив’язаної сесії. - Базовий процес: + Базовий сценарій: - - Запускайте через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійних follow-up). + - Запускайте через `sessions_spawn` з `thread: true` (і за бажанням `mode: "session"` для постійних подальших повідомлень). - Або вручну прив’яжіть через `/focus `. - - Використовуйте `/agents` для перевірки стану прив’язки. - - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокусу. + - Використовуйте `/agents`, щоб перевірити стан прив’язки. + - Використовуйте `/session idle ` і `/session max-age `, щоб керувати автоматичним зняттям фокуса. - Використовуйте `/unfocus`, щоб від’єднати thread. Потрібна конфігурація: - - Глобальні параметри за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. - - Перевизначення для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. - - Автоприв’язка під час spawn: установіть `channels.discord.threadBindings.spawnSubagentSessions: true`. + - Глобальні значення за замовчуванням: `session.threadBindings.enabled`, `session.threadBindings.idleHours`, `session.threadBindings.maxAgeHours`. + - Override для Discord: `channels.discord.threadBindings.enabled`, `channels.discord.threadBindings.idleHours`, `channels.discord.threadBindings.maxAgeHours`. + - Автоматична прив’язка під час spawn: задайте `channels.discord.threadBindings.spawnSubagentSessions: true`. - Документація: [Sub-agent](/uk/tools/subagents), [Discord](/uk/channels/discord), [Довідник із конфігурації](/uk/gateway/configuration-reference), [Слеш-команди](/uk/tools/slash-commands). + Документація: [Sub-agents](/uk/tools/subagents), [Discord](/uk/channels/discord), [Configuration Reference](/uk/gateway/configuration-reference), [Slash commands](/uk/tools/slash-commands). - + Спочатку перевірте визначений маршрут запитувача: - - Доставка subagent у режимі завершення надає перевагу будь-якому прив’язаному thread або маршруту розмови, якщо такий існує. - - Якщо джерело завершення містить лише канал, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. - - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не спрацювати, і результат повернеться до доставки через чергу сесії замість негайної публікації в чат. - - Некоректні або застарілі цілі все одно можуть примусово спричинити fallback до черги або остаточну помилку доставки. - - Якщо остання видима відповідь асистента дочірнього елемента — це точний тихий токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує announce замість публікації застарілого попереднього прогресу. - - Якщо дочірній елемент завершився через timeout після самих лише викликів інструментів, announce може згорнути це в короткий підсумок часткового прогресу замість відтворення сирого виводу інструментів. + - Доставка sub-agent у режимі завершення віддає перевагу будь-якому прив’язаному thread або маршруту conversation, якщо такий існує. + - Якщо джерело завершення містить лише channel, OpenClaw повертається до збереженого маршруту сесії запитувача (`lastChannel` / `lastTo` / `lastAccountId`), щоб пряма доставка все одно могла спрацювати. + - Якщо немає ні прив’язаного маршруту, ні придатного збереженого маршруту, пряма доставка може не вдатися, і результат повернеться до доставки через queue сесії замість негайної публікації в чат. + - Некоректні або застарілі цілі все одно можуть примусово перевести доставку в queue fallback або спричинити остаточну помилку доставки. + - Якщо остання видима відповідь assistant від дочірнього процесу — це точний мовчазний токен `NO_REPLY` / `no_reply` або рівно `ANNOUNCE_SKIP`, OpenClaw навмисно пригнічує анонс замість публікації застарілого попереднього прогресу. + - Якщо дочірній процес вийшов за тайм-аут після одних лише викликів tools, анонс може звести це до короткого підсумку часткового прогресу замість відтворення сирого виводу tool. Налагодження: @@ -1077,19 +1078,19 @@ x-i18n: openclaw tasks show ``` - Документація: [Sub-agent](/uk/tools/subagents), [Фонові завдання](/uk/automation/tasks), [Інструмент Session](/uk/concepts/session-tool). + Документація: [Sub-agents](/uk/tools/subagents), [Background Tasks](/uk/automation/tasks), [Session Tools](/uk/concepts/session-tool). - Cron працює всередині процесу Gateway. Якщо Gateway не працює безперервно, - заплановані завдання не виконуватимуться. + Cron виконується всередині процесу Gateway. Якщо Gateway не працює безперервно, + заплановані завдання не запускатимуться. Контрольний список: - - Переконайтеся, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. - - Переконайтеся, що Gateway працює 24/7 (без сну/перезапусків). - - Перевірте налаштування часового поясу для завдання (`--tz` проти часового поясу хоста). + - Підтвердьте, що cron увімкнено (`cron.enabled`) і `OPENCLAW_SKIP_CRON` не задано. + - Перевірте, що Gateway працює 24/7 (без сну/перезапусків). + - Переконайтеся в правильності налаштувань часового поясу для завдання (`--tz` проти часового поясу хоста). Налагодження: @@ -1098,21 +1099,21 @@ x-i18n: openclaw cron runs --id --limit 50 ``` - Документація: [Cron-завдання](/uk/automation/cron-jobs), [Автоматизація й завдання](/uk/automation). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Automation & Tasks](/uk/automation). - + Спочатку перевірте режим доставки: - - `--no-deliver` / `delivery.mode: "none"` означає, що резервне надсилання з боку виконавця не очікується. - - Відсутня або некоректна announce-ціль (`channel` / `to`) означає, що виконавець пропустив вихідну доставку. - - Збої автентифікації каналу (`unauthorized`, `Forbidden`) означають, що виконавець спробував доставити, але облікові дані заблокували це. - - Тихий ізольований результат (`NO_REPLY` / `no_reply` лише) вважається навмисно непридатним до доставки, тому виконавець також пригнічує доставку через чергу як fallback. + - `--no-deliver` / `delivery.mode: "none"` означає, що runner fallback send не очікується. + - Відсутня або некоректна ціль анонсу (`channel` / `to`) означає, що runner пропустив вихідну доставку. + - Помилки auth каналу (`unauthorized`, `Forbidden`) означають, що runner спробував виконати доставку, але облікові дані її заблокували. + - Мовчазний ізольований результат (`NO_REPLY` / `no_reply` only) вважається навмисно недоставлюваним, тому runner також пригнічує queued fallback delivery. - Для ізольованих cron-завдань агент усе ще може надсилати напряму за допомогою інструмента `message`, - коли доступний маршрут чату. `--announce` керує лише резервним шляхом виконавця - для фінального тексту, який агент ще не надіслав сам. + Для ізольованих Cron jobs агент усе ще може надсилати повідомлення напряму за допомогою tool `message`, + коли доступний маршрут чату. `--announce` керує лише шляхом runner + fallback для фінального тексту, який агент ще не надіслав сам. Налагодження: @@ -1121,27 +1122,27 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron-завдання](/uk/automation/cron-jobs), [Фонові завдання](/uk/automation/tasks). + Документація: [Cron jobs](/uk/automation/cron-jobs), [Background Tasks](/uk/automation/tasks). - + Зазвичай це шлях live-перемикання моделі, а не дубльоване планування. - Ізольований cron може зберегти передавання керування моделлю під час виконання та повторити спробу, коли активний - запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкнений - provider/model, а якщо перемикання містило нове перевизначення профілю автентифікації, cron + Ізольований cron може зберегти runtime-передачу моделі й повторити спробу, коли активний + запуск викидає `LiveSessionModelSwitchError`. Повторна спроба зберігає перемкненого + провайдера/модель, і якщо перемикання містило новий override профілю auth, cron також зберігає його перед повторною спробою. Пов’язані правила вибору: - - Спочатку має перевагу перевизначення моделі Gmail hook, якщо воно застосовне. - - Потім `model` окремого завдання. - - Потім будь-яке збережене перевизначення моделі cron-сесії. - - Потім звичайний вибір моделі агента/типової моделі. + - Override моделі Gmail hook має найвищий пріоритет, коли застосовується. + - Потім іде `model` на рівні завдання. + - Потім будь-який збережений override моделі cron-session. + - Потім звичайний вибір моделі агента/моделі за замовчуванням. - Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб через перемикання - cron перериває виконання замість безкінечного циклу. + Цикл повторних спроб обмежений. Після початкової спроби плюс 2 повторних спроб перемикання + cron припиняє роботу замість нескінченного циклу. Налагодження: @@ -1150,13 +1151,13 @@ x-i18n: openclaw tasks show ``` - Документація: [Cron-завдання](/uk/automation/cron-jobs), [CLI cron](/uk/cli/cron). + Документація: [Cron jobs](/uk/automation/cron-jobs), [cron CLI](/uk/cli/cron). - Використовуйте нативні команди `openclaw skills` або розміщуйте Skills у своєму робочому просторі. UI Skills для macOS недоступний на Linux. - Переглядати Skills можна на [https://clawhub.ai](https://clawhub.ai). + Використовуйте нативні команди `openclaw skills` або покладіть Skills у свій workspace. UI Skills для macOS недоступний на Linux. + Переглянути Skills можна на [https://clawhub.ai](https://clawhub.ai). ```bash openclaw skills search "calendar" @@ -1169,41 +1170,41 @@ x-i18n: openclaw skills check ``` - Нативна команда `openclaw skills install` записує у каталог `skills/` - активного робочого простору. Установлюйте окремий CLI `clawhub`, лише якщо хочете публікувати або - синхронізувати власні Skills. Для спільних встановлень між агентами розміщуйте Skill у + Нативна команда `openclaw skills install` записує в каталог `skills/` + активного workspace. Окремий CLI `clawhub` встановлюйте лише якщо хочете публікувати або + синхронізувати власні Skills. Для спільних встановлень між агентами розміщуйте skill у `~/.openclaw/skills` і використовуйте `agents.defaults.skills` або - `agents.list[].skills`, якщо хочете звузити, які агенти можуть його бачити. + `agents.list[].skills`, якщо хочете звузити перелік агентів, які можуть його бачити. Так. Використовуйте планувальник Gateway: - - **Cron-завдання** для запланованих або періодичних завдань (зберігаються після перезапусків). + - **Cron jobs** для запланованих або повторюваних завдань (зберігаються після перезапусків). - **Heartbeat** для періодичних перевірок «основної сесії». - **Ізольовані завдання** для автономних агентів, які публікують підсумки або доставляють їх у чати. - Документація: [Cron-завдання](/uk/automation/cron-jobs), [Автоматизація й завдання](/uk/automation), + Документація: [Cron jobs](/uk/automation/cron-jobs), [Automation & Tasks](/uk/automation), [Heartbeat](/uk/gateway/heartbeat). - - Не напряму. Skills macOS обмежуються через `metadata.openclaw.os` і потрібні бінарні файли, а Skills з’являються в system prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (як-от `apple-notes`, `apple-reminders`, `things-mac`) не завантажуються, якщо ви не перевизначите це обмеження. + + Не напряму. macOS Skills обмежуються через `metadata.openclaw.os` плюс потрібні бінарні файли, і Skills з’являються в system prompt лише тоді, коли вони придатні на **хості Gateway**. На Linux Skills лише для `darwin` (наприклад `apple-notes`, `apple-reminders`, `things-mac`) не завантажаться, якщо ви не перевизначите це обмеження. - Є три підтримувані шаблони: + Підтримуються три варіанти: **Варіант A — запускати Gateway на Mac (найпростіше).** - Запускайте Gateway там, де існують бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуватимуться нормально, бо хост Gateway — macOS. + Запускайте Gateway там, де доступні бінарні файли macOS, а потім підключайтеся з Linux у [віддаленому режимі](#gateway-ports-already-running-and-remote-mode) або через Tailscale. Skills завантажуються як звичайно, тому що хост Gateway — macOS. **Варіант B — використовувати macOS Node (без SSH).** - Запускайте Gateway на Linux, під’єднайте macOS Node (застосунок menubar) і встановіть **Node Run Commands** у значення "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills, доступні лише для macOS, придатними, коли потрібні бінарні файли існують на Node. Агент запускає ці Skills через інструмент `nodes`. Якщо ви виберете "Always Ask", погодження "Always Allow" у prompt додасть цю команду до allowlist. + Запускайте Gateway на Linux, підключіть macOS Node (застосунок меню-бару) і встановіть **Node Run Commands** у значення "Always Ask" або "Always Allow" на Mac. OpenClaw може вважати Skills лише для macOS придатними, коли потрібні бінарні файли є на Node. Агент запускає ці Skills через tool `nodes`. Якщо ви виберете "Always Ask", підтвердження "Always Allow" у prompt додасть цю команду до allowlist. - **Варіант C — проксувати бінарні файли macOS через SSH (просунутий).** - Тримайте Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли визначалися як SSH-обгортки, що виконуються на Mac. Потім перевизначте Skill, щоб дозволити Linux, і він лишався придатним. + **Варіант C — проксіювати бінарні файли macOS через SSH (просунутий варіант).** + Залиште Gateway на Linux, але зробіть так, щоб потрібні CLI-бінарні файли розв’язувалися в SSH-обгортки, які запускаються на Mac. Потім перевизначте skill, щоб дозволити Linux, і він залишався придатним. - 1. Створіть SSH-обгортку для бінарного файла (приклад: `memo` для Apple Notes): + 1. Створіть SSH-обгортку для бінарного файлу (приклад: `memo` для Apple Notes): ```bash #!/usr/bin/env bash @@ -1211,36 +1212,36 @@ x-i18n: exec ssh -T user@mac-host /opt/homebrew/bin/memo "$@" ``` - 2. Розмістіть обгортку в `PATH` на хості Linux (наприклад `~/bin/memo`). - 3. Перевизначте metadata Skill (робочий простір або `~/.openclaw/skills`), щоб дозволити Linux: + 2. Додайте обгортку в `PATH` на Linux-хості (наприклад `~/bin/memo`). + 3. Перевизначте метадані skill (у workspace або `~/.openclaw/skills`), щоб дозволити Linux: ```markdown --- name: apple-notes - description: Manage Apple Notes via the memo CLI on macOS. + description: Керування Apple Notes через CLI `memo` у macOS. metadata: { "openclaw": { "os": ["darwin", "linux"], "requires": { "bins": ["memo"] } } } --- ``` - 4. Почніть нову сесію, щоб знімок Skills оновився. + 4. Запустіть нову сесію, щоб оновився знімок Skills. - Сьогодні вбудованої немає. + Вбудованої інтеграції наразі немає. Варіанти: - - **Власний Skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). - - **Автоматизація браузера:** працює без коду, але повільніша й крихкіша. + - **Власний skill / Plugin:** найкраще для надійного доступу до API (і Notion, і HeyGen мають API). + - **Browser automation:** працює без коду, але повільніше й крихкіше. - Якщо ви хочете зберігати контекст окремо для кожного клієнта (сценарії агентств), простий шаблон такий: + Якщо ви хочете зберігати контекст окремо для кожного клієнта (workflow агенції), простий шаблон такий: - - Одна сторінка Notion на клієнта (контекст + уподобання + активна робота). + - Одна сторінка Notion на клієнта (контекст + налаштування + активна робота). - Попросіть агента отримувати цю сторінку на початку сесії. - Якщо вам потрібна нативна інтеграція, створіть feature request або розробіть Skill, - націлений на ці API. + Якщо вам потрібна нативна інтеграція, створіть feature request або розробіть skill, + орієнтований на ці API. Установлення Skills: @@ -1249,131 +1250,131 @@ x-i18n: openclaw skills update --all ``` - Нативні встановлення потрапляють у каталог `skills/` активного робочого простору. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують, що бінарні файли буде встановлено через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). + Нативні встановлення потрапляють у каталог `skills/` активного workspace. Для спільних Skills між агентами розміщуйте їх у `~/.openclaw/skills//SKILL.md`. Якщо спільне встановлення мають бачити лише деякі агенти, налаштуйте `agents.defaults.skills` або `agents.list[].skills`. Деякі Skills очікують бінарні файли, установлені через Homebrew; на Linux це означає Linuxbrew (див. запис FAQ про Homebrew на Linux вище). Див. [Skills](/uk/tools/skills), [Skills config](/uk/tools/skills-config) і [ClawHub](/uk/tools/clawhub). - - Використовуйте вбудований профіль браузера `user`, який під’єднується через Chrome DevTools MCP: + + Використовуйте вбудований профіль браузера `user`, який підключається через Chrome DevTools MCP: ```bash openclaw browser --browser-profile user tabs openclaw browser --browser-profile user snapshot ``` - Якщо ви хочете власну назву, створіть явний профіль MCP: + Якщо вам потрібна власна назва, створіть явний профіль MCP: ```bash openclaw browser create-profile --name chrome-live --driver existing-session openclaw browser --browser-profile chrome-live tabs ``` - Цей шлях може використовувати локальний браузер хоста або під’єднаний browser node. Якщо Gateway працює деінде, або запустіть хост node на машині з браузером, або використовуйте віддалений CDP. + Цей шлях може використовувати локальний браузер хоста або підключений browser node. Якщо Gateway працює деінде, або запустіть node host на машині з браузером, або використовуйте віддалений CDP. - Поточні обмеження `existing-session` / `user`: + Поточні обмеження для `existing-session` / `user`: - - дії прив’язані до `ref`, а не до CSS-selector - - завантаження файлів вимагає `ref` / `inputRef` і наразі підтримує по одному файлу за раз + - дії керуються через ref, а не через CSS-selector + - uploads потребують `ref` / `inputRef` і наразі підтримують лише один файл за раз - `responsebody`, експорт PDF, перехоплення завантажень і пакетні дії все ще потребують керованого браузера або профілю raw CDP -## Ізоляція та пам’ять +## Ізоляція та memory - Так. Див. [Ізоляція](/uk/gateway/sandboxing). Для налаштування, специфічного для Docker (повний gateway у Docker або образи пісочниці), див. [Docker](/uk/install/docker). + Так. Див. [Sandboxing](/uk/gateway/sandboxing). Налаштування для Docker (повний gateway у Docker або образи sandbox) див. у [Docker](/uk/install/docker). - Образ за замовчуванням орієнтований насамперед на безпеку і працює від імені користувача `node`, тому - не містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого середовища: + Образ за замовчуванням орієнтований на безпеку й запускається від користувача `node`, тому він не + містить системних пакетів, Homebrew або вбудованих браузерів. Для повнішого налаштування: - - Зберігайте `/home/node` через `OPENCLAW_HOME_VOLUME`, щоб кеші переживали перезапуски. - - Запікайте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. - - Установлюйте браузери Playwright через вбудований CLI: + - Зберігайте `/home/node` за допомогою `OPENCLAW_HOME_VOLUME`, щоб кеші не зникали. + - Вбудовуйте системні залежності в образ через `OPENCLAW_DOCKER_APT_PACKAGES`. + - Встановлюйте браузери Playwright через вбудований CLI: `node /app/node_modules/playwright-core/cli.js install chromium` - - Установіть `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. + - Задайте `PLAYWRIGHT_BROWSERS_PATH` і переконайтеся, що цей шлях зберігається. Документація: [Docker](/uk/install/docker), [Browser](/uk/tools/browser). - Так — якщо ваш приватний трафік це **DM**, а публічний трафік — **групи**. + Так — якщо ваш приватний трафік це **DM**, а публічний трафік це **групи**. - Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/каналів (ключі не `main`) працювали у налаштованому backend пісочниці, а основна DM-сесія залишалася на хості. Docker — backend за замовчуванням, якщо ви не вибрали інший. Потім обмежте, які інструменти доступні в ізольованих сесіях, через `tools.sandbox.tools`. + Використовуйте `agents.defaults.sandbox.mode: "non-main"`, щоб сесії груп/channel (ключі не-main) виконувалися в налаштованому backend sandbox, тоді як основна DM-сесія залишалася на хості. Docker є backend за замовчуванням, якщо ви не вибрали інший. Потім обмежте набір tools, доступних в ізольованих сесіях, через `tools.sandbox.tools`. Покрокове налаштування + приклад конфігурації: [Групи: особисті DM + публічні групи](/uk/channels/groups#pattern-personal-dms-public-groups-single-agent) - Довідник із ключової конфігурації: [Конфігурація Gateway](/uk/gateway/configuration-reference#agentsdefaultssandbox) + Довідник щодо ключової конфігурації: [Gateway configuration](/uk/gateway/configuration-reference#agentsdefaultssandbox) - - Установіть `agents.defaults.sandbox.docker.binds` у `["host:path:mode"]` (наприклад, `"/home/user/src:/src:ro"`). Глобальні прив’язки й прив’язки на рівні агента об’єднуються; прив’язки на рівні агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові межі пісочниці. + + Задайте `agents.defaults.sandbox.docker.binds` як `["host:path:mode"]` (наприклад `"/home/user/src:/src:ro"`). Глобальні прив’язки та прив’язки на рівні агента об’єднуються; прив’язки на рівні агента ігноруються, коли `scope: "shared"`. Використовуйте `:ro` для всього чутливого й пам’ятайте, що прив’язки обходять файлові стіни sandbox. - OpenClaw перевіряє джерела прив’язки як за нормалізованим шляхом, так і за канонічним шляхом, розв’язаним через найглибший наявний батьківський елемент. Це означає, що виходи за межі через symlink-батьківський шлях усе одно надійно блокуються, навіть коли останній сегмент шляху ще не існує, а перевірки дозволених коренів усе одно застосовуються після розв’язання symlink. + OpenClaw перевіряє джерела bind і за нормалізованим шляхом, і за канонічним шляхом, розв’язаним через найглибший наявний ancestor. Це означає, що виходи через symlink-parent усе одно безпечно блокуються навіть тоді, коли останній сегмент шляху ще не існує, а перевірки allowed-root усе одно застосовуються після розв’язання symlink. - Див. [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts) і [Пісочниця vs політика інструментів vs elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check) для прикладів і приміток щодо безпеки. + Приклади та примітки з безпеки див. у [Sandboxing](/uk/gateway/sandboxing#custom-bind-mounts) і [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated#bind-mounts-security-quick-check). - - Пам’ять OpenClaw — це просто Markdown-файли в робочому просторі агента: + + Memory в OpenClaw — це просто файли Markdown у workspace агента: - Щоденні нотатки в `memory/YYYY-MM-DD.md` - - Відібрані довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії) + - Кураторські довгострокові нотатки в `MEMORY.md` (лише основні/приватні сесії) - OpenClaw також виконує **тихе попереднє скидання пам’яті перед Compaction**, щоб нагадати моделі - записати довговічні нотатки перед автоматичним Compaction. Це виконується лише тоді, коли робочий простір - доступний для запису (пісочниці тільки для читання це пропускають). Див. [Пам’ять](/uk/concepts/memory). + OpenClaw також виконує **тихе скидання memory перед Compaction**, щоб нагадати моделі + записати довговічні нотатки перед автоматичною Compaction. Це працює лише тоді, коли workspace + доступний для запису (sandbox у режимі лише читання це пропускають). Див. [Memory](/uk/concepts/memory). - - Попросіть бота **записати факт у пам’ять**. Довгострокові нотатки мають зберігатися в `MEMORY.md`, + + Попросіть бота **записати факт у memory**. Довгострокові нотатки мають бути в `MEMORY.md`, короткостроковий контекст — у `memory/YYYY-MM-DD.md`. - Це все ще напрям, який ми покращуємо. Корисно нагадувати моделі зберігати спогади; - вона знатиме, що робити. Якщо вона все одно забуває, переконайтеся, що Gateway використовує той самий - робочий простір при кожному запуску. + Це все ще напрям, який ми вдосконалюємо. Корисно нагадувати моделі зберігати спогади; + вона зрозуміє, що робити. Якщо вона все одно забуває, перевірте, що Gateway використовує той самий + workspace під час кожного запуску. - Документація: [Пам’ять](/uk/concepts/memory), [Робочий простір агента](/uk/concepts/agent-workspace). + Документація: [Memory](/uk/concepts/memory), [Agent workspace](/uk/concepts/agent-workspace). - - Файли пам’яті живуть на диску та зберігаються, доки ви їх не видалите. Обмеженням є ваше - сховище, а не модель. **Контекст сесії** усе ще обмежений вікном контексту - моделі, тож довгі розмови можуть ущільнюватися або обрізатися. Саме тому - існує семантичний пошук по пам’яті — він повертає в контекст лише релевантні частини. + + Файли memory зберігаються на диску й існують, доки ви їх не видалите. Обмеженням є ваше + сховище, а не модель. **Контекст сесії** все одно обмежений + вікном контексту моделі, тому довгі розмови можуть ущільнюватися або обрізатися. Саме тому + існує пошук у memory — він повертає в контекст лише релевантні частини. - Документація: [Пам’ять](/uk/concepts/memory), [Контекст](/uk/concepts/context). + Документація: [Memory](/uk/concepts/memory), [Context](/uk/concepts/context). - - Лише якщо ви використовуєте **embeddings OpenAI**. Codex OAuth покриває chat/completions і - **не** надає доступу до embeddings, тому **вхід через Codex (OAuth або - вхід через Codex CLI)** не допомагає для семантичного пошуку в пам’яті. Для embeddings OpenAI + + Лише якщо ви використовуєте **OpenAI embeddings**. Codex OAuth покриває chat/completions і + **не** надає доступу до embeddings, тож **вхід через Codex (OAuth або + через логін Codex CLI)** не допомагає для семантичного пошуку в memory. Для OpenAI embeddings усе ще потрібен справжній API key (`OPENAI_API_KEY` або `models.providers.openai.apiKey`). - Якщо ви явно не задаєте provider, OpenClaw автоматично вибирає provider, коли може - розв’язати API key (профілі автентифікації, `models.providers.*.apiKey` або змінні середовища). - Він надає перевагу OpenAI, якщо вдається розв’язати ключ OpenAI, інакше Gemini, якщо вдається розв’язати ключ Gemini, - потім Voyage, потім Mistral. Якщо жоден віддалений ключ недоступний, пошук у пам’яті - лишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано і наявний шлях до локальної моделі, - OpenClaw - надає перевагу `local`. Ollama підтримується, коли ви явно задаєте + Якщо ви не задаєте провайдера явно, OpenClaw автоматично вибирає провайдера, коли + може знайти API key (профілі auth, `models.providers.*.apiKey` або env vars). + Він віддає перевагу OpenAI, якщо знайдено ключ OpenAI, інакше Gemini, якщо знайдено ключ Gemini, + потім Voyage, потім Mistral. Якщо жоден віддалений ключ недоступний, пошук у memory + залишається вимкненим, доки ви його не налаштуєте. Якщо у вас налаштовано й доступний шлях + до локальної моделі, OpenClaw + віддає перевагу `local`. Ollama підтримується, коли ви явно задаєте `memorySearch.provider = "ollama"`. - Якщо ви волієте залишатися локально, задайте `memorySearch.provider = "local"` (і за бажанням - `memorySearch.fallback = "none"`). Якщо ви хочете embeddings Gemini, задайте + Якщо ви хочете залишатися локальними, задайте `memorySearch.provider = "local"` (і за бажанням + `memorySearch.fallback = "none"`). Якщо вам потрібні Gemini embeddings, задайте `memorySearch.provider = "gemini"` і надайте `GEMINI_API_KEY` (або `memorySearch.remote.apiKey`). Ми підтримуємо embedding-моделі **OpenAI, Gemini, Voyage, Mistral, Ollama або local** — - див. [Пам’ять](/uk/concepts/memory) для деталей налаштування. + подробиці налаштування див. у [Memory](/uk/concepts/memory). @@ -1381,53 +1382,53 @@ x-i18n: ## Де що зберігається на диску - + Ні — **стан OpenClaw локальний**, але **зовнішні сервіси все одно бачать те, що ви їм надсилаєте**. - - **Локально за замовчуванням:** сесії, файли пам’яті, конфігурація та робочий простір живуть на хості Gateway - (`~/.openclaw` + каталог вашого робочого простору). - - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте provider моделей (Anthropic/OpenAI тощо), потрапляють до - їхніх API, а платформи чатів (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на своїх - серверах. - - **Ви керуєте відбитком:** використання локальних моделей зберігає prompt на вашій машині, але трафік + - **Локально за замовчуванням:** сесії, файли memory, конфігурація та workspace живуть на хості Gateway + (`~/.openclaw` + каталог вашого workspace). + - **Віддалено за необхідністю:** повідомлення, які ви надсилаєте провайдерам моделей (Anthropic/OpenAI тощо), потрапляють + до їхніх API, а chat platforms (WhatsApp/Telegram/Slack тощо) зберігають дані повідомлень на + своїх серверах. + - **Ви керуєте слідом даних:** використання локальних моделей залишає prompt на вашій машині, але трафік каналів усе одно проходить через сервери каналу. - Пов’язане: [Робочий простір агента](/uk/concepts/agent-workspace), [Пам’ять](/uk/concepts/memory). + Пов’язане: [Agent workspace](/uk/concepts/agent-workspace), [Memory](/uk/concepts/memory). - Усе живе в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): + Усе зберігається в `$OPENCLAW_STATE_DIR` (типово: `~/.openclaw`): - | Шлях | Призначення | - | -------------------------------------------------------------- | ----------------------------------------------------------------- | - | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | - | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Імпорт застарілого OAuth (копіюється в профілі автентифікації під час першого використання) | - | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі автентифікації (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | - | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язковий payload секретів у файлі для provider SecretRef типу `file` | - | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищуються) | - | `$OPENCLAW_STATE_DIR/credentials/` | Стан provider (наприклад, `whatsapp//creds.json`) | - | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + sessions) | - | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | - | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | + | Path | Призначення | + | --------------------------------------------------------------- | ----------------------------------------------------------------- | + | `$OPENCLAW_STATE_DIR/openclaw.json` | Основна конфігурація (JSON5) | + | `$OPENCLAW_STATE_DIR/credentials/oauth.json` | Застарілий імпорт OAuth (копіюється в профілі auth під час першого використання) | + | `$OPENCLAW_STATE_DIR/agents//agent/auth-profiles.json` | Профілі auth (OAuth, API keys і необов’язкові `keyRef`/`tokenRef`) | + | `$OPENCLAW_STATE_DIR/secrets.json` | Необов’язкове файлове сховище секретів для провайдерів SecretRef `file` | + | `$OPENCLAW_STATE_DIR/agents//agent/auth.json` | Файл застарілої сумісності (статичні записи `api_key` очищено) | + | `$OPENCLAW_STATE_DIR/credentials/` | Стан провайдера (наприклад `whatsapp//creds.json`) | + | `$OPENCLAW_STATE_DIR/agents/` | Стан для кожного агента (agentDir + sessions) | + | `$OPENCLAW_STATE_DIR/agents//sessions/` | Історія розмов і стан (для кожного агента) | + | `$OPENCLAW_STATE_DIR/agents//sessions/sessions.json` | Метадані сесій (для кожного агента) | - Застарілий шлях для одного агента: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`). + Застарілий шлях single-agent: `~/.openclaw/agent/*` (мігрується за допомогою `openclaw doctor`). - Ваш **робочий простір** (`AGENTS.md`, файли пам’яті, Skills тощо) є окремим і налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). + Ваш **workspace** (`AGENTS.md`, файли memory, Skills тощо) зберігається окремо й налаштовується через `agents.defaults.workspace` (типово: `~/.openclaw/workspace`). - Ці файли живуть у **робочому просторі агента**, а не в `~/.openclaw`. + Ці файли зберігаються у **workspace агента**, а не в `~/.openclaw`. - - **Робочий простір (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, + - **Workspace (для кожного агента)**: `AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `USER.md`, `MEMORY.md`, `memory/YYYY-MM-DD.md`, необов’язковий `HEARTBEAT.md`. - `memory.md` у нижньому регістрі в корені використовується лише як вхід для виправлення застарілого формату; `openclaw doctor --fix` - може об’єднати його в `MEMORY.md`, коли обидва файли існують. - - **Каталог стану (`~/.openclaw`)**: конфігурація, стан каналу/provider, профілі автентифікації, сесії, журнали, + Root-файл `memory.md` у нижньому регістрі — лише вхід для виправлення застарілих даних; `openclaw doctor --fix` + може об’єднати його в `MEMORY.md`, коли існують обидва файли. + - **Каталог state (`~/.openclaw`)**: конфігурація, стан channel/provider, профілі auth, сесії, журнали, і спільні Skills (`~/.openclaw/skills`). - Робочий простір за замовчуванням — `~/.openclaw/workspace`, налаштовується через: + Типовий workspace — `~/.openclaw/workspace`, налаштовується так: ```json5 { @@ -1436,43 +1437,43 @@ x-i18n: ``` Якщо бот «забуває» після перезапуску, переконайтеся, що Gateway використовує той самий - робочий простір під час кожного запуску (і пам’ятайте: віддалений режим використовує робочий простір **хоста gateway**, + workspace під час кожного запуску (і пам’ятайте: віддалений режим використовує **workspace хоста gateway**, а не вашого локального ноутбука). - Порада: якщо ви хочете зберегти поведінку або вподобання надовго, попросіть бота **записати це в - AGENTS.md або MEMORY.md**, а не покладатися на історію чату. + Порада: якщо вам потрібна стійка поведінка чи налаштування, попросіть бота **записати це в + AGENTS.md або MEMORY.md**, а не покладайтеся на історію чату. - Див. [Робочий простір агента](/uk/concepts/agent-workspace) і [Пам’ять](/uk/concepts/memory). + Див. [Agent workspace](/uk/concepts/agent-workspace) і [Memory](/uk/concepts/memory). - Розмістіть свій **робочий простір агента** у **приватному** git-репозиторії та створюйте його резервні копії десь - у приватному місці (наприклад, GitHub private). Це захоплює пам’ять + файли AGENTS/SOUL/USER - і дає змогу пізніше відновити «свідомість» асистента. + Розмістіть свій **workspace агента** в **приватному** git-репозиторії та створюйте його резервну копію + у приватному місці (наприклад, у приватному GitHub). Це охоплює memory + файли AGENTS/SOUL/USER + і дозволяє пізніше відновити «розум» помічника. - **Не** робіть commit нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані payload секретів). - Якщо вам потрібне повне відновлення, окремо створюйте резервні копії і робочого простору, і каталогу стану - (див. питання про міграцію вище). + **Не** робіть commit нічого з `~/.openclaw` (облікові дані, сесії, токени або зашифровані дані секретів). + Якщо вам потрібне повне відновлення, створюйте резервні копії і workspace, і каталогу state + окремо (див. питання про міграцію вище). - Документація: [Робочий простір агента](/uk/concepts/agent-workspace). + Документація: [Agent workspace](/uk/concepts/agent-workspace). - Див. окремий посібник: [Видалення](/uk/install/uninstall). + Див. окремий посібник: [Uninstall](/uk/install/uninstall). - - Так. Робочий простір — це **cwd за замовчуванням** і прив’язка пам’яті, а не жорстка пісочниця. - Відносні шляхи розв’язуються в межах робочого простору, але абсолютні шляхи можуть отримувати доступ до інших - місць на хості, якщо пісочниця не ввімкнена. Якщо вам потрібна ізоляція, використовуйте - [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування пісочниці для окремого агента. Якщо ви - хочете, щоб репозиторій був робочим каталогом за замовчуванням, вкажіть для цього агента - `workspace` на корінь репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте - робочий простір окремо, якщо тільки ви свідомо не хочете, щоб агент працював усередині нього. + + Так. Workspace — це **типовий cwd** і опорна точка для memory, а не жорсткий sandbox. + Відносні шляхи розв’язуються всередині workspace, але абсолютні шляхи можуть відкривати доступ до інших + місць на хості, якщо sandboxing не ввімкнено. Якщо вам потрібна ізоляція, використовуйте + [`agents.defaults.sandbox`](/uk/gateway/sandboxing) або налаштування sandbox для окремих агентів. Якщо ви + хочете, щоб репозиторій був типовим робочим каталогом, вкажіть для цього агента + `workspace` як root репозиторію. Репозиторій OpenClaw — це лише вихідний код; тримайте + workspace окремо, якщо тільки ви навмисно не хочете, щоб агент працював усередині нього. - Приклад (репозиторій як cwd за замовчуванням): + Приклад (репозиторій як типовий cwd): ```json5 { @@ -1486,30 +1487,30 @@ x-i18n: - - Станом сесій володіє **хост gateway**. Якщо ви в віддаленому режимі, важливе для вас сховище сесій перебуває на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Керування сесіями](/uk/concepts/session). + + Станом сесій володіє **хост gateway**. Якщо ви працюєте у віддаленому режимі, потрібне вам сховище сесій знаходиться на віддаленій машині, а не на вашому локальному ноутбуці. Див. [Session management](/uk/concepts/session). ## Основи конфігурації - + OpenClaw читає необов’язкову конфігурацію **JSON5** з `$OPENCLAW_CONFIG_PATH` (типово: `~/.openclaw/openclaw.json`): ``` $OPENCLAW_CONFIG_PATH ``` - Якщо файл відсутній, використовуються відносно безпечні типові значення (зокрема типовий робочий простір `~/.openclaw/workspace`). + Якщо файл відсутній, використовуються відносно безпечні значення за замовчуванням (зокрема workspace за замовчуванням `~/.openclaw/workspace`). - Прив’язки не до loopback **потребують коректного шляху автентифікації gateway**. На практиці це означає: + Прив’язки не до loopback **потребують чинного шляху auth gateway**. На практиці це означає: - - автентифікація спільним секретом: токен або пароль - - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим reverse proxy з обізнаністю про ідентичність, не на loopback + - auth зі спільним секретом: токен або пароль + - `gateway.auth.mode: "trusted-proxy"` за правильно налаштованим identity-aware reverse proxy не на loopback ```json5 { @@ -1525,32 +1526,32 @@ x-i18n: Примітки: - - `gateway.remote.token` / `.password` самі по собі **не** вмикають локальну автентифікацію gateway. + - `gateway.remote.token` / `.password` **самі по собі** не вмикають auth локального gateway. - Локальні шляхи виклику можуть використовувати `gateway.remote.*` як fallback лише тоді, коли `gateway.auth.*` не задано. - - Для автентифікації паролем установіть `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). - - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і його не вдається розв’язати, розв’язання закривається на відмову (без маскування віддаленим fallback). - - Налаштування спільного секрету Control UI проходять автентифікацію через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях застосунку/UI). Режими з передаванням ідентичності, як-от Tailscale Serve або `trusted-proxy`, натомість використовують заголовки запиту. Уникайте розміщення спільних секретів в URL. - - З `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback на тому самому хості все одно **не** задовольняють автентифікацію trusted-proxy. Trusted proxy має бути налаштованим джерелом не на loopback. + - Для auth через пароль задайте `gateway.auth.mode: "password"` разом із `gateway.auth.password` (або `OPENCLAW_GATEWAY_PASSWORD`). + - Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і не розв’язано, розв’язання безпечно завершується помилкою (без маскування через віддалений fallback). + - Налаштування Control UI зі спільним секретом автентифікуються через `connect.params.auth.token` або `connect.params.auth.password` (зберігаються в налаштуваннях app/UI). Режими з ідентифікацією, такі як Tailscale Serve або `trusted-proxy`, замість цього використовують заголовки запиту. Не розміщуйте спільні секрети в URL. + - З `gateway.auth.mode: "trusted-proxy"` reverse proxy на loopback того самого хоста все одно **не** задовольняють auth trusted-proxy. Trusted proxy має бути налаштованим джерелом не на loopback. - - OpenClaw типово примусово застосовує автентифікацію gateway, зокрема і на loopback. У звичайному типовому сценарії це означає автентифікацію токеном: якщо явний шлях автентифікації не налаштовано, під час запуску gateway вибирається режим токена й автоматично генерується токен, який зберігається в `gateway.auth.token`, тож **локальні WS-клієнти мають проходити автентифікацію**. Це блокує іншим локальним процесам можливість викликати Gateway. + + OpenClaw примусово вимагає auth gateway за замовчуванням, включно з loopback. У звичайному типовому сценарії це означає auth через токен: якщо явний шлях auth не налаштовано, під час запуску gateway вибирається режим токена й він автоматично генерується, зберігаючись у `gateway.auth.token`, тому **локальні WS-клієнти повинні автентифікуватися**. Це блокує доступ інших локальних процесів до Gateway. - Якщо ви віддаєте перевагу іншому шляху автентифікації, можна явно вибрати режим пароля (або, для reverse proxy з awareness про ідентичність не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно встановіть `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен будь-коли: `openclaw doctor --generate-gateway-token`. + Якщо ви віддаєте перевагу іншому шляху auth, можете явно вибрати режим пароля (або, для identity-aware reverse proxy не на loopback, `trusted-proxy`). Якщо ви **справді** хочете відкритий loopback, явно задайте `gateway.auth.mode: "none"` у конфігурації. Doctor може згенерувати токен для вас будь-коли: `openclaw doctor --generate-gateway-token`. - - Gateway відстежує конфігурацію та підтримує гаряче перезавантаження: + + Gateway відстежує конфігурацію і підтримує hot-reload: - - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує hot-зміни, для критичних виконує перезапуск + - `gateway.reload.mode: "hybrid"` (типово): безпечно застосовує hot-зміни, а для критичних виконує перезапуск - також підтримуються `hot`, `restart`, `off` - Установіть `cli.banner.taglineMode` у конфігурації: + Задайте `cli.banner.taglineMode` у конфігурації: ```json5 { @@ -1562,24 +1563,24 @@ x-i18n: } ``` - - `off`: приховує текст слогана, але зберігає рядок заголовка/версії банера. + - `off`: приховує текст слогана, але залишає рядок заголовка/version banner. - `default`: щоразу використовує `All your chats, one OpenClaw.`. - - `random`: обертові кумедні/сезонні слогани (поведінка за замовчуванням). - - Якщо ви хочете повністю прибрати банер, установіть змінну середовища `OPENCLAW_HIDE_BANNER=1`. + - `random`: ротація кумедних/сезонних слоганів (типова поведінка). + - Якщо ви хочете повністю прибрати banner, задайте env `OPENCLAW_HIDE_BANNER=1`. - + `web_fetch` працює без API key. `web_search` залежить від вибраного - provider: + провайдера: - - Provider-и на основі API, як-от Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. + - Провайдери на основі API, такі як Brave, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Perplexity і Tavily, потребують звичайного налаштування API key. - Ollama Web Search не потребує ключа, але використовує налаштований хост Ollama і вимагає `ollama signin`. - DuckDuckGo не потребує ключа, але це неофіційна інтеграція на основі HTML. - - SearXNG не потребує ключа / є self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. + - SearXNG не потребує ключа / може бути self-hosted; налаштуйте `SEARXNG_BASE_URL` або `plugins.entries.searxng.config.webSearch.baseUrl`. - **Рекомендовано:** виконайте `openclaw configure --section web` і виберіть provider. - Альтернативи через змінні середовища: + **Рекомендовано:** запустіть `openclaw configure --section web` і виберіть провайдера. + Альтернативи через середовище: - Brave: `BRAVE_API_KEY` - Exa: `EXA_API_KEY` @@ -1621,64 +1622,64 @@ x-i18n: } ``` - Конфігурація вебпошуку для конкретного provider тепер розташована в `plugins.entries..config.webSearch.*`. - Застарілі шляхи provider у `tools.web.search.*` усе ще тимчасово завантажуються для сумісності, але їх не слід використовувати в нових конфігураціях. - Конфігурація fallback для web fetch у Firecrawl міститься в `plugins.entries.firecrawl.config.webFetch.*`. + Конфігурація web-search для конкретного провайдера тепер розміщується в `plugins.entries..config.webSearch.*`. + Застарілі шляхи провайдера `tools.web.search.*` тимчасово все ще завантажуються для сумісності, але не повинні використовуватися в нових конфігураціях. + Конфігурація fallback для Firecrawl web-fetch розміщується в `plugins.entries.firecrawl.config.webFetch.*`. Примітки: - - Якщо ви використовуєте allowlist, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. - - `web_fetch` типово увімкнений (якщо явно не вимкнено). - - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає перший готовий fallback provider для fetch за наявними обліковими даними. Наразі вбудований provider — Firecrawl. - - Daemon-и читають змінні середовища з `~/.openclaw/.env` (або із середовища service). + - Якщо ви використовуєте allowlists, додайте `web_search`/`web_fetch`/`x_search` або `group:web`. + - `web_fetch` увімкнено за замовчуванням (якщо не вимкнено явно). + - Якщо `tools.web.fetch.provider` пропущено, OpenClaw автоматично визначає першого готового fallback-провайдера fetch серед доступних облікових даних. Наразі вбудований провайдер — Firecrawl. + - Демони читають env vars з `~/.openclaw/.env` (або з оточення сервісу). - Документація: [Вебінструменти](/uk/tools/web). + Документація: [Web tools](/uk/tools/web). - + `config.apply` замінює **всю конфігурацію**. Якщо ви надсилаєте частковий об’єкт, усе інше видаляється. - Поточний OpenClaw захищає від багатьох випадкових затирань: + Поточна версія OpenClaw захищає від багатьох випадкових руйнівних перезаписів: - - Записи конфігурації, якими керує OpenClaw, перевіряють повну конфігурацію після змін перед записом. - - Невалідні або руйнівні записи, якими керує OpenClaw, відхиляються та зберігаються як `openclaw.json.rejected.*`. - - Якщо пряме редагування ламає запуск або hot reload, Gateway відновлює останню відому коректну конфігурацію і зберігає відхилений файл як `openclaw.json.clobbered.*`. - - Після відновлення основний агент отримує попередження під час завантаження, щоб не переписати погану конфігурацію знову навмання. + - Записи конфігурації, керовані OpenClaw, перевіряють повну конфігурацію після зміни перед записом. + - Некоректні або руйнівні записи, керовані OpenClaw, відхиляються і зберігаються як `openclaw.json.rejected.*`. + - Якщо пряме редагування ламає запуск або hot reload, Gateway відновлює останню коректну конфігурацію і зберігає відхилений файл як `openclaw.json.clobbered.*`. + - Після відновлення основний агент отримує попередження під час запуску, щоб не записувати некоректну конфігурацію повторно навмання. Відновлення: - Перевірте `openclaw logs --follow` на наявність `Config auto-restored from last-known-good`, `Config write rejected:` або `config reload restored last-known-good config`. - Перегляньте найновіший `openclaw.json.clobbered.*` або `openclaw.json.rejected.*` поруч з активною конфігурацією. - - Залиште активну відновлену конфігурацію, якщо вона працює, а потім поверніть лише потрібні ключі за допомогою `openclaw config set` або `config.patch`. - - Виконайте `openclaw config validate` і `openclaw doctor`. - - Якщо у вас немає last-known-good або відхиленого payload, відновіть із резервної копії або повторно виконайте `openclaw doctor` і заново налаштуйте канали/моделі. - - Якщо це було неочікувано, створіть bug report і додайте останню відому конфігурацію або будь-яку резервну копію. - - Локальний агент для програмування часто може відновити робочу конфігурацію з журналів або історії. + - Залиште активну відновлену конфігурацію, якщо вона працює, потім поверніть лише потрібні ключі через `openclaw config set` або `config.patch`. + - Запустіть `openclaw config validate` і `openclaw doctor`. + - Якщо у вас немає last-known-good або відхиленого payload, відновіть із резервної копії або повторно запустіть `openclaw doctor` і заново налаштуйте channels/models. + - Якщо це було неочікувано, створіть bug report і додайте вашу останню відому конфігурацію або будь-яку резервну копію. + - Локальний coding agent часто може відновити робочу конфігурацію з журналів або історії. - Як уникнути: + Як уникнути цього: - Використовуйте `openclaw config set` для невеликих змін. - Використовуйте `openclaw configure` для інтерактивного редагування. - - Спочатку використовуйте `config.schema.lookup`, якщо ви не впевнені в точному шляху або формі поля; він повертає поверхневий вузол схеми плюс короткі описи безпосередніх дочірніх елементів для подальшого заглиблення. - - Використовуйте `config.patch` для часткових редагувань через RPC; залишайте `config.apply` лише для повної заміни конфігурації. - - Якщо ви використовуєте інструмент `gateway`, доступний лише owner, із запуску агента, він усе одно відхилятиме записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими псевдонімами `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). + - Спочатку використовуйте `config.schema.lookup`, коли не впевнені щодо точного шляху або форми поля; він повертає неглибокий вузол схеми та підсумки безпосередніх дочірніх елементів для подальшого перегляду. + - Використовуйте `config.patch` для часткових RPC-редагувань; залишайте `config.apply` лише для повної заміни конфігурації. + - Якщо ви використовуєте доступний лише owner інструмент `gateway` із запуску агента, він усе одно відхиляє записи в `tools.exec.ask` / `tools.exec.security` (включно із застарілими alias `tools.bash.*`, які нормалізуються до тих самих захищених шляхів exec). - Документація: [Конфігурація](/uk/cli/config), [Налаштування](/uk/cli/configure), [Усунення несправностей Gateway](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). + Документація: [Config](/uk/cli/config), [Configure](/uk/cli/configure), [Gateway troubleshooting](/uk/gateway/troubleshooting#gateway-restored-last-known-good-config), [Doctor](/uk/gateway/doctor). - - Типовий шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **Node-и** та **агенти**: + + Найпоширеніший шаблон — **один Gateway** (наприклад, Raspberry Pi) плюс **nodes** і **agents**: - - **Gateway (центральний):** володіє каналами (Signal/WhatsApp), маршрутизацією та сесіями. - - **Node-и (пристрої):** Mac/iOS/Android підключаються як периферія та надають локальні інструменти (`system.run`, `canvas`, `camera`). - - **Агенти (worker-и):** окремі «мозки»/робочі простори для спеціалізованих ролей (наприклад, "Hetzner ops", "Personal data"). - - **Sub-agent:** запускають фонову роботу з основного агента, коли вам потрібен паралелізм. - - **TUI:** підключається до Gateway і дає змогу перемикати агентів/сесії. + - **Gateway (центральний):** володіє channels (Signal/WhatsApp), маршрутизацією та сесіями. + - **Nodes (пристрої):** Mac/iOS/Android підключаються як периферія і надають локальні tools (`system.run`, `canvas`, `camera`). + - **Agents (воркери):** окремі brain/workspace для спеціальних ролей (наприклад, «Hetzner ops», «Personal data»). + - **Sub-agents:** запускають фонову роботу з основного агента, коли потрібен паралелізм. + - **TUI:** підключається до Gateway і перемикає agents/sessions. - Документація: [Node-и](/uk/nodes), [Віддалений доступ](/uk/gateway/remote), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Sub-agent](/uk/tools/subagents), [TUI](/uk/web/tui). + Документація: [Nodes](/uk/nodes), [Remote access](/uk/gateway/remote), [Multi-Agent Routing](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [TUI](/uk/web/tui). @@ -1696,150 +1697,150 @@ x-i18n: } ``` - Типове значення — `false` (із видимим вікном). Headless-режим із більшою ймовірністю викликає перевірки anti-bot на деяких сайтах. Див. [Browser](/uk/tools/browser). + Значення за замовчуванням — `false` (із видимим вікном). Headless-режим з більшою ймовірністю викликає anti-bot перевірки на деяких сайтах. Див. [Browser](/uk/tools/browser). - Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, збирання даних, входи). Основні відмінності: + Headless використовує **той самий рушій Chromium** і працює для більшості сценаріїв автоматизації (форми, кліки, скрейпінг, логіни). Основні відмінності: - - Немає видимого вікна браузера (використовуйте знімки екрана, якщо вам потрібна візуалізація). + - Немає видимого вікна браузера (використовуйте знімки екрана, якщо потрібна візуалізація). - Деякі сайти суворіше ставляться до автоматизації в headless-режимі (CAPTCHA, anti-bot). Наприклад, X/Twitter часто блокує headless-сесії. - Установіть `browser.executablePath` на ваш бінарний файл Brave (або будь-який браузер на базі Chromium) і перезапустіть Gateway. + Задайте `browser.executablePath` для вашого бінарного файлу Brave (або будь-якого браузера на базі Chromium) і перезапустіть Gateway. Повні приклади конфігурації див. у [Browser](/uk/tools/browser#use-brave-or-another-chromium-based-browser). -## Віддалені gateway і Node-и +## Віддалені gateway і nodes - + Повідомлення Telegram обробляються **gateway**. Gateway запускає агента і - лише потім викликає Node-и через **Gateway WebSocket**, коли потрібен інструмент node: + лише потім викликає nodes через **Gateway WebSocket**, коли потрібен tool вузла: - Telegram → Gateway → Агент → `node.*` → Node → Gateway → Telegram + Telegram → Gateway → Agent → `node.*` → Node → Gateway → Telegram - Node-и не бачать вхідний трафік provider; вони лише отримують виклики node RPC. + Nodes не бачать вхідний трафік провайдера; вони отримують лише виклики node RPC. - - Коротка відповідь: **під’єднайте свій комп’ютер як Node**. Gateway працює деінде, але він може - викликати інструменти `node.*` (screen, camera, system) на вашій локальній машині через Gateway WebSocket. + + Коротка відповідь: **підключіть свій комп’ютер як Node**. Gateway працює в іншому місці, але він може + викликати tools `node.*` (екран, камера, система) на вашій локальній машині через Gateway WebSocket. Типове налаштування: - 1. Запустіть Gateway на хості, що завжди працює (VPS/домашній сервер). + 1. Запустіть Gateway на хості, який завжди увімкнений (VPS/домашній сервер). 2. Додайте хост Gateway і ваш комп’ютер до однієї tailnet. - 3. Переконайтеся, що Gateway WS доступний (tailnet bind або SSH tunnel). - 4. Відкрийте застосунок macOS локально і підключіться в режимі **Remote over SSH** (або напряму через tailnet) + 3. Переконайтеся, що Gateway WS доступний (прив’язка tailnet або SSH tunnel). + 4. Відкрийте застосунок macOS локально і підключіться в режимі **Remote over SSH** (або напряму через tailnet), щоб він міг зареєструватися як Node. - 5. Погодьте Node на Gateway: + 5. Підтвердьте Node на Gateway: ```bash openclaw devices list openclaw devices approve ``` - Окремий TCP-міст не потрібен; Node-и підключаються через Gateway WebSocket. + Окремий TCP bridge не потрібен; nodes підключаються через Gateway WebSocket. - Нагадування щодо безпеки: під’єднання macOS Node дозволяє `system.run` на цій машині. Під’єднуйте - лише пристрої, яким довіряєте, і ознайомтеся з [Безпекою](/uk/gateway/security). + Нагадування щодо безпеки: підключення macOS Node дозволяє `system.run` на цій машині. Підключайте + лише пристрої, яким довіряєте, і перегляньте [Security](/uk/gateway/security). - Документація: [Node-и](/uk/nodes), [Протокол Gateway](/uk/gateway/protocol), [Віддалений режим macOS](/uk/platforms/mac/remote), [Безпека](/uk/gateway/security). + Документація: [Nodes](/uk/nodes), [Gateway protocol](/uk/gateway/protocol), [macOS remote mode](/uk/platforms/mac/remote), [Security](/uk/gateway/security). - + Перевірте базові речі: - - Gateway запущено: `openclaw gateway status` + - Gateway запущений: `openclaw gateway status` - Стан Gateway: `openclaw status` - - Стан каналів: `openclaw channels status` + - Стан channel: `openclaw channels status` - Потім перевірте автентифікацію та маршрутизацію: + Потім перевірте auth і маршрутизацію: - - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` налаштовано правильно. - - Якщо ви підключаєтеся через SSH tunnel, переконайтеся, що локальний tunnel активний і вказує на правильний порт. - - Переконайтеся, що ваші allowlist (DM або група) містять ваш обліковий запис. + - Якщо ви використовуєте Tailscale Serve, переконайтеся, що `gateway.auth.allowTailscale` задано правильно. + - Якщо ви підключаєтеся через SSH tunnel, переконайтеся, що локальний тунель піднятий і вказує на правильний порт. + - Переконайтеся, що ваші allowlists (DM або group) включають ваш обліковий запис. - Документація: [Tailscale](/uk/gateway/tailscale), [Віддалений доступ](/uk/gateway/remote), [Канали](/uk/channels). + Документація: [Tailscale](/uk/gateway/tailscale), [Remote access](/uk/gateway/remote), [Channels](/uk/channels). - - Так. Вбудованого мосту «бот-до-бота» немає, але це можна налаштувати кількома + + Так. Вбудованого мосту «bot-to-bot» немає, але це можна налаштувати кількома надійними способами: - **Найпростіше:** використовуйте звичайний чат-канал, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). - Нехай Bot A надішле повідомлення Bot B, а потім Bot B відповість як зазвичай. + **Найпростіше:** використовуйте звичайний chat channel, до якого мають доступ обидва боти (Telegram/Slack/WhatsApp). + Нехай Bot A надсилає повідомлення Bot B, а Bot B відповідає як зазвичай. - **CLI-міст (загальний):** запустіть скрипт, який викликає інший Gateway через - `openclaw agent --message ... --deliver`, націлюючись на чат, де слухає інший бот. - Якщо один бот працює на віддаленому VPS, направте свій CLI на цей віддалений Gateway - через SSH/Tailscale (див. [Віддалений доступ](/uk/gateway/remote)). + **Міст через CLI (універсально):** запустіть скрипт, який викликає інший Gateway за допомогою + `openclaw agent --message ... --deliver`, націливши його на чат, який слухає інший бот. + Якщо один бот розміщений на віддаленому VPS, направте свій CLI на цей віддалений Gateway + через SSH/Tailscale (див. [Remote access](/uk/gateway/remote)). - Приклад шаблону (запускати з машини, яка може дістатися до цільового Gateway): + Приклад шаблону (запускається з машини, яка може дістатися до цільового Gateway): ```bash openclaw agent --message "Hello from local bot" --deliver --channel telegram --reply-to ``` - Порада: додайте запобіжник, щоб два боти не зациклилися безкінечно (лише згадки, channel - allowlist або правило «не відповідати на повідомлення ботів»). + Порада: додайте запобіжник, щоб два боти не зациклилися нескінченно (відповіді лише на згадки, channel + allowlists або правило «не відповідати на повідомлення ботів»). - Документація: [Віддалений доступ](/uk/gateway/remote), [CLI Agent](/uk/cli/agent), [Надсилання Agent](/uk/tools/agent-send). + Документація: [Remote access](/uk/gateway/remote), [Agent CLI](/uk/cli/agent), [Agent send](/uk/tools/agent-send). - Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм робочим простором, типовими моделями - і маршрутизацією. Це звичайне налаштування, і воно набагато дешевше та простіше, ніж запускати - окремий VPS для кожного агента. + Ні. Один Gateway може розміщувати кількох агентів, кожен зі своїм workspace, типовими моделями + та маршрутизацією. Це нормальна конфігурація, і вона значно дешевша та простіша, ніж запускати + один VPS на кожного агента. Використовуйте окремі VPS лише тоді, коли вам потрібна жорстка ізоляція (межі безпеки) або дуже - різні конфігурації, які ви не хочете спільно використовувати. В іншому разі тримайте один Gateway і - використовуйте кількох агентів або sub-agent. + різні конфігурації, якими ви не хочете ділитися. В іншому разі залишайте один Gateway і + використовуйте кількох агентів або sub-agents. - - Так — Node-и є пріоритетним способом доступу до вашого ноутбука з віддаленого Gateway, і вони + + Так — nodes є основним способом доступу до вашого ноутбука з віддаленого Gateway, і вони дають більше, ніж просто доступ до оболонки. Gateway працює на macOS/Linux (Windows через WSL2) і є - легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 GB RAM більш ніж достатньо), тому поширеним - варіантом є хост, що завжди працює, плюс ваш ноутбук як Node. + легким (достатньо невеликого VPS або пристрою класу Raspberry Pi; 4 GB RAM більш ніж достатньо), тож поширений + сценарій — це хост, що завжди увімкнений, плюс ваш ноутбук як Node. - - **Не потрібен вхідний SSH.** Node-и самі підключаються до Gateway WebSocket і використовують спарювання пристроїв. - - **Безпечніший контроль виконання.** `system.run` обмежується allowlist/погодженнями Node на цьому ноутбуці. - - **Більше інструментів пристрою.** Node-и надають `canvas`, `camera` і `screen` на додачу до `system.run`. - - **Локальна автоматизація браузера.** Тримайте Gateway на VPS, але запускайте Chrome локально через хост Node на ноутбуці або під’єднуйтеся до локального Chrome на хості через Chrome MCP. + - **Не потрібен вхідний SSH.** Nodes самі підключаються до Gateway WebSocket і використовують pairing пристрою. + - **Безпечніший контроль виконання.** `system.run` на цьому ноутбуці обмежується allowlists/підтвердженнями Node. + - **Більше інструментів пристрою.** Nodes надають `canvas`, `camera` і `screen` на додачу до `system.run`. + - **Локальна browser automation.** Тримайте Gateway на VPS, але запускайте Chrome локально через node host на ноутбуці або підключайтеся до локального Chrome на хості через Chrome MCP. - SSH підходить для разового доступу до оболонки, але Node-и простіші для постійних робочих процесів агента і - автоматизації пристроїв. + SSH підходить для епізодичного доступу до оболонки, але nodes простіші для постійних workflow агента та + автоматизації пристрою. - Документація: [Node-и](/uk/nodes), [CLI Node-ів](/uk/cli/nodes), [Browser](/uk/tools/browser). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/uk/cli/nodes), [Browser](/uk/tools/browser). - - Ні. На хості має працювати лише **один gateway**, якщо тільки ви свідомо не запускаєте ізольовані профілі (див. [Кілька gateway](/uk/gateway/multiple-gateways)). Node-и — це периферія, яка підключається - до gateway (Node-и iOS/Android або режим macOS "node mode" у застосунку menubar). Для headless - хостів Node та керування через CLI див. [CLI Node host](/uk/cli/node). + + Ні. На одному хості має працювати лише **один gateway**, якщо тільки ви навмисно не запускаєте ізольовані профілі (див. [Multiple gateways](/uk/gateway/multiple-gateways)). Nodes — це периферійні компоненти, які підключаються + до gateway (nodes iOS/Android або macOS у «режимі node» в застосунку меню-бару). Для headless node + hosts і керування через CLI див. [Node host CLI](/uk/cli/node). - Повний перезапуск потрібен для змін `gateway`, `discovery` і `canvasHost`. + Для змін `gateway`, `discovery` і `canvasHost` потрібен повний перезапуск. Так. - - `config.schema.lookup`: перевіряє одне піддерево конфігурації разом із його поверхневим вузлом схеми, відповідною підказкою UI та короткими описами безпосередніх дочірніх елементів перед записом - - `config.get`: отримує поточний знімок + hash - - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); виконує hot-reload, коли можливо, і перезапуск, коли потрібно - - `config.apply`: перевіряє + замінює всю конфігурацію; виконує hot-reload, коли можливо, і перезапуск, коли потрібно - - Інструмент виконання `gateway`, доступний лише owner, як і раніше, відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі псевдоніми `tools.bash.*` нормалізуються до тих самих захищених шляхів exec + - `config.schema.lookup`: перевірити одне піддерево конфігурації з його неглибоким вузлом схеми, підібраною підказкою UI та підсумками безпосередніх дочірніх елементів перед записом + - `config.get`: отримати поточний snapshot + hash + - `config.patch`: безпечне часткове оновлення (рекомендовано для більшості RPC-редагувань); виконує hot-reload, коли це можливо, і перезапуск, коли потрібно + - `config.apply`: перевіряє й замінює повну конфігурацію; виконує hot-reload, коли це можливо, і перезапуск, коли потрібно + - Доступний лише owner runtime tool `gateway` усе одно відмовляється переписувати `tools.exec.ask` / `tools.exec.security`; застарілі alias `tools.bash.*` нормалізуються до тих самих захищених шляхів exec @@ -1851,29 +1852,29 @@ x-i18n: } ``` - Це задає ваш робочий простір і обмежує коло тих, хто може активувати бота. + Це задає ваш workspace і обмежує, хто може активувати бота. Мінімальні кроки: - 1. **Установіть + увійдіть на VPS** + 1. **Встановлення + вхід на VPS** ```bash curl -fsSL https://tailscale.com/install.sh | sh sudo tailscale up ``` - 2. **Установіть + увійдіть на Mac** - - Використовуйте застосунок Tailscale і ввійдіть у ту саму tailnet. + 2. **Встановлення + вхід на Mac** + - Використайте застосунок Tailscale і увійдіть у ту саму tailnet. 3. **Увімкніть MagicDNS (рекомендовано)** - - В адмінконсолі Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. - 4. **Використовуйте hostname tailnet** + - У консолі адміністрування Tailscale увімкніть MagicDNS, щоб VPS мав стабільне ім’я. + 4. **Використовуйте ім’я хоста tailnet** - SSH: `ssh user@your-vps.tailnet-xxxx.ts.net` - Gateway WS: `ws://your-vps.tailnet-xxxx.ts.net:18789` - Якщо ви хочете Control UI без SSH, використовуйте Tailscale Serve на VPS: + Якщо вам потрібен Control UI без SSH, використайте Tailscale Serve на VPS: ```bash openclaw gateway --tailscale serve @@ -1884,48 +1885,48 @@ x-i18n: - Serve відкриває **Gateway Control UI + WS**. Node-и підключаються через той самий endpoint Gateway WS. + Serve відкриває **Gateway Control UI + WS**. Nodes підключаються через ту саму кінцеву точку Gateway WS. Рекомендоване налаштування: - 1. **Переконайтеся, що VPS і Mac перебувають в одній tailnet**. - 2. **Використовуйте застосунок macOS у віддаленому режимі** (SSH-ціллю може бути hostname tailnet). - Застосунок пробросить порт Gateway і підключиться як Node. - 3. **Погодьте Node** на gateway: + 1. **Переконайтеся, що VPS + Mac перебувають в одній tailnet**. + 2. **Використовуйте застосунок macOS у віддаленому режимі** (SSH-ціллю може бути ім’я хоста tailnet). + Застосунок протунелює порт Gateway і підключиться як Node. + 3. **Підтвердьте Node** на gateway: ```bash openclaw devices list openclaw devices approve ``` - Документація: [Протокол Gateway](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [Віддалений режим macOS](/uk/platforms/mac/remote). + Документація: [Gateway protocol](/uk/gateway/protocol), [Discovery](/uk/gateway/discovery), [macOS remote mode](/uk/platforms/mac/remote). - - Якщо вам потрібні лише **локальні інструменти** (screen/camera/exec) на другому ноутбуці, додайте його як - **Node**. Це зберігає один Gateway і дозволяє уникнути дублювання конфігурації. Локальні інструменти Node - наразі доступні лише на macOS, але ми плануємо поширити їх і на інші ОС. + + Якщо вам потрібні лише **локальні tools** (screen/camera/exec) на другому ноутбуці, додайте його як + **Node**. Це дозволяє зберегти один Gateway і уникнути дублювання конфігурації. Локальні node tools + наразі доступні лише на macOS, але ми плануємо поширити їх на інші ОС. - Установлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. + Встановлюйте другий Gateway лише тоді, коли вам потрібна **жорстка ізоляція** або два повністю окремі боти. - Документація: [Node-и](/uk/nodes), [CLI Node-ів](/uk/cli/nodes), [Кілька gateway](/uk/gateway/multiple-gateways). + Документація: [Nodes](/uk/nodes), [Nodes CLI](/uk/cli/nodes), [Multiple gateways](/uk/gateway/multiple-gateways). -## Змінні середовища та завантаження .env +## Env vars і завантаження .env - OpenClaw читає змінні середовища з батьківського процесу (оболонка, launchd/systemd, CI тощо) і додатково завантажує: + OpenClaw читає env vars з батьківського процесу (shell, launchd/systemd, CI тощо) і додатково завантажує: - `.env` з поточного робочого каталогу - - глобальний резервний `.env` із `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) + - глобальний fallback `.env` з `~/.openclaw/.env` (тобто `$OPENCLAW_STATE_DIR/.env`) - Жоден із файлів `.env` не перевизначає вже наявні змінні середовища. + Жоден із `.env` файлів не перевизначає вже наявні env vars. - Ви також можете визначати вбудовані змінні середовища в конфігурації (застосовуються лише за відсутності в середовищі процесу): + Ви також можете визначити вбудовані env vars у конфігурації (застосовуються лише якщо їх немає в env процесу): ```json5 { @@ -1936,15 +1937,15 @@ x-i18n: } ``` - Див. [/environment](/uk/help/environment) для повного порядку пріоритетів і джерел. + Повний порядок пріоритетів і джерела див. у [/environment](/uk/help/environment). - - Є два поширені виправлення: + + Є два поширені способи виправити це: - 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися навіть тоді, коли service не успадковує середовище вашої оболонки. - 2. Увімкніть імпорт із оболонки (зручність за запитом): + 1. Помістіть відсутні ключі в `~/.openclaw/.env`, щоб вони підхоплювалися, навіть коли сервіс не успадковує env вашої shell. + 2. Увімкніть імпорт shell (зручна опція за бажанням): ```json5 { @@ -1957,18 +1958,18 @@ x-i18n: } ``` - Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти змінних середовища: + Це запускає вашу login shell і імпортує лише відсутні очікувані ключі (ніколи не перевизначає наявні). Еквіваленти env vars: `OPENCLAW_LOAD_SHELL_ENV=1`, `OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000`. - - `openclaw models status` повідомляє, чи ввімкнено **імпорт змінних середовища з оболонки**. "Shell env: off" - **не** означає, що ваші змінні середовища відсутні — це лише означає, що OpenClaw не завантажуватиме + + `openclaw models status` повідомляє, чи увімкнено **імпорт shell env**. "Shell env: off" + **не** означає, що ваші env vars відсутні — це лише означає, що OpenClaw не завантажуватиме вашу login shell автоматично. - Якщо Gateway працює як service (launchd/systemd), він не успадковує середовище вашої оболонки. - Виправлення — зробіть одне з наведеного: + Якщо Gateway працює як сервіс (launchd/systemd), він не успадковує середовище + вашої shell. Виправити це можна одним із таких способів: 1. Помістіть токен у `~/.openclaw/.env`: @@ -1976,8 +1977,8 @@ x-i18n: COPILOT_GITHUB_TOKEN=... ``` - 2. Або увімкніть імпорт із оболонки (`env.shellEnv.enabled: true`). - 3. Або додайте його в блок `env` конфігурації (застосовується лише за відсутності). + 2. Або увімкніть імпорт shell (`env.shellEnv.enabled: true`). + 3. Або додайте його в блок `env` конфігурації (застосовується лише якщо він відсутній). Потім перезапустіть gateway і перевірте ще раз: @@ -1995,14 +1996,14 @@ x-i18n: - Надішліть `/new` або `/reset` окремим повідомленням. Див. [Керування сесіями](/uk/concepts/session). + Надішліть `/new` або `/reset` як окреме повідомлення. Див. [Session management](/uk/concepts/session). - Термін дії сесій може спливати після `session.idleMinutes`, але це **типово вимкнено** (типове значення **0**). - Встановіть додатне значення, щоб увімкнути завершення через бездіяльність. Коли це ввімкнено, **наступне** - повідомлення після періоду бездіяльності починає новий ID сесії для цього ключа чату. - Це не видаляє transcript — лише починає нову сесію. + Сесії можуть завершуватися за `session.idleMinutes`, але це **вимкнено за замовчуванням** (значення за замовчуванням — **0**). + Задайте додатне значення, щоб увімкнути завершення через неактивність. Коли це увімкнено, **наступне** + повідомлення після періоду неактивності починає новий id сесії для цього ключа чату. + Це не видаляє транскрипти — лише запускає нову сесію. ```json5 { @@ -2014,30 +2015,30 @@ x-i18n: - - Так, через **маршрутизацію multi-agent** і **sub-agent**. Ви можете створити одного агента-координатора - і кількох агентів-worker-ів із власними робочими просторами та моделями. + + Так, через **маршрутизацію multi-agent** і **sub-agents**. Ви можете створити одного агента-координатора + і кількох агентів-воркерів із власними workspace і моделями. - Утім, найкраще сприймати це як **цікавий експеримент**. Це витрачає багато токенів і часто + Втім, це радше варто розглядати як **цікавий експеримент**. Це витратно за токенами і часто менш ефективно, ніж використання одного бота з окремими сесіями. Типова модель, яку ми - уявляємо, — це один бот, з яким ви спілкуєтеся, але з різними сесіями для паралельної роботи. Такий - бот також може запускати sub-agent за потреби. + бачимо, — один бот, з яким ви спілкуєтеся, але з різними сесіями для паралельної роботи. Такий + бот також може запускати sub-agents за потреби. - Документація: [Маршрутизація multi-agent](/uk/concepts/multi-agent), [Sub-agent](/uk/tools/subagents), [CLI Agents](/uk/cli/agents). + Документація: [Multi-agent routing](/uk/concepts/multi-agent), [Sub-agents](/uk/tools/subagents), [Agents CLI](/uk/cli/agents). - - Контекст сесії обмежений вікном моделі. Довгі чати, великий вивід інструментів або велика кількість - файлів можуть спричинити Compaction або обрізання. + + Контекст сесії обмежений вікном моделі. Довгі чати, великі виводи tools або велика кількість + файлів можуть спричиняти compaction або обрізання. Що допомагає: - Попросіть бота підсумувати поточний стан і записати його у файл. - - Використовуйте `/compact` перед довгими завданнями, а `/new` — при зміні теми. - - Тримайте важливий контекст у робочому просторі й просіть бота перечитати його. - - Використовуйте sub-agent для довгої або паралельної роботи, щоб основний чат залишався меншим. - - Виберіть модель із більшим вікном контексту, якщо це часто трапляється. + - Використовуйте `/compact` перед довгими завданнями, а `/new` — під час зміни теми. + - Тримайте важливий контекст у workspace і просіть бота перечитувати його. + - Використовуйте sub-agents для довгої або паралельної роботи, щоб основний чат залишався меншим. + - Оберіть модель із більшим вікном контексту, якщо це трапляється часто. @@ -2062,14 +2063,14 @@ x-i18n: Примітки: - - Онбординг також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Онбординг (CLI)](/uk/start/wizard). - - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог стану (типові значення — `~/.openclaw-`). - - Скидання для розробки: `openclaw gateway --dev --reset` (лише для dev; стирає dev-конфігурацію + облікові дані + сесії + робочий простір). + - Onboarding також пропонує **Reset**, якщо бачить наявну конфігурацію. Див. [Onboarding (CLI)](/uk/start/wizard). + - Якщо ви використовували профілі (`--profile` / `OPENCLAW_PROFILE`), скиньте кожен каталог state (типові шляхи — `~/.openclaw-`). + - Скидання для dev: `openclaw gateway --dev --reset` (лише для dev; стирає конфігурацію dev + облікові дані + сесії + workspace). - - Використовуйте один із варіантів: + + Використайте один із варіантів: - **Compaction** (зберігає розмову, але підсумовує старіші ходи): @@ -2077,42 +2078,42 @@ x-i18n: /compact ``` - або `/compact `, щоб спрямувати підсумок. + або `/compact `, щоб керувати підсумком. - - **Скидання** (новий ID сесії для того самого ключа чату): + - **Скидання** (новий id сесії для того самого ключа чату): ``` /new /reset ``` - Якщо це постійно повторюється: + Якщо це трапляється постійно: - - Увімкніть або налаштуйте **очищення сесії** (`agents.defaults.contextPruning`), щоб обрізати старий вивід інструментів. + - Увімкніть або налаштуйте **pruning сесій** (`agents.defaults.contextPruning`), щоб обрізати старий вивід tools. - Використовуйте модель із більшим вікном контексту. - Документація: [Compaction](/uk/concepts/compaction), [Очищення сесії](/uk/concepts/session-pruning), [Керування сесіями](/uk/concepts/session). + Документація: [Compaction](/uk/concepts/compaction), [Session pruning](/uk/concepts/session-pruning), [Session management](/uk/concepts/session). - Це помилка перевірки provider: модель згенерувала блок `tool_use` без обов’язкового - `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих thread - або зміни інструмента/схеми). + Це помилка валідації провайдера: модель згенерувала блок `tool_use` без обов’язкового + `input`. Зазвичай це означає, що історія сесії застаріла або пошкоджена (часто після довгих threads + або зміни tool/schema). - Виправлення: почніть нову сесію за допомогою `/new` (окремим повідомленням). + Виправлення: почніть нову сесію командою `/new` (окремим повідомленням). - - Heartbeat типово запускаються кожні **30m** (**1h** при використанні OAuth auth). Налаштуйте або вимкніть їх: + + Heartbeat виконується кожні **30m** за замовчуванням (**1h** при використанні OAuth auth). Налаштуйте або вимкніть його: ```json5 { agents: { defaults: { heartbeat: { - every: "2h", // or "0m" to disable + every: "2h", // або "0m", щоб вимкнути }, }, }, @@ -2120,16 +2121,16 @@ x-i18n: ``` Якщо `HEARTBEAT.md` існує, але фактично порожній (лише порожні рядки та markdown-заголовки - на кшталт `# Heading`), OpenClaw пропускає запуск heartbeat, щоб заощадити API calls. - Якщо файл відсутній, heartbeat усе одно запускається, і модель сама вирішує, що робити. + на кшталт `# Heading`), OpenClaw пропускає виконання heartbeat, щоб зекономити API-виклики. + Якщо файл відсутній, heartbeat усе одно виконується, і модель сама вирішує, що робити. - Перевизначення для окремих агентів використовують `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). + Override для окремих агентів задаються через `agents.list[].heartbeat`. Документація: [Heartbeat](/uk/gateway/heartbeat). Ні. OpenClaw працює від **вашого власного облікового запису**, тож якщо ви є в групі, OpenClaw може її бачити. - Типово відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). + За замовчуванням відповіді в групах заблоковані, доки ви не дозволите відправників (`groupPolicy: "allowlist"`). Якщо ви хочете, щоб запускати відповіді в групі могли лише **ви**: @@ -2147,137 +2148,137 @@ x-i18n: - Варіант 1 (найшвидший): переглядайте журнали в реальному часі та надішліть тестове повідомлення в групу: + Варіант 1 (найшвидший): перегляньте журнали і надішліть тестове повідомлення в групу: ```bash openclaw logs --follow --json ``` - Знайдіть `chatId` (або `from`), що закінчується на `@g.us`, наприклад: + Шукайте `chatId` (або `from`), що закінчується на `@g.us`, наприклад: `1234567890-1234567890@g.us`. - Варіант 2 (якщо вже налаштовано/додано до allowlist): виведіть групи з конфігурації: + Варіант 2 (якщо вже налаштовано/додано в allowlist): перегляньте групи з конфігурації: ```bash openclaw directory groups list --channel whatsapp ``` - Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Журнали](/uk/cli/logs). + Документація: [WhatsApp](/uk/channels/whatsapp), [Directory](/uk/cli/directory), [Logs](/uk/cli/logs). Дві поширені причини: - - Увімкнено обмеження згадкою (типово). Ви маєте @згадати бота (або відповідати `mentionPatterns`). - - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано до allowlist. + - Увімкнено gating за згадками (типово). Ви маєте @згадати бота (або збігтися з `mentionPatterns`). + - Ви налаштували `channels.whatsapp.groups` без `"*"`, і групу не додано в allowlist. - Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + Див. [Groups](/uk/channels/groups) і [Group messages](/uk/channels/group-messages). - - Прямі чати типово зводяться до основної сесії. Групи/канали мають власні ключі сесій, а теми Telegram / thread Discord — це окремі сесії. Див. [Групи](/uk/channels/groups) і [Групові повідомлення](/uk/channels/group-messages). + + Прямі чати за замовчуванням згортаються до основної сесії. Групи/channels мають власні ключі сесій, а теми Telegram / threads Discord є окремими сесіями. Див. [Groups](/uk/channels/groups) і [Group messages](/uk/channels/group-messages). - + Жорстких обмежень немає. Десятки (навіть сотні) — це нормально, але стежте за таким: - - **Зростання диска:** сесії + transcript зберігаються в `~/.openclaw/agents//sessions/`. + - **Зростання диска:** сесії + транскрипти зберігаються в `~/.openclaw/agents//sessions/`. - **Вартість токенів:** більше агентів означає більше одночасного використання моделей. - - **Операційні витрати:** профілі автентифікації для кожного агента, робочі простори і маршрутизація каналів. + - **Операційні витрати:** профілі auth, workspace і маршрутизація channel для кожного агента. Поради: - - Тримайте один **активний** робочий простір для кожного агента (`agents.defaults.workspace`). - - Очищуйте старі сесії (видаляйте записи JSONL або зі сховища), якщо диск розростається. - - Використовуйте `openclaw doctor`, щоб знаходити сторонні робочі простори та невідповідності профілів. + - Тримайте один **активний** workspace на агента (`agents.defaults.workspace`). + - Очищуйте старі сесії (видаляйте JSONL або записи сховища), якщо диск переповнюється. + - Використовуйте `openclaw doctor`, щоб знаходити зайві workspace і невідповідності профілів. - Так. Використовуйте **Маршрутизацію Multi-Agent**, щоб запускати кілька ізольованих агентів і маршрутизувати вхідні повідомлення за - каналом/обліковим записом/peer. Slack підтримується як канал і може бути прив’язаний до конкретних агентів. + Так. Використовуйте **Multi-Agent Routing**, щоб запускати кількох ізольованих агентів і маршрутизувати вхідні повідомлення за + channel/account/peer. Slack підтримується як channel і може бути прив’язаний до конкретних агентів. - Доступ до браузера потужний, але це не «робити все, що може людина» — anti-bot, CAPTCHA і MFA - усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості, - або використовуйте CDP на машині, яка фактично запускає браузер. + Доступ до браузера потужний, але це не «можливість робити все, що може людина» — anti-bot, CAPTCHA і MFA + усе ще можуть блокувати автоматизацію. Для найнадійнішого керування браузером використовуйте локальний Chrome MCP на хості + або CDP на машині, яка фактично запускає браузер. Рекомендоване налаштування: - - Хост Gateway, що завжди працює (VPS/Mac mini). + - Хост Gateway, що завжди увімкнений (VPS/Mac mini). - Один агент на роль (bindings). - Канал(и) Slack, прив’язані до цих агентів. - - Локальний браузер через Chrome MCP або Node за потреби. + - Локальний браузер через Chrome MCP або Node, коли потрібно. - Документація: [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), - [Browser](/uk/tools/browser), [Node-и](/uk/nodes). + Документація: [Multi-Agent Routing](/uk/concepts/multi-agent), [Slack](/uk/channels/slack), + [Browser](/uk/tools/browser), [Nodes](/uk/nodes). -## Моделі: типові значення, вибір, псевдоніми, перемикання +## Моделі: значення за замовчуванням, вибір, alias, перемикання - - Типова модель OpenClaw — це те, що ви встановили як: + + Модель OpenClaw за замовчуванням — це те, що ви задали як: ``` agents.defaults.model.primary ``` - На моделі посилаються у форматі `provider/model` (приклад: `openai/gpt-5.5`). Якщо ви пропускаєте provider, OpenClaw спочатку пробує псевдонім, потім унікальний збіг налаштованого provider для цього точного ID моделі, і лише потім повертається до налаштованого типового provider як до застарілого шляху сумісності. Якщо цей provider більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення видаленого provider. Вам усе одно слід **явно** вказувати `provider/model`. + На моделі посилаються як `provider/model` (приклад: `openai/gpt-5.5`). Якщо ви не вказуєте провайдера, OpenClaw спочатку намагається знайти alias, потім — унікальний збіг серед налаштованих провайдерів для точного id моделі, і лише потім повертається до налаштованого провайдера за замовчуванням як до застарілого шляху сумісності. Якщо цей провайдер більше не надає налаштовану модель за замовчуванням, OpenClaw повертається до першої налаштованої пари провайдер/модель замість показу застарілого типового значення від вилученого провайдера. Але вам усе одно слід **явно** задавати `provider/model`. - **Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку provider. - **Для агентів з увімкненими інструментами або з недовіреним вхідним вмістом:** надавайте пріоритет силі моделі, а не вартості. - **Для звичайного/низькоризикового чату:** використовуйте дешевші fallback-моделі та маршрутизуйте за роллю агента. + **Рекомендоване типове значення:** використовуйте найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + **Для агентів з увімкненими tools або з недовіреним вхідним потоком:** надавайте перевагу силі моделі над вартістю. + **Для рутинного/малоризикового чату:** використовуйте дешевші fallback-моделі та маршрутизуйте за роллю агента. - Для MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і - [Локальні моделі](/uk/gateway/local-models). + У MiniMax є окрема документація: [MiniMax](/uk/providers/minimax) і + [Local models](/uk/gateway/local-models). Практичне правило: використовуйте **найкращу модель, яку можете собі дозволити** для важливих завдань, і дешевшу - модель для звичайного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента і використовувати sub-agent для - паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Моделі](/uk/concepts/models) і - [Sub-agent](/uk/tools/subagents). + модель для повсякденного чату або підсумків. Ви можете маршрутизувати моделі для кожного агента і використовувати sub-agents для + паралелізації довгих завдань (кожен sub-agent споживає токени). Див. [Models](/uk/concepts/models) і + [Sub-agents](/uk/tools/subagents). - Серйозне попередження: слабші або надмірно квантизовані моделі є більш вразливими до prompt - injection і небезпечної поведінки. Див. [Безпека](/uk/gateway/security). + Серйозне попередження: слабші/надмірно квантизовані моделі більш вразливі до prompt + injection і небезпечної поведінки. Див. [Security](/uk/gateway/security). - Додатково: [Моделі](/uk/concepts/models). + Більше контексту: [Models](/uk/concepts/models). - + Використовуйте **команди моделей** або редагуйте лише поля **model**. Уникайте повної заміни конфігурації. Безпечні варіанти: - - `/model` у чаті (швидко, для поточної сесії) + - `/model` у чаті (швидко, для окремої сесії) - `openclaw models set ...` (оновлює лише конфігурацію моделі) - `openclaw configure --section model` (інтерактивно) - - відредагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` + - редагуйте `agents.defaults.model` у `~/.openclaw/openclaw.json` - Уникайте `config.apply` з частковим об’єктом, якщо тільки ви не маєте наміру замінити всю конфігурацію. - Для редагувань через RPC спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Payload lookup дає вам нормалізований шлях, поверхневу документацію/обмеження схеми та короткі описи безпосередніх дочірніх елементів. + Уникайте `config.apply` з частковим об’єктом, якщо ви не плануєте замінити всю конфігурацію. + Для RPC-редагувань спочатку перевіряйте через `config.schema.lookup` і віддавайте перевагу `config.patch`. Payload lookup дає нормалізований шлях, документацію/обмеження неглибокої схеми та підсумки безпосередніх дочірніх елементів. для часткових оновлень. - Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно виконайте `openclaw doctor` для виправлення. + Якщо ви все ж перезаписали конфігурацію, відновіть її з резервної копії або повторно запустіть `openclaw doctor` для виправлення. - Документація: [Моделі](/uk/concepts/models), [Налаштування](/uk/cli/configure), [Конфігурація](/uk/cli/config), [Doctor](/uk/gateway/doctor). + Документація: [Models](/uk/concepts/models), [Configure](/uk/cli/configure), [Config](/uk/cli/config), [Doctor](/uk/gateway/doctor). - Так. Ollama — найпростіший шлях до локальних моделей. + Так. Ollama — найпростіший шлях для локальних моделей. Найшвидше налаштування: 1. Установіть Ollama з `https://ollama.com/download` 2. Завантажте локальну модель, наприклад `ollama pull gemma4` - 3. Якщо ви хочете також хмарні моделі, виконайте `ollama signin` - 4. Виконайте `openclaw onboard` і виберіть `Ollama` + 3. Якщо ви також хочете хмарні моделі, виконайте `ollama signin` + 4. Запустіть `openclaw onboard` і виберіть `Ollama` 5. Виберіть `Local` або `Cloud + Local` Примітки: @@ -2287,19 +2288,19 @@ x-i18n: - для ручного перемикання використовуйте `openclaw models list` і `openclaw models set ollama/` Примітка щодо безпеки: менші або сильно квантизовані моделі більш вразливі до prompt - injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати інструменти. - Якщо ви все ж хочете маленькі моделі, увімкніть ізоляцію та суворі allowlist інструментів. + injection. Ми наполегливо рекомендуємо **великі моделі** для будь-якого бота, який може використовувати tools. + Якщо ви все ж хочете маленькі моделі, увімкніть sandboxing і суворі tool allowlists. - Документація: [Ollama](/uk/providers/ollama), [Локальні моделі](/uk/gateway/local-models), - [Model providers](/uk/concepts/model-providers), [Безпека](/uk/gateway/security), - [Ізоляція](/uk/gateway/sandboxing). + Документація: [Ollama](/uk/providers/ollama), [Local models](/uk/gateway/local-models), + [Model providers](/uk/concepts/model-providers), [Security](/uk/gateway/security), + [Sandboxing](/uk/gateway/sandboxing). - - Ці розгортання можуть відрізнятися та змінюватися з часом; фіксованої рекомендації щодо provider немає. - - Перевіряйте поточне налаштування під час виконання на кожному gateway за допомогою `openclaw models status`. - - Для агентів, чутливих до безпеки / з увімкненими інструментами, використовуйте найсильнішу доступну модель останнього покоління. + - Ці розгортання можуть відрізнятися й змінюватися з часом; фіксованої рекомендації щодо провайдера немає. + - Перевіряйте поточне runtime-налаштування на кожному gateway через `openclaw models status`. + - Для агентів, чутливих до безпеки / з увімкненими tools, використовуйте найсильнішу доступну модель останнього покоління. @@ -2315,27 +2316,27 @@ x-i18n: /model gemini-flash-lite ``` - Це вбудовані псевдоніми. Власні псевдоніми можна додати через `agents.defaults.models`. + Це вбудовані alias. Власні alias можна додати через `agents.defaults.models`. Ви можете переглянути доступні моделі через `/model`, `/model list` або `/model status`. - `/model` (і `/model list`) показує компактний нумерований засіб вибору. Вибір за номером: + `/model` (і `/model list`) показує компактний нумерований список вибору. Вибір за номером: ``` /model 3 ``` - Ви також можете примусово задати конкретний профіль автентифікації для provider (для поточної сесії): + Ви також можете примусово вибрати конкретний профіль auth для провайдера (для окремої сесії): ``` /model opus@anthropic:default /model opus@anthropic:work ``` - Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль автентифікації буде спробовано наступним. - Він також показує налаштований endpoint provider (`baseUrl`) і режим API (`api`), коли це доступно. + Порада: `/model status` показує, який агент активний, який файл `auth-profiles.json` використовується і який профіль auth буде спробовано наступним. + Він також показує налаштований endpoint провайдера (`baseUrl`) і режим API (`api`), коли вони доступні. - **Як відкріпити профіль, який я встановив через @profile?** + **Як зняти прив’язку профілю, який я задав через @profile?** Повторно виконайте `/model` **без** суфікса `@profile`: @@ -2343,28 +2344,28 @@ x-i18n: /model anthropic/claude-opus-4-6 ``` - Якщо ви хочете повернутися до типового значення, виберіть його в `/model` (або надішліть `/model `). - Використовуйте `/model status`, щоб підтвердити, який профіль автентифікації активний. + Якщо ви хочете повернутися до значення за замовчуванням, виберіть його через `/model` (або надішліть `/model `). + Використовуйте `/model status`, щоб підтвердити, який профіль auth активний. - Так. Установіть одну як типову і перемикайтеся за потреби: + Так. Задайте одну як типову, а за потреби перемикайте: - - **Швидке перемикання (для сесії):** `/model gpt-5.5` для щоденних завдань, `/model openai-codex/gpt-5.5` для програмування з Codex OAuth. - - **Типове значення + перемикання:** установіть `agents.defaults.model.primary` у `openai/gpt-5.5`, а потім перемикайтеся на `openai-codex/gpt-5.5` для програмування (або навпаки). - - **Sub-agent:** маршрутизуйте завдання програмування до sub-agent із іншою типовою моделлю. + - **Швидке перемикання (для сесії):** `/model gpt-5.5` для щоденних завдань або збережіть ту саму модель і за потреби переключайте auth/profile. + - **Типове значення:** задайте `agents.defaults.model.primary` як `openai/gpt-5.5`. + - **Sub-agents:** маршрутизуйте завдання програмування до sub-agents з іншою моделлю за замовчуванням. - Див. [Моделі](/uk/concepts/models) і [Слеш-команди](/uk/tools/slash-commands). + Див. [Models](/uk/concepts/models) і [Slash commands](/uk/tools/slash-commands). - Використовуйте або перемикач для сесії, або типове значення в конфігурації: + Використовуйте або перемикач для сесії, або значення за замовчуванням у конфігурації: - - **Для сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.5` або `openai-codex/gpt-5.5`. - - **Типове значення для моделі:** установіть `agents.defaults.models["openai/gpt-5.5"].params.fastMode` у `true`. - - **Також для Codex OAuth:** якщо ви також використовуєте `openai-codex/gpt-5.5`, установіть той самий прапорець і там. + - **Для сесії:** надішліть `/fast on`, поки сесія використовує `openai/gpt-5.5`. + - **Типове значення для моделі:** задайте `agents.defaults.models["openai/gpt-5.5"].params.fastMode` як `true`. + - **Застарілі alias:** старіші записи `openai-codex/gpt-*` можуть зберігати власні параметри, але в нових конфігураціях параметри слід задавати для `openai/gpt-*`. Приклад: @@ -2378,51 +2379,46 @@ x-i18n: fastMode: true, }, }, - "openai-codex/gpt-5.5": { - params: { - fastMode: true, - }, - }, }, }, }, } ``` - Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. `/fast` для сесії має пріоритет над типовими значеннями конфігурації. + Для OpenAI fast mode відповідає `service_tier = "priority"` у підтримуваних нативних запитах Responses. Сесійні override через `/fast` мають вищий пріоритет за типові значення конфігурації. - Див. [Thinking і fast mode](/uk/tools/thinking) і [Fast mode OpenAI](/uk/providers/openai#openai-fast-mode). + Див. [Thinking and fast mode](/uk/tools/thinking) і [OpenAI fast mode](/uk/providers/openai#openai-fast-mode). - Якщо встановлено `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких - перевизначень сесії. Вибір моделі, якої немає в цьому списку, повертає: + Якщо задано `agents.defaults.models`, це стає **allowlist** для `/model` і будь-яких + override сесії. Вибір моделі, якої немає в цьому списку, повертає: ``` Model "provider/model" is not allowed. Use /model to list available models. ``` Ця помилка повертається **замість** звичайної відповіді. Виправлення: додайте модель до - `agents.defaults.models`, приберіть allowlist або виберіть модель із `/model list`. + `agents.defaults.models`, приберіть allowlist або виберіть модель через `/model list`. - Це означає, що **provider не налаштований** (не знайдено конфігурації provider MiniMax або профілю - автентифікації), тому модель не вдається розв’язати. + Це означає, що **провайдер не налаштований** (не знайдено конфігурацію провайдера MiniMax або профіль + auth), тому модель не може бути розв’язана. Контрольний список для виправлення: 1. Оновіться до поточного релізу OpenClaw (або запускайте з вихідного коду `main`), а потім перезапустіть gateway. - 2. Переконайтеся, що MiniMax налаштовано (через майстер або JSON), або що автентифікація MiniMax - існує в env/профілях автентифікації, щоб можна було підставити відповідний provider - (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений OAuth MiniMax - для `minimax-portal`). - 3. Використовуйте точний ID моделі (з урахуванням регістру) для вашого шляху автентифікації: - `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування - через API key, або `minimax-portal/MiniMax-M2.7` / - `minimax-portal/MiniMax-M2.7-highspeed` для налаштування через OAuth. + 2. Переконайтеся, що MiniMax налаштовано (через майстер або JSON), або що auth MiniMax + існує в env/профілях auth, щоб відповідний провайдер міг бути ін’єктований + (`MINIMAX_API_KEY` для `minimax`, `MINIMAX_OAUTH_TOKEN` або збережений MiniMax + OAuth для `minimax-portal`). + 3. Використовуйте точний id моделі (з урахуванням регістру) для вашого шляху auth: + `minimax/MiniMax-M2.7` або `minimax/MiniMax-M2.7-highspeed` для налаштування з API key, + або `minimax-portal/MiniMax-M2.7` / + `minimax-portal/MiniMax-M2.7-highspeed` для налаштування з OAuth. 4. Виконайте: ```bash @@ -2431,12 +2427,12 @@ x-i18n: і виберіть зі списку (або `/model list` у чаті). - Див. [MiniMax](/uk/providers/minimax) і [Моделі](/uk/concepts/models). + Див. [MiniMax](/uk/providers/minimax) і [Models](/uk/concepts/models). - - Так. Використовуйте **MiniMax за замовчуванням** і перемикайте моделі **для окремої сесії** за потреби. + + Так. Використовуйте **MiniMax як типову модель** і перемикайте моделі **для окремих сесій** за потреби. Fallback призначені для **помилок**, а не для «складних завдань», тому використовуйте `/model` або окремого агента. **Варіант A: перемикання для окремої сесії** @@ -2464,16 +2460,16 @@ x-i18n: **Варіант B: окремі агенти** - - Типова модель агента A: MiniMax - - Типова модель агента B: OpenAI + - Типове значення агента A: MiniMax + - Типове значення агента B: OpenAI - Маршрутизуйте за агентом або використовуйте `/agent` для перемикання - Документація: [Моделі](/uk/concepts/models), [Маршрутизація Multi-Agent](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). + Документація: [Models](/uk/concepts/models), [Multi-Agent Routing](/uk/concepts/multi-agent), [MiniMax](/uk/providers/minimax), [OpenAI](/uk/providers/openai). - Так. OpenClaw постачається з кількома скороченнями за замовчуванням (застосовуються лише тоді, коли модель існує в `agents.defaults.models`): + Так. OpenClaw постачається з кількома типовими shorthand-іменами (застосовуються лише коли модель існує в `agents.defaults.models`): - `opus` → `anthropic/claude-opus-4-6` - `sonnet` → `anthropic/claude-sonnet-4-6` @@ -2484,12 +2480,12 @@ x-i18n: - `gemini-flash` → `google/gemini-3-flash-preview` - `gemini-flash-lite` → `google/gemini-3.1-flash-lite-preview` - Якщо ви задаєте власний псевдонім із тією самою назвою, пріоритет матиме ваше значення. + Якщо ви задасте власний alias з такою самою назвою, пріоритет матиме ваше значення. - - Псевдоніми беруться з `agents.defaults.models..alias`. Приклад: + + Alias беруться з `agents.defaults.models..alias`. Приклад: ```json5 { @@ -2506,11 +2502,11 @@ x-i18n: } ``` - Потім `/model sonnet` (або `/`, якщо це підтримується) розв’язується до цього ID моделі. + Тоді `/model sonnet` (або `/`, коли підтримується) буде розв’язуватися до цього ID моделі. - + OpenRouter (оплата за токени; багато моделей): ```json5 @@ -2539,12 +2535,12 @@ x-i18n: } ``` - Якщо ви посилаєтеся на provider/model, але потрібний ключ provider відсутній, ви отримаєте помилку автентифікації під час виконання (наприклад, `No API key found for provider "zai"`). + Якщо ви посилаєтесь на `provider/model`, але потрібний ключ провайдера відсутній, ви отримаєте runtime-помилку auth (наприклад, `No API key found for provider "zai"`). - **Після додавання нового агента з’являється повідомлення No API key found for provider** + **Після додавання нового агента з’являється помилка No API key found for provider** - Зазвичай це означає, що **новий агент** має порожнє сховище автентифікації. Автентифікація є окремою для кожного агента і - зберігається тут: + Зазвичай це означає, що в **нового агента** порожнє сховище auth. Auth прив’язаний до агента і + зберігається в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2552,10 +2548,10 @@ x-i18n: Варіанти виправлення: - - Виконайте `openclaw agents add ` і налаштуйте автентифікацію під час роботи майстра. + - Запустіть `openclaw agents add ` і налаштуйте auth у майстрі. - Або скопіюйте `auth-profiles.json` з `agentDir` основного агента в `agentDir` нового агента. - **Не** використовуйте спільний `agentDir` для кількох агентів; це спричиняє конфлікти автентифікації/сесій. + **Не** використовуйте один і той самий `agentDir` для кількох агентів; це спричиняє конфлікти auth/сесій. @@ -2566,104 +2562,105 @@ x-i18n: Fallback відбувається у два етапи: - 1. **Ротація профілів автентифікації** в межах того самого provider. + 1. **Ротація профілів auth** в межах одного провайдера. 2. **Fallback моделі** до наступної моделі в `agents.defaults.model.fallbacks`. - До профілів, що збоять, застосовуються cooldown (експоненційний backoff), тому OpenClaw може й далі відповідати, навіть коли provider обмежений за rate limit або тимчасово не працює. + До профілів, що помиляються, застосовуються cooldown (експоненційний backoff), тому OpenClaw може й далі відповідати, навіть коли провайдер обмежений за rate limit або тимчасово не працює. - Кошик rate limit включає не лише прості відповіді `429`. OpenClaw - також вважає такими, що варті fallback, повідомлення на кшталт `Too many concurrent requests`, + До bucket rate limit входять не лише прості відповіді `429`. OpenClaw + також трактує повідомлення на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded`, `resource exhausted` і періодичні - ліміти вікон використання (`weekly/monthly limit reached`). + ліміти вікна використання (`weekly/monthly limit reached`) як rate limit, + гідні переходу на fallback. - Деякі відповіді, схожі на проблеми з білінгом, не є `402`, і деякі відповіді HTTP `402` - також лишаються в цьому тимчасовому кошику. Якщо provider повертає - явний текст про білінг у `401` або `403`, OpenClaw усе одно може залишити це в - гілці білінгу, але текстові відповідники, специфічні для provider, лишаються в межах - provider, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` - натомість схоже на повторюваний ліміт вікна використання або + Деякі відповіді, схожі на білінгові, не мають коду `402`, а деякі HTTP `402` + також залишаються в цьому transient bucket. Якщо провайдер повертає + явний білінговий текст на `401` або `403`, OpenClaw усе ще може лишити це в + білінговому bucket, але специфічні для провайдера text matcher-и залишаються прив’язаними до + провайдера, якому вони належать (наприклад, OpenRouter `Key limit exceeded`). Якщо ж повідомлення `402` + більше схоже на вікно використання, яке можна повторити, або ліміт витрат organization/workspace (`daily limit reached, resets tomorrow`, `organization spending limit exceeded`), OpenClaw трактує це як `rate_limit`, а не як довготривале вимкнення через білінг. - Помилки переповнення контексту відрізняються: сигнатури на кшталт + Помилки переповнення контексту — це інше: сигнатури на кшталт `request_too_large`, `input exceeds the maximum number of tokens`, `input token count exceeds the maximum number of input tokens`, `input is too long for the model` або `ollama error: context length - exceeded` залишаються на шляху Compaction/повторної спроби замість переходу до - fallback моделі. + exceeded` залишаються на шляху compaction/retry замість переходу до model + fallback. Загальний текст server error навмисно вужчий, ніж «усе, що містить - unknown/error». OpenClaw справді вважає такими, що варті fallback, перехідні форми, прив’язані до provider, - як-от просте повідомлення Anthropic `An unknown error occurred`, просте повідомлення OpenRouter - `Provider returned error`, помилки stop-reason, наприклад `Unhandled stop reason: - error`, JSON-payload `api_error` з тимчасовим текстом серверної помилки + unknown/error». OpenClaw справді трактує transient-форми, обмежені провайдером, + такі як Anthropic bare `An unknown error occurred`, OpenRouter bare + `Provider returned error`, помилки stop-reason на кшталт `Unhandled stop reason: + error`, JSON `api_error` payloads із transient server text (`internal server error`, `unknown error, 520`, `upstream error`, `backend - error`) і помилки зайнятості provider, як-от `ModelNotReadyException`, як сигнали - timeout/overloaded, що варті fallback, коли збігається контекст provider. - Загальний внутрішній fallback-текст на кшталт `LLM request failed with an unknown - error.` лишається консервативним і сам по собі не запускає fallback моделі. + error`) і помилки зайнятості провайдера, такі як `ModelNotReadyException`, як сигнали timeout/overloaded, + гідні fallback, коли контекст провайдера збігається. + Загальний внутрішній fallback text на кшталт `LLM request failed with an unknown + error.` лишається консервативним і сам по собі не запускає model fallback. - Це означає, що система спробувала використати ID профілю автентифікації `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі автентифікації. + Це означає, що система намагалася використати ID профілю auth `anthropic:default`, але не змогла знайти для нього облікові дані в очікуваному сховищі auth. **Контрольний список для виправлення:** - - **Перевірте, де живуть профілі автентифікації** (нові та застарілі шляхи) - - Поточний: `~/.openclaw/agents//agent/auth-profiles.json` - - Застарілий: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) - - **Переконайтеся, що Gateway завантажує вашу змінну середовища** - - Якщо ви встановили `ANTHROPIC_API_KEY` у своїй оболонці, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або ввімкніть `env.shellEnv`. + - **Переконайтеся, де зберігаються профілі auth** (нові та застарілі шляхи) + - Поточний шлях: `~/.openclaw/agents//agent/auth-profiles.json` + - Застарілий шлях: `~/.openclaw/agent/*` (мігрується через `openclaw doctor`) + - **Переконайтеся, що Gateway завантажив вашу env var** + - Якщо ви задали `ANTHROPIC_API_KEY` у shell, але запускаєте Gateway через systemd/launchd, він може її не успадкувати. Помістіть її в `~/.openclaw/.env` або увімкніть `env.shellEnv`. - **Переконайтеся, що редагуєте правильного агента** - - У multi-agent налаштуваннях може бути кілька файлів `auth-profiles.json`. - - **Перевірте стан моделі/автентифікації** - - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі і чи провайдери автентифіковані. + - У multi-agent-налаштуваннях може бути кілька файлів `auth-profiles.json`. + - **Базова перевірка статусу model/auth** + - Використовуйте `openclaw models status`, щоб побачити налаштовані моделі та чи автентифіковано провайдерів. **Контрольний список для виправлення "No credentials found for profile anthropic"** - Це означає, що запуск закріплено за профілем автентифікації Anthropic, але Gateway - не може знайти його у своєму сховищі автентифікації. + Це означає, що запуск прив’язаний до профілю auth Anthropic, але Gateway + не може знайти його у своєму сховищі auth. - - **Використовуйте Claude CLI** - - Виконайте `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. - - **Якщо натомість ви хочете використовувати API key** + - **Використайте Claude CLI** + - Запустіть `openclaw models auth login --provider anthropic --method cli --set-default` на хості gateway. + - **Якщо ви натомість хочете використовувати API key** - Помістіть `ANTHROPIC_API_KEY` у `~/.openclaw/.env` на **хості gateway**. - - Очистіть будь-який закріплений порядок, який примусово вимагає відсутній профіль: + - Очистьте будь-який примусовий порядок, який вимагає відсутній профіль: ```bash openclaw models auth order clear --provider anthropic ``` - **Переконайтеся, що запускаєте команди на хості gateway** - - У віддаленому режимі профілі автентифікації живуть на машині gateway, а не на вашому ноутбуці. + - У віддаленому режимі профілі auth живуть на машині gateway, а не на вашому ноутбуці. - - Якщо ваша конфігурація моделі включає Google Gemini як fallback (або ви перемкнулися на скорочення Gemini), OpenClaw спробує її під час fallback моделі. Якщо ви не налаштували облікові дані Google, побачите `No API key found for provider "google"`. + + Якщо ваша конфігурація моделі містить Google Gemini як fallback (або ви перемкнулися на shorthand Gemini), OpenClaw спробує його під час model fallback. Якщо ви не налаштували облікові дані Google, ви побачите `No API key found for provider "google"`. - Виправлення: або надайте автентифікацію Google, або приберіть/уникайте моделей Google в `agents.defaults.model.fallbacks` / aliases, щоб fallback не маршрутизував туди. + Виправлення: або надайте auth Google, або приберіть/уникайте моделей Google у `agents.defaults.model.fallbacks` / alias, щоб fallback не маршрутизував туди. **LLM request rejected: thinking signature required (Google Antigravity)** - Причина: історія сесії містить **thinking-блоки без сигнатур** (часто після - перерваного/часткового потоку). Google Antigravity вимагає сигнатури для thinking-блоків. + Причина: історія сесії містить **thinking blocks без сигнатур** (часто через + перерваний/частковий потік). Google Antigravity вимагає сигнатури для thinking blocks. - Виправлення: тепер OpenClaw видаляє непідписані thinking-блоки для Google Antigravity Claude. Якщо проблема все ще з’являється, почніть **нову сесію** або встановіть `/thinking off` для цього агента. + Виправлення: тепер OpenClaw видаляє thinking blocks без сигнатур для Google Antigravity Claude. Якщо це все ще з’являється, почніть **нову сесію** або задайте `/thinking off` для цього агента. -## Профілі автентифікації: що це і як ними керувати +## Профілі auth: що це таке і як ними керувати -Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (OAuth flow, зберігання токенів, шаблони роботи з кількома обліковими записами) +Пов’язане: [/concepts/oauth](/uk/concepts/oauth) (OAuth flows, зберігання токенів, шаблони для кількох облікових записів) - - Профіль автентифікації — це іменований запис облікових даних (OAuth або API key), прив’язаний до provider. Профілі зберігаються тут: + + Профіль auth — це іменований запис облікових даних (OAuth або API key), прив’язаний до провайдера. Профілі зберігаються в: ``` ~/.openclaw/agents//agent/auth-profiles.json @@ -2672,36 +2669,36 @@ x-i18n: - OpenClaw використовує ID з префіксом provider, наприклад: + OpenClaw використовує ID з префіксом провайдера, наприклад: - `anthropic:default` (поширений варіант, коли немає email-ідентичності) - `anthropic:` для OAuth-ідентичностей - - власні ID, які ви вибираєте (наприклад, `anthropic:work`) + - власні ID на ваш вибір (наприклад `anthropic:work`) - - Так. Конфігурація підтримує необов’язкові metadata для профілів і порядок для кожного provider (`auth.order.`). Це **не** зберігає секрети; воно зіставляє ID з provider/mode і задає порядок ротації. + + Так. Конфігурація підтримує необов’язкові метадані для профілів і порядок для кожного провайдера (`auth.order.`). Це **не** зберігає секрети; воно лише зіставляє ID з провайдером/режимом і задає порядок ротації. - OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **cooldown** (rate limit/timeout/збій автентифікації) або в довшому стані **disabled** (білінг/недостатньо кредитів). Щоб перевірити це, виконайте `openclaw models status --json` і перегляньте `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. + OpenClaw може тимчасово пропустити профіль, якщо він перебуває в короткому **cooldown** (rate limit/timeouts/auth failures) або в довшому стані **disabled** (billing/insufficient credits). Щоб перевірити це, виконайте `openclaw models status --json` і подивіться `auth.unusableProfiles`. Налаштування: `auth.cooldowns.billingBackoffHours*`. - Cooldown для rate limit може бути прив’язаний до моделі. Профіль, який перебуває в cooldown - для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого provider, - тоді як вікна billing/disabled усе одно блокують увесь профіль. + Cooldown через rate limit може бути прив’язаний до моделі. Профіль, який перебуває в cooldown + для однієї моделі, усе ще може бути придатним для спорідненої моделі того самого провайдера, + тоді як billing/disabled-вікна все одно блокують увесь профіль. - Ви також можете встановити перевизначення порядку **для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: + Ви також можете задати **override порядку для окремого агента** (зберігається в `auth-state.json` цього агента) через CLI: ```bash - # Defaults to the configured default agent (omit --agent) + # За замовчуванням використовується типовий агент із конфігурації (опустіть --agent) openclaw models auth order get --provider anthropic - # Lock rotation to a single profile (only try this one) + # Зафіксувати ротацію на одному профілі (пробувати лише цей) openclaw models auth order set --provider anthropic anthropic:default - # Or set an explicit order (fallback within provider) + # Або задати явний порядок (fallback у межах провайдера) openclaw models auth order set --provider anthropic anthropic:work anthropic:default - # Clear override (fall back to config auth.order / round-robin) + # Очистити override (повернутися до config auth.order / round-robin) openclaw models auth order clear --provider anthropic ``` @@ -2711,22 +2708,22 @@ x-i18n: openclaw models auth order set --provider anthropic --agent main anthropic:default ``` - Щоб перевірити, що саме буде спробовано на практиці, використовуйте: + Щоб перевірити, що справді буде спробовано, використовуйте: ```bash openclaw models status --probe ``` Якщо збережений профіль пропущено в явному порядку, probe повідомить - `excluded_by_auth_order` для цього профілю замість того, щоб мовчки пробувати його. + `excluded_by_auth_order` для цього профілю замість мовчазної спроби. - + OpenClaw підтримує обидва варіанти: - - **OAuth** часто використовує доступ за підпискою (де це застосовно). - - **API keys** використовують білінг за моделлю оплати за токени. + - **OAuth** часто використовує доступ за підпискою (де це можливо). + - **API keys** використовують оплату за токени. Майстер явно підтримує Anthropic Claude CLI, OpenAI Codex OAuth і API keys. @@ -2742,24 +2739,24 @@ x-i18n: Пріоритет: ``` - --port > OPENCLAW_GATEWAY_PORT > gateway.port > default 18789 + --port > OPENCLAW_GATEWAY_PORT > gateway.port > типове значення 18789 ``` - - Тому що "running" — це погляд **supervisor** (launchd/systemd/schtasks). А probe підключення — це CLI, який реально намагається під’єднатися до gateway WebSocket. + + Тому що "running" — це погляд **супервізора** (launchd/systemd/schtasks). А connectivity probe — це фактична спроба CLI підключитися до gateway WebSocket. - Використовуйте `openclaw gateway status` і довіряйте таким рядкам: + Використовуйте `openclaw gateway status` і орієнтуйтеся на ці рядки: - `Probe target:` (URL, який probe фактично використав) - `Listening:` (що реально прив’язано до порту) - - `Last gateway error:` (типова першопричина, коли процес живий, але порт не слухає) + - `Last gateway error:` (типова коренева причина, коли процес живий, але порт не слухає) - - Ви редагуєте один файл конфігурації, а service працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). + + Ви редагуєте один файл конфігурації, а сервіс працює з іншим (часто через невідповідність `--profile` / `OPENCLAW_STATE_DIR`). Виправлення: @@ -2767,19 +2764,19 @@ x-i18n: openclaw gateway install --force ``` - Запускайте це з того самого `--profile` / середовища, яке service має використовувати. + Запускайте це з того самого `--profile` / середовища, яке має використовувати сервіс. - OpenClaw примусово застосовує блокування runtime, негайно прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується помилкою `EADDRINUSE`, викидається `GatewayLockError`, що означає, що вже слухає інший інстанс. + OpenClaw примусово використовує runtime-lock, одразу прив’язуючи слухач WebSocket під час запуску (типово `ws://127.0.0.1:18789`). Якщо прив’язка завершується з `EADDRINUSE`, викидається `GatewayLockError`, який означає, що інший екземпляр уже слухає. - Виправлення: зупиніть інший інстанс, звільніть порт або запускайте з `openclaw gateway --port `. + Виправлення: зупиніть інший екземпляр, звільніть порт або запускайте з `openclaw gateway --port `. - - Установіть `gateway.mode: "remote"` і вкажіть віддалений URL WebSocket, за потреби з віддаленими обліковими даними спільного секрету: + + Задайте `gateway.mode: "remote"` і вкажіть URL віддаленого WebSocket, за потреби разом із віддаленими обліковими даними зі спільним секретом: ```json5 { @@ -2796,90 +2793,90 @@ x-i18n: Примітки: - - `openclaw gateway` запускається лише коли `gateway.mode` має значення `local` (або якщо ви передасте прапорець перевизначення). - - Застосунок macOS стежить за файлом конфігурації та динамічно перемикає режими, коли ці значення змінюються. - - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають локальну автентифікацію gateway. + - `openclaw gateway` запускається лише коли `gateway.mode` має значення `local` (або якщо ви передали прапорець override). + - Застосунок macOS стежить за файлом конфігурації і в реальному часі перемикає режими, коли ці значення змінюються. + - `gateway.remote.token` / `.password` — це лише клієнтські віддалені облікові дані; самі по собі вони не вмикають auth локального gateway. - - Шлях автентифікації вашого gateway і метод автентифікації UI не збігаються. + + Шлях auth вашого gateway і метод auth у UI не збігаються. Факти (з коду): - - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраного URL gateway, тож оновлення в тій самій вкладці продовжують працювати без відновлення довготривалого збереження токена в localStorage. - - Для `AUTH_TOKEN_MISMATCH` довірені клієнти можуть виконати одну обмежену повторну спробу з кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). - - Тепер ця повторна спроба з кешованим токеном повторно використовує кешовані схвалені scopes, збережені разом із токеном пристрою. Виклики з явним `deviceToken` / явними `scopes` усе ще зберігають свій запитаний набір scopes замість успадкування кешованих scopes. - - Поза цим шляхом повторної спроби пріоритет автентифікації підключення такий: явний спільний токен/пароль спочатку, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap-токен. - - Перевірки scope bootstrap-токена мають префікс ролі. Вбудований allowlist bootstrap-оператора задовольняє лише запити оператора; node або інші ролі, що не є оператором, усе одно потребують scopes під власним префіксом ролі. + - Control UI зберігає токен у `sessionStorage` для поточної сесії вкладки браузера та вибраної URL-адреси gateway, тож оновлення в межах тієї самої вкладки продовжують працювати без відновлення довготривалої прив’язки токена в localStorage. + - За `AUTH_TOKEN_MISMATCH` довірені клієнти можуть спробувати один обмежений повторний запит із кешованим токеном пристрою, коли gateway повертає підказки для повтору (`canRetryWithDeviceToken=true`, `recommendedNextStep=retry_with_device_token`). + - Цей повтор із кешованим токеном тепер повторно використовує кешовані дозволені scopes, збережені разом із токеном пристрою. Явні виклики `deviceToken` / явні `scopes` усе одно зберігають свій запитаний набір scopes замість успадковування кешованих. + - Поза цим шляхом повтору пріоритет auth під час підключення такий: спочатку явний shared token/password, потім явний `deviceToken`, потім збережений токен пристрою, потім bootstrap token. + - Перевірки scope bootstrap token мають префікси ролей. Вбудований allowlist для bootstrap operator задовольняє лише запити operator; Node або інші не-operator ролі все одно потребують scopes під власним префіксом ролі. Виправлення: - - Найшвидше: `openclaw dashboard` (виводить + копіює URL dashboard, намагається відкрити; показує підказку SSH, якщо headless). + - Найшвидше: `openclaw dashboard` (друкує + копіює URL dashboard, намагається відкрити; якщо режим headless, показує підказку для SSH). - Якщо у вас ще немає токена: `openclaw doctor --generate-gateway-token`. - - Якщо віддалено, спочатку зробіть tunnel: `ssh -N -L 18789:127.0.0.1:18789 user@host`, а потім відкрийте `http://127.0.0.1:18789/`. - - Режим спільного секрету: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, а потім вставте відповідний секрет у налаштуваннях Control UI. - - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і що ви відкриваєте URL Serve, а не сирий URL loopback/tailnet, який обходить заголовки ідентичності Tailscale. - - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований reverse proxy з awareness про ідентичність, не на loopback, а не через loopback-проксі на тому самому хості або сирий URL gateway. - - Якщо невідповідність зберігається після однієї повторної спроби, замініть/повторно схваліть спарений токен пристрою: + - Якщо віддалено, спочатку створіть тунель: `ssh -N -L 18789:127.0.0.1:18789 user@host`, потім відкрийте `http://127.0.0.1:18789/`. + - Режим shared-secret: задайте `gateway.auth.token` / `OPENCLAW_GATEWAY_TOKEN` або `gateway.auth.password` / `OPENCLAW_GATEWAY_PASSWORD`, потім вставте відповідний секрет у налаштуваннях Control UI. + - Режим Tailscale Serve: переконайтеся, що `gateway.auth.allowTailscale` увімкнено і ви відкриваєте URL Serve, а не сирий loopback/tailnet URL, який обходить заголовки ідентичності Tailscale. + - Режим trusted-proxy: переконайтеся, що ви заходите через налаштований identity-aware proxy не на loopback, а не через loopback proxy на тому самому хості чи сирий URL gateway. + - Якщо невідповідність залишається після однієї повторної спроби, перевипустіть/повторно підтвердьте токен парного пристрою: - `openclaw devices list` - `openclaw devices rotate --device --role operator` - - Якщо ця команда rotate каже, що запит відхилено, перевірте дві речі: - - сесії спарених пристроїв можуть замінювати лише **власний** пристрій, якщо тільки вони також не мають `operator.admin` + - Якщо цей виклик rotate повідомляє, що його відхилено, перевірте дві речі: + - сесії парних пристроїв можуть перевипускати лише **власний** пристрій, якщо в них немає також `operator.admin` - явні значення `--scope` не можуть перевищувати поточні operator scopes викликача - - Усе ще не виходить? Виконайте `openclaw status --all` і дотримуйтесь [Усунення несправностей](/uk/gateway/troubleshooting). Деталі автентифікації див. в [Dashboard](/uk/web/dashboard). + - Усе ще не виходить? Запустіть `openclaw status --all` і дотримуйтеся [Troubleshooting](/uk/gateway/troubleshooting). Подробиці auth див. у [Dashboard](/uk/web/dashboard). - - Прив’язка `tailnet` вибирає IP Tailscale з ваших мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), прив’язуватися нема до чого. + + Прив’язка `tailnet` вибирає IP-адресу Tailscale з мережевих інтерфейсів (100.64.0.0/10). Якщо машина не в Tailscale (або інтерфейс вимкнений), прив’язуватися немає до чого. Виправлення: - Запустіть Tailscale на цьому хості (щоб він мав адресу 100.x), або - - перемкніться на `gateway.bind: "loopback"` / `"lan"`. + - Перемкніться на `gateway.bind: "loopback"` / `"lan"`. - Примітка: `tailnet` є явним режимом. `auto` надає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли хочете прив’язку лише до tailnet. + Примітка: `tailnet` задається явно. `auto` віддає перевагу loopback; використовуйте `gateway.bind: "tailnet"`, коли вам потрібна прив’язка лише до tailnet. - Зазвичай ні — один Gateway може запускати кілька каналів обміну повідомленнями та агентів. Використовуйте кілька Gateway лише тоді, коли вам потрібна резервність (наприклад, rescue bot) або жорстка ізоляція. + Зазвичай ні — один Gateway може обслуговувати кілька messaging channels і агентів. Кілька Gateway використовуйте лише тоді, коли вам потрібна резервність (наприклад, rescue bot) або жорстка ізоляція. - Так, але ви маєте ізолювати: + Так, але вам потрібно ізолювати: - - `OPENCLAW_CONFIG_PATH` (окрема конфігурація для кожного інстансу) - - `OPENCLAW_STATE_DIR` (окремий стан для кожного інстансу) - - `agents.defaults.workspace` (ізоляція робочого простору) + - `OPENCLAW_CONFIG_PATH` (окрема конфігурація для кожного екземпляра) + - `OPENCLAW_STATE_DIR` (окремий state для кожного екземпляра) + - `agents.defaults.workspace` (ізоляція workspace) - `gateway.port` (унікальні порти) Швидке налаштування (рекомендовано): - - Використовуйте `openclaw --profile ...` для кожного інстансу (автоматично створює `~/.openclaw-`). - - Установіть унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). - - Установіть service для кожного профілю: `openclaw --profile gateway install`. + - Використовуйте `openclaw --profile ...` для кожного екземпляра (автоматично створює `~/.openclaw-`). + - Задайте унікальний `gateway.port` у конфігурації кожного профілю (або передавайте `--port` для ручних запусків). + - Встановіть сервіс для кожного профілю: `openclaw --profile gateway install`. - Профілі також додають суфікси до назв service (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). - Повний посібник: [Кілька gateway](/uk/gateway/multiple-gateways). + Профілі також додають суфікс до назв сервісів (`ai.openclaw.`; застарілі `com.openclaw.*`, `openclaw-gateway-.service`, `OpenClaw Gateway ()`). + Повний посібник: [Multiple gateways](/uk/gateway/multiple-gateways). - Gateway — це **WebSocket server**, і він очікує, що найпершим повідомленням - буде frame `connect`. Якщо він отримує щось інше, то закриває з’єднання + Gateway — це **сервер WebSocket**, і він очікує, що першим повідомленням + буде кадр `connect`. Якщо він отримує щось інше, то закриває з’єднання з **code 1008** (порушення політики). Поширені причини: - Ви відкрили **HTTP** URL у браузері (`http://...`) замість WS-клієнта. - Ви використали неправильний порт або шлях. - - Проксі або tunnel видалив заголовки автентифікації чи надіслав не-Gateway-запит. + - Proxy або tunnel видалив заголовки auth або надіслав запит не до Gateway. Швидкі виправлення: 1. Використовуйте WS URL: `ws://:18789` (або `wss://...`, якщо HTTPS). 2. Не відкривайте WS-порт у звичайній вкладці браузера. - 3. Якщо автентифікацію ввімкнено, включіть токен/пароль у frame `connect`. + 3. Якщо auth увімкнено, передайте токен/пароль у кадрі `connect`. Якщо ви використовуєте CLI або TUI, URL має виглядати так: @@ -2887,22 +2884,22 @@ x-i18n: openclaw tui --url ws://:18789 --token ``` - Подробиці протоколу: [Протокол Gateway](/uk/gateway/protocol). + Подробиці протоколу: [Gateway protocol](/uk/gateway/protocol). -## Журналювання та налагодження +## Журнали та налагодження - + Файлові журнали (структуровані): ``` /tmp/openclaw/openclaw-YYYY-MM-DD.log ``` - Ви можете задати стабільний шлях через `logging.file`. Рівень файлового журналу керується `logging.level`. Детальність консолі керується `--verbose` і `logging.consoleLevel`. + Ви можете задати стабільний шлях через `logging.file`. Рівень файлового журналювання контролюється `logging.level`. Детальність консолі контролюється через `--verbose` і `logging.consoleLevel`. Найшвидший перегляд хвоста журналу: @@ -2910,17 +2907,17 @@ x-i18n: openclaw logs --follow ``` - Журнали service/supervisor (коли gateway запускається через launchd/systemd): + Журнали сервісу/супервізора (коли gateway працює через launchd/systemd): - - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; профілі використовують `~/.openclaw-/logs/...`) + - macOS: `$OPENCLAW_STATE_DIR/logs/gateway.log` і `gateway.err.log` (типово: `~/.openclaw/logs/...`; для профілів — `~/.openclaw-/logs/...`) - Linux: `journalctl --user -u openclaw-gateway[-].service -n 200 --no-pager` - Windows: `schtasks /Query /TN "OpenClaw Gateway ()" /V /FO LIST` - Докладніше див. в [Усуненні несправностей](/uk/gateway/troubleshooting). + Докладніше див. у [Troubleshooting](/uk/gateway/troubleshooting). - + Використовуйте допоміжні команди gateway: ```bash @@ -2928,16 +2925,16 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути порт. Див. [Gateway](/uk/gateway). + Якщо ви запускаєте gateway вручну, `openclaw gateway --force` може повернути собі порт. Див. [Gateway](/uk/gateway). - Є **два режими встановлення в Windows**: + Є **два режими встановлення у Windows**: **1) WSL2 (рекомендовано):** Gateway працює всередині Linux. - Відкрийте PowerShell, увійдіть у WSL, а потім перезапустіть: + Відкрийте PowerShell, увійдіть у WSL, потім перезапустіть: ```powershell wsl @@ -2945,7 +2942,7 @@ x-i18n: openclaw gateway restart ``` - Якщо ви ніколи не встановлювали service, запустіть його у foreground: + Якщо ви ніколи не встановлювали сервіс, запустіть його на передньому плані: ```bash openclaw gateway run @@ -2960,18 +2957,18 @@ x-i18n: openclaw gateway restart ``` - Якщо ви запускаєте його вручну (без service), використовуйте: + Якщо ви запускаєте його вручну (без сервісу), використовуйте: ```powershell openclaw gateway run ``` - Документація: [Windows (WSL2)](/uk/platforms/windows), [Операційний посібник служби Gateway](/uk/gateway). + Документація: [Windows (WSL2)](/uk/platforms/windows), [Gateway service runbook](/uk/gateway). - - Почніть із швидкої перевірки працездатності: + + Почніть із швидкої перевірки стану: ```bash openclaw status @@ -2982,24 +2979,24 @@ x-i18n: Поширені причини: - - Автентифікацію моделі не завантажено на **хості gateway** (перевірте `models status`). - - Спарювання каналу/allowlist блокує відповіді (перевірте конфігурацію каналу + журнали). + - Auth моделі не завантажено на **хості gateway** (перевірте `models status`). + - Pairing/allowlist каналу блокує відповіді (перевірте конфігурацію channel + журнали). - WebChat/Dashboard відкрито без правильного токена. - Якщо ви працюєте віддалено, переконайтеся, що з’єднання tunnel/Tailscale активне і що + Якщо ви працюєте віддалено, переконайтеся, що tunnel/Tailscale-з’єднання підняте і що Gateway WebSocket доступний. - Документація: [Канали](/uk/channels), [Усунення несправностей](/uk/gateway/troubleshooting), [Віддалений доступ](/uk/gateway/remote). + Документація: [Channels](/uk/channels), [Troubleshooting](/uk/gateway/troubleshooting), [Remote access](/uk/gateway/remote). - + Зазвичай це означає, що UI втратив з’єднання WebSocket. Перевірте: - 1. Чи працює Gateway? `openclaw gateway status` + 1. Чи запущений Gateway? `openclaw gateway status` 2. Чи справний Gateway? `openclaw status` 3. Чи має UI правильний токен? `openclaw dashboard` - 4. Якщо віддалено, чи активне з’єднання tunnel/Tailscale? + 4. Якщо віддалено, чи працює tunnel/Tailscale-з’єднання? Потім перегляньте журнали: @@ -3007,31 +3004,31 @@ x-i18n: openclaw logs --follow ``` - Документація: [Dashboard](/uk/web/dashboard), [Віддалений доступ](/uk/gateway/remote), [Усунення несправностей](/uk/gateway/troubleshooting). + Документація: [Dashboard](/uk/web/dashboard), [Remote access](/uk/gateway/remote), [Troubleshooting](/uk/gateway/troubleshooting). - - Почніть із журналів і стану каналу: + + Почніть із журналів і статусу channel: ```bash openclaw channels status openclaw channels logs --channel telegram ``` - Потім зіставте з помилкою: + Далі зіставте з помилкою: - - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато записів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд Plugin/Skill/власних команд або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. - - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволено і DNS працює для `api.telegram.org`. + - `BOT_COMMANDS_TOO_MUCH`: у меню Telegram забагато елементів. OpenClaw уже обрізає список до ліміту Telegram і повторює спробу з меншою кількістю команд, але деякі записи меню все одно потрібно прибрати. Зменште кількість команд plugin/skill/custom або вимкніть `channels.telegram.commands.native`, якщо меню вам не потрібне. + - `TypeError: fetch failed`, `Network request for 'setMyCommands' failed!` або подібні мережеві помилки: якщо ви на VPS або за proxy, переконайтеся, що вихідний HTTPS дозволений і DNS працює для `api.telegram.org`. - Якщо Gateway віддалений, переконайтеся, що ви дивитеся журнали на хості Gateway. + Якщо Gateway віддалений, переконайтеся, що ви дивитесь журнали саме на хості Gateway. - Документація: [Telegram](/uk/channels/telegram), [Усунення несправностей каналів](/uk/channels/troubleshooting). + Документація: [Telegram](/uk/channels/telegram), [Channel troubleshooting](/uk/channels/troubleshooting). - - Спочатку переконайтеся, що Gateway доступний і агент може запускатися: + + Спочатку переконайтеся, що Gateway доступний і агент може працювати: ```bash openclaw status @@ -3039,53 +3036,53 @@ x-i18n: openclaw logs --follow ``` - У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в чат- - каналі, переконайтеся, що доставку ввімкнено (`/deliver on`). + У TUI використовуйте `/status`, щоб побачити поточний стан. Якщо ви очікуєте відповіді в chat + channel, переконайтеся, що доставку увімкнено (`/deliver on`). - Документація: [TUI](/uk/web/tui), [Слеш-команди](/uk/tools/slash-commands). + Документація: [TUI](/uk/web/tui), [Slash commands](/uk/tools/slash-commands). - - Якщо ви встановили service: + + Якщо ви встановили сервіс: ```bash openclaw gateway stop openclaw gateway start ``` - Це зупиняє/запускає **керовану service** (launchd на macOS, systemd на Linux). - Використовуйте це, коли Gateway працює у фоновому режимі як daemon. + Це зупиняє/запускає **керований сервіс** (launchd на macOS, systemd на Linux). + Використовуйте це, коли Gateway працює у фоновому режимі як демон. - Якщо ви запускаєте у foreground, зупиніть через Ctrl-C, а потім: + Якщо ви запускаєте його на передньому плані, зупиніть через Ctrl-C, потім: ```bash openclaw gateway run ``` - Документація: [Операційний посібник служби Gateway](/uk/gateway). + Документація: [Gateway service runbook](/uk/gateway). - - - `openclaw gateway restart`: перезапускає **фонову service** (launchd/systemd). - - `openclaw gateway`: запускає gateway **у foreground** для цієї сесії термінала. + + - `openclaw gateway restart`: перезапускає **фоновий сервіс** (launchd/systemd). + - `openclaw gateway`: запускає gateway **на передньому плані** для цієї сесії термінала. - Якщо ви встановили service, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли - вам потрібен одноразовий запуск у foreground. + Якщо ви встановили сервіс, використовуйте команди gateway. Використовуйте `openclaw gateway`, коли + вам потрібен одноразовий запуск на передньому плані. - - Запустіть Gateway з `--verbose`, щоб отримати більше деталей у консолі. Потім перевірте файл журналу на предмет автентифікації каналу, маршрутизації моделей і помилок RPC. + + Запустіть Gateway з `--verbose`, щоб отримати докладніший консольний вивід. Потім перевірте файл журналу на предмет auth channel, маршрутизації моделі та помилок RPC. ## Медіа та вкладення - - Вихідні вкладення від агента мають містити рядок `MEDIA:` (в окремому рядку). Див. [Налаштування помічника OpenClaw](/uk/start/openclaw) і [Надсилання Agent](/uk/tools/agent-send). + + Вихідні вкладення від агента мають містити рядок `MEDIA:` (окремим рядком). Див. [OpenClaw assistant setup](/uk/start/openclaw) і [Agent send](/uk/tools/agent-send). Надсилання через CLI: @@ -3095,12 +3092,12 @@ x-i18n: Також перевірте: - - Цільовий канал підтримує вихідні медіа і не блокується allowlist. - - Файл не перевищує ліміти розміру provider (зображення змінюють розмір до максимуму 2048px). - - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів робочим простором, temp/media-store і файлами, перевіреними пісочницею. - - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа та безпечних типів документів (зображення, аудіо, відео, PDF і документи Office). Звичайні текстові та схожі на секрети файли все одно блокуються. + - Цільовий channel підтримує вихідні медіа й не блокується allowlists. + - Файл не перевищує обмеження розміру провайдера (зображення змінюються до максимуму 2048px). + - `tools.fs.workspaceOnly=true` обмежує надсилання локальних шляхів workspace, temp/media-store і файлами, перевіреними sandbox. + - `tools.fs.workspaceOnly=false` дозволяє `MEDIA:` надсилати локальні файли хоста, які агент уже може читати, але лише для медіа плюс безпечних типів документів (зображення, аудіо, відео, PDF і Office-документи). Звичайні текстові та схожі на секрети файли все одно блокуються. - Див. [Зображення](/uk/nodes/images). + Див. [Images](/uk/nodes/images). @@ -3109,112 +3106,111 @@ x-i18n: - Розглядайте вхідні DM як недовірений вхідний вміст. Поведінка за замовчуванням спрямована на зменшення ризику: + Ставтеся до вхідних DM як до недовіреного вводу. Значення за замовчуванням розроблені так, щоб зменшувати ризик: - - Типова поведінка на каналах, що підтримують DM, — це **pairing**: - - Невідомі відправники отримують код pairing; бот не обробляє їхнє повідомлення. - - Погодження через: `openclaw pairing approve --channel [--account ] ` - - Кількість pending-запитів обмежена **3 на канал**; перевірте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. - - Відкрити DM публічно можна лише через явне opt-in (`dmPolicy: "open"` і allowlist `"*"`). + - Типова поведінка на channels, що підтримують DM, — це **pairing**: + - Невідомі відправники отримують pairing code; бот не обробляє їхнє повідомлення. + - Схвалення: `openclaw pairing approve --channel [--account ] ` + - Кількість очікуваних запитів обмежена **3 на channel**; перевіряйте `openclaw pairing list --channel [--account ]`, якщо код не надійшов. + - Публічне відкриття DM потребує явної згоди (`dmPolicy: "open"` і allowlist `"*"`). Запустіть `openclaw doctor`, щоб виявити ризиковані політики DM. - - Ні. Prompt injection стосується **недовіреного вмісту**, а не лише того, хто може написати боту в DM. - Якщо ваш помічник читає зовнішній вміст (web search/fetch, сторінки в browser, email, + + Ні. Prompt injection — це про **недовірений вміст**, а не лише про те, хто може писати боту в DM. + Якщо ваш помічник читає зовнішній вміст (web search/fetch, сторінки браузера, email, документи, вкладення, вставлені журнали), цей вміст може містити інструкції, які намагаються - перехопити керування моделлю. Це може статися, навіть якщо **ви єдиний відправник**. + перехопити контроль над моделлю. Це може трапитися, навіть якщо **єдиний відправник — ви самі**. - Найбільший ризик виникає, коли ввімкнено інструменти: модель можна змусити - ексфільтрувати контекст або викликати інструменти від вашого імені. Зменшуйте радіус ураження так: + Найбільший ризик виникає, коли ввімкнено tools: модель можна змусити + витягувати контекст або викликати tools від вашого імені. Зменшуйте зону ураження так: - - використовуйте агента-"читача" лише для читання або без інструментів, щоб підсумовувати недовірений вміст - - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими інструментами - - також розглядайте декодований текст файлів/документів як недовірений: OpenResponses - `input_file` і витягування з медіавкладень обгортають витягнутий текст у - явні маркери меж зовнішнього вмісту замість передавання сирого тексту файла - - використовуйте ізоляцію та суворі allowlist інструментів + - використовуйте агента «reader» лише для читання або без tools, щоб підсумовувати недовірений вміст + - тримайте `web_search` / `web_fetch` / `browser` вимкненими для агентів з увімкненими tools + - також ставтеся до декодованого тексту файлів/документів як до недовіреного: OpenResponses + `input_file` і витяг тексту з медіа-вкладень обидва обгортають витягнутий текст + явними маркерами меж зовнішнього вмісту замість передавання сирого тексту файлу + - використовуйте sandboxing і суворі tool allowlists - Подробиці: [Безпека](/uk/gateway/security). + Подробиці: [Security](/uk/gateway/security). - - Так, для більшості налаштувань. Ізоляція бота в окремих облікових записах і номерах телефону - зменшує радіус ураження, якщо щось піде не так. Це також спрощує ротацію + + Так, для більшості конфігурацій. Ізоляція бота за допомогою окремих облікових записів і номерів телефону + зменшує зону ураження, якщо щось піде не так. Це також спрощує ротацію облікових даних або відкликання доступу без впливу на ваші особисті облікові записи. - Починайте з малого. Надавайте доступ лише до тих інструментів і облікових записів, які вам справді потрібні, і розширюйте - пізніше за потреби. + Починайте з малого. Надавайте доступ лише до тих tools і облікових записів, які вам справді потрібні, і за + потреби розширюйте пізніше. - Документація: [Безпека](/uk/gateway/security), [Pairing](/uk/channels/pairing). + Документація: [Security](/uk/gateway/security), [Pairing](/uk/channels/pairing). - - Ми **не** рекомендуємо повну автономність над вашими особистими повідомленнями. Найбезпечніший шаблон такий: + + Ми **не** рекомендуємо повну автономність щодо ваших особистих повідомлень. Найбезпечніший шаблон такий: - - Тримайте DM у **режимі pairing** або зі строгим allowlist. - - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він писав від вашого імені. - - Дозвольте йому створити чернетку, а потім **погоджуйте перед надсиланням**. + - Тримайте DM у режимі **pairing** або зі строгим allowlist. + - Використовуйте **окремий номер або обліковий запис**, якщо хочете, щоб він надсилав повідомлення від вашого імені. + - Дозвольте йому створювати чернетки, а потім **схвалюйте перед надсиланням**. - Якщо хочете поекспериментувати, робіть це на окремому обліковому записі та тримайте його ізольованим. Див. - [Безпека](/uk/gateway/security). + Якщо хочете поекспериментувати, робіть це на окремому обліковому записі й тримайте його ізольованим. Див. + [Security](/uk/gateway/security). - Так, **якщо** агент працює лише в чаті, а вхідний вміст є довіреним. Менші моделі - більш схильні до перехоплення інструкцій, тому уникайте їх для агентів з увімкненими інструментами - або під час читання недовіреного вмісту. Якщо вам усе ж потрібна менша модель, обмежте - інструменти й запускайте все в пісочниці. Див. [Безпека](/uk/gateway/security). + Так, **якщо** агент працює лише в чаті, а вхідні дані довірені. Менші рівні + більш схильні до перехоплення інструкцій, тож уникайте їх для агентів з увімкненими tools + або під час читання недовіреного вмісту. Якщо вам усе ж потрібна менша модель, жорстко обмежте + tools і запускайте всередині sandbox. Див. [Security](/uk/gateway/security). - - Коди pairing надсилаються **лише** коли невідомий відправник пише боту і + + Pairing codes надсилаються **лише** тоді, коли невідомий відправник пише боту і ввімкнено `dmPolicy: "pairing"`. Сам по собі `/start` не генерує код. - Перевірте pending-запити: + Перевірте очікувані запити: ```bash openclaw pairing list telegram ``` - Якщо хочете негайний доступ, додайте свій sender id до allowlist або встановіть `dmPolicy: "open"` + Якщо вам потрібен негайний доступ, додайте свій id відправника в allowlist або задайте `dmPolicy: "open"` для цього облікового запису. - Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише код pairing, і їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які він отримує, або на явні надсилання, які запускаєте ви. + Ні. Типова політика WhatsApp DM — **pairing**. Невідомі відправники отримують лише pairing code, а їхнє повідомлення **не обробляється**. OpenClaw відповідає лише на чати, які отримує, або на явні надсилання, які ви ініціюєте. - Погодження pairing через: + Схвалення pairing: ```bash openclaw pairing approve whatsapp ``` - Перегляд pending-запитів: + Перелік очікуваних запитів: ```bash openclaw pairing list whatsapp ``` - Запит номера телефону в майстрі: він використовується для встановлення вашого **allowlist/owner**, щоб дозволити ваші власні DM. Він не використовується для автонadсилання. Якщо ви запускаєте на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. + Запит номера телефону в майстрі: він використовується, щоб налаштувати ваш **allowlist/owner**, аби ваші власні DM були дозволені. Він не використовується для автоматичного надсилання. Якщо ви запускаєте систему на своєму особистому номері WhatsApp, використовуйте цей номер і ввімкніть `channels.whatsapp.selfChatMode`. -## Команди чату, скасування завдань і "він не зупиняється" +## Команди чату, переривання завдань і "воно не зупиняється" - - Більшість внутрішніх або службових повідомлень з’являються лише тоді, коли для цієї сесії ввімкнено - **verbose**, **trace** або **reasoning**. + + Більшість внутрішніх або tool-повідомлень з’являються лише коли для цієї сесії увімкнено **verbose**, **trace** або **reasoning**. - Виправлення в тому чаті, де ви це бачите: + Виправлення в чаті, де ви це бачите: ``` /verbose off @@ -3222,16 +3218,16 @@ x-i18n: /reasoning off ``` - Якщо все ще надто шумно, перевірте налаштування сесії в Control UI і встановіть verbose - у значення **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з параметром `verboseDefault`, - установленим у `on` у конфігурації. + Якщо все одно занадто шумно, перевірте налаштування сесії в Control UI і задайте verbose + як **inherit**. Також переконайтеся, що ви не використовуєте профіль бота з `verboseDefault`, встановленим + у `on` у конфігурації. - Документація: [Thinking і verbose](/uk/tools/thinking), [Безпека](/uk/gateway/security#reasoning-verbose-output-in-groups). + Документація: [Thinking and verbose](/uk/tools/thinking), [Security](/uk/gateway/security#reasoning-verbose-output-in-groups). - - Надішліть будь-що з цього **окремим повідомленням** (без слеша): + + Надішліть будь-яке з цього **як окреме повідомлення** (без слеша): ``` stop @@ -3255,25 +3251,25 @@ x-i18n: interrupt ``` - Це тригери скасування (не слеш-команди). + Це тригери переривання (не slash-команди). - Для фонових процесів (з інструмента exec) ви можете попросити агента виконати: + Для фонових процесів (з tool exec) ви можете попросити агента виконати: ``` process action:kill sessionId:XXX ``` - Огляд слеш-команд: див. [Слеш-команди](/uk/tools/slash-commands). + Огляд slash-команд: див. [Slash commands](/uk/tools/slash-commands). - Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (наприклад, `/status`) також працюють inline для відправників в allowlist. + Більшість команд потрібно надсилати як **окреме** повідомлення, що починається з `/`, але кілька скорочень (як-от `/status`) також працюють inline для відправників з allowlist. - - OpenClaw типово блокує повідомлення **між різними provider**. Якщо виклик інструмента прив’язаний - до Telegram, він не надсилатиме в Discord, якщо ви явно не дозволите це. + + OpenClaw за замовчуванням блокує повідомлення **між різними провайдерами**. Якщо виклик tool прив’язаний + до Telegram, він не надсилатиме в Discord, якщо ви явно цього не дозволите. - Увімкніть крос-provider-повідомлення для агента: + Увімкніть міжпровайдерні повідомлення для агента: ```json5 { @@ -3292,28 +3288,28 @@ x-i18n: - - Режим черги визначає, як нові повідомлення взаємодіють із запуском, що вже виконується. Використовуйте `/queue`, щоб змінити режими: + + Режим queue визначає, як нові повідомлення взаємодіють із уже активним запуском. Використовуйте `/queue`, щоб змінити режими: - - `steer` — нові повідомлення перенаправляють поточне завдання - - `followup` — повідомлення виконуються по одному - - `collect` — пакетування повідомлень і одна відповідь (типово) - - `steer-backlog` — спрямувати зараз, а потім обробити backlog - - `interrupt` — скасувати поточний запуск і почати заново + - `steer` - нові повідомлення перенаправляють поточне завдання + - `followup` - повідомлення виконуються по одному + - `collect` - повідомлення збираються в пакет і відповідь надсилається один раз (типово) + - `steer-backlog` - спочатку перенаправлення, потім обробка черги + - `interrupt` - перервати поточний запуск і почати заново - Можна додавати параметри на кшталт `debounce:2s cap:25 drop:summarize` для режимів followup. + Ви можете додавати параметри, такі як `debounce:2s cap:25 drop:summarize` для режимів followup. -## Інше +## Різне - - В OpenClaw облікові дані та вибір моделі — це окремі речі. Установлення `ANTHROPIC_API_KEY` (або збереження API key Anthropic у профілях автентифікації) вмикає автентифікацію, але фактичною типовою моделлю є те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який запущено. + + В OpenClaw облікові дані й вибір моделі розділені. Установлення `ANTHROPIC_API_KEY` (або збереження API key Anthropic у профілях auth) увімкне автентифікацію, але фактична модель за замовчуванням — це те, що ви налаштували в `agents.defaults.model.primary` (наприклад, `anthropic/claude-sonnet-4-6` або `anthropic/claude-opus-4-6`). Якщо ви бачите `No credentials found for profile "anthropic:default"`, це означає, що Gateway не зміг знайти облікові дані Anthropic в очікуваному `auth-profiles.json` для агента, який виконується. --- -Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [обговорення GitHub](https://github.com/openclaw/openclaw/discussions). +Усе ще застрягли? Запитайте в [Discord](https://discord.com/invite/clawd) або відкрийте [GitHub discussion](https://github.com/openclaw/openclaw/discussions). diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index f0f61f008..ec9127361 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,13 +3,13 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для багів моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та що охоплює кожен тест' +summary: 'Набір для тестування: набори unit/e2e/live, Docker-ранери та те, що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T19:48:40Z" + generated_at: "2026-04-23T20:05:11Z" model: gpt-5.4 provider: openai - source_hash: a868c91c94d862b75375a90bc9b5b0d8cf618e81c437e275ef1830c4a3a70c38 + source_hash: 28472f335f77c8e1d126b64b38b4841867aff2edd5f87438fcd904d421ec37cf source_path: help/testing.md workflow: 15 --- @@ -17,158 +17,158 @@ x-i18n: OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker-ранерів. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. +- Як додавати регресійні тести для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: -- Повний контрольний прогін (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` +- Повний гейт (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` +- Швидший локальний запуск повного набору на потужній машині: `pnpm test:max` - Прямий цикл спостереження Vitest: `pnpm test:watch` - Прямий таргетинг файлів тепер також маршрутизує шляхи extension/channel: `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` -- Коли ви ітеруєтеся над одним падінням, спочатку віддавайте перевагу цільовим запускам. +- Якщо ви ітеруєтеся над одним збоєм, спочатку віддавайте перевагу цільовим запускам. - QA-сайт на базі Docker: `pnpm qa:lab:up` - QA-лінія на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви торкаєтесь тестів або хочете додаткової впевненості: +Коли ви змінюєте тести або хочете більше впевненості: -- Контрольний прогін покриття: `pnpm test:coverage` +- Гейт покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Набір live (моделі + probe Gateway для інструментів/зображень): `pnpm test:live` -- Точково запустити один live-файл у тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` -- Docker-прогін live-моделей: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід і невеликий probe у стилі читання файлу. - Моделі, у чиїх метаданих вказано вхід `image`, також виконують мініатюрний хід із зображенням. - Вимкніть додаткові probe через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або +- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` +- Тихий запуск одного live-файлу: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Docker live sweep моделей: `pnpm test:docker:live-models` + - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку у стилі читання файлу. + Моделі, чиї метадані оголошують вхід `image`, також виконують маленький хід із зображенням. + Вимкніть додаткові перевірки за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, який включає окремі матричні job-и Docker live-моделей, - розшардовані за провайдером. - - Для точкових повторних запусків у CI dispatch-ніть `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, який включає окремі Docker live matrix job-и + із шардингом за провайдером. + - Для точкових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + - Додавайте нові high-signal секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його - запланованих/релізних викликів. -- Димовий тест вартості Moonshot/Kimi: коли встановлено `MOONSHOT_API_KEY`, виконайте - `openclaw models list --provider moonshot --json`, а потім ізольований + викликів для scheduled/release. +- Коштовнісний smoke-тест Moonshot/Kimi: якщо встановлено `MOONSHOT_API_KEY`, виконайте + `openclaw models list --provider moonshot --json`, потім запустіть ізольований `openclaw agent --local --session-id live-kimi-cost --message 'Reply exactly: KIMI_LIVE_OK' --thinking off --json` - для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6, а + для `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6 і що транскрипт асистента зберігає нормалізоване `usage.cost`. Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## Спеціальні QA-ранери +## QA-специфічні ранери -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм qa-lab: +Ці команди працюють поряд з основними наборами тестів, коли вам потрібен реалізм qa-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` виконується для відповідних PR і -з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` виконується щоночі на -`main` і з ручного dispatch з mock parity gate, live-лінією Matrix та live-лінією Telegram, -керованою Convex, як паралельними job-ами. `OpenClaw Release Checks` -запускає ті самі лінії перед схваленням релізу. +CI запускає QA Lab у виділених workflow. `Parity gate` запускається для відповідних PR і +з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і з ручного dispatch із mock parity gate, live Matrix lane та +live Telegram lane під керуванням Convex як паралельні job-и. `OpenClaw Release Checks` +запускає ті самі лінії перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає сценарії QA з репозиторію безпосередньо на хості. + - Запускає QA-сценарії з репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - воркерами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежується + Gateway-воркерами. `qa-channel` за замовчуванням має concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість воркерів, або `--concurrency 1` для старішої послідовної лінії. - - Завершується з ненульовим кодом, якщо будь-який сценарій падає. Використовуйте `--allow-failures`, коли + кількість воркерів, або `--concurrency 1` для старої послідовної лінії. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстур і протокольних mock-ів, не замінюючи орієнтовану на сценарії + покриття фікстур і моків протоколу, не замінюючи при цьому сценарно-орієнтовану лінію `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий набір QA усередині одноразової Linux VM Multipass. + - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для гостьової системи: - ключі провайдерів на основі env, шлях до конфігурації QA live provider та `CODEX_HOME`, - якщо він присутній. + - Live-запуски пересилають підтримувані вхідні дані автентифікації QA, які практичні для гостьової системи: + ключі провайдера на основі env, шлях до конфігурації QA live-провайдера та `CODEX_HOME`, + якщо присутній. - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через змонтований workspace. - - Записує звичайний QA-звіт + підсумок, а також журнали Multipass у + - Записує звичайний QA-звіт і зведення, а також логи Multipass у `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball із поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивне налаштування з API-ключем OpenAI, за замовчуванням - налаштовує Telegram, перевіряє, що ввімкнення plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти mock-endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму лінію - встановлення з пакета з Discord. + Docker, виконує неінтерактивний онбординг OpenAI API key, за замовчуванням + налаштовує Telegram, перевіряє, що ввімкнення Plugin встановлює runtime-залежності на вимогу, + запускає doctor і виконує один локальний хід агента проти замоканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму + лінію встановлення з пакета для Discord. - `pnpm test:docker:bundled-channel-deps` - - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway - зі сконфігурованим OpenAI, а потім вмикає bundled channel/plugins через + - Пакує і встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, потім вмикає вбудовані channel/Plugin-и через редагування конфігурації. - Перевіряє, що виявлення налаштування залишає runtime-залежності - несконфігурованих plugins відсутніми, що перший сконфігурований запуск Gateway або doctor встановлює - runtime-залежності кожного bundled plugin за потреби, і що другий перезапуск не перевстановлює - залежності, які вже були активовані. - - Також установлює відому старішу npm-базову версію, вмикає Telegram перед запуском - `openclaw update --tag `, і перевіряє, що doctor кандидата - після оновлення відновлює runtime-залежності bundled channel без - postinstall-відновлення з боку harness. + неналаштованих Plugin-ів відсутніми, що перший налаштований запуск Gateway або doctor + встановлює runtime-залежності кожного вбудованого Plugin на вимогу, і що другий + перезапуск не перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата після оновлення + відновлює runtime-залежності вбудованих channel без postinstall-відновлення + з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямого димового - тестування протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування + протоколу. - `pnpm openclaw qa matrix` - - Запускає live-лінію QA Matrix проти одноразового homeserver Tuwunel на базі Docker. - - Цей хост QA сьогодні призначений лише для repo/dev. Упаковані встановлення OpenClaw не постачають + - Запускає live QA-лінію Matrix проти тимчасового Tuwunel homeserver на базі Docker. + - Цей QA-хост наразі призначений лише для репозиторію/розробки. Паковані встановлення OpenClaw не постачають `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок - встановлення plugin не потрібен. - - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway із реальним Matrix plugin як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. - - Matrix не надає спільних прапорців джерела облікових даних, оскільки лінія локально створює одноразових користувачів. - - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - Checkout-и репозиторію завантажують вбудований раннер напряму; окремий крок + встановлення Plugin не потрібен. + - Створює трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, потім запускає дочірній QA Gateway із реальним Plugin Matrix як транспортом SUT. + - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки лінія локально створює тимчасових користувачів. + - Записує QA-звіт Matrix, зведення, артефакт observed-events і комбінований лог виводу stdout/stderr у `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live-лінію QA Telegram проти реальної приватної групи, використовуючи токени бота driver і SUT з env. + - Запускає live QA-лінію Telegram проти реальної приватної групи з використанням токенів ботів driver і SUT з env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулованих облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пуловані оренди. - - Завершується з ненульовим кодом, якщо будь-який сценарій падає. Використовуйте `--allow-failures`, коли + - Підтримує `--credential-source convex` для спільних пулових облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані спільні облікові дані. + - Завершується з ненульовим кодом, якщо будь-який сценарій не вдався. Використовуйте `--allow-failures`, якщо вам потрібні артефакти без коду завершення з помилкою. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує QA-звіт Telegram, підсумок і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостереженої відповіді SUT. + - Потребує двох різних ботів в одній приватній групі, при цьому бот SUT має надавати Telegram username. + - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, зведення та артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на відправлення driver до спостереженої відповіді SUT. -Live-транспортні лінії використовують єдиний стандартний контракт, щоб нові транспорти не розходилися: +Live-транспортні лінії мають один спільний стандартний контракт, щоб нові транспорти не дрейфували: -`qa-channel` залишається широким синтетичним набором QA і не є частиною матриці покриття live-транспорту. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live-транспорту. -| Лінія | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження реакцій | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Gating згадувань | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальші дії в треді | Ізоляція тредів | Спостереження реакцій | Команда help | +| -------- | ------ | ---------------- | -------------------- | ------------------------- | ----------------------------- | -------------------- | --------------- | --------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -для цієї оренди, поки лінія виконується, і звільняє оренду під час завершення роботи. +для цієї оренди, поки лінія працює, і звільняє оренду під час завершення роботи. -Еталонний каркас проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` Обов’язкові env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) + - Env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (за замовчуванням `ci` у CI, інакше `maintainer`) Необов’язкові env-змінні: @@ -178,14 +178,14 @@ QA lab отримує ексклюзивну оренду з пулу на ба - `OPENCLAW_QA_CREDENTIAL_HTTP_TIMEOUT_MS` (за замовчуванням `15000`) - `OPENCLAW_QA_CONVEX_ENDPOINT_PREFIX` (за замовчуванням `/qa-credentials/v1`) - `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) -- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL-адреси Convex лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністративні команди для супровідників (додавання/видалення/список пулу) вимагають +Адміністративні команди maintainer (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-допоміжні команди для супровідників: +CLI-хелпери для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -193,7 +193,7 @@ pnpm openclaw qa credentials list --kind telegram pnpm openclaw qa credentials remove --credential-id ``` -Використовуйте `--json` для машинозчитуваного виводу в скриптах і утилітах CI. +Використовуйте `--json` для машиночитаного виводу в скриптах і утилітах CI. Контракт endpoint за замовчуванням (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): @@ -213,7 +213,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист від активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -224,27 +224,27 @@ pnpm openclaw qa credentials remove --credential-id - `groupId` має бути рядком із числовим Telegram chat id. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. -### Додавання каналу до QA +### Додавання channel до QA -Додавання каналу до markdown-системи QA вимагає рівно двох речей: +Додавання channel до markdown-системи QA потребує рівно двох речей: -1. Транспортного адаптера для каналу. -2. Набору сценаріїв, який перевіряє контракт каналу. +1. Транспортного адаптера для channel. +2. Пакета сценаріїв, який перевіряє контракт channel. -Не додавайте новий кореневий QA-командний рівень, якщо спільний хост `qa-lab` може -керувати цим потоком. +Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може +володіти цим потоком. -`qa-lab` відповідає за спільну хостову механіку: +`qa-lab` відповідає за спільну механіку хоста: -- кореневу команду `openclaw qa` -- запуск і завершення suite +- кореневий простір команд `openclaw qa` +- запуск і завершення набору - concurrency воркерів - запис артефактів - генерацію звітів - виконання сценаріїв -- compatibility aliases для старіших сценаріїв `qa-channel` +- alias-и сумісності для старіших сценаріїв `qa-channel` -Runner plugins відповідають за транспортний контракт: +Runner Plugin-и відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` - як Gateway налаштовується для цього транспорту @@ -252,27 +252,27 @@ Runner plugins відповідають за транспортний контр - як інжектяться вхідні події - як спостерігаються вихідні повідомлення - як надаються транскрипти й нормалізований стан транспорту -- як виконуються дії, підтримувані транспортом -- як обробляється транспортно-специфічний reset або cleanup +- як виконуються дії на базі транспорту +- як обробляється transport-specific reset або cleanup -Мінімальний поріг впровадження нового каналу такий: +Мінімальний поріг впровадження для нового channel: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте transport runner на спільному host seam `qa-lab`. -3. Залишайте транспортно-специфічну механіку всередині runner plugin або harness каналу. +2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. +3. Залишайте transport-specific механіку всередині runner Plugin або harness channel. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins повинні оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoint. + Runner Plugin-и мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI й runner має залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте загальні scenario helpers для нових сценаріїв. -7. Зберігайте працездатність наявних compatibility aliases, якщо тільки в репозиторії не виконується навмисна міграція. +6. Використовуйте generic helper-и для нових сценаріїв. +7. Зберігайте працездатність наявних alias-ів сумісності, якщо тільки репозиторій не виконує навмисну міграцію. Правило прийняття рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного транспорту каналу, залишайте її в цьому runner plugin або plugin harness. -- Якщо сценарію потрібна нова можливість, якою може користуватися більше ніж один канал, додавайте загальний helper замість channel-specific гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно фіксуйте це в контракті сценарію. +- Якщо поведінка залежить від одного channel transport, залишайте її в runner Plugin або harness цього plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один channel, додавайте generic helper замість channel-specific гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій transport-specific і явно відображайте це в контракті сценарію. Бажані назви generic helper для нових сценаріїв: @@ -289,7 +289,7 @@ Runner plugins відповідають за транспортний контр - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: +Alias-и сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -297,291 +297,293 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic helper names. -Compatibility aliases існують, щоб уникнути міграції в стилі flag day, а не як модель для +Нова робота з channel має використовувати generic назви helper-ів. +Alias-и сумісності існують, щоб уникнути міграції в один день, а не як модель для створення нових сценаріїв. ## Набори тестів (що де запускається) -Сприймайте набори як «зростання реалізму» (і зростання нестабільності/вартості): +Сприймайте набори як «зростаючий реалізм» (і зростаючу flaky/cost): ### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: нетаргетовані запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project шарди в per-project конфігурації для паралельного планування -- Файли: core/unit inventory у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist node-тести `ui`, які покриває `vitest.unit.config.ts` +- Конфіг: нетаргетовані запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати багатопроєктні шарди в конфігурації для окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, що покриваються `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) + - Внутрішньопроцесні integration-тести (автентифікація Gateway, маршрутизація, tooling, парсинг, config) - Детерміновані регресії для відомих багів - Очікування: - Запускається в CI - Реальні ключі не потрібні - Має бути швидким і стабільним - - Нетаргетовані запуски `pnpm test` використовують дванадцять менших shard-конфігурацій (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` як і раніше використовує native root-граф проєкту `vitest.config.ts`, оскільки цикл спостереження з multi-shard не є практичним. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні target файлу/каталогу через scoped lanes, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable source/test файлів; редагування config/setup, як і раніше, повертаються до широкого повторного запуску root project. - `pnpm check:changed` — це стандартний розумний локальний контрольний прогін для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні lanes typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають перевірку extensions, оскільки extensions залежать від цих core-контрактів. Оновлення версій, що стосуються лише release metadata, запускають таргетовані перевірки version/config/root-dependency замість повного набору, із захистом, який відхиляє зміни package поза полем версії верхнього рівня. - Полегшені з точки зору імпортів unit-тести для agents, commands, plugins, helper-функцій auto-reply, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через lane `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; файли зі stateful/runtime-heavy поведінкою залишаються на наявних lanes. - Вибрані helper source-файли `plugin-sdk` і `commands` також відображають changed-mode запуски на явні sibling-тести в цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три виділені bucket: helper-функції core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це прибирає найважчу роботу harness reply із дешевих тестів status/chunk/token. + - Нетаргетований `pnpm test` запускає дванадцять менших конфігурацій шардів (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу root project. Це зменшує піковий RSS на навантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` як і раніше використовує native граф проєктів root `vitest.config.ts`, оскільки цикл watch із багатьма шардами непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файлів/каталогів через scope-нуті лінії, тож `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scope-нуті лінії, коли diff торкається лише маршрутованих файлів source/test; редагування config/setup як і раніше повертаються до широкого перезапуску root project. - `pnpm check:changed` — це звичайний розумний локальний гейт для вузької роботи. Він класифікує diff на core, тести core, extensions, тести extension, apps, docs, release metadata і tooling, а потім запускає відповідні лінії typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають валідацію extension, оскільки extensions залежать від цих core-контрактів. Version bump-и лише в release metadata запускають цільові перевірки version/config/root-dependency замість повного набору, із guard, який відхиляє зміни пакетів поза полем version верхнього рівня. - Unit-тести з малими import із agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих utility-областей маршрутизуються через лінію `unit-fast`, яка пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних лініях. - Вибрані helper source-файли `plugin-sdk` і `commands` також маплять запуски в режимі changed на явні sibling-тести в цих легких лініях, тож редагування helper-ів не змушують повторно запускати повний важкий набір для цього каталогу. - `auto-reply` має три виділені бакети: helper-и core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. - - Коли ви змінюєте вхідні дані для виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте вузько сфокусовані helper-регресії для чистих меж маршрутизації та нормалізації. - - Підтримуйте в робочому стані integration suites embedded runner: + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, зберігайте обидва рівні покриття. + - Додавайте сфокусовані helper-регресії для чистих меж маршрутизації та нормалізації. + - Підтримуйте інтеграційні набори embedded runner у здоровому стані: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка Compaction, як і раніше, проходять + - Ці набори перевіряють, що scope-нуті id і поведінка Compaction як і раніше проходять через реальні шляхи `run.ts` / `compact.ts`; helper-only тести не є достатньою заміною для цих integration-шляхів. - - - Базова конфігурація Vitest за замовчуванням використовує `threads`. - - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - non-isolated runner в root projects, а також у конфігураціях e2e і live. - - Root UI lane зберігає своє налаштування `jsdom` й optimizer, але також працює на - спільному non-isolated runner. + + - Базовий конфіг Vitest за замовчуванням використовує `threads`. + - Спільний конфіг Vitest фіксує `isolate: false` і використовує + неізольований runner у root project, e2e і live-конфігах. + - Root-лінія UI зберігає свій setup `jsdom` і optimizer, але також працює на + спільному неізольованому runner. - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` - зі спільної конфігурації Vitest. + зі спільного конфігу Vitest. - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти з типовою поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. + - `pnpm changed:lanes` показує, які архітектурні лінії запускає diff. - Pre-commit hook запускає `pnpm check:changed --staged` після staged - formatting/linting, тож commit-и лише для core не оплачують вартість тестів extension, + formatting/linting, тож commit-и лише для core не сплачують вартість тестів extension, якщо вони не торкаються публічних контрактів, орієнтованих на extension. Commit-и лише з - release metadata залишаються на таргетованій - lane version/config/root-dependency. - - Якщо точний staged-набір змін уже був перевірений - рівними або сильнішими контрольними прогоном, використовуйте + release metadata залишаються на цільовій лінії + version/config/root-dependency. + - Якщо точний staged набір змін уже був перевірений + рівними або сильнішими гейтами, використовуйте `scripts/committer --fast "" `, щоб пропустити лише повторний запуск changed-scope hook. - Staged format/lint усе одно виконуються. Згадайте завершені контрольні прогони у вашому handoff. Це також прийнятно після - повторного запуску ізольованого flaky hook failure, який пройшов із scoped proof. - - `pnpm test:changed` маршрутизується через scoped lanes, коли змінені шляхи - чисто відображаються на менший набір. + Staged format/lint усе одно запускаються. Згадайте + виконані гейти у своєму handoff. Це також припустимо після повторного запуску + ізольованого flaky hook failure, якщо він проходить із scope-нутим доказом. + - `pnpm test:changed` маршрутизується через scope-нуті лінії, коли змінені шляхи + чисто мапляться на менший набір. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, лише з вищим лімітом воркерів. - - Автоматичне масштабування локальних воркерів навмисно є консервативним і знижує навантаження, - коли середнє навантаження хоста вже високе, тож кілька паралельних + - Автомасштабування локальних воркерів навмисно консервативне й відступає, + коли середнє навантаження хоста вже високе, тож кілька одночасних запусків Vitest за замовчуванням завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб reruns у changed-mode залишалися коректними, коли змінюється wiring тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на - підтримуваних хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одну явну локацію кешу для прямого profiling. + - Базовий конфіг Vitest позначає проєкти/конфіг-файли як + `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється wiring тестів. + - Конфіг зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітність Vitest про тривалість імпорту плюс - вивід import-breakdown. - - `pnpm test:perf:imports:changed` звужує той самий вигляд profiling до - файлів, змінених відносно `origin/main`. - - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із native root-project шляхом для цього закоміченого diff і виводить wall time плюс macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточне брудне дерево, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфігурацію Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль main-thread для - витрат Vitest/Vite на startup і transform. - - `pnpm test:perf:profile:runner` записує CPU+heap профілі runner для - unit-набору з вимкненим file parallelism. + - `pnpm test:perf:imports` вмикає звітність Vitest щодо тривалості import плюс + вивід деталізації import. + - `pnpm test:perf:imports:changed` обмежує той самий вигляд профілювання + файлами, зміненими від `origin/main`. + - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутований + `test:changed` із native шляхом root project для цього закоміченого diff і виводить wall time плюс max RSS на macOS. + - `pnpm test:perf:changed:bench -- --worktree` бенчмаркає поточне брудне дерево, + маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і root-конфіг Vitest. + - `pnpm test:perf:profile:main` записує CPU profile основного потоку для + накладних витрат запуску й transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує CPU+heap profile runner для + unit-набору з вимкненим файловим паралелізмом. ### Stability (Gateway) - Команда: `pnpm test:stability:gateway` -- Конфігурація: `vitest.gateway.config.ts`, примусово один воркер +- Конфіг: `vitest.gateway.config.ts`, примусово один воркер - Обсяг: - - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Пропускає синтетичне churn повідомлень gateway, пам’яті та великих payload через діагностичний шлях подій - - Виконує запити до `diagnostics.stability` через WS RPC Gateway - - Покриває helper-функції збереження diagnostic stability bundle - - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету тиску, а глибини черг для кожної сесії знову знижуються до нуля + - Запускає реальний loopback Gateway з diagnostics, увімкненими за замовчуванням + - Проганяє синтетичне churn повідомлень Gateway, пам’яті та великих payload через шлях діагностичних подій + - Запитує `diagnostics.stability` через Gateway WS RPC + - Покриває helper-и persistence для diagnostic stability bundle + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS лишаються в межах бюджету тиску, а глибина черг на сесію зменшується назад до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька lane для подальшої роботи над stability-регресіями, а не заміна повного набору Gateway + - Вузька лінія для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (димове тестування gateway) +### E2E (Gateway smoke) - Команда: `pnpm test:e2e` -- Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` +- Конфіг: `vitest.e2e.config.ts` +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести вбудованих Plugin-ів у `extensions/` - Значення runtime за замовчуванням: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - Використовує адаптивну кількість воркерів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. + - За замовчуванням працює в silent-режимі, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість воркерів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=` щоб примусово задати кількість воркерів (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` щоб знову ввімкнути докладний console output. - Обсяг: - - Наскрізна поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairing Node і важча мережева взаємодія + - Поведінка multi-instance Gateway end-to-end + - Поверхні WebSocket/HTTP, pairing Node і важчий networking - Очікування: - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Більше рухомих частин, ніж в unit-тестах (може бути повільнішим) + - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) -### E2E: димове тестування backend OpenShell +### E2E: smoke-тест бекенда OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований gateway OpenShell на хості через Docker + - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє поведінку файлової системи в remote-canonical режимі через bridge файлової системи sandbox + - Перевіряє бекенд OpenShell у OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє поведінку remote-canonical файлової системи через sandbox fs bridge - Очікування: - - Лише за явним увімкненням; не входить до стандартного запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працюючого Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише opt-in; не входить до стандартного запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і робочого Docker daemon + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий Gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1` щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` щоб вказати нестандартний CLI-бінарник або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` -- Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` +- Конфіг: `vitest.live.config.ts` +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести вбудованих Plugin-ів у `extensions/` - За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки rate limit + - Виявлення змін формату провайдера, особливостей виклику tool, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом нестабільний для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / витрачає rate limits - - Краще запускати звужені підмножини, а не «все підряд» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. -- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли вам навмисно потрібно, щоб live-тести використовували ваш реальний домашній каталог. -- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він залишає вивід прогресу `[live] ...`, але приглушує додаткове повідомлення про `~/.profile` і вимикає журнали bootstrap gateway/шум Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. -- Ротація API-ключів (специфічна для провайдера): встановлюйте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад, `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або використовуйте перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. -- Вивід прогресу/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдерів помітно активні навіть тоді, коли перехоплення консолі Vitest тихе. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, щоб рядки прогресу провайдера/gateway одразу передавалися під час live-запусків. - - Налаштовуйте Heartbeat для прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat для gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - За задумом не є CI-stable (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / використовує rate limit + - Переважно запускайте звужені підмножини, а не «все» +- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API key. +- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють config/auth-матеріали до тимчасового test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Встановлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням працює в тихішому режимі: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує логи bootstrap Gateway / chatter Bonjour. Встановіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете знову бачити повні стартові логи. +- Ротація API key (залежно від провайдера): встановіть `*_API_KEYS` у форматі через кому/крапку з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або override для конкретного live-запуску через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Вивід progress/Heartbeat: + - Live-набори тепер виводять рядки прогресу до stderr, тож під час довгих викликів провайдера помітно, що робота триває, навіть коли console capture у Vitest тихий. + - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/Gateway одразу транслюються під час live-запусків. + - Налаштовуйте Heartbeat direct-model через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? -Скористайтеся цією таблицею рішень: +Використовуйте цю таблицю рішень: -- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) -- Торкаєтеся мережевої взаємодії gateway / протоколу WS / pairing: додайте `pnpm test:e2e` -- Налагоджуєте «мій бот не працює» / специфічні для провайдера збої / виклик інструментів: запускайте звужений `pnpm test:live` +- Редагуєте логіку/тести: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Торкаєтеся networking Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагоджуєте «мій бот не працює» / збої конкретного провайдера / виклик tool: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android Node +## Live: sweep можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яку наразі рекламує** підключений Android Node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. - Обсяг: - - Попередньо підготовлене/ручне налаштування (набір не встановлює, не запускає і не виконує pairing app). - - Перевірка `node.invoke` gateway команда за командою для вибраного Android Node. + - Попередньо підготовлений / ручний setup (набір не встановлює, не запускає і не pair-ить app). + - Перевірка `node.invoke` Gateway для вибраного Android Node, команда за командою. - Необхідне попереднє налаштування: - - Android app уже підключено та спарено з gateway. - - App утримується на передньому плані. - - Для можливостей, які ви очікуєте успішно пройти, надано дозволи/згоду на захоплення. + - Android app уже підключено і pair-ено до Gateway. + - App має залишатися на передньому плані. + - Для можливостей, які ви очікуєте як успішні, мають бути надані permissions / capture consent. - Необов’язкові перевизначення цілі: - `OPENCLAW_ANDROID_NODE_ID` або `OPENCLAW_ANDROID_NODE_NAME`. - `OPENCLAW_ANDROID_GATEWAY_URL` / `OPENCLAW_ANDROID_GATEWAY_TOKEN` / `OPENCLAW_ANDROID_GATEWAY_PASSWORD`. -- Повні подробиці налаштування Android: [Android App](/uk/platforms/android) +- Повні деталі налаштування Android: [Android App](/uk/platforms/android) -## Live: димове тестування моделі (ключі профілів) +## Live: smoke-тест моделі (profile keys) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два рівні, щоб можна було ізолювати збої: -- «Пряма модель» показує, що провайдер/модель взагалі може відповідати з наданим ключем. -- «Димове тестування Gateway» показує, що повний pipeline gateway+agent працює для цієї моделі (сесії, історія, інструменти, політика sandbox тощо). +- «Direct model» показує, чи провайдер/модель узагалі може відповісти з наданим ключем. +- «Gateway smoke» показує, чи працює повний pipeline gateway+agent для цієї моделі (сесії, history, tools, policy sandbox тощо). -### Шар 1: Пряме завершення моделі (без gateway) +### Рівень 1: Direct model completion (без Gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - Перелічити виявлені моделі - - Використати `getApiKeyForModel`, щоб вибрати моделі, для яких у вас є облікові дані - - Виконати невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані + - Виконати невелике completion для кожної моделі (і цільові регресії, де потрібно) - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше його буде пропущено, щоб `pnpm test:live` залишався зосередженим на димовому тестуванні gateway + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) +- Встановіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб справді запустити цей набір; інакше він буде пропущений, щоб `pnpm test:live` залишався сфокусованим на gateway smoke - Як вибирати моделі: - - `OPENCLAW_LIVE_MODELS=modern`, щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_MODELS=all` — псевдонім для modern allowlist + - `OPENCLAW_LIVE_MODELS=modern` щоб запустити modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) + - `OPENCLAW_LIVE_MODELS=all` — це alias для modern allowlist - або `OPENCLAW_LIVE_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Прогони modern/all за замовчуванням обмежені відібраною high-signal межею; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного прогону modern або додатне число для меншого ліміту. + - Для sweep modern/all за замовчуванням застосовується curated high-signal cap; встановіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпного sweep modern або додатне число для меншого cap. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - За замовчуванням: сховище профілів і env fallback-и - - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** -- Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline агента gateway зламаний» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) + - За замовчуванням: profile store і env fallback-и + - Встановіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише profile store** +- Для чого це існує: + - Відокремлює «API провайдера зламане / ключ недійсний» від «pipeline gateway agent зламаний» + - Містить невеликі ізольовані регресії (приклад: replay reasoning OpenAI Responses/Codex Responses + потоки tool-call) -### Шар 2: Димове тестування Gateway + dev agent (що насправді робить "@openclaw") +### Рівень 2: smoke-тест Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - - Підняти in-process gateway - - Створити/оновити сесію `agent:dev:*` (перевизначення моделі для кожного запуску) - - Ітеруватися моделями-з-ключами і перевіряти: - - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (read probe) - - необов’язкові додаткові probe інструментів (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → подальша відповідь) і далі працюють -- Подробиці probe (щоб ви могли швидко пояснювати збої): - - `read` probe: тест записує файл із nonce у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім `read`-ом прочитати його назад. - - image probe: тест прикріплює згенерований PNG (cat + випадковий код) і очікує, що модель поверне `cat `. + - Підняти Gateway in-process + - Створити/оновити сесію `agent:dev:*` (override моделі на кожен запуск) + - Ітерувати за моделями з ключами й перевіряти: + - «змістовну» відповідь (без tools) + - що реальний виклик tool працює (read probe) + - необов’язкові додаткові probe tool (exec+read probe) + - що регресійні шляхи OpenAI (лише tool-call → follow-up) продовжують працювати +- Деталі probe (щоб можна було швидко пояснити збої): + - `read` probe: тест записує nonce-файл у workspace і просить agent виконати `read` цього файлу та повернути nonce. + - `exec+read` probe: тест просить agent через `exec` записати nonce у temp-файл, а потім виконати `read` цього файлу. + - image probe: тест прикріплює згенерований PNG (cat + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - Як вибирати моделі: - За замовчуванням: modern allowlist (Opus/Sonnet 4.6+, GPT-5.x + Codex, Gemini 3, GLM 4.7, MiniMax M2.7, Grok 4) - - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — псевдонім для modern allowlist - - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити - - Прогони modern/all gateway за замовчуванням обмежені відібраною high-signal межею; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного прогону modern або додатне число для меншого ліміту. -- Як вибирати провайдерів (уникати «усе з OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - Для gateway sweep modern/all за замовчуванням застосовується curated high-signal cap; встановіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпного sweep modern або додатне число для меншого cap. +- Як вибирати провайдерів (уникайте «усе OpenRouter»): - `OPENCLAW_LIVE_GATEWAY_PROVIDERS="google,google-antigravity,google-gemini-cli,openai,anthropic,zai,minimax"` (allowlist через кому) -- Probe інструментів і зображень у цьому live-тесті завжди ввімкнені: - - `read` probe + `exec+read` probe (навантаження на інструменти) - - image probe запускається, коли модель рекламує підтримку вхідних зображень - - Потік (на високому рівні): - - Тест генерує крихітний PNG із “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) +- Probe tool + image у цьому live-тесті завжди увімкнені: + - `read` probe + `exec+read` probe (навантаження на tool) + - image probe запускається, коли модель оголошує підтримку вводу зображень + - Потік (високорівнево): + - Тест генерує крихітний PNG із «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway парсить вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - - Embedded agent передає моделі мультимодальне повідомлення користувача + - Gateway парсить attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Вбудований agent пересилає мультимодальне повідомлення користувача до моделі - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що саме ви можете тестувати на своїй машині (і точні id `provider/model`), виконайте: +Порада: щоб побачити, що можна тестувати на вашій машині (і точні id `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: димове тестування backend CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke-тест CLI-бекенда (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити pipeline Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашої стандартної конфігурації. -- Значення димового тестування backend за замовчуванням для конкретного backend містяться у визначенні `cli-backend.ts` extension-власника. +- Мета: перевірити pipeline Gateway + agent, використовуючи локальний CLI-бекенд, не торкаючись вашого config за замовчуванням. +- Значення smoke за замовчуванням, специфічні для бекенда, зберігаються у визначенні `cli-backend.ts` extension-власника. - Увімкнення: - - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) + - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо запускаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Значення за замовчуванням: - Провайдер/модель за замовчуванням: `claude-cli/claude-sonnet-4-6` - - Поведінка команди/аргументів/зображень береться з метаданих plugin-а backend CLI-власника. + - Поведінка command/args/image береться з метаданих Plugin CLI-бекенда-власника. - Перевизначення (необов’язково): - `OPENCLAW_LIVE_CLI_BACKEND_MODEL="codex-cli/gpt-5.5"` - `OPENCLAW_LIVE_CLI_BACKEND_COMMAND="/full/path/to/codex"` - `OPENCLAW_LIVE_CLI_BACKEND_ARGS='["exec","--json","--color","never","--sandbox","read-only","--skip-git-repo-check"]'` - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1`, щоб надіслати реальне вкладення-зображення (шляхи інжектяться в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"`, щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`), щоб керувати способом передавання аргументів зображень, коли встановлено `IMAGE_ARG`. - - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1`, щоб надіслати другий хід і перевірити потік resume. - - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути стандартний probe безперервності тієї самої сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово його ввімкнути, коли вибрана модель підтримує ціль перемикання). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_PROBE=1` щоб надіслати реальне вкладення-зображення (шляхи інжектяться в prompt). + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` щоб передавати шляхи до файлів зображень як аргументи CLI замість інжекції в prompt. + - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_MODE="repeat"` (або `"list"`) щоб керувати тим, як передаються аргументи зображень, коли встановлено `IMAGE_ARG`. + - `OPENCLAW_LIVE_CLI_BACKEND_RESUME_PROBE=1` щоб надіслати другий хід і перевірити flow відновлення. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0` щоб вимкнути стандартний probe безперервності тієї самої сесії Claude Sonnet -> Opus (встановіть `1`, щоб примусово ввімкнути його, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -597,7 +599,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Рецепти Docker для окремих провайдерів: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -608,29 +610,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker-ранер розміщений у `scripts/test-live-cli-backend-docker.sh`. -- Він запускає димове тестування live CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані димового тестування CLI з extension-власника, а потім встановлює відповідний Linux-пакет CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований доступний для запису префікс за адресою `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). -- `pnpm test:docker:live-cli-backend:claude-subscription` вимагає переносиму OAuth-автентифікацію підписки Claude Code через або `~/.claude/.credentials.json` із `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` із `claude setup-token`. Спочатку він доводить прямий запуск `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження env-змінних API-ключа Anthropic. Ця лінія підписки за замовчуванням вимикає probe Claude MCP/tool і image, оскільки Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra-usage, а не через звичайні ліміти плану підписки. -- Димове тестування live CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через CLI gateway. -- Стандартне димове тестування Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. +- Docker-ранер розміщено в `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke-тест CLI-бекенда всередині Docker-образу репозиторію від імені непривілейованого користувача `node`. +- Він визначає smoke-метадані CLI з extension-власника, а потім встановлює відповідний Linux CLI-пакет (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`) у кешований каталог запису за префіксом `OPENCLAW_DOCKER_CLI_TOOLS_DIR` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`). +- `pnpm test:docker:live-cli-backend:claude-subscription` потребує portable Claude Code subscription OAuth через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він перевіряє прямий `claude -p` у Docker, а потім запускає два ходи Gateway CLI-бекенда без збереження env-змінних API key Anthropic. Ця subscription-лінія за замовчуванням вимикає MCP/tool та image probe Claude, тому що Claude наразі маршрутизує використання сторонніх застосунків через тарифікацію extra-usage замість звичайних лімітів subscription plan. +- Live smoke-тест CLI-бекенда тепер перевіряє той самий end-to-end flow для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, а потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. +- Стандартний smoke-тест Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає попередню нотатку. -## Live: димове тестування ACP bind (`/acp spawn ... --bind here`) +## Live: smoke-тест прив’язки ACP (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік conversation-bind ACP із live ACP agent: +- Мета: перевірити реальний flow прив’язки розмови ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - прив’язати синтетичну розмову message-channel на місці - - надіслати звичайний подальший запит у тій самій розмові - - перевірити, що подальший запит потрапляє до транскрипту прив’язаної ACP-сесії + - надіслати звичайне follow-up у тій самій розмові + - перевірити, що follow-up потрапляє до транскрипту прив’язаної ACP-сесії - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Значення за замовчуванням: - ACP-агенти в Docker: `claude,codex,gemini` - ACP-агент для прямого `pnpm test:live ...`: `claude` - - Синтетичний канал: контекст розмови у стилі Slack DM - - ACP-backend: `acpx` + - Синтетичний channel: контекст розмови у стилі Slack DM + - Бекенд ACP: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -639,8 +641,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND='npx -y @agentclientprotocol/claude-agent-acp@'` - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - Примітки: - - Ця лінія використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли прикріплювати контекст message-channel без удавання зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. + - Ця лінія використовує поверхню Gateway `chat.send` з admin-only synthetic полями `originating-route`, щоб тести могли додавати контекст message-channel без імітації зовнішньої доставки. + - Якщо `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів Plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -656,7 +658,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Рецепти Docker для окремих агентів: +Рецепти Docker для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -666,35 +668,35 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker-ранер розміщений у `scripts/test-live-acp-bind-docker.sh`. -- За замовчуванням він запускає димове тестування ACP bind послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. +- Docker-ранер розміщено в `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke-тест прив’язки ACP послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він використовує `~/.profile`, готує відповідний auth-матеріал CLI у контейнері, встановлює `acpx` у доступний для запису npm-префікс, а потім, якщо потрібно, встановлює запитаний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`). -- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб `acpx` зберігав env-змінні провайдера з `profile`, доступні для дочірнього harness CLI. +- Він використовує `~/.profile`, переносить відповідний auth-матеріал CLI в контейнер, встановлює `acpx` у npm-префікс із правом запису, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker раннер встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера з підключеного profile доступними для дочірнього harness CLI. -## Live: димове тестування harness app-server Codex +## Live: smoke-тест harness app-server Codex -- Мета: перевірити harness Codex, що належить plugin, через стандартний - метод gateway `agent`: - - завантажити bundled plugin `codex` +- Мета: перевірити Plugin-власний harness Codex через звичайний Gateway + метод `agent`: + - завантажити вбудований Plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `codex/gpt-5.5` - - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що потік app-server - може відновитися - - запустити `/codex status` і `/codex models` через той самий шлях команди - gateway - - за потреби виконати два shell-probe з підвищеними правами, перевірені Guardian: одну нешкідливу - команду, яку має бути схвалено, і одне фальшиве завантаження секрету, - яке має бути відхилено, щоб агент перепитав + - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусово вибраним harness Codex + - надіслати другий хід у ту саму сесію OpenClaw і перевірити, що thread + app-server може відновитися + - виконати `/codex status` і `/codex models` через той самий командний шлях + Gateway + - за бажанням виконати дві shell-перевірки з ескалацією, переглянуті Guardian: одну нешкідливу + команду, яку слід дозволити, і одну фальшиву відправку секрету, яку слід + заборонити, щоб агент перепитав - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` -- Модель за замовчуванням: `codex/gpt-5.5` +- Модель за замовчуванням: `openai/gpt-5.5` - Необов’язковий image probe: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` - Необов’язковий MCP/tool probe: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` -- Необов’язковий Guardian probe: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` -- Це димове тестування встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти, тихо переключившись на PI. -- Автентифікація: `OPENAI_API_KEY` із shell/profile, плюс необов’язково скопійовані +- Необов’язковий probe Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke-тест встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний + harness Codex не міг пройти тест тихо переключившись на Pi. +- Автентифікація: `OPENAI_API_KEY` з shell/profile, а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml` Локальний рецепт: @@ -705,7 +707,7 @@ OPENCLAW_LIVE_CODEX_HARNESS=1 \ OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1 \ OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1 \ - OPENCLAW_LIVE_CODEX_HARNESS_MODEL=codex/gpt-5.5 \ + OPENCLAW_LIVE_CODEX_HARNESS_MODEL=openai/gpt-5.5 \ pnpm test:live -- src/gateway/gateway-codex-harness.live.test.ts ``` @@ -718,65 +720,67 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker-ранер розміщений у `scripts/test-live-codex-harness-docker.sh`. +- Docker-ранер розміщено в `scripts/test-live-codex-harness-docker.sh`. - Він використовує змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює файли - автентифікації Codex CLI, якщо вони є, встановлює `@openai/codex` у доступний для запису змонтований npm-префікс, - готує дерево вихідних файлів, а потім запускає лише live-тест Codex-harness. -- Docker за замовчуванням вмикає image-, MCP/tool- і Guardian-probe. Встановіть - `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0`, або - `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, або - `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли вам потрібен вужчий прогін для налагодження. -- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, - щоб fallback `openai-codex/*` або PI не міг приховати регресію Codex harness. + автентифікації CLI Codex, якщо вони є, встановлює `@openai/codex` у змонтований npm-префікс + із правом запису, переносить дерево source, а потім запускає лише live-тест harness Codex. +- Docker за замовчуванням вмикає image, MCP/tool і Guardian probe. Встановіть + `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=0` або + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0` або + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий + діагностичний запуск. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і live-конфіг + тесту, щоб legacy alias-и або fallback на Pi не могли приховати регресію + harness Codex. -### Рекомендовані рецепти live +### Рекомендовані live-рецепти -Найшвидші та найменш нестабільні — вузькі, явні allowlist: +Вузькі, явні allowlist — найшвидші й найменш flaky: -- Одна модель, напряму (без gateway): +- Одна модель, direct (без Gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.5" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, димове тестування gateway: +- Одна модель, gateway smoke: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Виклик інструментів у кількох провайдерів: +- Виклик tool для кількох провайдерів: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3-flash-preview,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -- Фокус на Google (API-ключ Gemini + Antigravity): - - Gemini (API-ключ): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +- Фокус на Google (API key Gemini + Antigravity): + - Gemini (API key): `OPENCLAW_LIVE_GATEWAY_MODELS="google/gemini-3-flash-preview" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Antigravity (OAuth): `OPENCLAW_LIVE_GATEWAY_MODELS="google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-pro-high" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` Примітки: -- `google/...` використовує Gemini API (API-ключ). -- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента в стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості інструментів). +- `google/...` використовує Gemini API (API key). +- `google-antigravity/...` використовує міст Antigravity OAuth (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний Gemini CLI на вашій машині (окрема автентифікація + особливості tooling). - Gemini API проти Gemini CLI: - - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація API-ключем / профілем); зазвичай саме це більшість користувачів мають на увазі під “Gemini”. - - CLI: OpenClaw викликає локальний бінарний файл `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/підтримка інструментів/version skew). + - API: OpenClaw викликає розміщений Google Gemini API через HTTP (автентифікація через API key / profile); саме це більшість користувачів мають на увазі під “Gemini”. + - CLI: OpenClaw звертається до локального бінарника `gemini`; він має власну автентифікацію та може поводитися інакше (streaming/support tools/version skew). ## Live: матриця моделей (що ми покриваємо) -Немає фіксованого «списку моделей CI» (live вмикається за потреби), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. +Фіксованого «списку моделей CI» не існує (live — це opt-in), але це **рекомендовані** моделі для регулярного покриття на dev-машині з ключами. -### Сучасний набір димового тестування (виклик інструментів + image) +### Сучасний набір smoke (виклик tool + image) -Це прогін «типових моделей», який ми очікуємо підтримувати в робочому стані: +Це запуск «поширених моделей», який ми очікуємо зберігати працездатним: - OpenAI (не Codex): `openai/gpt-5.5` (необов’язково: `openai/gpt-5.4-mini`) -- OpenAI Codex: `openai-codex/gpt-5.5` +- OpenAI Codex OAuth: `openai/gpt-5.5` (`openai-codex/gpt-*` залишається legacy alias) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (Gemini API): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) - Google (Antigravity): `google-antigravity/claude-opus-4-6-thinking` і `google-antigravity/gemini-3-flash` - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск димового тестування gateway з інструментами + image: -`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` +Запуск gateway smoke з tools + image: +`OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.5,anthropic/claude-opus-4-6,google/gemini-3.1-pro-preview,google/gemini-3-flash-preview,google-antigravity/claude-opus-4-6-thinking,google-antigravity/gemini-3-flash,zai/glm-4.7,minimax/MiniMax-M2.7" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` -### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) +### Базовий рівень: виклик tool (Read + необов’язковий Exec) -Виберіть щонайменше одну модель з кожної родини провайдерів: +Виберіть принаймні одну модель на кожну сім’ю провайдерів: - OpenAI: `openai/gpt-5.5` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -784,81 +788,81 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Необов’язкове додаткове покриття (було б добре мати): +Необов’язкове додаткове покриття (бажано мати): - xAI: `xai/grok-4` (або найновіша доступна) -- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас увімкнено) -- Cerebras: `cerebras/`… (якщо у вас є доступ) -- LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) +- Mistral: `mistral/`… (виберіть одну модель із підтримкою `tools`, яку у вас ввімкнено) +- Cerebras: `cerebras/`… (якщо маєте доступ) +- LM Studio: `lmstudio/`… (локально; виклик tool залежить від режиму API) ### Vision: надсилання image (вкладення → мультимодальне повідомлення) -Додайте щонайменше одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте щонайменше одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні Gateway +### Aggregator-и / альтернативні Gateway -Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: +Якщо у вас увімкнено ключі, ми також підтримуємо тестування через: - OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) - OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live-матрицю (якщо у вас є облікові дані/конфігурація): +Інші провайдери, яких можна включити до live-матриці (якщо у вас є облікові дані/config): - Вбудовані: `openai`, `openai-codex`, `anthropic`, `google`, `google-vertex`, `google-antigravity`, `google-gemini-cli`, `zai`, `openrouter`, `opencode`, `opencode-go`, `xai`, `groq`, `cerebras`, `mistral`, `github-copilot` -- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) +- Через `models.providers` (custom endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний проксі (LM Studio, vLLM, LiteLLM тощо) -Порада: не намагайтеся жорстко зашивати в документацію «всі моделі». Авторитетний список — це те, що повертає `discoverModels(...)` на вашій машині, плюс ті ключі, які доступні. +Порада: не намагайтеся жорстко закодувати в документації «усі моделі». Авторитетним списком є те, що `discoverModels(...)` повертає на вашій машині, плюс доступні ключі. ## Облікові дані (ніколи не комітьте) -Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: +Live-тести виявляють облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. - Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «ключі профілів» у live-тестах) -- Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється в підготовлений live-home, якщо присутній, але не є основним сховищем ключів профілів) -- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; підготовлені live-home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального workspace хоста. +- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає “profile keys” у live-тестах) +- Config: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) +- Legacy-каталог стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо присутній, але це не основне сховище profile key) +- Локальні live-запуски за замовчуванням копіюють активний config, файли `auth-profiles.json` для окремих агентів, legacy `credentials/` і підтримувані зовнішні каталоги автентифікації CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального workspace хоста. -Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker-ранери нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на env-ключі (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile` або використовуйте Docker-ранери нижче (вони можуть змонтувати `~/.profile` у контейнер). -## Live Deepgram (транскрипція аудіо) +## Live Deepgram (транскрибування аудіо) - Тест: `extensions/deepgram/audio.live.test.ts` - Увімкнення: `DEEPGRAM_API_KEY=... DEEPGRAM_LIVE_TEST=1 pnpm test:live extensions/deepgram/audio.live.test.ts` -## Live BytePlus coding plan +## Live для coding plan BytePlus - Тест: `extensions/byteplus/live.test.ts` - Увімкнення: `BYTEPLUS_API_KEY=... BYTEPLUS_LIVE_TEST=1 pnpm test:live extensions/byteplus/live.test.ts` - Необов’язкове перевизначення моделі: `BYTEPLUS_CODING_MODEL=ark-code-latest` -## Live ComfyUI workflow media +## Live для workflow media ComfyUI - Тест: `extensions/comfy/comfy.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts` - Обсяг: - - Перевіряє bundled-шляхи comfy для image, video і `music_generate` + - Перевіряє вбудовані шляхи comfy для image, video і `music_generate` - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - Корисно після змін у надсиланні workflow comfy, polling, завантаженнях або реєстрації plugin -## Live генерація зображень +## Live для генерації зображень - Тест: `test/image-generation.runtime.live.test.ts` - Команда: `pnpm test:live test/image-generation.runtime.live.test.ts` - Harness: `pnpm test:live:media image` - Обсяг: - - Перелічує кожен зареєстрований plugin провайдера генерації зображень - - Завантажує відсутні env-змінні провайдера з вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Запускає стандартні варіанти генерації зображень через спільну runtime-можливість: + - Перелічує кожен зареєстрований provider Plugin генерації зображень + - Завантажує відсутні env-змінні provider із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API key раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає provider-ів без придатної автентифікації/profile/model + - Проганяє стандартні варіанти генерації зображень через спільну runtime-можливість: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled-провайдери, які покриваються: +- Поточні вбудовані provider-и, які покриваються: - `fal` - `google` - `minimax` @@ -870,75 +874,75 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_MODELS="openai/gpt-image-2,google/gemini-3.1-flash-image-preview,xai/grok-imagine-image"` - `OPENCLAW_LIVE_IMAGE_GENERATION_CASES="google:flash-generate,google:pro-edit,xai:default-generate,xai:default-edit"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile-store та ігнорувати перевизначення лише через env -## Live генерація музики +## Live для генерації музики - Тест: `extensions/music-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts` - Harness: `pnpm test:live:media music` - Обсяг: - - Перевіряє спільний bundled-шлях провайдера генерації музики - - Наразі охоплює Google і MiniMax - - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перевіряє спільний шлях вбудованих provider-ів генерації музики + - Наразі покриває Google і MiniMax + - Завантажує env-змінні provider із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API key раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає provider-ів без придатної автентифікації/profile/model - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt - - `edit`, коли провайдер оголошує `capabilities.edit.enabled` + - `generate` з input лише у вигляді prompt + - `edit`, коли provider оголошує `capabilities.edit.enabled` - Поточне покриття спільної лінії: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не цей спільний прогін + - `comfy`: окремий live-файл Comfy, а не цей спільний sweep - Необов’язкове звуження: - `OPENCLAW_LIVE_MUSIC_GENERATION_PROVIDERS="google,minimax"` - `OPENCLAW_LIVE_MUSIC_GENERATION_MODELS="google/lyria-3-clip-preview,minimax/music-2.5+"` - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile-store та ігнорувати перевизначення лише через env -## Live генерація відео +## Live для генерації відео - Тест: `extensions/video-generation-providers.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts` - Harness: `pnpm test:live:media video` - Обсяг: - - Перевіряє спільний bundled-шлях провайдера генерації відео - - За замовчуванням використовує безпечний для релізу шлях димового тестування: провайдери без FAL, один запит text-to-video на провайдера, одноcекундний lobster prompt і обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) - - За замовчуванням пропускає FAL, оскільки затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб явно його запустити - - Завантажує env-змінні провайдера з вашого login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі раніше за збережені auth-профілі, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Перевіряє спільний шлях вбудованих provider-ів генерації відео + - За замовчуванням використовує безпечний для релізу smoke-шлях: provider-и без FAL, один запит text-to-video на provider, односекундний lobster prompt і обмеження операції на provider через `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, оскільки затримка черги на боці provider може домінувати в часі релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Завантажує env-змінні provider із вашого login shell (`~/.profile`) перед probe + - За замовчуванням використовує live/env API key раніше за збережені auth profile, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає provider-ів без придатної автентифікації/profile/model - За замовчуванням запускає лише `generate` - - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний image-вхід на основі buffer у спільному прогоні - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний video-вхід на основі buffer у спільному прогоні - - Поточні оголошені, але пропущені провайдери `imageToVideo` у спільному прогоні: - - `vydra`, тому що bundled `veo3` підтримує лише text, а bundled `kling` вимагає віддалений image URL - - Специфічне для провайдера покриття Vydra: + - Встановіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими transform, коли вони доступні: + - `imageToVideo`, коли provider оголошує `capabilities.imageToVideo.enabled` і вибраний provider/model приймає локальний image input на основі buffer у спільному sweep + - `videoToVideo`, коли provider оголошує `capabilities.videoToVideo.enabled` і вибраний provider/model приймає локальний video input на основі buffer у спільному sweep + - Поточні provider-и `imageToVideo`, що оголошені, але пропускаються у спільному sweep: + - `vydra`, тому що вбудований `veo3` є лише текстовим, а вбудований `kling` потребує віддаленого URL зображення + - Provider-specific покриття Vydra: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка за замовчуванням використовує фікстуру з віддаленим image URL + - цей файл запускає `veo3` text-to-video плюс лінію `kling`, яка за замовчуванням використовує фікстуру з віддаленим URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - - Поточні оголошені, але пропущені провайдери `videoToVideo` у спільному прогоні: - - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені reference URL `http(s)` / MP4 - - `google`, тому що поточна спільна лінія Gemini/Veo використовує локальний вхід на основі buffer, і цей шлях не приймається у спільному прогоні - - `openai`, тому що поточна спільна лінія не гарантує організаційно-специфічний доступ до video inpaint/remix + - Поточні provider-и `videoToVideo`, що оголошені, але пропускаються у спільному sweep: + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі потребують віддалених еталонних URL `http(s)` / MP4 + - `google`, тому що поточна спільна лінія Gemini/Veo використовує локальний input на основі buffer, а цей шлях не приймається у спільному sweep + - `openai`, тому що поточній спільній лінії бракує гарантій org-specific доступу до video inpaint/remix - Необов’язкове звуження: - `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="google,openai,runway"` - `OPENCLAW_LIVE_VIDEO_GENERATION_MODELS="google/veo-3.1-fast-generate-preview,openai/sora-2,runway/gen4_aleph"` - - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до стандартного прогону, зокрема FAL - - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера під час агресивного димового прогону + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного provider у стандартний sweep, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції на кожен provider для агресивного smoke-запуску - Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише через env + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати автентифікацію через profile-store та ігнорувати перевизначення лише через env -## Harness для media live +## Live media harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для image, music і video через один рідний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію - - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і тихого режиму залишається узгодженою + - Запускає спільні live-набори для image, music і video через одну repo-native точку входу + - Автоматично завантажує відсутні env-змінні provider із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до provider-ів, які зараз мають придатну автентифікацію + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet-mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -947,213 +951,215 @@ Live-тести знаходять облікові дані так само, я ## Docker-ранери (необов’язкові перевірки «працює в Linux») -Ці Docker-ранери поділяються на дві групи: +Ці Docker-ранери поділено на дві категорії: -- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл із profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог конфігурації та workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live-ранери за замовчуванням використовують меншу межу димового тестування, щоб повний Docker-прогін залишався практичним: - `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` за замовчуванням використовує `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model ранери: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл profile-key всередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний config-dir і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні точки входу — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live-ранери за замовчуванням використовують менший smoke-cap, щоб повний Docker sweep залишався практичним: + `test:docker:live-models` за замовчуванням встановлює `OPENCLAW_LIVE_MAX_MODELS=12`, а + `test:docker:live-gateway` за замовчуванням встановлює `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам явно потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. Воно також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних E2E-ранерів димового тестування, які перевіряють зібраний app. -- Контейнерні ранери димового тестування: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + вам явно потрібне більше, вичерпне сканування. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker-ліній live. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke-ранерів E2E, які перевіряють зібраний app. +- Container smoke-ранери: `test:docker:openwebui`, `test:docker:onboard`, `test:docker:npm-onboard-channel-agent`, `test:docker:gateway-network`, `test:docker:mcp-channels`, `test:docker:pi-bundle-mcp-tools`, `test:docker:cron-mcp-cleanup`, `test:docker:plugins`, `test:docker:plugin-update` і `test:docker:config-reload` піднімають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. -Docker-ранери live-model також bind-монтують лише потрібні домівки автентифікації CLI (або всі підтримувані, коли прогін не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста: +Docker-ранери live-model також bind-mount-ять лише потрібні каталоги автентифікації CLI (або всі підтримувані, коли запуск не звужений), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без зміни сховища автентифікації хоста: -- Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Димове тестування ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Димове тестування CLI backend: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) -- Димове тестування harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) +- Direct model: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) +- Smoke-тест прив’язки ACP: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke-тест CLI-бекенда: `pnpm test:docker:live-cli-backend` (скрипт: `scripts/test-live-cli-backend-docker.sh`) +- Smoke-тест harness app-server Codex: `pnpm test:docker:live-codex-harness` (скрипт: `scripts/test-live-codex-harness-docker.sh`) - Gateway + dev agent: `pnpm test:docker:live-gateway` (скрипт: `scripts/test-live-gateway-models-docker.sh`) -- Димове тестування Open WebUI live: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) - Майстер онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Димове тестування онбордингу/каналу/агента через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг з env-ref плюс Telegram за замовчуванням, перевіряє, що ввімкнення plugin встановлює його runtime deps за потреби, запускає doctor і виконує один хід агента з mock OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Димове тестування глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає bundled-провайдерів зображень замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Мережева взаємодія Gateway (два контейнери, WS auth + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) -- Мінімальна reasoning-регресія OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає mock OpenAI server через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово викликає відхилення schema провайдера й перевіряє, що сирі подробиці з’являються в логах Gateway. -- Міст каналу MCP (seeded Gateway + міст stdio + димове тестування raw Claude notification-frame): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти Pi bundle MCP (реальний stdio MCP server + димове тестування allow/deny профілю embedded Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих прогонів cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (димове тестування встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Димове тестування незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Димове тестування метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий образ Docker-ранера, один раз збирає та пакує OpenClaw на host, а потім монтує цей tarball у кожний сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Звужуйте runtime deps bundled plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: +- Smoke-тест онбордингу/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через онбординг env-ref і за замовчуванням Telegram, перевіряє, що ввімкнення Plugin встановлює його runtime-залежності на вимогу, запускає doctor і виконує один замоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або перемкніть channel через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест глобального встановлення Bun: `bash scripts/e2e/bun-global-install-smoke.sh` пакує поточне дерево, встановлює його через `bun install -g` в ізольованому home і перевіряє, що `openclaw infer image providers --json` повертає вбудовані provider-и зображень замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Smoke-тест інсталятора в Docker: `bash scripts/test-install-sh-docker.sh` використовує спільний npm-кеш для root-, update-, direct-npm- і non-root-контейнерів. Встановіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати цей кеш між локальними повторними запусками. +- Мережа Gateway (два контейнери, автентифікація WS + health): `pnpm test:docker:gateway-network` (скрипт: `scripts/e2e/gateway-network-docker.sh`) +- Мінімальна регресія reasoning для OpenAI Responses web_search: `pnpm test:docker:openai-web-search-minimal` (скрипт: `scripts/e2e/openai-web-search-minimal-docker.sh`) запускає замоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово змушує схему provider відхилити дані й перевіряє, що сирі деталі з’являються в логах Gateway. +- Міст каналу MCP (seeded Gateway + stdio bridge + сирий smoke notification-frame у стилі Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у комплекті Pi (реальний stdio MCP-сервер + smoke allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) +- Очищення MCP Cron/subagent (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і one-shot subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugin-и (smoke встановлення + alias `/plugin` + семантика перезапуску набору Claude): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime-залежності вбудованого Plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ раннера, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій Linux-інсталяції. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропускайте host rebuild після свіжого локального build через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть на наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте runtime-залежності вбудованого Plugin під час ітерацій, вимикаючи не пов’язані сценарії, наприклад: `OPENCLAW_BUNDLED_CHANNEL_SCENARIOS=0 OPENCLAW_BUNDLED_CHANNEL_UPDATE_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_ROOT_OWNED_SCENARIO=0 OPENCLAW_BUNDLED_CHANNEL_SETUP_ENTRY_SCENARIO=0 pnpm test:docker:bundled-channel-deps`. -Щоб вручну попередньо зібрати та повторно використовувати спільний образ built-app: +Щоб вручну попередньо зібрати й повторно використовувати спільний образ built-app: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення образів для конкретних наборів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та інсталятора зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не runtime спільного built-app. +Специфічні для набору перевизначення образів, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, як і раніше мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Тести QR та інсталятора в Docker зберігають власні Dockerfile, оскільки вони перевіряють поведінку пакування/встановлення, а не спільне runtime зібраного app. Docker-ранери live-model також монтують поточний checkout лише для читання і -підготовлюють його у тимчасовому workdir усередині контейнера. Це зберігає -runtime image компактним, водночас усе одно запускаючи Vitest проти ваших точних локальних source/config. -Крок підготовки пропускає великі локальні кеші та результати збірки app, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для app каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання -машинно-специфічних артефактів. +переносять його до тимчасового workdir усередині контейнера. Це дозволяє +зберігати runtime-образ компактним і водночас запускати Vitest проти вашого +точного локального source/config. +Крок staging пропускає великі локальні кеші та результати збірки app, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для app каталоги `.build` або +виводу Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання +специфічних для машини артефактів. Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -реальні воркери каналів Telegram/Discord тощо всередині контейнера. +реальні воркери channel Telegram/Discord тощо всередині контейнера. `test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття -gateway live з цієї Docker-лінії. -`test:docker:openwebui` — це димове тестування сумісності вищого рівня: воно запускає -контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, -запускає pin-ований контейнер Open WebUI проти цього gateway, виконує вхід через -Open WebUI, перевіряє, що `/api/models` надає `openclaw/default`, а потім надсилає -реальний chat-запит через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження -образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start налаштування. -Ця лінія очікує наявність придатного live-ключа моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) — основний спосіб надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити live-покриття +Gateway із цієї Docker-лінії. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-сумісними HTTP-endpoint, запускає +закріплений контейнер Open WebUI проти цього Gateway, виконує вхід через +Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає +реальний запит чату через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження +образу Open WebUI, а Open WebUI може потребувати завершення власного cold-start setup. +Ця лінія потребує придатного ключа live-моделі, а `OPENCLAW_PROFILE_FILE` +(за замовчуванням `~/.profile`) — основний спосіб надати його в Dockerized-запусках. +Успішні запуски виводять невеликий JSON-payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно є детермінованим і не потребує -реального облікового запису Telegram, Discord або iMessage. Воно запускає seeded контейнер -Gateway, запускає другий контейнер, який піднімає `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку черги live-подій, маршрутизацію outbound send, а також channel- і -permission-сповіщення у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує raw stdio MCP frames, тож димове тестування перевіряє те, що -міст реально випромінює, а не лише те, що випадково надає конкретний SDK клієнта. -`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує live-ключа -моделі. Воно збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через runtime embedded Pi bundle -MCP, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають +`test:docker:mcp-channels` навмисно детермінований і не потребує +реального облікового запису Telegram, Discord чи iMessage. Він піднімає seeded +контейнер Gateway, запускає другий контейнер, який виконує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутованих розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію outbound send і сповіщення у стилі Claude про channel + +permissions через реальний міст stdio MCP. Перевірка сповіщень +безпосередньо інспектує сирі кадри stdio MCP, тож smoke перевіряє те, що міст +справді відправляє, а не лише те, що трапляється відображати конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа +live-моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe-сервер +усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP комплекту Pi, +виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` є детермінованим і не потребує live-ключа -моделі. Воно запускає seeded Gateway з реальним stdio MCP probe server, виконує -ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа +live-моделі. Він запускає seeded Gateway з реальним stdio MCP probe-сервером, виконує +ізольований хід cron і one-shot дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручне димове тестування ACP plain-language thread (не CI): +Ручний smoke plain-language для thread ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. +- Залишайте цей скрипт для workflow регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тож не видаляйте його. Корисні env-змінні: - `OPENCLAW_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` - `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` - `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і використовується перед запуском тестів -- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевірити лише env-змінні, використані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань auth CLI -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли auth CLI під `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, підключені з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без зовнішніх монтувань автентифікації CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker +- Зовнішні каталоги/файли автентифікації CLI під `$HOME` монтуються лише для читання в `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів - Каталоги за замовчуванням: `.minimax` - Файли за замовчуванням: `~/.codex/auth.json`, `~/.codex/config.toml`, `.claude.json`, `~/.claude/.credentials.json`, `~/.claude/settings.json`, `~/.claude/settings.local.json` - - Звужені запуски провайдерів монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` + - Звужені запуски provider монтують лише потрібні каталоги/файли, визначені з `OPENCLAW_LIVE_PROVIDERS` / `OPENCLAW_LIVE_GATEWAY_PROVIDERS` - Перевизначайте вручну через `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` -- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити прогін -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів у контейнері -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібне перебирання -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway надає для димового тестування Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, використаний у димовому тестуванні Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити pin-ований тег образу Open WebUI +- `OPENCLAW_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати provider-ів у контейнері +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використовувати наявний образ `openclaw:local-live` для повторних запусків, яким не потрібне перевизначення збірки +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані беруться з profile store (а не з env) +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку Gateway показує для smoke Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt для перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI -## Перевірка коректності документації +## Перевірка документації Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки heading у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте повну валідацію anchor у Mintlify, коли вам також потрібні перевірки заголовків у межах сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Offline-регресія (безпечна для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (case: "runs a mock OpenAI tool call end-to-end via gateway agent loop") -- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (case: "runs wizard over ws and writes auth token config") +- Виклик tool у Gateway (замоканий OpenAI, реальний цикл Gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Майстер Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Замоканий виклик tool через реальний цикл Gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end-потоки майстра, які перевіряють wiring сесії та вплив config (`src/gateway/gateway.test.ts`). -Що все ще відсутнє для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи обирає агент правильний Skill (або уникає нерелевантних)? -- **Відповідність:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? -- **Контракти workflow:** multi-turn сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Вибір рішення:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок tool, перенесення history сесії та межі sandbox. -Майбутні evals спочатку мають залишатися детермінованими: +Майбутні eval-и мають насамперед залишатися детермінованими: -- Scenario runner з mock-провайдерами для перевірки викликів інструментів + порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, орієнтованих на skills (використовувати чи уникати, gating, prompt injection). -- Необов’язкові live evals (увімкнення за потреби, обмеження через env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, який використовує mock provider-и для перевірки викликів tool + їхнього порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval-и (opt-in, з керуванням через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму інтерфейсному контракту. Вони ітеруються за всіма виявленими plugins і запускають набір -перевірок форми та поведінки. Стандартна unit-лінія `pnpm test` навмисно -пропускає ці файли спільних seam і smoke; запускайте контрактні команди явно, +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає своєму +контракту інтерфейсу. Вони ітеруються по всіх виявлених Plugin-ах і запускають набір +перевірок форми та поведінки. Лінія unit за замовчуванням `pnpm test` навмисно +пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, коли торкаєтеся спільних поверхонь channel або provider. ### Команди -- Усі контрактні тести: `pnpm test:contracts` -- Лише контрактні тести channel: `pnpm test:contracts:channels` -- Лише контрактні тести provider: `pnpm test:contracts:plugins` +- Усі контракти: `pnpm test:contracts` +- Лише контракти channel: `pnpm test:contracts:channels` +- Лише контракти provider: `pnpm test:contracts:plugins` -### Контрактні тести channel +### Контракти channel -Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** - Базова форма plugin (id, name, capabilities) +- **plugin** - Базова форма Plugin (id, name, capabilities) - **setup** - Контракт майстра налаштування - **session-binding** - Поведінка прив’язки сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень - **actions** - Обробники дій channel - **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Застосування групової політики +- **directory** - API каталогу/складу +- **group-policy** - Застосування групової policy -### Контракти статусу provider +### Контракти status provider -Розміщені в `src/plugins/contracts/*.contract.test.ts`. +Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки статусу channel -- **registry** - Форма реєстру plugin +- **status** - Probe status channel +- **registry** - Форма registry Plugin -### Контрактні тести provider +### Контракти provider -Розміщені в `src/plugins/contracts/*.contract.test.ts`: +Розташовані в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку автентифікації -- **auth-choice** - Вибір/добір автентифікації +- **auth-choice** - Вибір/selection автентифікації - **catalog** - API каталогу моделей -- **discovery** - Виявлення plugin -- **loader** - Завантаження plugin +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin - **runtime** - Runtime provider -- **shape** - Форма/інтерфейс plugin +- **shape** - Форма/інтерфейс Plugin - **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни channel чи provider plugin -- Після рефакторингу реєстрації plugin або виявлення +- Після зміни export-ів або subpath у plugin-sdk +- Після додавання або зміни channel чи provider Plugin +- Після рефакторингу реєстрації або виявлення Plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Контрактні тести запускаються в CI і не потребують реальних API key. -## Додавання регресій (рекомендації) +## Додавання регресій (настанови) Коли ви виправляєте проблему provider/model, виявлену в live: -- За можливості додавайте безпечну для CI регресію (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики автентифікації), залишайте live-тест вузьким і таким, що вмикається через env vars -- Віддавайте перевагу найменшому шару, який виявляє баг: - - баг перетворення/повторення запиту provider → тест прямих моделей - - баг pipeline сесії/історії/інструментів gateway → live smoke gateway або безпечний для CI mock-тест gateway -- Захист SecretRef traversal: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить по одній вибірковій цілі для кожного класу SecretRef із метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id із traversal-segment відхиляються. - - Якщо ви додаєте нову родину цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або зафіксуйте точну трансформацію форми запиту) +- Якщо це за своєю природою лише live-проблема (rate limit, policy автентифікації), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому рівню, який ловить баг: + - баг перетворення/повтору запиту provider → direct models test + - баг pipeline Gateway session/history/tool → live gateway smoke або безпечний для CI mock-тест Gateway +- Захисне обмеження обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. + - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих target id, щоб нові класи не могли бути тихо пропущені. diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 50e869984..6eb7b56de 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,32 +1,29 @@ --- read_when: - - Ви хочете використовувати вбудований harness app-server Codex + - Ви хочете використовувати комплектний harness app-server Codex - Вам потрібні посилання на моделі Codex і приклади конфігурації - - Ви хочете вимкнути fallback до PI для розгортань лише з Codex -summary: Запускайте ходи вбудованого агента OpenClaw через вбудований harness app-server Codex -title: Codex Harness + - Ви хочете вимкнути резервне перемикання на Pi для розгортань лише з Codex +summary: Запускайте вбудовані ходи агента OpenClaw через комплектний harness app-server Codex +title: Harness Codex x-i18n: - generated_at: "2026-04-23T19:25:44Z" + generated_at: "2026-04-23T20:05:13Z" model: gpt-5.4 provider: openai - source_hash: 99ca00550be4e41aa154a99298e3e1b027f8199d541249149cb0ec722e035876 + source_hash: 323ee3e0f4b78017e325288247c025403fc55216059a71e2596acdaaf56e7b25 source_path: plugins/codex-harness.md workflow: 15 --- -# Codex Harness +# Harness Codex -Вбудований Plugin `codex` дає OpenClaw змогу запускати ходи вбудованого агента через -app-server Codex замість вбудованого harness PI. +Комплектний Plugin `codex` дає змогу OpenClaw запускати вбудовані ходи агента через app-server Codex замість вбудованого harness Pi. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням потоків, нативним Compaction і виконанням app-server. -OpenClaw усе ще керує чат-каналами, файлами сесій, вибором моделей, інструментами, -підтвердженнями, доставкою медіа та видимим дзеркалом transcript. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням потоку, нативним Compaction і виконанням app-server. +OpenClaw і далі керує чат-каналами, файлами сесій, вибором моделей, інструментами, +погодженнями, доставкою медіа та видимим дзеркалом транскрипту. -Нативні ходи Codex також дотримуються спільних хуків Plugin, тож shim-и prompt, -автоматизація з урахуванням Compaction, middleware інструментів і спостерігачі життєвого циклу -залишаються узгодженими з harness PI: +Нативні ходи Codex також враховують спільні хуки Plugin, тож шими запитів, +автоматизація з урахуванням Compaction, middleware інструментів і спостерігачі життєвого циклу залишаються узгодженими з harness Pi: - `before_prompt_build` - `before_compaction`, `after_compaction` @@ -35,60 +32,49 @@ OpenClaw усе ще керує чат-каналами, файлами сесі - `before_message_write` - `agent_end` -Вбудовані Plugin також можуть реєструвати factory розширення app-server Codex для додавання -асинхронного middleware `tool_result`. +Комплектні Plugin також можуть реєструвати фабрику розширення app-server Codex, щоб додавати асинхронне middleware `tool_result`. -Harness вимкнено за замовчуванням. Його вибирають лише тоді, коли Plugin `codex` -увімкнено і резолвлена модель є моделлю `codex/*`, або коли ви явно -примусово задаєте `embeddedHarness.runtime: "codex"` чи `OPENCLAW_AGENT_RUNTIME=codex`. -Якщо ви ніколи не налаштовуєте `codex/*`, наявні запуски PI, OpenAI, Anthropic, Gemini, local -і custom provider зберігають поточну поведінку. +Harness вимкнено за замовчуванням. У нових конфігураціях слід залишати посилання на моделі OpenAI канонічними у вигляді `openai/gpt-*` і явно примусово вказувати +`embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають harness для сумісності. ## Виберіть правильний префікс моделі -OpenClaw має окремі маршрути для доступу у форматі OpenAI та Codex: +Тепер OpenClaw зберігає канонічні посилання на моделі OpenAI GPT як `openai/*`: -| Посилання на модель | Шлях runtime | Використовуйте, коли | -| ----------------------- | -------------------------------------------- | ------------------------------------------------------------------------- | -| `openai/gpt-5.5` | Провайдер OpenAI через логіку OpenClaw/PI | Вам потрібен прямий доступ до OpenAI Platform API через `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | Провайдер OpenAI Codex OAuth через PI | Вам потрібен ChatGPT/Codex OAuth без harness app-server Codex. | -| `codex/gpt-5.5` | Вбудований провайдер Codex плюс Codex harness | Вам потрібне нативне виконання app-server Codex для ходу вбудованого агента. | +| Посилання на модель | Шлях runtime | Використовуйте, коли | +| ---------------------------------------------------- | ------------------------------------------- | ------------------------------------------------------------------------- | +| `openai/gpt-5.5` | Провайдер OpenAI через внутрішню логіку OpenClaw/Pi | Вам потрібен прямий доступ до OpenAI Platform API за допомогою `OPENAI_API_KEY`. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | -Codex harness обробляє лише посилання на моделі `codex/*`. Наявні посилання `openai/*`, -`openai-codex/*`, Anthropic, Gemini, xAI, local і custom provider зберігають -свої звичайні шляхи. +Застарілі посилання `openai-codex/gpt-*` і `codex/gpt-*` залишаються підтримуваними як псевдоніми сумісності, але в новій документації та прикладах конфігурації слід використовувати `openai/gpt-*`. -Вибір harness не є механізмом керування live-сесією. Коли виконується вбудований хід, -OpenClaw записує id вибраного harness у цю сесію і продовжує використовувати його -для наступних ходів у межах того самого id сесії. Змінюйте конфігурацію `embeddedHarness` або +Вибір harness не є елементом керування живою сесією. Коли виконується вбудований хід, +OpenClaw записує ідентифікатор вибраного harness у цю сесію і продовжує використовувати його для наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або `OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням -наявної розмови між PI і Codex. Це запобігає відтворенню одного transcript через +використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної +розмови між Pi і Codex. Це дає змогу уникнути повторного відтворення одного транскрипту через дві несумісні нативні системи сесій. -Застарілі сесії, створені до появи фіксації harness, вважаються прив’язаними до PI, щойно вони -мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на -Codex після зміни конфігурації. +Застарілі сесії, створені до закріплення harness, вважаються закріпленими за Pi, щойно в них з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на Codex після зміни конфігурації. -`/status` показує фактичний non-PI harness поруч із `Fast`, наприклад -`Fast · codex`. Harness PI за замовчуванням не показується. +`/status` показує ефективний harness, відмінний від Pi, поруч із `Fast`, наприклад +`Fast · codex`. Harness Pi за замовчуванням не показується. ## Вимоги -- OpenClaw із доступним вбудованим Plugin `codex`. -- App-server Codex версії `0.118.0` або новіший. -- Auth Codex, доступна процесу app-server. +- OpenClaw із доступним комплектним Plugin `codex`. +- app-server Codex версії `0.118.0` або новішої. +- Автентифікація Codex, доступна для процесу app-server. -Plugin блокує старіші або безверсійні handshake app-server. Це гарантує, що -OpenClaw працює з поверхнею протоколу, з якою його було протестовано. +Plugin блокує старіші або неверсійовані handshake app-server. Це гарантує, що +OpenClaw працює з тією поверхнею протоколу, щодо якої його було протестовано. -Для live і Docker smoke-тестів auth зазвичай надходить із `OPENAI_API_KEY`, разом із -необов’язковими файлами CLI Codex, такими як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте ті самі auth-матеріали, що й ваш локальний app-server Codex. +Для live- і Docker-smoke-тестів автентифікація зазвичай надходить з `OPENAI_API_KEY`, а також з необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі матеріали автентифікації, що й ваш локальний app-server Codex. ## Мінімальна конфігурація -Використовуйте `codex/gpt-5.5`, увімкніть вбудований Plugin і примусово задайте harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть комплектний Plugin і примусово задайте harness `codex`: ```json5 { @@ -101,7 +87,7 @@ OpenClaw працює з поверхнею протоколу, з якою йо }, agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -111,7 +97,7 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди й `codex`: +Якщо у вашій конфігурації використовується `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -126,14 +112,12 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -Задання `agents.defaults.model` або моделі агента як `codex/` також -автоматично вмикає вбудований Plugin `codex`. Явний запис Plugin усе ще -корисний у спільних конфігураціях, бо робить намір розгортання очевидним. +Застарілі конфігурації, які задають `agents.defaults.model` або модель агента як +`codex/`, і далі автоматично вмикають комплектний Plugin `codex`. У нових конфігураціях слід віддавати перевагу `openai/` разом із явним записом `embeddedHarness` вище. -## Додати Codex без заміни інших моделей +## Додайте Codex без заміни інших моделей -Залишайте `runtime: "auto"`, якщо хочете використовувати Codex для моделей `codex/*`, а PI — для -всього іншого: +Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а Pi — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для агентів, які мають використовувати harness. ```json5 { @@ -147,17 +131,15 @@ OpenClaw працює з поверхнею протоколу, з якою йо agents: { defaults: { model: { - primary: "codex/gpt-5.5", + primary: "openai/gpt-5.5", fallbacks: ["openai/gpt-5.5", "anthropic/claude-opus-4-6"], }, models: { - "codex/gpt-5.5": { alias: "codex" }, - "codex/gpt-5.4-mini": { alias: "codex-mini" }, "openai/gpt-5.5": { alias: "gpt" }, "anthropic/claude-opus-4-6": { alias: "opus" }, }, embeddedHarness: { - runtime: "auto", + runtime: "codex", fallback: "pi", }, }, @@ -165,23 +147,21 @@ OpenClaw працює з поверхнею протоколу, з якою йо } ``` -У такій конфігурації: +За такої структури: -- `/model codex` або `/model codex/gpt-5.5` використовує harness app-server Codex. -- `/model gpt` або `/model openai/gpt-5.5` використовує шлях провайдера OpenAI. +- `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації. - `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не-Codex модель, PI залишається сумісним harness. +- Якщо вибрано не-Codex модель, Pi залишається harness сумісності. ## Розгортання лише з Codex -Вимкніть fallback до PI, якщо вам потрібно гарантувати, що кожен хід вбудованого агента використовує -Codex harness: +Вимкніть резервне перемикання на Pi, коли потрібно довести, що кожен вбудований хід агента використовує harness Codex: ```json5 { agents: { defaults: { - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -199,13 +179,12 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Якщо fallback вимкнено, OpenClaw завершується помилкою на ранньому етапі, якщо Plugin Codex вимкнено, -потрібна модель не є посиланням `codex/*`, app-server надто старий або -app-server не може запуститися. +Коли резервне перемикання вимкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, +app-server надто старий або app-server не вдається запустити. ## Codex для окремого агента -Ви можете зробити один агент лише для Codex, тоді як агент за замовчуванням збереже звичайний +Ви можете зробити одного агента лише-Codex, тоді як агент за замовчуванням зберігатиме звичайний автовибір: ```json5 @@ -226,7 +205,7 @@ app-server не може запуститися. { id: "codex", name: "Codex", - model: "codex/gpt-5.5", + model: "openai/gpt-5.5", embeddedHarness: { runtime: "codex", fallback: "none", @@ -238,18 +217,18 @@ app-server не може запуститися. ``` Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а Codex harness створює або відновлює свій sidecar app-server -потік за потреби. `/reset` очищає прив’язку сесії OpenClaw до цього потоку -і дає змогу наступному ходу знову визначити harness з поточної конфігурації. +сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server +за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку +і дає змогу наступному ходу знову визначити harness із поточної конфігурації. ## Виявлення моделей За замовчуванням Plugin Codex запитує в app-server доступні моделі. Якщо -виявлення не вдається або перевищує час очікування, використовується вбудований fallback-каталог: +виявлення не вдається або завершується за тайм-аутом, він використовує комплектний резервний каталог для: -- `codex/gpt-5.5` -- `codex/gpt-5.4-mini` -- `codex/gpt-5.2` +- GPT-5.5 +- GPT-5.4 mini +- GPT-5.2 Ви можете налаштувати виявлення в `plugins.entries.codex.config.discovery`: @@ -271,8 +250,7 @@ app-server не може запуститися. } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску OpenClaw не опитував Codex і використовував лише -fallback-каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося опитування Codex і використовувався лише резервний каталог: ```json5 { @@ -293,19 +271,18 @@ fallback-каталог: ## Підключення до app-server і політика -За замовчуванням Plugin запускає Codex локально так: +За замовчуванням Plugin локально запускає Codex так: ```bash codex app-server --listen stdio:// ``` -За замовчуванням OpenClaw запускає локальні сесії Codex harness у режимі YOLO: +За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це довірена позиція локального оператора, яка використовується -для автономних Heartbeat: Codex може використовувати shell і мережеві інструменти без -зупинки на нативних prompt підтвердження, коли нікому відповісти. +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, що використовується +для автономних Heartbeat: Codex може використовувати shell та мережеві інструменти, не зупиняючись на нативних запитах на погодження, на які нікому відповідати. -Щоб увімкнути підтвердження Codex, перевірені guardian, задайте `appServer.mode: +Щоб увімкнути погодження Codex, які перевіряє guardian, задайте `appServer.mode: "guardian"`: ```json5 @@ -326,9 +303,9 @@ codex app-server --listen stdio:// } ``` -Guardian — це нативний reviewer підтверджень Codex. Коли Codex просить вийти з sandbox, записати поза workspace або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на підтвердження reviewer-субагенту, а не людині через prompt. Reviewer застосовує систему оцінки ризику Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, якщо вам потрібні жорсткіші обмеження, ніж у режимі YOLO, але ви все одно хочете, щоб агенти без нагляду могли просуватися далі. +Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти за межі sandbox, записати за межами workspace або додати дозволи, як-от мережевий доступ, Codex спрямовує цей запит на погодження до субагента-рецензента, а не до людини через запит. Рецензент застосовує ризикову модель Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші запобіжники, ніж у режимі YOLO, але при цьому агенти мають і далі просуватися без нагляду. -Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики все одно перевизначають `mode`, тож складні розгортання можуть поєднувати пресет із явними параметрами. +Набір `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики, як і раніше, мають пріоритет над `mode`, тож у розширених розгортаннях можна поєднувати цей набір із явними виборами. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -354,23 +331,22 @@ Guardian — це нативний reviewer підтверджень Codex. Ко Підтримувані поля `appServer`: -| Поле | За замовчуванням | Значення | -| ------------------- | --------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| Поле | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | | `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не задано | URL app-server WebSocket. | -| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane до app-server. | -| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика підтверджень Codex, що надсилається під час запуску/відновлення потоку/ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Codex Guardian перевіряв prompt підтвердження. | -| `serviceTier` | не задано | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | +| `url` | не задано | URL app-server WebSocket. | +| `authToken` | не задано | Bearer-токен для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | +| `mode` | `"yolo"` | Набір для YOLO або виконання з погодженням, що перевіряється guardian. | +| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час старту/відновлення потоку/ходу. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час старту/відновлення потоку. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб Guardian Codex перевіряв запити. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу app-server Codex: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Старіші змінні середовища все ще працюють як fallback для локального тестування, коли -відповідне поле конфігурації не задано: +Старіші змінні середовища, як і раніше, працюють як резервні варіанти для локального тестування, коли відповідне поле конфігурації не задано: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -378,13 +354,13 @@ Guardian — це нативний reviewer підтверджень Codex. Ко - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було видалено. Натомість використовуйте +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` видалено. Натомість використовуйте `plugins.entries.codex.config.appServer.mode: "guardian"` або -`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Конфігурація -є кращим варіантом для відтворюваних розгортань, оскільки зберігає поведінку Plugin в -одному перевіреному файлі разом з рештою налаштувань Codex harness. +`OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для разового локального тестування. Для +відтворюваних розгортань перевага надається конфігурації, оскільки вона зберігає поведінку Plugin +в тому самому перевіреному файлі, що й решта налаштування harness Codex. -## Типові рецепти +## Поширені рецепти Локальний Codex зі стандартним транспортом stdio: @@ -400,7 +376,7 @@ Guardian — це нативний reviewer підтверджень Codex. Ко } ``` -Перевірка harness лише для Codex, із вимкненим fallback до PI: +Перевірка harness лише-Codex, із вимкненим резервним перемиканням на Pi: ```json5 { @@ -417,7 +393,7 @@ Guardian — це нативний reviewer підтверджень Codex. Ко } ``` -Підтвердження Codex із перевіркою guardian: +Погодження Codex, перевірені Guardian: ```json5 { @@ -439,7 +415,7 @@ Guardian — це нативний reviewer підтверджень Codex. Ко } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -462,60 +438,58 @@ Guardian — це нативний reviewer підтверджень Codex. Ко } ``` -Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw прив’язано +Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано до наявного потоку Codex, наступний хід знову надсилає до -app-server поточну вибрану модель `codex/*`, провайдера, політику підтверджень, sandbox і service tier. -Перемикання з `codex/gpt-5.5` на `codex/gpt-5.2` зберігає прив’язку до -потоку, але просить Codex продовжити з новою вибраною моделлю. +app-server поточно вибрану модель OpenAI, провайдера, політику погодження, sandbox і рівень сервісу. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає +прив’язку до потоку, але просить Codex продовжити з нововибраною моделлю. ## Команда Codex -Вбудований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -загальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. +Комплектний Plugin реєструє `/codex` як авторизовану slash-команду. Вона є +універсальною і працює в будь-якому каналі, що підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує live-підключення до app-server, моделі, акаунт, rate limits, сервери MCP і skills. -- `/codex models` показує список live-моделей app-server Codex. +- `/codex status` показує стан живого підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. +- `/codex models` показує список живих моделей app-server Codex. - `/codex threads [filter]` показує список нещодавніх потоків Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати Compaction прив’язаного потоку. -- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. -- `/codex account` показує стан акаунта й rate-limit. -- `/codex mcp` показує стан MCP-серверів app-server Codex. -- `/codex skills` показує Skills app-server Codex. +- `/codex resume ` приєднує поточну сесію OpenClaw до наявного потоку Codex. +- `/codex compact` просить app-server Codex виконати Compaction для приєднаного потоку. +- `/codex review` запускає нативний перегляд Codex для приєднаного потоку. +- `/codex account` показує стан облікового запису та лімітів швидкості. +- `/codex mcp` показує список станів MCP-серверів app-server Codex. +- `/codex skills` показує список skills app-server Codex. `/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. На наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw `codex/*` до app-server і залишає розширену -історію ввімкненою. +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає +поточну вибрану модель OpenClaw `codex/*` до app-server і зберігає +увімкнену розширену історію. -Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Окремі -методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або власний app-server не надає цього JSON-RPC-методу. +Поверхня команд вимагає app-server Codex версії `0.118.0` або новішої. Про окремі +методи керування повідомляється як `unsupported by this Codex app-server`, якщо +майбутній або користувацький app-server не надає цей метод JSON-RPC. ## Інструменти, медіа та Compaction -Codex harness змінює лише низькорівневий виконавець вбудованого агента. +Harness Codex змінює лише низькорівневий виконавець вбудованого агента. OpenClaw і далі формує список інструментів і отримує динамічні результати інструментів від -harness. Текст, зображення, відео, музика, TTS, підтвердження та вивід інструментів обміну повідомленнями +harness. Текст, зображення, відео, музика, TTS, погодження та вихід інструментів обміну повідомленнями і далі проходять через звичайний шлях доставки OpenClaw. -Запити на підтвердження інструментів MCP Codex маршрутизуються через потік підтверджень Plugin OpenClaw, +Запити погодження інструментів MCP Codex маршрутизуються через потік погодження Plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`; інші запити на підтвердження та довільне введення, як і раніше, безумовно відхиляються. +`"mcp_tool_call"`; інші запити на підтвердження й запити довільного вводу, як і раніше, відхиляються безумовно. -Коли вибрана модель використовує Codex harness, нативний Compaction потоку -делегується app-server Codex. OpenClaw зберігає дзеркало transcript для історії -каналу, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -включає prompt користувача, фінальний текст асистента та полегшені записи reasoning або плану Codex, коли app-server їх надсилає. Наразі OpenClaw лише -записує сигнали початку і завершення нативного Compaction. Він поки що не показує -людинозрозуміле резюме Compaction або придатний для аудиту список того, які записи Codex -зберіг після Compaction. +Коли вибрана модель використовує harness Codex, нативний Compaction потоку делегується app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, +пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало +містить запит користувача, фінальний текст асистента та полегшені записи міркувань або плану Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише нативні сигнали початку та завершення Compaction. Він ще не показує +людинозрозумілий підсумок Compaction або придатний до аудиту список того, які записи Codex +залишив після Compaction. -Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як +Генерація медіа не потребує Pi. Генерація зображень, відео, музики, PDF, TTS і +розуміння медіа і далі використовують відповідні налаштування провайдера/моделі, такі як `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. @@ -524,28 +498,26 @@ harness. Текст, зображення, відео, музика, TTS, під **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, задайте посилання на модель `codex/*` або перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує PI замість Codex:** якщо жоден Codex harness не обробляє запуск, -OpenClaw може використати PI як сумісний backend. Задайте +**OpenClaw використовує Pi замість Codex:** якщо жоден harness Codex не бере на себе виконання, +OpenClaw може використовувати Pi як backend сумісності. Задайте `embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування, або -`embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден Plugin harness не підходить. Щойно -буде вибрано app-server Codex, його збої відображатимуться напряму без додаткової -конфігурації fallback. +`embeddedHarness.fallback: "none"`, щоб отримувати помилку, коли жоден Plugin harness не підходить. Щойно app-server Codex вибрано, його збої проявляються безпосередньо без додаткової конфігурації резервного перемикання. -**App-server відхиляється:** оновіть Codex, щоб handshake app-server -повідомляв версію `0.118.0` або новішу. +**app-server відхиляється:** оновіть Codex, щоб handshake app-server +повідомляв про версію `0.118.0` або новішу. **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket одразу завершується помилкою:** перевірте `appServer.url`, `authToken` -і що віддалений app-server підтримує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket одразу завершується з помилкою:** перевірте `appServer.url`, `authToken` +і що віддалений app-server використовує ту саму версію протоколу app-server Codex. -**Не-Codex модель використовує PI:** це очікувано. Codex harness обробляє лише -посилання на моделі `codex/*`. +**Модель не-Codex використовує Pi:** це очікувана поведінка. Harness Codex бере на себе +лише посилання на моделі `codex/*`. ## Пов’язане -- [Plugin harness агента](/uk/plugins/sdk-agent-harness) +- [Plugins Harness агента](/uk/plugins/sdk-agent-harness) - [Провайдери моделей](/uk/concepts/model-providers) -- [Довідник з конфігурації](/uk/gateway/configuration-reference) +- [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 200afed97..096c29b46 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,53 +1,60 @@ --- read_when: - - Ви змінюєте вбудований рантайм агента або реєстр harness-ів - - Ви реєструєте harness агента з bundled або довіреного Plugin-а - - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із провайдерами моделей + - Ви змінюєте вбудований runtime агента або реєстр каркаса. + - Ви реєструєте каркас агента з bundled або trusted plugin. + - Вам потрібно зрозуміти, як plugin Codex пов’язаний із постачальниками моделей. sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для Plugin-ів, які замінюють низькорівневий вбудований виконавець агента -title: Plugin-и Agent Harness +summary: Експериментальна поверхня SDK для plugin, які замінюють низькорівневий вбудований виконавець агента. +title: Плагіни каркаса агента x-i18n: - generated_at: "2026-04-23T19:26:26Z" + generated_at: "2026-04-23T20:06:10Z" model: gpt-5.4 provider: openai - source_hash: c0822248298c61f9dda7ec342558e8cda7c936876060b471ed01dc6c90779010 + source_hash: b0c0bd3ef17ce7609a50354eb3bd717ddc45102eaf3ebca022c6861169b0753c source_path: plugins/sdk-agent-harness.md workflow: 15 --- -# Plugin-и Agent Harness +# Плагіни каркаса агента -**Agent harness** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не провайдер моделі, не канал і не реєстр інструментів. +**Каркас агента** — це низькорівневий виконавець одного підготовленого ходу +агента OpenClaw. Це не постачальник моделей, не channel і не реєстр інструментів. -Використовуйте цю поверхню лише для bundled або довірених native Plugin-ів. Контракт усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований runner. +Використовуйте цю поверхню лише для bundled або trusted native plugin. Контракт +усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний +вбудований виконавець. -## Коли використовувати harness +## Коли використовувати каркас -Реєструйте agent harness, коли сімейство моделей має власний native session runtime і звичайний транспорт провайдера OpenClaw є хибною абстракцією. +Реєструйте каркас агента, коли сімейство моделей має власний native session +runtime і звичайний транспорт provider OpenClaw є хибною абстракцією. Приклади: -- native сервер coding-agent, який керує thread-ами та Compaction -- локальний CLI або демон, який має стримити native події plan/reasoning/tool -- runtime моделі, якому потрібен власний resume id на додачу до transcript сесії OpenClaw +- native-сервер агента для програмування, який керує threads і Compaction +- локальний CLI або daemon, який має транслювати native-події plan/reasoning/tool +- runtime моделі, якому потрібен власний resume id на додачу до transcript + session OpenClaw -**Не** реєструйте harness лише для додавання нового API LLM. Для звичайних HTTP- або WebSocket-API моделей створіть [provider Plugin](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних +HTTP- або WebSocket-API моделей створіть [plugin provider](/uk/plugins/sdk-provider-plugins). -## Що все ще належить core +## Що core усе ще контролює -Перед вибором harness OpenClaw уже визначив: +Перед тим як буде вибрано каркас, OpenClaw уже визначив: -- провайдера та модель +- provider і модель - стан автентифікації runtime - рівень thinking і бюджет контексту -- файл transcript/сесії OpenClaw +- файл transcript/session OpenClaw - workspace, sandbox і політику інструментів -- callback-и відповіді каналу та callback-и стримінгу -- політику fallback моделі та живого перемикання моделей +- callback-функції відповіді channel і callback-функції streaming +- політику fallback моделі та live-перемикання моделей -Такий поділ є навмисним. Harness виконує підготовлену спробу; він не вибирає провайдерів, не замінює доставку каналу й не перемикає моделі непомітно. +Цей поділ є навмисним. Каркас виконує підготовлену спробу; він не вибирає +provider, не замінює доставку channel і не перемикає моделі непомітно. -## Зареєструйте harness +## Зареєструвати каркас **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -85,64 +92,106 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає harness після визначення провайдера/моделі: +OpenClaw вибирає каркас після визначення provider/моделі: -1. Якщо в наявній сесії вже записано id harness, він має пріоритет, тому зміни config/env не перемикають цей transcript на інший runtime на льоту. -2. `OPENCLAW_AGENT_RUNTIME=` примусово вказує зареєстрований harness із цим id для сесій, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вказує вбудований harness PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані harness-и, чи підтримують вони визначену пару провайдер/модель. -5. Якщо жоден зареєстрований harness не підходить, OpenClaw використовує PI, якщо fallback PI не вимкнено. +1. Ідентифікатор каркаса, записаний в наявній session, має пріоритет, щоб зміни config/env не + перемикали цей transcript на інший runtime гарячим способом. +2. `OPENCLAW_AGENT_RUNTIME=` примусово вибирає зареєстрований каркас із цим id для + session, які ще не закріплено. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вибирає вбудований каркас PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` запитує зареєстровані каркаси, чи підтримують вони + визначені provider/модель. +5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо fallback PI + не вимкнено. -Збої Plugin harness відображаються як помилки виконання. У режимі `auto` fallback до PI використовується лише тоді, коли жоден зареєстрований Plugin harness не підтримує визначену пару провайдер/модель. Щойно Plugin harness узяв на себе виконання, OpenClaw не повторює той самий хід через PI, оскільки це може змінити семантику auth/runtime або дублювати побічні ефекти. +Збої каркасів plugin відображаються як збої виконання. У режимі `auto` fallback на PI +використовується лише тоді, коли жоден зареєстрований каркас plugin не підтримує визначені +provider/модель. Щойно каркас plugin узяв виконання на себе, OpenClaw не +повторює той самий хід через PI, оскільки це може змінити семантику auth/runtime +або дублювати побічні ефекти. -Вибраний id harness зберігається разом з id сесії після вбудованого запуску. Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них з’являється history transcript. Використовуйте нову/скинуту сесію, коли перемикаєтеся між PI і native Plugin harness. `/status` показує нестандартні id harness, такі як `codex`, поруч із `Fast`; PI лишається прихованим, оскільки це шлях сумісності за замовчуванням. +Вибраний id каркаса зберігається разом з id session після вбудованого виконання. +Старі session, створені до появи закріплення каркасів, вважаються закріпленими за PI, щойно +вони мають історію transcript. Використовуйте нову/скинуту session під час перемикання між PI та +native-каркасом plugin. `/status` показує нестандартні id каркасів, наприклад `codex`, +поруч із `Fast`; PI залишається прихованим, бо це стандартний сумісний шлях. -Bundled Plugin Codex реєструє `codex` як свій id harness. Core трактує це як звичайний id Plugin harness; специфічні для Codex псевдоніми мають належати Plugin-у або config оператора, а не спільному селектору runtime. +Bundled plugin Codex реєструє `codex` як свій id каркаса. Core сприймає це як +звичайний id каркаса plugin; псевдоніми, специфічні для Codex, мають належати plugin +або config оператора, а не спільному селектору runtime. -## Поєднання provider і harness +## Поєднання provider і каркаса -Більшість harness-ів також мають реєструвати provider. Provider робить видимими для решти OpenClaw посилання на моделі, стан auth, метадані моделі та вибір `/model`. Потім harness заявляє про підтримку цього provider у `supports(...)`. +Більшість каркасів також мають реєструвати provider. Provider робить посилання на моделі, +стан auth, метадані моделі та вибір `/model` видимими для решти +OpenClaw. Потім каркас заявляє підтримку цього provider у `supports(...)`. -Bundled Plugin Codex дотримується цього шаблону: +Bundled plugin Codex дотримується цього шаблону: - id provider: `codex` -- посилання користувача на моделі: `codex/gpt-5.5`, `codex/gpt-5.2` або інша модель, повернена app-server Codex -- id harness: `codex` -- auth: синтетична доступність provider, оскільки harness Codex керує native входом/сесією Codex -- запит до app-server: OpenClaw надсилає в Codex простий id моделі та дозволяє harness спілкуватися з native протоколом app-server +- посилання моделі для користувача: канонічне `openai/gpt-5.5` плюс + `embeddedHarness.runtime: "codex"`; старі посилання `codex/gpt-*` і далі приймаються + для сумісності +- id каркаса: `codex` +- auth: синтетична доступність provider, оскільки каркас Codex контролює + native-вхід/session Codex +- запит до app-server: OpenClaw надсилає до Codex базовий id моделі й дозволяє + каркасу працювати з native-протоколом app-server -Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` лишаються посиланнями provider OpenAI та продовжують використовувати звичайний шлях provider OpenClaw. Вибирайте `codex/gpt-*`, коли вам потрібні auth під керуванням Codex, виявлення моделей Codex, native thread-и та виконання через app-server Codex. `/model` може перемикатися між моделями Codex, поверненими app-server Codex, без потреби в облікових даних provider OpenAI. +Plugin Codex є адитивним. Звичайні посилання `openai/gpt-*` і далі використовують +звичайний шлях provider OpenClaw, якщо ви явно не примусите каркас Codex через +`embeddedHarness.runtime: "codex"`. Старі посилання `codex/gpt-*` і далі вибирають +provider і каркас Codex для сумісності. -Налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex див. у [Codex Harness](/uk/plugins/codex-harness). +Щодо налаштування оператором, прикладів префіксів моделей і config лише для Codex, див. +[Каркас Codex](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Plugin Codex перевіряє initialize handshake app-server і блокує старіші сервери або сервери без версії, щоб OpenClaw працював лише з тією поверхнею протоколу, яку було протестовано. +OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Plugin Codex перевіряє +initialize-handshake app-server і блокує старіші або безверсійні сервери, щоб +OpenClaw працював лише з поверхнею протоколу, з якою його було протестовано. ### Middleware результатів інструментів Codex app-server -Bundled Plugin-и також можуть підключати middleware `tool_result`, специфічний для Codex app-server, через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній маніфест оголошує `contracts.embeddedExtensionFactories: ["codex-app-server"]`. Це seam довіреного Plugin-а для асинхронних трансформацій `tool_result`, які мають виконуватися всередині native harness Codex до того, як вивід інструмента буде спроєктовано назад у transcript OpenClaw. +Bundled plugin також можуть підключати middleware `tool_result`, специфічний для Codex app-server, +через `api.registerCodexAppServerExtensionFactory(...)`, коли їхній manifest оголошує +`contracts.embeddedExtensionFactories: ["codex-app-server"]`. +Це seam trusted-plugin для асинхронних перетворень `tool_result`, які мають +працювати всередині native-каркаса Codex, перш ніж вивід інструмента буде спроєктовано +назад у transcript OpenClaw. -### Режим native harness Codex +### Режим native-каркаса Codex -Bundled harness `codex` — це native режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть bundled Plugin `codex` і додайте `codex` у `plugins.allow`, якщо у вашій config використовується обмежувальний allowlist. Він відрізняється від `openai-codex/*`: +Bundled каркас `codex` — це native-режим Codex для вбудованих ходів +агента OpenClaw. Спочатку увімкніть bundled plugin `codex` і додайте `codex` до +`plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Нові config мають +використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Старі +посилання моделей `openai-codex/*` і `codex/*` залишаються псевдонімами сумісності. -- `openai-codex/*` використовує OAuth ChatGPT/Codex через звичайний шлях provider OpenClaw. -- `codex/*` використовує bundled provider Codex і маршрутизує хід через app-server Codex. +Коли цей режим працює, Codex контролює native id thread, поведінку resume, +Compaction і виконання app-server. OpenClaw і далі контролює chat channel, +видиме дзеркало transcript, політику інструментів, approvals, доставку медіа та вибір +session. Використовуйте `embeddedHarness.runtime: "codex"` разом з +`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях +Codex app-server може взяти це виконання. Цей config є лише захистом вибору: +збої Codex app-server уже напряму завершуються помилкою замість повторної спроби через PI. -Коли працює цей режим, Codex керує native id thread, поведінкою resume, Compaction і виконанням app-server. OpenClaw усе ще керує chat-каналом, видимим дзеркалом transcript, політикою інструментів, погодженнями, доставкою медіа та вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що лише шлях app-server Codex може взяти на себе виконання. Ця config є лише захистом вибору: збої app-server Codex і так завершуються помилкою напряму, а не повторною спробою через PI. +## Вимкнення fallback PI -## Вимкнення fallback до PI +За замовчуванням OpenClaw запускає вбудованих агентів з `agents.defaults.embeddedHarness`, +встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси plugin +можуть узяти на себе пару provider/модель. Якщо жоден не підходить, OpenClaw повертається до PI. -За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані Plugin harness-и можуть взяти на себе пару провайдер/модель. Якщо жоден не підходить, OpenClaw переходить на PI. +Установіть `fallback: "none"`, коли вам потрібно, щоб відсутність вибору каркаса plugin +призводила до помилки замість використання PI. Збої вже вибраного каркаса plugin і так завершуються жорстко. Це +не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. -Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору Plugin harness завершувалася помилкою замість використання PI. Збої вже вибраного Plugin harness і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. - -Для вбудованих запусків лише з Codex: +Для вбудованих виконань лише з Codex: ```json { "agents": { "defaults": { - "model": "codex/gpt-5.5", + "model": "openai/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" @@ -152,7 +201,9 @@ Bundled harness `codex` — це native режим Codex для вбудован } ``` -Якщо ви хочете, щоб будь-який зареєстрований Plugin harness міг узяти на себе відповідні моделі, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть fallback: +Якщо ви хочете, щоб будь-який зареєстрований каркас plugin міг узяти відповідні моделі, але +ніколи не хочете, щоб OpenClaw непомітно повертався до PI, залиште `runtime: "auto"` і вимкніть +fallback: ```json { @@ -181,7 +232,7 @@ Bundled harness `codex` — це native режим Codex для вбудован "list": [ { "id": "codex-only", - "model": "codex/gpt-5.5", + "model": "openai/gpt-5.5", "embeddedHarness": { "runtime": "codex", "fallback": "none" @@ -192,7 +243,9 @@ Bundled harness `codex` — це native режим Codex для вбудован } ``` -`OPENCLAW_AGENT_RUNTIME` усе ще перевизначає налаштований runtime. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback до PI через середовище. +`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI через +середовище. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -200,39 +253,53 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли fallback вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний harness не зареєстровано, він не підтримує визначену пару провайдер/модель або завершується збоєм до створення побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що фактично використовується шлях app-server Codex. +Коли fallback вимкнено, session завершується помилкою на ранньому етапі, якщо запитаний каркас не +зареєстровано, не підтримує визначені provider/модель або завершується помилкою до +створення побічних ефектів ходу. Це зроблено навмисно для розгортань лише з Codex і +для live-тестів, які мають довести, що шлях Codex app-server справді використовується. -Цей параметр керує лише вбудованим agent harness. Він не вимикає маршрутизацію image, video, music, TTS, PDF або інших моделей, специфічних для provider. +Цей параметр керує лише каркасом вбудованого агента. Він не вимикає +маршрутизацію моделей, специфічну для provider, для image, video, music, TTS, PDF чи інших типів. -## Native сесії та дзеркало transcript +## Native session і дзеркало transcript -Harness може зберігати native id сесії, id thread або resume token на боці демона. Зберігайте цю прив’язку явно пов’язаною із сесією OpenClaw і продовжуйте дзеркалити видимий користувачу вивід assistant/tool у transcript OpenClaw. +Каркас може зберігати native id session, id thread або токен resume на боці daemon. +Явно підтримуйте зв’язок цього прив’язування із session OpenClaw і +продовжуйте дзеркалити видимий користувачеві вивід assistant/tool у transcript OpenClaw. Transcript OpenClaw залишається шаром сумісності для: -- видимої в каналі history сесії -- пошуку й індексації transcript -- перемикання назад на вбудований harness PI на наступному ході -- типової поведінки `/new`, `/reset` і видалення сесії +- видимої в channel історії session +- пошуку та індексації transcript +- повернення до вбудованого каркаса PI на наступному ході +- загальної поведінки `/new`, `/reset` і видалення session -Якщо ваш harness зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг очистити її під час скидання відповідної сесії OpenClaw. +Якщо ваш каркас зберігає sidecar-прив’язування, реалізуйте `reset(...)`, щоб OpenClaw міг +очистити його під час скидання пов’язаної session OpenClaw. ## Результати інструментів і медіа -Core формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли harness виконує динамічний виклик інструмента, повертайте результат інструмента назад через форму результату harness, а не надсилайте медіа в канал самостійно. +Core формує список інструментів OpenClaw і передає його в підготовлену спробу. +Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через +форму результату каркаса, а не надсилайте медіа в channel самостійно. -Це зберігає text, image, video, music, TTS, approval і виводи інструментів обміну повідомленнями в тому самому шляху доставки, що й у запусків на базі PI. +Це зберігає text, image, video, music, TTS, approval і виводи інструментів обміну повідомленнями +на тому самому шляху доставки, що й у виконаннях на базі PI. ## Поточні обмеження -- Публічний шлях імпорту є узагальненим, але деякі псевдоніми типів спроб/результатів усе ще містять назви `Pi` для сумісності. -- Установлення сторонніх harness-ів є експериментальним. Віддавайте перевагу provider Plugin-ам, доки вам не знадобиться native session runtime. -- Перемикання harness підтримується між ходами. Не перемикайте harness посеред ходу після того, як уже почалися native інструменти, approvals, текст assistant або надсилання повідомлень. +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів attempt/result і далі + містять назви `Pi` для сумісності. +- Установлення сторонніх каркасів є експериментальним. Надавайте перевагу plugin provider, + доки вам не стане потрібен native session runtime. +- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред + ходу після того, як уже почалися native-інструменти, approvals, текст assistant або + надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) - [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) -- [Provider Plugin-и](/uk/plugins/sdk-provider-plugins) -- [Codex Harness](/uk/plugins/codex-harness) -- [Провайдери моделей](/uk/concepts/model-providers) +- [Плагіни provider](/uk/plugins/sdk-provider-plugins) +- [Каркас Codex](/uk/plugins/codex-harness) +- [Постачальники моделей](/uk/concepts/model-providers) diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index 05cc28636..2b2a63c76 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,56 +1,56 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете використовувати автентифікацію через підписку Codex замість API-ключів + - Ви хочете використовувати автентифікацію Codex subscription замість API key - Вам потрібна суворіша поведінка виконання агента GPT-5 -summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw +summary: Використовуйте OpenAI через API key або Codex subscription в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-23T19:26:50Z" + generated_at: "2026-04-23T20:06:14Z" model: gpt-5.4 provider: openai - source_hash: 75c0492abf21cc2f0dfb83f32111b2b7e41cb85dd09ede6c1c45b18a135e46e1 + source_hash: 012be7535f442e382180f883435c2be907e0b56cf73413d23a3e8e4321e56063 source_path: providers/openai.md workflow: 15 --- # OpenAI - OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два варіанти автентифікації: + OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує два шляхи автентифікації за однаковими канонічними посиланнями на моделі OpenAI: - - **API-ключ** — прямий доступ до OpenAI Platform з оплатою за використання (`openai/*` моделі) - - **Підписка Codex** — вхід через ChatGPT/Codex з доступом за підпискою (`openai-codex/*` моделі) + - **API key** — прямий доступ до OpenAI Platform з білінгом за використання (`openai/*` моделі) + - **Codex subscription** — вхід через ChatGPT/Codex із доступом за підпискою. Внутрішній ідентифікатор автентифікації/постачальника — `openai-codex`, але нові посилання на моделі все одно мають використовувати `openai/*`. - OpenAI явно підтримує використання subscription OAuth у зовнішніх інструментах і робочих процесах на кшталт OpenClaw. + OpenAI явно підтримує використання OAuth підписки у зовнішніх інструментах і робочих процесах, як-от OpenClaw. ## Покриття можливостей OpenClaw - | Можливість OpenAI | Поверхня OpenClaw | Стан | - | ------------------------ | ----------------------------------------- | ------------------------------------------------------ | - | Chat / Responses | Провайдер моделей `openai/` | Так | - | Моделі підписки Codex | Провайдер моделей `openai-codex/` | Так | - | Server-side web search | Рідний інструмент OpenAI Responses | Так, коли web search увімкнено й провайдер не закріплено | - | Зображення | `image_generate` | Так | - | Відео | `video_generate` | Так | - | Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так | - | Batch speech-to-text | `tools.media.audio` / розуміння медіа | Так | - | Streaming speech-to-text | Voice Call `streaming.provider: "openai"` | Так | - | Realtime voice | Voice Call `realtime.provider: "openai"` | Так | - | Embeddings | Провайдер embedding для пам’яті | Так | + | Можливість OpenAI | Поверхня OpenClaw | Статус | + | ------------------------- | ----------------------------------------- | ------------------------------------------------------ | + | Чат / Responses | Постачальник моделей `openai/` | Так | + | Моделі Codex subscription | `openai/` з автентифікацією `openai-codex` | Так | + | Вебпошук на стороні сервера | Рідний інструмент OpenAI Responses | Так, коли вебпошук увімкнено і постачальника не закріплено | + | Зображення | `image_generate` | Так | + | Відео | `video_generate` | Так | + | Перетворення тексту в мовлення | `messages.tts.provider: "openai"` / `tts` | Так | + | Пакетне перетворення мовлення в текст | `tools.media.audio` / розуміння медіа | Так | + | Потокове перетворення мовлення в текст | Voice Call `streaming.provider: "openai"` | Так | + | Realtime voice | Voice Call `realtime.provider: "openai"` | Так | + | Embeddings | постачальник embedding для пам’яті | Так | ## Початок роботи - Виберіть бажаний метод автентифікації та виконайте кроки налаштування. + Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - **Найкраще для:** прямого доступу до API та тарифікації за використання. + **Найкраще підходить для:** прямого доступу до API та білінгу за використання. - - Створіть або скопіюйте API-ключ з [панелі OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API key з [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). - + ```bash openclaw onboard --auth-choice openai-api-key ``` @@ -61,22 +61,22 @@ x-i18n: openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` - ### Зведення маршрутів + ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| | `openai/gpt-5.5` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.5-pro` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | - Вхід через ChatGPT/Codex маршрутизується через `openai-codex/*`, а не `openai/*`. + `openai-codex/*` усе ще приймається як застарілий псевдонім сумісності, але нові конфігурації мають використовувати `openai/*`. ### Приклад конфігурації @@ -89,13 +89,13 @@ x-i18n: ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху прямого API. Реальні запити до OpenAI API відхиляють цю модель. Spark доступна лише в Codex. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark` на шляху прямого API. Реальні запити до OpenAI API відхиляють цю модель. Spark доступний лише в Codex. - - **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT. + + **Найкраще підходить для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud вимагає входу в ChatGPT. @@ -109,87 +109,87 @@ x-i18n: openclaw models auth login --provider openai-codex ``` - Для headless або конфігурацій, несприятливих до callback, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback локального браузера: + Для headless або несумісних із callback налаштувань додайте `--device-code`, щоб увійти через потік коду пристрою ChatGPT замість callback браузера localhost: ```bash openclaw models auth login --provider openai-codex --device-code ``` - + ```bash - openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 + openclaw config set agents.defaults.model.primary openai/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` - ### Зведення маршрутів + ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Маршрут | Автентифікація | |-----------|-------|------| - | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth | Вхід у Codex | - | `openai-codex/gpt-5.3-codex-spark` | ChatGPT/Codex OAuth | Вхід у Codex (залежить від entitlement) | + | `openai/gpt-5.5` | OAuth ChatGPT/Codex | вхід Codex | + | `openai/gpt-5.3-codex-spark` | OAuth ChatGPT/Codex | вхід Codex (залежить від entitlement) | - Цей маршрут навмисно відокремлений від `openai/gpt-5.5`. Використовуйте `openai/*` з API-ключем для прямого доступу до Platform, а `openai-codex/*` — для доступу через підписку Codex. + Посилання на моделі `openai-codex/*` і `codex/*` — це застарілі псевдоніми сумісності. Для команд автентифікації/профілю продовжуйте використовувати ідентифікатор постачальника `openai-codex`. ### Приклад конфігурації ```json5 { - agents: { defaults: { model: { primary: "openai-codex/gpt-5.5" } } }, + agents: { defaults: { model: { primary: "openai/gpt-5.5" } } }, } ``` - Onboarding більше не імпортує матеріали OAuth із `~/.codex`. Увійдіть через browser OAuth (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. + Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через OAuth у браузері (типово) або через потік коду пристрою вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агента. ### Обмеження вікна контексту OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення. - Для `openai-codex/gpt-5.5`: + Для `openai/gpt-5.5` через Codex OAuth: - - Нативне `contextWindow`: `1000000` - - Типове обмеження `contextTokens` під час виконання: `272000` +- Власне `contextWindow`: `1000000` +- Типове обмеження `contextTokens` під час виконання: `272000` - Менше типове обмеження на практиці дає кращі характеристики затримки та якості. Перевизначте його через `contextTokens`: +Менше типове обмеження на практиці має кращі характеристики затримки та якості. Перевизначте його за допомогою `contextTokens`: - ```json5 - { - models: { - providers: { - "openai-codex": { - models: [{ id: "gpt-5.5", contextTokens: 160000 }], - }, - }, +```json5 +{ + models: { + providers: { + "openai-codex": { + models: [{ id: "gpt-5.5", contextTokens: 160000 }], }, - } - ``` + }, + }, +} +``` - - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. - + +Використовуйте `contextWindow`, щоб оголосити власні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. + ## Генерація зображень -Убудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. +Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -| Можливість | Значення | -| ------------------------ | ---------------------------------- | -| Типова модель | `openai/gpt-image-2` | -| Макс. зображень на запит | 4 | -| Режим редагування | Увімкнено (до 5 еталонних зображень) | -| Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | +| Можливість | Значення | +| ------------------------- | ---------------------------------- | +| Модель за замовчуванням | `openai/gpt-image-2` | +| Макс. кількість зображень на запит | 4 | +| Режим редагування | Увімкнено (до 5 еталонних зображень) | +| Перевизначення розміру | Підтримується, зокрема розміри 2K/4K | | Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | ```json5 @@ -203,35 +203,33 @@ x-i18n: ``` -Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку резервування. +Див. [Генерація зображень](/uk/tools/image-generation) щодо спільних параметрів інструмента, вибору постачальника та поведінки резервного перемикання. -`gpt-image-2` є типовим як для генерації зображень з тексту OpenAI, так і для -редагування зображень. `gpt-image-1` залишається доступною як явне перевизначення моделі, але нові -робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. +`gpt-image-2` є типовим значенням як для генерації зображень із тексту OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але в нових робочих процесах зображень OpenAI слід використовувати `openai/gpt-image-2`. -Згенерувати: +Генерування: ``` -/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +/tool image_generate model=openai/gpt-image-2 prompt="Відполірований постер запуску OpenClaw на macOS" size=3840x2160 count=1 ``` -Редагувати: +Редагування: ``` -/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 +/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536 ``` ## Генерація відео -Убудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. +Вбудований Plugin `openai` реєструє генерацію відео через інструмент `video_generate`. -| Можливість | Значення | -| ---------------- | --------------------------------------------------------------------------------- | -| Типова модель | `openai/sora-2` | -| Режими | Текст у відео, зображення у відео, редагування одного відео | -| Еталонні входи | 1 зображення або 1 відео | -| Перевизначення розміру | Підтримується | +| Можливість | Значення | +| ---------------- | ----------------------------------------------------------------------------------- | +| Модель за замовчуванням | `openai/sora-2` | +| Режими | Текст у відео, зображення у відео, редагування одного відео | +| Еталонні вхідні дані | 1 зображення або 1 відео | +| Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | ```json5 @@ -245,25 +243,25 @@ x-i18n: ``` -Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір провайдера та поведінку резервування. +Див. [Генерація відео](/uk/tools/video-generation) щодо спільних параметрів інструмента, вибору постачальника та поведінки резервного перемикання. -## Внесок prompt для GPT-5 +## Внесок у промпт GPT-5 -OpenClaw додає спільний внесок у prompt для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за id моделі, тому `openai/gpt-5.5`, `openai-codex/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий оверлей. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `openai/gpt-5.5`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий оверлей. Старіші моделі GPT-4.x — ні. -Убудований провайдер рідного harness Codex (`codex/*`) використовує ту саму поведінку GPT-5 і оверлей Heartbeat через інструкції розробника app-server Codex, тож сесії `codex/gpt-5.x` зберігають ту саму послідовність виконання та вказівки щодо проактивного Heartbeat, навіть попри те, що рештою prompt harness керує Codex. +Вбудований нативний harness Codex використовує ту саму поведінку GPT-5 і оверлей Heartbeat через інструкції розробника Codex app-server, тому сеанси `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ту саму послідовність виконання та проактивні вказівки Heartbeat, навіть якщо рештою промпта harness керує Codex. -Внесок GPT-5 додає контракт поведінки з тегами для збереження persona, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається у спільному системному prompt OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. +Внесок GPT-5 додає тегований контракт поведінки для збереження персони, безпеки виконання, дисципліни інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповіді та тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди увімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| ---------------------- | ------------------------------------------ | -| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише шар дружнього стилю | +| Значення | Ефект | +| --------------------- | --------------------------------------------- | +| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише шар дружнього стилю | - + ```json5 { agents: { @@ -288,23 +286,23 @@ OpenClaw додає спільний внесок у prompt для запуск -Застаріле `plugins.entries.openai.config.personality` усе ще читається як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застаріле `plugins.entries.openai.config.personality` усе ще зчитується як резервний варіант сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення - Убудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. + Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Параметр | Шлях конфігурації | Типове значення | + | Налаштування | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | - | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | - | API-ключ | `messages.tts.providers.openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | + | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових повідомлень, `mp3` для файлів | + | API key | `messages.tts.providers.openai.apiKey` | Повертається до `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -322,23 +320,23 @@ OpenClaw додає спільний внесок у prompt для запуск ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базову URL-адресу TTS, не впливаючи на кінцеву точку chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку API чату. - - Убудований Plugin `openai` реєструє пакетне speech-to-text через - поверхню транскрипції розуміння медіа OpenClaw. + + Вбудований Plugin `openai` реєструє пакетне перетворення мовлення в текст через + поверхню транскрибування розуміння медіа в OpenClaw. - - Типова модель: `gpt-4o-transcribe` - - Ендпоїнт: OpenAI REST `/v1/audio/transcriptions` - - Вхідний шлях: multipart-вивантаження аудіофайла - - Підтримується в OpenClaw всюди, де транскрипція вхідного аудіо використовує - `tools.media.audio`, включно із сегментами голосових каналів Discord і - аудіовкладеннями каналів + - Модель за замовчуванням: `gpt-4o-transcribe` + - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` + - Вхідний шлях: multipart-завантаження аудіофайлу + - Підтримується в OpenClaw скрізь, де транскрибування вхідного аудіо використовує + `tools.media.audio`, зокрема сегменти голосового каналу Discord і аудіовкладення + каналу - Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо: + Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: ```json5 { @@ -358,72 +356,73 @@ OpenClaw додає спільний внесок у prompt для запуск } ``` - Підказки мови й prompt передаються до OpenAI, коли їх задано через - спільну конфігурацію аудіомедіа або запит транскрипції для конкретного виклику. + Підказки мови та промпта передаються до OpenAI, коли їх указано в + спільній конфігурації аудіомедіа або в запиті транскрибування для конкретного виклику. - - Убудований Plugin `openai` реєструє транскрипцію в реальному часі для Plugin Voice Call. + + Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. - | Параметр | Шлях конфігурації | Типове значення | + | Налаштування | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | - | Prompt | `...openai.prompt` | (не задано) | + | Промпт | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API-ключ | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | + | API key | `...openai.apiKey` | Повертається до `OPENAI_API_KEY` | - Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей streaming provider призначений для шляху транскрипції в реальному часі Plugin Voice Call; голос у Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрипції `tools.media.audio`. + Використовує WebSocket-з’єднання з `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий постачальник призначений для шляху транскрибування в реальному часі Plugin Voice Call; голос у Discord наразі записує короткі сегменти й натомість використовує пакетний шлях транскрибування `tools.media.audio`. - Убудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. + Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. - | Параметр | Шлях конфігурації | Типове значення | + | Налаштування | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API-ключ | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | + | API key | `...openai.apiKey` | Повертається до `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двоспрямований виклик інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує формат аудіо G.711 u-law. -## Ендпоїнти Azure OpenAI +## Кінцеві точки Azure OpenAI -Убудований провайдер `openai` може спрямовувати генерацію зображень до ресурсу Azure OpenAI -шляхом перевизначення базової URL-адреси. На шляху генерації зображень OpenClaw -автоматично визначає імена хостів Azure в `models.providers.openai.baseUrl` і переключається на -формат запиту Azure. +Вбудований постачальник `openai` може націлюватися на ресурс Azure OpenAI для +генерації зображень шляхом перевизначення базового URL. На шляху генерації +зображень OpenClaw визначає імена хостів Azure у `models.providers.openai.baseUrl` і автоматично перемикається на +форму запиту Azure. Голос у реальному часі використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос -у реальному часі** в розділі [Голос і мовлення](#voice-and-speech) для налаштувань Azure. +у реальному часі** в розділі [Голос і мовлення](#voice-and-speech) щодо його налаштувань +Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка, квота або корпоративна угода Azure OpenAI +- У вас уже є підписка Azure OpenAI, квота або корпоративна угода - Вам потрібне регіональне зберігання даних або засоби відповідності вимогам, які надає Azure -- Ви хочете зберігати трафік у межах наявного тенанту Azure +- Ви хочете зберегти трафік у межах наявного tenancy Azure ### Конфігурація -Для генерації зображень через Azure із використанням убудованого провайдера `openai` вкажіть -`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` у +Для генерації зображень Azure через вбудованого постачальника `openai` вкажіть +`models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` як ключ Azure OpenAI (а не ключ OpenAI Platform): ```json5 @@ -439,7 +438,8 @@ OpenClaw додає спільний внесок у prompt для запуск } ``` -OpenClaw розпізнає такі суфікси хостів Azure для маршруту генерації зображень Azure: +OpenClaw розпізнає такі суфікси хостів Azure для маршруту генерації +зображень Azure: - `*.openai.azure.com` - `*.services.ai.azure.com` @@ -451,13 +451,14 @@ OpenClaw розпізнає такі суфікси хостів Azure для м - Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Інші base URL (публічний OpenAI, сумісні з OpenAI proxy) зберігають стандартний -формат запиту зображень OpenAI. +Для інших базових URL (публічний OpenAI, сумісні з OpenAI проксі) зберігається стандартна +форма запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує -OpenClaw 2026.4.22 або новішої версії. Попередні версії розглядають будь-який нетиповий -`openai.baseUrl` як публічний ендпоїнт OpenAI і завершуються помилкою при роботі з deployment зображень Azure. +Маршрутизація Azure для шляху генерації зображень постачальника `openai` +вимагає OpenClaw 2026.4.22 або новішої версії. Старіші версії обробляють будь-який власний +`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із deployment +зображень Azure. ### Версія API @@ -469,63 +470,63 @@ OpenClaw 2026.4.22 або новішої версії. Попередні вер export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типове значення — `2024-12-01-preview`, якщо змінну не встановлено. +Типове значення — `2024-12-01-preview`, коли змінна не задана. -### Назви моделей — це назви deployment +### Імена моделей — це імена deployment Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure, -маршрутизованих через убудований провайдер `openai`, поле `model` в OpenClaw -має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не -публічним id моделі OpenAI. +маршрутизованих через вбудованого постачальника `openai`, поле `model` в OpenClaw +має бути **іменем deployment Azure**, яке ви налаштували в порталі Azure, а не +публічним ідентифікатором моделі OpenAI. - Якщо ви створите deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: +Якщо ви створите deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: - ``` - /tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 - ``` +``` +/tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1 +``` - Те саме правило назв deployment застосовується до викликів генерації зображень, - маршрутизованих через убудований провайдер `openai`. +Те саме правило імен deployment застосовується до викликів генерації зображень, +маршрутизованих через вбудованого постачальника `openai`. - ### Регіональна доступність +### Регіональна доступність - Генерація зображень Azure наразі доступна лише в частині регіонів - (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, - `uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням - deployment і підтвердьте, що конкретна модель доступна у вашому регіоні. +Генерація зображень Azure наразі доступна лише в підмножині регіонів +(наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, +`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням +deployment і підтвердьте, що конкретна модель пропонується у вашому регіоні. - ### Відмінності параметрів +### Відмінності параметрів - Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. - Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні - значення `background` у `gpt-image-2`), або надавати їх лише для певних версій - моделі. Ці відмінності походять від Azure і базової моделі, а не від - OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте - набір параметрів, підтримуваний вашим конкретним deployment і версією API, у - порталі Azure. +Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. +Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні +значення `background` для `gpt-image-2`) або надавати їх лише в конкретних версіях +моделі. Ці відмінності походять від Azure і базової моделі, а не від +OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте +набір параметрів, які підтримуються вашим конкретним deployment і версією API в +порталі Azure. - - Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує - прихованих заголовків attribution OpenClaw — див. акордеон **Нативні vs сумісні з OpenAI - маршрути** у розділі [Розширена конфігурація](#advanced-configuration). + +Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує +приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні та OpenAI-compatible +маршрути** в розділі [Розширена конфігурація](#advanced-configuration). - Для трафіку chat або Responses в Azure (поза генерацією зображень) використовуйте - потік onboarding або окрему конфігурацію провайдера Azure — одного лише - `openai.baseUrl` недостатньо, щоб підхопити формат API/автентифікації Azure. Існує окремий - провайдер `azure-openai-responses/*`; див. - акордеон Server-side Compaction нижче. - +Для трафіку чату або Responses на Azure (поза генерацією зображень) використовуйте +потік онбордингу або окрему конфігурацію постачальника Azure — лише `openai.baseUrl` +не підхоплює форму API/автентифікації Azure. Існує окремий постачальник +`azure-openai-responses/*`; див. +акордеон Server-side compaction нижче. + - ## Розширена конфігурація +## Розширена конфігурація - + OpenClaw використовує WebSocket-first із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - Повторює одну ранню помилку WebSocket перед переходом на SSE - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час охолодження - - Додає стабільні заголовки ідентичності сесії та ходу для повторів і повторних з’єднань + - Додає стабільні заголовки ідентичності сеансу й ходу для повторних спроб і повторних підключень - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | @@ -539,7 +540,7 @@ Azure OpenAI прив’язує моделі до deployment. Для запит agents: { defaults: { models: { - "openai-codex/gpt-5.5": { + "openai/gpt-5.5": { params: { transport: "auto" }, }, }, @@ -548,17 +549,17 @@ Azure OpenAI прив’язує моделі до deployment. Для запит } ``` - Пов’язана документація OpenAI: + Пов’язані документи OpenAI: - [Realtime API with WebSocket](https://platform.openai.com/docs/guides/realtime-websocket) - [Streaming API responses (SSE)](https://platform.openai.com/docs/guides/streaming-responses) - - OpenClaw типово вмикає прогрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу. + + OpenClaw типово вмикає попередній прогрів WebSocket для `openai/*`, щоб зменшити затримку першого ходу. ```json5 - // Disable warm-up + // Вимкнути попередній прогрів { agents: { defaults: { @@ -575,12 +576,12 @@ Azure OpenAI прив’язує моделі до deployment. Для запит - OpenClaw надає спільний перемикач швидкого режиму як для `openai/*`, так і для `openai-codex/*`: + OpenClaw надає спільний перемикач швидкого режиму для `openai/*`: - - **Chat/UI:** `/fast status|on|off` + - **Чат/UI:** `/fast status|on|off` - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` - Коли цю функцію ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. + Коли ввімкнено, OpenClaw відображає швидкий режим у пріоритетну обробку OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, і швидкий режим не переписує `reasoning` або `text.verbosity`. ```json5 { @@ -588,7 +589,6 @@ Azure OpenAI прив’язує моделі до deployment. Для запит defaults: { models: { "openai/gpt-5.5": { params: { fastMode: true } }, - "openai-codex/gpt-5.5": { params: { fastMode: true } }, }, }, }, @@ -596,7 +596,7 @@ Azure OpenAI прив’язує моделі до deployment. Для запит ``` - Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI Sessions повертає сесію до налаштованого типового значення. + Перевизначення сеансу мають пріоритет над конфігурацією. Очищення перевизначення сеансу в UI Sessions повертає сеанс до налаштованого типового значення. @@ -610,7 +610,6 @@ Azure OpenAI прив’язує моделі до deployment. Для запит defaults: { models: { "openai/gpt-5.5": { params: { serviceTier: "priority" } }, - "openai-codex/gpt-5.5": { params: { serviceTier: "priority" } }, }, }, }, @@ -620,7 +619,7 @@ Azure OpenAI прив’язує моделі до deployment. Для запит Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних ендпоїнтів OpenAI (`api.openai.com`) і нативних ендпоїнтів Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-який із цих провайдерів через proxy, OpenClaw залишає `service_tier` без змін. + `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих постачальників через проксі, OpenClaw залишає `service_tier` без змін. @@ -628,13 +627,13 @@ Azure OpenAI прив’язує моделі до deployment. Для запит Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) OpenClaw автоматично вмикає Server-side Compaction: - - Примусово встановлює `store: true` (якщо сумісність моделі не задає `supportsStore: false`) - - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` - - Типове значення `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне) + - Примусово встановлює `store: true` (якщо compat моделі не задає `supportsStore: false`) + - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Типове `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо він недоступний) - - Корисно для сумісних ендпоїнтів на кшталт Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses: ```json5 { @@ -686,13 +685,13 @@ Azure OpenAI прив’язує моделі до deployment. Для запит - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses усе одно примусово встановлюють `store: true`, якщо compat не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставленням `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо compat не задає `supportsStore: false`. - Для запусків сімейства GPT-5 на `openai/*` і `openai-codex/*` OpenClaw може використовувати суворіший вбудований контракт виконання: + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання: ```json5 { @@ -705,49 +704,49 @@ Azure OpenAI прив’язує моделі до deployment. Для запит ``` З `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія інструмента + - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - Повторює хід із вказівкою діяти негайно - Автоматично вмикає `update_plan` для суттєвої роботи - - Показує явний заблокований стан, якщо модель продовжує планувати без дії + - Показує явний стан блокування, якщо модель продовжує планувати без дії - Поширюється лише на запуски сімейства GPT-5 OpenAI і Codex. Інші провайдери та старіші сімейства моделей зберігають типову поведінку. + Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку. - - OpenClaw обробляє прямі ендпоїнти OpenAI, Codex і Azure OpenAI інакше, ніж загальні сумісні з OpenAI proxy `/v1`: + + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-compatible проксі `/v1`: - **Нативні маршрути** (`openai/*`, `openai-codex/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують значення OpenAI `none` - - Не надсилають вимкнений reasoning для моделей або proxy, які відхиляють `reasoning.effort: "none"` - - Типово використовують строгий режим схем інструментів - - Додають приховані заголовки attribution лише на перевірених нативних хостах - - Зберігають форматування запитів, специфічне для OpenAI (`service_tier`, `store`, compat reasoning, підказки prompt-cache) + **Нативні маршрути** (`openai/*`, Azure OpenAI): + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI effort `none` + - Пропускають вимкнене reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` + - Типово встановлюють strict mode для схем інструментів + - Додають приховані заголовки атрибуції лише на перевірених нативних хостах + - Зберігають формування запитів, специфічне для OpenAI (`service_tier`, `store`, compat reasoning, підказки кешу промпта) **Маршрути proxy/compatible:** - Використовують м’якшу поведінку compat - - Не примушують до строгих схем інструментів або заголовків лише для нативного режиму + - Не примушують strict mode для схем інструментів або нативні заголовки - Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує прихованих заголовків attribution. + Azure OpenAI використовує нативний транспорт і поведінку compat, але не отримує прихованих заголовків атрибуції. -## Пов’язане +## Пов’язано - Вибір провайдерів, посилань на моделі та поведінки резервування. + Вибір постачальників, посилань на моделі та поведінки резервного перемикання. - Спільні параметри інструмента зображень і вибір провайдера. + Спільні параметри інструмента зображень і вибір постачальника. - Спільні параметри інструмента відео та вибір провайдера. + Спільні параметри інструмента відео і вибір постачальника. - Деталі автентифікації та правила повторного використання облікових даних. + Подробиці автентифікації та правила повторного використання облікових даних. diff --git a/docs/uk/reference/wizard.md b/docs/uk/reference/wizard.md index 248818460..fc140922a 100644 --- a/docs/uk/reference/wizard.md +++ b/docs/uk/reference/wizard.md @@ -1,16 +1,16 @@ --- read_when: - - Пошук конкретного кроку або прапорця онбордингу - - Автоматизація онбордингу в неінтерактивному режимі + - Пошук конкретного кроку онбордингу або прапорця + - Автоматизація онбордингу за допомогою неінтерактивного режиму - Налагодження поведінки онбордингу sidebarTitle: Onboarding Reference -summary: 'Повний довідник з онбордингу CLI: кожен крок, прапорець і поле конфігурації' +summary: 'Повний довідник для онбордингу CLI: кожен крок, прапорець і поле конфігурації' title: Довідник з онбордингу x-i18n: - generated_at: "2026-04-23T19:27:11Z" + generated_at: "2026-04-23T20:06:22Z" model: gpt-5.4 provider: openai - source_hash: 136fd90adfaaa9f0481168642e5efadb4f9ee67def0ac1bb40433d178f791474 + source_hash: 7b3874415ca6c5d948190655859cbaacc8d880257e79d4e3089ea7334eff7d74 source_path: reference/wizard.md workflow: 15 --- @@ -18,139 +18,139 @@ x-i18n: # Довідник з онбордингу Це повний довідник для `openclaw onboard`. -Огляд на високому рівні див. у [Onboarding (CLI)](/uk/start/wizard). +Для огляду на високому рівні див. [Онбординг (CLI)](/uk/start/wizard). -## Подробиці потоку (локальний режим) +## Деталі потоку (локальний режим) - - Якщо `~/.openclaw/openclaw.json` існує, виберіть **Залишити / Змінити / Скинути**. + - Якщо `~/.openclaw/openclaw.json` існує, виберіть **Зберегти / Змінити / Скинути**. - Повторний запуск онбордингу **не** стирає нічого, якщо ви явно не виберете **Скинути** (або не передасте `--reset`). - - CLI `--reset` типово використовує `config+creds+sessions`; використовуйте `--reset-scope full`, - щоб також видалити workspace. - - Якщо конфігурація невалідна або містить застарілі ключі, майстер зупиняється і просить - вас перед продовженням виконати `openclaw doctor`. - - Скидання використовує `trash` (ніколи не `rm`) і пропонує такі області: + - Для CLI `--reset` типово використовує `config+creds+sessions`; використайте `--reset-scope full`, + щоб також видалити робочий простір. + - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється і просить + вас запустити `openclaw doctor` перед продовженням. + - Скидання використовує `trash` (ніколи не `rm`) і пропонує області: - Лише конфігурація - Конфігурація + облікові дані + сесії - - Повне скидання (також видаляє workspace) + - Повне скидання (також видаляє робочий простір) - - - **Ключ API Anthropic**: використовує `ANTHROPIC_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його для використання демоном. - - **Ключ API Anthropic**: пріоритетний варіант Anthropic assistant в onboarding/configure. - - **Anthropic setup-token**: усе ще доступний в onboarding/configure, хоча тепер OpenClaw надає перевагу повторному використанню Claude CLI, коли це можливо. - - **Підписка OpenAI Code (Codex) (OAuth)**: потік через браузер; вставте `code#state`. - - Встановлює `agents.defaults.model` у `openai-codex/gpt-5.5`, коли модель не задано або це `openai/*`. - - **Підписка OpenAI Code (Codex) (device pairing)**: потік парування через браузер із короткоживучим кодом пристрою. - - Встановлює `agents.defaults.model` у `openai-codex/gpt-5.5`, коли модель не задано або це `openai/*`. - - **Ключ API OpenAI**: використовує `OPENAI_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його в профілях auth. - - Встановлює `agents.defaults.model` у `openai/gpt-5.5`, коли модель не задано, або це `openai/*`, або `openai-codex/*`. - - **Ключ API xAI (Grok)**: запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделі. - - **OpenCode**: запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`, отримайте його на https://opencode.ai/auth) і дає змогу вибрати каталог Zen або Go. - - **Ollama**: спочатку пропонує **Cloud + Local**, **Тільки Cloud** або **Тільки Local**. `Тільки Cloud` запитує `OLLAMA_API_KEY` і використовує `https://ollama.com`; режими з локальним хостом запитують базову URL-адресу Ollama, виявляють доступні моделі та автоматично завантажують вибрану локальну модель, коли це потрібно; `Cloud + Local` також перевіряє, чи виконано вхід на цьому хості Ollama для доступу до cloud. + + - **Anthropic API key**: використовує `ANTHROPIC_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його для використання демоном. + - **Anthropic API key**: бажаний вибір помічника Anthropic в onboarding/configure. + - **Anthropic setup-token**: усе ще доступний в onboarding/configure, хоча OpenClaw тепер надає перевагу повторному використанню Claude CLI, коли це можливо. + - **OpenAI Code (Codex) subscription (OAuth)**: потік через браузер; вставте `code#state`. + - Встановлює `agents.defaults.model` у `openai/gpt-5.5`, коли модель не задана або вже належить до сімейства OpenAI. + - **OpenAI Code (Codex) subscription (device pairing)**: потік спарювання в браузері з короткоживучим кодом пристрою. + - Встановлює `agents.defaults.model` у `openai/gpt-5.5`, коли модель не задана або вже належить до сімейства OpenAI. + - **OpenAI API key**: використовує `OPENAI_API_KEY`, якщо він є, або запитує ключ, а потім зберігає його в профілях автентифікації. + - Встановлює `agents.defaults.model` у `openai/gpt-5.5`, коли модель не задана, має вигляд `openai/*` або `openai-codex/*`. + - **xAI (Grok) API key**: запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделей. + - **OpenCode**: запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`, отримати можна на https://opencode.ai/auth) і дозволяє вибрати каталог Zen або Go. + - **Ollama**: спочатку пропонує **Cloud + Local**, **Cloud only** або **Local only**. `Cloud only` запитує `OLLAMA_API_KEY` і використовує `https://ollama.com`; режими з хостом запитують базову URL-адресу Ollama, виявляють доступні моделі та автоматично завантажують вибрану локальну модель за потреби; `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для доступу до cloud. - Докладніше: [Ollama](/uk/providers/ollama) - - **Ключ API**: зберігає ключ за вас. + - **API key**: зберігає ключ за вас. - **Vercel AI Gateway (багатомодельний проксі)**: запитує `AI_GATEWAY_API_KEY`. - Докладніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway) - **Cloudflare AI Gateway**: запитує Account ID, Gateway ID і `CLOUDFLARE_AI_GATEWAY_API_KEY`. - Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway) - - **MiniMax**: конфігурація записується автоматично; типовий hosted-варіант — `MiniMax-M2.7`. + - **MiniMax**: конфігурація записується автоматично; hosted-варіант за замовчуванням — `MiniMax-M2.7`. Налаштування через API-ключ використовує `minimax/...`, а налаштування через OAuth використовує `minimax-portal/...`. - Докладніше: [MiniMax](/uk/providers/minimax) - - **StepFun**: конфігурація записується автоматично для StepFun standard або Step Plan на китайських або глобальних endpoint-ах. - - До standard наразі входить `step-3.5-flash`, а до Step Plan також входить `step-3.5-flash-2603`. + - **StepFun**: конфігурація автоматично записується для StepFun standard або Step Plan на китайських або глобальних endpoint. + - Standard наразі включає `step-3.5-flash`, а Step Plan також включає `step-3.5-flash-2603`. - Докладніше: [StepFun](/uk/providers/stepfun) - **Synthetic (сумісний з Anthropic)**: запитує `SYNTHETIC_API_KEY`. - Докладніше: [Synthetic](/uk/providers/synthetic) - **Moonshot (Kimi K2)**: конфігурація записується автоматично. - **Kimi Coding**: конфігурація записується автоматично. - Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot) - - **Пропустити**: auth поки не налаштовано. - - Виберіть типову модель із виявлених варіантів (або введіть provider/model вручну). Для найкращої якості та нижчого ризику prompt injection обирайте найсильнішу доступну модель останнього покоління у вашому стеку provider-ів. - - Під час онбордингу виконується перевірка моделі та виводиться попередження, якщо налаштована модель невідома або для неї бракує auth. - - Режим зберігання API-ключів типово використовує текстові значення в auth-profile. Використовуйте `--secret-input-mode ref`, щоб натомість зберігати посилання на env (наприклад, `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). - - Профілі auth зберігаються в `~/.openclaw/agents//agent/auth-profiles.json` (API-ключі + OAuth). `~/.openclaw/credentials/oauth.json` — це застаріле джерело лише для імпорту. + - **Пропустити**: автентифікацію поки що не налаштовано. + - Виберіть модель за замовчуванням із виявлених варіантів (або введіть provider/model вручну). Для найкращої якості та нижчого ризику prompt injection виберіть найсильнішу модель останнього покоління, доступну у вашому стеку провайдерів. + - Онбординг запускає перевірку моделі та попереджає, якщо налаштована модель невідома або для неї відсутня автентифікація. + - Режим зберігання API-ключів за замовчуванням — значення auth-profile у відкритому тексті. Використайте `--secret-input-mode ref`, щоб зберігати натомість посилання на змінні середовища (наприклад `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`). + - Профілі автентифікації знаходяться в `~/.openclaw/agents//agent/auth-profiles.json` (API-ключі + OAuth). `~/.openclaw/credentials/oauth.json` — це застаріле джерело лише для імпорту. - Докладніше: [/concepts/oauth](/uk/concepts/oauth) Порада для headless/server: завершіть OAuth на машині з браузером, а потім скопіюйте - `auth-profiles.json` цього агента (наприклад, + `auth-profiles.json` цього агента (наприклад `~/.openclaw/agents//agent/auth-profiles.json` або відповідний шлях - `$OPENCLAW_STATE_DIR/...`) на хост gateway. `credentials/oauth.json` + `$OPENCLAW_STATE_DIR/...`) на хост Gateway. `credentials/oauth.json` є лише застарілим джерелом імпорту. - + - Типово `~/.openclaw/workspace` (можна налаштувати). - - Створює файли workspace, потрібні для bootstrap ritual агента. - - Повне компонування workspace + посібник із резервного копіювання: [Agent workspace](/uk/concepts/agent-workspace) + - Ініціалізує файли робочого простору, потрібні для ритуалу bootstrap агента. + - Повна структура робочого простору + посібник із резервного копіювання: [Робочий простір агента](/uk/concepts/agent-workspace) - - Порт, bind, режим auth, експонування через tailscale. - - Рекомендація щодо auth: залишайте **Token** навіть для loopback, щоб локальні WS-клієнти мусили автентифікуватися. + - Порт, bind, режим автентифікації, експонування через tailscale. + - Рекомендація щодо автентифікації: залишайте **Token** навіть для loopback, щоб локальні WS-клієнти мали проходити автентифікацію. - У режимі token інтерактивне налаштування пропонує: - - **Згенерувати/зберегти plaintext token** (типово) - - **Використовувати SecretRef** (опціонально) - - Quickstart повторно використовує наявні SecretRef `gateway.auth.token` через провайдери `env`, `file` і `exec` для probe/dashboard bootstrap під час онбордингу. - - Якщо цей SecretRef налаштовано, але його неможливо розв’язати, онбординг завершується помилкою на ранньому етапі з чітким повідомленням про виправлення замість мовчазної деградації auth runtime. - - У режимі password інтерактивне налаштування також підтримує зберігання в plaintext або через SecretRef. - - Шлях SecretRef для token у неінтерактивному режимі: `--gateway-token-ref-env `. - - Вимагає непорожню змінну середовища в середовищі процесу онбордингу. + - **Згенерувати/зберегти token у відкритому тексті** (за замовчуванням) + - **Використати SecretRef** (за бажанням) + - Quickstart повторно використовує наявні SecretRef `gateway.auth.token` у провайдерах `env`, `file` і `exec` для probe/dashboard bootstrap під час онбордингу. + - Якщо цей SecretRef налаштовано, але його не вдається розв’язати, онбординг завершується рано з чітким повідомленням про виправлення замість тихого погіршення runtime-автентифікації. + - У режимі password інтерактивне налаштування також підтримує зберігання у відкритому тексті або через SecretRef. + - Шлях SecretRef token у неінтерактивному режимі: `--gateway-token-ref-env `. + - Потрібна непорожня змінна середовища в середовищі процесу онбордингу. - Не можна поєднувати з `--gateway-token`. - - Вимикайте auth лише якщо повністю довіряєте кожному локальному процесу. - - Прив’язки не до loopback усе одно потребують auth. + - Вимикайте автентифікацію лише якщо ви повністю довіряєте кожному локальному процесу. + - Прив’язки не до loopback усе одно потребують автентифікації. - [WhatsApp](/uk/channels/whatsapp): необов’язковий вхід через QR. - - [Telegram](/uk/channels/telegram): токен бота. - - [Discord](/uk/channels/discord): токен бота. + - [Telegram](/uk/channels/telegram): token бота. + - [Discord](/uk/channels/discord): token бота. - [Google Chat](/uk/channels/googlechat): JSON service account + аудиторія webhook. - - [Mattermost](/uk/channels/mattermost) (Plugin): токен бота + базова URL-адреса. + - [Mattermost](/uk/channels/mattermost) (plugin): token бота + базова URL-адреса. - [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація облікового запису. - [BlueBubbles](/uk/channels/bluebubbles): **рекомендовано для iMessage**; URL-адреса сервера + пароль + webhook. - - [iMessage](/uk/channels/imessage): застарілий шлях CLI `imsg` + доступ до БД. - - Безпека DM: типово використовується pairing. Перше DM надсилає код; схваліть через `openclaw pairing approve ` або використовуйте allowlist-и. + - [iMessage](/uk/channels/imessage): застарілий шлях до CLI `imsg` + доступ до БД. + - Безпека DM: за замовчуванням використовується спарювання. Перший DM надсилає код; підтвердьте через `openclaw pairing approve ` або використовуйте allowlist. - - Виберіть підтримуваного provider-а, наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG або Tavily (або пропустіть). - - Provider-и з API можуть використовувати env vars або наявну config для швидкого налаштування; provider-и без ключів використовують свої специфічні передумови. - - Пропустити можна через `--skip-search`. + - Виберіть підтримуваного провайдера, наприклад Brave, DuckDuckGo, Exa, Firecrawl, Gemini, Grok, Kimi, MiniMax Search, Ollama Web Search, Perplexity, SearXNG або Tavily (або пропустіть). + - Провайдери з API можуть використовувати змінні середовища або наявну конфігурацію для швидкого налаштування; провайдери без ключів натомість використовують свої специфічні передумови. + - Пропустити через `--skip-search`. - Налаштувати пізніше: `openclaw configure --section web`. - + - macOS: LaunchAgent - - Потребує активної сесії користувача; для headless використовуйте власний LaunchDaemon (не постачається). + - Потребує сеансу користувача з входом у систему; для headless використовуйте власний LaunchDaemon (не постачається). - Linux (і Windows через WSL2): unit systemd користувача - - Онбординг намагається ввімкнути lingering через `loginctl enable-linger `, щоб Gateway лишався запущеним після виходу користувача із системи. - - Може запитати sudo (записує в `/var/lib/systemd/linger`); спочатку пробує без sudo. - - **Вибір runtime:** Node (рекомендовано; обов’язково для WhatsApp/Telegram). Bun **не рекомендується**. - - Якщо auth через token вимагає token і `gateway.auth.token` керується через SecretRef, установлення демона перевіряє його, але не зберігає розв’язані plaintext-значення token у метаданих середовища сервісу супервізора. - - Якщо auth через token вимагає token, а налаштований token SecretRef не розв’язується, установлення демона блокується з практичними вказівками. - - Якщо одночасно налаштовано `gateway.auth.token` і `gateway.auth.password`, а `gateway.auth.mode` не задано, установлення демона блокується, доки режим не буде явно вказано. + - Онбординг намагається увімкнути lingering через `loginctl enable-linger `, щоб Gateway залишався запущеним після виходу з системи. + - Може запросити sudo (записує у `/var/lib/systemd/linger`); спочатку намагається без sudo. + - **Вибір середовища виконання:** Node (рекомендовано; обов’язково для WhatsApp/Telegram). Bun **не рекомендовано**. + - Якщо для token-автентифікації потрібен token і `gateway.auth.token` керується через SecretRef, встановлення демона перевіряє його, але не зберігає розв’язані plaintext-значення token у метаданих середовища сервісу supervisor. + - Якщо для token-автентифікації потрібен token і налаштований token SecretRef не розв’язується, встановлення демона блокується з практичними вказівками. + - Якщо налаштовані і `gateway.auth.token`, і `gateway.auth.password`, а `gateway.auth.mode` не задано, встановлення демона блокується, доки режим не буде встановлено явно. - Запускає Gateway (за потреби) і виконує `openclaw health`. - - Порада: `openclaw status --deep` додає live-probe стану gateway до виводу status, включно з probe-ами каналів, де це підтримується (потребує доступного gateway). + - Порада: `openclaw status --deep` додає живу health probe Gateway до виводу статусу, включно з probe каналів, якщо це підтримується (потрібен доступний Gateway). - Зчитує доступні Skills і перевіряє вимоги. - - Дає змогу вибрати менеджер Node: **npm / pnpm** (bun не рекомендується). - - Установлює необов’язкові залежності (деякі використовують Homebrew на macOS). + - Дозволяє вибрати менеджер Node: **npm / pnpm** (bun не рекомендовано). + - Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS). - - Підсумок + наступні кроки, включно з iOS/Android/macOS застосунками для додаткових можливостей. + - Підсумок + наступні кроки, включно із застосунками iOS/Android/macOS для додаткових функцій. -Якщо GUI не виявлено, онбординг виводить інструкції з SSH port-forward для Control UI замість відкриття браузера. -Якщо ресурси Control UI відсутні, онбординг намагається зібрати їх; запасний варіант — `pnpm ui:build` (автоматично встановлює залежності UI). +Якщо GUI не виявлено, онбординг виводить інструкції з переадресації порту SSH для Control UI замість відкриття браузера. +Якщо ресурси Control UI відсутні, онбординг намагається їх зібрати; запасний варіант — `pnpm ui:build` (автоматично встановлює залежності UI). ## Неінтерактивний режим -Використовуйте `--non-interactive`, щоб автоматизувати або скриптувати онбординг: +Використайте `--non-interactive`, щоб автоматизувати або скриптувати онбординг: ```bash openclaw onboard --non-interactive \ @@ -164,9 +164,9 @@ openclaw onboard --non-interactive \ --skip-skills ``` -Додайте `--json` для підсумку в машиночитному форматі. +Додайте `--json` для машиночитаного підсумку. -SecretRef токена Gateway у неінтерактивному режимі: +Gateway token SecretRef у неінтерактивному режимі: ```bash export OPENCLAW_GATEWAY_TOKEN="your-token" @@ -177,13 +177,13 @@ openclaw onboard --non-interactive \ --gateway-token-ref-env OPENCLAW_GATEWAY_TOKEN ``` -`--gateway-token` і `--gateway-token-ref-env` взаємовиключні. +`--gateway-token` і `--gateway-token-ref-env` є взаємовиключними. `--json` **не** означає неінтерактивний режим. Для скриптів використовуйте `--non-interactive` (і `--workspace`). -Приклади команд для конкретних provider-ів наведено в [CLI Automation](/uk/start/wizard-cli-automation#provider-specific-examples). +Приклади команд для конкретних провайдерів наведено в [Автоматизація CLI](/uk/start/wizard-cli-automation#provider-specific-examples). Використовуйте цю довідкову сторінку для семантики прапорців і порядку кроків. ### Додати агента (неінтерактивно) @@ -202,34 +202,34 @@ openclaw agents add work \ Gateway надає потік онбордингу через RPC (`wizard.start`, `wizard.next`, `wizard.cancel`, `wizard.status`). Клієнти (застосунок macOS, Control UI) можуть відображати кроки без повторної реалізації логіки онбордингу. -## Налаштування Signal (`signal-cli`) +## Налаштування Signal (signal-cli) Онбординг може встановити `signal-cli` з GitHub releases: -- Завантажує відповідний asset release. +- Завантажує відповідний артефакт релізу. - Зберігає його в `~/.openclaw/tools/signal-cli//`. -- Записує `channels.signal.cliPath` у вашу config. +- Записує `channels.signal.cliPath` у вашу конфігурацію. Примітки: -- Збірки JVM потребують **Java 21**. -- Native-збірки використовуються, коли вони доступні. -- Windows використовує WSL2; встановлення `signal-cli` відбувається за Linux-потоком усередині WSL. +- JVM-збірки потребують **Java 21**. +- Коли доступно, використовуються нативні збірки. +- Windows використовує WSL2; встановлення signal-cli виконується за Linux-потоком всередині WSL. ## Що записує майстер Типові поля в `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` -- `agents.defaults.model` / `models.providers` (якщо вибрано MiniMax) -- `tools.profile` (локальний онбординг типово встановлює `"coding"`, якщо значення не задано; наявні явні значення зберігаються) -- `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (подробиці поведінки: [CLI Setup Reference](/uk/start/wizard-cli-reference#outputs-and-internals)) +- `agents.defaults.model` / `models.providers` (якщо вибрано Minimax) +- `tools.profile` (для локального онбордингу за замовчуванням використовується `"coding"`, якщо значення не задано; наявні явні значення зберігаються) +- `gateway.*` (режим, bind, автентифікація, tailscale) +- `session.dmScope` (деталі поведінки: [Довідник із налаштування CLI](/uk/start/wizard-cli-reference#outputs-and-internals)) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Allowlist-и каналів (Slack/Discord/Matrix/Microsoft Teams), коли ви погоджуєтеся на це під час запитів (імена, де можливо, перетворюються на ID). +- Allowlist каналів (Slack/Discord/Matrix/Microsoft Teams), якщо ви погоджуєтесь під час підказок (імена за можливості розв’язуються в ID). - `skills.install.nodeManager` - `setup --node-manager` приймає `npm`, `pnpm` або `bun`. - - Ручна config усе ще може використовувати `yarn`, якщо напряму встановити `skills.install.nodeManager`. + - Для ручної конфігурації все ще можна використовувати `yarn`, встановивши `skills.install.nodeManager` безпосередньо. - `wizard.lastRunAt` - `wizard.lastRunVersion` - `wizard.lastRunCommit` @@ -241,13 +241,13 @@ Gateway надає потік онбордингу через RPC (`wizard.start Облікові дані WhatsApp зберігаються в `~/.openclaw/credentials/whatsapp//`. Сесії зберігаються в `~/.openclaw/agents//sessions/`. -Деякі канали постачаються як Plugin-и. Коли ви вибираєте один із них під час налаштування, онбординг -запропонує встановити його (через npm або з локального шляху), перш ніж його можна буде налаштувати. +Деякі канали постачаються як plugins. Коли ви вибираєте один із них під час налаштування, онбординг +запропонує встановити його (через npm або локальний шлях), перш ніж його можна буде налаштувати. ## Пов’язані документи -- Огляд онбордингу: [Onboarding (CLI)](/uk/start/wizard) -- Онбординг у застосунку macOS: [Onboarding](/uk/start/onboarding) -- Довідник з config: [Gateway configuration](/uk/gateway/configuration) -- Провайдери: [WhatsApp](/uk/channels/whatsapp), [Telegram](/uk/channels/telegram), [Discord](/uk/channels/discord), [Google Chat](/uk/channels/googlechat), [Signal](/uk/channels/signal), [BlueBubbles](/uk/channels/bluebubbles) (iMessage), [iMessage](/uk/channels/imessage) (legacy) -- Skills: [Skills](/uk/tools/skills), [Skills config](/uk/tools/skills-config) +- Огляд онбордингу: [Онбординг (CLI)](/uk/start/wizard) +- Онбординг у застосунку macOS: [Онбординг](/uk/start/onboarding) +- Довідник із конфігурації: [Конфігурація Gateway](/uk/gateway/configuration) +- Провайдери: [WhatsApp](/uk/channels/whatsapp), [Telegram](/uk/channels/telegram), [Discord](/uk/channels/discord), [Google Chat](/uk/channels/googlechat), [Signal](/uk/channels/signal), [BlueBubbles](/uk/channels/bluebubbles) (iMessage), [iMessage](/uk/channels/imessage) (застарілий) +- Skills: [Skills](/uk/tools/skills), [Конфігурація Skills](/uk/tools/skills-config) diff --git a/docs/uk/start/wizard-cli-reference.md b/docs/uk/start/wizard-cli-reference.md index b58ae27be..19ffee0ee 100644 --- a/docs/uk/start/wizard-cli-reference.md +++ b/docs/uk/start/wizard-cli-reference.md @@ -1,118 +1,118 @@ --- read_when: - - Вам потрібен детальний опис поведінки `openclaw onboard` - - Ви налагоджуєте результати онбордингу або інтегруєте клієнтів онбордингу + - Вам потрібна детальна поведінка для `openclaw onboard` + - Ви налагоджуєте результати онбордингу або інтегруєте клієнти онбордингу sidebarTitle: CLI reference -summary: Повний довідник потоку налаштування CLI, налаштування auth/моделі, виводів і внутрішньої реалізації -title: Довідник з налаштування CLI +summary: Повний довідник щодо процесу налаштування CLI, налаштування автентифікації/моделей, вихідних даних і внутрішньої будови +title: Довідник із налаштування CLI x-i18n: - generated_at: "2026-04-23T19:27:38Z" + generated_at: "2026-04-23T20:06:30Z" model: gpt-5.4 provider: openai - source_hash: 485f7d074b5f9cde9cb9342bd213a93a8221c3561a92184edeceb98c40267d1d + source_hash: 5277842fa96eb49d07630c7c01831fc52edb1ad0f76bffe2926d6755a8a2fab2 source_path: start/wizard-cli-reference.md workflow: 15 --- -# Довідник з налаштування CLI +# Довідник із налаштування CLI Ця сторінка — повний довідник для `openclaw onboard`. -Короткий посібник див. у [Онбординг (CLI)](/uk/start/wizard). +Короткий посібник дивіться в [Онбординг (CLI)](/uk/start/wizard). ## Що робить майстер Локальний режим (за замовчуванням) проводить вас через: -- Налаштування моделі й auth (OAuth підписки OpenAI Code, Anthropic Claude CLI або API key, а також варіанти MiniMax, GLM, Ollama, Moonshot, StepFun і AI Gateway) +- Налаштування моделі й автентифікації (OAuth підписки OpenAI Code, Anthropic Claude CLI або API key, а також параметри MiniMax, GLM, Ollama, Moonshot, StepFun і AI Gateway) - Розташування workspace і bootstrap-файли -- Налаштування Gateway (порт, bind, auth, Tailscale) -- Канали та провайдери (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles та інші вбудовані Plugin каналів) -- Встановлення daemon (LaunchAgent, user unit systemd або нативне Scheduled Task Windows із fallback через папку Startup) +- Налаштування Gateway (порт, bind, автентифікація, Tailscale) +- Канали й провайдери (Telegram, WhatsApp, Discord, Google Chat, Mattermost, Signal, BlueBubbles та інші комплектні channel plugins) +- Установлення демона (LaunchAgent, користувацький systemd unit або нативне завдання Windows Scheduled Task із резервним варіантом через папку Startup) - Перевірку стану - Налаштування Skills -Віддалений режим налаштовує цю машину на підключення до Gateway в іншому місці. +Віддалений режим налаштовує цю машину для підключення до Gateway, розташованого в іншому місці. Він не встановлює і не змінює нічого на віддаленому хості. -## Деталі локального потоку +## Подробиці локального процесу - Якщо `~/.openclaw/openclaw.json` існує, виберіть Keep, Modify або Reset. - - Повторний запуск майстра нічого не стирає, якщо ви явно не вибрали Reset (або не передали `--reset`). + - Повторний запуск майстра нічого не стирає, якщо ви явно не виберете Reset (або не передасте `--reset`). - CLI `--reset` за замовчуванням використовує `config+creds+sessions`; використовуйте `--reset-scope full`, щоб також видалити workspace. - - Якщо конфігурація некоректна або містить застарілі ключі, майстер зупиняється і просить запустити `openclaw doctor` перед продовженням. + - Якщо конфігурація недійсна або містить застарілі ключі, майстер зупиняється і просить запустити `openclaw doctor`, перш ніж продовжити. - Reset використовує `trash` і пропонує такі області: - Лише конфігурація - Конфігурація + облікові дані + сесії - - Повний reset (також видаляє workspace) + - Повний скидання (також видаляє workspace) - - - Повна матриця варіантів наведена в [Варіанти auth і моделей](#auth-and-model-options). + + - Повна матриця варіантів наведена в [Параметри автентифікації та моделей](#auth-and-model-options). - - За замовчуванням `~/.openclaw/workspace` (можна налаштувати). + - За замовчуванням `~/.openclaw/workspace` (можна змінити). - Створює файли workspace, потрібні для bootstrap-ритуалу першого запуску. - Структура workspace: [Workspace агента](/uk/concepts/agent-workspace). - - Пропонує ввести порт, bind, режим auth і доступ через Tailscale. - - Рекомендація: залишайте auth через токен увімкненою навіть для loopback, щоб локальні WS-клієнти мусили автентифікуватися. + - Запитує порт, bind, режим автентифікації та експонування через Tailscale. + - Рекомендовано: залишати автентифікацію токеном увімкненою навіть для loopback, щоб локальні WS-клієнти мали проходити автентифікацію. - У режимі токена інтерактивне налаштування пропонує: - - **Generate/store plaintext token** (за замовчуванням) - - **Use SecretRef** (опційно) - - У режимі пароля інтерактивне налаштування також підтримує зберігання у відкритому вигляді або через SecretRef. - - Неінтерактивний шлях SecretRef для токена: `--gateway-token-ref-env `. - - Потребує непорожньої env-змінної в середовищі процесу онбордингу. + - **Згенерувати/зберегти токен відкритим текстом** (за замовчуванням) + - **Використати SecretRef** (за бажанням) + - У режимі пароля інтерактивне налаштування також підтримує зберігання відкритим текстом або через SecretRef. + - Неінтерактивний шлях для SecretRef токена: `--gateway-token-ref-env `. + - Потребує непорожньої змінної середовища в середовищі процесу онбордингу. - Не можна поєднувати з `--gateway-token`. - - Вимикайте auth лише якщо повністю довіряєте кожному локальному процесу. - - Bind, відмінні від loopback, однаково потребують auth. + - Вимикайте автентифікацію лише якщо повністю довіряєте кожному локальному процесу. + - Bind, відмінні від loopback, усе одно потребують автентифікації. - [WhatsApp](/uk/channels/whatsapp): необов’язковий вхід через QR - [Telegram](/uk/channels/telegram): токен бота - [Discord](/uk/channels/discord): токен бота - - [Google Chat](/uk/channels/googlechat): JSON service account + webhook audience - - [Mattermost](/uk/channels/mattermost): токен бота + base URL - - [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація акаунта - - [BlueBubbles](/uk/channels/bluebubbles): рекомендовано для iMessage; URL сервера + пароль + webhook + - [Google Chat](/uk/channels/googlechat): JSON облікового запису служби + аудиторія Webhook + - [Mattermost](/uk/channels/mattermost): токен бота + базовий URL + - [Signal](/uk/channels/signal): необов’язкове встановлення `signal-cli` + конфігурація облікового запису + - [BlueBubbles](/uk/channels/bluebubbles): рекомендовано для iMessage; URL сервера + пароль + Webhook - [iMessage](/uk/channels/imessage): застарілий шлях CLI `imsg` + доступ до DB - Безпека DM: за замовчуванням використовується pairing. Перше DM надсилає код; схваліть через `openclaw pairing approve ` або використовуйте allowlist. - + - macOS: LaunchAgent - - Потребує сеансу користувача з входом; для headless використовуйте власний LaunchDaemon (не постачається). - - Linux і Windows через WSL2: user unit systemd - - Майстер намагається виконати `loginctl enable-linger `, щоб gateway залишався запущеним після виходу. - - Може запросити sudo (записує `/var/lib/systemd/linger`); спочатку пробує без sudo. + - Потребує активної сесії користувача; для безголового режиму використовуйте власний LaunchDaemon (не постачається). + - Linux і Windows через WSL2: користувацький systemd unit + - Майстер намагається виконати `loginctl enable-linger `, щоб Gateway залишався активним після виходу з системи. + - Може запитати sudo (записує в `/var/lib/systemd/linger`); спочатку намагається без sudo. - Нативний Windows: спочатку Scheduled Task - - Якщо створення задачі заборонено, OpenClaw переходить до fallback через елемент входу в папці Startup для конкретного користувача і одразу запускає gateway. - - Scheduled Task залишаються пріоритетними, оскільки дають кращий статус supervisor. - - Вибір runtime: Node (рекомендовано; потрібен для WhatsApp і Telegram). Bun не рекомендовано. + - Якщо створення завдання заборонене, OpenClaw переходить до резервного варіанту: елемента входу в систему для користувача через папку Startup і негайно запускає Gateway. + - Scheduled Tasks лишаються пріоритетними, бо дають кращий статус супервізора. + - Вибір runtime: Node (рекомендовано; обов’язковий для WhatsApp і Telegram). Bun не рекомендований. - - Запускає gateway (за потреби) і виконує `openclaw health`. - - `openclaw status --deep` додає live-перевірку стану gateway до виводу status, зокрема перевірки каналів, де це підтримується. + - Запускає Gateway (за потреби) і виконує `openclaw health`. + - `openclaw status --deep` додає до виводу статусу live-перевірку стану Gateway, зокрема перевірки каналів, якщо вони підтримуються. - Зчитує доступні Skills і перевіряє вимоги. - - Дає вибрати менеджер Node: npm, pnpm або bun. - - Встановлює необов’язкові залежності (деякі використовують Homebrew на macOS). + - Дає змогу вибрати менеджер Node: npm, pnpm або bun. + - Установлює необов’язкові залежності (деякі використовують Homebrew на macOS). - - Підсумок і наступні кроки, зокрема варіанти застосунків для iOS, Android і macOS. + - Підсумок і наступні кроки, зокрема варіанти програм для iOS, Android і macOS. -Якщо GUI не виявлено, майстер виводить інструкції з переадресації портів SSH для Control UI замість відкриття браузера. -Якщо ресурси Control UI відсутні, майстер намагається їх зібрати; fallback — `pnpm ui:build` (автоматично встановлює UI-залежності). +Якщо GUI не виявлено, майстер виводить інструкції з перенаправлення порту SSH для Control UI замість відкриття браузера. +Якщо ресурси Control UI відсутні, майстер намагається їх зібрати; резервний варіант — `pnpm ui:build` (автоматично встановлює залежності UI). -## Деталі віддаленого режиму +## Подробиці віддаленого режиму -Віддалений режим налаштовує цю машину для підключення до Gateway в іншому місці. +Віддалений режим налаштовує цю машину для підключення до Gateway, розташованого в іншому місці. Віддалений режим не встановлює і не змінює нічого на віддаленому хості. @@ -121,7 +121,7 @@ x-i18n: Що ви задаєте: - URL віддаленого Gateway (`ws://...`) -- Токен, якщо віддалений Gateway вимагає auth (рекомендовано) +- Токен, якщо для віддаленого Gateway потрібна автентифікація (рекомендовано) - Якщо Gateway доступний лише через loopback, використовуйте SSH-тунелювання або tailnet. @@ -130,151 +130,151 @@ x-i18n: - Linux: Avahi (`avahi-browse`) -## Варіанти auth і моделей +## Параметри автентифікації та моделей - - Використовує `ANTHROPIC_API_KEY`, якщо він присутній, або просить ввести ключ, а потім зберігає його для використання daemon. + + Використовує `ANTHROPIC_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає його для використання демоном. - Потік через браузер; вставте `code#state`. + Процес через браузер; вставте `code#state`. - Встановлює `agents.defaults.model` у `openai-codex/gpt-5.5`, якщо модель не задано або це `openai/*`. + Встановлює `agents.defaults.model` у `openai/gpt-5.5`, якщо модель не задана або вже належить до сімейства OpenAI. - - Потік pairing через браузер із короткочасним кодом пристрою. + + Процес прив’язки через браузер із короткоживучим кодом пристрою. - Встановлює `agents.defaults.model` у `openai-codex/gpt-5.5`, якщо модель не задано або це `openai/*`. + Встановлює `agents.defaults.model` у `openai/gpt-5.5`, якщо модель не задана або вже належить до сімейства OpenAI. - - Використовує `OPENAI_API_KEY`, якщо він присутній, або просить ввести ключ, а потім зберігає облікові дані в auth profiles. + + Використовує `OPENAI_API_KEY`, якщо він наявний, або запитує ключ, а потім зберігає облікові дані в профілях автентифікації. - Встановлює `agents.defaults.model` у `openai/gpt-5.5`, якщо модель не задано, це `openai/*` або `openai-codex/*`. + Встановлює `agents.defaults.model` у `openai/gpt-5.5`, якщо модель не задана, має вигляд `openai/*` або `openai-codex/*`. - - Просить `XAI_API_KEY` і налаштовує xAI як провайдера моделей. + + Запитує `XAI_API_KEY` і налаштовує xAI як провайдера моделей. - Просить `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) і дає вибрати каталог Zen або Go. + Запитує `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) і дає змогу вибрати каталог Zen або Go. URL налаштування: [opencode.ai/auth](https://opencode.ai/auth). Зберігає ключ для вас. - Просить `AI_GATEWAY_API_KEY`. - Детальніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway). + Запитує `AI_GATEWAY_API_KEY`. + Докладніше: [Vercel AI Gateway](/uk/providers/vercel-ai-gateway). - Просить id акаунта, id gateway і `CLOUDFLARE_AI_GATEWAY_API_KEY`. - Детальніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway). + Запитує ID облікового запису, ID Gateway і `CLOUDFLARE_AI_GATEWAY_API_KEY`. + Докладніше: [Cloudflare AI Gateway](/uk/providers/cloudflare-ai-gateway). - Конфігурація записується автоматично. Розміщене значення за замовчуванням — `MiniMax-M2.7`; налаштування через API key використовує - `minimax/...`, а через OAuth — `minimax-portal/...`. - Детальніше: [MiniMax](/uk/providers/minimax). + Конфігурація записується автоматично. Hosted-варіант за замовчуванням — `MiniMax-M2.7`; налаштування через API key використовує + `minimax/...`, а налаштування через OAuth — `minimax-portal/...`. + Докладніше: [MiniMax](/uk/providers/minimax). Конфігурація автоматично записується для стандартного StepFun або Step Plan на китайських чи глобальних endpoint. - Наразі стандартний варіант включає `step-3.5-flash`, а Step Plan також включає `step-3.5-flash-2603`. - Детальніше: [StepFun](/uk/providers/stepfun). + Стандартний варіант наразі включає `step-3.5-flash`, а Step Plan також включає `step-3.5-flash-2603`. + Докладніше: [StepFun](/uk/providers/stepfun). - Просить `SYNTHETIC_API_KEY`. - Детальніше: [Synthetic](/uk/providers/synthetic). + Запитує `SYNTHETIC_API_KEY`. + Докладніше: [Synthetic](/uk/providers/synthetic). - Спочатку пропонує `Cloud + Local`, `Cloud only` або `Local only`. + Спочатку запитує `Cloud + Local`, `Cloud only` або `Local only`. `Cloud only` використовує `OLLAMA_API_KEY` з `https://ollama.com`. - Режими, що використовують хост, просять base URL (за замовчуванням `http://127.0.0.1:11434`), виявляють доступні моделі та пропонують типові варіанти. - `Cloud + Local` також перевіряє, чи цей хост Ollama увійшов у систему для доступу до cloud. - Детальніше: [Ollama](/uk/providers/ollama). + Режими з прив’язкою до хоста запитують базовий URL (за замовчуванням `http://127.0.0.1:11434`), виявляють доступні моделі та пропонують типові варіанти. + `Cloud + Local` також перевіряє, чи виконано вхід цього хоста Ollama для доступу до cloud. + Докладніше: [Ollama](/uk/providers/ollama). Конфігурації Moonshot (Kimi K2) і Kimi Coding записуються автоматично. - Детальніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot). + Докладніше: [Moonshot AI (Kimi + Kimi Coding)](/uk/providers/moonshot). - - Працює з endpoint, сумісними з OpenAI і Anthropic. + + Працює з endpoint, сумісними з OpenAI та Anthropic. - Інтерактивний онбординг підтримує ті самі варіанти зберігання API key, що й інші потоки API key провайдерів: - - **Paste API key now** (відкритий текст) - - **Use secret reference** (env-посилання або налаштоване посилання провайдера, з preflight-перевіркою) + Інтерактивний онбординг підтримує ті самі варіанти зберігання API key, що й інші процеси з API key провайдера: + - **Вставити API key зараз** (відкритий текст) + - **Використати посилання на секрет** (env ref або налаштований ref провайдера, з попередньою перевіркою) Неінтерактивні прапорці: - `--auth-choice custom-api-key` - `--custom-base-url` - `--custom-model-id` - - `--custom-api-key` (необов’язково; fallback до `CUSTOM_API_KEY`) + - `--custom-api-key` (необов’язково; за замовчуванням використовується `CUSTOM_API_KEY`) - `--custom-provider-id` (необов’язково) - `--custom-compatibility ` (необов’язково; за замовчуванням `openai`) - Залишає auth неналаштованою. + Залишає автентифікацію неналаштованою. -Поведінка моделей: +Поведінка моделі: - Виберіть модель за замовчуванням із виявлених варіантів або введіть провайдера й модель вручну. -- Коли онбординг починається з вибору auth провайдера, пікер моделі автоматично надає - перевагу цьому провайдеру. Для Volcengine і BytePlus така сама перевага +- Коли онбординг починається з вибору автентифікації провайдера, засіб вибору моделей автоматично надає перевагу + цьому провайдеру. Для Volcengine і BytePlus така сама перевага також поширюється на їхні варіанти coding-plan (`volcengine-plan/*`, `byteplus-plan/*`). -- Якщо такий фільтр бажаного провайдера був би порожнім, пікер повертається до - повного каталогу замість показу відсутності моделей. -- Майстер запускає перевірку моделі й попереджає, якщо налаштована модель невідома або відсутня auth. +- Якщо за такого фільтра за пріоритетним провайдером список був би порожнім, засіб вибору + повертається до повного каталогу замість показу порожнього списку моделей. +- Майстер виконує перевірку моделі та попереджає, якщо налаштована модель невідома або для неї немає автентифікації. Шляхи до облікових даних і профілів: -- Auth profiles (API keys + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` +- Профілі автентифікації (API keys + OAuth): `~/.openclaw/agents//agent/auth-profiles.json` - Імпорт застарілого OAuth: `~/.openclaw/credentials/oauth.json` Режим зберігання облікових даних: -- Поведінка онбордингу за замовчуванням зберігає API key як відкриті значення в auth profiles. -- `--secret-input-mode ref` вмикає режим посилань замість зберігання ключів у відкритому вигляді. - В інтерактивному налаштуванні можна вибрати одне з двох: +- Типова поведінка онбордингу зберігає API keys як значення відкритим текстом у профілях автентифікації. +- `--secret-input-mode ref` вмикає режим посилань замість зберігання ключів відкритим текстом. + В інтерактивному налаштуванні можна вибрати: - посилання на змінну середовища (наприклад `keyRef: { source: "env", provider: "default", id: "OPENAI_API_KEY" }`) - - налаштоване посилання провайдера (`file` або `exec`) з псевдонімом провайдера + id -- Інтерактивний режим посилань виконує швидку preflight-перевірку перед збереженням. - - Env-посилання: перевіряє назву змінної і непорожнє значення в поточному середовищі онбордингу. - - Посилання провайдера: перевіряє конфігурацію провайдера і резолвить запитаний id. - - Якщо preflight завершується помилкою, онбординг показує її і дає повторити спробу. -- У неінтерактивному режимі `--secret-input-mode ref` підтримує лише env. + - посилання на налаштований провайдер (`file` або `exec`) з псевдонімом провайдера + id +- Інтерактивний режим посилань виконує швидку попередню перевірку перед збереженням. + - Посилання env: перевіряє назву змінної та непорожнє значення в поточному середовищі онбордингу. + - Посилання провайдера: перевіряє конфігурацію провайдера та знаходить запитаний id. + - Якщо попередня перевірка не проходить, онбординг показує помилку і дає змогу повторити спробу. +- У неінтерактивному режимі `--secret-input-mode ref` працює лише з env. - Задайте env-змінну провайдера в середовищі процесу онбордингу. - - Вбудовані прапорці ключів (наприклад `--openai-api-key`) вимагають, щоб ця env-змінна була задана; інакше онбординг одразу завершується помилкою. - - Для власних провайдерів у неінтерактивному режимі `ref` `models.providers..apiKey` зберігається як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. - - У цьому випадку для власного провайдера `--custom-api-key` вимагає, щоб було задано `CUSTOM_API_KEY`; інакше онбординг одразу завершується помилкою. -- Облікові дані auth Gateway підтримують вибір між відкритим текстом і SecretRef в інтерактивному налаштуванні: - - Режим токена: **Generate/store plaintext token** (за замовчуванням) або **Use SecretRef**. + - Вбудовані прапорці ключів (наприклад `--openai-api-key`) вимагають, щоб цю env-змінну було задано; інакше онбординг швидко завершується з помилкою. + - Для користувацьких провайдерів неінтерактивний режим `ref` зберігає `models.providers..apiKey` як `{ source: "env", provider: "default", id: "CUSTOM_API_KEY" }`. + - У цьому випадку з користувацьким провайдером `--custom-api-key` вимагає, щоб `CUSTOM_API_KEY` було задано; інакше онбординг швидко завершується з помилкою. +- Облікові дані автентифікації Gateway підтримують вибір між відкритим текстом і SecretRef в інтерактивному налаштуванні: + - Режим токена: **Згенерувати/зберегти токен відкритим текстом** (за замовчуванням) або **Використати SecretRef**. - Режим пароля: відкритий текст або SecretRef. -- Неінтерактивний шлях SecretRef для токена: `--gateway-token-ref-env `. -- Наявні налаштування з відкритим текстом продовжують працювати без змін. +- Неінтерактивний шлях для SecretRef токена: `--gateway-token-ref-env `. +- Наявні налаштування з відкритим текстом і далі працюють без змін. -Порада для headless і серверів: завершіть OAuth на машині з браузером, а потім скопіюйте +Порада для безголового режиму і серверів: завершіть OAuth на машині з браузером, а потім скопіюйте `auth-profiles.json` цього агента (наприклад `~/.openclaw/agents//agent/auth-profiles.json` або відповідний шлях `$OPENCLAW_STATE_DIR/...`) на хост Gateway. `credentials/oauth.json` використовується лише як застаріле джерело імпорту. -## Виводи й внутрішня реалізація +## Вихідні дані та внутрішня будова Типові поля в `~/.openclaw/openclaw.json`: - `agents.defaults.workspace` - `agents.defaults.model` / `models.providers` (якщо вибрано Minimax) -- `tools.profile` (локальний онбординг за замовчуванням встановлює `"coding"`, якщо значення не задано; наявні явні значення зберігаються) -- `gateway.*` (mode, bind, auth, tailscale) -- `session.dmScope` (локальний онбординг за замовчуванням встановлює `per-channel-peer`, якщо значення не задано; наявні явні значення зберігаються) +- `tools.profile` (локальний онбординг за замовчуванням встановлює `"coding"`, якщо значення не задано; наявні явно вказані значення зберігаються) +- `gateway.*` (mode, bind, auth, Tailscale) +- `session.dmScope` (локальний онбординг за замовчуванням встановлює `per-channel-peer`, якщо значення не задано; наявні явно вказані значення зберігаються) - `channels.telegram.botToken`, `channels.discord.token`, `channels.matrix.*`, `channels.signal.*`, `channels.imessage.*` -- Allowlist каналів (Slack, Discord, Matrix, Microsoft Teams), якщо ви погоджуєтеся під час prompt (імена по можливості резолвляться в id) +- Allowlist каналів (Slack, Discord, Matrix, Microsoft Teams), якщо ви погоджуєтеся під час запитів (імена за можливості зіставляються з ID) - `skills.install.nodeManager` - Прапорець `setup --node-manager` приймає `npm`, `pnpm` або `bun`. - У ручній конфігурації пізніше все ще можна задати `skills.install.nodeManager: "yarn"`. @@ -290,8 +290,8 @@ x-i18n: Сесії зберігаються в `~/.openclaw/agents//sessions/`. -Деякі канали постачаються як Plugin. Якщо їх вибрати під час налаштування, майстер -запропонує встановити Plugin (npm або локальний шлях) перед конфігурацією каналу. +Деякі канали постачаються як plugins. Якщо їх вибрано під час налаштування, майстер +пропонує встановити Plugin (npm або локальний шлях) перед конфігурацією каналу. RPC майстра Gateway: @@ -301,19 +301,19 @@ RPC майстра Gateway: - `wizard.cancel` - `wizard.status` -Клієнти (застосунок macOS і Control UI) можуть відображати кроки, не перевпроваджуючи логіку онбордингу. +Клієнти (програма macOS і Control UI) можуть відображати кроки без повторної реалізації логіки онбордингу. Поведінка налаштування Signal: -- Завантажує відповідний release-артефакт +- Завантажує відповідний release asset - Зберігає його в `~/.openclaw/tools/signal-cli//` - Записує `channels.signal.cliPath` у конфігурацію -- Для JVM-збірок потрібна Java 21 -- Якщо доступні нативні збірки, використовуються саме вони -- Windows використовує WSL2 і дотримується Linux-потоку signal-cli всередині WSL +- Збірки JVM потребують Java 21 +- Нативні збірки використовуються, коли доступні +- Windows використовує WSL2 і дотримується Linux-процесу signal-cli всередині WSL -## Пов’язана документація +## Пов’язані документи - Центр онбордингу: [Онбординг (CLI)](/uk/start/wizard) -- Автоматизація та сценарії: [Автоматизація CLI](/uk/start/wizard-cli-automation) +- Автоматизація та скрипти: [Автоматизація CLI](/uk/start/wizard-cli-automation) - Довідник команд: [`openclaw onboard`](/uk/cli/onboard) diff --git a/docs/uk/tools/llm-task.md b/docs/uk/tools/llm-task.md index aed91b677..01cd52c47 100644 --- a/docs/uk/tools/llm-task.md +++ b/docs/uk/tools/llm-task.md @@ -1,14 +1,14 @@ --- read_when: - - Вам потрібен крок LLM лише з JSON усередині workflow - - Вам потрібен вивід LLM, валідований за schema, для автоматизації -summary: Завдання LLM лише з JSON для workflow (необов’язковий інструмент plugin) + - Ви хочете крок LLM лише з JSON усередині workflow + - Вам потрібен вивід LLM, перевірений за схемою, для автоматизації +summary: Завдання LLM лише з JSON для workflow (необов’язковий інструмент Plugin) title: Завдання LLM x-i18n: - generated_at: "2026-04-23T19:28:17Z" + generated_at: "2026-04-23T20:06:55Z" model: gpt-5.4 provider: openai - source_hash: 4234b2fd9247c06fcc481be6e3339726ebdb84891f4b8324f17e2d387dac4d8a + source_hash: 5b8dcc3c23f5181c36a8b2b34528a984bc703065617ed7091f2513cbcfb20912 source_path: tools/llm-task.md workflow: 15 --- @@ -16,12 +16,12 @@ x-i18n: # Завдання LLM `llm-task` — це **необов’язковий інструмент Plugin**, який виконує завдання LLM лише з JSON і -повертає структурований вивід (за потреби валідований за JSON Schema). +повертає структурований вивід (за потреби перевірений за JSON Schema). -Це ідеально підходить для рушіїв workflow, таких як Lobster: ви можете додати один крок LLM -без написання власного коду OpenClaw для кожного workflow. +Це ідеально підходить для рушіїв workflow на кшталт Lobster: ви можете додати один крок LLM +без написання кастомного коду OpenClaw для кожного workflow. -## Увімкніть Plugin +## Увімкнення Plugin 1. Увімкніть Plugin: @@ -62,7 +62,7 @@ x-i18n: "defaultProvider": "openai-codex", "defaultModel": "gpt-5.5", "defaultAuthProfileId": "main", - "allowedModels": ["openai-codex/gpt-5.5"], + "allowedModels": ["openai/gpt-5.5"], "maxTokens": 800, "timeoutMs": 30000 } @@ -88,14 +88,14 @@ x-i18n: - `maxTokens` (number, необов’язковий) - `timeoutMs` (number, необов’язковий) -`thinking` приймає стандартні пресети міркування OpenClaw, наприклад `low` або `medium`. +`thinking` приймає стандартні пресети reasoning OpenClaw, наприклад `low` або `medium`. ## Вивід -Повертає `details.json`, що містить розібраний JSON (і проходить валідацію за -`schema`, якщо її надано). +Повертає `details.json`, що містить розібраний JSON (і перевіряє його за +`schema`, якщо її задано). -## Приклад: крок workflow Lobster +## Приклад: крок workflow у Lobster ```lobster openclaw.invoke --tool llm-task --action json --args-json '{ @@ -120,7 +120,7 @@ openclaw.invoke --tool llm-task --action json --args-json '{ ## Примітки щодо безпеки - Інструмент працює **лише з JSON** і наказує моделі виводити тільки JSON (без - code fences і без коментарів). + code fence, без коментарів). - Для цього запуску моделі не надаються жодні інструменти. -- Вважайте вивід недовіреним, якщо не виконаєте валідацію за `schema`. -- Ставте approvals перед будь-яким кроком із побічними ефектами (send, post, exec). +- Вважайте вивід ненадійним, доки не перевірите його через `schema`. +- Розміщуйте погодження перед будь-яким кроком із побічними ефектами (send, post, exec).