From 8074591b98e6e29f3d365546d6150ea12022064b Mon Sep 17 00:00:00 2001 From: "openclaw-docs-i18n[bot]" Date: Sat, 25 Apr 2026 00:05:46 +0000 Subject: [PATCH] chore(i18n): refresh uk translations --- docs/uk/channels/discord.md | 522 +++++++++--------- docs/uk/channels/slack.md | 331 ++++++------ docs/uk/ci.md | 163 +++--- docs/uk/cli/browser.md | 111 ++-- docs/uk/cli/status.md | 42 +- docs/uk/concepts/model-providers.md | 300 +++++------ docs/uk/gateway/config-agents.md | 484 ++++++++--------- docs/uk/help/testing.md | 766 ++++++++++++++------------- docs/uk/nodes/media-understanding.md | 136 ++--- docs/uk/plugins/building-plugins.md | 224 ++++---- docs/uk/plugins/codex-harness.md | 368 ++++++------- docs/uk/plugins/manifest.md | 514 +++++++++--------- docs/uk/plugins/sdk-agent-harness.md | 220 +++----- docs/uk/plugins/sdk-migration.md | 643 +++++++++++----------- docs/uk/plugins/sdk-overview.md | 314 ++++++----- docs/uk/providers/google.md | 189 ++++--- docs/uk/providers/openai.md | 437 ++++++++------- docs/uk/reference/test.md | 98 ++-- docs/uk/tools/browser-control.md | 177 ++++--- docs/uk/tools/browser.md | 397 +++++++------- docs/uk/tools/pdf.md | 97 ++-- docs/uk/tools/slash-commands.md | 359 ++++++------- 22 files changed, 3389 insertions(+), 3503 deletions(-) diff --git a/docs/uk/channels/discord.md b/docs/uk/channels/discord.md index 15b27194d..46b4038cf 100644 --- a/docs/uk/channels/discord.md +++ b/docs/uk/channels/discord.md @@ -1,72 +1,72 @@ --- read_when: - Робота над функціями каналу Discord -summary: Статус підтримки бота Discord, можливості та налаштування +summary: Статус підтримки Discord бота, можливості та конфігурація title: Discord x-i18n: - generated_at: "2026-04-24T17:24:52Z" + generated_at: "2026-04-25T00:01:07Z" model: gpt-5.4 provider: openai - source_hash: df5d215c6a6c43e1b3f60837752f60eafc6e34c1ffd4aaceb2f60d4dd3c130be + source_hash: 349f82e96e17aad30e4dc28c25d06841121f37b35c367f13f52cd0700105bd11 source_path: channels/discord.md workflow: 15 --- -Готово для приватних повідомлень і каналів серверів через офіційний Gateway Discord. +Готово для особистих повідомлень і каналів гільдії через офіційний Gateway Discord. - - Приватні повідомлення Discord за замовчуванням використовують режим сполучення. + + Особисті повідомлення Discord типово працюють у режимі підключення. - Нативна поведінка команд і каталог команд. + Власна поведінка команд і каталог команд. - Міжканальна діагностика та процес відновлення. + Діагностика між каналами та процес відновлення. ## Швидке налаштування -Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і сполучити його з OpenClaw. Ми рекомендуємо додати бота до вашого власного приватного сервера. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). +Вам потрібно створити новий застосунок із ботом, додати бота на свій сервер і підключити його до OpenClaw. Ми рекомендуємо додати бота на ваш власний приватний сервер. Якщо у вас його ще немає, [спочатку створіть його](https://support.discord.com/hc/en-us/articles/204849977-How-do-I-create-a-server) (виберіть **Create My Own > For me and my friends**). - + Перейдіть до [Discord Developer Portal](https://discord.com/developers/applications) і натисніть **New Application**. Назвіть його, наприклад, "OpenClaw". - На бічній панелі натисніть **Bot**. Установіть **Username** на ту назву, якою ви називаєте свого агента OpenClaw. + Натисніть **Bot** на бічній панелі. Установіть **Username** на ту назву, якою ви називаєте свого агента OpenClaw. - - Усе ще на сторінці **Bot** прокрутіть до **Privileged Gateway Intents** і увімкніть: + + Досі на сторінці **Bot**, прокрутіть до **Privileged Gateway Intents** і ввімкніть: - **Message Content Intent** (обов’язково) - **Server Members Intent** (рекомендовано; обов’язково для allowlist ролей і зіставлення імені з ID) - - **Presence Intent** (необов’язково; потрібне лише для оновлень присутності) + - **Presence Intent** (необов’язково; потрібне лише для оновлень статусу) - + Прокрутіть угору на сторінці **Bot** і натисніть **Reset Token**. Попри назву, це генерує ваш перший токен — нічого не «скидається». - Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він незабаром знадобиться. + Скопіюйте токен і збережіть його десь. Це ваш **Bot Token**, і він вам скоро знадобиться. - - На бічній панелі натисніть **OAuth2**. Ви згенеруєте URL-запрошення з правильними дозволами, щоб додати бота на свій сервер. + + Натисніть **OAuth2** на бічній панелі. Ви згенеруєте URL-запрошення з правильними дозволами, щоб додати бота на свій сервер. - Прокрутіть до **OAuth2 URL Generator** і увімкніть: + Прокрутіть до **OAuth2 URL Generator** і ввімкніть: - `bot` - `applications.commands` - Нижче з’явиться розділ **Bot Permissions**. Увімкніть щонайменше: + Унизу з’явиться розділ **Bot Permissions**. Увімкніть щонайменше: **General Permissions** - View Channels @@ -78,30 +78,30 @@ x-i18n: - Add Reactions (необов’язково) Це базовий набір для звичайних текстових каналів. Якщо ви плануєте публікувати в тредах Discord, зокрема в процесах форумних або медіаканалів, які створюють або продовжують тред, також увімкніть **Send Messages in Threads**. - Скопіюйте згенерований URL унизу, вставте його в браузер, виберіть свій сервер і натисніть **Continue** для підключення. Тепер ви маєте бачити свого бота на сервері Discord. + Скопіюйте згенерований URL унизу, вставте його у браузер, виберіть свій сервер і натисніть **Continue**, щоб підключити. Тепер ви маєте побачити свого бота на сервері Discord. - Повернувшись у застосунок Discord, вам потрібно увімкнути Developer Mode, щоб мати змогу копіювати внутрішні ID. + Повернувшись у застосунок Discord, вам потрібно ввімкнути Developer Mode, щоб мати змогу копіювати внутрішні ID. 1. Натисніть **User Settings** (значок шестерні поруч із вашим аватаром) → **Advanced** → увімкніть **Developer Mode** - 2. Клацніть правою кнопкою миші **значок сервера** на бічній панелі → **Copy Server ID** - 3. Клацніть правою кнопкою миші свій **аватар** → **Copy User ID** + 2. Клацніть правою кнопкою миші на **значку сервера** на бічній панелі → **Copy Server ID** + 3. Клацніть правою кнопкою миші на **своєму аватарі** → **Copy User ID** - Збережіть свої **Server ID** і **User ID** разом із Bot Token — на наступному кроці ви передасте всі три значення в OpenClaw. + Збережіть свій **Server ID** і **User ID** разом із Bot Token — ви надішлете всі три до OpenClaw на наступному кроці. - - Щоб сполучення працювало, Discord має дозволяти вашому боту надсилати вам приватні повідомлення. Клацніть правою кнопкою миші **значок сервера** → **Privacy Settings** → увімкніть **Direct Messages**. + + Щоб підключення працювало, Discord має дозволяти вашому боту надсилати вам особисті повідомлення. Клацніть правою кнопкою миші на **значку сервера** → **Privacy Settings** → увімкніть **Direct Messages**. - Це дозволяє учасникам сервера (зокрема ботам) надсилати вам приватні повідомлення. Залиште це ввімкненим, якщо хочете використовувати приватні повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали сервера, після сполучення можна вимкнути приватні повідомлення. + Це дозволяє учасникам сервера (включно з ботами) надсилати вам особисті повідомлення. Залиште це ввімкненим, якщо хочете використовувати особисті повідомлення Discord з OpenClaw. Якщо ви плануєте використовувати лише канали гільдії, можете вимкнути особисті повідомлення після підключення. - - Токен вашого бота Discord — це секрет (як пароль). Установіть його на машині, де працює OpenClaw, перш ніж надсилати повідомлення агенту. + + Токен вашого бота Discord — це секрет (як пароль). Установіть його на машині, де працює OpenClaw, перш ніж писати своєму агенту. ```bash export DISCORD_BOT_TOKEN="YOUR_BOT_TOKEN" @@ -115,16 +115,16 @@ openclaw gateway - + - - Напишіть своєму агенту OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і скажіть йому це. Якщо Discord — ваш перший канал, натомість використайте вкладку CLI / config. + + Напишіть своєму агенту OpenClaw у будь-якому наявному каналі (наприклад, Telegram) і повідомте йому це. Якщо Discord — ваш перший канал, замість цього використайте вкладку CLI / config. - > "Я вже встановив токен свого Discord-бота в config. Будь ласка, заверши налаштування Discord з User ID `` і Server ID ``." + > "Я вже встановив токен свого Discord бота в конфігурації. Будь ласка, заверши налаштування Discord з User ID `` і Server ID ``." - Якщо ви віддаєте перевагу файловій конфігурації, установіть: + Якщо ви віддаєте перевагу файловій конфігурації, встановіть: ```json5 { @@ -141,27 +141,27 @@ openclaw gateway } ``` - Резервне env-значення для стандартного облікового запису: + Резервне значення env для облікового запису за замовчуванням: ```bash DISCORD_BOT_TOKEN=... ``` - Підтримуються plaintext-значення `token`. Значення SecretRef також підтримуються для `channels.discord.token` у провайдерах env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). + Підтримуються прості текстові значення `token`. Також підтримуються значення SecretRef для `channels.discord.token` у постачальниках env/file/exec. Див. [Керування секретами](/uk/gateway/secrets). - - Дочекайтеся, поки Gateway запуститься, а потім напишіть боту в приватні повідомлення в Discord. У відповідь він надішле код сполучення. + + Дочекайтеся, поки Gateway запуститься, а потім напишіть своєму боту в Discord. Він відповість кодом підключення. - - Надішліть код сполучення своєму агенту в наявному каналі: + + Надішліть код підключення своєму агенту у вашому наявному каналі: - > "Схвали цей код сполучення Discord: ``" + > "Підтвердь цей код підключення Discord: ``" @@ -173,29 +173,29 @@ openclaw pairing approve discord - Термін дії кодів сполучення закінчується через 1 годину. + Термін дії кодів підключення спливає через 1 годину. - Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через приватні повідомлення. + Тепер ви маєте змогу спілкуватися зі своїм агентом у Discord через особисті повідомлення. -Визначення токена враховує обліковий запис. Значення токена в config мають пріоритет над резервним env-значенням. `DISCORD_BOT_TOKEN` використовується лише для стандартного облікового запису. -Для розширених вихідних викликів (дії інструмента повідомлень/каналу) явний `token` використовується для цього конкретного виклику. Це стосується дій надсилання та читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Політика облікового запису/повторних спроб усе ще надходить із вибраного облікового запису в активному runtime snapshot. +Визначення токена враховує обліковий запис. Значення токена в конфігурації мають пріоритет над резервним значенням env. `DISCORD_BOT_TOKEN` використовується лише для облікового запису за замовчуванням. +Для розширених вихідних викликів (інструмент повідомлень/дії каналу) явний `token` використовується для цього конкретного виклику. Це стосується дій надсилання та дій читання/перевірки (наприклад, read/search/fetch/thread/pins/permissions). Параметри політики облікового запису/повторних спроб і надалі беруться з вибраного облікового запису в активному знімку runtime. -## Рекомендовано: налаштуйте робочий простір сервера +## Рекомендовано: Налаштуйте робочий простір гільдії -Коли приватні повідомлення вже працюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує окрему сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. +Щойно особисті повідомлення запрацюють, ви можете налаштувати свій сервер Discord як повноцінний робочий простір, де кожен канал отримує власну сесію агента з власним контекстом. Це рекомендовано для приватних серверів, де є лише ви та ваш бот. - - Це дозволяє вашому агенту відповідати в будь-якому каналі вашого сервера, а не лише в приватних повідомленнях. + + Це дає змогу вашому агенту відповідати в будь-якому каналі на вашому сервері, а не лише в особистих повідомленнях. - - > "Додай мій Server ID Discord `` до allowlist серверів" + + > "Додай мій Server ID Discord `` до allowlist гільдії" @@ -221,14 +221,14 @@ openclaw pairing approve discord - За замовчуванням ваш агент відповідає в каналах сервера лише тоді, коли його згадують через @mention. Для приватного сервера вам, імовірно, потрібно, щоб він відповідав на кожне повідомлення. + За замовчуванням ваш агент відповідає в каналах гільдії лише тоді, коли його згадують через @mention. Для приватного сервера ви, ймовірно, захочете, щоб він відповідав на кожне повідомлення. - - > "Дозволь моєму агенту відповідати на цьому сервері без потреби в @mentioned" + + > "Дозволь моєму агенту відповідати на цьому сервері без потреби в @mention" - Установіть `requireMention: false` у конфігурації сервера: + Установіть `requireMention: false` у конфігурації вашої гільдії: ```json5 { @@ -249,31 +249,31 @@ openclaw pairing approve discord - - За замовчуванням довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях приватних повідомлень. У каналах сервера `MEMORY.md` не завантажується автоматично. + + За замовчуванням довготривала пам’ять (`MEMORY.md`) завантажується лише в сесіях особистих повідомлень. У каналах гільдії `MEMORY.md` автоматично не завантажується. - + > "Коли я ставлю запитання в каналах Discord, використовуй memory_search або memory_get, якщо тобі потрібен довготривалий контекст із MEMORY.md." - Якщо вам потрібен спільний контекст у кожному каналі, розмістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони додаються до кожної сесії). Довготривалі нотатки зберігайте в `MEMORY.md` і звертайтеся до них за потреби за допомогою інструментів пам’яті. + Якщо вам потрібен спільний контекст у кожному каналі, помістіть стабільні інструкції в `AGENTS.md` або `USER.md` (вони додаються до кожної сесії). Зберігайте довготривалі нотатки в `MEMORY.md` і звертайтеся до них за потреби через інструменти пам’яті. -Тепер створіть кілька каналів на своєму сервері Discord і починайте спілкуватися. Ваш агент може бачити назву каналу, і кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що інше, що відповідає вашому робочому процесу. +Тепер створіть кілька каналів на своєму сервері Discord і почніть спілкування. Ваш агент бачить назву каналу, а кожен канал отримує власну ізольовану сесію — тож ви можете налаштувати `#coding`, `#home`, `#research` або будь-що, що відповідає вашому робочому процесу. ## Модель runtime - Gateway керує підключенням до Discord. -- Маршрутизація відповідей детермінована: вхідні повідомлення Discord отримують відповіді назад у Discord. -- За замовчуванням (`session.dmScope=main`) прямі чати використовують спільну головну сесію агента (`agent:main:main`). -- Канали сервера мають ізольовані ключі сесій (`agent::discord:channel:`). -- Групові приватні повідомлення за замовчуванням ігноруються (`channels.discord.dm.groupEnabled=false`). -- Нативні слеш-команди виконуються в ізольованих сесіях команд (`agent::discord:slash:`), водночас зберігаючи `CommandTargetSessionKey` для маршрутизованої сесії розмови. +- Маршрутизація відповідей детермінована: вхідні повідомлення з Discord повертаються в Discord. +- За замовчуванням (`session.dmScope=main`) прямі чати спільно використовують головну сесію агента (`agent:main:main`). +- Канали гільдії мають ізольовані ключі сесій (`agent::discord:channel:`). +- Групові особисті повідомлення типово ігноруються (`channels.discord.dm.groupEnabled=false`). +- Власні слеш-команди працюють в ізольованих сесіях команд (`agent::discord:slash:`), водночас зберігаючи `CommandTargetSessionKey` для маршрутизованої сесії розмови. ## Форумні канали @@ -300,7 +300,7 @@ openclaw message thread create --channel discord --target channel: \ ## Інтерактивні компоненти -OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із payload `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення й дотримуються наявних налаштувань Discord `replyToMode`. +OpenClaw підтримує контейнери компонентів Discord v2 для повідомлень агента. Використовуйте інструмент повідомлень із навантаженням `components`. Результати взаємодії маршрутизуються назад до агента як звичайні вхідні повідомлення та відповідають наявним налаштуванням Discord `replyToMode`. Підтримувані блоки: @@ -308,21 +308,21 @@ OpenClaw підтримує контейнери компонентів Discord - Рядки дій дозволяють до 5 кнопок або одне меню вибору - Типи вибору: `string`, `user`, `role`, `mentionable`, `channel` -За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, списків вибору та форм до закінчення строку їх дії. +За замовчуванням компоненти одноразові. Установіть `components.reusable=true`, щоб дозволити багаторазове використання кнопок, списків вибору та форм, доки не сплине строк їх дії. -Щоб обмежити, хто може натискати кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо це налаштовано, користувачі, які не відповідають умові, отримають ефемерну відмову. +Щоб обмежити, хто може натиснути кнопку, установіть `allowedUsers` для цієї кнопки (ID користувачів Discord, теги або `*`). Якщо це налаштовано, користувачі, які не відповідають умовам, отримають тимчасову відмову, видиму лише їм. -Слеш-команди `/model` і `/models` відкривають інтерактивний вибір моделі зі списками провайдера й моделі та кроком Submit. `/models add` застаріла й тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь засобу вибору є ефемерною, і лише користувач, який викликав команду, може нею користуватися. +Слеш-команди `/model` і `/models` відкривають інтерактивний засіб вибору моделі з випадаючими списками постачальника, моделі та сумісних runtime, а також із кроком Submit. `/models add` застаріла і тепер повертає повідомлення про застарілість замість реєстрації моделей із чату. Відповідь засобу вибору є тимчасовою, видимою лише користувачу, який викликав її, і лише він може нею користуватися. Вкладення файлів: - Блоки `file` мають вказувати на посилання вкладення (`attachment://`) -- Надайте вкладення через `media`/`path`/`filePath` (один файл); для кількох файлів використовуйте `media-gallery` +- Передайте вкладення через `media`/`path`/`filePath` (один файл); використовуйте `media-gallery` для кількох файлів - Використовуйте `filename`, щоб перевизначити назву завантаження, коли вона має відповідати посиланню вкладення Модальні форми: -- Додайте `components.modal` із максимум 5 полями +- Додайте `components.modal` з до 5 полями - Типи полів: `text`, `checkbox`, `radio`, `select`, `role-select`, `user-select` - OpenClaw автоматично додає кнопку запуску @@ -333,45 +333,45 @@ OpenClaw підтримує контейнери компонентів Discord channel: "discord", action: "send", to: "channel:123456789012345678", - message: "Необов’язковий резервний текст", + message: "Optional fallback text", components: { reusable: true, - text: "Виберіть шлях", + text: "Choose a path", blocks: [ { type: "actions", buttons: [ { - label: "Схвалити", + label: "Approve", style: "success", allowedUsers: ["123456789012345678"], }, - { label: "Відхилити", style: "danger" }, + { label: "Decline", style: "danger" }, ], }, { type: "actions", select: { type: "string", - placeholder: "Виберіть варіант", + placeholder: "Pick an option", options: [ - { label: "Варіант A", value: "a" }, - { label: "Варіант B", value: "b" }, + { label: "Option A", value: "a" }, + { label: "Option B", value: "b" }, ], }, }, ], modal: { - title: "Деталі", - triggerLabel: "Відкрити форму", + title: "Details", + triggerLabel: "Open form", fields: [ - { type: "text", label: "Запитувач" }, + { type: "text", label: "Requester" }, { type: "select", - label: "Пріоритет", + label: "Priority", options: [ - { label: "Низький", value: "low" }, - { label: "Високий", value: "high" }, + { label: "Low", value: "low" }, + { label: "High", value: "high" }, ], }, ], @@ -380,18 +380,18 @@ OpenClaw підтримує контейнери компонентів Discord } ``` -## Контроль доступу та маршрутизація +## Керування доступом і маршрутизація - - `channels.discord.dmPolicy` керує доступом до приватних повідомлень (застаріле: `channels.discord.dm.policy`): + + `channels.discord.dmPolicy` керує доступом до DM (застаріле: `channels.discord.dm.policy`): - - `pairing` (за замовчуванням) + - `pairing` (типово) - `allowlist` - - `open` (потрібно, щоб `channels.discord.allowFrom` містив `"*"`; застаріле: `channels.discord.dm.allowFrom`) + - `open` (потребує, щоб `channels.discord.allowFrom` містив `"*"`; застаріле: `channels.discord.dm.allowFrom`) - `disabled` - Якщо політика приватних повідомлень не є open, невідомі користувачі блокуються (або отримують запит на сполучення в режимі `pairing`). + Якщо політика DM не є open, невідомі користувачі блокуються (або отримують запит на підключення в режимі `pairing`). Пріоритет для кількох облікових записів: @@ -404,12 +404,12 @@ OpenClaw підтримує контейнери компонентів Discord - `user:` - згадка `<@id>` - Числові ID без префікса є неоднозначними й відхиляються, якщо явно не вказано тип цілі user/channel. + Числові ID без префікса неоднозначні й відхиляються, якщо явно не вказано тип цілі користувача/каналу. - - Обробка серверів керується `channels.discord.groupPolicy`: + + Обробкою гільдії керує `channels.discord.groupPolicy`: - `open` - `allowlist` @@ -419,12 +419,12 @@ OpenClaw підтримує контейнери компонентів Discord Поведінка `allowlist`: - - сервер має відповідати `channels.discord.guilds` (перевага надається `id`, slug приймається) + - гільдія має збігатися з `channels.discord.guilds` (перевага надається `id`, також приймається slug) - необов’язкові allowlist відправників: `users` (рекомендовано стабільні ID) і `roles` (лише ID ролей); якщо налаштовано будь-який із них, відправники дозволяються, коли вони збігаються з `users` АБО `roles` - - пряме зіставлення за іменем/тегом вимкнене за замовчуванням; увімкніть `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності - - імена/теги підтримуються для `users`, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи з іменами/тегами - - якщо для сервера налаштовано `channels`, канали поза списком відхиляються - - якщо для сервера немає блока `channels`, дозволяються всі канали в цьому сервері з allowlist + - пряме зіставлення за ім’ям/тегом типово вимкнене; вмикайте `channels.discord.dangerouslyAllowNameMatching: true` лише як аварійний режим сумісності + - для `users` підтримуються імена/теги, але ID безпечніші; `openclaw security audit` попереджає, коли використовуються записи імен/тегів + - якщо для гільдії налаштовано `channels`, канали, яких немає в списку, забороняються + - якщо гільдія не має блоку `channels`, дозволяються всі канали в цій гільдії з allowlist Приклад: @@ -450,33 +450,33 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Якщо ви лише встановили `DISCORD_BOT_TOKEN` і не створили блок `channels.discord`, резервне значення runtime буде `groupPolicy="allowlist"` (із попередженням у журналах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. + Якщо ви лише встановите `DISCORD_BOT_TOKEN` і не створите блок `channels.discord`, резервним значенням runtime буде `groupPolicy="allowlist"` (із попередженням у логах), навіть якщо `channels.defaults.groupPolicy` має значення `open`. - - Повідомлення на сервері за замовчуванням вимагають згадки. + + Повідомлення гільдії типово вимагають згадки. Визначення згадки включає: - явну згадку бота - - налаштовані шаблони згадки (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`) + - налаштовані шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`) - неявну поведінку відповіді боту в підтримуваних випадках - `requireMention` налаштовується для кожного сервера/каналу (`channels.discord.guilds...`). - `ignoreOtherMentions` за потреби відкидає повідомлення, які згадують іншого користувача/роль, але не бота (крім @everyone/@here). + `requireMention` налаштовується для кожної гільдії/каналу (`channels.discord.guilds...`). + `ignoreOtherMentions` за потреби відкидає повідомлення, які згадують іншого користувача/роль, але не бота (за винятком @everyone/@here). - Групові приватні повідомлення: + Групові DM: - - за замовчуванням: ігноруються (`dm.groupEnabled=false`) + - типово: ігноруються (`dm.groupEnabled=false`) - необов’язковий allowlist через `dm.groupChannels` (ID каналів або slug) -### Маршрутизація агентів на основі ролей +### Маршрутизація агента за ролями -Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників сервера Discord до різних агентів за ID ролі. Прив’язки на основі ролей приймають лише ID ролей і обчислюються після прив’язок peer або parent-peer та перед прив’язками лише для сервера. Якщо прив’язка також задає інші поля match (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. +Використовуйте `bindings[].match.roles`, щоб маршрутизувати учасників гільдії Discord до різних агентів за ID ролі. Прив’язки за ролями приймають лише ID ролей і перевіряються після прив’язок peer або parent-peer та перед прив’язками лише для гільдії. Якщо прив’язка також задає інші поля match (наприклад, `peer` + `guildId` + `roles`), усі налаштовані поля мають збігатися. ```json5 { @@ -500,51 +500,51 @@ OpenClaw підтримує контейнери компонентів Discord } ``` -## Нативні команди та авторизація команд +## Власні команди та авторизація команд -- `commands.native` за замовчуванням має значення `"auto"` і увімкнено для Discord. +- `commands.native` типово має значення `"auto"` і ввімкнене для Discord. - Перевизначення для каналу: `channels.discord.commands.native`. -- `commands.native=false` явно очищає раніше зареєстровані нативні команди Discord. -- Авторизація нативних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. -- Команди все ще можуть бути видимими в інтерфейсі Discord для користувачів, які не авторизовані; виконання все одно застосовує авторизацію OpenClaw і повертає "не авторизовано". +- `commands.native=false` явно очищає раніше зареєстровані власні команди Discord. +- Авторизація власних команд використовує ті самі allowlist/політики Discord, що й звичайна обробка повідомлень. +- Команди все ще можуть бути видимими в інтерфейсі Discord для користувачів, які не авторизовані; виконання все одно застосовує авторизацію OpenClaw і повертає "not authorized". -Див. [Слеш-команди](/uk/tools/slash-commands), щоб переглянути каталог команд і поведінку. +Див. [Слеш-команди](/uk/tools/slash-commands) для каталогу команд і поведінки. -Налаштування слеш-команд за замовчуванням: +Типові налаштування слеш-команд: - `ephemeral: true` ## Деталі функцій - + Discord підтримує теги відповіді у виводі агента: - `[[reply_to_current]]` - `[[reply_to:]]` - Керується через `channels.discord.replyToMode`: + Це керується через `channels.discord.replyToMode`: - - `off` (за замовчуванням) + - `off` (типово) - `first` - `all` - `batched` - Примітка: `off` вимикає неявне впорядкування відповідей у треді. Явні теги `[[reply_to_*]]` усе одно враховуються. - `first` завжди додає неявне посилання нативної відповіді до першого вихідного повідомлення Discord у межах ходу. - `batched` додає неявне посилання нативної відповіді Discord лише тоді, коли - вхідний хід був дебаунс-пакетом із кількох повідомлень. Це корисно, - коли нативні відповіді потрібні переважно для неоднозначних чатів зі сплесками, а не для кожного - окремого ходу з одним повідомленням. + Примітка: `off` вимикає неявне розгалуження відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються. + `first` завжди додає неявне посилання власної відповіді до першого вихідного повідомлення Discord для цього ходу. + `batched` додає неявне посилання власної відповіді Discord лише тоді, коли + вхідний хід був відкладеним пакетом із кількох повідомлень. Це корисно, + коли ви хочете використовувати власні відповіді переважно для неоднозначних + чатів зі сплесками повідомлень, а не для кожного окремого повідомлення. - ID повідомлень додаються до context/history, щоб агенти могли орієнтуватися на конкретні повідомлення. + ID повідомлень доступні в контексті/історії, тому агенти можуть націлюватися на конкретні повідомлення. - - OpenClaw може потоково передавати чернетки відповідей, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (за замовчуванням) | `partial` | `block` | `progress`. `progress` у Discord відображається як `partial`; `streamMode` є застарілим псевдонімом і автоматично мігрується. + + OpenClaw може передавати чернетки відповідей потоком, надсилаючи тимчасове повідомлення та редагуючи його в міру надходження тексту. `channels.discord.streaming` приймає `off` (типово) | `partial` | `block` | `progress`. `progress` відображається як `partial` у Discord; `streamMode` — це застарілий псевдонім, який автоматично мігрується. - За замовчуванням лишається `off`, тому що редагування попереднього перегляду в Discord швидко впирається в обмеження частоти, коли кілька ботів або Gateway спільно використовують один обліковий запис. + Типовим залишається `off`, оскільки редагування попереднього перегляду в Discord швидко впирається в обмеження частоти, коли кілька ботів або Gateway використовують спільний обліковий запис. ```json5 { @@ -562,47 +562,47 @@ OpenClaw підтримує контейнери компонентів Discord ``` - `partial` редагує одне повідомлення попереднього перегляду в міру надходження токенів. - - `block` надсилає фрагменти розміру чернетки (використовуйте `draftChunk`, щоб налаштувати розмір і точки розриву, обмежені до `textChunkLimit`). - - Підсумкові повідомлення з медіа, помилками та явними відповідями скасовують усі очікувані редагування попереднього перегляду. - - `streaming.preview.toolProgress` (за замовчуванням `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. + - `block` надсилає фрагменти розміром із чернетку (використовуйте `draftChunk` для налаштування розміру та точок розбиття, обмежених до `textChunkLimit`). + - Остаточні повідомлення з медіа, помилкою та явною відповіддю скасовують відкладені редагування попереднього перегляду. + - `streaming.preview.toolProgress` (типово `true`) керує тим, чи оновлення інструментів/прогресу повторно використовують повідомлення попереднього перегляду. - Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли явно ввімкнено потоковий режим `block`, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потокового передавання. + Потоковий попередній перегляд підтримує лише текст; відповіді з медіа повертаються до звичайної доставки. Коли потік `block` явно ввімкнено, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійного потоку. - Контекст історії сервера: + Контекст історії гільдії: - - `channels.discord.historyLimit` за замовчуванням `20` + - `channels.discord.historyLimit` типово `20` - резервне значення: `messages.groupChat.historyLimit` - `0` вимикає - Керування історією приватних повідомлень: + Керування історією DM: - `channels.discord.dmHistoryLimit` - `channels.discord.dms[""].historyLimit` Поведінка тредів: - - Треди Discord маршрутизуються як сесії каналів і успадковують конфігурацію батьківського каналу, якщо не перевизначено інше. - - `channels.discord.thread.inheritParent` (за замовчуванням `false`) дозволяє новим автотредам ініціалізуватися з батьківського транскрипту. Перевизначення для окремих облікових записів містяться в `channels.discord.accounts..thread.inheritParent`. + - Треди Discord маршрутизуються як сесії каналів і успадковують конфігурацію батьківського каналу, якщо не перевизначено інакше. + - `channels.discord.thread.inheritParent` (типово `false`) дозволяє новим автоматичним тредам початково використовувати транскрипт батьківського каналу. Перевизначення для облікових записів розташовані в `channels.discord.accounts..thread.inheritParent`. - Реакції інструмента повідомлень можуть визначати DM-цілі `user:`. - `guilds..channels..requireMention: false` зберігається під час резервної активації на етапі відповіді. - Теми каналів додаються як **ненадійний** контекст. Allowlist визначають, хто може запускати агента, але не є повноцінною межею редагування додаткового контексту. + Теми каналів додаються як **недовірений** контекст. Allowlist визначають, хто може запускати агента, але не є повноцінною межею редагування додаткового контексту. - Discord може прив’язувати тред до цілі сесії, щоб подальші повідомлення в цьому треді й надалі маршрутизувалися до тієї самої сесії (зокрема до сесій субагентів). + Discord може прив’язати тред до цілі сесії, щоб наступні повідомлення в цьому треді й далі маршрутизувалися до тієї самої сесії (включно із сесіями субагентів). Команди: - - `/focus ` прив’язати поточний/новий тред до цілі субагента/сесії - - `/unfocus` видалити поточну прив’язку треду - - `/agents` показати активні запуски та стан прив’язки - - `/session idle ` переглянути/оновити автоматичне зняття фокусу через неактивність для сфокусованих прив’язок - - `/session max-age ` переглянути/оновити жорсткий максимальний вік для сфокусованих прив’язок + - `/focus ` прив’язує поточний/новий тред до цілі субагента/сесії + - `/unfocus` видаляє поточну прив’язку треду + - `/agents` показує активні запуски та стан прив’язки + - `/session idle ` переглядає/оновлює автоматичне зняття фокуса через неактивність для сфокусованих прив’язок + - `/session max-age ` переглядає/оновлює жорсткий максимальний вік для сфокусованих прив’язок Конфігурація: @@ -621,7 +621,7 @@ OpenClaw підтримує контейнери компонентів Discord enabled: true, idleHours: 24, maxAgeHours: 0, - spawnSubagentSessions: false, // увімкнення за бажанням + spawnSubagentSessions: false, // opt-in }, }, }, @@ -630,18 +630,18 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - `session.threadBindings.*` задає глобальні значення за замовчуванням. + - `session.threadBindings.*` задає глобальні типові значення. - `channels.discord.threadBindings.*` перевизначає поведінку Discord. - `spawnSubagentSessions` має бути true, щоб автоматично створювати/прив’язувати треди для `sessions_spawn({ thread: true })`. - `spawnAcpSessions` має бути true, щоб автоматично створювати/прив’язувати треди для ACP (`/acp spawn ... --thread ...` або `sessions_spawn({ runtime: "acp", thread: true })`). - - Якщо прив’язки тредів вимкнено для облікового запису, `/focus` та пов’язані операції прив’язки тредів недоступні. + - Якщо прив’язки тредів вимкнено для облікового запису, `/focus` і пов’язані операції прив’язки тредів недоступні. - Див. [Субагенти](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Configuration Reference](/uk/gateway/configuration-reference). + Див. [Субагенти](/uk/tools/subagents), [ACP Agents](/uk/tools/acp-agents) і [Довідник із конфігурації](/uk/gateway/configuration-reference). - Для стабільних ACP-робочих просторів «always-on» налаштуйте типізовані ACP-прив’язки верхнього рівня, націлені на розмови Discord. + Для стабільних ACP-робочих просторів "always-on" налаштуйте верхньорівневі типізовані прив’язки ACP, націлені на розмови Discord. Шлях конфігурації: @@ -697,49 +697,49 @@ OpenClaw підтримує контейнери компонентів Discord Примітки: - - `/acp spawn codex --bind here` прив’язує поточний канал або тред на місці й зберігає майбутні повідомлення в тій самій ACP-сесії. Повідомлення в треді успадковують прив’язку батьківського каналу. - - У прив’язаному каналі або треді `/new` і `/reset` скидають ту саму ACP-сесію на місці. Тимчасові прив’язки тредів можуть перевизначати визначення цілі, поки вони активні. + - `/acp spawn codex --bind here` прив’язує поточний канал або тред на місці й зберігає майбутні повідомлення в тій самій сесії ACP. Повідомлення тредів успадковують прив’язку батьківського каналу. + - У прив’язаному каналі або треді `/new` і `/reset` скидають ту саму сесію ACP на місці. Тимчасові прив’язки тредів можуть перевизначати визначення цілі, поки вони активні. - `spawnAcpSessions` потрібен лише тоді, коли OpenClaw має створити/прив’язати дочірній тред через `--thread auto|here`. - Див. [ACP Agents](/uk/tools/acp-agents), щоб ознайомитися з деталями поведінки прив’язок. + Див. [ACP Agents](/uk/tools/acp-agents) для подробиць про поведінку прив’язок. - Режим сповіщень про реакції для кожного сервера: + Режим сповіщень про реакції для кожної гільдії: - `off` - - `own` (за замовчуванням) + - `own` (типово) - `all` - `allowlist` (використовує `guilds..users`) - Події реакцій перетворюються на системні події й додаються до маршрутизованої Discord-сесії. + Події реакцій перетворюються на системні події та додаються до маршрутизованої сесії Discord. - - `ackReaction` надсилає емодзі підтвердження, поки OpenClaw обробляє вхідне повідомлення. + + `ackReaction` надсилає емодзі-підтвердження, поки OpenClaw обробляє вхідне повідомлення. Порядок визначення: - `channels.discord.accounts..ackReaction` - `channels.discord.ackReaction` - `messages.ackReaction` - - резервне значення емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") + - резервний варіант емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: - - Discord приймає Unicode-емодзі або назви користувацьких емодзі. + - Discord приймає Unicode-емодзі або назви власних емодзі. - Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису. - - Записи в config, ініційовані з каналу, увімкнені за замовчуванням. + + Записи конфігурації, ініційовані з каналу, типово ввімкнені. - Це впливає на потоки `/config set|unset` (коли функції команд увімкнені). + Це впливає на процеси `/config set|unset` (коли функції команд увімкнені). - Вимкнення: + Вимкнути: ```json5 { @@ -754,7 +754,7 @@ OpenClaw підтримує контейнери компонентів Discord - Маршрутизуйте WebSocket-трафік Gateway Discord і стартові REST-запити (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. + Маршрутизуйте трафік WebSocket Gateway Discord і стартові REST-запити (ID застосунку + визначення allowlist) через HTTP(S)-проксі за допомогою `channels.discord.proxy`. ```json5 { @@ -766,7 +766,7 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Перевизначення для окремого облікового запису: + Перевизначення для облікового запису: ```json5 { @@ -793,7 +793,7 @@ OpenClaw підтримує контейнери компонентів Discord discord: { pluralkit: { enabled: true, - token: "pk_live_...", // необов’язково; потрібен для приватних систем + token: "pk_live_...", // optional; needed for private systems }, }, }, @@ -804,13 +804,13 @@ OpenClaw підтримує контейнери компонентів Discord - allowlist можуть використовувати `pk:` - відображувані імена учасників зіставляються за іменем/slug лише коли `channels.discord.dangerouslyAllowNameMatching: true` - - пошук використовує ID оригінального повідомлення й обмежується часовим вікном - - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо тільки `allowBots=true` + - пошуки використовують ID вихідного повідомлення та обмежуються часовим вікном + - якщо пошук не вдається, проксійовані повідомлення вважаються повідомленнями бота й відкидаються, якщо не встановлено `allowBots=true` - - Оновлення статусу присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичний статус присутності. + + Оновлення присутності застосовуються, коли ви задаєте поле статусу або активності, або коли вмикаєте автоматичну присутність. Приклад лише зі статусом: @@ -824,13 +824,13 @@ OpenClaw підтримує контейнери компонентів Discord } ``` - Приклад активності (користувацький статус — тип активності за замовчуванням): + Приклад активності (типовий тип активності — власний статус): ```json5 { channels: { discord: { - activity: "Час фокусування", + activity: "Focus time", activityType: 4, }, }, @@ -854,13 +854,13 @@ OpenClaw підтримує контейнери компонентів Discord Відповідність типів активності: - 0: Playing - - 1: Streaming (потрібен `activityUrl`) + - 1: Streaming (потребує `activityUrl`) - 2: Listening - 3: Watching - 4: Custom (використовує текст активності як стан статусу; емодзі необов’язкове) - 5: Competing - Приклад автоматичного статусу присутності (сигнал стану runtime): + Приклад автоматичної присутності (сигнал стану runtime): ```json5 { @@ -870,14 +870,14 @@ OpenClaw підтримує контейнери компонентів Discord enabled: true, intervalMs: 30000, minUpdateIntervalMs: 15000, - exhaustedText: "токен вичерпано", + exhaustedText: "token exhausted", }, }, }, } ``` - Автоматичний статус присутності зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: + Автоматична присутність зіставляє доступність runtime зі статусом Discord: healthy => online, degraded або unknown => idle, exhausted або unavailable => dnd. Необов’язкові перевизначення тексту: - `autoPresence.healthyText` - `autoPresence.degradedText` @@ -886,62 +886,62 @@ OpenClaw підтримує контейнери компонентів Discord - Discord підтримує обробку погоджень за допомогою кнопок у приватних повідомленнях і за бажанням може публікувати запити на погодження в каналі походження. + Discord підтримує обробку погоджень за допомогою кнопок у DM і може за потреби публікувати запити на погодження у вихідному каналі. Шлях конфігурації: - `channels.discord.execApprovals.enabled` - - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовується резервне значення `commands.ownerAllowFrom`) - - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, за замовчуванням: `dm`) + - `channels.discord.execApprovals.approvers` (необов’язково; за можливості використовує резервне значення `commands.ownerAllowFrom`) + - `channels.discord.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter`, `cleanupAfterResolve` - Discord автоматично вмикає нативні exec-погодження, коли `enabled` не задано або має значення `"auto"` і принаймні одного погоджувача можна визначити або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не визначає exec-погоджувачів із `allowFrom` каналу, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як нативний клієнт погодження. + Discord автоматично вмикає власні погодження exec, коли `enabled` не задано або дорівнює `"auto"` і можна визначити принаймні одного погоджувача — або з `execApprovals.approvers`, або з `commands.ownerAllowFrom`. Discord не визначає погоджувачів exec із канального `allowFrom`, застарілого `dm.allowFrom` або `defaultTo` для прямих повідомлень. Установіть `enabled: false`, щоб явно вимкнути Discord як власний клієнт погоджень. - Коли `target` має значення `channel` або `both`, запит на погодження видно в каналі. Лише визначені погоджувачі можуть використовувати кнопки; інші користувачі отримують ефемерну відмову. Запити на погодження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw використовує резервну доставку через DM. + Коли `target` має значення `channel` або `both`, запит на погодження видимий у каналі. Лише визначені погоджувачі можуть користуватися кнопками; інші користувачі отримують тимчасову відмову, видиму лише їм. Запити на погодження містять текст команди, тому вмикайте доставку в канал лише в довірених каналах. Якщо ID каналу неможливо вивести з ключа сесії, OpenClaw повертається до доставки через DM. - Discord також відображає спільні кнопки погодження, які використовуються іншими чат-каналами. Нативний адаптер Discord головним чином додає маршрутизацію DM для погоджувачів і fanout у канали. + Discord також відображає спільні кнопки погодження, які використовують інші чат-канали. Власний адаптер Discord головно додає маршрутизацію DM для погоджувачів і fanout у канал. Коли ці кнопки присутні, вони є основним UX погодження; OpenClaw - має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, - що погодження через чат недоступні або ручне погодження — єдиний шлях. + має включати ручну команду `/approve` лише тоді, коли результат інструмента каже, + що погодження в чаті недоступні або ручне погодження є єдиним шляхом. - Авторизація Gateway і визначення погодження відповідають спільному клієнтському контракту Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). За замовчуванням термін дії погоджень спливає через 30 хвилин. + Авторизація Gateway і визначення погодження дотримуються спільного контракту клієнта Gateway (`plugin:` ID визначаються через `plugin.approval.resolve`; інші ID — через `exec.approval.resolve`). Типовий строк дії погоджень — 30 хвилин. - Див. [Exec approvals](/uk/tools/exec-approvals). + Див. [Погодження exec](/uk/tools/exec-approvals). ## Інструменти та обмеження дій -Дії з повідомленнями Discord включають обмін повідомленнями, адміністрування каналів, модерацію, статус присутності та дії з метаданими. +Дії повідомлень Discord включають обмін повідомленнями, адміністрування каналів, модерацію, присутність і дії з метаданими. Основні приклади: - обмін повідомленнями: `sendMessage`, `readMessages`, `editMessage`, `deleteMessage`, `threadReply` - реакції: `react`, `reactions`, `emojiList` - модерація: `timeout`, `kick`, `ban` -- статус присутності: `setPresence` +- присутність: `setPresence` -Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла) для встановлення обкладинки запланованої події. +Дія `event-create` приймає необов’язковий параметр `image` (URL або шлях до локального файла), щоб установити зображення обкладинки запланованої події. Обмеження дій розташовані в `channels.discord.actions.*`. -Поведінка обмежень за замовчуванням: +Типова поведінка обмежень: -| Група дій | Значення за замовчуванням | -| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------- | -| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | увімкнено | -| roles | вимкнено | -| moderation | вимкнено | -| presence | вимкнено | +| Група дій | Типово | +| ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | +| reactions, messages, threads, pins, polls, search, memberInfo, roleInfo, channelInfo, channels, voiceStatus, events, stickers, emojiUploads, stickerUploads, permissions | ввімкнено | +| roles | вимкнено | +| moderation | вимкнено | +| presence | вимкнено | -## Інтерфейс Components v2 +## UI компонентів v2 -OpenClaw використовує Discord components v2 для exec-погоджень і маркерів між контекстами. Дії з повідомленнями Discord також можуть приймати `components` для користувацького інтерфейсу (розширено; потребує побудови payload компонентів через інструмент Discord), тоді як застарілі `embeds` залишаються доступними, але не рекомендуються. +OpenClaw використовує компоненти Discord v2 для погоджень exec і маркерів між контекстами. Дії повідомлень Discord також можуть приймати `components` для власного UI (розширено; потребує побудови навантаження компонента через інструмент discord), тоді як застарілі `embeds` і далі доступні, але не рекомендовані. -- `channels.discord.ui.components.accentColor` задає акцентний колір, який використовується контейнерами компонентів Discord (hex). -- Для окремого облікового запису задається через `channels.discord.accounts..ui.components.accentColor`. -- `embeds` ігноруються, коли присутні components v2. +- `channels.discord.ui.components.accentColor` задає акцентний колір, який використовують контейнери компонентів Discord (hex). +- Для окремого облікового запису встановлюється через `channels.discord.accounts..ui.components.accentColor`. +- `embeds` ігноруються, коли присутні компоненти v2. Приклад: @@ -961,19 +961,19 @@ OpenClaw використовує Discord components v2 для exec-погодж ## Голос -У Discord є дві окремі голосові поверхні: голосові канали realtime (**voice channels**) (безперервні розмови) і вкладення голосових повідомлень (**voice message attachments**) (формат із попереднім переглядом waveform). Gateway підтримує обидва варіанти. +У Discord є дві окремі голосові поверхні: голосові канали realtime (безперервні розмови) і вкладення голосових повідомлень (формат попереднього перегляду waveform). Gateway підтримує обидві. ### Голосові канали Вимоги: -- Увімкніть нативні команди (`commands.native` або `channels.discord.commands.native`). +- Увімкніть власні команди (`commands.native` або `channels.discord.commands.native`). - Налаштуйте `channels.discord.voice`. -- Бот потребує дозволів Connect + Speak у цільовому голосовому каналі. +- Бот має мати дозволи Connect + Speak у цільовому голосовому каналі. -Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує стандартного агента облікового запису й дотримується тих самих правил allowlist і group policy, що й інші команди Discord. +Використовуйте `/vc join|leave|status` для керування сесіями. Команда використовує типового агента облікового запису й дотримується тих самих правил allowlist і group policy, що й інші команди Discord. -Приклад автоматичного підключення: +Приклад автоматичного приєднання: ```json5 { @@ -1002,20 +1002,20 @@ OpenClaw використовує Discord components v2 для exec-погодж Примітки: - `voice.tts` перевизначає `messages.tts` лише для голосового відтворення. -- Для ходів транскрипції голосу статус власника визначається з Discord `allowFrom` (або `dm.allowFrom`); користувачі без статусу власника не можуть отримувати доступ до інструментів лише для власника (наприклад `gateway` і `cron`). -- Голос увімкнено за замовчуванням; установіть `channels.discord.voice.enabled=false`, щоб вимкнути його. -- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів підключення `@discordjs/voice`. -- Значення за замовчуванням `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. -- OpenClaw також відстежує помилки дешифрування під час прийому й автоматично відновлюється, виходячи з голосового каналу та повторно приєднуючись після повторних помилок у короткому часовому вікні. -- Якщо журнали прийому неодноразово показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути помилка прийому upstream `@discordjs/voice`, описана в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). +- Ходи транскрипції голосу визначають статус власника з Discord `allowFrom` (або `dm.allowFrom`); мовці, які не є власниками, не можуть отримувати доступ до інструментів лише для власника (наприклад, `gateway` і `cron`). +- Голос типово ввімкнений; установіть `channels.discord.voice.enabled=false`, щоб його вимкнути. +- `voice.daveEncryption` і `voice.decryptionFailureTolerance` передаються до параметрів приєднання `@discordjs/voice`. +- Типові значення `@discordjs/voice` — `daveEncryption=true` і `decryptionFailureTolerance=24`, якщо їх не задано. +- OpenClaw також відстежує помилки розшифрування під час отримання й автоматично відновлюється, виходячи та повторно приєднуючись до голосового каналу після повторних помилок за короткий проміжок часу. +- Якщо журнали отримання постійно показують `DecryptionFailed(UnencryptedWhenPassthroughDisabled)`, це може бути помилка отримання в `@discordjs/voice`, що відстежується в [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419). ### Голосові повідомлення -Голосові повідомлення Discord показують попередній перегляд waveform і вимагають аудіо OGG/Opus. OpenClaw генерує waveform автоматично, але потребує `ffmpeg` і `ffprobe` на хості Gateway для аналізу та конвертації. +Голосові повідомлення Discord показують попередній перегляд waveform і потребують аудіо OGG/Opus. OpenClaw автоматично генерує waveform, але на хості Gateway потрібні `ffmpeg` і `ffprobe` для аналізу та конвертації. -- Надайте **шлях до локального файла** (URL відхиляються). -- Не додавайте текстовий вміст (Discord відхиляє текст + голосове повідомлення в одному payload). -- Підтримується будь-який аудіоформат; OpenClaw за потреби конвертує в OGG/Opus. +- Передайте **шлях до локального файла** (URL відхиляються). +- Не додавайте текстовий вміст (Discord відхиляє одночасне надсилання тексту й голосового повідомлення). +- Підтримується будь-який формат аудіо; OpenClaw за потреби конвертує його в OGG/Opus. ```bash message(action="send", channel="discord", target="channel:123", path="/path/to/audio.mp3", asVoice=true) @@ -1024,19 +1024,19 @@ message(action="send", channel="discord", target="channel:123", path="/path/to/a ## Усунення проблем - + - увімкніть Message Content Intent - - увімкніть Server Members Intent, якщо ви покладаєтеся на визначення користувача/учасника + - увімкніть Server Members Intent, якщо ви залежите від визначення користувача/учасника - перезапустіть Gateway після зміни intents - + - перевірте `groupPolicy` - - перевірте allowlist серверів у `channels.discord.guilds` - - якщо існує мапа `channels` сервера, дозволяються лише канали зі списку + - перевірте allowlist гільдії в `channels.discord.guilds` + - якщо існує мапа `channels` гільдії, дозволені лише канали зі списку - перевірте поведінку `requireMention` і шаблони згадок Корисні перевірки: @@ -1049,12 +1049,12 @@ openclaw logs --follow - + Поширені причини: - - `groupPolicy="allowlist"` без відповідного allowlist сервера/каналу - - `requireMention` налаштовано в неправильному місці (має бути в `channels.discord.guilds` або в записі каналу) - - відправника заблоковано allowlist `users` сервера/каналу + - `groupPolicy="allowlist"` без відповідного allowlist гільдії/каналу + - `requireMention` налаштовано не в тому місці (має бути під `channels.discord.guilds` або в записі каналу) + - відправника заблоковано allowlist `users` гільдії/каналу @@ -1068,14 +1068,14 @@ openclaw logs --follow Параметр бюджету listener: - - один обліковий запис: `channels.discord.eventQueue.listenerTimeout` - - кілька облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` + - для одного облікового запису: `channels.discord.eventQueue.listenerTimeout` + - для кількох облікових записів: `channels.discord.accounts..eventQueue.listenerTimeout` Параметр тайм-ауту виконання worker: - - один обліковий запис: `channels.discord.inboundWorker.runTimeoutMs` - - кілька облікових записів: `channels.discord.accounts..inboundWorker.runTimeoutMs` - - за замовчуванням: `1800000` (30 хвилин); установіть `0`, щоб вимкнути + - для одного облікового запису: `channels.discord.inboundWorker.runTimeoutMs` + - для кількох облікових записів: `channels.discord.accounts..inboundWorker.runTimeoutMs` + - типове значення: `1800000` (30 хвилин); установіть `0`, щоб вимкнути Рекомендоване базове налаштування: @@ -1098,52 +1098,52 @@ openclaw logs --follow } ``` - Використовуйте `eventQueue.listenerTimeout` для повільного налаштування listener, а `inboundWorker.runTimeoutMs` - лише якщо вам потрібен окремий запобіжник для агентських ходів у черзі. + Використовуйте `eventQueue.listenerTimeout` для повільного налаштування listener і `inboundWorker.runTimeoutMs` + лише якщо вам потрібен окремий запобіжний механізм для поставлених у чергу ходів агента. Перевірки дозволів `channels status --probe` працюють лише для числових ID каналів. - Якщо ви використовуєте ключі slug, зіставлення в runtime все одно може працювати, але probe не може повністю перевірити дозволи. + Якщо ви використовуєте ключі slug, зіставлення під час runtime усе ще може працювати, але probe не може повністю перевірити дозволи. - + - - приватні повідомлення вимкнено: `channels.discord.dm.enabled=false` - - політику приватних повідомлень вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) - - очікується схвалення сполучення в режимі `pairing` + - DM вимкнено: `channels.discord.dm.enabled=false` + - політику DM вимкнено: `channels.discord.dmPolicy="disabled"` (застаріле: `channels.discord.dm.policy`) + - очікується підтвердження підключення в режимі `pairing` - За замовчуванням повідомлення, створені ботами, ігноруються. + Типово повідомлення, створені ботами, ігноруються. - Якщо ви встановлюєте `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. - Надавайте перевагу `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення ботів, які згадують бота. + Якщо ви встановили `channels.discord.allowBots=true`, використовуйте суворі правила згадок і allowlist, щоб уникнути циклічної поведінки. + Краще використовувати `channels.discord.allowBots="mentions"`, щоб приймати лише повідомлення від ботів, які згадують бота. - + - - підтримуйте актуальну версію OpenClaw (`openclaw update`), щоб логіка відновлення отримання голосу Discord була доступна - - підтвердьте `channels.discord.voice.daveEncryption=true` (за замовчуванням) - - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (значення upstream за замовчуванням) і змінюйте лише за потреби + - підтримуйте актуальну версію OpenClaw (`openclaw update`), щоб логіка відновлення отримання голосу Discord була наявна + - підтвердьте `channels.discord.voice.daveEncryption=true` (типово) + - починайте з `channels.discord.voice.decryptionFailureTolerance=24` (типове значення upstream) і налаштовуйте лише за потреби - стежте за журналами: - `discord voice: DAVE decrypt failures detected` - `discord voice: repeated decrypt failures; attempting rejoin` - - якщо помилки тривають після автоматичного повторного підключення, зберіть журнали й порівняйте з [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) + - якщо збої тривають після автоматичного повторного приєднання, зберіть журнали та порівняйте з [discord.js #11419](https://github.com/discordjs/discord.js/issues/11419) -## Довідник конфігурації +## Довідник із конфігурації -Основний довідник: [Configuration reference - Discord](/uk/gateway/config-channels#discord). +Основне посилання: [Довідник із конфігурації - Discord](/uk/gateway/config-channels#discord). - + - запуск/автентифікація: `enabled`, `token`, `accounts.*`, `allowBots` - політика: `groupPolicy`, `dm.*`, `guilds.*`, `guilds.*.channels.*` @@ -1152,26 +1152,26 @@ openclaw logs --follow - вхідний worker: `inboundWorker.runTimeoutMs` - відповідь/історія: `replyToMode`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` - доставка: `textChunkLimit`, `chunkMode`, `maxLinesPerMessage` -- потокове передавання: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` -- медіа/повторні спроби: `mediaMaxMb` (обмежує вихідні завантаження Discord, за замовчуванням `100MB`), `retry` +- потокова передача: `streaming` (застарілий псевдонім: `streamMode`), `streaming.preview.toolProgress`, `draftChunk`, `blockStreaming`, `blockStreamingCoalesce` +- медіа/повторні спроби: `mediaMaxMb` (обмежує вихідні завантаження Discord, типово `100MB`), `retry` - дії: `actions.*` -- статус присутності: `activity`, `status`, `activityType`, `activityUrl` +- присутність: `activity`, `status`, `activityType`, `activityUrl` - UI: `ui.components.accentColor` -- функції: `threadBindings`, верхньорівневий `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` +- функції: `threadBindings`, верхньорівневі `bindings[]` (`type: "acp"`), `pluralkit`, `execApprovals`, `intents`, `agentComponents`, `heartbeat`, `responsePrefix` -## Безпека та експлуатація +## Безпека й експлуатація -- Розглядайте токени ботів як секрети (у контрольованих середовищах бажано використовувати `DISCORD_BOT_TOKEN`). -- Надавайте дозволи Discord за принципом найменших привілеїв. -- Якщо розгортання/стан команд застарів, перезапустіть Gateway і повторно перевірте за допомогою `openclaw channels status --probe`. +- Розглядайте токени ботів як секрети (у керованих середовищах перевага надається `DISCORD_BOT_TOKEN`). +- Надавайте Discord мінімально необхідні дозволи. +- Якщо розгортання/стан команд застаріли, перезапустіть Gateway і повторно перевірте через `openclaw channels status --probe`. ## Пов’язане - - Сполучіть користувача Discord із Gateway. + + Підключіть користувача Discord до Gateway. Поведінка групового чату та allowlist. @@ -1183,9 +1183,9 @@ openclaw logs --follow Модель загроз і посилення захисту. - Зіставляйте сервери та канали з агентами. + Зіставляйте гільдії та канали з агентами. - Поведінка нативних команд. + Поведінка власних команд. diff --git a/docs/uk/channels/slack.md b/docs/uk/channels/slack.md index f8d59a4fb..0bf1a4b5c 100644 --- a/docs/uk/channels/slack.md +++ b/docs/uk/channels/slack.md @@ -1,41 +1,41 @@ --- read_when: - - Налаштування Slack або налагодження режиму сокета/HTTP у Slack + - Налаштування Slack або налагодження режиму socket/HTTP у Slack summary: Налаштування Slack і поведінка під час виконання (Socket Mode + URL-адреси HTTP-запитів) title: Slack x-i18n: - generated_at: "2026-04-24T23:30:39Z" + generated_at: "2026-04-25T00:01:09Z" model: gpt-5.4 provider: openai - source_hash: d0ab5b0865102175477bacac2ef948cdb2e42892fdfd5adb73afe89f0f482de5 + source_hash: d8d177cad1e795ecccf31cff486b9c8036bf91b22d122e8afbd9cfaf7635e4ea source_path: channels/slack.md workflow: 15 --- -Готово до production для особистих повідомлень і каналів через інтеграції застосунку Slack. Режим за замовчуванням — Socket Mode; також підтримуються URL-адреси HTTP-запитів. +Готово до використання в продакшені для особистих повідомлень і каналів через інтеграції застосунку Slack. Типовий режим — Socket Mode; також підтримуються URL-адреси HTTP-запитів. - - Для особистих повідомлень Slack режим прив’язки використовується за замовчуванням. + + Особисті повідомлення Slack типово працюють у режимі підключення. - Вбудована поведінка команд і каталог команд. + Нативна поведінка команд і каталог команд. - - Міжканальна діагностика та інструкції з відновлення. + + Міжканальна діагностика та сценарії відновлення. ## Швидке налаштування - + У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: - виберіть **from a manifest** і виберіть робочий простір для свого застосунку - - вставте [приклад маніфесту](#manifest-and-scope-checklist) нижче та продовжте створення + - вставте [приклад manifest](#manifest-and-scope-checklist) нижче та продовжте створення - згенеруйте **App-Level Token** (`xapp-...`) з `connections:write` - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) @@ -55,7 +55,7 @@ x-i18n: } ``` - Резервний варіант через змінні середовища (лише для облікового запису за замовчуванням): + Резервний варіант через змінні середовища (лише для типового облікового запису): ```bash SLACK_APP_TOKEN=xapp-... @@ -81,7 +81,7 @@ openclaw gateway У налаштуваннях застосунку Slack натисніть кнопку **[Create New App](https://api.slack.com/apps/new)**: - виберіть **from a manifest** і виберіть робочий простір для свого застосунку - - вставте [приклад маніфесту](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням + - вставте [приклад manifest](#manifest-and-scope-checklist) і оновіть URL-адреси перед створенням - збережіть **Signing Secret** для перевірки запитів - встановіть застосунок і скопіюйте показаний **Bot Token** (`xoxb-...`) @@ -104,9 +104,9 @@ openclaw gateway ``` - Використовуйте унікальні шляхи Webhook для багатокористувацького HTTP + Використовуйте унікальні шляхи Webhook для багатьох облікових записів HTTP - Для кожного облікового запису задавайте окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували. + Надайте кожному обліковому запису окремий `webhookPath` (типово `/slack/events`), щоб реєстрації не конфліктували. @@ -123,11 +123,11 @@ openclaw gateway -## Контрольний список маніфесту та scope +## Контрольний список manifest і scope -Базовий маніфест застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` слеш-команди). +Базовий manifest застосунку Slack однаковий для Socket Mode і URL-адрес HTTP-запитів. Відрізняється лише блок `settings` (і `url` для слеш-команди). -Базовий маніфест (Socket Mode за замовчуванням): +Базовий manifest (Socket Mode типово): ```json { @@ -229,14 +229,14 @@ openclaw gateway } ``` -### Додаткові налаштування маніфесту +### Додаткові параметри manifest -Описано різні можливості, які розширюють наведені вище значення за замовчуванням. +Показують різні можливості, що розширюють наведені вище типові значення. - + - Можна використовувати кілька [вбудованих слеш-команд](#commands-and-slash-behavior) замість однієї налаштованої команди, з такими нюансами: + Кілька [нативних слеш-команд](#commands-and-slash-behavior) можна використовувати замість однієї налаштованої команди з певними нюансами: - Використовуйте `/agentstatus` замість `/status`, оскільки команда `/status` зарезервована. - Одночасно можна зробити доступними не більше 25 слеш-команд. @@ -244,7 +244,7 @@ openclaw gateway Замініть наявний розділ `features.slash_commands` на підмножину [доступних команд](/uk/tools/slash-commands#command-list): - + ```json "slash_commands": [ @@ -385,11 +385,11 @@ openclaw gateway - Додайте bot scope `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували активну ідентичність агента (власні ім’я користувача та іконку) замість типової ідентичності застосунку Slack. + Додайте bot scope `chat:write.customize`, якщо хочете, щоб вихідні повідомлення використовували ідентичність активного агента (власні ім’я користувача та значок) замість типової ідентичності застосунку Slack. - Якщо ви використовуєте іконку emoji, Slack очікує синтаксис `:emoji_name:`. + Якщо ви використовуєте значок emoji, Slack очікує синтаксис `:emoji_name:`. - + Якщо ви налаштовуєте `channels.slack.userToken`, типовими scope читання є: - `channels:history`, `groups:history`, `im:history`, `mpim:history` @@ -398,7 +398,7 @@ openclaw gateway - `reactions:read` - `pins:read` - `emoji:read` - - `search:read` (якщо ви покладаєтеся на читання через пошук Slack) + - `search:read` (якщо ви покладаєтесь на читання через пошук Slack) @@ -406,43 +406,43 @@ openclaw gateway ## Модель токенів - Для Socket Mode потрібні `botToken` + `appToken`. -- Для HTTP mode потрібні `botToken` + `signingSecret`. -- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні текстові +- Для режиму HTTP потрібні `botToken` + `signingSecret`. +- `botToken`, `appToken`, `signingSecret` і `userToken` приймають звичайні рядки або об’єкти SecretRef. -- Токени в конфігурації мають пріоритет над резервними значеннями зі змінних середовища. -- Резервне значення зі змінних середовища `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до облікового запису за замовчуванням. -- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного значення через змінні середовища) і за замовчуванням працює лише для читання (`userTokenReadOnly: true`). +- Токени в конфігурації мають пріоритет над резервним варіантом через env. +- Резервний варіант через env `SLACK_BOT_TOKEN` / `SLACK_APP_TOKEN` застосовується лише до типового облікового запису. +- `userToken` (`xoxp-...`) доступний лише в конфігурації (без резервного варіанту через env) і типово працює лише для читання (`userTokenReadOnly: true`). Поведінка знімка стану: -- Перевірка облікового запису Slack відстежує для кожних облікових даних поля - `*Source` і `*Status` (`botToken`, `appToken`, `signingSecret`, `userToken`). -- Статус може бути `available`, `configured_unavailable` або `missing`. -- `configured_unavailable` означає, що обліковий запис налаштовано через SecretRef - або інше не вбудоване джерело секретів, але поточний шлях команди/виконання +- Перевірка облікового запису Slack відстежує поля `*Source` і `*Status` + для кожних облікових даних (`botToken`, `appToken`, `signingSecret`, `userToken`). +- Статус має значення `available`, `configured_unavailable` або `missing`. +- `configured_unavailable` означає, що обліковий запис налаштований через SecretRef + або інше неinline-джерело секрету, але поточний шлях команди/виконання не зміг визначити фактичне значення. -- У HTTP mode включається `signingSecretStatus`; у Socket Mode - потрібна пара — `botTokenStatus` + `appTokenStatus`. +- У режимі HTTP включається `signingSecretStatus`; у Socket Mode + потрібною парою є `botTokenStatus` + `appTokenStatus`. -Для дій/читання каталогів може надаватися перевага токену користувача, якщо його налаштовано. Для запису перевага все одно надається bot token; запис через user token дозволений лише коли `userTokenReadOnly: false`, а bot token недоступний. +Для дій/читання каталогів user token може мати пріоритет, якщо його налаштовано. Для запису пріоритетним залишається bot token; запис через user token дозволений лише коли `userTokenReadOnly: false`, а bot token недоступний. ## Дії та обмеження Дії Slack керуються через `channels.slack.actions.*`. -Доступні групи дій у поточному інструментарії Slack: +Доступні групи дій у поточному наборі інструментів Slack: | Група | Типово | | ---------- | ------- | -| messages | enabled | -| reactions | enabled | -| pins | enabled | -| memberInfo | enabled | -| emojiList | enabled | +| messages | увімкнено | +| reactions | увімкнено | +| pins | увімкнено | +| memberInfo | увімкнено | +| emojiList | увімкнено | -Поточні дії для повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. +Поточні дії для повідомлень Slack включають `send`, `upload-file`, `download-file`, `read`, `edit`, `delete`, `pin`, `unpin`, `list-pins`, `member-info` і `emoji-list`. `download-file` приймає ідентифікатори файлів Slack, показані у вхідних заповнювачах файлів, і повертає попередній перегляд зображень для зображень або метадані локального файла для інших типів файлів. ## Керування доступом і маршрутизація @@ -452,7 +452,7 @@ openclaw gateway - `pairing` (типово) - `allowlist` - - `open` (потребує, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`) + - `open` (потрібно, щоб `channels.slack.allowFrom` містив `"*"`; застаріле: `channels.slack.dm.allowFrom`) - `disabled` Прапорці DM: @@ -460,7 +460,7 @@ openclaw gateway - `dm.enabled` (типово true) - `channels.slack.allowFrom` (рекомендовано) - `dm.allowFrom` (застаріле) - - `dm.groupEnabled` (для групових DM типово false) + - `dm.groupEnabled` (групові DM типово false) - `dm.groupChannels` (необов’язковий allowlist MPIM) Пріоритет для кількох облікових записів: @@ -469,37 +469,37 @@ openclaw gateway - Іменовані облікові записи успадковують `channels.slack.allowFrom`, якщо їхній власний `allowFrom` не задано. - Іменовані облікові записи не успадковують `channels.slack.accounts.default.allowFrom`. - Прив’язка в DM використовує `openclaw pairing approve slack `. + Підключення в DM використовує `openclaw pairing approve slack `. - + `channels.slack.groupPolicy` керує обробкою каналів: - `open` - `allowlist` - `disabled` - Allowlist каналів знаходиться в `channels.slack.channels` і має використовувати стабільні ID каналів. + Allowlist каналів розміщується в `channels.slack.channels` і має використовувати стабільні ідентифікатори каналів. - Примітка щодо runtime: якщо `channels.slack` повністю відсутній (налаштування лише через env), runtime використовує резервне значення `groupPolicy="allowlist"` і записує попередження в журнал (навіть якщо задано `channels.defaults.groupPolicy`). + Примітка щодо виконання: якщо `channels.slack` повністю відсутній (налаштування лише через env), під час виконання використовується резервне значення `groupPolicy="allowlist"` і записується попередження в журнал (навіть якщо задано `channels.defaults.groupPolicy`). - Визначення імен/ID: + Визначення імені/ідентифікатора: - - записи allowlist каналів і DM allowlist визначаються під час запуску, якщо доступ токена це дозволяє - - нерозпізнані записи назв каналів зберігаються як налаштовано, але типово ігноруються під час маршрутизації - - авторизація вхідних повідомлень і маршрутизація каналів типово працюють за принципом ID-first; пряме зіставлення імен користувачів/slug потребує `channels.slack.dangerouslyAllowNameMatching: true` + - записи allowlist каналів і записи allowlist DM визначаються під час запуску, якщо доступ токена це дозволяє + - нерозв’язані записи назв каналів зберігаються як налаштовані, але типово ігноруються для маршрутизації + - вхідна авторизація та маршрутизація каналів типово виконуються за ідентифікатором; пряме зіставлення імені користувача/slug вимагає `channels.slack.dangerouslyAllowNameMatching: true` - - Повідомлення в каналах типово проходять через обмеження за згадками. + + Повідомлення в каналах типово обмежуються згадками. Джерела згадок: - явна згадка застосунку (`<@botId>`) - - шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`) - - неявна поведінка reply-to-bot у тредах (вимикається, коли `thread.requireExplicitMention` має значення `true`) + - шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) + - неявна поведінка відповіді в гілці для бота (вимикається, коли `thread.requireExplicitMention` дорівнює `true`) Керування для кожного каналу (`channels.slack.channels.`; імена лише через визначення під час запуску або `dangerouslyAllowNameMatching`): @@ -510,35 +510,35 @@ openclaw gateway - `systemPrompt` - `tools`, `toolsBySender` - формат ключа `toolsBySender`: `id:`, `e164:`, `username:`, `name:` або wildcard `"*"` - (застарілі ключі без префікса, як і раніше, зіставляються лише з `id:`) + (застарілі ключі без префікса все ще зіставляються лише з `id:`) -## Треди, сесії та теги відповіді +## Гілки, сесії та теги відповідей - DM маршрутизуються як `direct`; канали — як `channel`; MPIM — як `group`. -- Із типовим `session.dmScope=main` DM у Slack згортаються в основну сесію агента. +- Із типовим `session.dmScope=main` DM у Slack згортаються до основної сесії агента. - Сесії каналів: `agent::slack:channel:`. -- Відповіді в тредах можуть створювати суфікси сесій тредів (`:thread:`), коли це застосовно. -- Типове значення `channels.slack.thread.historyScope` — `thread`; типове значення `thread.inheritParent` — `false`. -- `channels.slack.thread.initialHistoryLimit` визначає, скільки наявних повідомлень треду буде отримано, коли починається нова сесія треду (типово `20`; встановіть `0`, щоб вимкнути). -- `channels.slack.thread.requireExplicitMention` (типово `false`): коли має значення `true`, неявні згадки в тредах пригнічуються, і бот відповідає лише на явні згадки `@bot` усередині тредів, навіть якщо бот уже брав участь у треді. Без цього відповіді в треді за участю бота обходять обмеження `requireMention`. +- Відповіді в гілках можуть створювати суфікси сесій гілок (`:thread:`), коли це застосовно. +- `channels.slack.thread.historyScope` типово має значення `thread`; `thread.inheritParent` типово має значення `false`. +- `channels.slack.thread.initialHistoryLimit` визначає, скільки наявних повідомлень гілки отримується під час запуску нової сесії гілки (типово `20`; установіть `0`, щоб вимкнути). +- `channels.slack.thread.requireExplicitMention` (типово `false`): коли має значення `true`, пригнічує неявні згадки в гілках, тому бот відповідає лише на явні згадки `@bot` усередині гілок, навіть якщо бот уже брав участь у гілці. Без цього відповіді в гілці, у якій брав участь бот, оминають обмеження `requireMention`. -Керування тредами відповідей: +Елементи керування гілками відповідей: - `channels.slack.replyToMode`: `off|first|all|batched` (типово `off`) -- `channels.slack.replyToModeByChatType`: для `direct|group|channel` -- застаріле резервне значення для прямих чатів: `channels.slack.dm.replyToMode` +- `channels.slack.replyToModeByChatType`: для кожного `direct|group|channel` +- застарілий резервний варіант для прямих чатів: `channels.slack.dm.replyToMode` -Підтримуються ручні теги відповіді: +Підтримуються ручні теги відповідей: - `[[reply_to_current]]` - `[[reply_to:]]` -Примітка: `replyToMode="off"` вимикає **усі** треди відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"` — треди Slack приховують повідомлення з каналу, тоді як відповіді Telegram залишаються видимими вбудовано. +Примітка: `replyToMode="off"` вимикає **усі** гілки відповідей у Slack, включно з явними тегами `[[reply_to_*]]`. Це відрізняється від Telegram, де явні теги все ще враховуються в режимі `"off"` — у Slack гілки приховують повідомлення з каналу, тоді як відповіді в Telegram залишаються видимими вбудовано. -## Реакції-підтвердження +## Реакції підтвердження `ackReaction` надсилає emoji-підтвердження, поки OpenClaw обробляє вхідне повідомлення. @@ -547,7 +547,7 @@ openclaw gateway - `channels.slack.accounts..ackReaction` - `channels.slack.ackReaction` - `messages.ackReaction` -- резервне значення emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") +- резервний emoji ідентичності агента (`agents.list[].identity.emoji`, інакше "👀") Примітки: @@ -556,22 +556,22 @@ openclaw gateway ## Потокова передача тексту -`channels.slack.streaming` керує поведінкою live preview: +`channels.slack.streaming` керує поведінкою попереднього перегляду в реальному часі: -- `off`: вимкнути потокову live preview. -- `partial` (типово): замінювати текст попереднього перегляду останнім частковим виводом. -- `block`: додавати оновлення попереднього перегляду частинами. +- `off`: вимкнути потоковий попередній перегляд у реальному часі. +- `partial` (типово): замінювати текст попереднього перегляду найновішим частковим виводом. +- `block`: додавати порційні оновлення попереднього перегляду. - `progress`: показувати текст стану прогресу під час генерації, а потім надсилати фінальний текст. -- `streaming.preview.toolProgress`: коли чернетковий попередній перегляд активний, спрямовувати оновлення інструментів/прогресу в те саме редаговане повідомлення попереднього перегляду (типово: `true`). Встановіть `false`, щоб залишити окремі повідомлення інструментів/прогресу. +- `streaming.preview.toolProgress`: коли активний чернетковий попередній перегляд, спрямовувати оновлення інструментів/прогресу в те саме відредаговане повідомлення попереднього перегляду (типово: `true`). Установіть `false`, щоб зберегти окремі повідомлення інструментів/прогресу. -`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` має значення `partial` (типово: `true`). +`channels.slack.streaming.nativeTransport` керує нативною потоковою передачею тексту Slack, коли `channels.slack.streaming.mode` дорівнює `partial` (типово: `true`). -- Для нативної потокової передачі тексту та появи статусу треду Slack assistant має бути доступний тред відповіді. Вибір треду, як і раніше, підпорядковується `replyToMode`. -- Корені каналів і групових чатів усе ще можуть використовувати звичайний чернетковий попередній перегляд, коли нативна потокова передача недоступна. -- DM верхнього рівня в Slack типово залишаються поза тредами, тому не показують попередній перегляд у стилі треду; використовуйте відповіді в тредах або `typingReaction`, якщо там потрібен видимий прогрес. -- Для медіа та нетекстових payload використовується звичайне доставлення. -- Фінальні повідомлення media/error скасовують відкладені редагування попереднього перегляду; придатні фінальні повідомлення text/block скидаються лише тоді, коли можуть відредагувати попередній перегляд на місці. -- Якщо потокова передача зламається посеред відповіді, OpenClaw переходить на звичайне доставлення для решти payload. +- Для нативної потокової передачі тексту та відображення статусу гілки помічника Slack має бути доступна гілка відповіді. Вибір гілки все одно підпорядковується `replyToMode`. +- Кореневі повідомлення каналів і групових чатів усе ще можуть використовувати звичайний чернетковий попередній перегляд, коли нативна потокова передача недоступна. +- DM верхнього рівня в Slack типово залишаються поза гілками, тому не показують попередній перегляд у стилі гілки; використовуйте відповіді в гілках або `typingReaction`, якщо хочете видимий прогрес там. +- Для медіа й нетекстових корисних навантажень використовується звичайна доставка. +- Фінальні медіа/помилки скасовують відкладені редагування попереднього перегляду; придатні фінальні текстові/блокові відповіді скидаються лише тоді, коли можуть відредагувати попередній перегляд на місці. +- Якщо потокова передача збоїть посеред відповіді, OpenClaw повертається до звичайної доставки для решти корисних навантажень. Використовуйте чернетковий попередній перегляд замість нативної потокової передачі тексту Slack: @@ -590,13 +590,13 @@ openclaw gateway Застарілі ключі: -- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрує до `channels.slack.streaming.mode`. -- булеве значення `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. +- `channels.slack.streamMode` (`replace | status_final | append`) автоматично мігрується до `channels.slack.streaming.mode`. +- булеве `channels.slack.streaming` автоматично мігрує до `channels.slack.streaming.mode` і `channels.slack.streaming.nativeTransport`. - застаріле `channels.slack.nativeStreaming` автоматично мігрує до `channels.slack.streaming.nativeTransport`. ## Резервна реакція набору тексту -`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення виконання. Це найкорисніше поза відповідями в тредах, де використовується типовий індикатор стану "is typing...". +`typingReaction` додає тимчасову реакцію до вхідного повідомлення Slack, поки OpenClaw обробляє відповідь, а потім видаляє її після завершення виконання. Це найбільш корисно поза відповідями в гілках, які використовують типовий індикатор стану "is typing...". Порядок визначення: @@ -606,26 +606,26 @@ openclaw gateway Примітки: - Slack очікує shortcodes (наприклад, `"hourglass_flowing_sand"`). -- Реакція виконується за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або шляху помилки. +- Реакція надсилається за принципом best-effort, а очищення автоматично намагається виконатися після завершення відповіді або сценарію помилки. -## Медіа, розбиття на частини та доставлення +## Медіа, розбиття на частини та доставка - Файлові вкладення Slack завантажуються з приватних URL-адрес, розміщених у Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, якщо отримання успішне та дозволяють обмеження розміру. + Вкладення файлів Slack завантажуються з приватних URL-адрес, що хостяться Slack (потік запитів з автентифікацією токеном), і записуються до сховища медіа, якщо отримання успішне та дозволяють обмеження розміру. Заповнювачі файлів включають Slack `fileId`, щоб агенти могли отримати оригінальний файл через `download-file`. - Типове обмеження розміру вхідних даних у runtime — `20MB`, якщо не перевизначено через `channels.slack.mediaMaxMb`. + Типове обмеження розміру вхідних даних під час виконання — `20MB`, якщо не перевизначено через `channels.slack.mediaMaxMb`. - - текстові частини використовують `channels.slack.textChunkLimit` (типово 4000) + - частини тексту використовують `channels.slack.textChunkLimit` (типово 4000) - `channels.slack.chunkMode="newline"` вмикає розбиття спочатку за абзацами - - надсилання файлів використовує API завантаження Slack і може включати відповіді в тредах (`thread_ts`) - - обмеження вихідних медіа дотримується `channels.slack.mediaMaxMb`, якщо його налаштовано; інакше надсилання в канал використовують типові значення MIME-kind із медіапайплайна + - надсилання файлів використовує API завантаження Slack і може включати відповіді в гілках (`thread_ts`) + - обмеження вихідних медіа підпорядковується `channels.slack.mediaMaxMb`, якщо налаштовано; інакше для надсилання в канали використовуються типові MIME-kind з медіаконвеєра - + Бажані явні цілі: - `user:` для DM @@ -638,7 +638,7 @@ openclaw gateway ## Команди та поведінка слеш-команд -Слеш-команди відображаються в Slack або як одна налаштована команда, або як кілька вбудованих команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команди: +Слеш-команди з’являються в Slack або як одна налаштована команда, або як кілька нативних команд. Налаштуйте `channels.slack.slashCommand`, щоб змінити типові параметри команди: - `enabled: false` - `name: "openclaw"` @@ -649,30 +649,30 @@ openclaw gateway /openclaw /help ``` -Вбудовані команди потребують [додаткових налаштувань маніфесту](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях. +Нативні команди потребують [додаткових параметрів manifest](#additional-manifest-settings) у вашому застосунку Slack і вмикаються через `channels.slack.commands.native: true` або `commands.native: true` у глобальних конфігураціях. -- Режим auto для вбудованих команд у Slack **вимкнений**, тому `commands.native: "auto"` не вмикає вбудовані команди Slack. +- Автоматичний режим нативних команд для Slack **вимкнено**, тому `commands.native: "auto"` не вмикає нативні команди Slack. ```txt /help ``` -Меню аргументів вбудованих команд використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед відправленням значення вибраного параметра: +Нативні меню аргументів використовують адаптивну стратегію рендерингу, яка показує модальне вікно підтвердження перед надсиланням вибраного значення параметра: -- до 5 параметрів: button blocks -- 6-100 параметрів: static select menu -- понад 100 параметрів: external select з асинхронною фільтрацією параметрів, якщо доступні обробники параметрів interactivity -- перевищено ліміти Slack: закодовані значення параметрів повертаються до buttons +- до 5 варіантів: блоки кнопок +- 6-100 варіантів: статичне меню вибору +- більше 100 варіантів: зовнішній вибір з асинхронною фільтрацією варіантів, якщо доступні обробники параметрів інтерактивності +- перевищено обмеження Slack: закодовані значення варіантів резервно переходять до кнопок ```txt /think ``` -Сесії слеш-команд використовують ізольовані ключі на кшталт `agent::slack:slash:` і все одно маршрутизують виконання команд до цільової сесії розмови через `CommandTargetSessionKey`. +Сесії слеш-команд використовують ізольовані ключі, такі як `agent::slack:slash:`, і все ще маршрутизують виконання команд до сесії цільової розмови за допомогою `CommandTargetSessionKey`. ## Інтерактивні відповіді -Slack може рендерити інтерактивні елементи відповіді, створені агентом, але ця можливість типово вимкнена. +Slack може відображати інтерактивні елементи керування відповідями, створеними агентом, але ця можливість типово вимкнена. Увімкніть її глобально: @@ -688,7 +688,7 @@ Slack може рендерити інтерактивні елементи ві } ``` -Або увімкніть її лише для одного облікового запису Slack: +Або увімкніть лише для одного облікового запису Slack: ```json5 { @@ -706,43 +706,44 @@ Slack може рендерити інтерактивні елементи ві } ``` -Коли її ввімкнено, агенти можуть надсилати директиви відповіді лише для Slack: +Коли функцію ввімкнено, агенти можуть виводити директиви відповідей лише для Slack: - `[[slack_buttons: Approve:approve, Reject:reject]]` - `[[slack_select: Choose a target | Canary:canary, Production:production]]` -Ці директиви компілюються в Slack Block Kit і маршрутизують натискання або вибір назад через наявний шлях подій взаємодії Slack. +Ці директиви компілюються в Slack Block Kit і спрямовують натискання або вибори назад через наявний шлях подій взаємодії Slack. Примітки: - Це UI, специфічний для Slack. Інші канали не перекладають директиви Slack Block Kit у власні системи кнопок. -- Значення інтерактивних callback — це непрозорі токени, згенеровані OpenClaw, а не сирі значення, створені агентом. -- Якщо згенеровані інтерактивні блоки перевищують ліміти Slack Block Kit, OpenClaw повертається до початкової текстової відповіді замість надсилання невалідного payload blocks. +- Значення інтерактивного callback — це непрозорі токени, згенеровані OpenClaw, а не необроблені значення, створені агентом. +- Якщо згенеровані інтерактивні блоки перевищують обмеження Slack Block Kit, OpenClaw резервно повертається до початкової текстової відповіді замість надсилання некоректного payload блоків. -## Погодження exec у Slack +## Підтвердження exec у Slack -Slack може працювати як нативний клієнт погодження з інтерактивними кнопками та взаємодіями замість переходу до Web UI або термінала. +Slack може діяти як нативний клієнт підтвердження з інтерактивними кнопками та взаємодіями, замість резервного переходу до Web UI або термінала. -- Погодження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналів. -- Погодження Plugin, як і раніше, можуть визначатися через ту саму Slack-native поверхню кнопок, коли запит уже надходить у Slack, а тип id погодження — `plugin:`. -- Авторизація того, хто погоджує, як і раніше, примусово перевіряється: лише користувачі, ідентифіковані як ті, хто погоджує, можуть погоджувати або відхиляти запити через Slack. +- Підтвердження exec використовують `channels.slack.execApprovals.*` для нативної маршрутизації DM/каналів. +- Підтвердження Plugin також можуть визначатися через ту саму нативну поверхню кнопок Slack, коли запит уже надходить у Slack, а тип ідентифікатора підтвердження — `plugin:`. +- Авторизація того, хто підтверджує, усе ще примусово застосовується: лише користувачі, визначені як ті, хто підтверджує, можуть схвалювати або відхиляти запити через Slack. -Це використовує ту саму спільну поверхню кнопок погодження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на погодження відображаються як кнопки Block Kit безпосередньо в розмові. -Коли ці кнопки присутні, вони є основним UX погодження; OpenClaw -має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що погодження в чаті недоступні або ручне погодження — єдиний шлях. +Це використовує ту саму спільну поверхню кнопок підтвердження, що й інші канали. Коли `interactivity` увімкнено в налаштуваннях вашого застосунку Slack, запити на підтвердження відображаються як кнопки Block Kit безпосередньо в розмові. +Коли ці кнопки присутні, вони є основним UX підтвердження; OpenClaw +має включати ручну команду `/approve` лише тоді, коли результат інструмента вказує, що підтвердження в чаті недоступні +або ручне підтвердження є єдиним шляхом. Шлях конфігурації: - `channels.slack.execApprovals.enabled` -- `channels.slack.execApprovals.approvers` (необов’язково; за можливості використовує резервне значення `commands.ownerAllowFrom`) +- `channels.slack.execApprovals.approvers` (необов’язково; за можливості використовує резервне значення з `commands.ownerAllowFrom`) - `channels.slack.execApprovals.target` (`dm` | `channel` | `both`, типово: `dm`) - `agentFilter`, `sessionFilter` -Slack автоматично вмикає нативні погодження exec, коли `enabled` не задано або має значення `"auto"` і визначається принаймні один користувач, що погоджує. -Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт погодження. -Установіть `enabled: true`, щоб примусово ввімкнути нативні погодження, коли визначаються користувачі, що погоджують. +Slack автоматично вмикає нативні підтвердження exec, коли `enabled` не задано або має значення `"auto"` і визначається принаймні один +користувач, що підтверджує. Установіть `enabled: false`, щоб явно вимкнути Slack як нативний клієнт підтвердження. +Установіть `enabled: true`, щоб примусово ввімкнути нативні підтвердження, коли визначаються користувачі, що підтверджують. -Типова поведінка без явної конфігурації погодження exec для Slack: +Типова поведінка без явної конфігурації підтвердження exec для Slack: ```json5 { @@ -752,8 +753,8 @@ Slack автоматично вмикає нативні погодження ex } ``` -Явна Slack-native конфігурація потрібна лише тоді, коли ви хочете перевизначити користувачів, що погоджують, додати фільтри або -використовувати доставлення до чату-джерела: +Явна нативна конфігурація Slack потрібна лише тоді, коли ви хочете перевизначити користувачів, що підтверджують, додати фільтри або +вибрати доставку до початкового чату: ```json5 { @@ -769,38 +770,38 @@ Slack автоматично вмикає нативні погодження ex } ``` -Спільне переспрямування `approvals.exec` налаштовується окремо. Використовуйте його лише тоді, коли запити на погодження exec також мають -маршрутизуватися до інших чатів або явно заданих зовнішніх цілей. Спільне переспрямування `approvals.plugin` також -налаштовується окремо; Slack-native кнопки все одно можуть обробляти погодження Plugin, коли ці запити вже надходять +Пересилання спільних `approvals.exec` є окремим. Використовуйте його лише тоді, коли запити на підтвердження exec також мають +маршрутизуватися в інші чати або явні позасмугові цілі. Пересилання спільних `approvals.plugin` також є +окремим; нативні кнопки Slack усе ще можуть визначати підтвердження Plugin, коли ці запити вже надходять у Slack. -`/approve` у тому самому чаті також працює в каналах і DM Slack, які вже підтримують команди. Повну модель переспрямування погоджень див. у [Погодження exec](/uk/tools/exec-approvals). +`/approve` у тому ж чаті також працює в каналах і DM Slack, які вже підтримують команди. Повну модель пересилання підтверджень див. у [Підтвердження exec](/uk/tools/exec-approvals). ## Події та операційна поведінка - Редагування/видалення повідомлень зіставляються із системними подіями. -- Thread broadcasts (відповіді в тредах з опцією "Also send to channel") обробляються як звичайні повідомлення користувачів. +- Розсилки з гілок ("Also send to channel" для відповідей у гілках) обробляються як звичайні повідомлення користувача. - Події додавання/видалення реакцій зіставляються із системними подіями. - Події входу/виходу учасників, створення/перейменування каналів і додавання/видалення закріплень зіставляються із системними подіями. -- `channel_id_changed` може мігрувати ключі конфігурації каналів, коли ввімкнено `configWrites`. -- Метадані теми/призначення каналу вважаються недовіреним контекстом і можуть впроваджуватися в контекст маршрутизації. -- Ініціатор треду та початкове наповнення контексту історією треду фільтруються за налаштованими allowlist відправників, де це застосовно. -- Дії блоків і взаємодії з модальними вікнами створюють структуровані системні події `Slack interaction: ...` з насиченими полями payload: - - дії блоків: вибрані значення, мітки, значення picker і метадані `workflow_*` - - події модальних вікон `view_submission` і `view_closed` з метаданими маршрутизованого каналу та полями форм +- `channel_id_changed` може мігрувати ключі конфігурації каналу, коли ввімкнено `configWrites`. +- Метадані topic/purpose каналу вважаються недовіреним контекстом і можуть бути вставлені в контекст маршрутизації. +- Початкове повідомлення гілки та початкове заповнення контексту історії гілки фільтруються за налаштованими allowlist відправників, коли це застосовно. +- Дії блоків і взаємодії з модальними вікнами генерують структуровані системні події `Slack interaction: ...` з розширеними полями payload: + - дії блоків: вибрані значення, мітки, значення вибору та метадані `workflow_*` + - події модальних вікон `view_submission` і `view_closed` з маршрутизованими метаданими каналу та введеними даними форми ## Довідник конфігурації -Основний довідник: [Довідник конфігурації - Slack](/uk/gateway/config-channels#slack). +Основне посилання: [Довідник конфігурації - Slack](/uk/gateway/config-channels#slack). - + - mode/auth: `mode`, `botToken`, `appToken`, `signingSecret`, `webhookPath`, `accounts.*` - доступ до DM: `dm.enabled`, `dmPolicy`, `allowFrom` (застаріле: `dm.policy`, `dm.allowFrom`), `dm.groupEnabled`, `dm.groupChannels` -- перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний режим; залишайте вимкненим, якщо немає потреби) +- перемикач сумісності: `dangerouslyAllowNameMatching` (аварійний варіант; залишайте вимкненим, якщо не потрібно) - доступ до каналів: `groupPolicy`, `channels.*`, `channels.*.users`, `channels.*.requireMention` -- треди/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` -- доставлення: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` +- гілки/історія: `replyToMode`, `replyToModeByChatType`, `thread.*`, `historyLimit`, `dmHistoryLimit`, `dms.*.historyLimit` +- доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `streaming`, `streaming.nativeTransport`, `streaming.preview.toolProgress` - операції/можливості: `configWrites`, `commands.native`, `slashCommand.*`, `actions.*`, `userToken`, `userTokenReadOnly` @@ -809,7 +810,7 @@ Slack автоматично вмикає нативні погодження ex - Перевірте по черзі: + Перевірте по порядку: - `groupPolicy` - allowlist каналів (`channels.slack.channels`) @@ -831,10 +832,10 @@ openclaw doctor - `channels.slack.dm.enabled` - `channels.slack.dmPolicy` (або застаріле `channels.slack.dm.policy`) - - погодження прив’язки / записи allowlist - - події Slack Assistant DM: докладні журнали з фразою `drop message_changed` - зазвичай означають, що Slack надіслав подію редагування треду Assistant без - придатного для відновлення відправника-людини в метаданих повідомлення + - підтвердження підключення / записи allowlist + - події DM Slack Assistant: докладні журнали з `drop message_changed` + зазвичай означають, що Slack надіслав подію відредагованої гілки Assistant без + людського відправника, якого можна відновити, у метаданих повідомлення ```bash openclaw pairing list slack @@ -842,34 +843,34 @@ openclaw pairing list slack - - Перевірте bot token + app token і те, що Socket Mode увімкнено в налаштуваннях застосунку Slack. + + Перевірте bot token + app token і ввімкнення Socket Mode в налаштуваннях застосунку Slack. Якщо `openclaw channels status --probe --json` показує `botTokenStatus` або `appTokenStatus: "configured_unavailable"`, обліковий запис Slack - налаштовано, але поточний runtime не зміг визначити значення, - що надходить через SecretRef. + налаштований, але поточне середовище виконання не змогло визначити значення, + що походить із SecretRef. - + Перевірте: - signing secret - шлях webhook - - Slack Request URLs (Events + Interactivity + Slash Commands) - - унікальний `webhookPath` для кожного HTTP-облікового запису + - URL-адреси запитів Slack (Events + Interactivity + Slash Commands) + - унікальний `webhookPath` для кожного облікового запису HTTP - Якщо в знімках облікового запису з’являється `signingSecretStatus: "configured_unavailable"`, - HTTP-обліковий запис налаштовано, але поточний runtime не зміг - визначити signing secret, що надходить через SecretRef. + Якщо `signingSecretStatus: "configured_unavailable"` з’являється у знімках + облікового запису, обліковий запис HTTP налаштований, але поточне середовище виконання не змогло + визначити signing secret, що походить із SecretRef. - - Перевірте, що саме ви хотіли використати: + + Перевірте, що саме ви мали на увазі: - - режим вбудованих команд (`channels.slack.commands.native: true`) з відповідними слеш-командами, зареєстрованими в Slack + - режим нативних команд (`channels.slack.commands.native: true`) з відповідними слеш-командами, зареєстрованими в Slack - або режим однієї слеш-команди (`channels.slack.slashCommand.enabled: true`) Також перевірте `commands.useAccessGroups` і allowlist каналів/користувачів. @@ -880,8 +881,8 @@ openclaw pairing list slack ## Пов’язане - - Прив’яжіть користувача Slack до Gateway. + + Підключити користувача Slack до Gateway. Поведінка каналів і групових DM. @@ -893,7 +894,7 @@ openclaw pairing list slack Модель загроз і посилення захисту. - Структура конфігурації та пріоритетність. + Структура конфігурації та пріоритети. Каталог команд і поведінка. diff --git a/docs/uk/ci.md b/docs/uk/ci.md index 423d69e81..8e2a1bb30 100644 --- a/docs/uk/ci.md +++ b/docs/uk/ci.md @@ -1,60 +1,27 @@ --- read_when: - - Потрібно зрозуміти, чому завдання CI запустилося або не запустилося - - Ви налагоджуєте збої в перевірках GitHub Actions -summary: Граф завдань CI, межі перевірок і локальні еквіваленти команд -title: конвеєр CI + - Вам потрібно зрозуміти, чому завдання CI запустилося або не запустилося + - Ви налагоджуєте збої перевірок GitHub Actions +summary: Граф завдань CI, обмеження за областю змін і локальні еквіваленти команд +title: Конвеєр CI x-i18n: - generated_at: "2026-04-24T22:51:37Z" + generated_at: "2026-04-25T00:01:09Z" model: gpt-5.4 provider: openai - source_hash: bfcd687e6555b15ddebe3c061a814911d4f8a49c0db1c42aff357976a82bbbd5 + source_hash: 03105fd06cf6a913ef0fb8cbe84c64ed89edbc09652f347b4508552a2f33bb71 source_path: ci.md workflow: 15 --- -CI запускається для кожного push до `main` і для кожного pull request. Він використовує розумне визначення області змін, щоб пропускати дорогі завдання, коли змінено лише не пов’язані ділянки. +CI запускається для кожного push до `main` і кожного pull request. Він використовує розумне обмеження за областю змін, щоб пропускати дорогі завдання, коли змінено лише не пов’язані частини. -QA Lab має окремі смуги CI поза основним workflow з розумним визначенням області змін. Workflow -`Parity gate` запускається для відповідних змін у PR і через ручний запуск; він -збирає приватне середовище виконання QA та порівнює agentic pack-и mock GPT-5.4 і Opus 4.6. -Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через -ручний запуск; він розгалужує mock parity gate, live Matrix lane і live -Telegram lane як паралельні завдання. Live-завдання використовують середовище -`qa-live-shared`, а Telegram lane використовує оренди Convex. `OpenClaw Release -Checks` також запускає ті самі смуги QA Lab перед погодженням релізу. +QA Lab має окремі доріжки CI поза основним workflow з розумним обмеженням за областю змін. Workflow `Parity gate` запускається для відповідних змін у PR і через manual dispatch; він збирає приватне середовище виконання QA і порівнює agentic packs mock GPT-5.4 та Opus 4.6. Workflow `QA-Lab - All Lanes` запускається щоночі на `main` і через manual dispatch; він розгалужує mock parity gate, live Matrix lane і live Telegram lane як паралельні завдання. Live-завдання використовують середовище `qa-live-shared`, а доріжка Telegram використовує Convex leases. `OpenClaw Release Checks` також запускає ті самі доріжки QA Lab перед затвердженням релізу. -Workflow `Duplicate PRs After Merge` — це ручний workflow для мейнтейнерів для -очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і -закриває лише явно перелічені PR, коли `apply=true`. Перед внесенням змін у GitHub -він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільну -пов’язану issue, або перетин змінених фрагментів. +Workflow `Duplicate PRs After Merge` — це ручний workflow для супровідників, призначений для очищення дублікатів після злиття. За замовчуванням він працює в режимі dry-run і закриває лише явно перелічені PR, коли `apply=true`. Перед внесенням змін у GitHub він перевіряє, що злитий PR справді об’єднано, і що кожен дублікат має або спільну пов’язану issue, або перетин змінених hunk-ів. -Workflow `Docs Agent` — це maintenance lane Codex на основі подій для підтримання -наявної документації у відповідності до нещодавно злитих змін. Він не має окремого запуску за розкладом: -його може запустити успішний CI run не-бота для push у `main`, а також він може -запускатися безпосередньо вручну. Запуски через workflow-run пропускаються, якщо -`main` уже пішов уперед або якщо інший непропущений запуск Docs Agent був створений -протягом останньої години. Коли він запускається, він переглядає діапазон комітів -від вихідного SHA попереднього непропущеного Docs Agent до поточного `main`, -тож один щогодинний запуск може охопити всі зміни в main, накопичені з часу -останнього проходу документації. +Workflow `Docs Agent` — це подієва доріжка обслуговування Codex для підтримання наявної документації у відповідності до нещодавно злитих змін. Він не має чистого розкладу: його може запустити успішний неблокований push CI на `main`, а manual dispatch може запускати його безпосередньо. Виклики через workflow-run пропускаються, якщо `main` уже пішла вперед або якщо інший непропущений запуск Docs Agent було створено протягом останньої години. Коли він запускається, то переглядає діапазон комітів від попереднього вихідного SHA непропущеного Docs Agent до поточної `main`, тож один щогодинний запуск може охопити всі зміни в main, накопичені з часу останнього проходу документації. -Workflow `Test Performance Agent` — це maintenance lane Codex на основі подій -для повільних тестів. Він не має окремого запуску за розкладом: його може запустити -успішний CI run не-бота для push у `main`, але він пропускається, якщо інший запуск -через workflow-run уже виконався або виконується в ту саму добу UTC. Ручний запуск -обходить це добове обмеження активності. Lane будує згрупований звіт продуктивності -Vitest для повного набору тестів, дозволяє Codex вносити лише невеликі зміни -продуктивності тестів зі збереженням покриття замість широких рефакторингів, потім -повторно запускає звіт для повного набору й відхиляє зміни, які зменшують базову -кількість успішних тестів. Якщо в базі є тести, що падають, Codex може виправляти -лише очевидні збої, і звіт повного набору після роботи агента має пройти повністю, -перш ніж щось буде закомічено. Коли `main` просувається вперед до того, як bot push -буде застосовано, lane перебазовує перевірений патч, повторно запускає -`pnpm check:changed` і повторює спробу push; конфліктні застарілі патчі пропускаються. -Він використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму -безпечну модель без `sudo`, що й docs agent. +Workflow `Test Performance Agent` — це подієва доріжка обслуговування Codex для повільних тестів. Він не має чистого розкладу: його може запустити успішний неблокований push CI на `main`, але він пропускається, якщо інший виклик через workflow-run уже виконався або виконується того ж дня за UTC. Manual dispatch обходить цю добову перевірку активності. Доріжка будує звіт продуктивності Vitest для повного набору тестів із групуванням, дозволяє Codex вносити лише невеликі правки продуктивності тестів без зниження покриття замість широких рефакторингів, потім повторно запускає звіт для повного набору й відхиляє зміни, що зменшують кількість тестів базової лінії, які проходять. Якщо в базовій лінії є тести зі збоями, Codex може виправляти лише очевидні проблеми, а підсумковий звіт для повного набору після роботи агента має пройти повністю, перш ніж щось буде закомічено. Коли `main` просувається вперед до того, як bot push буде злитий, доріжка перебазовує перевірений патч, повторно запускає `pnpm check:changed` і повторює push; конфліктні застарілі патчі пропускаються. Вона використовує GitHub-hosted Ubuntu, щоб дія Codex могла зберігати ту саму безпечну політику drop-sudo, що й docs agent. ```bash gh workflow run duplicate-after-merge.yml \ @@ -65,84 +32,84 @@ gh workflow run duplicate-after-merge.yml \ ## Огляд завдань -| Завдання | Призначення | Коли запускається | -| -------------------------------- | -------------------------------------------------------------------------------------------- | ----------------------------------- | -| `preflight` | Визначення змін лише в документації, змінених областей, змінених extensions і побудова маніфесту CI | Завжди для non-draft push і PR | -| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для non-draft push і PR | -| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для non-draft push і PR | -| `security-fast` | Обов’язковий агрегатор для швидких завдань безпеки | Завжди для non-draft push і PR | -| `build-artifacts` | Збірка `dist/`, Control UI, перевірки built-artifact і повторно використовувані downstream artifacts | Зміни, пов’язані з Node | -| `checks-fast-core` | Швидкі Linux-смуги коректності, такі як перевірки bundled/plugin-contract/protocol | Зміни, пов’язані з Node | -| `checks-fast-contracts-channels` | Розбиті на шарди перевірки channel contract зі стабільним агрегованим результатом перевірки | Зміни, пов’язані з Node | -| `checks-node-extensions` | Повні шарди тестів bundled-plugin для всього набору extension | Зміни, пов’язані з Node | -| `checks-node-core-test` | Шарди основних Node-тестів, за винятком channel, bundled, contract і extension lanes | Зміни, пов’язані з Node | -| `extension-fast` | Цільові тести лише для змінених bundled plugins | Pull request із змінами в extension | -| `check` | Еквівалент основної локальної перевірки, розбитої на шарди: prod types, lint, guards, test types і strict smoke | Зміни, пов’язані з Node | -| `check-additional` | Шарди архітектурних, boundary, extension-surface, package-boundary і gateway-watch перевірок | Зміни, пов’язані з Node | -| `build-smoke` | Smoke-тести built-CLI і smoke-тест пам’яті під час запуску | Зміни, пов’язані з Node | -| `checks` | Верифікатор для built-artifact channel tests плюс сумісність Node 22 лише для push | Зміни, пов’язані з Node | -| `check-docs` | Форматування документації, lint і перевірки зламаних посилань | Змінено документацію | -| `skills-python` | Ruff + pytest для Skills на Python | Зміни, пов’язані з Python Skills | -| `checks-windows` | Windows-специфічні тестові смуги | Зміни, пов’язані з Windows | -| `macos-node` | Смуга тестів TypeScript на macOS з використанням спільних built artifacts | Зміни, пов’язані з macOS | -| `macos-swift` | Lint, збірка і тести Swift для застосунку macOS | Зміни, пов’язані з macOS | -| `android` | Android unit-тести для обох flavor плюс одна debug APK збірка | Зміни, пов’язані з Android | -| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успішний Main CI або ручний запуск | +| Завдання | Призначення | Коли запускається | +| -------------------------------- | -------------------------------------------------------------------------------------------- | ------------------------------------ | +| `preflight` | Виявлення змін лише в документації, змінених областей, змінених extensions і побудова маніфесту CI | Завжди для недрафтових push і PR | +| `security-scm-fast` | Виявлення приватних ключів і аудит workflow через `zizmor` | Завжди для недрафтових push і PR | +| `security-dependency-audit` | Аудит production lockfile без залежностей щодо advisory npm | Завжди для недрафтових push і PR | +| `security-fast` | Обов’язковий агрегат для швидких завдань безпеки | Завжди для недрафтових push і PR | +| `build-artifacts` | Збірка `dist/`, Control UI, перевірки зібраних артефактів і багаторазово використовувані downstream-артефакти | Зміни, пов’язані з Node | +| `checks-fast-core` | Швидкі Linux-доріжки перевірки коректності, як-от bundled/plugin-contract/protocol checks | Зміни, пов’язані з Node | +| `checks-fast-contracts-channels` | Шардовані перевірки контрактів каналів зі стабільним агрегованим результатом перевірки | Зміни, пов’язані з Node | +| `checks-node-extensions` | Шардовані тести повного набору bundled-plugin для всього набору extensions | Зміни, пов’язані з Node | +| `checks-node-core-test` | Шарди базових Node-тестів, без доріжок channel, bundled, contract і extension | Зміни, пов’язані з Node | +| `extension-fast` | Сфокусовані тести лише для змінених bundled plugins | Pull request із змінами в extensions | +| `check` | Шардований еквівалент основного локального gate: production types, lint, guards, test types і strict smoke | Зміни, пов’язані з Node | +| `check-additional` | Архітектура, перевірки меж, extension-surface guards, package-boundary і шардовані gateway-watch | Зміни, пов’язані з Node | +| `build-smoke` | Smoke-тести зібраного CLI і smoke-тест використання пам’яті під час запуску | Зміни, пов’язані з Node | +| `checks` | Верифікатор для тестів каналів на зібраних артефактах плюс сумісність Node 22 лише для push | Зміни, пов’язані з Node | +| `check-docs` | Форматування документації, lint і перевірки битих посилань | Якщо змінено документацію | +| `skills-python` | Ruff + pytest для Skills на базі Python | Зміни, пов’язані з Python Skills | +| `checks-windows` | Специфічні для Windows доріжки тестування | Зміни, пов’язані з Windows | +| `macos-node` | Доріжка тестів TypeScript на macOS із використанням спільних зібраних артефактів | Зміни, пов’язані з macOS | +| `macos-swift` | Swift lint, збірка і тести для застосунку macOS | Зміни, пов’язані з macOS | +| `android` | Модульні тести Android для обох flavor плюс одна збірка debug APK | Зміни, пов’язані з Android | +| `test-performance-agent` | Щоденна оптимізація повільних тестів Codex після довіреної активності | Успіх CI в main або manual dispatch | ## Порядок Fail-Fast -Завдання впорядковані так, щоб дешеві перевірки падали раніше, ніж запустяться дорогі: +Завдання впорядковано так, щоб дешеві перевірки завершувалися з помилкою раніше, ніж запустяться дорогі: -1. `preflight` вирішує, які смуги взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. -2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` швидко падають, не чекаючи важчих матричних завдань для артефактів і платформ. -3. `build-artifacts` виконується паралельно зі швидкими Linux-смугами, щоб downstream-споживачі могли стартувати щойно буде готова спільна збірка. -4. Після цього розгалужуються важчі платформні смуги й смуги виконання: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. +1. `preflight` визначає, які доріжки взагалі існують. Логіка `docs-scope` і `changed-scope` — це кроки всередині цього завдання, а не окремі завдання. +2. `security-scm-fast`, `security-dependency-audit`, `security-fast`, `check`, `check-additional`, `check-docs` і `skills-python` завершуються швидко, не чекаючи важчих завдань артефактів і платформних матриць. +3. `build-artifacts` виконується паралельно зі швидкими Linux-доріжками, щоб downstream-споживачі могли почати роботу, щойно спільна збірка буде готова. +4. Після цього розгалужуються важчі платформні та runtime-доріжки: `checks-fast-core`, `checks-fast-contracts-channels`, `checks-node-extensions`, `checks-node-core-test`, лише для PR `extension-fast`, `checks`, `checks-windows`, `macos-node`, `macos-swift` і `android`. -Логіка визначення області змін знаходиться в `scripts/ci-changed-scope.mjs` і покривається unit-тестами в `src/scripts/ci-changed-scope.test.ts`. -Зміни у workflow CI перевіряють граф Node CI і lint workflow, але самі по собі не примушують запускати native-збірки Windows, Android або macOS; ці платформні смуги й далі залежать лише від змін у коді відповідних платформ. -Перевірки Windows Node обмежені Windows-специфічними wrappers для process/path, допоміжними засобами npm/pnpm/UI runner, конфігурацією package manager і поверхнями workflow CI, які запускають цю смугу; не пов’язані зміни у коді, plugins, install-smoke і лише тестах залишаються на Linux Node lanes, щоб не резервувати Windows worker із 16 vCPU для покриття, яке вже забезпечується звичайними test shards. -Окремий workflow `install-smoke` повторно використовує той самий скрипт визначення області змін через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest bundled plugin і поверхонь core plugin/channel/gateway/Plugin SDK, які перевіряються Docker smoke jobs. Зміни лише у вихідному коді bundled plugin, лише в тестах і лише в документації не резервують Docker workers. Швидкий шлях один раз збирає root Dockerfile image, перевіряє CLI, запускає container gateway-network e2e, перевіряє аргумент збірки bundled extension і запускає обмежений профіль Docker для bundled-plugin із тайм-аутом команди 120 секунд. Повний шлях зберігає покриття встановлення QR package і installer Docker/update для нічних запусків за розкладом, ручних запусків, workflow-call release checks і pull request, які справді торкаються поверхонь installer/package/Docker. Push у `main`, включно з merge commits, не примушують повний шлях; коли логіка changed-scope вимагала б повне покриття для push, workflow зберігає швидкий Docker smoke і залишає повний install smoke для нічної або релізної перевірки. Повільний smoke для Bun global install image-provider додатково захищається прапорцем `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а ручні запуски `install-smoke` можуть явно його ввімкнути, але pull request і push у `main` його не запускають. Тести QR і installer Docker мають власні Dockerfile, зосереджені на встановленні. Локальний агрегат `test:docker:all` попередньо збирає один спільний live-test image і один built-app image `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lanes із ваговим планувальником і `OPENCLAW_SKIP_DOCKER_BUILD=1`; налаштовуйте типову кількість слотів основного пулу — 10 — через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів tail-пулу, чутливого до provider, — 10 — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження важких смуг за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`, щоб смуги npm install і multi-service не перевантажували Docker, поки легші смуги все ще використовують доступні слоти. Запуски смуг за замовчуванням розносяться на 2 секунди, щоб уникати локальних штормів створення контейнерів Docker; перевизначте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегат перед стартом перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних смуг, зберігає таймінги смуг для впорядкування за принципом найдовші спочатку й підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перевірки планувальника. За замовчуванням він припиняє планувати нові pooled lanes після першої помилки, а кожна смуга має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; вибрані live/tail lanes використовують жорсткіші індивідуальні обмеження. Повторно використовуваний workflow live/E2E віддзеркалює шаблон спільного image: він збирає і публікує один GHCR Docker E2E image з тегом SHA перед Docker matrix, а потім запускає матрицю з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Workflow scheduled live/E2E щодня запускає повний Docker suite за релізним сценарієм. Матрицю bundled update поділено за ціллю оновлення, щоб повторні проходи npm update і doctor repair можна було шардувати разом з іншими bundled checks. +Логіка обмеження за областю змін міститься в `scripts/ci-changed-scope.mjs` і покривається модульними тестами в `src/scripts/ci-changed-scope.test.ts`. +Зміни workflow CI перевіряють граф Node CI і lint workflow, але самі по собі не примушують виконувати нативні збірки для Windows, Android або macOS; ці платформні доріжки й надалі обмежуються змінами у вихідному коді відповідних платформ. +Перевірки Windows Node обмежені специфічними для Windows process/path wrappers, npm/pnpm/UI runner helpers, конфігурацією package manager і поверхнями workflow CI, які запускають цю доріжку; не пов’язані зміни у вихідному коді, plugins, install-smoke і зміни лише в тестах залишаються на Linux Node lanes, щоб не резервувати 16-vCPU Windows worker для покриття, яке вже перевіряється звичайними шардованими тестами. +Окремий workflow `install-smoke` повторно використовує той самий скрипт обмеження за областю через власне завдання `preflight`. Він розділяє smoke-покриття на `run_fast_install_smoke` і `run_full_install_smoke`. Pull request запускають швидкий шлях для поверхонь Docker/package, змін package/manifest у bundled plugins і поверхонь core plugin/channel/gateway/Plugin SDK, які використовують завдання Docker smoke. Зміни лише у вихідному коді bundled plugins, зміни лише в тестах і зміни лише в документації не резервують Docker workers. Швидкий шлях один раз збирає образ кореневого Dockerfile, перевіряє CLI, запускає container gateway-network e2e, перевіряє build arg для bundled extension і запускає обмежений Docker-профіль bundled-plugin з тайм-аутом команди 120 секунд. Повний шлях зберігає покриття QR package install і installer Docker/update для нічних запусків за розкладом, manual dispatch, workflow-call release checks і pull request, які справді зачіпають поверхні installer/package/Docker. Push у `main`, включно з merge commits, не примушують виконувати повний шлях; коли логіка changed-scope намагалася б запросити повне покриття для push, workflow залишає швидкий Docker smoke, а повний install smoke — для нічної або релізної валідації. Повільний smoke для глобальної інсталяції Bun image-provider окремо керується через `run_bun_global_install_smoke`; він запускається за нічним розкладом і з workflow release checks, а manual dispatch `install-smoke` може явно його ввімкнути, але pull request і push до `main` його не запускають. Тести QR і installer Docker зберігають власні Dockerfile, орієнтовані на встановлення. Локальний агрегат `test:docker:all` попередньо збирає один спільний live-test image і один спільний built-app image з `scripts/e2e/Dockerfile`, а потім запускає live/E2E smoke lanes зі зваженим планувальником і `OPENCLAW_SKIP_DOCKER_BUILD=1`; стандартну кількість слотів основного пулу, рівну 10, можна налаштувати через `OPENCLAW_DOCKER_ALL_PARALLELISM`, а кількість слотів tail-пулу, чутливого до provider, теж рівну 10 — через `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM`. Обмеження для важких доріжок за замовчуванням дорівнюють `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`, щоб доріжки npm install і multi-service не перевантажували Docker, поки легші доріжки все ще заповнюють доступні слоти. Запуски доріжок за замовчуванням зсуваються на 2 секунди, щоб уникнути локальних сплесків create-операцій Docker daemon; це можна змінити через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=0` або інше значення в мілісекундах. Локальний агрегат попередньо перевіряє Docker, видаляє застарілі контейнери OpenClaw E2E, виводить статус активних доріжок, зберігає таймінги доріжок для впорядкування за принципом longest-first і підтримує `OPENCLAW_DOCKER_ALL_DRY_RUN=1` для перегляду роботи планувальника. За замовчуванням він припиняє планувати нові об’єднані доріжки після першої помилки, і кожна доріжка має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; для окремих live/tail-доріжок використовуються жорсткіші індивідуальні обмеження. Багаторазово використовуваний workflow live/E2E віддзеркалює шаблон спільного image, збираючи й публікуючи один SHA-позначений GHCR Docker E2E image перед Docker matrix, а потім запускаючи matrix з `OPENCLAW_SKIP_DOCKER_BUILD=1`. Запланований workflow live/E2E щодня запускає повний Docker-набір за релізним шляхом. Матриця bundled update розділена за ціллю оновлення, щоб повторювані проходи npm update і doctor repair могли шардитися разом з іншими bundled checks. -Локальна логіка changed-lane знаходиться в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Ця локальна перевірка суворіше ставиться до архітектурних меж, ніж широка платформна область CI: зміни core production запускають typecheck для core prod плюс тести core, зміни лише в core tests запускають лише typecheck/tests для core tests, зміни extension production запускають typecheck для extension prod плюс тести extension, а зміни лише в extension tests запускають лише typecheck/tests для extension tests. Зміни в публічному Plugin SDK або plugin-contract розширюють перевірку на extensions, оскільки extensions залежать від цих core-контрактів. Підвищення версії лише в метаданих релізу запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config безпечно переводять перевірку на всі смуги. +Локальна логіка changed-lane міститься в `scripts/changed-lanes.mjs` і виконується через `scripts/check-changed.mjs`. Цей локальний gate суворіше ставиться до архітектурних меж, ніж широка платформна область CI: зміни в production-частині core запускають typecheck production core плюс тести core, зміни лише в тестах core запускають лише typecheck/tests для тестів core, зміни в production-частині extension запускають typecheck production extension плюс тести extension, а зміни лише в тестах extension запускають лише typecheck/tests для тестів extension. Зміни в публічному Plugin SDK або plugin-contract розширюють валідацію до extensions, оскільки extensions залежать від цих core-контрактів. Підвищення версії лише в release metadata запускають цільові перевірки version/config/root-dependency. Невідомі зміни в root/config за принципом fail-safe запускають усі доріжки. -Для push матриця `checks` додає lane `compat-node22`, який запускається лише для push. Для pull request цей lane пропускається, і матриця залишається зосередженою на звичайних test/channel lanes. +Для push матриця `checks` додає доріжку `compat-node22`, яка запускається лише для push. Для pull request цю доріжку пропускають, і матриця зосереджується на звичайних доріжках test/channel. -Найповільніші сімейства Node-тестів розділені або збалансовані так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: channel contracts запускаються як три зважені шарди, тести bundled plugin балансуються між шістьма extension worker-ами, невеликі core unit lanes поєднуються попарно, auto-reply працює на трьох збалансованих worker-ах замість шести дрібних worker-ів, а agentic gateway/plugin configs розподіляються між наявними source-only agentic Node jobs замість очікування built artifacts. Широкі тести browser, QA, media і miscellaneous plugin використовують свої окремі конфігурації Vitest замість спільного універсального набору plugin. Завдання extension shard запускають до двох груп конфігурацій plugin одночасно з одним worker-ом Vitest на групу та більшим heap Node, щоб import-інтенсивні пакети plugin не створювали зайві завдання CI. Широка agents lane використовує спільний планувальник файлового паралелізму Vitest, оскільки тут домінують import/планування, а не один окремий повільний test file. `runtime-config` запускається разом із shard `infra core-runtime`, щоб спільний shard runtime не володів хвостом. `check-additional` тримає разом package-boundary compile/canary роботу і відокремлює архітектуру runtime topology від покриття gateway watch; shard boundary guard запускає свої малі незалежні guards паралельно всередині одного завдання. Gateway watch, channel tests і shard core support-boundary запускаються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі імена перевірок як легкі завдання-верифікатори, водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. -Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його lane unit-тестів усе одно компілює цей flavor з прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK для кожного Android-релевантного push. -`extension-fast` є лише для PR, оскільки push-запуски вже виконують повні шарди bundled plugin. Це дає швидкий зворотний зв’язок щодо змінених plugin для рев’ю, не резервуючи додатковий Blacksmith worker у `main` для покриття, яке вже присутнє в `checks-node-extensions`. +Найповільніші сімейства Node-тестів розділено або збалансовано так, щоб кожне завдання залишалося невеликим без надмірного резервування runner-ів: контракти каналів виконуються як три зважені shard-и, тести bundled plugin розподіляються між шістьма worker-ами extensions, невеликі core unit lanes поєднуються в пари, auto-reply виконується трьома збалансованими worker-ами замість шести дрібних worker-ів, а agentic gateway/plugin configs розподіляються між наявними source-only agentic Node jobs замість очікування зібраних артефактів. Широкі browser-, QA-, media- і miscellaneous plugin-тести використовують свої спеціалізовані конфігурації Vitest замість спільного універсального набору plugin-тестів. Завдання shard-ів extension запускають до двох груп конфігурацій plugin одночасно з одним worker-ом Vitest на групу і збільшеним heap Node, щоб пакети plugin-ів із великим обсягом імпортів не створювали додаткових завдань CI. Широка доріжка agents використовує спільний file-parallel scheduler Vitest, оскільки для неї домінують імпорти/планування, а не один окремий повільний тестовий файл. `runtime-config` виконується разом із shard-ом infra core-runtime, щоб спільний runtime-shard не залишався найдовшим у хвості. `check-additional` тримає разом package-boundary compile/canary-роботи й відокремлює runtime topology architecture від покриття gateway watch; shard boundary guard паралельно запускає свої невеликі незалежні guards усередині одного завдання. Gateway watch, тести каналів і shard меж підтримки core виконуються паралельно всередині `build-artifacts` після того, як `dist/` і `dist-runtime/` уже зібрані, зберігаючи свої старі назви перевірок як легкі завдання-верифікатори й водночас уникаючи двох додаткових Blacksmith worker-ів і другої черги споживачів артефактів. +Android CI запускає і `testPlayDebugUnitTest`, і `testThirdPartyDebugUnitTest`, а потім збирає Play debug APK. Flavor third-party не має окремого source set або manifest; його доріжка unit-тестів усе одно компілює цей flavor із прапорцями BuildConfig для SMS/call-log, водночас уникаючи дубльованого завдання пакування debug APK для кожного push, що стосується Android. +`extension-fast` призначено лише для PR, тому що push-запуски вже виконують повні shard-и bundled plugin. Це дає швидкий зворотний зв’язок щодо змінених plugin-ів під час review, не резервуючи додаткового Blacksmith worker-а на `main` для покриття, яке вже є в `checks-node-extensions`. -GitHub може позначати витіснені завдання як `cancelled`, коли новіший push потрапляє в той самий ref PR або `main`. Вважайте це шумом CI, якщо тільки найновіший запуск для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, щоб вони все одно повідомляли про звичайні збої shard-ів, але не ставали в чергу після того, як весь workflow уже був витіснений. -Ключ concurrency у CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безкінечно блокувати новіші запуски main. +GitHub може позначати витіснені завдання як `cancelled`, коли новіший push потрапляє в той самий PR або ref `main`. Сприймайте це як шум CI, якщо тільки найновіший запуск для того самого ref також не завершується помилкою. Агреговані shard-перевірки використовують `!cancelled() && always()`, тому вони все одно повідомляють про звичайні помилки shard-ів, але не стають у чергу після того, як увесь workflow уже був витіснений. +Ключ конкурентності CI має версію (`CI-v7-*`), щоб zombie-процес на боці GitHub у старій групі черги не міг безстроково блокувати новіші запуски main. ## Runner-и -| Runner | Завдання | -| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки та агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, перевірки channel contract, розбиті на шарди, шарди `check`, окрім lint, шарди й агрегати `check-additional`, агреговані верифікатори Node-тестів, перевірки документації, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла потрапити в чергу раніше | -| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, шарди Linux Node-тестів, шарди тестів bundled plugin, `android` | -| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який залишається достатньо чутливим до CPU, так що 8 vCPU коштували дорожче, ніж заощаджували; Docker-збірки install-smoke, де вартість часу в черзі для 32 vCPU була вищою за вигоду | -| `blacksmith-16vcpu-windows-2025` | `checks-windows` | -| `blacksmith-6vcpu-macos-latest` | `macos-node` у `openclaw/openclaw`; fork-и повертаються до `macos-latest` | -| `blacksmith-12vcpu-macos-latest` | `macos-swift` у `openclaw/openclaw`; fork-и повертаються до `macos-latest` | +| Runner | Завдання | +| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `ubuntu-24.04` | `preflight`, швидкі завдання безпеки й агрегати (`security-scm-fast`, `security-dependency-audit`, `security-fast`), швидкі перевірки protocol/contract/bundled, шардовані перевірки контрактів каналів, shard-и `check`, крім lint, shard-и й агрегати `check-additional`, агреговані верифікатори Node-тестів, перевірки docs, Python Skills, workflow-sanity, labeler, auto-response; preflight для install-smoke також використовує GitHub-hosted Ubuntu, щоб матриця Blacksmith могла ставати в чергу раніше | +| `blacksmith-8vcpu-ubuntu-2404` | `build-artifacts`, build-smoke, shard-и Linux Node-тестів, shard-и тестів bundled plugin, `android` | +| `blacksmith-16vcpu-ubuntu-2404` | `check-lint`, який і далі достатньо чутливий до CPU, тож 8 vCPU коштували дорожче, ніж зекономили; Docker-збірки install-smoke, де вартість часу очікування в черзі для 32 vCPU була вищою за вигоду | +| `blacksmith-16vcpu-windows-2025` | `checks-windows` | +| `blacksmith-6vcpu-macos-latest` | `macos-node` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` | +| `blacksmith-12vcpu-macos-latest` | `macos-swift` на `openclaw/openclaw`; fork-и повертаються до `macos-latest` | ## Локальні еквіваленти ```bash pnpm changed:lanes # переглянути локальний класифікатор changed-lane для origin/main...HEAD -pnpm check:changed # розумна локальна перевірка: changed typecheck/lint/tests за boundary lane -pnpm check # швидка локальна перевірка: production tsgo + lint, розбитий на шарди + паралельні швидкі guards +pnpm check:changed # розумний локальний gate: changed typecheck/lint/tests за boundary lane +pnpm check # швидкий локальний gate: production tsgo + sharded lint + parallel fast guards pnpm check:test-types -pnpm check:timed # та сама перевірка з таймінгами для кожного етапу +pnpm check:timed # той самий gate з таймінгами для кожного етапу pnpm build:strict-smoke pnpm check:architecture pnpm test:gateway:watch-regression pnpm test # тести vitest pnpm test:channels pnpm test:contracts:channels -pnpm check:docs # форматування документації + lint + зламані посилання -pnpm build # зібрати dist, коли важливі смуги CI artifact/build-smoke +pnpm check:docs # форматування docs + lint + биті посилання +pnpm build # зібрати dist, коли важливі доріжки CI artifact/build-smoke node scripts/ci-run-timings.mjs # підсумувати загальний час, час у черзі та найповільніші завдання -node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски main CI +node scripts/ci-run-timings.mjs --recent 10 # порівняти нещодавні успішні запуски CI для main pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json ``` @@ -150,4 +117,4 @@ pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifac ## Пов’язане - [Огляд встановлення](/uk/install) -- [Канали релізу](/uk/install/development-channels) +- [Канали релізів](/uk/install/development-channels) diff --git a/docs/uk/cli/browser.md b/docs/uk/cli/browser.md index f2e80de18..b3361e3d4 100644 --- a/docs/uk/cli/browser.md +++ b/docs/uk/cli/browser.md @@ -1,34 +1,34 @@ --- read_when: - Ви використовуєте `openclaw browser` і хочете приклади для поширених завдань - - Ви хочете керувати браузером, що працює на іншій машині, через вузол-хост - - Ви хочете під’єднатися до свого локального Chrome, у якому виконано вхід, через Chrome MCP -summary: Довідка CLI для `openclaw browser` (життєвий цикл, профілі, вкладки, дії, стан і налагодження) + - Ви хочете керувати браузером, що працює на іншій машині, через хост вузла + - Ви хочете під’єднатися до свого локального Chrome, у якому вже виконано вхід, через Chrome MCP +summary: Довідник CLI для `openclaw browser` (життєвий цикл, профілі, вкладки, дії, стан і налагодження) title: Браузер x-i18n: - generated_at: "2026-04-24T23:39:04Z" + generated_at: "2026-04-25T00:01:11Z" model: gpt-5.4 provider: openai - source_hash: c6e9201d028d94c92dec9ee87fd6097a9cfa039c777a543ca424d8b9981618e7 + source_hash: fe7dcbc830044db4814fa1671807baae82ddcb32bd5228b165bfdbcddd5128de source_path: cli/browser.md workflow: 15 --- # `openclaw browser` -Керуйте поверхнею керування браузером OpenClaw і виконуйте дії браузера (життєвий цикл, профілі, вкладки, знімки стану, знімки екрана, навігація, введення, емуляція стану та налагодження). +Керуйте поверхнею керування браузером OpenClaw і виконуйте дії в браузері (життєвий цикл, профілі, вкладки, знімки, скриншоти, навігація, введення, емуляція стану та налагодження). -Пов’язано: +Пов’язане: -- Інструмент браузера + API: [Інструмент браузера](/uk/tools/browser) +- Інструмент Browser + API: [інструмент Browser](/uk/tools/browser) ## Поширені прапорці - `--url `: URL WebSocket Gateway (типово з конфігурації). -- `--token `: токен Gateway (якщо потрібен). +- `--token `: токен Gateway (за потреби). - `--timeout `: тайм-аут запиту (мс). -- `--expect-final`: чекати на фінальну відповідь Gateway. -- `--browser-profile `: вибрати профіль браузера (типовий — з конфігурації). +- `--expect-final`: чекати фінальну відповідь Gateway. +- `--browser-profile `: вибрати профіль браузера (типовий береться з конфігурації). - `--json`: машинозчитуваний вивід (де підтримується). ## Швидкий старт (локально) @@ -40,24 +40,26 @@ openclaw browser --browser-profile openclaw open https://example.com openclaw browser --browser-profile openclaw snapshot ``` -## Швидке усунення проблем +## Швидке усунення несправностей -Якщо `start` завершується з помилкою `not reachable after start`, спершу перевірте готовність CDP. Якщо `start` і `tabs` працюють, але `open` або `navigate` завершується з помилкою, площина керування браузером справна, а збій зазвичай пов’язаний із політикою SSRF для навігації. +Якщо `start` завершується помилкою `not reachable after start`, спочатку перевірте готовність CDP. Якщо `start` і `tabs` працюють, але `open` або `navigate` не працює, площина керування браузером справна, а збій зазвичай пов’язаний із політикою SSRF навігації. Мінімальна послідовність: ```bash +openclaw browser --browser-profile openclaw doctor openclaw browser --browser-profile openclaw start openclaw browser --browser-profile openclaw tabs openclaw browser --browser-profile openclaw open https://example.com ``` -Докладні вказівки: [Усунення проблем із браузером](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) +Докладні вказівки: [усунення несправностей Browser](/uk/tools/browser#cdp-startup-failure-vs-navigation-ssrf-block) ## Життєвий цикл ```bash openclaw browser status +openclaw browser doctor openclaw browser start openclaw browser stop openclaw browser --browser-profile openclaw reset-profile @@ -65,19 +67,14 @@ openclaw browser --browser-profile openclaw reset-profile Примітки: -- Для профілів `attachOnly` і віддалених CDP `openclaw browser stop` закриває - активний сеанс керування та скидає тимчасові перевизначення емуляції, навіть - якщо OpenClaw не запускав процес браузера самостійно. -- Для локальних керованих профілів `openclaw browser stop` зупиняє запущений - процес браузера. +- Для профілів `attachOnly` і віддалених CDP `openclaw browser stop` закриває активний сеанс керування та скидає тимчасові перевизначення емуляції, навіть якщо OpenClaw сам не запускав процес браузера. +- Для локальних керованих профілів `openclaw browser stop` зупиняє породжений процес браузера. ## Якщо команда відсутня -Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у -`~/.openclaw/openclaw.json`. +Якщо `openclaw browser` є невідомою командою, перевірте `plugins.allow` у `~/.openclaw/openclaw.json`. -Коли `plugins.allow` присутній, вбудований plugin браузера має бути явно -вказаний у списку: +Коли `plugins.allow` присутній, вбудований плагін браузера має бути явно вказаний у списку: ```json5 { @@ -87,16 +84,16 @@ openclaw browser --browser-profile openclaw reset-profile } ``` -`browser.enabled=true` не відновлює підкоманду CLI, якщо список дозволених plugin виключає `browser`. +`browser.enabled=true` не відновлює підкоманду CLI, якщо список дозволених плагінів виключає `browser`. -Пов’язано: [Інструмент браузера](/uk/tools/browser#missing-browser-command-or-tool) +Пов’язане: [інструмент Browser](/uk/tools/browser#missing-browser-command-or-tool) ## Профілі Профілі — це іменовані конфігурації маршрутизації браузера. На практиці: -- `openclaw`: запускає або під’єднується до виділеного екземпляра Chrome під керуванням OpenClaw (ізольований каталог даних користувача). -- `user`: керує вашим наявним сеансом Chrome із виконаним входом через Chrome DevTools MCP. +- `openclaw`: запускає або під’єднується до окремого екземпляра Chrome, яким керує OpenClaw (ізольований каталог користувацьких даних). +- `user`: керує вашим наявним сеансом Chrome, у якому вже виконано вхід, через Chrome DevTools MCP. - власні профілі CDP: вказують на локальну або віддалену кінцеву точку CDP. ```bash @@ -126,37 +123,34 @@ openclaw browser focus docs openclaw browser close t1 ``` -`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`, -необов’язкову мітку та сирий `targetId`. Агенти мають передавати -`suggestedTargetId` назад у `focus`, `close`, знімки стану та дії. Ви можете -призначити мітку за допомогою `open --label`, `tab new --label` або `tab label`; мітки, -ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси target-id -усі приймаються. +`tabs` спочатку повертає `suggestedTargetId`, потім стабільний `tabId`, наприклад `t1`, необов’язкову мітку та сирий `targetId`. Агенти мають передавати `suggestedTargetId` назад у `focus`, `close`, знімки та дії. Ви можете призначити мітку за допомогою `open --label`, `tab new --label` або `tab label`; мітки, ідентифікатори вкладок, сирі ідентифікатори цілей і унікальні префікси ідентифікаторів цілей — усе це підтримується. -## Знімок стану / знімок екрана / дії +## Знімок / скриншот / дії -Знімок стану: +Знімок: ```bash openclaw browser snapshot +openclaw browser snapshot --urls ``` -Знімок екрана: +Скриншот: ```bash openclaw browser screenshot openclaw browser screenshot --full-page openclaw browser screenshot --ref e12 +openclaw browser screenshot --labels ``` Примітки: -- `--full-page` призначено лише для знімків сторінки; його не можна поєднувати з `--ref` - або `--element`. -- Профілі `existing-session` / `user` підтримують знімки екрана сторінки та знімки екрана `--ref` - з виводу знімка стану, але не підтримують знімки екрана CSS `--element`. +- `--full-page` призначений лише для захоплення сторінки; його не можна поєднувати з `--ref` або `--element`. +- Профілі `existing-session` / `user` підтримують скриншоти сторінок і скриншоти `--ref` із виводу знімка, але не підтримують скриншоти CSS `--element`. +- `--labels` накладає поточні посилання знімка на скриншот. +- `snapshot --urls` додає виявлені адреси посилань до AI-знімків, щоб агенти могли вибирати прямі цілі навігації замість здогадок лише за текстом посилання. -Навігація/клацання/введення (автоматизація UI на основі ref): +Navigate/click/type (автоматизація UI на основі ref): ```bash openclaw browser navigate https://example.com @@ -183,7 +177,7 @@ openclaw browser dialog --accept ## Стан і сховище -Вікно перегляду + емуляція: +Viewport + емуляція: ```bash openclaw browser resize 1280 720 @@ -233,34 +227,31 @@ openclaw browser create-profile --name brave-live --driver existing-session --us openclaw browser --browser-profile chrome-live tabs ``` -Цей шлях доступний лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених налаштувань використовуйте натомість профіль CDP. +Цей шлях доступний лише на хості. Для Docker, headless-серверів, Browserless або інших віддалених сценаріїв використовуйте профіль CDP. Поточні обмеження existing-session: -- дії на основі знімка стану використовують ref, а не CSS-селектори -- `click` підтримує лише клацання лівою кнопкою +- дії на основі знімків використовують ref, а не CSS-селектори +- `click` підтримує лише лівий клік - `type` не підтримує `slowly=true` - `press` не підтримує `delayMs` -- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють - перевизначення тайм-ауту для окремих викликів +- `hover`, `scrollintoview`, `drag`, `select`, `fill` і `evaluate` відхиляють перевизначення тайм-ауту для окремого виклику - `select` підтримує лише одне значення - `wait --load networkidle` не підтримується -- вивантаження файлів потребує `--ref` / `--input-ref`, не підтримує CSS - `--element`, і наразі підтримує по одному файлу за раз -- перехоплювачі діалогів не підтримують `--timeout` -- знімки екрана підтримують знімки сторінки та `--ref`, але не CSS `--element` -- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії все ще - потребують керованого браузера або сирого профілю CDP +- завантаження файлів вимагає `--ref` / `--input-ref`, не підтримує CSS `--element` і наразі підтримує лише один файл за раз +- обробники діалогів не підтримують `--timeout` +- скриншоти підтримують захоплення сторінки та `--ref`, але не CSS `--element` +- `responsebody`, перехоплення завантажень, експорт PDF і пакетні дії, як і раніше, вимагають керованого браузера або сирого профілю CDP -## Віддалене керування браузером (проксі вузла-хоста) +## Віддалене керування браузером (проксі хоста вузла) -Якщо Gateway працює на іншій машині, ніж браузер, запустіть **вузол-хост** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксіюватиме дії браузера до цього вузла (окремий сервер керування браузером не потрібен). +Якщо Gateway працює на іншій машині, ніж браузер, запустіть **хост вузла** на машині, де є Chrome/Brave/Edge/Chromium. Gateway проксуватиме дії браузера до цього вузла (окремий сервер керування браузером не потрібен). -Використовуйте `gateway.nodes.browser.mode` для керування автоматичною маршрутизацією та `gateway.nodes.browser.node` для прив’язки до конкретного вузла, якщо підключено кілька вузлів. +Використовуйте `gateway.nodes.browser.mode` для керування автоматичною маршрутизацією та `gateway.nodes.browser.node`, щоб закріпити конкретний вузол, якщо під’єднано кілька вузлів. -Безпека + віддалене налаштування: [Інструмент браузера](/uk/tools/browser), [Віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [Безпека](/uk/gateway/security) +Безпека й віддалене налаштування: [інструмент Browser](/uk/tools/browser), [віддалений доступ](/uk/gateway/remote), [Tailscale](/uk/gateway/tailscale), [безпека](/uk/gateway/security) -## Пов’язано +## Пов’язане -- [Довідка CLI](/uk/cli) -- [Браузер](/uk/tools/browser) +- [Довідник CLI](/uk/cli) +- [Browser](/uk/tools/browser) diff --git a/docs/uk/cli/status.md b/docs/uk/cli/status.md index 8caf21226..3c4c10e36 100644 --- a/docs/uk/cli/status.md +++ b/docs/uk/cli/status.md @@ -1,21 +1,21 @@ --- read_when: - - Вам потрібна швидка діагностика стану каналу + нещодавніх одержувачів сесії - - Вам потрібен придатний для вставлення статус “all” для налагодження -summary: Довідка CLI для `openclaw status` (діагностика, перевірки, знімки використання) + - Вам потрібна швидка діагностика стану каналу + одержувачі нещодавніх сеансів + - Вам потрібен придатний для вставлення статус «all» для налагодження +summary: Довідник CLI для `openclaw status` (діагностика, проби, знімки використання) title: Стан x-i18n: - generated_at: "2026-04-24T03:16:04Z" + generated_at: "2026-04-25T00:01:11Z" model: gpt-5.4 provider: openai - source_hash: 369de48e283766ec23ef87f79df39893957101954c4a351e46ef24104d78ec1d + source_hash: ef182b95eabdb2c24d5d011ed3c3291308373620b893750d6d27470bd88ca3dc source_path: cli/status.md workflow: 15 --- # `openclaw status` -Діагностика для каналів + сесій. +Діагностика для каналів + сеансів. ```bash openclaw status @@ -26,23 +26,23 @@ openclaw status --usage Примітки: -- `--deep` запускає живі перевірки (WhatsApp Web + Telegram + Discord + Slack + Signal). -- `--usage` виводить нормалізовані вікна використання провайдера як `X% left`. -- Вивід стану сесії тепер розділяє `Runtime:` і `Runner:`. `Runtime` — це шлях виконання та стан пісочниці (`direct`, `docker/*`), а `Runner` повідомляє, чи використовує сесія вбудований Pi, провайдера на основі CLI або бекенд harness ACP, наприклад `codex (acp/acpx)`. -- Необроблені поля `usage_percent` / `usagePercent` у MiniMax означають залишок квоти, тому OpenClaw інвертує їх перед показом; поля на основі підрахунку мають пріоритет, якщо присутні. Відповіді `model_remains` надають перевагу запису chat-model, за потреби виводять мітку вікна з часових позначок і включають назву моделі в мітку плану. -- Коли поточний знімок сесії містить мало даних, `/status` може доповнити лічильники токенів і кешу з найновішого журналу використання transcript. Наявні ненульові живі значення все одно мають пріоритет над резервними значеннями з transcript. -- Резервний варіант через transcript також може відновити мітку активної моделі runtime, якщо в живому записі сесії її немає. Якщо ця модель transcript відрізняється від вибраної моделі, status визначає контекстне вікно за відновленою моделлю runtime, а не за вибраною. -- Для обліку розміру prompt резервний варіант через transcript надає перевагу більшому загальному значенню, орієнтованому на prompt, коли метадані сесії відсутні або менші, щоб сесії custom-provider не зводилися до показу `0` токенів. -- Вивід включає сховища сесій для кожного агента, коли налаштовано кілька агентів. -- Огляд включає стан встановлення/виконання сервісу хоста Gateway + Node, коли він доступний. -- Огляд включає канал оновлення + git SHA (для вихідних checkout). -- Інформація про оновлення відображається в Огляді; якщо оновлення доступне, status виводить підказку виконати `openclaw update` (див. [Оновлення](/uk/install/updating)). +- `--deep` запускає живі проби (WhatsApp Web + Telegram + Discord + Slack + Signal). +- `--usage` виводить нормалізовані вікна використання провайдера у форматі `X% left`. +- Вивід стану сеансу розділяє `Execution:` і `Runtime:`. `Execution` — це шлях sandbox (`direct`, `docker/*`), тоді як `Runtime` повідомляє, чи використовує сеанс `OpenClaw Pi Default`, `OpenAI Codex`, бекенд CLI або бекенд ACP, такий як `codex (acp/acpx)`. +- Сирі поля MiniMax `usage_percent` / `usagePercent` означають залишок квоти, тому OpenClaw інвертує їх перед показом; поля на основі підрахунку мають пріоритет, якщо вони присутні. Відповіді `model_remains` надають перевагу запису chat-model, за потреби виводять мітку вікна з часових позначок і включають назву моделі до мітки плану. +- Коли поточний знімок сеансу є неповним, `/status` може підставити назад лічильники токенів і кешу з найновішого журналу використання транскрипту. Наявні ненульові живі значення все одно мають пріоритет над резервними значеннями з транскрипту. +- Резервні дані з транскрипту також можуть відновити мітку активної моделі runtime, якщо в живому записі сеансу її немає. Якщо ця модель транскрипту відрізняється від вибраної моделі, status визначає контекстне вікно за відновленою моделлю runtime, а не за вибраною. +- Для обліку розміру prompt резервні дані з транскрипту надають перевагу більшому загальному значенню, орієнтованому на prompt, коли метадані сеансу відсутні або менші, тому сеанси custom-provider не зводяться до показу `0` токенів. +- Вивід включає сховища сеансів для кожного агента, якщо налаштовано кілька агентів. +- Огляд включає статус встановлення/роботи служби хоста Gateway + Node, якщо доступно. +- Огляд включає канал оновлень + git SHA (для checkout із вихідного коду). +- Інформація про оновлення відображається в розділі Overview; якщо оновлення доступне, status виводить підказку виконати `openclaw update` (див. [Оновлення](/uk/install/updating)). - Поверхні стану лише для читання (`status`, `status --json`, `status --all`) за можливості визначають підтримувані SecretRef для цільових шляхів конфігурації. -- Якщо підтримуваний SecretRef каналу налаштовано, але він недоступний у поточному шляху команди, status залишається в режимі лише для читання та повідомляє про деградований вивід замість аварійного завершення. Зрозумілий для людини вивід показує попередження на кшталт “configured token unavailable in this command path”, а JSON-вивід містить `secretDiagnostics`. -- Коли локальне для команди визначення SecretRef успішне, status надає перевагу визначеному знімку та прибирає тимчасові маркери каналу “secret unavailable” з фінального виводу. -- `status --all` включає рядок огляду Secrets і розділ діагностики, який підсумовує діагностику секретів (усічену для читабельності) без зупинки генерації звіту. +- Якщо підтримуваний SecretRef каналу налаштовано, але він недоступний у поточному шляху команди, status залишається в режимі лише для читання і повідомляє про деградований вивід замість аварійного завершення. Людинозрозумілий вивід показує попередження на кшталт “configured token unavailable in this command path”, а JSON-вивід містить `secretDiagnostics`. +- Коли локальне для команди визначення SecretRef вдається, status надає перевагу визначеному знімку й очищає тимчасові маркери каналу “secret unavailable” з фінального виводу. +- `status --all` включає рядок огляду Secrets і розділ діагностики, який підсумовує діагностику секретів (усічену для читабельності), не зупиняючи генерацію звіту. ## Пов’язане -- [Довідка CLI](/uk/cli) +- [Довідник CLI](/uk/cli) - [Doctor](/uk/gateway/doctor) diff --git a/docs/uk/concepts/model-providers.md b/docs/uk/concepts/model-providers.md index 18e599489..2da05c03e 100644 --- a/docs/uk/concepts/model-providers.md +++ b/docs/uk/concepts/model-providers.md @@ -1,62 +1,65 @@ --- read_when: - Вам потрібен довідник із налаштування моделей для кожного постачальника окремо - - Вам потрібні приклади конфігурацій або команд онбордингу CLI для постачальників моделей -summary: Огляд постачальника моделей із прикладами конфігурацій + потоками CLI + - Ви хочете приклади конфігурацій або команд онбордингу CLI для постачальників моделей +summary: Огляд постачальників моделей із прикладами конфігурацій + потоками CLI title: Постачальники моделей x-i18n: - generated_at: "2026-04-24T15:13:05Z" + generated_at: "2026-04-25T00:01:08Z" model: gpt-5.4 provider: openai - source_hash: 79258cb26fae7926c65b6fe0db938c7b5736a540b33bc24c1fad5ad706ac8204 + source_hash: 1c02aff44b00748bdcb5e4dc02c1725ae4c5d4b9fe3a9da523053a7e95a03f16 source_path: concepts/model-providers.md workflow: 15 --- -Ця сторінка охоплює **постачальників LLM/моделей** (а не чат-канали на кшталт WhatsApp/Telegram). -Правила вибору моделей дивіться в [/concepts/models](/uk/concepts/models). +Ця сторінка охоплює **постачальників LLM/моделей** (а не канали чату, як-от WhatsApp/Telegram). +Правила вибору моделей див. у [/concepts/models](/uk/concepts/models). ## Швидкі правила -- Посилання на моделі використовують формат `provider/model` (приклад: `opencode/claude-opus-4-6`). +- Посилання на моделі використовують `provider/model` (приклад: `opencode/claude-opus-4-6`). - `agents.defaults.models` працює як список дозволених значень, якщо його задано. - Допоміжні CLI-команди: `openclaw onboard`, `openclaw models list`, `openclaw models set `. -- `models.providers.*.models[].contextWindow` — це власні метадані моделі; `contextTokens` — це фактичне обмеження середовища виконання. -- Правила резервного перемикання, перевірки cooldown і збереження перевизначення сесії: [Перемикання моделей при збої](/uk/concepts/model-failover). -- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/` використовує OAuth Codex у PI, а `openai/` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний app-server harness Codex. Дивіться [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). -- Автоматичне ввімкнення Plugin дотримується тієї самої межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. -- GPT-5.5 наразі доступна через маршрути підписки/OAuth: `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness app-server Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі, доступні через API, наприклад `openai/gpt-5.4`, для конфігурацій `OPENAI_API_KEY`. +- `models.providers.*.models[].contextWindow` — це вбудовані метадані моделі; `contextTokens` — це фактичне обмеження під час виконання. +- Правила резервного перемикання, cooldown-перевірки та збереження перевизначень сеансу див. у [Model failover](/uk/concepts/model-failover). +- Маршрути сімейства OpenAI залежать від префікса: `openai/` використовує прямого постачальника API-ключа OpenAI у PI, `openai-codex/` використовує Codex OAuth у PI, а `openai/` разом із `agents.defaults.embeddedHarness.runtime: "codex"` використовує нативний harness сервера застосунку Codex. Див. [OpenAI](/uk/providers/openai) і [Codex harness](/uk/plugins/codex-harness). +- Автоматичне ввімкнення Plugin дотримується тієї ж межі: `openai-codex/` належить Plugin OpenAI, тоді як Plugin Codex вмикається через `embeddedHarness.runtime: "codex"` або застарілі посилання `codex/`. +- CLI-середовища виконання використовують той самий поділ: вибирайте канонічні посилання на моделі, як-от `anthropic/claude-*`, `google/gemini-*` або `openai/gpt-*`, а потім задавайте `agents.defaults.embeddedHarness.runtime` як `claude-cli`, `google-gemini-cli` або `codex-cli`, якщо хочете локальний бекенд CLI. + Застарілі посилання `claude-cli/*`, `google-gemini-cli/*` і `codex-cli/*` мігрують назад до канонічних посилань постачальників, а середовище виконання записується окремо. +- GPT-5.5 наразі доступна через маршрути підписки/OAuth: + `openai-codex/gpt-5.5` у PI або `openai/gpt-5.5` із harness сервера застосунку Codex. Прямий маршрут API-ключа для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте моделі з доступом через API, наприклад `openai/gpt-5.4`, для налаштувань `OPENAI_API_KEY`. -## Поведінка постачальників, що належить Plugin +## Поведінка постачальника, що належить Plugin -Більшість логіки, специфічної для постачальника, живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл інференсу. Plugin відповідають за онбординг, каталоги моделей, зіставлення auth env var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію збоїв для резервного перемикання, оновлення OAuth, звітність про використання, профілі thinking/reasoning та інше. +Більшість специфічної для постачальника логіки живе в Plugin постачальників (`registerProvider(...)`), тоді як OpenClaw зберігає загальний цикл inference. Plugins відповідають за онбординг, каталоги моделей, зіставлення auth env-var, нормалізацію транспорту/конфігурації, очищення схем інструментів, класифікацію failover, оновлення OAuth, звітування про використання, профілі thinking/reasoning тощо. -Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю власний виконавець запитів, є окремою, глибшою поверхнею розширення. +Повний список хуків SDK постачальників і прикладів вбудованих Plugin наведено в [Provider plugins](/uk/plugins/sdk-provider-plugins). Постачальник, якому потрібен повністю кастомний виконавець запитів, — це окрема, глибша поверхня розширення. -Середовище виконання постачальника `capabilities` — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки для transport/cache). Це не те саме, що [публічна модель capability](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий інференс, мовлення тощо). +`capabilities` середовища виконання постачальника — це спільні метадані раннера (сімейство постачальника, особливості transcript/tooling, підказки щодо transport/cache). Це не те саме, що [public capability model](/uk/plugins/architecture#public-capability-model), яка описує, що реєструє Plugin (текстовий inference, мовлення тощо). ## Ротація API-ключів -- Підтримує загальну ротацію ключів постачальника для вибраних постачальників. +- Підтримує загальну ротацію постачальників для вибраних постачальників. - Налаштуйте кілька ключів через: - `OPENCLAW_LIVE__KEY` (одне live-перевизначення, найвищий пріоритет) - `_API_KEYS` (список через кому або крапку з комою) - `_API_KEY` (основний ключ) - `_API_KEY_*` (нумерований список, наприклад `_API_KEY_1`) - Для постачальників Google `GOOGLE_API_KEY` також включається як резервний варіант. -- Порядок вибору ключів зберігає пріоритет і усуває дублікати значень. -- Запити повторюються з наступним ключем лише у відповідях із перевищенням ліміту запитів (наприклад, `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many +- Порядок вибору ключів зберігає пріоритет і прибирає дублікати значень. +- Запити повторюються з наступним ключем лише у відповідь на повідомлення про обмеження швидкості (наприклад `429`, `rate_limit`, `quota`, `resource exhausted`, `Too many concurrent requests`, `ThrottlingException`, `concurrency limit reached`, `workers_ai ... quota limit exceeded` або періодичні повідомлення про ліміт використання). -- Помилки, не пов’язані з лімітом запитів, завершуються негайно; ротація ключів не виконується. -- Коли всі можливі ключі завершуються невдачею, повертається остання помилка з фінальної спроби. +- Помилки, не пов’язані з обмеженням швидкості, одразу завершуються з помилкою; ротація ключів не виконується. +- Якщо всі можливі ключі завершуються помилкою, повертається фінальна помилка з останньої спроби. ## Вбудовані постачальники (каталог pi-ai) -OpenClaw постачається з каталогом pi‑ai. Для цих постачальників **не потрібна** -конфігурація `models.providers`; просто задайте auth і виберіть модель. +OpenClaw постачається з каталогом pi‑ai. Ці постачальники **не** +потребують конфігурації `models.providers`; достатньо налаштувати auth і вибрати модель. ### OpenAI @@ -64,18 +67,18 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Auth: `OPENAI_API_KEY` - Необов’язкова ротація: `OPENAI_API_KEYS`, `OPENAI_API_KEY_1`, `OPENAI_API_KEY_2`, а також `OPENCLAW_LIVE_OPENAI_KEY` (одне перевизначення) - Приклади моделей: `openai/gpt-5.4`, `openai/gpt-5.4-mini` -- Пряма підтримка GPT-5.5 через API тут готова на майбутнє, щойно OpenAI відкриє GPT-5.5 в API +- Пряма підтримка API для GPT-5.5 тут підготовлена на майбутнє, щойно OpenAI відкриє GPT-5.5 в API - CLI: `openclaw onboard --auth-choice openai-api-key` -- Типовий transport — `auto` (спочатку WebSocket, потім SSE як резерв) +- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі через `agents.defaults.models["openai/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- Прогрівання OpenAI Responses WebSocket типово ввімкнене через `params.openaiWsWarmup` (`true`/`false`) +- Розігрів OpenAI Responses WebSocket типово ввімкнений через `params.openaiWsWarmup` (`true`/`false`) - Пріоритетну обробку OpenAI можна ввімкнути через `agents.defaults.models["openai/"].params.serviceTier` -- `/fast` і `params.fastMode` зіставляють прямі запити `openai/*` Responses з `service_tier=priority` на `api.openai.com` +- `/fast` і `params.fastMode` напряму зіставляють запити `openai/*` Responses із `service_tier=priority` на `api.openai.com` - Використовуйте `params.serviceTier`, якщо вам потрібен явний рівень замість спільного перемикача `/fast` - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) застосовуються лише до нативного трафіку OpenAI на `api.openai.com`, а не до загальних OpenAI-сумісних проксі -- Нативні маршрути OpenAI також зберігають `store` для Responses, підказки кешу prompt і формування payload для сумісності з reasoning OpenAI; проксі-маршрути цього не роблять -- `openai/gpt-5.3-codex-spark` навмисно приховано в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не показує +- Нативні маршрути OpenAI також зберігають Responses `store`, підказки кешу prompt і формування payload для сумісності reasoning OpenAI; проксі-маршрути цього не роблять +- `openai/gpt-5.3-codex-spark` навмисно приглушено в OpenClaw, оскільки live-запити OpenAI API його відхиляють, а поточний каталог Codex його не надає ```json5 { @@ -90,9 +93,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Необов’язкова ротація: `ANTHROPIC_API_KEYS`, `ANTHROPIC_API_KEY_1`, `ANTHROPIC_API_KEY_2`, а також `OPENCLAW_LIVE_ANTHROPIC_KEY` (одне перевизначення) - Приклад моделі: `anthropic/claude-opus-4-6` - CLI: `openclaw onboard --auth-choice apiKey` -- Прямі публічні запити Anthropic також підтримують спільний перемикач `/fast` і `params.fastMode`, зокрема трафік з API-ключем і OAuth-автентифікацією, надісланий на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) -- Примітка Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тож OpenClaw вважає повторне використання Claude CLI і `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. -- setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI і `claude -p`, коли це доступно. +- Прямі публічні запити Anthropic підтримують спільний перемикач `/fast` і `params.fastMode`, включно з трафіком з API-ключем і OAuth-автентифікацією, надісланим на `api.anthropic.com`; OpenClaw зіставляє це з Anthropic `service_tier` (`auto` проти `standard_only`) +- Примітка щодо Anthropic: співробітники Anthropic повідомили нам, що використання Claude CLI у стилі OpenClaw знову дозволене, тому OpenClaw вважає повторне використання Claude CLI і використання `claude -p` санкціонованими для цієї інтеграції, якщо Anthropic не опублікує нову політику. +- Setup-token Anthropic залишається доступним як підтримуваний шлях токена OpenClaw, але тепер OpenClaw надає перевагу повторному використанню Claude CLI та `claude -p`, коли вони доступні. ```json5 { @@ -105,19 +108,19 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `openai-codex` - Auth: OAuth (ChatGPT) - Посилання на модель PI: `openai-codex/gpt-5.5` -- Посилання нативного harness app-server Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` +- Посилання на нативний harness сервера застосунку Codex: `openai/gpt-5.5` з `agents.defaults.embeddedHarness.runtime: "codex"` - Застарілі посилання на моделі: `codex/gpt-*` -- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin app-server Codex вибирається лише середовищем виконання Codex harness або застарілими посиланнями `codex/*`. +- Межа Plugin: `openai-codex/*` завантажує Plugin OpenAI; нативний Plugin сервера застосунку Codex вибирається лише через середовище виконання harness Codex або застарілі посилання `codex/*`. - CLI: `openclaw onboard --auth-choice openai-codex` або `openclaw models auth login --provider openai-codex` -- Типовий transport — `auto` (спочатку WebSocket, потім SSE як резерв) +- Типовий transport — `auto` (спочатку WebSocket, резервно SSE) - Перевизначення для окремої моделі PI через `agents.defaults.models["openai-codex/"].params.transport` (`"sse"`, `"websocket"` або `"auto"`) -- `params.serviceTier` також передається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) +- `params.serviceTier` також пересилається в нативних запитах Codex Responses (`chatgpt.com/backend-api`) - Приховані заголовки атрибуції OpenClaw (`originator`, `version`, `User-Agent`) додаються лише до нативного трафіку Codex на `chatgpt.com/backend-api`, а не до загальних OpenAI-сумісних проксі - Використовує той самий перемикач `/fast` і конфігурацію `params.fastMode`, що й прямий `openai/*`; OpenClaw зіставляє це з `service_tier=priority` -- `openai-codex/gpt-5.5` зберігає нативний `contextWindow = 1000000` і типове обмеження середовища виконання `contextTokens = 272000`; перевизначте обмеження середовища через `models.providers.openai-codex.models[].contextTokens` -- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/потоків роботи на кшталт OpenClaw. +- `openai-codex/gpt-5.5` зберігає нативні `contextWindow = 1000000` і типове runtime-значення `contextTokens = 272000`; перевизначте runtime-обмеження через `models.providers.openai-codex.models[].contextTokens` +- Примітка щодо політики: OpenAI Codex OAuth явно підтримується для зовнішніх інструментів/робочих процесів, таких як OpenClaw. - Поточний доступ до GPT-5.5 використовує цей маршрут OAuth/підписки, доки OpenAI не ввімкне GPT-5.5 у публічному API. ```json5 @@ -138,7 +141,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих } ``` -### Інші розміщені варіанти в стилі підписки +### Інші хостовані варіанти у стилі підписки - [Qwen Cloud](/uk/providers/qwen): поверхня постачальника Qwen Cloud, а також зіставлення кінцевих точок Alibaba DashScope і Coding Plan - [MiniMax](/uk/providers/minimax): доступ до MiniMax Coding Plan через OAuth або API-ключ @@ -147,8 +150,8 @@ OpenClaw постачається з каталогом pi‑ai. Для цих ### OpenCode - Auth: `OPENCODE_API_KEY` (або `OPENCODE_ZEN_API_KEY`) -- Постачальник середовища Zen: `opencode` -- Постачальник середовища Go: `opencode-go` +- Постачальник середовища виконання Zen: `opencode` +- Постачальник середовища виконання Go: `opencode-go` - Приклади моделей: `opencode/claude-opus-4-6`, `opencode-go/kimi-k2.5` - CLI: `openclaw onboard --auth-choice opencode-zen` або `openclaw onboard --auth-choice opencode-go` @@ -162,19 +165,19 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Постачальник: `google` - Auth: `GEMINI_API_KEY` -- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне перевизначення) +- Необов’язкова ротація: `GEMINI_API_KEYS`, `GEMINI_API_KEY_1`, `GEMINI_API_KEY_2`, резервний `GOOGLE_API_KEY` і `OPENCLAW_LIVE_GEMINI_KEY` (одне live-перевизначення) - Приклади моделей: `google/gemini-3.1-pro-preview`, `google/gemini-3-flash-preview` - Сумісність: застаріла конфігурація OpenClaw із `google/gemini-3.1-flash-preview` нормалізується до `google/gemini-3-flash-preview` - CLI: `openclaw onboard --auth-choice gemini-api-key` - Прямі запуски Gemini також приймають `agents.defaults.models["google/"].params.cachedContent` - (або застарілий `cached_content`) для передавання нативного - дескриптора `cachedContents/...`; потрапляння в кеш Gemini відображаються як OpenClaw `cacheRead` + (або застаріле `cached_content`) для пересилання нативного + дескриптора постачальника `cachedContents/...`; попадання в кеш Gemini відображаються як OpenClaw `cacheRead` ### Google Vertex і Gemini CLI - Постачальники: `google-vertex`, `google-gemini-cli` -- Auth: Vertex використовує gcloud ADC; Gemini CLI використовує власний потік OAuth -- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте неважливий обліковий запис, якщо вирішите продовжити. +- Auth: Vertex використовує gcloud ADC; Gemini CLI — свій потік OAuth +- Застереження: OAuth Gemini CLI в OpenClaw є неофіційною інтеграцією. Деякі користувачі повідомляли про обмеження облікового запису Google після використання сторонніх клієнтів. Ознайомтеся з умовами Google і використовуйте некритичний обліковий запис, якщо вирішите продовжити. - OAuth Gemini CLI постачається як частина вбудованого Plugin `google`. - Спочатку встановіть Gemini CLI: - `brew install gemini-cli` @@ -182,9 +185,9 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Увімкнення: `openclaw plugins enable google` - Вхід: `openclaw models auth login --provider google-gemini-cli --set-default` - Типова модель: `google-gemini-cli/gemini-3-flash-preview` - - Примітка: ви **не** вставляєте client id або secret у `openclaw.json`. Потік входу CLI зберігає токени в auth profiles на хості Gateway. - - Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway. - - Відповіді JSON Gemini CLI аналізуються з `response`; використання береться з `stats` як резерв, а `stats.cached` нормалізується до OpenClaw `cacheRead`. + - Примітка: вам **не потрібно** вставляти client id або secret в `openclaw.json`. Потік входу CLI зберігає токени в auth-профілях на хості gateway. + - Якщо після входу запити завершуються помилкою, задайте `GOOGLE_CLOUD_PROJECT` або `GOOGLE_CLOUD_PROJECT_ID` на хості gateway. + - JSON-відповіді Gemini CLI розбираються з `response`; використання резервно береться зі `stats`, а `stats.cached` нормалізується до OpenClaw `cacheRead`. ### Z.AI (GLM) @@ -192,7 +195,7 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Auth: `ZAI_API_KEY` - Приклад моделі: `zai/glm-5.1` - CLI: `openclaw onboard --auth-choice zai-api-key` - - Псевдоніми: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` + - Аліаси: `z.ai/*` і `z-ai/*` нормалізуються до `zai/*` - `zai-api-key` автоматично визначає відповідну кінцеву точку Z.AI; `zai-coding-global`, `zai-coding-cn`, `zai-global` і `zai-cn` примусово вибирають конкретну поверхню ### Vercel AI Gateway @@ -209,71 +212,72 @@ OpenClaw постачається з каталогом pi‑ai. Для цих - Auth: `KILOCODE_API_KEY` - Приклад моделі: `kilocode/kilo/auto` - CLI: `openclaw onboard --auth-choice kilocode-api-key` -- Базова URL-адреса: `https://api.kilo.ai/api/gateway/` +- Базовий URL: `https://api.kilo.ai/api/gateway/` - Статичний резервний каталог постачається з `kilocode/kilo/auto`; live-виявлення через - `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог середовища виконання. -- Точна маршрутизація на боці джерела для `kilocode/kilo/auto` належить Kilo Gateway, + `https://api.kilo.ai/api/gateway/models` може додатково розширити каталог + середовища виконання. +- Точна маршрутизація вгору за потоком для `kilocode/kilo/auto` належить Kilo Gateway, а не жорстко закодована в OpenClaw. -Деталі налаштування дивіться в [/providers/kilocode](/uk/providers/kilocode). +Деталі налаштування див. у [/providers/kilocode](/uk/providers/kilocode). ### Інші вбудовані Plugin постачальників -| Постачальник | Id | Auth env | Приклад моделі | -| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ----------------------------------------------- | -| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | -| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | -| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | -| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | -| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | -| Groq | `groq` | `GROQ_API_KEY` | — | -| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` or `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | -| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | -| Kimi Coding | `kimi` | `KIMI_API_KEY` or `KIMICODE_API_KEY` | `kimi/kimi-code` | -| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | -| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | -| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | +| Постачальник | Id | Auth env | Приклад моделі | +| ----------------------- | -------------------------------- | ------------------------------------------------------------ | ---------------------------------------------- | +| BytePlus | `byteplus` / `byteplus-plan` | `BYTEPLUS_API_KEY` | `byteplus-plan/ark-code-latest` | +| Cerebras | `cerebras` | `CEREBRAS_API_KEY` | `cerebras/zai-glm-4.7` | +| Cloudflare AI Gateway | `cloudflare-ai-gateway` | `CLOUDFLARE_AI_GATEWAY_API_KEY` | — | +| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` | `deepseek/deepseek-v4-flash` | +| GitHub Copilot | `github-copilot` | `COPILOT_GITHUB_TOKEN` / `GH_TOKEN` / `GITHUB_TOKEN` | — | +| Groq | `groq` | `GROQ_API_KEY` | — | +| Hugging Face Inference | `huggingface` | `HUGGINGFACE_HUB_TOKEN` або `HF_TOKEN` | `huggingface/deepseek-ai/DeepSeek-R1` | +| Kilo Gateway | `kilocode` | `KILOCODE_API_KEY` | `kilocode/kilo/auto` | +| Kimi Coding | `kimi` | `KIMI_API_KEY` або `KIMICODE_API_KEY` | `kimi/kimi-code` | +| MiniMax | `minimax` / `minimax-portal` | `MINIMAX_API_KEY` / `MINIMAX_OAUTH_TOKEN` | `minimax/MiniMax-M2.7` | +| Mistral | `mistral` | `MISTRAL_API_KEY` | `mistral/mistral-large-latest` | +| Moonshot | `moonshot` | `MOONSHOT_API_KEY` | `moonshot/kimi-k2.6` | | NVIDIA | `nvidia` | `NVIDIA_API_KEY` | `nvidia/nvidia/llama-3.1-nemotron-70b-instruct` | -| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | -| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | -| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | -| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | -| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | -| Venice | `venice` | `VENICE_API_KEY` | — | -| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | -| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | -| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | -| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | +| OpenRouter | `openrouter` | `OPENROUTER_API_KEY` | `openrouter/auto` | +| Qianfan | `qianfan` | `QIANFAN_API_KEY` | `qianfan/deepseek-v3.2` | +| Qwen Cloud | `qwen` | `QWEN_API_KEY` / `MODELSTUDIO_API_KEY` / `DASHSCOPE_API_KEY` | `qwen/qwen3.5-plus` | +| StepFun | `stepfun` / `stepfun-plan` | `STEPFUN_API_KEY` | `stepfun/step-3.5-flash` | +| Together | `together` | `TOGETHER_API_KEY` | `together/moonshotai/Kimi-K2.5` | +| Venice | `venice` | `VENICE_API_KEY` | — | +| Vercel AI Gateway | `vercel-ai-gateway` | `AI_GATEWAY_API_KEY` | `vercel-ai-gateway/anthropic/claude-opus-4.6` | +| Volcano Engine (Doubao) | `volcengine` / `volcengine-plan` | `VOLCANO_ENGINE_API_KEY` | `volcengine-plan/ark-code-latest` | +| xAI | `xai` | `XAI_API_KEY` | `xai/grok-4` | +| Xiaomi | `xiaomi` | `XIAOMI_API_KEY` | `xiaomi/mimo-v2-flash` | Варто знати такі особливості: -- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-шлях у стилі OpenAI-compatible, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, `store` для Responses, підказки кешу prompt, сумісність reasoning OpenAI). Посилання, що використовують Gemini як бекенд, зберігають лише очищення thought-signature для проксі-Gemini. -- **Kilo Gateway** для посилань із Gemini як бекендом дотримується того самого шляху очищення проксі-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning. -- **MiniMax** під час онбордингу через API-ключ записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки цю конфігурацію не буде матеріалізовано. -- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнений; вимкніть через `agents.defaults.models["xai/"].params.tool_stream=false`. -- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; базова URL-адреса у форматі OpenAI-compatible — `https://api.cerebras.ai/v1`. +- **OpenRouter** застосовує свої заголовки атрибуції застосунку та маркери Anthropic `cache_control` лише на перевірених маршрутах `openrouter.ai`. Як проксі-подібний OpenAI-сумісний шлях, він пропускає формування, доступне лише для нативного OpenAI (`serviceTier`, Responses `store`, підказки кешу prompt, сумісність reasoning OpenAI). Посилання з бекендом Gemini зберігають лише санітизацію thought-signature для проксі-Gemini. +- **Kilo Gateway** для посилань із бекендом Gemini дотримується того самого шляху санітизації проксі-Gemini; `kilocode/kilo/auto` та інші посилання, що не підтримують proxy reasoning, пропускають ін’єкцію proxy reasoning. +- **MiniMax** онбординг через API-ключ записує явні визначення моделей M2.7 з `input: ["text", "image"]`; вбудований каталог зберігає chat-посилання лише текстовими, доки ця конфігурація не буде матеріалізована. +- **xAI** використовує шлях xAI Responses. `/fast` або `params.fastMode: true` переписує `grok-3`, `grok-3-mini`, `grok-4` і `grok-4-0709` на їхні варіанти `*-fast`. `tool_stream` типово ввімкнено; вимкнення через `agents.defaults.models["xai/"].params.tool_stream=false`. +- **Cerebras** моделі GLM використовують `zai-glm-4.7` / `zai-glm-4.6`; OpenAI-сумісний базовий URL — `https://api.cerebras.ai/v1`. -## Постачальники через `models.providers` (custom/base URL) +## Постачальники через `models.providers` (власний/base URL) -Використовуйте `models.providers` (або `models.json`), щоб додавати **власних** постачальників або -проксі, сумісні з OpenAI/Anthropic. +Використовуйте `models.providers` (або `models.json`), щоб додати **власних** постачальників або +OpenAI/Anthropic‑сумісні проксі. Багато з наведених нижче вбудованих Plugin постачальників уже публікують типовий каталог. Використовуйте явні записи `models.providers.` лише тоді, коли хочете перевизначити -типову базову URL-адресу, заголовки або список моделей. +типовий base URL, заголовки або список моделей. ### Moonshot AI (Kimi) -Moonshot постачається як вбудований Plugin постачальника. Використовуйте вбудованого постачальника -типово, а явний запис `models.providers.moonshot` додавайте лише тоді, коли -потрібно перевизначити базову URL-адресу або метадані моделі: +Moonshot постачається як вбудований Plugin постачальника. Типово використовуйте +вбудованого постачальника, а явний запис `models.providers.moonshot` додавайте лише тоді, коли +потрібно перевизначити base URL або метадані моделі: - Постачальник: `moonshot` - Auth: `MOONSHOT_API_KEY` - Приклад моделі: `moonshot/kimi-k2.6` - CLI: `openclaw onboard --auth-choice moonshot-api-key` або `openclaw onboard --auth-choice moonshot-api-key-cn` -Ідентифікатори моделей Kimi K2: +Id моделей Kimi K2: [//]: # "moonshot-kimi-k2-model-refs:start" @@ -306,7 +310,7 @@ Moonshot постачається як вбудований Plugin постач ### Kimi Coding -Kimi Coding використовує Anthropic-compatible endpoint від Moonshot AI: +Kimi Coding використовує Anthropic-сумісну кінцеву точку Moonshot AI: - Постачальник: `kimi` - Auth: `KIMI_API_KEY` @@ -321,7 +325,7 @@ Kimi Coding використовує Anthropic-compatible endpoint від Moonsh } ``` -Застарілий `kimi/k2p5` і далі приймається як сумісний ідентифікатор моделі. +Застарілий `kimi/k2p5` як і раніше приймається як id моделі для сумісності. ### Volcano Engine (Doubao) @@ -340,13 +344,13 @@ Volcano Engine (火山引擎) надає доступ до Doubao та інши } ``` -Під час онбордингу типовою є поверхня coding, але загальний каталог `volcengine/*` +Онбординг типово використовує поверхню coding, але загальний каталог `volcengine/*` реєструється одночасно. -У засобах вибору моделі для онбордингу/налаштування варіант auth для Volcengine надає перевагу рядкам -`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору, обмеженого постачальником. +У засобах вибору моделей onboarding/configure варіант auth для Volcengine надає перевагу рядкам +`volcengine/*` і `volcengine-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw повертається до нефільтрованого каталогу, а не показує порожній +засіб вибору в межах постачальника. Доступні моделі: @@ -381,13 +385,13 @@ BytePlus ARK надає міжнародним користувачам дост } ``` -Під час онбордингу типовою є поверхня coding, але загальний каталог `byteplus/*` +Онбординг типово використовує поверхню coding, але загальний каталог `byteplus/*` реєструється одночасно. -У засобах вибору моделі для онбордингу/налаштування варіант auth для BytePlus надає перевагу обом -рядкам `byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажено, -OpenClaw повертається до нефільтрованого каталогу замість показу порожнього -засобу вибору, обмеженого постачальником. +У засобах вибору моделей onboarding/configure варіант auth для BytePlus надає перевагу рядкам +`byteplus/*` і `byteplus-plan/*`. Якщо ці моделі ще не завантажені, +OpenClaw повертається до нефільтрованого каталогу, а не показує порожній +засіб вибору в межах постачальника. Доступні моделі: @@ -405,7 +409,7 @@ OpenClaw повертається до нефільтрованого катал ### Synthetic -Synthetic надає Anthropic-compatible моделі через постачальника `synthetic`: +Synthetic надає Anthropic-сумісні моделі через постачальника `synthetic`: - Постачальник: `synthetic` - Auth: `SYNTHETIC_API_KEY` @@ -433,26 +437,26 @@ Synthetic надає Anthropic-compatible моделі через постача ### MiniMax -MiniMax налаштовується через `models.providers`, оскільки використовує власні endpoint: +MiniMax налаштовується через `models.providers`, оскільки використовує власні кінцеві точки: - MiniMax OAuth (Global): `--auth-choice minimax-global-oauth` - MiniMax OAuth (CN): `--auth-choice minimax-cn-oauth` -- MiniMax API-ключ (Global): `--auth-choice minimax-global-api` -- MiniMax API-ключ (CN): `--auth-choice minimax-cn-api` +- MiniMax API key (Global): `--auth-choice minimax-global-api` +- MiniMax API key (CN): `--auth-choice minimax-cn-api` - Auth: `MINIMAX_API_KEY` для `minimax`; `MINIMAX_OAUTH_TOKEN` або `MINIMAX_API_KEY` для `minimax-portal` -Деталі налаштування, варіанти моделей і фрагменти конфігурації дивіться в [/providers/minimax](/uk/providers/minimax). +Деталі налаштування, варіанти моделей і фрагменти конфігурації див. у [/providers/minimax](/uk/providers/minimax). -На Anthropic-compatible streaming-шляху MiniMax OpenClaw типово вимикає thinking, +У Anthropic-сумісному потоковому шляху MiniMax OpenClaw типово вимикає thinking, якщо ви явно його не задасте, а `/fast on` переписує `MiniMax-M2.7` на `MiniMax-M2.7-highspeed`. -Розподіл capability, що належить Plugin: +Розділення можливостей, що належить Plugin: -- Типові значення для text/chat залишаються на `minimax/MiniMax-M2.7` +- Типові значення text/chat залишаються на `minimax/MiniMax-M2.7` - Генерація зображень — це `minimax/image-01` або `minimax-portal/image-01` -- Розуміння зображень — це керований Plugin `MiniMax-VL-01` на обох auth-шляхах MiniMax +- Розуміння зображень — це `MiniMax-VL-01`, що належить Plugin, на обох шляхах auth MiniMax - Вебпошук залишається на id постачальника `minimax` ### LM Studio @@ -461,9 +465,9 @@ LM Studio постачається як вбудований Plugin постач - Постачальник: `lmstudio` - Auth: `LM_API_TOKEN` -- Типова базова URL-адреса інференсу: `http://localhost:1234/v1` +- Типовий базовий URL inference: `http://localhost:1234/v1` -Потім задайте модель (замініть на один з id, які повертає `http://localhost:1234/api/v1/models`): +Потім задайте модель (замініть на один з id, повернутих `http://localhost:1234/api/v1/models`): ```json5 { @@ -473,16 +477,16 @@ LM Studio постачається як вбудований Plugin постач } ``` -OpenClaw використовує нативні `/api/v1/models` і `/api/v1/models/load` LM Studio -для виявлення й автозавантаження, а `/v1/chat/completions` — типово для інференсу. -Налаштування та усунення несправностей дивіться в [/providers/lmstudio](/uk/providers/lmstudio). +OpenClaw використовує нативні для LM Studio `/api/v1/models` і `/api/v1/models/load` +для виявлення й автозавантаження, а `/v1/chat/completions` типово — для inference. +Деталі налаштування та усунення несправностей див. у [/providers/lmstudio](/uk/providers/lmstudio). ### Ollama -Ollama постачається як вбудований Plugin постачальника і використовує нативний API Ollama: +Ollama постачається як вбудований Plugin постачальника й використовує нативний API Ollama: - Постачальник: `ollama` -- Auth: не потрібна (локальний сервер) +- Auth: не потрібен (локальний сервер) - Приклад моделі: `ollama/llama3.3` - Встановлення: [https://ollama.com/download](https://ollama.com/download) @@ -499,27 +503,27 @@ ollama pull llama3.3 } ``` -Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви явно вмикаєте це через +Ollama виявляється локально за адресою `http://127.0.0.1:11434`, коли ви вмикаєте її через `OLLAMA_API_KEY`, а вбудований Plugin постачальника додає Ollama безпосередньо до -`openclaw onboard` і засобу вибору моделі. Дивіться [/providers/ollama](/uk/providers/ollama) -для онбордингу, хмарного/локального режиму та власної конфігурації. +`openclaw onboard` і засобу вибору моделі. Див. [/providers/ollama](/uk/providers/ollama) +щодо онбордингу, хмарного/локального режиму та власної конфігурації. ### vLLM -vLLM постачається як вбудований Plugin постачальника для локальних/самостійно розміщених -серверів, сумісних з OpenAI: +vLLM постачається як вбудований Plugin постачальника для локальних/self-hosted OpenAI-сумісних +серверів: - Постачальник: `vllm` -- Auth: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:8000/v1` +- Auth: необов’язковий (залежить від вашого сервера) +- Типовий базовий URL: `http://127.0.0.1:8000/v1` -Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не вимагає auth): +Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export VLLM_API_KEY="vllm-local" ``` -Потім задайте модель (замініть на один з id, які повертає `/v1/models`): +Потім задайте модель (замініть на один з id, повернутих `/v1/models`): ```json5 { @@ -529,25 +533,25 @@ export VLLM_API_KEY="vllm-local" } ``` -Деталі дивіться в [/providers/vllm](/uk/providers/vllm). +Деталі див. у [/providers/vllm](/uk/providers/vllm). ### SGLang -SGLang постачається як вбудований Plugin постачальника для швидких самостійно розміщених -серверів, сумісних з OpenAI: +SGLang постачається як вбудований Plugin постачальника для швидких self-hosted +OpenAI-сумісних серверів: - Постачальник: `sglang` -- Auth: необов’язкова (залежить від вашого сервера) -- Типова базова URL-адреса: `http://127.0.0.1:30000/v1` +- Auth: необов’язковий (залежить від вашого сервера) +- Типовий базовий URL: `http://127.0.0.1:30000/v1` -Щоб локально ввімкнути автовиявлення (підійде будь-яке значення, якщо ваш сервер не +Щоб увімкнути автовиявлення локально (підійде будь-яке значення, якщо ваш сервер не вимагає auth): ```bash export SGLANG_API_KEY="sglang-local" ``` -Потім задайте модель (замініть на один з id, які повертає `/v1/models`): +Потім задайте модель (замініть на один з id, повернутих `/v1/models`): ```json5 { @@ -557,11 +561,11 @@ export SGLANG_API_KEY="sglang-local" } ``` -Деталі дивіться в [/providers/sglang](/uk/providers/sglang). +Деталі див. у [/providers/sglang](/uk/providers/sglang). ### Локальні проксі (LM Studio, vLLM, LiteLLM тощо) -Приклад (OpenAI‑compatible): +Приклад (OpenAI‑сумісний): ```json5 { @@ -596,18 +600,18 @@ export SGLANG_API_KEY="sglang-local" Примітки: -- Для custom постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` є необов’язковими. - Якщо їх пропущено, OpenClaw типово використовує: +- Для власних постачальників `reasoning`, `input`, `cost`, `contextWindow` і `maxTokens` необов’язкові. + Якщо їх не задано, OpenClaw типово використовує: - `reasoning: false` - `input: ["text"]` - `cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 }` - `contextWindow: 200000` - `maxTokens: 8192` -- Рекомендовано: задавайте явні значення, які відповідають лімітам вашого проксі/моделі. -- Для `api: "openai-completions"` на ненативних endpoint (будь-який непорожній `baseUrl`, хост якого не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникнути помилок 400 від постачальника через непідтримувані ролі `developer`. -- Маршрути у стилі проксі, сумісні з OpenAI, також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без `store` для Responses, без підказок кешу prompt, без формування payload для сумісності reasoning OpenAI і без прихованих заголовків атрибуції OpenClaw. -- Якщо `baseUrl` порожній або пропущений, OpenClaw зберігає типову поведінку OpenAI (яка зводиться до `api.openai.com`). -- Для безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних endpoint `openai-completions`. +- Рекомендовано: задавайте явні значення, що відповідають обмеженням вашого проксі/моделі. +- Для `api: "openai-completions"` на ненативних кінцевих точках (будь-який непорожній `baseUrl`, чий host не є `api.openai.com`) OpenClaw примусово встановлює `compat.supportsDeveloperRole: false`, щоб уникати помилок постачальника 400 для непідтримуваних ролей `developer`. +- Проксі-подібні OpenAI-сумісні маршрути також пропускають формування запитів, доступне лише для нативного OpenAI: без `service_tier`, без Responses `store`, без підказок кешу prompt, без формування payload для сумісності reasoning OpenAI та без прихованих заголовків атрибуції OpenClaw. +- Якщо `baseUrl` порожній/не заданий, OpenClaw зберігає типову поведінку OpenAI (яка веде до `api.openai.com`). +- Для безпеки явне `compat.supportsDeveloperRole: true` все одно перевизначається на ненативних кінцевих точках `openai-completions`. ## Приклади CLI @@ -617,11 +621,11 @@ openclaw models set opencode/claude-opus-4-6 openclaw models list ``` -Дивіться також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. +Див. також: [/gateway/configuration](/uk/gateway/configuration) для повних прикладів конфігурації. -## Пов’язані сторінки +## Пов’язане -- [Models](/uk/concepts/models) — конфігурація моделей і псевдоніми +- [Models](/uk/concepts/models) — конфігурація моделей і аліаси - [Model Failover](/uk/concepts/model-failover) — ланцюжки резервного перемикання та поведінка повторних спроб - [Configuration Reference](/uk/gateway/config-agents#agent-defaults) — ключі конфігурації моделей -- [Providers](/uk/providers) — окремі посібники з налаштування постачальників +- [Providers](/uk/providers) — інструкції з налаштування для кожного постачальника diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index ff6b88b90..a3d88322e 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,20 +1,20 @@ --- read_when: - - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування сеансу, доставки повідомлень і поведінки режиму talk -summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk + - Налаштування типових параметрів агента (моделі, мислення, робочий простір, Heartbeat, медіа, Skills) + - Налаштування маршрутизації та прив’язок між кількома агентами + - Налаштування сесії, доставки повідомлень і поведінки режиму розмови +summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація розмови title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-24T21:43:38Z" + generated_at: "2026-04-25T00:01:08Z" model: gpt-5.4 provider: openai - source_hash: 6c74f7d730fa4380acdd2af7b6dd8f3db635d901151826ce8c80993fedd70365 + source_hash: fe9405429df108dd6a745102e03ad1dea29cf9559ad534bba202c767db047a75 source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, `messages.*` і `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який відображається в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. +Необов’язковий корінь репозиторію, що показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись вгору від робочого простору. ```json5 { @@ -58,11 +58,11 @@ x-i18n: } ``` -- Не вказуйте `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` @@ -76,9 +76,9 @@ x-i18n: ### `agents.defaults.contextInjection` -Керує тим, коли bootstrap-файли робочого простору додаються до системного запиту. Типове значення: `"always"`. +Керує тим, коли bootstrap-файли робочого простору впроваджуються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне додавання bootstrap-контексту робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"continuation-skip"`: безпечні ходи продовження (після завершеної відповіді асистента) пропускають повторне впровадження bootstrap-даних робочого простору, зменшуючи розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. ```json5 { @@ -98,7 +98,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що додаються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна загальна кількість символів, що впроваджуються через всі bootstrap-файли робочого простору. Типове значення: `60000`. ```json5 { @@ -111,9 +111,9 @@ x-i18n: Керує видимим для агента текстом попередження, коли bootstrap-контекст обрізано. Типове значення: `"once"`. -- `"off"`: ніколи не додавати текст попередження до системного запиту. -- `"once"`: додавати попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). -- `"always"`: додавати попередження під час кожного запуску, якщо є обрізання. +- `"off"`: ніколи не впроваджувати текст попередження в системний запит. +- `"once"`: впроваджувати попередження один раз для кожного унікального сигнатурного обрізання (рекомендовано). +- `"always"`: впроваджувати попередження при кожному запуску, коли є обрізання. ```json5 { @@ -121,24 +121,24 @@ x-i18n: } ``` -### Карта володіння бюджетом контексту +### Мапа відповідальності за бюджет контексту OpenClaw має кілька високонавантажених бюджетів запиту/контексту, і вони -навмисно розділені між підсистемами, а не проходять через один універсальний -параметр. +навмисно розділені між підсистемами, а не зведені до одного загального +параметра. - `agents.defaults.bootstrapMaxChars` / `agents.defaults.bootstrapTotalMaxChars`: - звичайне додавання bootstrap-контексту робочого простору. + звичайне впровадження bootstrap-даних робочого простору. - `agents.defaults.startupContext.*`: - одноразова стартова преамбула для `/new` і `/reset`, зокрема нещодавні щоденні - файли `memory/*.md`. + одноразова стартова преамбула для `/new` і `/reset`, включно з нещодавніми + щоденними файлами `memory/*.md`. - `skills.limits.*`: - компактний список Skills, який додається до системного запиту. + компактний список Skills, що впроваджується в системний запит. - `agents.defaults.contextLimits.*`: - обмежені витяги середовища виконання та додані блоки, якими керує runtime. + обмежені фрагменти середовища виконання та впроваджені блоки, що належать середовищу виконання. - `memory.qmd.limits.*`: - індексований фрагмент пошуку пам’яті та параметри додавання. + розмір фрагментів індексованого пошуку в пам’яті та їх впровадження. Використовуйте відповідне перевизначення для конкретного агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -148,7 +148,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.defaults.startupContext` -Керує стартовою преамбулою першого ходу, яка додається під час порожніх запусків `/new` і `/reset`. +Керує стартовою преамбулою першого ходу, що впроваджується під час простих запусків `/new` і `/reset`. ```json5 { @@ -186,16 +186,16 @@ OpenClaw має кілька високонавантажених бюджеті } ``` -- `memoryGetMaxChars`: типове обмеження розміру витягу `memory_get` перед додаванням +- `memoryGetMaxChars`: типове обмеження фрагмента `memory_get` перед додаванням метаданих обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines` - не вказано. -- `toolResultMaxChars`: поточне обмеження розміру результату інструмента, що використовується для збережених результатів і відновлення після переповнення. -- `postCompactionMaxChars`: обмеження розміру витягу AGENTS.md, що використовується під час додавання оновлення після Compaction. +- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` + пропущено. +- `toolResultMaxChars`: обмеження результату інструмента в реальному часі, що використовується для збережених результатів і відновлення після переповнення. +- `postCompactionMaxChars`: обмеження фрагмента AGENTS.md, що використовується під час впровадження оновлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для конкретного агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення на рівні агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -222,7 +222,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, який додається до системного запиту. Це +Глобальне обмеження для компактного списку Skills, що впроваджується в системний запит. Це не впливає на читання файлів `SKILL.md` на вимогу. ```json5 @@ -237,7 +237,7 @@ OpenClaw має кілька високонавантажених бюджеті #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення бюджету запиту Skills для конкретного агента. +Перевизначення бюджету запиту Skills на рівні агента. ```json5 { @@ -256,11 +256,11 @@ OpenClaw має кілька високонавантажених бюджеті ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень стенограми/інструментів перед викликами провайдера. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструментів перед викликами провайдера. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту в сценаріях із великою кількістю знімків екрана. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір тіла запиту для сценаріїв із великою кількістю скриншотів. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -320,7 +320,7 @@ OpenClaw має кілька високонавантажених бюджеті }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "auto", // auto | pi | зареєстрований ідентифікатор harness, наприклад codex + runtime: "pi", // pi | auto | ідентифікатор зареєстрованого harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -339,50 +339,50 @@ OpenClaw має кілька високонавантажених бюджеті - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель плюс впорядкований список моделей для аварійного перемикання. + - Форма об’єкта задає основну модель і впорядкований список резервних моделей для перемикання при відмові. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як конфігурація його vision-моделі. - - Також використовується для резервної маршрутизації, коли вибрана/типова модель не може приймати вхідні зображення. + - Використовується шляхом інструмента `image` як його конфігурація vision-моделі. + - Також використовується як резервна маршрутизація, коли вибрана/типова модель не може приймати вхідні зображення. - `imageGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації зображень і будь-якою майбутньою поверхнею інструмента/Plugin, що генерує зображення. - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal або `openai/gpt-image-2` для OpenAI Images. - - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). - - Якщо не вказано, `image_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2`, `FAL_KEY` для `fal/*`). + - Якщо параметр пропущено, `image_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів. - `musicGenerationModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується спільною можливістю генерації музики та вбудованим інструментом `music_generate`. - Типові значення: `google/lyria-3-clip-preview`, `google/lyria-3-pro-preview` або `minimax/music-2.5+`. - - Якщо не вказано, `music_generate` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. + - Якщо параметр пропущено, `music_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера/API-ключ. - `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` усе одно може визначити типовий провайдер на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. - - Якщо ви безпосередньо вибираєте провайдера/модель, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд і параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` та `watermark`. + - Якщо параметр пропущено, `video_generate` усе одно може визначити типове значення провайдера за наявною автентифікацією. Спочатку він пробує поточного типового провайдера, потім — решту зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо ви безпосередньо вибираєте `provider/model`, налаштуйте також відповідну автентифікацію провайдера/API-ключ. + - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сеансу/типову модель. + - Якщо параметр пропущено, інструмент 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 спершу пробує псевдонім, потім — однозначний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла сумісна поведінка, тож краще вказувати явний `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення видаленого провайдера. -- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`). - - Безпечні зміни: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених значень, якщо не передати `--replace`. - - Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих нерелевантних провайдерів. - - Для прямих моделей OpenAI Responses компактування на стороні сервера вмикається автоматично. Використовуйте `params.responsesServerCompaction: false`, щоб припинити додавання `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Compaction на стороні сервера OpenAI](/uk/providers/openai#server-side-compaction-responses-api). +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного витягування в інструменті `pdf`. +- `verboseDefault`: типовий рівень докладності для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. +- `elevatedDefault`: типовий рівень розширеного виводу для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.4` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо ви пропускаєте провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення від видаленого провайдера. +- `models`: налаштований каталог моделей і список дозволених значень для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`). + - Безпечне редагування: використовуйте `openclaw config set agents.defaults.models '' --strict-json --merge`, щоб додавати записи. `config set` відмовляє в замінах, які видалили б наявні записи зі списку дозволених, якщо не передати `--replace`. + - Потоки налаштування/онбордингу в межах провайдера об’єднують вибрані моделі провайдера в цю мапу та зберігають уже налаштованих інших, не пов’язаних провайдерів. + - Для прямих моделей OpenAI Responses автоматично вмикається серверний Compaction. Використовуйте `params.responsesServerCompaction: false`, щоб припинити впровадження `context_management`, або `params.responsesCompactThreshold`, щоб перевизначити поріг. Див. [Серверний Compaction OpenAI](/uk/providers/openai#server-side-compaction-responses-api). - `params`: глобальні типові параметри провайдера, що застосовуються до всіх моделей. Задаються в `agents.defaults.params` (наприклад, `{ cacheRetention: "long" }`). -- Пріоритет злиття `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключами. Докладніше див. у [Кешування запитів](/uk/reference/prompt-caching). -- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Використовуйте `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness брати на себе підтримувані моделі, `runtime: "pi"`, щоб примусово використовувати вбудований harness PI, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Автоматичне резервне перемикання на PI типово дорівнює `"pi"` лише в режимі `auto`. Явні середовища виконання Plugin, такі як `codex`, типово мають `"none"`, якщо ви не задасте `fallback: "pi"`. Нові конфігурації harness Codex мають зберігати посилання на моделі в канонічному вигляді `openai/*` і вибирати harness тут, а не використовувати застарілі посилання на моделі `codex/*`. -- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних варіантів. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сеансами (кожен сеанс усе одно серіалізується). Типове значення: 4. +- Порядок об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для конкретної моделі), а потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає значення за ключами. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). +- `embeddedHarness`: типова політика низькорівневого середовища виконання для вбудованого агента. Якщо `runtime` пропущено, типовим є OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово застосовувати вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness у Plugin перехоплювати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід до PI. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси провайдера runtime. +- Засоби запису конфігурації, які змінюють ці поля (наприклад, `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних моделей. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно виконується послідовно). Типове значення: 4. ### `agents.defaults.embeddedHarness` -`embeddedHarness` керує тим, який низькорівневий виконавець запускає ходи вбудованого агента. -У більшості розгортань слід залишити типове значення `{ runtime: "auto", fallback: "pi" }`. -Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований -harness app-server Codex. +`embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. +У більшості розгортань слід залишити типовий runtime OpenClaw Pi. +Використовуйте це, коли довірений Plugin надає нативний harness, наприклад вбудований +harness app-server для Codex. ```json5 { @@ -398,14 +398,14 @@ harness app-server Codex. } ``` -- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого Plugin harness. Вбудований Plugin Codex реєструє `codex`. -- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущений fallback типово дорівнює `"pi"`, щоб старі конфігурації могли й далі використовувати PI, коли жоден Plugin harness не бере запуск на себе. У режимі явного Plugin runtime, наприклад `runtime: "codex"`, пропущений fallback типово дорівнює `"none"`, щоб відсутній harness спричиняв помилку замість мовчазного використання PI. Перевизначення runtime не успадковують fallback із ширшої області; задайте `fallback: "pi"` разом із явним runtime, коли вам свідомо потрібен цей сумісний резервний варіант. Збої вибраного Plugin harness завжди відображаються безпосередньо. -- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає fallback для цього процесу. -- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності також можна явно задати `embeddedHarness.fallback: "none"`; це типове значення для явних Plugin runtime. -- Вибір harness фіксується для кожного ідентифікатора сеансу після першого вбудованого запуску. Зміни конфігурації/змінних середовища впливають на нові або скинуті сеанси, а не на наявну стенограму. Застарілі сеанси з історією стенограми, але без зафіксованого вибору, вважаються прив’язаними до PI. `/status` показує не-PI ідентифікатори harness, такі як `codex`, поруч із `Fast`. -- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS усе ще використовують свої параметри провайдера/моделі. +- `runtime`: `"auto"`, `"pi"` або ідентифікатор зареєстрованого harness у Plugin. Вбудований Plugin Codex реєструє `codex`. +- `fallback`: `"pi"` або `"none"`. У режимі `runtime: "auto"` пропущене значення `fallback` типово дорівнює `"pi"`, щоб старі конфігурації могли й надалі використовувати PI, коли жоден harness у Plugin не перехоплює запуск. У режимі явного runtime Plugin, наприклад `runtime: "codex"`, пропущене значення `fallback` типово дорівнює `"none"`, щоб відсутність harness спричиняла помилку, а не тихе використання PI. Перевизначення runtime не успадковують `fallback` із ширшої області; задайте `fallback: "pi"` поруч із явним `runtime`, якщо вам навмисно потрібна така сумісність. Помилки вибраного harness Plugin завжди показуються безпосередньо. +- Перевизначення через змінні середовища: `OPENCLAW_AGENT_RUNTIME=` перевизначає `runtime`; `OPENCLAW_AGENT_HARNESS_FALLBACK=pi|none` перевизначає `fallback` для цього процесу. +- Для розгортань лише з Codex установіть `model: "openai/gpt-5.5"` і `embeddedHarness.runtime: "codex"`. Для читабельності ви також можете явно встановити `embeddedHarness.fallback: "none"`; це типове значення для явних runtime Plugin. +- Вибір harness закріплюється за ідентифікатором сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, а не на наявну транскрипцію. Застарілі сесії з історією транскрипції, але без зафіксованого закріплення, вважаються закріпленими за PI. `/status` показує ідентифікатори harness, відмінні від PI, наприклад `codex`, поруч із `Fast`. +- Це керує лише harness вбудованого чату. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують власні налаштування провайдера/моделі. -**Вбудовані скорочення-псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочені псевдоніми** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): | Псевдонім | Модель | | ------------------- | -------------------------------------------------- | @@ -420,13 +420,13 @@ harness app-server Codex. Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. -Для моделей Z.AI GLM-4.x режим thinking вмикається автоматично, якщо ви не задасте `--thinking off` або самостійно не визначите `agents.defaults.models["zai/"].params.thinking`. -Для моделей Z.AI типово вмикається `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. -Для моделей Anthropic Claude 4.6 типово використовується thinking `adaptive`, якщо явний рівень thinking не задано. +Для моделей Z.AI GLM-4.x режим мислення автоматично вмикається, якщо ви не задасте `--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`, якщо явний рівень мислення не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери відмовляють. ```json5 { @@ -454,13 +454,13 @@ harness app-server Codex. } ``` -- CLI-бекенди орієнтовані насамперед на текст; інструменти завжди вимкнені. -- Сеанси підтримуються, коли задано `sessionArg`. -- Наскрізна передача зображень підтримується, коли `imageArg` приймає шляхи до файлів. +- CLI-бекенди насамперед орієнтовані на текст; інструменти завжди вимкнені. +- Сесії підтримуються, коли задано `sessionArg`. +- Передавання зображень підтримується, коли `imageArg` приймає шляхи до файлів. ### `agents.defaults.systemPromptOverride` -Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для конкретного агента (`agents.list[].systemPromptOverride`). Значення для конкретного агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -474,7 +474,7 @@ harness app-server Codex. ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запитів, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки між провайдерами; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -490,9 +490,9 @@ harness app-server Codex. } ``` -- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії. +- `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. - `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. +- Застаріле `plugins.entries.openai.config.personality` усе ще читається, якщо цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -506,9 +506,9 @@ harness app-server Codex. every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // типово: true; false не додає розділ Heartbeat до системного запиту + includeSystemPromptSection: true, // типово: true; false пропускає секцію Heartbeat у системному запиті lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору - isolatedSession: false, // типово: false; true запускає кожен heartbeat у новому сеансі (без історії розмови) + isolatedSession: false, // типово: false; true запускає кожен heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", directPolicy: "allow", // allow (типово) | block @@ -523,15 +523,15 @@ harness app-server Codex. } ``` -- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація API-ключем) або `1h` (автентифікація OAuth). Установіть `0m`, щоб вимкнути. -- `includeSystemPromptSection`: коли `false`, не додає розділ Heartbeat до системного запиту та пропускає додавання `HEARTBEAT.md` до bootstrap-контексту. Типове значення: `true`. -- `suppressToolErrorWarnings`: коли `true`, пригнічує корисні навантаження з попередженнями про помилки інструментів під час запусків heartbeat. -- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після чого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. -- `directPolicy`: політика доставки напряму/в особисті повідомлення. `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-ключ) або `1h` (автентифікація через OAuth). Установіть `0m`, щоб вимкнути. +- `includeSystemPromptSection`: якщо `false`, пропускає секцію Heartbeat у системному запиті та не впроваджує `HEARTBEAT.md` у bootstrap-контекст. Типове значення: `true`. +- `suppressToolErrorWarnings`: якщо `true`, приглушує вміст попереджень про помилки інструментів під час запусків heartbeat. +- `timeoutSeconds`: максимальний час у секундах, дозволений для одного ходу агента heartbeat, після якого його буде перервано. Якщо не задано, використовується `agents.defaults.timeoutSeconds`. +- `directPolicy`: політика прямої доставки/DM. `allow` (типово) дозволяє доставку до прямої цілі. `block` приглушує доставку до прямої цілі та видає `reason=dm-blocked`. +- `lightContext`: якщо `true`, запуски heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. +- `isolatedSession`: якщо `true`, кожен heartbeat запускається в новій сесії без попередньої історії розмови. Така сама схема ізоляції, як у Cron `sessionTarget: "isolated"`. Зменшує вартість одного heartbeat у токенах приблизно зі ~100K до ~2-5K токенів. +- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо будь-який агент визначає `heartbeat`, heartbeat запускаються **лише для цих агентів**. +- Heartbeat запускає повноцінні ходи агента — коротші інтервали витрачають більше токенів. ### `agents.defaults.compaction` @@ -541,14 +541,14 @@ harness app-server Codex. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id зареєстрованого Plugin-провайдера compaction (необов’язково) + provider: "my-provider", // id зареєстрованого Plugin провайдера compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, identifierPolicy: "strict", // strict | off | custom identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom - postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне додавання + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне впровадження model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для compaction - notifyUser: true, // надсилати короткі сповіщення, коли compaction починається і завершується (типово: false) + notifyUser: true, // надсилати короткі сповіщення користувачу на початку і після завершення compaction (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -562,18 +562,18 @@ harness app-server Codex. ``` - `mode`: `default` або `safeguard` (підсумовування довгої історії частинами). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin-провайдера compaction. Якщо задано, замість вбудованого LLM-підсумовування викликається `summarize()` провайдера. У разі збою повертається до вбудованого варіанта. Установлення провайдера примусово вмикає `mode: "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 для збереження тривалої пам’яті. Пропускається, коли робочий простір доступний лише для читання. +- `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 для збереження довготривалих спогадів. Пропускається, якщо робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сеансу на диску. +Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -598,7 +598,7 @@ harness app-server Codex. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання можна запускати знову (після останнього торкання кешу). +- `ttl` визначає, як часто обрізання може запускатися знову (після останнього торкання кешу). - Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. @@ -607,13 +607,13 @@ harness app-server Codex. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. +- Блоки зображень ніколи не обрізаються і не очищаються. - Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. - Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. -Докладніше про поведінку див. у [Обрізання сеансу](/uk/concepts/session-pruning). +Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning). ### Блокове потокове передавання @@ -632,10 +632,10 @@ harness app-server Codex. ``` - Канали, крім Telegram, потребують явного `*.blockStreaming: true`, щоб увімкнути блокові відповіді. -- Перевизначення каналу: `channels..blockStreamingCoalesce` (і варіанти для конкретних облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. -- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500 мс. Перевизначення для конкретного агента: `agents.list[].humanDelay`. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типово `minChars: 1500`. +- `humanDelay`: випадкова пауза між блоковими відповідями. `natural` = 800–2500ms. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Докладніше про поведінку й розбиття на фрагменти див. у [Потокове передавання](/uk/concepts/streaming). +Докладніше про поведінку та розбиття на частини див. у [Потокове передавання](/uk/concepts/streaming). ### Індикатори набору тексту @@ -650,16 +650,16 @@ harness app-server Codex. } ``` -- Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. -- Перевизначення для сеансу: `session.typingMode`, `session.typingIntervalSeconds`. +- Типові значення: `instant` для прямих чатів/згадувань, `message` для групових чатів без згадки. +- Перевизначення на рівні сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору тексту](/uk/concepts/typing-indicators). +Докладніше див. у [Індикатори набору тексту](/uk/concepts/typing-indicators). ### `agents.defaults.sandbox` -Необов’язкова sandbox-ізоляція для вбудованого агента. Повний посібник див. у [Sandboxing](/uk/gateway/sandboxing). +Необов’язкова пісочниця для вбудованого агента. Повний посібник див. у [Пісочниця](/uk/gateway/sandboxing). ```json5 { @@ -754,7 +754,7 @@ harness app-server Codex. } ``` - + **Бекенд:** @@ -762,16 +762,16 @@ harness app-server Codex. - `ssh`: універсальне віддалене середовище виконання на основі SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, налаштування, специфічні для середовища виконання, переміщуються до +Коли вибрано `backend: "openshell"`, специфічні для цього runtime налаштування переносяться до `plugins.entries.openshell.config`. **Конфігурація SSH-бекенда:** - `target`: SSH-ціль у форматі `user@host[:port]` - `command`: команда SSH-клієнта (типово: `ssh`) -- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області -- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, що передаються в OpenSSH -- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує в тимчасові файли під час виконання +- `workspaceRoot`: абсолютний віддалений корінь, що використовується для робочих просторів у межах області дії +- `identityFile` / `certificateFile` / `knownHostsFile`: наявні локальні файли, які передаються до OpenSSH +- `identityData` / `certificateData` / `knownHostsData`: вбудований вміст або SecretRef, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет автентифікації SSH:** @@ -779,27 +779,27 @@ harness app-server Codex. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data`, що базуються на SecretRef, визначаються з активного знімка середовища виконання секретів до початку сеансу sandbox +- Значення `*Data` на основі SecretRef визначаються з активного знімка runtime секретів до початку сесії пісочниці **Поведінка SSH-бекенда:** - один раз ініціалізує віддалений робочий простір після створення або повторного створення -- потім підтримує віддалений робочий простір SSH як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH -- не синхронізує віддалені зміни назад на хост автоматично +- потім зберігає віддалений робочий простір як канонічний +- маршрутизує `exec`, файлові інструменти та шляхи медіафайлів через SSH +- не синхронізує зміни з віддаленого середовища назад на хост автоматично - не підтримує браузерні контейнери sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox у межах області під `~/.openclaw/sandboxes` +- `none`: робочий простір sandbox у межах області дії під `~/.openclaw/sandboxes` - `ro`: робочий простір sandbox у `/workspace`, робочий простір агента змонтовано лише для читання в `/agent` - `rw`: робочий простір агента змонтовано для читання/запису в `/workspace` -**Область:** +**Область дії:** -- `session`: окремий контейнер і робочий простір для кожного сеансу -- `agent`: один контейнер і робочий простір на агента (типово) -- `shared`: спільний контейнер і робочий простір (без ізоляції між сеансами) +- `session`: окремий контейнер і робочий простір для кожної сесії +- `agent`: один контейнер і робочий простір для кожного агента (типово) +- `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -829,29 +829,29 @@ harness app-server Codex. **Режим OpenShell:** -- `mirror`: ініціалізує віддалене середовище з локального перед `exec`, синхронізує назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: один раз ініціалізує віддалене середовище, коли створюється sandbox, після чого віддалений робочий простір залишається канонічним +- `mirror`: ініціалізує віддалене середовище з локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалене середовище під час створення sandbox, а потім зберігає віддалений робочий простір як канонічний -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспортом є SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою синхронізацією mirror керує Plugin. +У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після етапу ініціалізації. +Транспортом є SSH до sandbox OpenShell, але Plugin керує життєвим циклом sandbox і необов’язковою синхронізацією в режимі mirror. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного доступу до мережі, кореневої файлової системи з можливістю запису та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує мережевого виходу, доступного для запису кореня та користувача root. -**Типово контейнери мають `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не задасте -`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний варіант). +**Для контейнерів типовим є `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите +`sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний обхід). -**Вхідні вкладення** розміщуються у `media/inbound/*` в активному робочому просторі. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для конкретного агента об’єднуються. +**`docker.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 впроваджується в системний запит. Не потребує `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` для контейнера браузера. +- `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=` @@ -871,29 +871,29 @@ 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` знову вмикає розширення, якщо вони + потрібні вашому робочому процесу. - `--renderer-process-limit=2` можна змінити через `OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=`; установіть `0`, щоб використовувати типове обмеження процесів Chromium. - а також `--no-sandbox` і `--disable-setuid-sandbox`, коли ввімкнено `noSandbox`. - - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний - образ браузера з власним entrypoint. + - Типові значення є базовими для образу контейнера; щоб змінити типові параметри контейнера, використовуйте власний браузерний образ із власним + entrypoint. -Ізоляція браузера та `sandbox.docker.binds` доступні лише для Docker. +Пісочниця браузера та `sandbox.docker.binds` підтримуються лише для Docker. -Збірка образів: +Зібрати образи: ```bash scripts/sandbox-setup.sh # основний образ sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` -### `agents.list` (перевизначення для конкретного агента) +### `agents.list` (перевизначення для окремого агента) ```json5 { @@ -906,11 +906,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } - thinkingDefault: "high", // перевизначення рівня thinking для конкретного агента - reasoningDefault: "on", // перевизначення видимості reasoning для конкретного агента - fastModeDefault: false, // перевизначення fast mode для конкретного агента + thinkingDefault: "high", // перевизначення типового рівня мислення для окремого агента + reasoningDefault: "on", // перевизначення типової видимості міркувань для окремого агента + fastModeDefault: false, // перевизначення типового швидкого режиму для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає ключі у відповідних defaults.models params + params: { cacheRetention: "none" }, // перевизначає ключі відповідних params у defaults.models skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", @@ -943,26 +943,26 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ``` - `id`: стабільний ідентифікатор агента (обов’язково). -- `default`: якщо задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим буде перший елемент списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні варіанти). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні варіанти, якщо не задати `fallbacks: []`. -- `params`: параметри потоку для конкретного агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для перевизначень на рівні агента, таких як `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `skills`: необов’язковий список дозволених Skills для конкретного агента. Якщо не задано, агент успадковує `agents.defaults.skills`, коли він заданий; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для конкретного агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення на рівні повідомлення або сеансу. -- `reasoningDefault`: необов’язкове типове значення видимості reasoning для конкретного агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning на рівні повідомлення або сеансу. -- `fastModeDefault`: необов’язкове типове значення fast mode для конкретного агента (`true | false`). Застосовується, коли не задано перевизначення fast mode на рівні повідомлення або сеансу. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для конкретного агента. Використовуйте `{ runtime: "codex" }`, щоб зробити одного агента лише Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI в режимі `auto`. -- `runtime`: необов’язковий дескриптор середовища виконання для конкретного агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сеанси harness ACP. +- `default`: якщо задано для кількох, перемагає перший (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Cron-завдання, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо не встановити `fallbacks: []`. +- `params`: параметри потоку для окремого агента, об’єднані поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, як-от `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо пропущено, агент успадковує `agents.defaults.skills`, якщо їх задано; явний список замінює типові значення, а не об’єднується з ними, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень мислення для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, якщо не задано перевизначення для конкретного повідомлення або сесії. +- `reasoningDefault`: необов’язкове типове значення видимості міркувань для окремого агента (`on | off | stream`). Застосовується, якщо не задано перевизначення міркувань для конкретного повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення швидкого режиму для окремого агента (`true | false`). Застосовується, якщо не задано перевизначення швидкого режиму для конкретного повідомлення або сесії. +- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише Codex, тоді як інші агенти зберігатимуть типовий резервний PI у режимі `auto`. +- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент повинен типово працювати із сесіями harness ACP. - `identity.avatar`: шлях відносно робочого простору, URL `http(s)` або URI `data:`. - `identity` виводить типові значення: `ackReaction` з `emoji`, `mentionPatterns` з `name`/`emoji`. - `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сеанс-ініціатор працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. -- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких пропущено `agentId` (примушує до явного вибору профілю; типово: false). +- Захист успадкування sandbox: якщо сесія-запитувач працює в sandbox, `sessions_spawn` відхиляє цілі, які працювали б без sandbox. +- `subagents.requireAgentId`: якщо `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація між кількома агентами -Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Багатоагентність](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -979,29 +979,29 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля зіставлення прив’язки +### Поля відповідності binding -- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип не вказано, типовим є route), `acp` для постійних binding розмов ACP. - `match.channel` (обов’язково) -- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо не вказано = типовий обліковий запис) +- `match.accountId` (необов’язково; `*` = будь-який обліковий запис; якщо пропущено = типовий обліковий запис) - `match.peer` (необов’язково; `{ kind: direct|group|channel, id }`) -- `match.guildId` / `match.teamId` (необов’язково; залежить від каналу) +- `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) -5. `match.accountId: "*"` (на рівні всього каналу) +5. `match.accountId: "*"` (на весь канал) 6. Типовий агент -У межах кожного рівня перший відповідний запис у `bindings` має пріоритет. +У межах кожного рівня перемагає перший відповідний запис `bindings`. -Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів прив’язки route. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує наведений вище порядок рівнів route binding. -### Профілі доступу для конкретних агентів +### Профілі доступу для окремих агентів @@ -1096,7 +1096,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Докладніше про пріоритети див. у [Sandbox і інструменти в багатоагентному режимі](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Пісочниця й інструменти Multi-Agent](/uk/tools/multi-agent-sandbox-tools). --- @@ -1122,22 +1122,22 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, resetTriggers: ["/new", "/reset"], store: "~/.openclaw/agents/{agentId}/sessions/sessions.json", - parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables) + parentForkMaxTokens: 100000, // пропускати відгалуження від батьківської гілки вище цієї кількості токенів (0 вимикає) maintenance: { mode: "warn", // warn | enforce pruneAfter: "30d", maxEntries: 500, rotateBytes: "10mb", - resetArchiveRetention: "30d", // duration or false - maxDiskBytes: "500mb", // optional hard budget - highWaterBytes: "400mb", // optional cleanup target + resetArchiveRetention: "30d", // тривалість або false + maxDiskBytes: "500mb", // необов’язковий жорсткий бюджет + highWaterBytes: "400mb", // необов’язкова ціль очищення }, threadBindings: { enabled: true, - idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables) - maxAgeHours: 0, // default hard max age in hours (`0` disables) + idleHours: 24, // типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає) + maxAgeHours: 0, // типова жорстка максимальна давність у годинах (`0` вимикає) }, - mainKey: "main", // legacy (runtime always uses "main") + mainKey: "main", // застаріле поле (runtime завжди використовує "main") agentToAgent: { maxPingPongTurns: 5 }, sendPolicy: { rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }], @@ -1147,37 +1147,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + -- **`scope`**: базова стратегія групування сеансів для контекстів групового чату. - - `per-sender` (типово): кожен відправник отримує ізольований сеанс у межах контексту каналу. - - `global`: усі учасники в контексті каналу спільно використовують один сеанс (використовуйте лише тоді, коли потрібен спільний контекст). -- **`dmScope`**: як групуються особисті повідомлення. - - `main`: усі особисті повідомлення використовують головний сеанс. +- **`scope`**: базова стратегія групування сесій для контекстів групового чату. + - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. + - `global`: усі учасники в контексті каналу спільно використовують одну сесію (використовуйте лише тоді, коли потрібен спільний контекст). +- **`dmScope`**: спосіб групування DM. + - `main`: усі DM використовують спільну основну сесію. - `per-peer`: ізоляція за ідентифікатором відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для спільних вхідних). + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких вхідних скриньок). - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних ідентифікаторів на peer-ідентифікатори з префіксом провайдера для спільного використання сеансів між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва варіанти, спрацьовує той, що завершується раніше. -- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальне значення `totalTokens` батьківського сеансу, дозволене під час створення розгалуженого сеансу потоку (типово `100000`). - - Якщо `totalTokens` батьківського сеансу перевищує це значення, OpenClaw запускає новий сеанс потоку замість успадкування історії стенограми батьківського сеансу. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківського сеансу. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного сегмента особистого чату. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у зворотному ланцюжку між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ping-pong-ланцюжок. +- **`identityLinks`**: мапа канонічних ідентифікаторів до peer із префіксом провайдера для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що настає раніше. +- **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застаріле `dm` приймається як псевдонім для `direct`. +- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` у батьківській сесії, дозволена під час створення відгалуженої сесії потоку (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії транскрипції батьківської сесії. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти відгалуження від батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика прямих чатів. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість зворотних ходів між агентами під час взаємодії агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. - **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. -- **`maintenance`**: очищення сховища сеансів + параметри зберігання. +- **`maintenance`**: очищення сховища сесій і керування збереженням. - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг давності для застарілих записів (типово `30d`). + - `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`: термін зберігання архівів транскрипцій `*.reset.`. Типово дорівнює `pruneAfter`; установіть `false`, щоб вимкнути. + - `maxDiskBytes`: необов’язковий дисковий бюджет для каталогу сесій. У режимі `warn` це записує попередження в журнал; у режимі `enforce` спочатку видаляються найстаріші артефакти/сесії. + - `highWaterBytes`: необов’язкова ціль після очищення за бюджетом. Типово дорівнює `80%` від `maxDiskBytes`. +- **`threadBindings`**: глобальні типові значення для можливостей сесій, прив’язаних до потоків. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокусу після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типова жорстка максимальна давність у годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1188,7 +1188,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б ```json5 { messages: { - responsePrefix: "🦞", // or "auto" + responsePrefix: "🦞", // або "auto" ackReaction: "👀", ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all removeAckAfterReply: false, @@ -1203,7 +1203,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 вимикає byChannel: { whatsapp: 5000, slack: 1500, @@ -1217,7 +1217,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Порядок визначення значення (найспецифічніше має пріоритет): обліковий запис → канал → глобальне. `""` вимикає та зупиняє каскад. `"auto"` формує `[{identity.name}]`. +Визначення значення (найспецифічніше перемагає): обліковий запис → канал → глобальне. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** @@ -1226,27 +1226,27 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б | `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | | `{provider}` | Назва провайдера | `anthropic` | -| `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{thinkingLevel}` | Поточний рівень мислення | `high`, `low`, `off` | +| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | -Змінні нечутливі до регістру. `{think}` — псевдонім для `{thinkingLevel}`. +Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. -### Реакція-підтвердження +### Реакція підтвердження -- Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. +- Типово використовує `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. - Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. -- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді у Slack, Discord і Telegram. +- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження. + У Slack і Discord, якщо значення не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. У Telegram установіть це значення явно в `true`, щоб увімкнути реакції статусу життєвого циклу. -### Inbound debounce +### Debounce для вхідних повідомлень -Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди оминають debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Керівні команди обходять debounce. -### TTS (перетворення тексту на мовлення) +### TTS (синтез мовлення) ```json5 { @@ -1289,16 +1289,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - `auto` керує типовим режимом автоматичного TTS: `off`, `always`, `inbound` або `tagged`. `/tts on|off` може перевизначати локальні налаштування, а `/tts status` показує фактичний стан. - `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. -- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (лише за явної згоди). -- Для API-ключів резервно використовуються `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (лише за явного ввімкнення). +- 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 сервер і послаблює перевірку моделі/голосу. +- Коли `openai.baseUrl` вказує на endpoint, відмінний від OpenAI, OpenClaw трактує його як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. --- -## Talk +## Розмова -Типові значення для режиму Talk (macOS/iOS/Android). +Типові значення для режиму розмови (macOS/iOS/Android). ```json5 { @@ -1322,18 +1322,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька провайдерів Talk. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються до `talk.providers.`. -- Для ідентифікаторів голосу резервно використовуються `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.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються в `talk.providers.`. +- Ідентифікатори голосів беруться з резервних значень `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `providers.*.apiKey` приймає текстові рядки або об’єкти SecretRef. +- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ режиму розмови не налаштовано. +- `providers.*.voiceAliases` дозволяє директивам режиму розмови використовувати дружні назви. +- `silenceTimeoutMs` визначає, скільки часу режим розмови чекає після тиші користувача, перш ніж надіслати транскрипцію. Якщо не задано, зберігається типове для платформи вікно паузи (`700 ms на macOS і Android, 900 ms на iOS`). --- -## Пов’язані матеріали +## Пов’язане - [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації -- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування +- [Конфігурація](/uk/gateway/configuration) — типові завдання та швидке налаштування - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/help/testing.md b/docs/uk/help/testing.md index 11df82be8..a70ecad64 100644 --- a/docs/uk/help/testing.md +++ b/docs/uk/help/testing.md @@ -1,204 +1,241 @@ --- read_when: - Запуск тестів локально або в CI - - Додавання регресійних тестів для багів моделі/провайдера + - Додавання регресій для помилок моделі/провайдера - Налагодження поведінки Gateway + агента -summary: 'Набір для тестування: unit/e2e/live набори, Docker runners і що саме охоплює кожен тест' +summary: 'Набір для тестування: модульні/e2e/live набори, ранери Docker і що охоплює кожен тест' title: Тестування x-i18n: - generated_at: "2026-04-24T22:51:38Z" + generated_at: "2026-04-25T00:01:10Z" model: gpt-5.4 provider: openai - source_hash: d8d70027f15c4e12198d6e8fa8cb74086c30dd405d6681d78ecb811bd448e838 + source_hash: b3bd1ab654b43a380c6eecb3ba53e74442bad9374be4eea2d9ce368d8b89b7c2 source_path: help/testing.md workflow: 15 --- -OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір Docker runners. Цей документ — посібник «як ми тестуємо»: +OpenClaw має три набори Vitest (unit/integration, e2e, live) і невеликий набір +ранерів Docker. Цей документ — посібник «як ми тестуємо»: - Що охоплює кожен набір (і що він навмисно _не_ охоплює). -- Які команди запускати для типових сценаріїв роботи (локально, перед push, налагодження). +- Які команди запускати для типових сценаріїв (локально, перед push, налагодження). - Як live-тести знаходять облікові дані та вибирають моделі/провайдерів. -- Як додавати регресійні тести для реальних проблем із моделями/провайдерами. +- Як додавати регресії для реальних проблем моделей/провайдерів. ## Швидкий старт У більшості випадків: - Повний gate (очікується перед push): `pnpm build && pnpm check && pnpm check:test-types && pnpm test` -- Швидший локальний запуск усього набору на потужній машині: `pnpm test:max` +- Швидший локальний запуск повного набору на потужній машині: `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 lane на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` +- Під час ітерації над однією помилкою спочатку віддавайте перевагу цільовим запускам. +- Сайт QA на базі Docker: `pnpm qa:lab:up` +- Лінія QA на базі Linux VM: `pnpm openclaw qa suite --runner multipass --scenario channel-chat-baseline` -Коли ви змінюєте тести або хочете більшої впевненості: +Коли ви змінюєте тести або хочете додаткової впевненості: -- Gate покриття: `pnpm test:coverage` +- Перевірка coverage: `pnpm test:coverage` - Набір E2E: `pnpm test:e2e` Під час налагодження реальних провайдерів/моделей (потрібні реальні облікові дані): -- Live-набір (моделі + перевірки інструментів/зображень Gateway): `pnpm test:live` -- Цільовий запуск одного live-файлу в тихому режимі: `pnpm test:live -- src/agents/models.profiles.live.test.ts` +- Live-набір (моделі + Gateway tool/image probes): `pnpm test:live` +- Тихо запустити один live-файл: `pnpm test:live -- src/agents/models.profiles.live.test.ts` - Docker live model sweep: `pnpm test:docker:live-models` - - Кожна вибрана модель тепер виконує текстовий хід плюс невелику перевірку у стилі читання файлу. - Моделі, чиї метадані оголошують вхід `image`, також виконують невеликий хід із зображенням. - Вимкніть додаткові перевірки через `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або + - Кожна вибрана модель тепер запускає текстовий хід плюс невеликий probe у стилі читання файла. + Моделі, метадані яких оголошують вхід `image`, також запускають невеликий хід із зображенням. + Вимкніть додаткові probe за допомогою `OPENCLAW_LIVE_MODEL_FILE_PROBE=0` або `OPENCLAW_LIVE_MODEL_IMAGE_PROBE=0`, коли ізолюєте збої провайдера. - - Покриття в CI: щоденні `OpenClaw Scheduled Live And E2E Checks` і ручні + - Покриття в CI: щоденний `OpenClaw Scheduled Live And E2E Checks` і ручний `OpenClaw Release Checks` обидва викликають повторно використовуваний workflow live/E2E з - `include_live_suites: true`, що включає окремі матричні jobs Docker live model, - розбиті за провайдером. - - Для точкових повторних запусків у CI запустіть `OpenClaw Live And E2E Checks (Reusable)` + `include_live_suites: true`, який включає окремі Docker live model + matrix jobs, розшардовані за провайдером. + - Для цільових повторних запусків у 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` і його + - Додавайте нові високосигнальні секрети провайдерів до `scripts/ci-hydrate-live-auth.sh`, + а також до `.github/workflows/openclaw-live-and-e2e-checks-reusable.yml` і його викликів для scheduled/release. - Native Codex bound-chat smoke: `pnpm test:docker:live-codex-bind` - - Запускає Docker live lane проти шляху app-server Codex, прив’язує синтетичний + - Запускає Docker live lane для шляху Codex app-server, прив’язує синтетичний Slack DM через `/codex bind`, виконує `/codex fast` і - `/codex permissions`, а потім перевіряє, що звичайна відповідь і вкладення із зображенням - маршрутизуються через нативну прив’язку plugin, а не через ACP. + `/codex permissions`, потім перевіряє, що звичайна відповідь і вкладення + зображення проходять через native plugin binding, а не через ACP. - Moonshot/Kimi cost smoke: якщо встановлено `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`. + проти `moonshot/kimi-k2.6`. Переконайтеся, що JSON повідомляє Moonshot/K2.6, а + транскрипт асистента зберігає нормалізоване `usage.cost`. -Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через змінні середовища allowlist, описані нижче. +Порада: коли вам потрібен лише один збійний випадок, віддавайте перевагу звуженню live-тестів через env-змінні allowlist, описані нижче. -## Runner-и, специфічні для QA +## Спеціальні ранери QA -Ці команди розташовані поруч з основними наборами тестів, коли вам потрібен реалізм QA-lab: +Ці команди розташовані поруч з основними тестовими наборами, коли вам потрібна реалістичність qa-lab: -CI запускає QA Lab в окремих workflow. `Parity gate` запускається на відповідних PR і -з ручного dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на -`main` і з ручного dispatch із mock parity gate, live Matrix lane та live Telegram lane під керуванням Convex як паралельними jobs. `OpenClaw Release Checks` -запускає ті самі lane-и перед погодженням релізу. +CI запускає QA Lab в окремих workflow. `Parity gate` запускається для відповідних PR і +через ручний dispatch із mock-провайдерами. `QA-Lab - All Lanes` запускається щоночі на +`main` і через ручний dispatch із mock parity gate, live Matrix lane і +керованою Convex live Telegram lane як паралельними jobs. `OpenClaw Release Checks` +запускає ті самі лінії перед погодженням релізу. - `pnpm openclaw qa suite` - Запускає сценарії QA на базі репозиторію безпосередньо на хості. - За замовчуванням запускає кілька вибраних сценаріїв паралельно з ізольованими - worker-ами Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежену + worker Gateway. `qa-channel` за замовчуванням має concurrency 4 (обмежується кількістю вибраних сценаріїв). Використовуйте `--concurrency `, щоб налаштувати - кількість worker-ів, або `--concurrency 1` для старого послідовного lane. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. - - Підтримує режими провайдера `live-frontier`, `mock-openai` і `aimock`. + кількість worker, або `--concurrency 1` для старішої послідовної лінії. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, коли + хочете отримати артефакти без коду завершення з помилкою. + - Підтримує режими провайдерів `live-frontier`, `mock-openai` і `aimock`. `aimock` запускає локальний сервер провайдера на базі AIMock для експериментального - покриття fixture і протокольних mock-ів без заміни сценарно-орієнтованого - lane `mock-openai`. + покриття фікстурами та protocol-mock, не замінюючи сценарно-орієнтовану + лінію `mock-openai`. - `pnpm openclaw qa suite --runner multipass` - - Запускає той самий QA-набір усередині тимчасової Linux VM Multipass. + - Запускає той самий набір QA всередині тимчасової Linux VM Multipass. - Зберігає ту саму поведінку вибору сценаріїв, що й `qa suite` на хості. - Повторно використовує ті самі прапорці вибору провайдера/моделі, що й `qa suite`. - - Live-запуски передають підтримувані QA-входи автентифікації, практичні для гостьової системи: - ключі провайдера на базі env, шлях до конфігурації QA live provider і `CODEX_HOME`, якщо він присутній. - - Каталоги виводу мають залишатися в межах кореня репозиторію, щоб гостьова система могла записувати назад через + - Live-запуски передають підтримувані вхідні дані автентифікації QA, практичні для guest: + ключі провайдера на основі env, шлях конфігурації QA live provider і `CODEX_HOME`, + якщо він присутній. + - Каталоги виводу мають залишатися під коренем репозиторію, щоб guest міг записувати назад через змонтований workspace. - - Записує звичайний QA report + summary, а також журнали Multipass у + - Записує звичайний звіт QA + summary, а також журнали 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 з API-ключем OpenAI, за замовчуванням налаштовує Telegram, + - Збирає npm tarball із поточного checkout, глобально встановлює його в + Docker, виконує неінтерактивний onboarding з OpenAI API key, за замовчуванням налаштовує Telegram, перевіряє, що ввімкнення plugin встановлює runtime dependencies на вимогу, - запускає doctor і виконує один локальний хід агента проти змоканого endpoint OpenAI. - - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити той самий - lane пакетного встановлення з Discord. + запускає doctor і виконує один локальний agent turn проти змоканого endpoint OpenAI. + - Використовуйте `OPENCLAW_NPM_ONBOARD_CHANNEL=discord`, щоб запустити ту саму + лінію інсталяції з пакета з Discord. - `pnpm test:docker:npm-telegram-live` - - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding для - встановленого пакета, налаштовує Telegram через встановлений CLI, а потім повторно використовує - QA lane live Telegram із цим встановленим пакетом як SUT Gateway. - - За замовчуванням використовує `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. + - Встановлює опублікований пакет OpenClaw у Docker, виконує onboarding встановленого пакета, + налаштовує Telegram через встановлений CLI, а потім повторно використовує + live Telegram QA lane з цим встановленим пакетом як Gateway SUT. + - За замовчуванням використовується `OPENCLAW_NPM_TELEGRAM_PACKAGE_SPEC=openclaw@beta`. - Використовує ті самі env-облікові дані Telegram або джерело облікових даних Convex, що й `pnpm openclaw qa telegram`. Для автоматизації CI/release встановіть - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` плюс - `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі. Якщо + `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_SOURCE=convex` разом із + `OPENCLAW_QA_CONVEX_SITE_URL` і секретом ролі. Якщо `OPENCLAW_QA_CONVEX_SITE_URL` і секрет ролі Convex присутні в CI, - Docker wrapper автоматично вибирає Convex. + обгортка Docker автоматично вибирає Convex. - `OPENCLAW_NPM_TELEGRAM_CREDENTIAL_ROLE=ci|maintainer` перевизначає спільний - `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цього lane. - - GitHub Actions надає цей lane як ручний workflow для супровідника - `NPM Telegram Beta E2E`. Він не запускається під час merge. Workflow використовує - середовище `qa-live-shared` і оренду CI-облікових даних Convex. + `OPENCLAW_QA_CREDENTIAL_ROLE` лише для цієї лінії. + - GitHub Actions надає цю лінію як ручний workflow для мейнтейнерів + `NPM Telegram Beta E2E`. Вона не запускається при merge. Workflow використовує + середовище `qa-live-shared` і оренду облікових даних Convex CI. - `pnpm test:docker:bundled-channel-deps` - - Пакує й установлює поточну збірку OpenClaw у Docker, запускає Gateway з налаштованим OpenAI, а потім вмикає bundled channel/plugin через редагування конфігурації. - - Перевіряє, що виявлення налаштування залишає runtime dependencies - неналаштованих plugin відсутніми, що перший налаштований запуск Gateway або doctor - встановлює runtime dependencies кожного bundled plugin на вимогу, і що другий перезапуск не перевстановлює залежності, які вже були активовані. - - Також установлює відому старішу npm baseline, вмикає Telegram перед запуском - `openclaw update --tag ` і перевіряє, що - `doctor` кандидата після оновлення відновлює bundled channel runtime dependencies без виправлення `postinstall` з боку harness. + - Пакує та встановлює поточну збірку OpenClaw у Docker, запускає Gateway + з налаштованим OpenAI, а потім вмикає вбудовані channel/plugins через редагування config. + - Перевіряє, що виявлення setup залишає runtime dependencies + неналаштованого plugin відсутніми, перший налаштований запуск Gateway або doctor встановлює + runtime dependencies кожного вбудованого plugin на вимогу, а другий перезапуск не + перевстановлює залежності, які вже були активовані. + - Також встановлює відому старішу npm baseline, вмикає Telegram перед запуском + `openclaw update --tag `, і перевіряє, що doctor кандидата + після оновлення відновлює runtime dependencies вбудованих channel без + відновлення postinstall з боку harness. +- `pnpm test:parallels:npm-update` + - Запускає native smoke оновлення встановленого пакета в гостьових системах Parallels. Кожна + вибрана платформа спочатку встановлює потрібний baseline package, потім запускає + встановлену команду `openclaw update` у тій самій guest-системі та перевіряє встановлену + версію, стан оновлення, готовність gateway і один локальний agent turn. + - Використовуйте `--platform macos`, `--platform windows` або `--platform linux`, коли + ітеруєте лише на одній guest-системі. Використовуйте `--json` для шляху до summary artifact і + стану кожної лінії. + - Обгорніть довгі локальні запуски в timeout на хості, щоб зависання транспорту Parallels не + поглинало решту вікна тестування: + + ```bash + timeout --foreground 150m pnpm test:parallels:npm-update -- --json + timeout --foreground 90m pnpm test:parallels:npm-update -- --platform windows --json + ``` + + - Скрипт записує вкладені журнали ліній у `/tmp/openclaw-parallels-npm-update.*`. + Перегляньте `windows-update.log`, `macos-update.log` або `linux-update.log`, + перш ніж вважати, що зовнішня обгортка зависла. + - Оновлення Windows може витрачати 10–15 хвилин на post-update doctor/runtime + dependency repair на холодній guest-системі; це все ще нормально, якщо вкладений + журнал npm debug просувається. + - Не запускайте цю агреговану обгортку паралельно з окремими smoke-лініями Parallels + для macOS, Windows або Linux. Вони спільно використовують стан VM і можуть конфліктувати під час + відновлення snapshot, роздачі package або стану guest gateway. + - Доказ після оновлення запускає звичайну поверхню вбудованого plugin, оскільки + capability facades, такі як мовлення, генерація зображень і + розуміння медіа, завантажуються через вбудовані runtime API, навіть коли сам + agent turn перевіряє лише просту текстову відповідь. + - `pnpm openclaw qa aimock` - Запускає лише локальний сервер провайдера AIMock для прямого smoke-тестування протоколу. - `pnpm openclaw qa matrix` - Запускає live QA lane Matrix проти тимчасового homeserver Tuwunel на базі Docker. - - Цей QA-хост наразі призначений лише для repo/dev. Пакетні встановлення OpenClaw не постачають - `qa-lab`, тому вони не надають `openclaw qa`. - - Checkout-и репозиторію завантажують bundled runner безпосередньо; окремий крок встановлення plugin не потрібен. - - Надає три тимчасові користувачі Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній процес QA gateway із реальним plugin Matrix як транспортом SUT. - - За замовчуванням використовує зафіксований стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, якщо потрібно протестувати інший образ. - - Matrix не надає спільні прапорці джерела облікових даних, тому що lane локально створює тимчасових користувачів. - - Записує Matrix QA report, summary, артефакт observed-events і комбінований журнал виводу stdout/stderr до `.artifacts/qa-e2e/...`. - - За замовчуванням виводить прогрес і примусово застосовує жорсткий timeout виконання через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (типово 30 хвилин). Cleanup обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а помилки включають команду відновлення `docker compose ... down --remove-orphans`. + - Цей QA host наразі призначений лише для репозиторію/розробки. Встановлені пакети OpenClaw не постачають + `qa-lab`, тож вони не надають `openclaw qa`. + - Checkout репозиторію безпосередньо завантажують вбудований runner; окремий крок встановлення plugin не потрібен. + - Піднімає трьох тимчасових користувачів Matrix (`driver`, `sut`, `observer`) плюс одну приватну кімнату, а потім запускає дочірній QA gateway з реальним plugin Matrix як транспортом SUT. + - За замовчуванням використовує закріплений стабільний образ Tuwunel `ghcr.io/matrix-construct/tuwunel:v1.5.1`. Перевизначайте через `OPENCLAW_QA_MATRIX_TUWUNEL_IMAGE`, коли потрібно протестувати інший образ. + - Matrix не надає спільних прапорців джерела облікових даних, оскільки лінія локально створює тимчасових користувачів. + - Записує звіт Matrix QA, summary, артефакт observed-events і комбінований журнал виводу stdout/stderr у `.artifacts/qa-e2e/...`. + - За замовчуванням виводить прогрес і застосовує жорсткий timeout запуску через `OPENCLAW_QA_MATRIX_TIMEOUT_MS` (за замовчуванням 30 хвилин). Очищення обмежується `OPENCLAW_QA_MATRIX_CLEANUP_TIMEOUT_MS`, а збої включають команду відновлення `docker compose ... down --remove-orphans`. - `pnpm openclaw qa telegram` - - Запускає live QA lane Telegram проти реальної приватної групи, використовуючи токени ботів driver і SUT з env. + - Запускає live Telegram QA lane проти реальної приватної групи, використовуючи токени бота driver і SUT з env. - Потребує `OPENCLAW_QA_TELEGRAM_GROUP_ID`, `OPENCLAW_QA_TELEGRAM_DRIVER_BOT_TOKEN` і `OPENCLAW_QA_TELEGRAM_SUT_BOT_TOKEN`. Ідентифікатор групи має бути числовим Telegram chat id. - - Підтримує `--credential-source convex` для спільних пулів облікових даних. За замовчуванням використовуйте режим env, або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб перейти на pooled leases. - - Завершується з ненульовим кодом, якщо будь-який сценарій не вдається. Використовуйте `--allow-failures`, коли - вам потрібні артефакти без коду завершення з помилкою. + - Підтримує `--credential-source convex` для спільних пулів облікових даних. За замовчуванням використовуйте режим env або встановіть `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`, щоб увімкнути орендовані спільні облікові дані. + - Завершується з ненульовим кодом, якщо будь-який сценарій зазнає збою. Використовуйте `--allow-failures`, коли + хочете отримати артефакти без коду завершення з помилкою. - Потребує двох різних ботів в одній приватній групі, причому бот SUT має мати Telegram username. - - Для стабільного спостереження взаємодії між ботами увімкніть Bot-to-Bot Communication Mode у `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. - - Записує Telegram QA report, summary і артефакт observed-messages до `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. + - Для стабільного спостереження бот-до-бота увімкніть режим Bot-to-Bot Communication Mode в `@BotFather` для обох ботів і переконайтеся, що бот driver може спостерігати трафік ботів у групі. + - Записує звіт Telegram QA, summary і артефакт observed-messages у `.artifacts/qa-e2e/...`. Сценарії з відповідями включають RTT від запиту на надсилання driver до спостережуваної відповіді SUT. -Live transport lane-и мають спільний стандартний контракт, щоб нові транспорти не дрейфували: +Live transport lanes мають один стандартний контракт, щоб нові транспорти не розходилися в поведінці: -`qa-channel` залишається широким синтетичним QA-набором і не входить до матриці покриття live transport. +`qa-channel` залишається широким синтетичним набором QA і не є частиною матриці покриття live transport. -| Lane | Canary | Mention gating | Allowlist block | Top-level reply | Restart resume | Thread follow-up | Thread isolation | Reaction observation | Help command | -| -------- | ------ | -------------- | --------------- | --------------- | -------------- | ---------------- | ---------------- | -------------------- | ------------ | -| Matrix | x | x | x | x | x | x | x | x | | -| Telegram | x | | | | | | | | x | +| Лінія | Canary | Обмеження згадок | Блокування allowlist | Відповідь верхнього рівня | Відновлення після перезапуску | Подальша відповідь у треді | Ізоляція тредів | Спостереження за реакціями | Команда help | +| -------- | ------ | ---------------- | -------------------- | ------------------------- | ----------------------------- | -------------------------- | --------------- | -------------------------- | ------------ | +| Matrix | x | x | x | x | x | x | x | x | | +| Telegram | x | | | | | | | | x | ### Спільні облікові дані Telegram через Convex (v1) Коли для `openclaw qa telegram` увімкнено `--credential-source convex` (або `OPENCLAW_QA_CREDENTIAL_SOURCE=convex`), -QA lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat -для цієї оренди, поки lane виконується, і звільняє оренду під час завершення роботи. +qa-lab отримує ексклюзивну оренду з пулу на базі Convex, надсилає Heartbeat +для цієї оренди, поки лінія виконується, і звільняє оренду під час завершення роботи. Еталонний каркас проєкту Convex: - `qa/convex-credential-broker/` -Обов’язкові змінні середовища: +Обов’язкові env-змінні: -- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад `https://your-deployment.convex.site`) +- `OPENCLAW_QA_CONVEX_SITE_URL` (наприклад, `https://your-deployment.convex.site`) - Один секрет для вибраної ролі: - `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER` для `maintainer` - `OPENCLAW_QA_CONVEX_SECRET_CI` для `ci` - Вибір ролі облікових даних: - CLI: `--credential-role maintainer|ci` - - Типове значення env: `OPENCLAW_QA_CREDENTIAL_ROLE` (типово `ci` у CI, інакше `maintainer`) + - Значення env за замовчуванням: `OPENCLAW_QA_CREDENTIAL_ROLE` (у CI за замовчуванням `ci`, інакше `maintainer`) -Необов’язкові змінні середовища: +Необов’язкові env-змінні: -- `OPENCLAW_QA_CREDENTIAL_LEASE_TTL_MS` (типово `1200000`) -- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (типово `30000`) -- `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_LEASE_TTL_MS` (за замовчуванням `1200000`) +- `OPENCLAW_QA_CREDENTIAL_HEARTBEAT_INTERVAL_MS` (за замовчуванням `30000`) +- `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://` URL-адреси Convex лише для локальної розробки. +- `OPENCLAW_QA_ALLOW_INSECURE_HTTP=1` дозволяє loopback URL Convex `http://` лише для локальної розробки. `OPENCLAW_QA_CONVEX_SITE_URL` у звичайному режимі роботи має використовувати `https://`. -Команди адміністрування для супровідників (додавання/видалення/перелік пулу) потребують +Адміністративні команди для мейнтейнерів (додавання/видалення/перелік пулу) потребують саме `OPENCLAW_QA_CONVEX_SECRET_MAINTAINER`. -CLI-хелпери для супровідників: +Допоміжні CLI-команди для мейнтейнерів: ```bash pnpm openclaw qa credentials doctor @@ -208,7 +245,7 @@ pnpm openclaw qa credentials remove --credential-id ``` Використовуйте `doctor` перед live-запусками, щоб перевірити URL сайту Convex, секрети broker, -префікс endpoint, timeout HTTP і доступність admin/list без виведення +префікс endpoint, HTTP timeout і досяжність admin/list без виведення значень секретів. Використовуйте `--json` для машиночитного виводу в скриптах і утилітах CI. @@ -224,14 +261,14 @@ pnpm openclaw qa credentials remove --credential-id - `POST /release` - Запит: `{ kind, ownerId, actorRole, credentialId, leaseToken }` - Успіх: `{ status: "ok" }` (або порожній `2xx`) -- `POST /admin/add` (лише секрет супровідника) +- `POST /admin/add` (лише секрет maintainer) - Запит: `{ kind, actorId, payload, note?, status? }` - Успіх: `{ status: "ok", credential }` -- `POST /admin/remove` (лише секрет супровідника) +- `POST /admin/remove` (лише секрет maintainer) - Запит: `{ credentialId, actorId }` - Успіх: `{ status: "ok", changed, credential }` - Захист активної оренди: `{ status: "error", code: "LEASE_ACTIVE", ... }` -- `POST /admin/list` (лише секрет супровідника) +- `POST /admin/list` (лише секрет maintainer) - Запит: `{ kind?, status?, includePayload?, limit? }` - Успіх: `{ status: "ok", credentials, count }` @@ -245,53 +282,53 @@ pnpm openclaw qa credentials remove --credential-id Додавання каналу до markdown-системи QA потребує рівно двох речей: -1. Транспортного адаптера для каналу. -2. Набору сценаріїв, який перевіряє контракт каналу. +1. Адаптер транспорту для каналу. +2. Пакет сценаріїв, який перевіряє контракт каналу. Не додавайте новий кореневий QA-командний простір верхнього рівня, якщо спільний хост `qa-lab` може -керувати цим потоком. +обслуговувати цей потік. -`qa-lab` володіє спільною хост-механікою: +`qa-lab` відповідає за спільну хостову механіку: -- коренем команди `openclaw qa` -- запуском і завершенням набору -- concurrency worker-ів -- записом артефактів -- генерацією звітів -- виконанням сценаріїв -- псевдонімами сумісності для старіших сценаріїв `qa-channel` +- кореневий простір команд `openclaw qa` +- запуск і завершення набору +- concurrency worker +- запис артефактів +- генерацію звітів +- виконання сценаріїв +- сумісні alias для старіших сценаріїв `qa-channel` -Runner plugins володіють транспортним контрактом: +Runner plugins відповідають за транспортний контракт: - як `openclaw qa ` монтується під спільним коренем `qa` -- як Gateway налаштовується для цього транспорту +- як налаштовується gateway для цього транспорту - як перевіряється готовність - як інжектуються вхідні події - як спостерігаються вихідні повідомлення -- як надаються транскрипти й нормалізований стан транспорту +- як надаються транскрипти та нормалізований стан транспорту - як виконуються дії на основі транспорту -- як обробляється специфічний для транспорту reset або cleanup +- як обробляються специфічні для транспорту скидання або очищення -Мінімальний поріг впровадження для нового каналу такий: +Мінімальний поріг прийняття для нового каналу: -1. Зберігайте `qa-lab` як власника спільного кореня `qa`. -2. Реалізуйте transport runner на спільному seam хоста `qa-lab`. -3. Тримайте специфічну для транспорту механіку всередині runner plugin або harness каналу. -4. Монтуйте runner як `openclaw qa ` замість реєстрації конкуруючої кореневої команди. - Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` із `runtime-api.ts`. - Тримайте `runtime-api.ts` легким; відкладене виконання CLI і runner має залишатися за окремими entrypoint. +1. Залишайте `qa-lab` власником спільного кореня `qa`. +2. Реалізуйте transport runner на спільному хостовому шві `qa-lab`. +3. Залишайте специфічну для транспорту механіку всередині runner plugin або harness каналу. +4. Монтуйте runner як `openclaw qa `, а не реєструйте конкуруючу кореневу команду. + Runner plugins мають оголошувати `qaRunners` у `openclaw.plugin.json` і експортувати відповідний масив `qaRunnerCliRegistrations` з `runtime-api.ts`. + Залишайте `runtime-api.ts` легким; ліниве виконання CLI і runner має залишатися за окремими entrypoint. 5. Створюйте або адаптуйте markdown-сценарії в тематичних каталогах `qa/scenarios/`. -6. Використовуйте generic-хелпери сценаріїв для нових сценаріїв. -7. Зберігайте наявні псевдоніми сумісності робочими, якщо в репозиторії не виконується навмисна міграція. +6. Використовуйте загальні допоміжні функції сценаріїв для нових сценаріїв. +7. Зберігайте наявні alias сумісності працездатними, якщо тільки репозиторій не виконує навмисну міграцію. Правило прийняття рішення суворе: - Якщо поведінку можна один раз виразити в `qa-lab`, розміщуйте її в `qa-lab`. -- Якщо поведінка залежить від одного канального транспорту, тримайте її в runner plugin або harness цього plugin. -- Якщо сценарію потрібна нова можливість, яку може використовувати більше ніж один канал, додайте generic-хелпер замість специфічної для каналу гілки в `suite.ts`. -- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно зазначайте це в контракті сценарію. +- Якщо поведінка залежить від транспорту одного каналу, залишайте її в цьому runner plugin або harness plugin. +- Якщо сценарію потрібна нова можливість, яку можуть використовувати кілька каналів, додайте загальний helper замість специфічної для каналу гілки в `suite.ts`. +- Якщо поведінка має сенс лише для одного транспорту, залишайте сценарій специфічним для цього транспорту й явно позначайте це в контракті сценарію. -Бажані назви generic-хелперів для нових сценаріїв: +Бажані назви загальних helper для нових сценаріїв: - `waitForTransportReady` - `waitForChannelReady` @@ -306,7 +343,7 @@ Runner plugins володіють транспортним контрактом: - `formatTransportTranscript` - `resetTransport` -Для наявних сценаріїв залишаються доступними псевдоніми сумісності, зокрема: +Alias сумісності залишаються доступними для наявних сценаріїв, зокрема: - `waitForQaChannelReady` - `waitForOutboundMessage` @@ -314,227 +351,226 @@ Runner plugins володіють транспортним контрактом: - `formatConversationTranscript` - `resetBus` -Нова робота над каналами має використовувати generic-назви хелперів. -Псевдоніми сумісності існують, щоб уникнути одномоментної міграції, а не як модель для +Нова робота над каналами має використовувати загальні назви helper. +Alias сумісності існують, щоб уникнути міграції «в один день», а не як модель для створення нових сценаріїв. -## Набори тестів (що і де запускається) +## Набори тестів (що де запускається) -Думайте про набори як про «зростання реалізму» (і зростання flaky-поведінки/вартості): +Сприймайте набори як «зростаючий реалізм» (і зростаючу нестабільність/вартість): -### Unit / integration (типово) +### Unit / integration (за замовчуванням) - Команда: `pnpm test` -- Конфігурація: ненацілені запуски використовують набір shard `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації для кожного проєкту для паралельного планування -- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і whitelist-нуті node-тести `ui`, які охоплює `vitest.unit.config.ts` +- Конфігурація: нетаргетовані запуски використовують набір шардів `vitest.full-*.config.ts` і можуть розгортати multi-project shards у конфігурації для окремих проєктів для паралельного планування +- Файли: інвентарі core/unit у `src/**/*.test.ts`, `packages/**/*.test.ts`, `test/**/*.test.ts` і дозволені node-тести `ui`, охоплені `vitest.unit.config.ts` - Обсяг: - Чисті unit-тести - - Інтеграційні тести в межах процесу (автентифікація Gateway, маршрутизація, інструменти, парсинг, конфігурація) + - In-process integration-тести (автентифікація gateway, маршрутизація, tooling, парсинг, config) - Детерміновані регресії для відомих багів - Очікування: - - Запускаються в CI + - Запускається в CI - Реальні ключі не потрібні - - Мають бути швидкими й стабільними + - Має бути швидким і стабільним - + - - Ненацілені запуски `pnpm test` використовують дванадцять менших конфігурацій shard (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного гігантського процесу native root-project. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти не пов’язані набори. - - `pnpm test --watch` усе ще використовує native root граф проєкту `vitest.config.ts`, тому що цикл watch із кількома shards непрактичний. + - Нетаргетований `pnpm test` запускає дванадцять менших конфігурацій shard (`core-unit-fast`, `core-unit-src`, `core-unit-security`, `core-unit-ui`, `core-unit-support`, `core-support-boundary`, `core-contracts`, `core-bundled`, `core-runtime`, `agentic`, `auto-reply`, `extensions`) замість одного великого native root-project process. Це зменшує піковий RSS на завантажених машинах і не дає роботі auto-reply/extension витісняти інші набори. + - `pnpm test --watch` усе ще використовує native root `vitest.config.ts` project graph, оскільки цикл спостереження multi-shard непрактичний. - `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` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, release metadata і tooling, а потім запускає відповідні typecheck/lint/test lanes. Зміни в публічному Plugin SDK і plugin-contract включають один прохід перевірки extension, тому що extensions залежать від цих контрактів core. Оновлення версій лише в release metadata запускають цільові перевірки 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 з явними сусідніми тестами в цих легких lanes, тож зміни хелперів не змушують повторно запускати повний важкий набір для цього каталогу. - - `auto-reply` має три виділені блоки: top-level core хелпери, top-level інтеграційні тести `reply.*` і піддерево `src/auto-reply/reply/**`. Це не дає найважчій роботі harness reply потрапляти в дешеві тести status/chunk/token. + - `pnpm test:changed` розгортає змінені git-шляхи в ті самі scoped lanes, коли diff торкається лише routable файлів source/test; редагування config/setup усе ще повертаються до широкого повторного запуску root-project. + - `pnpm check:changed` — це звичайний розумний локальний gate для вузької роботи. Він класифікує diff на core, core tests, extensions, extension tests, apps, docs, метадані release і tooling, а потім запускає відповідні лінії typecheck/lint/test. Зміни в публічному Plugin SDK і plugin-contract включають один прохід валідації extension, оскільки extensions залежать від цих контрактів core. Версійні зміни лише в метаданих release запускають цільові перевірки 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 файли залишаються на наявних лініях. + - Вибрані helper source-файли `plugin-sdk` і `commands` також зіставляють запуски в режимі changed з явними sibling tests у цих легких lanes, тож редагування helper уникають повторного запуску повного важкого набору для цього каталогу. + - `auto-reply` має три окремі кошики: helper верхнього рівня core, integration-тести верхнього рівня `reply.*` і піддерево `src/auto-reply/reply/**`. Це утримує найважчу роботу harness reply подалі від дешевих тестів status/chunk/token. - - Коли ви змінюєте входи виявлення message-tool або runtime-контекст compaction, + - Коли ви змінюєте входи виявлення message-tool або runtime-контекст Compaction, зберігайте обидва рівні покриття. - - Додавайте сфокусовані регресії хелперів для чистих меж - маршрутизації та нормалізації. + - Додавайте цільові регресії helper для чистих меж маршрутизації та + нормалізації. - Підтримуйте інтеграційні набори embedded runner у здоровому стані: `src/agents/pi-embedded-runner/compact.hooks.test.ts`, `src/agents/pi-embedded-runner/run.overflow-compaction.test.ts` і `src/agents/pi-embedded-runner/run.overflow-compaction.loop.test.ts`. - - Ці набори перевіряють, що scoped id і поведінка compaction усе ще проходять - через реальні шляхи `run.ts` / `compact.ts`; тести лише на рівні хелперів - не є достатньою заміною для цих інтеграційних шляхів. + - Ці набори перевіряють, що scoped ids і поведінка compaction і надалі проходять + через реальні шляхи `run.ts` / `compact.ts`; тести лише helper + не є достатньою заміною для цих integration-шляхів. - + - - Базова конфігурація Vitest типово використовує `threads`. + - Базова конфігурація Vitest за замовчуванням використовує `threads`. - Спільна конфігурація Vitest фіксує `isolate: false` і використовує - non-isolated runner у root projects, а також у конфігураціях e2e і live. - - Root UI lane зберігає свій `jsdom` setup і optimizer, але теж працює на + non-isolated runner у root projects, e2e та live config. + - Коренева лінія UI зберігає свої `jsdom` setup і optimizer, але також працює на спільному non-isolated runner. - - Кожен shard `pnpm test` успадковує ті самі типові значення - `threads` + `isolate: false` зі спільної конфігурації Vitest. - - `scripts/run-vitest.mjs` типово додає `--no-maglev` для дочірніх Node-процесів Vitest, + - Кожен shard `pnpm test` успадковує ті самі значення за замовчуванням `threads` + `isolate: false` зі спільної конфігурації Vitest. + - `scripts/run-vitest.mjs` за замовчуванням додає `--no-maglev` для дочірніх Node-процесів Vitest, щоб зменшити churn компіляції V8 під час великих локальних запусків. - Встановіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною + Установіть `OPENCLAW_VITEST_ENABLE_MAGLEV=1`, щоб порівняти зі стандартною поведінкою V8. - - `pnpm changed:lanes` показує, які архітектурні lanes запускає diff. - - Pre-commit hook відповідає лише за форматування. Він повторно додає відформатовані файли до stage і + - `pnpm changed:lanes` показує, які архітектурні лінії зачіпає diff. + - Хук pre-commit виконує лише форматування. Він повторно індексує відформатовані файли і не запускає lint, typecheck або тести. - - Запускайте `pnpm check:changed` явно перед передачею чи push, коли вам + - Явно запускайте `pnpm check:changed` перед передачею роботи або push, коли вам потрібен розумний локальний gate. Зміни в публічному Plugin SDK і plugin-contract - включають один прохід перевірки extension. + включають один прохід валідації extension. - `pnpm test:changed` маршрутизує через scoped lanes, коли змінені шляхи - чітко відповідають меншому набору. + однозначно відповідають меншому набору. - `pnpm test:max` і `pnpm test:changed:max` зберігають ту саму поведінку маршрутизації, - лише з вищим лімітом worker-ів. - - Автоматичне масштабування локальних worker-ів навмисно консервативне й зменшується, - коли середнє навантаження хоста вже високе, тому кілька одночасних - запусків Vitest типово завдають менше шкоди. - - Базова конфігурація Vitest позначає файли projects/config як - `forceRerunTriggers`, щоб повторні запуски в режимі changed лишалися коректними, коли змінюється зв’язування тестів. - - Конфігурація зберігає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних - хостах; встановіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете - одну явну локацію кешу для прямого профілювання. + лише з вищою межею кількості worker. + - Автомасштабування локальних worker навмисно консервативне і зменшує навантаження, + коли середнє навантаження хоста вже високе, тож кілька одночасних + запусків Vitest за замовчуванням завдають менше шкоди. + - Базова конфігурація Vitest позначає проєкти/конфігураційні файли як + `forceRerunTriggers`, щоб повторні запуски в режимі changed залишалися коректними, коли змінюється зв’язування тестів. + - Конфігурація тримає `OPENCLAW_VITEST_FS_MODULE_CACHE` увімкненим на підтримуваних + хостах; установіть `OPENCLAW_VITEST_FS_MODULE_CACHE_PATH=/abs/path`, якщо хочете + мати одну явну локацію кешу для прямого профілювання. - - `pnpm test:perf:imports` вмикає звітування Vitest про тривалість імпорту та - вивід деталізації імпортів. - - `pnpm test:perf:imports:changed` обмежує той самий вид профілювання - файлами, зміненими відносно `origin/main`. - - Коли один «гарячий» тест усе ще витрачає більшість часу на стартові імпорти, - тримайте важкі залежності за вузьким локальним seam `*.runtime.ts` і - мокайте цей seam безпосередньо замість глибокого імпорту runtime-хелперів - лише для того, щоб передати їх через `vi.mock(...)`. + - `pnpm test:perf:imports` вмикає звіти Vitest про тривалість імпорту плюс + вивід деталізації імпорту. + - `pnpm test:perf:imports:changed` звужує той самий профілювальний вигляд до + файлів, змінених відносно `origin/main`. + - Якщо один «гарячий» тест усе ще витрачає більшість часу на стартові імпорти, + тримайте важкі залежності за вузьким локальним швом `*.runtime.ts` і + мокайте цей шов безпосередньо замість глибоких імпортів runtime helper лише + для того, щоб передати їх через `vi.mock(...)`. - `pnpm test:perf:changed:bench -- --ref ` порівнює маршрутизований - `test:changed` із native root-project шляхом для цього закоміченого - diff і виводить wall time та macOS max RSS. - - `pnpm test:perf:changed:bench -- --worktree` вимірює поточне брудне дерево, - маршрутизуючи список змінених файлів через - `scripts/test-projects.mjs` і root-конфігурацію Vitest. + `test:changed` із native root-project шляхом для цього зафіксованого + diff і виводить wall time плюс macOS max RSS. + - `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного + брудного дерева, маршрутизуючи список змінених файлів через + `scripts/test-projects.mjs` і кореневу конфігурацію Vitest. - `pnpm test:perf:profile:main` записує профіль CPU основного потоку для - накладних витрат запуску та transform у Vitest/Vite. - - `pnpm test:perf:profile:runner` записує профілі CPU+heap runner-а для - unit-набору з вимкненим файловим паралелізмом. + накладних витрат запуску та трансформації Vitest/Vite. + - `pnpm test:perf:profile:runner` записує профілі CPU+heap раннера для + unit-набору з вимкненим паралелізмом файлів. -### Стабільність (Gateway) +### Стабільність (gateway) - Команда: `pnpm test:stability:gateway` - Конфігурація: `vitest.gateway.config.ts`, примусово один worker - Обсяг: - Запускає реальний loopback Gateway з увімкненою діагностикою за замовчуванням - - Пропускає синтетичне churn повідомлень gateway, пам’яті та великих payload через діагностичний шлях подій - - Виконує запит до `diagnostics.stability` через Gateway WS RPC - - Охоплює хелпери збереження пакета діагностики стабільності - - Перевіряє, що recorder залишається обмеженим, синтетичні зразки RSS не перевищують бюджет тиску, а глибини черг для кожної сесії знову знижуються до нуля + - Проганяє синтетичне churn повідомлень gateway, пам’яті та великих payload через шлях діагностичних подій + - Виконує запити до `diagnostics.stability` через WS RPC Gateway + - Охоплює helper збереження пакета стабільності діагностики + - Перевіряє, що recorder залишається обмеженим, синтетичні вибірки RSS залишаються в межах бюджету тиску, а глибини черг по сесіях повертаються до нуля - Очікування: - Безпечно для CI і без ключів - - Вузький lane для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway + - Вузька лінія для подальшої роботи над регресіями стабільності, а не заміна повного набору Gateway ### E2E (gateway smoke) - Команда: `pnpm test:e2e` - Конфігурація: `vitest.e2e.config.ts` -- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і E2E-тести bundled plugin у `extensions/` -- Типові параметри runtime: +- Файли: `src/**/*.e2e.test.ts`, `test/**/*.e2e.test.ts` і bundled-plugin E2E-тести в `extensions/` +- Значення runtime за замовчуванням: - Використовує Vitest `threads` з `isolate: false`, як і решта репозиторію. - - Використовує адаптивних worker-ів (CI: до 2, локально: 1 за замовчуванням). - - За замовчуванням запускається в тихому режимі, щоб зменшити накладні витрати на console I/O. + - Використовує adaptive workers (CI: до 2, локально: 1 за замовчуванням). + - За замовчуванням працює в silent mode, щоб зменшити накладні витрати на I/O консолі. - Корисні перевизначення: - - `OPENCLAW_E2E_WORKERS=` — щоб примусово задати кількість worker-ів (обмежено 16). - - `OPENCLAW_E2E_VERBOSE=1` — щоб знову ввімкнути докладний вивід у консоль. + - `OPENCLAW_E2E_WORKERS=`, щоб примусово задати кількість worker (не більше 16). + - `OPENCLAW_E2E_VERBOSE=1`, щоб знову ввімкнути докладний вивід у консоль. - Обсяг: - - Наскрізна поведінка gateway з кількома інстансами - - Поверхні WebSocket/HTTP, pairинг Node і важчий мережевий стек + - End-to-end поведінка gateway з кількома екземплярами + - Поверхні WebSocket/HTTP, pairинг Node і важче мережеве навантаження - Очікування: - - Запускається в CI (коли ввімкнено в pipeline) + - Запускається в CI (коли увімкнено в pipeline) - Реальні ключі не потрібні - Більше рухомих частин, ніж у unit-тестах (може бути повільніше) -### E2E: smoke для backend OpenShell +### E2E: smoke OpenShell backend - Команда: `pnpm test:e2e:openshell` - Файл: `extensions/openshell/src/backend.e2e.test.ts` - Обсяг: - - Запускає ізольований Gateway OpenShell на хості через Docker + - Запускає ізольований gateway OpenShell на хості через Docker - Створює sandbox із тимчасового локального Dockerfile - - Перевіряє backend OpenShell в OpenClaw через реальні `sandbox ssh-config` + SSH exec + - Перевіряє OpenShell backend OpenClaw через реальні `sandbox ssh-config` + SSH exec - Перевіряє remote-canonical поведінку файлової системи через sandbox fs bridge - Очікування: - - Лише opt-in; не входить до типового запуску `pnpm test:e2e` - - Потребує локального CLI `openshell` і працездатного Docker daemon - - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує test gateway і sandbox + - Лише за явним увімкненням; не входить до стандартного запуску `pnpm test:e2e` + - Потребує локального CLI `openshell` і працездатного демона Docker + - Використовує ізольовані `HOME` / `XDG_CONFIG_HOME`, а потім знищує тестовий gateway і sandbox - Корисні перевизначення: - - `OPENCLAW_E2E_OPENSHELL=1` — щоб увімкнути тест під час ручного запуску ширшого набору e2e - - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell` — щоб указати нестандартний бінарний файл CLI або wrapper script + - `OPENCLAW_E2E_OPENSHELL=1`, щоб увімкнути тест під час ручного запуску ширшого e2e-набору + - `OPENCLAW_E2E_OPENSHELL_COMMAND=/path/to/openshell`, щоб вказати нестандартний двійковий файл CLI або wrapper script ### Live (реальні провайдери + реальні моделі) - Команда: `pnpm test:live` - Конфігурація: `vitest.live.config.ts` -- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і live-тести bundled plugin у `extensions/` -- Типово: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) +- Файли: `src/**/*.live.test.ts`, `test/**/*.live.test.ts` і bundled-plugin live-тести в `extensions/` +- За замовчуванням: **увімкнено** через `pnpm test:live` (встановлює `OPENCLAW_LIVE_TEST=1`) - Обсяг: - «Чи справді цей провайдер/модель працює _сьогодні_ з реальними обліковими даними?» - - Виявлення змін формату провайдера, особливостей виклику інструментів, проблем автентифікації та поведінки обмежень швидкості + - Виявлення змін формату провайдера, особливостей виклику tool, проблем автентифікації та поведінки rate limit - Очікування: - - За задумом нестабільні для CI (реальні мережі, реальні політики провайдерів, квоти, збої) - - Коштують грошей / використовують rate limits - - Переважно запускати звужені підмножини, а не «все» -- Live-запуски використовують `~/.profile`, щоб підхопити відсутні API-ключі. -- За замовчуванням live-запуски все одно ізолюють `HOME` і копіюють матеріали config/auth у тимчасовий test home, щоб unit-fixtures не могли змінити ваш реальний `~/.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. -- Вивід progress/Heartbeat: - - Live-набори тепер виводять рядки прогресу в stderr, тож довгі виклики провайдера помітно активні навіть тоді, коли Vitest працює з тихим перехопленням консолі. - - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway передаються негайно під час live-запусків. - - Налаштовуйте Heartbeat прямої моделі через `OPENCLAW_LIVE_HEARTBEAT_MS`. - - Налаштовуйте Heartbeat gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. + - Навмисно нестабільно для CI (реальні мережі, реальні політики провайдерів, квоти, збої) + - Коштує грошей / витрачає rate limit + - Краще запускати звужені підмножини, а не «все» +- Live-запуски зчитують `~/.profile`, щоб підхопити відсутні API key. +- За замовчуванням live-запуски все ще ізолюють `HOME` і копіюють config/auth матеріали в тимчасовий test home, щоб unit-фікстури не могли змінити ваш реальний `~/.openclaw`. +- Установлюйте `OPENCLAW_LIVE_USE_REAL_HOME=1` лише тоді, коли навмисно хочете, щоб live-тести використовували ваш реальний домашній каталог. +- `pnpm test:live` тепер за замовчуванням використовує тихіший режим: він зберігає вивід прогресу `[live] ...`, але приховує додаткове повідомлення `~/.profile` і приглушує журнали bootstrap Gateway/шум Bonjour. Установіть `OPENCLAW_LIVE_TEST_QUIET=0`, якщо хочете повернути повні журнали запуску. +- Ротація API key (залежно від провайдера): установлюйте `*_API_KEYS` у форматі з комами/крапками з комою або `*_API_KEY_1`, `*_API_KEY_2` (наприклад `OPENAI_API_KEYS`, `ANTHROPIC_API_KEYS`, `GEMINI_API_KEYS`) або перевизначення для live через `OPENCLAW_LIVE_*_KEY`; тести повторюють спробу у відповідь на rate limit. +- Вивід прогресу/Heartbeat: + - Live-набори тепер надсилають рядки прогресу в stderr, щоб було видно, що довгі виклики провайдера активні, навіть коли захоплення консолі Vitest тихе. + - `vitest.live.config.ts` вимикає перехоплення консолі Vitest, тож рядки прогресу провайдера/Gateway одразу передаються під час live-запусків. + - Налаштовуйте Heartbeat прямих моделей через `OPENCLAW_LIVE_HEARTBEAT_MS`. + - Налаштовуйте Heartbeat Gateway/probe через `OPENCLAW_LIVE_GATEWAY_HEARTBEAT_MS`. ## Який набір мені запускати? Використовуйте цю таблицю рішень: -- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо ви багато що змінили) -- Зміни в мережевій взаємодії gateway / WS protocol / pairing: додайте `pnpm test:e2e` -- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику інструментів: запускайте звужений `pnpm test:live` +- Редагування логіки/тестів: запускайте `pnpm test` (і `pnpm test:coverage`, якщо змінили багато) +- Зміни в мережевій взаємодії gateway / WS protocol / pairинг: додайте `pnpm test:e2e` +- Налагодження «мій бот не працює» / збоїв, специфічних для провайдера / виклику tool: запускайте звужений `pnpm test:live` -## Live-тести (що звертаються до мережі) +## Live (мережеві) тести -Для live matrix моделей, smoke-тестів backend CLI, smoke-тестів ACP, harness -Codex app-server і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, -music, video, media harness) — а також обробки облікових даних для live-запусків — див. +Для live model matrix, smoke CLI backend, smoke ACP, harness Codex app-server +і всіх live-тестів медіапровайдерів (Deepgram, BytePlus, ComfyUI, image, +music, video, media harness) — а також для обробки облікових даних під час live-запусків — див. [Тестування — live-набори](/uk/help/testing-live). -## Docker runners (необов’язкові перевірки «працює в Linux») +## Ранери Docker (необов’язкові перевірки «працює в Linux») -Ці Docker runners поділяються на дві категорії: +Ці ранери Docker поділяються на дві групи: -- Live-model runners: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний їхньому ключу профілю live-файл всередині Docker image репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і використовують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint-и: `test:live:models-profiles` і `test:live:gateway-profiles`. -- Docker live runners за замовчуванням мають менший smoke-ліміт, щоб повний Docker sweep залишався практичним: +- Ранери live-model: `test:docker:live-models` і `test:docker:live-gateway` запускають лише відповідний live-файл з profile-key усередині Docker-образу репозиторію (`src/agents/models.profiles.live.test.ts` і `src/gateway/gateway-models.profiles.live.test.ts`), монтують ваш локальний каталог config і workspace (і зчитують `~/.profile`, якщо його змонтовано). Відповідні локальні entrypoint — `test:live:models-profiles` і `test:live:gateway-profiles`. +- Docker live runners за замовчуванням мають меншу межу smoke, щоб повний Docker sweep залишався практичним: `test:docker:live-models` за замовчуванням використовує `OPENCLAW_LIVE_MAX_MODELS=12`, а `test:docker:live-gateway` — `OPENCLAW_LIVE_GATEWAY_SMOKE=1`, `OPENCLAW_LIVE_GATEWAY_MAX_MODELS=8`, `OPENCLAW_LIVE_GATEWAY_STEP_TIMEOUT_MS=45000` і `OPENCLAW_LIVE_GATEWAY_MODEL_TIMEOUT_MS=90000`. Перевизначайте ці env-змінні, коли - вам свідомо потрібне більше вичерпне сканування. -- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для Docker lane-ів live. Він також збирає один спільний image `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для container smoke runner-ів E2E, які перевіряють зібраний застосунок. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, а resource caps не дають одночасно стартувати всім важким live, npm-install і multi-service lane-ам. Типові значення — 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли Docker-хост має більше запасу ресурсів. Runner за замовчуванням виконує Docker preflight, видаляє застарілі контейнери OpenClaw E2E, кожні 30 секунд виводить статус, зберігає тривалості успішних lane-ів у `.artifacts/docker-tests/lane-timings.json` і використовує ці тривалості, щоб у наступних запусках спочатку стартували довші lane-и. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести зважений маніфест lane-ів без збирання та запуску Docker. -- 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` запускають один або кілька реальних контейнерів і перевіряють інтеграційні шляхи вищого рівня. + явно хочете ширший вичерпний прогін. +- `test:docker:all` один раз збирає live Docker image через `test:docker:live-build`, а потім повторно використовує його для live Docker lanes. Він також збирає один спільний образ `scripts/e2e/Dockerfile` через `test:docker:e2e-build` і повторно використовує його для контейнерних E2E smoke runners, які перевіряють зібраний застосунок. Агрегат використовує зважений локальний планувальник: `OPENCLAW_DOCKER_ALL_PARALLELISM` керує слотами процесів, тоді як обмеження ресурсів не дають важким live-, npm-install- і multi-service-лініям стартувати одночасно. Значення за замовчуванням: 10 слотів, `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; налаштовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` лише тоді, коли хост Docker має більший запас ресурсів. За замовчуванням раннер виконує preflight Docker, видаляє застарілі контейнери OpenClaw E2E, друкує стан кожні 30 секунд, зберігає час успішних ліній у `.artifacts/docker-tests/lane-timings.json` і використовує ці значення часу, щоб на наступних запусках стартувати довші лінії раніше. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати зважений маніфест ліній без збирання або запуску Docker. +- Контейнерні 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-и (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб OAuth зовнішнього CLI міг оновлювати токени без змін у сховищі auth на хості: +Ранери Docker для live-model також монтують лише потрібні auth home зовнішнього CLI (або всі підтримувані, якщо запуск не звужено), а потім копіюють їх у домашній каталог контейнера перед запуском, щоб зовнішній CLI OAuth міг оновлювати токени, не змінюючи auth store хоста: - Прямі моделі: `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`) @@ -542,136 +578,136 @@ Docker runners live-model також bind-mount-ять лише потрібні - Smoke harness Codex app-server: `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`) - Smoke Open WebUI live: `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, перевіряє, що doctor відновлює runtime deps активованого plugin, і виконує один змоканий хід агента OpenAI. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_NPM_ONBOARD_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host rebuild через `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 image providers замість зависання. Повторно використовуйте попередньо зібраний tarball через `OPENCLAW_BUN_GLOBAL_SMOKE_PACKAGE_TGZ=/path/to/openclaw-*.tgz`, пропустіть host build через `OPENCLAW_BUN_GLOBAL_SMOKE_HOST_BUILD=0` або скопіюйте `dist/` із зібраного Docker image через `OPENCLAW_BUN_GLOBAL_SMOKE_DIST_IMAGE=openclaw-dockerfile-smoke:local`. -- Smoke Installer у Docker: `bash scripts/test-install-sh-docker.sh` використовує спільний npm cache для своїх контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням використовує npm `latest` як стабільну baseline перед оновленням до tarball кандидата. Перевірки installer без root зберігають ізольований npm cache, щоб cache entries, створені root, не маскували поведінку локального встановлення користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати cache root/update/direct-npm у локальних повторних запусках. -- Install Smoke CI пропускає дубльований direct-npm global update через `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`, потім примусово викликає відхилення provider schema і перевіряє, що сирі деталі з’являються в логах Gateway. -- Міст MCP channel (seeded Gateway + stdio bridge + 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`) -- Cleanup MCP для Cron/subagent (реальний Gateway + teardown дочірнього stdio MCP після ізольованих запусків cron і одноразового subagent): `pnpm test:docker:cron-mcp-cleanup` (скрипт: `scripts/e2e/cron-mcp-cleanup-docker.sh`) -- Plugins (smoke встановлення + псевдонім `/plugin` + семантика перезапуску Claude-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) +- Wizard онбордингу (TTY, повне scaffolding): `pnpm test:docker:onboard` (скрипт: `scripts/e2e/onboard-docker.sh`) +- Smoke онбордингу/channel/agent з npm tarball: `pnpm test:docker:npm-onboard-channel-agent` глобально встановлює запакований tarball OpenClaw у Docker, налаштовує OpenAI через onboarding на основі env-ref плюс Telegram за замовчуванням, перевіряє, що doctor відновлює runtime deps активованого plugin, і виконує один змоканий agent turn 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` повертає вбудованих image-провайдерів, а не зависає. Повторно використовуйте попередньо зібраний 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`. +- Smoke інсталятора Docker: `bash scripts/test-install-sh-docker.sh` використовує один спільний кеш npm для своїх контейнерів root, update і direct-npm. Smoke оновлення за замовчуванням бере npm `latest` як стабільний baseline перед оновленням до tarball-кандидата. Перевірки інсталятора без root зберігають ізольований кеш npm, щоб записи кешу, що належать root, не маскували поведінку локальної інсталяції користувача. Установіть `OPENCLAW_INSTALL_SMOKE_NPM_CACHE_DIR=/path/to/cache`, щоб повторно використовувати кеш root/update/direct-npm між локальними повторними запусками. +- Install Smoke у CI пропускає дубльоване пряме глобальне оновлення 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 (засіяний Gateway + stdio bridge + 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-bundle): `pnpm test:docker:plugins` (скрипт: `scripts/e2e/plugins-docker.sh`) - Smoke незмінного оновлення Plugin: `pnpm test:docker:plugin-update` (скрипт: `scripts/e2e/plugin-update-unchanged-docker.sh`) -- Smoke метаданих перезавантаження конфігурації: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) -- Runtime deps bundled plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker image runner-а, один раз збирає й пакує OpenClaw на хості, а потім монтує цей tarball у кожний Linux-сценарій встановлення. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть host rebuild після свіжої локальної збірки через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker aggregate попередньо пакує цей tarball один раз, а потім розбиває перевірки bundled channel на незалежні lane-и, включно з окремими lane-ами оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску bundled lane, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Lane також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. -- Звужуйте runtime deps bundled plugin під час ітерації, вимикаючи не пов’язані сценарії, наприклад: +- Smoke метаданих перезавантаження config: `pnpm test:docker:config-reload` (скрипт: `scripts/e2e/config-reload-source-docker.sh`) +- Runtime deps вбудованого plugin: `pnpm test:docker:bundled-channel-deps` за замовчуванням збирає невеликий Docker runner image, один раз збирає і пакує OpenClaw на хості, а потім монтує цей tarball у кожен сценарій Linux install. Повторно використовуйте image через `OPENCLAW_SKIP_DOCKER_BUILD=1`, пропустіть повторне збирання на хості після свіжого локального збирання через `OPENCLAW_BUNDLED_CHANNEL_HOST_BUILD=0` або вкажіть наявний tarball через `OPENCLAW_BUNDLED_CHANNEL_PACKAGE_TGZ=/path/to/openclaw-*.tgz`. Повний Docker-агрегат попередньо пакує цей tarball один раз, а потім розшардовує перевірки вбудованих каналів у незалежні лінії, зокрема окремі лінії оновлення для Telegram, Discord, Slack, Feishu, memory-lancedb і ACPX. Використовуйте `OPENCLAW_BUNDLED_CHANNELS=telegram,slack`, щоб звузити матрицю каналів під час прямого запуску лінії вбудованих каналів, або `OPENCLAW_BUNDLED_CHANNEL_UPDATE_TARGETS=telegram,acpx`, щоб звузити сценарій оновлення. Лінія також перевіряє, що `channels..enabled=false` і `plugins.entries..enabled=false` пригнічують відновлення doctor/runtime-dependency. +- Звужуйте runtime deps вбудованого 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`. -Щоб вручну попередньо зібрати та повторно використати спільний image built-app: +Щоб вручну попередньо зібрати і повторно використати спільний образ built-app: ```bash OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local pnpm test:docker:e2e-build OPENCLAW_DOCKER_E2E_IMAGE=openclaw-docker-e2e:local OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:mcp-channels ``` -Перевизначення image для конкретного набору, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе ще мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` указує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, тому що вони перевіряють поведінку пакування/встановлення, а не спільний runtime built-app. +Специфічні для набору перевизначення image, такі як `OPENCLAW_GATEWAY_NETWORK_E2E_IMAGE`, усе одно мають пріоритет, якщо задані. Коли `OPENCLAW_SKIP_DOCKER_BUILD=1` вказує на віддалений спільний image, скрипти завантажують його, якщо його ще немає локально. Docker-тести QR та installer зберігають власні Dockerfile, тому що вони перевіряють поведінку package/install, а не спільний runtime built-app. -Docker runners live-model також bind-mount-ять поточний checkout у режимі лише для читання і -розміщують його у тимчасовому workdir усередині контейнера. Це зберігає runtime -image компактним, але все одно запускає Vitest проти ваших точних локальних source/config. -Етап розміщення пропускає великі локальні cache та результати збірки застосунків, такі як -`.pnpm-store`, `.worktrees`, `__openclaw_vitest__`, а також локальні для застосунків каталоги `.build` або -виводу Gradle, щоб Docker live-запуски не витрачали хвилини на копіювання +Ранери Docker для live-model також монтують поточний checkout лише для читання і +розміщують його в тимчасовий робочий каталог усередині контейнера. Це дозволяє +зберігати runtime image компактним, але водночас запускати Vitest проти ваших точних локальних source/config. +Етап розміщення пропускає великі локальні кеші та результати збирання застосунків, такі як +`.pnpm-store`, `.worktrees`, `__openclaw_vitest__` і локальні для застосунків каталоги `.build` або +результати Gradle, щоб live-запуски Docker не витрачали хвилини на копіювання машинно-специфічних артефактів. -Вони також установлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live probes Gateway не запускали -реальні worker-и каналів Telegram/Discord тощо всередині контейнера. -`test:docker:live-models` усе ще запускає `pnpm test:live`, тому також передавайте -`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити покриття gateway -live із цього Docker lane. -`test:docker:openwebui` — це smoke перевірки сумісності вищого рівня: він запускає -контейнер Gateway OpenClaw з увімкненими HTTP endpoint OpenAI-compatible, -запускає закріплений контейнер Open WebUI проти цього gateway, виконує вхід через +Вони також встановлюють `OPENCLAW_SKIP_CHANNELS=1`, щоб live-probe Gateway не запускали +реальні worker каналів Telegram/Discord тощо всередині контейнера. +`test:docker:live-models` усе ще запускає `pnpm test:live`, тож також передавайте +`OPENCLAW_LIVE_GATEWAY_*`, коли вам потрібно звузити або виключити coverage Gateway +live з цієї Docker-лінії. +`test:docker:openwebui` — це smoke сумісності вищого рівня: він запускає +контейнер Gateway OpenClaw з увімкненими OpenAI-compatible HTTP endpoint, +запускає закріплений контейнер Open WebUI проти цього gateway, входить через Open WebUI, перевіряє, що `/api/models` показує `openclaw/default`, а потім надсилає -реальний запит чату через proxy Open WebUI `/api/chat/completions`. -Перший запуск може бути помітно повільнішим, оскільки Docker може потребувати завантаження -image Open WebUI, а самому Open WebUI може знадобитися завершити власне cold-start налаштування. -Цей lane очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` -(`~/.profile` за замовчуванням) є основним способом надати його в Dockerized-запусках. -Успішні запуски виводять невеликий JSON payload на кшталт `{ "ok": true, "model": +реальний chat-запит через проксі Open WebUI `/api/chat/completions`. +Перший запуск може бути помітно повільнішим, оскільки Docker може знадобитися завантажити +image Open WebUI, а Open WebUI може потребувати завершення власного холодного запуску. +Ця лінія очікує придатний ключ live-моделі, а `OPENCLAW_PROFILE_FILE` +(за замовчуванням `~/.profile`) є основним способом передати його в Dockerized-запусках. +Успішні запуски друкують невеликий JSON payload на кшталт `{ "ok": true, "model": "openclaw/default", ... }`. -`test:docker:mcp-channels` навмисно детермінований і не потребує -реального акаунта Telegram, Discord або iMessage. Він запускає seeded Gateway -container, стартує другий container, який породжує `openclaw mcp serve`, а потім -перевіряє виявлення маршрутизованої розмови, читання транскриптів, метадані вкладень, -поведінку черги live event, маршрутизацію вихідних надсилань і сповіщення у стилі Claude про channel + -permission через реальний stdio MCP bridge. Перевірка сповіщень -безпосередньо аналізує сирі stdio MCP frames, тож smoke перевіряє те, що -міст справді випромінює, а не лише те, що певний SDK клієнта випадково показує. -`test:docker:pi-bundle-mcp-tools` детермінований і не потребує -ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server -усередині контейнера, матеріалізує цей server через runtime MCP вбудованого bundle Pi, +`test:docker:mcp-channels` навмисно є детермінованим і не потребує +реального облікового запису Telegram, Discord або iMessage. Він запускає засіяний контейнер Gateway, +стартує другий контейнер, який запускає `openclaw mcp serve`, а потім +перевіряє маршрутизоване виявлення розмов, читання транскриптів, метадані вкладень, +поведінку черги live-подій, маршрутизацію вихідного надсилання, а також сповіщення у стилі Claude про канал + +дозволи через реальний stdio MCP bridge. Перевірка сповіщень +безпосередньо інспектує необроблені кадри stdio MCP, тож smoke перевіряє те, що +міст насправді надсилає, а не лише те, що випадково показує певний SDK клієнта. +`test:docker:pi-bundle-mcp-tools` є детермінованим і не потребує +реального ключа live-моделі. Він збирає Docker image репозиторію, запускає реальний stdio MCP probe server +усередині контейнера, матеріалізує цей сервер через вбудований runtime MCP пакета Pi, виконує tool, а потім перевіряє, що `coding` і `messaging` зберігають інструменти `bundle-mcp`, тоді як `minimal` і `tools.deny: ["bundle-mcp"]` їх фільтрують. -`test:docker:cron-mcp-cleanup` детермінований і не потребує ключа live-моделі. -Він запускає seeded Gateway із реальним stdio MCP probe server, виконує -ізольований cron-хід і одноразовий дочірній хід `/subagents spawn`, а потім перевіряє, +`test:docker:cron-mcp-cleanup` є детермінованим і не потребує реального +ключа live-моделі. Він запускає засіяний Gateway з реальним stdio MCP probe server, виконує +ізольований хід cron і дочірній одноразовий хід `/subagents spawn`, а потім перевіряє, що дочірній процес MCP завершується після кожного запуску. Ручний smoke plain-language thread для ACP (не CI): - `bun scripts/dev/discord-acp-plain-language-smoke.ts --channel ...` -- Зберігайте цей скрипт для сценаріїв регресії/налагодження. Він може знову знадобитися для перевірки маршрутизації ACP thread, тому не видаляйте його. +- Зберігайте цей скрипт для регресійних сценаріїв/налагодження. Він може знову знадобитися для перевірки маршрутизації тредів ACP, тож не видаляйте його. -Корисні змінні середовища: +Корисні 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 vars, отримані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої CLI auth -- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (типово: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker -- Зовнішні каталоги/файли CLI auth під `$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_CONFIG_DIR=...` (за замовчуванням: `~/.openclaw`) монтується в `/home/node/.openclaw` +- `OPENCLAW_WORKSPACE_DIR=...` (за замовчуванням: `~/.openclaw/workspace`) монтується в `/home/node/.openclaw/workspace` +- `OPENCLAW_PROFILE_FILE=...` (за замовчуванням: `~/.profile`) монтується в `/home/node/.profile` і зчитується перед запуском тестів +- `OPENCLAW_DOCKER_PROFILE_ENV_ONLY=1`, щоб перевіряти лише env-змінні, зчитані з `OPENCLAW_PROFILE_FILE`, використовуючи тимчасові каталоги config/workspace і без монтування зовнішньої auth зовнішніх CLI +- `OPENCLAW_DOCKER_CLI_TOOLS_DIR=...` (за замовчуванням: `~/.cache/openclaw/docker-cli-tools`) монтується в `/home/node/.npm-global` для кешованих встановлень CLI усередині Docker +- Каталоги/файли auth зовнішніх CLI у `$HOME` монтуються лише для читання під `/host-auth...`, а потім копіюються в `/home/node/...` перед стартом тестів + - Каталоги за замовчуванням: `.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_LIVE_GATEWAY_MODELS=...` / `OPENCLAW_LIVE_MODELS=...`, щоб звузити запуск -- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб відфільтрувати провайдерів усередині контейнера -- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, яким не потрібна перебудова -- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб переконатися, що облікові дані надходять зі сховища profile (а не з env) +- `OPENCLAW_LIVE_GATEWAY_PROVIDERS=...` / `OPENCLAW_LIVE_PROVIDERS=...`, щоб фільтрувати провайдерів усередині контейнера +- `OPENCLAW_SKIP_DOCKER_BUILD=1`, щоб повторно використати наявний image `openclaw:local-live` для повторних запусків, які не потребують нового збирання +- `OPENCLAW_LIVE_REQUIRE_PROFILE_KEYS=1`, щоб гарантувати, що облікові дані беруться зі сховища profile (а не з env) - `OPENCLAW_OPENWEBUI_MODEL=...`, щоб вибрати модель, яку gateway показує для smoke Open WebUI - `OPENCLAW_OPENWEBUI_PROMPT=...`, щоб перевизначити nonce-check prompt, який використовує smoke Open WebUI -- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений tag image Open WebUI +- `OPENWEBUI_IMAGE=...`, щоб перевизначити закріплений тег image Open WebUI ## Перевірка документації -Після редагування документації запускайте перевірки docs: `pnpm check:docs`. -Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки внутрішньосторінкових heading: `pnpm docs:check-links:anchors`. +Запускайте перевірки документації після редагування docs: `pnpm check:docs`. +Запускайте повну перевірку anchor у Mintlify, коли вам також потрібні перевірки заголовків усередині сторінки: `pnpm docs:check-links:anchors`. -## Офлайн-регресія (безпечна для CI) +## Офлайнова регресія (безпечно для CI) Це регресії «реального pipeline» без реальних провайдерів: -- Виклик інструментів Gateway (mock OpenAI, реальний gateway + цикл агента): `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") +- Виклик tool через Gateway (змоканий OpenAI, реальний цикл gateway + agent): `src/gateway/gateway.test.ts` (випадок: "runs a mock OpenAI tool call end-to-end via gateway agent loop") +- Wizard Gateway (WS `wizard.start`/`wizard.next`, примусовий запис config + auth): `src/gateway/gateway.test.ts` (випадок: "runs wizard over ws and writes auth token config") ## Оцінювання надійності агента (Skills) -У нас уже є кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: +Ми вже маємо кілька безпечних для CI тестів, які поводяться як «оцінювання надійності агента»: -- Mock-виклик інструментів через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). -- Наскрізні потоки майстра, які перевіряють прив’язку сесії та ефекти конфігурації (`src/gateway/gateway.test.ts`). +- Моканий виклик tool через реальний цикл gateway + agent (`src/gateway/gateway.test.ts`). +- End-to-end потоки wizard, які перевіряють зв’язування сесії та ефекти config (`src/gateway/gateway.test.ts`). -Що ще бракує для Skills (див. [Skills](/uk/tools/skills)): +Чого ще бракує для Skills (див. [Skills](/uk/tools/skills)): -- **Вибір рішення:** коли Skills перелічені в prompt, чи вибирає агент правильний skill (або уникає нерелевантних)? -- **Дотримання вимог:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/аргументи? -- **Контракти workflow:** багатокрокові сценарії, які перевіряють порядок інструментів, перенесення історії сесії та межі sandbox. +- **Decisioning:** коли Skills перелічені в prompt, чи вибирає агент правильний Skill (або уникає нерелевантних)? +- **Compliance:** чи читає агент `SKILL.md` перед використанням і чи виконує обов’язкові кроки/args? +- **Workflow contracts:** multi-turn сценарії, які перевіряють порядок tool, перенесення історії сесії та межі sandbox. -Майбутні eval-и мають насамперед залишатися детермінованими: +Майбутні eval насамперед мають залишатися детермінованими: -- Runner сценаріїв, який використовує mock-провайдерів для перевірки викликів інструментів + їх порядку, читання skill-файлів і прив’язки сесії. -- Невеликий набір сценаріїв, зосереджених на skills (використати чи уникнути, gating, prompt injection). -- Необов’язкові live eval-и (opt-in, із керуванням через env) — лише після того, як з’явиться безпечний для CI набір. +- Runner сценаріїв, що використовує mock-провайдерів для перевірки викликів tool + їх порядку, читання файлів skill і зв’язування сесій. +- Невеликий набір сценаріїв, зосереджених на Skills (використовувати чи уникати, gating, prompt injection). +- Необов’язкові live eval (opt-in, із керуванням через env) лише після того, як буде готовий набір, безпечний для CI. -## Контрактні тести (форма plugin і channel) +## Contract-тести (форма plugin і channel) -Контрактні тести перевіряють, що кожен зареєстрований plugin і channel відповідає -своєму інтерфейсному контракту. Вони проходять по всіх виявлених plugin-ах і запускають -набір перевірок форми та поведінки. Типовий unit lane `pnpm test` навмисно -пропускає ці спільні seam- і smoke-файли; запускайте контрактні команди явно, -коли торкаєтеся спільних поверхонь channel або provider. +Contract-тести перевіряють, що кожен зареєстрований plugin і channel відповідає своєму +інтерфейсному контракту. Вони проходять по всіх виявлених plugin і запускають набір +перевірок форми та поведінки. Лінія unit за замовчуванням `pnpm test` +навмисно пропускає ці файли спільних seam і smoke; явно запускайте команди contract, +коли торкаєтесь спільних поверхонь channel або provider. ### Команди @@ -681,58 +717,58 @@ permission через реальний stdio MCP bridge. Перевірка сп ### Контракти channel -Розташовані в `src/channels/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/channels/plugins/contracts/*.contract.test.ts`: - **plugin** - Базова форма plugin (id, name, capabilities) -- **setup** - Контракт майстра налаштування -- **session-binding** - Поведінка прив’язки сесії +- **setup** - Контракт wizard налаштування +- **session-binding** - Поведінка прив’язування сесії - **outbound-payload** - Структура payload повідомлення - **inbound** - Обробка вхідних повідомлень -- **actions** - Обробники дій каналу -- **threading** - Обробка ID thread -- **directory** - API directory/roster -- **group-policy** - Застосування group policy +- **actions** - Обробники дій channel +- **threading** - Обробка ID тредів +- **directory** - API каталогу/реєстру +- **group-policy** - Забезпечення групової політики ### Контракти статусу provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`. +Розміщені в `src/plugins/contracts/*.contract.test.ts`. -- **status** - Перевірки status каналу -- **registry** - Форма registry plugin +- **status** - Проби статусу channel +- **registry** - Форма реєстру plugin ### Контракти provider -Розташовані в `src/plugins/contracts/*.contract.test.ts`: +Розміщені в `src/plugins/contracts/*.contract.test.ts`: - **auth** - Контракт потоку auth -- **auth-choice** - Вибір/селекція auth +- **auth-choice** - Вибір/селектор auth - **catalog** - API каталогу моделей - **discovery** - Виявлення plugin - **loader** - Завантаження plugin -- **runtime** - Runtime провайдера +- **runtime** - Runtime provider - **shape** - Форма/інтерфейс plugin -- **wizard** - Майстер налаштування +- **wizard** - Wizard налаштування ### Коли запускати -- Після зміни export-ів або subpath-ів plugin-sdk +- Після зміни експортів або підшляхів plugin-sdk - Після додавання або зміни channel чи provider plugin - Після рефакторингу реєстрації або виявлення plugin -Контрактні тести запускаються в CI і не потребують реальних API-ключів. +Contract-тести запускаються в CI і не потребують реальних API key. ## Додавання регресій (рекомендації) Коли ви виправляєте проблему provider/model, виявлену в live: -- Додайте безпечну для CI регресію, якщо можливо (mock/stub provider або захоплення точної трансформації форми запиту) -- Якщо проблема за своєю природою лише live (rate limits, політики auth), залишайте live-тест вузьким і opt-in через env vars -- Переважно націлюватися на найменший рівень, який виявляє баг: - - баг конвертації/відтворення запиту провайдера → тест прямих моделей - - баг pipeline сесії/історії/інструментів gateway → live smoke gateway або безпечний для CI mock-тест gateway -- Захист traversal для SecretRef: - - `src/secrets/exec-secret-ref-id-parity.test.ts` виводить одну вибіркову ціль на клас SecretRef із метаданих registry (`listSecretTargetRegistryEntries()`), а потім перевіряє, що exec id сегментів traversal відхиляються. - - Якщо ви додаєте нове сімейство цілей SecretRef з `includeInPlan` у `src/secrets/target-registry-data.ts`, оновіть `classifyTargetClass` у цьому тесті. Тест навмисно падає на некласифікованих target id, щоб нові класи не можна було пропустити мовчки. +- Додайте безпечну для CI регресію, якщо це можливо (mock/stub provider або фіксація точної трансформації форми запиту) +- Якщо проблема за своєю природою лише live (rate limit, політики auth), залишайте live-тест вузьким і opt-in через env-змінні +- Віддавайте перевагу найменшому рівню, який виявляє баг: + - баг перетворення/повторення запиту provider → direct models test + - баг у pipeline сесії/історії/tool gateway → 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, щоб нові класи не можна було тихо пропустити. ## Пов’язане diff --git a/docs/uk/nodes/media-understanding.md b/docs/uk/nodes/media-understanding.md index 310648318..5728361d2 100644 --- a/docs/uk/nodes/media-understanding.md +++ b/docs/uk/nodes/media-understanding.md @@ -2,54 +2,54 @@ read_when: - Проєктування або рефакторинг розуміння медіа - Налаштування попередньої обробки вхідного аудіо/відео/зображень -summary: Вхідне розуміння зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера та CLI +summary: Розуміння вхідних зображень/аудіо/відео (необов’язково) з резервними варіантами через провайдера + CLI title: Розуміння медіа x-i18n: - generated_at: "2026-04-24T01:43:33Z" + generated_at: "2026-04-25T00:01:29Z" model: gpt-5.4 provider: openai - source_hash: a9eb9449fbc1bed170bbef213aa43d71d4146edbc0dd626ef50af9e044a8e299 + source_hash: 108a90f15f7c86539d01a880e601d2c43305029a2e29330778c60fddf79a4d32 source_path: nodes/media-understanding.md workflow: 15 --- -# Розуміння медіа — вхідне (2026-01-17) +# Розуміння медіа — вхідні дані (2026-01-17) -OpenClaw може **узагальнювати вхідні медіа** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдерів, і цю функцію можна вимкнути або налаштувати. Якщо розуміння вимкнено, моделі, як і раніше, отримують оригінальні файли/URL. +OpenClaw може **узагальнювати вхідні медіафайли** (зображення/аудіо/відео) до запуску конвеєра відповіді. Він автоматично визначає, коли доступні локальні інструменти або ключі провайдера, і цю функцію можна вимкнути або налаштувати. Якщо розуміння вимкнено, моделі, як і раніше, отримують оригінальні файли/URL. -Поведінка медіа, специфічна для вендора, реєструється плагінами вендорів, тоді як ядро OpenClaw володіє спільною конфігурацією `tools.media`, порядком резервного переходу та інтеграцією з конвеєром відповіді. +Поведінка медіа, специфічна для постачальника, реєструється через plugin постачальника, тоді як ядро OpenClaw керує спільною конфігурацією `tools.media`, порядком резервного перемикання та інтеграцією з конвеєром відповіді. ## Цілі -- Необов’язково: попередньо перетворювати вхідні медіа на короткий текст для швидшої маршрутизації та кращого розбору команд. -- Завжди зберігати доставку оригінальних медіа до моделі. -- Підтримувати **API провайдерів** і **резервні варіанти через CLI**. -- Дозволяти кілька моделей з упорядкованим резервним переходом (помилка/розмір/тайм-аут). +- Необов’язково: попередньо зводити вхідні медіафайли до короткого тексту для швидшої маршрутизації + кращого розбору команд. +- Завжди зберігати доставку оригінального медіа до моделі. +- Підтримувати **API провайдерів** і **резервні варіанти CLI**. +- Дозволяти кілька моделей з упорядкованим резервним перемиканням (помилка/розмір/тайм-аут). ## Поведінка на високому рівні 1. Зібрати вхідні вкладення (`MediaPaths`, `MediaUrls`, `MediaTypes`). -2. Для кожної увімкненої можливості (зображення/аудіо/відео) вибрати вкладення згідно з політикою (типово: **перше**). -3. Вибрати перший придатний запис моделі (розмір + можливість + автентифікація). -4. Якщо модель не спрацювала або медіа надто велике, **перейти до наступного запису**. +2. Для кожної ввімкненої можливості (зображення/аудіо/відео) вибрати вкладення відповідно до політики (типово: **перше**). +3. Вибрати перший допустимий запис моделі (розмір + можливість + автентифікація). +4. Якщо модель не спрацьовує або медіафайл надто великий, **переключитися на наступний запис**. 5. У разі успіху: - `Body` стає блоком `[Image]`, `[Audio]` або `[Video]`. - Для аудіо встановлюється `{{Transcript}}`; розбір команд використовує текст підпису, якщо він є, інакше — транскрипт. - Підписи зберігаються як `User text:` усередині блоку. -Якщо розуміння не вдалося або його вимкнено, **потік відповіді продовжується** з оригінальним тілом і вкладеннями. +Якщо розуміння не спрацювало або вимкнене, **потік відповіді продовжується** з оригінальним тілом + вкладеннями. ## Огляд конфігурації -`tools.media` підтримує **спільні моделі** та перевизначення для окремих можливостей: +`tools.media` підтримує **спільні моделі** плюс перевизначення для кожної можливості окремо: -- `tools.media.models`: список спільних моделей (використовуйте `capabilities` для обмеження). +- `tools.media.models`: спільний список моделей (використовуйте `capabilities` для обмеження). - `tools.media.image` / `tools.media.audio` / `tools.media.video`: - типові значення (`prompt`, `maxChars`, `maxBytes`, `timeoutSeconds`, `language`) - перевизначення провайдера (`baseUrl`, `headers`, `providerOptions`) - - аудіоопції Deepgram через `tools.media.audio.providerOptions.deepgram` - - елементи керування відображенням транскрипту аудіо (`echoTranscript`, типово `false`; `echoFormat`) - - необов’язковий список `models` **для окремої можливості** (має пріоритет над спільними моделями) + - параметри аудіо Deepgram через `tools.media.audio.providerOptions.deepgram` + - елементи керування ехо транскрипту аудіо (`echoTranscript`, типово `false`; `echoFormat`) + - необов’язковий список `models` **для конкретної можливості** (має пріоритет над спільними моделями) - політика `attachments` (`mode`, `maxAttachments`, `prefer`) - `scope` (необов’язкове обмеження за channel/chatType/session key) - `tools.media.concurrency`: максимальна кількість одночасних запусків можливостей (типово **2**). @@ -117,8 +117,8 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб Шаблони CLI також можуть використовувати: - `{{MediaDir}}` (каталог, що містить медіафайл) -- `{{OutputDir}}` (робочий каталог, створений для цього запуску) -- `{{OutputBase}}` (базовий шлях робочого файла без розширення) +- `{{OutputDir}}` (тимчасовий каталог, створений для цього запуску) +- `{{OutputBase}}` (базовий шлях до тимчасового файла, без розширення) ## Типові значення та обмеження @@ -133,18 +133,18 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб Правила: -- Якщо медіа перевищує `maxBytes`, ця модель пропускається і **робиться спроба з наступною моделлю**. -- Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через провайдера/CLI. -- Якщо модель повертає більше ніж `maxChars`, вивід обрізається. -- `prompt` типово має простий вигляд “Describe the {media}.” плюс підказка щодо `maxChars` (лише для зображень/відео). -- Якщо активна основна модель зображень уже нативно підтримує vision, OpenClaw пропускає блок підсумку `[Image]` і натомість передає оригінальне зображення в модель. -- Якщо основна модель Gateway/WebChat підтримує лише текст, вкладення зображень зберігаються як вивантажені посилання `media://inbound/*`, щоб інструмент зображень або налаштована модель зображень усе ще могли їх перевірити замість втрати вкладення. -- Явні запити `openclaw infer image describe --model ` відрізняються: вони запускають цей provider/model з підтримкою зображень напряму, зокрема посилання Ollama на кшталт `ollama/qwen2.5vl:7b`. -- Якщо `.enabled: true`, але моделі не налаштовано, OpenClaw пробує **активну модель відповіді**, якщо її провайдер підтримує цю можливість. +- Якщо медіафайл перевищує `maxBytes`, ця модель пропускається і **пробується наступна модель**. +- Аудіофайли менші за **1024 байти** вважаються порожніми/пошкодженими й пропускаються до транскрибування через provider/CLI. +- Якщо модель повертає більше, ніж `maxChars`, вивід обрізається. +- Типове значення `prompt` — просте “Describe the {media}.” плюс вказівка щодо `maxChars` (лише для зображення/відео). +- Якщо активна основна модель для зображень уже нативно підтримує зір, OpenClaw пропускає блок узагальнення `[Image]` і натомість передає оригінальне зображення в модель. +- Якщо основна модель Gateway/WebChat є лише текстовою, вкладення зображень зберігаються як винесені посилання `media://inbound/*`, щоб інструменти для зображень/PDF або налаштована модель для зображень усе ще могли їх аналізувати замість втрати вкладення. +- Явні запити `openclaw infer image describe --model ` відрізняються: вони напряму запускають указаного provider/model із підтримкою зображень, включно з посиланнями Ollama, такими як `ollama/qwen2.5vl:7b`. +- Якщо `.enabled: true`, але моделі не налаштовано, OpenClaw намагається використати **активну модель відповіді**, якщо її провайдер підтримує цю можливість. ### Автовизначення розуміння медіа (типово) -Якщо `tools.media..enabled` **не** встановлено в `false` і ви не налаштували моделі, OpenClaw виконує автовизначення в такому порядку і **зупиняється на першому робочому варіанті**: +Якщо `tools.media..enabled` **не** встановлено в `false` і ви не налаштували моделі, OpenClaw автоматично визначає у такому порядку і **зупиняється на першому робочому варіанті**: 1. **Активна модель відповіді**, якщо її провайдер підтримує цю можливість. 2. Основні/резервні посилання **`agents.defaults.imageModel`** (лише для зображень). @@ -154,10 +154,10 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб - `whisper` (Python CLI; автоматично завантажує моделі) 4. **Gemini CLI** (`gemini`) з використанням `read_many_files` 5. **Автентифікація провайдера** - - Налаштовані записи `models.providers.*`, які підтримують цю можливість, пробуються до вбудованого порядку резервного переходу. - - Провайдери з конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим плагіном вендора. - - Розуміння зображень через Ollama доступне за явного вибору, наприклад через `agents.defaults.imageModel` або `openclaw infer image describe --model ollama/`. - - Вбудований порядок резервного переходу: + - Налаштовані записи `models.providers.*`, що підтримують цю можливість, пробуються до вбудованого порядку резервного перемикання. + - Провайдери конфігурації лише для зображень із моделлю, що підтримує зображення, автоматично реєструються для розуміння медіа, навіть якщо вони не є вбудованим vendor plugin. + - Розуміння зображень Ollama доступне за явного вибору, наприклад через `agents.defaults.imageModel` або `openclaw infer image describe --model ollama/`. + - Вбудований порядок резервного перемикання: - Аудіо: OpenAI → Groq → xAI → Deepgram → Google → Mistral - Зображення: OpenAI → Anthropic → Google → MiniMax → MiniMax Portal → Z.AI - Відео: Google → Qwen → Moonshot @@ -176,19 +176,19 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб } ``` -Примітка: визначення бінарних файлів є best-effort у macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну CLI-модель з повним шляхом до команди. +Примітка: виявлення бінарних файлів є best-effort на macOS/Linux/Windows; переконайтеся, що CLI є в `PATH` (ми розгортаємо `~`), або задайте явну модель CLI з повним шляхом до команди. -### Підтримка середовища проксі (моделі провайдерів) +### Підтримка проксі через середовище (моделі provider) -Коли увімкнено розуміння медіа **audio** і **video** на основі провайдера, OpenClaw враховує стандартні змінні середовища вихідного проксі для HTTP-викликів провайдера: +Коли ввімкнено розуміння медіа **аудіо** та **відео** на основі провайдера, OpenClaw враховує стандартні змінні середовища вихідного проксі для HTTP-викликів провайдера: - `HTTPS_PROXY` - `HTTP_PROXY` - `https_proxy` - `http_proxy` -Якщо змінні середовища проксі не задані, розуміння медіа використовує прямий вихідний трафік. -Якщо значення проксі некоректне, OpenClaw записує попередження в журнал і повертається до прямого отримання. +Якщо змінні середовища проксі не задано, розуміння медіа використовує прямий вихідний трафік. +Якщо значення проксі має неправильний формат, OpenClaw записує попередження в журнал і повертається до прямого отримання. ## Можливості (необов’язково) @@ -207,33 +207,33 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб - `deepgram`: **audio** - Будь-який каталог `models.providers..models[]` з моделлю, що підтримує зображення: **image** -Для записів CLI **задавайте `capabilities` явно**, щоб уникнути неочікуваних збігів. -Якщо ви пропускаєте `capabilities`, запис придатний для списку, у якому він з’являється. +Для записів CLI **явно задавайте `capabilities`**, щоб уникнути неочікуваних збігів. +Якщо ви опускаєте `capabilities`, запис вважається допустимим для того списку, в якому він з’являється. ## Матриця підтримки провайдерів (інтеграції OpenClaw) -| Можливість | Інтеграція провайдера | Примітки | -| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Зображення | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Плагіни вендорів реєструють підтримку зображень; `openai-codex/*` використовує механізм OAuth-провайдера; `codex/*` використовує обмежений хід Codex app-server; MiniMax і MiniMax OAuth обидва використовують `MiniMax-VL-01`; провайдери конфігурації з підтримкою зображень реєструються автоматично. | -| Аудіо | OpenAI, Groq, Deepgram, Google, Mistral | Транскрибування через провайдера (Whisper/Deepgram/Gemini/Voxtral). | -| Відео | Google, Qwen, Moonshot | Розуміння відео через провайдера за допомогою плагінів вендорів; розуміння відео Qwen використовує Standard DashScope endpoints. | +| Capability | Provider integration | Notes | +| ---------- | ---------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Image | OpenAI, OpenAI Codex OAuth, Codex app-server, OpenRouter, Anthropic, Google, MiniMax, Moonshot, Qwen, Z.AI, config providers | Vendor plugins register image support; `openai-codex/*` uses OAuth provider plumbing; `codex/*` uses a bounded Codex app-server turn; MiniMax and MiniMax OAuth both use `MiniMax-VL-01`; image-capable config providers auto-register. | +| Audio | OpenAI, Groq, Deepgram, Google, Mistral | Provider transcription (Whisper/Deepgram/Gemini/Voxtral). | +| Video | Google, Qwen, Moonshot | Provider video understanding via vendor plugins; Qwen video understanding uses the Standard DashScope endpoints. | Примітка щодо MiniMax: -- Розуміння зображень через `minimax` і `minimax-portal` походить із провайдера медіа `MiniMax-VL-01`, що належить плагіну. -- Вбудований текстовий каталог MiniMax, як і раніше, починається з режиму лише тексту; явні записи `models.providers.minimax` матеріалізують посилання чату M2.7 з підтримкою зображень. +- `minimax` і `minimax-portal` для розуміння зображень походять із media provider `MiniMax-VL-01`, яким керує plugin. +- Вбудований текстовий каталог MiniMax, як і раніше, спочатку є лише текстовим; явні записи `models.providers.minimax` матеріалізують chat-посилання M2.7 із підтримкою зображень. ## Рекомендації щодо вибору моделі -- Віддавайте перевагу найсильнішій моделі останнього покоління, доступній для кожної медіаможливості, коли важливі якість і безпека. -- Для агентів з увімкненими інструментами, які працюють із недовіреними вхідними даними, уникайте старіших/слабших медіамоделей. -- Тримайте принаймні один резервний варіант для кожної можливості з міркувань доступності (якісна модель + швидша/дешевша модель). +- Надавайте перевагу найсильнішій моделі останнього покоління, доступній для кожної медіаможливості, коли важливі якість і безпека. +- Для агентів з увімкненими інструментами, які обробляють недовірені вхідні дані, уникайте старіших/слабших медіамоделей. +- Тримайте принаймні один резервний варіант для кожної можливості на випадок недоступності (якісна модель + швидша/дешевша модель). - Резервні варіанти CLI (`whisper-cli`, `whisper`, `gemini`) корисні, коли API провайдерів недоступні. -- Примітка щодо `parakeet-mlx`: із `--output-dir` OpenClaw читає `/.txt`, коли формат виводу — `txt` (або не заданий); для форматів, відмінних від `txt`, використовується stdout. +- Примітка щодо `parakeet-mlx`: з `--output-dir` OpenClaw читає `/.txt`, коли формат виводу — `txt` (або не вказаний); формати, відмінні від `txt`, повертаються до stdout. ## Політика вкладень -Параметр `attachments` для окремої можливості керує тим, які вкладення обробляються: +`attachments` для конкретної можливості керує тим, які вкладення обробляються: - `mode`: `first` (типово) або `all` - `maxAttachments`: обмеження кількості оброблюваних вкладень (типово **1**) @@ -241,18 +241,18 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб Коли `mode: "all"`, результати позначаються як `[Image 1/2]`, `[Audio 2/2]` тощо. -Поведінка витягування з файлових вкладень: +Поведінка вилучення тексту з файлових вкладень: -- Витягнутий текст файлу обгортається як **недовірений зовнішній вміст** перед додаванням до підказки медіа. -- Вставлений блок використовує явні маркери меж на кшталт `<<>>` / - `<<>>` і містить рядок метаданих `Source: External`. -- Цей шлях витягування вкладень навмисно пропускає довгий банер `SECURITY NOTICE:`, щоб не роздувати підказку медіа; маркери меж і метадані при цьому все одно зберігаються. -- Якщо файл не містить тексту, який можна витягнути, OpenClaw вставляє `[No extractable text]`. -- Якщо PDF у цьому шляху повертається до відтворених зображень сторінок, підказка медіа зберігає заповнювач `[PDF content rendered to images; images not forwarded to model]`, тому що цей крок витягування вкладень пересилає текстові блоки, а не відтворені зображення PDF. +- Вилучений текст файла обгортається як **недовірений зовнішній вміст**, перш ніж його буде додано до media prompt. +- Вставлений блок використовує явні маркери меж, такі як `<<>>` / + `<<>>`, і містить рядок метаданих `Source: External`. +- Цей шлях вилучення вкладень навмисно опускає довгий банер `SECURITY NOTICE:`, щоб не роздувати media prompt; маркери меж і метадані при цьому все одно зберігаються. +- Якщо файл не містить тексту, який можна вилучити, OpenClaw вставляє `[No extractable text]`. +- Якщо PDF у цьому шляху повертається до рендерингу сторінок як зображень, media prompt зберігає заповнювач `[PDF content rendered to images; images not forwarded to model]`, оскільки цей крок вилучення вкладень передає текстові блоки, а не відрендерені PDF-зображення. ## Приклади конфігурації -### 1) Список спільних моделей + перевизначення +### 1) Спільний список моделей + перевизначення ```json5 { @@ -360,7 +360,7 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб } ``` -### 4) Один мультимодальний запис (явно вказані можливості) +### 4) Один multimodal-запис (явні можливості) ```json5 { @@ -398,23 +398,23 @@ OpenClaw може **узагальнювати вхідні медіа** (зоб } ``` -## Вивід статусу +## Вивід стану -Коли виконується розуміння медіа, `/status` містить короткий рядок підсумку: +Коли запускається розуміння медіа, `/status` містить короткий підсумковий рядок: ``` -📎 Медіа: зображення ok (openai/gpt-5.4) · аудіо пропущено (maxBytes) +📎 Media: image ok (openai/gpt-5.4) · audio skipped (maxBytes) ``` -Тут показуються результати для кожної можливості та вибраний provider/model, якщо застосовно. +Це показує результати для кожної можливості та вибраного provider/model, якщо застосовно. ## Примітки - Розуміння є **best-effort**. Помилки не блокують відповіді. - Вкладення все одно передаються моделям, навіть коли розуміння вимкнено. -- Використовуйте `scope`, щоб обмежити, де запускається розуміння (наприклад, лише в особистих повідомленнях). +- Використовуйте `scope`, щоб обмежити, де запускається розуміння (наприклад, лише в DM). -## Пов’язана документація +## Пов’язані документи - [Конфігурація](/uk/gateway/configuration) - [Підтримка зображень і медіа](/uk/nodes/images) diff --git a/docs/uk/plugins/building-plugins.md b/docs/uk/plugins/building-plugins.md index 5af324235..2841978e5 100644 --- a/docs/uk/plugins/building-plugins.md +++ b/docs/uk/plugins/building-plugins.md @@ -1,60 +1,49 @@ --- read_when: - Ви хочете створити новий Plugin для OpenClaw - - Вам потрібен швидкий старт для розробки Plugin-ів + - Вам потрібен швидкий старт для розробки Plugin - Ви додаєте новий канал, провайдера, інструмент або іншу можливість до OpenClaw sidebarTitle: Getting Started summary: Створіть свій перший Plugin для OpenClaw за лічені хвилини -title: Створення Plugin-ів +title: Створення плагінів x-i18n: - generated_at: "2026-04-24T20:32:17Z" + generated_at: "2026-04-25T00:01:40Z" model: gpt-5.4 provider: openai - source_hash: fc6a4b97c403d7d381fae13e3815737a4b21144755e924bdf9d63c22d4cac844 + source_hash: 69c7ffb65750fd0c1fa786600c55a371dace790b8b1034fa42f4b80f5f7146df source_path: plugins/building-plugins.md workflow: 15 --- -Plugin-и розширюють OpenClaw новими можливостями: канали, провайдери моделей, -мовлення, транскрибування в реальному часі, голос у реальному часі, розуміння медіа, генерація -зображень, генерація відео, отримання вебданих, вебпошук, інструменти агентів або -будь-яка комбінація. +Plugins розширюють OpenClaw новими можливостями: канали, провайдери моделей, мовлення, транскрипція в реальному часі, голос у реальному часі, розуміння медіа, генерація зображень, генерація відео, web fetch, web search, інструменти агента або будь-яка їх комбінація. -Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в -[ClawHub](/uk/tools/clawhub) або npm, і користувачі встановлять його за допомогою -`openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub, а -потім автоматично переходить до npm. +Вам не потрібно додавати свій Plugin до репозиторію OpenClaw. Опублікуйте його в [ClawHub](/uk/tools/clawhub) або npm, а користувачі встановлять його за допомогою `openclaw plugins install `. OpenClaw спочатку намагається використати ClawHub і автоматично переходить на npm, якщо це потрібно. ## Передумови - Node >= 22 і менеджер пакетів (npm або pnpm) - Знайомство з TypeScript (ESM) -- Для Plugin-ів у репозиторії: клонований репозиторій і виконано `pnpm install` +- Для Plugin у репозиторії: репозиторій клоновано і виконано `pnpm install` -## Який тип Plugin-а? +## Який тип Plugin? Підключіть OpenClaw до платформи обміну повідомленнями (Discord, IRC тощо) - Додайте провайдера моделей (LLM, проксі або власний endpoint) + Додайте провайдера моделі (LLM, проксі або власну кінцеву точку) - - Зареєструйте інструменти агента, event hooks або сервіси — продовження нижче + + Зареєструйте інструменти агента, хуки подій або сервіси — продовження нижче -Для Plugin-а каналу, який не гарантовано буде встановлений під час виконання -onboarding/setup, використовуйте `createOptionalChannelSetupSurface(...)` з -`openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера setup + wizard, -яка повідомляє про вимогу встановлення та блокує реальні записи конфігурації, -доки Plugin не буде встановлено. +Для Plugin каналу, який не гарантовано буде встановлений на момент запуску онбордингу/налаштування, використовуйте `createOptionalChannelSetupSurface(...)` з `openclaw/plugin-sdk/channel-setup`. Він створює пару адаптера налаштування + майстра, яка повідомляє про вимогу встановлення та забороняє реальні записи конфігурації, доки Plugin не буде встановлено. -## Швидкий старт: Plugin інструмента +## Швидкий старт: Plugin інструменту -Цей посібник створює мінімальний Plugin, який реєструє інструмент агента. Для Plugin-ів -каналів і провайдерів є окремі посібники за посиланнями вище. +У цьому покроковому прикладі створюється мінімальний Plugin, який реєструє інструмент агента. Для Plugin каналів і провайдерів є окремі посібники за посиланнями вище. @@ -91,9 +80,7 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac ``` - Кожному Plugin-у потрібен маніфест, навіть якщо в ньому немає конфігурації. Див. - [Manifest](/uk/plugins/manifest) для повної схеми. Канонічні фрагменти публікації в ClawHub - містяться в `docs/snippets/plugin-publish/`. + Кожному Plugin потрібен маніфест, навіть якщо конфігурації немає. Повну схему дивіться в [Manifest](/uk/plugins/manifest). Канонічні фрагменти для публікації в ClawHub розміщено в `docs/snippets/plugin-publish/`. @@ -121,15 +108,14 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac }); ``` - `definePluginEntry` призначений для Plugin-ів, які не є каналами. Для каналів використовуйте - `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). - Повний список параметрів точки входу див. у [Entry Points](/uk/plugins/sdk-entrypoints). + `definePluginEntry` призначений для Plugin, які не є каналами. Для каналів використовуйте `defineChannelPluginEntry` — див. [Channel Plugins](/uk/plugins/sdk-channel-plugins). + Повний список параметрів точки входу дивіться в [Entry Points](/uk/plugins/sdk-entrypoints). - **Зовнішні Plugin-и:** виконайте перевірку та опублікуйте через ClawHub, а потім встановіть: + **Зовнішні Plugins:** перевірте й опублікуйте через ClawHub, а потім встановіть: ```bash clawhub package publish your-org/your-plugin --dry-run @@ -137,10 +123,9 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac openclaw plugins install clawhub:@myorg/openclaw-my-plugin ``` - OpenClaw також перевіряє ClawHub перед npm для звичайних специфікацій пакетів, таких як - `@myorg/openclaw-my-plugin`. + OpenClaw також перевіряє ClawHub перед npm для простих специфікацій пакетів, таких як `@myorg/openclaw-my-plugin`. - **Plugin-и в репозиторії:** розмістіть у дереві workspace вбудованих Plugin-ів — вони будуть виявлені автоматично. + **Plugins у репозиторії:** розмістіть у дереві workspace вбудованих Plugin — їх буде виявлено автоматично. ```bash pnpm test -- /my-plugin/ @@ -149,70 +134,59 @@ onboarding/setup, використовуйте `createOptionalChannelSetupSurfac -## Можливості Plugin-а +## Можливості Plugin -Один Plugin може реєструвати будь-яку кількість можливостей через об’єкт `api`: +Один Plugin може зареєструвати будь-яку кількість можливостей через об’єкт `api`: -| Можливість | Метод реєстрації | Докладний посібник | -| --------------------- | ---------------------------------------------- | ------------------------------------------------------------------------------- | -| Текстова інференція (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | -| Backend інференції CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) | -| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | -| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Транскрибування в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Отримання вебданих | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Вебпошук | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | -| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [SDK Overview](/uk/plugins/sdk-overview#registration-api) | -| Інструменти агентів | `api.registerTool(...)` | Нижче | -| Користувацькі команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| Plugin hooks | `api.on(...)` | [Plugin hooks](/uk/plugins/hooks) | -| Внутрішні event hooks | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) | -| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Можливість | Метод реєстрації | Детальний посібник | +| ---------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------ | +| Текстовий inference (LLM) | `api.registerProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins) | +| Бекенд inference для CLI | `api.registerCliBackend(...)` | [CLI Backends](/uk/gateway/cli-backends) | +| Канал / повідомлення | `api.registerChannel(...)` | [Channel Plugins](/uk/plugins/sdk-channel-plugins) | +| Мовлення (TTS/STT) | `api.registerSpeechProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Транскрипція в реальному часі | `api.registerRealtimeTranscriptionProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Голос у реальному часі | `api.registerRealtimeVoiceProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Розуміння медіа | `api.registerMediaUnderstandingProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація зображень | `api.registerImageGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація музики | `api.registerMusicGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Генерація відео | `api.registerVideoGenerationProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web fetch | `api.registerWebFetchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Web search | `api.registerWebSearchProvider(...)` | [Provider Plugins](/uk/plugins/sdk-provider-plugins#step-5-add-extra-capabilities) | +| Middleware результатів інструментів | `api.registerAgentToolResultMiddleware(...)` | [Огляд SDK](/uk/plugins/sdk-overview#registration-api) | +| Інструменти агента | `api.registerTool(...)` | Нижче | +| Власні команди | `api.registerCommand(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| Хуки Plugin | `api.on(...)` | [Хуки Plugin](/uk/plugins/hooks) | +| Внутрішні хуки подій | `api.registerHook(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | +| HTTP-маршрути | `api.registerHttpRoute(...)` | [Internals](/uk/plugins/architecture-internals#gateway-http-routes) | +| Підкоманди CLI | `api.registerCli(...)` | [Entry Points](/uk/plugins/sdk-entrypoints) | -Повний API реєстрації див. у [SDK Overview](/uk/plugins/sdk-overview#registration-api). +Повний API реєстрації дивіться в [Огляд SDK](/uk/plugins/sdk-overview#registration-api). -Вбудовані Plugin-и можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм -потрібне асинхронне переписування результатів інструментів до того, як модель побачить вивід. Вкажіть -цільові harnesses у `contracts.agentToolResultMiddleware`, наприклад -`["pi", "codex-app-server"]`. Це довірений механізм для вбудованих Plugin-ів; зовнішнім -Plugin-ам варто надавати перевагу звичайним Plugin hooks OpenClaw, якщо тільки OpenClaw не отримає -явну політику довіри для цієї можливості. +Вбудовані Plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли їм потрібно асинхронно переписувати результати інструментів до того, як модель побачить вивід. Оголосіть цільові runtime у `contracts.agentToolResultMiddleware`, наприклад `["pi", "codex"]`. Це шов довіри для вбудованих Plugin; зовнішнім Plugins слід віддавати перевагу звичайним хукам Plugin OpenClaw, якщо тільки в OpenClaw не з’явиться явна політика довіри для цієї можливості. -Якщо ваш Plugin реєструє користувацькі методи gateway RPC, використовуйте -префікс, специфічний для Plugin-а. Простори імен адміністрування ядра (`config.*`, -`exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди відповідають -`operator.admin`, навіть якщо Plugin запитує вужчу область доступу. +Якщо ваш Plugin реєструє власні методи Gateway RPC, використовуйте префікс, специфічний для Plugin. Простори імен адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, `update.*`) залишаються зарезервованими й завжди зіставляються з `operator.admin`, навіть якщо Plugin запитує вужчу область видимості. -Семантика захисту hooks, про яку слід пам’ятати: +Семантика guard-хуків, яку варто враховувати: -- `before_tool_call`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `before_tool_call`: `{ block: false }` розглядається як відсутність рішення. -- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує у користувача підтвердження через overlay підтвердження exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. -- `before_install`: `{ block: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `before_install`: `{ block: false }` розглядається як відсутність рішення. -- `message_sending`: `{ cancel: true }` є остаточним рішенням і зупиняє обробники з нижчим пріоритетом. -- `message_sending`: `{ cancel: false }` розглядається як відсутність рішення. -- `message_received`: надавайте перевагу типізованому полю `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для додаткових даних, специфічних для каналу. -- `message_sending`: надавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId`, а не ключам metadata, специфічним для каналу. +- `before_tool_call`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом. +- `before_tool_call`: `{ block: false }` вважається відсутністю рішення. +- `before_tool_call`: `{ requireApproval: true }` призупиняє виконання агента й запитує схвалення користувача через накладку схвалення exec, кнопки Telegram, взаємодії Discord або команду `/approve` у будь-якому каналі. +- `before_install`: `{ block: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом. +- `before_install`: `{ block: false }` вважається відсутністю рішення. +- `message_sending`: `{ cancel: true }` є термінальним результатом і зупиняє обробники з нижчим пріоритетом. +- `message_sending`: `{ cancel: false }` вважається відсутністю рішення. +- `message_received`: віддавайте перевагу типізованому полю `threadId`, коли вам потрібна маршрутизація вхідних потоків/тем. `metadata` залишайте для специфічних для каналу доповнень. +- `message_sending`: віддавайте перевагу типізованим полям маршрутизації `replyToId` / `threadId`, а не специфічним для каналу ключам metadata. -Команда `/approve` обробляє як підтвердження exec, так і підтвердження Plugin-ів з обмеженим fallback: якщо ідентифікатор підтвердження exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через підтвердження Plugin-ів. Переспрямування підтверджень Plugin-ів можна налаштувати окремо через `approvals.plugin` у конфігурації. +Команда `/approve` обробляє як схвалення exec, так і схвалення Plugin, із обмеженим fallback: якщо ідентифікатор схвалення exec не знайдено, OpenClaw повторно пробує той самий ідентифікатор через схвалення Plugin. Переспрямування схвалень Plugin можна налаштувати окремо через `approvals.plugin` у конфігурації. -Якщо користувацька логіка підтвердження має визначати той самий випадок обмеженого fallback, -використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` -замість ручного зіставлення рядків закінчення терміну підтвердження. +Якщо власна логіка схвалення має визначати той самий випадок обмеженого fallback, використовуйте `isApprovalNotFoundError` з `openclaw/plugin-sdk/error-runtime` замість ручного зіставлення рядків закінчення строку дії схвалення. -Приклади й довідник hooks див. у [Plugin hooks](/uk/plugins/hooks). +Приклади й довідку щодо хуків дивіться в [Хуки Plugin](/uk/plugins/hooks). -## Реєстрація інструментів агентів +## Реєстрація інструментів агента -Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди -доступні) або необов’язковими (користувач сам вмикає їх): +Інструменти — це типізовані функції, які може викликати LLM. Вони можуть бути обов’язковими (завжди доступні) або необов’язковими (користувач вмикає їх окремо): ```typescript register(api) { @@ -251,11 +225,11 @@ register(api) { - Назви інструментів не повинні конфліктувати з інструментами ядра (конфлікти пропускаються) - Використовуйте `optional: true` для інструментів із побічними ефектами або додатковими вимогами до бінарних файлів -- Користувачі можуть увімкнути всі інструменти з Plugin-а, додавши ідентифікатор Plugin-а до `tools.allow` +- Користувачі можуть увімкнути всі інструменти Plugin, додавши ідентифікатор Plugin до `tools.allow` -## Угоди щодо імпортів +## Угоди щодо імпорту -Завжди імпортуйте з цільових шляхів `openclaw/plugin-sdk/`: +Завжди імпортуйте з вузькоспрямованих шляхів `openclaw/plugin-sdk/`: ```typescript import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry"; @@ -265,72 +239,66 @@ import { createPluginRuntimeStore } from "openclaw/plugin-sdk/runtime-store"; import { ... } from "openclaw/plugin-sdk"; ``` -Повний довідник підшляхів див. у [SDK Overview](/uk/plugins/sdk-overview). +Повний довідник підшляхів дивіться в [Огляд SDK](/uk/plugins/sdk-overview). -У межах вашого Plugin-а використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для -внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK. +У межах вашого Plugin використовуйте локальні barrel-файли (`api.ts`, `runtime-api.ts`) для внутрішніх імпортів — ніколи не імпортуйте власний Plugin через його шлях SDK. -Для Plugin-ів провайдерів зберігайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах -кореня пакета, якщо тільки цей механізм не є справді загальним. Поточні вбудовані приклади: +Для Plugin провайдерів тримайте допоміжні функції, специфічні для провайдера, у цих barrel-файлах у корені пакета, якщо тільки цей шов не є справді загальним. Поточні вбудовані приклади: -- Anthropic: обгортки потоків Claude і допоміжні засоби `service_tier` / beta -- OpenAI: конструктори провайдерів, допоміжні засоби для моделей за замовчуванням, провайдери реального часу -- OpenRouter: конструктор провайдера плюс допоміжні засоби onboarding/config +- Anthropic: обгортки потоків Claude і допоміжні функції для `service_tier` / beta +- OpenAI: конструктори провайдерів, допоміжні функції для моделей за замовчуванням, провайдери реального часу +- OpenRouter: конструктор провайдера плюс допоміжні функції для онбордингу/конфігурації -Якщо допоміжний засіб корисний лише в межах одного пакета вбудованого провайдера, залишайте його -на цьому рівні пакета замість перенесення до `openclaw/plugin-sdk/*`. +Якщо допоміжна функція корисна лише всередині одного пакета вбудованого провайдера, залишайте її на шві кореня цього пакета замість перенесення в `openclaw/plugin-sdk/*`. -Деякі згенеровані механізми допоміжних засобів `openclaw/plugin-sdk/` усе ще існують для -підтримки вбудованих Plugin-ів і сумісності, наприклад -`plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Розглядайте їх як зарезервовані -поверхні, а не як типовий шаблон для нових сторонніх Plugin-ів. +Деякі згенеровані шви допоміжних функцій `openclaw/plugin-sdk/` усе ще існують для підтримки та сумісності вбудованих Plugin, наприклад `plugin-sdk/feishu-setup` або `plugin-sdk/zalo-setup`. Сприймайте їх як зарезервовані поверхні, а не як типовий шаблон для нових сторонніх Plugin. ## Контрольний список перед поданням -**package.json** має коректні метадані `openclaw` +**package.json** має правильні метадані `openclaw` Маніфест **openclaw.plugin.json** присутній і валідний Точка входу використовує `defineChannelPluginEntry` або `definePluginEntry` -Усі імпорти використовують цільові шляхи `plugin-sdk/` +Усі імпорти використовують вузькоспрямовані шляхи `plugin-sdk/` Внутрішні імпорти використовують локальні модулі, а не self-imports через SDK Тести проходять (`pnpm test -- /my-plugin/`) -`pnpm check` проходить (для Plugin-ів у репозиторії) +`pnpm check` проходить (для Plugin у репозиторії) -## Тестування beta-релізів +## Тестування beta-релізу -1. Слідкуйте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів. -2. Протестуйте свій Plugin на beta-тегу щойно він з’явиться. Вікно до stable зазвичай становить лише кілька годин. -3. Після тестування напишіть у гілці вашого Plugin-а в каналі Discord `plugin-forum`: або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. +1. Стежте за тегами релізів GitHub у [openclaw/openclaw](https://github.com/openclaw/openclaw/releases) і підпишіться через `Watch` > `Releases`. Beta-теги мають вигляд `v2026.3.N-beta.1`. Ви також можете ввімкнути сповіщення для офіційного акаунта OpenClaw у X [@openclaw](https://x.com/openclaw) для анонсів релізів. +2. Протестуйте свій Plugin на beta-тезі щойно він з’явиться. Вікно до стабільного релізу зазвичай становить лише кілька годин. +3. Після тестування напишіть у гілці вашого Plugin у каналі Discord `plugin-forum`, вказавши або `all good`, або що саме зламалося. Якщо у вас ще немає гілки, створіть її. 4. Якщо щось зламалося, створіть або оновіть issue з назвою `Beta blocker: - ` і застосуйте мітку `beta-blocker`. Додайте посилання на issue у свою гілку. -5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у вашій гілці Discord. Учасники не можуть ставити мітки на PR, тому назва є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR будуть злиті; блокери без нього все одно можуть потрапити в реліз. Під час beta-тестування мейнтейнери стежать за цими гілками. -6. Відсутність повідомлень означає, що все добре. Якщо ви пропустите це вікно, ваше виправлення, імовірно, потрапить уже в наступний цикл. +5. Відкрийте PR до `main` з назвою `fix(): beta blocker - ` і додайте посилання на issue як у PR, так і у вашій гілці Discord. Учасники не можуть ставити мітки PR, тому назва є сигналом на боці PR для мейнтейнерів і автоматизації. Блокери з PR буде змерджено; блокери без нього все одно можуть потрапити в реліз. Мейнтейнери стежать за цими гілками під час beta-тестування. +6. Відсутність повідомлень означає, що все гаразд. Якщо ви пропустите вікно, ваше виправлення, імовірно, потрапить до наступного циклу. -## Подальші кроки +## Наступні кроки - - Створіть Plugin каналу обміну повідомленнями + + Створіть Plugin каналу повідомлень - - Створіть Plugin провайдера моделей + + Створіть Plugin провайдера моделі - + Карта імпортів і довідник API реєстрації - + TTS, пошук, subagent через api.runtime - - Утиліти та шаблони тестування + + Утиліти й шаблони тестування - + Повний довідник зі схеми маніфесту ## Пов’язане -- [Plugin Architecture](/uk/plugins/architecture) — детальний огляд внутрішньої архітектури -- [SDK Overview](/uk/plugins/sdk-overview) — довідник SDK Plugin-ів -- [Manifest](/uk/plugins/manifest) — формат маніфесту plugin-а -- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin-ів каналів -- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin-ів провайдерів +- [Архітектура Plugin](/uk/plugins/architecture) — глибоке занурення у внутрішню архітектуру +- [Огляд SDK](/uk/plugins/sdk-overview) — довідник SDK Plugin +- [Manifest](/uk/plugins/manifest) — формат маніфесту Plugin +- [Channel Plugins](/uk/plugins/sdk-channel-plugins) — створення Plugin каналів +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) — створення Plugin провайдерів diff --git a/docs/uk/plugins/codex-harness.md b/docs/uk/plugins/codex-harness.md index 8ffe3f081..0ac78389d 100644 --- a/docs/uk/plugins/codex-harness.md +++ b/docs/uk/plugins/codex-harness.md @@ -1,118 +1,87 @@ --- read_when: - - Ви хочете використовувати комплектований harness app-server Codex - - Вам потрібні приклади конфігурації harness Codex - - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу до Pi -summary: Запустіть вбудовані ходи агента OpenClaw через комплектований harness app-server Codex -title: harness Codex + - Ви хочете використовувати вбудований app-server harness Codex + - Вам потрібні приклади конфігурації Codex harness + - Ви хочете, щоб розгортання лише з Codex завершувалися помилкою замість переходу на PI +summary: Запускайте вбудовані ходи агента OpenClaw через вбудований app-server harness Codex +title: Codex harness x-i18n: - generated_at: "2026-04-24T21:43:41Z" + generated_at: "2026-04-25T00:02:18Z" model: gpt-5.4 provider: openai - source_hash: 674bc34552401d1a492b348ceb86fd513a894760987a0c6fef6e79fdb0b3ebfb + source_hash: 366400f3d4018d6149e80b0b87b49ad7332c6164e8b3b70a0c4359068ee2685f source_path: plugins/codex-harness.md workflow: 15 --- -Комплектований Plugin `codex` дає OpenClaw змогу запускати вбудовані ходи агента через -app-server Codex замість вбудованого harness PI. +Вбудований Plugin `codex` дає змогу OpenClaw виконувати вбудовані ходи агента через Codex app-server замість вбудованого harness PI. -Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням -моделей, нативним відновленням потоку, нативною Compaction та виконанням app-server. -OpenClaw і далі керує каналами чату, файлами сесії, вибором моделі, інструментами, -погодженнями, доставкою медіа та видимим дзеркалом транскрипту. +Використовуйте це, коли хочете, щоб Codex керував низькорівневою сесією агента: виявленням моделей, нативним відновленням thread, нативним Compaction і виконанням app-server. +OpenClaw, як і раніше, керує каналами чату, файлами сесій, вибором моделі, tools, +approvals, доставкою медіа та видимим дзеркалом transcript. -Нативні ходи Codex зберігають хука Plugin OpenClaw як публічний шар сумісності. -Це внутрішньопроцесні хуки OpenClaw, а не командні хуки Codex `hooks.json`: +Нативні ходи Codex зберігають plugin hooks OpenClaw як публічний шар сумісності. +Це in-process hooks OpenClaw, а не command hooks Codex `hooks.json`: - `before_prompt_build` - `before_compaction`, `after_compaction` - `llm_input`, `llm_output` - `after_tool_call` -- `before_message_write` для дзеркальних записів транскрипту +- `before_message_write` для дзеркальних записів transcript - `agent_end` -Plugins також можуть реєструвати нейтральне до harness middleware результатів інструментів, щоб переписувати -динамічні результати інструментів OpenClaw після того, як OpenClaw виконає інструмент, і до того, -як результат буде повернено до Codex. Це окремо від публічного -хука Plugin `tool_result_persist`, який трансформує записи результатів -інструментів у транскрипті, що належать OpenClaw. +Plugins також можуть реєструвати runtime-neutral middleware результатів tools, щоб переписувати динамічні результати tools OpenClaw після того, як OpenClaw виконає tool, і до того, як результат буде повернуто до Codex. Це окремо від публічного plugin hook `tool_result_persist`, який перетворює записи результатів tools у transcript, що належать OpenClaw. -За замовчуванням harness вимкнено. У нових конфігураціях слід зберігати посилання на моделі OpenAI -канонічними як `openai/gpt-*` і явно примусово вказувати +Harness вимкнено за замовчуванням. Нові конфігурації повинні зберігати canonical ref-и моделей OpenAI як `openai/gpt-*` і явно примусово вказувати `embeddedHarness.runtime: "codex"` або `OPENCLAW_AGENT_RUNTIME=codex`, коли -потрібне нативне виконання app-server. Застарілі посилання на моделі `codex/*` і далі автоматично вибирають -harness для сумісності, але не показуються як звичайні варіанти моделі/провайдера. +потрібне нативне виконання через app-server. Застарілі ref-и моделей `codex/*` і далі автоматично вибирають harness для сумісності, але застарілі provider prefixes, підкріплені runtime, не показуються як звичайні варіанти model/provider. ## Виберіть правильний префікс моделі -Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли хочете -Codex OAuth через PI; використовуйте `openai/*`, коли хочете прямий доступ до OpenAI API або -коли примусово використовуєте нативний harness app-server Codex: +Маршрути сімейства OpenAI залежать від префікса. Використовуйте `openai-codex/*`, коли вам потрібна авторизація Codex OAuth через PI; використовуйте `openai/*`, коли вам потрібен прямий доступ до OpenAI API або коли ви примусово вмикаєте нативний harness Codex app-server: -| Посилання на модель | Шлях runtime | Використовуйте, коли | -| ---------------------------------------------------- | -------------------------------------------- | --------------------------------------------------------------------------- | -| `openai/gpt-5.4` | Провайдер OpenAI через обв’язку OpenClaw/PI | Вам потрібен поточний прямий доступ до API платформи OpenAI з `OPENAI_API_KEY`. | -| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна автентифікація передплати ChatGPT/Codex із runner PI за замовчуванням. | -| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | Вам потрібне нативне виконання app-server Codex для вбудованого ходу агента. | +| Ref моделі | Шлях runtime | Коли використовувати | +| ----------------------------------------------------- | ------------------------------------------- | --------------------------------------------------------------------------- | +| `openai/gpt-5.4` | provider OpenAI через plumbing OpenClaw/PI | Вам потрібен поточний прямий доступ до API OpenAI Platform через `OPENAI_API_KEY`. | +| `openai-codex/gpt-5.5` | OpenAI Codex OAuth через OpenClaw/PI | Вам потрібна авторизація підписки ChatGPT/Codex із runner-ом PI за замовчуванням. | +| `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness Codex app-server | Вам потрібне нативне виконання через Codex app-server для вбудованого ходу агента. | -GPT-5.5 у OpenClaw наразі доступна лише через передплату/OAuth. Використовуйте -`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` з harness -app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` підтримуватиметься, -щойно OpenAI увімкне GPT-5.5 у публічному API. +GPT-5.5 наразі в OpenClaw доступна лише через підписку/OAuth. Використовуйте +`openai-codex/gpt-5.5` для PI OAuth або `openai/gpt-5.5` разом із harness Codex +app-server. Прямий доступ через API key для `openai/gpt-5.5` підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API. -Застарілі посилання `codex/gpt-*` і далі приймаються як псевдоніми сумісності. Doctor -міграція сумісності переписує застарілі основні посилання `codex/*` на `openai/*` -і окремо записує політику harness Codex. Нові конфігурації PI Codex OAuth -мають використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server -мають використовувати `openai/gpt-*` плюс `embeddedHarness.runtime: "codex"`. +Застарілі ref-и `codex/gpt-*` залишаються прийнятними як compatibility aliases. Міграція сумісності Doctor переписує застарілі primary runtime ref-и на canonical ref-и моделей і окремо записує policy runtime, тоді як застарілі ref-и лише для fallback залишаються без змін, оскільки runtime налаштовується для всього контейнера агента. Нові конфігурації PI Codex OAuth повинні використовувати `openai-codex/gpt-*`; нові конфігурації нативного harness app-server повинні використовувати `openai/gpt-*` разом із +`embeddedHarness.runtime: "codex"`. -`agents.defaults.imageModel` дотримується такого самого поділу префіксів. Використовуйте -`openai-codex/gpt-*`, коли розуміння зображень має виконуватися через шлях провайдера OpenAI -Codex OAuth. Використовуйте `codex/gpt-*`, коли розуміння зображень має виконуватися -через обмежений хід app-server Codex. Модель app-server Codex має -оголошувати підтримку вхідних зображень; текстові моделі Codex завершуються з помилкою до початку -медіа-ходу. +`agents.defaults.imageModel` дотримується того самого поділу за префіксами. Використовуйте +`openai-codex/gpt-*`, коли розпізнавання зображень має виконуватися через шлях provider OpenAI Codex OAuth. Використовуйте `codex/gpt-*`, коли розпізнавання зображень має виконуватися через обмежений хід Codex app-server. Модель Codex app-server повинна заявляти підтримку вхідних зображень; текстові моделі Codex без підтримки зображень завершуються помилкою до початку media turn. -Використовуйте `/status`, щоб підтвердити ефективний harness для поточної сесії. Якщо -вибір виглядає несподіваним, увімкніть журналювання налагодження для підсистеми `agents/harness` -і перегляньте структурований запис шлюзу `agent harness selected`. Він -містить ідентифікатор вибраного harness, причину вибору, політику runtime/fallback, а також, -у режимі `auto`, результат підтримки для кожного кандидата Plugin. +Використовуйте `/status`, щоб підтвердити фактичний harness для поточної сесії. Якщо вибір здається неочікуваним, увімкніть debug logging для підсистеми `agents/harness` і перегляньте структурований запис gateway `agent harness selected`. Він містить id вибраного harness, причину вибору, policy runtime/fallback і, у режимі `auto`, результат підтримки для кожного plugin-кандидата. -Вибір harness не є елементом керування живою сесією. Коли вбудований хід виконується, -OpenClaw записує ідентифікатор вибраного harness у цій сесії та продовжує використовувати його для -наступних ходів у межах того самого ідентифікатора сесії. Змінюйте конфігурацію `embeddedHarness` або -`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; -використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної -розмови між PI та Codex. Це запобігає повторному відтворенню одного транскрипту через -дві несумісні нативні системи сесій. +Вибір harness не є елементом live-керування сесією. Коли виконується вбудований хід, OpenClaw записує id вибраного harness у цю сесію і продовжує використовувати його для наступних ходів із тим самим id сесії. Змінюйте конфігурацію `embeddedHarness` або +`OPENCLAW_AGENT_RUNTIME`, коли хочете, щоб майбутні сесії використовували інший harness; використовуйте `/new` або `/reset`, щоб почати нову сесію перед перемиканням наявної розмови між PI і Codex. Це дає змогу уникнути повторного програвання одного transcript через дві несумісні нативні системи сесій. -Застарілі сесії, створені до закріплення harness, вважаються закріпленими за PI, щойно в них -з’являється історія транскрипту. Використовуйте `/new` або `/reset`, щоб перевести таку розмову на -Codex після зміни конфігурації. +Застарілі сесії, створені до появи прив’язки harness, трактуються як прив’язані до PI, щойно вони мають історію transcript. Використовуйте `/new` або `/reset`, щоб перевести цю розмову на Codex після зміни конфігурації. -`/status` показує ефективний не-PI harness поруч із `Fast`, наприклад -`Fast · codex`. Типовий harness PI і далі відображається як `Runner: pi (embedded)` і -не додає окремий бейдж harness. +`/status` показує фактичний runtime моделі. Harness PI за замовчуванням відображається як +`Runtime: OpenClaw Pi Default`, а harness Codex app-server — як +`Runtime: OpenAI Codex`. ## Вимоги -- OpenClaw із доступним комплектованим Plugin `codex`. +- OpenClaw із доступним вбудованим Plugin `codex`. - Codex app-server `0.118.0` або новіший. -- Автентифікація Codex, доступна для процесу app-server. +- Авторизація Codex, доступна для процесу app-server. -Plugin блокує старіші або неверсіоновані handshake app-server. Це залишає -OpenClaw на поверхні протоколу, з якою його було протестовано. +Plugin блокує старі або неверсіоновані handshake app-server. Це утримує +OpenClaw на тій поверхні protocol, з якою його було протестовано. -Для live- і Docker smoke-тестів автентифікація зазвичай надходить із `OPENAI_API_KEY`, а також з -необов’язкових файлів Codex CLI, таких як `~/.codex/auth.json` і -`~/.codex/config.toml`. Використовуйте той самий матеріал автентифікації, що й ваш локальний -app-server Codex. +Для live- і Docker smoke-тестів авторизація зазвичай надходить із `OPENAI_API_KEY`, а також, за потреби, з файлів Codex CLI, таких як `~/.codex/auth.json` і +`~/.codex/config.toml`. Використовуйте ті самі матеріали авторизації, що й ваш локальний Codex app-server. ## Мінімальна конфігурація -Використовуйте `openai/gpt-5.5`, увімкніть комплектований Plugin і примусово вкажіть harness `codex`: +Використовуйте `openai/gpt-5.5`, увімкніть вбудований plugin і примусово виберіть harness `codex`: ```json5 { @@ -135,7 +104,7 @@ app-server Codex. } ``` -Якщо ваша конфігурація використовує `plugins.allow`, включіть туди також `codex`: +Якщо ваша конфігурація використовує `plugins.allow`, додайте туди також `codex`: ```json5 { @@ -150,15 +119,12 @@ app-server Codex. } ``` -Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента на -`codex/`, усе ще автоматично вмикають комплектований Plugin `codex`. У нових конфігураціях слід -надавати перевагу `openai/` плюс явному запису `embeddedHarness`, наведеному вище. +Застарілі конфігурації, які встановлюють `agents.defaults.model` або модель агента в +`codex/`, і далі автоматично вмикають вбудований plugin `codex`. Нові конфігурації повинні надавати перевагу `openai/` разом із явним записом `embeddedHarness`, наведеним вище. ## Додайте Codex без заміни інших моделей -Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі посилання `codex/*` вибирали Codex, а -PI — для всього іншого. Для нових конфігурацій надавайте перевагу явному `runtime: "codex"` для -агентів, які мають використовувати harness. +Залишайте `runtime: "auto"`, якщо хочете, щоб застарілі ref-и `codex/*` вибирали Codex, а для всього іншого використовувався PI. Для нових конфігурацій краще явно задавати `runtime: "codex"` для агентів, які мають використовувати harness. ```json5 { @@ -188,16 +154,16 @@ PI — для всього іншого. Для нових конфігурац } ``` -За такої форми: +У такій конфігурації: -- `/model gpt` або `/model openai/gpt-5.5` використовує harness app-server Codex для цієї конфігурації. -- `/model opus` використовує шлях провайдера Anthropic. -- Якщо вибрано не-Codex модель, PI залишається harness сумісності. +- `/model gpt` або `/model openai/gpt-5.5` використовує harness Codex app-server для цієї конфігурації. +- `/model opus` використовує шлях provider Anthropic. +- Якщо вибрано модель не з Codex, PI залишається harness сумісності. ## Розгортання лише з Codex -Примусово використовуйте harness Codex, коли потрібно довести, що кожен вбудований хід агента -використовує Codex. Явні runtime Plugin за замовчуванням не мають fallback до PI, тому +Примусово вмикайте harness Codex, коли потрібно довести, що кожен вбудований хід агента +використовує Codex. Явно задані plugin runtime за замовчуванням не мають fallback до PI, тому `fallback: "none"` необов’язковий, але часто корисний як документація: ```json5 @@ -214,20 +180,18 @@ PI — для всього іншого. Для нових конфігурац } ``` -Перевизначення через середовище: +Перевизначення через змінну середовища: ```bash OPENCLAW_AGENT_RUNTIME=codex openclaw gateway run ``` -Коли Codex примусово увімкнено, OpenClaw завершується з помилкою на ранньому етапі, якщо Plugin Codex вимкнено, -app-server застарий або app-server не може запуститися. Встановлюйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв -відсутній вибір harness. +Коли Codex примусово увімкнено, OpenClaw завершується помилкою на ранньому етапі, якщо plugin Codex вимкнено, app-server надто старий або app-server не може запуститися. Установлюйте +`OPENCLAW_AGENT_HARNESS_FALLBACK=pi` лише якщо ви навмисно хочете, щоб PI обробляв відсутній вибір harness. ## Codex для окремого агента -Ви можете зробити одного агента лише-Codex, тоді як агент за замовчуванням зберігатиме звичайний +Ви можете зробити один агент лише з Codex, тоді як агент за замовчуванням зберігатиме звичайний автовибір: ```json5 @@ -259,15 +223,12 @@ app-server застарий або app-server не може запуститис } ``` -Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову -сесію OpenClaw, а harness Codex створює або відновлює свій sidecar-потік app-server -за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього потоку -і дозволяє наступному ходу знову визначити harness з поточної конфігурації. +Використовуйте звичайні команди сесії для перемикання агентів і моделей. `/new` створює нову сесію OpenClaw, а harness Codex створює або відновлює свій sidecar thread app-server за потреби. `/reset` очищає прив’язку сесії OpenClaw для цього thread і дає змогу наступному ходу знову визначити harness із поточної конфігурації. ## Виявлення моделей -За замовчуванням Plugin Codex запитує app-server про доступні моделі. Якщо -виявлення не вдається або завершується за тайм-аутом, використовується комплектований резервний каталог для: +За замовчуванням plugin Codex запитує в app-server список доступних моделей. Якщо +виявлення завершується помилкою або спрацьовує timeout, використовується вбудований fallback catalog для: - GPT-5.5 - GPT-5.4 mini @@ -293,8 +254,7 @@ app-server застарий або app-server не може запуститис } ``` -Вимкніть виявлення, якщо хочете, щоб під час запуску не відбувалося зондування Codex і використовувався -резервний каталог: +Вимкніть виявлення, якщо хочете, щоб під час запуску не виконувалося опитування Codex і використовувався лише fallback catalog: ```json5 { @@ -313,9 +273,9 @@ app-server застарий або app-server не може запуститис } ``` -## Підключення до app-server і політика +## Підключення до app-server і policy -За замовчуванням Plugin запускає Codex локально так: +За замовчуванням plugin локально запускає Codex так: ```bash codex app-server --listen stdio:// @@ -323,11 +283,9 @@ codex app-server --listen stdio:// За замовчуванням OpenClaw запускає локальні сесії harness Codex у режимі YOLO: `approvalPolicy: "never"`, `approvalsReviewer: "user"` і -`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується -для автономних Heartbeat: Codex може використовувати shell- і мережеві інструменти, не -зупиняючись на нативних запитах погодження, коли нікому відповісти. +`sandbox: "danger-full-access"`. Це позиція довіреного локального оператора, яка використовується для автономних Heartbeat: Codex може використовувати shell і network tools без зупинки на нативних approval prompts, на які нікому відповідати. -Щоб увімкнути погодження Codex, перевірені guardian, установіть `appServer.mode: +Щоб увімкнути approvals Codex із перевіркою guardian, установіть `appServer.mode: "guardian"`: ```json5 @@ -348,9 +306,9 @@ codex app-server --listen stdio:// } ``` -Guardian — це нативний рецензент погоджень Codex. Коли Codex просить вийти за межі sandbox, записати поза межами workspace або додати дозволи, як-от мережевий доступ, Codex надсилає цей запит на погодження рецензенту-субагенту, а не людині через prompt. Рецензент застосовує модель ризиків Codex і погоджує або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібно більше запобіжників, ніж у режимі YOLO, але при цьому потрібно, щоб агенти без нагляду продовжували роботу. +Guardian — це нативний reviewer approvals у Codex. Коли Codex просить вийти за межі sandbox, записати поза workspace або додати дозволи, як-от доступ до мережі, Codex спрямовує цей запит на approval до subagent reviewer, а не до prompt для людини. Reviewer застосовує framework ризиків Codex і схвалює або відхиляє конкретний запит. Використовуйте Guardian, коли вам потрібні суворіші запобіжники, ніж у режимі YOLO, але водночас потрібно, щоб unattended agents могли просуватися далі. -Пресет `guardian` розгортається в `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля політики й далі мають пріоритет над `mode`, тому розширені розгортання можуть поєднувати пресет із явними налаштуваннями. +Preset `guardian` розгортається до `approvalPolicy: "on-request"`, `approvalsReviewer: "guardian_subagent"` і `sandbox: "workspace-write"`. Окремі поля policy і далі мають вищий пріоритет за `mode`, тому просунуті розгортання можуть поєднувати preset із явними налаштуваннями. Для вже запущеного app-server використовуйте транспорт WebSocket: @@ -376,23 +334,23 @@ Guardian — це нативний рецензент погоджень Codex. Підтримувані поля `appServer`: -| Поле | Типове значення | Значення | -| ------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | -| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | -| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | -| `url` | не встановлено | URL WebSocket app-server. | -| `authToken` | не встановлено | Bearer token для транспорту WebSocket. | -| `headers` | `{}` | Додаткові заголовки WebSocket. | -| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control plane app-server. | -| `mode` | `"yolo"` | Пресет для виконання в режимі YOLO або з перевіркою guardian. | -| `approvalPolicy` | `"never"` | Нативна політика погодження Codex, що надсилається під час запуску/відновлення потоку/ходу. | -| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час запуску/відновлення потоку. | -| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти prompt. | -| `serviceTier` | не встановлено | Необов’язковий service tier app-server Codex: `"fast"`, `"flex"` або `null`. Неприпустимі застарілі значення ігноруються. | +| Поле | За замовчуванням | Значення | +| ------------------- | ---------------------------------------- | --------------------------------------------------------------------------------------------------------- | +| `transport` | `"stdio"` | `"stdio"` запускає Codex; `"websocket"` підключається до `url`. | +| `command` | `"codex"` | Виконуваний файл для транспорту stdio. | +| `args` | `["app-server", "--listen", "stdio://"]` | Аргументи для транспорту stdio. | +| `url` | не задано | URL WebSocket app-server. | +| `authToken` | не задано | Bearer token для транспорту WebSocket. | +| `headers` | `{}` | Додаткові заголовки WebSocket. | +| `requestTimeoutMs` | `60000` | Тайм-аут для викликів control-plane app-server. | +| `mode` | `"yolo"` | Preset для виконання в режимі YOLO або з approvals, перевіреними guardian. | +| `approvalPolicy` | `"never"` | Нативна policy approvals Codex, що надсилається під час start/resume/turn thread. | +| `sandbox` | `"danger-full-access"` | Нативний режим sandbox Codex, що надсилається під час start/resume thread. | +| `approvalsReviewer` | `"user"` | Використовуйте `"guardian_subagent"`, щоб дозволити Codex Guardian перевіряти prompts. | +| `serviceTier` | не задано | Необов’язковий рівень сервісу Codex app-server: `"fast"`, `"flex"` або `null`. Некоректні застарілі значення ігноруються. | -Старіші змінні середовища й далі працюють як fallback для локального тестування, коли -відповідне поле конфігурації не встановлено: +Старіші змінні середовища все ще працюють як fallback для локального тестування, коли +відповідне поле конфігурації не задане: - `OPENCLAW_CODEX_APP_SERVER_BIN` - `OPENCLAW_CODEX_APP_SERVER_ARGS` @@ -400,15 +358,14 @@ Guardian — це нативний рецензент погоджень Codex. - `OPENCLAW_CODEX_APP_SERVER_APPROVAL_POLICY` - `OPENCLAW_CODEX_APP_SERVER_SANDBOX` -`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Використовуйте -`plugins.entries.codex.config.appServer.mode: "guardian"` натомість або +`OPENCLAW_CODEX_APP_SERVER_GUARDIAN=1` було вилучено. Натомість використовуйте +`plugins.entries.codex.config.appServer.mode: "guardian"` або `OPENCLAW_CODEX_APP_SERVER_MODE=guardian` для одноразового локального тестування. Конфігурації -надається перевага для відтворюваних розгортань, оскільки вона зберігає поведінку Plugin в тому -самому перевіреному файлі, що й решта налаштувань harness Codex. +слід надавати перевагу для відтворюваних розгортань, оскільки вона зберігає поведінку plugin в тому самому перевіреному файлі, що й решта налаштувань harness Codex. -## Поширені рецепти +## Типові рецепти -Локальний Codex із типовим транспортом stdio: +Локальний Codex із transport stdio за замовчуванням: ```json5 { @@ -422,7 +379,7 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Перевірка harness лише-Codex із вимкненим fallback до PI: +Валідація harness лише для Codex, з вимкненим fallback до PI: ```json5 { @@ -439,7 +396,7 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Погодження Codex із перевіркою guardian: +Approvals Codex із перевіркою guardian: ```json5 { @@ -461,7 +418,7 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Віддалений app-server з явними заголовками: +Віддалений app-server із явними заголовками: ```json5 { @@ -484,100 +441,87 @@ Guardian — це нативний рецензент погоджень Codex. } ``` -Перемикання моделей залишається під керуванням OpenClaw. Коли сесію OpenClaw прив’язано -до наявного потоку Codex, наступний хід знову надсилає до -app-server поточну вибрану модель OpenAI, провайдера, політику погодження, sandbox і -service tier. Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає -прив’язку до потоку, але просить Codex продовжити з новою вибраною моделлю. +Перемикання моделей і далі контролюється OpenClaw. Коли сесію OpenClaw приєднано +до наявного thread Codex, наступний хід знову надсилає до +app-server поточні вибрані модель OpenAI, provider, policy approvals, sandbox і service tier. +Перемикання з `openai/gpt-5.5` на `openai/gpt-5.2` зберігає прив’язку до +thread, але просить Codex продовжити з новою вибраною моделлю. ## Команда Codex -Комплектований Plugin реєструє `/codex` як авторизовану slash-команду. Вона є -загальною та працює в будь-якому каналі, який підтримує текстові команди OpenClaw. +Вбудований plugin реєструє `/codex` як авторизовану slash-команду. Вона +є загальною і працює в будь-якому каналі, який підтримує текстові команди OpenClaw. Поширені форми: -- `/codex status` показує живе підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP-сервери та skills. -- `/codex models` показує список живих моделей app-server Codex. -- `/codex threads [filter]` показує список нещодавніх потоків Codex. -- `/codex resume ` прив’язує поточну сесію OpenClaw до наявного потоку Codex. -- `/codex compact` просить app-server Codex виконати compaction для прив’язаного потоку. -- `/codex review` запускає нативну перевірку Codex для прив’язаного потоку. +- `/codex status` показує поточне підключення до app-server, моделі, обліковий запис, ліміти швидкості, MCP servers і skills. +- `/codex models` показує список поточних моделей Codex app-server. +- `/codex threads [filter]` показує список нещодавніх thread-ів Codex. +- `/codex resume ` приєднує поточну сесію OpenClaw до наявного thread Codex. +- `/codex compact` просить Codex app-server виконати Compaction для приєднаного thread. +- `/codex review` запускає нативний review Codex для приєднаного thread. - `/codex account` показує стан облікового запису та лімітів швидкості. -- `/codex mcp` показує список станів MCP-серверів app-server Codex. -- `/codex skills` показує список Skills app-server Codex. +- `/codex mcp` показує список станів MCP server у Codex app-server. +- `/codex skills` показує список skills Codex app-server. -`/codex resume` записує той самий sidecar-файл прив’язки, який harness використовує для -звичайних ходів. У наступному повідомленні OpenClaw відновлює цей потік Codex, передає -поточну вибрану модель OpenClaw до app-server і зберігає розширену історію -увімкненою. +`/codex resume` записує той самий sidecar binding file, який harness використовує для +звичайних ходів. У наступному повідомленні OpenClaw відновлює цей thread Codex, передає +поточну вибрану модель OpenClaw до app-server і залишає розширену історію увімкненою. Поверхня команд вимагає Codex app-server `0.118.0` або новішої версії. Окремі методи керування позначаються як `unsupported by this Codex app-server`, якщо -майбутній або кастомний app-server не надає цей JSON-RPC метод. +майбутній або кастомний app-server не надає цей метод JSON-RPC. -## Межі хуків +## Межі hooks -Harness Codex має три шари хуків: +Harness Codex має три шари hooks: -| Шар | Власник | Призначення | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------- | -| хуки Plugin OpenClaw | OpenClaw | Сумісність продукту/Plugin між harness PI і Codex. | -| middleware розширення app-server Codex | комплектовані Plugins OpenClaw | Поведінка адаптера навколо динамічних інструментів OpenClaw для кожного ходу. | -| нативні хуки Codex | Codex | Низькорівневий життєвий цикл Codex і нативна політика інструментів із конфігурації Codex. | +| Шар | Власник | Призначення | +| ------------------------------------ | ------------------------ | ------------------------------------------------------------------- | +| OpenClaw plugin hooks | OpenClaw | Сумісність продукту/plugin між harness PI та Codex. | +| middleware розширення Codex app-server | Вбудовані plugins OpenClaw | Поведінка адаптера для кожного ходу навколо динамічних tools OpenClaw. | +| Нативні hooks Codex | Codex | Низькорівневий життєвий цикл Codex і policy нативних tools з конфігурації Codex. | -OpenClaw не використовує файли проєктного або глобального Codex `hooks.json` для маршрутизації -поведінки Plugin OpenClaw. Нативні хуки Codex корисні для операцій, -що належать Codex, як-от політика shell, нативна перевірка результатів інструментів, обробка зупинки та -нативна Compaction/життєвий цикл моделі, але вони не є API Plugin OpenClaw. +OpenClaw не використовує project або global файли Codex `hooks.json` для маршрутизації +поведінки plugin OpenClaw. Нативні hooks Codex корисні для операцій, що належать Codex, +як-от policy shell, перевірка результатів нативних tools, обробка зупинки та нативний життєвий цикл Compaction/моделі, але вони не є API plugin OpenClaw. -Для динамічних інструментів OpenClaw, OpenClaw виконує інструмент після того, як Codex запитує -виклик, тому OpenClaw запускає поведінку Plugin і middleware, якою він володіє, у -адаптері harness. Для нативних інструментів Codex саме Codex володіє канонічним записом інструмента. -OpenClaw може віддзеркалювати окремі події, але не може переписати нативний потік Codex, -якщо тільки Codex не надає цю операцію через app-server або нативні callback-хуки. +Для динамічних tools OpenClaw сам виконує tool після того, як Codex запитує +виклик, тому OpenClaw запускає поведінку plugin і middleware, якою він володіє, у +адаптері harness. Для нативних tools Codex саме Codex володіє canonical record tool. +OpenClaw може дзеркалювати окремі події, але не може переписувати нативний thread Codex, +якщо Codex не надає цю операцію через app-server або callbacks нативних hooks. -Коли новіші збірки app-server Codex надаватимуть події хуків нативної Compaction і життєвого циклу моделі, -OpenClaw має з урахуванням версії протоколу вмикати цю підтримку та зіставляти -події з наявним контрактом хуків OpenClaw там, де семантика є коректною. +Коли новіші збірки Codex app-server почнуть надавати події hooks життєвого циклу нативних Compaction і моделі, OpenClaw має обмежувати підтримку цього protocol за версією та відображати ці події в наявний контракт hooks OpenClaw там, де семантика є чесною. До того часу події OpenClaw `before_compaction`, `after_compaction`, `llm_input` і -`llm_output` є спостереженнями на рівні адаптера, а не побайтними копіями +`llm_output` є спостереженнями на рівні адаптера, а не побайтовими копіями внутрішнього запиту Codex або payload Compaction. -Нативні сповіщення app-server Codex `hook/started` і `hook/completed` -проєктуються як події агента `codex_app_server.hook` для траєкторії та налагодження. -Вони не викликають хуки Plugin OpenClaw. +Нативні сповіщення app-server Codex `hook/started` і `hook/completed` проєктуються як +події агента `codex_app_server.hook` для траєкторії та налагодження. +Вони не викликають plugin hooks OpenClaw. -## Інструменти, медіа та Compaction +## Tools, медіа та Compaction Harness Codex змінює лише низькорівневий виконавець вбудованого агента. -OpenClaw і далі формує список інструментів і отримує результати динамічних інструментів від -harness. Текст, зображення, відео, музика, TTS, погодження та вивід інструментів повідомлень +OpenClaw, як і раніше, будує список tools і отримує динамічні результати tools від +harness. Текст, зображення, відео, музика, TTS, approvals і вивід tools для повідомлень і далі проходять звичайним шляхом доставки OpenClaw. -Запити погодження інструментів Codex MCP маршрутизуються через потік погодження Plugin -OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як -`"mcp_tool_call"`. Prompt Codex `request_user_input` надсилаються назад у -початковий чат, а наступне поставлене в чергу повідомлення-відповідь відповідає на цей нативний -запит сервера замість того, щоб спрямовуватися як додатковий контекст. Інші запити elicitation MCP -і далі завершуються за принципом fail closed. +Запити на approvals для MCP tool у Codex маршрутизуються через flow approvals plugin OpenClaw, коли Codex позначає `_meta.codex_approval_kind` як +`"mcp_tool_call"`. Prompts Codex `request_user_input` надсилаються назад до +початкового чату, а наступне повідомлення в черзі відповідає на цей нативний +запит server, а не спрямовується як додатковий контекст. Інші запити MCP elicitation і далі завершуються в закритому режимі. -Коли вибрана модель використовує harness Codex, нативна Compaction потоку делегується -app-server Codex. OpenClaw зберігає дзеркало транскрипту для історії каналу, -пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало -містить prompt користувача, фінальний текст помічника та полегшені записи міркувань або -плану Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали -початку та завершення нативної Compaction. Він ще не надає зрозумілого для людини -зведення Compaction або придатного до аудиту списку того, які записи Codex -зберіг після Compaction. +Коли вибрана модель використовує harness Codex, нативний Compaction thread делегується Codex app-server. OpenClaw зберігає дзеркало transcript для історії каналів, пошуку, `/new`, `/reset` і майбутнього перемикання моделі або harness. Дзеркало містить prompt користувача, фінальний текст асистента та полегшені записи reasoning або plan Codex, коли app-server їх надсилає. Наразі OpenClaw записує лише сигнали початку та завершення нативного Compaction. Він ще не показує зрозумілий для людини підсумок Compaction або список для аудиту, які саме записи Codex зберіг після Compaction. -Оскільки Codex володіє канонічним нативним потоком, `tool_result_persist` наразі не -переписує записи результатів нативних інструментів Codex. Він застосовується лише тоді, коли -OpenClaw записує результат інструмента в транскрипт сесії, що належить OpenClaw. +Оскільки Codex володіє canonical нативним thread, `tool_result_persist` наразі не +переписує записи результатів нативних tools Codex. Він застосовується лише тоді, коли +OpenClaw записує результат tool у transcript сесії, що належить OpenClaw. -Генерація медіа не вимагає PI. Генерація зображень, відео, музики, PDF, TTS і -розуміння медіа й далі використовують відповідні налаштування провайдера/моделі, такі як +Генерація медіа не потребує PI. Генерація зображень, відео, музики, PDF, TTS і +розпізнавання медіа й далі використовують відповідні налаштування provider/моделі, як-от `agents.defaults.imageGenerationModel`, `videoGenerationModel`, `pdfModel` і `messages.tts`. @@ -585,14 +529,14 @@ OpenClaw записує результат інструмента в транс **Codex не з’являється в `/model`:** увімкніть `plugins.entries.codex.enabled`, виберіть модель `openai/gpt-*` з `embeddedHarness.runtime: "codex"` (або -застаріле посилання `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. +застарілий ref `codex/*`) і перевірте, чи `plugins.allow` не виключає `codex`. -**OpenClaw використовує PI замість Codex:** `runtime: "auto"` усе ще може використовувати PI як -бекенд сумісності, коли жоден harness Codex не бере виконання на себе. Установіть +**OpenClaw використовує PI замість Codex:** `runtime: "auto"` все ще може використовувати PI як +backend сумісності, коли жоден harness Codex не заявляє про цей запуск. Установіть `embeddedHarness.runtime: "codex"`, щоб примусово вибрати Codex під час тестування. Тепер -примусовий runtime Codex завершується з помилкою замість fallback до PI, якщо ви -явно не встановите `embeddedHarness.fallback: "pi"`. Щойно вибрано app-server Codex, -його збої проявляються безпосередньо без додаткової конфігурації fallback. +примусовий runtime Codex завершується помилкою замість fallback до PI, якщо ви +явно не встановили `embeddedHarness.fallback: "pi"`. Щойно буде вибрано Codex app-server, +його помилки надходитимуть безпосередньо без додаткової конфігурації fallback. **app-server відхиляється:** оновіть Codex, щоб handshake app-server повідомляв версію `0.118.0` або новішу. @@ -600,16 +544,16 @@ OpenClaw записує результат інструмента в транс **Виявлення моделей повільне:** зменште `plugins.entries.codex.config.discovery.timeoutMs` або вимкніть виявлення. -**Транспорт WebSocket відразу завершується з помилкою:** перевірте `appServer.url`, `authToken`, -і що віддалений app-server використовує ту саму версію протоколу app-server Codex. +**Транспорт WebSocket відразу завершується помилкою:** перевірте `appServer.url`, `authToken` +і те, що віддалений app-server використовує ту саму версію protocol Codex app-server. -**Не-Codex модель використовує PI:** це очікувано, якщо ви не примусово встановили -`embeddedHarness.runtime: "codex"` (або не вибрали застаріле посилання `codex/*`). Звичайні -`openai/gpt-*` та інші посилання провайдерів залишаються на своєму звичайному шляху провайдера. +**Модель не з Codex використовує PI:** це очікувано, якщо ви не примусово задали +`embeddedHarness.runtime: "codex"` (або не вибрали застарілий ref `codex/*`). Звичайні +`openai/gpt-*` та ref-и інших provider залишаються на своєму звичайному шляху provider. ## Пов’язане - [Plugins Harness агента](/uk/plugins/sdk-agent-harness) -- [Провайдери моделей](/uk/concepts/model-providers) +- [Providers моделей](/uk/concepts/model-providers) - [Довідник із конфігурації](/uk/gateway/configuration-reference) - [Тестування](/uk/help/testing-live#live-codex-app-server-harness-smoke) diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index af3dca3ea..1652ed63c 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,53 +1,53 @@ --- read_when: - - Ви створюєте Plugin для OpenClaw - - Вам потрібно надати schema конфігурації Plugin або налагодити помилки валідації Plugin -summary: Вимоги до маніфесту Plugin та JSON schema (сувора валідація конфігурації) -title: маніфест Plugin + - Ви створюєте plugin для OpenClaw + - Вам потрібно постачити схему конфігурації plugin або налагодити помилки валідації plugin +summary: Маніфест Plugin + вимоги до схеми JSON (сувора валідація конфігурації) +title: Маніфест Plugin x-i18n: - generated_at: "2026-04-24T22:21:56Z" + generated_at: "2026-04-25T00:02:28Z" model: gpt-5.4 provider: openai - source_hash: ddabd562db22a82ff9c46094248350ac30565c9c10c9d87d3c0e85d49e7044a9 + source_hash: 750878abda22dbc270483b2c6a32ba0918bce0beaf66f1d209bb226289ffd42a source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка призначена лише для **власного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **рідного маніфесту plugin OpenClaw**. -Сумісні компонування bundle дивіться в [Plugin bundles](/uk/plugins/bundles). +Сумісні макети пакетів див. у [Пакети plugin](/uk/plugins/bundles). -Сумісні формати bundle використовують інші файли маніфесту: +Сумісні формати пакетів використовують інші файли маніфесту: -- Codex bundle: `.codex-plugin/plugin.json` -- Claude bundle: `.claude-plugin/plugin.json` або стандартне компонування компонентів Claude без маніфесту -- Cursor bundle: `.cursor-plugin/plugin.json` +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або типовий макет компонента Claude без маніфесту +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично визначає ці компонування bundle, але вони не проходять валідацію за schema `openclaw.plugin.json`, описаною тут. +OpenClaw також автоматично визначає ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних bundle OpenClaw наразі зчитує метадані bundle, а також оголошені корені skills, корені команд Claude, типові значення `settings.json` для Claude bundle, типові значення LSP для Claude bundle і підтримувані набори hook, коли компонування відповідає очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw наразі читає метадані пакета плюс оголошені корені skill, корені команд Claude, типові значення `settings.json` пакета Claude, типові значення LSP пакета Claude і підтримувані набори hook, коли макет відповідає очікуванням runtime OpenClaw. -Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду Plugin**. Відсутні або некоректні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. +Кожен рідний plugin OpenClaw **повинен** постачатися з файлом `openclaw.plugin.json` у **корені plugin**. OpenClaw використовує цей маніфест для валідації конфігурації **без виконання коду plugin**. Відсутні або недійсні маніфести вважаються помилками plugin і блокують валідацію конфігурації. -Дивіться повний посібник по системі Plugin: [Plugins](/uk/tools/plugin). -Щодо власної моделі capability та поточних рекомендацій із зовнішньої сумісності: -[Модель capability](/uk/plugins/architecture#public-capability-model). +Повний посібник із системи plugin див. у [Plugins](/uk/tools/plugin). +Для рідної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: +[Модель можливостей](/uk/plugins/architecture#public-capability-model). ## Що робить цей файл -`openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску runtime Plugin. +`openclaw.plugin.json` — це метадані, які OpenClaw читає **до завантаження коду вашого plugin**. Усе нижче має бути достатньо дешевим для перевірки без запуску runtime plugin. **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації -- метаданих auth, onboarding і setup (alias, auto-enable, змінні середовища provider, варіанти auth) +- ідентичності plugin, валідації конфігурації та підказок для UI конфігурації +- метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) - підказок активації для поверхонь control plane -- скороченого володіння model-family -- статичних знімків володіння capability (`contracts`) +- скороченого володіння сімействами моделей +- статичних знімків володіння можливостями (`contracts`) - метаданих QA runner, які може перевіряти спільний хост `openclaw qa` -- метаданих конфігурації для конкретних channel, що об’єднуються в поверхні каталогу та валідації +- метаданих конфігурації, специфічних для каналу, об’єднаних у каталог і поверхні валідації -**Не використовуйте його для:** реєстрації поведінки runtime, оголошення code entrypoint або метаданих встановлення npm. Це належить до коду вашого Plugin і `package.json`. +**Не використовуйте його для:** реєстрації поведінки runtime, оголошення точок входу коду або метаданих встановлення npm. Це належить вашому коду plugin і `package.json`. ## Мінімальний приклад @@ -62,7 +62,7 @@ OpenClaw також автоматично визначає ці компону } ``` -## Розширений приклад +## Розгорнутий приклад ```json { @@ -127,67 +127,67 @@ OpenClaw також автоматично визначає ці компону ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний id Plugin. Це id, що використовується в `plugins.entries.`. | -| `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Пропустіть його або встановіть будь-яке значення, відмінне від `true`, щоб Plugin залишався типово вимкненим. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id provider, які повинні автоматично вмикати цей Plugin, коли auth, config або посилання на моделі згадують їх. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, що використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | id channel, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | id provider, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагого модуля виявлення provider, відносно кореня Plugin, для метаданих каталогу provider в межах маніфесту, які можна завантажити без активації повного runtime Plugin. | -| `modelSupport` | Ні | `object` | Короткі метадані model-family, що належать маніфесту і використовуються для автозавантаження Plugin до запуску runtime. | -| `providerEndpoints` | Ні | `object[]` | Метадані host/baseUrl endpoint, що належать маніфесту, для маршрутів provider, які core має класифікувати до завантаження runtime provider. | -| `cliBackends` | Ні | `string[]` | id backend CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску з явних посилань у config. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на provider або backend CLI, для яких слід перевіряти синтетичний hook auth, що належить Plugin, під час cold discovery моделей до завантаження runtime. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, що належать вбудованому Plugin і представляють несекретний локальний стан, OAuth або ambient credential state. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які повинні формувати діагностику config та CLI з урахуванням Plugin до завантаження runtime. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку auth/status provider. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом періоду deprecation. | -| `providerAuthAliases` | Ні | `Record` | id provider, які повинні повторно використовувати інший id provider для пошуку auth, наприклад provider для кодування, що використовує той самий API key базового provider і профілі auth. | -| `channelEnvVars` | Ні | `Record` | Легковагі метадані env для channel, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для setup channel на основі env або поверхонь auth, які мають бачити загальні helper запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Легковагі метадані варіантів auth для селекторів onboarding, визначення preferred provider і простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Легковагі метадані планувальника активації для завантаження за тригерами provider, command, channel, route і capability. Лише метадані; фактичною поведінкою все ще володіє runtime Plugin. | -| `setup` | Ні | `object` | Легковагі дескриптори setup/onboarding, які поверхні discovery та setup можуть перевіряти без завантаження runtime Plugin. | -| `qaRunners` | Ні | `object[]` | Легковагі дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження runtime Plugin. | -| `contracts` | Ні | `object` | Статичний знімок bundled capability для зовнішніх hook auth, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння tool. | -| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагі типові значення media-understanding для id provider, оголошених у `contracts.mediaUnderstandingProviders`. | -| `channelConfigs` | Ні | `Record` | Метадані конфігурації channel, що належать маніфесту і об’єднуються в поверхні discovery та валідації до завантаження runtime. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносно кореня Plugin. | -| `name` | Ні | `string` | Зрозуміла людині назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | -| `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | UI-мітки, placeholders і підказки щодо чутливості для полів конфігурації. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------------------------ | ----------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `id` | Так | `string` | Канонічний ідентифікатор plugin. Це ідентифікатор, що використовується в `plugins.entries.`. | +| `configSchema` | Так | `object` | Вбудована схема JSON для конфігурації цього plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований plugin як увімкнений типово. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб plugin типово залишався вимкненим. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує виключний тип plugin, що використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера відносно кореня plugin для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного runtime plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автозавантаження plugin до runtime. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/`baseUrl` кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження runtime провайдера. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів виведення CLI, якими володіє цей plugin. Використовується для автоактивації під час запуску з явних посилань конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдера або бекенд CLI, для яких синтетичний hook автентифікації, яким володіє plugin, слід перевіряти під час холодного виявлення моделі до завантаження runtime. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення API-ключів-заповнювачів, якими володіє вбудований plugin і які позначають несекретний локальний стан, OAuth або стан ambient credential. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей plugin і які мають створювати діагностику конфігурації та CLI з урахуванням plugin до завантаження runtime. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані змінних середовища для пошуку автентифікації/стану провайдера. Для нових plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще читає це протягом періоду знецінення. | +| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку автентифікації, наприклад coding provider, що ділить API-ключ і профілі автентифікації базового провайдера. | +| `channelEnvVars` | Ні | `Record` | Полегшені метадані змінних середовища каналу, які OpenClaw може перевіряти без завантаження коду plugin. Використовуйте це для налаштування каналу через env або поверхонь автентифікації, які мають бачити загальні helper. | +| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів автентифікації для селекторів онбордингу, визначення бажаного провайдера та простого підключення прапорців CLI. | +| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактичною поведінкою все ще керує runtime plugin. | +| `setup` | Ні | `object` | Полегшені дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження runtime plugin. | +| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовуються спільним хостом `openclaw qa` до завантаження runtime plugin. | +| `contracts` | Ні | `object` | Статичний знімок можливостей вбудованого пакета для зовнішніх hook автентифікації, speech, realtime transcription, realtime voice, media-understanding, image-generation, music-generation, video-generation, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Полегшені типові значення media-understanding для ідентифікаторів провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналу, якими володіє маніфест, що об’єднуються в поверхні виявлення та валідації до завантаження runtime. | +| `skills` | Ні | `string[]` | Каталоги Skills для завантаження відносно кореня plugin. | +| `name` | Ні | `string` | Людинозрозуміла назва plugin. | +| `description` | Ні | `string` | Короткий опис, що показується в поверхнях plugin. | +| `version` | Ні | `string` | Інформаційна версія plugin. | +| `uiHints` | Ні | `Record` | Мітки UI, заповнювачі та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант onboarding або auth. -OpenClaw зчитує це до завантаження runtime provider. -Потік setup provider надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard runtime і варіантів install-catalog. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. +OpenClaw читає це до завантаження runtime провайдера. +Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності повертається до метаданих wizard runtime і варіантів каталогу встановлення. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | id provider, до якого належить цей варіант. | -| `method` | Так | `string` | id методу auth, до якого слід спрямувати. | -| `choiceId` | Так | `string` | Стабільний id варіанта auth, який використовується потоками onboarding і CLI. | -| `choiceLabel` | Ні | `string` | Видима для користувача мітка. Якщо пропущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі id варіантів, які повинні перенаправляти користувачів до цього варіанта-замінника. | -| `groupId` | Ні | `string` | Необов’язковий id групи для групування пов’язаних варіантів. | -| `groupLabel` | Ні | `string` | Видима для користувача мітка цієї групи. | -| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | -| `optionKey` | Ні | `string` | Внутрішній ключ параметра для простих потоків auth з одним прапорцем. | -| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | -| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | -| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | -| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | У яких поверхнях onboarding має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що це означає | +| --------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | Ідентифікатор методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта автентифікації, який використовується в онбордингу та CLI. | +| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо не вказано, OpenClaw використовує `choiceId`. | +| `choiceHint` | Ні | `string` | Короткий допоміжний текст для селектора. | +| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних селекторах, керованих асистентом. | +| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із селекторів асистента, але все ще дозволяє ручний вибір через CLI. | +| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей замінний варіант. | +| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | +| `groupLabel` | Ні | `string` | Мітка цієї групи для користувача. | +| `groupHint` | Ні | `string` | Короткий допоміжний текст для групи. | +| `optionKey` | Ні | `string` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `cliFlag` | Ні | `string` | Назва прапорця CLI, наприклад `--openrouter-api-key`. | +| `cliOption` | Ні | `string` | Повна форма параметра CLI, наприклад `--openrouter-api-key `. | +| `cliDescription` | Ні | `string` | Опис, що використовується в довідці CLI. | +| `onboardingScopes` | Ні | `Array<"text-inference" \| "image-generation">` | На яких поверхнях онбордингу має з’являтися цей варіант. Якщо не вказано, типово використовується `["text-inference"]`. | ## Довідник `commandAliases` -Використовуйте `commandAliases`, коли Plugin володіє назвою runtime-команди, яку користувачі можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime Plugin. +Використовуйте `commandAliases`, коли plugin володіє назвою runtime-команди, яку користувачі можуть помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду runtime plugin. ```json { @@ -201,22 +201,22 @@ OpenClaw зчитує це до завантаження runtime provider. } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Так | `string` | Назва команди, що належить цьому Plugin. | -| `kind` | Ні | `"runtime-slash"` | Позначає alias як slash-команду чату, а не кореневу команду CLI. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------ | ----------- | ----------------- | ----------------------------------------------------------------------------- | +| `name` | Так | `string` | Назва команди, що належить цьому plugin. | +| `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | | `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід підказати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може з мінімальними витратами оголосити, які події control plane мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли plugin може дешево оголосити, які події control plane мають включати його в план активації/завантаження. -Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не гарантує, що код Plugin уже був виконаний. Планувальник активації використовує ці поля, щоб звузити коло кандидатів Plugin, перш ніж повертатися до наявних метаданих володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hook. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє поведінку runtime, не замінює `register(...)` і не гарантує, що код plugin уже було виконано. Планувальник активації використовує ці поля, щоб звузити коло кандидатів plugin, перш ніж повертатися до наявних метаданих володіння маніфестом, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, `contracts.tools` і hook. -Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають цей зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які неможливо подати через ці поля володіння. +Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальника, які не можна подати через ці поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` чи інші runtime/entrypoint Plugin. -Поточні споживачі використовують його як підказку для звуження кола перед ширшим завантаженням Plugin, тому відсутність метаданих активації зазвичай впливає лише на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі fallback-механізми володіння з маніфесту. +Цей блок є лише метаданими. Він не реєструє поведінку runtime і не замінює `register(...)`, `setupEntry` або інші точки входу runtime/plugin. +Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням plugin, тож відсутність метаданих активації зазвичай лише впливає на продуктивність; це не повинно змінювати коректність, доки все ще існують застарілі резервні варіанти володіння маніфестом. ```json { @@ -230,29 +230,29 @@ OpenClaw зчитує це до завантаження runtime provider. } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | id provider, які повинні включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | id команд, які повинні включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | id channel, які повинні включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи route, які повинні включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки capability, що використовуються плануванням активації control plane. Коли можливо, надавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що це означає | +| ---------------- | ----------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей plugin у плани активації/завантаження. | +| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей plugin у плани активації/завантаження. | +| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей plugin у плани активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей plugin у плани активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Широкі підказки щодо можливостей, які використовуються під час планування активації control plane. За можливості надавайте перевагу вужчим полям. | -Поточні live-споживачі: +Поточні живі споживачі: -- планування CLI, запущене командою, повертається до застарілих +- CLI-планування, запущене командою, повертається до застарілих `commandAliases[].cliCommand` або `commandAliases[].name` -- setup/channel planning, запущене channel, повертається до застарілого - володіння `channels[]`, коли явні метадані активації channel відсутні -- setup/runtime planning, запущене provider, повертається до застарілого - володіння `providers[]` і `cliBackends[]` верхнього рівня, коли явні - метадані активації provider відсутні +- setup/channel-планування, запущене каналом, повертається до застарілого + володіння `channels[]`, якщо явні метадані активації каналу відсутні +- setup/runtime-планування, запущене провайдером, повертається до застарілого + володіння `providers[]` і `cliBackends[]` верхнього рівня, якщо явні метадані + активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback за володінням у маніфесті. Наприклад, `activation-command-hint` означає, що спрацював збіг `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста і тестів; авторам Plugin слід і надалі оголошувати метадані, які найкраще описують володіння. +Діагностика планувальника може розрізняти явні підказки активації та резервне використання володіння маніфестом. Наприклад, `activation-command-hint` означає, що збіглося `activation.onCommands`, тоді як `manifest-command-alias` означає, що планувальник використав володіння `commandAliases`. Ці мітки причин призначені для діагностики хоста й тестів; авторам plugin слід і надалі оголошувати ті метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runner у спільному корені `openclaw qa`. Зберігайте ці метадані легковагими та статичними; фактичною реєстрацією CLI все ще володіє runtime Plugin через легковагу поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли plugin додає один або більше transport runner у межах спільного кореня `openclaw qa`. Зберігайте ці метадані дешевими та статичними; фактичною реєстрацією CLI все ще керує runtime plugin через полегшену поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -265,14 +265,14 @@ OpenClaw зчитує це до завантаження runtime provider. } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | -------- | ------------------------------------------------------------------- | -| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | -| `description` | Ні | `string` | Резервний текст довідки, що використовується, коли спільному хосту потрібна stub-команда. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | -------- | ------------------------------------------------------------------------------ | +| `commandName` | Так | `string` | Підкоманда, змонтована під `openclaw qa`, наприклад `matrix`. | +| `description` | Ні | `string` | Резервний текст довідки, який використовується, коли спільному хосту потрібна команда-заглушка. | ## Довідник `setup` -Використовуйте `setup`, коли поверхням setup і onboarding потрібні легковагі метадані Plugin до завантаження runtime. +Використовуйте `setup`, коли поверхням налаштування та онбордингу потрібні дешеві метадані, якими володіє plugin, до завантаження runtime. ```json { @@ -291,38 +291,42 @@ OpenClaw зчитує це до завантаження runtime provider. } ``` -`cliBackends` верхнього рівня залишається чинним і далі описує backend CLI inference. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які повинні залишатися лише метаданими. +`cliBackends` верхнього рівня залишається чинним і надалі описує бекенди виведення CLI. `setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для потоків control-plane/setup, які мають залишатися лише метаданими. -За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку setup у стилі descriptor-first для discovery setup. Якщо дескриптор лише звужує коло кандидатів Plugin, а setup усе ще потребує багатших runtime-hook на етапі setup, встановіть `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. +За наявності `setup.providers` і `setup.cliBackends` є бажаною поверхнею пошуку setup за принципом “спочатку дескриптор” для виявлення setup. Якщо дескриптор лише звужує plugin-кандидат, а setup все ще потребує багатших hook runtime під час налаштування, встановіть `requiresRuntime: true` і збережіть `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у загальні пошуки auth provider і env var. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду deprecation, але невбудовані Plugin, які все ще його використовують, отримують діагностику маніфесту. Нові Plugin повинні розміщувати метадані env для setup/status у `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` у загальні пошуки автентифікації провайдера та змінних середовища. +`providerAuthEnvVars` залишається підтримуваним через адаптер сумісності протягом періоду знецінення, але plugin не з пакета, які все ще його використовують, отримують діагностику маніфесту. Нові plugin мають розміщувати метадані env для setup/status у `setup.providers[].envVars`. -Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо Plugin, що працює лише на дескрипторах, усе ж містить один із цих runtime-entry setup, OpenClaw повідомляє про додаткову діагностику і продовжує його ігнорувати. Пропущене `requiresRuntime` зберігає застарілу fallback-поведінку, щоб не ламати наявні Plugin, які додали дескриптори без цього прапорця. +OpenClaw також може виводити прості варіанти setup із `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` означає, що runtime setup не потрібен. +Явні записи `providerAuthChoices` усе ще мають пріоритет для власних міток, прапорців CLI, області онбордингу та метаданих асистента. -Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених Plugin. Неоднозначне володіння закривається з відмовою, замість того щоб обирати переможця за порядком discovery. +Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для поверхні setup. OpenClaw трактує явне `false` як контракт лише з дескрипторами й не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо plugin, що працює лише через дескриптори, усе ж постачає одну з цих точок входу runtime setup, OpenClaw повідомляє додаткову діагностику і продовжує її ігнорувати. Пропущене `requiresRuntime` зберігає застарілу поведінку резервного варіанта, щоб наявні plugin, які додали дескриптори без цього прапорця, не ламалися. -Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про розходження descriptor, якщо `setup-api` реєструє provider або backend CLI, який не оголошено в дескрипторах маніфесту, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими й не призводять до відхилення застарілих Plugin. +Оскільки пошук setup може виконувати код `setup-api`, яким володіє plugin, нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними серед виявлених plugin. Неоднозначне володіння завершується в закритому режимі замість вибору переможця за порядком виявлення. + +Коли runtime setup таки виконується, діагностика реєстру setup повідомляє про розходження дескрипторів, якщо `setup-api` реєструє провайдера або бекенд CLI, який не оголошено дескрипторами маніфесту, або якщо дескриптор не має відповідної реєстрації runtime. Ці діагностики є додатковими й не відхиляють застарілі plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | -------------------------------------------------------------------------------------- | -| `id` | Так | `string` | id provider, доступний під час setup або onboarding. Зберігайте нормалізовані id глобально унікальними. | -| `authMethods` | Ні | `string[]` | id методів setup/auth, які цей provider підтримує без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Env var, які загальні поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------ | +| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або онбордингу. Нормалізовані ідентифікатори мають залишатися глобально унікальними. | +| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Змінні середовища, які загальні поверхні setup/status можуть перевіряти до завантаження runtime plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup provider, доступні під час setup та onboarding. | -| `cliBackends` | Ні | `string[]` | id backend, що використовуються під час setup для пошуку setup у стилі descriptor-first. Зберігайте нормалізовані id глобально унікальними. | -| `configMigrations` | Ні | `string[]` | id міграцій config, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що це означає | +| ------------------ | ----------- | ---------- | -------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдера, що відкриваються під час setup і онбордингу. | +| `cliBackends` | Ні | `string[]` | Ідентифікатори бекендів часу setup, що використовуються для пошуку setup за принципом “спочатку дескриптор”. Нормалізовані ідентифікатори мають залишатися глобально унікальними. | +| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи setup усе ще потребує виконання `setup-api` після пошуку за дескриптором. | ## Довідник `uiHints` -`uiHints` — це мапа від назв полів config до невеликих підказок для рендерингу. +`uiHints` — це відображення імен полів конфігурації на невеликі підказки рендерингу. ```json { @@ -337,25 +341,25 @@ OpenClaw також включає `setup.providers[].envVars` у загальн } ``` -Кожна підказка для поля може містити: +Кожна підказка поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | ---------------------------------------- | -| `label` | `string` | Видима для користувача мітка поля. | -| `help` | `string` | Короткий допоміжний текст. | -| `tags` | `string[]` | Необов’язкові UI-теги. | -| `advanced` | `boolean` | Позначає поле як розширене. | -| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | -| `placeholder` | `string` | Текст placeholder для полів форми. | +| Поле | Тип | Що це означає | +| ------------- | ---------- | --------------------------------------- | +| `label` | `string` | Мітка поля для користувача. | +| `help` | `string` | Короткий допоміжний текст. | +| `tags` | `string[]` | Необов’язкові теги UI. | +| `advanced` | `boolean` | Позначає поле як розширене. | +| `sensitive` | `boolean` | Позначає поле як секретне або чутливе. | +| `placeholder` | `string` | Текст-заповнювач для полів форми. | ## Довідник `contracts` -Використовуйте `contracts` лише для статичних метаданих володіння capability, які OpenClaw може зчитати без імпорту runtime Plugin. +Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може читати без імпорту runtime plugin. ```json { "contracts": { - "agentToolResultMiddleware": ["pi", "codex-app-server"], + "agentToolResultMiddleware": ["pi", "codex"], "externalAuthProviders": ["acme-ai"], "speechProviders": ["openai"], "realtimeTranscriptionProviders": ["openai"], @@ -371,33 +375,34 @@ OpenClaw також включає `setup.providers[].envVars` у загальн } ``` -Кожен список є необов’язковим: +Кожен список необов’язковий: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ----------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Застарілі id embedded extension factory. | -| `agentToolResultMiddleware` | `string[]` | id harness, для яких bundled Plugin може реєструвати middleware результатів tool. | -| `externalAuthProviders` | `string[]` | id provider, hook зовнішніх профілів auth яких належить цьому Plugin. | -| `speechProviders` | `string[]` | id provider speech, якими володіє цей Plugin. | -| `realtimeTranscriptionProviders` | `string[]` | id provider realtime-transcription, якими володіє цей Plugin. | -| `realtimeVoiceProviders` | `string[]` | id provider realtime-voice, якими володіє цей Plugin. | -| `memoryEmbeddingProviders` | `string[]` | id provider memory embedding, якими володіє цей Plugin. | -| `mediaUnderstandingProviders` | `string[]` | id provider media-understanding, якими володіє цей Plugin. | -| `imageGenerationProviders` | `string[]` | id provider image-generation, якими володіє цей Plugin. | -| `videoGenerationProviders` | `string[]` | id provider video-generation, якими володіє цей Plugin. | -| `webFetchProviders` | `string[]` | id provider web-fetch, якими володіє цей Plugin. | -| `webSearchProviders` | `string[]` | id provider web search, якими володіє цей Plugin. | -| `tools` | `string[]` | Назви agent tool, якими володіє цей Plugin для bundled-перевірок contract. | +| Поле | Тип | Що це означає | +| -------------------------------- | ---------- | ---------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | Застарілі ідентифікатори фабрик вбудованих extension. | +| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, hook зовнішнього профілю автентифікації яких належить цьому plugin. | +| `speechProviders` | `string[]` | Ідентифікатори speech-провайдерів, якими володіє цей plugin. | +| `realtimeTranscriptionProviders` | `string[]` | Ідентифікатори провайдерів realtime-transcription, якими володіє цей plugin. | +| `realtimeVoiceProviders` | `string[]` | Ідентифікатори провайдерів realtime-voice, якими володіє цей plugin. | +| `memoryEmbeddingProviders` | `string[]` | Ідентифікатори провайдерів memory embedding, якими володіє цей plugin. | +| `mediaUnderstandingProviders` | `string[]` | Ідентифікатори провайдерів media-understanding, якими володіє цей plugin. | +| `imageGenerationProviders` | `string[]` | Ідентифікатори провайдерів image-generation, якими володіє цей plugin. | +| `videoGenerationProviders` | `string[]` | Ідентифікатори провайдерів video-generation, якими володіє цей plugin. | +| `webFetchProviders` | `string[]` | Ідентифікатори провайдерів web-fetch, якими володіє цей plugin. | +| `webSearchProviders` | `string[]` | Ідентифікатори провайдерів web search, якими володіє цей plugin. | +| `tools` | `string[]` | Назви агентських інструментів, якими володіє цей plugin, для перевірок контрактів у пакеті. | -`contracts.embeddedExtensionFactories` збережено для bundled-коду сумісності, якому все ще потрібні прямі події embedded-runner Pi. Нові bundled-перетворення результатів tool повинні оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть реєструвати middleware результатів tool, оскільки ця поверхня може переписувати high-trust-вивід tool до того, як модель його побачить. +`contracts.embeddedExtensionFactories` збережено для коду сумісності пакетів, якому все ще потрібні прямі події вбудованого runner Pi. Нові перетворення результатів інструментів у пакеті мають оголошувати `contracts.agentToolResultMiddleware` і натомість реєструватися через `api.registerAgentToolResultMiddleware(...)`. +Зовнішні plugin не можуть реєструвати middleware результатів інструментів, оскільки цей шов може переписувати високодовірений вивід інструментів до того, як його побачить модель. -Plugin provider, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий fallback сумісності, але цей fallback повільніший і буде видалений після вікна міграції. +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють через застарілий резервний механізм сумісності, але цей механізм повільніший і буде видалений після завершення вікна міграції. -Bundled provider memory embedding повинні оголошувати `contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей contract маніфесту, щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway зареєструє provider. +Вбудовані провайдери memory embedding мають оголошувати `contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з вбудованими адаптерами, такими як `local`. Автономні шляхи CLI використовують цей контракт маніфесту, щоб завантажувати лише plugin-власник до того, як повний runtime Gateway зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли provider media-understanding має типові моделі, пріоритет fallback auto-auth або нативну підтримку документів, які потрібні загальним helper core до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має типові моделі, пріоритет резервного автовибору за автентифікацією або нативну підтримку документів, яка потрібна загальним helper ядра до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json { @@ -420,18 +425,18 @@ Bundled provider memory embedding повинні оголошувати `contrac } ``` -Кожен запис provider може містити: +Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості media, які надає цей provider. | -| `defaultModels` | `Record` | Типові значення model для capability, які використовуються, коли config не задає model. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback provider на основі credential. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні дані документів, які підтримує provider. | +| Поле | Тип | Що це означає | +| ---------------------- | ----------------------------------- | --------------------------------------------------------------------------- | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. | +| `defaultModels` | `Record` | Типові значення відповідності можливість-модель, що використовуються, коли конфігурація не вказує модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Нативні вхідні документи, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin channel потребує легковагих метаданих config до завантаження runtime. Discovery setup/status channel лише для читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх channel, коли запис setup недоступний або коли `setup.requiresRuntime: false` оголошує runtime setup непотрібним. +Використовуйте `channelConfigs`, коли plugin каналу потребує дешевих метаданих конфігурації до завантаження runtime. Виявлення setup/status каналу лише для читання може напряму використовувати ці метадані для налаштованих зовнішніх каналів, коли запис setup недоступний або коли `setup.requiresRuntime: false` означає, що runtime setup не потрібен. ```json { @@ -458,19 +463,19 @@ Bundled provider memory embedding повинні оголошувати `contrac } ``` -Кожен запис channel може містити: +Кожен запис каналу може містити: -| Поле | Тип | Що воно означає | -| ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису config channel. | -| `uiHints` | `Record` | Необов’язкові UI-мітки/placeholders/підказки чутливості для цього розділу config channel. | -| `label` | `string` | Мітка channel, що об’єднується в поверхнях вибору та inspect, коли метадані runtime ще не готові. | -| `description` | `string` | Короткий опис channel для поверхонь inspect і catalog. | -| `preferOver` | `string[]` | id застарілих або менш пріоритетних Plugin, які цей channel має перевершувати в поверхнях вибору. | +| Поле | Тип | Що це означає | +| ------------- | ------------------------ | --------------------------------------------------------------------------------------------- | +| `schema` | `object` | Схема JSON для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові мітки UI/заповнювачі/підказки чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та перевірки, коли метадані runtime ще не готові. | +| `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | +| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних plugin, які цей канал має випереджати на поверхнях вибору. | ## Довідник `modelSupport` -Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin provider із скорочених id model, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime Plugin. +Використовуйте `modelSupport`, коли OpenClaw має виводити ваш plugin провайдера зі скорочених ідентифікаторів моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime plugin. ```json { @@ -483,70 +488,71 @@ Bundled provider memory embedding повинні оголошувати `contrac OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` Plugin-власника -- `modelPatterns` мають вищий пріоритет за `modelPrefixes` -- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігноруються, доки користувач або config не вкаже provider +- явні посилання `provider/model` використовують метадані маніфесту `providers`, яким належить модель +- `modelPatterns` мають пріоритет над `modelPrefixes` +- якщо збігаються один plugin не з пакета і один plugin з пакета, перемагає plugin не з пакета +- інша неоднозначність ігнорується, доки користувач або конфігурація не вкаже провайдера Поля: -| Поле | Тип | Що воно означає | +| Поле | Тип | Що це означає | | --------------- | ---------- | -------------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id model. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id model після видалення суфікса profile. | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса профілю. | -Застарілі ключі capability верхнього рівня не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не розглядає ці поля верхнього рівня як володіння capability. +Застарілі ключі можливостей верхнього рівня знецінені. Використовуйте `openclaw doctor --fix`, щоб перемістити `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне завантаження маніфесту більше не трактує ці поля верхнього рівня як володіння можливостями. -## Маніфест проти package.json +## Маніфест проти `package.json` -Ці два файли виконують різні завдання: +Ці два файли виконують різні ролі: -| Файл | Використовуйте його для | +| Файл | Використовуйте для | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Discovery, валідації config, метаданих варіантів auth і підказок UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, який використовується для entrypoint, обмежень встановлення, setup або метаданих catalog | +| `openclaw.plugin.json` | Виявлення, валідація конфігурації, метадані варіантів автентифікації та підказки UI, які мають існувати до запуску коду plugin | +| `package.json` | Метадані npm, встановлення залежностей і блок `openclaw`, що використовується для точок входу, обмеження встановлення, setup або метаданих каталогу | -Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: +Якщо ви не впевнені, куди має належати певний фрагмент метаданих, користуйтеся таким правилом: -- якщо OpenClaw має знати це до завантаження коду Plugin, розміщуйте це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів entrypoint або поведінки встановлення npm, розміщуйте це в `package.json` +- якщо OpenClaw має знати це до завантаження коду plugin, розміщуйте це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розміщуйте це в `package.json` -### Поля `package.json`, що впливають на discovery +### Поля `package.json`, які впливають на виявлення -Деякі метадані Plugin до запуску runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані plugin до runtime навмисно розміщуються в `package.json` у блоці `openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `openclaw.extensions` | Оголошує entrypoint власного Plugin. Має залишатися в каталозі пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує entrypoint runtime built JavaScript для встановлених пакетів. Має залишатися в каталозі пакета Plugin. | -| `openclaw.setupEntry` | Легковагий entrypoint лише для setup, який використовується під час onboarding, відкладеного запуску channel і discovery статусу channel/SecretRef лише для читання. Має залишатися в каталозі пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint setup для встановлених пакетів. Має залишатися в каталозі пакета Plugin. | -| `openclaw.channel` | Легковагі метадані каталогу channel, такі як мітки, шляхи до документації, alias і текст для вибору. | -| `openclaw.channel.configuredState` | Легковагі метадані перевірки configured-state, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного runtime channel. | -| `openclaw.channel.persistedAuthState` | Легковагі метадані перевірки persisted-auth, які можуть відповісти на питання «чи вже є якийсь виконаний вхід?» без завантаження повного runtime channel. | -| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки встановлення/оновлення для bundled і зовнішньо опублікованих Plugin. | +| Поле | Що це означає | +| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `openclaw.extensions` | Оголошує рідні точки входу plugin. Має залишатися в каталозі пакета plugin. | +| `openclaw.runtimeExtensions` | Оголошує зібрані точки входу runtime JavaScript для встановлених пакетів. Має залишатися в каталозі пакета plugin. | +| `openclaw.setupEntry` | Полегшена точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та виявлення статусу каналу/SecretRef лише для читання. Має залишатися в каталозі пакета plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує зібрану точку входу setup JavaScript для встановлених пакетів. Має залишатися в каталозі пакета plugin. | +| `openclaw.channel` | Полегшені метадані каталогу каналу, такі як мітки, шляхи документації, псевдоніми та текст для вибору. | +| `openclaw.channel.configuredState` | Полегшені метадані перевірки налаштованого стану, які можуть відповісти на питання «чи вже існує setup лише через env?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки збереженого стану автентифікації, які можуть відповісти на питання «чи вже є хоч якийсь вхід у систему?» без завантаження повного runtime каналу. | +| `openclaw.install.npmSpec` / `openclaw.install.localPath` | Підказки для встановлення/оновлення для пакетних і зовнішньо опублікованих plugin. | | `openclaw.install.defaultChoice` | Бажаний шлях встановлення, коли доступно кілька джерел встановлення. | -| `openclaw.install.minHostVersion` | Мінімальна підтримувана версія хоста OpenClaw, із нижньою межею semver на кшталт `>=2026.3.22`. | -| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення перевіряють отриманий артефакт відносно нього. | -| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення через перевстановлення bundled Plugin, коли config некоректний. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням channel лише для setup завантажуватися до повного Plugin channel під час запуску. | +| `openclaw.install.minHostVersion` | Мінімально підтримувана версія хоста OpenClaw з нижньою межею semver на кшталт `>=2026.3.22`. | +| `openclaw.install.expectedIntegrity` | Очікуваний рядок цілісності npm dist, наприклад `sha512-...`; потоки встановлення й оновлення звіряють отриманий артефакт із ним. | +| `openclaw.install.allowInvalidConfigRecovery` | Дозволяє вузький шлях відновлення перевстановлення пакетного plugin, коли конфігурація недійсна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дає змогу поверхням каналу лише для setup завантажуватися до повного plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в onboarding до завантаження runtime. `package.json#openclaw.install` повідомляє onboarding, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. +Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей plugin, коли користувач обирає один із цих варіантів. Не переносіть підказки встановлення в `openclaw.plugin.json`. -`openclaw.install.minHostVersion` застосовується під час встановлення і завантаження реєстру маніфесту. Некоректні значення відхиляються; новіші, але коректні значення пропускають Plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але коректні значення пропускають plugin на старіших хостах. -Точне закріплення версії npm уже розміщується в `npmSpec`, наприклад -`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися відмовою, якщо отриманий npm-артефакт більше не відповідає закріпленому релізу. -Інтерактивний onboarding усе ще пропонує npm-специфікації довіреного реєстру, зокрема прості назви пакетів і dist-tag, для сумісності. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без закріплення цілісності, з невідповідністю імені пакета та некоректні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає коректного джерела npm, яке можна ним закріпити. -Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його пропущено, визначення реєстру записується без закріплення цілісності. +Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +`"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення завершувалися в закритому режимі, якщо отриманий npm-артефакт більше не відповідає закріпленому випуску. +Інтерактивний онбординг для сумісності все ще пропонує npm-специфікації довіреного реєстру, включно з простими назвами пакетів і dist-tag. Діагностика каталогу може розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю назви пакета та недійсні джерела default-choice. Вона також попереджає, коли `expectedIntegrity` присутній, але немає коректного npm-джерела, яке можна ним закріпити. +Коли `expectedIntegrity` присутній, потоки встановлення/оновлення застосовують його; коли його пропущено, розв’язання реєстру записується без закріплення за цілісністю. -Plugin channel повинні надавати `openclaw.setupEntry`, коли статус, список channel або сканування SecretRef мають визначати налаштовані акаунти без завантаження повного runtime. Запис setup повинен надавати метадані channel разом із безпечними для setup адаптерами config, status і secrets; мережеві клієнти, listener Gateway і transport runtime залишайте в основному entrypoint extension. +Plugin каналів мають надавати `openclaw.setupEntry`, коли status, список каналів або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного runtime. Точка входу setup має відкривати метадані каналу плюс безпечні для setup адаптери конфігурації, status і secrets; мережеві клієнти, слухачі Gateway і runtime транспорту слід тримати в основній точці входу extension. -Поля runtime entrypoint не перевизначають перевірки меж пакета для полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити придатним до завантаження шлях `openclaw.extensions`, що виходить за межі пакета. +Поля точки входу runtime не перевизначають перевірки меж пакета для полів точки входу джерела. +Наприклад, `openclaw.runtimeExtensions` не може зробити доступним шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він не робить довільні зламані config придатними до встановлення. Наразі він лише дозволяє потокам встановлення відновлюватися після певних застарілих збоїв оновлення bundled Plugin, наприклад відсутнього шляху bundled Plugin або застарілого запису `channels.` для того самого bundled Plugin. Непов’язані помилки config усе ще блокують встановлення й спрямовують операторів до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не робить довільні зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє потокам встановлення відновлюватися після конкретних застарілих збоїв оновлення пакетного plugin, таких як відсутній шлях пакетного plugin або застарілий запис `channels.` для того самого пакетного plugin. Непов’язані помилки конфігурації все одно блокують встановлення і спрямовують операторів до `openclaw doctor --fix`. `openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля перевірки: @@ -564,9 +570,9 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth типу так/ні до завантаження повного Plugin channel. Цільовий export має бути невеликою функцією, яка читає лише збережений стан; не спрямовуйте її через широкий barrel повного runtime channel. +Використовуйте це, коли потоки setup, doctor або configured-state потребують дешевого yes/no-пробника автентифікації до завантаження повного plugin каналу. Цільовий експорт має бути невеликою функцією, яка лише читає збережений стан; не спрямовуйте її через повний barrel runtime каналу. -`openclaw.channel.configuredState` має таку саму форму для дешевих перевірок configured-state лише через env: +`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок налаштованого стану лише через env: ```json { @@ -582,64 +588,64 @@ Plugin channel повинні надавати `openclaw.setupEntry`, коли } ``` -Використовуйте це, коли channel може визначити configured-state з env або інших невеликих нерuntime-вхідних даних. Якщо перевірка потребує повного визначення config або реального runtime channel, залишайте цю логіку в hook Plugin `config.hasConfiguredState`. +Використовуйте це, коли канал може відповісти про налаштований стан з env або інших малих нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або справжнього runtime каналу, натомість зберігайте цю логіку в hook plugin `config.hasConfiguredState`. -## Пріоритет discovery (дублікати id Plugin) +## Пріоритет виявлення (дублікати ідентифікаторів plugin) -OpenClaw виявляє Plugin з кількох коренів (bundled, global install, workspace, явно вибрані в config шляхи). Якщо два результати discovery мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. +OpenClaw виявляє plugin із кількох коренів (пакетні, глобальне встановлення, робочий простір, явно вибрані в конфігурації шляхи). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: -1. **Config-selected** — шлях, явно закріплений у `plugins.entries.` -2. **Bundled** — Plugin, що постачаються з OpenClaw -3. **Global install** — Plugin, встановлені в глобальний корінь Plugin OpenClaw -4. **Workspace** — Plugin, виявлені відносно поточного workspace +1. **Вибрані в конфігурації** — шлях, явно закріплений у `plugins.entries.` +2. **Пакетні** — plugin, що постачаються з OpenClaw +3. **Глобальне встановлення** — plugin, встановлені в глобальний корінь plugin OpenClaw +4. **Робочий простір** — plugin, виявлені відносно поточного робочого простору Наслідки: -- Форк або застаріла копія bundled Plugin, що лежить у workspace, не затьмарить bundled-збірку. -- Щоб справді перевизначити bundled Plugin локальним, закріпіть його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладайтеся на discovery workspace. -- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказувати на відкинуту копію. +- Форк або застаріла копія пакетного plugin у робочому просторі не зможе затінити пакетну збірку. +- Щоб справді перевизначити пакетний plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтеся на виявлення робочого простору. +- Відкидання дублікатів записується в журнал, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. -## Вимоги до JSON Schema +## Вимоги до схеми JSON -- **Кожен Plugin повинен містити JSON Schema**, навіть якщо він не приймає config. -- Порожня schema допустима (наприклад, `{ "type": "object", "additionalProperties": false }`). -- Schema проходять валідацію під час читання/запису config, а не під час runtime. +- **Кожен plugin має постачатися зі схемою JSON**, навіть якщо він не приймає конфігурацію. +- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- Схеми проходять валідацію під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки id channel не оголошено в маніфесті Plugin. +- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено маніфестом plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - повинні посилатися на **доступні для discovery** id Plugin. Невідомі id є **помилками**. -- Якщо Plugin встановлено, але він має зламаний або відсутній маніфест чи schema, - валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. -- Якщо config Plugin існує, але Plugin **вимкнено**, config зберігається, а в Doctor і логах з’являється **попередження**. + мають посилатися на **виявлювані** ідентифікатори plugin. Невідомі ідентифікатори є **помилками**. +- Якщо plugin встановлено, але він має зламаний або відсутній маніфест чи схему, + валідація не проходить, а Doctor повідомляє про помилку plugin. +- Якщо конфігурація plugin існує, але plugin **вимкнено**, конфігурація зберігається, і в Doctor + логах показується **попередження**. -Дивіться [Довідник з конфігурації](/uk/gateway/configuration) для повної schema `plugins.*`. +Повну схему `plugins.*` див. у [Довіднику з конфігурації](/uk/gateway/configuration). ## Примітки -- Маніфест є **обов’язковим для власних Plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime усе ще завантажує модуль Plugin окремо; маніфест використовується лише для discovery + валідації. -- Власні маніфести розбираються через JSON5, тож коментарі, завершальні коми й ключі без лапок приймаються, якщо кінцеве значення все одно є об’єктом. -- Завантажувач маніфесту зчитує лише документовані поля маніфесту. Уникайте власних ключів верхнього рівня. -- `channels`, `providers`, `cliBackends` і `skills` можна не вказувати, якщо Plugin їх не потребує. -- `providerDiscoveryEntry` має залишатися легковагим і не повинен імпортувати широкий runtime-код; використовуйте його для статичних метаданих каталогу provider або вузьких дескрипторів discovery, а не для виконання під час обробки запитів. -- Ексклюзивні типи Plugin вибираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). -- Метадані env var (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до Plugin і ефективної активації, перш ніж вважати env var налаштованою. -- Для метаданих runtime wizard, які потребують коду provider, дивіться [Runtime-hook provider](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від native modules, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). +- Маніфест є **обов’язковим для рідних plugin OpenClaw**, зокрема для локальних завантажень із файлової системи. Runtime усе одно завантажує модуль plugin окремо; маніфест призначений лише для виявлення + валідації. +- Рідні маніфести аналізуються як JSON5, тому приймаються коментарі, кінцеві коми та ключі без лапок, якщо кінцеве значення все ще є об’єктом. +- Завантажувач маніфесту читає лише задокументовані поля маніфесту. Уникайте власних ключів верхнього рівня. +- `channels`, `providers`, `cliBackends` і `skills` можна опускати, якщо plugin їх не потребує. +- `providerDiscoveryEntry` має залишатися полегшеним і не повинен імпортувати широкий код runtime; використовуйте його для статичних метаданих каталогу провайдера або вузьких дескрипторів виявлення, а не для виконання під час запиту. +- Виключні типи plugin обираються через `plugins.slots.*`: `kind: "memory"` через `plugins.slots.memory`, `kind: "context-engine"` через `plugins.slots.contextEngine` (типово `legacy`). +- Метадані змінних середовища (`setup.providers[].envVars`, застаріле `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Status, audit, валідація доставки Cron та інші поверхні лише для читання все одно застосовують політику довіри до plugin і ефективної активації, перш ніж вважати змінну середовища налаштованою. +- Для метаданих wizard runtime, які потребують коду провайдера, див. [Hook runtime провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш plugin залежить від native modules, задокументуйте кроки збірки й будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане - - Початок роботи з Plugin. + + Початок роботи з plugin. - - Внутрішня архітектура та модель capability. + + Внутрішня архітектура та модель можливостей. - Довідник SDK Plugin та імпорти підшляхів. + Довідник SDK plugin і імпорти підшляхів. diff --git a/docs/uk/plugins/sdk-agent-harness.md b/docs/uk/plugins/sdk-agent-harness.md index 189ed68a5..1dc5f3449 100644 --- a/docs/uk/plugins/sdk-agent-harness.md +++ b/docs/uk/plugins/sdk-agent-harness.md @@ -1,57 +1,51 @@ --- read_when: - - Ви змінюєте вбудований рантайм агента або реєстр каркаса агента - - Ви реєструєте каркас агента з вбудованого або довіреного плагіна - - Вам потрібно зрозуміти, як плагін Codex пов’язаний із постачальниками моделей + - Ви змінюєте вбудований runtime агента або реєстр каркасів + - Ви реєструєте каркас агента з вбудованого або довіреного Plugin + - Вам потрібно зрозуміти, як Plugin Codex пов’язаний із провайдерами моделей sidebarTitle: Agent Harness -summary: Експериментальна поверхня SDK для плагінів, які замінюють низькорівневий вбудований виконавець агентів -title: Плагіни каркаса агентів +summary: Експериментальна поверхня SDK для Plugin, які замінюють низькорівневий вбудований виконавець агента +title: Plugins каркаса агента x-i18n: - generated_at: "2026-04-24T20:32:19Z" + generated_at: "2026-04-25T00:02:34Z" model: gpt-5.4 provider: openai - source_hash: e73cbaaa239801ec5da18374cc1b2142c9cf7136f8d33d81d2fa04bc4dea3c11 + source_hash: 350dcfa9492ab30d14913a1f275747a5074f5d8651a96309f6002cdf9b8b2803 source_path: plugins/sdk-agent-harness.md workflow: 15 --- -**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не постачальник моделей, не канал і не реєстр інструментів. +**Каркас агента** — це низькорівневий виконавець для одного підготовленого ходу агента OpenClaw. Це не провайдер моделі, не канал і не реєстр інструментів. -Використовуйте цю поверхню лише для вбудованих або довірених нативних плагінів. Контракт -усе ще експериментальний, оскільки типи параметрів навмисно віддзеркалюють поточний -вбудований раннер. +Використовуйте цю поверхню лише для вбудованих або довірених нативних Plugin. Контракт усе ще є експериментальним, оскільки типи параметрів навмисно віддзеркалюють поточний вбудований runner. ## Коли використовувати каркас -Реєструйте каркас агента, коли сімейство моделей має власний нативний рантайм сесії -і звичайний транспорт постачальника OpenClaw є неправильною абстракцією. +Реєструйте каркас агента, коли сімейство моделей має власний нативний runtime сеансу і звичайний транспорт провайдера OpenClaw є хибною абстракцією. Приклади: -- нативний сервер coding-agent, який керує потоками й Compaction -- локальний CLI або демон, який має стримити нативні події плану/міркування/інструментів -- рантайм моделі, якому потрібен власний resume id на додачу до транскрипту - сесії OpenClaw +- нативний сервер coding-agent, який керує потоками та Compaction +- локальний CLI або демон, який має потоково передавати нативні події plan/reasoning/tool +- runtime моделі, якому потрібен власний resume id на додачу до транскрипту сеансу OpenClaw -**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або -WebSocket API моделей створіть [плагін постачальника](/uk/plugins/sdk-provider-plugins). +**Не** реєструйте каркас лише для того, щоб додати новий API LLM. Для звичайних HTTP або WebSocket API моделей створіть [Plugin провайдера](/uk/plugins/sdk-provider-plugins). -## Що все ще належить core +## Чим ядро все ще керує -Перш ніж буде вибрано каркас, OpenClaw уже визначив: +До того, як буде вибрано каркас, OpenClaw уже визначив: -- постачальника й модель -- стан автентифікації рантайму +- провайдера і модель +- стан автентифікації runtime - рівень thinking і бюджет контексту -- файл транскрипту/сесії OpenClaw -- робочий простір, sandbox і політику інструментів -- колбеки відповіді каналу й колбеки стримінгу -- політику резервного перемикання моделей і live-перемикання моделей +- файл транскрипту/сеансу OpenClaw +- workspace, sandbox і політику інструментів +- callback-и відповідей каналу і callback-и потокової передачі +- політику fallback моделі та live-перемикання моделі -Цей поділ навмисний. Каркас виконує підготовлену спробу; він не вибирає -постачальників, не замінює доставку через канал і не перемикає моделі непомітно. +Цей поділ навмисний. Каркас виконує підготовлену спробу; він не вибирає провайдерів, не замінює доставку каналу й не перемикає моделі непомітно. -## Зареєструвати каркас +## Реєстрація каркаса **Імпорт:** `openclaw/plugin-sdk/agent-harness` @@ -89,111 +83,58 @@ export default definePluginEntry({ ## Політика вибору -OpenClaw вибирає каркас після визначення постачальника/моделі: +OpenClaw вибирає каркас після визначення провайдера/моделі: -1. Якщо в наявної сесії записано id каркаса, він має пріоритет, тому зміни config/env не - перемикають цей транскрипт на інший рантайм на льоту. -2. `OPENCLAW_AGENT_RUNTIME=` примусово задає зареєстрований каркас із цим id для - сесій, які ще не закріплені. -3. `OPENCLAW_AGENT_RUNTIME=pi` примусово задає вбудований каркас PI. -4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих каркасів, чи підтримують вони - визначеного постачальника/модель. -5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо - резервний перехід на PI не вимкнено. +1. Записаний id каркаса наявного сеансу має пріоритет, щоб зміни config/env не перемикали цей транскрипт на інший runtime на льоту. +2. `OPENCLAW_AGENT_RUNTIME=` примусово вказує зареєстрований каркас із цим id для сеансів, які ще не закріплені. +3. `OPENCLAW_AGENT_RUNTIME=pi` примусово вказує вбудований каркас PI. +4. `OPENCLAW_AGENT_RUNTIME=auto` запитує в зареєстрованих каркасів, чи підтримують вони визначеного провайдера/модель. +5. Якщо жоден зареєстрований каркас не підходить, OpenClaw використовує PI, якщо fallback на PI не вимкнено. -Збої каркасів плагінів проявляються як збої виконання. У режимі `auto` резервний перехід на PI -використовується лише тоді, коли жоден зареєстрований каркас плагіна не підтримує визначеного -постачальника/модель. Щойно каркас плагіна взяв виконання на себе, OpenClaw не -переграє той самий хід через PI, оскільки це може змінити семантику автентифікації/рантайму -або дублювати побічні ефекти. +Збої каркаса Plugin відображаються як збої виконання. У режимі `auto` fallback на PI використовується лише тоді, коли жоден зареєстрований каркас Plugin не підтримує визначеного провайдера/модель. Щойно каркас Plugin узяв виконання на себе, OpenClaw не повторює той самий хід через PI, оскільки це може змінити семантику auth/runtime або дублювати побічні ефекти. -Вибраний id каркаса зберігається разом з id сесії після вбудованого виконання. -Застарілі сесії, створені до появи закріплення каркасів, вважаються закріпленими за PI, щойно -в них з’являється історія транскрипту. Використовуйте нову/скинуту сесію під час перемикання між PI і -нативним каркасом плагіна. `/status` показує нестандартні id каркасів, як-от `codex`, -поруч із `Fast`; PI залишається прихованим, бо це шлях сумісності за замовчуванням. -Якщо вибраний каркас виглядає несподівано, увімкніть журналювання налагодження `agents/harness` і -перегляньте структурований запис gateway `agent harness selected`. Він містить -вибраний id каркаса, причину вибору, політику рантайму/резервного переходу, а також у режимі -`auto` — результат підтримки для кожного кандидата-плагіна. +Вибраний id каркаса зберігається разом з id сеансу після вбудованого виконання. Застарілі сеанси, створені до закріплення каркасів, вважаються закріпленими за PI, щойно в них з’являється історія транскрипту. Використовуйте новий/скинутий сеанс під час перемикання між PI і нативним каркасом Plugin. `/status` показує нетипові id каркасів, такі як `codex`, поруч із `Fast`; PI приховано, оскільки це типовий шлях сумісності. Якщо вибраний каркас виглядає неочікуваним, увімкніть логування налагодження `agents/harness` і перегляньте структурований запис Gateway `agent harness selected`. Він містить id вибраного каркаса, причину вибору, політику runtime/fallback і, у режимі `auto`, результат підтримки для кожного кандидата Plugin. -Вбудований плагін Codex реєструє `codex` як свій id каркаса. Core розглядає це -як звичайний id каркаса плагіна; специфічні для Codex псевдоніми мають належати плагіну -або config оператора, а не спільному селектору рантайму. +Вбудований Plugin Codex реєструє `codex` як свій id каркаса. Ядро сприймає це як звичайний id каркаса Plugin; специфічні для Codex псевдоніми мають належати Plugin або конфігурації оператора, а не спільному селектору runtime. -## Поєднання постачальника й каркаса +## Поєднання провайдера й каркаса -Більшість каркасів також мають реєструвати постачальника. Постачальник робить refs моделей, -стан автентифікації, метадані моделі й вибір `/model` видимими для решти -OpenClaw. Потім каркас заявляє цей постачальник у `supports(...)`. +Більшість каркасів також мають реєструвати провайдера. Провайдер робить посилання на моделі, статус auth, метадані моделей і вибір `/model` видимими для решти OpenClaw. Потім каркас заявляє підтримку цього провайдера в `supports(...)`. -Вбудований плагін Codex дотримується цього шаблону: +Вбудований Plugin Codex дотримується цієї схеми: -- id постачальника: `codex` -- refs моделей для користувача: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; - застарілі refs `codex/gpt-*` і далі приймаються для сумісності +- id провайдера: `codex` +- користувацькі посилання на моделі: `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"`; застарілі посилання `codex/gpt-*` і далі підтримуються для сумісності - id каркаса: `codex` -- auth: синтетична доступність постачальника, оскільки каркас Codex керує - нативним входом/сесією Codex -- запит до app-server: OpenClaw надсилає Codex «голий» id моделі й дозволяє - каркасу працювати з нативним протоколом app-server +- auth: синтетична доступність провайдера, оскільки каркас Codex керує нативним входом/сеансом Codex +- запит app-server: OpenClaw надсилає Codex чистий id моделі й дозволяє каркасу працювати з нативним протоколом app-server -Плагін Codex є доповнювальним. Звичайні refs `openai/gpt-*` і далі використовують -нормальний шлях постачальника OpenClaw, якщо ви не примусите каркас Codex через -`embeddedHarness.runtime: "codex"`. Старіші refs `codex/gpt-*` усе ще вибирають -постачальника й каркас Codex для сумісності. +Plugin Codex є додатковим. Звичайні посилання `openai/gpt-*` і далі використовують стандартний шлях провайдера OpenClaw, якщо ви примусово не вкажете каркас Codex через `embeddedHarness.runtime: "codex"`. Старіші посилання `codex/gpt-*` і далі вибирають провайдера й каркас Codex для сумісності. -Щоб дізнатися про налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex, див. -[Каркас Codex](/uk/plugins/codex-harness). +Налаштування для операторів, приклади префіксів моделей і конфігурації лише для Codex дивіться в [Codex Harness](/uk/plugins/codex-harness). -OpenClaw вимагає Codex app-server `0.118.0` або новішої версії. Плагін Codex перевіряє -initialize-handshake app-server і блокує старіші або безверсійні сервери, щоб -OpenClaw працював лише з тією поверхнею протоколу, з якою його було протестовано. +OpenClaw вимагає Codex app-server версії `0.118.0` або новішої. Plugin Codex перевіряє initialize handshake app-server і блокує старі або неверсіоновані сервери, щоб OpenClaw працював лише з тим протокольним інтерфейсом, який було протестовано. ### Middleware результатів інструментів -Вбудовані плагіни можуть додавати не прив’язане до каркаса middleware результатів інструментів через -`api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує -цільові id каркасів у `contracts.agentToolResultMiddleware`. Цей довірений шов -призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex передадуть -вивід інструмента назад у модель. +Вбудовані Plugins можуть під’єднувати runtime-нейтральне middleware результатів інструментів через `api.registerAgentToolResultMiddleware(...)`, коли їхній маніфест оголошує цільові id runtime у `contracts.agentToolResultMiddleware`. Цей довірений шов призначений для асинхронних перетворень результатів інструментів, які мають виконуватися до того, як PI або Codex поверне вивід інструмента назад у модель. -Застарілі вбудовані плагіни все ще можуть використовувати -`api.registerCodexAppServerExtensionFactory(...)` для middleware лише для Codex app-server, -але нові перетворення результатів мають використовувати API, не прив’язане до каркаса. -Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` є застарілим для -перетворень результатів інструментів; залишайте його лише для вбудованого коду сумісності, якому -все ще потрібні прямі події вбудованого раннера Pi. +Застарілі вбудовані Plugins і далі можуть використовувати `api.registerCodexAppServerExtensionFactory(...)` для middleware лише app-server Codex, але нові перетворення результатів слід реалізовувати через runtime-нейтральний API. +Хук лише для Pi `api.registerEmbeddedExtensionFactory(...)` застарів для перетворень результатів інструментів; залишайте його лише для коду сумісності вбудованих Plugin, якому все ще потрібні прямі події вбудованого runner Pi. ### Режим нативного каркаса Codex -Вбудований каркас `codex` — це нативний режим Codex для вбудованих ходів -агента OpenClaw. Спочатку увімкніть вбудований плагін `codex` і додайте `codex` до -`plugins.allow`, якщо ваш config використовує обмежувальний allowlist. Конфігурації нативного app-server -мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. -Натомість використовуйте `openai-codex/*` для Codex OAuth через PI. Застарілі refs моделей `codex/*` -залишаються псевдонімами сумісності для нативного каркаса. +Вбудований каркас `codex` — це нативний режим Codex для вбудованих ходів агента OpenClaw. Спочатку увімкніть вбудований Plugin `codex` і додайте `codex` до `plugins.allow`, якщо ваша конфігурація використовує обмежувальний allowlist. Конфігурації нативного app-server мають використовувати `openai/gpt-*` з `embeddedHarness.runtime: "codex"`. Для Codex OAuth через PI використовуйте `openai-codex/*`. Застарілі посилання на моделі `codex/*` залишаються псевдонімами сумісності для нативного каркаса. -Коли цей режим виконується, Codex керує нативним id потоку, поведінкою відновлення, -Compaction і виконанням app-server. OpenClaw усе ще керує чат-каналом, -видимим дзеркалом транскрипту, політикою інструментів, погодженнями, доставкою медіа й -вибором сесії. Використовуйте `embeddedHarness.runtime: "codex"` разом із -`embeddedHarness.fallback: "none"`, коли вам потрібно довести, що лише шлях -Codex app-server може взяти виконання на себе. Ця конфігурація є лише запобіжником вибору: -збої Codex app-server уже й так напряму завершуються помилкою без повторної спроби через PI. +Коли цей режим працює, Codex керує нативним id потоку, поведінкою resume, Compaction і виконанням app-server. OpenClaw і далі керує чатом каналу, видимим дзеркалом транскрипту, політикою інструментів, схваленнями, доставкою медіа та вибором сеансу. Використовуйте `embeddedHarness.runtime: "codex"` разом із `embeddedHarness.fallback: "none"`, коли потрібно довести, що виконання може взяти на себе лише шлях app-server Codex. Ця конфігурація є лише guard-вибором: збої app-server Codex уже безпосередньо завершуються помилкою без повторної спроби через PI. -## Вимкнення резервного переходу на PI +## Вимкнення fallback на PI -За замовчуванням OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, -встановленим у `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані плагінні -каркаси можуть заявити про підтримку пари постачальник/модель. Якщо жоден не підходить, -OpenClaw переходить на PI. +Типово OpenClaw запускає вбудованих агентів із `agents.defaults.embeddedHarness`, установленим як `{ runtime: "auto", fallback: "pi" }`. У режимі `auto` зареєстровані каркаси Plugin можуть заявити підтримку для пари провайдер/модель. Якщо жоден не підходить, OpenClaw переходить на PI. -Установіть `fallback: "none"`, коли потрібно, щоб відсутність вибору каркаса плагіна -завершувалася помилкою замість використання PI. Збої вже вибраних каркасів плагінів і так завершуються помилкою. Це -не блокує явне `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. +Установіть `fallback: "none"`, коли потрібно, щоб відсутність відповідного каркаса Plugin спричиняла помилку замість використання PI. Збої вже вибраного каркаса Plugin і так завершуються жорсткою помилкою. Це не блокує явний `runtime: "pi"` або `OPENCLAW_AGENT_RUNTIME=pi`. -Для вбудованих виконань лише з Codex: +Для вбудованих запусків лише з Codex: ```json { @@ -209,9 +150,7 @@ OpenClaw переходить на PI. } ``` -Якщо ви хочете, щоб будь-який зареєстрований каркас плагіна міг заявити про відповідні моделі, але ніколи -не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть -резервний перехід: +Якщо ви хочете, щоб будь-який зареєстрований каркас Plugin міг заявляти підтримку для відповідних моделей, але ніколи не хочете, щоб OpenClaw непомітно переходив на PI, залиште `runtime: "auto"` і вимкніть fallback: ```json { @@ -251,9 +190,7 @@ OpenClaw переходить на PI. } ``` -`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований рантайм. Використовуйте -`OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути резервний перехід на PI через -оточення. +`OPENCLAW_AGENT_RUNTIME` і далі перевизначає налаштований runtime. Використовуйте `OPENCLAW_AGENT_HARNESS_FALLBACK=none`, щоб вимкнути fallback на PI через оточення. ```bash OPENCLAW_AGENT_RUNTIME=codex \ @@ -261,53 +198,40 @@ OPENCLAW_AGENT_HARNESS_FALLBACK=none \ openclaw gateway run ``` -Коли резервний перехід вимкнено, сесія завершується помилкою на ранньому етапі, якщо запитаний каркас не -зареєстровано, він не підтримує визначеного постачальника/модель або завершується помилкою до -появи побічних ефектів ходу. Це навмисно для розгортань лише з Codex і -для live-тестів, які мають довести, що шлях Codex app-server справді використовується. +Коли fallback вимкнено, сеанс завершується помилкою на ранньому етапі, якщо запитаний каркас не зареєстровано, не підтримує визначеного провайдера/модель або завершується помилкою до появи побічних ефектів ходу. Це навмисно для розгортань лише з Codex і для live-тестів, які мають довести, що насправді використовується шлях app-server Codex. -Цей параметр керує лише каркасом вбудованого агента. Він не вимикає маршрутизацію -специфічних для постачальника моделей для зображень, відео, музики, TTS, PDF чи інших. +Цей параметр керує лише вбудованим каркасом агента. Він не вимикає маршрутизацію моделей, специфічну для провайдерів, для зображень, відео, музики, TTS, PDF або інших типів. -## Нативні сесії та дзеркало транскрипту +## Нативні сеанси й дзеркало транскрипту -Каркас може зберігати нативний id сесії, id потоку або токен відновлення на боці демона. -Явно зберігайте цей зв’язок асоційованим із сесією OpenClaw і продовжуйте -дзеркалити видимий користувачеві вивід асистента/інструментів у транскрипт OpenClaw. +Каркас може зберігати нативний id сеансу, id потоку або токен resume на боці демона. +Тримайте цей зв’язок явно пов’язаним із сеансом OpenClaw і продовжуйте віддзеркалювати видимий для користувача вивід помічника/інструментів у транскрипт OpenClaw. Транскрипт OpenClaw залишається шаром сумісності для: -- видимої в каналі історії сесії +- історії сеансу, видимої в каналі - пошуку та індексації транскрипту -- перемикання назад на вбудований каркас PI на наступному ході -- загальної поведінки `/new`, `/reset` і видалення сесії +- повернення до вбудованого каркаса PI на наступному ході +- універсальної поведінки `/new`, `/reset` і видалення сеансу -Якщо ваш каркас зберігає sidecar-прив’язку, реалізуйте `reset(...)`, щоб OpenClaw міг -очистити її, коли пов’язану сесію OpenClaw скинуто. +Якщо ваш каркас зберігає sidecar-зв’язок, реалізуйте `reset(...)`, щоб OpenClaw міг очистити його під час скидання пов’язаного сеансу OpenClaw. ## Результати інструментів і медіа -Core формує список інструментів OpenClaw і передає його в підготовлену спробу. -Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через -форму результату каркаса, а не надсилайте медіа в канал самостійно. +Ядро формує список інструментів OpenClaw і передає його в підготовлену спробу. Коли каркас виконує динамічний виклик інструмента, повертайте результат інструмента через форму результату каркаса замість того, щоб самостійно надсилати медіа в канал. -Це зберігає текст, зображення, відео, музику, TTS, погодження та виводи -інструментів для обміну повідомленнями на тому самому шляху доставки, що й виконання з підтримкою PI. +Це зберігає текст, зображення, відео, музику, TTS, схвалення й результати інструментів повідомлень на тому самому шляху доставки, що й у запусках на основі PI. ## Поточні обмеження -- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроби/результату все ще - містять назви `Pi` для сумісності. -- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу плагінам постачальників, - доки вам не знадобиться нативний рантайм сесії. -- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред - ходу після того, як уже почалися нативні інструменти, погодження, текст асистента або - надсилання повідомлень. +- Публічний шлях імпорту є загальним, але деякі псевдоніми типів спроб/результатів і далі містять назви `Pi` для сумісності. +- Встановлення сторонніх каркасів є експериментальним. Віддавайте перевагу Plugin провайдерів, доки вам не знадобиться нативний runtime сеансу. +- Перемикання каркасів між ходами підтримується. Не перемикайте каркаси посеред ходу після того, як уже почалися нативні інструменти, схвалення, текст помічника або надсилання повідомлень. ## Пов’язане - [Огляд SDK](/uk/plugins/sdk-overview) -- [Допоміжні засоби рантайму](/uk/plugins/sdk-runtime) -- [Плагіни постачальників](/uk/plugins/sdk-provider-plugins) -- [Каркас Codex](/uk/plugins/codex-harness) -- [Постачальники моделей](/uk/concepts/model-providers) +- [Runtime Helpers](/uk/plugins/sdk-runtime) +- [Provider Plugins](/uk/plugins/sdk-provider-plugins) +- [Codex Harness](/uk/plugins/codex-harness) +- [Провайдери моделей](/uk/concepts/model-providers) diff --git a/docs/uk/plugins/sdk-migration.md b/docs/uk/plugins/sdk-migration.md index 89201598d..2d56e4b24 100644 --- a/docs/uk/plugins/sdk-migration.md +++ b/docs/uk/plugins/sdk-migration.md @@ -3,36 +3,47 @@ read_when: - Ви бачите попередження OPENCLAW_PLUGIN_SDK_COMPAT_DEPRECATED - Ви бачите попередження OPENCLAW_EXTENSION_API_DEPRECATED - Ви використовуєте `api.registerEmbeddedExtensionFactory` - - Ви оновлюєте Plugin до сучасної архітектури Plugin + - Ви оновлюєте Plugin до сучасної архітектури плагінів - Ви підтримуєте зовнішній Plugin OpenClaw sidebarTitle: Migrate to SDK -summary: Перейдіть із застарілого шару зворотної сумісності на сучасний Plugin SDK -title: Міграція Plugin SDK +summary: Перейти із застарілого шару зворотної сумісності на сучасний SDK Plugin +title: Міграція SDK Plugin x-i18n: - generated_at: "2026-04-24T20:32:19Z" + generated_at: "2026-04-25T00:02:51Z" model: gpt-5.4 provider: openai - source_hash: fe4a2f78653c1eabd4295cd7ad9cdb7b60995f172b6018650dd8f570f9b47c8d + source_hash: ccf6e736c2a7cb54f9249d92b27edcecfabda14c64d88a8932a69565e246c33c source_path: plugins/sdk-migration.md workflow: 15 --- -OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури Plugin із цільовими, задокументованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. +OpenClaw перейшов від широкого шару зворотної сумісності до сучасної архітектури плагінів із цільовими, документованими імпортами. Якщо ваш Plugin було створено до появи нової архітектури, цей посібник допоможе вам виконати міграцію. ## Що змінюється -Стара система Plugin надавала дві надто широкі поверхні, які дозволяли Plugin імпортувати все, що їм було потрібно, з однієї точки входу: +Стара система плагінів надавала дві широкі поверхні, які дозволяли Plugin імпортувати +будь-що потрібне з однієї точки входу: -- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки допоміжних засобів. Його було запроваджено, щоб старіші Plugin на основі хуків продовжували працювати під час створення нової архітектури Plugin. -- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до допоміжних засобів на стороні хоста, таких як вбудований запускальник агентів. -- **`api.registerEmbeddedExtensionFactory(...)`** — хук для вбудованих розширень лише для Pi, який міг спостерігати за подіями вбудованого запускальника, такими як `tool_result`. +- **`openclaw/plugin-sdk/compat`** — один імпорт, який повторно експортував десятки + допоміжних функцій. Його було запроваджено, щоб зберегти працездатність старіших + плагінів на основі hook, поки будувалася нова архітектура плагінів. +- **`openclaw/extension-api`** — міст, який надавав Plugin прямий доступ до + допоміжних функцій на боці хоста, таких як вбудований runner агента. +- **`api.registerEmbeddedExtensionFactory(...)`** — hook вбудованого extension + лише для Pi, який міг спостерігати події вбудованого runner, такі як `tool_result`. -Тепер ці поверхні **застарілі**. Вони все ще працюють під час виконання, але нові Plugin не повинні їх використовувати, а наявні Plugin слід мігрувати до того, як у наступному мажорному релізі їх буде видалено. +Ці поверхні тепер **застарілі**. Вони все ще працюють під час виконання, але нові +Plugin не повинні їх використовувати, а наявні мають перейти на новий підхід до того, +як наступний мажорний випуск їх видалить. -OpenClaw не видаляє й не переосмислює задокументовану поведінку Plugin у тій самій зміні, яка запроваджує заміну. Зміни контракту з порушенням сумісності спершу мають пройти через адаптер сумісності, діагностику, документацію та період застарівання. Це стосується імпортів SDK, полів маніфесту, API налаштування, хуків і поведінки реєстрації під час виконання. +OpenClaw не видаляє і не переосмислює документовану поведінку Plugin у тій самій +зміні, де вводиться заміна. Зміни контракту, що ламають сумісність, спочатку мають +пройти через адаптер сумісності, діагностику, документацію та період застарівання. +Це стосується імпортів SDK, полів manifest, API налаштування, hook і поведінки +реєстрації під час виконання. - Шар зворотної сумісності буде видалено в одному з майбутніх мажорних релізів. + Шар зворотної сумісності буде видалено в одному з майбутніх мажорних випусків. Plugin, які все ще імпортують із цих поверхонь, перестануть працювати, коли це станеться. @@ -40,40 +51,53 @@ OpenClaw не видаляє й не переосмислює задокумен Старий підхід спричиняв проблеми: -- **Повільний запуск** — імпорт одного допоміжного засобу завантажував десятки не пов’язаних між собою модулів -- **Циклічні залежності** — широкі повторні експорти полегшували створення циклів імпорту -- **Неочевидна поверхня API** — не було способу визначити, які експорти були стабільними, а які внутрішніми +- **Повільний запуск** — імпорт однієї допоміжної функції завантажував десятки не пов’язаних модулів +- **Циклічні залежності** — широкі повторні експорти спрощували створення циклів імпорту +- **Нечітка поверхня API** — не було способу зрозуміти, які експорти є стабільними, а які внутрішніми -Сучасний Plugin SDK вирішує цю проблему: кожен шлях імпорту (`openclaw/plugin-sdk/\`) — це невеликий самодостатній модуль із чітким призначенням і задокументованим контрактом. +Сучасний SDK Plugin виправляє це: кожен шлях імпорту (`openclaw/plugin-sdk/\`) +є невеликим, самодостатнім модулем із чітким призначенням і документованим контрактом. -Застарілі зручні шви provider для вбудованих каналів також зникли. Імпорти на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, `openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, допоміжні шви з брендуванням каналів і `openclaw/plugin-sdk/telegram-core` були приватними скороченнями для монорепозиторію, а не стабільними контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині робочого простору вбудованого Plugin зберігайте допоміжні засоби, що належать provider, у власному `api.ts` або `runtime-api.ts` цього Plugin. +Застарілі зручні seams provider для вбудованих каналів також зникли. Імпорти +на кшталт `openclaw/plugin-sdk/slack`, `openclaw/plugin-sdk/discord`, +`openclaw/plugin-sdk/signal`, `openclaw/plugin-sdk/whatsapp`, +допоміжні channel-branded seams і +`openclaw/plugin-sdk/telegram-core` були приватними скороченнями monorepo, а не +стабільними контрактами Plugin. Натомість використовуйте вузькі загальні підшляхи SDK. Усередині +робочого простору вбудованого Plugin зберігайте допоміжні функції, що належать provider, у власному +`api.ts` або `runtime-api.ts` цього Plugin. Поточні приклади вбудованих provider: -- Anthropic зберігає допоміжні засоби потокової передачі, специфічні для Claude, у власному шві `api.ts` / `contract-api.ts` -- OpenAI зберігає конструктори provider, допоміжні засоби для моделей за замовчуванням і конструктори realtime provider у власному `api.ts` -- OpenRouter зберігає конструктор provider і допоміжні засоби онбордингу/конфігурації у власному `api.ts` +- Anthropic зберігає допоміжні функції потокової передачі, специфічні для Claude, у власному seam `api.ts` / + `contract-api.ts` +- OpenAI зберігає builder-и provider, допоміжні функції типових моделей і builder-и provider + реального часу у власному `api.ts` +- OpenRouter зберігає builder provider і допоміжні функції onboarding/config у власному + `api.ts` ## Політика сумісності -Для зовнішніх Plugin робота із сумісністю виконується в такому порядку: +Для зовнішніх Plugin робота із сумісністю відбувається в такому порядку: 1. додати новий контракт -2. зберегти стару поведінку, підключивши її через адаптер сумісності -3. вивести діагностику або попередження, яке вказує старий шлях і заміну -4. покрити тести для обох шляхів +2. зберегти стару поведінку через адаптер сумісності +3. вивести діагностичне повідомлення або попередження, яке вказує старий шлях і заміну +4. покрити обидва шляхи в тестах 5. задокументувати застарівання та шлях міграції -6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному релізі +6. видаляти лише після оголошеного вікна міграції, зазвичай у мажорному випуску -Якщо поле маніфесту все ще приймається, автори Plugin можуть і далі його використовувати, доки документація й діагностика не скажуть інакше. Новий код має надавати перевагу задокументованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних релізів. +Якщо поле manifest усе ще приймається, автори Plugin можуть продовжувати його використовувати, +доки документація та діагностика не скажуть інше. Новому коду слід віддавати перевагу +документованій заміні, але наявні Plugin не повинні ламатися під час звичайних мінорних +випусків. -## Як мігрувати +## Як виконати міграцію - - Вбудовані Plugin повинні замінити обробники результатів інструментів лише для Pi через - `api.registerEmbeddedExtensionFactory(...)` на - middleware, нейтральне до harness. + + Вбудовані Plugin мають замінити обробники tool-result лише для Pi через + `api.registerEmbeddedExtensionFactory(...)` на middleware, нейтральне до runtime. ```typescript // Before: Pi-only compatibility hook @@ -83,50 +107,60 @@ OpenClaw не видаляє й не переосмислює задокумен }); }); - // After: Pi and Codex app-server dynamic tools + // After: Pi and Codex runtime dynamic tools api.registerAgentToolResultMiddleware(async (event) => { return compactToolResult(event); }, { - harnesses: ["pi", "codex-app-server"], + runtimes: ["pi", "codex"], }); ``` - Одночасно оновіть маніфест Plugin: + Одночасно оновіть manifest Plugin: ```json { "contracts": { - "agentToolResultMiddleware": ["pi", "codex-app-server"] + "agentToolResultMiddleware": ["pi", "codex"] } } ``` - Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності, якому все ще потрібні прямі події вбудованого запускальника Pi. Зовнішні Plugin не можуть реєструвати middleware результатів інструментів, оскільки воно може переписувати вихід інструмента з високим рівнем довіри до того, як модель його побачить. + Залишайте `contracts.embeddedExtensionFactories` лише для вбудованого коду сумісності, + якому все ще потрібні прямі події вбудованого runner Pi. Зовнішні Plugin + не можуть реєструвати middleware tool-result, оскільки воно може переписувати високодовірений + вивід інструмента до того, як його побачить модель. - - Plugin каналів із підтримкою approval тепер надають нативну поведінку approval через - `approvalCapability.nativeRuntime` разом зі спільним реєстром контексту runtime. + + Channel Plugin із підтримкою підтверджень тепер надають нативну поведінку підтвердження через + `approvalCapability.nativeRuntime` плюс спільний реєстр runtime-context. - Основні зміни: + Ключові зміни: - Замініть `approvalCapability.handler.loadRuntime(...)` на `approvalCapability.nativeRuntime` - - Перенесіть auth/доставку, специфічні для approval, зі застарілого підключення `plugin.auth` / - `plugin.approvals` на `approvalCapability` - - `ChannelPlugin.approvals` було видалено з публічного контракту Plugin каналу; перенесіть поля delivery/native/render до `approvalCapability` - - `plugin.auth` залишається лише для потоків входу/виходу з каналу; core більше не читає там хуки auth для approval - - Реєструйте об’єкти runtime, що належать каналу, як-от клієнти, токени або застосунки Bolt, через `openclaw/plugin-sdk/channel-runtime-context` - - Не надсилайте сповіщення про перенаправлення, що належать Plugin, із нативних обробників approval; тепер core відповідає за сповіщення «переспрямовано в інше місце» на основі фактичних результатів доставки - - Під час передавання `channelRuntime` до `createChannelManager(...)` надавайте справжню поверхню `createPluginRuntime().channel`. Часткові заглушки відхиляються. + - Перенесіть auth/delivery, специфічні для підтверджень, зі застарілої прив’язки `plugin.auth` / + `plugin.approvals` до `approvalCapability` + - `ChannelPlugin.approvals` видалено з публічного контракту channel-plugin; + перенесіть поля delivery/native/render до `approvalCapability` + - `plugin.auth` залишається лише для потоків входу/виходу channel; hook авторизації підтверджень + там більше не зчитуються core + - Реєструйте об’єкти runtime, що належать channel, такі як клієнти, токени або Bolt + apps, через `openclaw/plugin-sdk/channel-runtime-context` + - Не надсилайте сповіщення про перенаправлення, що належать Plugin, з native-обробників підтвердження; + тепер core керує сповіщеннями routed-elsewhere на основі фактичних результатів доставки + - Під час передавання `channelRuntime` у `createChannelManager(...)` надавайте + реальну поверхню `createPluginRuntime().channel`. Часткові stub відхиляються. - Поточну структуру можливостей approval див. у `/plugins/sdk-channel-plugins`. + Поточну структуру capability підтвердження див. у `/plugins/sdk-channel-plugins`. - - Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, нерозв’язані Windows-обгортки `.cmd`/`.bat` тепер завершуються із закритою відмовою, якщо ви явно не передасте `allowShellFallback: true`. + + Якщо ваш Plugin використовує `openclaw/plugin-sdk/windows-spawn`, невизначені wrapper `.cmd`/`.bat` у Windows + тепер завершуються без резервного переходу, якщо ви явно не передасте + `allowShellFallback: true`. ```typescript // Before @@ -141,12 +175,13 @@ OpenClaw не видаляє й не переосмислює задокумен }); ``` - Якщо ваш виклик не покладається навмисно на резервний перехід через оболонку, не встановлюйте `allowShellFallback`, а натомість обробляйте викинуту помилку. + Якщо ваш виклик не покладається навмисно на резервний перехід через shell, не задавайте + `allowShellFallback` і натомість обробляйте викинуту помилку. - Знайдіть у своєму Plugin імпорти з будь-якої із застарілих поверхонь: + Виконайте пошук у своєму Plugin для імпортів із будь-якої із застарілих поверхонь: ```bash grep -r "plugin-sdk/compat" my-plugin/ @@ -155,8 +190,8 @@ OpenClaw не видаляє й не переосмислює задокумен - - Кожен експорт зі старої поверхні відповідає певному сучасному шляху імпорту: + + Кожен експорт зі старої поверхні зіставляється з конкретним сучасним шляхом імпорту: ```typescript // Before (deprecated backwards-compatibility layer) @@ -172,7 +207,8 @@ OpenClaw не видаляє й не переосмислює задокумен import { resolveControlCommandGate } from "openclaw/plugin-sdk/command-auth"; ``` - Для допоміжних засобів на стороні хоста використовуйте ін’єктований runtime Plugin замість прямого імпорту: + Для допоміжних функцій на боці хоста використовуйте впроваджений runtime Plugin замість прямого + імпорту: ```typescript // Before (deprecated extension-api bridge) @@ -183,7 +219,7 @@ OpenClaw не видаляє й не переосмислює задокумен const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt }); ``` - Такий самий шаблон застосовується й до інших застарілих допоміжних засобів bridge: + Той самий шаблон застосовується до інших допоміжних функцій застарілого bridge: | Старий імпорт | Сучасний еквівалент | | --- | --- | @@ -193,7 +229,7 @@ OpenClaw не видаляє й не переосмислює задокумен | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` | | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` | | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` | - | допоміжні засоби сховища сесій | `api.runtime.agent.session.*` | + | session store helpers | `api.runtime.agent.session.*` | @@ -208,183 +244,185 @@ OpenClaw не видаляє й не переосмислює задокумен ## Довідник шляхів імпорту - | Шлях імпорту | Призначення | Основні експорти | + | Шлях імпорту | Призначення | Ключові експорти | | --- | --- | --- | - | `plugin-sdk/plugin-entry` | Канонічний допоміжний засіб точки входу Plugin | `definePluginEntry` | - | `plugin-sdk/core` | Застарілий узагальнений повторний експорт для визначень/конструкторів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | + | `plugin-sdk/plugin-entry` | Канонічна допоміжна функція точки входу Plugin | `definePluginEntry` | + | `plugin-sdk/core` | Застарілий парасольковий повторний експорт для визначень/builder-ів точок входу каналів | `defineChannelPluginEntry`, `createChatChannelPlugin` | | `plugin-sdk/config-schema` | Експорт кореневої схеми конфігурації | `OpenClawSchema` | - | `plugin-sdk/provider-entry` | Допоміжний засіб точки входу для одного provider | `defineSingleProviderPluginEntry` | - | `plugin-sdk/channel-core` | Цільові визначення та конструктори точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | - | `plugin-sdk/setup` | Спільні допоміжні засоби майстра налаштування | Запити allowlist, конструктори стану налаштування | - | `plugin-sdk/setup-runtime` | Допоміжні засоби runtime для етапу налаштування | Безпечні для імпорту адаптери патчів налаштування, допоміжні засоби для приміток пошуку, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | - | `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`, нормалізація ідентифікатора облікового запису | - | `plugin-sdk/account-resolution` | Допоміжні засоби пошуку облікового запису | Допоміжні засоби пошуку облікового запису + резервного значення за замовчуванням | - | `plugin-sdk/account-helpers` | Вузькі допоміжні засоби облікових записів | Допоміжні засоби для списку облікових записів/дій з обліковими записами | + | `plugin-sdk/provider-entry` | Допоміжна функція точки входу для одного provider | `defineSingleProviderPluginEntry` | + | `plugin-sdk/channel-core` | Цільові визначення та builder-и точок входу каналів | `defineChannelPluginEntry`, `defineSetupPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase` | + | `plugin-sdk/setup` | Спільні допоміжні функції майстра налаштування | Запити allowlist, builder-и стану налаштування | + | `plugin-sdk/setup-runtime` | Допоміжні функції runtime під час налаштування | Безпечні для імпорту адаптери patch для налаштування, допоміжні функції для lookup note, `promptResolvedAllowFrom`, `splitSetupEntries`, делеговані проксі налаштування | + | `plugin-sdk/setup-adapter-runtime` | Допоміжні функції адаптера налаштування | `createEnvPatchedAccountSetupAdapter` | + | `plugin-sdk/setup-tools` | Допоміжні функції інструментів налаштування | `formatCliCommand`, `detectBinary`, `extractArchive`, `resolveBrewExecutable`, `formatDocsLink`, `CONFIG_DIR` | + | `plugin-sdk/account-core` | Допоміжні функції для кількох облікових записів | Допоміжні функції списку облікових записів/конфігурації/action-gate | + | `plugin-sdk/account-id` | Допоміжні функції account-id | `DEFAULT_ACCOUNT_ID`, нормалізація account-id | + | `plugin-sdk/account-resolution` | Допоміжні функції пошуку облікового запису | Допоміжні функції пошуку облікового запису + резервного типового значення | + | `plugin-sdk/account-helpers` | Вузькі допоміжні функції для облікових записів | Допоміжні функції списку облікових записів/дій облікового запису | | `plugin-sdk/channel-setup` | Адаптери майстра налаштування | `createOptionalChannelSetupSurface`, `createOptionalChannelSetupAdapter`, `createOptionalChannelSetupWizard`, а також `DEFAULT_ACCOUNT_ID`, `createTopLevelChannelDmPolicy`, `setSetupChannelEnabled`, `splitSetupEntries` | - | `plugin-sdk/channel-pairing` | Примітиви DM-парування | `createChannelPairingController` | - | `plugin-sdk/channel-reply-pipeline` | Підключення префікса відповіді + індикатора набору | `createChannelReplyPipeline` | + | `plugin-sdk/channel-pairing` | Примітиви підключення DM | `createChannelPairingController` | + | `plugin-sdk/channel-reply-pipeline` | Префікс відповіді + логіка typing | `createChannelReplyPipeline` | | `plugin-sdk/channel-config-helpers` | Фабрики адаптерів конфігурації | `createHybridChannelConfigAdapter` | - | `plugin-sdk/channel-config-schema` | Конструктори схем конфігурації | Типи схем конфігурації каналу | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби конфігурації команд Telegram | Нормалізація назв команд, обрізання описів, валідація дублікатів/конфліктів | + | `plugin-sdk/channel-config-schema` | Builder-и схем конфігурації | Типи схем конфігурації каналів | + | `plugin-sdk/telegram-command-config` | Допоміжні функції конфігурації команд Telegram | Нормалізація назв команд, обрізання опису, перевірка дублікатів/конфліктів | | `plugin-sdk/channel-policy` | Визначення політики груп/DM | `resolveChannelGroupRequireMention` | - | `plugin-sdk/channel-lifecycle` | Допоміжні засоби життєвого циклу статусу облікового запису та чернеткового потоку | `createAccountStatusSink`, допоміжні засоби фіналізації попереднього перегляду чернетки | - | `plugin-sdk/inbound-envelope` | Допоміжні засоби вхідного envelope | Спільні допоміжні засоби маршрутизації + побудови envelope | - | `plugin-sdk/inbound-reply-dispatch` | Допоміжні засоби вхідних відповідей | Спільні допоміжні засоби запису та диспетчеризації | - | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні засоби розбору/зіставлення цілей | - | `plugin-sdk/outbound-media` | Допоміжні засоби вихідного медіа | Спільне завантаження вихідного медіа | - | `plugin-sdk/outbound-runtime` | Допоміжні засоби вихідного runtime | Допоміжні засоби вихідної ідентичності/делегата надсилання та планування payload | - | `plugin-sdk/thread-bindings-runtime` | Допоміжні засоби прив’язок потоків | Допоміжні засоби життєвого циклу та адаптера прив’язок потоків | - | `plugin-sdk/agent-media-payload` | Застарілі допоміжні засоби payload медіа агента | Конструктор payload медіа агента для застарілих макетів полів | - | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти runtime каналу | + | `plugin-sdk/channel-lifecycle` | Допоміжні функції стану облікового запису та життєвого циклу чернеткового потоку | `createAccountStatusSink`, допоміжні функції фіналізації чернеткового попереднього перегляду | + | `plugin-sdk/inbound-envelope` | Допоміжні функції вхідного envelope | Спільні допоміжні функції маршруту + builder-а envelope | + | `plugin-sdk/inbound-reply-dispatch` | Допоміжні функції вхідних відповідей | Спільні допоміжні функції record-and-dispatch | + | `plugin-sdk/messaging-targets` | Розбір цілей повідомлень | Допоміжні функції розбору/зіставлення цілей | + | `plugin-sdk/outbound-media` | Допоміжні функції вихідних медіа | Спільне завантаження вихідних медіа | + | `plugin-sdk/outbound-runtime` | Допоміжні функції вихідного runtime | Допоміжні функції вихідної ідентичності/send delegate і планування payload | + | `plugin-sdk/thread-bindings-runtime` | Допоміжні функції thread-binding | Допоміжні функції життєвого циклу та адаптера thread-binding | + | `plugin-sdk/agent-media-payload` | Застарілі допоміжні функції media payload | Builder media payload агента для застарілих схем полів | + | `plugin-sdk/channel-runtime` | Застарілий shim сумісності | Лише застарілі утиліти channel runtime | | `plugin-sdk/channel-send-result` | Типи результатів надсилання | Типи результатів відповіді | | `plugin-sdk/runtime-store` | Постійне сховище Plugin | `createPluginRuntimeStore` | - | `plugin-sdk/runtime` | Широкі допоміжні засоби runtime | Допоміжні засоби runtime/логування/резервного копіювання/встановлення Plugin | - | `plugin-sdk/runtime-env` | Вузькі допоміжні засоби середовища runtime | Допоміжні засоби logger/середовища runtime, timeout, retry та backoff | - | `plugin-sdk/plugin-runtime` | Спільні допоміжні засоби runtime Plugin | Допоміжні засоби команд/хуків/http/інтерактивності Plugin | - | `plugin-sdk/hook-runtime` | Допоміжні засоби конвеєра хуків | Спільні допоміжні засоби конвеєра Webhook/внутрішніх хуків | - | `plugin-sdk/lazy-runtime` | Допоміжні засоби лінивого runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | - | `plugin-sdk/process-runtime` | Допоміжні засоби процесів | Спільні допоміжні засоби exec | - | `plugin-sdk/cli-runtime` | Допоміжні засоби CLI runtime | Форматування команд, очікування, допоміжні засоби версій | - | `plugin-sdk/gateway-runtime` | Допоміжні засоби Gateway | Клієнт Gateway і допоміжні засоби патчів статусу каналу | - | `plugin-sdk/config-runtime` | Допоміжні засоби конфігурації | Допоміжні засоби завантаження/запису конфігурації | - | `plugin-sdk/telegram-command-config` | Допоміжні засоби команд Telegram | Допоміжні засоби валідації команд Telegram зі стабільною резервною поведінкою, коли поверхня контракту вбудованого Telegram недоступна | - | `plugin-sdk/approval-runtime` | Допоміжні засоби запитів approval | Допоміжні засоби payload approval exec/Plugin, можливостей/профілів approval, нативної маршрутизації/runtime approval | - | `plugin-sdk/approval-auth-runtime` | Допоміжні засоби auth для approval | Визначення approver, auth дій у тому самому чаті | - | `plugin-sdk/approval-client-runtime` | Допоміжні засоби клієнта approval | Допоміжні засоби профілю/фільтра нативного approval exec | - | `plugin-sdk/approval-delivery-runtime` | Допоміжні засоби доставки approval | Адаптери нативних можливостей/доставки approval | - | `plugin-sdk/approval-gateway-runtime` | Допоміжні засоби Gateway для approval | Спільний допоміжний засіб визначення Gateway для approval | - | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні засоби адаптера approval | Полегшені допоміжні засоби завантаження адаптера нативного approval для гарячих точок входу каналів | - | `plugin-sdk/approval-handler-runtime` | Допоміжні засоби обробника approval | Ширші допоміжні засоби runtime обробника approval; надавайте перевагу вужчим швам adapter/gateway, коли їх достатньо | - | `plugin-sdk/approval-native-runtime` | Допоміжні засоби цілей approval | Допоміжні засоби прив’язки цілей/облікових записів нативного approval | - | `plugin-sdk/approval-reply-runtime` | Допоміжні засоби відповіді approval | Допоміжні засоби payload відповіді approval exec/Plugin | - | `plugin-sdk/channel-runtime-context` | Допоміжні засоби контексту runtime каналу | Загальні допоміжні засоби register/get/watch для контексту runtime каналу | - | `plugin-sdk/security-runtime` | Допоміжні засоби безпеки | Спільні допоміжні засоби довіри, DM gating, зовнішнього вмісту та збирання секретів | - | `plugin-sdk/ssrf-policy` | Допоміжні засоби політики SSRF | Допоміжні засоби allowlist хостів і політики приватної мережі | - | `plugin-sdk/ssrf-runtime` | Допоміжні засоби SSRF runtime | Допоміжні засоби pinned-dispatcher, guarded fetch, політики SSRF | - | `plugin-sdk/collection-runtime` | Допоміжні засоби обмеженого кешу | `pruneMapToMaxSize` | - | `plugin-sdk/diagnostic-runtime` | Допоміжні засоби контролю діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | - | `plugin-sdk/error-runtime` | Допоміжні засоби форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні засоби графа помилок | - | `plugin-sdk/fetch-runtime` | Допоміжні засоби обгорнутого fetch/proxy | `resolveFetch`, допоміжні засоби proxy | - | `plugin-sdk/host-runtime` | Допоміжні засоби нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | - | `plugin-sdk/retry-runtime` | Допоміжні засоби retry | `RetryConfig`, `retryAsync`, виконавці політик | + | `plugin-sdk/runtime` | Широкі допоміжні функції runtime | Допоміжні функції runtime/logging/backup/plugin-install | + | `plugin-sdk/runtime-env` | Вузькі допоміжні функції середовища runtime | Допоміжні функції logger/runtime env, timeout, retry і backoff | + | `plugin-sdk/plugin-runtime` | Спільні допоміжні функції runtime Plugin | Допоміжні функції команд/hook/http/interactive для Plugin | + | `plugin-sdk/hook-runtime` | Допоміжні функції конвеєра hook | Спільні допоміжні функції конвеєра webhook/internal hook | + | `plugin-sdk/lazy-runtime` | Допоміжні функції lazy runtime | `createLazyRuntimeModule`, `createLazyRuntimeMethod`, `createLazyRuntimeMethodBinder`, `createLazyRuntimeNamedExport`, `createLazyRuntimeSurface` | + | `plugin-sdk/process-runtime` | Допоміжні функції процесів | Спільні допоміжні функції exec | + | `plugin-sdk/cli-runtime` | Допоміжні функції runtime CLI | Форматування команд, очікування, допоміжні функції версій | + | `plugin-sdk/gateway-runtime` | Допоміжні функції Gateway | Допоміжні функції клієнта Gateway і patch стану каналів | + | `plugin-sdk/config-runtime` | Допоміжні функції конфігурації | Допоміжні функції завантаження/запису конфігурації | + | `plugin-sdk/telegram-command-config` | Допоміжні функції команд Telegram | Допоміжні функції перевірки команд Telegram зі стабільним резервним варіантом, коли поверхня контракту вбудованого Telegram недоступна | + | `plugin-sdk/approval-runtime` | Допоміжні функції запитів на підтвердження | Payload підтвердження exec/plugin, допоміжні функції capability/profile підтвердження, нативні допоміжні функції маршрутизації/runtime підтвердження | + | `plugin-sdk/approval-auth-runtime` | Допоміжні функції auth для підтвердження | Визначення користувача, що підтверджує, auth дій у тому самому чаті | + | `plugin-sdk/approval-client-runtime` | Допоміжні функції клієнта підтвердження | Допоміжні функції profile/filter для нативного підтвердження exec | + | `plugin-sdk/approval-delivery-runtime` | Допоміжні функції доставки підтверджень | Адаптери capability/delivery нативного підтвердження | + | `plugin-sdk/approval-gateway-runtime` | Допоміжні функції Gateway для підтвердження | Спільна допоміжна функція визначення approval gateway | + | `plugin-sdk/approval-handler-adapter-runtime` | Допоміжні функції адаптера підтвердження | Легковагові допоміжні функції завантаження адаптера нативного підтвердження для гарячих точок входу каналів | + | `plugin-sdk/approval-handler-runtime` | Допоміжні функції обробника підтвердження | Ширші допоміжні функції runtime обробника підтвердження; віддавайте перевагу вужчим adapter/gateway seams, коли їх достатньо | + | `plugin-sdk/approval-native-runtime` | Допоміжні функції цілей підтвердження | Допоміжні функції нативного зв’язування цілі/облікового запису підтвердження | + | `plugin-sdk/approval-reply-runtime` | Допоміжні функції відповіді на підтвердження | Допоміжні функції payload відповіді на підтвердження exec/plugin | + | `plugin-sdk/channel-runtime-context` | Допоміжні функції channel runtime-context | Загальні допоміжні функції register/get/watch для channel runtime-context | + | `plugin-sdk/security-runtime` | Допоміжні функції безпеки | Спільні допоміжні функції trust, обмеження DM, external-content і збирання секретів | + | `plugin-sdk/ssrf-policy` | Допоміжні функції політики SSRF | Допоміжні функції allowlist хостів і політики приватної мережі | + | `plugin-sdk/ssrf-runtime` | Допоміжні функції runtime SSRF | Допоміжні функції pinned-dispatcher, guarded fetch, політики SSRF | + | `plugin-sdk/collection-runtime` | Допоміжні функції обмеженого кешу | `pruneMapToMaxSize` | + | `plugin-sdk/diagnostic-runtime` | Допоміжні функції обмеження діагностики | `isDiagnosticFlagEnabled`, `isDiagnosticsEnabled` | + | `plugin-sdk/error-runtime` | Допоміжні функції форматування помилок | `formatUncaughtError`, `isApprovalNotFoundError`, допоміжні функції графа помилок | + | `plugin-sdk/fetch-runtime` | Допоміжні функції wrapped fetch/proxy | `resolveFetch`, допоміжні функції proxy | + | `plugin-sdk/host-runtime` | Допоміжні функції нормалізації хоста | `normalizeHostname`, `normalizeScpRemoteHost` | + | `plugin-sdk/retry-runtime` | Допоміжні функції retry | `RetryConfig`, `retryAsync`, запускальники політик | | `plugin-sdk/allow-from` | Форматування allowlist | `formatAllowFromLowercase` | - | `plugin-sdk/allowlist-resolution` | Відображення вхідних даних allowlist | `mapAllowlistResolutionInputs` | - | `plugin-sdk/command-auth` | Допоміжні засоби контролю команд і поверхні команд | `resolveControlCommandGate`, допоміжні засоби авторизації відправника, допоміжні засоби реєстру команд | - | `plugin-sdk/command-status` | Відображувачі стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | - | `plugin-sdk/secret-input` | Розбір секретного вводу | Допоміжні засоби секретного вводу | - | `plugin-sdk/webhook-ingress` | Допоміжні засоби запитів Webhook | Утиліти цілей Webhook | - | `plugin-sdk/webhook-request-guards` | Допоміжні засоби guards для тіла запиту Webhook | Допоміжні засоби читання/обмеження тіла запиту | - | `plugin-sdk/reply-runtime` | Спільний runtime відповідей | Вхідна диспетчеризація, Heartbeat, планувальник відповідей, chunking | - | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні засоби диспетчеризації відповідей | Фіналізація, диспетчеризація provider і допоміжні засоби міток розмов | - | `plugin-sdk/reply-history` | Допоміжні засоби історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | - | `plugin-sdk/reply-reference` | Планування посилань на відповіді | `createReplyReferencePlanner` | - | `plugin-sdk/reply-chunking` | Допоміжні засоби чанків відповідей | Допоміжні засоби чанкінгу тексту/markdown | - | `plugin-sdk/session-store-runtime` | Допоміжні засоби сховища сесій | Допоміжні засоби шляху сховища + updated-at | - | `plugin-sdk/state-paths` | Допоміжні засоби шляхів стану | Допоміжні засоби каталогів стану та 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 запиту | Витягання рядкових URL з вхідних даних, подібних до запиту | - | `plugin-sdk/run-command` | Допоміжні засоби команд із timeout | Виконавець команд із timeout і нормалізованими stdout/stderr | + | `plugin-sdk/allowlist-resolution` | Зіставлення вхідних даних allowlist | `mapAllowlistResolutionInputs` | + | `plugin-sdk/command-auth` | Обмеження команд і допоміжні функції поверхні команд | `resolveControlCommandGate`, допоміжні функції авторизації відправника, допоміжні функції реєстру команд | + | `plugin-sdk/command-status` | Рендерери стану/довідки команд | `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage` | + | `plugin-sdk/secret-input` | Розбір secret input | Допоміжні функції secret input | + | `plugin-sdk/webhook-ingress` | Допоміжні функції запитів Webhook | Утиліти цілі Webhook | + | `plugin-sdk/webhook-request-guards` | Допоміжні функції guard для тіла запиту Webhook | Допоміжні функції читання/обмеження тіла запиту | + | `plugin-sdk/reply-runtime` | Спільний runtime відповіді | Вхідний dispatch, Heartbeat, планувальник відповіді, розбиття на частини | + | `plugin-sdk/reply-dispatch-runtime` | Вузькі допоміжні функції dispatch відповіді | Фіналізація, dispatch provider і допоміжні функції міток розмов | + | `plugin-sdk/reply-history` | Допоміжні функції історії відповідей | `buildHistoryContext`, `buildPendingHistoryContextFromMap`, `recordPendingHistoryEntry`, `clearHistoryEntriesIfEnabled` | + | `plugin-sdk/reply-reference` | Планування посилань відповіді | `createReplyReferencePlanner` | + | `plugin-sdk/reply-chunking` | Допоміжні функції частин відповіді | Допоміжні функції розбиття тексту/markdown | + | `plugin-sdk/session-store-runtime` | Допоміжні функції сховища сесій | Допоміжні функції шляху сховища + updated-at | + | `plugin-sdk/state-paths` | Допоміжні функції шляхів стану | Допоміжні функції каталогів стану та OAuth | + | `plugin-sdk/routing` | Допоміжні функції маршрутизації/ключів сесій | `resolveAgentRoute`, `buildAgentSessionKey`, `resolveDefaultAgentBoundAccountId`, допоміжні функції нормалізації ключів сесій | + | `plugin-sdk/status-helpers` | Допоміжні функції стану каналів | Builder-и підсумків стану каналу/облікового запису, типові значення runtime-state, допоміжні функції метаданих проблем | + | `plugin-sdk/target-resolver-runtime` | Допоміжні функції визначення цілі | Спільні допоміжні функції target resolver | + | `plugin-sdk/string-normalization-runtime` | Допоміжні функції нормалізації рядків | Допоміжні функції нормалізації slug/рядків | + | `plugin-sdk/request-url` | Допоміжні функції URL-адрес запитів | Витягування рядкових URL-адрес із request-подібних вхідних даних | + | `plugin-sdk/run-command` | Допоміжні функції команд із таймером | Запускальник команд із таймером і нормалізованими stdout/stderr | | `plugin-sdk/param-readers` | Читачі параметрів | Загальні читачі параметрів інструментів/CLI | - | `plugin-sdk/tool-payload` | Витягання payload інструмента | Витягання нормалізованих payload з об’єктів результатів інструментів | - | `plugin-sdk/tool-send` | Витягання надсилання інструмента | Витягання канонічних полів цілі надсилання з аргументів інструмента | - | `plugin-sdk/temp-path` | Допоміжні засоби тимчасових шляхів | Спільні допоміжні засоби шляхів тимчасового завантаження | - | `plugin-sdk/logging-core` | Допоміжні засоби логування | Допоміжні засоби logger підсистем і редагування | - | `plugin-sdk/markdown-table-runtime` | Допоміжні засоби markdown-таблиць | Допоміжні засоби режиму markdown-таблиць | - | `plugin-sdk/reply-payload` | Типи payload відповідей | Типи payload відповідей | - | `plugin-sdk/provider-setup` | Кураторські допоміжні засоби налаштування локального/self-hosted provider | Допоміжні засоби виявлення/конфігурації self-hosted provider | - | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні засоби налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні засоби виявлення/конфігурації self-hosted provider | - | `plugin-sdk/provider-auth-runtime` | Допоміжні засоби auth runtime provider | Допоміжні засоби визначення API-ключа runtime | - | `plugin-sdk/provider-auth-api-key` | Допоміжні засоби налаштування API-ключа provider | Допоміжні засоби онбордингу/запису профілю API-ключа | - | `plugin-sdk/provider-auth-result` | Допоміжні засоби результату auth provider | Стандартний конструктор результату auth OAuth | - | `plugin-sdk/provider-auth-login` | Допоміжні засоби інтерактивного входу provider | Спільні допоміжні засоби інтерактивного входу | - | `plugin-sdk/provider-selection-runtime` | Допоміжні засоби вибору provider | Вибір налаштованого або автоматичного provider і злиття сирої конфігурації provider | - | `plugin-sdk/provider-env-vars` | Допоміжні засоби змінних середовища provider | Допоміжні засоби пошуку змінних середовища auth provider | - | `plugin-sdk/provider-model-shared` | Спільні допоміжні засоби моделей/повторного відтворення provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні конструктори політик replay, допоміжні засоби endpoint provider і нормалізації ідентифікаторів моделей | - | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні засоби каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | - | `plugin-sdk/provider-onboard` | Патчі онбордингу provider | Допоміжні засоби конфігурації онбордингу | - | `plugin-sdk/provider-http` | Допоміжні засоби HTTP provider | Загальні допоміжні засоби HTTP/можливостей endpoint provider, включно з допоміжними засобами multipart form для аудіотранскрипції | - | `plugin-sdk/provider-web-fetch` | Допоміжні засоби web-fetch provider | Допоміжні засоби реєстрації/кешу web-fetch provider | - | `plugin-sdk/provider-web-search-config-contract` | Допоміжні засоби конфігурації вебпошуку provider | Вузькі допоміжні засоби конфігурації/облікових даних вебпошуку для provider, яким не потрібне підключення ввімкнення Plugin | - | `plugin-sdk/provider-web-search-contract` | Допоміжні засоби контракту вебпошуку provider | Вузькі допоміжні засоби контракту конфігурації/облікових даних вебпошуку, як-от `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped-сетери/гетери облікових даних | - | `plugin-sdk/provider-web-search` | Допоміжні засоби вебпошуку provider | Допоміжні засоби реєстрації/кешу/runtime вебпошуку provider | - | `plugin-sdk/provider-tools` | Допоміжні засоби сумісності інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика та допоміжні засоби сумісності xAI, як-от `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | - | `plugin-sdk/provider-usage` | Допоміжні засоби використання provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні засоби використання provider | - | `plugin-sdk/provider-stream` | Допоміжні засоби обгорток потоків provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоків і спільні допоміжні засоби обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | - | `plugin-sdk/provider-transport-runtime` | Допоміжні засоби транспорту provider | Нативні допоміжні засоби транспорту provider, як-от guarded fetch, перетворення транспортних повідомлень і записувані потоки транспортних подій | + | `plugin-sdk/tool-payload` | Витягування payload інструмента | Витягування нормалізованих payload із об’єктів результату інструмента | + | `plugin-sdk/tool-send` | Витягування send інструмента | Витягування канонічних полів цілі send з аргументів інструмента | + | `plugin-sdk/temp-path` | Допоміжні функції тимчасових шляхів | Спільні допоміжні функції тимчасових шляхів для завантаження | + | `plugin-sdk/logging-core` | Допоміжні функції logging | Допоміжні функції logger підсистеми та редагування конфіденційних даних | + | `plugin-sdk/markdown-table-runtime` | Допоміжні функції таблиць Markdown | Допоміжні функції режиму таблиць Markdown | + | `plugin-sdk/reply-payload` | Типи reply повідомлень | Типи payload відповіді | + | `plugin-sdk/provider-setup` | Кураторські допоміжні функції налаштування локального/self-hosted provider | Допоміжні функції виявлення/конфігурації self-hosted provider | + | `plugin-sdk/self-hosted-provider-setup` | Цільові допоміжні функції налаштування self-hosted provider, сумісного з OpenAI | Ті самі допоміжні функції виявлення/конфігурації self-hosted provider | + | `plugin-sdk/provider-auth-runtime` | Допоміжні функції runtime auth для provider | Допоміжні функції визначення API-ключа під час виконання | + | `plugin-sdk/provider-auth-api-key` | Допоміжні функції налаштування API-ключа provider | Допоміжні функції onboarding/запису profile для API-ключа | + | `plugin-sdk/provider-auth-result` | Допоміжні функції auth-result для provider | Стандартний builder auth-result OAuth | + | `plugin-sdk/provider-auth-login` | Допоміжні функції інтерактивного входу provider | Спільні допоміжні функції інтерактивного входу | + | `plugin-sdk/provider-selection-runtime` | Допоміжні функції вибору provider | Вибір provider за конфігурацією або автоматично та злиття сирої конфігурації provider | + | `plugin-sdk/provider-env-vars` | Допоміжні функції env var для provider | Допоміжні функції пошуку env var auth для provider | + | `plugin-sdk/provider-model-shared` | Спільні допоміжні функції моделей/replay provider | `ProviderReplayFamily`, `buildProviderReplayFamilyHooks`, `normalizeModelCompat`, спільні builder-и політики replay, допоміжні функції endpoint provider і нормалізації model-id | + | `plugin-sdk/provider-catalog-shared` | Спільні допоміжні функції каталогу provider | `findCatalogTemplate`, `buildSingleProviderApiKeyCatalog`, `supportsNativeStreamingUsageCompat`, `applyProviderNativeStreamingUsageCompat` | + | `plugin-sdk/provider-onboard` | Патчі onboarding для provider | Допоміжні функції конфігурації onboarding | + | `plugin-sdk/provider-http` | Допоміжні функції HTTP для provider | Загальні допоміжні функції HTTP/можливостей endpoint для provider, включно з допоміжними функціями multipart form для транскрибування аудіо | + | `plugin-sdk/provider-web-fetch` | Допоміжні функції web-fetch для provider | Допоміжні функції реєстрації/кешу provider web-fetch | + | `plugin-sdk/provider-web-search-config-contract` | Допоміжні функції конфігурації web-search для provider | Вузькі допоміжні функції конфігурації/облікових даних web-search для provider, яким не потрібна прив’язка вмикання Plugin | + | `plugin-sdk/provider-web-search-contract` | Допоміжні функції контракту web-search для provider | Вузькі допоміжні функції контракту конфігурації/облікових даних web-search, такі як `createWebSearchProviderContractFields`, `enablePluginInConfig`, `resolveProviderWebSearchPluginConfig` і scoped setter/getter-и облікових даних | + | `plugin-sdk/provider-web-search` | Допоміжні функції web-search для provider | Допоміжні функції реєстрації/кешу/runtime для provider web-search | + | `plugin-sdk/provider-tools` | Допоміжні функції сумісності інструментів/схем provider | `ProviderToolCompatFamily`, `buildProviderToolCompatFamilyHooks`, очищення схеми Gemini + діагностика, а також допоміжні функції сумісності xAI, такі як `resolveXaiModelCompatPatch` / `applyXaiModelCompat` | + | `plugin-sdk/provider-usage` | Допоміжні функції usage для provider | `fetchClaudeUsage`, `fetchGeminiUsage`, `fetchGithubCopilotUsage` та інші допоміжні функції usage для provider | + | `plugin-sdk/provider-stream` | Допоміжні функції обгорток потоку provider | `ProviderStreamFamily`, `buildProviderStreamFamilyHooks`, `composeProviderStreamWrappers`, типи обгорток потоку та спільні допоміжні функції обгорток Anthropic/Bedrock/Google/Kilocode/Moonshot/OpenAI/OpenRouter/Z.A.I/MiniMax/Copilot | + | `plugin-sdk/provider-transport-runtime` | Допоміжні функції транспорту provider | Нативні допоміжні функції транспорту provider, такі як guarded fetch, перетворення транспортних повідомлень і потоки подій writable transport | | `plugin-sdk/keyed-async-queue` | Упорядкована асинхронна черга | `KeyedAsyncQueue` | - | `plugin-sdk/media-runtime` | Спільні допоміжні засоби медіа | Допоміжні засоби отримання/перетворення/зберігання медіа, а також конструктори payload медіа | - | `plugin-sdk/media-generation-runtime` | Спільні допоміжні засоби генерації медіа | Спільні допоміжні засоби failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | - | `plugin-sdk/media-understanding` | Допоміжні засоби розуміння медіа | Типи provider для розуміння медіа, а також експорти допоміжних засобів зображень/аудіо для provider | - | `plugin-sdk/text-runtime` | Спільні допоміжні засоби тексту | Видалення видимого для асистента тексту, допоміжні засоби рендерингу/chunking/table markdown, допоміжні засоби редагування, допоміжні засоби тегів директив, утиліти безпечного тексту та пов’язані допоміжні засоби тексту/логування | - | `plugin-sdk/text-chunking` | Допоміжні засоби чанкінгу тексту | Допоміжний засіб чанкінгу вихідного тексту | - | `plugin-sdk/speech` | Допоміжні засоби мовлення | Типи provider мовлення, а також допоміжні засоби директив, реєстру та валідації для provider | + | `plugin-sdk/media-runtime` | Спільні допоміжні функції медіа | Допоміжні функції отримання/перетворення/збереження медіа плюс builder-и media payload | + | `plugin-sdk/media-generation-runtime` | Спільні допоміжні функції генерації медіа | Спільні допоміжні функції failover, вибору кандидатів і повідомлень про відсутню модель для генерації зображень/відео/музики | + | `plugin-sdk/media-understanding` | Допоміжні функції розуміння медіа | Типи provider для розуміння медіа плюс експорти допоміжних функцій зображень/аудіо для provider | + | `plugin-sdk/text-runtime` | Спільні допоміжні функції тексту | Вилучення видимого асистенту тексту, допоміжні функції рендерингу/розбиття/таблиць markdown, редагування конфіденційних даних, допоміжні функції тегів директив, утиліти безпечного тексту та пов’язані допоміжні функції тексту/logging | + | `plugin-sdk/text-chunking` | Допоміжні функції розбиття тексту | Допоміжна функція розбиття вихідного тексту | + | `plugin-sdk/speech` | Допоміжні функції мовлення | Типи provider мовлення плюс допоміжні функції директив, реєстру та перевірки для provider | | `plugin-sdk/speech-core` | Спільне ядро мовлення | Типи provider мовлення, реєстр, директиви, нормалізація | - | `plugin-sdk/realtime-transcription` | Допоміжні засоби транскрипції в realtime | Типи provider, допоміжні засоби реєстру та спільний допоміжний засіб сесії WebSocket | - | `plugin-sdk/realtime-voice` | Допоміжні засоби голосу в realtime | Типи provider, допоміжні засоби реєстру/визначення та допоміжні засоби bridge-сесій | - | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, failover, auth і допоміжні засоби реєстру | - | `plugin-sdk/music-generation` | Допоміжні засоби генерації музики | Типи provider/запитів/результатів генерації музики | - | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні засоби failover, пошук provider і розбір model-ref | - | `plugin-sdk/video-generation` | Допоміжні засоби генерації відео | Типи provider/запитів/результатів генерації відео | - | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні засоби failover, пошук provider і розбір model-ref | - | `plugin-sdk/interactive-runtime` | Допоміжні засоби інтерактивних відповідей | Нормалізація/зведення payload інтерактивних відповідей | + | `plugin-sdk/realtime-transcription` | Допоміжні функції транскрибування в реальному часі | Типи provider, допоміжні функції реєстру та спільна допоміжна функція сесії WebSocket | + | `plugin-sdk/realtime-voice` | Допоміжні функції голосу в реальному часі | Типи provider, допоміжні функції реєстру/визначення та допоміжні функції bridge session | + | `plugin-sdk/image-generation-core` | Спільне ядро генерації зображень | Типи генерації зображень, допоміжні функції failover, auth і реєстру | + | `plugin-sdk/music-generation` | Допоміжні функції генерації музики | Типи provider/запитів/результатів генерації музики | + | `plugin-sdk/music-generation-core` | Спільне ядро генерації музики | Типи генерації музики, допоміжні функції failover, пошук provider і розбір model-ref | + | `plugin-sdk/video-generation` | Допоміжні функції генерації відео | Типи provider/запитів/результатів генерації відео | + | `plugin-sdk/video-generation-core` | Спільне ядро генерації відео | Типи генерації відео, допоміжні функції failover, пошук provider і розбір model-ref | + | `plugin-sdk/interactive-runtime` | Допоміжні функції інтерактивних відповідей | Нормалізація/зменшення payload інтерактивних відповідей | | `plugin-sdk/channel-config-primitives` | Примітиви конфігурації каналу | Вузькі примітиви config-schema каналу | - | `plugin-sdk/channel-config-writes` | Допоміжні засоби запису конфігурації каналу | Допоміжні засоби авторизації запису конфігурації каналу | - | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude Plugin каналу | - | `plugin-sdk/channel-status` | Допоміжні засоби статусу каналу | Спільні допоміжні засоби snapshot/summary статусу каналу | - | `plugin-sdk/allowlist-config-edit` | Допоміжні засоби конфігурації allowlist | Допоміжні засоби редагування/читання конфігурації allowlist | - | `plugin-sdk/group-access` | Допоміжні засоби доступу до груп | Спільні допоміжні засоби рішень щодо доступу до груп | - | `plugin-sdk/direct-dm` | Допоміжні засоби прямих DM | Спільні допоміжні засоби auth/guard для прямих DM | - | `plugin-sdk/extension-shared` | Спільні допоміжні засоби extension | Примітиви допоміжних засобів пасивного каналу/статусу та ambient proxy | - | `plugin-sdk/webhook-targets` | Допоміжні засоби цілей Webhook | Допоміжні засоби реєстру цілей Webhook та встановлення маршрутів | - | `plugin-sdk/webhook-path` | Допоміжні засоби шляхів Webhook | Допоміжні засоби нормалізації шляхів Webhook | - | `plugin-sdk/web-media` | Спільні допоміжні засоби вебмедіа | Допоміжні засоби завантаження віддаленого/локального медіа | - | `plugin-sdk/zod` | Повторний експорт zod | Повторно експортований `zod` для споживачів Plugin SDK | - | `plugin-sdk/memory-core` | Допоміжні засоби вбудованого memory-core | Поверхня допоміжних засобів менеджера/config/файлів/CLI пам’яті | + | `plugin-sdk/channel-config-writes` | Допоміжні функції запису конфігурації каналу | Допоміжні функції авторизації запису конфігурації каналу | + | `plugin-sdk/channel-plugin-common` | Спільний prelude каналу | Експорти спільного prelude channel plugin | + | `plugin-sdk/channel-status` | Допоміжні функції стану каналу | Спільні допоміжні функції snapshot/summary стану каналу | + | `plugin-sdk/allowlist-config-edit` | Допоміжні функції конфігурації allowlist | Допоміжні функції редагування/читання конфігурації allowlist | + | `plugin-sdk/group-access` | Допоміжні функції доступу до груп | Спільні допоміжні функції ухвалення рішень щодо доступу до груп | + | `plugin-sdk/direct-dm` | Допоміжні функції прямих DM | Спільні допоміжні функції auth/guard для прямих DM | + | `plugin-sdk/extension-shared` | Спільні допоміжні функції extension | Примітиви допоміжних функцій passive-channel/status і ambient proxy | + | `plugin-sdk/webhook-targets` | Допоміжні функції цілей Webhook | Реєстр цілей Webhook і допоміжні функції встановлення маршрутів | + | `plugin-sdk/webhook-path` | Допоміжні функції шляху Webhook | Допоміжні функції нормалізації шляху Webhook | + | `plugin-sdk/web-media` | Спільні допоміжні функції вебмедіа | Допоміжні функції завантаження віддалених/локальних медіа | + | `plugin-sdk/zod` | Повторний експорт Zod | Повторно експортований `zod` для користувачів SDK Plugin | + | `plugin-sdk/memory-core` | Вбудовані допоміжні функції memory-core | Поверхня допоміжних функцій memory manager/config/file/CLI | | `plugin-sdk/memory-core-engine-runtime` | Фасад runtime рушія пам’яті | Фасад runtime індексу/пошуку пам’яті | - | `plugin-sdk/memory-core-host-engine-foundation` | Foundation engine хоста пам’яті | Експорти foundation engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-embeddings` | Embedding engine хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і загальні допоміжні засоби batch/remote; конкретні remote provider містяться у Plugin, яким вони належать | - | `plugin-sdk/memory-core-host-engine-qmd` | QMD engine хоста пам’яті | Експорти QMD engine хоста пам’яті | - | `plugin-sdk/memory-core-host-engine-storage` | Storage engine хоста пам’яті | Експорти storage engine хоста пам’яті | - | `plugin-sdk/memory-core-host-multimodal` | Допоміжні засоби мультимодального хоста пам’яті | Допоміжні засоби мультимодального хоста пам’яті | - | `plugin-sdk/memory-core-host-query` | Допоміжні засоби запитів хоста пам’яті | Допоміжні засоби запитів хоста пам’яті | - | `plugin-sdk/memory-core-host-secret` | Допоміжні засоби секретів хоста пам’яті | Допоміжні засоби секретів хоста пам’яті | - | `plugin-sdk/memory-core-host-events` | Допоміжні засоби журналу подій хоста пам’яті | Допоміжні засоби журналу подій хоста пам’яті | - | `plugin-sdk/memory-core-host-status` | Допоміжні засоби статусу хоста пам’яті | Допоміжні засоби статусу хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-cli` | CLI runtime хоста пам’яті | Допоміжні засоби CLI runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні засоби core runtime хоста пам’яті | - | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні засоби файлів/runtime хоста пам’яті | Допоміжні засоби файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів core runtime хоста пам’яті | - | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів журналу подій хоста пам’яті | - | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів файлів/runtime хоста пам’яті | - | `plugin-sdk/memory-host-markdown` | Допоміжні засоби керованого markdown | Спільні допоміжні засоби керованого markdown для Plugin, суміжних із пам’яттю | + | `plugin-sdk/memory-core-host-engine-foundation` | Рушій foundation хоста пам’яті | Експорти рушія foundation хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-embeddings` | Рушій embedding хоста пам’яті | Контракти embedding пам’яті, доступ до реєстру, локальний provider і загальні допоміжні функції batch/remote; конкретні remote provider містяться у Plugin-власниках | + | `plugin-sdk/memory-core-host-engine-qmd` | Рушій QMD хоста пам’яті | Експорти рушія QMD хоста пам’яті | + | `plugin-sdk/memory-core-host-engine-storage` | Рушій storage хоста пам’яті | Експорти рушія storage хоста пам’яті | + | `plugin-sdk/memory-core-host-multimodal` | Допоміжні функції multimodal хоста пам’яті | Допоміжні функції multimodal хоста пам’яті | + | `plugin-sdk/memory-core-host-query` | Допоміжні функції запитів хоста пам’яті | Допоміжні функції запитів хоста пам’яті | + | `plugin-sdk/memory-core-host-secret` | Допоміжні функції секретів хоста пам’яті | Допоміжні функції секретів хоста пам’яті | + | `plugin-sdk/memory-core-host-events` | Допоміжні функції журналу подій хоста пам’яті | Допоміжні функції журналу подій хоста пам’яті | + | `plugin-sdk/memory-core-host-status` | Допоміжні функції стану хоста пам’яті | Допоміжні функції стану хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-cli` | Runtime CLI хоста пам’яті | Допоміжні функції runtime CLI хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-core` | Core runtime хоста пам’яті | Допоміжні функції core runtime хоста пам’яті | + | `plugin-sdk/memory-core-host-runtime-files` | Допоміжні функції файлів/runtime хоста пам’яті | Допоміжні функції файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-core` | Псевдонім core runtime хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій core runtime хоста пам’яті | + | `plugin-sdk/memory-host-events` | Псевдонім журналу подій хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій журналу подій хоста пам’яті | + | `plugin-sdk/memory-host-files` | Псевдонім файлів/runtime хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій файлів/runtime хоста пам’яті | + | `plugin-sdk/memory-host-markdown` | Допоміжні функції керованого markdown | Спільні допоміжні функції керованого markdown для Plugin, суміжних із пам’яттю | | `plugin-sdk/memory-host-search` | Фасад пошуку Active Memory | Лінивий фасад runtime менеджера пошуку active-memory | - | `plugin-sdk/memory-host-status` | Псевдонім статусу хоста пам’яті | Нейтральний до вендора псевдонім для допоміжних засобів статусу хоста пам’яті | - | `plugin-sdk/memory-lancedb` | Допоміжні засоби вбудованого memory-lancedb | Поверхня допоміжних засобів memory-lancedb | - | `plugin-sdk/testing` | Тестові утиліти | Допоміжні засоби тестування та mocks | + | `plugin-sdk/memory-host-status` | Псевдонім стану хоста пам’яті | Нейтральний щодо вендора псевдонім для допоміжних функцій стану хоста пам’яті | + | `plugin-sdk/memory-lancedb` | Вбудовані допоміжні функції memory-lancedb | Поверхня допоміжних функцій memory-lancedb | + | `plugin-sdk/testing` | Тестові утиліти | Допоміжні функції та mock-и для тестування | -Ця таблиця навмисно є поширеною підмножиною для міграції, а не повною поверхнею SDK. Повний список із понад 200 точок входу міститься в +Ця таблиця навмисно містить поширену підмножину для міграції, а не всю поверхню +SDK. Повний список із понад 200 точок входу міститься в `scripts/lib/plugin-sdk-entrypoints.json`. -Цей список усе ще містить деякі шви допоміжних засобів вбудованих Plugin, як-от +Цей список усе ще включає деякі допоміжні seams для вбудованих Plugin, такі як `plugin-sdk/feishu`, `plugin-sdk/feishu-setup`, `plugin-sdk/zalo`, -`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони й надалі експортуються для -підтримки та сумісності вбудованих Plugin, але навмисно не включені до -поширеної таблиці міграції та не є рекомендованою ціллю для нового коду Plugin. +`plugin-sdk/zalo-setup` і `plugin-sdk/matrix*`. Вони залишаються експортованими для +підтримки та сумісності вбудованих Plugin, але навмисно +опущені з таблиці поширеної міграції й не є рекомендованою ціллю для +нового коду Plugin. -Те саме правило застосовується й до інших сімейств вбудованих допоміжних засобів, таких як: +Те саме правило застосовується до інших сімейств вбудованих допоміжних функцій, таких як: -- допоміжні засоби підтримки браузера: `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` +- допоміжні функції підтримки браузера: `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` - Matrix: `plugin-sdk/matrix*` - LINE: `plugin-sdk/line*` - IRC: `plugin-sdk/irc*` -- поверхні вбудованих допоміжних засобів/Plugin, такі як `plugin-sdk/googlechat`, +- поверхні вбудованих допоміжних функцій/Plugin, такі як `plugin-sdk/googlechat`, `plugin-sdk/zalouser`, `plugin-sdk/bluebubbles*`, `plugin-sdk/mattermost*`, `plugin-sdk/msteams`, `plugin-sdk/nextcloud-talk`, `plugin-sdk/nostr`, `plugin-sdk/tlon`, @@ -393,7 +431,7 @@ OpenClaw не видаляє й не переосмислює задокумен `plugin-sdk/diagnostics-otel`, `plugin-sdk/diffs`, `plugin-sdk/llm-task`, `plugin-sdk/thread-ownership` і `plugin-sdk/voice-call` -`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних засобів токена: +`plugin-sdk/github-copilot-token` наразі надає вузьку поверхню допоміжних функцій токенів `DEFAULT_COPILOT_API_BASE_URL`, `deriveCopilotApiBaseUrlFromToken` і `resolveCopilotApiToken`. @@ -402,18 +440,18 @@ OpenClaw не видаляє й не переосмислює задокумен ## Активні застарівання -Вужчі застарівання, які застосовуються в усьому Plugin SDK, контракті provider, -поверхні runtime і маніфесті. Кожен із них іще працює сьогодні, але буде видалений -у майбутньому мажорному релізі. Запис під кожним елементом зіставляє старий API з його +Вужчі застарівання, які застосовуються в SDK Plugin, контракті provider, +поверхні runtime і manifest. Кожне з них усе ще працює сьогодні, але буде видалене +в одному з майбутніх мажорних випусків. Запис під кожним елементом зіставляє старий API з його канонічною заміною. - + **Старе (`openclaw/plugin-sdk/command-auth`)**: `buildCommandsMessage`, `buildCommandsMessagePaginated`, `buildHelpMessage`. **Нове (`openclaw/plugin-sdk/command-status`)**: ті самі сигнатури, ті самі - експорти — лише імпортовані з вужчого підшляху. `command-auth` + експорти — просто імпортуються з вужчого підшляху. `command-auth` повторно експортує їх як compat-заглушки. ```typescript @@ -426,96 +464,97 @@ OpenClaw не видаляє й не переосмислює задокумен - + **Старе**: `resolveInboundMentionRequirement({ facts, policy })` і `shouldDropInboundForMention(...)` з `openclaw/plugin-sdk/channel-inbound` або `openclaw/plugin-sdk/channel-mention-gating`. **Нове**: `resolveInboundMentionDecision({ facts, policy })` — повертає - єдиний об’єкт рішення замість двох розділених викликів. + один об’єкт рішення замість двох розділених викликів. - Низхідні Plugin каналів (Slack, Discord, Matrix, MS Teams) уже - перейшли на це. + Downstream channel Plugin (Slack, Discord, Matrix, Microsoft Teams) уже + перейшли. - + `openclaw/plugin-sdk/channel-runtime` — це shim сумісності для старіших - Plugin каналів. Не імпортуйте його в новому коді; використовуйте - `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів - runtime. + channel Plugin. Не імпортуйте його в новому коді; використовуйте + `openclaw/plugin-sdk/channel-runtime-context` для реєстрації об’єктів runtime. - Допоміжні засоби `channelActions*` у `openclaw/plugin-sdk/channel-actions` застаріли - разом із сирими експортами дій каналу. Натомість надавайте можливості через - семантичну поверхню `presentation` — Plugin каналів оголошують, що саме вони рендерять - (картки, кнопки, списки вибору), а не які сирі назви дій вони приймають. + Допоміжні функції `channelActions*` в `openclaw/plugin-sdk/channel-actions` + застарівають разом із сирими експортами channel "actions". Натомість показуйте можливості + через семантичну поверхню `presentation` — channel Plugin оголошують, що саме вони + відображають (картки, кнопки, списки вибору), а не те, які сирі назви + дій вони приймають. - + **Старе**: фабрика `tool()` з `openclaw/plugin-sdk/provider-web-search`. **Нове**: реалізуйте `createTool(...)` безпосередньо в Plugin provider. - OpenClaw більше не потрібен допоміжний засіб SDK для реєстрації обгортки інструмента. + OpenClaw більше не потребує допоміжної функції SDK для реєстрації обгортки інструмента. - + **Старе**: `formatInboundEnvelope(...)` (і - `ChannelMessageForAgent.channelEnvelope`) для побудови плоского текстового prompt-envelope - із вхідних повідомлень каналу. + `ChannelMessageForAgent.channelEnvelope`) для побудови плоского plaintext prompt + envelope із вхідних channel-повідомлень. - **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Plugin - каналів прикріплюють метадані маршрутизації (потік, тему, reply-to, реакції) як - типізовані поля замість конкатенації їх у рядок prompt. Допоміжний засіб - `formatAgentEnvelope(...)` і далі підтримується для синтезованих envelope, - орієнтованих на асистента, але вхідні текстові envelope поступово виводяться з ужитку. + **Нове**: `BodyForAgent` плюс структуровані блоки контексту користувача. Channel + Plugin додають метадані маршрутизації (гілка, тема, reply-to, реакції) як + типізовані поля замість конкатенації їх у рядок prompt. Допоміжна функція + `formatAgentEnvelope(...)` усе ще підтримується для синтезованих + envelope, видимих асистенту, але вхідні plaintext envelope поступово + виводяться з ужитку. - Зачеплені області: `inbound_claim`, `message_received` і будь-який користувацький - Plugin каналу, який постобробляв текст `channelEnvelope`. + Зачеплені області: `inbound_claim`, `message_received` і будь-який власний + channel Plugin, який постобробляв текст `channelEnvelope`. - - Чотири псевдоніми типів виявлення тепер є тонкими обгортками над типами - ери каталогу: + + Чотири псевдоніми типів discovery тепер є тонкими обгортками над типами + епохи каталогу: - | Старий псевдонім | Новий тип | - | --------------------------- | ------------------------- | - | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | - | `ProviderDiscoveryContext` | `ProviderCatalogContext` | - | `ProviderDiscoveryResult` | `ProviderCatalogResult` | - | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | + | Старий псевдонім | Новий тип | + | -------------------------- | ----------------------- | + | `ProviderDiscoveryOrder` | `ProviderCatalogOrder` | + | `ProviderDiscoveryContext` | `ProviderCatalogContext`| + | `ProviderDiscoveryResult` | `ProviderCatalogResult` | + | `ProviderPluginDiscovery` | `ProviderPluginCatalog` | Плюс застарілий статичний набір `ProviderCapabilities` — Plugin provider - повинні прикріплювати факти можливостей через контракт runtime provider, + мають прикріплювати capability facts через контракт runtime provider, а не через статичний об’єкт. - - **Старе** (три окремі хуки в `ProviderThinkingPolicy`): + + **Старе** (три окремі hook на `ProviderThinkingPolicy`): `isBinaryThinking(ctx)`, `supportsXHighThinking(ctx)` і `resolveDefaultThinkingLevel(ctx)`. **Нове**: один `resolveThinkingProfile(ctx)`, який повертає - `ProviderThinkingProfile` з канонічним `id`, необов’язковим `label` і + `ProviderThinkingProfile` із канонічним `id`, необов’язковим `label` і ранжованим списком рівнів. OpenClaw автоматично знижує застарілі збережені значення за рангом профілю. - Реалізуйте один хук замість трьох. Застарілі хуки продовжують працювати впродовж - вікна застарівання, але не комбінуються з результатом профілю. + Реалізуйте один hook замість трьох. Застарілі hook продовжують працювати протягом + періоду застарівання, але не поєднуються з результатом профілю. - + **Старе**: реалізація `resolveExternalOAuthProfiles(...)` без - оголошення provider у маніфесті Plugin. + оголошення provider у manifest Plugin. - **Нове**: оголосіть `contracts.externalAuthProviders` у маніфесті Plugin - **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях - «резервного auth» видає попередження під час виконання й буде видалений. + **Нове**: оголосіть `contracts.externalAuthProviders` у manifest Plugin + **і** реалізуйте `resolveExternalAuthProfiles(...)`. Старий шлях "auth + fallback" виводить попередження під час виконання й буде видалений. ```json { @@ -527,41 +566,41 @@ OpenClaw не видаляє й не переосмислює задокумен - - **Старе** поле маніфесту: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. + + **Старе** поле manifest: `providerAuthEnvVars: { anthropic: ["ANTHROPIC_API_KEY"] }`. - **Нове**: віддзеркальте той самий пошук env vars у `setup.providers[].envVars` - в маніфесті. Це об’єднує метадані env налаштування/статусу в одному - місці й дозволяє уникнути запуску runtime Plugin лише для того, щоб відповісти на - запити щодо env vars. + **Нове**: продублюйте той самий пошук env var у `setup.providers[].envVars` + в manifest. Це об’єднує метадані env налаштування/стану в одному + місці й дозволяє уникнути запуску runtime Plugin лише для відповіді на + запити пошуку env var. - `providerAuthEnvVars` і далі підтримується через адаптер сумісності - до завершення вікна застарівання. + `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності + до завершення періоду застарівання. - + **Старе**: три окремі виклики — `api.registerMemoryPromptSection(...)`, `api.registerMemoryFlushPlan(...)`, `api.registerMemoryRuntime(...)`. - **Нове**: один виклик у API стану пам’яті — + **Нове**: один виклик до API memory-state — `registerMemoryCapability(pluginId, { promptBuilder, flushPlanResolver, runtime })`. - Ті самі слоти, один виклик реєстрації. Адитивні допоміжні засоби пам’яті + Ті самі слоти, один виклик реєстрації. Додаткові допоміжні функції memory (`registerMemoryPromptSupplement`, `registerMemoryCorpusSupplement`, - `registerMemoryEmbeddingProvider`) це не зачіпає. + `registerMemoryEmbeddingProvider`) не зачеплені. - - Два застарілі псевдоніми типів і далі експортуються з `src/plugins/runtime/types.ts`: + + Два застарілі псевдоніми типів усе ще експортуються з `src/plugins/runtime/types.ts`: - | Старе | Нове | - | ---------------------------- | ------------------------------- | - | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | - | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | + | Старе | Нове | + | --------------------------- | ------------------------------ | + | `SubagentReadSessionParams` | `SubagentGetSessionMessagesParams` | + | `SubagentReadSessionResult` | `SubagentGetSessionMessagesResult` | Метод runtime `readSession` застарів на користь `getSessionMessages`. Та сама сигнатура; старий метод викликає @@ -570,10 +609,10 @@ OpenClaw не видаляє й не переосмислює задокумен - **Старе**: `runtime.tasks.flow` (в однині) повертав засіб доступу до live TaskFlow. + **Старе**: `runtime.tasks.flow` (в однині) повертав accessor живого TaskFlow. **Нове**: `runtime.tasks.flows` (у множині) повертає доступ до TaskFlow на основі DTO, - який безпечний для імпорту й не потребує завантаження повного runtime завдань. + який безпечний для імпорту та не вимагає завантаження повного runtime завдань. ```typescript // Before @@ -584,17 +623,17 @@ OpenClaw не видаляє й не переосмислює задокумен - - Розглянуто вище в розділі «Як мігрувати → Мігруйте розширення результатів інструментів Pi на - middleware». Тут наведено для повноти: шлях лише для Pi + + Розглянуто вище в розділі "Як виконати міграцію → Мігруйте розширення Pi tool-result на + middleware". Додано тут для повноти: шлях лише для Pi `api.registerEmbeddedExtensionFactory(...)` застарів на користь - `api.registerAgentToolResultMiddleware(...)` з явним списком harness - у `contracts.agentToolResultMiddleware`. + `api.registerAgentToolResultMiddleware(...)` з явним списком runtime в + `contracts.agentToolResultMiddleware`. - `OpenClawSchemaType`, повторно експортований з `openclaw/plugin-sdk`, тепер є - однорядковим псевдонімом для `OpenClawConfig`. Надавайте перевагу канонічній назві. + `OpenClawSchemaType`, повторно експортований із `openclaw/plugin-sdk`, тепер є + однорядковим псевдонімом для `OpenClawConfig`. Віддавайте перевагу канонічній назві. ```typescript // Before @@ -607,11 +646,11 @@ OpenClaw не видаляє й не переосмислює задокумен -Застарівання на рівні extension (усередині вбудованих Plugin каналів/provider у -`extensions/`) відстежуються у власних barrel-файлах `api.ts` і `runtime-api.ts`. +Застарівання на рівні extension (усередині вбудованих channel/provider Plugin у +`extensions/`) відстежуються у власних barrels `api.ts` і `runtime-api.ts`. Вони не впливають на контракти сторонніх Plugin і тут не перелічені. -Якщо ви напряму споживаєте локальний barrel вбудованого Plugin, прочитайте -коментарі щодо застарівання в цьому barrel перед оновленням. +Якщо ви споживаєте локальний barrel вбудованого Plugin напряму, прочитайте +коментарі про застарівання в цьому barrel перед оновленням. ## Часова шкала видалення @@ -619,12 +658,12 @@ OpenClaw не видаляє й не переосмислює задокумен | Коли | Що відбувається | | ---------------------- | ---------------------------------------------------------------------- | | **Зараз** | Застарілі поверхні виводять попередження під час виконання | -| **Наступний мажорний реліз** | Застарілі поверхні буде видалено; Plugin, які досі їх використовують, перестануть працювати | +| **Наступний мажорний випуск** | Застарілі поверхні буде видалено; Plugin, які все ще їх використовують, перестануть працювати | -Усі core Plugin уже мігровано. Зовнішнім Plugin слід виконати -міграцію до наступного мажорного релізу. +Усі core Plugin уже мігровані. Зовнішні Plugin мають виконати міграцію +до наступного мажорного випуску. -## Тимчасове приглушення попереджень +## Тимчасове придушення попереджень Установіть ці змінні середовища, поки працюєте над міграцією: @@ -633,13 +672,13 @@ OPENCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 openclaw gateway run OPENCLAW_SUPPRESS_EXTENSION_API_WARNING=1 openclaw gateway run ``` -Це тимчасовий обхідний механізм, а не постійне рішення. +Це тимчасовий обхідний шлях, а не постійне рішення. ## Пов’язане -- [Початок роботи](/uk/plugins/building-plugins) — створіть свій перший Plugin +- [Початок роботи](/uk/plugins/building-plugins) — створення вашого першого Plugin - [Огляд SDK](/uk/plugins/sdk-overview) — повний довідник імпортів підшляхів -- [Plugin каналів](/uk/plugins/sdk-channel-plugins) — створення Plugin каналів -- [Plugin provider](/uk/plugins/sdk-provider-plugins) — створення Plugin provider -- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибоке занурення в архітектуру -- [Маніфест Plugin](/uk/plugins/manifest) — довідник схеми маніфесту +- [Channel Plugin](/uk/plugins/sdk-channel-plugins) — створення channel Plugin +- [Provider Plugin](/uk/plugins/sdk-provider-plugins) — створення provider Plugin +- [Внутрішня будова Plugin](/uk/plugins/architecture) — глибокий огляд архітектури +- [Manifest Plugin](/uk/plugins/manifest) — довідник зі схеми manifest diff --git a/docs/uk/plugins/sdk-overview.md b/docs/uk/plugins/sdk-overview.md index a0c29b167..9300bd5a6 100644 --- a/docs/uk/plugins/sdk-overview.md +++ b/docs/uk/plugins/sdk-overview.md @@ -1,33 +1,33 @@ --- read_when: - - Потрібно знати, з якого підшляху SDK імпортувати - - Потрібен довідник для всіх методів реєстрації в OpenClawPluginApi + - Вам потрібно знати, з якого підшляху SDK імпортувати + - Вам потрібен довідник для всіх методів реєстрації в OpenClawPluginApi - Ви шукаєте конкретний експорт SDK sidebarTitle: SDK overview -summary: Карта імпорту, довідник з API реєстрації та архітектура SDK -title: Огляд Plugin SDK +summary: Карта імпорту, довідник API реєстрації та архітектура SDK +title: Огляд SDK Plugin x-i18n: - generated_at: "2026-04-24T20:32:17Z" + generated_at: "2026-04-25T00:02:50Z" model: gpt-5.4 provider: openai - source_hash: 7b7b69a59c39d3abd5c70a1420e2f43da0470f66d283d76f069b0e77a5bf1551 + source_hash: ac8b101bc7a7c78a88311dc196ba5cacb78c5fe708f0749e47bde6b6d7f1c9df source_path: plugins/sdk-overview.md workflow: 15 --- -Plugin SDK — це типізований контракт між плагінами та ядром. Ця сторінка — -довідник про **що імпортувати** і **що можна реєструвати**. +SDK Plugin — це типізований контракт між plugins і core. Ця сторінка — +довідник про **що імпортувати** і **що можна зареєструвати**. Шукаєте натомість практичний посібник? -- Перший плагін? Почніть із [Створення плагінів](/uk/plugins/building-plugins). -- Плагін каналу? Дивіться [Плагіни каналів](/uk/plugins/sdk-channel-plugins). -- Плагін провайдера? Дивіться [Плагіни провайдерів](/uk/plugins/sdk-provider-plugins). -- Плагін інструмента або хука життєвого циклу? Дивіться [Хуки плагінів](/uk/plugins/hooks). +- Перший Plugin? Почніть з [Building plugins](/uk/plugins/building-plugins). +- Plugin каналу? Див. [Channel plugins](/uk/plugins/sdk-channel-plugins). +- Plugin постачальника? Див. [Provider plugins](/uk/plugins/sdk-provider-plugins). +- Plugin інструмента або lifecycle hook? Див. [Plugin hooks](/uk/plugins/hooks). -## Угода щодо імпорту +## Правило імпорту Завжди імпортуйте з конкретного підшляху: @@ -38,112 +38,112 @@ import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core"; Кожен підшлях — це невеликий самодостатній модуль. Це зберігає швидкий запуск і запобігає проблемам із циклічними залежностями. Для специфічних для каналу -допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; залишайте `openclaw/plugin-sdk/core` для -ширшої поверхні-парасольки та спільних допоміжних засобів, таких як +допоміжних засобів entry/build віддавайте перевагу `openclaw/plugin-sdk/channel-core`; `openclaw/plugin-sdk/core` залишайте для +ширшої umbrella-поверхні та спільних допоміжних засобів, таких як `buildChannelConfigSchema`. - Не імпортуйте branded convenience seams для провайдерів або каналів (наприклад + Не імпортуйте branded convenience seams постачальника або каналу (наприклад `openclaw/plugin-sdk/slack`, `.../discord`, `.../signal`, `.../whatsapp`). - Вбудовані плагіни поєднують загальні підшляхи SDK у власних barrel-файлах `api.ts` / - `runtime-api.ts`; споживачам ядра слід або використовувати ці локальні для плагіна - barrel-файли, або додати вузький загальний контракт SDK, коли потреба справді + Вбудовані plugins компонує загальні підшляхи SDK у власних barrel-файлах `api.ts` / + `runtime-api.ts`; споживачі core мають або використовувати ці локальні для plugin + barrel-файли, або додавати вузький загальний контракт SDK, коли потреба справді є міжканальною. -Невеликий набір helper seams для вбудованих плагінів (`plugin-sdk/feishu`, +Невеликий набір допоміжних seams для вбудованих plugins (`plugin-sdk/feishu`, `plugin-sdk/zalo`, `plugin-sdk/matrix*` та подібні) усе ще з’являється в -згенерованій карті експортів. Вони існують лише для супроводу вбудованих плагінів і -не рекомендуються як шляхи імпорту для нових сторонніх плагінів. +згенерованій карті експорту. Вони існують лише для підтримки вбудованих plugins і +не рекомендуються як шляхи імпорту для нових сторонніх plugins. ## Довідник підшляхів -Plugin SDK доступний як набір вузьких підшляхів, згрупованих за областями (entry -плагіна, канал, провайдер, auth, runtime, capability, memory і зарезервовані -helper-модулі для вбудованих плагінів). Повний каталог — згрупований і з посиланнями — дивіться в -[Підшляхи Plugin SDK](/uk/plugins/sdk-subpaths). +SDK Plugin доступний як набір вузьких підшляхів, згрупованих за областями (plugin +entry, channel, provider, auth, runtime, capability, memory і зарезервовані +допоміжні засоби для вбудованих plugins). Повний каталог — згрупований і з посиланнями — див. у +[Plugin SDK subpaths](/uk/plugins/sdk-subpaths). -Згенерований список із понад 200 підшляхів розміщено в `scripts/lib/plugin-sdk-entrypoints.json`. +Згенерований список із понад 200 підшляхів міститься в `scripts/lib/plugin-sdk-entrypoints.json`. ## API реєстрації -Колбек `register(api)` отримує об’єкт `OpenClawPluginApi` із такими +Зворотний виклик `register(api)` отримує об’єкт `OpenClawPluginApi` з такими методами: ### Реєстрація можливостей | Метод | Що він реєструє | -| ------------------------------------------------ | ----------------------------------- | +| ----------------------------------------------- | ----------------------------------- | | `api.registerProvider(...)` | Текстовий inference (LLM) | | `api.registerAgentHarness(...)` | Експериментальний низькорівневий виконавець агента | -| `api.registerCliBackend(...)` | Локальний backend inference для CLI | +| `api.registerCliBackend(...)` | Локальний бекенд inference CLI | | `api.registerChannel(...)` | Канал обміну повідомленнями | -| `api.registerSpeechProvider(...)` | Синтез мовлення / STT | +| `api.registerSpeechProvider(...)` | Синтез text-to-speech / STT | | `api.registerRealtimeTranscriptionProvider(...)` | Потокова транскрипція в реальному часі | -| `api.registerRealtimeVoiceProvider(...)` | Двобічні голосові сесії в реальному часі | +| `api.registerRealtimeVoiceProvider(...)` | Дуплексні голосові сеанси в реальному часі | | `api.registerMediaUnderstandingProvider(...)` | Аналіз зображень/аудіо/відео | | `api.registerImageGenerationProvider(...)` | Генерація зображень | | `api.registerMusicGenerationProvider(...)` | Генерація музики | | `api.registerVideoGenerationProvider(...)` | Генерація відео | -| `api.registerWebFetchProvider(...)` | Провайдер web fetch / scrape | +| `api.registerWebFetchProvider(...)` | Постачальник web fetch / scrape | | `api.registerWebSearchProvider(...)` | Вебпошук | -### Інструменти та команди +### Інструменти й команди -| Метод | Що він реєструє | -| ------------------------------- | ------------------------------------------- | +| Метод | Що він реєструє | +| ------------------------------ | --------------------------------------------- | | `api.registerTool(tool, opts?)` | Інструмент агента (обов’язковий або `{ optional: true }`) | -| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | +| `api.registerCommand(def)` | Користувацька команда (обходить LLM) | ### Інфраструктура | Метод | Що він реєструє | -| ----------------------------------------------- | ------------------------------------- | -| `api.registerHook(events, handler, opts?)` | Хук події | -| `api.registerHttpRoute(params)` | HTTP-ендпоінт Gateway | +| ---------------------------------------------- | ------------------------------------- | +| `api.registerHook(events, handler, opts?)` | Event hook | +| `api.registerHttpRoute(params)` | HTTP-кінцева точка Gateway | | `api.registerGatewayMethod(name, handler)` | RPC-метод Gateway | -| `api.registerGatewayDiscoveryService(service)` | Рекламування локального виявлення Gateway | +| `api.registerGatewayDiscoveryService(service)` | Локальний сервіс анонсування виявлення Gateway | | `api.registerCli(registrar, opts?)` | Підкоманда CLI | | `api.registerService(service)` | Фоновий сервіс | | `api.registerInteractiveHandler(registration)` | Інтерактивний обробник | -| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструментів harness | +| `api.registerAgentToolResultMiddleware(...)` | Middleware результатів інструментів під час виконання | | `api.registerEmbeddedExtensionFactory(factory)` | Застаріла фабрика розширень PI | -| `api.registerMemoryPromptSupplement(builder)` | Додатковий розділ промпта, суміжний із пам’яттю | -| `api.registerMemoryCorpusSupplement(adapter)` | Додатковий корпус пошуку/читання пам’яті | +| `api.registerMemoryPromptSupplement(builder)` | Адитивний розділ prompt, суміжний із пам’яттю | +| `api.registerMemoryCorpusSupplement(adapter)` | Адитивний корпус пошуку/читання пам’яті | - Зарезервовані простори назв адміністрування ядра (`config.*`, `exec.approvals.*`, `wizard.*`, - `update.*`) завжди залишаються `operator.admin`, навіть якщо плагін намагається призначити - вужчу область дії для методу gateway. Для методів, що належать плагіну, віддавайте перевагу - префіксам, специфічним для плагіна. + Зарезервовані простори назв адміністратора core (`config.*`, `exec.approvals.*`, `wizard.*`, + `update.*`) завжди залишаються `operator.admin`, навіть якщо Plugin намагається призначити + вужчу область для методу gateway. Віддавайте перевагу специфічним для plugin префіксам для + методів, що належать plugin. - Вбудовані плагіни можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли - їм потрібно переписати результат інструмента після виконання і до того, як harness - передасть цей результат назад у модель. Це довірений, нейтральний щодо harness - seam для асинхронних редукторів виводу, таких як tokenjuice. + Вбудовані plugins можуть використовувати `api.registerAgentToolResultMiddleware(...)`, коли + їм потрібно переписати результат інструмента після виконання і до того, як runtime + поверне цей результат назад у модель. Це довірений, нейтральний до runtime seam для + асинхронних редукторів виводу, таких як tokenjuice. -Вбудовані плагіни мають оголошувати `contracts.agentToolResultMiddleware` для кожного -цільового harness, наприклад `["pi", "codex-app-server"]`. Зовнішні плагіни -не можуть реєструвати це middleware; для роботи, якій не потрібен час обробки -результату інструмента до моделі, залишайте звичайні хуки плагінів OpenClaw. +Вбудовані plugins мають оголошувати `contracts.agentToolResultMiddleware` для кожного +цільового runtime, наприклад `["pi", "codex"]`. Зовнішні plugins +не можуть реєструвати це middleware; для роботи, якій не потрібен момент +до подачі результату інструмента в модель, використовуйте звичайні Plugin hooks OpenClaw. `api.registerEmbeddedExtensionFactory(...)` є застарілим. Він залишається - сумісним seam для вбудованих плагінів, яким усе ще потрібні прямі події - embedded-runner Pi. Нові перетворення результатів інструментів натомість мають використовувати - `api.registerAgentToolResultMiddleware(...)`. + сумісним seam для вбудованих plugins, яким усе ще потрібні прямі події + embedded-runner Pi. Нові трансформації результатів інструментів мають + натомість використовувати `api.registerAgentToolResultMiddleware(...)`. ### Реєстрація виявлення Gateway -`api.registerGatewayDiscoveryService(...)` дозволяє плагіну рекламувати активний -Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає сервіс -під час запуску Gateway, коли локальне виявлення ввімкнене, передає поточні -порти Gateway і несеκретні TXT-підказки, а під час завершення роботи Gateway -викликає повернений обробник `stop`. +`api.registerGatewayDiscoveryService(...)` дає Plugin змогу анонсувати активний +Gateway у локальному транспорті виявлення, такому як mDNS/Bonjour. OpenClaw викликає цей +сервіс під час запуску Gateway, коли локальне виявлення ввімкнене, передає +поточні порти Gateway і не секретні TXT-підказки, а потім викликає повернений +обробник `stop` під час завершення роботи Gateway. ```typescript api.registerGatewayDiscoveryService({ @@ -159,21 +159,21 @@ api.registerGatewayDiscoveryService({ }); ``` -Плагіни виявлення Gateway не повинні розглядати рекламовані значення TXT як секрети або -автентифікацію. Виявлення — це підказка для маршрутизації; довірою як і раніше керують -автентифікація Gateway і pinning TLS. +Plugins виявлення Gateway не повинні вважати опубліковані значення TXT секретами або +автентифікацією. Виявлення — це підказка маршрутизації; довірою, auth Gateway і pinning TLS +усе ще керують окремі механізми. ### Метадані реєстрації CLI `api.registerCli(registrar, opts?)` приймає два типи метаданих верхнього рівня: - `commands`: явні корені команд, що належать реєстратору -- `descriptors`: дескриптори команд на етапі парсингу, що використовуються для довідки root CLI, - маршрутизації та лінивої реєстрації CLI плагіна +- `descriptors`: дескриптори команд на етапі розбору, які використовуються для кореневої допомоги CLI, + маршрутизації та лінивої реєстрації CLI Plugin -Якщо ви хочете, щоб команда плагіна залишалася ліниво завантажуваною у звичайному шляху root CLI, -надайте `descriptors`, які охоплюють кожен корінь команди верхнього рівня, що надається -цим реєстратором. +Якщо ви хочете, щоб команда Plugin залишалася ліниво завантажуваною у звичайному +кореневому шляху CLI, надайте `descriptors`, що покривають кожен корінь команди верхнього рівня, +який відкриває цей реєстратор. ```typescript api.registerCli( @@ -193,131 +193,129 @@ api.registerCli( ); ``` -Використовуйте лише `commands`, тільки якщо вам не потрібна лінива реєстрація root CLI. -Цей eager-сумісний шлях усе ще підтримується, але не встановлює -плейсхолдери на основі дескрипторів для лінивого завантаження під час парсингу. +Використовуйте лише `commands`, якщо вам не потрібна лінива реєстрація кореневого CLI. +Цей eager-сумісний шлях залишається підтримуваним, але він не встановлює +placeholder-елементи на основі descriptors для лінивого завантаження на етапі розбору. -### Реєстрація backend CLI +### Реєстрація CLI-бекенду -`api.registerCliBackend(...)` дозволяє плагіну володіти конфігурацією за замовчуванням для локального -backend AI CLI, такого як `codex-cli`. +`api.registerCliBackend(...)` дає Plugin змогу володіти типовою конфігурацією локального +AI CLI-бекенду, такого як `codex-cli`. -- `id` backend стає префіксом провайдера в посиланнях на моделі, таких як `codex-cli/gpt-5`. -- `config` backend використовує ту саму форму, що й `agents.defaults.cliBackends.`. -- Конфігурація користувача все одно має пріоритет. OpenClaw зливає `agents.defaults.cliBackends.` поверх - стандартної конфігурації плагіна перед запуском CLI. -- Використовуйте `normalizeConfig`, коли backend потребує переписувань для сумісності після злиття - (наприклад, нормалізації старих форм прапорців). +- `id` бекенду стає префіксом постачальника в посиланнях на моделі, наприклад `codex-cli/gpt-5`. +- `config` бекенду використовує ту саму форму, що й `agents.defaults.cliBackends.`. +- Конфігурація користувача все одно має пріоритет. Перед запуском CLI OpenClaw об’єднує `agents.defaults.cliBackends.` поверх + значень Plugin за замовчуванням. +- Використовуйте `normalizeConfig`, якщо бекенду потрібні переписування сумісності після об’єднання + (наприклад, нормалізація старих форм прапорців). ### Ексклюзивні слоти -| Метод | Що він реєструє | -| ------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `api.registerContextEngine(id, factory)` | Context engine (одночасно активний лише один). Колбек `assemble()` отримує `availableTools` і `citationsMode`, щоб engine міг адаптувати доповнення до промпта. | -| `api.registerMemoryCapability(capability)` | Єдина можливість пам’яті | -| `api.registerMemoryPromptSection(builder)` | Конструктор розділу промпта пам’яті | -| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | -| `api.registerMemoryRuntime(runtime)` | Адаптер runtime пам’яті | +| Метод | Що він реєструє | +| ----------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `api.registerContextEngine(id, factory)` | Рушій контексту (одночасно активний лише один). Зворотний виклик `assemble()` отримує `availableTools` і `citationsMode`, щоб рушій міг адаптувати додавання до prompt. | +| `api.registerMemoryCapability(capability)` | Уніфіковану можливість пам’яті | +| `api.registerMemoryPromptSection(builder)` | Конструктор розділу prompt для пам’яті | +| `api.registerMemoryFlushPlan(resolver)` | Резолвер плану скидання пам’яті | +| `api.registerMemoryRuntime(runtime)` | Адаптер runtime для пам’яті | -### Адаптери embedding для пам’яті +### Адаптери вбудовування пам’яті | Метод | Що він реєструє | -| ---------------------------------------------- | -------------------------------------------- | -| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер embedding для пам’яті для активного плагіна | +| --------------------------------------------- | -------------------------------------------- | +| `api.registerMemoryEmbeddingProvider(adapter)` | Адаптер вбудовування пам’яті для активного Plugin | -- `registerMemoryCapability` — це рекомендований API ексклюзивного плагіна пам’яті. +- `registerMemoryCapability` — це рекомендований API ексклюзивного Plugin для пам’яті. - `registerMemoryCapability` також може надавати `publicArtifacts.listArtifacts(...)`, - щоб плагіни-супутники могли споживати експортовані артефакти пам’яті через - `openclaw/plugin-sdk/memory-host-core` замість звернення до приватної структури - конкретного плагіна пам’яті. + щоб супутні plugins могли споживати експортовані артефакти пам’яті через + `openclaw/plugin-sdk/memory-host-core` замість звернення до приватного + макета конкретного Plugin пам’яті. - `registerMemoryPromptSection`, `registerMemoryFlushPlan` і - `registerMemoryRuntime` — це сумісні зі старими версіями API ексклюзивного плагіна пам’яті. -- `registerMemoryEmbeddingProvider` дозволяє активному плагіну пам’яті реєструвати один - або більше ідентифікаторів адаптерів embedding (наприклад `openai`, `gemini` або - користувацький ідентифікатор, визначений плагіном). -- Користувацька конфігурація, така як `agents.defaults.memorySearch.provider` і + `registerMemoryRuntime` — це сумісні із застарілими версіями API ексклюзивного Plugin для пам’яті. +- `registerMemoryEmbeddingProvider` дає активному Plugin пам’яті змогу реєструвати один + або кілька id адаптерів вбудовування (наприклад `openai`, `gemini` або власний id, визначений plugin). +- Конфігурація користувача, така як `agents.defaults.memorySearch.provider` і `agents.defaults.memorySearch.fallback`, зіставляється з цими зареєстрованими - ідентифікаторами адаптерів. + id адаптерів. ### Події та життєвий цикл -| Метод | Що він робить | -| -------------------------------------------- | --------------------------- | -| `api.on(hookName, handler, opts?)` | Типізований хук життєвого циклу | -| `api.onConversationBindingResolved(handler)` | Колбек прив’язки розмови | +| Метод | Що він робить | +| ------------------------------------------- | ---------------------------- | +| `api.on(hookName, handler, opts?)` | Типізований lifecycle hook | +| `api.onConversationBindingResolved(handler)` | Зворотний виклик прив’язки розмови | -Дивіться [Хуки плагінів](/uk/plugins/hooks), щоб переглянути приклади, поширені назви хуків і -семантику guard. +Приклади, поширені назви hooks і семантику guard див. у [Plugin hooks](/uk/plugins/hooks). -### Семантика рішень для хуків +### Семантика рішень hook -- `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` залишайте для специфічних для каналу додаткових даних. -- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId`, перш ніж повертатися до специфічного для каналу `metadata`. -- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить Gateway, замість покладання на внутрішні хуки `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` залишайте для специфічних для каналу додаткових даних. +- `message_sending`: використовуйте типізовані поля маршрутизації `replyToId` / `threadId` перед тим, як переходити до специфічного для каналу `metadata`. +- `gateway_start`: використовуйте `ctx.config`, `ctx.workspaceDir` і `ctx.getCron?.()` для стану запуску, що належить gateway, замість покладання на внутрішні hooks `gateway:startup`. ### Поля об’єкта API -| Поле | Тип | Опис | -| ------------------------ | ------------------------- | ------------------------------------------------------------------------------------------- | -| `api.id` | `string` | Ідентифікатор плагіна | -| `api.name` | `string` | Відображувана назва | -| `api.version` | `string?` | Версія плагіна (необов’язково) | -| `api.description` | `string?` | Опис плагіна (необов’язково) | -| `api.source` | `string` | Шлях до джерела плагіна | -| `api.rootDir` | `string?` | Кореневий каталог плагіна (необов’язково) | -| `api.config` | `OpenClawConfig` | Поточний знімок конфігурації (активний внутрішній знімок runtime, коли доступний) | -| `api.pluginConfig` | `Record` | Конфігурація, специфічна для плагіна, із `plugins.entries..config` | -| `api.runtime` | `PluginRuntime` | [Допоміжні засоби runtime](/uk/plugins/sdk-runtime) | -| `api.logger` | `PluginLogger` | Логер з областю видимості (`debug`, `info`, `warn`, `error`) | -| `api.registrationMode` | `PluginRegistrationMode` | Поточний режим завантаження; `"setup-runtime"` — це легке вікно запуску/налаштування до повного entry | -| `api.resolvePath(input)` | `(string) => string` | Визначення шляху відносно кореня плагіна | +| Поле | Тип | Опис | +| ------------------------ | ------------------------- | -------------------------------------------------------------------------------------------- | +| `api.id` | `string` | Id 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 | ## Угода щодо внутрішніх модулів -Усередині вашого плагіна використовуйте локальні barrel-файли для внутрішніх імпортів: +Усередині вашого plugin використовуйте локальні barrel-файли для внутрішніх імпортів: ``` my-plugin/ api.ts # Публічні експорти для зовнішніх споживачів - runtime-api.ts # Експорти runtime лише для внутрішнього використання - index.ts # Точка входу плагіна - setup-entry.ts # Легка точка входу лише для setup (необов’язково) + runtime-api.ts # Лише внутрішні експорти runtime + index.ts # Точка входу Plugin + setup-entry.ts # Полегшена точка входу лише для налаштування (необов’язково) ``` - Ніколи не імпортуйте власний плагін через `openclaw/plugin-sdk/` - з production-коду. Спрямовуйте внутрішні імпорти через `./api.ts` або + Ніколи не імпортуйте власний plugin через `openclaw/plugin-sdk/` + у production-коді. Спрямовуйте внутрішні імпорти через `./api.ts` або `./runtime-api.ts`. Шлях SDK — це лише зовнішній контракт. -Публічні поверхні вбудованих плагінів, завантажених через facade (`api.ts`, `runtime-api.ts`, +Публічні поверхні вбудованих plugins, завантажуваних через facade (`api.ts`, `runtime-api.ts`, `index.ts`, `setup-entry.ts` та подібні публічні entry-файли), віддають перевагу -активному знімку конфігурації runtime, коли OpenClaw уже працює. Якщо знімок runtime -ще не існує, вони повертаються до визначеного файлу конфігурації на диску. +активному знімку конфігурації runtime, якщо OpenClaw уже запущено. Якщо знімок runtime +ще не існує, вони повертаються до розв’язаного файлу конфігурації на диску. -Плагіни провайдерів можуть надавати вузький локальний для плагіна контрактний barrel, коли -допоміжний засіб навмисно є специфічним для провайдера і ще не належить до загального підшляху SDK. -Приклади вбудованих плагінів: +Plugins постачальників можуть відкривати вузький barrel локального контракту plugin, коли +допоміжний засіб навмисно є специфічним для постачальника й поки не належить до +загального підшляху SDK. Приклади вбудованих plugins: -- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для заголовка бета-функцій Claude - та допоміжних засобів потоків `service_tier`. -- **`@openclaw/openai-provider`**: `api.ts` експортує builder-об’єкти провайдера, - допоміжні засоби моделей за замовчуванням і builder-об’єкти провайдерів realtime. -- **`@openclaw/openrouter-provider`**: `api.ts` експортує builder провайдера - разом із допоміжними засобами onboarding/config. +- **Anthropic**: публічний seam `api.ts` / `contract-api.ts` для допоміжних засобів + beta-header Claude і потоку `service_tier`. +- **`@openclaw/openai-provider`**: `api.ts` експортує конструктори постачальника, + допоміжні засоби для типових моделей і конструктори постачальників realtime. +- **`@openclaw/openrouter-provider`**: `api.ts` експортує конструктор постачальника + плюс допоміжні засоби onboarding/config. Production-код розширень також має уникати імпортів `openclaw/plugin-sdk/`. - Якщо допоміжний засіб справді є спільним, перенесіть його до нейтрального підшляху SDK, - такого як `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої - поверхні, орієнтованої на можливості, замість зв’язування двох плагінів між собою. + Якщо допоміжний засіб справді є спільним, підніміть його до нейтрального підшляху SDK, + наприклад `openclaw/plugin-sdk/speech`, `.../provider-model-shared` або іншої + поверхні, орієнтованої на можливості, замість жорсткого зв’язування двох plugins. ## Пов’язане @@ -329,7 +327,7 @@ my-plugin/ Повний довідник простору назв `api.runtime`. - + Пакування, маніфести та схеми конфігурації. @@ -338,7 +336,7 @@ my-plugin/ Міграція із застарілих поверхонь. - + Поглиблена архітектура та модель можливостей. diff --git a/docs/uk/providers/google.md b/docs/uk/providers/google.md index 6ed9d789c..3d934a5e4 100644 --- a/docs/uk/providers/google.md +++ b/docs/uk/providers/google.md @@ -1,42 +1,41 @@ --- read_when: - Ви хочете використовувати моделі Google Gemini з OpenClaw - - Вам потрібен ключ API або потік автентифікації OAuth -summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, вебпошук) + - Вам потрібен процес автентифікації за допомогою ключа API або OAuth +summary: Налаштування Google Gemini (ключ API + OAuth, генерація зображень, розуміння медіа, TTS, web search) title: Google (Gemini) x-i18n: - generated_at: "2026-04-24T08:40:13Z" + generated_at: "2026-04-25T00:03:21Z" model: gpt-5.4 provider: openai - source_hash: 7e66c9dd637e26976659d04b9b7e2452e6881945dab6011970f9e1c5e4a9a685 + source_hash: 6a3e8531d2cf58ac0f0c003d369be837576b4c2ff7d38e53cfb3f86ab8b44347 source_path: providers/google.md workflow: 15 --- -Плагін Google надає доступ до моделей Gemini через Google AI Studio, а також до -генерації зображень, розуміння медіа (зображення/аудіо/відео), text-to-speech і вебпошуку через -Gemini Grounding. +Plugin Google надає доступ до моделей Gemini через Google AI Studio, а також до генерації зображень, розуміння медіа (зображення/аудіо/відео), синтезу мовлення та web search через Gemini Grounding. - Провайдер: `google` - Автентифікація: `GEMINI_API_KEY` або `GOOGLE_API_KEY` - API: Google Gemini API -- Альтернативний провайдер: `google-gemini-cli` (OAuth) +- Параметр runtime: `agents.defaults.embeddedHarness.runtime: "google-gemini-cli"` + повторно використовує OAuth Gemini CLI, зберігаючи канонічні посилання на моделі як `google/*`. ## Початок роботи -Оберіть бажаний спосіб автентифікації та виконайте кроки налаштування. +Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - + **Найкраще для:** стандартного доступу до Gemini API через Google AI Studio. - + ```bash openclaw onboard --auth-choice gemini-api-key ``` - Або передайте ключ напряму: + Або передайте ключ безпосередньо: ```bash openclaw onboard --non-interactive \ @@ -45,7 +44,7 @@ Gemini Grounding. --gemini-api-key "$GEMINI_API_KEY" ``` - + ```json5 { agents: { @@ -56,7 +55,7 @@ Gemini Grounding. } ``` - + ```bash openclaw models list --provider google ``` @@ -64,7 +63,7 @@ Gemini Grounding. - Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка у вас уже налаштована. + Змінні середовища `GEMINI_API_KEY` і `GOOGLE_API_KEY` обидві підтримуються. Використовуйте ту, яка вже налаштована у вас. @@ -74,37 +73,37 @@ Gemini Grounding. Провайдер `google-gemini-cli` є неофіційною інтеграцією. Деякі користувачі - повідомляють про обмеження облікового запису при використанні OAuth у такий спосіб. Використовуйте на власний ризик. + повідомляють про обмеження облікового запису при такому використанні OAuth. Використовуйте на власний ризик. - + Локальна команда `gemini` має бути доступною в `PATH`. ```bash # Homebrew brew install gemini-cli - # або npm + # or npm npm install -g @google/gemini-cli ``` - OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, зокрема - поширені схеми Windows/npm. + OpenClaw підтримує як встановлення через Homebrew, так і глобальні встановлення через npm, включно з поширеними схемами Windows/npm. - + ```bash openclaw models auth login --provider google-gemini-cli --set-default ``` - + ```bash - openclaw models list --provider google-gemini-cli + openclaw models list --provider google ``` - - Модель за замовчуванням: `google-gemini-cli/gemini-3-flash-preview` + - Модель за замовчуванням: `google/gemini-3.1-pro-preview` + - Runtime: `google-gemini-cli` - Псевдонім: `gemini-cli` **Змінні середовища:** @@ -115,53 +114,53 @@ Gemini Grounding. (Або варіанти `GEMINI_CLI_*`.) - Якщо OAuth-запити Gemini CLI не вдаються після входу, задайте `GOOGLE_CLOUD_PROJECT` або - `GOOGLE_CLOUD_PROJECT_ID` на хості gateway і повторіть спробу. + Якщо OAuth-запити Gemini CLI завершуються помилкою після входу, установіть `GOOGLE_CLOUD_PROJECT` або + `GOOGLE_CLOUD_PROJECT_ID` на хості Gateway і повторіть спробу. - Якщо вхід не вдається ще до запуску потоку в браузері, переконайтеся, що локальна команда `gemini` - встановлена й доступна в `PATH`. + Якщо вхід завершується помилкою до початку браузерного потоку, переконайтеся, що локальну команду `gemini` + встановлено і вона є в `PATH`. - Провайдер `google-gemini-cli`, який працює лише через OAuth, є окремою поверхнею - текстового інференсу. Генерація зображень, розуміння медіа та Gemini Grounding залишаються на - ідентифікаторі провайдера `google`. + Посилання на моделі `google-gemini-cli/*` є застарілими псевдонімами сумісності. У нових + конфігураціях слід використовувати посилання на моделі `google/*` разом із runtime `google-gemini-cli`, + коли потрібне локальне виконання Gemini CLI. ## Можливості -| Можливість | Підтримка | -| --------------------- | ------------------------------ | -| Завершення чату | Так | -| Генерація зображень | Так | -| Генерація музики | Так | -| Text-to-speech | Так | -| Голос у реальному часі| Так (Google Live API) | -| Розуміння зображень | Так | -| Транскрипція аудіо | Так | -| Розуміння відео | Так | -| Вебпошук (Grounding) | Так | -| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) | -| Моделі Gemma 4 | Так | +| Можливість | Підтримка | +| --------------------- | ----------------------------- | +| Chat completions | Так | +| Генерація зображень | Так | +| Генерація музики | Так | +| Синтез мовлення | Так | +| Голос у реальному часі | Так (Google Live API) | +| Розуміння зображень | Так | +| Транскрипція аудіо | Так | +| Розуміння відео | Так | +| Web search (Grounding) | Так | +| Thinking/reasoning | Так (Gemini 2.5+ / Gemini 3+) | +| Моделі Gemma 4 | Так | Моделі Gemini 3 використовують `thinkingLevel` замість `thinkingBudget`. OpenClaw зіставляє -керування міркуванням для Gemini 3, Gemini 3.1 і псевдоніма `gemini-*-latest` з +елементи керування reasoning для Gemini 3, Gemini 3.1 і псевдонімів `gemini-*-latest` з `thinkingLevel`, щоб типові/низьколатентні запуски не надсилали вимкнені значення `thinkingBudget`. -Моделі Gemma 4 (наприклад, `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw -переписує `thinkingBudget` у підтримуваний Google `thinkingLevel` для Gemma 4. -Установлення thinking у `off` зберігає thinking вимкненим замість зіставлення з +Моделі Gemma 4 (наприклад `gemma-4-26b-a4b-it`) підтримують режим thinking. OpenClaw +переписує `thinkingBudget` на підтримуваний Google `thinkingLevel` для Gemma 4. +Установлення thinking у `off` зберігає його вимкненим замість зіставлення з `MINIMAL`. ## Генерація зображень -Вбудований провайдер генерації зображень `google` за замовчуванням використовує +Вбудований провайдер генерації зображень `google` типово використовує `google/gemini-3.1-flash-image-preview`. - Також підтримує `google/gemini-3-pro-image-preview` @@ -169,7 +168,7 @@ Gemini Grounding. - Режим редагування: увімкнено, до 5 вхідних зображень - Керування геометрією: `size`, `aspectRatio` і `resolution` -Щоб використовувати Google як провайдер зображень за замовчуванням: +Щоб використовувати Google як провайдера зображень за замовчуванням: ```json5 { @@ -184,7 +183,7 @@ Gemini Grounding. ``` -Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація зображень](/uk/tools/image-generation). ## Генерація відео @@ -193,11 +192,11 @@ Gemini Grounding. інструмент `video_generate`. - Модель відео за замовчуванням: `google/veo-3.1-fast-generate-preview` -- Режими: text-to-video, image-to-video і потоки з посиланням на одне відео +- Режими: text-to-video, image-to-video і потоки з одним еталонним відео - Підтримує `aspectRatio`, `resolution` і `audio` - Поточне обмеження тривалості: **від 4 до 8 секунд** -Щоб використовувати Google як провайдер відео за замовчуванням: +Щоб використовувати Google як провайдера відео за замовчуванням: ```json5 { @@ -212,7 +211,7 @@ Gemini Grounding. ``` -Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація відео](/uk/tools/video-generation). ## Генерація музики @@ -222,12 +221,12 @@ Gemini Grounding. - Модель музики за замовчуванням: `google/lyria-3-clip-preview` - Також підтримує `google/lyria-3-pro-preview` -- Керування підказкою: `lyrics` і `instrumental` -- Формат виводу: `mp3` за замовчуванням, а також `wav` у `google/lyria-3-pro-preview` -- Опорні входи: до 10 зображень -- Запуски з підтримкою сесій відокремлюються через спільний потік задач/статусу, зокрема `action: "status"` +- Керування prompt: `lyrics` і `instrumental` +- Формат виводу: `mp3` за замовчуванням, а також `wav` для `google/lyria-3-pro-preview` +- Еталонні вхідні дані: до 10 зображень +- Запуски з підтримкою сеансів від’єднуються через спільний потік задачі/статусу, включно з `action: "status"` -Щоб використовувати Google як провайдер музики за замовчуванням: +Щоб використовувати Google як провайдера музики за замовчуванням: ```json5 { @@ -242,12 +241,12 @@ Gemini Grounding. ``` -Див. [Генерація музики](/uk/tools/music-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. +Спільні параметри інструмента, вибір провайдера та поведінку failover див. у [Генерація музики](/uk/tools/music-generation). -## Text-to-speech +## Синтез мовлення -Вбудований мовний провайдер `google` використовує шлях Gemini API TTS з +Вбудований провайдер мовлення `google` використовує шлях Gemini API TTS з `gemini-3.1-flash-tts-preview`. - Голос за замовчуванням: `Kore` @@ -255,7 +254,7 @@ Gemini Grounding. - Вивід: WAV для звичайних TTS-вкладень, PCM для Talk/телефонії - Нативний вивід голосових нотаток: не підтримується на цьому шляху Gemini API, оскільки API повертає PCM, а не Opus -Щоб використовувати Google як TTS-провайдер за замовчуванням: +Щоб використовувати Google як провайдера TTS за замовчуванням: ```json5 { @@ -274,14 +273,14 @@ Gemini Grounding. } ``` -Gemini API TTS приймає виразні аудіотеги в квадратних дужках у тексті, наприклад -`[whispers]` або `[laughs]`. Щоб приховати теги з видимої відповіді чату, але +Gemini API TTS приймає виразні квадратні аудіотеги в тексті, наприклад +`[whispers]` або `[laughs]`. Щоб не показувати теги у видимій відповіді чату, але надсилати їх до TTS, помістіть їх у блок `[[tts:text]]...[[/tts:text]]`: ```text -Ось чистий текст відповіді. +Here is the clean reply text. -[[tts:text]][whispers] Ось озвучена версія.[[/tts:text]] +[[tts:text]][whispers] Here is the spoken version.[[/tts:text]] ``` @@ -294,17 +293,17 @@ Gemini API TTS приймає виразні аудіотеги в квадра Вбудований Plugin `google` реєструє провайдера голосу в реальному часі на базі Gemini Live API для серверних аудіомостів, таких як Voice Call і Google Meet. -| Налаштування | Шлях конфігурації | За замовчуванням | -| --------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | -| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | -| Голос | `...google.voice` | `Kore` | -| Temperature | `...google.temperature` | (не задано) | -| Чутливість початку VAD| `...google.startSensitivity` | (не задано) | -| Чутливість кінця VAD | `...google.endSensitivity` | (не задано) | -| Тривалість тиші | `...google.silenceDurationMs` | (не задано) | -| Ключ API | `...google.apiKey` | Використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` як запасний варіант | +| Параметр | Шлях конфігурації | Значення за замовчуванням | +| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | +| Модель | `plugins.entries.voice-call.config.realtime.providers.google.model` | `gemini-2.5-flash-native-audio-preview-12-2025` | +| Голос | `...google.voice` | `Kore` | +| Temperature | `...google.temperature` | (не встановлено) | +| Чутливість початку VAD | `...google.startSensitivity` | (не встановлено) | +| Чутливість завершення VAD | `...google.endSensitivity` | (не встановлено) | +| Тривалість тиші | `...google.silenceDurationMs` | (не встановлено) | +| Ключ API | `...google.apiKey` | Резервно використовує `models.providers.google.apiKey`, `GEMINI_API_KEY` або `GOOGLE_API_KEY` | -Приклад конфігурації Voice Call для роботи в реальному часі: +Приклад конфігурації Voice Call realtime: ```json5 { @@ -332,32 +331,32 @@ Gemini Live API для серверних аудіомостів, таких я Google Live API використовує двоспрямоване аудіо та виклик функцій через WebSocket. -OpenClaw адаптує аудіо телефонії/Meet-мосту до потоку PCM Live API Gemini і +OpenClaw адаптує аудіо телефонії/мосту Meet до PCM Live API потоку Gemini і зберігає виклики інструментів у межах спільного контракту голосу в реальному часі. Залишайте `temperature` -не заданим, якщо вам не потрібні зміни семплювання; OpenClaw пропускає недодатні значення, +не встановленим, якщо вам не потрібні зміни вибірки; OpenClaw пропускає непозитивні значення, оскільки Google Live може повертати транскрипти без аудіо для `temperature: 0`. -Транскрипція Gemini API вмикається без `languageCodes`; поточний Google -SDK відхиляє підказки кодів мов на цьому шляху API. +Транскрипцію Gemini API увімкнено без `languageCodes`; поточний Google SDK +відхиляє підказки кодів мов на цьому шляху API. -Сесії Talk у браузері в UI Control, як і раніше, потребують провайдера голосу в реальному часі з -реалізацією сеансу браузерного WebRTC. Наразі цим шляхом є OpenAI Realtime; провайдер -Google призначений для серверних мостів реального часу. +Сеанси браузера Talk у Control UI і далі потребують провайдера голосу в реальному часі з +реалізацією браузерного сеансу WebRTC. Наразі цей шлях — OpenAI Realtime; провайдер +Google призначений для серверних realtime-мостів. -## Розширене налаштування +## Розширена конфігурація - - Для прямих запусків Gemini API (`api: "google-generative-ai"`) OpenClaw - передає налаштований дескриптор `cachedContent` у запити Gemini. + + Для прямих запусків Gemini API (`api: "google-generative-ai"`), OpenClaw + передає налаштований дескриптор `cachedContent` до запитів Gemini. - - Налаштовуйте параметри для моделі або глобально за допомогою - `cachedContent` або застарілого `cached_content` + - Налаштуйте параметри для моделі або глобально через + `cachedContent` або застарілий `cached_content` - Якщо присутні обидва, пріоритет має `cachedContent` - Приклад значення: `cachedContents/prebuilt-context` - - Використання влучань кешу Gemini нормалізується в OpenClaw `cacheRead` з + - Використання кеш-потрапляння Gemini нормалізується в OpenClaw `cacheRead` із висхідного `cachedContentTokenCount` ```json5 @@ -379,13 +378,13 @@ Google призначений для серверних мостів реаль - Під час використання OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує - JSON-вивід CLI таким чином: + При використанні OAuth-провайдера `google-gemini-cli` OpenClaw нормалізує + JSON-вивід CLI так: - Текст відповіді береться з поля CLI JSON `response`. - - Використання бере `stats` як запасний варіант, якщо CLI залишає `usage` порожнім. + - Використання резервно береться з `stats`, якщо CLI залишає `usage` порожнім. - `stats.cached` нормалізується в OpenClaw `cacheRead`. - - Якщо `stats.input` відсутнє, OpenClaw обчислює вхідні токени з + - Якщо `stats.input` відсутній, OpenClaw обчислює вхідні токени з `stats.input_tokens - stats.cached`. diff --git a/docs/uk/providers/openai.md b/docs/uk/providers/openai.md index a356a95d7..d15f32131 100644 --- a/docs/uk/providers/openai.md +++ b/docs/uk/providers/openai.md @@ -1,78 +1,79 @@ --- read_when: - Ви хочете використовувати моделі OpenAI в OpenClaw - - Ви хочете автентифікацію за підпискою Codex замість API-ключів - - Вам потрібні суворіші правила виконання агента GPT-5 + - Ви хочете автентифікацію через підписку Codex замість API-ключів + - Вам потрібна суворіша поведінка виконання агента GPT-5 summary: Використовуйте OpenAI через API-ключі або підписку Codex в OpenClaw title: OpenAI x-i18n: - generated_at: "2026-04-24T16:58:35Z" + generated_at: "2026-04-25T00:03:26Z" model: gpt-5.4 provider: openai - source_hash: bedc8975dae28e13d653494723ca0ee44cefdb63cbd4c6397658bd22fd8c3d80 + source_hash: 281ea7705763053b7038159035867b54e7255dc01136c54bfb7c68b5cc34cab1 source_path: providers/openai.md workflow: 15 --- -OpenAI надає API для розробників для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут: +OpenAI надає API розробника для моделей GPT. OpenClaw підтримує три маршрути сімейства OpenAI. Префікс моделі визначає маршрут: -- **API-ключ** — прямий доступ до OpenAI Platform з тарифікацією за використання (`openai/*` моделі) -- **Підписка Codex через PI** — вхід через ChatGPT/Codex із доступом за підпискою (`openai-codex/*` моделі) -- **Обв’язка Codex app-server** — нативне виконання через Codex app-server (`openai/*` моделі плюс `agents.defaults.embeddedHarness.runtime: "codex"`) +- **API key** — прямий доступ до OpenAI Platform з оплатою за використання (моделі `openai/*`) +- **Підписка Codex через PI** — вхід через ChatGPT/Codex з доступом за підпискою (моделі `openai-codex/*`) +- **Harness app-server Codex** — власне виконання через app-server Codex (моделі `openai/*` плюс `agents.defaults.embeddedHarness.runtime: "codex"`) -OpenAI явно підтримує використання OAuth за підпискою в зовнішніх інструментах і робочих процесах, таких як OpenClaw. +OpenAI явно підтримує використання OAuth підписки в зовнішніх інструментах і робочих процесах, таких як OpenClaw. ## Швидкий вибір -| Ціль | Використовуйте | Примітки | -| --------------------------------------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------- | -| Пряма тарифікація за API-ключем | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або виконайте онбординг OpenAI API-key. | -| GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для конфігурацій із підпискою. | -| GPT-5.5 з нативною поведінкою Codex app-server | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує обв’язку Codex app-server, а не публічний маршрут OpenAI API. | -| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. | +| Ціль | Використовуйте | Примітки | +| --------------------------------------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------- | +| Пряме виставлення рахунків за API key | `openai/gpt-5.4` | Установіть `OPENAI_API_KEY` або запустіть онбординг OpenAI API key. | +| GPT-5.5 з автентифікацією через підписку ChatGPT/Codex | `openai-codex/gpt-5.5` | Типовий маршрут PI для Codex OAuth. Найкращий перший вибір для налаштувань із підпискою. | +| GPT-5.5 із власною поведінкою app-server Codex | `openai/gpt-5.5` плюс `embeddedHarness.runtime: "codex"` | Використовує harness app-server Codex, а не публічний маршрут OpenAI API. | +| Генерація або редагування зображень | `openai/gpt-image-2` | Працює як з `OPENAI_API_KEY`, так і з OpenAI Codex OAuth. | -GPT-5.5 наразі доступний в OpenClaw через маршрути підписки/OAuth: -`openai-codex/gpt-5.5` з виконавцем PI або `openai/gpt-5.5` з -обв’язкою Codex app-server. Прямий доступ за API-ключем до `openai/gpt-5.5` -підтримуватиметься, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу використовуйте -модель із підтримкою API, наприклад `openai/gpt-5.4`, для конфігурацій із `OPENAI_API_KEY`. +GPT-5.5 зараз доступна в OpenClaw через маршрути підписки/OAuth: +`openai-codex/gpt-5.5` з runner PI або `openai/gpt-5.5` з +harness app-server Codex. Прямий доступ через API key для `openai/gpt-5.5` +підтримується, щойно OpenAI увімкне GPT-5.5 у публічному API; до того часу +використовуйте модель із доступом через API, таку як `openai/gpt-5.4`, для +налаштувань із `OPENAI_API_KEY`. Увімкнення Plugin OpenAI або вибір моделі `openai-codex/*` не -вмикає вбудований Plugin Codex app-server. OpenClaw вмикає цей Plugin лише -коли ви явно обираєте нативну обв’язку Codex за допомогою -`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання на модель `codex/*`. +вмикає вбудований Plugin app-server Codex. OpenClaw вмикає цей Plugin лише +коли ви явно вибираєте власний harness Codex через +`embeddedHarness.runtime: "codex"` або використовуєте застаріле посилання моделі `codex/*`. -## Покриття можливостей OpenClaw +## Покриття функцій OpenClaw -| Можливість OpenAI | Поверхня OpenClaw | Статус | -| ------------------------- | --------------------------------------------------------- | ------------------------------------------------------ | -| Chat / Responses | постачальник моделей `openai/` | Так | -| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | -| Обв’язка Codex app-server | `openai/` з `embeddedHarness.runtime: codex` | Так | -| Пошук у вебі на стороні сервера | нативний інструмент OpenAI Responses | Так, коли ввімкнено вебпошук і не закріплено постачальника | -| Зображення | `image_generate` | Так | -| Відео | `video_generate` | Так | -| Перетворення тексту на мовлення | `messages.tts.provider: "openai"` / `tts` | Так | -| Пакетне перетворення мовлення на текст | `tools.media.audio` / розуміння медіа | Так | -| Потокове перетворення мовлення на текст | Voice Call `streaming.provider: "openai"` | Так | -| Голос у реальному часі | Voice Call `realtime.provider: "openai"` / Control UI Talk | Так | -| Вбудовування | постачальник embedding для пам’яті | Так | +| Можливість OpenAI | Поверхня OpenClaw | Статус | +| ------------------------- | ---------------------------------------------------------- | ------------------------------------------------------ | +| Чат / Responses | Провайдер моделей `openai/` | Так | +| Моделі підписки Codex | `openai-codex/` з OAuth `openai-codex` | Так | +| Harness app-server Codex | `openai/` з `embeddedHarness.runtime: codex` | Так | +| Пошук у вебі на стороні сервера | Власний інструмент OpenAI Responses | Так, коли вебпошук увімкнено й не закріплено провайдера | +| Зображення | `image_generate` | Так | +| Відео | `video_generate` | Так | +| Text-to-speech | `messages.tts.provider: "openai"` / `tts` | Так | +| Batch speech-to-text | `tools.media.audio` / розуміння медіа | Так | +| Streaming speech-to-text | Voice Call `streaming.provider: "openai"` | Так | +| Realtime voice | Voice Call `realtime.provider: "openai"` / розмова в Control UI | Так | +| Embeddings | провайдер embedding для пам’яті | Так | ## Початок роботи Виберіть бажаний спосіб автентифікації та виконайте кроки налаштування. - - **Найкраще для:** прямого доступу до API та тарифікації за використання. + + **Найкраще для:** прямого доступу до API й виставлення рахунків за використання. - - Створіть або скопіюйте API-ключ у [панелі керування OpenAI Platform](https://platform.openai.com/api-keys). + + Створіть або скопіюйте API key з [панелі OpenAI Platform](https://platform.openai.com/api-keys). ```bash @@ -85,7 +86,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути openclaw onboard --openai-api-key "$OPENAI_API_KEY" ``` - + ```bash openclaw models list --provider openai ``` @@ -94,16 +95,16 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Route | Auth | |-----------|-------|------| | `openai/gpt-5.4` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.4-mini` | Прямий API OpenAI Platform | `OPENAI_API_KEY` | | `openai/gpt-5.5` | Майбутній прямий маршрут API, щойно OpenAI увімкне GPT-5.5 в API | `OPENAI_API_KEY` | - `openai/*` — це прямий маршрут OpenAI API-key, якщо ви явно не примусите - обв’язку Codex app-server. Сам GPT-5.5 наразі доступний лише через підписку/OAuth; - використовуйте `openai-codex/*` для Codex OAuth через типовий виконавець PI. + `openai/*` — це прямий маршрут OpenAI API через API key, якщо ви явно не + примусите використання harness app-server Codex. Сама GPT-5.5 зараз доступна + лише через підписку/OAuth; використовуйте `openai-codex/*` для Codex OAuth через типовий runner PI. ### Приклад конфігурації @@ -116,13 +117,13 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ``` - OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Реальні запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. + OpenClaw **не** надає `openai/gpt-5.3-codex-spark`. Живі запити до OpenAI API відхиляють цю модель, і поточний каталог Codex також її не надає. - **Найкраще для:** використання підписки ChatGPT/Codex замість окремого API-ключа. Codex cloud потребує входу через ChatGPT. + **Найкраще для:** використання вашої підписки ChatGPT/Codex замість окремого API key. Codex cloud потребує входу через ChatGPT. @@ -136,7 +137,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути openclaw models auth login --provider openai-codex ``` - Для headless-конфігурацій або конфігурацій, де незручно використовувати callback, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість browser callback на localhost: + Для headless-середовищ або налаштувань, де callback працює погано, додайте `--device-code`, щоб увійти через потік device-code ChatGPT замість callback браузера на localhost: ```bash openclaw models auth login --provider openai-codex --device-code @@ -147,7 +148,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути openclaw config set agents.defaults.model.primary openai-codex/gpt-5.5 ``` - + ```bash openclaw models list --provider openai-codex ``` @@ -156,15 +157,15 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ### Підсумок маршруту - | Посилання на модель | Маршрут | Автентифікація | + | Model ref | Route | Auth | |-----------|-------|------| | `openai-codex/gpt-5.5` | ChatGPT/Codex OAuth через PI | вхід Codex | - | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | Обв’язка Codex app-server | автентифікація Codex app-server | + | `openai/gpt-5.5` + `embeddedHarness.runtime: "codex"` | harness app-server Codex | автентифікація app-server Codex | - Продовжуйте використовувати ідентифікатор постачальника `openai-codex` для команд - автентифікації/профілю. Префікс моделі `openai-codex/*` також є явним маршрутом PI для Codex OAuth. - Він не вибирає і не вмикає автоматично вбудовану обв’язку Codex app-server. + Продовжуйте використовувати ідентифікатор провайдера `openai-codex` для команд auth/profile. Префікс моделі + `openai-codex/*` також є явним маршрутом PI для Codex OAuth. + Він не вибирає і не автовмикає вбудований harness app-server Codex. ### Приклад конфігурації @@ -176,29 +177,28 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ``` - Онбординг більше не імпортує матеріали OAuth з `~/.codex`. Увійдіть через browser OAuth (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі автентифікації агентів. + Онбординг більше не імпортує OAuth-матеріали з `~/.codex`. Увійдіть через OAuth у браузері (типово) або через потік device-code вище — OpenClaw керує отриманими обліковими даними у власному сховищі auth агента. - ### Індикатор стану + ### Індикатор статусу - У чаті `/status` показує, яка вбудована обв’язка активна для поточної - сесії. Типова обв’язка PI відображається як `Runner: pi (embedded)` і не - додає окремий бейдж. Коли вибрано вбудовану обв’язку Codex app-server, - `/status` додає ідентифікатор обв’язки не-PI поруч із `Fast`, наприклад - `Fast · codex`. Існуючі сесії зберігають зафіксований ідентифікатор обв’язки, тому використовуйте + Чат `/status` показує, який runtime моделі активний для поточної сесії. + Типовий harness PI відображається як `Runtime: OpenClaw Pi Default`. Коли + вибрано вбудований harness app-server Codex, `/status` показує + `Runtime: OpenAI Codex`. Наявні сесії зберігають записаний ідентифікатор harness, тому використайте `/new` або `/reset` після зміни `embeddedHarness`, якщо хочете, щоб `/status` відображав новий вибір PI/Codex. - ### Обмеження вікна контексту + ### Обмеження контекстного вікна - OpenClaw розглядає метадані моделі та обмеження контексту під час виконання як окремі значення. + OpenClaw розглядає метадані моделі й обмеження контексту runtime як окремі значення. Для `openai-codex/gpt-5.5` через Codex OAuth: - - Нативний `contextWindow`: `1000000` - - Типове обмеження `contextTokens` під час виконання: `272000` + - Власне `contextWindow`: `1000000` + - Типове обмеження runtime `contextTokens`: `272000` - Менше типове обмеження на практиці має кращі характеристики затримки та якості. Ви можете перевизначити його через `contextTokens`: + Менше типове обмеження на практиці дає кращу затримку та якість. Перевизначте його через `contextTokens`: ```json5 { @@ -213,15 +213,15 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ``` - Використовуйте `contextWindow`, щоб оголосити нативні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту під час виконання. + Використовуйте `contextWindow`, щоб оголосити власні метадані моделі. Використовуйте `contextTokens`, щоб обмежити бюджет контексту runtime. ### Відновлення каталогу - OpenClaw використовує метадані вихідного каталогу Codex для `gpt-5.5`, коли вони - присутні. Якщо під час реального виявлення Codex відсутній рядок `openai-codex/gpt-5.5`, - а обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб - Cron, субагент і запуски зі сконфігурованою типовою моделлю не завершувалися помилкою + OpenClaw використовує метадані каталогу upstream Codex для `gpt-5.5`, коли вони + присутні. Якщо живе виявлення Codex пропускає рядок `openai-codex/gpt-5.5`, хоча + обліковий запис автентифіковано, OpenClaw синтезує цей рядок OAuth-моделі, щоб + Cron, субагент і запуски з налаштованою типовою моделлю не завершувалися помилкою `Unknown model`. @@ -230,18 +230,18 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ## Генерація зображень Вбудований Plugin `openai` реєструє генерацію зображень через інструмент `image_generate`. -Він підтримує і генерацію зображень OpenAI за API-ключем, і генерацію зображень -через Codex OAuth з тим самим посиланням на модель `openai/gpt-image-2`. +Він підтримує як генерацію зображень OpenAI через API key, так і генерацію зображень +через Codex OAuth за тим самим посиланням моделі `openai/gpt-image-2`. -| Можливість | API-ключ OpenAI | Codex OAuth | -| ------------------------- | ----------------------------------- | ------------------------------------ | -| Посилання на модель | `openai/gpt-image-2` | `openai/gpt-image-2` | -| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | -| Транспорт | OpenAI Images API | бекенд Codex Responses | -| Максимум зображень на запит | 4 | 4 | +| Можливість | OpenAI API key | Codex OAuth | +| ------------------------- | ---------------------------------- | ------------------------------------ | +| Посилання моделі | `openai/gpt-image-2` | `openai/gpt-image-2` | +| Автентифікація | `OPENAI_API_KEY` | вхід через OpenAI Codex OAuth | +| Транспорт | OpenAI Images API | бекенд Codex Responses | +| Максимум зображень на запит | 4 | 4 | | Режим редагування | Увімкнено (до 5 еталонних зображень) | Увімкнено (до 5 еталонних зображень) | | Перевизначення розміру | Підтримується, включно з розмірами 2K/4K | Підтримується, включно з розмірами 2K/4K | -| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | За можливості безпечно зіставляється з підтримуваним розміром | +| Співвідношення сторін / роздільна здатність | Не передається до OpenAI Images API | Відображається на підтримуваний розмір, коли це безпечно | ```json5 { @@ -254,34 +254,31 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ``` -Див. [Генерація зображень](/uk/tools/image-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover. +Див. [Генерація зображень](/uk/tools/image-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. -`gpt-image-2` є типовим для перетворення тексту на зображення та редагування зображень в OpenAI. -`gpt-image-1` і надалі можна використовувати як явне перевизначення моделі, але для нових -робочих процесів OpenAI із зображеннями слід використовувати `openai/gpt-image-2`. +`gpt-image-2` є типовим значенням як для генерації текст-у-зображення OpenAI, так і для редагування зображень. `gpt-image-1` і далі можна використовувати як явне перевизначення моделі, але нові робочі процеси OpenAI для зображень мають використовувати `openai/gpt-image-2`. -Для інсталяцій із Codex OAuth зберігайте те саме посилання `openai/gpt-image-2`. Коли -налаштовано OAuth-профіль `openai-codex`, OpenClaw знаходить збережений OAuth-токен -доступу та надсилає запити на зображення через бекенд Codex Responses. Він -не намагається спочатку використати `OPENAI_API_KEY` і не виконує тихого fallback до API-ключа для цього -запиту. Налаштуйте `models.providers.openai` явно з API-ключем, -власним базовим URL або кінцевою точкою Azure, якщо хочете використовувати прямий маршрут OpenAI Images API -замість цього. -Якщо ця власна кінцева точка зображень розташована в довіреній LAN/приватній адресі, також установіть -`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і далі -блокує приватні/внутрішні OpenAI-сумісні кінцеві точки зображень, якщо не задано цей явний дозвіл. +Для встановлень із Codex OAuth залишайте те саме посилання `openai/gpt-image-2`. Коли +налаштовано профіль OAuth `openai-codex`, OpenClaw визначає збережений токен +доступу OAuth і надсилає запити на зображення через бекенд Codex Responses. Він +не пробує спочатку `OPENAI_API_KEY` і не переходить мовчки на API key для цього +запиту. Явно налаштуйте `models.providers.openai` з API key, +власним base URL або кінцевою точкою Azure, якщо хочете використовувати прямий маршрут OpenAI Images API. +Якщо ця власна кінцева точка зображень розміщена в довіреній LAN/приватній адресі, також установіть +`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; OpenClaw і далі блокує +приватні/внутрішні сумісні з OpenAI кінцеві точки зображень, якщо немає цього явного дозволу. -Згенерувати: +Генерація: -```text -/tool image_generate model=openai/gpt-image-2 prompt="A polished launch poster for OpenClaw on macOS" size=3840x2160 count=1 +``` +/tool image_generate model=openai/gpt-image-2 prompt="Вишуканий постер запуску OpenClaw на macOS" size=3840x2160 count=1 ``` -Редагувати: +Редагування: -```text -/tool image_generate model=openai/gpt-image-2 prompt="Preserve the object shape, change the material to translucent glass" image=/path/to/reference.png size=1024x1536 +``` +/tool image_generate model=openai/gpt-image-2 prompt="Збережи форму об’єкта, зміни матеріал на напівпрозоре скло" image=/path/to/reference.png size=1024x1536 ``` ## Генерація відео @@ -292,7 +289,7 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути | ---------------- | --------------------------------------------------------------------------------- | | Типова модель | `openai/sora-2` | | Режими | Text-to-video, image-to-video, редагування одного відео | -| Вхідні еталони | 1 зображення або 1 відео | +| Еталонні входи | 1 зображення або 1 відео | | Перевизначення розміру | Підтримується | | Інші перевизначення | `aspectRatio`, `resolution`, `audio`, `watermark` ігноруються з попередженням інструмента | @@ -307,22 +304,22 @@ GPT-5.5 наразі доступний в OpenClaw через маршрути ``` -Див. [Генерація відео](/uk/tools/video-generation), щоб дізнатися про спільні параметри інструмента, вибір постачальника та поведінку failover. +Див. [Генерація відео](/uk/tools/video-generation) для спільних параметрів інструмента, вибору провайдера та поведінки failover. ## Внесок у промпт GPT-5 -OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних постачальників. Він застосовується за ідентифікатором моделі, тому `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують однакове накладання. Старіші моделі GPT-4.x — ні. +OpenClaw додає спільний внесок у промпт GPT-5 для запусків сімейства GPT-5 у різних провайдерів. Він застосовується за ID моделі, тож `openai-codex/gpt-5.5`, `openai/gpt-5.4`, `openrouter/openai/gpt-5.5`, `opencode/gpt-5.5` та інші сумісні посилання GPT-5 отримують той самий шар. Старіші моделі GPT-4.x — ні. -Вбудована нативна обв’язка Codex використовує ту саму поведінку GPT-5 і накладання Heartbeat через інструкції розробника Codex app-server, тому сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі правила доведення до кінця та проактивного Heartbeat, навіть якщо рештою промпту обв’язки керує Codex. +Вбудований власний harness Codex використовує ту саму поведінку GPT-5 і шар Heartbeat через інструкції розробника app-server Codex, тож сесії `openai/gpt-5.x`, примусово спрямовані через `embeddedHarness.runtime: "codex"`, зберігають ті самі вказівки щодо доведення до кінця й проактивного Heartbeat, хоча рештою промпта harness керує Codex. -Внесок GPT-5 додає позначений контракт поведінки для збереження персони, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Специфічна для каналу поведінка відповідей і тихих повідомлень залишається у спільному системному промпті OpenClaw і політиці вихідної доставки. Правила GPT-5 завжди ввімкнені для відповідних моделей. Дружній стиль взаємодії — окремий і налаштовуваний шар. +Внесок GPT-5 додає контракт поведінки з тегами для збереження персони, безпеки виконання, дисципліни використання інструментів, форми виводу, перевірок завершення та верифікації. Поведінка відповідей для конкретних каналів і поведінка тихих повідомлень залишаються в спільному системному промпті OpenClaw і політиці вихідної доставки. Вказівки GPT-5 завжди ввімкнені для відповідних моделей. Шар дружнього стилю взаємодії є окремим і налаштовуваним. -| Значення | Ефект | -| --------------------- | ------------------------------------------ | -| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | -| `"on"` | Псевдонім для `"friendly"` | -| `"off"` | Вимкнути лише шар дружнього стилю | +| Значення | Ефект | +| ---------------------- | ---------------------------------------------- | +| `"friendly"` (типово) | Увімкнути шар дружнього стилю взаємодії | +| `"on"` | Псевдонім для `"friendly"` | +| `"off"` | Вимкнути лише шар дружнього стилю | @@ -346,11 +343,11 @@ OpenClaw додає спільний внесок у промпт GPT-5 для -Значення під час виконання нечутливі до регістру, тому і `"Off"`, і `"off"` вимикають шар дружнього стилю. +Під час runtime значення не чутливі до регістру, тож і `"Off"`, і `"off"` вимикають шар дружнього стилю. -Застаріле `plugins.entries.openai.config.personality` і далі зчитується як fallback для сумісності, якщо спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. +Застаріле `plugins.entries.openai.config.personality` і далі читається як резервне значення для сумісності, коли спільне налаштування `agents.defaults.promptOverlays.gpt5.personality` не задано. ## Голос і мовлення @@ -359,14 +356,14 @@ OpenClaw додає спільний внесок у промпт GPT-5 для Вбудований Plugin `openai` реєструє синтез мовлення для поверхні `messages.tts`. - | Налаштування | Шлях конфігурації | Типово | + | Параметр | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `messages.tts.providers.openai.model` | `gpt-4o-mini-tts` | | Голос | `messages.tts.providers.openai.voice` | `coral` | | Швидкість | `messages.tts.providers.openai.speed` | (не задано) | | Інструкції | `messages.tts.providers.openai.instructions` | (не задано, лише `gpt-4o-mini-tts`) | - | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових повідомлень, `mp3` для файлів | - | API-ключ | `messages.tts.providers.openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | + | Формат | `messages.tts.providers.openai.responseFormat` | `opus` для голосових нотаток, `mp3` для файлів | + | API key | `messages.tts.providers.openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | | Base URL | `messages.tts.providers.openai.baseUrl` | `https://api.openai.com/v1` | Доступні моделі: `gpt-4o-mini-tts`, `tts-1`, `tts-1-hd`. Доступні голоси: `alloy`, `ash`, `ballad`, `cedar`, `coral`, `echo`, `fable`, `juniper`, `marin`, `onyx`, `nova`, `sage`, `shimmer`, `verse`. @@ -384,23 +381,23 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ``` - Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку chat API. + Установіть `OPENAI_TTS_BASE_URL`, щоб перевизначити базовий URL TTS без впливу на кінцеву точку чат-API. - + Вбудований Plugin `openai` реєструє пакетне перетворення мовлення на текст через - поверхню транскрибування для розуміння медіа в OpenClaw. + поверхню транскрипції для розуміння медіа в OpenClaw. - Типова модель: `gpt-4o-transcribe` - Кінцева точка: OpenAI REST `/v1/audio/transcriptions` - - Вхідний шлях: завантаження аудіофайлу multipart - - Підтримується в OpenClaw всюди, де для транскрибування вхідного аудіо використовується + - Шлях введення: multipart-завантаження аудіофайла + - Підтримується в OpenClaw всюди, де транскрипція вхідного аудіо використовує `tools.media.audio`, включно з сегментами голосових каналів Discord і аудіовкладеннями каналів - Щоб примусово використовувати OpenAI для транскрибування вхідного аудіо: + Щоб примусово використовувати OpenAI для транскрипції вхідного аудіо: ```json5 { @@ -420,43 +417,43 @@ OpenClaw додає спільний внесок у промпт GPT-5 для } ``` - Підказки мови та промпту передаються в OpenAI, коли вони надані - спільною конфігурацією аудіомедіа або запитом транскрибування для окремого виклику. + Підказки мови та промпта пересилаються до OpenAI, коли їх задає + спільна конфігурація аудіомедіа або запит на транскрипцію для конкретного виклику. - - Вбудований Plugin `openai` реєструє транскрибування в реальному часі для Plugin Voice Call. + + Вбудований Plugin `openai` реєструє транскрипцію в realtime для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Параметр | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.streaming.providers.openai.model` | `gpt-4o-transcribe` | | Мова | `...openai.language` | (не задано) | | Промпт | `...openai.prompt` | (не задано) | | Тривалість тиші | `...openai.silenceDurationMs` | `800` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | - | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | + | API key | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | - Використовує з’єднання WebSocket із `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей постачальник потокової обробки призначений для шляху транскрибування в реальному часі в Voice Call; голос у Discord наразі натомість записує короткі сегменти та використовує пакетний шлях транскрибування `tools.media.audio`. + Використовує підключення WebSocket до `wss://api.openai.com/v1/realtime` з аудіо G.711 u-law (`g711_ulaw` / `audio/pcmu`). Цей потоковий провайдер призначений для шляху транскрипції в realtime у Voice Call; голос Discord наразі записує короткі сегменти та замість цього використовує пакетний шлях транскрипції `tools.media.audio`. - - Вбудований Plugin `openai` реєструє голос у реальному часі для Plugin Voice Call. + + Вбудований Plugin `openai` реєструє голос у realtime для Plugin Voice Call. - | Налаштування | Шлях конфігурації | Типово | + | Параметр | Шлях конфігурації | Типове значення | |---------|------------|---------| | Модель | `plugins.entries.voice-call.config.realtime.providers.openai.model` | `gpt-realtime-1.5` | | Голос | `...openai.voice` | `alloy` | | Temperature | `...openai.temperature` | `0.8` | | Поріг VAD | `...openai.vadThreshold` | `0.5` | | Тривалість тиші | `...openai.silenceDurationMs` | `500` | - | API-ключ | `...openai.apiKey` | Використовує `OPENAI_API_KEY` як fallback | + | API key | `...openai.apiKey` | Використовує резервне значення `OPENAI_API_KEY` | - Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двобічний виклик інструментів. Використовує аудіоформат G.711 u-law. + Підтримує Azure OpenAI через ключі конфігурації `azureEndpoint` і `azureDeployment`. Підтримує двосторонній виклик інструментів. Використовує формат аудіо G.711 u-law. @@ -464,28 +461,27 @@ OpenClaw додає спільний внесок у промпт GPT-5 для ## Кінцеві точки Azure OpenAI -Вбудований постачальник `openai` може спрямовувати генерацію зображень на ресурс Azure OpenAI -через перевизначення базового URL. На шляху генерації зображень OpenClaw -виявляє імена хостів Azure у `models.providers.openai.baseUrl` і автоматично +Вбудований провайдер `openai` може націлюватися на ресурс Azure OpenAI для +генерації зображень через перевизначення base URL. На шляху генерації зображень OpenClaw +визначає імена хостів Azure в `models.providers.openai.baseUrl` і автоматично перемикається на формат запиту Azure. -Голос у реальному часі використовує окремий шлях конфігурації +Голос у realtime використовує окремий шлях конфігурації (`plugins.entries.voice-call.config.realtime.providers.openai.azureEndpoint`) -і на нього не впливає `models.providers.openai.baseUrl`. Див. акордеон **Голос -у реальному часі** в розділі [Голос і мовлення](#voice-and-speech), щоб дізнатися про налаштування Azure -для нього. +і не залежить від `models.providers.openai.baseUrl`. Див. акордеон **Голос у realtime** +в розділі [Голос і мовлення](#voice-and-speech) для його параметрів Azure. Використовуйте Azure OpenAI, коли: -- У вас уже є підписка Azure OpenAI, квота або корпоративна угода -- Вам потрібна регіональна резидентність даних або засоби відповідності вимогам, які надає Azure -- Ви хочете залишити трафік у межах наявного tenancy Azure +- У вас уже є підписка, квота або корпоративна угода Azure OpenAI +- Вам потрібне регіональне розміщення даних або засоби відповідності, які надає Azure +- Ви хочете зберігати трафік у межах наявного середовища Azure ### Конфігурація -Для генерації зображень через Azure у вбудованому постачальнику `openai` укажіть +Для генерації зображень Azure через вбудований провайдер `openai` вкажіть `models.providers.openai.baseUrl` на ваш ресурс Azure і встановіть `apiKey` як ключ Azure OpenAI (а не ключ OpenAI Platform): @@ -511,90 +507,89 @@ OpenClaw розпізнає такі суфікси хостів Azure для м Для запитів генерації зображень на розпізнаному хості Azure OpenClaw: - Надсилає заголовок `api-key` замість `Authorization: Bearer` -- Використовує шляхи в межах deployment (`/openai/deployments/{deployment}/...`) +- Використовує шляхи, прив’язані до розгортання (`/openai/deployments/{deployment}/...`) - Додає `?api-version=...` до кожного запиту -Інші базові URL (публічний OpenAI, OpenAI-сумісні проксі) зберігають стандартний +Інші base URL (публічний OpenAI, сумісні з OpenAI проксі) зберігають стандартний формат запиту зображень OpenAI. -Маршрутизація Azure для шляху генерації зображень постачальника `openai` -потребує OpenClaw 2026.4.22 або новішої версії. Попередні версії трактують будь-який власний -`openai.baseUrl` так само, як публічну кінцеву точку OpenAI, і не працюватимуть з deployment генерації -зображень у Azure. +Маршрутизація Azure для шляху генерації зображень провайдера `openai` потребує +OpenClaw 2026.4.22 або новішої версії. Раніші версії трактують будь-який власний +`openai.baseUrl` як публічну кінцеву точку OpenAI і не працюватимуть із розгортаннями зображень Azure. ### Версія API -Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview або GA-версію Azure +Установіть `AZURE_OPENAI_API_VERSION`, щоб зафіксувати конкретну preview- або GA-версію Azure для шляху генерації зображень Azure: ```bash export AZURE_OPENAI_API_VERSION="2024-12-01-preview" ``` -Типове значення — `2024-12-01-preview`, якщо змінну не задано. +Типове значення — `2024-12-01-preview`, якщо змінну не встановлено. -### Назви моделей — це назви deployment +### Назви моделей — це назви розгортань -Azure OpenAI прив’язує моделі до deployment. Для запитів генерації зображень Azure, -спрямованих через вбудований постачальник `openai`, поле `model` в OpenClaw -має бути **назвою deployment Azure**, яку ви налаштували в порталі Azure, а не -публічним ідентифікатором моделі OpenAI. +Azure OpenAI прив’язує моделі до розгортань. Для запитів генерації зображень Azure, +маршрутизованих через вбудований провайдер `openai`, поле `model` в OpenClaw +має бути **назвою розгортання Azure**, яку ви налаштували в порталі Azure, а не +публічним ID моделі OpenAI. -Якщо ви створили deployment з назвою `gpt-image-2-prod`, який обслуговує `gpt-image-2`: +Якщо ви створили розгортання з назвою `gpt-image-2-prod`, яке обслуговує `gpt-image-2`: -```text -/tool image_generate model=openai/gpt-image-2-prod prompt="A clean poster" size=1024x1024 count=1 +``` +/tool image_generate model=openai/gpt-image-2-prod prompt="Чистий постер" size=1024x1024 count=1 ``` -Те саме правило назви deployment застосовується до викликів генерації зображень, спрямованих через -вбудований постачальник `openai`. +Те саме правило назв розгортань застосовується до викликів генерації зображень, +маршрутизованих через вбудований провайдер `openai`. ### Регіональна доступність -Генерація зображень у Azure зараз доступна лише в частині регіонів +Генерація зображень Azure зараз доступна лише в частині регіонів (наприклад, `eastus2`, `swedencentral`, `polandcentral`, `westus3`, -`uaenorth`). Перевірте актуальний список регіонів Microsoft перед створенням -deployment і переконайтеся, що потрібна модель доступна у вашому регіоні. +`uaenorth`). Перш ніж створювати розгортання, перевірте актуальний список регіонів Microsoft +і підтвердьте, що конкретна модель доступна у вашому регіоні. ### Відмінності параметрів Azure OpenAI і публічний OpenAI не завжди приймають однакові параметри зображень. -Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, певні -значення `background` для `gpt-image-2`), або надавати їх лише для певних версій -моделі. Ці відмінності походять від Azure та базової моделі, а не від +Azure може відхиляти параметри, які дозволяє публічний OpenAI (наприклад, деякі +значення `background` для `gpt-image-2`) або надавати їх лише для певних +версій моделей. Ці відмінності походять від Azure та базової моделі, а не від OpenClaw. Якщо запит Azure завершується помилкою валідації, перевірте -набір параметрів, які підтримує саме ваш deployment і версія API, у +набір параметрів, який підтримує саме ваше розгортання та версія API в порталі Azure. -Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує -приховані заголовки атрибуції OpenClaw — див. акордеон **Нативні маршрути та OpenAI-сумісні -маршрути** в розділі [Розширена конфігурація](#advanced-configuration). +Azure OpenAI використовує власний транспорт і сумісну поведінку, але не отримує +прихованих заголовків атрибуції OpenClaw — див. акордеон **Власні маршрути vs OpenAI-compatible +routes** у розділі [Розширена конфігурація](#advanced-configuration). -Для трафіку chat або Responses на Azure (окрім генерації зображень) використовуйте -потік онбордингу або окрему конфігурацію постачальника Azure — одного лише -`openai.baseUrl` недостатньо, щоб застосувати форму API/автентифікації Azure. Існує -окремий постачальник `azure-openai-responses/*`; див. -акордеон про серверний Compaction нижче. +Для трафіку чату або Responses в Azure (окрім генерації зображень) використовуйте +процес онбордингу або окрему конфігурацію провайдера Azure — одного лише +`openai.baseUrl` недостатньо, щоб застосувати формат API/автентифікації Azure. Існує окремий +провайдер `azure-openai-responses/*`; див. +акордеон Server-side Compaction нижче. ## Розширена конфігурація - OpenClaw використовує WebSocket-first із fallback до SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. + OpenClaw використовує спочатку WebSocket із резервним переходом на SSE (`"auto"`) як для `openai/*`, так і для `openai-codex/*`. У режимі `"auto"` OpenClaw: - - Повторює одну ранню помилку WebSocket перед переходом до SSE - - Після помилки позначає WebSocket як деградований приблизно на 60 секунд і використовує SSE під час цього періоду охолодження - - Додає стабільні заголовки ідентифікації сесії та ходу для повторних спроб і перепідключень - - Нормалізує лічильники використання (`input_tokens` / `prompt_tokens`) між варіантами транспорту + - Повторює одну ранню помилку WebSocket перед переходом на SSE + - Після помилки позначає WebSocket як degraded приблизно на 60 секунд і використовує SSE під час періоду охолодження + - Додає стабільні заголовки ідентичності сесії та ходу для повторних спроб і повторних підключень + - Нормалізує лічильники usage (`input_tokens` / `prompt_tokens`) між варіантами транспорту | Значення | Поведінка | |-------|----------| - | `"auto"` (типово) | Спочатку WebSocket, fallback до SSE | + | `"auto"` (типово) | Спочатку WebSocket, резервний перехід на SSE | | `"sse"` | Примусово лише SSE | | `"websocket"` | Примусово лише WebSocket | @@ -621,11 +616,11 @@ Azure OpenAI використовує нативний транспорт і п - - OpenClaw типово вмикає прогрівання WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. + + OpenClaw типово вмикає попередній прогрів WebSocket для `openai/*` і `openai-codex/*`, щоб зменшити затримку першого ходу. ```json5 - // Вимкнути прогрівання + // Disable warm-up { agents: { defaults: { @@ -644,8 +639,8 @@ Azure OpenAI використовує нативний транспорт і п OpenClaw надає спільний перемикач швидкого режиму для `openai/*` і `openai-codex/*`: - - **Chat/UI:** `/fast status|on|off` - - **Config:** `agents.defaults.models["/"].params.fastMode` + - **Чат/UI:** `/fast status|on|off` + - **Конфігурація:** `agents.defaults.models["/"].params.fastMode` Коли його ввімкнено, OpenClaw зіставляє швидкий режим із пріоритетною обробкою OpenAI (`service_tier = "priority"`). Наявні значення `service_tier` зберігаються, а швидкий режим не переписує `reasoning` або `text.verbosity`. @@ -662,7 +657,7 @@ Azure OpenAI використовує нативний транспорт і п ``` - Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI сесій повертає сесію до типового налаштованого значення. + Перевизначення сесії мають пріоритет над конфігурацією. Очищення перевизначення сесії в UI сесій повертає сесію до налаштованого типового значення. @@ -685,23 +680,23 @@ Azure OpenAI використовує нативний транспорт і п Підтримувані значення: `auto`, `default`, `flex`, `priority`. - `serviceTier` передається лише до нативних кінцевих точок OpenAI (`api.openai.com`) і нативних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих постачальників через проксі, OpenClaw залишає `service_tier` без змін. + `serviceTier` пересилається лише до власних кінцевих точок OpenAI (`api.openai.com`) і власних кінцевих точок Codex (`chatgpt.com/backend-api`). Якщо ви маршрутизуєте будь-якого з цих провайдерів через проксі, OpenClaw залишає `service_tier` без змін. - - Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) обгортка потоку Pi-harness Plugin OpenAI автоматично вмикає серверний Compaction: + + Для прямих моделей OpenAI Responses (`openai/*` на `api.openai.com`) поточна обгортка stream Pi-harness Plugin OpenAI автоматично вмикає server-side Compaction: - - Примусово встановлює `store: true` (якщо лише сумісність моделі не задає `supportsStore: false`) - - Впроваджує `context_management: [{ type: "compaction", compact_threshold: ... }]` + - Примусово встановлює `store: true` (якщо сумісність моделі не задає `supportsStore: false`) + - Вставляє `context_management: [{ type: "compaction", compact_threshold: ... }]` - Типовий `compact_threshold`: 70% від `contextWindow` (або `80000`, якщо значення недоступне) - Це застосовується до вбудованого шляху Pi harness і до хуків постачальника OpenAI, які використовуються вбудованими запусками. Нативна обв’язка Codex app-server керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. + Це застосовується до вбудованого шляху Pi harness і до hook провайдера OpenAI, які використовуються в embedded-запусках. Власний harness app-server Codex керує власним контекстом через Codex і налаштовується окремо через `agents.defaults.embeddedHarness.runtime`. - - Корисно для сумісних кінцевих точок, як-от Azure OpenAI Responses: + + Корисно для сумісних кінцевих точок, таких як Azure OpenAI Responses: ```json5 { @@ -735,7 +730,7 @@ Azure OpenAI використовує нативний транспорт і п } ``` - + ```json5 { agents: { @@ -753,13 +748,13 @@ Azure OpenAI використовує нативний транспорт і п - `responsesServerCompaction` керує лише впровадженням `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо лише сумісність не задає `supportsStore: false`. + `responsesServerCompaction` керує лише вставкою `context_management`. Прямі моделі OpenAI Responses і далі примусово встановлюють `store: true`, якщо сумісність не задає `supportsStore: false`. - Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший вбудований контракт виконання: + Для запусків сімейства GPT-5 на `openai/*` OpenClaw може використовувати суворіший embedded-контракт виконання: ```json5 { @@ -771,33 +766,33 @@ Azure OpenAI використовує нативний транспорт і п } ``` - З `strict-agentic` OpenClaw: - - Більше не вважає хід лише з планом успішним прогресом, якщо доступна дія через інструмент + Із `strict-agentic` OpenClaw: + - Більше не вважає хід лише з планом успішним прогресом, коли доступна дія інструмента - Повторює хід із вказівкою діяти негайно - Автоматично вмикає `update_plan` для суттєвої роботи - - Показує явний заблокований стан, якщо модель продовжує планувати без дій + - Показує явний заблокований стан, якщо модель продовжує планувати без дії - Обмежено лише запусками сімейства GPT-5 OpenAI і Codex. Інші постачальники та старіші сімейства моделей зберігають типову поведінку. + Обмежено лише запусками OpenAI та Codex сімейства GPT-5. Інші провайдери й старіші сімейства моделей зберігають типову поведінку. - - OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-сумісні проксі `/v1`: + + OpenClaw по-різному обробляє прямі кінцеві точки OpenAI, Codex і Azure OpenAI та загальні OpenAI-compatible проксі `/v1`: - **Нативні маршрути** (`openai/*`, Azure OpenAI): - - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` effort + **Власні маршрути** (`openai/*`, Azure OpenAI): + - Зберігають `reasoning: { effort: "none" }` лише для моделей, які підтримують OpenAI `none` для effort - Пропускають вимкнене reasoning для моделей або проксі, які відхиляють `reasoning.effort: "none"` - - Типово використовують строгий режим для схем інструментів - - Додають приховані заголовки атрибуції лише на перевірених нативних хостах - - Зберігають формування запитів, характерне лише для OpenAI (`service_tier`, `store`, reasoning-compat, підказки кешу промптів) + - Типово використовують суворий режим для схем інструментів + - Додають приховані заголовки атрибуції лише на перевірених власних хостах + - Зберігають формування запитів лише для OpenAI (`service_tier`, `store`, сумісність reasoning, підказки кешу промптів) - **Маршрути проксі/сумісності:** - - Використовують менш строгі правила сумісності - - Не примушують строгі схеми інструментів або заголовки, доступні лише для нативних маршрутів + **Проксі/сумісні маршрути:** + - Використовують м’якшу сумісну поведінку + - Не примушують суворі схеми інструментів або заголовки лише для власних маршрутів - Azure OpenAI використовує нативний транспорт і поведінку сумісності, але не отримує приховані заголовки атрибуції. + Azure OpenAI використовує власний транспорт і сумісну поведінку, але не отримує прихованих заголовків атрибуції. @@ -806,15 +801,15 @@ Azure OpenAI використовує нативний транспорт і п - Вибір постачальників, посилань на моделі та поведінки failover. + Вибір провайдерів, посилань моделей і поведінки failover. - Спільні параметри інструмента зображень і вибір постачальника. + Спільні параметри інструмента зображень і вибір провайдера. - Спільні параметри інструмента відео та вибір постачальника. + Спільні параметри інструмента відео і вибір провайдера. - - Докладно про автентифікацію та правила повторного використання облікових даних. + + Подробиці auth і правила повторного використання облікових даних. diff --git a/docs/uk/reference/test.md b/docs/uk/reference/test.md index c2163158d..bfba8294f 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-24T22:51:37Z" + generated_at: "2026-04-25T00:03:42Z" model: gpt-5.4 provider: openai - source_hash: f15e68a95d68dd076862aa168a836c4918876afa1f925ed183f7fde8ec75f24a + source_hash: 91009b51cee872f542a9aed0f882359c763cfb88722860eb8ef7deae434a89e7 source_path: reference/test.md workflow: 15 --- -- Повний набір для тестування (сьюти, live, Docker): [Тестування](/uk/help/testing) +- Повний набір для тестування (с’юти, live, Docker): [Тестування](/uk/help/testing) -- `pnpm test:force`: Завершує будь-який завислий процес gateway, який утримує типовий порт керування, а потім запускає повний набір Vitest з ізольованим портом gateway, щоб серверні тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим порт 18789. -- `pnpm test:coverage`: Запускає набір unit-тестів з V8 coverage (через `vitest.unit.config.ts`). Це перевірка unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, перевірка вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен файл вихідного коду з розбитих lane непокритим. +- `pnpm test:force`: Завершує будь-який gateway process, що залишився і тримає стандартний control port, а потім запускає повний набір Vitest з ізольованим port gateway, щоб server-тести не конфліктували із запущеним екземпляром. Використовуйте це, коли попередній запуск gateway залишив зайнятим port 18789. +- `pnpm test:coverage`: Запускає unit-набір із V8 coverage (через `vitest.unit.config.ts`). Це gate unit coverage для завантажених файлів, а не coverage всіх файлів у всьому репозиторії. Порогові значення: 70% для lines/functions/statements і 55% для branches. Оскільки `coverage.all` має значення false, gate вимірює файли, завантажені набором unit coverage, замість того щоб вважати кожен source file із розділених lane-ів непокритим. - `pnpm test:coverage:changed`: Запускає unit coverage лише для файлів, змінених відносно `origin/main`. -- `pnpm test:changed`: розгортає змінені git-шляхи у scoped lane Vitest, коли diff зачіпає лише routable файли коду/тестів. Зміни конфігурації/налаштування все одно повертаються до нативного запуску root project, щоб за потреби правки wiring перезапускали ширший набір. -- `pnpm changed:lanes`: показує архітектурні lane, які запускаються diff відносно `origin/main`. -- `pnpm check:changed`: запускає розумну changed-перевірку для diff відносно `origin/main`. Вона запускає core-роботи з lane core-тестів, extension-роботи з lane extension-тестів, test-only зміни лише з test typecheck/tests, розширює зміни публічного Plugin SDK або plugin-contract до одного проходу валідації extension і залишає підвищення версій лише в release metadata на цільових перевірках version/config/root-dependency. -- `pnpm test`: маршрутизує явні цілі файлів/каталогів через scoped lane Vitest. Запуски без цілей використовують фіксовані shard-групи та розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до per-extension shard config, а не до одного великого процесу root project. -- Повні запуски та запуски shard extension оновлюють локальні дані таймінгів у `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги для балансування повільних і швидких shard. Встановіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. -- Вибрані тестові файли `plugin-sdk` і `commands` тепер маршрутизуються через окремі легкі lane, які зберігають лише `test/setup.ts`, залишаючи runtime-важкі випадки у наявних lane. -- Вибрані допоміжні файли коду `plugin-sdk` і `commands` також відображають `pnpm test:changed` на явні сусідні тести в цих легких lane, тому невеликі правки helper не змушують перезапускати важкі набори з підтримкою runtime. -- `auto-reply` тепер також розбивається на три окремі config (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими top-level тестами status/token/helper. -- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнений у всіх конфігураціях репозиторію. +- `pnpm test:changed`: розгортає змінені git paths у scoped Vitest lanes, коли diff зачіпає лише routable source/test files. Зміни config/setup і далі переходять до нативного запуску root projects, щоб зміни wiring за потреби повторно запускали ширший набір перевірок. +- `pnpm changed:lanes`: показує архітектурні lanes, що спрацьовують для diff відносно `origin/main`. +- `pnpm check:changed`: запускає розумний changed gate для diff відносно `origin/main`. Він запускає роботу core разом із core test lanes, роботу extension — з extension test lanes, зміни лише в тестах — лише з test typecheck/tests, розширює зміни в публічному Plugin SDK або plugin-contract до одного проходу валідації extension і залишає підвищення версії лише в release metadata на цільових перевірках version/config/root-dependency. +- `pnpm test`: маршрутизує явно вказані цілі file/directory через scoped Vitest lanes. Запуски без цілей використовують фіксовані shard groups і розгортаються до leaf configs для локального паралельного виконання; група extension завжди розгортається до shard configs для окремих extension, а не до одного гігантського процесу root-project. +- Повні запуски і запуски shard-ів extension оновлюють локальні дані часу в `.artifacts/vitest-shard-timings.json`; наступні запуски використовують ці таймінги, щоб балансувати повільні й швидкі shard-и. Установіть `OPENCLAW_TEST_PROJECTS_TIMINGS=0`, щоб ігнорувати локальний артефакт таймінгів. +- Вибрані test files `plugin-sdk` і `commands` тепер маршрутизуються через спеціальні легкі lanes, які залишають лише `test/setup.ts`, а випадки з важчим runtime залишаються у своїх наявних lanes. +- Вибрані helper source files `plugin-sdk` і `commands` також зіставляють `pnpm test:changed` з явними сусідніми tests у цих легких lanes, щоб невеликі зміни helper-ів не спричиняли повторний запуск важких наборів, що залежать від runtime. +- `auto-reply` тепер також розділяється на три окремі configs (`core`, `top-level`, `reply`), щоб harness reply не домінував над легшими tests верхнього рівня для status/token/helper. +- Базова конфігурація Vitest тепер за замовчуванням використовує `pool: "threads"` і `isolate: false`, а спільний неізольований runner увімкнено в усьому наборі configs репозиторію. - `pnpm test:channels` запускає `vitest.channels.config.ts`. -- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard extension/plugin. Важкі channel plugins, browser plugin і OpenAI запускаються як окремі shard; інші групи plugin залишаються згрупованими. Використовуйте `pnpm test extensions/` для однієї bundled lane plugin. -- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпорту та деталізацію імпорту, при цьому все ще використовує маршрутизацію scoped lane для явних цілей файлів/каталогів. -- `pnpm test:perf:imports:changed`: те саме профілювання імпорту, але лише для файлів, змінених відносно `origin/main`. -- `pnpm test:perf:changed:bench -- --ref ` виконує benchmark маршрутизованого шляху changed-mode проти нативного запуску root project для того самого закоміченого git diff. -- `pnpm test:perf:changed:bench -- --worktree` виконує benchmark поточного набору змін у worktree без попереднього коміту. -- `pnpm test:perf:profile:main`: записує CPU profile для головного потоку Vitest (`.artifacts/vitest-main-profile`). +- `pnpm test:extensions` і `pnpm test extensions` запускають усі shard-и extension/plugin. Важкі channel plugins, plugin browser і OpenAI запускаються як окремі shard-и; інші групи plugin-ів залишаються згрупованими. Використовуйте `pnpm test extensions/` для одного lane bundled plugin. +- `pnpm test:perf:imports`: вмикає звітність Vitest про тривалість імпортів і import-breakdown, при цьому й надалі використовує scoped lane routing для явно вказаних цілей file/directory. +- `pnpm test:perf:imports:changed`: те саме профілювання імпортів, але лише для файлів, змінених відносно `origin/main`. +- `pnpm test:perf:changed:bench -- --ref ` порівнює у режимі benchmark маршрутизований шлях changed-mode з нативним запуском root-project для того самого закоміченого git diff. +- `pnpm test:perf:changed:bench -- --worktree` порівнює у режимі benchmark поточний набір змін у worktree без попереднього коміту. +- `pnpm test:perf:profile:main`: записує CPU profile для main thread Vitest (`.artifacts/vitest-main-profile`). - `pnpm test:perf:profile:runner`: записує CPU + heap profiles для unit runner (`.artifacts/vitest-runner-profile`). -- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожну leaf config Vitest повного набору та записує згруповані дані тривалості разом з JSON/log-артефактами для кожної config. Агент продуктивності тестів використовує це як базову лінію перед спробами виправлення повільних тестів. +- `pnpm test:perf:groups --full-suite --allow-failures --output .artifacts/test-perf/baseline-before.json`: послідовно запускає кожен leaf config Vitest для повного набору і записує згруповані дані тривалості плюс JSON/log-артефакти для кожного config. Test Performance Agent використовує це як baseline перед спробою виправити повільні тести. - `pnpm test:perf:groups:compare .artifacts/test-perf/baseline-before.json .artifacts/test-perf/after-agent.json`: порівнює згруповані звіти після змін, спрямованих на продуктивність. -- Інтеграція Gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. -- `pnpm test:e2e`: Запускає smoke-тести gateway end-to-end (pairing кількох екземплярів WS/HTTP/node). За замовчуванням використовує `threads` + `isolate: false` з адаптивною кількістю worker у `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` через зважений планувальник. `OPENCLAW_DOCKER_ALL_PARALLELISM=` керує кількістю слотів процесів і за замовчуванням дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` керує чутливим до провайдера tail pool і за замовчуванням теж дорівнює 10. Обмеження для важких lane за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=4`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=4` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=5`; використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` для більших хостів. Запуски lane за замовчуванням відтерміновуються на 2 секунди, щоб уникати локальних сплесків створення контейнерів у Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner за замовчуванням виконує попередню перевірку Docker, очищує застарілі контейнери OpenClaw E2E, виводить статус активних lane кожні 30 секунд і зберігає таймінги lane у `.artifacts/docker-tests/lane-timings.json` для впорядкування за принципом longest-first у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб вивести manifest lane без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` для налаштування виводу статусу або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання таймінгів. Runner припиняє планувати нові pooled lane після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, а кожна lane має резервний timeout у 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lane використовують жорсткіші ліміти для кожної 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`: Запускає seeded контейнер Gateway і другий клієнтський контейнер, який запускає `openclaw mcp serve`, а потім перевіряє routed discovery розмов, читання transcript, metadata вкладень, поведінку live event queue, маршрутизацію outbound send і сповіщення каналу + дозволів у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає необроблені stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально надсилає. +- Інтеграція gateway: вмикається через `OPENCLAW_TEST_INCLUDE_GATEWAY=1 pnpm test` або `pnpm test:gateway`. +- `pnpm test:e2e`: Запускає gateway end-to-end smoke-тести (pairing multi-instance WS/HTTP/node). За замовчуванням використовує `threads` + `isolate: false` з adaptive workers у `vitest.e2e.config.ts`; налаштовуйте через `OPENCLAW_E2E_WORKERS=` і встановлюйте `OPENCLAW_E2E_VERBOSE=1` для докладних логів. +- `pnpm test:live`: Запускає live-тести provider-ів (minimax/zai). Потрібні API keys і `LIVE=1` (або специфічне для provider `*_LIVE_TEST=1`), щоб зняти пропуск. +- `pnpm test:docker:all`: Один раз збирає спільний live-test image і Docker E2E image, а потім запускає Docker smoke lanes з `OPENCLAW_SKIP_DOCKER_BUILD=1` через зважений scheduler. `OPENCLAW_DOCKER_ALL_PARALLELISM=` керує слотами process і за замовчуванням дорівнює 10; `OPENCLAW_DOCKER_ALL_TAIL_PARALLELISM=` керує tail pool, чутливим до provider, і також за замовчуванням дорівнює 10. Обмеження для важких lanes за замовчуванням: `OPENCLAW_DOCKER_ALL_LIVE_LIMIT=6`, `OPENCLAW_DOCKER_ALL_NPM_LIMIT=8` і `OPENCLAW_DOCKER_ALL_SERVICE_LIMIT=7`; використовуйте `OPENCLAW_DOCKER_ALL_WEIGHT_LIMIT` або `OPENCLAW_DOCKER_ALL_DOCKER_LIMIT` для більших хостів. Запуски lanes за замовчуванням зсуваються на 2 секунди, щоб уникнути локальних сплесків create-операцій Docker daemon; перевизначайте через `OPENCLAW_DOCKER_ALL_START_STAGGER_MS=`. Runner за замовчуванням виконує preflight для Docker, очищає застарілі OpenClaw E2E containers, виводить status активних lanes кожні 30 секунд і зберігає таймінги lanes у `.artifacts/docker-tests/lane-timings.json` для впорядкування за принципом longest-first у наступних запусках. Використовуйте `OPENCLAW_DOCKER_ALL_DRY_RUN=1`, щоб надрукувати маніфест lanes без запуску Docker, `OPENCLAW_DOCKER_ALL_STATUS_INTERVAL_MS=` для налаштування виводу status, або `OPENCLAW_DOCKER_ALL_TIMINGS=0`, щоб вимкнути повторне використання таймінгів. Runner припиняє планування нових pooled lanes після першої помилки, якщо не встановлено `OPENCLAW_DOCKER_ALL_FAIL_FAST=0`, і кожен lane має резервний тайм-аут 120 хвилин, який можна перевизначити через `OPENCLAW_DOCKER_ALL_LANE_TIMEOUT_MS`; окремі live/tail lanes використовують жорсткіші обмеження для кожного lane. Логи для кожного lane записуються в `.artifacts/docker-tests//`. +- `pnpm test:docker:openwebui`: Запускає Dockerized OpenClaw + Open WebUI, входить через Open WebUI, перевіряє `/api/models`, а потім виконує реальний проксований чат через `/api/chat/completions`. Потребує придатного ключа live-моделі (наприклад, OpenAI у `~/.profile`), завантажує зовнішній image Open WebUI і не вважається настільки стабільним для CI, як звичайні unit/e2e suites. +- `pnpm test:docker:mcp-channels`: Запускає seeded Gateway container і другий client container, який запускає `openclaw mcp serve`, а потім перевіряє routed conversation discovery, читання transcript, metadata вкладень, поведінку live event queue, маршрутизацію вихідного надсилання та сповіщення про channel + permissions у стилі Claude через реальний міст stdio. Перевірка сповіщень Claude читає сирі stdio MCP frames безпосередньо, щоб smoke відображав те, що міст реально надсилає. -## Локальна PR-перевірка +## Локальний PR gate -Для локальних перевірок перед злиттям/гейтом PR запустіть: +Для локальних перевірок перед злиттям PR/gate запускайте: - `pnpm check:changed` - `pnpm check` @@ -54,12 +54,12 @@ x-i18n: - `pnpm test` - `pnpm check:docs` -Якщо `pnpm test` дає flaky-результат на завантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `pnpm test `. Для хостів з обмеженою пам’яттю використовуйте: +Якщо `pnpm test` дає flake на навантаженому хості, перезапустіть один раз, перш ніж вважати це регресією, а потім ізолюйте через `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: “Reply with a single word: ok. No punctuation or extra text.” +- Prompt за замовчуванням: “Reply with a single word: ok. No punctuation or extra text.” Останній запуск (2025-12-31, 20 запусків): -- minimax median 1279ms (min 1114, max 2431) -- opus median 2454ms (min 1224, max 3170) +- median для minimax: 1279ms (мін. 1114, макс. 2431) +- median для opus: 2454ms (мін. 1224, макс. 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: +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`: обидва preset-и -Вивід включає `sampleCount`, avg, p50, p95, min/max, розподіл exit-code/signal і зведення максимального 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 profiles для кожного запуску, щоб вимірювання часу й збирання profile використовували той самий 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` записує артефакт повного набору в `.artifacts/cli-startup-bench-all.json` з параметрами `runs=5` і `warmup=1` +- `pnpm test:startup:bench:update` оновлює закомічений baseline fixture у `test/fixtures/cli-startup-bench.json` з параметрами `runs=5` і `warmup=1` -Fixture, закомічений у репозиторій: +Закомічений fixture: - `test/fixtures/cli-startup-bench.json` -- Оновіть через `pnpm test:startup:bench:update` -- Порівняйте поточні результати з fixture через `pnpm test:startup:bench:check` +- Оновлення: `pnpm test:startup:bench:update` +- Порівняння поточних результатів із fixture: `pnpm test:startup:bench:check` ## E2E онбордингу (Docker) Docker необов’язковий; це потрібно лише для containerized smoke-тестів онбордингу. -Повний потік cold-start у чистому Linux-контейнері: +Повний cold-start flow у чистому Linux container: ```bash scripts/e2e/onboard-docker.sh ``` -Цей скрипт керує інтерактивним майстром через pseudo-tty, перевіряє файли config/workspace/session, а потім запускає gateway і виконує `openclaw health`. +Цей скрипт проводить інтерактивний wizard через pseudo-tty, перевіряє файли config/workspace/session, потім запускає gateway і виконує `openclaw health`. -## Smoke для QR import (Docker) +## QR import smoke (Docker) -Переконується, що підтримуваний helper runtime для QR завантажується в підтримуваних Node runtime у Docker (Node 24 за замовчуванням, Node 22 сумісний): +Гарантує, що підтримуваний helper QR runtime завантажується в підтримуваних Docker Node runtimes (Node 24 за замовчуванням, Node 22 сумісний): ```bash pnpm test:docker:qr diff --git a/docs/uk/tools/browser-control.md b/docs/uk/tools/browser-control.md index 633963783..2cbe9f45f 100644 --- a/docs/uk/tools/browser-control.md +++ b/docs/uk/tools/browser-control.md @@ -1,32 +1,32 @@ --- read_when: - - Написання сценаріїв або налагодження браузера агента через локальний API керування + - Скриптування або налагодження браузера агента через локальний API керування - Шукаєте довідник CLI `openclaw browser` - - Додавання власної автоматизації браузера зі знімками та refs -summary: API керування браузером OpenClaw, довідник CLI та дії для сценаріїв + - Додавання власної автоматизації браузера зі snapshot і ref +summary: API керування браузером OpenClaw, довідник CLI та дії для скриптування title: API керування браузером x-i18n: - generated_at: "2026-04-24T02:43:41Z" + generated_at: "2026-04-25T00:03:45Z" model: gpt-5.4 provider: openai - source_hash: e29ad295085e2c36a6c2ce01366a4186e45a7ecfe1d3c3072353c55794b05b5f + source_hash: ec7b6e83b231fefc9c4a63fabde9bdaeb2ea2b2a8ab64943e179a7af5ed4badc source_path: tools/browser-control.md workflow: 15 --- Для налаштування, конфігурації та усунення несправностей див. [Browser](/uk/tools/browser). -Ця сторінка є довідником для локального HTTP API керування, CLI `openclaw browser` -і шаблонів написання сценаріїв (знімки, refs, очікування, потоки налагодження). +Ця сторінка — довідник для локального HTTP API керування, CLI `openclaw browser` +і шаблонів скриптування (snapshot, ref, очікування, потоки налагодження). ## API керування (необов’язково) Лише для локальних інтеграцій Gateway надає невеликий loopback HTTP API: -- Стан/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` +- Статус/запуск/зупинка: `GET /`, `POST /start`, `POST /stop` - Вкладки: `GET /tabs`, `POST /tabs/open`, `POST /tabs/focus`, `DELETE /tabs/:targetId` -- Знімок/скриншот: `GET /snapshot`, `POST /screenshot` +- Snapshot/screenshot: `GET /snapshot`, `POST /screenshot` - Дії: `POST /navigate`, `POST /act` -- Хуки: `POST /hooks/file-chooser`, `POST /hooks/dialog` +- Hooks: `POST /hooks/file-chooser`, `POST /hooks/dialog` - Завантаження: `POST /download`, `POST /wait/download` - Налагодження: `GET /console`, `POST /pdf` - Налагодження: `GET /errors`, `GET /requests`, `POST /trace/start`, `POST /trace/stop`, `POST /highlight` @@ -37,19 +37,22 @@ x-i18n: Усі кінцеві точки приймають `?profile=`. -Якщо налаштовано автентифікацію Gateway зі спільним секретом, HTTP-маршрути браузера також потребують автентифікації: +Якщо налаштовано auth gateway зі спільним секретом, HTTP-маршрути браузера також потребують auth: - `Authorization: Bearer ` - `x-openclaw-password: ` або HTTP Basic auth із цим паролем Примітки: -- Цей окремий loopback API браузера **не** використовує заголовки ідентифікації trusted-proxy або Tailscale Serve. -- Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера не успадковують ці режими з передаванням ідентичності; залишайте їх доступними лише через loopback. +- Цей окремий loopback API браузера **не** використовує заголовки ідентичності trusted-proxy або + Tailscale Serve. +- Якщо `gateway.auth.mode` має значення `none` або `trusted-proxy`, ці loopback-маршрути браузера + не успадковують ці режими з ідентифікаційними даними; залишайте їх лише для loopback. ### Контракт помилок `/act` -`POST /act` використовує структуровану відповідь про помилку для перевірки на рівні маршруту та збоїв політик: +`POST /act` використовує структуровану відповідь помилки для перевірки на рівні маршруту і +збоїв політики: ```json { "error": "", "code": "ACT_*" } @@ -58,43 +61,44 @@ x-i18n: Поточні значення `code`: - `ACT_KIND_REQUIRED` (HTTP 400): `kind` відсутній або не розпізнаний. -- `ACT_INVALID_REQUEST` (HTTP 400): корисне навантаження дії не пройшло нормалізацію або перевірку. -- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з типом дії, який не підтримується. +- `ACT_INVALID_REQUEST` (HTTP 400): payload дії не пройшов нормалізацію або перевірку. +- `ACT_SELECTOR_UNSUPPORTED` (HTTP 400): `selector` використано з непідтримуваним типом дії. - `ACT_EVALUATE_DISABLED` (HTTP 403): `evaluate` (або `wait --fn`) вимкнено конфігурацією. -- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з цільовим об’єктом запиту. +- `ACT_TARGET_ID_MISMATCH` (HTTP 403): верхньорівневий або пакетний `targetId` конфліктує з ціллю запиту. - `ACT_EXISTING_SESSION_UNSUPPORTED` (HTTP 501): дія не підтримується для профілів existing-session. -Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без поля `code`. +Інші збої під час виконання все ще можуть повертати `{ "error": "" }` без +поля `code`. ### Вимога Playwright -Для деяких можливостей (navigate/act/AI snapshot/role snapshot, скриншоти елементів, -PDF) потрібен Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають +Деякі функції (navigate/act/AI snapshot/role snapshot, screenshot елемента, +PDF) потребують Playwright. Якщо Playwright не встановлено, ці кінцеві точки повертають зрозумілу помилку 501. Що все ще працює без Playwright: -- ARIA-знімки -- Скриншоти сторінки для керованого браузера `openclaw`, коли доступний WebSocket - CDP для окремої вкладки -- Скриншоти сторінки для профілів `existing-session` / Chrome MCP -- Скриншоти на основі refs для `existing-session` (`--ref`) із виводу snapshot +- ARIA snapshot +- Screenshot сторінки для керованого браузера `openclaw`, коли доступний CDP + WebSocket для кожної вкладки +- Screenshot сторінки для профілів `existing-session` / Chrome MCP +- Screenshot на основі ref для `existing-session` (`--ref`) з виводу snapshot Що все ще потребує Playwright: - `navigate` - `act` -- AI-знімки / role snapshots -- Скриншоти елементів за CSS-селектором (`--element`) +- AI snapshot / role snapshot +- Screenshot елемента за CSS-selector (`--element`) - повний експорт PDF браузера -Скриншоти елементів також не приймають `--full-page`; маршрут повертає `fullPage is +Screenshot елемента також відхиляють `--full-page`; маршрут повертає `fullPage is not supported for element screenshots`. Якщо ви бачите `Playwright is not available in this gateway build`, відновіть -залежності середовища виконання вбудованого browser Plugin, щоб було встановлено -`playwright-core`, а потім перезапустіть Gateway. Для пакетних встановлень виконайте `openclaw doctor --fix`. -Для Docker також встановіть двійкові файли браузера Chromium, як показано нижче. +залежності runtime вбудованого Plugin браузера, щоб було встановлено `playwright-core`, +а потім перезапустіть gateway. Для пакетних встановлень виконайте `openclaw doctor --fix`. +Для Docker також встановіть бінарні файли браузера Chromium, як показано нижче. #### Встановлення Playwright у Docker @@ -106,13 +110,13 @@ docker compose run --rm openclaw-cli \ node /app/node_modules/playwright-core/cli.js install chromium ``` -Щоб зберігати завантаження браузера, встановіть `PLAYWRIGHT_BROWSERS_PATH` (наприклад, +Щоб зберігати завантаження браузера, задайте `PLAYWRIGHT_BROWSERS_PATH` (наприклад, `/home/node/.cache/ms-playwright`) і переконайтеся, що `/home/node` зберігається через `OPENCLAW_HOME_VOLUME` або bind mount. Див. [Docker](/uk/install/docker). ## Як це працює (внутрішньо) -Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери та профілі вільно змінюються під ним. +Невеликий loopback-сервер керування приймає HTTP-запити та підключається до браузерів на базі Chromium через CDP. Розширені дії (click/type/snapshot/PDF) виконуються через Playwright поверх CDP; коли Playwright відсутній, доступні лише операції без Playwright. Агент бачить один стабільний інтерфейс, тоді як локальні/віддалені браузери й профілі можуть вільно змінюватися під ним. ## Короткий довідник CLI @@ -120,14 +124,14 @@ docker compose run --rm openclaw-cli \ - + ```bash openclaw browser status openclaw browser start -openclaw browser stop # також очищає емуляцію для attach-only/remote CDP +openclaw browser stop # also clears emulation on attach-only/remote CDP openclaw browser tabs -openclaw browser tab # скорочення для поточної вкладки +openclaw browser tab # shortcut for current tab openclaw browser tab new openclaw browser tab select 2 openclaw browser tab close 2 @@ -143,12 +147,14 @@ openclaw browser close abcd1234 ```bash openclaw browser screenshot openclaw browser screenshot --full-page -openclaw browser screenshot --ref 12 # або --ref e12 +openclaw browser screenshot --ref 12 # or --ref e12 +openclaw browser screenshot --labels openclaw browser snapshot openclaw browser snapshot --format aria --limit 200 openclaw browser snapshot --interactive --compact --depth 6 openclaw browser snapshot --efficient openclaw browser snapshot --labels +openclaw browser snapshot --urls openclaw browser snapshot --selector "#main" --interactive openclaw browser snapshot --frame "iframe#main" --interactive openclaw browser console --level error @@ -165,7 +171,7 @@ openclaw browser responsebody "**/api" --max-chars 5000 ```bash openclaw browser navigate https://example.com openclaw browser resize 1280 720 -openclaw browser click 12 --double # або e12 для role refs +openclaw browser click 12 --double # or e12 for role refs openclaw browser type 23 "hello" --submit openclaw browser press Enter openclaw browser hover 44 @@ -198,7 +204,7 @@ openclaw browser storage local set theme dark openclaw browser storage session clear openclaw browser set offline on openclaw browser set headers --headers-json '{"X-Debug":"1"}' -openclaw browser set credentials user pass # --clear для видалення +openclaw browser set credentials user pass # --clear to remove openclaw browser set geo 37.7749 -122.4194 --origin "https://example.com" openclaw browser set media dark openclaw browser set timezone America/New_York @@ -212,53 +218,56 @@ openclaw browser set device "iPhone 14" Примітки: -- `upload` і `dialog` — це виклики **підготовки**; запускайте їх перед click/press, що викликає вибір файлу або діалог. -- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12` або role ref `e12`). CSS-селектори навмисно не підтримуються для дій. -- Шляхи download, trace і upload обмежені тимчасовими кореневими каталогами OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`). +- `upload` і `dialog` — це виклики **arming**; запускайте їх перед click/press, що запускає вибір файлу/діалог. +- `click`/`type`/тощо потребують `ref` із `snapshot` (числовий `12` або role ref `e12`). CSS selectors навмисно не підтримуються для дій. +- Шляхи download, trace і upload обмежені тимчасовими коренями OpenClaw: `/tmp/openclaw{,/downloads,/uploads}` (резервний варіант: `${os.tmpdir()}/openclaw/...`). - `upload` також може напряму встановлювати file input через `--input-ref` або `--element`. -Прапорці snapshot коротко: +Коротко про прапорці snapshot: -- `--format ai` (типово з Playwright): AI-знімок із числовими refs (`aria-ref=""`). -- `--format aria`: дерево доступності, без refs; лише для інспекції. -- `--efficient` (або `--mode efficient`): компактний preset role snapshot. Установіть `browser.snapshotDefaults.mode: "efficient"`, щоб зробити це типовим значенням (див. [Конфігурація Gateway](/uk/gateway/configuration-reference#browser)). -- `--interactive`, `--compact`, `--depth`, `--selector` примусово вмикають role snapshot із refs `ref=e12`. `--frame "