From fff4e6a66cd59a55c63632c1d6b962be5a539df9 Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Thu, 23 Apr 2026 23:36:59 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/gateway/configuration-reference.md | 1548 ++++++++++---------- docs/uk/help/testing.md | 1042 +++++++------ docs/uk/plugins/sdk-overview.md | 584 +++----- docs/uk/plugins/sdk-subpaths.md | 280 ++++ docs/uk/reference/test.md | 94 +- docs/uk/tools/exec-approvals-advanced.md | 274 ++++ docs/uk/tools/exec-approvals.md | 486 ++---- docs/uk/tools/exec.md | 233 +-- docs/uk/tools/image-generation.md | 196 +-- docs/uk/tools/music-generation.md | 236 +-- docs/uk/tools/tts.md | 226 +-- docs/uk/tools/video-generation.md | 346 ++--- 12 files changed, 2817 insertions(+), 2728 deletions(-) create mode 100644 docs/uk/plugins/sdk-subpaths.md create mode 100644 docs/uk/tools/exec-approvals-advanced.md diff --git a/docs/uk/gateway/configuration-reference.md b/docs/uk/gateway/configuration-reference.md index 525eda7f9..666448409 100644 --- a/docs/uk/gateway/configuration-reference.md +++ b/docs/uk/gateway/configuration-reference.md @@ -1,41 +1,41 @@ --- read_when: - - Вам потрібні точні семантики конфігурації або типові значення на рівні полів - - Ви перевіряєте блоки конфігурації каналу, моделі, gateway або інструмента -summary: Довідник конфігурації Gateway для основних ключів OpenClaw, типових значень і посилань на окремі довідники підсистем + - Вам потрібні точні семантики конфігурації на рівні полів або значення за замовчуванням + - Ви перевіряєте блоки конфігурації каналу, моделі, Gateway або інструмента +summary: Довідник конфігурації Gateway для основних ключів OpenClaw, значень за замовчуванням і посилань на окремі довідники підсистем title: Довідник конфігурації x-i18n: - generated_at: "2026-04-23T22:59:51Z" + generated_at: "2026-04-23T23:27:46Z" model: gpt-5.4 provider: openai - source_hash: d1ac8dc6955425e3aa5c327f2024b877c1126ea821cccbef2da3a284b92d70ef + source_hash: 8d5bcafbb701c326c027059de03c647eb9b2cf2bb1a543bc91c42b5deafa4378 source_path: gateway/configuration-reference.md workflow: 15 --- Основний довідник конфігурації для `~/.openclaw/openclaw.json`. Для огляду, орієнтованого на завдання, див. [Configuration](/uk/gateway/configuration). -Ця сторінка охоплює основні поверхні конфігурації OpenClaw і дає посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр пам’яті/QMD. +Ця сторінка охоплює основні поверхні конфігурації OpenClaw і містить посилання назовні, коли підсистема має власний глибший довідник. Вона **не** намагається вбудувати на одній сторінці кожен каталог команд, що належить каналу/Plugin, або кожен глибокий параметр memory/QMD. Джерело істини в коді: -- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та Control UI, з об’єднаними метаданими bundled/plugin/channel, коли вони доступні -- `config.schema.lookup` повертає один вузол schema, обмежений шляхом, для інструментів детального перегляду -- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc щодо поточної поверхні schema +- `openclaw config schema` виводить актуальну JSON Schema, яка використовується для валідації та UI керування, із злитими метаданими bundled/Plugin/channel, якщо вони доступні +- `config.schema.lookup` повертає один вузол схеми з прив’язкою до шляху для інструментів деталізованого перегляду +- `pnpm config:docs:check` / `pnpm config:docs:gen` перевіряють базовий хеш config-doc щодо поточної поверхні схеми -Окремі глибокі довідники: +Окремі поглиблені довідники: -- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації dreaming у `plugins.entries.memory-core.config.dreaming` +- [Довідник конфігурації пам’яті](/uk/reference/memory-config) для `agents.defaults.memorySearch.*`, `memory.qmd.*`, `memory.citations` і конфігурації Dreaming у `plugins.entries.memory-core.config.dreaming` - [Slash Commands](/uk/tools/slash-commands) для поточного вбудованого + bundled каталогу команд -- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналу +- сторінки відповідних каналів/Plugin для поверхонь команд, специфічних для каналів -Формат конфігурації — **JSON5** (дозволено коментарі та кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні типові значення, якщо їх не вказано. +Формат конфігурації — **JSON5** (дозволені коментарі + кінцеві коми). Усі поля необов’язкові — OpenClaw використовує безпечні значення за замовчуванням, якщо їх не вказано. --- ## Канали -Кожен канал запускається автоматично, коли існує його розділ конфігурації (якщо не задано `enabled: false`). +Кожен канал запускається автоматично, коли існує його секція конфігурації (якщо не встановлено `enabled: false`). ### Доступ до DM і груп @@ -43,26 +43,26 @@ x-i18n: | Політика DM | Поведінка | | ------------------- | -------------------------------------------------------------- | -| `pairing` (типово) | Невідомі відправники отримують одноразовий код pairing; власник має схвалити | -| `allowlist` | Лише відправники в `allowFrom` (або в paired allow store) | +| `pairing` (типово) | Невідомі відправники отримують одноразовий код сполучення; власник має підтвердити | +| `allowlist` | Лише відправники з `allowFrom` (або зі сховища дозволів для сполучених) | | `open` | Дозволити всі вхідні DM (потрібно `allowFrom: ["*"]`) | | `disabled` | Ігнорувати всі вхідні DM | | Політика груп | Поведінка | | --------------------- | ------------------------------------------------------ | -| `allowlist` (типово) | Лише групи, що відповідають налаштованому allowlist | -| `open` | Обійти group allowlist (обмеження за згадкою все одно діє) | +| `allowlist` (типово) | Лише групи, що відповідають налаштованому списку дозволів | +| `open` | Обійти списки дозволів груп (обмеження за згадуванням усе ще застосовується) | | `disabled` | Блокувати всі повідомлення груп/кімнат | -`channels.defaults.groupPolicy` встановлює типове значення, коли `groupPolicy` провайдера не задано. -Коди pairing закінчують дію через 1 годину. Незавершені запити на pairing DM обмежено до **3 на канал**. -Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика runtime для груп повертається до `allowlist` (fail-closed) з попередженням під час запуску. +`channels.defaults.groupPolicy` задає значення за замовчуванням, коли `groupPolicy` провайдера не встановлено. +Коди сполучення спливають через 1 годину. Кількість очікуваних запитів на сполучення DM обмежена **3 на канал**. +Якщо блок провайдера повністю відсутній (`channels.` відсутній), політика груп під час виконання повертається до `allowlist` (fail-closed) із попередженням під час запуску. -### Перевизначення моделі для каналів +### Перевизначення моделей для каналів -Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сесія ще не має перевизначення моделі (наприклад, встановленого через `/model`). +Використовуйте `channels.modelByChannel`, щоб закріпити конкретні ID каналів за моделлю. Значення приймають `provider/model` або налаштовані псевдоніми моделей. Відображення каналу застосовується, коли сеанс ще не має перевизначення моделі (наприклад, встановленого через `/model`). ```json5 { @@ -83,9 +83,9 @@ x-i18n: } ``` -### Типові значення каналів і Heartbeat +### Значення за замовчуванням для каналів і Heartbeat -Використовуйте `channels.defaults` для спільної поведінки group-policy і Heartbeat у різних провайдерів: +Використовуйте `channels.defaults` для спільної поведінки політики груп і Heartbeat у провайдерів: ```json5 { @@ -103,15 +103,15 @@ x-i18n: } ``` -- `channels.defaults.groupPolicy`: запасна політика груп, коли `groupPolicy` на рівні провайдера не задано. -- `channels.defaults.contextVisibility`: типовий режим видимості додаткового контексту для всіх каналів. Значення: `all` (типово, включати весь контекст цитат/тредів/історії), `allowlist` (включати контекст лише від allowlisted відправників), `allowlist_quote` (те саме, що allowlist, але зберігати явний контекст цитати/відповіді). Перевизначення для окремого каналу: `channels..contextVisibility`. -- `channels.defaults.heartbeat.showOk`: включати статуси справних каналів у вивід 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 працює через вебканал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язана сесія. +WhatsApp працює через web-канал gateway (Baileys Web). Він запускається автоматично, коли існує прив’язаний сеанс. ```json5 { @@ -122,7 +122,7 @@ WhatsApp працює через вебканал 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 }, }, @@ -144,7 +144,7 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` - + ```json5 { @@ -162,10 +162,10 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- Вихідні команди типово використовують акаунт `default`, якщо він є; інакше — перший налаштований ID акаунта (відсортований). -- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає це запасне вибирання типового акаунта, якщо він збігається з налаштованим ID акаунта. -- Застарілий каталог автентифікації Baileys для одного акаунта переноситься `openclaw doctor` у `whatsapp/default`. -- Перевизначення для окремого акаунта: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. +- Вихідні команди типово використовують обліковий запис `default`, якщо він присутній; інакше — перший налаштований ID облікового запису (після сортування). +- Необов’язковий `channels.whatsapp.defaultAccount` перевизначає цей резервний вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Застарілий каталог автентифікації Baileys для одного облікового запису мігрується командою `openclaw doctor` у `whatsapp/default`. +- Перевизначення на рівні облікового запису: `channels.whatsapp.accounts..sendReadReceipts`, `channels.whatsapp.accounts..dmPolicy`, `channels.whatsapp.accounts..allowFrom`. @@ -223,13 +223,13 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), із `TELEGRAM_BOT_TOKEN` як запасним варіантом для типового акаунта. -- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. -- У конфігураціях із кількома акаунтами (2+ ID акаунтів) установіть явне типове значення (`channels.telegram.defaultAccount` або `channels.telegram.accounts.default`), щоб уникнути запасної маршрутизації; `openclaw doctor` попереджає, коли цього бракує або значення невалідне. -- `configWrites: false` блокує записи конфігурації, ініційовані з Telegram (перенесення ID supergroup, `/config set|unset`). +- Токен бота: `channels.telegram.botToken` або `channels.telegram.tokenFile` (лише звичайний файл; symlink відхиляються), із `TELEGRAM_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Необов’язковий `channels.telegram.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- У конфігураціях із кількома обліковими записами (2+ ID облікових записів) установіть явний типовий (`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` (працює в особистих і групових чатах). -- Політика повторних спроб: див. [Retry policy](/uk/concepts/retry). +- Попередній перегляд потоків у Telegram використовує `sendMessage` + `editMessageText` (працює в особистих і групових чатах). +- Політика повторних спроб: див. [Політика повторних спроб](/uk/concepts/retry). ### Discord @@ -331,36 +331,36 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- Токен: `channels.discord.token`, із `DISCORD_BOT_TOKEN` як запасним варіантом для типового акаунта. -- Прямі вихідні виклики, які передають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик акаунта все одно беруться з вибраного акаунта в активному знімку runtime. -- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. -- Використовуйте `user:` (DM) або `channel:` (канал guild) як цілі доставки; прості числові ID відхиляються. -- Slug-и guild мають нижній регістр, а пробіли в них замінюються на `-`; ключі каналів використовують slug-ім’я (без `#`). Віддавайте перевагу ID guild. +- Токен: `channels.discord.token`, з `DISCORD_BOT_TOKEN` як резервним варіантом для типового облікового запису. +- Прямі вихідні виклики, які передають явний Discord `token`, використовують цей токен для виклику; налаштування повторних спроб/політик облікового запису все одно беруться з вибраного облікового запису в активному знімку runtime. +- Необов’язковий `channels.discord.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Використовуйте `user:` (DM) або `channel:` (канал guild) для цілей доставки; прості числові ID відхиляються. +- Slug-и guild — у нижньому регістрі із заміною пробілів на `-`; ключі каналів використовують slug-ім’я (без `#`). Надавайте перевагу ID 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` і прив’язана доставка/маршрутизація) - - `idleHours`: перевизначення Discord для автоматичного зняття фокусу через неактивність у годинах (`0` вимикає) +- `channels.discord.guilds..ignoreOtherMentions` (і перевизначення на рівні каналу) відкидає повідомлення, які згадують іншого користувача або роль, але не бота (за винятком @everyone/@here). +- `maxLinesPerMessage` (типово 17) розбиває високі повідомлення, навіть якщо вони не перевищують 2000 символів. +- `channels.discord.threadBindings` керує маршрутизацією, прив’язаною до Discord thread: + - `enabled`: перевизначення Discord для функцій сеансів, прив’язаних до thread (`/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. -- `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 із присутністю бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. + - `spawnSubagentSessions`: перемикач opt-in для автоматичного створення/прив’язки thread через `sessions_spawn({ thread: true })` +- Записи верхнього рівня `bindings[]` з `type: "acp"` налаштовують постійні прив’язки ACP для каналів і thread (використовуйте id каналу/thread у `match.peer.id`). Семантика полів спільна з [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). +- `channels.discord.ui.components.accentColor` встановлює колір акценту для контейнерів Discord components 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 зі статусом присутності бота (healthy => online, degraded => idle, exhausted => dnd) і дозволяє необов’язкові перевизначення тексту статусу. - `channels.discord.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваними іменами/тегами (режим сумісності break-glass). -- `channels.discord.execApprovals`: доставка схвалень exec, нативна для Discord, і авторизація тих, хто може схвалювати. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто може схвалювати, можна визначити з `approvers` або `commands.ownerAllowFrom`. +- `channels.discord.execApprovals`: доставка підтверджень exec, нативна для Discord, і авторизація схвалювачів. + - `enabled`: `true`, `false` або `"auto"` (типово). В auto-режимі підтвердження exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. - `approvers`: ID користувачів Discord, яким дозволено схвалювати запити exec. Якщо не вказано, використовується `commands.ownerAllowFrom`. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо не вказувати, схвалення передаються для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово) надсилає в DM тим, хто може схвалювати, `"channel"` надсилає у вихідний канал, `"both"` надсилає в обидва місця. Коли target включає `"channel"`, кнопки можуть використовувати лише визначені approvers. - - `cleanupAfterResolve`: коли `true`, видаляє DM зі схваленням після схвалення, відхилення або тайм-ауту. + - `agentFilter`: необов’язковий allowlist 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 @@ -391,10 +391,10 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- JSON сервісного акаунта: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). -- Також підтримується SecretRef сервісного акаунта (`serviceAccountRef`). -- Запасні варіанти через env: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. -- Використовуйте `spaces/` або `users/` як цілі доставки. +- JSON облікового запису служби: вбудований (`serviceAccount`) або на основі файла (`serviceAccountFile`). +- Також підтримується SecretRef облікового запису служби (`serviceAccountRef`). +- Резервні змінні середовища: `GOOGLE_CHAT_SERVICE_ACCOUNT` або `GOOGLE_CHAT_SERVICE_ACCOUNT_FILE`. +- Використовуйте `spaces/` або `users/` для цілей доставки. - `channels.googlechat.dangerouslyAllowNameMatching` повторно вмикає зіставлення за змінюваним email principal (режим сумісності break-glass). ### Slack @@ -462,35 +462,35 @@ WhatsApp працює через вебканал gateway (Baileys Web). Він } ``` -- **Socket mode** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як запасний варіант env для типового акаунта). -- **HTTP mode** вимагає `botToken` плюс `signingSecret` (у корені або для окремого акаунта). -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні +- **Режим socket** вимагає і `botToken`, і `appToken` (`SLACK_BOT_TOKEN` + `SLACK_APP_TOKEN` як резервні змінні середовища для типового облікового запису). +- **HTTP mode** вимагає `botToken` плюс `signingSecret` (на корені або для кожного облікового запису окремо). +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають відкриті рядки або об’єкти SecretRef. -- Знімки акаунтів Slack показують поля джерела/статусу для кожного облікового даного, як-от - `botTokenSource`, `botTokenStatus`, `appTokenStatus`, а в HTTP mode — - `signingSecretStatus`. `configured_unavailable` означає, що акаунт +- Знімки облікових записів Slack показують поля джерела/статусу для кожного облікового запису, такі як + `botTokenSource`, `botTokenStatus`, `appTokenStatus` і, у HTTP mode, + `signingSecretStatus`. `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef, але поточний шлях команди/runtime не зміг - розв’язати значення секрету. + визначити значення секрету. - `configWrites: false` блокує записи конфігурації, ініційовані зі Slack. -- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. -- `channels.slack.streaming.mode` — канонічний ключ режиму потоку Slack. `channels.slack.streaming.nativeTransport` керує нативним потоковим транспортом Slack. Застарілі значення `streamMode`, булеві значення `streaming` і `nativeStreaming` переносяться автоматично. -- Використовуйте `user:` (DM) або `channel:` як цілі доставки. +- Необов’язковий `channels.slack.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- `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` — для окремого треду (типово) або спільно для каналу. `thread.inheritParent` копіює транскрипт батьківського каналу в нові треди. +**Ізоляція сеансів thread:** `thread.historyScope` — для кожного thread окремо (типово) або спільно для каналу. `thread.inheritParent` копіює transcript батьківського каналу в нові thread. -- Нативний потік Slack разом зі статусом треду Slack у стилі помічника «is typing...» вимагають ціль відповіді у треді. DM верхнього рівня типово залишаються поза тредом, тому вони використовують `typingReaction` або звичайну доставку замість попереднього перегляду в стилі треду. -- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки виконується відповідь, а після завершення видаляє її. Використовуйте shortcode емодзі Slack, наприклад `"hourglass_flowing_sand"`. -- `channels.slack.execApprovals`: доставка схвалень exec, нативна для Slack, і авторизація тих, хто може схвалювати. Та сама schema, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). +- Нативна потокова передача Slack плюс статус thread у стилі Slack assistant "is typing..." вимагають ціль відповіді у thread. Верхньорівневі DM типово залишаються поза thread, тому використовують `typingReaction` або звичайну доставку замість попереднього перегляду у стилі thread. +- `typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack під час виконання відповіді, а потім видаляє її після завершення. Використовуйте shortcode emoji Slack, наприклад `"hourglass_flowing_sand"`. +- `channels.slack.execApprovals`: доставка підтверджень exec, нативна для Slack, і авторизація схвалювачів. Та сама схема, що й у Discord: `enabled` (`true`/`false`/`"auto"`), `approvers` (ID користувачів Slack), `agentFilter`, `sessionFilter` і `target` (`"dm"`, `"channel"` або `"both"`). -| Група дій | Типово | Примітки | -| ----------- | ------- | ----------------------------- | -| reactions | увімкнено | Реакція + список реакцій | -| messages | увімкнено | Читання/надсилання/редагування/видалення | -| pins | увімкнено | Закріплення/відкріплення/список | -| memberInfo | увімкнено | Інформація про учасника | -| emojiList | увімкнено | Список власних емодзі | +| Група дій | Типово | Примітки | +| ------------ | -------- | ---------------------- | +| reactions | увімкнено | Реагування + список реакцій | +| messages | увімкнено | Читання/надсилання/редагування/видалення | +| pins | увімкнено | Закріпити/відкріпити/перелічити | +| memberInfo | увімкнено | Інформація про учасника | +| emojiList | увімкнено | Список користувацьких emoji | ### Mattermost @@ -524,23 +524,23 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -Режими чату: `oncall` (відповідати на @-згадку, типово), `onmessage` (на кожне повідомлення), `onchar` (на повідомлення, що починаються з префікса тригера). +Режими чату: `oncall` (відповідати на @-згадування, типово), `onmessage` (кожне повідомлення), `onchar` (повідомлення, що починаються з префікса тригера). Коли нативні команди 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/внутрішніх хостів callback Mattermost може вимагати, щоб - `ServiceSettings.AllowedUntrustedInternalConnections` включав callback host/domain. - Використовуйте значення host/domain, а не повні URL. +- Для приватних/tailnet/internal хостів зворотних викликів Mattermost може вимагати, + щоб `ServiceSettings.AllowedUntrustedInternalConnections` включав хост/домен зворотного виклику. + Використовуйте значення хоста/домену, а не повні URL. - `channels.mattermost.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з Mattermost. - `channels.mattermost.requireMention`: вимагати `@mention` перед відповіддю в каналах. -- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадкою для окремого каналу (`"*"` для типового значення). -- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. +- `channels.mattermost.groups..requireMention`: перевизначення обмеження за згадуванням для окремого каналу (`"*"` для типового значення). +- Необов’язковий `channels.mattermost.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. ### Signal @@ -561,11 +561,11 @@ Mattermost постачається як Plugin: `openclaw plugins install @open } ``` -**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (із `reactionAllowlist`). +**Режими сповіщень про реакції:** `off`, `own` (типово), `all`, `allowlist` (з `reactionAllowlist`). -- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю акаунта Signal. +- `channels.signal.account`: закріпити запуск каналу за конкретною ідентичністю облікового запису Signal. - `channels.signal.configWrites`: дозволити або заборонити записи конфігурації, ініційовані із Signal. -- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. +- Необов’язковий `channels.signal.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. ### BlueBubbles @@ -584,14 +584,14 @@ 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). +- Основні шляхи ключів, що розглядаються тут: `channels.bluebubbles`, `channels.bluebubbles.dmPolicy`. +- Необов’язковий `channels.bluebubbles.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови BlueBubbles до постійних сеансів ACP. Використовуйте handle 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 -OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потрібні ні daemon, ні порт. +OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Демон або порт не потрібні. ```json5 { @@ -615,17 +615,17 @@ OpenClaw запускає `imsg rpc` (JSON-RPC через stdio). Не потр } ``` -- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. +- Необов’язковий `channels.imessage.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. -- Потрібен Full Disk Access до бази даних Messages. -- Віддавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. -- `cliPath` може вказувати на SSH-обгортку; задайте `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. +- Потрібен Full Disk Access до БД Messages. +- Надавайте перевагу цілям `chat_id:`. Використовуйте `imsg chats --limit 20`, щоб переглянути список чатів. +- `cliPath` може вказувати на SSH-обгортку; встановіть `remoteHost` (`host` або `user@host`) для отримання вкладень через SCP. - `attachmentRoots` і `remoteAttachmentRoots` обмежують шляхи вхідних вкладень (типово: `/Users/*/Library/Messages/Attachments`). -- SCP використовує сувору перевірку ключа хоста, тому переконайтеся, що ключ хоста relay уже існує в `~/.ssh/known_hosts`. +- SCP використовує сувору перевірку host-key, тому переконайтеся, що ключ relay-хоста вже існує в `~/.ssh/known_hosts`. - `channels.imessage.configWrites`: дозволити або заборонити записи конфігурації, ініційовані з 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). +- Записи верхнього рівня `bindings[]` з `type: "acp"` можуть прив’язувати розмови iMessage до постійних сеансів ACP. Використовуйте нормалізований handle або явну ціль чату (`chat_id:*`, `chat_guid:*`, `chat_identifier:*`) у `match.peer.id`. Спільна семантика полів: [ACP Agents](/uk/tools/acp-agents#channel-specific-settings). - + ```bash #!/usr/bin/env bash @@ -636,7 +636,7 @@ exec ssh -T gateway-host imsg "$@" ### Matrix -Matrix працює на базі Plugin і налаштовується в `channels.matrix`. +Matrix працює через Plugin і налаштовується в `channels.matrix`. ```json5 { @@ -667,24 +667,24 @@ Matrix працює на базі Plugin і налаштовується в `cha ``` - Автентифікація за токеном використовує `accessToken`; автентифікація за паролем використовує `userId` + `password`. -- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S) proxy. Іменовані акаунти можуть перевизначати його через `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`: доставка схвалень exec, нативна для Matrix, і авторизація тих, хто може схвалювати. - - `enabled`: `true`, `false` або `"auto"` (типово). В автоматичному режимі схвалення exec активуються, коли тих, хто може схвалювати, можна визначити з `approvers` або `commands.ownerAllowFrom`. - - `approvers`: ID користувачів Matrix (наприклад `@owner:example.org`), яким дозволено схвалювати запити exec. - - `agentFilter`: необов’язковий allowlist ID агентів. Якщо не вказувати, схвалення передаються для всіх агентів. - - `sessionFilter`: необов’язкові шаблони ключів сесій (підрядок або regex). - - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (кімната походження) або `"both"`. - - Перевизначення для окремого акаунта: `channels.matrix.accounts..execApprovals`. -- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сесії: `per-user` (типово) ділить за маршрутизованим peer, а `per-room` ізолює кожну кімнату DM. -- Перевірки статусу Matrix і живі пошуки в каталозі використовують ту саму proxy-policy, що й runtime-трафік. +- `channels.matrix.proxy` маршрутизує HTTP-трафік Matrix через явний HTTP(S)-проксі. Іменовані облікові записи можуть перевизначати це через `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`: доставка підтверджень exec, нативна для Matrix, і авторизація схвалювачів. + - `enabled`: `true`, `false` або `"auto"` (типово). У режимі auto підтвердження exec активуються, коли схвалювачів можна визначити з `approvers` або `commands.ownerAllowFrom`. + - `approvers`: ID користувачів Matrix (наприклад, `@owner:example.org`), яким дозволено схвалювати запити exec. + - `agentFilter`: необов’язковий allowlist ID агентів. Якщо пропущено, підтвердження пересилаються для всіх агентів. + - `sessionFilter`: необов’язкові шаблони ключів сеансів (підрядок або regex). + - `target`: куди надсилати запити на схвалення. `"dm"` (типово), `"channel"` (початкова кімната) або `"both"`. + - Перевизначення на рівні облікового запису: `channels.matrix.accounts..execApprovals`. +- `channels.matrix.dm.sessionScope` керує тим, як DM Matrix групуються в сеанси: `per-user` (типово) спільний для маршрутизованого peer, тоді як `per-room` ізолює кожну DM-кімнату. +- Перевірки статусу Matrix і live directory lookups використовують ту саму політику проксі, що й runtime-трафік. - Повну конфігурацію Matrix, правила націлювання та приклади налаштування задокументовано в [Matrix](/uk/channels/matrix). ### Microsoft Teams -Microsoft Teams працює на базі Plugin і налаштовується в `channels.msteams`. +Microsoft Teams працює через Plugin і налаштовується в `channels.msteams`. ```json5 { @@ -699,12 +699,12 @@ Microsoft Teams працює на базі Plugin і налаштовуєтьс } ``` -- Основні шляхи ключів, охоплені тут: `channels.msteams`, `channels.msteams.configWrites`. -- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих команд/каналів) задокументовано в [Microsoft Teams](/uk/channels/msteams). +- Основні шляхи ключів, що розглядаються тут: `channels.msteams`, `channels.msteams.configWrites`. +- Повну конфігурацію Teams (облікові дані, webhook, політика DM/груп, перевизначення для окремих team/channel) задокументовано в [Microsoft Teams](/uk/channels/msteams). ### IRC -IRC працює на базі Plugin і налаштовується в `channels.irc`. +IRC працює через Plugin і налаштовується в `channels.irc`. ```json5 { @@ -725,13 +725,13 @@ IRC працює на базі Plugin і налаштовується в `channe } ``` -- Основні шляхи ключів, охоплені тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. -- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового акаунта, якщо він збігається з налаштованим ID акаунта. -- Повну конфігурацію каналу IRC (host/port/TLS/channels/allowlists/mention gating) задокументовано в [IRC](/uk/channels/irc). +- Основні шляхи ключів, що розглядаються тут: `channels.irc`, `channels.irc.dmPolicy`, `channels.irc.configWrites`, `channels.irc.nickserv.*`. +- Необов’язковий `channels.irc.defaultAccount` перевизначає вибір типового облікового запису, якщо він збігається з налаштованим ID облікового запису. +- Повну конфігурацію IRC-каналу (host/port/TLS/channels/allowlists/обмеження за згадуванням) задокументовано в [IRC](/uk/channels/irc). -### Кілька акаунтів (усі канали) +### Багатообліковість (усі канали) -Запускайте кілька акаунтів на канал (кожен зі своїм `accountId`): +Запускайте кілька облікових записів на канал (кожен зі своїм `accountId`): ```json5 { @@ -752,28 +752,28 @@ IRC працює на базі Plugin і налаштовується в `channe } ``` -- `default` використовується, коли `accountId` не вказано (CLI + маршрутизація). -- Токени env застосовуються лише до **типового** акаунта. -- Базові налаштування каналу застосовуються до всіх акаунтів, якщо їх не перевизначено для окремого акаунта. -- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен акаунт до іншого агента. -- Якщо ви додаєте нетиповий акаунт через `openclaw channels add` (або onboarding каналу), залишаючись у верхньорівневій конфігурації каналу для одного акаунта, OpenClaw спочатку переносить верхньорівневі значення для одного акаунта, прив’язані до акаунта, у мапу акаунтів каналу, щоб початковий акаунт продовжив працювати. Більшість каналів переміщують їх у `channels..accounts.default`; Matrix може натомість зберегти наявну відповідну іменовану/типову ціль. -- Наявні прив’язки лише для каналу (без `accountId`) і далі відповідають типовому акаунту; прив’язки на рівні акаунта залишаються необов’язковими. -- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи верхньорівневі значення для одного акаунта, прив’язані до акаунта, у перенесений акаунт, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix може натомість зберегти наявну відповідну іменовану/типову ціль. +- `default` використовується, коли `accountId` пропущено (CLI + маршрутизація). +- Токени змінних середовища застосовуються лише до **типового** облікового запису. +- Базові налаштування каналу застосовуються до всіх облікових записів, якщо не перевизначені для конкретного облікового запису. +- Використовуйте `bindings[].match.accountId`, щоб маршрутизувати кожен обліковий запис до іншого агента. +- Якщо ви додаєте нетиповий обліковий запис через `openclaw channels add` (або онбординг каналу), залишаючись у верхньорівневій конфігурації каналу для одного облікового запису, OpenClaw спочатку переносить значення верхнього рівня для одного облікового запису, прив’язані до конкретного облікового запису, у карту облікових записів каналу, щоб початковий обліковий запис продовжив працювати. Більшість каналів переносять їх у `channels..accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. +- Наявні прив’язки лише на рівні каналу (без `accountId`) продовжують відповідати типовому обліковому запису; прив’язки з областю облікового запису залишаються необов’язковими. +- `openclaw doctor --fix` також виправляє змішані форми, переміщуючи значення верхнього рівня для одного облікового запису, прив’язані до конкретного облікового запису, у підвищений обліковий запис, вибраний для цього каналу. Більшість каналів використовують `accounts.default`; Matrix натомість може зберегти наявну відповідну іменовану/типову ціль. ### Інші канали Plugin -Багато каналів Plugin налаштовуються як `channels.` і задокументовані на своїх окремих сторінках каналів (наприклад Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). +Багато каналів Plugin налаштовуються як `channels.` і задокументовані на їхніх окремих сторінках каналів (наприклад, Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat і Twitch). Див. повний індекс каналів: [Channels](/uk/channels). -### Обмеження за згадкою в групових чатах +### Обмеження за згадуванням у групових чатах -Для групових повідомлень типово **потрібна згадка** (згадка в метаданих або безпечні regex-шаблони). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat та iMessage. +Для групових повідомлень типово **потрібне згадування** (метадані згадування або безпечні regex-шаблони). Це застосовується до групових чатів WhatsApp, Telegram, Discord, Google Chat і iMessage. -**Типи згадок:** +**Типи згадувань:** -- **Згадки в метаданих**: нативні платформні @-згадки. Ігноруються в режимі self-chat WhatsApp. -- **Текстові шаблони**: безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Недійсні шаблони та небезпечні вкладені повторення ігноруються. -- Обмеження за згадкою застосовується лише тоді, коли виявлення можливе (нативні згадки або принаймні один шаблон). +- **Згадування в метаданих**: Нативні @-згадування платформи. Ігноруються в режимі чату з собою WhatsApp. +- **Текстові шаблони**: Безпечні regex-шаблони в `agents.list[].groupChat.mentionPatterns`. Некоректні шаблони та небезпечні вкладені повторення ігноруються. +- Обмеження за згадуванням застосовується лише тоді, коли виявлення можливе (нативні згадування або принаймні один шаблон). ```json5 { @@ -786,7 +786,7 @@ IRC працює на базі Plugin і налаштовується в `channe } ``` -`messages.groupChat.historyLimit` задає глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для окремого акаунта). Установіть `0`, щоб вимкнути. +`messages.groupChat.historyLimit` встановлює глобальне типове значення. Канали можуть перевизначати його через `channels..historyLimit` (або для конкретного облікового запису). Установіть `0`, щоб вимкнути. #### Ліміти історії DM @@ -803,13 +803,13 @@ IRC працює на базі Plugin і налаштовується в `channe } ``` -Порядок визначення: перевизначення для окремого DM → типове значення провайдера → без ліміту (зберігається все). +Порядок визначення: перевизначення для конкретного DM → типове значення провайдера → без обмеження (зберігається все). Підтримується: `telegram`, `whatsapp`, `discord`, `slack`, `signal`, `imessage`, `msteams`. -#### Режим self-chat +#### Режим чату з собою -Додайте власний номер до `allowFrom`, щоб увімкнути режим self-chat (ігнорує нативні @-згадки, відповідає лише на текстові шаблони): +Додайте власний номер до `allowFrom`, щоб увімкнути режим чату з собою (ігнорує нативні @-згадування, відповідає лише на текстові шаблони): ```json5 { @@ -860,37 +860,37 @@ IRC працює на базі Plugin і налаштовується в `channe - Цей блок налаштовує поверхні команд. Для поточного вбудованого + bundled каталогу команд див. [Slash Commands](/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 та в [Slash Commands](/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, а також у [Slash Commands](/uk/tools/slash-commands). - Текстові команди мають бути **окремими** повідомленнями з початковим `/`. - `native: "auto"` вмикає нативні команди для Discord/Telegram, залишає Slack вимкненим. - `nativeSkills: "auto"` вмикає нативні команди Skills для Discord/Telegram, залишає Slack вимкненим. -- Перевизначення для окремого каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. -- Перевизначайте реєстрацію нативних команд Skills для окремого каналу через `channels..commands.nativeSkills`. +- Перевизначення для кожного каналу: `channels.discord.commands.native` (bool або `"auto"`). `false` очищає раніше зареєстровані команди. +- Перевизначуйте реєстрацію нативних команд Skills для кожного каналу через `channels..commands.nativeSkills`. - `channels.telegram.customCommands` додає додаткові записи меню бота Telegram. - `bash: true` вмикає `! ` для shell хоста. Потрібні `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` — це явний allowlist власника для команд/інструментів лише для власника. Він окремий від `allowFrom`. -- `ownerDisplay: "hash"` хешує ID власника в системному промпті. Задайте `ownerDisplaySecret`, щоб керувати хешуванням. -- `allowFrom` задається для кожного провайдера. Якщо його встановлено, це **єдине** джерело авторизації (allowlist/pairing каналу і `useAccessGroups` ігноруються). -- `useAccessGroups: false` дозволяє командам обходити політики access-group, коли `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 власників у системному prompt. Установіть `ownerDisplaySecret`, щоб керувати хешуванням. +- `allowFrom` — для кожного провайдера окремо. Якщо встановлено, це **єдине** джерело авторизації (списки дозволів/сполучення каналу і `useAccessGroups` ігноруються). +- `useAccessGroups: false` дозволяє командам обходити політики груп доступу, коли `allowFrom` не встановлено. - Карта документації команд: - вбудований + bundled каталог: [Slash Commands](/uk/tools/slash-commands) - - поверхні команд, специфічні для каналу: [Channels](/uk/channels) + - поверхні команд, специфічні для каналів: [Channels](/uk/channels) - команди QQ Bot: [QQ Bot](/uk/channels/qqbot) - - команди pairing: [Pairing](/uk/channels/pairing) + - команди сполучення: [Pairing](/uk/channels/pairing) - команда картки LINE: [LINE](/uk/channels/line) - - dreaming пам’яті: [Dreaming](/uk/concepts/dreaming) + - memory dreaming: [Dreaming](/uk/concepts/dreaming) --- -## Типові значення агента +## Значення за замовчуванням для агентів ### `agents.defaults.workspace` @@ -904,7 +904,7 @@ IRC працює на базі Plugin і налаштовується в `channe ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного промпта. Якщо не задано, OpenClaw автоматично виявляє його, рухаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який відображається в рядку Runtime системного prompt. Якщо не встановлено, OpenClaw автоматично визначає його, піднімаючись вгору від workspace. ```json5 { @@ -922,23 +922,23 @@ IRC працює на базі Plugin і налаштовується в `channe agents: { defaults: { skills: ["github", "weather"] }, list: [ - { id: "writer" }, // inherits github, weather - { id: "docs", skills: ["docs-search"] }, // replaces defaults - { id: "locked-down", skills: [] }, // no skills + { id: "writer" }, // успадковує github, weather + { id: "docs", skills: ["docs-search"] }, // замінює типові значення + { id: "locked-down", skills: [] }, // без Skills ], }, } ``` -- Не вказуйте `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` -Вимикає автоматичне створення bootstrap-файлів робочого простору (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). +Вимикає автоматичне створення bootstrap-файлів workspace (`AGENTS.md`, `SOUL.md`, `TOOLS.md`, `IDENTITY.md`, `USER.md`, `HEARTBEAT.md`, `BOOTSTRAP.md`). ```json5 { @@ -948,9 +948,9 @@ IRC працює на базі Plugin і налаштовується в `channe ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору додаються до системного промпта. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли workspace вставляються в системний prompt. Типове значення: `"always"`. -- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне додавання bootstrap робочого простору, зменшуючи розмір промпта. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. +- `"continuation-skip"`: безпечні continuation-ходи (після завершеної відповіді асистента) пропускають повторну вставку bootstrap workspace, зменшуючи розмір prompt. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. ```json5 { @@ -960,7 +960,7 @@ IRC працює на базі Plugin і налаштовується в `channe ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів на один bootstrap-файл робочого простору перед обрізанням. Типове значення: `12000`. +Максимальна кількість символів на bootstrap-файл workspace до обрізання. Типове значення: `12000`. ```json5 { @@ -970,7 +970,7 @@ IRC працює на базі Plugin і налаштовується в `channe ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів workspace. Типове значення: `60000`. ```json5 { @@ -980,12 +980,12 @@ IRC працює на базі Plugin і налаштовується в `channe ### `agents.defaults.bootstrapPromptTruncationWarning` -Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізається. +Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. Типове значення: `"once"`. -- `"off"`: ніколи не додавати текст попередження в системний промпт. -- `"once"`: додавати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). -- `"always"`: додавати попередження під час кожного запуску, коли є обрізання. +- `"off"`: ніколи не вставляти текст попередження в системний prompt. +- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного варіанта обрізання (рекомендовано). +- `"always"`: вставляти попередження під час кожного запуску, коли існує обрізання. ```json5 { @@ -993,26 +993,26 @@ IRC працює на базі Plugin і налаштовується в `channe } ``` -### Карта володіння бюджетом контексту +### Карта відповідальності за бюджет контексту -OpenClaw має кілька великих бюджетів промпта/контексту, і вони -навмисно розділені за підсистемами, замість того щоб усі проходили через один загальний -параметр. +OpenClaw має кілька великих бюджетів prompt/контексту, і вони +навмисно розділені за підсистемами, а не проходять через один загальний +перемикач. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне додавання bootstrap робочого простору. + звичайна вставка bootstrap workspace. - `agents.defaults.startupContext.*`: - одноразовий стартовий пролог для `/new` і `/reset`, зокрема нещодавні щоденні - файли `memory/*.md`. + одноразовий стартовий пролог для `/new` і `/reset`, включно з нещодавніми щоденними + файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, що додається до системного промпта. + компактний список Skills, що вставляється в системний prompt. - `agents.defaults.contextLimits.*`: - обмежені runtime-витяги та додані блоки, якими володіє runtime. + обмежені runtime-уривки та вставлені блоки, що належать runtime. - `memory.qmd.limits.*`: - розмір фрагментів пошуку в індексованій пам’яті та їх додавання. + розмір фрагментів і вставок для індексованого пошуку в пам’яті. -Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший +Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший бюджет: - `agents.list[].skillsLimits.maxSkillsPromptChars` @@ -1020,7 +1020,7 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `agents.defaults.startupContext` -Керує стартовим прологом першого ходу, який додається під час «голих» запусків `/new` і `/reset`. +Керує стартовим прологом першого ходу, який вставляється в базові запуски `/new` і `/reset`. ```json5 { @@ -1058,18 +1058,18 @@ OpenClaw має кілька великих бюджетів промпта/ко } ``` -- `memoryGetMaxChars`: типове обмеження витягу `memory_get` перед додаванням метаданих - про обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines` - не вказано. +- `memoryGetMaxChars`: типове обмеження уривка `memory_get` перед додаванням + метаданих обрізання і повідомлення про продовження. +- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` + пропущено. - `toolResultMaxChars`: актуальне обмеження результату інструмента, яке використовується для збережених результатів і - відновлення переповнення. -- `postCompactionMaxChars`: обмеження витягу AGENTS.md, яке використовується під час додавання + відновлення після переповнення. +- `postCompactionMaxChars`: обмеження уривка AGENTS.md, що використовується під час вставки оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Не вказані поля успадковуються +Перевизначення для конкретного агента для спільних перемикачів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -1096,7 +1096,7 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, що додається до системного промпта. Це +Глобальне обмеження для компактного списку Skills, що вставляється в системний prompt. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -1111,7 +1111,7 @@ OpenClaw має кілька великих бюджетів промпта/ко #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету промпта Skills. +Перевизначення бюджету prompt для Skills для конкретного агента. ```json5 { @@ -1130,10 +1130,10 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для найдовшої сторони зображення в блоках зображень транскрипта/інструмента перед викликами провайдера. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. Типове значення: `1200`. -Нижчі значення зазвичай зменшують використання vision-token і розмір payload запиту для запусків із великою кількістю знімків екрана. +Нижчі значення зазвичай зменшують використання vision-token і розмір корисного навантаження запиту в запусках із великою кількістю скриншотів. Вищі значення зберігають більше візуальних деталей. ```json5 @@ -1144,7 +1144,7 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного промпта (не для часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного prompt (не для міток часу повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -1154,7 +1154,7 @@ OpenClaw має кілька великих бюджетів промпта/ко ### `agents.defaults.timeFormat` -Формат часу в системному промпті. Типове значення: `auto` (налаштування ОС). +Формат часу в системному prompt. Типове значення: `auto` (налаштування ОС). ```json5 { @@ -1213,48 +1213,48 @@ OpenClaw має кілька великих бюджетів промпта/ко - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядкований список моделей для failover. + - Форма об’єкта задає основну модель плюс впорядковані failover-моделі. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як його конфігурація vision-model. - - Також використовується як запасна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. + - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. + - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. + - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею tool/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера (наприклад `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` для `openai/*`, `FAL_KEY` для `fal/*`). - - Якщо не вказано, `image_generate` все одно може визначити типове значення провайдера з підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). + - Якщо пропущено, `image_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо не вказано, `music_generate` все одно може визначити типове значення провайдера з підтримкою автентифікації. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. + - Якщо пропущено, `music_generate` все одно може визначити типове значення провайдера з автентифікацією. Спочатку він пробує поточного типового провайдера, потім решту зареєстрованих провайдерів генерації музики у порядку provider-id. + - Якщо ви напряму вибираєте provider/model, також налаштуйте відповідну автентифікацію/API key провайдера. - `videoGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації відео та вбудованим інструментом `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-id. - - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію/API-ключ провайдера. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри на рівні провайдера `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 }`). - Використовується інструментом `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.4` для доступу за API-ключем або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви не вкажете провайдера, OpenClaw спочатку пробує alias, потім унікальний збіг налаштованого провайдера для цього точного ID моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому віддавайте перевагу явному `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого провайдера/моделі замість того, щоб показувати застаріле типове значення від видаленого провайдера. + - Якщо пропущено, інструмент 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.4` для доступу через API key або `openai-codex/gpt-5.5` для Codex OAuth). Якщо пропустити провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг точного model id серед налаштованих провайдерів, і лише потім повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тому краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw повертається до першого налаштованого provider/model замість того, щоб показувати застаріле типове значення від видаленого провайдера. - `models`: налаштований каталог моделей і allowlist для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`). - - Безпечні редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи allowlist, якщо ви не передасте `--replace`. - - Потоки configure/onboarding на рівні провайдера об’єднують вибрані моделі провайдера в цю мапу й зберігають не пов’язаних із ними провайдерів, уже налаштованих. -- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад `{ cacheRetention: "long" }`). -- Пріоритет об’єднання `params` (конфігурація): `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. -- Записувачі конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди add/remove для fallback), зберігають канонічну форму об’єкта й за можливості зберігають наявні списки fallback. -- `maxConcurrent`: максимальна кількість паралельних запусків агента між сесіями (кожна сесія все одно серіалізується). Типове значення: 4. + - Безпечні редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляється від замін, які видалили б наявні записи allowlist, якщо не передано `--replace`. + - Потоки configure/onboarding з областю провайдера зливають вибрані моделі провайдера в цю мапу й зберігають уже налаштованих не пов’язаних провайдерів. +- `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). +- Пріоритет злиття `params` (конфігурація): `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. +- Засоби запису конфігурації, що змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення fallback), зберігають канонічну форму об’єкта та за можливості зберігають наявні списки fallback. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сеансах (кожен сеанс усе одно серіалізований). Типово: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте це, коли довірений Plugin надає нативний harness, наприклад bundled +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований harness app-server Codex. ```json5 @@ -1271,14 +1271,14 @@ 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: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. -- Вибір harness закріплюється за кожним ID сесії після першого вбудованого запуску. Зміни конфігурації/env впливають на нові або скинуті сесії, але не на наявний транскрипт. Застарілі сесії з історією транскрипта, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує не-PI ID harness, наприклад `codex`, поруч із `Fast`. -- Це керує лише вбудованим chat harness. Генерація медіа, vision, PDF, музика, відео й TTS усе ще використовують свої налаштування provider/model. +- `runtime`: `"auto"`, `"pi"` або id зареєстрованого harness Plugin. Вбудований 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: "openai/gpt-5.5"`, `embeddedHarness.runtime: "codex"` і `embeddedHarness.fallback: "none"`. +- Вибір harness закріплюється за кожним id сеансу після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сеанси, а не на наявний transcript. Застарілі сеанси з історією transcript, але без записаного закріплення, вважаються закріпленими за PI. `/status` показує id harness, відмінні від PI, наприклад `codex`, поруч із `Fast`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої налаштування provider/model. -**Вбудовані скорочені alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочення alias** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): | Alias | Модель | | ------------------- | -------------------------------------------------- | @@ -1293,13 +1293,13 @@ harness app-server Codex. Ваші налаштовані alias завжди мають пріоритет над типовими. -Моделі Z.AI GLM-4.x автоматично вмикають режим thinking, якщо ви не задасте `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.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 типово використовується `adaptive` thinking, коли явний рівень thinking не задано. +Моделі Anthropic Claude 4.6 типово використовують `adaptive` thinking, коли не задано явного рівня thinking. ### `agents.defaults.cliBackends` -Необов’язкові CLI-backend-и для запасних запусків лише з текстом (без викликів інструментів). Корисно як резерв, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. ```json5 { @@ -1327,13 +1327,13 @@ harness app-server Codex. } ``` -- CLI-backend-и орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сесії підтримуються, коли задано `sessionArg`. +- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. +- Сеанси підтримуються, коли задано `sessionArg`. - Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінити весь системний промпт, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із промптами. +Замінює весь системний prompt, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із prompt. ```json5 { @@ -1347,7 +1347,7 @@ harness app-server Codex. ### `agents.defaults.promptOverlays` -Незалежні від провайдера prompt overlay, що застосовуються за сімейством моделей. ID моделей сімейства GPT-5 отримують спільний поведінковий контракт у різних провайдерів; `personality` керує лише дружнім шаром стилю взаємодії. +Незалежні від провайдера накладки prompt, що застосовуються за сімейством моделей. ID моделей сімейства GPT-5 отримують спільний контракт поведінки в усіх провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -1363,9 +1363,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` @@ -1396,15 +1396,15 @@ harness app-server Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація за API-ключем) або `1h` (OAuth-автентифікація). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли false, прибирає секцію Heartbeat із системного промпта й пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли true, пригнічує payload попереджень про помилки інструментів під час запусків Heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента Heartbeat, після чого його буде перервано. Якщо не вказано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика прямої/DM-доставки. `allow` (типово) дозволяє доставку на пряму ціль. `block` пригнічує доставку на пряму ціль і видає `reason=dm-blocked`. -- `lightContext`: коли true, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: коли true, кожен Heartbeat запускається в новій сесії без попередньої історії розмов. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Коли будь-який агент визначає `heartbeat`, Heartbeat запускаються **лише для цих агентів**. -- Heartbeat запускає повні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API key) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо false, прибирає секцію Heartbeat із системного prompt і пропускає вставку `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` @@ -1434,19 +1434,19 @@ harness app-server Codex. } ``` -- `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 для збереження довготривалих спогадів. Пропускається, коли робочий простір доступний лише для читання. +- `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` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. ```json5 { @@ -1471,24 +1471,24 @@ harness app-server Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко підрізає завеликі результати інструментів, а потім, за потреби, жорстко очищує старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. -**М’яке обрізання** зберігає початок + кінець і вставляє `...` посередині. +**М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Жорстке очищення** замінює весь результат інструмента на placeholder. +**Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються/не очищуються. -- Співвідношення базуються на кількості символів (приблизно), а не на точних підрахунках токенів. +- Блоки зображень ніколи не обрізаються й не очищаються. +- Співвідношення базуються на символах (приблизно), а не на точній кількості токенів. - Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. -Докладніше про поведінку див. у [Session Pruning](/uk/concepts/session-pruning). +Подробиці поведінки див. у [Session Pruning](/uk/concepts/session-pruning). -### Блокове потокове передавання +### Блокова потокова передача ```json5 { @@ -1504,11 +1504,11 @@ harness app-server Codex. } ``` -- Для каналів, відмінних від Telegram, потрібно явно вказати `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих акаунтів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. +- Канали, крім Telegram, вимагають явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. +- Перевизначення для каналу: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку та розбиття на частини див. у [Streaming](/uk/concepts/streaming). +Подробиці поведінки й розбиття на частини див. у [Streaming](/uk/concepts/streaming). ### Індикатори набору тексту @@ -1523,8 +1523,8 @@ harness app-server Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для окремої сесії: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадування. +- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. Див. [Typing Indicators](/uk/concepts/typing-indicators). @@ -1532,7 +1532,7 @@ harness app-server Codex. ### `agents.defaults.sandbox` -Необов’язковий sandboxing для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язковий sandbox для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). ```json5 { @@ -1627,52 +1627,52 @@ harness app-server Codex. } ``` - + -**Backend:** +**Бекенд:** - `docker`: локальний runtime Docker (типово) -- `ssh`: універсальний віддалений runtime на базі SSH +- `ssh`: загальний віддалений runtime на основі SSH - `openshell`: runtime OpenShell -Коли вибрано `backend: "openshell"`, специфічні для runtime параметри переміщуються в +Коли вибрано `backend: "openshell"`, налаштування, специфічні для runtime, переносяться до `plugins.entries.openshell.config`. -**Конфігурація backend SSH:** +**Конфігурація SSH-бекенда:** -- `target`: SSH-ціль у формі `user@host[:port]` +- `target`: SSH-ціль у форматі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, який використовується для робочих просторів за scope -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються в OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час runtime -- `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для workspace за областями +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час runtime +- `strictHostKeyChecking` / `updateHostKeys`: перемикачі політики host-key OpenSSH **Пріоритет автентифікації SSH:** - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data` на базі SecretRef визначаються з активного знімка runtime секретів до початку сесії sandbox +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів перед початком сеансу sandbox -**Поведінка backend SSH:** +**Поведінка SSH-бекенда:** -- один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім зберігає віддалений SSH-робочий простір як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH +- один раз ініціалізує віддалений workspace після створення або перевідтворення +- далі підтримує віддалений SSH-workspace як канонічний +- маршрутизує `exec`, файлові інструменти та медіашляхи через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує браузерні контейнери sandbox +- не підтримує контейнери браузера sandbox -**Доступ до робочого простору:** +**Доступ до workspace:** -- `none`: робочий простір sandbox за scope у `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` -- `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` +- `none`: sandbox-workspace за областю в `~/.openclaw/sandboxes` +- `ro`: sandbox-workspace в `/workspace`, workspace агента монтується лише для читання в `/agent` +- `rw`: workspace агента монтується для читання/запису в `/workspace` -**Scope:** +**Область:** -- `session`: окремий контейнер + робочий простір для кожної сесії -- `agent`: один контейнер + робочий простір на агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) +- `session`: окремий контейнер + workspace для кожного сеансу +- `agent`: один контейнер + workspace на агента (типово) +- `shared`: спільний контейнер і workspace (без ізоляції між сеансами) **Конфігурація Plugin OpenShell:** @@ -1702,30 +1702,30 @@ harness app-server Codex. **Режим OpenShell:** -- `mirror`: ініціалізувати віддалене середовище з локального перед exec, синхронізувати назад після exec; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізувати віддалене середовище, коли sandbox створюється, а потім зберігати віддалений робочий простір канонічним +- `mirror`: перед `exec` засіває віддалений простір із локального, після `exec` синхронізує назад; локальний workspace залишається канонічним +- `remote`: один раз засіває віддалений простір під час створення sandbox, після чого канонічним залишається віддалений workspace -У режимі `remote` зміни на хості, зроблені локально поза OpenClaw, не синхронізуються в sandbox автоматично після кроку початкової ініціалізації. +У режимі `remote` редагування на локальному хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу засівання. Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією mirror. -**`setupCommand`** запускається один раз після створення контейнера (через `sh -lc`). Потрібні вихід у мережу, доступний для запису корінь і користувач root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, кореня з можливістю запису та користувача root. -**Для контейнерів типово встановлено `network: "none"`** — задайте `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` також типово заблоковано, якщо ви явно не встановите +**Контейнери типово використовують `network: "none"`** — установіть `"bridge"` (або користувацьку bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (режим break-glass). -**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** тимчасово розміщуються в `media/inbound/*` активного workspace. -**`docker.binds`** монтує додаткові директорії хоста; глобальні та для окремого агента `binds` об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні та для окремого агента `binds` об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC додається в системний промпт. Не вимагає `browser.enabled` в `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, а OpenClaw видає короткоживучий URL із токеном (замість відкриття пароля в спільному URL). +**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний prompt. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача noVNC типово використовує VNC-автентифікацію, а OpenClaw видає короткоживучий URL із токеном (замість розкриття пароля у спільному URL). -- `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` і налаштовано для хостів із контейнерами: +- `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` @@ -1744,26 +1744,26 @@ harness app-server Codex. - `--metrics-recording-only` - `--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` повторно вмикає розширення, якщо ваш workflow залежить від них. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення — це базова конфігурація образу контейнера; використовуйте власний образ браузера з власним + - Типові значення є базовими для образу контейнера; використовуйте користувацький образ браузера з користувацьким entrypoint, щоб змінити типові значення контейнера. -Browser sandboxing і `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера в sandbox і `sandbox.docker.binds` доступні лише для Docker. -Зібрати образи: +Збирання образів: ```bash -scripts/sandbox-setup.sh # main sandbox image -scripts/sandbox-browser-setup.sh # optional browser image +scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) @@ -1816,26 +1816,26 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - `id`: стабільний id агента (обов’язково). -- `default`: коли встановлено кілька, перемагає перший (записується попередження). Якщо не встановлено жодного, типовим є перший запис у списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні fallback). Cron jobs, які перевизначають лише `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, тоді як інші агенти зберігатимуть типовий запасний перехід до PI. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. -- `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. +- `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. +- `identity.avatar`: шлях відносно workspace, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. -- `subagents.allowAgents`: allowlist ID агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли true, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: false). +- `subagents.allowAgents`: allowlist id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування sandbox: якщо сеанс-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: якщо true, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує явний вибір профілю; типово: false). --- -## Маршрутизація кількох агентів +## Маршрутизація між кількома агентами -Запускайте кількох ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1852,27 +1852,27 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -### Поля відповідності binding +### Поля зіставлення прив’язок -- `type` (необов’язково): `route` для звичайної маршрутизації (відсутній type типово означає route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який акаунт; не вказано = типовий акаунт) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) - `match.guildId` / `match.teamId` (необов’язково; специфічно для каналу) - `acp` (необов’язково; лише для записів `type: "acp"`): `{ mode, label, cwd, backend }` -**Детермінований порядок відповідності:** +**Детермінований порядок зіставлення:** 1. `match.peer` 2. `match.guildId` 3. `match.teamId` -4. `match.accountId` (точний, без peer/guild/team) +4. `match.accountId` (точний збіг, без peer/guild/team) 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-прив’язок. ### Профілі доступу для окремих агентів @@ -1894,7 +1894,7 @@ scripts/sandbox-browser-setup.sh # optional browser image - + ```json5 { @@ -1969,11 +1969,11 @@ scripts/sandbox-browser-setup.sh # optional browser image -Докладніше про пріоритети див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). +Подробиці щодо пріоритетів див. у [Multi-Agent Sandbox & Tools](/uk/tools/multi-agent-sandbox-tools). --- -## Сесія +## Сеанс ```json5 { @@ -2020,36 +2020,36 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` - + -- **`scope`**: базова стратегія групування сесій для контекстів групового чату. - - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`scope`**: базова стратегія групування сеансів для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли задумано спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM використовують спільну основну сесію. - - `per-peer`: ізоляція за ID відправника між каналами. - - `per-channel-peer`: ізоляція для кожного каналу + відправника (рекомендовано для скриньок вхідних повідомлень із кількома користувачами). - - `per-account-channel-peer`: ізоляція для кожного акаунта + каналу + відправника (рекомендовано для кількох акаунтів). -- **`identityLinks`**: мапа канонічних ID до peer із префіксом провайдера для спільного використання сесій між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Коли налаштовано обидва варіанти, спрацьовує той, що закінчується першим. + - `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`. Перше deny перемагає. -- **`maintenance`**: елементи керування очищенням + збереженням session-store. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг віку для застарілих записів (типово `30d`). +- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківському сеансі, дозволена під час створення розгалуженого сеансу thread (типово `100000`). + - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс thread замість успадкування історії transcript батьківського сеансу. + - Установіть `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`**: глобальні типові значення для функцій сесій, прив’язаних до тредів. + - `rotateBytes`: ротує `sessions.json`, коли він перевищує цей розмір (типово `10mb`). + - `resetArchiveRetention`: термін збереження архівів transcript `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий жорсткий бюджет дискового простору для каталогу сеансів. У режимі `warn` реєструє попередження; у режимі `enforce` спочатку видаляє найстаріші артефакти/сеанси. + - `highWaterBytes`: необов’язкова ціль після очищення бюджету. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для функцій сеансів, прив’язаних до thread. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокусу через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) - `maxAgeHours`: типовий жорсткий максимальний вік у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -2088,36 +2088,36 @@ scripts/sandbox-browser-setup.sh # optional browser image ### Префікс відповіді -Перевизначення для окремого каналу/акаунта: `channels..responsePrefix`, `channels..accounts..responsePrefix`. +Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення (найспецифічніше перемагає): акаунт → канал → глобальне значення. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Порядок визначення (перемагає найбільш специфічний): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` формує `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ------------------------ | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | -| `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{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}` — alias для `{thinkingLevel}`. -### Реакція ack +### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. -- Перевизначення для окремого каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: акаунт → канал → `messages.ackReaction` → запасний варіант з identity. -- Scope: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє ack після відповіді у Slack, Discord і Telegram. -- `messages.statusReactions.enabled`: вмикає статусні реакції життєвого циклу у Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, статусні реакції залишаються ввімкненими, коли активні реакції ack. - У Telegram установіть це явно в `true`, щоб увімкнути статусні реакції життєвого циклу. +- Перевизначення для каналу: `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`. -### Вхідний debounce +### Inbound debounce -Групує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Об’єднує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. ### TTS (text-to-speech) @@ -2160,12 +2160,12 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `auto` керує типовим режимом auto-TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. -- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумовування. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (потрібен явний opt-in). -- API-ключі використовують запасні значення `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-сервер і послаблює валідацію моделі/голосу. +- `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово має значення `false` (opt-in). +- API key використовують резервні значення `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `openai.baseUrl` перевизначає endpoint TTS OpenAI. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. +- Коли `openai.baseUrl` вказує на endpoint, що не належить OpenAI, OpenClaw розглядає його як TTS-сервер, сумісний з OpenAI, і послаблює перевірку моделі/голосу. --- @@ -2195,13 +2195,13 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `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-ключ 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 чекає після тиші користувача, перш ніж надіслати transcript. Якщо не задано, використовується типове вікно паузи платформи (`700 ms на macOS і Android, 900 ms на iOS`). --- @@ -2211,35 +2211,35 @@ scripts/sandbox-browser-setup.sh # optional browser image `tools.profile` задає базовий allowlist перед `tools.allow`/`tools.deny`: -Локальний onboarding типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). +Локальний онбординг типово встановлює для нових локальних конфігурацій `tools.profile: "coding"`, якщо значення не задано (наявні явні профілі зберігаються). -| Профіль | Включає | -| ----------- | --------------------------------------------------------------------------------------------------------------------------------- | -| `minimal` | лише `session_status` | +| Профіль | Містить | +| ----------- | ------------------------------------------------------------------------------------------------------------------------------- | +| `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` | Без обмежень (те саме, що не задано) | +| `messaging` | `group:messaging`, `sessions_list`, `sessions_history`, `sessions_send`, `session_status` | +| `full` | Без обмежень (те саме, що й без значення) | ### Групи інструментів -| Група | Інструменти | -| ------------------ | --------------------------------------------------------------------------------------------------------------------- | -| `group:runtime` | `exec`, `process`, `code_execution` (`bash` приймається як alias для `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` | Усі вбудовані інструменти (без 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` -Глобальна політика allow/deny для інструментів (deny має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується навіть тоді, коли Docker sandbox вимкнено. +Глобальна політика дозволу/заборони інструментів (заборона має пріоритет). Нечутлива до регістру, підтримує wildcard `*`. Застосовується, навіть коли sandbox Docker вимкнено. ```json5 { @@ -2265,7 +2265,7 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.elevated` -Керує доступом elevated exec поза sandbox: +Керує підвищеним доступом до exec поза sandbox: ```json5 { @@ -2282,8 +2282,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ``` - Перевизначення для окремого агента (`agents.list[].tools.elevated`) може лише додатково обмежувати. -- `/elevated on|off|ask|full` зберігає стан для кожної сесії; inline-директиви застосовуються до одного повідомлення. -- Elevated `exec` обходить sandboxing і використовує налаштований шлях виходу (`gateway` типово, або `node`, коли ціль exec — `node`). +- `/elevated on|off|ask|full` зберігає стан для кожного сеансу; вбудовані директиви застосовуються до одного повідомлення. +- Підвищений `exec` обходить sandbox і використовує налаштований шлях виходу (`gateway` типово або `node`, коли ціллю exec є `node`). ### `tools.exec` @@ -2307,8 +2307,8 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.loopDetection` -Перевірки безпеки для циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. -Параметри можна задавати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. +Перевірки безпеки циклів інструментів **типово вимкнені**. Установіть `enabled: true`, щоб увімкнути виявлення. +Налаштування можна визначати глобально в `tools.loopDetection` і перевизначати для окремого агента в `agents.list[].tools.loopDetection`. ```json5 { @@ -2332,10 +2332,10 @@ scripts/sandbox-browser-setup.sh # optional browser image - `historySize`: максимальна історія викликів інструментів, що зберігається для аналізу циклів. - `warningThreshold`: поріг повторюваного шаблону без прогресу для попереджень. - `criticalThreshold`: вищий поріг повторення для блокування критичних циклів. -- `globalCircuitBreakerThreshold`: жорсткий поріг зупинки для будь-якого запуску без прогресу. +- `globalCircuitBreakerThreshold`: поріг жорсткої зупинки для будь-якого запуску без прогресу. - `detectors.genericRepeat`: попереджати про повторні виклики того самого інструмента з тими самими аргументами. -- `detectors.knownPollNoProgress`: попереджати/блокувати відомі інструменти poll (`process.poll`, `command_status` тощо). -- `detectors.pingPong`: попереджати/блокувати чергування парних шаблонів без прогресу. +- `detectors.knownPollNoProgress`: попереджати/блокувати відомі poll-інструменти (`process.poll`, `command_status` тощо). +- `detectors.pingPong`: попереджати/блокувати чергування пар шаблонів без прогресу. - Якщо `warningThreshold >= criticalThreshold` або `criticalThreshold >= globalCircuitBreakerThreshold`, валідація завершується помилкою. ### `tools.web` @@ -2404,11 +2404,11 @@ scripts/sandbox-browser-setup.sh # optional browser image -**Запис провайдера** (`type: "provider"` або не вказано): +**Запис провайдера** (`type: "provider"` або пропущено): -- `provider`: ID API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) -- `model`: перевизначення ID моделі -- `profile` / `preferredProfile`: вибір профілю з `auth-profiles.json` +- `provider`: id API-провайдера (`openai`, `anthropic`, `google`/`gemini`, `groq` тощо) +- `model`: перевизначення id моделі +- `profile` / `preferredProfile`: вибір профілю `auth-profiles.json` **Запис CLI** (`type: "cli"`): @@ -2418,16 +2418,16 @@ scripts/sandbox-browser-setup.sh # optional browser image **Спільні поля:** - `capabilities`: необов’язковий список (`image`, `audio`, `video`). Типові значення: `openai`/`anthropic`/`minimax` → image, `google` → image+audio+video, `groq` → audio. -- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для окремого запису. -- У разі помилки використовується наступний запис. +- `prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`: перевизначення для конкретного запису. +- У разі збоїв використовується наступний запис. Автентифікація провайдера дотримується стандартного порядку: `auth-profiles.json` → змінні середовища → `models.providers.*.apiKey`. **Поля async completion:** - `asyncCompletion.directSend`: коли `true`, завершені асинхронні завдання `music_generate` - і `video_generate` спочатку намагаються доставити результат напряму в канал. Типове значення: `false` - (застарілий шлях пробудження сесії запитувача/доставки моделлю). + і `video_generate` спочатку намагаються доставити результат безпосередньо в канал. Типове значення: `false` + (застарілий шлях пробудження requester-session/model-delivery). @@ -2446,9 +2446,9 @@ scripts/sandbox-browser-setup.sh # optional browser image ### `tools.sessions` -Керує тим, на які сесії можуть націлюватися session tools (`sessions_list`, `sessions_history`, `sessions_send`). +Керує тим, на які сеанси можна націлюватися інструментами сеансів (`sessions_list`, `sessions_history`, `sessions_send`). -Типове значення: `tree` (поточна сесія + сесії, створені нею, наприклад підлеглі агенти). +Типове значення: `tree` (поточний сеанс + сеанси, породжені ним, наприклад субагенти). ```json5 { @@ -2463,15 +2463,15 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: -- `self`: лише ключ поточної сесії. -- `tree`: поточна сесія + сесії, створені поточною сесією (підлеглі агенти). -- `agent`: будь-яка сесія, що належить поточному ID агента (може включати інших користувачів, якщо ви запускаєте сесії per-sender під тим самим ID агента). -- `all`: будь-яка сесія. Націлювання між агентами все одно вимагає `tools.agentToAgent`. -- Обмеження sandbox: коли поточна сесія працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється на `tree`, навіть якщо `tools.sessions.visibility="all"`. +- `self`: лише ключ поточного сеансу. +- `tree`: поточний сеанс + сеанси, породжені поточним сеансом (субагенти). +- `agent`: будь-який сеанс, що належить поточному id агента (може включати інших користувачів, якщо ви запускаєте сеанси per-sender під тим самим id агента). +- `all`: будь-який сеанс. Націлювання між агентами все одно вимагає `tools.agentToAgent`. +- Обмеження sandbox: коли поточний сеанс працює в sandbox і `agents.defaults.sandbox.sessionToolsVisibility="spawned"`, видимість примусово встановлюється в `tree`, навіть якщо `tools.sessions.visibility="all"`. ### `tools.sessions_spawn` -Керує підтримкою inline-вкладень для `sessions_spawn`. +Керує підтримкою вбудованих вкладень для `sessions_spawn`. ```json5 { @@ -2492,17 +2492,17 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - Вкладення підтримуються лише для `runtime: "subagent"`. Runtime ACP їх відхиляє. -- Файли матеріалізуються в дочірньому робочому просторі в `.openclaw/attachments//` разом із `.manifest.json`. -- Вміст вкладень автоматично редагується під час збереження транскрипта. -- Входи base64 перевіряються суворими перевірками алфавіту/заповнення та попереднім захистом розміру до декодування. -- Права доступу до файлів: `0700` для директорій і `0600` для файлів. -- Очищення дотримується політики `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише тоді, коли `retainOnSessionKeep: true`. +- Файли матеріалізуються в дочірньому workspace у `.openclaw/attachments//` з `.manifest.json`. +- Вміст вкладень автоматично редагується в збереженні transcript. +- Входи Base64 перевіряються суворими перевірками алфавіту/доповнення та захистом розміру до декодування. +- Дозволи файлів: `0700` для каталогів і `0600` для файлів. +- Очищення виконується згідно з політикою `cleanup`: `delete` завжди видаляє вкладення; `keep` зберігає їх лише коли `retainOnSessionKeep: true`. ### `tools.experimental` -Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не застосовується правило авто-вмикання strict-agentic GPT-5. +Експериментальні прапорці вбудованих інструментів. Типово вимкнені, якщо не застосовується правило автоматичного вмикання strict-agentic GPT-5. ```json5 { @@ -2517,8 +2517,8 @@ scripts/sandbox-browser-setup.sh # optional browser image Примітки: - `planTool`: вмикає структурований інструмент `update_plan` для відстеження нетривіальної багатокрокової роботи. -- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією сферою, або `false`, щоб залишити його вимкненим навіть для запусків strict-agentic GPT-5. -- Коли інструмент увімкнено, системний промпт також додає вказівки з використання, щоб модель застосовувала його лише для суттєвої роботи й тримала щонайбільше один крок у стані `in_progress`. +- Типове значення: `false`, якщо тільки `agents.defaults.embeddedPi.executionContract` (або перевизначення для окремого агента) не встановлено в `"strict-agentic"` для запуску OpenAI або OpenAI Codex сімейства GPT-5. Установіть `true`, щоб примусово ввімкнути інструмент поза цією областю, або `false`, щоб залишити його вимкненим навіть для strict-agentic запусків GPT-5. +- Коли інструмент увімкнений, системний prompt також додає вказівки щодо використання, щоб модель застосовувала його лише для суттєвої роботи й тримала не більш як один крок у стані `in_progress`. ### `agents.defaults.subagents` @@ -2538,16 +2538,16 @@ scripts/sandbox-browser-setup.sh # optional browser image } ``` -- `model`: типова модель для створених підлеглих агентів. Якщо не вказано, підлеглі агенти успадковують модель викликача. -- `allowAgents`: типовий allowlist цільових ID агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). -- `runTimeoutSeconds`: типовий timeout (у секундах) для `sessions_spawn`, коли виклик інструмента не містить `runTimeoutSeconds`. `0` означає відсутність timeout. -- Політика інструментів для окремого підлеглого агента: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. +- `model`: типова модель для породжених субагентів. Якщо пропущено, субагенти успадковують модель викликача. +- `allowAgents`: типовий allowlist цільових id агентів для `sessions_spawn`, коли агент-запитувач не задає власний `subagents.allowAgents` (`["*"]` = будь-який; типово: лише той самий агент). +- `runTimeoutSeconds`: типовий тайм-аут (у секундах) для `sessions_spawn`, коли виклик інструмента не передає `runTimeoutSeconds`. `0` означає відсутність тайм-ауту. +- Політика інструментів для субагентів: `tools.subagents.tools.allow` / `tools.subagents.tools.deny`. --- -## Власні провайдери та base URL +## Користувацькі провайдери й base URL -OpenClaw використовує вбудований каталог моделей. Додавайте власних провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. +OpenClaw використовує вбудований каталог моделей. Додавайте користувацьких провайдерів через `models.providers` у конфігурації або `~/.openclaw/agents//agent/models.json`. ```json5 { @@ -2576,49 +2576,49 @@ OpenClaw використовує вбудований каталог модел } ``` -- Використовуйте `authHeader: true` + `headers` для власних потреб автентифікації. -- Перевизначте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). -- Пріоритет об’єднання для відповідних ID провайдера: - - Непорожні значення `baseUrl` у `models.json` агента мають пріоритет. +- Використовуйте `authHeader: true` + `headers` для користувацьких потреб автентифікації. +- Перевизначайте корінь конфігурації агента через `OPENCLAW_AGENT_DIR` (або `PI_CODING_AGENT_DIR`, застарілий alias змінної середовища). +- Пріоритет злиття для однакових ID провайдерів: + - Непорожні значення `baseUrl` з агентського `models.json` мають пріоритет. - Непорожні значення `apiKey` агента мають пріоритет лише тоді, коли цей провайдер не керується через SecretRef у поточному контексті config/auth-profile. - - Значення `apiKey` провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`ENV_VAR_NAME` для env-ref, `secretref-managed` для file/exec ref) замість збереження розв’язаних секретів. - - Значення заголовків провайдера, якими керує SecretRef, оновлюються з маркерів джерела (`secretref-env:ENV_VAR_NAME` для env-ref, `secretref-managed` для file/exec ref). - - Порожні або відсутні `apiKey`/`baseUrl` агента використовують запасні значення з `models.providers` у конфігурації. - - Для відповідних моделей `contextWindow`/`maxTokens` використовують вище значення між явною конфігурацією та неявними значеннями каталогу. - - Для відповідних моделей `contextTokens` зберігає явне обмеження runtime, якщо воно задане; використовуйте це, щоб обмежити ефективний контекст без зміни нативних метаданих моделі. - - Використовуйте `models.mode: "replace"`, коли хочете, щоб конфігурація повністю переписала `models.json`. - - Збереження маркерів є авторитетним щодо джерела: маркери записуються з активного знімка конфігурації джерела (до розв’язання), а не з розв’язаних значень секретів runtime. + - Значення `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. -### Деталі полів провайдера +### Подробиці полів провайдера - `models.mode`: поведінка каталогу провайдерів (`merge` або `replace`). -- `models.providers`: мапа власних провайдерів з ключем за ID провайдера. - - Безпечні редагування: використовуйте `openclaw config set models.providers. '' --strict-json --merge` або `openclaw config set models.providers..models '' --strict-json --merge` для додаткових оновлень. `config set` відмовляється від руйнівних замін, якщо ви не передасте `--replace`. +- `models.providers`: мапа користувацьких провайдерів, ключована за 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`: облікові дані провайдера (краще використовувати SecretRef/підстановку env). +- `models.providers.*.apiKey`: облікові дані провайдера (краще використовувати SecretRef/підстановку через env). - `models.providers.*.auth`: стратегія автентифікації (`api-key`, `token`, `oauth`, `aws-sdk`). -- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` додає `options.num_ctx` до запитів (типово: `true`). -- `models.providers.*.authHeader`: примусово передавати облікові дані в заголовку `Authorization`, коли це потрібно. -- `models.providers.*.baseUrl`: базовий URL висхідного API. +- `models.providers.*.injectNumCtxForOpenAICompat`: для Ollama + `openai-completions` вставляє `options.num_ctx` у запити (типово: `true`). +- `models.providers.*.authHeader`: примусово передає облікові дані в заголовку `Authorization`, коли це потрібно. +- `models.providers.*.baseUrl`: базовий URL API верхнього рівня. - `models.providers.*.headers`: додаткові статичні заголовки для маршрутизації proxy/tenant. -- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів до модельного провайдера. - - `request.headers`: додаткові заголовки (об’єднуються з типовими значеннями провайдера). Значення приймають SecretRef. +- `models.providers.*.request`: перевизначення транспорту для HTTP-запитів провайдера моделей. + - `request.headers`: додаткові заголовки (зливаються з типовими значеннями провайдера). Значення приймають SecretRef. - `request.auth`: перевизначення стратегії автентифікації. Режими: `"provider-default"` (використовувати вбудовану автентифікацію провайдера), `"authorization-bearer"` (із `token`), `"header"` (із `headerName`, `value`, необов’язковим `prefix`). - - `request.proxy`: перевизначення HTTP proxy. Режими: `"env-proxy"` (використовувати змінні середовища `HTTP_PROXY`/`HTTPS_PROXY`), `"explicit-proxy"` (із `url`). Обидва режими приймають необов’язковий підоб’єкт `tls`. + - `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 провайдера (operator opt-in для довірених self-hosted endpoint OpenAI-compatible). WebSocket використовує той самий `request` для заголовків/TLS, але не цей fetch SSRF gate. Типове значення `false`. + - `request.allowPrivateNetwork`: коли `true`, дозволяє HTTPS до `baseUrl`, якщо DNS визначається в приватні, CGNAT або подібні діапазони, через захист HTTP fetch провайдера (opt-in оператора для довірених саморозгорнутих 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-compatible chat endpoint, які підтримують лише рядки. Коли `true`, OpenClaw сплющує масиви `messages[].content`, що містять лише текст, у звичайні рядки перед надсиланням запиту. +- `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.defaultMaxTokens`: запасна максимальна кількість вихідних токенів для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultContextWindow`: резервне контекстне вікно для виявлених моделей. +- `plugins.entries.amazon-bedrock.config.discovery.defaultMaxTokens`: резервна максимальна кількість вихідних токенів для виявлених моделей. ### Приклади провайдерів @@ -2656,7 +2656,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` — для прямого доступу до Z.AI. +Використовуйте `cerebras/zai-glm-4.7` для Cerebras; `zai/glm-4.7` для прямого Z.AI. @@ -2673,7 +2673,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Установіть `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`). Використовуйте refs `opencode/...` для каталогу Zen або refs `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`. @@ -2693,8 +2693,8 @@ OpenClaw використовує вбудований каталог модел Установіть `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 визначте власного провайдера з перевизначенням base URL. +- Endpoint для кодування (типово): `https://api.z.ai/api/coding/paas/v4` +- Для загального endpoint визначте користувацького провайдера з перевизначенням base URL. @@ -2735,9 +2735,9 @@ OpenClaw використовує вбудований каталог модел Для endpoint у Китаї: `baseUrl: "https://api.moonshot.cn/v1"` або `openclaw onboard --auth-choice moonshot-api-key-cn`. -Нативні endpoint Moonshot оголошують сумісність використання потокової передачі на спільному -транспорті `openai-completions`, і OpenClaw орієнтується на можливості endpoint, -а не лише на вбудований ID провайдера. +Нативні endpoint Moonshot повідомляють про сумісність використання потокової передачі на спільному +транспорті `openai-completions`, і OpenClaw прив’язує це до можливостей endpoint, +а не лише до вбудованого id провайдера. @@ -2755,7 +2755,7 @@ OpenClaw використовує вбудований каталог модел } ``` -Anthropic-compatible, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. +Сумісний з Anthropic, вбудований провайдер. Скорочення: `openclaw onboard --auth-choice kimi-code-api-key`. @@ -2794,7 +2794,7 @@ Anthropic-compatible, вбудований провайдер. Скорочен } ``` -Base URL має не містити `/v1` (клієнт Anthropic додає його сам). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. +Base URL має не містити `/v1` (клієнт Anthropic додає його). Скорочення: `openclaw onboard --auth-choice synthetic-api-key`. @@ -2839,7 +2839,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й `openclaw onboard --auth-choice minimax-cn-api`. Каталог моделей типово містить лише M2.7. На Anthropic-compatible шляху потокової передачі OpenClaw типово вимикає thinking MiniMax, -якщо ви явно не задасте `thinking` самі. `/fast on` або +якщо ви явно не задасте `thinking` самостійно. `/fast on` або `params.fastMode: true` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. @@ -2847,7 +2847,7 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й -Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; при цьому зберігайте merged хостовані моделі як fallback. +Див. [Local Models](/uk/gateway/local-models). Коротко: запускайте велику локальну модель через LM Studio Responses API на серйозному обладнанні; для резервного варіанта залишайте злитими хостовані моделі. @@ -2878,18 +2878,18 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `allowBundled`: необов’язковий allowlist лише для bundled Skills (керовані/робочі Skills не зачіпаються). +- `allowBundled`: необов’язковий allowlist лише для 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-змінну (звичайний рядок або об’єкт SecretRef). +- `entries..enabled: false` вимикає Skill, навіть якщо він bundled/встановлений. +- `entries..apiKey`: зручне поле для Skills, які оголошують основну змінну середовища (відкритий рядок або об’єкт SecretRef). --- -## Plugin +## Plugins ```json5 { @@ -2914,40 +2914,40 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - Завантажуються з `~/.openclaw/extensions`, `/.openclaw/extensions`, а також `plugins.load.paths`. -- Виявлення приймає нативні Plugin OpenClaw, а також сумісні пакети Codex і Claude, включно з пакетами Claude стандартного компонування без manifest. -- **Зміни конфігурації вимагають перезапуску gateway.** -- `allow`: необов’язковий allowlist (завантажуються лише перелічені Plugin). `deny` має пріоритет. -- `plugins.entries..apiKey`: зручне поле API-ключа на рівні Plugin (коли Plugin це підтримує). -- `plugins.entries..env`: мапа env-змінних для окремого Plugin. -- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` та ігнорує поля, що змінюють промпт, із застарілого `before_agent_start`, зберігаючи при цьому застарілі `modelOverride` і `providerOverride`. Застосовується до нативних хуків Plugin і підтримуваних каталогів хуків, наданих пакетами. -- `plugins.entries..subagent.allowModelOverride`: явна довіра цьому Plugin запитувати перевизначення `provider` і `model` для окремого запуску фонових підлеглих агентів. -- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `provider/model` для довірених перевизначень підлеглих агентів. Використовуйте `"*"`, лише якщо ви свідомо хочете дозволити будь-яку модель. -- `plugins.entries..config`: об’єкт конфігурації, визначений Plugin (перевіряється schema нативного Plugin OpenClaw, коли вона доступна). -- `plugins.entries.firecrawl.config.webFetch`: налаштування провайдера Firecrawl web-fetch. - - `apiKey`: API-ключ Firecrawl (приймає SecretRef). Використовує запасне значення з `plugins.entries.firecrawl.config.webSearch.apiKey`, застарілого `tools.web.fetch.firecrawl.apiKey` або env-змінної `FIRECRAWL_API_KEY`. +- Виявлення приймає нативні Plugins OpenClaw, а також сумісні bundles Codex і Claude, включно з bundles Claude без manifest із типовим layout. +- **Зміни конфігурації потребують перезапуску gateway.** +- `allow`: необов’язковий allowlist (завантажуються лише Plugins зі списку). `deny` має пріоритет. +- `plugins.entries..apiKey`: зручне поле API key на рівні Plugin (коли це підтримує Plugin). +- `plugins.entries..env`: мапа змінних середовища в області Plugin. +- `plugins.entries..hooks.allowPromptInjection`: коли `false`, core блокує `before_prompt_build` і ігнорує поля legacy `before_agent_start`, що змінюють prompt, зберігаючи legacy `modelOverride` і `providerOverride`. Застосовується до нативних hooks Plugin і підтримуваних каталогів hooks, наданих bundle. +- `plugins.entries..subagent.allowModelOverride`: явно довіряти цьому Plugin запитувати перевизначення `provider` і `model` для окремих запусків у фонових субагентах. +- `plugins.entries..subagent.allowedModels`: необов’язковий allowlist канонічних цілей `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`, legacy `tools.web.fetch.firecrawl.apiKey` або змінну середовища `FIRECRAWL_API_KEY`. - `baseUrl`: базовий URL API Firecrawl (типово: `https://api.firecrawl.dev`). - - `onlyMainContent`: витягувати лише основний вміст зі сторінок (типово: `true`). + - `onlyMainContent`: витягувати лише основний вміст сторінок (типово: `true`). - `maxAgeMs`: максимальний вік кешу в мілісекундах (типово: `172800000` / 2 дні). - - `timeoutSeconds`: timeout запиту scrape у секундах (типово: `60`). -- `plugins.entries.xai.config.xSearch`: налаштування xAI X Search (Grok web search). + - `timeoutSeconds`: тайм-аут запиту scrape у секундах (типово: `60`). +- `plugins.entries.xai.config.xSearch`: налаштування X Search xAI (вебпошук Grok). - `enabled`: увімкнути провайдера X Search. - - `model`: модель Grok для пошуку (наприклад `"grok-4-1-fast"`). -- `plugins.entries.memory-core.config.dreaming`: налаштування memory dreaming. Див. [Dreaming](/uk/concepts/dreaming) для фаз і порогів. + - `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 * * *"`). - - політика фаз і пороги — це деталі реалізації (не ключі конфігурації для користувача). -- Повна конфігурація пам’яті міститься в [Memory configuration reference](/uk/reference/memory-config): + - `frequency`: Cron-каденс для кожного повного проходу dreaming (типово `"0 3 * * *"`). + - політика фаз і пороги — це деталі реалізації (не користувацькі ключі конфігурації). +- Повна конфігурація пам’яті знаходиться в [Memory configuration reference](/uk/reference/memory-config): - `agents.defaults.memorySearch.*` - `memory.backend` - `memory.citations` - `memory.qmd.*` - `plugins.entries.memory-core.config.dreaming` -- Увімкнені пакети Claude також можуть додавати вбудовані типові значення Pi з `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі patch конфігурації OpenClaw. -- `plugins.slots.memory`: виберіть ID активного memory Plugin або `"none"`, щоб вимкнути memory Plugin. -- `plugins.slots.contextEngine`: виберіть ID активного context engine Plugin; типово `"legacy"`, якщо ви не встановите й не виберете інший engine. -- `plugins.installs`: метадані встановлення, якими керує CLI, і які використовуються `openclaw plugins update`. - - Включає `source`, `spec`, `sourcePath`, `installPath`, `version`, `resolvedName`, `resolvedVersion`, `resolvedSpec`, `integrity`, `shasum`, `resolvedAt`, `installedAt`. - - Ставтеся до `plugins.installs.*` як до керованого стану; віддавайте перевагу командам CLI замість ручного редагування. +- Увімкнені Plugins bundle Claude також можуть додавати типові значення вбудованого Pi із `settings.json`; OpenClaw застосовує їх як санітизовані налаштування агента, а не як сирі patches конфігурації 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](/uk/tools/plugin). @@ -2990,29 +2990,29 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й ``` - `evaluateEnabled: false` вимикає `act:evaluate` і `wait --fn`. -- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому навігація browser типово залишається суворою. -- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви свідомо довіряєте навігації browser у приватній мережі. -- У строгому режимі endpoint-и віддалених CDP-профілів (`profiles.*.cdpUrl`) підпадають під те саме блокування приватної мережі під час перевірок досяжності/виявлення. -- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як застарілий alias. +- `ssrfPolicy.dangerouslyAllowPrivateNetwork` вимкнено, якщо не задано, тому browser navigation типово залишається в строгому режимі. +- Установлюйте `ssrfPolicy.dangerouslyAllowPrivateNetwork: true` лише тоді, коли ви навмисно довіряєте browser navigation у приватній мережі. +- У строгому режимі endpoint віддалених профілів CDP (`profiles.*.cdpUrl`) підлягають тому самому блокуванню приватної мережі під час перевірок доступності/виявлення. +- `ssrfPolicy.allowPrivateNetwork` і далі підтримується як legacy alias. - У строгому режимі використовуйте `ssrfPolicy.hostnameAllowlist` і `ssrfPolicy.allowedHostnames` для явних винятків. - Віддалені профілі працюють лише в режимі attach-only (start/stop/reset вимкнено). - `profiles.*.cdpUrl` приймає `http://`, `https://`, `ws://` і `wss://`. - Використовуйте HTTP(S), коли хочете, щоб OpenClaw виявив `/json/version`; використовуйте WS(S), - коли ваш провайдер дає прямий DevTools WebSocket URL. -- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть приєднуватися на - вибраному хості або через підключений browser node. -- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлюватися на конкретний + Використовуйте HTTP(S), коли хочете, щоб OpenClaw визначав `/json/version`; використовуйте WS(S), + коли ваш провайдер надає прямий DevTools WebSocket URL. +- Профілі `existing-session` використовують Chrome MCP замість CDP і можуть приєднуватися + на вибраному хості або через підключений browser Node. +- Профілі `existing-session` можуть задавати `userDataDir`, щоб націлитися на конкретний профіль браузера на основі Chromium, наприклад Brave або Edge. - Профілі `existing-session` зберігають поточні обмеження маршруту Chrome MCP: - дії на основі snapshot/ref замість націлювання через CSS-селектори, hooks для завантаження одного файла, - без перевизначень timeout для діалогів, без `wait --load networkidle`, а також без - `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. -- Для локальних керованих профілів `openclaw` `cdpPort` і `cdpUrl` призначаються автоматично; явно + дії на основі snapshot/ref замість націлювання за CSS-selector, hooks завантаження + одного файла, відсутність перевизначення тайм-аутів діалогів, відсутність `wait --load networkidle`, + а також відсутність `responsebody`, експорту PDF, перехоплення завантажень або пакетних дій. +- Локальні керовані профілі `openclaw` автоматично призначають `cdpPort` і `cdpUrl`; явно задавайте `cdpUrl` лише для віддаленого CDP. -- Порядок автовиявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. -- Control service: лише loopback (порт виводиться з `gateway.port`, типово `18791`). -- `extraArgs` додає додаткові прапорці запуску до локального старту Chromium (наприклад - `--disable-gpu`, розмір вікна або прапорці налагодження). +- Порядок автоматичного виявлення: типовий браузер, якщо він на основі Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary. +- Служба керування: лише loopback (порт визначається з `gateway.port`, типово `18791`). +- `extraArgs` додає додаткові прапорці запуску до локального запуску Chromium (наприклад + `--disable-gpu`, розміри вікна або прапорці налагодження). --- @@ -3030,8 +3030,8 @@ Base URL має не містити `/v1` (клієнт Anthropic додає й } ``` -- `seamColor`: акцентний колір для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). -- `assistant`: перевизначення ідентичності Control UI. Використовує запасне значення з ідентичності активного агента. +- `seamColor`: колір акценту для chrome нативного UI застосунку (відтінок бульбашки Talk Mode тощо). +- `assistant`: перевизначення ідентичності UI керування. Якщо не задано, використовується identity активного агента. --- @@ -3098,66 +3098,66 @@ 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` (лише 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` усередині контейнера. За мережі Docker bridge (`-p 18789:18789`) трафік приходить на `eth0`, тому gateway недоступний. Використовуйте `--network host` або встановіть `bind: "lan"` (або `bind: "custom"` з `customBindHost: "0.0.0.0"`), щоб слухати на всіх інтерфейсах. -- **Auth**: типово обов’язкова. Binds, відмінні від loopback, вимагають auth gateway. На практиці це означає спільний токен/пароль або reverse proxy з урахуванням identity із `gateway.auth.mode: "trusted-proxy"`. Wizard onboarding типово генерує токен. -- Якщо налаштовано і `gateway.auth.token`, і `gateway.auth.password` (включно з SecretRef), явно задайте `gateway.auth.mode` як `token` або `password`. Потоки startup та install/repair сервісу завершуються помилкою, коли налаштовано обидва значення, а mode не задано. -- `gateway.auth.mode: "none"`: явний режим без auth. Використовуйте лише для довірених локальних конфігурацій loopback; цей варіант навмисно не пропонується в підказках onboarding. -- `gateway.auth.mode: "trusted-proxy"`: делегувати auth reverse proxy з урахуванням identity і довіряти заголовкам identity від `gateway.trustedProxies` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує **не-loopback** джерело proxy; reverse proxy на тому самому хості через loopback не задовольняють auth trusted-proxy. -- `gateway.auth.allowTailscale`: коли `true`, заголовки identity Tailscale Serve можуть задовольняти auth для Control UI/WebSocket (перевіряється через `tailscale whois`). HTTP API endpoint-и **не** використовують цю auth заголовків Tailscale; вони дотримуються звичайного режиму HTTP auth gateway. Цей потік без токена передбачає, що хост gateway є довіреним. Типове значення `true`, коли `tailscale.mode = "serve"`. -- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб auth. Застосовується для кожного IP клієнта й для кожної області auth (спільний секрет і device-token відстежуються окремо). Заблоковані спроби повертають `429` + `Retry-After`. - - На асинхронному шляху Tailscale Serve Control UI невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому одночасні хибні спроби від того самого клієнта можуть спровокувати спрацьовування обмежувача вже на другому запиті, замість того щоб обидві пройшли як звичайні невідповідності. - - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; установіть `false`, коли навмисно хочете, щоб трафік localhost також обмежувався (для тестових конфігурацій або суворих розгортань proxy). -- Спроби auth WS із browser-origin завжди обмежуються без звільнення для loopback (додатковий захист від brute force localhost із браузера). -- На loopback ці блокування для browser-origin ізольовано для кожного нормалізованого значення `Origin`, - тому повторні збої з одного localhost origin не блокують автоматично - інший origin. -- `tailscale.mode`: `serve` (лише tailnet, bind loopback) або `funnel` (публічно, вимагає auth). -- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Обов’язковий, коли очікуються клієнти браузера з origin, відмінних від loopback. -- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, який вмикає запасний варіант origin через заголовок Host для розгортань, що навмисно покладаються на політику origin на основі заголовка Host. -- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` `remote.url` має бути `ws://` або `wss://`. -- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське перевизначення break-glass, яке дозволяє незашифрований `ws://` до довірених IP приватної мережі; типово plaintext як і раніше дозволено лише для loopback. -- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Самі по собі вони не налаштовують auth gateway. -- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL зовнішнього ретранслятора APNs, який використовується офіційними/TestFlight збірками iOS після того, як вони публікують реєстрації через ретранслятор у gateway. Цей URL має збігатися з URL ретранслятора, зібраним у збірку iOS. -- `gateway.push.apns.relay.timeoutMs`: timeout надсилання gateway-to-relay у мілісекундах. Типове значення `10000`. -- Реєстрації через ретранслятор делегуються конкретній identity gateway. Зв’язаний застосунок iOS отримує `gateway.identity.get`, включає цю identity до реєстрації ретранслятора й передає gateway грант надсилання в межах цієї реєстрації. Інший gateway не може повторно використати таку збережену реєстрацію. -- `OPENCLAW_APNS_RELAY_BASE_URL` / `OPENCLAW_APNS_RELAY_TIMEOUT_MS`: тимчасові перевизначення через env для конфігурації ретранслятора вище. -- `OPENCLAW_APNS_RELAY_ALLOW_HTTP=true`: запасний варіант лише для розробки, що дозволяє loopback HTTP URL ретранслятора. У production 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 і не розв’язано, розв’язання завершується fail-closed (без маскування через запасний remote). -- `trustedProxies`: IP reverse proxy, які завершують TLS або додають заголовки forwarded-client. Додавайте лише 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`: додаткові назви інструментів, заблоковані для HTTP `POST /tools/invoke` (розширює типовий deny list). -- `gateway.tools.allow`: прибрати назви інструментів із типового HTTP deny list. +- `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`. +- **Застарілі 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"`), щоб слухати на всіх інтерфейсах. +- **Автентифікація**: типово обов’язкова. Bind, відмінні від loopback, вимагають автентифікації gateway. На практиці це означає спільний token/password або reverse proxy з урахуванням ідентичності з `gateway.auth.mode: "trusted-proxy"`. Wizard онбордингу типово генерує 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` (див. [Trusted Proxy Auth](/uk/gateway/trusted-proxy-auth)). Цей режим очікує джерело proxy **не loopback**; same-host reverse proxy через loopback не задовольняють автентифікацію trusted-proxy. +- `gateway.auth.allowTailscale`: коли `true`, заголовки ідентичності Tailscale Serve можуть задовольняти автентифікацію UI керування/WebSocket (перевіряється через `tailscale whois`). Endpoint HTTP API **не** використовують цю автентифікацію заголовками Tailscale; натомість вони дотримуються звичайного режиму HTTP-автентифікації gateway. Цей безтокенний потік передбачає, що хост gateway є довіреним. Типово має значення `true`, коли `tailscale.mode = "serve"`. +- `gateway.auth.rateLimit`: необов’язковий обмежувач невдалих спроб автентифікації. Застосовується для кожного IP клієнта й для кожної області автентифікації окремо (спільний секрет і device-token відстежуються незалежно). Заблоковані спроби повертають `429` + `Retry-After`. + - На асинхронному шляху UI керування Tailscale Serve невдалі спроби для того самого `{scope, clientIp}` серіалізуються перед записом збою. Тому одночасні хибні спроби від того самого клієнта можуть спрацювати на обмежувач уже на другому запиті, замість того щоб обидві одночасно пройшли як звичайні невідповідності. + - `gateway.auth.rateLimit.exemptLoopback` типово має значення `true`; встановіть `false`, якщо ви навмисно хочете обмежувати швидкість і для localhost-трафіку (для тестових конфігурацій або строгих розгортань proxy). +- Спроби WS-автентифікації з browser-origin завжди обмежуються без винятку для loopback (додатковий захист від брутфорсу localhost через браузер). +- На loopback такі блокування за browser-origin ізольовані для кожного нормалізованого + значення `Origin`, тому повторні збої з одного localhost-origin не блокують + автоматично інший origin. +- `tailscale.mode`: `serve` (лише tailnet, bind на loopback) або `funnel` (публічно, потребує автентифікації). +- `controlUi.allowedOrigins`: явний allowlist browser-origin для підключень Gateway WebSocket. Потрібний, коли очікуються browser-клієнти з origin, відмінних від loopback. +- `controlUi.dangerouslyAllowHostHeaderOriginFallback`: небезпечний режим, що вмикає fallback origin за заголовком Host для розгортань, які навмисно покладаються на політику origin через заголовок Host. +- `remote.transport`: `ssh` (типово) або `direct` (ws/wss). Для `direct` значення `remote.url` має бути `ws://` або `wss://`. +- `OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1`: клієнтське перевизначення break-glass, яке дозволяє відкритий `ws://` до довірених IP приватної мережі; типове значення для відкритого протоколу все ще обмежене лише loopback. +- `gateway.remote.token` / `.password` — це поля облікових даних віддаленого клієнта. Вони самі по собі не налаштовують автентифікацію gateway. +- `gateway.push.apns.relay.baseUrl`: базовий HTTPS URL для зовнішнього APNs relay, який використовують офіційні/TestFlight збірки iOS після публікації relay-backed реєстрацій у 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`: інтервал health-monitor каналу в хвилинах. Установіть `0`, щоб глобально вимкнути перезапуски health-monitor. Типово: `5`. +- `gateway.channelStaleEventThresholdMinutes`: поріг застарілого сокета в хвилинах. Це значення має бути більшим або рівним `gateway.channelHealthCheckMinutes`. Типово: `30`. +- `gateway.channelMaxRestartsPerHour`: максимальна кількість перезапусків health-monitor на канал/обліковий запис протягом ковзної години. Типово: `10`. +- `channels..healthMonitor.enabled`: відмова для окремого каналу від перезапусків health-monitor за збереження глобального монітора увімкненим. +- `channels..accounts..healthMonitor.enabled`: перевизначення для окремого облікового запису в багатооблікових каналах. Якщо задано, воно має пріоритет над перевизначенням на рівні каналу. +- Локальні шляхи виклику gateway можуть використовувати `gateway.remote.*` як резервне значення лише тоді, коли `gateway.auth.*` не задано. +- Якщо `gateway.auth.token` / `gateway.auth.password` явно налаштовано через SecretRef і вони не можуть бути визначені, визначення завершується в fail-closed (без маскування резервним remote). +- `trustedProxies`: IP reverse proxy, які завершують TLS або вставляють заголовки forwarded-client. Додавайте лише proxy, які ви контролюєте. Записи 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-списку заборон. -### Endpoint-и OpenAI-compatible +### Endpoint OpenAI-compatible - Chat Completions: типово вимкнено. Увімкніть через `gateway.http.endpoints.chatCompletions.enabled: true`. - Responses API: `gateway.http.endpoints.responses.enabled`. -- Захист URL-input для Responses: +- Посилення захисту URL-входу для Responses: - `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)) + і/або `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)) -### Ізоляція кількох екземплярів +### Ізоляція кількох інстансів -Запускайте кілька gateway на одному хості з унікальними портами й каталогами стану: +Запускайте кілька gateway на одному хості з унікальними портами та каталогами стану: ```bash OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \ @@ -3186,10 +3186,10 @@ openclaw gateway --port 19001 ``` - `enabled`: вмикає завершення TLS на слухачі gateway (HTTPS/WSS) (типово: `false`). -- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, коли явні файли не налаштовано; лише для локального/dev використання. -- `certPath`: шлях у файловій системі до файла TLS-сертифіката. -- `keyPath`: шлях у файловій системі до файла приватного ключа TLS; обмежте права доступу. -- `caPath`: необов’язковий шлях до bundle CA для перевірки клієнта або власних ланцюжків довіри. +- `autoGenerate`: автоматично генерує локальну самопідписану пару cert/key, якщо явні файли не налаштовано; лише для local/dev. +- `certPath`: шлях файлової системи до файла TLS-сертифіката. +- `keyPath`: шлях файлової системи до приватного ключа TLS; обмежуйте дозволи доступу. +- `caPath`: необов’язковий шлях до CA bundle для перевірки клієнта або користувацьких ланцюжків довіри. ### `gateway.reload` @@ -3206,12 +3206,12 @@ openclaw gateway --port 19001 ``` - `mode`: керує тим, як зміни конфігурації застосовуються під час runtime. - - `"off"`: ігнорувати live-редагування; зміни вимагають явного перезапуску. - - `"restart"`: завжди перезапускати процес gateway після зміни конфігурації. + - `"off"`: ігнорувати зміни в реальному часі; зміни потребують явного перезапуску. + - `"restart"`: завжди перезапускати процес gateway при зміні конфігурації. - `"hot"`: застосовувати зміни в процесі без перезапуску. - - `"hybrid"` (типово): спочатку пробувати hot reload; за потреби переходити до restart. + - `"hybrid"` (типово): спочатку пробувати hot reload; за потреби повертатися до перезапуску. - `debounceMs`: вікно debounce у мс перед застосуванням змін конфігурації (невід’ємне ціле число). -- `deferralTimeoutMs`: максимальний час у мс очікування завершення поточних операцій перед примусовим перезапуском (типово: `300000` = 5 хвилин). +- `deferralTimeoutMs`: максимальний час у мс очікування завершення операцій у польоті перед примусовим перезапуском (типово: `300000` = 5 хвилин). --- @@ -3248,7 +3248,7 @@ openclaw gateway --port 19001 } ``` -Auth: `Authorization: Bearer ` або `x-openclaw-token: `. +Автентифікація: `Authorization: Bearer ` або `x-openclaw-token: `. Токени hooks у query-string відхиляються. Примітки щодо валідації та безпеки: @@ -3257,38 +3257,38 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `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. +- Якщо 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` із payload запиту приймається лише тоді, коли `hooks.allowRequestSessionKey=true` (типово: `false`). - `POST /hooks/` → визначається через `hooks.mappings` - - Значення mapping `sessionKey`, сформовані шаблоном, вважаються зовнішньо наданими й також вимагають `hooks.allowRequestSessionKey=true`. + - Значення `sessionKey` mapping, сформовані шаблоном, вважаються зовнішньо переданими й також вимагають `hooks.allowRequestSessionKey=true`. - + - `match.path` відповідає підшляху після `/hooks` (наприклад `/hooks/gmail` → `gmail`). - `match.source` відповідає полю payload для загальних шляхів. -- Шаблони на кшталт `{{messages[0].subject}}` зчитують дані з payload. +- Шаблони на кшталт `{{messages[0].subject}}` читають дані з payload. - `transform` може вказувати на модуль JS/TS, який повертає дію hook. - - `transform.module` має бути відносним шляхом і залишатися в межах `hooks.transformsDir` (абсолютні шляхи та traversal відхиляються). -- `agentId` маршрутизує до конкретного агента; невідомі ID використовують запасний перехід до типового агента. -- `allowedAgentIds`: обмежує явну маршрутизацію (`*` або не вказано = дозволити всі, `[]` = заборонити всі). -- `defaultSessionKey`: необов’язковий фіксований ключ сесії для запусків hook-агента без явного `sessionKey`. -- `allowRequestSessionKey`: дозволити викликачам `/hooks/agent` і session key mapping-ів на основі шаблонів задавати `sessionKey` (типово: `false`). + - `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` типово дорівнює `last`. -- `model` перевизначає LLM для цього запуску hook (має бути дозволено, якщо задано каталог моделей). +- `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 { @@ -3316,7 +3316,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. --- -## Хост Canvas +## Canvas host ```json5 { @@ -3328,22 +3328,22 @@ 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"` (типово). -- Binds, відмінні від loopback: маршрути canvas вимагають auth Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. -- Node WebView зазвичай не надсилають заголовки auth; після pairing і підключення node Gateway рекламує URL можливостей із областю node для доступу до canvas/A2UI. -- URL можливостей прив’язані до активної WS-сесії node і швидко закінчують дію. Запасний варіант на основі IP не використовується. -- Додає клієнт live-reload у HTML, що обслуговується. -- Автоматично створює стартовий `index.html`, якщо каталог порожній. +- Лише локально: залишайте `gateway.bind: "loopback"` (типово). +- Для bind, відмінних від loopback: маршрути canvas вимагають автентифікації Gateway (token/password/trusted-proxy), так само як і інші HTTP-поверхні Gateway. +- Node WebViews зазвичай не надсилають заголовки автентифікації; після сполучення й підключення Node Gateway рекламує URL можливостей із областю Node для доступу до canvas/A2UI. +- URL можливостей прив’язані до активного WS-сеансу Node і швидко спливають. Резервний варіант на основі IP не використовується. +- Вставляє клієнт live-reload у HTML, що обслуговується. +- Автоматично створює початковий `index.html`, коли каталог порожній. - Також обслуговує A2UI за адресою `/__openclaw__/a2ui/`. -- Зміни вимагають перезапуску gateway. -- Вимикайте live reload для великих каталогів або в разі помилок `EMFILE`. +- Зміни потребують перезапуску gateway. +- Вимикайте live reload для великих каталогів або за помилок `EMFILE`. --- -## Discovery +## Виявлення ### mDNS (Bonjour) @@ -3359,7 +3359,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `minimal` (типово): не включати `cliPath` + `sshPort` у TXT-записи. - `full`: включати `cliPath` + `sshPort`. -- Типове ім’я хоста — `openclaw`. Перевизначення через `OPENCLAW_MDNS_HOSTNAME`. +- Типове ім’я хоста — `openclaw`. Перевизначайте через `OPENCLAW_MDNS_HOSTNAME`. ### Wide-area (DNS-SD) @@ -3371,7 +3371,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -Записує unicast DNS-SD zone у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS Tailscale. +Записує зону unicast DNS-SD у `~/.openclaw/dns/`. Для виявлення між мережами поєднуйте з DNS-сервером (рекомендовано CoreDNS) + split DNS у Tailscale. Налаштування: `openclaw dns setup --apply`. @@ -3379,7 +3379,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Середовище -### `env` (вбудовані env-змінні) +### `env` (вбудовані змінні середовища) ```json5 { @@ -3396,14 +3396,14 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Вбудовані env-змінні застосовуються лише тоді, коли в середовищі процесу немає цього ключа. +- Вбудовані змінні середовища застосовуються лише тоді, коли в середовищі процесу відсутній цей ключ. - Файли `.env`: `.env` поточного робочого каталогу + `~/.openclaw/.env` (жоден із них не перевизначає наявні змінні). -- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашої login shell. -- Повний порядок пріоритетів див. у [Environment](/uk/help/environment). +- `shellEnv`: імпортує відсутні очікувані ключі з профілю вашого login shell. +- Повний пріоритет див. у [Environment](/uk/help/environment). -### Підстановка env-змінних +### Підстановка змінних середовища -Посилайтеся на env-змінні в будь-якому рядку конфігурації через `${VAR_NAME}`: +Посилайтеся на змінні середовища в будь-якому рядку конфігурації через `${VAR_NAME}`: ```json5 { @@ -3413,7 +3413,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Відповідають лише імена у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. +- Зіставляються лише назви у верхньому регістрі: `[A-Z_][A-Z0-9_]*`. - Відсутні/порожні змінні спричиняють помилку під час завантаження конфігурації. - Екрануйте через `$${VAR}` для буквального `${VAR}`. - Працює з `$include`. @@ -3422,7 +3422,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Секрети -Посилання на секрети є додатковими: звичайні текстові значення все ще працюють. +Посилання на секрети є додатковими: відкриті значення також продовжують працювати. ### `SecretRef` @@ -3438,13 +3438,13 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - шаблон `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` відхиляється) +- `id` для `source: "exec"` не повинні містити сегменти шляху `.` або `..`, розділені слешами (наприклад `a/../b` відхиляється) ### Підтримувана поверхня облікових даних -- Канонічна матриця: [SecretRef Credential Surface](/uk/reference/secretref-credential-surface) +- Канонічна матриця: [Поверхня облікових даних SecretRef](/uk/reference/secretref-credential-surface) - `secrets apply` націлюється на підтримувані шляхи облікових даних у `openclaw.json`. -- Посилання в `auth-profiles.json` включено в runtime-розв’язання та покриття аудитом. +- Посилання в `auth-profiles.json` включено до визначення runtime і покриття аудиту. ### Конфігурація провайдерів секретів @@ -3476,18 +3476,18 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. Примітки: -- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (`id` має бути `"value"` у режимі singleValue). -- Шляхи file і exec провайдерів працюють fail-closed, коли перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. -- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload протоколу через stdin/stdout. -- Типово шляхи команд symlink відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою розв’язаного цільового шляху. -- Якщо налаштовано `trustedDirs`, перевірка trusted-dir застосовується до розв’язаного цільового шляху. +- Провайдер `file` підтримує `mode: "json"` і `mode: "singleValue"` (у режимі singleValue `id` має бути `"value"`). +- Шляхи до провайдерів file і exec переходять у fail-closed, коли перевірка ACL Windows недоступна. Установлюйте `allowInsecurePath: true` лише для довірених шляхів, які неможливо перевірити. +- Провайдер `exec` вимагає абсолютний шлях `command` і використовує payload-и протоколу через stdin/stdout. +- Типово шляхи команд через symlink відхиляються. Установіть `allowSymlinkCommand: true`, щоб дозволити шляхи symlink із перевіркою шляху до визначеної цілі. +- Якщо налаштовано `trustedDirs`, перевірка довірених каталогів застосовується до шляху визначеної цілі. - Дочірнє середовище `exec` типово мінімальне; передавайте потрібні змінні явно через `passEnv`. -- Посилання на секрети розв’язуються під час активації у знімок у пам’яті, а далі шляхи запитів читають лише цей знімок. -- Під час активації застосовується фільтрація активної поверхні: нерозв’язані посилання на увімкнених поверхнях спричиняють помилку startup/reload, тоді як неактивні поверхні пропускаються з діагностикою. +- Посилання на секрети визначаються під час активації в знімок у пам’яті, після чого шляхи запитів читають лише цей знімок. +- Під час активації застосовується фільтрація активної поверхні: невизначені посилання на ввімкнених поверхнях призводять до помилки запуску/перезавантаження, тоді як неактивні поверхні пропускаються з діагностикою. --- -## Сховище auth +## Сховище автентифікації ```json5 { @@ -3507,11 +3507,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Профілі для окремого агента зберігаються в `/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-profile на основі 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` @@ -3533,21 +3533,21 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `billingBackoffHours`: базовий backoff у годинах, коли профіль зазнає збою через справжні - помилки billing/недостатнього балансу (типово: `5`). Явний текст про billing - усе ще може потрапити сюди навіть у відповідях `401`/`403`, але - текстові matcher-и, специфічні для провайдера, залишаються обмеженими тим провайдером, - якому вони належать (наприклад OpenRouter - `Key limit exceeded`). Повторювані HTTP `402` usage-window або - повідомлення про ліміт витрат organization/workspace натомість залишаються в шляху `rate_limit`. -- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff для billing за провайдером. -- `billingMaxHours`: обмеження в годинах для експоненційного зростання billing backoff (типово: `24`). -- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` з високою впевненістю (типово: `10`). +- `billingBackoffHours`: базовий backoff у годинах, коли профіль завершується помилкою через справжні + помилки білінгу/недостатнього кредиту (типово: `5`). Явний текст білінгу + все ще може потрапляти сюди навіть у відповідях `401`/`403`, але + зіставлення тексту, специфічні для провайдера, залишаються в межах того + провайдера, якому вони належать (наприклад OpenRouter + `Key limit exceeded`). Повторювані повідомлення HTTP `402` про вікно використання або + ліміти витрат організації/workspace замість цього лишаються в шляху `rate_limit`. +- `billingBackoffHoursByProvider`: необов’язкові перевизначення годин backoff білінгу для окремих провайдерів. +- `billingMaxHours`: обмеження в годинах для експоненційного зростання backoff білінгу (типово: `24`). +- `authPermanentBackoffMinutes`: базовий backoff у хвилинах для збоїв `auth_permanent` із високою впевненістю (типово: `10`). - `authPermanentMaxMinutes`: обмеження в хвилинах для зростання backoff `auth_permanent` (типово: `60`). -- `failureWindowHours`: ковзне вікно в годинах, що використовується для лічильників backoff (типово: `24`). -- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile для того самого провайдера при помилках перевантаження перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми на кшталт `ModelNotReadyException`, коли провайдер зайнятий. +- `failureWindowHours`: ковзне вікно в годинах, яке використовується для лічильників backoff (типово: `24`). +- `overloadedProfileRotations`: максимальна кількість ротацій auth-profile в межах того самого провайдера для перевантажених помилок перед переходом до fallback моделі (типово: `1`). Сюди потрапляють форми зайнятості провайдера, як-от `ModelNotReadyException`. - `overloadedBackoffMs`: фіксована затримка перед повторною спробою ротації перевантаженого провайдера/профілю (типово: `0`). -- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile для того самого провайдера при помилках rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає специфічний для провайдерів текст на кшталт `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. +- `rateLimitedProfileRotations`: максимальна кількість ротацій auth-profile в межах того самого провайдера для помилок rate-limit перед переходом до fallback моделі (типово: `1`). Цей кошик rate-limit включає текстові форми провайдера, такі як `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` і `resource exhausted`. --- @@ -3568,7 +3568,7 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - Типовий файл журналу: `/tmp/openclaw/openclaw-YYYY-MM-DD.log`. - Установіть `logging.file` для стабільного шляху. -- `consoleLevel` підвищується до `debug` з `--verbose`. +- `consoleLevel` підвищується до `debug` при `--verbose`. - `maxFileBytes`: максимальний розмір файла журналу в байтах, після якого запис припиняється (додатне ціле число; типово: `524288000` = 500 MB). Для production-розгортань використовуйте зовнішню ротацію журналів. --- @@ -3606,19 +3606,19 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: головний перемикач для виводу інструментування (типово: `true`). -- `flags`: масив рядків-прапорців, що вмикають цільовий вивід журналу (підтримує wildcard на кшталт `"telegram.*"` або `"*"`). -- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сесії, поки сесія залишається в стані обробки. +- `enabled`: головний перемикач для виводу інструментації (типово: `true`). +- `flags`: масив рядків прапорців, що вмикає цільовий вивід журналу (підтримує wildcard, наприклад `"telegram.*"` або `"*"`). +- `stuckSessionWarnMs`: поріг віку в мс для виведення попереджень про завислі сеанси, поки сеанс залишається у стані обробки. - `otel.enabled`: вмикає конвеєр експорту OpenTelemetry (типово: `false`). -- `otel.endpoint`: URL collector для експорту OTel. +- `otel.endpoint`: URL колектора для експорту OTel. - `otel.protocol`: `"http/protobuf"` (типово) або `"grpc"`. -- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються разом із запитами експорту OTel. +- `otel.headers`: додаткові заголовки метаданих HTTP/gRPC, що надсилаються із запитами експорту OTel. - `otel.serviceName`: назва сервісу для атрибутів ресурсу. - `otel.traces` / `otel.metrics` / `otel.logs`: увімкнути експорт trace, metrics або logs. -- `otel.sampleRate`: частота семплювання trace `0`–`1`. +- `otel.sampleRate`: частота вибірки trace `0`–`1`. - `otel.flushIntervalMs`: інтервал періодичного скидання телеметрії в мс. -- `cacheTrace.enabled`: журналювати знімки трасування кешу для вбудованих запусків (типово: `false`). -- `cacheTrace.filePath`: шлях виводу для cache trace JSONL (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). +- `cacheTrace.enabled`: журналювати знімки cache trace для вбудованих запусків (типово: `false`). +- `cacheTrace.filePath`: шлях виводу для JSONL cache trace (типово: `$OPENCLAW_STATE_DIR/logs/cache-trace.jsonl`). - `cacheTrace.includeMessages` / `includePrompt` / `includeSystem`: керують тим, що включається до виводу cache trace (усі типово: `true`). --- @@ -3644,9 +3644,9 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. - `channel`: канал релізів для встановлень npm/git — `"stable"`, `"beta"` або `"dev"`. - `checkOnStart`: перевіряти оновлення npm під час запуску gateway (типово: `true`). - `auto.enabled`: увімкнути фонове автооновлення для встановлень пакетів (типово: `false`). -- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням stable-channel (типово: `6`; макс.: `168`). -- `auto.stableJitterHours`: додаткове вікно розподілу rollout stable-channel у годинах (типово: `12`; макс.: `168`). -- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-channel у годинах (типово: `1`; макс.: `24`). +- `auto.stableDelayHours`: мінімальна затримка в годинах перед автоматичним застосуванням у stable-каналі (типово: `6`; макс.: `168`). +- `auto.stableJitterHours`: додаткове вікно розподілу розгортання stable-каналу в годинах (типово: `12`; макс.: `168`). +- `auto.betaCheckIntervalHours`: як часто виконуються перевірки beta-каналу в годинах (типово: `1`; макс.: `24`). --- @@ -3679,22 +3679,22 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: глобальний feature gate для ACP (типово: `false`). -- `dispatch.enabled`: незалежний gate для диспетчеризації ходів сесії ACP (типово: `true`). Установіть `false`, щоб залишити команди ACP доступними, але заблокувати виконання. -- `backend`: ID типового ACP runtime backend (має відповідати зареєстрованому Plugin runtime ACP). -- `defaultAgent`: запасний цільовий ID агента ACP, коли spawn не задає явну ціль. -- `allowedAgents`: allowlist ID агентів, дозволених для runtime-сесій ACP; порожнє значення означає відсутність додаткових обмежень. -- `maxConcurrentSessions`: максимальна кількість одночасно активних сесій ACP. -- `stream.coalesceIdleMs`: вікно idle flush у мс для потокового тексту. -- `stream.maxChunkChars`: максимальний розмір частини перед розбиттям проєкції потокового блока. +- `enabled`: глобальний прапорець функції ACP (типово: `false`). +- `dispatch.enabled`: незалежний прапорець для диспетчеризації ходів сеансу ACP (типово: `true`). Установіть `false`, щоб зберегти доступність команд ACP, але заблокувати виконання. +- `backend`: id типового runtime-бекенда ACP (має відповідати зареєстрованому Plugin runtime ACP). +- `defaultAgent`: резервний id цільового агента ACP, коли спавни не задають явної цілі. +- `allowedAgents`: allowlist id агентів, дозволених для runtime-сеансів ACP; порожнє значення означає відсутність додаткових обмежень. +- `maxConcurrentSessions`: максимальна кількість одночасно активних сеансів ACP. +- `stream.coalesceIdleMs`: вікно idle-flush у мс для потокового тексту. +- `stream.maxChunkChars`: максимальний розмір чанка перед розбиттям потокової проєкції блока. - `stream.repeatSuppression`: пригнічувати повторювані рядки статусу/інструментів для кожного ходу (типово: `true`). -- `stream.deliveryMode`: `"live"` передає потік поступово; `"final_only"` буферизує до завершальних подій ходу. -- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструмента (типово: `"paragraph"`). -- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, що проєктується за один хід ACP. +- `stream.deliveryMode`: `"live"` транслює поступово; `"final_only"` буферизує до термінальних подій ходу. +- `stream.hiddenBoundarySeparator`: роздільник перед видимим текстом після прихованих подій інструментів (типово: `"paragraph"`). +- `stream.maxOutputChars`: максимальна кількість символів виводу асистента, проєктованих на хід ACP. - `stream.maxSessionUpdateChars`: максимальна кількість символів для проєктованих рядків статусу/оновлення ACP. -- `stream.tagVisibility`: запис імен тегів у відповідні булеві перевизначення видимості для потокових подій. -- `runtime.ttlMinutes`: idle TTL у хвилинах для працівників сесії ACP до можливого очищення. -- `runtime.installCommand`: необов’язкова команда встановлення, яку потрібно виконати під час bootstrap середовища runtime ACP. +- `stream.tagVisibility`: запис імен тегів до булевих перевизначень видимості для потокових подій. +- `runtime.ttlMinutes`: idle TTL у хвилинах для воркерів сеансу ACP до можливого очищення. +- `runtime.installCommand`: необов’язкова команда встановлення, яку слід запустити під час bootstrap середовища runtime ACP. --- @@ -3710,17 +3710,17 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `cli.banner.taglineMode` керує стилем слогана в banner: - - `"random"` (типово): ротаційні кумедні/сезонні слогани. - - `"default"`: фіксований нейтральний слоган (`All your chats, one OpenClaw.`). - - `"off"`: без тексту слогана (назва/версія banner усе одно показуються). -- Щоб приховати весь banner (а не лише слогани), установіть env `OPENCLAW_HIDE_BANNER=1`. +- `cli.banner.taglineMode` керує стилем tagline банера: + - `"random"` (типово): змінні кумедні/сезонні tagline. + - `"default"`: фіксований нейтральний tagline (`All your chats, one OpenClaw.`). + - `"off"`: без тексту tagline (назва/версія банера все одно показуються). +- Щоб приховати весь банер (не лише tagline), установіть env `OPENCLAW_HIDE_BANNER=1`. --- ## Wizard -Метадані, записані потоками керованого налаштування CLI (`onboard`, `configure`, `doctor`): +Метадані, що записуються керованими потоками налаштування CLI (`onboard`, `configure`, `doctor`): ```json5 { @@ -3738,15 +3738,15 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. ## Identity -Див. поля identity в `agents.list` у розділі [Типові значення агента](#agent-defaults). +Див. поля identity у `agents.list` у розділі [Значення за замовчуванням для агентів](#agent-defaults). --- -## Bridge (застарілий, видалений) +## Bridge (legacy, вилучено) -Поточні збірки більше не містять TCP bridge. Node підключаються через WebSocket Gateway. Ключі `bridge.*` більше не входять до schema конфігурації (валідація завершується помилкою, доки їх не буде видалено; `openclaw doctor --fix` може прибрати невідомі ключі). +Поточні збірки більше не містять TCP bridge. Node підключаються через Gateway WebSocket. Ключі `bridge.*` більше не є частиною схеми конфігурації (валідація завершується помилкою, доки їх не буде вилучено; `openclaw doctor --fix` може прибрати невідомі ключі). - + ```json { @@ -3784,11 +3784,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `sessionRetention`: як довго зберігати завершені ізольовані сесії запуску cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених транскриптів cron. Типове значення: `24h`; установіть `false`, щоб вимкнути. -- `runLog.maxBytes`: максимальний розмір файла журналу одного запуску (`cron/runs/.jsonl`) перед очищенням. Типове значення: `2_000_000` байтів. -- `runLog.keepLines`: кількість найновіших рядків, які зберігаються, коли спрацьовує очищення журналу запуску. Типове значення: `2000`. -- `webhookToken`: bearer token, який використовується для доставки POST до cron Webhook (`delivery.mode = "webhook"`); якщо не вказано, заголовок auth не надсилається. -- `webhook`: застарілий запасний URL webhook (http/https), який використовується лише для збережених job, що все ще мають `notify: true`. +- `sessionRetention`: як довго зберігати завершені ізольовані сеанси виконання Cron перед очищенням із `sessions.json`. Також керує очищенням архівованих видалених transcript Cron. Типово: `24h`; установіть `false`, щоб вимкнути. +- `runLog.maxBytes`: максимальний розмір кожного файла журналу запуску (`cron/runs/.jsonl`) перед очищенням. Типово: `2_000_000` байтів. +- `runLog.keepLines`: кількість найновіших рядків, що зберігаються, коли запускається очищення журналу виконання. Типово: `2000`. +- `webhookToken`: bearer token, що використовується для POST-доставки webhook Cron (`delivery.mode = "webhook"`); якщо пропущено, заголовок автентифікації не надсилається. +- `webhook`: застарілий legacy fallback URL webhook (http/https), який використовується лише для збережених завдань, що все ще мають `notify: true`. ### `cron.retry` @@ -3804,11 +3804,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `maxAttempts`: максимальна кількість повторних спроб для одноразових job при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). +- `maxAttempts`: максимальна кількість повторних спроб для одноразових завдань при тимчасових помилках (типово: `3`; діапазон: `0`–`10`). - `backoffMs`: масив затримок backoff у мс для кожної повторної спроби (типово: `[30000, 60000, 300000]`; 1–10 записів). -- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Не вказуйте, щоб повторювати всі тимчасові типи. +- `retryOn`: типи помилок, які запускають повторні спроби — `"rate_limit"`, `"overloaded"`, `"network"`, `"timeout"`, `"server_error"`. Пропустіть, щоб повторювати для всіх тимчасових типів. -Застосовується лише до одноразових cron job. Періодичні job використовують окрему обробку помилок. +Застосовується лише до одноразових завдань Cron. Для періодичних завдань використовується окрема обробка збоїв. ### `cron.failureAlert` @@ -3826,11 +3826,11 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- `enabled`: увімкнути попередження про збої для cron job (типово: `false`). -- `after`: кількість послідовних збоїв перед спрацюванням попередження (додатне ціле число, мін.: `1`). -- `cooldownMs`: мінімальна кількість мілісекунд між повторними попередженнями для тієї самої job (невід’ємне ціле число). -- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST до налаштованого webhook. -- `accountId`: необов’язковий ID акаунта або каналу для обмеження доставки попередження. +- `enabled`: увімкнути сповіщення про збої для завдань Cron (типово: `false`). +- `after`: кількість послідовних збоїв перед спрацюванням сповіщення (додатне ціле число, мін.: `1`). +- `cooldownMs`: мінімальна кількість мілісекунд між повторними сповіщеннями для того самого завдання (невід’ємне ціле число). +- `mode`: режим доставки — `"announce"` надсилає через повідомлення каналу; `"webhook"` робить POST на налаштований webhook. +- `accountId`: необов’язковий id облікового запису або каналу для області доставки сповіщення. ### `cron.failureDestination` @@ -3847,45 +3847,45 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. } ``` -- Типова ціль для сповіщень про збої cron для всіх job. -- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних цілі. -- `channel`: перевизначення каналу для доставки announce. `"last"` повторно використовує останній відомий канал доставки. -- `to`: явна ціль announce або URL webhook. Обов’язково для режиму webhook. -- `accountId`: необов’язкове перевизначення акаунта для доставки. -- `delivery.failureDestination` для окремої job перевизначає це глобальне типове значення. -- Коли не задано ні глобальної, ні специфічної для job цілі збоїв, job, які вже доставляють через `announce`, у разі збою використовують як запасний варіант цю основну ціль announce. -- `delivery.failureDestination` підтримується лише для job із `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` job не дорівнює `"webhook"`. +- Типова ціль для сповіщень про збої Cron у всіх завданнях. +- `mode`: `"announce"` або `"webhook"`; типово `"announce"`, коли існує достатньо даних про ціль. +- `channel`: перевизначення каналу для announce-доставки. `"last"` повторно використовує останній відомий канал доставки. +- `to`: явна announce-ціль або URL webhook. Обов’язково для режиму webhook. +- `accountId`: необов’язкове перевизначення облікового запису для доставки. +- `delivery.failureDestination` для конкретного завдання перевизначає це глобальне типове значення. +- Коли ні глобальну, ні для конкретного завдання ціль збоїв не задано, завдання, які вже доставляють через `announce`, у разі збою повертаються до цієї основної announce-цілі. +- `delivery.failureDestination` підтримується лише для завдань `sessionTarget="isolated"`, якщо тільки основний `delivery.mode` завдання не дорівнює `"webhook"`. -Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання cron відстежуються як [background tasks](/uk/automation/tasks). +Див. [Cron Jobs](/uk/automation/cron-jobs). Ізольовані виконання Cron відстежуються як [фонові завдання](/uk/automation/tasks). --- ## Змінні шаблону моделі медіа -Заповнювачі шаблону, що розгортаються в `tools.media.models[].args`: +Заповнювачі шаблонів, що розгортаються в `tools.media.models[].args`: -| Змінна | Опис | -| ------------------ | ------------------------------------------------- | -| `{{Body}}` | Повний текст вхідного повідомлення | -| `{{RawBody}}` | Сирий текст повідомлення (без обгорток історії/відправника) | -| `{{BodyStripped}}` | Текст повідомлення з прибраними груповими згадками | -| `{{From}}` | Ідентифікатор відправника | -| `{{To}}` | Ідентифікатор призначення | -| `{{MessageSid}}` | ID повідомлення каналу | -| `{{SessionId}}` | UUID поточної сесії | -| `{{IsNewSession}}` | `"true"`, коли створено нову сесію | -| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | -| `{{MediaPath}}` | Локальний шлях до медіа | -| `{{MediaType}}` | Тип медіа (image/audio/document/…) | -| `{{Transcript}}` | Аудіотранскрипт | -| `{{Prompt}}` | Розв’язаний медіапромпт для записів CLI | -| `{{MaxChars}}` | Розв’язана максимальна кількість символів виводу для записів CLI | -| `{{ChatType}}` | `"direct"` або `"group"` | -| `{{GroupSubject}}` | Тема групи (best effort) | -| `{{GroupMembers}}` | Попередній перегляд учасників групи (best effort) | -| `{{SenderName}}` | Відображуване ім’я відправника (best effort) | -| `{{SenderE164}}` | Номер телефону відправника (best effort) | -| `{{Provider}}` | Підказка провайдера (whatsapp, telegram, discord тощо) | +| Змінна | Опис | +| ----------------- | -------------------------------------------------- | +| `{{Body}}` | Повний текст вхідного повідомлення | +| `{{RawBody}}` | Сирий текст (без обгорток історії/відправника) | +| `{{BodyStripped}}`| Текст без згадувань у групі | +| `{{From}}` | Ідентифікатор відправника | +| `{{To}}` | Ідентифікатор призначення | +| `{{MessageSid}}` | ID повідомлення каналу | +| `{{SessionId}}` | UUID поточного сеансу | +| `{{IsNewSession}}`| `"true"`, коли створено новий сеанс | +| `{{MediaUrl}}` | Псевдо-URL вхідного медіа | +| `{{MediaPath}}` | Локальний шлях до медіа | +| `{{MediaType}}` | Тип медіа (image/audio/document/…) | +| `{{Transcript}}` | Аудіо 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 тощо) | --- @@ -3907,12 +3907,12 @@ Auth: `Authorization: Bearer ` або `x-openclaw-token: `. **Поведінка злиття:** - Один файл: замінює об’єкт-контейнер. -- Масив файлів: глибоко зливається в заданому порядку (пізніші значення перевизначають попередні). +- Масив файлів: глибоко зливається в заданому порядку (пізніші перевизначають попередні). - Сусідні ключі: зливаються після include (перевизначають включені значення). -- Вкладені include: до 10 рівнів глибини. -- Шляхи: розв’язуються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` для `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно розв’язуються в межах цієї межі. -- Записи, якими керує OpenClaw і які змінюють лише один розділ верхнього рівня, підкріплений include одного файла, записуються безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. -- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів, якими керує OpenClaw; такі записи завершуються fail-closed замість сплющення конфігурації. +- Вкладені include: до 10 рівнів вкладеності. +- Шляхи: визначаються відносно файла, що включає, але мають залишатися в межах каталогу конфігурації верхнього рівня (`dirname` від `openclaw.json`). Абсолютні форми/`../` дозволені лише тоді, коли вони все одно визначаються в межах цієї границі. +- Записи під керуванням OpenClaw, які змінюють лише один розділ верхнього рівня, підтримуваний include з одного файла, виконують запис безпосередньо в цей включений файл. Наприклад, `plugins install` оновлює `plugins: { $include: "./plugins.json5" }` у `plugins.json5` і залишає `openclaw.json` без змін. +- Кореневі include, масиви include та include із сусідніми перевизначеннями є лише для читання для записів під керуванням OpenClaw; такі записи завершуються в fail-closed замість сплощення конфігурації. - Помилки: зрозумілі повідомлення для відсутніх файлів, помилок розбору та циклічних include. --- diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index a073cd6d0..6e8ddba27 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -3,158 +3,159 @@ read_when: - Запуск тестів локально або в CI - Додавання регресійних тестів для помилок моделей/провайдерів - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker runners і що покриває кожен тест' +summary: 'Набір для тестування: unit/e2e/live набори, Docker runners і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-23T23:00:29Z" + generated_at: "2026-04-23T23:27:49Z" model: gpt-5.4 provider: openai - source_hash: 7a9e2a48bf887b6bf59e395e5966c2e77032403c0a05c81322ffe0b3247c7dff + source_hash: 5bb91a95c7b56825fe20a816a81603a9f3afe1bf62dbe20a2d500cefac27d798 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір -Docker runners. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runners. Цей документ — посібник «як ми тестуємо»: -- Що покриває кожен набір (і що він навмисно _не_ покриває). -- Які команди запускати для типових робочих процесів (локально, перед push, налагодження). -- Як live-тести знаходять облікові дані й вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. +- Що охоплює кожен набір (і що він навмисно _не_ охоплює). +- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. +- Як додавати регресійні тести для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: -- Повна перевірка (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск повного набору на продуктивній машині: `pnpm test:max` +- Повний gate (очікується перед 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` +- QA lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більше впевненості: +Коли ви торкаєтеся тестів або хочете більше впевненості: -- Перевірка покриття: `pnpm test:coverage` +- Gate покриття: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + probe інструментів/зображень Gateway): `pnpm test:live` +- Live-набір (моделі + зонди інструментів/зображень 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-перевірка моделей у Docker: `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` і ручні - `OpenClaw Release Checks` обидва викликають reusable workflow live/E2E з - `include_live_suites: true`, що включає окремі Docker live model + - Покриття CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + `OpenClaw Release Checks` обидва викликають багаторазово використовуваний workflow live/E2E з + `include_live_suites: true`, який включає окремі Docker live model matrix jobs, розшардовані за провайдером. - - Для цільових повторних запусків у CI викликайте `OpenClaw Live And E2E Checks (Reusable)` + - Для точкових повторних запусків у CI викличте `OpenClaw Live And E2E Checks (Reusable)` з `include_live_suites: true` і `live_models_only: true`. - - Додавайте нові секрети провайдерів із високим сигналом до `scripts/ci-hydrate-live-auth.sh` - разом із `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` та його - scheduled/release викликачами. -- Кошторисна smoke-перевірка Moonshot/Kimi: якщо задано `MOONSHOT_API_KEY`, виконайте + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його + викликачів scheduled/release. +- Перевірка вартості 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 і що - транскрипт асистента зберігає нормалізований `usage.cost`. + стенограма помічника зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, краще звузити live-тести через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. -## Спеціалізовані runners для QA +## QA-специфічні runners -Ці команди використовуються поряд з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними наборами тестів, коли вам потрібна реалістичність QA-lab: CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і через manual dispatch з mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch з mock parity gate, live Matrix lane та -Convex-managed live Telegram lane як паралельними jobs. `OpenClaw Release Checks` -запускає ті самі ланки перед схваленням релізу. +керованою Convex live Telegram lane як паралельними jobs. `OpenClaw Release Checks` +запускає ті самі lane перед затвердженням релізу. - `pnpm openclaw qa suite` - - Запускає QA-сценарії на основі репозиторію безпосередньо на хості. - - Типово запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-процесами Gateway. `qa-channel` типово має concurrency 4 (обмежене + - Запускає repo-backed QA-сценарії безпосередньо на хості. + - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими + Gateway workers. `qa-channel` за замовчуванням має concurrency 4 (обмежено кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість worker-процесів, або `--concurrency 1` для старішої послідовної ланки. - - Завершується з ненульовим кодом, якщо бодай один сценарій завершується помилкою. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без помилкового коду завершення. + кількість workers, або `--concurrency 1` для старого послідовного lane. + - Завершується з ненульовим кодом, якщо якийсь сценарій завершується невдачею. Використовуйте `--allow-failures`, коли + хочете отримати артефакти без коду завершення з помилкою. - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття фікстурами та mock протоколу без заміни сценарно-орієнтованої - ланки `mock-openai`. + покриття фікстур і mock-покриття протоколу, не замінюючи сценарно-орієнтований + lane `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані вхідні дані автентифікації QA, які практичні для гостьової системи: - ключі провайдера на основі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він є. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через - змонтований робочий простір. - - Записує звичайний QA report + summary, а також журнали Multipass у + - Live-запуски передають підтримувані вхідні дані QA auth, практичні для guest: + ключі провайдерів на основі env, шлях до конфігурації live-провайдера QA і `CODEX_HOME`, + якщо він присутній. + - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб guest міг записувати назад через + змонтований workspace. + - Записує звичайний QA-звіт + підсумок, а також логи Multipass до `.artifacts/qa-e2e/...`. - `pnpm qa:lab:up` - - Запускає QA-сайт на базі Docker для операторської роботи в QA. + - Запускає QA-сайт на базі Docker для QA-роботи в операторському стилі. - `pnpm test:docker:npm-onboard-channel-agent` - Збирає npm tarball з поточного checkout, глобально встановлює його в - Docker, виконує неінтерактивний onboarding OpenAI API key, типово налаштовує Telegram, - перевіряє, що ввімкнення plugin встановлює runtime-залежності за потреби, - запускає doctor і виконує один локальний хід агента проти mock OpenAI endpoint. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму packaged-install - ланку з Discord. + Docker, виконує неінтерактивне onboarding з ключем OpenAI API, за замовчуванням налаштовує + Telegram, перевіряє, що ввімкнення Plugin встановлює runtime-залежності за потреби, + запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий + lane пакетного встановлення з Discord. - `pnpm test:docker:bundled-channel-deps` - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає bundled channel/plugins через редагування конфігурації. - - Перевіряє, що виявлення setup залишає невстановлені runtime-залежності - для не налаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor встановлює runtime-залежності кожного bundled - plugin за потреби, і що другий перезапуск не перевстановлює залежності, - які вже були активовані. - - Також встановлює відому старішу npm-базу, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що - post-update doctor кандидата відновлює runtime-залежності bundled channel без - postinstall-відновлення з боку harness. + - Перевіряє, що виявлення setup залишає runtime-залежності + не налаштованих plugin відсутніми, перший налаштований запуск Gateway або doctor встановлює + runtime-залежності кожного bundled plugin за потреби, а другий перезапуск не + перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу базову версію npm, вмикає Telegram перед запуском + `openclaw update --tag ` і перевіряє, що doctor кандидата + після оновлення відновлює runtime-залежності bundled channel без + відновлення postinstall з боку harness. - `pnpm openclaw qa aimock` - - Запускає лише локальний сервер провайдера AIMock для прямої smoke-перевірки протоколу. + - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування + протоколу. - `pnpm openclaw qa matrix` - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для репозиторію/розробки. Упаковані інсталяції OpenClaw не постачаються з - `qa-lab`, тому не надають `openclaw qa`. - - Checkouts репозиторію завантажують 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 не надає спільних прапорців джерела облікових даних, оскільки ця ланка локально створює тимчасових користувачів. - - Записує Matrix QA report, summary, артефакт observed-events і комбінований журнал stdout/stderr у `.artifacts/qa-e2e/...`. + - Цей QA-хост наразі призначений лише для repo/dev. Пакетні встановлення 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 не надає спільні прапорці джерела облікових даних, оскільки lane локально надає тимчасових користувачів. + - Записує QA-звіт Matrix, підсумок, артефакт observed-events і комбінований лог виводу stdout/stderr до `.artifacts/qa-e2e/...`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. - - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. ID групи має бути числовим ID чату Telegram. - - Підтримує `--credential-source convex` для спільних пулів облікових даних. Типово використовуйте режим env або задайте `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled leases. - - Завершується з ненульовим кодом, якщо бодай один сценарій завершується помилкою. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без помилкового коду завершення. - - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження bot-to-bot увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує Telegram QA report, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії відповідей включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. + - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени bot driver і SUT із env. + - Потрібні `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим ідентифікатором чату Telegram. + - Підтримує `--credential-source convex` для спільних пулованих облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути пуловані lease. + - Завершується з ненульовим кодом, якщо якийсь сценарій завершується невдачею. Використовуйте `--allow-failures`, коли + хочете отримати артефакти без коду завершення з помилкою. + - Потрібні два різні боти в одній приватній групі, причому bot SUT має надавати ім’я користувача Telegram. + - Для стабільного спостереження bot-to-bot увімкніть режим Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що bot driver може спостерігати трафік ботів у групі. + - Записує QA-звіт Telegram, підсумок і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту надсилання driver до спостережуваної відповіді SUT. -Live transport lanes використовують один стандартний контракт, щоб нові транспорти не відхилялися: +Live transport lane використовують один стандартний контракт, щоб нові транспорти не розходилися: -`qa-channel` лишається широким синтетичним QA-набором і не є частиною матриці покриття live transport. +`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. -| Ланка | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальше повідомлення в треді | Ізоляція тредів | Спостереження реакцій | Команда help | -| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | ----------------------------- | --------------- | --------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Lane | Canary | Гейтінг згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у thread | Ізоляція thread | Спостереження за реакціями | Команда help | +| -------- | ------ | -------------- | -------------------- | ------------------------- | ----------------------------- | --------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | -### Спільні Telegram credentials через Convex (v1) +### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну lease із пулу на основі Convex, надсилає Heartbeat -для цієї lease, поки ланка працює, і звільняє lease під час завершення роботи. +QA lab отримує ексклюзивний lease із пулу на базі Convex, надсилає Heartbeat для +цього lease, поки lane виконується, і звільняє lease під час завершення роботи. -Базовий scaffold проєкту Convex: +Еталонний scaffold проєкту Convex: - `qa/convex-credential-broker/` @@ -166,7 +167,7 @@ QA lab отримує ексклюзивну lease із пулу на основ - `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`) Необов’язкові змінні середовища: @@ -175,15 +176,15 @@ QA lab отримує ексклюзивну lease із пулу на основ - `OPENCLAW_QA_CREDENTIAL_ACQUIRE_TIMEOUT_MS` (типово `90000`) - `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://` Convex URL для суто локальної розробки. +- `OPENCLAW_QA_CREDENTIAL_OWNER_ID` (необов’язковий trace id) +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback `http://` URL Convex лише для локальної розробки. -`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі має використовувати `https://`. +`OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Адміністраторські команди maintainer (додавання/видалення/список пулу) потребують +Адміністративні команди maintainer (додавання/видалення/перелік пулу) вимагають саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-помічники для maintainer: +CLI-хелпери для maintainer: ```bash pnpm openclaw qa credentials add --kind telegram --payload-file qa/telegram-credential.json @@ -191,9 +192,9 @@ 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`): +Контракт типового endpoint (`OPENCLAW_QA_CONVEX_SITE_URL` + `/qa-credentials/v1`): - `POST /acquire` - Запит: `{ kind, ownerId, actorRole, leaseTtlMs, heartbeatIntervalMs }` @@ -211,7 +212,7 @@ pnpm openclaw qa credentials remove --credential-id - `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - - Захист активної lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` + - Захист активного lease: `{ status: "error", code: "LEASE_ACTIVE", ... }` - `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -219,60 +220,60 @@ pnpm openclaw qa credentials remove --credential-id Форма payload для типу Telegram: - `{ groupId: string, driverToken: string, sutToken: string }` -- `groupId` має бути рядком із числовим ID чату Telegram. +- `groupId` має бути рядком числового ідентифікатора чату Telegram. - `admin/add` перевіряє цю форму для `kind: "telegram"` і відхиляє некоректні payload. ### Додавання каналу до QA -Додавання каналу до системи markdown QA вимагає рівно двох речей: +Додавання каналу до markdown-системи QA вимагає рівно двох речей: -1. Транспортний адаптер для каналу. -2. Набір сценаріїв, який перевіряє контракт каналу. +1. Адаптера транспорту для каналу. +2. Набору сценаріїв, що перевіряє контракт каналу. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим потоком. +володіти цим потоком. -`qa-lab` відповідає за спільну механіку хоста: +`qa-lab` відповідає за спільні механізми хоста: -- кореневу команду `openclaw qa` -- запуск і завершення suite -- паралелізм worker-процесів +- кореневий командний простір `openclaw qa` +- запуск і завершення набору +- concurrency workers - запис артефактів - генерацію звітів - виконання сценаріїв -- compatibility aliases для старіших сценаріїв `qa-channel` +- alias сумісності для старіших сценаріїв `qa-channel` -Плагіни runner відповідають за транспортний контракт: +Runner plugins відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` -- як налаштовується gateway для цього транспорту +- як Gateway налаштовується для цього транспорту - як перевіряється готовність -- як інжектуються вхідні події +- як ін’єктуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти і нормалізований стан транспорту -- як виконуються дії на базі транспорту -- як обробляється специфічне для транспорту скидання або очищення +- як надаються стенограми та нормалізований стан транспорту +- як виконуються дії, підкріплені транспортом +- як обробляється скидання або очищення, специфічні для транспорту -Мінімальний поріг прийняття для нового каналу такий: +Мінімальний поріг впровадження для нового каналу: 1. Залишайте `qa-lab` власником спільного кореня `qa`. -2. Реалізуйте транспортний runner на спільному шві хоста `qa-lab`. -3. Зберігайте специфічну для транспорту механіку всередині плагіна runner або harness каналу. +2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. +3. Залишайте механіку, специфічну для транспорту, всередині runner plugin або harness каналу. 4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Плагіни runner мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. - Зберігайте `runtime-api.ts` легким; ліниві CLI і виконання runner мають залишатися за окремими entrypoint. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; відкладене виконання CLI і runner має залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Для нових сценаріїв використовуйте загальні допоміжні функції сценаріїв. -7. Зберігайте працездатність наявних compatibility aliases, якщо тільки репозиторій не виконує навмисну міграцію. +6. Використовуйте загальні helper-и сценаріїв для нових сценаріїв. +7. Зберігайте роботу наявних alias сумісності, якщо тільки репозиторій не виконує навмисну міграцію. Правило прийняття рішення суворе: -- Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від транспорту одного каналу, залишайте її в цьому плагіні runner або harness плагіна. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте загальну допоміжну функцію замість специфічної для каналу гілки в `suite.ts`. +- Якщо поведінку можна виразити один раз у `qa-lab`, розміщуйте її в `qa-lab`. +- Якщо поведінка залежить від транспорту одного каналу, зберігайте її в цьому runner plugin або harness plugin. +- Якщо сценарію потрібна нова можливість, яку може використовувати більш ніж один канал, додавайте загальний helper замість гілки, специфічної для каналу, у `suite.ts`. - Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. -Бажані назви загальних допоміжних функцій для нових сценаріїв: +Бажані назви загальних helper-ів для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -287,7 +288,7 @@ pnpm openclaw qa credentials remove --credential-id - `formatTransportTranscript` - `resetTransport` -Compatibility aliases залишаються доступними для наявних сценаріїв, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -295,299 +296,294 @@ Compatibility aliases залишаються доступними для ная - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати загальні назви допоміжних функцій. -Compatibility aliases існують, щоб уникнути міграції одним днем, а не як модель для +Нова робота над каналами має використовувати загальні назви helper-ів. +Alias сумісності існують, щоб уникнути міграції одним днем, а не як модель для створення нових сценаріїв. -## Набори тестів (що й де запускається) +## Набори тестів (що і де запускається) -Думайте про набори як про «зростання реалізму» (і зростання нестабільності/вартості): +Думайте про ці набори як про «зростання реалістичності» (і зростання нестабільності/вартості): ### Unit / integration (типово) - Команда: `pnpm test` -- Конфігурація: ненаправлені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації для окремих проєктів для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, що покриваються `vitest.unit.config.ts` +- Конфігурація: ненацілені запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shard-и в конфігурації для кожного проєкту для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, конфігурація) - - Детерміновані регресійні тести для відомих помилок + - In-process integration-тести (gateway auth, маршрутизація, tooling, parsing, config) + - Детерміновані регресії для відомих помилок - Очікування: - - Запускаються в CI + - Запускається в CI - Реальні ключі не потрібні - - Мають бути швидкими й стабільними + - Має бути швидким і стабільним - - Ненаправлений `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` і далі використовує нативний граф проєкту root `vitest.config.ts`, оскільки цикл watch для багатьох шардів непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через 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 включають валідацію extension, оскільки extensions залежать від цих core-контрактів. Версійні зміни лише в метаданих релізу запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни пакетів поза верхньорівневим полем версії. - Unit-тести з малим імпортом із agents, commands, plugins, допоміжних функцій auto-reply, `plugin-sdk` та подібних чистих утилітних ділянок маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються на наявних lanes. - Вибрані допоміжні вихідні файли `plugin-sdk` і `commands` також зіставляють запуски в changed-mode з явними sibling tests у цих легких lanes, тому редагування допоміжних функцій уникає повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три спеціалізовані кошики: допоміжні функції верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це тримає найважчу роботу harness reply поза дешевими тестами status/chunk/token. + - Ненацілені запуски `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. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension виснажувати не пов’язані набори. - `pnpm test --watch` усе ще використовує native-граф проєктів root `vitest.config.ts`, тому що multi-shard цикл watch непрактичний. - `pnpm test`, `pnpm test:watch` і `pnpm test:perf:imports` спочатку маршрутизують явні цілі файл/каталог через scoped lanes, тому `pnpm test extensions/discord/src/monitor/message-handler.preflight.test.ts` уникає повної вартості запуску root-project. - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише маршрутизованих файлів source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. - `pnpm check:changed` — це типовий розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, метадані релізу й tooling, а потім запускає відповідні lane typecheck/lint/test. Зміни публічного Plugin SDK і plugin-contract включають один прохід перевірки extension, оскільки extensions залежать від цих контрактів core. Оновлення версій лише в метаданих релізу запускають цільові перевірки version/config/root-dependency замість повного набору, із захистом, що відхиляє зміни package поза полем версії верхнього рівня. - Легкі щодо імпортів unit-тести з agents, commands, plugins, helper-ів auto-reply, `plugin-sdk` та подібних чистих утилітних областей маршрутизуються через lane `unit-fast`, який пропускає `test/setup-openclaw-runtime.ts`; stateful/runtime-heavy файли залишаються в наявних lane. - Вибрані файли source helper-ів `plugin-sdk` і `commands` також відображають запуски в режимі changed на явні sibling-тести в цих легких lane, тому редагування helper-ів уникає повторного запуску повного важкого набору для цього каталогу. - `auto-reply` має три окремі bucket: helper-и core верхнього рівня, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply поза дешевими тестами status/chunk/token. - - Коли ви змінюєте вхідні дані виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте цільові регресійні тести допоміжних функцій для чистих меж маршрутизації та нормалізації. - - Підтримуйте в здоровому стані integration-набори вбудованого runner: + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, + зберігайте обидва рівні покриття. + - Додавайте точкові helper-регресії для чистих меж маршрутизації та нормалізації. + - Підтримуйте вбудовані integration-набори 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 ids і поведінка Compaction і далі проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише допоміжних функцій - не є достатньою заміною для цих integration-шляхів. + - Ці набори перевіряють, що scoped id і поведінка Compaction усе ще проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише для helper-ів не є + достатньою заміною для цих integration-шляхів. - - - Базова конфігурація Vitest типово використовує `threads`. + + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - неізольований runner у root projects, e2e і live configs. + неізольований runner у конфігураціях root projects, e2e і live. - Root UI lane зберігає своє налаштування `jsdom` та optimizer, але також працює на спільному неізольованому runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, - щоб зменшити V8 compile churn під час великих локальних запусків. - Задайте `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + - Кожен shard `pnpm test` успадковує ті самі типові значення `threads` + `isolate: false` + зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх процесів Node Vitest, + щоб зменшити churn компіляції V8 під час великих локальних запусків. + Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook запускає `pnpm check:changed --staged` після staged - formatting/linting, тому коміти лише для core не платять вартість тестів extension, - якщо вони не торкаються публічних контрактів, орієнтованих на extension. Коміти лише з - метаданими релізу залишаються на цільовій - lane version/config/root-dependency. - - Якщо точний staged-набір змін уже було перевірено - рівними або сильнішими перевірками, використовуйте - `scripts/committer --fast "" `, щоб пропустити лише - повторний запуск changed-scope hook. Staged format/lint і далі виконуються. Згадайте - завершені перевірки у вашому handoff. Це також прийнятно після - ізольованого flaky-збою hook, якщо його повторно запущено і він пройшов із scoped-доказом. + - `pnpm changed:lanes` показує, які архітектурні lane запускає diff. + - Pre-commit hook відповідає лише за форматування. Він повторно додає відформатовані файли до staging і + не запускає lint, typecheck чи тести. + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли вам + потрібен розумний локальний gate. Зміни публічного Plugin SDK і plugin-contract + включають один прохід перевірки extension. - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чітко відображаються на менший набір. + однозначно відображаються на менший набір. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищою межею кількості worker-процесів. - - Автомасштабування локальних worker-процесів навмисно консервативне і знижує навантаження, + лише з вищою межею workers. + - Автоматичне масштабування локальних workers навмисно консервативне й зменшує навантаження, коли середнє навантаження хоста вже високе, тому кілька одночасних запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає проєкти/файли конфігурації як - `forceRerunTriggers`, щоб повторні запуски у changed-mode залишалися коректними, коли змінюється - обв’язка тестів. + - Базова конфігурація Vitest позначає файли projects/config як + `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється тестова обв’язка. - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; задайте `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - один явний шлях кешу для прямого профілювання. + хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + одну явну локацію кешу для прямого профілювання. - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту плюс вивід деталізації імпорту. - - `pnpm test:perf:imports:changed` обмежує те саме подання профілювання - файлами, зміненими від `origin/main`. - - Коли один гарячий тест і далі витрачає більшість часу на стартові імпорти, - тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і - безпосередньо mock-айте цей шов замість deep-import runtime helper, лише - щоб передати їх через `vi.mock(...)`. + - `pnpm test:perf:imports:changed` звужує той самий вигляд профілювання до + файлів, змінених від `origin/main`. + - Коли один гарячий тест усе ще витрачає більшість часу на стартові імпорти, + тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і + напряму мокайте цей seam замість deep-import runtime-helper-ів лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із нативним шляхом root-project для цього зафіксованого - diff і виводить wall time плюс максимальний RSS у macOS. - - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного - брудного дерева, маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і конфігурацію root Vitest. - - `pnpm test:perf:profile:main` записує CPU-профіль основного потоку для - накладних витрат запуску й трансформації Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner для - unit-набору з вимкненим паралелізмом файлів. + `test:changed` з native-шляхом root-project для цього закоміченого + diff і друкує wall time плюс macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` бенчмаркає поточне брудне дерево, + маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. + - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для + накладних витрат запуску та transform у Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap для runner + unit-набору з вимкненим паралелізмом за файлами. -### Stability (gateway) +### Stability (Gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Пропускає синтетичне churn повідомлень gateway, пам’яті й великих payload через шлях подій діагностики - - Запитує `diagnostics.stability` через WS RPC Gateway - - Покриває допоміжні функції збереження діагностичного пакета стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні RSS-зразки не перевищують бюджет тиску, а глибини черг для кожного сеансу повертаються до нуля + - Запускає реальний loopback Gateway з увімкненою за замовчуванням діагностикою + - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper-и збереження bundle стабільності діагностики + - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS залишаються нижче бюджету тиску, а глибина черги для кожної сесії знову спадає до нуля - Очікування: - Безпечно для CI і без ключів - - Вузька lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway -### E2E (gateway smoke) +### E2E (smoke-тести Gateway) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` -- Типові параметри виконання: +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled-plugin у `extensions/` +- Типові параметри runtime: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивну кількість worker-процесів (CI: до 2, локально: типово 1). - - Типово запускається в тихому режимі, щоб зменшити накладні витрати на I/O консолі. + - Використовує адаптивну кількість workers (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням запускається в silent mode, щоб зменшити накладні витрати на console I/O. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` — примусово задати кількість worker-процесів (обмеження до 16). - - `OPENCLAW_E2E_VERBOSE=1` — знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=` для примусового задання кількості workers (обмежено 16). + - `OPENCLAW_E2E_VERBOSE=1` для повторного ввімкнення детального виводу console. - Обсяг: - - Поведінка multi-instance gateway end-to-end - - Поверхні WebSocket/HTTP, pairing вузлів і важче мережеве навантаження + - Наскрізна поведінка Gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairing вузлів і складніша мережева взаємодія - Очікування: - - Запускається в CI (коли це ввімкнено в pipeline) + - Запускається в CI (коли ввімкнено в pipeline) - Реальні ключі не потрібні - - Має більше рухомих частин, ніж unit-тести (може бути повільнішим) + - Більше рухомих частин, ніж в unit-тестах (може бути повільніше) -### E2E: smoke-перевірка backend OpenShell +### E2E: smoke-тест backend OpenShell - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований OpenShell gateway на хості через Docker + - Запускає ізольований Gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec - - Перевіряє canonical-поведінку віддаленої файлової системи через fs bridge sandbox + - Перевіряє backend OpenShell у OpenClaw через реальні `sandbox ssh-config` + виконання SSH + - Перевіряє канонічну для віддаленого середовища поведінку файлової системи через міст fs sandbox - Очікування: - Лише за явним увімкненням; не входить до типового запуску `pnpm test:e2e` - - Потрібен локальний CLI `openshell` і працездатний Docker daemon + - Потрібні локальний CLI `openshell` і працюючий Docker daemon - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` — увімкнути тест під час ручного запуску ширшого e2e-набору - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` — вказати нестандартний CLI binary або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого набору e2e + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб указати нестандартний двійковий файл CLI або wrapper-скрипт ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` -- Типове значення: **увімкнено** через `pnpm test:live` (задає `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled-plugin у `extensions/` +- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - - «Чи справді цей провайдер/модель _сьогодні_ працює з реальними обліковими даними?» - - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем автентифікації та поведінки лімітів частоти + - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» + - Виявлення змін форматів провайдерів, особливостей виклику інструментів, проблем auth і поведінки rate limit - Очікування: - - За задумом не є стабільним для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштує грошей / використовує ліміти частоти + - Навмисно нестабільний для 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. +- 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-запусків. + - Live-набори тепер виводять рядки прогресу в stderr, щоб було видно активність тривалих викликів провайдерів, навіть коли перехоплення console Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення console у Vitest, тому рядки прогресу провайдера/Gateway відразу транслюються під час live-запусків. - Налаштовуйте Heartbeat для прямих моделей через `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`, якщо змін багато) +- Зміни мережевої взаємодії Gateway / протоколу WS / pairing: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` -## Live: перевірка можливостей Android node +## Live: перевірка можливостей Android Node - Тест: `src/gateway/android-node.capabilities.live.test.ts` - Скрипт: `pnpm android:test:integration` -- Мета: викликати **кожну команду, яка наразі рекламується** підключеним Android node, і перевірити поведінку контракту команд. +- Мета: викликати **кожну команду, яку наразі оголошує** підключений Android Node, і перевірити поведінку контракту команди. - Обсяг: - Попередньо підготовлене/ручне налаштування (набір не встановлює/не запускає/не pair-ить застосунок). - - Перевірка gateway `node.invoke` команда за командою для вибраного Android node. -- Потрібне попереднє налаштування: - - Android-застосунок уже підключений і paired до gateway. - - Застосунок тримається на передньому плані. - - Надано дозволи/згоду на захоплення для можливостей, які ви очікуєте перевірити успішно. + - Перевірка `node.invoke` Gateway команда за командою для вибраного Android Node. +- Обов’язкове попереднє налаштування: + - Android-застосунок уже підключено та pair-ено з gateway. + - Застосунок має залишатися на передньому плані. + - Надано дозволи/згоду на capture для можливостей, які ви очікуєте як успішні. - Необов’язкові перевизначення цілі: - `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: smoke-перевірка моделей (ключі профілів) +## Live: smoke-тест моделей (ключі профілів) -Live-тести поділено на два шари, щоб можна було ізолювати збої: +Live-тести поділено на два рівні, щоб можна було ізолювати збої: -- «Пряма модель» показує, що провайдер/модель взагалі може відповідати з наданим ключем. -- «Gateway smoke» показує, що повний конвеєр gateway+agent працює для цієї моделі (сеанси, історія, інструменти, політика sandbox тощо). +- «Пряма модель» показує, чи може провайдер/модель узагалі відповісти з наданим ключем. +- «Smoke Gateway» показує, чи працює для цієї моделі повний конвеєр gateway+agent (sessions, history, tools, політика sandbox тощо). -### Шар 1: пряме завершення моделі (без gateway) +### Рівень 1: пряме завершення моделі (без gateway) - Тест: `src/agents/models.profiles.live.test.ts` - Мета: - - Перелічити знайдені моделі + - Перелічити виявлені моделі - Використати `getApiKeyForModel` для вибору моделей, для яких у вас є облікові дані - - Запустити невелике completion для кожної моделі (і цільові регресії там, де потрібно) + - Виконати невелике завершення для кожної моделі (і точкові регресії за потреби) - Як увімкнути: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) -- Задайте `OPENCLAW_LIVE_MODELS=modern` (або `all`, псевдонім для modern), щоб справді запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на gateway smoke +- Установіть `OPENCLAW_LIVE_MODELS=modern` (або `all`, alias для modern), щоб дійсно запустити цей набір; інакше він пропускається, щоб `pnpm test:live` залишався зосередженим на smoke Gateway - Як вибирати моделі: - - `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.4,openai-codex/gpt-5.5,anthropic/claude-opus-4-6,..."` (allowlist через кому) - - Перевірки modern/all типово мають curated high-signal cap; задайте `OPENCLAW_LIVE_MAX_MODELS=0` для повної modern-перевірки або додатне число для меншого обмеження. + - За замовчуванням перевірки modern/all обмежені підібраною високосигнальною межею; установіть `OPENCLAW_LIVE_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншої межі. - Як вибирати провайдерів: - `OPENCLAW_LIVE_PROVIDERS="google,google-antigravity,google-gemini-cli"` (allowlist через кому) - Звідки беруться ключі: - - Типово: зі сховища профілів і з env як резервного варіанта - - Задайте `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** + - За замовчуванням: сховище профілів і резервні значення env + - Установіть `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати **лише сховище профілів** - Навіщо це існує: - - Відокремлює «API провайдера зламане / ключ недійсний» від «зламано конвеєр gateway agent» - - Містить невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + tool-call flows) + - Відокремлює «API провайдера зламане / ключ недійсний» від «конвеєр gateway agent зламаний» + - Утримує невеликі ізольовані регресії (приклад: OpenAI Responses/Codex Responses reasoning replay + потоки tool-call) -### Шар 2: smoke-перевірка Gateway + dev agent (що насправді робить "@openclaw") +### Рівень 2: smoke Gateway + dev agent (що насправді робить "@openclaw") - Тест: `src/gateway/gateway-models.profiles.live.test.ts` - Мета: - Запустити in-process gateway - - Створити/пропатчити сеанс `agent:dev:*` (перевизначення моделі для кожного запуску) - - Перебрати моделі-з-ключами й перевірити: + - Створити/оновити session `agent:dev:*` (перевизначення моделі для кожного запуску) + - Ітеруватися по моделях із ключами і перевіряти: - «змістовну» відповідь (без інструментів) - - що працює реальний виклик інструмента (read probe) - - необов’язкові додаткові probe інструментів (exec+read probe) - - що регресійні шляхи OpenAI (лише tool-call → follow-up) і далі працюють -- Деталі probe (щоб можна було швидко пояснити збої): - - `read` probe: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. - - `exec+read` probe: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім `read` його назад. - - image probe: тест додає згенерований PNG (кіт + випадковий код) і очікує, що модель поверне `cat `. + - що працює реальний виклик інструмента (зонд читання) + - необов’язкові додаткові зонди інструментів (зонд exec+read) + - що шляхи регресії OpenAI (лише tool-call → follow-up) продовжують працювати +- Відомості про зонди (щоб ви могли швидко пояснювати збої): + - Зонд `read`: тест записує nonce-файл у workspace і просить агента `read` його та повернути nonce. + - Зонд `exec+read`: тест просить агента через `exec` записати nonce у тимчасовий файл, а потім `read` його назад. + - Зонд зображення: тест прикріплює згенерований PNG (кіт + рандомізований код) і очікує, що модель поверне `cat `. - Посилання на реалізацію: `src/gateway/gateway-models.profiles.live.test.ts` і `src/gateway/live-image-probe.ts`. - Як увімкнути: - `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 типово мають curated high-signal cap; задайте `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для повної modern-перевірки або додатне число для меншого обмеження. -- Як вибирати провайдерів (уникнути «усе через OpenRouter»): + - `OPENCLAW_LIVE_GATEWAY_MODELS=all` — це alias для modern allowlist + - Або встановіть `OPENCLAW_LIVE_GATEWAY_MODELS="provider/model"` (або список через кому), щоб звузити вибір + - За замовчуванням перевірки gateway modern/all обмежені підібраною високосигнальною межею; установіть `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=0` для вичерпної modern-перевірки або додатне число для меншої межі. +- Як вибирати провайдерів (уникати «все з 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 запускається, коли модель рекламує підтримку image input +- Зонди інструментів і зображень у цьому live-тесті завжди ввімкнені: + - зонд `read` + зонд `exec+read` (навантаження на інструменти) + - зонд зображення запускається, коли модель оголошує підтримку входу зображень - Потік (на високому рівні): - - Тест генерує крихітний PNG з “CAT” + випадковим кодом (`src/gateway/live-image-probe.ts`) + - Тест генерує крихітний PNG з «CAT» + випадковим кодом (`src/gateway/live-image-probe.ts`) - Надсилає його через `agent` `attachments: [{ mimeType: "image/png", content: "" }]` - - Gateway розбирає attachments у `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) + - Gateway розбирає вкладення в `images[]` (`src/gateway/server-methods/agent.ts` + `src/gateway/chat-attachments.ts`) - Вбудований агент передає моделі мультимодальне повідомлення користувача - Перевірка: відповідь містить `cat` + код (допуск OCR: незначні помилки дозволені) -Порада: щоб побачити, що можна тестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: +Порада: щоб побачити, що можна протестувати на вашій машині (і точні ідентифікатори `provider/model`), виконайте: ```bash openclaw models list openclaw models list --json ``` -## Live: smoke-перевірка backend CLI (Claude, Codex, Gemini або інші локальні CLI) +## Live: smoke-тест backend CLI (Claude, Codex, Gemini або інші локальні CLI) - Тест: `src/gateway/gateway-cli-backend.live.test.ts` -- Мета: перевірити конвеєр Gateway + agent, використовуючи локальний backend CLI, не торкаючись вашої типової конфігурації. -- Типові параметри smoke backend залежать від конкретного розширення і знаходяться у визначенні `cli-backend.ts` розширення-власника. +- Мета: перевірити конвеєр Gateway + agent з використанням локального backend CLI, не торкаючись вашої типової конфігурації. +- Типові параметри smoke для конкретного backend містяться у визначенні `cli-backend.ts` відповідного extension. - Увімкнення: - `pnpm test:live` (або `OPENCLAW_LIVE_TEST=1`, якщо викликаєте Vitest напряму) - `OPENCLAW_LIVE_CLI_BACKEND=1` - Типові значення: - Типовий провайдер/модель: `claude-cli/claude-sonnet-4-6` - - Поведінка command/args/image береться з метаданих плагіна CLI backend-власника. + - Поведінка command/args/image походить із метаданих plugin відповідного backend 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` — надіслати реальний image attachment (шляхи інжектуються в prompt). - - `OPENCLAW_LIVE_CLI_BACKEND_IMAGE_ARG="--image"` — передавати шляхи до файлів зображень як CLI args замість інжекції в 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` — вимкнути типову перевірку безперервності тієї самої сесії 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`, щоб надіслати другий хід і перевірити потік resume. + - `OPENCLAW_LIVE_CLI_BACKEND_MODEL_SWITCH_PROBE=0`, щоб вимкнути типову перевірку безперервності в тій самій сесії Claude Sonnet -> Opus (установіть `1`, щоб примусово ввімкнути її, коли вибрана модель підтримує ціль перемикання). Приклад: @@ -603,7 +599,7 @@ OPENCLAW_LIVE_CLI_BACKEND=1 \ pnpm test:docker:live-cli-backend ``` -Docker-рецепти для одного провайдера: +Рецепти Docker для одного провайдера: ```bash pnpm test:docker:live-cli-backend:claude @@ -614,29 +610,29 @@ pnpm test:docker:live-cli-backend:gemini Примітки: -- Docker runner розташовано в `scripts/test-live-cli-backend-docker.sh`. -- Він запускає live smoke-перевірку CLI-backend усередині Docker-образу репозиторію від імені непривілейованого користувача `node`. -- Він визначає метадані CLI smoke з розширення-власника, а потім встановлює відповідний Linux CLI package (`@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 зараз маршрутизує використання сторонніх застосунків через виставлення рахунків за додаткове використання замість звичайних лімітів тарифного плану підписки. -- Live smoke-перевірка CLI-backend тепер перевіряє той самий end-to-end потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через CLI gateway. -- Типова smoke-перевірка Claude також патчить сеанс із Sonnet на Opus і перевіряє, що відновлений сеанс усе ще пам’ятає попередню нотатку. +- Docker runner розташований у `scripts/test-live-cli-backend-docker.sh`. +- Він запускає live smoke-тест CLI-backend усередині 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` потребує переносимого OAuth підписки Claude Code через або `~/.claude/.credentials.json` з `claudeAiOauth.subscriptionType`, або `CLAUDE_CODE_OAUTH_TOKEN` з `claude setup-token`. Спочатку він доводить прямий `claude -p` у Docker, а потім виконує два ходи Gateway CLI-backend без збереження змінних середовища API-ключа Anthropic. Цей lane підписки типово вимикає зонди Claude MCP/tool і image, тому що зараз Claude маршрутизує використання сторонніх застосунків через оплату додаткового використання замість звичайних лімітів плану підписки. +- Live smoke-тест CLI-backend тепер перевіряє той самий наскрізний потік для Claude, Codex і Gemini: текстовий хід, хід класифікації зображення, потім виклик інструмента MCP `cron`, перевірений через Gateway CLI. +- Типовий smoke для Claude також оновлює сесію з Sonnet до Opus і перевіряє, що відновлена сесія все ще пам’ятає ранішу примітку. -## Live: smoke-перевірка ACP bind (`/acp spawn ... --bind here`) +## Live: smoke-тест ACP bind (`/acp spawn ... --bind here`) - Тест: `src/gateway/gateway-acp-bind.live.test.ts` -- Мета: перевірити реальний потік ACP conversation-bind із live ACP agent: +- Мета: перевірити реальний потік прив’язування розмови ACP з live ACP-агентом: - надіслати `/acp spawn --bind here` - - прив’язати синтетичну розмову каналу повідомлень на місці + - прив’язати синтетичну розмову message-channel на місці - надіслати звичайне follow-up у тій самій розмові - - перевірити, що follow-up потрапляє в транскрипт прив’язаного сеансу ACP + - перевірити, що follow-up потрапляє в стенограму прив’язаної сесії ACP - Увімкнення: - `pnpm test:live src/gateway/gateway-acp-bind.live.test.ts` - `OPENCLAW_LIVE_ACP_BIND=1` - Типові значення: - - ACP agents у Docker: `claude,codex,gemini` - - ACP agent для прямого `pnpm test:live ...`: `claude` + - ACP-агенти в Docker: `claude,codex,gemini` + - ACP-агент для прямого `pnpm test:live ...`: `claude` - Синтетичний канал: контекст розмови у стилі Slack DM - - ACP backend: `acpx` + - ACP-backend: `acpx` - Перевизначення: - `OPENCLAW_LIVE_ACP_BIND_AGENT=claude` - `OPENCLAW_LIVE_ACP_BIND_AGENT=codex` @@ -646,8 +642,8 @@ pnpm test:docker:live-cli-backend:gemini - `OPENCLAW_LIVE_ACP_BIND_CODEX_MODEL=gpt-5.5` - `OPENCLAW_LIVE_ACP_BIND_PARENT_MODEL=openai/gpt-5.4` - Примітки: - - Ця ланка використовує поверхню gateway `chat.send` з доступними лише адміністратору синтетичними полями originating-route, щоб тести могли прив’язувати контекст каналу повідомлень без імітації зовнішньої доставки. - - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не задано, тест використовує вбудований реєстр агентів плагіна `acpx` для вибраного ACP harness agent. + - Цей lane використовує поверхню gateway `chat.send` з admin-only синтетичними полями originating-route, щоб тести могли приєднувати контекст message-channel, не вдаючи зовнішню доставку. + - Коли `OPENCLAW_LIVE_ACP_BIND_AGENT_COMMAND` не встановлено, тест використовує вбудований реєстр агентів plugin `acpx` для вибраного ACP harness agent. Приклад: @@ -663,7 +659,7 @@ OPENCLAW_LIVE_ACP_BIND=1 \ pnpm test:docker:live-acp-bind ``` -Docker-рецепти для одного агента: +Рецепти Docker для одного агента: ```bash pnpm test:docker:live-acp-bind:claude @@ -673,37 +669,37 @@ pnpm test:docker:live-acp-bind:gemini Примітки щодо Docker: -- Docker runner розташовано в `scripts/test-live-acp-bind-docker.sh`. -- Типово він запускає smoke-перевірку ACP bind послідовно для всіх підтримуваних live CLI agent: `claude`, `codex`, потім `gemini`. +- Docker runner розташований у `scripts/test-live-acp-bind-docker.sh`. +- За замовчуванням він запускає smoke-тест ACP bind послідовно для всіх підтримуваних live CLI-агентів: `claude`, `codex`, потім `gemini`. - Використовуйте `OPENCLAW_LIVE_ACP_BIND_AGENTS=claude`, `OPENCLAW_LIVE_ACP_BIND_AGENTS=codex` або `OPENCLAW_LIVE_ACP_BIND_AGENTS=gemini`, щоб звузити матрицю. -- Він зчитує `~/.profile`, розміщує відповідні матеріали автентифікації CLI в контейнері, встановлює `acpx` у записуваний npm-префікс, а потім установлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. -- Усередині Docker runner задає `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав env-змінні провайдера зі зчитаного профілю доступними для дочірнього harness CLI. +- Він читає `~/.profile`, переносить відповідний auth-матеріал CLI до контейнера, встановлює `acpx` у записуваний npm-префікс, а потім встановлює потрібний live CLI (`@anthropic-ai/claude-code`, `@openai/codex` або `@google/gemini-cli`), якщо його немає. +- Усередині Docker runner встановлює `OPENCLAW_LIVE_ACP_BIND_ACPX_COMMAND=$HOME/.npm-global/bin/acpx`, щоб acpx зберігав змінні середовища провайдера з прочитаного профілю доступними для дочірнього harness CLI. -## Live: smoke-перевірка harness app-server Codex +## Live: smoke-тест harness app-server Codex -- Мета: перевірити plugin-власний harness Codex через звичайний метод gateway - `agent`: +- Мета: перевірити harness Codex, яким володіє plugin, через звичайний + метод gateway `agent`: - завантажити bundled plugin `codex` - вибрати `OPENCLAW_AGENT_RUNTIME=codex` - - надіслати перший хід gateway agent до `openai/gpt-5.5` із примусово заданим harness Codex - - надіслати другий хід у той самий сеанс OpenClaw і перевірити, що thread app-server - може відновитися - - запустити `/codex status` і `/codex models` через той самий командний + - надіслати перший хід gateway agent до `openai/gpt-5.5` з примусовим harness Codex + - надіслати другий хід до тієї самої сесії OpenClaw і перевірити, що thread + app-server може відновитися + - виконати `/codex status` і `/codex models` через той самий командний шлях gateway - - за потреби запустити дві перевірки escalated shell, перевірені Guardian: одну нешкідливу - команду, яку слід схвалити, і одне фіктивне завантаження секрету, яке має бути - відхилене, щоб агент перепитав + - за потреби виконати два Guardian-reviewed ескаловані shell-зонди: один нешкідливий + командний виклик, який має бути схвалений, і одне фальшиве завантаження секрету, + яке має бути відхилене, щоб агент поставив уточнювальне запитання - Тест: `src/gateway/gateway-codex-harness.live.test.ts` - Увімкнення: `OPENCLAW_LIVE_CODEX_HARNESS=1` - Типова модель: `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` -- Smoke-перевірка задає `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний harness Codex - не міг пройти, тихо перейшовши назад до PI. -- Автентифікація: автентифікація app-server Codex із локального логіна підписки Codex. Docker - smoke також можуть надавати `OPENAI_API_KEY` для probe, не пов’язаних із Codex, коли це доречно, - а також за потреби копіювати `~/.codex/auth.json` і `~/.codex/config.toml`. +- Необов’язковий зонд зображення: `OPENCLAW_LIVE_CODEX_HARNESS_IMAGE_PROBE=1` +- Необов’язковий зонд MCP/tool: `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=1` +- Необов’язковий зонд Guardian: `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=1` +- Smoke встановлює `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб зламаний + harness Codex не міг пройти непомітно, тихо повернувшись до PI. +- Auth: auth app-server Codex з локального логіну підписки Codex. Docker + smoke-тести також можуть надавати `OPENAI_API_KEY` для не-Codex-зондів, коли доречно, + а також необов’язково скопійовані `~/.codex/auth.json` і `~/.codex/config.toml`. Локальний рецепт: @@ -726,18 +722,17 @@ pnpm test:docker:live-codex-harness Примітки щодо Docker: -- Docker runner розташовано в `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. Задайте +- Docker runner розташований у `scripts/test-live-codex-harness-docker.sh`. +- Він читає змонтований `~/.profile`, передає `OPENAI_API_KEY`, копіює auth-файли CLI Codex, + якщо вони є, встановлює `@openai/codex` у записуваний змонтований npm-префікс, + переносить дерево source, а потім запускає лише live-тест harness Codex. +- Docker типово вмикає зонди image, MCP/tool і Guardian. Установіть `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-тесту, щоб застарілі псевдоніми або резервний перехід до PI не могли приховати регресію - harness Codex. + `OPENCLAW_LIVE_CODEX_HARNESS_MCP_PROBE=0`, або + `OPENCLAW_LIVE_CODEX_HARNESS_GUARDIAN_PROBE=0`, коли потрібен вужчий запуск + для налагодження. +- Docker також експортує `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, як і конфігурація live-тесту, + щоб старі alias або fallback до PI не могли приховати регресію harness Codex. ### Рекомендовані live-рецепти @@ -746,7 +741,7 @@ pnpm test:docker:live-codex-harness - Одна модель, напряму (без gateway): - `OPENCLAW_LIVE_MODELS="openai/gpt-5.4" pnpm test:live src/agents/models.profiles.live.test.ts` -- Одна модель, gateway smoke: +- Одна модель, smoke Gateway: - `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4" pnpm test:live src/gateway/gateway-models.profiles.live.test.ts` - Виклик інструментів через кількох провайдерів: @@ -759,21 +754,21 @@ pnpm test:docker:live-codex-harness Примітки: - `google/...` використовує API Gemini (API-ключ). -- `google-antigravity/...` використовує міст Antigravity OAuth (кінцева точка агента у стилі Cloud Code Assist). -- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окрема автентифікація + особливості інструментів). +- `google-antigravity/...` використовує міст OAuth Antigravity (endpoint агента у стилі Cloud Code Assist). +- `google-gemini-cli/...` використовує локальний CLI Gemini на вашій машині (окремий auth + особливості tooling). - API Gemini проти CLI Gemini: - - API: OpenClaw викликає розміщений Google API Gemini через HTTP (автентифікація через API-ключ / профіль); саме це більшість користувачів мають на увазі під “Gemini”. - - CLI: OpenClaw виконує локальний binary `gemini`; він має власну автентифікацію і може поводитися інакше (streaming/tool support/version skew). + - API: OpenClaw викликає розміщений Google API Gemini через HTTP (API-ключ / auth профілю); саме це більшість користувачів мають на увазі під «Gemini». + - CLI: OpenClaw виконує локальний двійковий файл `gemini`; він має власний auth і може поводитися інакше (streaming/підтримка інструментів/розсинхрон версій). -## Live: матриця моделей (що ми покриваємо) +## Live: матриця моделей (що ми охоплюємо) -Фіксованого «списку моделей CI» немає (live — за явним увімкненням), але це **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. +Фіксованого «списку моделей CI» не існує (live запускається за явним увімкненням), але ось **рекомендовані** моделі для регулярного покриття на машині розробника з ключами. -### Сучасний smoke-набір (виклик інструментів + зображення) +### Сучасний набір smoke (виклик інструментів + image) -Це запуск «поширених моделей», який, як ми очікуємо, має працювати: +Це запуск «поширених моделей», який ми очікуємо підтримувати працездатним: -- OpenAI (не Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) +- OpenAI (не-Codex): `openai/gpt-5.4` (необов’язково: `openai/gpt-5.4-mini`) - OpenAI Codex OAuth: `openai-codex/gpt-5.5` - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) - Google (API Gemini): `google/gemini-3.1-pro-preview` і `google/gemini-3-flash-preview` (уникайте старіших моделей Gemini 2.x) @@ -781,12 +776,12 @@ pnpm test:docker:live-codex-harness - Z.AI (GLM): `zai/glm-4.7` - MiniMax: `minimax/MiniMax-M2.7` -Запуск gateway smoke з інструментами + зображенням: +Запуск smoke Gateway з інструментами + image: `OPENCLAW_LIVE_GATEWAY_MODELS="openai/gpt-5.4,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` ### Базовий рівень: виклик інструментів (Read + необов’язковий Exec) -Виберіть принаймні одну модель для кожної сім’ї провайдерів: +Вибирайте щонайменше одну модель на сімейство провайдерів: - OpenAI: `openai/gpt-5.4` (або `openai/gpt-5.4-mini`) - Anthropic: `anthropic/claude-opus-4-6` (або `anthropic/claude-sonnet-4-6`) @@ -794,25 +789,25 @@ 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/`… (якщо у вас є доступ) +- Cerebras: `cerebras/`… (якщо маєте доступ) - LM Studio: `lmstudio/`… (локально; виклик інструментів залежить від режиму API) -### Vision: надсилання зображення (attachment → мультимодальне повідомлення) +### Vision: надсилання зображення (вкладення → мультимодальне повідомлення) -Додайте принаймні одну модель із підтримкою зображень у `OPENCLAW_LIVE_GATEWAY_MODELS` (Claude/Gemini/варіанти OpenAI з підтримкою vision тощо), щоб перевірити image probe. +Додайте принаймні одну модель із підтримкою зображень до `OPENCLAW_LIVE_GATEWAY_MODELS` (варіанти Claude/Gemini/OpenAI із підтримкою vision тощо), щоб перевірити image probe. -### Агрегатори / альтернативні gateway +### Aggregators / альтернативні gateway Якщо у вас увімкнені ключі, ми також підтримуємо тестування через: -- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tools+image) -- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (автентифікація через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) +- OpenRouter: `openrouter/...` (сотні моделей; використовуйте `openclaw models scan`, щоб знайти кандидатів із підтримкою tool+image) +- OpenCode: `opencode/...` для Zen і `opencode-go/...` для Go (auth через `OPENCODE_API_KEY` / `OPENCODE_ZEN_API_KEY`) -Більше провайдерів, які можна включити в live matrix (якщо у вас є облікові дані/конфігурація): +Інші провайдери, які можна включити до live matrix (якщо у вас є облікові дані/конфігурація): - Вбудовані: `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` (власні endpoint): `minimax` (cloud/API), а також будь-який OpenAI/Anthropic-сумісний proxy (LM Studio, vLLM, LiteLLM тощо) @@ -823,17 +818,17 @@ pnpm test:docker:live-codex-harness Live-тести знаходять облікові дані так само, як і CLI. Практичні наслідки: -- Якщо CLI працює, live-тести мають знайти ті самі ключі. -- Якщо live-тест каже «no creds», налагоджуйте це так само, як ви налагоджували б `openclaw models list` / вибір моделі. +- Якщо CLI працює, live-тести мають знаходити ті самі ключі. +- Якщо live-тест каже «немає облікових даних», налагоджуйте це так само, як налагоджували б `openclaw models list` / вибір моделі. -- Профілі автентифікації для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це означає «profile keys» у live-тестах) +- Профілі auth для окремих агентів: `~/.openclaw/agents//agent/auth-profiles.json` (саме це в live-тестах означає «ключі профілів») - Конфігурація: `~/.openclaw/openclaw.json` (або `OPENCLAW_CONFIG_PATH`) -- Застарілий каталог стану: `~/.openclaw/credentials/` (копіюється в staged live home, якщо існує, але не є основним сховищем profile keys) -- Локальні live-запуски типово копіюють активну конфігурацію, файли `auth-profiles.json` для окремих агентів, застарілий `credentials/` і підтримувані зовнішні каталоги автентифікації CLI у тимчасовий test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` видаляються, щоб probe не торкалися вашого реального workspace хоста. +- Каталог застарілого стану: `~/.openclaw/credentials/` (копіюється до staged live home, якщо існує, але не є основним сховищем ключів профілів) +- Локальні live-запуски за замовчуванням копіюють активну конфігурацію, файли `auth-profiles.json` для кожного агента, застарілий `credentials/` і підтримувані зовнішні каталоги auth CLI до тимчасового test home; staged live home пропускають `workspace/` і `sandboxes/`, а перевизначення шляхів `agents.*.workspace` / `agentDir` прибираються, щоб зонди не працювали у вашому реальному workspace хоста. -Якщо ви хочете покладатися на ключі з env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.profile` у контейнер). +Якщо ви хочете покладатися на ключі env (наприклад, експортовані у вашому `~/.profile`), запускайте локальні тести після `source ~/.profile`, або використовуйте Docker runners нижче (вони можуть монтувати `~/.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` @@ -844,14 +839,14 @@ Live-тести знаходять облікові дані так само, я - Увімкнення: `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 для зображень, відео та `music_generate` + - Перевіряє bundled-шляхи comfy для зображень, відео і `music_generate` - Пропускає кожну можливість, якщо не налаштовано `models.providers.comfy.` - - Корисно після змін у поданні workflow comfy, polling, завантаженнях або реєстрації plugin + - Корисно після змін у надсиланні workflow comfy, опитуванні, завантаженнях або реєстрації plugin ## Live генерація зображень @@ -859,16 +854,16 @@ Live-тести знаходять облікові дані так само, я - Команда: `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-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Проганяє стандартні варіанти генерації зображень через спільну runtime-можливість: + - Перелічує кожен зареєстрований bundled plugin провайдера генерації зображень + - Перед перевіркою завантажує відсутні змінні середовища провайдера з вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатного auth/профілю/моделі + - Запускає стандартні варіанти генерації зображень через спільну runtime-capability: - `google:flash-generate` - `google:pro-generate` - `google:pro-edit` - `openai:default-generate` -- Поточні bundled-провайдери, що покриваються: +- Поточні bundled-провайдери, що охоплюються: - `fal` - `google` - `minimax` @@ -879,8 +874,8 @@ Live-тести знаходять облікові дані так само, я - `OPENCLAW_LIVE_IMAGE_GENERATION_PROVIDERS="openai,google,xai"` - `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 +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Live генерація музики @@ -889,22 +884,22 @@ Live-тести знаходять облікові дані так само, я - Harness: `pnpm test:live:media music` - Обсяг: - Перевіряє спільний bundled-шлях провайдера генерації музики - - Наразі покриває Google і MiniMax - - Завантажує env-змінні провайдера з вашої login shell (`~/.profile`) перед probe - - За замовчуванням використовує live/env API-ключі перед збереженими профілями автентифікації, щоб застарілі тестові ключі в `auth-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі + - Наразі охоплює Google і MiniMax + - Перед перевіркою завантажує змінні середовища провайдера з вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатного auth/профілю/моделі - Запускає обидва оголошені runtime-режими, коли вони доступні: - - `generate` з вхідними даними лише у вигляді prompt + - `generate` з вхідними даними лише prompt - `edit`, коли провайдер оголошує `capabilities.edit.enabled` - - Поточне покриття спільної ланки: + - Поточне покриття спільного lane: - `google`: `generate`, `edit` - `minimax`: `generate` - - `comfy`: окремий live-файл Comfy, не ця спільна перевірка + - `comfy`: окремий live-файл Comfy, а не ця спільна перевірка - Необов’язкове звуження: - `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 +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Live генерація відео @@ -913,42 +908,42 @@ Live-тести знаходять облікові дані так само, я - Harness: `pnpm test:live:media video` - Обсяг: - Перевіряє спільний bundled-шлях провайдера генерації відео - - Типово використовує безпечний для релізу smoke-шлях: провайдери без FAL, один запит text-to-video на провайдера, односекундний 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-profiles.json` не маскували реальні shell-облікові дані - - Пропускає провайдерів без придатної автентифікації/профілю/моделі - - Типово запускає лише `generate` - - Задайте `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: - - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід із зображенням на основі buffer у спільній перевірці - - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled` і вибраний провайдер/модель приймає локальний вхід із відео на основі buffer у спільній перевірці + - За замовчуванням використовує безпечний для релізу smoke-шлях: провайдери, крім FAL, один запит text-to-video на провайдера, prompt про односекундного омара і обмеження операції на провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням) + - За замовчуванням пропускає FAL, тому що затримка черги на боці провайдера може домінувати над часом релізу; передайте `--video-providers fal` або `OPENCLAW_LIVE_VIDEO_GENERATION_PROVIDERS="fal"`, щоб запустити його явно + - Перед перевіркою завантажує змінні середовища провайдера з вашого login shell (`~/.profile`) + - За замовчуванням використовує live/env API-ключі раніше за збережені профілі auth, щоб застарілі test-ключі в `auth-profiles.json` не маскували реальні облікові дані shell + - Пропускає провайдерів без придатного auth/профілю/моделі + - За замовчуванням запускає лише `generate` + - Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими трансформації, коли вони доступні: + - `imageToVideo`, коли провайдер оголошує `capabilities.imageToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані зображень на основі буфера в спільній перевірці + - `videoToVideo`, коли провайдер оголошує `capabilities.videoToVideo.enabled`, а вибраний провайдер/модель приймає локальні вхідні дані відео на основі буфера в спільній перевірці - Поточні провайдери `imageToVideo`, оголошені, але пропущені в спільній перевірці: - - `vydra`, оскільки bundled `veo3` підтримує лише text, а bundled `kling` потребує віддаленого URL зображення + - `vydra`, тому що bundled `veo3` підтримує лише текст, а bundled `kling` вимагає віддалений URL зображення - Покриття Vydra, специфічне для провайдера: - `OPENCLAW_LIVE_TEST=1 OPENCLAW_LIVE_VYDRA_VIDEO=1 pnpm test:live -- extensions/vydra/vydra.live.test.ts` - - цей файл запускає `veo3` text-to-video плюс ланку `kling`, яка типово використовує фікстуру віддаленого URL зображення + - цей файл запускає `veo3` text-to-video плюс lane `kling`, який за замовчуванням використовує fixture віддаленого URL зображення - Поточне live-покриття `videoToVideo`: - лише `runway`, коли вибрана модель — `runway/gen4_aleph` - Поточні провайдери `videoToVideo`, оголошені, але пропущені в спільній перевірці: - - `alibaba`, `qwen`, `xai`, оскільки ці шляхи наразі вимагають віддалених еталонних URL `http(s)` / MP4 - - `google`, оскільки поточна спільна ланка Gemini/Veo використовує локальний вхід на основі buffer, а цей шлях не приймається в спільній перевірці - - `openai`, оскільки поточна спільна ланка не має гарантій доступу до організаційно-специфічного video inpaint/remix + - `alibaba`, `qwen`, `xai`, тому що ці шляхи наразі вимагають віддалені URL-посилання `http(s)` / MP4 + - `google`, тому що поточний спільний lane Gemini/Veo використовує локальний вхід на основі буфера, і цей шлях не приймається в спільній перевірці + - `openai`, тому що поточний спільний lane не гарантує доступ до 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` — зменшити обмеження операції для кожного провайдера для агресивного smoke-запуску -- Необов’язкова поведінка автентифікації: - - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1` — примусово використовувати автентифікацію зі сховища профілів і ігнорувати перевизначення лише з env + - `OPENCLAW_LIVE_VIDEO_GENERATION_SKIP_PROVIDERS=""`, щоб включити кожного провайдера до типової перевірки, включно з FAL + - `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS=60000`, щоб зменшити обмеження операції для кожного провайдера під час агресивного smoke-запуску +- Необов’язкова поведінка auth: + - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб примусово використовувати auth зі сховища профілів і ігнорувати перевизначення лише з env ## Media live harness - Команда: `pnpm test:live:media` - Призначення: - - Запускає спільні live-набори для зображень, музики та відео через один нативний для репозиторію entrypoint - - Автоматично завантажує відсутні env-змінні провайдера з `~/.profile` - - Автоматично звужує кожен набір до провайдерів, які наразі мають придатну автентифікацію, за замовчуванням - - Повторно використовує `scripts/test-live.mjs`, тому поведінка Heartbeat і тихого режиму залишається узгодженою + - Запускає спільні live-набори для зображень, музики і відео через один рідний для репозиторію entrypoint + - Автоматично завантажує відсутні змінні середовища провайдерів із `~/.profile` + - За замовчуванням автоматично звужує кожен набір до провайдерів, які наразі мають придатний auth + - Повторно використовує `scripts/test-live.mjs`, тож поведінка Heartbeat і quiet mode залишається узгодженою - Приклади: - `pnpm test:live:media` - `pnpm test:live:media image video --providers openai,google,minimax` @@ -957,157 +952,156 @@ Live-тести знаходять облікові дані так само, я ## Docker runners (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві категорії: +Ці Docker runners поділяються на дві групи: -- Live-model runners: `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 runners типово використовують менший smoke-cap, щоб повна Docker-перевірка залишалася практичною: - `test:docker:live-models` типово задає `OPENCLAW_LIVE_MAX_MODELS=12`, а - `test:docker:live-gateway` типово задає `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, +- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їм live-файл із ключами профілів усередині 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 runners за замовчуванням використовують меншу межу smoke, щоб повна Docker-перевірка лишалася практичною: + `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 image через `test:docker:live-build`, а потім повторно використовує його для двох Docker live lanes. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke runners E2E, які перевіряють зібраний застосунок. + `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці змінні середовища, коли + явно хочете більшу вичерпну перевірку. +- `test:docker:all` один раз збирає live Docker-образ через `test:docker:live-build`, а потім повторно використовує його для двох Docker lane live. Воно також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для E2E container smoke runners, які перевіряють зібраний застосунок. - Container smoke runners: `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 runners для live-model також bind-mount-ять лише потрібні CLI auth home (або всі підтримувані, коли запуск не звужено), а потім копіюють їх у home контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи сховище автентифікації хоста: +Docker runners для live-model також монтують лише потрібні домашні каталоги auth CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх до домашнього каталогу контейнера перед запуском, щоб зовнішній OAuth CLI міг оновлювати токени, не змінюючи сховище auth хоста: - Прямі моделі: `pnpm test:docker:live-models` (скрипт: `scripts/test-live-models-docker.sh`) -- Smoke-перевірка ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) -- Smoke-перевірка CLI backend: `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`) +- Smoke-тест ACP bind: `pnpm test:docker:live-acp-bind` (скрипт: `scripts/test-live-acp-bind-docker.sh`) +- Smoke-тест CLI backend: `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`) -- Live smoke-перевірка Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) -- Майстер onboarding (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) -- Smoke-перевірка onboarding/channel/agent через npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding з env-ref і типово Telegram, перевіряє, що ввімкнення plugin встановлює його runtime-залежності за потреби, запускає doctor і виконує один mock-хід агента OpenAI. Використовуйте готовий tarball повторно через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. -- Smoke-перевірка глобального встановлення 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`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` спільно використовує один npm-кеш для своїх контейнерів root, update і direct-npm. Smoke-перевірка update типово використовує npm `latest` як стабільну базу перед оновленням до tarball-кандидата. Непривілейовані перевірки installer зберігають ізольований npm-кеш, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Задайте `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm у локальних повторних запусках. -- Install Smoke CI пропускає дубльоване пряме глобальне оновлення direct-npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. -- Мережа 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 через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, а потім примусово спричиняє відхилення схеми провайдера й перевіряє, що необроблена деталь з’являється в журналах Gateway. -- Міст каналу MCP (ініціалізований Gateway + міст stdio + smoke-перевірка необробленого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) -- Інструменти Pi bundle MCP (реальний stdio MCP server + smoke-перевірка allow/deny вбудованого профілю Pi): `pnpm test:docker:pi-bundle-mcp-tools` (скрипт: `scripts/e2e/pi-bundle-mcp-tools-docker.sh`) -- Очищення Cron/subagent MCP (реальний Gateway + завершення дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (install smoke + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) -- Smoke-перевірка plugin update без змін: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke-перевірка метаданих config reload: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime-залежності bundled plugin: `pnpm test:docker:bundled-channel-deps` типово збирає невеликий Docker runner image, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій Linux-інсталяції. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. -- Під час ітерації звужуйте перевірку runtime-залежностей bundled plugin, вимикаючи не пов’язані сценарії, наприклад: +- Live smoke Open WebUI: `pnpm test:docker:openwebui` (скрипт: `scripts/e2e/openwebui-docker.sh`) +- Майстер onboarding (TTY, повний scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke-тест onboarding/channel/agent із npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding із посиланням на env плюс Telegram за замовчуванням, перевіряє, що ввімкнення Plugin встановлює його runtime-залежності за потреби, запускає doctor і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть перебудову на хості через `OPENCLAW_NPM_ONBOARD_HOST_BUILD=0` або змініть канал через `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`. +- Smoke-тест глобального встановлення 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`, пропустіть збірку на хості через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` зі зібраного Docker-образу через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. +- Installer Docker smoke: `bash scripts/test-install-sh-docker.sh` використовує спільний npm-кеш для своїх контейнерів root, update і direct-npm. Smoke-тест оновлення за замовчуванням використовує npm `latest` як стабільну базову версію перед оновленням до tarball-кандидата. Перевірки installer без root зберігають ізольований npm-кеш, щоб записи кешу, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- У CI для Install Smoke пропускається дубльоване пряме глобальне оновлення npm через `OPENCLAW_INSTALL_SMOKE_SKIP_NPM_GLOBAL=1`; запускайте скрипт локально без цього env, коли потрібне покриття прямого `npm install -g`. +- Мережева взаємодія 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`) запускає змоканий сервер OpenAI через Gateway, перевіряє, що `web_search` підвищує `reasoning.effort` з `minimal` до `low`, потім примусово спричиняє відхилення схеми провайдера й перевіряє, що необроблена деталізація з’являється в логах Gateway. +- Міст каналу MCP (seeded Gateway + міст stdio + smoke-тест сирого notification-frame Claude): `pnpm test:docker:mcp-channels` (скрипт: `scripts/e2e/mcp-channels-docker.sh`) +- Інструменти MCP у наборі Pi (реальний stdio MCP server + 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 і одноразового запуску subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) +- Plugins (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-залежності bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker-образ runner, один раз збирає і пакує OpenClaw на хості, а потім монтує цей tarball в кожен сценарій встановлення Linux. Повторно використовуйте образ через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть перебудову на хості після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. +- Звужуйте перевірку runtime-залежностей bundled 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 image: +Щоб вручну попередньо зібрати й повторно використати спільний образ 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 ``` -Перевизначення image для конкретного набору, як-от `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, і далі мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Тести Docker для QR та installer зберігають власні Dockerfile, оскільки вони перевіряють поведінку package/install, а не runtime спільного built-app. +Перевизначення образів для конкретних наборів, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо встановлені. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний образ, скрипти завантажують його, якщо його ще немає локально. Тести Docker для QR і installer зберігають власні Dockerfile, тому що вони перевіряють поведінку пакетування/встановлення, а не runtime спільного built-app. -Docker runners для live-model також монтують поточний checkout лише для читання й -розміщують його у тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно дозволяє запускати Vitest проти ваших точних локальних source/config. -Крок розміщення пропускає великі локальні кеші й артефакти збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або -Gradle output, щоб Docker live-запуски не витрачали хвилини на копіювання -специфічних для машини артефактів. -Вони також задають `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали -реальні worker-процеси каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` і далі запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття gateway -live із цієї Docker-ланки. -`test:docker:openwebui` — це smoke-перевірка сумісності вищого рівня: вона запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint, сумісними з OpenAI, -запускає прив’язаний контейнер Open WebUI проти цього gateway, входить через +Docker runners для live-model також монтують поточний checkout лише для читання і +переносять його до тимчасового workdir усередині контейнера. Це зберігає runtime-образ +легким і водночас дозволяє запускати Vitest точно проти вашого локального source/config. +Етап перенесення пропускає великі локальні кеші та результати збірки застосунку, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунку каталоги `.build` або +виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +артефактів, специфічних для машини. +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-зонди gateway не запускали +реальні workers каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли потрібно звузити або виключити покриття live gateway з цього Docker lane. +`test:docker:openwebui` — це smoke-тест сумісності вищого рівня: він запускає +контейнер gateway OpenClaw з увімкненими OpenAI-сумісними HTTP endpoint, +запускає закріплений контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний chat-запит через proxy `/api/chat/completions` Open WebUI. -Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити -image Open WebUI, а самому Open WebUI — завершити власне холодне стартове налаштування. -Ця ланка очікує придатний ключ live-моделі, і `OPENCLAW_PROFILE_FILE` -(типово `~/.profile`) є основним способом надати його в Dockerized-запусках. +реальний chat-запит через проксі `/api/chat/completions` Open WebUI. +Перший запуск може бути помітно повільнішим, тому що Docker може потребувати завантаження +образу Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. +Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(типово `~/.profile`) — основний спосіб надати його в Dockerized-запусках. Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. `test:docker:mcp-channels` навмисно детермінований і не потребує -реального облікового запису Telegram, Discord або iMessage. Він запускає ініціалізований -контейнер Gateway, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованих розмов, читання транскриптів, метадані вкладень, -поведінку live event queue, маршрутизацію вихідного надсилання і сповіщення каналу + -дозволів у стилі Claude через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує необроблені stdio MCP frames, тому smoke-перевірка перевіряє, що -міст насправді надсилає, а не лише те, що випадково показує конкретний client SDK. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує ключа live-моделі. -Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -всередині контейнера, матеріалізує цей сервер через runtime MCP вбудованого bundle Pi, +реального облікового запису Telegram, Discord або iMessage. Він запускає seeded Gateway +контейнер, запускає другий контейнер, який стартує `openclaw mcp serve`, а потім +перевіряє виявлення маршрутизованих розмов, читання стенограм, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про канал + +дозволи через реальний міст stdio MCP. Перевірка сповіщень +безпосередньо аналізує сирі кадри stdio MCP, тож smoke-тест перевіряє те, що міст +справді випромінює, а не лише те, що випадково показує конкретний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` детермінований і не потребує живого +ключа моделі. Він збирає Docker-образ репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP набору Pi, виконує інструмент, а потім перевіряє, що `coding` і `messaging` зберігають -інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх відфільтровують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. -Він запускає ініціалізований Gateway з реальним stdio MCP probe server, виконує +інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. +`test:docker:cron-mcp-cleanup` детермінований і не потребує живого ключа моделі. +Він запускає seeded Gateway з реальним stdio MCP probe server, виконує ізольований хід cron і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. -Ручна smoke-перевірка ACP plain-language thread (не для CI): +Ручний smoke-тест ACP plain-language thread (не для CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для робочих процесів регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації 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 і без монтування зовнішньої CLI-автентифікації -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI всередині Docker -- Зовнішні каталоги/файли CLI-автентифікації в `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед початком тестів +- `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`, щоб перевіряти лише змінні середовища, прочитані з `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/...` перед стартом тестів - Типові каталоги: `.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` - - Перевизначення вручну: `OPENCLAW_DOCKER_AUTH_DIRS=all`, `OPENCLAW_DOCKER_AUTH_DIRS=none` або список через кому, наприклад `OPENCLAW_DOCKER_AUTH_DIRS=.claude,.codex` + - Перевизначайте вручну через `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`, щоб повторно використовувати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний образ `openclaw:local-live` для повторних запусків, які не потребують перебудови - `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища профілів (а не з env) -- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke-перевірки Open WebUI -- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke-перевірка Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити прив’язаний тег image Open WebUI +- `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke-тесту Open WebUI +- `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити prompt перевірки nonce, який використовує smoke Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег образу Open WebUI -## Перевірка документації +## Перевірка коректності документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку якорів Mintlify, коли вам також потрібна перевірка заголовків у межах сторінки: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли потрібні також перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечно для CI) +## Офлайн-регресія (безпечна для CI) Це регресії «реального конвеєра» без реальних провайдерів: - Виклик інструментів Gateway (mock 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") +- Майстер 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`). -- End-to-end потоки майстра, які перевіряють обв’язку сеансу та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Наскрізні потоки майстра, які перевіряють wiring сесії та ефекти config (`src/gateway/gateway.test.ts`). -Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Прийняття рішень:** коли Skills перелічено в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/args? -- **Контракти workflow:** багатохідні сценарії, які перевіряють порядок інструментів, перенесення історії сеансу й межі sandbox. +- **Прийняття рішень:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? +- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує потрібні кроки/аргументи? +- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. -Майбутні eval-оцінювання мають залишатися спершу детермінованими: +Майбутні eval мають насамперед залишатися детермінованими: -- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і обв’язки сеансів. -- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, гейтінг, ін’єкція prompt). -- Необов’язкові live eval-оцінювання (за явним увімкненням, керовані env) лише після того, як буде готовий безпечний для CI набір. +- Runner сценаріїв, що використовує mock-провайдерів для перевірки викликів інструментів + порядку, читання skill-файлів і wiring сесії. +- Невеликий набір сценаріїв, сфокусованих на Skills (використовувати чи уникати, гейтінг, prompt injection). +- Необов’язкові live eval (за явним увімкненням, із гейтінгом через env) лише після того, як буде готовий безпечний для CI набір. -## Контрактні тести (форма plugin і channel) +## Контрактні тести (форма Plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму інтерфейсному контракту. Вони перебирають усі знайдені plugin і запускають набір -перевірок форми та поведінки. Типова unit-ланка `pnpm test` навмисно +Контрактні тести перевіряють, що кожен зареєстрований Plugin і channel відповідає +контракту свого інтерфейсу. Вони ітеруються по всіх виявлених plugins і запускають набір +перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтесь спільних поверхонь channel або provider. +коли торкаєтеся спільних поверхонь channel або provider. ### Команди @@ -1119,53 +1113,53 @@ image Open WebUI, а самому Open WebUI — завершити власне Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: -- **plugin** — базова форма plugin (id, name, capabilities) -- **setup** — контракт майстра налаштування -- **session-binding** — поведінка прив’язки сеансу -- **outbound-payload** — структура payload повідомлення -- **inbound** — обробка вхідних повідомлень -- **actions** — обробники дій channel -- **threading** — обробка ID thread -- **directory** — API directory/roster -- **group-policy** — застосування групової політики +- **plugin** - Базова форма Plugin (id, name, capabilities) +- **setup** - Контракт майстра налаштування +- **session-binding** - Поведінка прив’язування сесії +- **outbound-payload** - Структура payload повідомлення +- **inbound** - Обробка вхідних повідомлень +- **actions** - Обробники дій channel +- **threading** - Обробка ID thread +- **directory** - API каталогу/списку учасників +- **group-policy** - Забезпечення дотримання групових політик ### Контракти статусу provider Розташовані в `src/plugins/contracts/*.contract.test.ts`. -- **status** — probe-перевірки статусу channel -- **registry** — форма реєстру plugin +- **status** - Зонди статусу channel +- **registry** - Форма реєстру Plugin ### Контракти provider Розташовані в `src/plugins/contracts/*.contract.test.ts`: -- **auth** — контракт потоку автентифікації -- **auth-choice** — вибір/визначення автентифікації -- **catalog** — API каталогу моделей -- **discovery** — виявлення plugin -- **loader** — завантаження plugin -- **runtime** — runtime provider -- **shape** — форма/інтерфейс plugin -- **wizard** — майстер налаштування +- **auth** - Контракт потоку auth +- **auth-choice** - Вибір/селекція auth +- **catalog** - API каталогу моделей +- **discovery** - Виявлення Plugin +- **loader** - Завантаження Plugin +- **runtime** - Runtime provider +- **shape** - Форма/інтерфейс Plugin +- **wizard** - Майстер налаштування ### Коли запускати -- Після зміни export або subpath у plugin-sdk -- Після додавання або зміни plugin channel або provider -- Після рефакторингу реєстрації plugin або виявлення +- Після зміни export-ів або subpath у plugin-sdk +- Після додавання або зміни channel чи provider Plugin +- Після рефакторингу реєстрації або виявлення Plugin Контрактні тести запускаються в CI і не потребують реальних API-ключів. -## Додавання регресій (рекомендації) +## Додавання регресійних тестів (рекомендації) -Коли ви виправляєте проблему provider/model, виявлену під час live: +Коли ви виправляєте проблему provider/model, виявлену в live: -- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) -- Якщо це за своєю природою лише live-проблема (rate limit, політики автентифікації), залишайте live-тест вузьким і таким, що вмикається через env-змінні -- Намагайтеся цілити в найменший шар, який ловить помилку: - - помилка конвертації/повторного програвання запиту provider → тест прямих моделей - - помилка конвеєра gateway session/history/tool → gateway live smoke або безпечний для CI mock-тест gateway -- Захисне обмеження обходу SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів обходу відхиляються. - - Якщо ви додаєте нову сім’ю цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується з помилкою для некласифікованих target id, щоб нові класи не можна було тихо пропустити. +- Якщо можливо, додайте безпечну для CI регресію (mock/stub provider або захопіть точну трансформацію форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), зберігайте live-тест вузьким і таким, що вмикається через змінні env +- Намагайтеся націлюватися на найменший рівень, який виявляє помилку: + - помилка перетворення/повторного відтворення запиту provider → тест прямих моделей + - помилка конвеєра сесії/історії/інструментів gateway → smoke live gateway або безпечний для CI mock-тест gateway +- Захисний бар’єр обходу SecretRef: + - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef з метаданих реєстру (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегмента обходу відхиляються. + - Якщо ви додаєте нове сімейство цілей SecretRef `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно завершується помилкою для некласифікованих id цілей, щоб нові класи не можна було тихо пропустити. diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index d540f05d0..582fa1d80 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,389 +1,140 @@ --- read_when: - - Вам потрібно знати, з якого subpath SDK імпортувати】【”】【analysis to=final code_block=None ақәascii_fix_REASONING + - Потрібно знати, з якого підшляху SDK імпортувати - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - - Ви шукаєте конкретний export SDK + - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Import map, довідник API реєстрації та архітектура SDK +summary: Карта імпорту, довідник з API реєстрації та архітектура SDK title: Огляд Plugin SDK x-i18n: - generated_at: "2026-04-23T21:03:18Z" + generated_at: "2026-04-23T23:27:51Z" model: gpt-5.4 provider: openai - source_hash: efe676e4907428459ed3e30dd2e1df891eae0f0f1e87b0a850eb45140572a348 + source_hash: 7090e13508382a68988f3d345bf12d6f3822c499e01a3affb1fa7a277b22f276 source_path: plugins/sdk-overview.md workflow: 15 --- -Plugin SDK — це типізований контракт між Plugins і core. Ця сторінка є -довідником для **що імпортувати** і **що можна реєструвати**. +Plugin SDK — це типізований контракт між plugins і ядром. Ця сторінка — +довідник про **що імпортувати** і **що можна реєструвати**. Шукаєте натомість практичний посібник? -- Перший Plugin? Почніть з [Створення Plugins](/uk/plugins/building-plugins). -- Plugin каналу? Див. [Plugins каналів](/uk/plugins/sdk-channel-plugins). -- Plugin провайдера? Див. [Plugins провайдерів](/uk/plugins/sdk-provider-plugins). +- Перший plugin? Почніть із [Створення plugins](/uk/plugins/building-plugins). +- Channel plugin? Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). +- Provider plugin? Див. [Provider plugins](/uk/plugins/sdk-provider-plugins). ## Угода щодо імпорту -Завжди імпортуйте з конкретного subpath: +Завжди імпортуйте з конкретного підшляху: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; ``` -Кожен subpath — це невеликий самодостатній модуль. Це пришвидшує запуск і -запобігає проблемам із циклічними залежностями. Для entry/build helper-ів, специфічних для каналів, -віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для -ширшої umbrella-поверхні та спільних helper-ів, як-от +Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і +запобігає проблемам із циклічними залежностями. Для специфічних для channel +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої узагальненої поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. - Не імпортуйте provider- або channel-брендовані convenience-seam-и (наприклад + Не імпортуйте branded convenience seams для provider або channel (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані Plugins композують універсальні subpath-и SDK у власних barrel-файлах `api.ts` / - `runtime-api.ts`; споживачам core слід або використовувати ці plugin-local - barrel-и, або додавати вузький універсальний контракт SDK, коли потреба справді є + Вбудовані plugins компонують загальні підшляхи SDK у власних barrel-файлах `api.ts` / + `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для plugin + barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді є міжканальною. -Невеликий набір helper-seam-ів для bundled Plugin (`plugin-sdk/feishu`, -`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється у -згенерованій export map. Вони існують лише для супроводу bundled Plugin і -не рекомендуються як шляхи імпорту для нових сторонніх Plugins. +Невеликий набір допоміжних seams для вбудованих plugins (`plugin-sdk/feishu`, +`plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в +згенерованій карті експортів. Вони існують лише для підтримки вбудованих plugins і +не рекомендовані як шляхи імпорту для нових сторонніх plugins. -## Довідник subpath-ів +## Довідник підшляхів -Найуживаніші subpath-и, згруповані за призначенням. Згенерований повний список із -200+ subpath-ів міститься в `scripts/lib/plugin-sdk-entrypoints.json`; зарезервовані -helper-subpath-и bundled Plugin там теж присутні, але є деталлю реалізації, -якщо тільки якась сторінка документації явно не рекомендує їх. +Plugin SDK надається як набір вузьких підшляхів, згрупованих за областями (plugin +entry, channel, provider, auth, runtime, capability, memory і зарезервовані +допоміжні засоби для вбудованих plugins). Повний каталог — згрупований і з посиланнями — див. у +[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). -### Entry Plugin - -| Subpath | Key exports | -| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | -| `plugin-sdk/plugin-entry` | `definePluginEntry` | -| `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | -| `plugin-sdk/config-schema` | `OpenClawSchema` | -| `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/config-schema` | Root Zod-схема `openclaw.json` (`OpenClawSchema`) | - | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/setup` | Спільні helper-и setup wizard, prompts allowlist, builders статусу setup | - | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | - | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | - | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | - | `plugin-sdk/account-core` | Helper-и multi-account config/action-gate, helper-и fallback для default-account | - | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, helper-и нормалізації account-id | - | `plugin-sdk/account-resolution` | Lookup account + helper-и fallback до default | - | `plugin-sdk/account-helpers` | Вузькі helper-и list/action для account | - | `plugin-sdk/channel-pairing` | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | - | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Helper-и нормалізації/валідації кастомних команд Telegram з fallback до bundled-contract | - | `plugin-sdk/command-gating` | Вузькі helper-и authorization gate для команд | - | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, helper-и життєвого циклу/фіналізації draft stream | - | `plugin-sdk/inbound-envelope` | Спільні helper-и для побудови inbound route + envelope | - | `plugin-sdk/inbound-reply-dispatch` | Спільні helper-и для inbound record-and-dispatch | - | `plugin-sdk/messaging-targets` | Helper-и парсингу/зіставлення target | - | `plugin-sdk/outbound-media` | Спільні helper-и завантаження outbound media | - | `plugin-sdk/outbound-runtime` | Helper-и outbound identity, send delegate і планування payload | - | `plugin-sdk/poll-runtime` | Вузькі helper-и нормалізації poll | - | `plugin-sdk/thread-bindings-runtime` | Helper-и життєвого циклу та adapter для thread-binding | - | `plugin-sdk/agent-media-payload` | Застарілий builder media payload агента | - | `plugin-sdk/conversation-runtime` | Helper-и conversation/thread binding, pairing і configured-binding | - | `plugin-sdk/runtime-config-snapshot` | Helper runtime config snapshot | - | `plugin-sdk/runtime-group-policy` | Helper-и розв’язання runtime group-policy | - | `plugin-sdk/channel-status` | Спільні helper-и snapshot/summary статусу каналу | - | `plugin-sdk/channel-config-primitives` | Вузькі primitives схеми конфігурації каналу | - | `plugin-sdk/channel-config-writes` | Helper-и authorization для config-write каналу | - | `plugin-sdk/channel-plugin-common` | Спільні prelude-export-и Plugin каналу | - | `plugin-sdk/allowlist-config-edit` | Helper-и редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Спільні helper-и рішень щодо group-access | - | `plugin-sdk/direct-dm` | Спільні helper-и auth/guard для direct-DM | - | `plugin-sdk/interactive-runtime` | Semantic presentation повідомлень, доставка та helper-и застарілої interactive reply. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | - | `plugin-sdk/channel-inbound` | Compatibility barrel для inbound debounce, mention matching, helper-ів mention-policy та envelope | - | `plugin-sdk/channel-mention-gating` | Вузькі helper-и mention-policy без ширшої inbound runtime-поверхні | - | `plugin-sdk/channel-location` | Helper-и контексту й форматування location каналу | - | `plugin-sdk/channel-logging` | Helper-и логування каналу для inbound drop і збоїв typing/ack | - | `plugin-sdk/channel-send-result` | Типи результатів reply | - | `plugin-sdk/channel-actions` | Helper-и дій повідомлень каналу, а також застарілі helper-и native schema, збережені для сумісності Plugin | - | `plugin-sdk/channel-targets` | Helper-и парсингу/зіставлення target | - | `plugin-sdk/channel-contract` | Типи контракту каналу | - | `plugin-sdk/channel-feedback` | Wiring feedback/reaction | - | `plugin-sdk/channel-secret-runtime` | Вузькі helper-и secret-contract, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи secret target | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | - | `plugin-sdk/provider-setup` | Добірні helper-и setup для локальних/self-hosted провайдерів | - | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані helper-и setup для self-hosted провайдерів, сумісних з OpenAI | - | `plugin-sdk/cli-backend` | Типові значення CLI backend + константи watchdog | - | `plugin-sdk/provider-auth-runtime` | Helper-и runtime-розв’язання API-ключів для Plugin провайдерів | - | `plugin-sdk/provider-auth-api-key` | Helper-и onboarding/profile-write для API-ключів, такі як `upsertApiKeyProfile` | - | `plugin-sdk/provider-auth-result` | Стандартний builder результату OAuth auth | - | `plugin-sdk/provider-auth-login` | Спільні helper-и інтерактивного login для Plugin провайдерів | - | `plugin-sdk/provider-env-vars` | Helper-и пошуку env vars для auth провайдера | - | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | - | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и replay-policy, helper-и endpoint провайдерів і helper-и нормалізації model-id, такі як `normalizeNativeXaiModelId` | - | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-http` | Універсальні helper-и HTTP/endpoint capability для провайдерів, зокрема helper-и multipart form для транскрипції аудіо | - | `plugin-sdk/provider-web-fetch-contract` | Вузькі helper-и контракту config/selection для web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | - | `plugin-sdk/provider-web-fetch` | Helper-и реєстрації/cache/runtime для web-fetch провайдерів | - | `plugin-sdk/provider-web-search-config-contract` | Вузькі helper-и config/credential для web-search провайдерів, яким не потрібне ввімкнення Plugin у wiring | - | `plugin-sdk/provider-web-search-contract` | Вузькі helper-и контракту config/credential для web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig`, а також scoped setter/getter-и облікових даних | - | `plugin-sdk/provider-web-search` | Helper-и реєстрації/cache/runtime для web-search провайдерів | - | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схем Gemini + diagnostics і helper-и compat для xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | `fetchClaudeUsage` і подібні | - | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи stream wrapper і спільні helper-и wrapper для Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Native helper-и provider transport, такі як guarded fetch, transport message transforms і writable transport event streams | - | `plugin-sdk/provider-onboard` | Helper-и patch конфігурації onboarding | - | `plugin-sdk/global-singleton` | Helper-и process-local singleton/map/cache | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/command-auth` | `resolveControlCommandGate`, helper-и registry команд, helper-и авторизації відправника | - | `plugin-sdk/command-status` | Builder-и повідомлень command/help, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | - | `plugin-sdk/approval-auth-runtime` | Розв’язання approver і helper-и same-chat action-auth | - | `plugin-sdk/approval-client-runtime` | Native helper-и profile/filter для exec approval | - | `plugin-sdk/approval-delivery-runtime` | Native adapter-и capability/delivery для approval | - | `plugin-sdk/approval-gateway-runtime` | Спільний helper розв’язання approval gateway | - | `plugin-sdk/approval-handler-adapter-runtime` | Легкі helper-и завантаження native approval adapter для гарячих channel entrypoint | - | `plugin-sdk/approval-handler-runtime` | Ширші helper-и runtime для approval handler; віддавайте перевагу вужчим adapter/gateway seam-ам, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Native helper-и target + account-binding для approval | - | `plugin-sdk/approval-reply-runtime` | Helper-и reply payload для exec/plugin approval | - | `plugin-sdk/command-auth-native` | Native command auth + native helper-и session-target | - | `plugin-sdk/command-detection` | Спільні helper-и виявлення команд | - | `plugin-sdk/command-surface` | Helper-и нормалізації command-body і command-surface | - | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | - | `plugin-sdk/channel-secret-runtime` | Вузькі helper-и збирання secret-contract для secret-поверхонь channel/plugin | - | `plugin-sdk/secret-ref-runtime` | Вузькі helper-и `coerceSecretRef` і типізації SecretRef для парсингу secret-contract/config | - | `plugin-sdk/security-runtime` | Спільні helper-и trust, DM gating, external-content і збирання секретів | - | `plugin-sdk/ssrf-policy` | Helper-и allowlist хостів і SSRF policy для приватних мереж | - | `plugin-sdk/ssrf-dispatcher` | Вузькі helper-и pinned-dispatcher без широкої infra runtime-поверхні | - | `plugin-sdk/ssrf-runtime` | Helper-и pinned-dispatcher, SSRF-guarded fetch і SSRF policy | - | `plugin-sdk/secret-input` | Helper-и парсингу secret input | - | `plugin-sdk/webhook-ingress` | Helper-и request/target для webhook | - | `plugin-sdk/webhook-request-guards` | Helper-и розміру тіла запиту/timeout | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/runtime` | Широкі helper-и runtime/logging/backup/plugin-install | - | `plugin-sdk/runtime-env` | Вузькі helper-и runtime env, logger, timeout, retry і backoff | - | `plugin-sdk/channel-runtime-context` | Універсальні helper-и реєстрації та lookup runtime-context каналу | - | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | - | `plugin-sdk/plugin-runtime` | Спільні helper-и plugin command/hook/http/interactive | - | `plugin-sdk/hook-runtime` | Спільні helper-и pipeline webhook/internal hook | - | `plugin-sdk/lazy-runtime` | Helper-и lazy runtime import/binding, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Helper-и exec процесів | - | `plugin-sdk/cli-runtime` | Helper-и форматування, wait і version для CLI | - | `plugin-sdk/gateway-runtime` | Helper-и клієнта Gateway і patch channel-status | - | `plugin-sdk/config-runtime` | Helper-и load/write конфігурації та helper-и lookup plugin-config | - | `plugin-sdk/telegram-command-config` | Helper-и нормалізації name/description команд Telegram і перевірки duplicate/conflict, навіть коли поверхня bundled Telegram contract недоступна | - | `plugin-sdk/text-autolink-runtime` | Виявлення autolink для file-reference без широкого barrel `text-runtime` | - | `plugin-sdk/approval-runtime` | Helper-и exec/plugin approval, builder-и approval-capability, helper-и auth/profile, native routing/runtime | - | `plugin-sdk/reply-runtime` | Спільні inbound/reply runtime helper-и, chunking, dispatch, heartbeat, reply planner | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі helper-и dispatch/finalize для reply | - | `plugin-sdk/reply-history` | Спільні helper-и короткого вікна history для reply, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Вузькі helper-и chunking для text/markdown | - | `plugin-sdk/session-store-runtime` | Helper-и path + updated-at для session store | - | `plugin-sdk/state-paths` | Helper-и шляхів state/OAuth dir | - | `plugin-sdk/routing` | Helper-и route/session-key/account binding, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | - | `plugin-sdk/status-helpers` | Спільні helper-и summary статусу channel/account, типові значення runtime-state і helper-и metadata проблем | - | `plugin-sdk/target-resolver-runtime` | Спільні helper-и target resolver | - | `plugin-sdk/string-normalization-runtime` | Helper-и slug/string normalization | - | `plugin-sdk/request-url` | Витяг рядкових URL із fetch/request-подібних входів | - | `plugin-sdk/run-command` | Runner команд із timeout і нормалізованими результатами stdout/stderr | - | `plugin-sdk/param-readers` | Поширені readers параметрів tool/CLI | - | `plugin-sdk/tool-payload` | Витяг нормалізованих payload-ів із об’єктів результатів tool | - | `plugin-sdk/tool-send` | Витяг канонічних полів send target з аргументів tool | - | `plugin-sdk/temp-path` | Спільні helper-и шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Helper-и subsystem logger і redaction | - | `plugin-sdk/markdown-table-runtime` | Helper-и режиму Markdown table | - | `plugin-sdk/json-store` | Невеликі helper-и читання/запису JSON state | - | `plugin-sdk/file-lock` | Re-entrant helper-и file-lock | - | `plugin-sdk/persistent-dedupe` | Helper-и disk-backed dedupe cache | - | `plugin-sdk/acp-runtime` | Helper-и ACP runtime/session і reply-dispatch | - | `plugin-sdk/acp-binding-resolve-runtime` | Read-only розв’язання ACP binding без import-ів startup lifecycle | - | `plugin-sdk/agent-config-primitives` | Вузькі primitives схеми конфігурації agent runtime | - | `plugin-sdk/boolean-param` | Loose reader boolean-параметрів | - | `plugin-sdk/dangerous-name-runtime` | Helper-и розв’язання dangerous-name matching | - | `plugin-sdk/device-bootstrap` | Helper-и device bootstrap і pairing token | - | `plugin-sdk/extension-shared` | Спільні primitives helper-ів passive-channel, status і ambient proxy | - | `plugin-sdk/models-provider-runtime` | Helper-и відповідей `/models` command/provider | - | `plugin-sdk/skill-commands-runtime` | Helper-и переліку команд Skill | - | `plugin-sdk/native-command-registry` | Helper-и registry/build/serialize для native команд | - | `plugin-sdk/agent-harness` | Експериментальна trusted-plugin-поверхня для низькорівневих harness агента: типи harness, helper-и steer/abort для active-run, helper-и bridge інструментів OpenClaw і утиліти результатів спроб | - | `plugin-sdk/provider-zai-endpoint` | Helper-и виявлення endpoint Z.AI | - | `plugin-sdk/infra-runtime` | Helper-и system event/heartbeat | - | `plugin-sdk/collection-runtime` | Невеликі helper-и bounded cache | - | `plugin-sdk/diagnostic-runtime` | Helper-и діагностичних прапорців і подій | - | `plugin-sdk/error-runtime` | Helper-и graph/formatting/error classification, `isApprovalNotFoundError` | - | `plugin-sdk/fetch-runtime` | Helper-и wrapped fetch, proxy і pinned lookup | - | `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без import-ів proxy/guarded-fetch | - | `plugin-sdk/response-limit-runtime` | Reader обмеженого response-body без широкої media runtime-поверхні | - | `plugin-sdk/session-binding-runtime` | Поточний стан conversation binding без configured binding routing або pairing store | - | `plugin-sdk/session-store-runtime` | Helper-и читання session-store без широких import-ів config writes/maintenance | - | `plugin-sdk/context-visibility-runtime` | Розв’язання context visibility і фільтрація supplemental context без широких import-ів config/security | - | `plugin-sdk/string-coerce-runtime` | Вузькі helper-и coercion і normalization для primitive record/string без import-ів markdown/logging | - | `plugin-sdk/host-runtime` | Helper-и нормалізації hostname і SCP host | - | `plugin-sdk/retry-runtime` | Helper-и конфігурації retry і retry runner | - | `plugin-sdk/agent-runtime` | Helper-и agent dir/identity/workspace | - | `plugin-sdk/directory-runtime` | Query/dedup directory на основі config | - | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/media-runtime` | Спільні helper-и fetch/transform/store для media плюс builder-и media payload | - | `plugin-sdk/media-generation-runtime` | Спільні helper-и failover для media-generation, вибір кандидатів і повідомлення про відсутню модель | - | `plugin-sdk/media-understanding` | Типи провайдерів media understanding плюс provider-facing export-и helper-ів image/audio | - | `plugin-sdk/text-runtime` | Спільні helper-и text/markdown/logging, такі як assistant-visible-text stripping, helper-и render/chunking/table для markdown, helper-и redaction, helper-и directive-tag і safe-text utilities | - | `plugin-sdk/text-chunking` | Helper chunking для outbound text | - | `plugin-sdk/speech` | Типи speech provider плюс provider-facing helper-и directive, registry і validation | - | `plugin-sdk/speech-core` | Спільні типи speech provider, registry, directive і helper-и normalization | - | `plugin-sdk/realtime-transcription` | Типи провайдерів realtime transcription, helper-и registry і спільний helper WebSocket session | - | `plugin-sdk/realtime-voice` | Типи провайдерів realtime voice і helper-и registry | - | `plugin-sdk/image-generation` | Типи провайдерів image generation | - | `plugin-sdk/image-generation-core` | Спільні типи image-generation, helper-и failover, auth і registry | - | `plugin-sdk/music-generation` | Типи provider/request/result для music generation | - | `plugin-sdk/music-generation-core` | Спільні типи music-generation, helper-и failover, lookup провайдерів і парсинг model-ref | - | `plugin-sdk/video-generation` | Типи provider/request/result для video generation | - | `plugin-sdk/video-generation-core` | Спільні типи video-generation, helper-и failover, lookup провайдерів і парсинг model-ref | - | `plugin-sdk/webhook-targets` | Реєстр webhook target і helper-и встановлення route | - | `plugin-sdk/webhook-path` | Helper-и нормалізації webhook path | - | `plugin-sdk/web-media` | Спільні helper-и завантаження віддалених/локальних media | - | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів plugin SDK | - | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | - - - - | Subpath | Key exports | - | --- | --- | - | `plugin-sdk/memory-core` | Вбудована helper-поверхня memory-core для helper-ів manager/config/file/CLI | - | `plugin-sdk/memory-core-engine-runtime` | Runtime facade індексації/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Export-и foundation engine для memory host | - | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding для memory host, доступ до registry, локальний provider і універсальні helper-и batch/remote | - | `plugin-sdk/memory-core-host-engine-qmd` | Export-и QMD engine для memory host | - | `plugin-sdk/memory-core-host-engine-storage` | Export-и storage engine для memory host | - | `plugin-sdk/memory-core-host-multimodal` | Multimodal helper-и для memory host | - | `plugin-sdk/memory-core-host-query` | Query helper-и для memory host | - | `plugin-sdk/memory-core-host-secret` | Secret helper-и для memory host | - | `plugin-sdk/memory-core-host-events` | Helper-и journal подій для memory host | - | `plugin-sdk/memory-core-host-status` | Helper-и status для memory host | - | `plugin-sdk/memory-core-host-runtime-cli` | Helper-и CLI runtime для memory host | - | `plugin-sdk/memory-core-host-runtime-core` | Базові helper-и runtime для memory host | - | `plugin-sdk/memory-core-host-runtime-files` | Helper-и file/runtime для memory host | - | `plugin-sdk/memory-host-core` | Vendor-neutral alias для базових helper-ів runtime memory host | - | `plugin-sdk/memory-host-events` | Vendor-neutral alias для helper-ів journal подій memory host | - | `plugin-sdk/memory-host-files` | Vendor-neutral alias для helper-ів file/runtime memory host | - | `plugin-sdk/memory-host-markdown` | Спільні helper-и managed-markdown для plugin-ів, суміжних із пам’яттю | - | `plugin-sdk/memory-host-search` | Active Memory runtime facade для доступу до search-manager | - | `plugin-sdk/memory-host-status` | Vendor-neutral alias для helper-ів status memory host | - | `plugin-sdk/memory-lancedb` | Вбудована helper-поверхня memory-lancedb | - - - - | Family | Current subpaths | Intended use | - | --- | --- | --- | - | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Helper-и підтримки bundled browser Plugin (`browser-support` залишається compatibility barrel) | - | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Helper/runtime-поверхня bundled Matrix | - | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Helper/runtime-поверхня bundled LINE | - | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Helper-поверхня bundled IRC | - | Channel-specific helpers | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Compatibility/helper seam-и bundled channel | - | Auth/plugin-specific helpers | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Helper seam-и bundled feature/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | - - +Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Callback `register(api)` отримує об’єкт `OpenClawPluginApi` з такими +Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей -| Method | What it registers | -| ------------------------------------------------ | ------------------------------------- | -| `api.registerProvider(...)` | Текстове виведення (LLM) | -| `api.registerAgentHarness(...)` | Експериментальний низькорівневий executor агента | -| `api.registerCliBackend(...)` | Локальний inference backend CLI | -| `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Text-to-speech / STT synthesis | -| `api.registerRealtimeTranscriptionProvider(...)` | Потокова realtime-транскрипція | -| `api.registerRealtimeVoiceProvider(...)` | Двосторонні realtime-голосові сесії | -| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | -| `api.registerImageGenerationProvider(...)` | Генерація зображень | -| `api.registerMusicGenerationProvider(...)` | Генерація музики | -| `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | -| `api.registerWebSearchProvider(...)` | Web search | +| Метод | Що він реєструє | +| ------------------------------------------------ | -------------------------------------- | +| `api.registerProvider(...)` | Текстовий inference (LLM) | +| `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | +| `api.registerCliBackend(...)` | Локальний backend inference для CLI | +| `api.registerChannel(...)` | Канал обміну повідомленнями | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | +| `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сесії в реальному часі | +| `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | +| `api.registerImageGenerationProvider(...)` | Генерація зображень | +| `api.registerMusicGenerationProvider(...)` | Генерація музики | +| `api.registerVideoGenerationProvider(...)` | Генерація відео | +| `api.registerWebFetchProvider(...)` | Provider для отримання / скрапінгу вебданих | +| `api.registerWebSearchProvider(...)` | Вебпошук | ### Інструменти та команди -| Method | What it registers | -| ------------------------------- | --------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------- | -------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацька команда (оминає LLM) | ### Інфраструктура -| Method | What it registers | -| ----------------------------------------------- | --------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Event hook | -| `api.registerHttpRoute(params)` | HTTP endpoint Gateway | -| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerCli(registrar, opts?)` | Підкоманда CLI | -| `api.registerService(service)` | Фоновий сервіс | -| `api.registerInteractiveHandler(registration)` | Interactive handler | -| `api.registerEmbeddedExtensionFactory(factory)` | Extension factory для embedded-runner Pi | -| `api.registerMemoryPromptSupplement(builder)` | Additive prompt section, суміжна з пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Additive corpus для пошуку/читання пам’яті | +| Метод | Що він реєструє | +| ----------------------------------------------- | ---------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Хук події | +| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway | +| `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | +| `api.registerCli(registrar, opts?)` | Підкоманда CLI | +| `api.registerService(service)` | Фоновий сервіс | +| `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | +| `api.registerEmbeddedExtensionFactory(factory)` | Фабрика extension для вбудованого runner у Pi | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | - Зарезервовані core admin namespace-и (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити - для методу Gateway вужчу scope. Для методів, якими володіє Plugin, віддавайте перевагу префіксам, специфічним для Plugin. + Зарезервовані простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) завжди залишаються `operator.admin`, навіть якщо plugin намагається призначити + вужчу область для методу Gateway. Для методів, що належать plugin, віддавайте перевагу префіксам, специфічним для plugin. - Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли Plugin потребує Pi-native - часової семантики подій під час embedded-запусків OpenClaw — наприклад асинхронних переписувань `tool_result`, які мають відбутися до того, як буде надіслано фінальне повідомлення з результатом інструмента. + Використовуйте `api.registerEmbeddedExtensionFactory(...)`, коли plugin потребує Pi-native + синхронізації подій під час вбудованих запусків OpenClaw — наприклад, для асинхронних переписувань `tool_result`, + які мають відбутися до того, як буде надіслано фінальне повідомлення з результатом інструмента. -Наразі це seam для bundled Plugin: лише bundled Plugins можуть реєструвати його, -і вони мають оголошувати `contracts.embeddedExtensionFactories: ["pi"]` у -`openclaw.plugin.json`. Для всього, що не потребує цього нижчого рівня seam, залишайте звичайні hooks Plugin OpenClaw. +Сьогодні це seam для вбудованих plugins: лише вбудовані plugins можуть реєструвати такий, +і вони мають оголосити `contracts.embeddedExtensionFactories: ["pi"]` у + `openclaw.plugin.json`. Для всього, що не потребує цього низькорівневого seam, використовуйте звичайні хуки plugin OpenClaw. -### Metadata реєстрації CLI +### Метадані реєстрації CLI -`api.registerCli(registrar, opts?)` приймає два види top-level metadata: +`api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: -- `commands`: явні корені команд, якими володіє registrar -- `descriptors`: parse-time descriptor-и команд, які використовуються для root CLI help, - routing і lazy-реєстрації CLI Plugin +- `commands`: явні корені команд, що належать реєстратору +- `descriptors`: дескриптори команд на етапі розбору, що використовуються для довідки кореневого CLI, + маршрутизації та лінивої реєстрації CLI plugin -Якщо ви хочете, щоб команда Plugin залишалася lazy-loaded у звичайному root CLI path, -надайте `descriptors`, які покривають кожен top-level command root, відкритий цим -registrar. +Якщо ви хочете, щоб команда plugin залишалася ліниво завантажуваною в звичайному шляху кореневого CLI, +надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, доступний через цей +реєстратор. ```typescript api.registerCli( @@ -395,7 +146,7 @@ api.registerCli( descriptors: [ { name: "matrix", - description: "Manage Matrix accounts, verification, devices, and profile state", + description: "Керування обліковими записами Matrix, верифікацією, пристроями та станом профілю", hasSubcommands: true, }, ], @@ -403,140 +154,139 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, коли вам не потрібна lazy-реєстрація в root CLI. -Цей eager-шлях сумісності все ще підтримується, але він не встановлює -placeholders на основі descriptor-ів для parse-time lazy loading. +Використовуйте лише `commands`, тільки якщо вам не потрібна лінива реєстрація кореневого CLI. +Цей eager-сумісний шлях залишається підтримуваним, але він не встановлює +плейсхолдери на основі descriptor для лінивого завантаження на етапі розбору. -### Реєстрація CLI backend +### Реєстрація backend для CLI -`api.registerCliBackend(...)` дозволяє Plugin володіти типовою конфігурацією для локального +`api.registerCliBackend(...)` дає змогу plugin володіти типовою конфігурацією для локального backend AI CLI, такого як `codex-cli`. -- `id` backend-а стає префіксом provider у model ref на кшталт `codex-cli/gpt-5`. -- `config` backend-а використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Користувацька конфігурація все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх - типових значень Plugin перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує суміснісних переписувань після merge - (наприклад нормалізації старих форм flags). +- `id` backend стає префіксом provider у посиланнях на моделі, як-от `codex-cli/gpt-5`. +- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + типового значення plugin перед запуском CLI. +- Використовуйте `normalizeConfig`, коли backend потребує сумісних переписувань після об’єднання + (наприклад, нормалізації старих форм прапорців). -### Exclusive slots +### Ексклюзивні слоти -| Method | What it registers | +| Метод | Що він реєструє | | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (активним може бути лише один). Callback `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до prompt. | -| `api.registerMemoryCapability(capability)` | Уніфікована memory capability | -| `api.registerMemoryPromptSection(builder)` | Builder prompt section для пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Resolver плану flush для пам’яті | -| `api.registerMemoryRuntime(runtime)` | Adapter runtime для пам’яті | +| `api.registerContextEngine(id, factory)` | Механізм контексту (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб механізм міг налаштовувати додавання до prompt. | +| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt для пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Resolver плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | -### Adapters embedding для пам’яті +### Адаптери embedding для пам’яті -| Method | What it registers | -| ---------------------------------------------- | ---------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Adapter embedding для пам’яті активного Plugin | +| Метод | Що він реєструє | +| ---------------------------------------------- | ----------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного plugin | -- `registerMemoryCapability` — це рекомендований exclusive API memory-plugin. -- `registerMemoryCapability` також може відкривати `publicArtifacts.listArtifacts(...)`, - щоб companion Plugins могли споживати експортовані memory artifacts через - `openclaw/plugin-sdk/memory-host-core` замість доступу до приватної розкладки конкретного - Plugin пам’яті. +- `registerMemoryCapability` — це пріоритетний API ексклюзивного plugin пам’яті. +- `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, + щоб супутні plugins могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури + конкретного plugin пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні з legacy exclusive API memory-plugin. -- `registerMemoryEmbeddingProvider` дозволяє активному Plugin пам’яті реєструвати один - або більше id embedding-adapter-ів (наприклад `openai`, `gemini` або custom - id, визначений Plugin). -- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і - `agents.defaults.memorySearch.fallback`, розв’язується відносно цих зареєстрованих - id adapter-ів. + `registerMemoryRuntime` — це legacy-сумісні API ексклюзивного plugin пам’яті. +- `registerMemoryEmbeddingProvider` дозволяє активному plugin пам’яті реєструвати один + або кілька id адаптерів embedding (наприклад, `openai`, `gemini` або кастомний id, визначений plugin). +- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і + `agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими + id адаптерів. ### Події та життєвий цикл -| Method | What it does | -| -------------------------------------------- | ----------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | -| `api.onConversationBindingResolved(handler)` | Callback прив’язки conversation | +| Метод | Що він робить | +| -------------------------------------------- | -------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | +| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | -### Семантика рішень hook +### Семантика рішень хуків -- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. -- `before_tool_call`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як override. -- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. -- `before_install`: повернення `{ block: false }` трактується як відсутність рішення (так само, як і пропуск `block`), а не як override. -- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який handler бере на себе dispatch, handler-и нижчого пріоритету та типовий шлях model dispatch пропускаються. -- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який handler встановлює це значення, handler-и нижчого пріоритету пропускаються. -- `message_sending`: повернення `{ cancel: false }` трактується як відсутність рішення (так само, як і пропуск `cancel`), а не як override. -- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна inbound-маршрутизація thread/topic. `metadata` залишайте для channel-specific extra-даних. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж використовувати fallback до channel-specific `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для startup-стану, яким володіє Gateway, замість покладання на внутрішні hooks `gateway:startup`. +- `before_tool_call`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_tool_call`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. +- `before_install`: повернення `{ block: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `before_install`: повернення `{ block: false }` розглядається як відсутність рішення (так само, як пропуск `block`), а не як перевизначення. +- `reply_dispatch`: повернення `{ handled: true, ... }` є термінальним. Щойно будь-який обробник бере на себе dispatch, обробники з нижчим пріоритетом і типовий шлях dispatch моделі пропускаються. +- `message_sending`: повернення `{ cancel: true }` є термінальним. Щойно будь-який обробник встановлює його, обробники з нижчим пріоритетом пропускаються. +- `message_sending`: повернення `{ cancel: false }` розглядається як відсутність рішення (так само, як пропуск `cancel`), а не як перевизначення. +- `message_received`: використовуйте типізоване поле `threadId`, коли вам потрібна маршрутизація вхідних thread/topic. `metadata` залишайте для extras, специфічних для channel. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж переходити до `metadata`, специфічних для channel. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні хуки `gateway:startup`. ### Поля об’єкта API -| Field | Type | Description | +| Поле | Тип | Опис | | ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | ID Plugin | -| `api.name` | `string` | Display name | -| `api.version` | `string?` | Версія Plugin (необов’язково) | -| `api.description` | `string?` | Опис Plugin (необов’язково) | -| `api.source` | `string` | Шлях до джерела Plugin | -| `api.rootDir` | `string?` | Кореневий каталог Plugin (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний snapshot конфігурації (активний runtime snapshot у пам’яті, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація Plugin з `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Helper-и runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Logger з обмеженою областю (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/setup до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Розв’язати шлях відносно кореня Plugin | +| `api.id` | `string` | Ідентифікатор plugin | +| `api.name` | `string` | Відображувана назва | +| `api.version` | `string?` | Версія plugin (необов’язково) | +| `api.description` | `string?` | Опис plugin (необов’язково) | +| `api.source` | `string` | Шлях до джерела plugin | +| `api.rootDir` | `string?` | Кореневий каталог plugin (необов’язково) | +| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний внутрішній знімок runtime, коли доступний) | +| `api.pluginConfig` | `Record` | Конфігурація, специфічна для plugin, з `plugins.entries..config` | +| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | +| `api.logger` | `PluginLogger` | Logger з областю видимості (`debug`, `info`, `warn`, `error`) | +| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це полегшене вікно запуску/налаштування до повного entry | +| `api.resolvePath(input)` | `(string) => string` | Визначити шлях відносно кореня plugin | -## Угода щодо внутрішніх модулів +## Внутрішня угода щодо модулів -Усередині вашого Plugin використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: -```text +``` my-plugin/ - api.ts # Public exports for external consumers - runtime-api.ts # Internal-only runtime exports - index.ts # Plugin entry point - setup-entry.ts # Lightweight setup-only entry (optional) + api.ts # Публічні експорти для зовнішніх споживачів + runtime-api.ts # Експорти runtime лише для внутрішнього використання + index.ts # Точка входу plugin + setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний Plugin через `openclaw/plugin-sdk/` - з production-коду. Маршрутизуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` + з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Facade-loaded публічні поверхні bundled Plugin (`api.ts`, `runtime-api.ts`, -`index.ts`, `setup-entry.ts` та подібні публічні entry-файли) віддають перевагу -активному runtime snapshot конфігурації, коли OpenClaw уже запущено. Якщо runtime -snapshot ще не існує, вони використовують fallback до розв’язаного файла конфігурації на диску. +Публічні поверхні вбудованих plugins, завантажувані через facade (`api.ts`, `runtime-api.ts`, +`index.ts`, `setup-entry.ts` та подібні публічні entry-файли), надають перевагу +активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до визначеного файлу конфігурації на диску. -Plugins провайдерів можуть відкривати вузький plugin-local contract barrel, коли -helper навмисно є provider-specific і поки що не належить до універсального SDK -subpath. Приклади вбудованих: +Plugins provider можуть надавати вузький локальний для plugin barrel контракту, коли +певний допоміжний засіб навмисно є специфічним для provider і ще не належить до загального підшляху SDK. +Приклади вбудованих: - **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для Claude - beta-header і stream-helper-ів `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и провайдера, - helper-и типових моделей і builder-и realtime provider. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера - плюс helper-и onboarding/config. + beta-header і допоміжних засобів потоку `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує builder-и provider, + допоміжні засоби для типових моделей і builder-и provider для realtime. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder provider + разом із допоміжними засобами для onboarding/конфігурації. Production-код extension також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо helper справді є спільним, підніміть його до нейтрального SDK subpath, + Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - capability-орієнтованої поверхні, замість того щоб жорстко зв’язувати два Plugins між собою. + поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins між собою. -## Пов’язане +## Пов’язані матеріали - Параметри `definePluginEntry` і `defineChannelPluginEntry`. + Опції `definePluginEntry` і `defineChannelPluginEntry`. - + Повний довідник простору імен `api.runtime`. - + Пакування, маніфести та схеми конфігурації. @@ -545,7 +295,7 @@ subpath. Приклади вбудованих: Міграція із застарілих поверхонь. - - Глибока архітектура та модель можливостей. + + Поглиблена архітектура та модель можливостей. diff --git a/docs/uk/plugins/sdk-subpaths.md b/docs/uk/plugins/sdk-subpaths.md new file mode 100644 index 000000000..0d0044572 --- /dev/null +++ b/docs/uk/plugins/sdk-subpaths.md @@ -0,0 +1,280 @@ +--- +read_when: + - Вибір правильного підшляху plugin-sdk для імпорту Plugin + - Аудит підшляхів bundled-plugin і допоміжних поверхонь +summary: 'Каталог підшляхів Plugin SDK: які імпорти де розташовані, згруповано за областями' +title: Підшляхи Plugin SDK +x-i18n: + generated_at: "2026-04-23T23:27:47Z" + model: gpt-5.4 + provider: openai + source_hash: b0a1d4c2e2d4af147a21716e5240cb3be35ccde9f1d8dea3fc98ae87d3e6ca40 + source_path: plugins/sdk-subpaths.md + workflow: 15 +--- + + SDK Plugin доступний як набір вузьких підшляхів у `openclaw/plugin-sdk/`. + На цій сторінці наведено каталог найуживаніших підшляхів, згрупованих за призначенням. Згенерований + повний список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`; + зарезервовані допоміжні підшляхи bundled-plugin також наведено там, але вони є деталями + реалізації, якщо лише сторінка документації явно не просуває їх. + + Посібник з розробки Plugin див. у [Огляд SDK Plugin](/uk/plugins/sdk-overview). + + ## Точка входу Plugin + + | Підшлях | Ключові експорти | + | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | + | `plugin-sdk/plugin-entry` | `definePluginEntry` | + | `plugin-sdk/core` | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` | + | `plugin-sdk/config-schema` | `OpenClawSchema` | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/channel-core` | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/config-schema` | Експорт кореневої Zod-схеми `openclaw.json` (`OpenClawSchema`) | + | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | + | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування, запити allowlist, збирачі статусу налаштування | + | `plugin-sdk/setup-runtime` | `createPatchedAccountSetupAdapter`, `createEnvPatchedAccountSetupAdapter`, `createSetupInputPresenceValidator`, `noteChannelLookupFailure`, `noteChannelLookupSummary`, `promptResolvedAllowFrom`, `splitSetupEntries`, `createAllowlistSetupWizardProxy`, `createDelegatedSetupWizardProxy` | + | `plugin-sdk/setup-adapter-runtime` | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Допоміжні засоби для багатокористувацької конфігурації/керування шлюзами дій, допоміжні засоби резервного вибору облікового запису за замовчуванням | + | `plugin-sdk/account-id` | `DEFAULT_ACCOUNT_ID`, допоміжні засоби нормалізації id облікового запису | + | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису та резервного вибору за замовчуванням | + | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби для списку облікових записів/дій з обліковими записами | + | `plugin-sdk/channel-pairing` | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` | + | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` | + | `plugin-sdk/channel-config-schema` | Типи схеми конфігурації каналу | + | `plugin-sdk/telegram-command-config` | Допоміжні засоби нормалізації/перевірки власних команд Telegram із резервним використанням bundled-contract | + | `plugin-sdk/command-gating` | Вузькі допоміжні засоби шлюзування авторизації команд | + | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` | + | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink`, допоміжні засоби життєвого циклу/фіналізації чернеткового потоку | + | `plugin-sdk/inbound-envelope` | Спільні допоміжні засоби маршрутизації вхідних повідомлень і побудови envelope | + | `plugin-sdk/inbound-reply-dispatch` | Спільні допоміжні засоби запису та диспетчеризації вхідних відповідей | + | `plugin-sdk/messaging-targets` | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Спільні допоміжні засоби завантаження вихідних медіа | + | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідної ідентичності, делегування надсилання та планування payload | + | `plugin-sdk/poll-runtime` | Вузькі допоміжні засоби нормалізації опитувань | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби життєвого циклу прив’язок потоків і адаптера | + | `plugin-sdk/agent-media-payload` | Застарілий конструктор payload медіа агента | + | `plugin-sdk/conversation-runtime` | Допоміжні засоби прив’язки розмов/потоків, pairing і налаштованих прив’язок | + | `plugin-sdk/runtime-config-snapshot` | Допоміжний засіб знімка конфігурації середовища виконання | + | `plugin-sdk/runtime-group-policy` | Допоміжні засоби визначення групової політики середовища виконання | + | `plugin-sdk/channel-status` | Спільні допоміжні засоби знімка/підсумку стану каналу | + | `plugin-sdk/channel-config-primitives` | Вузькі примітиви схеми конфігурації каналу | + | `plugin-sdk/channel-config-writes` | Допоміжні засоби авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільні прелюдні експорти Plugin каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Спільні допоміжні засоби ухвалення рішень щодо групового доступу | + | `plugin-sdk/direct-dm` | Спільні допоміжні засоби auth/guard для прямих DM | + | `plugin-sdk/interactive-runtime` | Семантичне представлення повідомлень, доставка та застарілі допоміжні засоби інтерактивних відповідей. Див. [Представлення повідомлень](/uk/plugins/message-presentation) | + | `plugin-sdk/channel-inbound` | Barrel сумісності для debounce вхідних повідомлень, зіставлення згадок, допоміжних засобів політики згадок і допоміжних засобів envelope | + | `plugin-sdk/channel-mention-gating` | Вузькі допоміжні засоби політики згадок без ширшої поверхні вхідного runtime | + | `plugin-sdk/channel-location` | Допоміжні засоби контексту й форматування розташування каналу | + | `plugin-sdk/channel-logging` | Допоміжні засоби журналювання каналу для відкидання вхідних повідомлень і збоїв typing/ack | + | `plugin-sdk/channel-send-result` | Типи результату відповіді | + | `plugin-sdk/channel-actions` | Допоміжні засоби дій з повідомленнями каналу, а також застарілі допоміжні засоби нативної схеми, збережені для сумісності Plugin | + | `plugin-sdk/channel-targets` | Допоміжні засоби розбору/зіставлення цілей | + | `plugin-sdk/channel-contract` | Типи контракту каналу | + | `plugin-sdk/channel-feedback` | Підключення feedback/reaction | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби секретних контрактів, такі як `collectSimpleChannelFieldAssignments`, `getChannelSurface`, `pushAssignment`, і типи цілей секретів | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/provider-entry` | `defineSingleProviderPluginEntry` | + | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted провайдера | + | `plugin-sdk/self-hosted-provider-setup` | Сфокусовані допоміжні засоби налаштування self-hosted провайдера, сумісного з OpenAI | + | `plugin-sdk/cli-backend` | Значення CLI backend за замовчуванням і константи watchdog | + | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби визначення API-ключів у runtime для Plugin провайдерів | + | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби онбордингу API-ключів/запису профілів, такі як `upsertApiKeyProfile` | + | `plugin-sdk/provider-auth-result` | Стандартний конструктор результату OAuth auth | + | `plugin-sdk/provider-auth-login` | Спільні допоміжні засоби інтерактивного входу для Plugin провайдерів | + | `plugin-sdk/provider-env-vars` | Допоміжні засоби пошуку змінних середовища auth провайдера | + | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile`, `upsertApiKeyProfile`, `writeOAuthCredentials` | + | `plugin-sdk/provider-model-shared` | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політики replay, допоміжні засоби endpoint провайдерів і допоміжні засоби нормалізації id моделей, такі як `normalizeNativeXaiModelId` | + | `plugin-sdk/provider-catalog-shared` | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-http` | Загальні допоміжні засоби HTTP/можливостей endpoint провайдера, зокрема допоміжні засоби multipart form для аудіотранскрипції | + | `plugin-sdk/provider-web-fetch-contract` | Вузькі допоміжні засоби контракту конфігурації/вибору web-fetch, такі як `enablePluginInConfig` і `WebFetchProviderPlugin` | + | `plugin-sdk/provider-web-fetch` | Допоміжні засоби реєстрації/кешування провайдера web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Вузькі допоміжні засоби конфігурації/облікових даних web-search для провайдерів, яким не потрібне підключення увімкнення Plugin | + | `plugin-sdk/provider-web-search-contract` | Вузькі допоміжні засоби контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні засоби реєстрації/кешування/runtime провайдера web-search | + | `plugin-sdk/provider-tools` | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini й діагностика, а також допоміжні засоби сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | `fetchClaudeUsage` та подібні | + | `plugin-sdk/provider-stream` | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту нативного провайдера, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій транспорту, доступні для запису | + | `plugin-sdk/provider-onboard` | Допоміжні засоби патчів конфігурації онбордингу | + | `plugin-sdk/global-singleton` | Допоміжні засоби process-local singleton/map/cache | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/command-auth` | `resolveControlCommandGate`, допоміжні засоби реєстру команд, допоміжні засоби авторизації відправника | + | `plugin-sdk/command-status` | Конструктори повідомлень команд/довідки, такі як `buildCommandsMessagePaginated` і `buildHelpMessage` | + | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби визначення схвалювача та auth дій у межах того самого чату | + | `plugin-sdk/approval-client-runtime` | Допоміжні засоби профілю/фільтра нативного схвалення exec | + | `plugin-sdk/approval-delivery-runtime` | Адаптери нативної можливості/доставки схвалення | + | `plugin-sdk/approval-gateway-runtime` | Спільний допоміжний засіб визначення Gateway схвалення | + | `plugin-sdk/approval-handler-adapter-runtime` | Полегшені допоміжні засоби завантаження адаптера нативного схвалення для гарячих точок входу каналу | + | `plugin-sdk/approval-handler-runtime` | Ширші допоміжні засоби runtime обробника схвалення; віддавайте перевагу вужчим швам adapter/gateway, якщо їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні засоби нативної цілі схвалення та прив’язки облікового запису | + | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби payload відповіді для схвалення exec/plugin | + | `plugin-sdk/command-auth-native` | Нативний auth команд і допоміжні засоби нативної цілі сесії | + | `plugin-sdk/command-detection` | Спільні допоміжні засоби виявлення команд | + | `plugin-sdk/command-surface` | Допоміжні засоби нормалізації тіла команди та поверхні команди | + | `plugin-sdk/allow-from` | `formatAllowFromLowercase` | + | `plugin-sdk/channel-secret-runtime` | Вузькі допоміжні засоби збирання секретних контрактів для поверхонь секретів каналу/plugin | + | `plugin-sdk/secret-ref-runtime` | Вузькі допоміжні засоби `coerceSecretRef` і типізації SecretRef для розбору secret-contract/config | + | `plugin-sdk/security-runtime` | Спільні допоміжні засоби довіри, шлюзування DM, зовнішнього вмісту та збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF для allowlist хостів і приватних мереж | + | `plugin-sdk/ssrf-dispatcher` | Вузькі допоміжні засоби pinned-dispatcher без широкої поверхні infra runtime | + | `plugin-sdk/ssrf-runtime` | Допоміжні засоби pinned-dispatcher, fetch із захистом SSRF і політики SSRF | + | `plugin-sdk/secret-input` | Допоміжні засоби розбору введення секретів | + | `plugin-sdk/webhook-ingress` | Допоміжні засоби запиту/цілі Webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні засоби розміру тіла запиту/тайм-аутів | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime/журналювання/резервного копіювання/встановлення plugin | + | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби env runtime, logger, timeout, retry і backoff | + | `plugin-sdk/channel-runtime-context` | Загальні допоміжні засоби реєстрації та пошуку runtime-контексту каналу | + | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби команд/hooks/http/interactive для plugin | + | `plugin-sdk/hook-runtime` | Спільні допоміжні засоби конвеєра webhook/внутрішніх hook | + | `plugin-sdk/lazy-runtime` | Допоміжні засоби ледачого імпорту/прив’язки runtime, такі як `createLazyRuntimeModule`, `createLazyRuntimeMethod` і `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні засоби виконання процесів | + | `plugin-sdk/cli-runtime` | Допоміжні засоби форматування CLI, очікування та версій | + | `plugin-sdk/gateway-runtime` | Допоміжні засоби клієнта Gateway і патчів стану каналу | + | `plugin-sdk/config-runtime` | Допоміжні засоби завантаження/запису конфігурації та пошуку конфігурації plugin | + | `plugin-sdk/telegram-command-config` | Нормалізація назв/описів команд Telegram і перевірки дублікатів/конфліктів, навіть коли поверхня bundled Telegram contract недоступна | + | `plugin-sdk/text-autolink-runtime` | Виявлення autolink посилань на файли без широкого barrel `text-runtime` | + | `plugin-sdk/approval-runtime` | Допоміжні засоби схвалення exec/plugin, конструктори можливостей схвалення, допоміжні засоби auth/профілів, нативної маршрутизації/runtime | + | `plugin-sdk/reply-runtime` | Спільні допоміжні засоби runtime вхідних повідомлень/відповідей, chunking, dispatch, Heartbeat, планувальник відповідей | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби dispatch/finalize відповідей | + | `plugin-sdk/reply-history` | Спільні допоміжні засоби short-window історії відповідей, такі як `buildHistoryContext`, `recordPendingHistoryEntry` і `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Вузькі допоміжні засоби chunking тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби шляху до сховища сесій і `updated-at` | + | `plugin-sdk/state-paths` | Допоміжні засоби шляхів до каталогів state/OAuth | + | `plugin-sdk/routing` | Допоміжні засоби маршруту/ключа сесії/прив’язки облікового запису, такі як `resolveAgentRoute`, `buildAgentSessionKey` і `resolveDefaultAgentBoundAccountId` | + | `plugin-sdk/status-helpers` | Спільні допоміжні засоби підсумку стану каналу/облікового запису, значення стану runtime за замовчуванням і допоміжні засоби метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Спільні допоміжні засоби визначення цілі | + | `plugin-sdk/string-normalization-runtime` | Допоміжні засоби нормалізації slug/рядків | + | `plugin-sdk/request-url` | Витягування рядкових URL із входів типу fetch/request | + | `plugin-sdk/run-command` | Виконавець команд із таймером і нормалізованими результатами stdout/stderr | + | `plugin-sdk/param-readers` | Типові читачі параметрів tool/CLI | + | `plugin-sdk/tool-payload` | Витягування нормалізованих payload з об’єктів результатів tool | + | `plugin-sdk/tool-send` | Витягування канонічних полів цілі надсилання з аргументів tool | + | `plugin-sdk/temp-path` | Спільні допоміжні засоби шляхів до тимчасових завантажень | + | `plugin-sdk/logging-core` | Допоміжні засоби logger підсистеми та редагування чутливих даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби режиму таблиць Markdown | + | `plugin-sdk/json-store` | Невеликі допоміжні засоби читання/запису стану JSON | + | `plugin-sdk/file-lock` | Допоміжні засоби реентерабельного блокування файлів | + | `plugin-sdk/persistent-dedupe` | Допоміжні засоби кешу дедуплікації з дисковим зберіганням | + | `plugin-sdk/acp-runtime` | Допоміжні засоби ACP runtime/session і dispatch відповідей | + | `plugin-sdk/acp-binding-resolve-runtime` | Визначення прив’язок ACP лише для читання без імпортів запуску життєвого циклу | + | `plugin-sdk/agent-config-primitives` | Вузькі примітиви схеми конфігурації runtime агента | + | `plugin-sdk/boolean-param` | Читач слабко типізованих булевих параметрів | + | `plugin-sdk/dangerous-name-runtime` | Допоміжні засоби визначення збігів небезпечних назв | + | `plugin-sdk/device-bootstrap` | Допоміжні засоби bootstrap пристрою та токенів pairing | + | `plugin-sdk/extension-shared` | Спільні примітиви допоміжних засобів passive-channel, status і ambient proxy | + | `plugin-sdk/models-provider-runtime` | Допоміжні засоби команд `/models` і відповідей провайдера | + | `plugin-sdk/skill-commands-runtime` | Допоміжні засоби переліку команд Skills | + | `plugin-sdk/native-command-registry` | Допоміжні засоби реєстру/побудови/серіалізації нативних команд | + | `plugin-sdk/agent-harness` | Експериментальна поверхня trusted-plugin для низькорівневих harness агента: типи harness, допоміжні засоби steer/abort активного запуску, допоміжні засоби мосту tool OpenClaw і утиліти результатів спроб | + | `plugin-sdk/provider-zai-endpoint` | Допоміжні засоби виявлення endpoint Z.AI | + | `plugin-sdk/infra-runtime` | Допоміжні засоби системних подій/Heartbeat | + | `plugin-sdk/collection-runtime` | Невеликі допоміжні засоби обмеженого кешу | + | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби діагностичних прапорців і подій | + | `plugin-sdk/error-runtime` | Граф помилок, форматування, спільні допоміжні засоби класифікації помилок, `isApprovalNotFoundError` | + | `plugin-sdk/fetch-runtime` | Обгорнуті допоміжні засоби fetch, proxy і pinned lookup | + | `plugin-sdk/runtime-fetch` | Dispatcher-aware runtime fetch без імпортів proxy/guarded-fetch | + | `plugin-sdk/response-limit-runtime` | Читач обмеженого тіла відповіді без широкої поверхні media runtime | + | `plugin-sdk/session-binding-runtime` | Поточний стан прив’язки розмови без маршрутизації налаштованих прив’язок або сховищ pairing | + | `plugin-sdk/session-store-runtime` | Допоміжні засоби читання сховища сесій без широких імпортів запису/обслуговування конфігурації | + | `plugin-sdk/context-visibility-runtime` | Визначення видимості контексту та фільтрація додаткового контексту без широких імпортів config/security | + | `plugin-sdk/string-coerce-runtime` | Вузькі допоміжні засоби приведення та нормалізації примітивних записів/рядків без імпортів markdown/logging | + | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації hostname і SCP host | + | `plugin-sdk/retry-runtime` | Допоміжні засоби конфігурації retry і виконавця retry | + | `plugin-sdk/agent-runtime` | Допоміжні засоби каталогу/ідентичності/робочого простору агента | + | `plugin-sdk/directory-runtime` | Запит/дедуплікація каталогів на основі конфігурації | + | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/media-runtime` | Спільні допоміжні засоби fetch/transform/store для медіа, а також конструктори payload медіа | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби failover генерації медіа, вибору кандидатів і повідомлень про відсутню модель | + | `plugin-sdk/media-understanding` | Типи провайдерів розуміння медіа, а також орієнтовані на провайдерів експорти допоміжних засобів для зображень/аудіо | + | `plugin-sdk/text-runtime` | Спільні допоміжні засоби text/markdown/logging, такі як видалення видимого для помічника тексту, допоміжні засоби рендерингу/chunking/таблиць markdown, редагування чутливих даних, допоміжні засоби тегів директив і утиліти безпечного тексту | + | `plugin-sdk/text-chunking` | Допоміжний засіб chunking вихідного тексту | + | `plugin-sdk/speech` | Типи провайдерів мовлення, а також орієнтовані на провайдерів допоміжні засоби директив, реєстру й валідації | + | `plugin-sdk/speech-core` | Спільні типи провайдерів мовлення, допоміжні засоби реєстру, директив і нормалізації | + | `plugin-sdk/realtime-transcription` | Типи провайдерів транскрипції в реальному часі, допоміжні засоби реєстру й спільний допоміжний засіб WebSocket-сесії | + | `plugin-sdk/realtime-voice` | Типи провайдерів голосу в реальному часі та допоміжні засоби реєстру | + | `plugin-sdk/image-generation` | Типи провайдерів генерації зображень | + | `plugin-sdk/image-generation-core` | Спільні типи генерації зображень, допоміжні засоби failover, auth і реєстру | + | `plugin-sdk/music-generation` | Типи провайдера/запиту/результату генерації музики | + | `plugin-sdk/music-generation-core` | Спільні типи генерації музики, допоміжні засоби failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/video-generation` | Типи провайдера/запиту/результату генерації відео | + | `plugin-sdk/video-generation-core` | Спільні типи генерації відео, допоміжні засоби failover, пошук провайдера та розбір model-ref | + | `plugin-sdk/webhook-targets` | Допоміжні засоби реєстру цілей Webhook і встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні засоби нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні засоби завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторно експортований `zod` для споживачів SDK Plugin | + | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` | + + + + | Підшлях | Ключові експорти | + | --- | --- | + | `plugin-sdk/memory-core` | Поверхня допоміжних засобів bundled `memory-core` для менеджера/конфігурації/файлів/допоміжних засобів CLI | + | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime індексу/пошуку Memory | + | `plugin-sdk/memory-core-host-engine-foundation` | Експорти foundation engine хоста Memory | + | `plugin-sdk/memory-core-host-engine-embeddings` | Контракти embedding хоста Memory, доступ до реєстру, локальний провайдер і загальні допоміжні засоби batch/remote | + | `plugin-sdk/memory-core-host-engine-qmd` | Експорти QMD engine хоста Memory | + | `plugin-sdk/memory-core-host-engine-storage` | Експорти storage engine хоста Memory | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби multimodal хоста Memory | + | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста Memory | + | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста Memory | + | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста Memory | + | `plugin-sdk/memory-core-host-status` | Допоміжні засоби стану хоста Memory | + | `plugin-sdk/memory-core-host-runtime-cli` | Допоміжні засоби runtime CLI хоста Memory | + | `plugin-sdk/memory-core-host-runtime-core` | Допоміжні засоби core runtime хоста Memory | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста Memory | + | `plugin-sdk/memory-host-core` | Нейтральний до постачальника псевдонім для допоміжних засобів core runtime хоста Memory | + | `plugin-sdk/memory-host-events` | Нейтральний до постачальника псевдонім для допоміжних засобів журналу подій хоста Memory | + | `plugin-sdk/memory-host-files` | Нейтральний до постачальника псевдонім для допоміжних засобів файлів/runtime хоста Memory | + | `plugin-sdk/memory-host-markdown` | Спільні допоміжні засоби керованого markdown для plugin, суміжних із memory | + | `plugin-sdk/memory-host-search` | Фасад runtime Active Memory для доступу до search-manager | + | `plugin-sdk/memory-host-status` | Нейтральний до постачальника псевдонім для допоміжних засобів стану хоста Memory | + | `plugin-sdk/memory-lancedb` | Поверхня допоміжних засобів bundled `memory-lancedb` | + + + + | Сімейство | Поточні підшляхи | Призначення | + | --- | --- | --- | + | Browser | `plugin-sdk/browser-cdp`, `plugin-sdk/browser-config-runtime`, `plugin-sdk/browser-config-support`, `plugin-sdk/browser-control-auth`, `plugin-sdk/browser-node-runtime`, `plugin-sdk/browser-profiles`, `plugin-sdk/browser-security-runtime`, `plugin-sdk/browser-setup-tools`, `plugin-sdk/browser-support` | Допоміжні засоби підтримки bundled browser plugin (`browser-support` залишається barrel сумісності) | + | Matrix | `plugin-sdk/matrix`, `plugin-sdk/matrix-helper`, `plugin-sdk/matrix-runtime-heavy`, `plugin-sdk/matrix-runtime-shared`, `plugin-sdk/matrix-runtime-surface`, `plugin-sdk/matrix-surface`, `plugin-sdk/matrix-thread-bindings` | Поверхня допоміжних засобів/runtime bundled Matrix | + | Line | `plugin-sdk/line`, `plugin-sdk/line-core`, `plugin-sdk/line-runtime`, `plugin-sdk/line-surface` | Поверхня допоміжних засобів/runtime bundled LINE | + | IRC | `plugin-sdk/irc`, `plugin-sdk/irc-surface` | Поверхня допоміжних засобів bundled IRC | + | Допоміжні засоби для конкретних каналів | `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles`, `plugin-sdk/bluebubbles-policy`, `plugin-sdk/mattermost`, `plugin-sdk/mattermost-policy`, `plugin-sdk/feishu-conversation`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, `plugin-sdk/twitch` | Шви сумісності/допоміжних засобів bundled каналів | + | Допоміжні засоби для auth/plugin | `plugin-sdk/github-copilot-login`, `plugin-sdk/github-copilot-token`, `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership`, `plugin-sdk/voice-call` | Шви допоміжних засобів bundled функцій/plugin; `plugin-sdk/github-copilot-token` наразі експортує `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken` | + + + +## Пов’язане + +- [Огляд SDK Plugin](/uk/plugins/sdk-overview) +- [Налаштування SDK Plugin](/uk/plugins/sdk-setup) +- [Створення plugin](/uk/plugins/building-plugins) diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index 3d5333851..259e2cb1b 100644 --- a/docs/uk/reference/test.md +++ b/docs/uk/reference/test.md @@ -1,51 +1,51 @@ --- read_when: - Запуск або виправлення тестів -summary: Як запускати тести локально (vitest) і коли використовувати режими force/coverage +summary: Як запускати тести локально (`vitest`) і коли використовувати режими force/coverage title: Тести x-i18n: - generated_at: "2026-04-23T21:58:41Z" + generated_at: "2026-04-23T23:27:46Z" model: gpt-5.4 provider: openai - source_hash: 3753fd6f29598318f15a34e623a06fac80430cae34d6b42ad06657a46c72fc54 + source_hash: 1224c2c0fc4b96a6631ba238e4e9b13ed61e918282db393df7a9db93b3fbf8cf source_path: reference/test.md workflow: 15 --- - Повний набір для тестування (сьюти, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: завершує будь-який завислий процес gateway, що утримує порт керування за замовчуванням, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. -- `pnpm test:coverage`: запускає набір unit-тестів з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка покриття unit-тестів для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення: 70% для рядків/функцій/інструкцій і 55% для гілок. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit-тестів з покриттям, замість того щоб вважати всі файли вихідного коду з розбитих lane непокритими. -- `pnpm test:coverage:changed`: запускає покриття unit-тестів лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені шляхи git у scoped lane Vitest, коли diff торкається лише routable файлів джерела/тестів. Зміни конфігурації/налаштування, як і раніше, повертаються до нативного запуску root projects, щоб за потреби правки wiring запускали ширший прогін. -- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумну перевірку changed gate для diff відносно `origin/main`. Вона запускає core-роботи разом із core test lane, роботу над розширеннями — з extension test lane, роботу лише над тестами — лише з typecheck/tests для тестів, розгортає зміни публічного Plugin SDK або plugin-contract до перевірки розширень і залишає version bump лише в release metadata на цільових перевірках version/config/root-dependency. -- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілі використовують фіксовані shard-групи та розгортаються в leaf configs для локального паралельного виконання; група розширень завжди розгортається в shard-конфіги для кожного extension/plugin, а не в один великий процес root-project. -- Повні запуски та запуски shard розширень оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane, які залишають тільки `test/setup.ts`, а ресурсомісткі runtime-кейси лишаються на своїх наявних lane. -- Вибрані файли вихідного коду helper у `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane, щоб невеликі правки helper не перезапускали важкі сьюти, що залежать від runtime. -- `auto-reply` тепер також поділяється на три окремі конфігурації (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper. -- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний non-isolated runner увімкнено в усіх конфігураціях репозиторію. +- `pnpm test:force`: завершує будь-який завислий процес Gateway, який утримує типовий порт керування, а потім запускає повну сьюту Vitest з ізольованим портом Gateway, щоб тести сервера не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск Gateway залишив зайнятим порт 18789. +- `pnpm test:coverage`: запускає unit-сьюту з покриттям V8 (через `vitest.unit.config.ts`). Це перевірка unit-покриття для завантажених файлів, а не покриття всього репозиторію для всіх файлів. Порогові значення становлять 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені unit-сьютою покриття, замість того щоб вважати кожен файл вихідного коду з розділених lane-ів непокритим. +- `pnpm test:coverage:changed`: запускає unit-покриття лише для файлів, змінених відносно `origin/main`. +- `pnpm test:changed`: розгортає змінені git-шляхи у scoped lane-и Vitest, коли diff торкається лише routable-файлів коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску root-проєктів, щоб за потреби зміни wiring перевиконувалися ширше. +- `pnpm changed:lanes`: показує архітектурні lane-и, запущені diff-ом відносно `origin/main`. +- `pnpm check:changed`: запускає розумну перевірку зміненого diff-а відносно `origin/main`. Вона запускає core-роботу разом із core test lane-ами, роботу extension — разом із extension test lane-ами, test-only зміни — лише з test typecheck/tests, розширює зміни в публічному Plugin SDK або plugin-contract до одного проходу перевірки extension, а для version bump-ів лише в release metadata зберігає цільові перевірки version/config/root-dependency. +- `pnpm test`: спрямовує явні цілі файлів/директорій через scoped lane-и Vitest. Запуски без цілі використовують фіксовані групи shard-ів і розгортаються до leaf-конфігів для локального паралельного виконання; група extension завжди розгортається до shard-конфігів для кожного extension окремо, а не до одного великого root-project процесу. +- Повні запуски та запуски shard-ів extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard-ів. Встановіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. +- Вибрані тестові файли `plugin-sdk` і `commands` тепер спрямовуються через спеціальні легкі lane-и, які зберігають лише `test/setup.ts`, залишаючи runtime-важкі кейси на їхніх наявних lane-ах. +- Вибрані вихідні helper-файли `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми тестами в цих легких lane-ах, щоб невеликі зміни helper-ів не перезапускали важкі сьюти, які залежать від runtime. +- `auto-reply` тепер також поділяється на три спеціальні конфіги (`core`, `top-level`, `reply`), щоб harness для reply не домінував над легшими top-level тестами status/token/helper. +- Базова конфігурація Vitest тепер типово використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в конфігах усього репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugin, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin лишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. -- `pnpm test:perf:imports`: вмикає звітність Vitest щодо тривалості імпорту та деталізації імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів. -- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` виконує benchmark маршрутизованого changed-режиму проти нативного запуску root-project для того самого закоміченого git diff. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту. +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard-и; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane-а bundled plugin. +- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та import-breakdown, водночас і далі використовуючи scoped lane routing для явних цілей файлів/директорій. +- `pnpm test:perf:imports:changed`: той самий профайлінг імпорту, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` бенчмаркує routed changed-mode шлях проти нативного запуску root-project для того самого зафіксованого git diff-а. +- `pnpm test:perf:changed:bench -- --worktree` бенчмаркує поточний набір змін у worktree без попереднього коміту. - `pnpm test:perf:profile:main`: записує CPU-профіль для головного потоку Vitest (`.artifacts/vitest-main-profile`). -- `pnpm test:perf:profile:runner`: записує профілі CPU + heap для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf-конфігурацію Vitest повного набору та записує дані про тривалість за групами, а також JSON/лог-артефакти для кожної конфігурації. Агент Test Performance використовує це як базову лінію перед спробою виправити повільні тести. -- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність. -- Інтеграція Gateway: увімкнення за бажанням через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: запускає наскрізні smoke-тести gateway (multi-instance WS/HTTP/node pairing). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю worker у `vitest.e2e.config.ts`; налаштовується через `OPENCLAW_E2E_WORKERS=`, а для докладних логів установіть `OPENCLAW_E2E_VERBOSE=1`. -- `pnpm test:live`: запускає live-тести provider (minimax/zai). Потрібні API-ключі та `LIVE=1` (або provider-специфічний `*_LIVE_TEST=1`) для зняття `skip`. -- `pnpm test:docker:all`: один раз збирає спільний образ для live-тестів і Docker E2E image, а потім запускає Docker smoke lane з `OPENCLAW_SKIP_DOCKER_BUILD=1` і типовим паралелізмом 4. Налаштовується через `OPENCLAW_DOCKER_ALL_PARALLELISM=`. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а для кожного lane діє тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Lane, чутливі до старту або provider, запускаються ексклюзивно після паралельного пулу. Логи для кожного lane записуються в `.artifacts/docker-tests//`. -- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксований чат через `/api/chat/completions`. Потрібен робочий live model key (наприклад, OpenAI у `~/.profile`), завантажується зовнішній образ Open WebUI, і цей сценарій не очікується стабільним у CI так, як звичайні unit/e2e сьюти. -- `pnpm test:docker:mcp-channels`: запускає seeded-контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, метадані вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-фрейми напряму, щоб smoke-тест відображав те, що міст фактично надсилає. +- `pnpm test:perf:profile:runner`: записує CPU- і heap-профілі для unit runner (`.artifacts/vitest-runner-profile`). +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf-конфіг Vitest із повної suite і записує згруповані дані тривалості разом із JSON/log-артефактами для кожного конфіга. Агент продуктивності тестів використовує це як базову точку перед спробою виправити повільні тести. +- `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після зміни, зосередженої на продуктивності. +- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: запускає наскрізні smoke-тести Gateway (multi-instance WS/HTTP/node pairing). Типово використовує `threads` + `isolate: false` з адаптивною кількістю workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановіть `OPENCLAW_E2E_VERBOSE=1` для докладних логів. +- `pnpm test:live`: запускає live-тести провайдерів (minimax/zai). Потребує API-ключів і `LIVE=1` (або провайдер-специфічного `*_LIVE_TEST=1`) для зняття пропуску. +- `pnpm test:docker:all`: один раз збирає спільний образ live-тестів і Docker E2E-образ, а потім запускає Docker smoke lane-и з `OPENCLAW_SKIP_DOCKER_BUILD=1` із concurrency 4 за замовчуванням. Налаштовуйте через `OPENCLAW_DOCKER_ALL_PARALLELISM=`. Runner припиняє планувати нові pooled lane-и після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожен lane має тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`. Чутливі до запуску або провайдера lane-и запускаються ексклюзивно після паралельного пулу. Логи для кожного lane-а записуються в `.artifacts/docker-tests//`. +- `pnpm test:docker:openwebui`: запускає Dockerized OpenClaw + Open WebUI, виконує вхід через Open WebUI, перевіряє `/api/models`, а потім запускає реальний проксійований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній образ Open WebUI і не розрахований на CI-стабільність, як звичайні unit/e2e-сьюти. +- `pnpm test:docker:mcp-channels`: запускає контейнер Gateway із попереднім наповненням і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє виявлення routed conversations, читання transcript-ів, metadata вкладень, поведінку черги live-подій, outbound send routing і сповіщення про channel + permissions у стилі Claude через реальний stdio bridge. Перевірка сповіщень Claude читає сирі stdio MCP-кадри безпосередньо, щоб smoke відображав те, що міст реально надсилає. ## Локальна PR-перевірка -Для локальних перевірок перед злиттям PR запускайте: +Для локальних перевірок перед злиттям/гейтом PR запустіть: - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` нестабільно працює на завантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте проблему через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` флейкиться на навантаженому хості, перезапустіть його один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженнями пам’яті використовуйте: - `OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test` - `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/tmp/openclaw-vitest-cache pnpm test:changed` -## Benchmark затримки моделі (локальні ключі) +## Бенч затримки моделі (локальні ключі) Скрипт: [`scripts/bench-model.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-model.ts) @@ -67,14 +67,14 @@ x-i18n: - `source ~/.profile && pnpm tsx scripts/bench-model.ts --runs 10` - Необов’язкові env: `MINIMAX_API_KEY`, `MINIMAX_BASE_URL`, `MINIMAX_MODEL`, `ANTHROPIC_API_KEY` -- Типовий prompt: “Відповідай одним словом: ok. Без розділових знаків або додаткового тексту.” +- Типовий prompt: “Відповідай одним словом: ok. Без пунктуації або додаткового тексту.” -Останній запуск (2025-12-31, 20 прогонів): +Останній запуск (2025-12-31, 20 запусків): - minimax median 1279ms (min 1114, max 2431) - opus median 2454ms (min 1224, max 3170) -## Benchmark запуску CLI +## Бенч запуску CLI Скрипт: [`scripts/bench-cli-startup.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/bench-cli-startup.ts) @@ -95,41 +95,41 @@ x-i18n: - `pnpm tsx scripts/bench-cli-startup.ts --preset real --cpu-prof-dir .artifacts/cli-cpu` - `pnpm tsx scripts/bench-cli-startup.ts --json` -Preset: +Пресети: - `startup`: `--version`, `--help`, `health`, `health --json`, `status --json`, `status` - `real`: `health`, `status`, `status --json`, `sessions`, `sessions --json`, `agents list --json`, `gateway status`, `gateway status --json`, `gateway health --json`, `config get gateway.port` -- `all`: обидва preset +- `all`: обидва пресети -Вивід містить `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного прогону, тож вимірювання часу та захоплення профілю використовують той самий harness. +Вивід включає `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і підсумки max RSS для кожної команди. Необов’язкові `--cpu-prof-dir` / `--heap-prof-dir` записують V8-профілі для кожного запуску, щоб вимірювання часу й захоплення профілів використовували один і той самий harness. Умовні позначення для збереженого виводу: - `pnpm test:startup:bench:smoke` записує цільовий smoke-артефакт у `.artifacts/cli-startup-bench-smoke.json` -- `pnpm test:startup:bench:save` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1` -- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` +- `pnpm test:startup:bench:save` записує артефакт повної suite у `.artifacts/cli-startup-bench-all.json`, використовуючи `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює зафіксований у репозиторії baseline-фікстур у `test/fixtures/cli-startup-bench.json`, використовуючи `runs=5` і `warmup=1` -Закомічений fixture: +Фікстур, зафіксований у репозиторії: - `test/fixtures/cli-startup-bench.json` -- Оновлення: `pnpm test:startup:bench:update` -- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check` +- Оновіть через `pnpm test:startup:bench:update` +- Порівняйте поточні результати з фікстуром через `pnpm test:startup:bench:check` ## Onboarding E2E (Docker) -Docker необов’язковий; це потрібно лише для контейнеризованих onboarding smoke-тестів. +Docker необов’язковий; це потрібно лише для контейнеризованих smoke-тестів onboarding. -Повний cold-start сценарій у чистому Linux-контейнері: +Повний cold-start потік у чистому Linux-контейнері: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. +Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, потім запускає Gateway і виконує `openclaw health`. ## Smoke-тест імпорту QR (Docker) -Переконується, що підтримуваний QR runtime helper завантажується в підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22): +Гарантує, що підтримуваний helper QR runtime завантажується у підтримуваних Docker runtime Node (типово Node 24, сумісно з Node 22): ```bash pnpm test:docker:qr diff --git a/docs/uk/tools/exec-approvals-advanced.md b/docs/uk/tools/exec-approvals-advanced.md new file mode 100644 index 000000000..dc70c9a25 --- /dev/null +++ b/docs/uk/tools/exec-approvals-advanced.md @@ -0,0 +1,274 @@ +--- +read_when: + - Налаштування безпечних бінарних файлів або користувацьких профілів safe-bin + - Переспрямування схвалень до Slack/Discord/Telegram або інших чат-каналів + - Реалізація нативного клієнта схвалення для каналу +summary: 'Розширені дозволи на виконання: безпечні бінарні файли, прив’язка інтерпретатора, переспрямування схвалення, нативна доставка' +title: Дозволи на виконання — розширені +x-i18n: + generated_at: "2026-04-23T23:27:49Z" + model: gpt-5.4 + provider: openai + source_hash: 8a24a3539126b0f0fd11696c31efc8a6a9a4262fe4cd89bf456ff92a4f05c36c + source_path: tools/exec-approvals-advanced.md + workflow: 15 +--- + +Розширені теми дозволів на виконання: швидкий шлях `safeBins`, прив’язка +інтерпретатора/середовища виконання та переспрямування схвалень до чат-каналів +(включно з нативною доставкою). Базову політику та потік схвалення див. у [Дозволи на виконання](/uk/tools/exec-approvals). + +## Безпечні бінарні файли (лише stdin) + +`tools.exec.safeBins` визначає невеликий список **бінарних файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів у allowlist. Безпечні бінарні файли відхиляють позиційні файлові аргументи та токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. Розглядайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри. + + +**Не** додавайте бінарні файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, +`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код, +виконувати підкоманди або читати файли, надавайте перевагу явним записам у allowlist +і залишайте підказки схвалення ввімкненими. Користувацькі безпечні бінарні файли мають визначати явний +профіль у `tools.exec.safeBinProfiles.`. + + +Типові безпечні бінарні файли: + +[//]: # "SAFE_BIN_DEFAULTS:START" + +`cut`, `uniq`, `head`, `tail`, `tr`, `wc` + +[//]: # "SAFE_BIN_DEFAULTS:END" + +`grep` і `sort` не входять до типового списку. Якщо ви явно вмикаєте їх, зберігайте явні +записи allowlist для їхніх сценаріїв не через stdin. Для `grep` у режимі safe-bin +передавайте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється, +щоб файлові операнди не можна було приховано передати як неоднозначні позиційні аргументи. + +### Перевірка argv і заборонені прапорці + +Перевірка є детермінованою лише за формою argv (без перевірок існування у файловій системі хоста), +що запобігає поведінці оракула існування файлів через відмінності allow/deny. +Опції, орієнтовані на файли, заборонені для типових safe-bin; довгі +опції перевіряються за принципом fail-closed (невідомі прапорці та неоднозначні скорочення +відхиляються). + +Заборонені прапорці за профілем safe-bin: + +[//]: # "SAFE_BIN_DENIED_FLAGS:START" + +- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` +- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` +- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` +- `wc`: `--files0-from` + +[//]: # "SAFE_BIN_DENIED_FLAGS:END" + +Безпечні бінарні файли також примусово обробляють токени argv як **буквальний текст** під час виконання +(без глобінгу та без розгортання `$VARS`) для сегментів лише зі stdin, тож шаблони +на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів. + +### Довірені каталоги бінарних файлів + +Безпечні бінарні файли мають визначатися з довірених каталогів бінарних файлів (системні типові каталоги плюс +необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються автоматично довіреними. +Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо ваш safe-bin виконуваний файл +розташовано в шляхах менеджера пакетів або користувача (наприклад +`/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх +явно до `tools.exec.safeBinTrustedDirs`. + +### Ланцюжки shell-команд, обгортки та мультиплексори + +Ланцюжки shell-команд (`&&`, `||`, `;`) дозволені, якщо кожен сегмент верхнього рівня +відповідає allowlist (включно з safe-bin або авто-дозволом Skills). Перенаправлення +у режимі allowlist, як і раніше, не підтримуються. Підстановка команд (`$()` / зворотні лапки) відхиляється +під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. + +У схваленнях companion app на macOS сирий shell-текст, що містить синтаксис керування оболонкою або розгортання +(`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), вважається промахом allowlist, якщо сам бінарний файл shell не входить до allowlist. + +Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env на рівні запиту +зводяться до невеликого явного allowlist (`TERM`, `LANG`, `LC_*`, `COLORTERM`, +`NO_COLOR`, `FORCE_COLOR`). + +Для рішень `allow-always` у режимі allowlist відомі обгортки диспетчеризації (`env`, +`nice`, `nohup`, `stdbuf`, `timeout`) зберігають шлях до внутрішнього виконуваного файла, +а не шлях до обгортки. Shell-мультиплексори (`busybox`, `toybox`) розгортаються для +аплетів shell (`sh`, `ash` тощо) так само. Якщо обгортку або мультиплексор +не можна безпечно розгорнути, жоден запис allowlist автоматично не зберігається. + +Якщо ви додаєте до allowlist такі інтерпретатори, як `python3` або `node`, надавайте перевагу +`tools.exec.strictInlineEval=true`, щоб inline eval і надалі вимагав явного +схвалення. У strict mode `allow-always` усе ще може зберігати нешкідливі +виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. + +### Safe bins проти allowlist + +| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | +| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | +| Мета | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів | +| Тип відповідності | Ім’я виконуваного файла + політика argv safe-bin | Глоб-шаблон шляху до визначеного виконуваного файла | +| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише відповідність шляху; за аргументи в іншому ви відповідаєте самі | +| Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI | +| Найкраще застосування | Малоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | + +Розташування конфігурації: + +- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для конкретного агента). +- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для конкретного агента). +- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для конкретного агента). Ключі профілів для конкретного агента перевизначають глобальні ключі. +- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). +- `openclaw security audit` попереджає кодом `tools.exec.safe_bins_interpreter_unprofiled`, коли бінарні файли інтерпретаторів/середовищ виконання з’являються в `safeBins` без явних профілів. +- `openclaw doctor --fix` може створити відсутні записи `safeBinProfiles.` як `{}` (після цього перегляньте й посильте їх). Для бінарних файлів інтерпретаторів/середовищ виконання автогенерація не виконується. + +Приклад користувацького профілю: +__OC_I18N_900000__ +Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє builtin `env` у режимі safe-bin, +тому `jq -n env` не зможе вивантажити середовище процесу хоста без явного шляху в allowlist +або підказки схвалення. + +## Команди інтерпретатора/середовища виконання + +Запуски інтерпретатора/середовища виконання, підкріплені схваленням, навмисно є консервативними: + +- Точний контекст argv/cwd/env завжди прив’язується. +- Прямі форми shell-скриптів і прямі форми файлів середовища виконання прив’язуються за можливості до одного конкретного локального знімка файла. +- Поширені форми обгорток менеджерів пакетів, які все ще визначаються в один прямий локальний файл (наприклад + `pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою. +- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання + (наприклад скрипти пакетів, форми eval, специфічні для середовища виконання ланцюжки завантажувачів або неоднозначні багатофайлові + форми), виконання, підкріплене схваленням, відхиляється замість того, щоб заявляти семантичне покриття, + якого насправді немає. +- Для таких сценаріїв надавайте перевагу sandboxing, окремій межі хоста або явному + довіреному allowlist/повному workflow, де оператор приймає ширшу семантику середовища виконання. + +Коли потрібні схвалення, інструмент exec одразу повертає ідентифікатор схвалення. Використовуйте цей id, щоб +співвіднести подальші системні події (`Exec finished` / `Exec denied`). Якщо рішення не надходить до завершення +тайм-ауту, запит вважається тайм-аутом схвалення і відображається як причина відмови. + +### Поведінка доставки followup + +Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` до тієї самої сесії. + +- Якщо існує дійсна зовнішня ціль доставки (канал, придатний до доставки, плюс цільовий `to`), followup-доставка використовує цей канал. +- У потоках лише webchat або internal-session без зовнішньої цілі followup-доставка залишається лише в межах сесії (`deliver: false`). +- Якщо викликач явно вимагає сувору зовнішню доставку, але жоден зовнішній канал не можна визначити, запит завершується помилкою `INVALID_REQUEST`. +- Якщо увімкнено `bestEffortDeliver` і жоден зовнішній канал не можна визначити, доставку буде знижено до лише сесійної замість помилки. + +## Переспрямування схвалень до чат-каналів + +Ви можете переспрямовувати підказки схвалення exec до будь-якого чат-каналу (включно з каналами Plugin) і схвалювати +їх через `/approve`. Для цього використовується звичайний конвеєр вихідної доставки. + +Конфігурація: +__OC_I18N_900001__ +Відповідь у чаті: +__OC_I18N_900002__ +Команда `/approve` обробляє і exec-схвалення, і схвалення Plugin. Якщо ID не відповідає очікуваному exec-схваленню, вона автоматично перевіряє схвалення Plugin. + +### Переспрямування схвалень Plugin + +Переспрямування схвалень Plugin використовує той самий конвеєр доставки, що й exec-схвалення, але має власну +незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше. +__OC_I18N_900003__ +Форма конфігурації ідентична `approvals.exec`: `enabled`, `mode`, `agentFilter`, +`sessionFilter` і `targets` працюють однаково. + +Канали, що підтримують спільні інтерактивні відповіді, відображають ті самі кнопки схвалення як для exec, так і для схвалень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`. + +### Схвалення в тому самому чаті на будь-якому каналі + +Коли запит на exec або схвалення Plugin походить із чат-поверхні, придатної до доставки, цей самий чат +тепер за замовчуванням може схвалити його через `/approve`. Це стосується таких каналів, як Slack, Matrix і +Microsoft Teams, на додачу до вже наявних потоків Web UI і terminal UI. + +Цей спільний шлях текстової команди використовує звичайну модель автентифікації каналу для цієї розмови. Якщо +чат-джерело вже може надсилати команди й отримувати відповіді, для запитів на схвалення більше не потрібен +окремий адаптер нативної доставки лише для того, щоб залишатися в очікуванні. + +Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали все ще використовують свій +визначений список approver для авторизації, навіть коли нативну доставку схвалень вимкнено. + +Для Telegram та інших нативних клієнтів схвалення, які напряму викликають Gateway, +цей fallback навмисно обмежено збоями типу «схвалення не знайдено». Справжня +відмова/помилка exec-схвалення не повторюється мовчки як схвалення Plugin. + +### Нативна доставка схвалень + +Деякі канали також можуть працювати як нативні клієнти схвалень. Нативні клієнти додають approver DM, fanout чату-джерела +та специфічний для каналу інтерактивний UX схвалення поверх спільного потоку `/approve` у тому самому чаті. + +Коли доступні нативні картки/кнопки схвалення, цей нативний UI є основним +шляхом для агента. Агент також не повинен дублювати звичайну чат-команду +`/approve`, якщо тільки результат інструмента не вказує, що чат-схвалення недоступні або +ручне схвалення є єдиним шляхом, що залишився. + +Загальна модель: + +- політика host exec, як і раніше, визначає, чи потрібне exec-схвалення +- `approvals.exec` керує переспрямуванням підказок схвалення до інших чат-цілей +- `channels..execApprovals` керує тим, чи працює цей канал як нативний клієнт схвалень + +Нативні клієнти схвалень автоматично вмикають доставку спочатку в DM, коли виконуються всі ці умови: + +- канал підтримує нативну доставку схвалень +- approver можна визначити з явних `execApprovals.approvers` або з + документованих fallback-джерел цього каналу +- `channels..execApprovals.enabled` не задано або має значення `"auto"` + +Установіть `enabled: false`, щоб явно вимкнути нативний клієнт схвалень. Установіть `enabled: true`, щоб примусово +увімкнути його, коли approver визначаються. Публічна доставка до чату-джерела й надалі явно задається через +`channels..execApprovals.target`. + +FAQ: [Чому для чат-схвалень існує дві конфігурації exec-схвалень?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) + +- Discord: `channels.discord.execApprovals.*` +- Slack: `channels.slack.execApprovals.*` +- Telegram: `channels.telegram.execApprovals.*` + +Ці нативні клієнти схвалень додають DM-маршрутизацію та необов’язковий fanout каналу поверх спільного +потоку `/approve` у тому самому чаті та спільних кнопок схвалення. + +Спільна поведінка: + +- Slack, Matrix, Microsoft Teams та подібні чати з можливістю доставки використовують звичайну модель автентифікації каналу + для `/approve` у тому самому чаті +- коли нативний клієнт схвалень вмикається автоматично, типовою нативною ціллю доставки є DM для approver +- для Discord і Telegram лише визначені approver можуть схвалювати або відхиляти +- approver у Discord можуть бути явними (`execApprovals.approvers`) або визначатися з `commands.ownerAllowFrom` +- approver у Telegram можуть бути явними (`execApprovals.approvers`) або визначатися з наявної конфігурації owner (`allowFrom`, а також `defaultTo` для direct-message, де це підтримується) +- approver у Slack можуть бути явними (`execApprovals.approvers`) або визначатися з `commands.ownerAllowFrom` +- нативні кнопки Slack зберігають тип id схвалення, тож id `plugin:` можуть визначати схвалення Plugin + без другого локального fallback-рівня Slack +- нативна DM/канальна маршрутизація Matrix і скорочення через реакції обробляють і exec-схвалення, і схвалення Plugin; + авторизація Plugin і надалі походить з `channels.matrix.dm.allowFrom` +- запитувач не зобов’язаний бути approver +- чат-джерело може схвалити запит напряму через `/approve`, якщо цей чат уже підтримує команди та відповіді +- нативні кнопки схвалення Discord маршрутизують за типом id схвалення: id `plugin:` одразу + спрямовуються до схвалень Plugin, усе інше — до exec-схвалень +- нативні кнопки схвалення Telegram використовують той самий обмежений exec-to-plugin fallback, що й `/approve` +- коли нативний `target` вмикає доставку до чату-джерела, підказки схвалення містять текст команди +- exec-схвалення в очікуванні за замовчуванням спливають через 30 хвилин +- якщо жоден UI оператора або налаштований клієнт схвалень не може прийняти запит, підказка повертається до `askFallback` + +Telegram за замовчуванням використовує DM для approver (`target: "dm"`). Ви можете переключити на `channel` або `both`, якщо +хочете, щоб підказки схвалення також з’являлися в чаті/темі Telegram, звідки надійшов запит. Для тем форуму Telegram +OpenClaw зберігає тему для підказки схвалення та follow-up після схвалення. + +Див. також: + +- [Discord](/channels/discord) +- [Telegram](/channels/telegram) + +### Потік macOS IPC +__OC_I18N_900004__ +Примітки щодо безпеки: + +- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`. +- Перевірка peer з тим самим UID. +- Challenge/response (nonce + HMAC token + request hash) + короткий TTL. + +## Пов’язане + +- [Дозволи на виконання](/uk/tools/exec-approvals) — базова політика та потік схвалення +- [Інструмент exec](/uk/tools/exec) +- [Підвищений режим](/uk/tools/elevated) +- [Skills](/uk/tools/skills) — поведінка автодозволу на основі Skills diff --git a/docs/uk/tools/exec-approvals.md b/docs/uk/tools/exec-approvals.md index 733dce48b..af370eae8 100644 --- a/docs/uk/tools/exec-approvals.md +++ b/docs/uk/tools/exec-approvals.md @@ -1,65 +1,67 @@ --- read_when: - - Налаштування підтверджень виконання або списків дозволених елементів - - Реалізація UX для підтвердження виконання в застосунку macOS - - Перегляд запитів на вихід із пісочниці та їхніх наслідків -summary: Підтвердження виконання, списки дозволених елементів і запити на вихід із пісочниці -title: Підтвердження виконання + - Налаштування затверджень виконання або списків дозволеного + - Реалізація UX затвердження виконання у застосунку macOS + - Перевірка підказок щодо виходу з пісочниці та їхніх наслідків +summary: Підказки щодо затвердження виконання, списків дозволеного та виходу з пісочниці +title: Затвердження виконання x-i18n: - generated_at: "2026-04-23T22:14:40Z" + generated_at: "2026-04-23T23:27:47Z" model: gpt-5.4 provider: openai - source_hash: a4090e0726d9cee3372a11e6bf8f7899546e68f4fabea42dcb55b87593e9315c + source_hash: 0d7c5cd24e7c1831d5a865da6fa20f4c23280a0ec12b9e8f7f3245170a05a37d source_path: tools/exec-approvals.md workflow: 15 --- -Підтвердження виконання — це **захисний механізм companion app / хоста Node** для надання змоги агенту в пісочниці виконувати команди на реальному хості (`gateway` або `node`). Це запобіжник безпеки: команди дозволяються лише тоді, коли політика + список дозволених елементів + (необов’язкове) підтвердження користувача збігаються. Підтвердження виконання накладаються **поверх** політики інструментів і підвищеного рівня доступу (окрім випадку, коли elevated встановлено в `full`, що пропускає підтвердження). +Затвердження виконання — це **запобіжник застосунку-компаньйона / хоста Node**, який дає змогу агенту в пісочниці запускати команди на реальному хості (`gateway` або `node`). Це запобіжне блокування: команди дозволяються лише тоді, коли політика + список дозволеного + (необов’язкове) затвердження користувачем усі це підтверджують. Затвердження виконання накладаються **поверх** політики інструментів і підвищеного шлюзу (окрім випадку, коли elevated встановлено в `full`, що пропускає затвердження). -Ефективна політика є **суворішою** з `tools.exec.*` і значень за замовчуванням для підтверджень; якщо поле підтверджень пропущено, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан підтверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжуватиме запитувати підтвердження, навіть якщо параметри сеансу або конфігурації вимагають `ask: "on-miss"`. +Ефективна політика — **суворіша** з `tools.exec.*` та типових значень затверджень; якщо поле затверджень пропущено, використовується значення `tools.exec`. Виконання на хості також використовує локальний стан затверджень на цій машині — локальне для хоста `ask: "always"` у `~/.openclaw/exec-approvals.json` продовжує показувати запит навіть тоді, коли типові значення сеансу або конфігурації вимагають `ask: "on-miss"`. ## Перевірка ефективної політики -- `openclaw approvals get`, `... --gateway`, `... --node ` — показують запитану політику, джерела політики хоста та ефективний результат. +- `openclaw approvals get`, `... --gateway`, `... --node ` — показує запитану політику, джерела політики хоста та ефективний результат. - `openclaw exec-policy show` — об’єднане подання для локальної машини. -- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом підтверджень хоста за один крок. +- `openclaw exec-policy set|preset` — синхронізує локально запитану політику з локальним файлом затверджень хоста за один крок. -Коли локальна область запитує `host=node`, `exec-policy show` повідомляє про цю область як керовану вузлом під час виконання, а не вдає, що локальний файл підтверджень є джерелом істини. +Коли локальна область запитує `host=node`, `exec-policy show` повідомляє про цю область як про керовану Node під час виконання, замість того щоб удавати, ніби локальний файл затверджень є джерелом істини. -Якщо UI companion app **недоступний**, будь-який запит, який зазвичай потребував би підтвердження, обробляється через **резервний режим ask** (типово: deny). +Якщо UI застосунку-компаньйона **недоступний**, будь-який запит, який зазвичай викликав би запит на підтвердження, обробляється через **резервну поведінку ask** (типово: deny). -Нативні клієнти підтвердження в чаті можуть додавати специфічні для каналу зручні елементи до повідомлення про очікуване підтвердження. Наприклад, Matrix додає швидкі реакції (`✅` -дозволити один раз, `❌` відхилити, `♾️` дозволити завжди), водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант. +Нативні клієнти затвердження в чаті можуть додавати специфічні для каналу елементи керування до повідомлення з очікуванням затвердження. Наприклад, Matrix додає швидкі реакції (`✅` дозволити один раз, `❌` заборонити, `♾️` дозволити завжди), водночас залишаючи команди `/approve ...` у повідомленні як резервний варіант. ## Де це застосовується -Підтвердження виконання застосовуються локально на хості виконання: +Затвердження виконання застосовуються локально на хості виконання: - **gateway host** → процес `openclaw` на машині Gateway -- **node host** → виконавець вузла (companion app macOS або headless-хост вузла) +- **node host** → виконавець Node (застосунок-компаньйон macOS або headless-хост Node) Примітка щодо моделі довіри: - Виклики, автентифіковані через Gateway, є довіреними операторами для цього Gateway. -- Спарені вузли поширюють цю можливість довіреного оператора на хост вузла. -- Підтвердження виконання зменшують ризик випадкового виконання, але не є межею автентифікації на рівні окремого користувача. -- Схвалені запуски на хості вузла прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, якщо застосовно. -- Для shell-скриптів і прямих викликів файлів інтерпретатора/середовища виконання OpenClaw також намагається прив’язати один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після підтвердження, але до виконання, запуск відхиляється замість виконання зміненого вмісту. -- Ця прив’язка файлів навмисно є best-effort, а не повною семантичною моделлю для кожного шляху завантаження інтерпретатора/середовища виконання. -- Якщо режим підтвердження не може однозначно визначити рівно один конкретний локальний файл для прив’язки, він відмовляється створювати запуск, підтриманий підтвердженням, замість того щоб удавати повне покриття. +- Спарені Node розширюють цю можливість довіреного оператора на хост Node. +- Затвердження виконання знижують ризик випадкового виконання, але не є межею автентифікації на рівні користувача. +- Затверджені запуски на хості Node прив’язують канонічний контекст виконання: канонічний cwd, точний argv, прив’язку env за наявності та зафіксований шлях до виконуваного файла, якщо застосовно. +- Для shell-скриптів і прямих викликів файла інтерпретатора/середовища виконання OpenClaw також намагається прив’язати + один конкретний локальний файловий операнд. Якщо цей прив’язаний файл змінюється після затвердження, але до виконання, + запуск забороняється замість виконання зміненого вмісту. +- Ця файлова прив’язка навмисно є best-effort, а не повною семантичною моделлю для кожного + шляху завантаження інтерпретатора/середовища виконання. Якщо режим затвердження не може визначити рівно один конкретний локальний + файл для прив’язки, він відмовляється створювати запуск, підкріплений затвердженням, замість того щоб удавати повне покриття. -Розділення в macOS: +Розподіл у macOS: -- **служба node host** пересилає `system.run` до **застосунку macOS** через локальний IPC. -- **застосунок macOS** застосовує підтвердження + виконує команду в контексті UI. +- **служба хоста Node** пересилає `system.run` до **застосунку macOS** через локальний IPC. +- **застосунок macOS** застосовує затвердження + виконує команду в контексті UI. ## Налаштування та зберігання -Підтвердження зберігаються в локальному JSON-файлі на хості виконання: +Затвердження зберігаються в локальному JSON-файлі на хості виконання: `~/.openclaw/exec-approvals.json` @@ -98,35 +100,35 @@ x-i18n: } ``` -## Режим "YOLO" без підтверджень +## Режим "YOLO" без затвердження -Якщо ви хочете, щоб виконання на хості відбувалося без запитів на підтвердження, потрібно відкрити **обидва** рівні політики: +Якщо ви хочете, щоб виконання на хості працювало без запитів на затвердження, потрібно відкрити **обидва** рівні політики: -- запитана політика виконання в конфігурації OpenClaw (`tools.exec.*`) -- локальна для хоста політика підтверджень у `~/.openclaw/exec-approvals.json` +- запитувана політика виконання в конфігурації OpenClaw (`tools.exec.*`) +- локальна для хоста політика затверджень у `~/.openclaw/exec-approvals.json` Тепер це типова поведінка хоста, якщо ви явно не зробите її суворішою: - `tools.exec.security`: `full` на `gateway`/`node` - `tools.exec.ask`: `off` -- хост `askFallback`: `full` +- host `askFallback`: `full` -Важливе розрізнення: +Важлива відмінність: - `tools.exec.host=auto` визначає, де виконується exec: у пісочниці, якщо вона доступна, інакше на gateway. -- YOLO визначає, як схвалюється виконання на хості: `security=full` плюс `ask=off`. -- Провайдери на базі CLI, які надають власний неінтерактивний режим дозволів, можуть дотримуватися цієї політики. - Claude CLI додає `--permission-mode bypassPermissions`, коли запитана політика виконання OpenClaw — це - YOLO. Ви можете перевизначити цю поведінку бекенда явними аргументами Claude у +- YOLO визначає, як затверджується виконання на хості: `security=full` плюс `ask=off`. +- Провайдери на основі CLI, які мають власний неінтерактивний режим дозволів, можуть дотримуватися цієї політики. + Claude CLI додає `--permission-mode bypassPermissions`, коли запитана OpenClaw політика виконання є + YOLO. Перевизначте цю поведінку бекенда явними аргументами Claude в `agents.defaults.cliBackends.claude-cli.args` / `resumeArgs`, наприклад `--permission-mode default`, `acceptEdits` або `bypassPermissions`. -- У режимі YOLO OpenClaw не додає окремий евристичний бар’єр підтвердження для обфускації команд або рівень відхилення скриптів перед виконанням поверх налаштованої політики виконання на хості. -- `auto` не робить маршрутизацію через gateway безкоштовним способом обійти обмеження із сеансу в пісочниці. Запит `host=node` для окремого виклику дозволений з `auto`, а `host=gateway` дозволений з `auto` лише тоді, коли немає активного середовища виконання в пісочниці. Якщо вам потрібне стабільне значення за замовчуванням, відмінне від auto, установіть `tools.exec.host` або використовуйте `/exec host=...` явно. +- У режимі YOLO OpenClaw не додає окремий евристичний шлюз затвердження для обфускації команд або шар відхилення script-preflight поверх налаштованої політики виконання на хості. +- `auto` не перетворює маршрутизацію через gateway на безкоштовне перевизначення із сеансу в пісочниці. Запит на рівні виклику `host=node` дозволений із `auto`, а `host=gateway` дозволений із `auto` лише тоді, коли середовище виконання пісочниці неактивне. Якщо вам потрібне стабільне типове значення без auto, установіть `tools.exec.host` або використовуйте `/exec host=...` явно. -Якщо вам потрібніше більш консервативне налаштування, знову зробіть будь-який із рівнів суворішим до `allowlist` / `on-miss` +Якщо вам потрібне більш консервативне налаштування, знову зробіть будь-який із шарів суворішим до `allowlist` / `on-miss` або `deny`. -Постійне налаштування gateway host у режимі "ніколи не запитувати": +Постійне налаштування gateway-host "ніколи не запитувати": ```bash openclaw config set tools.exec.host gateway @@ -135,7 +137,7 @@ openclaw config set tools.exec.ask off openclaw gateway restart ``` -Потім узгодьте з цим файл підтверджень хоста: +Потім налаштуйте файл затверджень хоста відповідно: ```bash openclaw approvals set --stdin <<'EOF' @@ -150,22 +152,22 @@ openclaw approvals set --stdin <<'EOF' EOF ``` -Локальний скорочений спосіб для тієї самої політики gateway host на поточній машині: +Локальне скорочення для тієї самої політики gateway-host на поточній машині: ```bash openclaw exec-policy preset yolo ``` -Цей локальний скорочений спосіб оновлює обидва: +Це локальне скорочення оновлює обидва: - локальні `tools.exec.host/security/ask` -- локальні значення за замовчуванням у `~/.openclaw/exec-approvals.json` +- локальні типові значення в `~/.openclaw/exec-approvals.json` -Він навмисно працює лише локально. Якщо вам потрібно змінити підтвердження gateway host або node host +Воно навмисно працює лише локально. Якщо вам потрібно змінити затвердження gateway-host або node-host віддалено, і надалі використовуйте `openclaw approvals set --gateway` або `openclaw approvals set --node `. -Для хоста вузла застосуйте той самий файл підтверджень на цьому вузлі: +Для хоста Node застосуйте той самий файл затверджень на цій Node: ```bash openclaw approvals set --node --stdin <<'EOF' @@ -180,45 +182,45 @@ openclaw approvals set --node --stdin <<'EOF' EOF ``` -Важливе обмеження лише для локального використання: +Важливе обмеження лише для локального режиму: -- `openclaw exec-policy` не синхронізує підтвердження вузла +- `openclaw exec-policy` не синхронізує затвердження Node - `openclaw exec-policy set --host node` відхиляється -- підтвердження виконання вузла отримуються з вузла під час виконання, тому для оновлень, спрямованих на вузол, потрібно використовувати `openclaw approvals --node ...` +- затвердження виконання Node отримуються з Node під час виконання, тому цільові оновлення для Node потрібно робити через `openclaw approvals --node ...` -Скорочений спосіб лише для сеансу: +Скорочення лише для сеансу: - `/exec security=full ask=off` змінює лише поточний сеанс. -- `/elevated full` — це аварійний скорочений спосіб, який також пропускає підтвердження виконання для цього сеансу. +- `/elevated full` — це аварійне скорочення, яке також пропускає затвердження виконання для цього сеансу. -Якщо файл підтверджень хоста залишається суворішим за конфігурацію, перевагу все одно має суворіша політика хоста. +Якщо файл затверджень хоста залишається суворішим за конфігурацію, усе одно перемагає суворіша політика хоста. ## Параметри політики ### Security (`exec.security`) - **deny**: блокувати всі запити на виконання на хості. -- **allowlist**: дозволяти лише команди зі списку дозволених елементів. +- **allowlist**: дозволяти лише команди зі списку дозволеного. - **full**: дозволяти все (еквівалент elevated). ### Ask (`exec.ask`) -- **off**: ніколи не запитувати. -- **on-miss**: запитувати лише тоді, коли список дозволених елементів не збігається. -- **always**: запитувати для кожної команди. -- довірений режим `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always` +- **off**: ніколи не показувати запит. +- **on-miss**: показувати запит лише тоді, коли список дозволеного не збігається. +- **always**: показувати запит для кожної команди. +- довготривала довіра `allow-always` не пригнічує запити, коли ефективний режим ask дорівнює `always` ### Ask fallback (`askFallback`) -Якщо потрібне підтвердження, але немає доступного UI, резервний варіант визначає дію: +Якщо потрібен запит, але жоден UI недоступний, резервна поведінка визначає: - **deny**: блокувати. -- **allowlist**: дозволяти лише за умови збігу зі списком дозволених елементів. +- **allowlist**: дозволяти лише за наявності збігу зі списком дозволеного. - **full**: дозволяти. -### Посилений режим inline eval для інтерпретаторів (`tools.exec.strictInlineEval`) +### Посилення inline interpreter eval (`tools.exec.strictInlineEval`) -Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують лише явного підтвердження, навіть якщо сам двійковий файл інтерпретатора внесений до списку дозволених елементів. +Коли `tools.exec.strictInlineEval=true`, OpenClaw розглядає форми inline code-eval як такі, що потребують лише затвердження, навіть якщо сам двійковий файл інтерпретатора є в списку дозволеного. Приклади: @@ -230,15 +232,18 @@ EOF - `lua -e` - `osascript -e` -Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються однозначно з одним стабільним файловим операндом. У строгому режимі: +Це захист у глибину для завантажувачів інтерпретаторів, які не зіставляються чисто з одним стабільним файловим операндом. У строгому режимі: -- такі команди все одно потребують явного підтвердження; -- `allow-always` не зберігає для них нові записи списку дозволених елементів автоматично. +- ці команди все одно потребують явного затвердження; +- `allow-always` не зберігає для них нові записи списку дозволеного автоматично. -## Список дозволених елементів (для кожного агента) +## Список дозволеного (для кожного агента) -Списки дозволених елементів є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, якого ви редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**. Шаблони мають відповідати **шляхам до двійкових файлів** (записи лише з basename ігноруються). Застарілі записи `agents.default` під час завантаження переносяться до `agents.main`. -Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволених елементів. +Списки дозволеного є **окремими для кожного агента**. Якщо існує кілька агентів, перемкніть агента, +якого ви редагуєте, у застосунку macOS. Шаблони — це **нечутливі до регістру glob-збіги**. +Шаблони мають розв’язуватися до **шляхів двійкових файлів** (записи лише з basename ігноруються). +Застарілі записи `agents.default` під час завантаження мігруються до `agents.main`. +Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимагають, щоб кожен сегмент верхнього рівня відповідав правилам списку дозволеного. Приклади: @@ -246,297 +251,65 @@ Shell-ланцюжки, як-от `echo ok && pwd`, усе одно вимага - `~/.local/bin/*` - `/opt/homebrew/bin/rg` -Кожен запис списку дозволених елементів відстежує: +Кожен запис списку дозволеного відстежує: -- **id** — стабільний UUID, що використовується для ідентифікації в UI (необов’язково) -- **last used** — мітка часу останнього використання +- **id** — стабільний UUID, який використовується для ідентичності в UI (необов’язково) +- **last used** — позначка часу останнього використання - **last used command** - **last resolved path** -## Автодозвіл для CLI зі Skills +## Автодозвіл для CLI Skills Коли ввімкнено **Auto-allow skill CLIs**, виконувані файли, на які посилаються відомі Skills, -вважаються внесеними до списку дозволених елементів на вузлах (вузол macOS або headless-хост вузла). Для цього використовується -`skills.bins` через Gateway RPC, щоб отримати список bin-файлів skill. Вимкніть це, якщо вам потрібні суворі ручні списки дозволених елементів. +розглядаються як такі, що входять до списку дозволеного на Node (macOS node або headless-хост Node). Для цього використовується +`skills.bins` через Gateway RPC, щоб отримати список bin для skill. Вимкніть це, якщо вам потрібні суворі списки дозволеного, задані вручну. Важливі примітки щодо довіри: -- Це **неявний зручний список дозволених елементів**, окремий від ручних записів списку дозволених шляхів. -- Він призначений для довірених середовищ операторів, де Gateway і вузол перебувають в одній межі довіри. -- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволених шляхів. +- Це **неявний зручний список дозволеного**, окремий від записів ручного списку дозволеного за шляхами. +- Він призначений для середовищ довірених операторів, де Gateway і Node перебувають в одній межі довіри. +- Якщо вам потрібна сувора явна довіра, залиште `autoAllowSkills: false` і використовуйте лише ручні записи списку дозволеного за шляхами. -## Безпечні bin-файли (лише stdin) +## Safe bins і пересилання затвердження -`tools.exec.safeBins` визначає невеликий список **bin-файлів лише для stdin** (наприклад, `cut`), які можуть працювати в режимі allowlist **без** явних записів у списку дозволених елементів. Безпечні bin-файли відхиляють позиційні аргументи файлів і токени, схожі на шляхи, тому можуть працювати лише з вхідним потоком. Сприймайте це як вузький швидкий шлях для потокових фільтрів, а не як загальний список довіри. +Щодо safe bins (швидкий шлях лише через stdin), деталей прив’язки інтерпретатора та того, +як пересилати запити на затвердження до Slack/Discord/Telegram (або запускати їх як нативні +клієнти затвердження), див. [Затвердження виконання — додатково](/uk/tools/exec-approvals-advanced). - -**Не** додавайте двійкові файли інтерпретаторів або середовищ виконання (наприклад, `python3`, `node`, -`ruby`, `bash`, `sh`, `zsh`) до `safeBins`. Якщо команда за своєю природою може обчислювати код, -виконувати підкоманди або читати файли, віддавайте перевагу явним записам списку дозволених елементів -і залишайте ввімкненими запити на підтвердження. Користувацькі safe bins мають визначати явний -профіль у `tools.exec.safeBinProfiles.`. - + -Типові safe bins: +## Редагування в UI керування -[//]: # "SAFE_BIN_DEFAULTS:START" +Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати типові значення, перевизначення +для окремих агентів і списки дозволеного. Виберіть область (Defaults або агент), налаштуйте політику, +додайте/видаліть шаблони списку дозволеного, а потім натисніть **Save**. UI показує метадані **last used** +для кожного шаблону, щоб вам було легше підтримувати список в охайному стані. -`cut`, `uniq`, `head`, `tail`, `tr`, `wc` - -[//]: # "SAFE_BIN_DEFAULTS:END" - -`grep` і `sort` не входять до типового списку. Якщо ви вмикаєте їх, зберігайте явні -записи списку дозволених елементів для їхніх сценаріїв, що не обмежуються stdin. Для `grep` у режимі safe-bin -вказуйте шаблон через `-e`/`--regexp`; позиційна форма шаблону відхиляється, -щоб файлові операнди не можна було непомітно передати як неоднозначні позиційні аргументи. - -### Перевірка Argv і заборонені прапорці - -Перевірка є детермінованою лише за формою argv (без перевірок існування файлової системи хоста), що запобігає поведінці оракула існування файлів через відмінності між allow/deny. Параметри, орієнтовані на файли, заборонені для типових safe bins; довгі параметри перевіряються за принципом fail-closed (невідомі прапорці й неоднозначні скорочення відхиляються). - -Заборонені прапорці за профілем safe-bin: - -[//]: # "SAFE_BIN_DENIED_FLAGS:START" - -- `grep`: `--dereference-recursive`, `--directories`, `--exclude-from`, `--file`, `--recursive`, `-R`, `-d`, `-f`, `-r` -- `jq`: `--argfile`, `--from-file`, `--library-path`, `--rawfile`, `--slurpfile`, `-L`, `-f` -- `sort`: `--compress-program`, `--files0-from`, `--output`, `--random-source`, `--temporary-directory`, `-T`, `-o` -- `wc`: `--files0-from` - -[//]: # "SAFE_BIN_DENIED_FLAGS:END" - -Safe bins також примусово обробляють токени argv як **буквальний текст** під час виконання -(без globbing і без розгортання `$VARS`) для сегментів лише зі stdin, тому шаблони -на кшталт `*` або `$HOME/...` не можна використати для прихованого читання файлів. - -### Довірені каталоги двійкових файлів - -Safe bins мають визначатися з довірених каталогів двійкових файлів (системні типові значення плюс необов’язкові `tools.exec.safeBinTrustedDirs`). Записи `PATH` ніколи не вважаються довіреними автоматично. Типові довірені каталоги навмисно мінімальні: `/bin`, `/usr/bin`. Якщо ваш виконуваний файл safe-bin розташовано в шляхах менеджера пакетів або користувача (наприклад, `/opt/homebrew/bin`, `/usr/local/bin`, `/opt/local/bin`, `/snap/bin`), додайте їх явно до `tools.exec.safeBinTrustedDirs`. - -### Ланцюжки shell-команд, обгортки та мультиплексори - -Ланцюжки shell-команд (`&&`, `||`, `;`) дозволені, коли кожен сегмент верхнього рівня відповідає списку дозволених елементів (зокрема safe bins або автодозвіл для skill). Переспрямування залишаються непідтримуваними в режимі allowlist. Підстановка команд (`$()` / зворотні лапки) відхиляється під час розбору allowlist, зокрема всередині подвійних лапок; використовуйте одинарні лапки, якщо вам потрібен буквальний текст `$()`. - -У підтвердженнях companion app на macOS необроблений текст shell, що містить керівний або розширювальний синтаксис shell (`&&`, `||`, `;`, `|`, `` ` ``, `$`, `<`, `>`, `(`, `)`), розглядається як промах allowlist, якщо сам двійковий файл shell не внесений до списку дозволених елементів. - -Для shell-обгорток (`bash|sh|zsh ... -c/-lc`) перевизначення env в межах запиту зводяться до невеликого явного списку дозволених елементів (`TERM`, `LANG`, `LC_*`, `COLORTERM`, `NO_COLOR`, `FORCE_COLOR`). - -Для рішень `allow-always` у режимі allowlist відомі обгортки-диспетчери (`env`, `nice`, `nohup`, `stdbuf`, `timeout`) зберігають внутрішній шлях до виконуваного файла замість шляху обгортки. Shell-мультиплексори (`busybox`, `toybox`) так само розгортаються для shell-аплетів (`sh`, `ash` тощо). Якщо обгортку або мультиплексор неможливо безпечно розгорнути, запис allowlist не зберігається автоматично. - -Якщо ви додаєте до allowlist інтерпретатори, як-от `python3` або `node`, краще встановити -`tools.exec.strictInlineEval=true`, щоб inline eval усе ще вимагав явного підтвердження. У строгому режимі `allow-always` усе ще може зберігати нешкідливі виклики інтерпретатора/скрипта, але носії inline-eval автоматично не зберігаються. - -### Safe bins проти allowlist - -| Тема | `tools.exec.safeBins` | Allowlist (`exec-approvals.json`) | -| ---------------- | ------------------------------------------------------ | ------------------------------------------------------------ | -| Призначення | Автодозвіл для вузьких stdin-фільтрів | Явна довіра до конкретних виконуваних файлів | -| Тип збігу | Назва виконуваного файла + політика argv safe-bin | Glob-шаблон шляху до визначеного виконуваного файла | -| Область аргументів | Обмежена профілем safe-bin і правилами буквальних токенів | Лише збіг шляху; за аргументи в іншому відповідаєте ви | -| Типові приклади | `head`, `tail`, `tr`, `wc` | `jq`, `python3`, `node`, `ffmpeg`, користувацькі CLI | -| Найкраще застосування | Низькоризикові текстові перетворення в конвеєрах | Будь-який інструмент із ширшою поведінкою або побічними ефектами | - -Розташування конфігурації: - -- `safeBins` надходить із конфігурації (`tools.exec.safeBins` або `agents.list[].tools.exec.safeBins` для конкретного агента). -- `safeBinTrustedDirs` надходить із конфігурації (`tools.exec.safeBinTrustedDirs` або `agents.list[].tools.exec.safeBinTrustedDirs` для конкретного агента). -- `safeBinProfiles` надходить із конфігурації (`tools.exec.safeBinProfiles` або `agents.list[].tools.exec.safeBinProfiles` для конкретного агента). Ключі профілів для конкретного агента перевизначають глобальні ключі. -- записи allowlist зберігаються в локальному для хоста `~/.openclaw/exec-approvals.json` у `agents..allowlist` (або через Control UI / `openclaw approvals allowlist ...`). -- `openclaw security audit` попереджає через `tools.exec.safe_bins_interpreter_unprofiled`, коли двійкові файли інтерпретатора/середовища виконання з’являються в `safeBins` без явних профілів. -- `openclaw doctor --fix` може створити шаблони відсутніх користувацьких записів `safeBinProfiles.` як `{}` (перегляньте та посильте їх після цього). Для двійкових файлів інтерпретатора/середовища виконання шаблони не створюються автоматично. - -Приклад користувацького профілю: -__OC_I18N_900005__ -Якщо ви явно додаєте `jq` до `safeBins`, OpenClaw усе одно відхиляє вбудовану команду `env` у режимі safe-bin, -щоб `jq -n env` не міг вивантажити середовище процесу хоста без явного шляху allowlist -або запиту на підтвердження. - -## Редагування в Control UI - -Використовуйте картку **Control UI → Nodes → Exec approvals**, щоб редагувати значення за замовчуванням, перевизначення для конкретного агента та списки дозволених елементів. Виберіть область (Defaults або агент), змініть політику, додайте/видаліть шаблони allowlist, а потім натисніть **Save**. UI показує метадані **last used** для кожного шаблону, щоб список залишався впорядкованим. - -Селектор цілі вибирає **Gateway** (локальні підтвердження) або **Node**. Вузли -мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост вузла). -Якщо вузол ще не оголошує підтвердження виконання, редагуйте його локальний +Перемикач цілі вибирає **Gateway** (локальні затвердження) або **Node**. Node +мають оголошувати `system.execApprovals.get/set` (застосунок macOS або headless-хост Node). +Якщо Node ще не оголошує затвердження виконання, редагуйте її локальний `~/.openclaw/exec-approvals.json` безпосередньо. -CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI підтверджень](/cli/approvals)). +CLI: `openclaw approvals` підтримує редагування gateway або node (див. [CLI затверджень](/uk/cli/approvals)). -## Потік підтвердження +## Потік затвердження -Коли потрібне підтвердження, gateway транслює `exec.approval.requested` клієнтам операторів. -Control UI і застосунок macOS обробляють це через `exec.approval.resolve`, а потім gateway пересилає -схвалений запит до хоста вузла. +Коли потрібен запит, gateway розсилає `exec.approval.requested` клієнтам операторів. +Control UI і застосунок macOS обробляють його через `exec.approval.resolve`, після чого gateway пересилає +затверджений запит на хост Node. -Для `host=node` запити на підтвердження містять канонічний payload `systemRunPlan`. Gateway використовує -цей план як авторитетний контекст command/cwd/session під час пересилання схвалених запитів `system.run`. +Для `host=node` запити на затвердження містять канонічне корисне навантаження `systemRunPlan`. Gateway використовує +цей план як авторитетний контекст команди/cwd/сеансу під час пересилання затверджених запитів `system.run`. -Це важливо для затримки асинхронного підтвердження: +Це важливо для затримки асинхронного затвердження: -- шлях виконання вузла готує один канонічний план наперед -- запис підтвердження зберігає цей план і його метадані прив’язки -- після схвалення остаточний пересланий виклик `system.run` повторно використовує збережений план - замість довіри до пізніших змін з боку викликача -- якщо викликач змінює `command`, `rawCommand`, `cwd`, `agentId` або - `sessionKey` після створення запиту на підтвердження, gateway відхиляє - пересланий запуск як невідповідність підтвердженню - -## Команди інтерпретатора/середовища виконання - -Запуски інтерпретатора/середовища виконання, підтримані підтвердженням, навмисно консервативні: - -- Точний контекст argv/cwd/env завжди прив’язується. -- Форми прямого shell-скрипта й прямого файла середовища виконання прив’язуються в режимі best-effort до одного конкретного локального знімка файла. -- Поширені форми обгорток менеджерів пакетів, які все ще визначаються як один прямий локальний файл (наприклад - `pnpm exec`, `pnpm node`, `npm exec`, `npx`), розгортаються перед прив’язкою. -- Якщо OpenClaw не може визначити рівно один конкретний локальний файл для команди інтерпретатора/середовища виконання - (наприклад package scripts, eval-форми, специфічні для середовища виконання ланцюжки завантаження або неоднозначні багатофайлові - форми), виконання, підтримане підтвердженням, відхиляється замість того, щоб заявляти про семантичне покриття, - якого насправді немає. -- Для таких сценаріїв краще використовувати пісочницю, окрему межу хоста або явний - довірений робочий процес allowlist/full, де оператор приймає ширшу семантику середовища виконання. - -Коли потрібні підтвердження, інструмент exec одразу повертає ідентифікатор підтвердження. Використовуйте цей ідентифікатор, щоб -співвідносити подальші системні події (`Exec finished` / `Exec denied`). Якщо до завершення -тайм-ауту рішення не надійде, запит вважається таким, що перевищив час очікування підтвердження, і відображається як причина відхилення. - -### Поведінка доставлення followup - -Після завершення схваленого асинхронного exec OpenClaw надсилає followup-хід `agent` у той самий сеанс. - -- Якщо існує коректна зовнішня ціль доставлення (канал із можливістю доставлення плюс ціль `to`), доставлення followup використовує цей канал. -- У потоках лише вебчату або внутрішнього сеансу без зовнішньої цілі доставлення followup залишається лише в межах сеансу (`deliver: false`). -- Якщо викликач явно запитує суворе зовнішнє доставлення без такого зовнішнього каналу, запит завершується помилкою `INVALID_REQUEST`. -- Якщо ввімкнено `bestEffortDeliver` і зовнішній канал не вдається визначити, доставлення знижується до режиму лише для сеансу замість помилки. - -Діалог підтвердження містить: - -- command + args -- cwd -- id агента -- визначений шлях до виконуваного файла -- метадані host + policy - -Дії: - -- **Allow once** → виконати зараз -- **Always allow** → додати до allowlist + виконати -- **Deny** → заблокувати - -## Пересилання підтверджень до чат-каналів - -Ви можете пересилати запити на підтвердження exec до будь-якого чат-каналу (зокрема каналів Plugin) і схвалювати -їх через `/approve`. Для цього використовується звичайний конвеєр вихідного доставлення. - -Конфігурація: -__OC_I18N_900006__ -Відповідь у чаті: -__OC_I18N_900007__ -Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin. Якщо ID не відповідає очікуваному підтвердженню exec, вона автоматично перевіряє підтвердження Plugin. - -### Пересилання підтверджень Plugin - -Пересилання підтверджень Plugin використовує той самий конвеєр доставлення, що й підтвердження exec, але має власну -незалежну конфігурацію в `approvals.plugin`. Увімкнення або вимкнення одного не впливає на інше. -__OC_I18N_900008__ -Форма конфігурації ідентична до `approvals.exec`: `enabled`, `mode`, `agentFilter`, -`sessionFilter` і `targets` працюють однаково. - -Канали, що підтримують спільні інтерактивні відповіді, відображають однакові кнопки підтвердження як для exec, так і для -підтверджень Plugin. Канали без спільного інтерактивного UI повертаються до звичайного тексту з інструкціями `/approve`. - -### Підтвердження в тому самому чаті на будь-якому каналі - -Коли запит на підтвердження exec або Plugin походить із чат-поверхні з можливістю доставлення, той самий чат -тепер може схвалити його через `/approve` за замовчуванням. Це стосується таких каналів, як Slack, Matrix і -Microsoft Teams, на додачу до вже наявних потоків Web UI і terminal UI. - -Цей спільний шлях текстових команд використовує звичайну модель автентифікації каналу для цієї розмови. Якщо початковий -чат уже може надсилати команди й отримувати відповіді, запитам на підтвердження більше не потрібен -окремий нативний адаптер доставлення, щоб залишатися в стані очікування. - -Discord і Telegram також підтримують `/approve` у тому самому чаті, але ці канали й далі використовують свій -визначений список схвалювачів для авторизації, навіть коли нативне доставлення підтверджень вимкнено. - -Для Telegram та інших нативних клієнтів підтвердження, які викликають Gateway напряму, -цей резервний варіант навмисно обмежений помилками типу «підтвердження не знайдено». Реальна -відмова/помилка підтвердження exec не повторюється мовчки як підтвердження Plugin. - -### Нативне доставлення підтверджень - -Деякі канали також можуть працювати як нативні клієнти підтвердження. Нативні клієнти додають DM схвалювачам, fanout у чаті походження -і специфічний для каналу інтерактивний UX підтвердження поверх спільного потоку `/approve` -у тому самому чаті. - -Коли доступні нативні картки/кнопки підтвердження, цей нативний UI є основним -шляхом для агента. Агент не повинен також дублювати звичайну чат-команду -`/approve`, якщо тільки результат інструмента не вказує, що чат-підтвердження недоступні або -єдиним варіантом, що залишився, є ручне підтвердження. - -Загальна модель: - -- політика виконання на хості все ще визначає, чи потрібне підтвердження exec -- `approvals.exec` керує пересиланням запитів на підтвердження до інших цільових чатів -- `channels..execApprovals` визначає, чи діє цей канал як нативний клієнт підтвердження - -Нативні клієнти підтвердження автоматично вмикають доставлення спочатку в DM, коли виконуються всі ці умови: - -- канал підтримує нативне доставлення підтверджень -- схвалювачів можна визначити з явних `execApprovals.approvers` або з - документованих резервних джерел цього каналу -- `channels..execApprovals.enabled` не задано або дорівнює `"auto"` - -Установіть `enabled: false`, щоб явно вимкнути нативний клієнт підтвердження. Установіть `enabled: true`, щоб примусово -увімкнути його, коли визначаються схвалювачі. Публічне доставлення до чату походження й надалі задається явно через -`channels..execApprovals.target`. - -FAQ: [Чому для чат-підтверджень існують дві конфігурації підтвердження exec?](/help/faq#why-are-there-two-exec-approval-configs-for-chat-approvals) - -- Discord: `channels.discord.execApprovals.*` -- Slack: `channels.slack.execApprovals.*` -- Telegram: `channels.telegram.execApprovals.*` - -Ці нативні клієнти підтвердження додають маршрутизацію DM і необов’язковий fanout у канал поверх спільного -потоку `/approve` у тому самому чаті та спільних кнопок підтвердження. - -Спільна поведінка: - -- Slack, Matrix, Microsoft Teams і подібні чати з можливістю доставлення використовують звичайну модель автентифікації каналу - для `/approve` у тому самому чаті -- коли нативний клієнт підтвердження вмикається автоматично, типовою ціллю нативного доставлення є DM схвалювачам -- для Discord і Telegram лише визначені схвалювачі можуть схвалювати або відхиляти -- схвалювачі Discord можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- схвалювачі Telegram можуть бути явними (`execApprovals.approvers`) або виведеними з наявної конфігурації власника (`allowFrom`, а також `defaultTo` для прямих повідомлень, де це підтримується) -- схвалювачі Slack можуть бути явними (`execApprovals.approvers`) або виведеними з `commands.ownerAllowFrom` -- нативні кнопки Slack зберігають тип id підтвердження, тому id `plugin:` можуть обробляти підтвердження Plugin - без другого локального резервного рівня Slack -- нативна маршрутизація DM/каналу в Matrix і швидкі реакції обробляють як підтвердження exec, так і Plugin; - авторизація Plugin і надалі походить із `channels.matrix.dm.allowFrom` -- запитувач не зобов’язаний бути схвалювачем -- чат походження може схвалити запит напряму через `/approve`, коли цей чат уже підтримує команди й відповіді -- нативні кнопки підтвердження Discord маршрутизують за типом id підтвердження: id `plugin:` переходять - безпосередньо до підтверджень Plugin, усе інше — до підтверджень exec -- нативні кнопки підтвердження Telegram дотримуються того самого обмеженого резервного переходу від exec до Plugin, що й `/approve` -- коли нативний `target` вмикає доставлення до чату походження, запити на підтвердження містять текст команди -- очікувані підтвердження exec типово спливають через 30 хвилин -- якщо жоден UI оператора або налаштований клієнт підтвердження не може прийняти запит, для запиту використовується `askFallback` - -Для Telegram типово використовуються DM схвалювачам (`target: "dm"`). Ви можете переключитися на `channel` або `both`, якщо -хочете, щоб запити на підтвердження також з’являлися в початковому чаті/темі Telegram. Для тем форуму Telegram -OpenClaw зберігає тему для запиту на підтвердження та follow-up після підтвердження. - -Див. також: - -- [Discord](/channels/discord) -- [Telegram](/channels/telegram) - -### Потік IPC у macOS -__OC_I18N_900009__ -Примітки щодо безпеки: - -- Режим Unix socket `0600`, токен зберігається в `exec-approvals.json`. -- Перевірка peer з тим самим UID. -- Challenge/response (nonce + HMAC token + hash запиту) + короткий TTL. +- шлях виконання node готує один канонічний план наперед +- запис затвердження зберігає цей план та його метадані прив’язки +- після затвердження остаточний пересланий виклик `system.run` повторно використовує збережений план + замість того, щоб довіряти пізнішим змінам виклику +- якщо виклик змінює `command`, `rawCommand`, `cwd`, `agentId` або + `sessionKey` після створення запиту на затвердження, gateway відхиляє + пересланий запуск як невідповідність затвердженню ## Системні події @@ -546,34 +319,37 @@ __OC_I18N_900009__ - `Exec finished` - `Exec denied` -Вони публікуються в сеанс агента після того, як вузол повідомляє про подію. -Підтвердження exec на gateway host генерують ті самі події життєвого циклу, коли команда завершується (і необов’язково коли виконується довше за поріг). -Виклики exec, захищені підтвердженням, повторно використовують id підтвердження як `runId` у цих повідомленнях для зручного зіставлення. +Вони публікуються в сеанс агента після того, як Node повідомляє про подію. +Затвердження виконання на gateway-host видають ті самі події життєвого циклу, коли команда завершується (і, за потреби, коли вона виконується довше за поріг). +Виконання з перевіркою через затвердження повторно використовують ідентифікатор затвердження як `runId` у цих повідомленнях для зручної кореляції. -## Поведінка при відхиленому підтвердженні +## Поведінка у разі відхилення затвердження -Коли підтвердження асинхронного exec відхиляється, OpenClaw не дозволяє агенту повторно використовувати -вивід із будь-якого попереднього запуску тієї самої команди в межах сеансу. Причина відхилення -передається з явною вказівкою, що вивід команди недоступний, що не дає -агенту стверджувати, ніби є новий вивід, або повторювати відхилену команду зі -застарілими результатами попереднього успішного запуску. +Коли асинхронне затвердження виконання відхиляється, OpenClaw не дозволяє агенту повторно використовувати +вивід будь-якого попереднього запуску тієї самої команди в цьому сеансі. Причина відхилення +передається разом із явною вказівкою, що вивід команди недоступний, що не дає +агенту стверджувати, що є новий вивід, або повторювати відхилену команду зі +застарілими результатами з попереднього успішного запуску. ## Наслідки -- **full** є потужним режимом; коли можливо, віддавайте перевагу спискам дозволених елементів. -- **ask** тримає вас у контурі, водночас дозволяючи швидкі підтвердження. -- Списки дозволених елементів для кожного агента окремо не дають підтвердженням одного агента «просочуватися» до інших. -- Підтвердження застосовуються лише до запитів exec на хості від **авторизованих відправників**. Неавторизовані відправники не можуть виконувати `/exec`. -- `/exec security=full` — це зручний параметр рівня сеансу для авторизованих операторів, і він навмисно пропускає підтвердження. Щоб жорстко заблокувати виконання на хості, установіть для security підтверджень значення `deny` або забороніть інструмент `exec` через політику інструментів. +- **full** — потужний режим; коли можливо, надавайте перевагу спискам дозволеного. +- **ask** тримає вас у курсі подій, водночас дозволяючи швидкі затвердження. +- Окремі для кожного агента списки дозволеного не дають затвердженням одного агента поширюватися на інших. +- Затвердження застосовуються лише до запитів на виконання на хості від **авторизованих відправників**. Неавторизовані відправники не можуть видавати `/exec`. +- `/exec security=full` — це зручність на рівні сеансу для авторизованих операторів і за задумом пропускає затвердження. Щоб жорстко заблокувати виконання на хості, установіть для затверджень значення security `deny` або забороніть інструмент `exec` через політику інструментів. ## Пов’язане - - Інструмент виконання shell-команд. + + Safe bins, прив’язка інтерпретатора та пересилання затверджень до чату. + + + Інструмент виконання команд shell. - Аварійний шлях, який також пропускає підтвердження. + Аварійний шлях, який також пропускає затвердження. Режими пісочниці та доступ до робочого простору. @@ -582,7 +358,7 @@ __OC_I18N_900009__ Модель безпеки та посилення захисту. - Коли варто використовувати кожен із цих механізмів. + Коли варто використовувати кожен із цих засобів керування. Поведінка автодозволу на основі Skills. diff --git a/docs/uk/tools/exec.md b/docs/uk/tools/exec.md index f6948393e..3c969e955 100644 --- a/docs/uk/tools/exec.md +++ b/docs/uk/tools/exec.md @@ -1,26 +1,26 @@ --- read_when: - - Використання або змінення інструмента Exec + - Використання або змінення інструмента exec - Налагодження поведінки stdin або TTY -summary: Використання інструмента Exec, режими stdin і підтримка TTY -title: Інструмент Exec +summary: Використання інструмента exec, режими stdin і підтримка TTY +title: Інструмент exec x-i18n: - generated_at: "2026-04-23T23:07:45Z" + generated_at: "2026-04-23T23:27:47Z" model: gpt-5.4 provider: openai - source_hash: 4e2a7fc3b0570d59a6694d0a4ff9def1a5721c8a3d13abf7f947e7ea835535b3 + source_hash: 4cad17fecfaf7d6a523282ef4f0090e4ffaab89ab53945b5cd831e426f3fc3ac source_path: tools/exec.md workflow: 15 --- -Запускає shell-команди у workspace. Підтримує виконання у foreground + background через `process`. -Якщо `process` заборонено, `exec` виконується синхронно й ігнорує `yieldMs`/`background`. -Background-сесії мають область дії в межах агента; `process` бачить лише сесії того самого агента. +Запускає shell-команди в робочому просторі. Підтримує виконання на передньому плані й у фоновому режимі через `process`. +Якщо `process` недоступний, `exec` запускається синхронно та ігнорує `yieldMs`/`background`. +Фонові сесії обмежені межами агента; `process` бачить лише сесії того самого агента. ## Параметри -Команда shell для запуску. +Shell-команда для запуску. @@ -28,27 +28,27 @@ Background-сесії мають область дії в межах агент -Перевизначення середовища у форматі ключ/значення, об’єднані поверх успадкованого середовища. +Перевизначення змінних середовища у форматі ключ/значення, які об’єднуються поверх успадкованого середовища. -Автоматично переводить команду в background після цієї затримки (мс). +Автоматично переводить команду у фоновий режим після цієї затримки (мс). -Негайно переводить команду в background замість очікування `yieldMs`. +Негайно переводить команду у фоновий режим замість очікування `yieldMs`. -Завершити команду після такої кількості секунд. +Завершує команду після такої кількості секунд. -Запускати в псевдотерміналі, якщо доступно. Використовуйте для CLI, що працюють лише з TTY, coding-агентів і terminal UI. +Запускає в псевдотерміналі, коли це можливо. Використовуйте для CLI, що потребують TTY, агентів кодування та термінальних UI. -Де виконувати. `auto` перетворюється на `sandbox`, коли активний runtime sandbox, і на `gateway` в іншому разі. +Де виконувати. `auto` визначається як `sandbox`, коли для середовища виконання активний sandbox, інакше як `gateway`. @@ -56,63 +56,63 @@ Background-сесії мають область дії в межах агент -Поведінка запиту погодження для виконання `gateway` / `node`. +Поведінка запиту на схвалення для виконання `gateway` / `node`. -Id/назва Node, коли `host=node`. +Ідентифікатор або назва Node, коли `host=node`. -Запитати elevated mode — вийти із sandbox на налаштований шлях хоста. `security=full` примусово застосовується лише тоді, коли elevated перетворюється на `full`. +Запитує підвищений режим — вихід із sandbox на налаштований шлях хоста. `security=full` примусово встановлюється лише тоді, коли elevated визначається як `full`. Примітки: -- `host` типово дорівнює `auto`: sandbox, коли runtime sandbox активний для сесії, інакше gateway. -- `auto` — це типова стратегія маршрутизації, а не wildcard. Виклик `host=node` для окремого запиту дозволено з `auto`; виклик `host=gateway` для окремого запиту дозволено лише тоді, коли runtime sandbox неактивний. -- Без додаткового config `host=auto` усе одно «просто працює»: без sandbox він перетворюється на `gateway`; з активним sandbox залишається в sandbox. -- `elevated` виходить із sandbox на налаштований шлях хоста: типово `gateway`, або `node`, коли `tools.exec.host=node` (або типовим значенням сесії є `host=node`). Це доступно лише тоді, коли для поточної сесії/провайдера ввімкнено elevated access. -- Погодження `gateway`/`node` керуються через `~/.openclaw/exec-approvals.json`. -- `node` потребує pairied Node (companion app або headless-хост Node). -- Якщо доступно кілька Node, задайте `exec.node` або `tools.exec.node`, щоб вибрати одну. -- `exec host=node` — це єдиний шлях виконання shell для Node; застарілу обгортку `nodes.run` видалено. -- На хостах не з Windows exec використовує `SHELL`, якщо його задано; якщо `SHELL` — це `fish`, він надає перевагу `bash` (або `sh`) - з `PATH`, щоб уникнути несумісних із fish скриптів, а потім повертається до `SHELL`, якщо жодного з них немає. -- На хостах Windows exec надає перевагу пошуку PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, потім PATH), +- `host` типово має значення `auto`: sandbox, коли для сесії активне середовище виконання sandbox, інакше gateway. +- `auto` — це типова стратегія маршрутизації, а не шаблон. Виклик із `host=node` на рівні окремого запиту дозволений із `auto`; виклик із `host=gateway` на рівні окремого запиту дозволений лише тоді, коли середовище виконання sandbox не активне. +- Без додаткової конфігурації `host=auto` усе одно «просто працює»: без sandbox він визначається як `gateway`; з активним sandbox лишається в sandbox. +- `elevated` виводить із sandbox на налаштований шлях хоста: типово `gateway`, або `node`, коли `tools.exec.host=node` (або типовим для сесії є `host=node`). Доступний лише тоді, коли для поточної сесії/провайдера ввімкнено підвищений доступ. +- Схвалення для `gateway`/`node` керуються через `~/.openclaw/exec-approvals.json`. +- Для `node` потрібен спарений Node (додаток-компаньйон або безголовий вузол-хост). +- Якщо доступно кілька Node, установіть `exec.node` або `tools.exec.node`, щоб вибрати один. +- `exec host=node` — єдиний шлях виконання shell-команд для Node; застарілу обгортку `nodes.run` вилучено. +- На хостах, відмінних від Windows, exec використовує `SHELL`, якщо його задано; якщо `SHELL` має значення `fish`, він віддає перевагу `bash` (або `sh`) + із `PATH`, щоб уникнути скриптів, несумісних із fish, а потім повертається до `SHELL`, якщо жоден із них не існує. +- На хостах Windows exec віддає перевагу пошуку PowerShell 7 (`pwsh`) (Program Files, ProgramW6432, потім PATH), а потім повертається до Windows PowerShell 5.1. -- Виконання на хості (`gateway`/`node`) відхиляє `env.PATH` і перевизначення loader (`LD_*`/`DYLD_*`), щоб +- Виконання на хості (`gateway`/`node`) відхиляє перевизначення `env.PATH` і завантажувача (`LD_*`/`DYLD_*`), щоб запобігти підміні бінарних файлів або ін’єкції коду. -- OpenClaw задає `OPENCLAW_SHELL=exec` у середовищі запущеної команди (включно з PTY і виконанням у sandbox), щоб правила shell/profile могли визначати контекст exec-tool. -- Важливо: sandboxing **вимкнений типово**. Якщо sandboxing вимкнено, неявний `host=auto` - перетворюється на `gateway`. Явний `host=sandbox` усе одно завершується в режимі fail-closed замість тихого - виконання на хості gateway. Увімкніть sandboxing або використовуйте `host=gateway` з погодженнями. -- Preflight-перевірки скриптів (для типових помилок синтаксису shell у Python/Node) перевіряють лише файли в межах - ефективної межі `workdir`. Якщо шлях до скрипта перетворюється на такий, що виходить за межі `workdir`, preflight для - цього файла пропускається. -- Для довготривалої роботи, яка починається зараз, запустіть її один раз і покладайтеся на автоматичне - пробудження після завершення, коли воно ввімкнене і команда виводить щось або завершується помилкою. - Використовуйте `process` для журналів, статусу, введення або втручання; не імітуйте - планування через цикли sleep, цикли timeout або повторне polling. -- Для роботи, яка має відбутися пізніше або за розкладом, використовуйте cron замість - шаблонів sleep/delay через `exec`. +- OpenClaw установлює `OPENCLAW_SHELL=exec` у середовищі запущеної команди (зокрема для PTY і виконання в sandbox), щоб правила shell/профілю могли виявити контекст інструмента exec. +- Важливо: sandboxing **типово вимкнений**. Якщо sandboxing вимкнено, неявний `host=auto` + визначається як `gateway`. Явний `host=sandbox` у такому разі все одно завершується закритою відмовою, а не тихо + запускається на хості gateway. Увімкніть sandboxing або використовуйте `host=gateway` зі схваленнями. +- Перевірки preflight для скриптів (для поширених помилок синтаксису shell у Python/Node) перевіряють лише файли в межах + фактичної межі `workdir`. Якщо шлях до скрипта визначається поза `workdir`, preflight для + цього файлу пропускається. +- Для довготривалої роботи, яка починається зараз, запускайте її один раз і покладайтеся на автоматичне + пробудження після завершення, якщо воно ввімкнене і команда виводить результат або завершується з помилкою. + Використовуйте `process` для журналів, стану, введення або втручання; не імітуйте + планування за допомогою циклів sleep, циклів timeout або повторного опитування. +- Для роботи, яка має відбутися пізніше або за розкладом, використовуйте Cron замість + шаблонів sleep/delay з `exec`. -## Config +## Конфігурація -- `tools.exec.notifyOnExit` (типово: true): якщо true, переведені в background exec-сесії ставлять у чергу system event і запитують Heartbeat під час завершення. -- `tools.exec.approvalRunningNoticeMs` (типово: 10000): видає одне сповіщення “running”, коли exec із погодженням виконується довше за цей час (0 вимикає). -- `tools.exec.host` (типово: `auto`; перетворюється на `sandbox`, коли runtime sandbox активний, інакше на `gateway`) -- `tools.exec.security` (типово: `deny` для sandbox, `full` для gateway + node, якщо не задано) +- `tools.exec.notifyOnExit` (типово: true): якщо true, фонові сесії exec ставлять системну подію в чергу та запитують Heartbeat після завершення. +- `tools.exec.approvalRunningNoticeMs` (типово: 10000): надсилає одне сповіщення «виконується», коли exec, що потребує схвалення, працює довше за цей час (0 вимикає). +- `tools.exec.host` (типово: `auto`; визначається як `sandbox`, коли активне середовище виконання sandbox, інакше як `gateway`) +- `tools.exec.security` (типово: `deny` для sandbox, `full` для gateway і node, якщо не задано) - `tools.exec.ask` (типово: `off`) -- Виконання host exec без погодження є типовим для gateway + node. Якщо вам потрібна поведінка з погодженнями/allowlist, посильте і `tools.exec.*`, і політику хоста `~/.openclaw/exec-approvals.json`; див. [Погодження Exec](/uk/tools/exec-approvals#no-approval-yolo-mode). -- YOLO походить із типових значень політики хоста (`security=full`, `ask=off`), а не з `host=auto`. Якщо хочете примусово використовувати маршрутизацію gateway або node, задайте `tools.exec.host` або використовуйте `/exec host=...`. -- У режимі `security=full` плюс `ask=off` host exec напряму дотримується налаштованої policy; немає додаткового евристичного prefilter заплутування команд або шару відхилення script-preflight. +- Виконання на хості без схвалення є типовим для gateway і node. Якщо потрібна поведінка зі схваленнями/allowlist, посильте як `tools.exec.*`, так і політику хоста в `~/.openclaw/exec-approvals.json`; див. [Схвалення exec](/uk/tools/exec-approvals#no-approval-yolo-mode). +- Режим YOLO походить із типових значень політики хоста (`security=full`, `ask=off`), а не з `host=auto`. Якщо потрібно примусово використовувати gateway або node, установіть `tools.exec.host` або використайте `/exec host=...`. +- У режимі `security=full` разом із `ask=off` виконання на хості напряму дотримується налаштованої політики; немає додаткового евристичного префільтра затемнення команд або шару відхилення script-preflight. - `tools.exec.node` (типово: не задано) -- `tools.exec.strictInlineEval` (типово: false): якщо true, форми inline eval інтерпретаторів, такі як `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` і `osascript -e`, завжди потребують явного погодження. `allow-always` усе ще може зберігати довіру для безпечних викликів інтерпретатора/скрипта, але форми inline-eval усе одно запитують щоразу. -- `tools.exec.pathPrepend`: список каталогів, які потрібно додати на початок `PATH` для запусків exec (лише gateway + sandbox). -- `tools.exec.safeBins`: безпечні бінарні файли лише для stdin, які можуть працювати без явних записів у allowlist. Докладніше про поведінку див. в [Safe bins](/uk/tools/exec-approvals#safe-bins-stdin-only). -- `tools.exec.safeBinTrustedDirs`: додаткові явні каталоги, яким довіряють для перевірок шляхів виконуваних файлів safeBins. Записи `PATH` ніколи не вважаються надійними автоматично. Вбудовані типові значення — `/bin` і `/usr/bin`. -- `tools.exec.safeBinProfiles`: необов’язкова власна policy argv для кожного safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`). +- `tools.exec.strictInlineEval` (типово: false): якщо true, вбудовані форми eval в інтерпретаторах, як-от `python -c`, `node -e`, `ruby -e`, `perl -e`, `php -r`, `lua -e` і `osascript -e`, завжди вимагають явного схвалення. `allow-always` усе ще може зберігати довіру до безпечних викликів інтерпретаторів/скриптів, але форми inline-eval все одно щоразу запитують схвалення. +- `tools.exec.pathPrepend`: список каталогів, які потрібно додати на початок `PATH` для запусків exec (лише gateway і sandbox). +- `tools.exec.safeBins`: безпечні бінарні файли лише для stdin, які можуть запускатися без явних записів у allowlist. Подробиці поведінки див. у [Safe bins](/uk/tools/exec-approvals-advanced#safe-bins-stdin-only). +- `tools.exec.safeBinTrustedDirs`: додаткові явні каталоги, яким довіряють для перевірок шляхів виконуваних файлів у `safeBins`. Записи `PATH` ніколи не вважаються довіреними автоматично. Вбудовані типові значення — `/bin` і `/usr/bin`. +- `tools.exec.safeBinProfiles`: необов’язкова спеціальна політика argv для кожного safe bin (`minPositional`, `maxPositional`, `allowedValueFlags`, `deniedFlags`). Приклад: @@ -128,29 +128,29 @@ Id/назва Node, коли `host=node`. ### Обробка PATH -- `host=gateway`: об’єднує `PATH` вашого login-shell із середовищем exec. Перевизначення `env.PATH` - відхиляються для виконання на хості. Сам daemon усе одно працює з мінімальним `PATH`: +- `host=gateway`: об’єднує `PATH` вашої login-shell у середовище exec. Перевизначення `env.PATH` + відхиляються для виконання на хості. Сам демон і далі працює з мінімальним `PATH`: - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin` - Linux: `/usr/local/bin`, `/usr/bin`, `/bin` -- `host=sandbox`: запускає `sh -lc` (login shell) всередині контейнера, тому `/etc/profile` може скидати `PATH`. - OpenClaw додає `env.PATH` на початок після завантаження profile через внутрішню env var (без shell-інтерполяції); +- `host=sandbox`: запускає `sh -lc` (login shell) усередині контейнера, тому `/etc/profile` може скидати `PATH`. + OpenClaw додає `env.PATH` на початок після завантаження профілю через внутрішню змінну середовища (без інтерполяції shell); `tools.exec.pathPrepend` теж застосовується тут. -- `host=node`: на Node надсилаються лише не заблоковані перевизначення env, які ви передаєте. Перевизначення `env.PATH` - відхиляються для виконання на хості й ігноруються Node-хостами. Якщо вам потрібні додаткові записи PATH на Node, - налаштуйте середовище служби хоста Node (systemd/launchd) або встановіть інструменти в стандартні місця. +- `host=node`: лише передані вами перевизначення середовища, які не заблоковано, надсилаються до Node. Перевизначення `env.PATH` + відхиляються для виконання на хості та ігноруються хостами Node. Якщо вам потрібні додаткові записи PATH на Node, + налаштуйте середовище служби хоста Node (systemd/launchd) або встановіть інструменти в стандартні розташування. -Прив’язка Node для окремого агента (використовуйте індекс списку агентів у config): +Прив’язка Node на рівні агента (використовуйте індекс у списку агентів у конфігурації): ```bash openclaw config get agents.list openclaw config set agents.list[0].tools.exec.node "node-id-or-name" ``` -Control UI: вкладка Nodes містить невелику панель “Exec node binding” для тих самих налаштувань. +Керувальний UI: вкладка Nodes містить невелику панель “Exec node binding” для тих самих налаштувань. ## Перевизначення сесії (`/exec`) -Використовуйте `/exec`, щоб задати **типові значення для поточної сесії** для `host`, `security`, `ask` і `node`. +Використовуйте `/exec`, щоб установити **типові значення для поточної сесії** для `host`, `security`, `ask` і `node`. Надішліть `/exec` без аргументів, щоб показати поточні значення. Приклад: @@ -161,71 +161,72 @@ Control UI: вкладка Nodes містить невелику панель ## Модель авторизації -`/exec` обробляється лише для **авторизованих відправників** (allowlist/pairing каналу плюс `commands.useAccessGroups`). -Вона оновлює **лише стан сесії** і не записує config. Щоб жорстко вимкнути exec, забороніть його через tool -policy (`tools.deny: ["exec"]` або для окремого агента). Погодження хоста все одно застосовуються, якщо ви явно не задали +`/exec` враховується лише для **авторизованих відправників** (allowlist каналів/спарювання плюс `commands.useAccessGroups`). +Він оновлює **лише стан сесії** і не записує конфігурацію. Щоб повністю вимкнути exec, забороніть його через +політику інструментів (`tools.deny: ["exec"]` або на рівні агента). Схвалення на хості все одно застосовуються, якщо ви явно не встановите `security=full` і `ask=off`. -## Погодження Exec (companion app / host Node) +## Схвалення exec (додаток-компаньйон / хост node) -Sandboxed-агенти можуть вимагати погодження для кожного запиту, перш ніж `exec` виконуватиметься на хості gateway або node. -Див. [Погодження Exec](/uk/tools/exec-approvals) для policy, allowlist і потоку UI. +Агенти в sandbox можуть вимагати схвалення для кожного запиту перед тим, як `exec` буде запущено на хості gateway або node. +Опис політики, allowlist і потоку UI див. у [Схвалення exec](/uk/tools/exec-approvals). -Коли потрібні погодження, інструмент exec одразу повертає -`status: "approval-pending"` та id погодження. Після погодження (або відхилення / завершення за тайм-аутом) -Gateway видає system events (`Exec finished` / `Exec denied`). Якщо команда все ще -виконується після `tools.exec.approvalRunningNoticeMs`, видається одне сповіщення `Exec running`. -На каналах із власними картками/кнопками погодження агент має спочатку покладатися -саме на цей native UI й додавати ручну команду `/approve` лише тоді, коли результат -інструмента прямо каже, що погодження в чаті недоступні або ручне погодження є -єдиним шляхом. +Коли потрібні схвалення, інструмент exec негайно повертає +`status: "approval-pending"` та ідентифікатор схвалення. Після схвалення (або відхилення / завершення за часом очікування) +Gateway надсилає системні події (`Exec finished` / `Exec denied`). Якщо команда все ще +виконується після `tools.exec.approvalRunningNoticeMs`, надсилається одне сповіщення `Exec running`. +У каналах із нативними картками/кнопками схвалення агент повинен насамперед покладатися на цей +нативний UI і включати ручну команду `/approve` лише тоді, коли в результаті інструмента +явно зазначено, що схвалення через чат недоступні, або ручне схвалення — +єдиний шлях. ## Allowlist + safe bins -Ручне застосування allowlist зіставляється **лише з перетвореними шляхами до бінарних файлів** (без зіставлення за basename). Коли -`security=allowlist`, shell-команди автоматично дозволяються лише тоді, коли кожен сегмент pipeline є -в allowlist або є safe bin. Ланцюжки (`;`, `&&`, `||`) і редиректи відхиляються в -режимі allowlist, якщо тільки кожен сегмент верхнього рівня не відповідає allowlist (включно з safe bins). -Редиректи все ще не підтримуються. -Довготривала довіра `allow-always` не обходить це правило: ланцюжкова команда все одно потребує, щоб кожен -сегмент верхнього рівня відповідав. +Ручне застосування allowlist зіставляє **лише визначені шляхи до бінарних файлів** (без зіставлення за самими базовими назвами). Коли +`security=allowlist`, shell-команди автоматично дозволяються лише тоді, коли кожен сегмент конвеєра +є в allowlist або є safe bin. Ланцюжки (`;`, `&&`, `||`) і перенаправлення відхиляються в +режимі allowlist, якщо кожен сегмент верхнього рівня не задовольняє allowlist (зокрема safe bins). +Перенаправлення, як і раніше, не підтримуються. +Тривала довіра `allow-always` не обходить це правило: ланцюгова команда все одно вимагає, щоб кожен +сегмент верхнього рівня збігався. -`autoAllowSkills` — це окремий зручний шлях у погодженнях exec. Це не те саме, що -ручні записи шляхів в allowlist. Для суворої явної довіри тримайте `autoAllowSkills` вимкненим. +`autoAllowSkills` — це окремий зручний шлях у схваленнях exec. Це не те саме, що +ручні записи шляху в allowlist. Для суворої явної довіри тримайте +`autoAllowSkills` вимкненим. -Використовуйте ці два механізми для різних завдань: +Використовуйте два елементи керування для різних завдань: -- `tools.exec.safeBins`: малі stream-фільтри лише для stdin. -- `tools.exec.safeBinTrustedDirs`: явні додаткові надійні каталоги для шляхів виконуваних файлів safe bin. -- `tools.exec.safeBinProfiles`: явна policy argv для власних safe bin. +- `tools.exec.safeBins`: невеликі потокові фільтри лише для stdin. +- `tools.exec.safeBinTrustedDirs`: явні додаткові довірені каталоги для шляхів виконуваних файлів safe bin. +- `tools.exec.safeBinProfiles`: явна політика argv для користувацьких safe bin. - allowlist: явна довіра до шляхів виконуваних файлів. -Не використовуйте `safeBins` як загальний allowlist і не додавайте бінарні файли інтерпретаторів/runtime (наприклад `python3`, `node`, `ruby`, `bash`). Якщо вони вам потрібні, використовуйте явні записи allowlist і залишайте ввімкненими запити погодження. -`openclaw security audit` попереджає, коли записи `safeBins` для інтерпретаторів/runtime не мають явних профілів, а `openclaw doctor --fix` може згенерувати відсутні записи `safeBinProfiles`. -`openclaw security audit` і `openclaw doctor` також попереджають, коли ви явно додаєте назад у `safeBins` бінарні файли з широкою поведінкою, такі як `jq`. -Якщо ви явно додаєте інтерпретатори в allowlist, увімкніть `tools.exec.strictInlineEval`, щоб форми inline code-eval усе одно вимагали нового погодження. +Не розглядайте `safeBins` як загальний allowlist і не додавайте туди бінарні файли інтерпретаторів/середовищ виконання (наприклад, `python3`, `node`, `ruby`, `bash`). Якщо вони вам потрібні, використовуйте явні записи allowlist і залишайте запити на схвалення ввімкненими. +`openclaw security audit` попереджає, коли для записів інтерпретаторів/середовищ виконання в `safeBins` бракує явних профілів, а `openclaw doctor --fix` може згенерувати відсутні користувацькі записи `safeBinProfiles`. +`openclaw security audit` і `openclaw doctor` також попереджають, коли ви явно додаєте назад у `safeBins` бінарні файли з широкою поведінкою, як-от `jq`. +Якщо ви явно додаєте інтерпретатори в allowlist, увімкніть `tools.exec.strictInlineEval`, щоб форми inline code-eval усе одно щоразу вимагали нового схвалення. -Повні подробиці policy й приклади див. в [Погодженнях Exec](/uk/tools/exec-approvals#safe-bins-stdin-only) і [Safe bins versus allowlist](/uk/tools/exec-approvals#safe-bins-versus-allowlist). +Повні відомості про політику та приклади див. у [Схвалення exec](/uk/tools/exec-approvals-advanced#safe-bins-stdin-only) і [Safe bins versus allowlist](/uk/tools/exec-approvals-advanced#safe-bins-versus-allowlist). ## Приклади -Foreground: +Передній план: ```json { "tool": "exec", "command": "ls -la" } ``` -Background + poll: +Фоновий режим + опитування: ```json {"tool":"exec","command":"npm run build","yieldMs":1000} {"tool":"process","action":"poll","sessionId":""} ``` -Polling призначене для статусу на вимогу, а не для циклів очікування. Якщо автоматичне пробудження -після завершення ввімкнене, команда може пробудити сесію, коли виведе щось або завершиться помилкою. +Опитування призначене для перевірки стану на вимогу, а не для циклів очікування. Якщо автоматичне пробудження +після завершення ввімкнено, команда може пробудити сесію, коли виведе результат або завершиться з помилкою. -Надсилання клавіш (у стилі tmux): +Надсилання натискань клавіш (у стилі tmux): ```json {"tool":"process","action":"send-keys","sessionId":"","keys":["Enter"]} @@ -233,23 +234,23 @@ Polling призначене для статусу на вимогу, а не д {"tool":"process","action":"send-keys","sessionId":"","keys":["Up","Up","Enter"]} ``` -Надіслати (лише CR): +Надсилання (лише CR): ```json { "tool": "process", "action": "submit", "sessionId": "" } ``` -Вставити (типово з bracketed paste): +Вставлення (типово в дужках): ```json { "tool": "process", "action": "paste", "sessionId": "", "text": "line1\nline2\n" } ``` -## `apply_patch` +## apply_patch `apply_patch` — це підінструмент `exec` для структурованих багатофайлових редагувань. -Він типово ввімкнений для моделей OpenAI і OpenAI Codex. Використовуйте config лише -тоді, коли хочете вимкнути його або обмежити певними моделями: +Він типово ввімкнений для моделей OpenAI і OpenAI Codex. Використовуйте конфігурацію лише +тоді, коли хочете вимкнути його або обмежити конкретними моделями: ```json5 { @@ -264,14 +265,14 @@ Polling призначене для статусу на вимогу, а не д Примітки: - Доступний лише для моделей OpenAI/OpenAI Codex. -- Tool policy усе одно застосовується; `allow: ["write"]` неявно дозволяє `apply_patch`. -- Config розташований у `tools.exec.applyPatch`. -- `tools.exec.applyPatch.enabled` типово дорівнює `true`; установіть `false`, щоб вимкнути інструмент для моделей OpenAI. -- `tools.exec.applyPatch.workspaceOnly` типово дорівнює `true` (обмеження workspace). Установлюйте `false` лише тоді, коли ви свідомо хочете, щоб `apply_patch` записував/видаляв файли поза каталогом workspace. +- Політика інструментів усе одно застосовується; `allow: ["write"]` неявно дозволяє `apply_patch`. +- Конфігурація розташована в `tools.exec.applyPatch`. +- `tools.exec.applyPatch.enabled` типово має значення `true`; установіть `false`, щоб вимкнути інструмент для моделей OpenAI. +- `tools.exec.applyPatch.workspaceOnly` типово має значення `true` (обмежено межами робочого простору). Установлюйте `false` лише тоді, коли свідомо хочете, щоб `apply_patch` записував/видаляв файли поза каталогом робочого простору. ## Пов’язане -- [Погодження Exec](/uk/tools/exec-approvals) — бар’єри погодження для shell-команд -- [Sandboxing](/uk/gateway/sandboxing) — запуск команд у sandboxed-середовищах -- [Background Process](/uk/gateway/background-process) — довготривалий exec та інструмент process -- [Безпека](/uk/gateway/security) — tool policy та elevated access +- [Схвалення exec](/uk/tools/exec-approvals) — шлюзи схвалення для shell-команд +- [Sandboxing](/uk/gateway/sandboxing) — запуск команд у середовищах sandbox +- [Фоновий процес](/uk/gateway/background-process) — довготривалий exec та інструмент process +- [Безпека](/uk/gateway/security) — політика інструментів і підвищений доступ diff --git a/docs/uk/tools/image-generation.md b/docs/uk/tools/image-generation.md index af6429622..abefb778f 100644 --- a/docs/uk/tools/image-generation.md +++ b/docs/uk/tools/image-generation.md @@ -2,14 +2,14 @@ read_when: - Генерація зображень через агента - Налаштування провайдерів і моделей для генерації зображень - - Розуміння параметрів інструмента image_generate -summary: Генерація та редагування зображень за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI) + - Розуміння параметрів інструмента `image_generate` +summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, fal, MiniMax, ComfyUI, Vydra, xAI) title: Генерація зображень x-i18n: - generated_at: "2026-04-23T23:07:48Z" + generated_at: "2026-04-23T23:28:27Z" model: gpt-5.4 provider: openai - source_hash: 820829a009d48ccb23fbd9ee256bae27f6d7d9539fd75c2b0a7cef4b91c5c873 + source_hash: 81d06d2be0d347be2aec54b02037c85fa4dcf71ccbc3c1b5d0aacac0b58892da source_path: tools/image-generation.md workflow: 15 --- @@ -17,13 +17,13 @@ x-i18n: Інструмент `image_generate` дає агенту змогу створювати й редагувати зображення за допомогою налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента. -Інструмент з’являється лише тоді, коли доступний щонайменше один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API key провайдера або увійдіть через OpenAI Codex OAuth. +Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів свого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth. ## Швидкий старт -1. Задайте API key щонайменше для одного провайдера (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth. -2. Необов’язково задайте бажану модель: +1. Задайте API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY` або `GEMINI_API_KEY`) або увійдіть через OpenAI Codex OAuth. +2. За потреби задайте бажану модель: ```json5 { @@ -37,29 +37,25 @@ x-i18n: } ``` -Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw маршрутизує запити на зображення -через цей самий OAuth-профіль замість того, щоб спочатку намагатися використати `OPENAI_API_KEY`. -Явна користувацька конфігурація зображень `models.providers.openai`, наприклад API key або -користувацький/Azure base URL, повертає використання прямого маршруту OpenAI Images API. +Codex OAuth використовує той самий ref моделі `openai/gpt-image-2`. Коли налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на зображення через цей самий OAuth-профіль замість того, щоб спочатку пробувати `OPENAI_API_KEY`. Явна власна конфігурація зображень `models.providers.openai`, наприклад API-ключ або custom/Azure base URL, знову перемикає маршрут на прямий OpenAI Images API. -3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_ +3. Попросіть агента: _«Згенеруй зображення дружнього маскота-робота.»_ -Агент автоматично викликає `image_generate`. Додавання до allowlist інструментів не потрібне — він типово ввімкнений, коли доступний провайдер. +Агент автоматично викликає `image_generate`. Додавати інструмент до allow-list не потрібно — він увімкнений за замовчуванням, коли доступний провайдер. ## Підтримувані провайдери -| Провайдер | Типова модель | Підтримка редагування | Auth | -| --------- | -------------------------------- | ---------------------------------- | ----------------------------------------------------- | -| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | -| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | -| MiniMax | `image-01` | Так (reference об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | -| ComfyUI | `workflow` | Так (1 зображення, визначене workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для cloud | -| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | +| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація | +| --------- | -------------------------------- | ---------------------------------- | ------------------------------------------------------ | +| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth | +| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` | +| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` | +| MiniMax | `image-01` | Так (reference зображення об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) | +| ComfyUI | `workflow` | Так (1 зображення, визначається workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари | +| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` | -Використовуйте `action: "list"`, щоб переглянути доступні провайдери й моделі під час runtime: +Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання: ``` /tool image_generate action=list @@ -68,11 +64,11 @@ Codex OAuth використовує те саме посилання на мо ## Параметри інструмента -Prompt для генерації зображення. Обов’язковий для `action: "generate"`. +Prompt генерації зображення. Обов’язковий для `action: "generate"`. -Використовуйте `"list"`, щоб переглянути доступні провайдери й моделі під час runtime. +Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання. @@ -88,28 +84,44 @@ Prompt для генерації зображення. Обов’язковий -Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. +Підказка розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`. -Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. +Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`. -Підказка щодо роздільної здатності. +Підказка роздільної здатності. + + + +Підказка якості, якщо провайдер це підтримує. + + + +Підказка формату виводу, якщо провайдер це підтримує. Кількість зображень для генерації (1–4). - -Підказка щодо імені вихідного файла. + +Необов’язковий тайм-аут запиту до провайдера в мілісекундах. -Не всі провайдери підтримують усі параметри. Коли fallback-провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує його на найближчий підтримуваний розмір, aspect ratio або роздільну здатність. Справді непідтримувані перевизначення все одно зазначаються в результаті інструмента. + +Підказка імені вихідного файлу. + -Результати інструмента повідомляють про застосовані параметри. Коли OpenClaw виконує переналаштування геометрії під час fallback провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що було фактично надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. + +Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`. + + +Не всі провайдери підтримують усі параметри. Коли fallback-провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед надсиланням переналаштовує запит до найближчого підтримуваного розміру, співвідношення сторін або роздільної здатності. Непідтримувані підказки виводу, такі як `quality` або `outputFormat`, відкидаються для провайдерів, які не декларують підтримку, і зазначаються в результаті інструмента. + +Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переналаштовує геометрію під час fallback провайдера, повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. ## Конфігурація @@ -128,125 +140,121 @@ Aspect ratio: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, ` } ``` -### Порядок вибору провайдера +### Порядок вибору провайдерів Під час генерації зображення OpenClaw пробує провайдерів у такому порядку: -1. **Параметр `model`** з виклику інструмента (якщо агент його задає) -2. **`imageGenerationModel.primary`** з config -3. **`imageGenerationModel.fallbacks`** за порядком -4. **Автовиявлення** — використовує лише типові значення провайдерів, підкріплені auth: +1. Параметр **`model`** з виклику інструмента (якщо агент його вказує) +2. **`imageGenerationModel.primary`** з конфігурації +3. **`imageGenerationModel.fallbacks`** у заданому порядку +4. **Автовиявлення** — використовуються лише типові значення провайдерів, підкріплені автентифікацією: - спочатку поточний типовий провайдер - - далі інші зареєстровані провайдери генерації зображень у порядку id провайдера + - далі решта зареєстрованих провайдерів генерації зображень у порядку provider-id -Якщо провайдер завершується помилкою (помилка auth, rate limit тощо), автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, помилка містить подробиці кожної спроби. +Якщо провайдер завершується помилкою (помилка автентифікації, rate limit тощо), автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, помилка містить подробиці кожної спроби. Примітки: -- Автовиявлення враховує auth. Типове значення провайдера потрапляє до списку кандидатів - лише тоді, коли OpenClaw справді може автентифікувати цей провайдер. -- Автовиявлення типово ввімкнено. Задайте - `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень - використовувала лише явні записи `model`, `primary` і `fallbacks`. -- Використовуйте `action: "list"`, щоб переглянути поточно зареєстровані провайдери, їхні - типові моделі та підказки щодо env vars для auth. +- Автовиявлення враховує стан автентифікації. Типовий провайдер потрапляє до списку кандидатів лише тоді, коли OpenClaw дійсно може автентифікувати цього провайдера. +- Автовиявлення увімкнене за замовчуванням. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень використовувала лише явні записи `model`, `primary` і `fallbacks`. +- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні типові моделі та підказки щодо env vars для автентифікації. ### Редагування зображень OpenAI, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування reference-зображень. Передайте шлях або URL reference-зображення: ``` -"Generate a watercolor version of this photo" + image: "/path/to/photo.jpg" +"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg" ``` OpenAI, Google і xAI підтримують до 5 reference-зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1. ### OpenAI `gpt-image-2` -Генерація зображень OpenAI типово використовує `openai/gpt-image-2`. Якщо налаштовано -OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth- -профіль, який застосовується для chat-моделей підписки Codex, і надсилає запит на зображення -через backend Codex Responses; він не виконує тихого fallback до -`OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут OpenAI Images API, -явно налаштуйте `models.providers.openai` з API key, користувацьким base URL -або endpoint-ом Azure. Старішу -модель `openai/gpt-image-1` усе ще можна явно вибрати, але для нових запитів на генерацію -і редагування зображень OpenAI слід використовувати `gpt-image-2`. +Генерація зображень OpenAI за замовчуванням використовує `openai/gpt-image-2`. Якщо налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, що й для моделей чату за підпискою Codex, і надсилає запит на зображення через бекенд Codex Responses; він не переходить непомітно на `OPENAI_API_KEY` для цього запиту. Щоб примусово використовувати прямий маршрут OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, custom base URL або Azure endpoint. Старішу модель `openai/gpt-image-1` усе ще можна явно вибрати, але для нових запитів генерації та редагування зображень OpenAI слід використовувати `gpt-image-2`. -`gpt-image-2` підтримує як генерацію text-to-image, так і редагування -reference-зображень через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`, -`count`, `size` і reference-зображення. OpenAI не отримує -`aspectRatio` або `resolution` напряму; коли можливо, OpenClaw відображає їх у -підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення. +`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування reference-зображень через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat` і reference-зображення. OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли це можливо, OpenClaw перетворює їх у підтримуваний `size`, інакше інструмент повідомляє про них як про проігноровані перевизначення. -Згенерувати одне 4K-зображення в альбомній орієнтації: +Параметри, специфічні для OpenAI, розміщені в об’єкті `openai`: -``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1 +```json +{ + "quality": "low", + "outputFormat": "jpeg", + "openai": { + "background": "opaque", + "moderation": "low", + "outputCompression": 60, + "user": "end-user-42" + } +} ``` -Згенерувати два квадратні зображення: +`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорий вивід вимагає `outputFormat` `png` або `webp`. `openai.outputCompression` застосовується до виводу JPEG/WebP. + +Згенеруйте одне 4K-зображення в альбомній орієнтації: ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Чистий редакційний постер для генерації зображень OpenClaw" size=3840x2160 count=1 ``` -Відредагувати одне локальне reference-зображення: +Згенеруйте два квадратні зображення: ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Два візуальні напрями для іконки спокійного застосунку продуктивності" size=1024x1024 count=2 ``` -Відредагувати з кількома reference: +Відредагуйте одне локальне reference-зображення: ``` -/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Збережи об’єкт, заміни тло на яскраву студійну сцену" image=/path/to/reference.png size=1024x1536 ``` -Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість -`api.openai.com`, див. [endpoint-и Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) -у документації провайдера OpenAI. +Редагування з кількома reference-зображеннями: -Генерація зображень MiniMax доступна через обидва вбудовані шляхи auth MiniMax: +``` +/tool image_generate action=generate model=openai/gpt-image-2 prompt="Поєднай образ персонажа з першого зображення з кольоровою палітрою другого" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024 +``` -- `minimax/image-01` для конфігурацій з API key -- `minimax-portal/image-01` для конфігурацій з OAuth +Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI замість `api.openai.com`, див. [endpoints Azure OpenAI](/uk/providers/openai#azure-openai-endpoints) у документації провайдера OpenAI. + +Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax: + +- `minimax/image-01` для налаштувань з API-ключем +- `minimax-portal/image-01` для OAuth-налаштувань ## Можливості провайдерів | Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI | | --------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- | -| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (визначені workflow виходи) | Так (1) | Так (до 4) | -| Редагування/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, reference об’єкта) | Так (1 зображення, визначене workflow) | Ні | Так (до 5 зображень) | +| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виводи визначаються workflow) | Так (1) | Так (до 4) | +| Редагування/reference | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, reference об’єкта) | Так (1 зображення, визначається workflow) | Ні | Так (до 5 зображень) | | Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні | -| Aspect ratio | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так | -| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | +| Співвідношення сторін | Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так | +| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) | ### xAI `grok-imagine-image` -Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з prompt -і `/v1/images/edits`, коли присутній `image` або `images`. +Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`. - Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro` -- Count: до 4 -- Reference: один `image` або до п’яти `images` -- Aspect ratio: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` -- Роздільна здатність: `1K`, `2K` -- Вихідні дані: повертаються як керовані OpenClaw вкладення зображень +- Кількість: до 4 +- References: один `image` або до п’яти `images` +- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2` +- Роздільні здатності: `1K`, `2K` +- Вивід: повертається як вкладення зображень, якими керує OpenClaw -OpenClaw навмисно не відкриває специфічні для xAI `quality`, `mask`, `user` або -додаткові native-only aspect ratio, доки ці елементи керування не з’являться в спільному -міжпровайдерному контракті `image_generate`. +OpenClaw навмисно не відкриває нативні для xAI параметри `quality`, `mask`, `user` або додаткові нативні співвідношення сторін, доки ці елементи керування не з’являться в спільному міжпровайдерному контракті `image_generate`. ## Пов’язане - [Огляд інструментів](/uk/tools) — усі доступні інструменти агента - [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal -- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI та workflow Comfy Cloud +- [ComfyUI](/uk/providers/comfy) — налаштування локального ComfyUI і workflow Comfy Cloud - [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini - [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax - [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images - [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra -- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду і TTS -- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) — config `imageGenerationModel` +- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS +- [Довідник з конфігурації](/uk/gateway/configuration-reference#agent-defaults) — конфігурація `imageGenerationModel` - [Моделі](/uk/concepts/models) — конфігурація моделей і failover diff --git a/docs/uk/tools/music-generation.md b/docs/uk/tools/music-generation.md index 95f4ff1d6..835458f2d 100644 --- a/docs/uk/tools/music-generation.md +++ b/docs/uk/tools/music-generation.md @@ -1,38 +1,39 @@ --- read_when: - - Генерація музики або аудіо через агента - - Налаштування providers і моделей для генерації музики + - Генерування музики або аудіо через агента + - Налаштування провайдерів і моделей для генерування музики - Розуміння параметрів інструмента music_generate -summary: Генерувати музику зі спільними providers, включно з plugins на основі workflow -title: Генерація музики +summary: Генерування музики зі спільними провайдерами, зокрема плагінами на основі workflow +title: Генерування музики x-i18n: - generated_at: "2026-04-23T21:16:22Z" + generated_at: "2026-04-23T23:28:46Z" model: gpt-5.4 provider: openai - source_hash: 5b03922bf032586f649e677d1d8c08250b1fd5dc95f1cdde050a058562feb3da + source_hash: 6010ee365e4b48b62eb20f3769aae4e409cb651fe7d5946b8c832f0fb120a1e4 source_path: tools/music-generation.md workflow: 15 --- Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через -спільну можливість генерації музики з налаштованими providers, такими як Google, +спільну можливість генерування музики з налаштованими провайдерами, такими як Google, MiniMax і ComfyUI, налаштований через workflow. -Для агентних сесій на основі спільних providers OpenClaw запускає генерацію музики як -фонове завдання, відстежує його в task ledger, а потім знову пробуджує агента, коли -трек готовий, щоб агент міг опублікувати готове аудіо назад у вихідний канал. +Для сесій агента на основі спільних провайдерів OpenClaw запускає генерування музики як +фонове завдання, відстежує його в журналі завдань, а потім знову пробуджує агента, коли +трек готовий, щоб агент міг опублікувати готове аудіо назад в +оригінальний канал. -Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один provider генерації музики. Якщо ви не бачите `music_generate` серед інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ provider. +Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерування музики. Якщо ви не бачите `music_generate` в інструментах свого агента, налаштуйте `agents.defaults.musicGenerationModel` або задайте API-ключ провайдера. ## Швидкий старт -### Генерація на основі спільних providers +### Генерування на основі спільного провайдера -1. Задайте API-ключ принаймні для одного provider, наприклад `GEMINI_API_KEY` або +1. Задайте API-ключ щонайменше для одного провайдера, наприклад `GEMINI_API_KEY` або `MINIMAX_API_KEY`. -2. За бажанням задайте бажану модель: +2. За потреби задайте бажану модель: ```json5 { @@ -46,122 +47,123 @@ MiniMax і ComfyUI, налаштований через workflow. } ``` -3. Попросіть агента: _"Generate an upbeat synthpop track about a night drive - through a neon city."_ +3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку + неоновим містом."_ -Агент автоматично викличе `music_generate`. Додавання в allow-list інструментів не потрібне. +Агент автоматично викликає `music_generate`. Додавання інструмента до allowlist не потрібне. -Для прямих синхронних контекстів без agent-run на основі сесії вбудований -інструмент усе одно повертається до inline-генерації та повертає фінальний шлях до media в +Для прямих синхронних контекстів без запуску агента з підтримкою сесії вбудований +інструмент усе одно переходить до вбудованого генерування та повертає фінальний шлях до медіафайлу в результаті інструмента. -Приклади prompt: +Приклади запитів: ```text -Generate a cinematic piano track with soft strings and no vocals. +Згенеруй кінематографічний фортепіанний трек із м’якими струнними без вокалу. ``` ```text -Generate an energetic chiptune loop about launching a rocket at sunrise. +Згенеруй енергійний chiptune-луп про запуск ракети на світанку. ``` -### Генерація Comfy на основі workflow +### Генерування Comfy на основі workflow -Вбудований plugin `comfy` підключається до спільного інструмента `music_generate` через -registry provider генерації музики. +Вбудований Plugin `comfy` підключається до спільного інструмента `music_generate` через +реєстр провайдерів генерування музики. 1. Налаштуйте `models.providers.comfy.music` із JSON workflow та вузлами prompt/output. 2. Якщо ви використовуєте Comfy Cloud, задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`. -3. Попросіть агента згенерувати музику або викличте інструмент напряму. +3. Попросіть агента створити музику або викличте інструмент безпосередньо. Приклад: ```text -/tool music_generate prompt="Warm ambient synth loop with soft tape texture" +/tool music_generate prompt="Теплий ambient synth loop із м’якою текстурою плівки" ``` -## Підтримка вбудованих shared providers +## Підтримка вбудованих спільних провайдерів -| Provider | Типова модель | Опорні входи | Підтримувані елементи керування | API-ключ | -| -------- | --------------------- | ----------------- | ---------------------------------------------------- | -------------------------------------- | -| ComfyUI | `workflow` | До 1 зображення | Музика або аудіо, визначені workflow | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | -| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | -| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | +| Провайдер | Типова модель | Еталонні входи | Підтримувані керувальні параметри | API-ключ | +| --------- | --------------------- | ---------------- | -------------------------------------------------------- | -------------------------------------- | +| ComfyUI | `workflow` | До 1 зображення | Визначені workflow музика або аудіо | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` | +| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` | +| MiniMax | `music-2.5+` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` | ### Матриця оголошених можливостей -Це явний контракт режимів, який використовують `music_generate`, contract tests -і shared live sweep. +Це явний контракт режимів, який використовують `music_generate`, контрактні тести +та спільний live sweep. -| Provider | `generate` | `edit` | Ліміт edit | Shared live lanes | -| -------- | ---------- | ------ | ---------- | ------------------------------------------------------------------------- | -| ComfyUI | Так | Так | 1 зображення | Не входить до shared sweep; покривається в `extensions/comfy/comfy.live.test.ts` | -| Google | Так | Так | 10 зображень | `generate`, `edit` | -| MiniMax | Так | Ні | Немає | `generate` | +| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live lanes | +| --------- | ---------- | ------ | ----------------- | ------------------------------------------------------------------------- | +| ComfyUI | Так | Так | 1 зображення | Не входить до спільного sweep; покрито `extensions/comfy/comfy.live.test.ts` | +| Google | Так | Так | 10 зображень | `generate`, `edit` | +| MiniMax | Так | Ні | Немає | `generate` | -Використовуйте `action: "list"`, щоб переглянути доступні shared providers і моделі під час -виконання: +Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі під +час виконання: ```text /tool music_generate action=list ``` -Використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до поточної сесії: +Використовуйте `action: "status"`, щоб перевірити активне завдання генерування музики з підтримкою сесії: ```text /tool music_generate action=status ``` -Приклад прямої генерації: +Приклад прямого генерування: ```text -/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true +/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та ніжним дощем" instrumental=true ``` ## Параметри вбудованого інструмента -| Параметр | Тип | Опис | -| ----------------- | --------- | ---------------------------------------------------------------------------------------------- | -| `prompt` | string | Prompt для генерації музики (обов’язковий для `action: "generate"`) | -| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії, або `"list"` для перегляду providers | -| `model` | string | Перевизначення provider/model, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | -| `lyrics` | string | Необов’язковий текст пісні, якщо provider підтримує явний ввід lyrics | -| `instrumental` | boolean | Запросити лише інструментальний вивід, якщо provider це підтримує | -| `image` | string | Шлях або URL одного опорного зображення | -| `images` | string[] | Кілька опорних зображень (до 10) | -| `durationSeconds` | number | Бажана тривалість у секундах, якщо provider підтримує підказки тривалості | -| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо provider це підтримує | -| `filename` | string | Підказка для імені вихідного файла | +| Параметр | Тип | Опис | +| ---------------- | -------- | ------------------------------------------------------------------------------------------------- | +| `prompt` | string | Запит для генерування музики (обов’язковий для `action: "generate"`) | +| `action` | string | `"generate"` (типово), `"status"` для поточного завдання сесії або `"list"` для перегляду провайдерів | +| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` | +| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне передавання тексту | +| `instrumental` | boolean | Запитати лише інструментальний результат, якщо провайдер це підтримує | +| `image` | string | Шлях або URL одного еталонного зображення | +| `images` | string[] | Кілька еталонних зображень (до 10) | +| `durationSeconds`| number | Бажана тривалість у секундах, якщо провайдер підтримує підказки тривалості | +| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах | +| `format` | string | Підказка щодо вихідного формату (`mp3` або `wav`), якщо провайдер це підтримує | +| `filename` | string | Підказка щодо назви вихідного файла | -Не всі providers підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження, -такі як кількість входів, до надсилання. Коли provider підтримує тривалість, але -має коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує +Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження, +як-от кількість входів, до надсилання. Коли провайдер підтримує тривалість, але +використовує коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує його до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки ігноруються -з попередженням, коли вибраний provider або модель не може їх виконати. +з попередженням, коли вибраний провайдер або модель не можуть їх застосувати. -Результати інструмента повідомляють застосовані налаштування. Коли OpenClaw обмежує тривалість під час fallback provider, повернуте `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує перетворення від запитаного до застосованого. +Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує тривалість під час fallback між провайдерами, повернене `durationSeconds` відображає надіслане значення, а `details.normalization.durationSeconds` показує зіставлення між запитаним і застосованим значенням. -## Асинхронна поведінка для шляху на основі shared providers +## Асинхронна поведінка для шляху на основі спільного провайдера -- Agent-run на основі сесії: `music_generate` створює фонове завдання, негайно повертає started/task response, а готовий трек публікує пізніше в follow-up повідомленні агента. -- Запобігання дублюванню: поки фонове завдання в тій самій сесії ще має стан `queued` або `running`, подальші виклики `music_generate` повертають статус завдання замість запуску нової генерації. -- Перевірка статусу: використовуйте `action: "status"`, щоб переглянути активне завдання генерації музики, прив’язане до поточної сесії, не запускаючи нову генерацію. -- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати статус queued, running і terminal для генерації. -- Пробудження після завершення: OpenClaw ін’єктує внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати follow-up для користувача. -- Підказка в prompt: подальші user/manual turns у тій самій сесії отримують невелику runtime-підказку, коли завдання генерації музики вже виконується, щоб модель не викликала `music_generate` повторно всліпу. -- Резервний варіант без сесії: прямі/локальні контексти без реальної agent-сесії все одно виконуються inline і повертають фінальний результат аудіо в тому самому turn. +- Запуски агента з підтримкою сесії: `music_generate` створює фонове завдання, негайно повертає відповідь started/task і пізніше публікує готовий трек у наступному повідомленні агента. +- Запобігання дублюванню: поки це фонове завдання має стан `queued` або `running`, наступні виклики `music_generate` у тій самій сесії повертають стан завдання замість запуску нового генерування. +- Перевірка стану: використовуйте `action: "status"`, щоб перевірити активне завдання генерування музики з підтримкою сесії без запуску нового. +- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб переглядати стани queued, running і terminal для генерування. +- Пробудження після завершення: OpenClaw вставляє внутрішню подію завершення назад у ту саму сесію, щоб модель могла сама написати користувацьке наступне повідомлення. +- Підказка в prompt: наступні користувацькі/ручні ходи в тій самій сесії отримують невелику підказку під час виконання, коли завдання музики вже виконується, щоб модель не викликала `music_generate` повторно всліпу. +- Fallback без сесії: прямі/локальні контексти без реальної сесії агента все одно виконуються вбудовано та повертають фінальний результат аудіо в тому самому ході. ### Життєвий цикл завдання Кожен запит `music_generate` проходить через чотири стани: -1. **queued** -- завдання створено, воно чекає, поки provider прийме його. -2. **running** -- provider обробляє його (зазвичай від 30 секунд до 3 хвилин, залежно від provider і тривалості). -3. **succeeded** -- трек готовий; агент пробуджується і публікує його в розмову. -4. **failed** -- помилка provider або timeout; агент пробуджується з деталями помилки. +1. **queued** -- завдання створено, очікує, поки провайдер його прийме. +2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера та тривалості). +3. **succeeded** -- трек готовий; агент пробуджується та публікує його в розмову. +4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. -Перевірка статусу з CLI: +Перевірка стану з CLI: ```bash openclaw tasks list @@ -169,7 +171,7 @@ openclaw tasks show openclaw tasks cancel ``` -Запобігання дублюванню: якщо для поточної сесії завдання музики вже має стан `queued` або `running`, `music_generate` повертає статус наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити це без запуску нової генерації. +Запобігання дублюванню: якщо для поточної сесії вже є музичне завдання у стані `queued` або `running`, `music_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нового генерування. ## Конфігурація @@ -188,41 +190,41 @@ openclaw tasks cancel } ``` -### Порядок вибору provider +### Порядок вибору провайдера -Під час генерації музики OpenClaw пробує providers у такому порядку: +Під час генерування музики OpenClaw намагається використовувати провайдерів у такому порядку: -1. параметр `model` із виклику інструмента, якщо агент його вказує -2. `musicGenerationModel.primary` з config -3. `musicGenerationModel.fallbacks` у заданому порядку -4. Автовизначення, використовуючи лише типові значення providers, підкріплені auth: - - спочатку поточний типовий provider - - далі решта зареєстрованих providers генерації музики в порядку provider-id +1. параметр `model` із виклику інструмента, якщо агент його задає +2. `musicGenerationModel.primary` із конфігурації +3. `musicGenerationModel.fallbacks` по черзі +4. автовизначення з використанням лише типових значень провайдера на основі auth: + - спочатку поточний типовий провайдер + - потім інші зареєстровані провайдери генерування музики в порядку ідентифікаторів провайдерів -Якщо provider не спрацьовує, автоматично пробується наступний кандидат. Якщо не спрацьовують усі, помилка -містить подробиці кожної спроби. +Якщо провайдер завершується з помилкою, автоматично пробується наступний кандидат. Якщо всі завершуються помилкою, +помилка містить деталі кожної спроби. -Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, -щоб генерація музики використовувала лише явні записи `model`, `primary` і `fallbacks`. +Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо ви хочете, +щоб генерування музики використовувало лише явні записи `model`, `primary` і `fallbacks`. -## Примітки щодо providers +## Примітки щодо провайдерів -- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує - prompt, необов’язковий текст lyrics і необов’язкові опорні зображення. -- MiniMax використовує пакетний ендпоінт `music_generation`. Поточний вбудований потік - підтримує prompt, необов’язкові lyrics, instrumental mode, керування тривалістю і - вивід у mp3. +- Google використовує пакетне генерування Lyria 3. Поточний вбудований потік підтримує + prompt, необов’язковий текст lyrics і необов’язкові еталонні зображення. +- MiniMax використовує пакетний ендпойнт `music_generation`. Поточний вбудований потік + підтримує prompt, необов’язкові lyrics, інструментальний режим, керування тривалістю та + вихід у форматі mp3. - Підтримка ComfyUI керується workflow і залежить від налаштованого графа та зіставлення вузлів для полів prompt/output. -## Режими можливостей provider +## Режими можливостей провайдерів -Спільний контракт генерації музики тепер підтримує явні оголошення режимів: +Контракт спільного генерування музики тепер підтримує явні оголошення режимів: -- `generate` для генерації лише за prompt -- `edit`, коли запит містить одне або кілька опорних зображень +- `generate` для генерування лише за prompt +- `edit`, коли запит містить одне або більше еталонних зображень -Нові реалізації providers повинні надавати перевагу явним блокам режимів: +Нові реалізації провайдерів мають надавати перевагу явним блокам режимів: ```typescript capabilities: { @@ -240,20 +242,20 @@ capabilities: { } ``` -Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і -`supportsFormat`, недостатньо, щоб оголосити підтримку edit. Providers повинні -явно оголошувати `generate` і `edit`, щоб live tests, contract tests і +Застарілих плоских полів, як-от `maxInputImages`, `supportsLyrics` і +`supportsFormat`, недостатньо, щоб оголосити підтримку редагування. Провайдери повинні +явно оголошувати `generate` і `edit`, щоб live-тести, контрактні тести та спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів. ## Вибір правильного шляху -- Використовуйте шлях на основі shared providers, коли вам потрібні вибір моделі, failover provider і вбудований асинхронний потік task/status. -- Використовуйте шлях plugin, наприклад ComfyUI, коли вам потрібен власний граф workflow або provider, який не входить до shared bundled capability генерації музики. -- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку shared providers, почніть з [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). +- Використовуйте шлях на основі спільного провайдера, коли вам потрібні вибір моделі, fallback між провайдерами та вбудований асинхронний потік завдання/стану. +- Використовуйте шлях через Plugin, такий як ComfyUI, коли вам потрібен користувацький граф workflow або провайдер, який не входить до спільної вбудованої можливості генерування музики. +- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного провайдера, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax). -## Live tests +## Live-тести -Opt-in live-покриття для shared bundled providers: +Покриття live-тестами за згодою для спільних вбудованих провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts @@ -265,31 +267,31 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv pnpm test:live:media music ``` -Цей live-файл завантажує відсутні env vars provider з `~/.profile`, типово надає -перевагу live/env API-ключам над збереженими auth profiles і запускає покриття -і для `generate`, і для оголошеного `edit`, коли provider вмикає режим edit. +Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово віддає +перевагу live/env API-ключам перед збереженими профілями auth і запускає покриття +і для `generate`, і для оголошеного `edit`, коли провайдер вмикає режим редагування. -Сьогодні це означає: +Наразі це означає: - `google`: `generate` плюс `edit` - `minimax`: лише `generate` -- `comfy`: окреме live-покриття Comfy, не shared provider sweep +- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів -Opt-in live-покриття для bundled-шляху музики ComfyUI: +Покриття live-тестами за згодою для вбудованого музичного шляху ComfyUI: ```bash OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts ``` -Live-файл Comfy також покриває workflows зображень і відео comfy, коли ці +Файл live-тестів Comfy також охоплює workflow для зображень і відео Comfy, коли ці розділи налаштовані. ## Пов’язане - [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate` -- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - config `musicGenerationModel` +- [Довідник із конфігурації](/uk/gateway/configuration-reference#agent-defaults) - конфігурація `musicGenerationModel` - [ComfyUI](/uk/providers/comfy) - [Google (Gemini)](/uk/providers/google) - [MiniMax](/uk/providers/minimax) -- [Models](/uk/concepts/models) - конфігурація моделей і failover -- [Огляд Tools](/uk/tools) +- [Моделі](/uk/concepts/models) - конфігурація моделей і fallback +- [Огляд інструментів](/uk/tools) diff --git a/docs/uk/tools/tts.md b/docs/uk/tools/tts.md index 4e827c8de..9a6f81f84 100644 --- a/docs/uk/tools/tts.md +++ b/docs/uk/tools/tts.md @@ -1,15 +1,15 @@ --- read_when: - Увімкнення text-to-speech для відповідей - - Налаштування провайдерів або обмежень TTS + - Налаштування provider TTS або обмежень - Використання команд /tts summary: Text-to-speech (TTS) для вихідних відповідей title: Text-to-speech x-i18n: - generated_at: "2026-04-23T23:08:56Z" + generated_at: "2026-04-23T23:28:55Z" model: gpt-5.4 provider: openai - source_hash: ba760f48e203a090ddc8f18198439541de8886422fca07edb94a46295684da02 + source_hash: 935fec2325a08da6f4ecd8ba5a9b889cd265025c5c7ee43bc4e0da36c1003d8f source_path: tools/tts.md workflow: 15 --- @@ -19,24 +19,24 @@ OpenClaw може перетворювати вихідні відповіді ## Підтримувані сервіси -- **ElevenLabs** (основний або резервний провайдер) -- **Google Gemini** (основний або резервний провайдер; використовує Gemini API TTS) -- **Microsoft** (основний або резервний провайдер; поточна bundled-реалізація використовує `node-edge-tts`) -- **MiniMax** (основний або резервний провайдер; використовує T2A v2 API) -- **OpenAI** (основний або резервний провайдер; також використовується для зведень) -- **xAI** (основний або резервний провайдер; використовує xAI TTS API) +- **ElevenLabs** (основний або резервний provider) +- **Google Gemini** (основний або резервний provider; використовує Gemini API TTS) +- **Microsoft** (основний або резервний provider; поточна вбудована реалізація використовує `node-edge-tts`) +- **MiniMax** (основний або резервний provider; використовує API T2A v2) +- **OpenAI** (основний або резервний provider; також використовується для підсумків) +- **xAI** (основний або резервний provider; використовує xAI TTS API) ### Примітки щодо Microsoft speech -Bundled-провайдер Microsoft speech наразі використовує онлайн-сервіс -нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це розміщений сервіс (не -локальний), використовує endpoint Microsoft і не потребує API key. +Поточний вбудований provider Microsoft speech зараз використовує онлайн-сервіс +нейронного TTS Microsoft Edge через бібліотеку `node-edge-tts`. Це хостинговий сервіс (не +локальний), використовує ендпоінти Microsoft і не потребує API-ключа. `node-edge-tts` надає параметри конфігурації мовлення та формати виводу, але -не всі параметри підтримуються сервісом. Застаріла конфігурація і вхідні директиви, -що використовують `edge`, і далі працюють і нормалізуються до `microsoft`. +сервіс підтримує не всі параметри. Старі конфігурації та вхідні директиви +з використанням `edge` усе ще працюють і нормалізуються до `microsoft`. -Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квоти, -ставтеся до нього як до best-effort. Якщо вам потрібні гарантовані ліміти й підтримка, використовуйте OpenAI +Оскільки цей шлях використовує публічний вебсервіс без опублікованого SLA або квот, +сприймайте його як best-effort. Якщо вам потрібні гарантовані ліміти та підтримка, використовуйте OpenAI або ElevenLabs. ## Необов’язкові ключі @@ -49,15 +49,15 @@ Bundled-провайдер Microsoft speech наразі використову - `OPENAI_API_KEY` - `XAI_API_KEY` -Microsoft speech **не** потребує API key. +Microsoft speech **не** потребує API-ключа. -Якщо налаштовано кілька провайдерів, спочатку використовується вибраний провайдер, а інші є резервними варіантами. -Автоматичне зведення використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), -тому якщо ви вмикаєте зведення, цей провайдер також має бути автентифікований. +Якщо налаштовано кілька provider, спочатку використовується вибраний provider, а інші стають резервними варіантами. +Автоматичне створення підсумків використовує налаштований `summaryModel` (або `agents.defaults.model.primary`), +тому якщо ви вмикаєте підсумки, цей provider також має бути автентифікований. ## Посилання на сервіси -- [Посібник OpenAI з Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) +- [Посібник OpenAI Text-to-Speech](https://platform.openai.com/docs/guides/text-to-speech) - [Довідник OpenAI Audio API](https://platform.openai.com/docs/api-reference/audio) - [ElevenLabs Text to Speech](https://elevenlabs.io/docs/api-reference/text-to-speech) - [Автентифікація ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication) @@ -66,20 +66,20 @@ Microsoft speech **не** потребує API key. - [Формати виводу Microsoft Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs) - [xAI Text to Speech](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest) -## Чи ввімкнено це за замовчуванням? +## Чи ввімкнено це типово? -Ні. Автоматичний TTS **вимкнено** за замовчуванням. Увімкніть його в конфігурації через -`messages.tts.auto` або локально через `/tts on`. +Ні. Автоматичний TTS типово **вимкнений**. Увімкніть його в конфігурації через +`messages.tts.auto` або локально за допомогою `/tts on`. Коли `messages.tts.provider` не задано, OpenClaw вибирає перший налаштований -speech-провайдер у порядку автоматичного вибору реєстру. +speech provider у порядку автоматичного вибору реєстру. ## Конфігурація -Конфігурація TTS розміщується в `messages.tts` у `openclaw.json`. +Конфігурація TTS знаходиться в `messages.tts` у `openclaw.json`. Повна схема наведена в [Конфігурація Gateway](/uk/gateway/configuration). -### Мінімальна конфігурація (увімкнення + провайдер) +### Мінімальна конфігурація (увімкнення + provider) ```json5 { @@ -92,7 +92,7 @@ speech-провайдер у порядку автоматичного вибо } ``` -### OpenAI як основний з резервним переходом на ElevenLabs +### Основний OpenAI з резервним ElevenLabs ```json5 { @@ -133,7 +133,7 @@ speech-провайдер у порядку автоматичного вибо } ``` -### Microsoft як основний (без API key) +### Основний Microsoft (без API-ключа) ```json5 { @@ -156,7 +156,7 @@ speech-провайдер у порядку автоматичного вибо } ``` -### MiniMax як основний +### Основний MiniMax ```json5 { @@ -180,7 +180,7 @@ speech-провайдер у порядку автоматичного вибо } ``` -### Google Gemini як основний +### Основний Google Gemini ```json5 { @@ -200,13 +200,13 @@ speech-провайдер у порядку автоматичного вибо } ``` -Google Gemini TTS використовує шлях API key Gemini. Ключ API Google Cloud Console, -обмежений Gemini API, тут є дійсним, і це той самий тип ключа, який використовує -bundled-провайдер генерації зображень Google. Порядок визначення: +Google Gemini TTS використовує шлях API-ключа Gemini. Тут також підходить API-ключ Google Cloud Console, +обмежений лише Gemini API, і це той самий тип ключа, який використовується +вбудованим provider генерації зображень Google. Порядок визначення: `messages.tts.providers.google.apiKey` -> `models.providers.google.apiKey` -> `GEMINI_API_KEY` -> `GOOGLE_API_KEY`. -### xAI як основний +### Основний xAI ```json5 { @@ -228,12 +228,12 @@ bundled-провайдер генерації зображень Google. Пор } ``` -xAI TTS використовує той самий шлях `XAI_API_KEY`, що й bundled-провайдер моделей Grok. +xAI TTS використовує той самий шлях `XAI_API_KEY`, що й вбудований provider моделей Grok. Порядок визначення: `messages.tts.providers.xai.apiKey` -> `XAI_API_KEY`. -Поточні live-голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типовим є `eve`. +Поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal` і `una`; типово використовується `eve`. `language` приймає тег BCP-47 або `auto`. -### Вимкнути Microsoft speech +### Вимкнення Microsoft speech ```json5 { @@ -249,7 +249,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -### Власні обмеження + шлях prefs +### Користувацькі обмеження + шлях до prefs ```json5 { @@ -276,7 +276,7 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що } ``` -### Вимкнути автоматичне зведення для довгих відповідей +### Вимкнення автоматичного підсумку для довгих відповідей ```json5 { @@ -299,70 +299,70 @@ xAI TTS використовує той самий шлях `XAI_API_KEY`, що - `auto`: режим автоматичного TTS (`off`, `always`, `inbound`, `tagged`). - `inbound` надсилає аудіо лише після вхідного голосового повідомлення. - `tagged` надсилає аудіо лише тоді, коли відповідь містить директиви `[[tts:key=value]]` або блок `[[tts:text]]...[[/tts:text]]`. -- `enabled`: застарілий перемикач (doctor мігрує це до `auto`). +- `enabled`: застарілий перемикач (doctor мігрує його в `auto`). - `mode`: `"final"` (типово) або `"all"` (включає відповіді інструментів/блоків). -- `provider`: id speech-провайдера, наприклад `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"` або `"openai"` (резервний перехід відбувається автоматично). -- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований speech-провайдер у порядку автоматичного вибору реєстру. -- Застаріле `provider: "edge"` і далі працює і нормалізується до `microsoft`. -- `summaryModel`: необов’язкова недорога модель для автоматичного зведення; типово `agents.defaults.model.primary`. +- `provider`: id speech provider, наприклад `"elevenlabs"`, `"google"`, `"microsoft"`, `"minimax"` або `"openai"` (резервне перемикання відбувається автоматично). +- Якщо `provider` **не задано**, OpenClaw використовує перший налаштований speech provider у порядку автоматичного вибору реєстру. +- Застаріле `provider: "edge"` усе ще працює і нормалізується до `microsoft`. +- `summaryModel`: необов’язкова недорога модель для автоматичного підсумку; типово використовується `agents.defaults.model.primary`. - Приймає `provider/model` або налаштований псевдонім моделі. -- `modelOverrides`: дозволяє моделі видавати директиви TTS (типово ввімкнено). - - `allowProvider` типово дорівнює `false` (перемикання провайдера вимагає явного ввімкнення). -- `providers.`: налаштування провайдера-власника, ключовані за id speech-провайдера. -- Застарілі прямі блоки провайдерів (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються до `messages.tts.providers.` під час завантаження. -- `maxTextLength`: жорстке обмеження для вхідного тексту TTS (символи). `/tts audio` завершується помилкою, якщо ліміт перевищено. +- `modelOverrides`: дозволяє моделі виводити директиви TTS (типово ввімкнено). + - `allowProvider` типово має значення `false` (перемикання provider вмикається явно). +- `providers.`: параметри, що належать provider, з ключем за id speech provider. +- Застарілі прямі блоки provider (`messages.tts.openai`, `messages.tts.elevenlabs`, `messages.tts.microsoft`, `messages.tts.edge`) автоматично мігруються в `messages.tts.providers.` під час завантаження. +- `maxTextLength`: жорстке обмеження для вхідного TTS-тексту (символи). Якщо його перевищено, `/tts audio` завершується помилкою. - `timeoutMs`: тайм-аут запиту (мс). -- `prefsPath`: перевизначає шлях до локального JSON prefs (provider/limit/summary). -- Значення `apiKey` переходять до env-змінних (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). +- `prefsPath`: перевизначає локальний шлях до JSON-файла prefs (provider/limit/summary). +- Значення `apiKey` можуть братися з env vars (`ELEVENLABS_API_KEY`/`XI_API_KEY`, `GEMINI_API_KEY`/`GOOGLE_API_KEY`, `MINIMAX_API_KEY`, `OPENAI_API_KEY`). - `providers.elevenlabs.baseUrl`: перевизначає базовий URL API ElevenLabs. -- `providers.openai.baseUrl`: перевизначає endpoint OpenAI TTS. +- `providers.openai.baseUrl`: перевизначає ендпоінт OpenAI TTS. - Порядок визначення: `messages.tts.providers.openai.baseUrl` -> `OPENAI_TTS_BASE_URL` -> `https://api.openai.com/v1` - - Нетипові значення обробляються як OpenAI-сумісні TTS endpoint, тому приймаються власні назви моделей і голосів. + - Нестандартні значення розглядаються як OpenAI-сумісні TTS-ендпоінти, тому допускаються користувацькі назви моделей і голосів. - `providers.elevenlabs.voiceSettings`: - `stability`, `similarityBoost`, `style`: `0..1` - `useSpeakerBoost`: `true|false` - - `speed`: `0.5..2.0` (1.0 = нормальна) + - `speed`: `0.5..2.0` (1.0 = звичайна швидкість) - `providers.elevenlabs.applyTextNormalization`: `auto|on|off` - `providers.elevenlabs.languageCode`: 2-літерний ISO 639-1 (наприклад, `en`, `de`) -- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінізм) +- `providers.elevenlabs.seed`: ціле число `0..4294967295` (best-effort детермінованість) - `providers.minimax.baseUrl`: перевизначає базовий URL API MiniMax (типово `https://api.minimax.io`, env: `MINIMAX_API_HOST`). -- `providers.minimax.model`: TTS-модель (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). +- `providers.minimax.model`: модель TTS (типово `speech-2.8-hd`, env: `MINIMAX_TTS_MODEL`). - `providers.minimax.voiceId`: ідентифікатор голосу (типово `English_expressive_narrator`, env: `MINIMAX_TTS_VOICE_ID`). - `providers.minimax.speed`: швидкість відтворення `0.5..2.0` (типово 1.0). - `providers.minimax.vol`: гучність `(0, 10]` (типово 1.0; має бути більшою за 0). -- `providers.minimax.pitch`: зсув тону `-12..12` (типово 0). -- `providers.google.model`: TTS-модель Gemini (типово `gemini-3.1-flash-tts-preview`). +- `providers.minimax.pitch`: зсув висоти тону `-12..12` (типово 0). +- `providers.google.model`: модель Gemini TTS (типово `gemini-3.1-flash-tts-preview`). - `providers.google.voiceName`: назва вбудованого голосу Gemini (типово `Kore`; також приймається `voice`). -- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Приймається лише `https://generativelanguage.googleapis.com`. - - Якщо `messages.tts.providers.google.apiKey` не вказано, TTS може повторно використати `models.providers.google.apiKey` перед переходом до env. -- `providers.xai.apiKey`: API key xAI TTS (env: `XAI_API_KEY`). +- `providers.google.baseUrl`: перевизначає базовий URL Gemini API. Допускається лише `https://generativelanguage.googleapis.com`. + - Якщо `messages.tts.providers.google.apiKey` пропущено, TTS може повторно використати `models.providers.google.apiKey` до переходу на env fallback. +- `providers.xai.apiKey`: API-ключ xAI TTS (env: `XAI_API_KEY`). - `providers.xai.baseUrl`: перевизначає базовий URL xAI TTS (типово `https://api.x.ai/v1`, env: `XAI_BASE_URL`). -- `providers.xai.voiceId`: id голосу xAI (типово `eve`; поточні live-голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`). +- `providers.xai.voiceId`: id голосу xAI (типово `eve`; поточні доступні голоси: `ara`, `eve`, `leo`, `rex`, `sal`, `una`). - `providers.xai.language`: код мови BCP-47 або `auto` (типово `en`). - `providers.xai.responseFormat`: `mp3`, `wav`, `pcm`, `mulaw` або `alaw` (типово `mp3`). -- `providers.xai.speed`: нативне перевизначення швидкості провайдера. -- `providers.microsoft.enabled`: дозволити використання Microsoft speech (типово `true`; без API key). +- `providers.xai.speed`: перевизначення швидкості, специфічне для provider. +- `providers.microsoft.enabled`: дозволити використання Microsoft speech (типово `true`; API-ключ не потрібен). - `providers.microsoft.voice`: назва нейронного голосу Microsoft (наприклад, `en-US-MichelleNeural`). - `providers.microsoft.lang`: код мови (наприклад, `en-US`). - `providers.microsoft.outputFormat`: формат виводу Microsoft (наприклад, `audio-24khz-48kbitrate-mono-mp3`). - - Див. формати виводу Microsoft Speech для коректних значень; не всі формати підтримуються bundled-транспортом на основі Edge. -- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки відсотків (наприклад, `+10%`, `-5%`). -- `providers.microsoft.saveSubtitles`: записувати JSON-субтитри поряд з аудіофайлом. -- `providers.microsoft.proxy`: proxy URL для запитів Microsoft speech. + - Допустимі значення див. у форматах виводу Microsoft Speech; не всі формати підтримуються вбудованим transport на основі Edge. +- `providers.microsoft.rate` / `providers.microsoft.pitch` / `providers.microsoft.volume`: рядки з відсотками (наприклад, `+10%`, `-5%`). +- `providers.microsoft.saveSubtitles`: записувати JSON-субтитри поруч з аудіофайлом. +- `providers.microsoft.proxy`: URL проксі для запитів Microsoft speech. - `providers.microsoft.timeoutMs`: перевизначення тайм-ауту запиту (мс). - `edge.*`: застарілий псевдонім для тих самих налаштувань Microsoft. ## Перевизначення, керовані моделлю (типово ввімкнено) -За замовчуванням модель **може** видавати директиви TTS для однієї відповіді. -Коли `messages.tts.auto` має значення `tagged`, ці директиви потрібні для запуску аудіо. +Типово модель **може** виводити директиви TTS для однієї відповіді. +Коли `messages.tts.auto` має значення `tagged`, ці директиви є обов’язковими для запуску аудіо. -Коли це ввімкнено, модель може видавати директиви `[[tts:...]]`, щоб перевизначити голос -для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, щоб -надати експресивні теги (сміх, підказки для співу тощо), які мають з’являтися +Коли це ввімкнено, модель може виводити директиви `[[tts:...]]`, щоб перевизначити голос +для однієї відповіді, а також необов’язковий блок `[[tts:text]]...[[/tts:text]]`, +щоб надати виразні теги (сміх, підказки для співу тощо), які мають з’являтися лише в аудіо. -Директиви `provider=...` ігноруються, якщо не задано `modelOverrides.allowProvider: true`. +Директиви `provider=...` ігноруються, якщо не встановлено `modelOverrides.allowProvider: true`. Приклад payload відповіді: @@ -375,12 +375,12 @@ Here you go. Доступні ключі директив (коли ввімкнено): -- `provider` (id зареєстрованого speech-провайдера, наприклад `openai`, `elevenlabs`, `google`, `minimax` або `microsoft`; потребує `allowProvider: true`) +- `provider` (id зареєстрованого speech provider, наприклад `openai`, `elevenlabs`, `google`, `minimax` або `microsoft`; потребує `allowProvider: true`) - `voice` (голос OpenAI), `voiceName` / `voice_name` / `google_voice` (голос Google) або `voiceId` (ElevenLabs / MiniMax / xAI) -- `model` (TTS-модель OpenAI, id моделі ElevenLabs або модель MiniMax) або `google_model` (TTS-модель Google) +- `model` (модель OpenAI TTS, id моделі ElevenLabs або модель MiniMax) або `google_model` (модель Google TTS) - `stability`, `similarityBoost`, `style`, `speed`, `useSpeakerBoost` - `vol` / `volume` (гучність MiniMax, 0-10) -- `pitch` (тон MiniMax, від -12 до 12) +- `pitch` (висота тону MiniMax, від -12 до 12) - `applyTextNormalization` (`auto|on|off`) - `languageCode` (ISO 639-1) - `seed` @@ -399,7 +399,7 @@ Here you go. } ``` -Необов’язковий allowlist (увімкнути перемикання провайдера, зберігаючи можливість налаштовувати інші параметри): +Необов’язковий allowlist (увімкнути перемикання provider, залишивши інші параметри налаштовуваними): ```json5 { @@ -417,15 +417,15 @@ Here you go. ## Налаштування для окремого користувача -Слеш-команди записують локальні перевизначення в `prefsPath` (типово: -`~/.openclaw/settings/tts.json`, перевизначається через `OPENCLAW_TTS_PREFS` або +Slash-команди записують локальні перевизначення в `prefsPath` (типово: +`~/.openclaw/settings/tts.json`, можна перевизначити через `OPENCLAW_TTS_PREFS` або `messages.tts.prefsPath`). -Поля, що зберігаються: +Збережені поля: - `enabled` - `provider` -- `maxLength` (поріг зведення; типово 1500 символів) +- `maxLength` (поріг для підсумку; типово 1500 символів) - `summarize` (типово `true`) Вони перевизначають `messages.tts.*` для цього хоста. @@ -433,33 +433,33 @@ Here you go. ## Формати виводу (фіксовані) - **Feishu / Matrix / Telegram / WhatsApp**: голосове повідомлення Opus (`opus_48000_64` від ElevenLabs, `opus` від OpenAI). - - 48 кГц / 64 кбіт/с — хороший компроміс для голосового повідомлення. -- **Інші канали**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). + - 48 кГц / 64 кбіт/с — хороший компроміс для голосових повідомлень. +- **Інші channel**: MP3 (`mp3_44100_128` від ElevenLabs, `mp3` від OpenAI). - 44,1 кГц / 128 кбіт/с — типовий баланс для чіткості мовлення. - **MiniMax**: MP3 (модель `speech-2.8-hd`, частота дискретизації 32 кГц). Формат голосових нотаток нативно не підтримується; використовуйте OpenAI або ElevenLabs для гарантованих голосових повідомлень Opus. -- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/телефонії. Нативний формат голосових нотаток Opus цим шляхом не підтримується. -- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST TTS endpoint xAI і повертає готове аудіовкладення; потоковий WebSocket TTS xAI цим шляхом провайдера не використовується. Нативний формат голосових нотаток Opus цим шляхом не підтримується. +- **Google Gemini**: Gemini API TTS повертає сирий PCM 24 кГц. OpenClaw обгортає його у WAV для аудіовкладень і повертає PCM напряму для Talk/telephony. Нативний формат голосових нотаток Opus цим шляхом не підтримується. +- **xAI**: типово MP3; `responseFormat` може бути `mp3`, `wav`, `pcm`, `mulaw` або `alaw`. OpenClaw використовує пакетний REST-ендпоінт xAI TTS і повертає готове аудіовкладення; потоковий TTS WebSocket від xAI цим шляхом provider не використовується. Нативний формат голосових нотаток Opus цим шляхом не підтримується. - **Microsoft**: використовує `microsoft.outputFormat` (типово `audio-24khz-48kbitrate-mono-mp3`). - - Bundled-транспорт приймає `outputFormat`, але не всі формати доступні в сервісі. - - Значення форматів виводу відповідають форматам виводу Microsoft Speech (зокрема Ogg/WebM Opus). - - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам - потрібні гарантовані голосові повідомлення Opus. - - Якщо налаштований формат виводу Microsoft завершується помилкою, OpenClaw повторює спробу з MP3. + - Вбудований transport приймає `outputFormat`, але сервіс надає не всі формати. + - Значення формату виводу відповідають форматам виводу Microsoft Speech (включно з Ogg/WebM Opus). + - Telegram `sendVoice` приймає OGG/MP3/M4A; використовуйте OpenAI/ElevenLabs, якщо вам потрібні + гарантовані голосові повідомлення Opus. + - Якщо налаштований формат виводу Microsoft не спрацьовує, OpenClaw повторює спробу з MP3. -Формати виводу OpenAI/ElevenLabs зафіксовані для кожного каналу (див. вище). +Формати виводу OpenAI/ElevenLabs фіксовані для кожного channel (див. вище). ## Поведінка автоматичного TTS -Коли функцію ввімкнено, OpenClaw: +Коли ввімкнено, OpenClaw: - пропускає TTS, якщо відповідь уже містить медіа або директиву `MEDIA:`. - пропускає дуже короткі відповіді (< 10 символів). -- робить зведення довгих відповідей, якщо це ввімкнено, використовуючи `agents.defaults.model.primary` (або `summaryModel`). +- створює підсумок довгих відповідей, якщо це ввімкнено, за допомогою `agents.defaults.model.primary` (або `summaryModel`). - додає згенероване аудіо до відповіді. -Якщо відповідь перевищує `maxLength`, а зведення вимкнено (або немає API key для -моделі зведення), аудіо -пропускається й надсилається звичайна текстова відповідь. +Якщо відповідь перевищує `maxLength`, а підсумок вимкнено (або немає API-ключа для +моделі підсумку), аудіо +пропускається, і надсилається звичайна текстова відповідь. ## Схема потоку @@ -476,13 +476,13 @@ Reply -> TTS enabled? -> TTS -> attach audio ``` -## Використання слеш-команд +## Використання Slash-команди Є одна команда: `/tts`. -Докладно про ввімкнення див. у [Слеш-команди](/uk/tools/slash-commands). +Докладніше про ввімкнення див. у [Slash-команди](/uk/tools/slash-commands). Примітка для Discord: `/tts` — це вбудована команда Discord, тому OpenClaw реєструє -`/voice` як нативну команду там. Текстова форма `/tts ...` і далі працює. +там `/voice` як нативну команду. Текстова команда `/tts ...` усе ще працює. ``` /tts off @@ -496,24 +496,26 @@ Reply -> TTS enabled? Примітки: -- Команди потребують авторизованого відправника (правила allowlist/owner і далі застосовуються). +- Команди вимагають авторизованого відправника (правила allowlist/owner усе ще застосовуються). - Має бути ввімкнено `commands.text` або реєстрацію нативних команд. - Конфігурація `messages.tts.auto` приймає `off|always|inbound|tagged`. -- `/tts on` записує локальне налаштування TTS як `always`; `/tts off` записує його як `off`. +- `/tts on` записує локальне налаштування TTS у `always`; `/tts off` записує його в `off`. - Використовуйте конфігурацію, якщо вам потрібні типові значення `inbound` або `tagged`. - `limit` і `summary` зберігаються в локальних prefs, а не в основній конфігурації. -- `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS назавжди). -- `/tts status` містить видимість резервного переходу для останньої спроби: - - успішний резервний перехід: `Fallback: -> ` плюс `Attempts: ...` - - збій: `Error: ...` плюс `Attempts: ...` +- `/tts audio` генерує одноразову аудіовідповідь (не вмикає TTS). +- `/tts status` включає видимість fallback для останньої спроби: + - успішний fallback: `Fallback: -> ` плюс `Attempts: ...` + - помилка: `Error: ...` плюс `Attempts: ...` - докладна діагностика: `Attempt details: provider:outcome(reasonCode) latency` -- Збої API OpenAI і ElevenLabs тепер містять розібрані деталі помилки провайдера та id запиту (коли провайдер його повертає), які відображаються в помилках/журналах TTS. +- Збої API OpenAI та ElevenLabs тепер містять розібрані деталі помилки provider і request id (коли його повертає provider), які відображаються в помилках/логах TTS. ## Інструмент агента -Інструмент `tts` перетворює текст на мовлення і повертає аудіовкладення для -доставки у відповіді. Коли каналом є Feishu, Matrix, Telegram або WhatsApp, -аудіо доставляється як голосове повідомлення, а не як файлове вкладення. +Інструмент `tts` перетворює текст на мовлення та повертає аудіовкладення для +доставки у відповіді. Коли channel — це Feishu, Matrix, Telegram або WhatsApp, +аудіо доставляється як голосове повідомлення, а не як вкладення файлу. +Він приймає необов’язкові поля `channel` і `timeoutMs`; `timeoutMs` — це +тайм-аут запиту provider для кожного виклику в мілісекундах. ## Gateway RPC @@ -526,7 +528,7 @@ Reply -> TTS enabled? - `tts.setProvider` - `tts.providers` -## Пов’язане +## Пов’язані матеріали - [Огляд медіа](/uk/tools/media-overview) - [Генерація музики](/uk/tools/music-generation) diff --git a/docs/uk/tools/video-generation.md b/docs/uk/tools/video-generation.md index e7741f61d..a550b2298 100644 --- a/docs/uk/tools/video-generation.md +++ b/docs/uk/tools/video-generation.md @@ -3,41 +3,41 @@ read_when: - Генерація відео через агента - Налаштування провайдерів і моделей генерації відео - Розуміння параметрів інструмента `video_generate` -summary: Генеруйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів +summary: Створюйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів title: Генерація відео x-i18n: - generated_at: "2026-04-23T21:17:50Z" + generated_at: "2026-04-23T23:28:53Z" model: gpt-5.4 provider: openai - source_hash: 67b3b0c669489dca7c0903dbd2ddd7b0f3438a3a722c5cb2b78850ecd1906866 + source_hash: 4fb4053d417e62d6145f6cd2bc2717ae120ca9a7cff34089ba65d4ba79ec8c75 source_path: tools/video-generation.md workflow: 15 --- -Агенти OpenClaw можуть генерувати відео з текстових запитів, референсних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними параметрами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає правильного провайдера на основі вашої конфігурації та доступних API keys. +Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає потрібного провайдера на основі вашої конфігурації та доступних API-ключів. -Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, установіть API key провайдера або налаштуйте `agents.defaults.videoGenerationModel`. +Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, задайте API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`. -OpenClaw розглядає генерацію відео як три режими runtime: +OpenClaw розглядає генерацію відео як три режими виконання: -- `generate` для запитів text-to-video без референсних медіа -- `imageToVideo`, коли запит містить одне або кілька референсних зображень -- `videoToVideo`, коли запит містить одне або кілька референсних відео +- `generate` для запитів text-to-video без еталонних медіа +- `imageToVideo`, коли запит містить одне або кілька еталонних зображень +- `videoToVideo`, коли запит містить одне або кілька еталонних відео Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний режим перед надсиланням і повідомляє підтримувані режими в `action=list`. ## Швидкий старт -1. Установіть API key для будь-якого підтримуваного провайдера: +1. Установіть API-ключ для будь-якого підтримуваного провайдера: ```bash export GEMINI_API_KEY="your-key" ``` -2. За бажанням закріпіть типову модель: +2. За потреби зафіксуйте типову модель: ```bash openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview" @@ -45,31 +45,31 @@ openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1 3. Попросіть агента: -> Generate a 5-second cinematic video of a friendly lobster surfing at sunset. +> Згенеруй 5-секундне кінематографічне відео з доброзичливим лобстером, який катається на серфі на заході сонця. -Агент автоматично викличе `video_generate`. Allowlist для інструментів не потрібен. +Агент автоматично викличе `video_generate`. Дозвіл через список дозволеного для інструмента не потрібен. ## Що відбувається, коли ви генеруєте відео -Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії: +Генерація відео є асинхронною. Коли агент викликає `video_generate` у межах сеансу: -1. OpenClaw надсилає запит провайдеру і одразу повертає ID задачі. -2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності). -3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення. +1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання. +2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). +3. Коли відео готове, OpenClaw пробуджує той самий сеанс внутрішньою подією завершення. 4. Агент публікує готове відео назад у вихідну розмову. -Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан задачі замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show `, щоб перевіряти прогрес через CLI. +Поки завдання виконується, повторні виклики `video_generate` у тому самому сеансі повертають поточний стан завдання замість запуску ще однієї генерації. Щоб перевірити поступ через CLI, використовуйте `openclaw tasks list` або `openclaw tasks show `. -Поза запусками агента, прив’язаними до сесії (наприклад, у разі прямих викликів інструмента), інструмент використовує запасний варіант — inline-генерацію — і повертає фінальний шлях до медіа в тому самому ході. +Поза сеансами, пов’язаними із запуском агента (наприклад, для прямих викликів інструмента), інструмент переходить до inline-генерації й повертає фінальний шлях до медіафайла в тому самому ході. -### Життєвий цикл задачі +### Життєвий цикл завдання Кожен запит `video_generate` проходить через чотири стани: -1. **queued** -- задачу створено, вона очікує, поки провайдер її прийме. -2. **running** -- провайдер обробляє її (зазвичай від 30 секунд до 5 хвилин, залежно від провайдера та роздільної здатності). -3. **succeeded** -- відео готове; агент прокидається й публікує його в розмову. -4. **failed** -- помилка провайдера або тайм-аут; агент прокидається з деталями помилки. +1. **queued** -- завдання створено, очікує, доки провайдер його прийме. +2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). +3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову. +4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з відомостями про помилку. Перевірка стану через CLI: @@ -79,164 +79,166 @@ openclaw tasks show openclaw tasks cancel ``` -Запобігання дублюванню: якщо для поточної сесії задача відео вже має стан `queued` або `running`, `video_generate` повертає стан наявної задачі замість запуску нової. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. +Запобігання дублюванню: якщо для поточного сеансу вже є відеозавдання у стані `queued` або `running`, `video_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації. ## Підтримувані провайдери -| Провайдер | Типова модель | Текст | Референсне зображення | Референсне відео | API key | -| --------------------- | ------------------------------ | ----- | ------------------------------------------------------ | ---------------- | ---------------------------------------- | -| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | -| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший + останній кадр) | Ні | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший + останній кадр через роль) | Ні | `BYTEPLUS_API_KEY` | -| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 референсних зображень | До 3 відео | `BYTEPLUS_API_KEY` | -| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | -| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` | -| Google | `veo-3.1-fast-generate-preview`| Так | 1 зображення | 1 відео | `GEMINI_API_KEY` | -| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` | -| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` | -| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | -| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | -| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` | -| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` | -| xAI | `grok-imagine-video` | Так | 1 зображення | 1 відео | `XAI_API_KEY` | +| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | API-ключ | +| -------------------- | ------------------------------ | ----- | ---------------------------------------------------- | ---------------- | ---------------------------------------- | +| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` | +| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший і останній кадр) | Ні | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший і останній кадр через role) | Ні | `BYTEPLUS_API_KEY` | +| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` | +| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` | +| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення | Ні | `FAL_KEY` | +| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` | +| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` | +| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` | +| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` | +| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` | +| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` | +| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` | +| xAI | `grok-imagine-video` | Так | 1 зображення | 1 відео | `XAI_API_KEY` | -Деякі провайдери приймають додаткові або альтернативні env vars для API key. Подробиці див. на окремих [сторінках провайдерів](#related). +Деякі провайдери приймають додаткові або альтернативні змінні середовища для API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related). -Запустіть `video_generate action=list`, щоб під час runtime переглянути доступних провайдерів, моделі та режими runtime. +Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та +режими виконання. -### Матриця оголошених можливостей +### Матриця заявлених можливостей -Це явний контракт режимів, який використовується `video_generate`, contract tests -і спільною live-перевіркою. +Це явний контракт режимів, який використовують `video_generate`, контрактні тести +та спільний live sweep. -| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Поточні спільні live-lanes | -| --------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | -| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` | -| ComfyUI | Так | Так | Ні | Не входить до спільної перевірки; покриття, специфічне для workflow, живе разом із тестами Comfy | -| fal | Так | Так | Ні | `generate`, `imageToVideo` | -| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки поточна buffer-backed Gemini/Veo перевірка не приймає такий ввід | -| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` | -| OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропускається, оскільки цей шлях org/input наразі потребує доступу до provider-side inpaint/remix | -| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | -| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | -| Together | Так | Так | Ні | `generate`, `imageToVideo` | -| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропускається, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення | -| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропускається, оскільки цьому провайдеру наразі потрібен віддалений MP4 URL | +| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-lane сьогодні | +| --------- | ---------- | -------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | +| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` | +| ComfyUI | Так | Так | Ні | Не входить до спільного sweep; покриття, специфічне для workflow, живе в тестах Comfy | +| fal | Так | Так | Ні | `generate`, `imageToVideo` | +| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний sweep Gemini/Veo на основі буфера не приймає це введення | +| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` | +| OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input зараз потребує доступу до inpaint/remix на боці провайдера | +| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео | +| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` запускається лише тоді, коли вибрана модель — `runway/gen4_aleph` | +| Together | Так | Так | Ні | `generate`, `imageToVideo` | +| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` потребує віддаленого URL зображення | +| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру зараз потрібен віддалений MP4 URL | ## Параметри інструмента ### Обов’язкові -| Параметр | Тип | Опис | -| -------- | ------ | ------------------------------------------------------------------------------- | -| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | +| Параметр | Тип | Опис | +| -------- | ------ | --------------------------------------------------------------------------- | +| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) | -### Вхідний вміст +### Вхідні дані вмісту -| Параметр | Тип | Опис | -| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------- | -| `image` | string | Одне референсне зображення (шлях або URL) | -| `images` | string[] | Кілька референсних зображень (до 9) | -| `imageRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` | -| `video` | string | Одне референсне відео (шлях або URL) | -| `videos` | string[] | Кілька референсних відео (до 4) | -| `videoRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку відео. Канонічне значення: `reference_video` | -| `audioRef` | string | Одне референсне аудіо (шлях або URL). Використовується, наприклад, для фонової музики або голосового референсу, коли провайдер підтримує аудіовходи | -| `audioRefs` | string[] | Кілька референсних аудіо (до 3) | -| `audioRoles` | string[] | Необов’язкові role hints для кожної позиції, паралельні об’єднаному списку аудіо. Канонічне значення: `reference_audio` | +| Параметр | Тип | Опис | +| ----------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | +| `image` | string | Одне еталонне зображення (шлях або URL) | +| `images` | string[] | Кілька еталонних зображень (до 9) | +| `imageRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` | +| `video` | string | Одне еталонне відео (шлях або URL) | +| `videos` | string[] | Кілька еталонних відео (до 4) | +| `videoRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку відео. Канонічне значення: `reference_video` | +| `audioRef` | string | Один еталонний аудіофайл (шлях або URL). Використовується, наприклад, для фонової музики або еталона голосу, коли провайдер підтримує аудіовхід | +| `audioRefs` | string[] | Кілька еталонних аудіофайлів (до 3) | +| `audioRoles` | string[] | Необов’язкові підказки ролей за позиціями, паралельні об’єднаному списку аудіо. Канонічне значення: `reference_audio` | -Role hints пересилаються провайдеру без змін. Канонічні значення походять із +Підказки ролей пересилаються провайдеру як є. Канонічні значення походять із об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові рядки ролей. Масиви `*Roles` не можуть містити більше записів, ніж -відповідний список референсів; помилки типу off-by-one завершуються зрозумілою помилкою. -Використовуйте порожній рядок, щоб залишити слот невстановленим. +відповідний список еталонів; помилки на один елемент дають чітке повідомлення. +Використовуйте порожній рядок, щоб залишити позицію незаданою. ### Керування стилем -| Параметр | Тип | Опис | -| ---------------- | ------- | -------------------------------------------------------------------------------------- | -| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` | -| `resolution` | string | `480P`, `720P`, `768P` або `1080P` | -| `durationSeconds`| number | Цільова тривалість у секундах (округлюється до найближчого значення, підтримуваного провайдером) | -| `size` | string | Підказка розміру, коли провайдер це підтримує | -| `audio` | boolean | Увімкнути згенероване аудіо у виводі, коли це підтримується. Відрізняється від `audioRef*` (входи) | -| `watermark` | boolean | Увімкнути або вимкнути watermark провайдера, коли це підтримується | +| Параметр | Тип | Опис | +| ----------------- | ------- | ----------------------------------------------------------------------------------------- | +| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` | +| `resolution` | string | `480P`, `720P`, `768P` або `1080P` | +| `durationSeconds` | number | Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер) | +| `size` | string | Підказка розміру, якщо провайдер це підтримує | +| `audio` | boolean | Увімкнути згенерований звук у виводі, якщо підтримується. Відрізняється від `audioRef*` (входи) | +| `watermark` | boolean | Перемикає водяні знаки провайдера, якщо підтримується | -`adaptive` — це provider-specific sentinel: він пересилається без змін -провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад BytePlus -Seedance використовує його для автоматичного визначення співвідношення сторін із -розмірів вхідного зображення). Провайдери, які не оголошують цю можливість, показують це значення через +`adaptive` — це специфічний для провайдера sentinel: він пересилається як є +провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus +Seedance використовує його, щоб автоматично визначати співвідношення сторін за розмірами +вхідного зображення). Провайдери, які його не оголошують, відображають це значення через `details.ignoredOverrides` у результаті інструмента, щоб відкидання було видимим. -### Розширені +### Додатково -| Параметр | Тип | Опис | -| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `action` | string | `"generate"` (типово), `"status"` або `"list"` | -| `model` | string | Перевизначення провайдера/моделі (наприклад `runway/gen4.5`) | -| `filename` | string | Підказка для імені вихідного файла | -| `providerOptions`| object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі та типи значень; невідомі ключі або невідповідності призводять до пропуску кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер | +| Параметр | Тип | Опис | +| ----------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `action` | string | `"generate"` (типово), `"status"` або `"list"` | +| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) | +| `filename` | string | Підказка для імені вихідного файла | +| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах | +| `providerOptions` | object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі й типи; невідомі ключі або невідповідності змушують пропустити кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`, щоб побачити, що приймає кожен провайдер | -Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого значення, яке підтримує провайдер, а також переназначає перекладені геометричні підказки, як-от size-to-aspect-ratio, коли fallback-провайдер надає іншу surface керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто багато референсних входів) призводять до помилки ще до надсилання. +Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого значення, яке підтримує провайдер, а також переназначає перекладені підказки геометрії, як-от size-to-aspect-ratio, коли fallback-провайдер надає іншу поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто велика кількість еталонних входів) спричиняють помилку до надсилання. -Результати інструмента повідомляють про застосовані параметри. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернені значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що фактично було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. +Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернуті значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого. -Референсні входи також визначають режим runtime: +Еталонні входи також визначають режим виконання: -- Без референсних медіа: `generate` -- Будь-яке референсне зображення: `imageToVideo` -- Будь-яке референсне відео: `videoToVideo` -- Референсні аудіовходи не змінюють визначений режим; вони застосовуються поверх режиму, який вибирають референсні зображення/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios` +- Без еталонних медіа: `generate` +- Будь-яке еталонне зображення: `imageToVideo` +- Будь-яке еталонне відео: `videoToVideo` +- Еталонні аудіовходи не змінюють визначений режим; вони застосовуються поверх режиму, який вибрали еталонні зображення/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios` -Змішані референси зображень і відео не є стабільною спільною поверхнею можливостей. -Надавайте перевагу одному типу референсу на запит. +Змішані еталонні зображення та відео не є стабільною спільною поверхнею можливостей. +Краще використовувати один тип еталона на запит. #### Fallback і типізовані параметри -Деякі перевірки можливостей застосовуються на рівні fallback, а не на -межі інструмента, щоб запит, який перевищує обмеження основного провайдера, -усе ще міг виконатися на fallback-провайдері, який це підтримує: +Деякі перевірки можливостей застосовуються на рівні fallback, а не на межі +інструмента, щоб запит, який перевищує обмеження основного провайдера, +усе ще міг виконатися на придатному fallback: - Якщо активний кандидат не оголошує `maxInputAudios` (або оголошує його як - `0`), він пропускається, коли запит містить аудіореференси, і - пробується наступний кандидат. -- Якщо `maxDurationSeconds` активного кандидата нижчий за запитане + `0`), його пропускають, коли запит містить еталонні аудіо, і + пробують наступного кандидата. +- Якщо `maxDurationSeconds` активного кандидата менше за запитане `durationSeconds`, а кандидат не оголошує список - `supportedDurationSeconds`, він пропускається. + `supportedDurationSeconds`, його пропускають. - Якщо запит містить `providerOptions`, а активний кандидат - явно оголошує типізовану схему `providerOptions`, кандидат - пропускається, коли передані ключі відсутні в схемі або типи значень + явно оголошує типізовану схему `providerOptions`, кандидата + пропускають, якщо надані ключі відсутні в схемі або типи значень не збігаються. Провайдери, які ще не оголосили схему, отримують - параметри як є (зворотно сумісний pass-through). Провайдер може - явно відмовитися від усіх provider options, оголосивши порожню схему - (`capabilities.providerOptions: {}`), що спричиняє той самий пропуск, що і - невідповідність типу. + параметри як є (зворотно сумісне наскрізне передавання). Провайдер може + явно відмовитися від усіх параметрів провайдера, оголосивши порожню схему + (`capabilities.providerOptions: {}`), що спричиняє те саме пропускання, що й + невідповідність типів. Перша причина пропуску в запиті логується на рівні `warn`, щоб оператори бачили, -коли основного провайдера було пропущено; наступні пропуски логуются на -рівні `debug`, щоб довгі fallback-ланцюжки не шуміли. Якщо пропущено кожного кандидата, -агрегована помилка включає причину пропуску для кожного. +коли їхнього основного провайдера було пропущено; наступні пропуски логуются на +рівні `debug`, щоб довгі ланцюжки fallback не створювали зайвого шуму. Якщо пропущено кожного кандидата, +агрегована помилка містить причину пропуску для кожного з них. ## Дії -- **generate** (типово) -- створити відео з указаного prompt і необов’язкових референсних входів. -- **status** -- перевірити стан поточної video task для поточної сесії без запуску нової генерації. +- **generate** (типово) -- створити відео з указаного запиту та необов’язкових еталонних входів. +- **status** -- перевірити стан відеозавдання, яке виконується для поточного сеансу, без запуску нової генерації. - **list** -- показати доступних провайдерів, моделі та їхні можливості. ## Вибір моделі Під час генерації відео OpenClaw визначає модель у такому порядку: -1. **Параметр інструмента `model`** -- якщо агент указує його у виклику. -2. **`videoGenerationModel.primary`** -- з конфігурації. -3. **`videoGenerationModel.fallbacks`** -- пробуються по порядку. -4. **Автовиявлення** -- використовує провайдерів із дійсною автентифікацією, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку. +1. **параметр інструмента `model`** -- якщо агент указує його у виклику. +2. **`videoGenerationModel.primary`** -- із конфігурації. +3. **`videoGenerationModel.fallbacks`** -- випробовуються по черзі. +4. **Автовизначення** -- використовує провайдерів із валідною автентифікацією, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку. -Якщо провайдер дає збій, автоматично пробується наступний кандидат. Якщо всі кандидати дають збій, помилка включає подробиці кожної спроби. +Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі кандидати завершуються помилкою, помилка містить подробиці кожної спроби. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо ви хочете, -щоб генерація відео використовувала лише явні записи `model`, `primary` і `fallbacks`. +щоб генерація відео використовувала лише явно задані записи `model`, `primary` і `fallbacks`. ```json5 { @@ -251,29 +253,29 @@ Seedance використовує його для автоматичного в } ``` -## Примітки про провайдерів +## Примітки щодо провайдерів -| Провайдер | Примітки | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Alibaba | Використовує асинхронний endpoint DashScope/Model Studio. Референсні зображення та відео мають бути віддаленими `http(s)` URL-адресами. | -| BytePlus (1.0) | ID провайдера `byteplus`. Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і загальні моделі `*-pro-*` підтримують одне референсне зображення (перший кадр). Передавайте зображення позиційно або встановлюйте `role: "first_frame"`. ID моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean, примусово задає 480p), `camera_fixed` (boolean). | -| BytePlus Seedance 1.5 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. Використовує уніфікований API `content[]`. Підтримує максимум 2 вхідних зображення (first_frame + last_frame). Усі входи мають бути віддаленими `https://` URL-адресами. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передавайте зображення позиційно. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) пересилається далі. | -| BytePlus Seedance 2.0 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). ID провайдера `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Використовує уніфікований API `content[]`. Підтримує до 9 референсних зображень, 3 референсних відео та 3 референсних аудіо. Усі входи мають бути віддаленими `https://` URL-адресами. Установіть `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) пересилається далі. | -| ComfyUI | Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований graph. | -| fal | Використовує queue-backed flow для довготривалих завдань. Лише одне референсне зображення. | -| Google | Використовує Gemini/Veo. Підтримує одне референсне зображення або одне референсне відео. | -| MiniMax | Лише одне референсне зображення. | -| OpenAI | Пересилається лише перевизначення `size`. Інші стильові перевизначення (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. | -| Qwen | Той самий бекенд DashScope, що й Alibaba. Референсні входи мають бути віддаленими `http(s)` URL-адресами; локальні файли відхиляються одразу. | -| Runway | Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Для запусків лише з текстом доступні співвідношення сторін `16:9` і `9:16`. | -| Together | Лише одне референсне зображення. | -| Vydra | Використовує напряму `https://www.vydra.ai/api/v1`, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано як text-to-video only; `kling` потребує віддаленої URL-адреси зображення. | -| xAI | Підтримує text-to-video, image-to-video і віддалені потоки редагування/розширення відео. | +| Провайдер | Примітки | +| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| Alibaba | Використовує асинхронний endpoint DashScope/Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`. | +| BytePlus (1.0) | Ідентифікатор провайдера `byteplus`. Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`. Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`. Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення. Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean, примусово встановлює 480p), `camera_fixed` (boolean). | +| BytePlus Seedance 1.5 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`. Використовує уніфікований API `content[]`. Підтримує не більш як 2 вхідні зображення (first_frame + last_frame). Усі входи мають бути віддаленими URL `https://`. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передайте зображення позиційно. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін за вхідним зображенням. `audio: true` відображається на `generate_audio`. `providerOptions.seed` (number) пересилається далі. | +| BytePlus Seedance 2.0 | Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`. Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими URL `https://`. Установлюйте `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`. `aspectRatio: "adaptive"` автоматично визначає співвідношення сторін за вхідним зображенням. `audio: true` відображається на `generate_audio`. `providerOptions.seed` (number) пересилається далі. | +| ComfyUI | Виконання локально або в хмарі на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф. | +| fal | Використовує flow на основі черги для довготривалих завдань. Лише одне еталонне зображення. | +| Google | Використовує Gemini/Veo. Підтримує одне еталонне зображення або одне еталонне відео. | +| MiniMax | Лише одне еталонне зображення. | +| OpenAI | Пересилається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням. | +| Qwen | Такий самий бекенд DashScope, як і в Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли відхиляються одразу. | +| Runway | Підтримує локальні файли через data URI. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`. | +| Together | Лише одне еталонне зображення. | +| Vydra | Напряму використовує `https://www.vydra.ai/api/v1`, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує віддаленого URL зображення. | +| xAI | Підтримує text-to-video, image-to-video та потоки віддаленого редагування/розширення відео. | -## Режими можливостей провайдера +## Режими можливостей провайдерів -Спільний контракт генерації відео тепер дозволяє провайдерам оголошувати -можливості, специфічні для режиму, а не лише плоскі агреговані обмеження. Нові +Спільний контракт генерації відео тепер дає провайдерам змогу оголошувати +можливості, специфічні для режиму, замість лише пласких агрегованих обмежень. Нові реалізації провайдерів мають надавати перевагу явним блокам режимів: ```typescript @@ -298,55 +300,55 @@ capabilities: { } ``` -Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо -для оголошення підтримки transform-режимів. Провайдери мають оголошувати -`generate`, `imageToVideo` і `videoToVideo` явно, щоб live tests, -contract tests і спільний інструмент `video_generate` могли детерміновано +Пласких агрегованих полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо, +щоб оголосити підтримку режимів перетворення. Провайдери мають оголошувати +`generate`, `imageToVideo` і `videoToVideo` явно, щоб live-тести, +контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти підтримку режимів. -## Live tests +## Live-тести -Opt-in live-покриття для спільних вбудованих провайдерів: +Опціональне live-покриття для спільних вбудованих провайдерів: ```bash OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts ``` -Repo wrapper: +Обгортка репозиторію: ```bash pnpm test:live:media video ``` -Цей live-файл завантажує відсутні env vars провайдерів із `~/.profile`, типово віддає -перевагу live/env API keys над збереженими профілями автентифікації, і за замовчуванням запускає -безпечний для релізу smoke: +Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово +надає перевагу live/env API-ключам над збереженими профілями автентифікації та запускає +безпечний для релізу smoke-тест за замовчуванням: -- `generate` для кожного провайдера в перевірці, крім FAL -- prompt про лобстера на одну секунду -- обмеження операцій для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` - (`180000` типово) +- `generate` для кожного провайдера зі sweep, окрім FAL +- односекундний запит про лобстера +- обмеження операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` + (`180000` за замовчуванням) -FAL вмикається лише за бажанням, оскільки затримка черги на боці провайдера може домінувати над часом релізу: +FAL є опціональним, оскільки затримка черги на боці провайдера може суттєво збільшувати час релізу: ```bash pnpm test:live:media video --video-providers fal ``` -Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені transform-режими, -які спільна перевірка може безпечно виконувати з локальними медіа: +Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення, +які спільний sweep може безпечно виконувати з локальними медіа: - `imageToVideo`, коли `capabilities.imageToVideo.enabled` - `videoToVideo`, коли `capabilities.videoToVideo.enabled` і провайдер/модель - приймає buffer-backed локальний вхід відео у спільній перевірці + приймає локальний відеовхід на основі буфера в межах спільного sweep -Наразі спільний live-lane `videoToVideo` охоплює: +Сьогодні спільна live-lane `videoToVideo` покриває: -- `runway` лише тоді, коли ви вибираєте `runway/gen4_aleph` +- лише `runway`, коли ви вибираєте `runway/gen4_aleph` ## Конфігурація -Установіть типову модель генерації відео у своїй конфігурації OpenClaw: +Установіть типову модель генерації відео у конфігурації OpenClaw: ```json5 { @@ -370,7 +372,7 @@ openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2 ## Пов’язане - [Огляд інструментів](/uk/tools) -- [Фонові завдання](/uk/automation/tasks) -- відстеження задач для асинхронної генерації відео +- [Фонові завдання](/uk/automation/tasks) -- відстеження завдань для асинхронної генерації відео - [Alibaba Model Studio](/uk/providers/alibaba) - [BytePlus](/uk/concepts/model-providers#byteplus-international) - [ComfyUI](/uk/providers/comfy)