diff --git a/docs/uk/channels/whatsapp.md b/docs/uk/channels/whatsapp.md index bccb7f18a..f99e1c0f4 100644 --- a/docs/uk/channels/whatsapp.md +++ b/docs/uk/channels/whatsapp.md @@ -4,15 +4,15 @@ read_when: summary: Підтримка каналу WhatsApp, керування доступом, поведінка доставки та операції title: WhatsApp x-i18n: - generated_at: "2026-04-26T03:02:53Z" + generated_at: "2026-04-26T04:44:00Z" model: gpt-5.4 provider: openai - source_hash: 120033548f60a39619952e908bd4925dc7da5f8baaa4406ed455aa46010fbb2e + source_hash: 300a8c7ff5768a8da869a4052c01639e7763550adceb40dabc908be44602f352 source_path: channels/whatsapp.md workflow: 15 --- -Статус: готово до production через WhatsApp Web (Baileys). Gateway керує пов’язаними сесіями. +Статус: готовий до production через WhatsApp Web (Baileys). Gateway керує прив’язаними сеансами. ## Встановлення (за потреби) @@ -20,7 +20,7 @@ x-i18n: буде запропоновано встановити Plugin WhatsApp, коли ви вперше його виберете. - `openclaw channels login --channel whatsapp` також пропонує процес встановлення, якщо Plugin ще не встановлено. -- Канал dev + checkout з git: за замовчуванням використовується локальний шлях Plugin. +- Канал dev + git checkout: за замовчуванням використовується локальний шлях Plugin. - Stable/Beta: за замовчуванням використовується npm-пакет `@openclaw/whatsapp`. Ручне встановлення також доступне: @@ -31,10 +31,10 @@ openclaw plugins install @openclaw/whatsapp - Політика DM за замовчуванням для невідомих відправників — сполучення. + Стандартна політика DM — сполучення для невідомих відправників. - - Міжканальна діагностика та сценарії відновлення. + + Діагностика між каналами та сценарії відновлення. Повні шаблони та приклади конфігурації каналу. @@ -61,7 +61,7 @@ openclaw plugins install @openclaw/whatsapp - + ```bash openclaw channels login --channel whatsapp @@ -73,7 +73,7 @@ openclaw channels login --channel whatsapp openclaw channels login --channel whatsapp --account work ``` - Щоб під’єднати наявний/власний каталог автентифікації WhatsApp Web перед входом: + Щоб підключити наявний/власний каталог автентифікації WhatsApp Web перед входом: ```bash openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth @@ -97,24 +97,24 @@ openclaw pairing list whatsapp openclaw pairing approve whatsapp ``` - Термін дії запитів на сполучення спливає через 1 годину. Кількість очікуваних запитів обмежена до 3 на канал. + Термін дії запитів на сполучення спливає через 1 годину. Кількість запитів у стані очікування обмежена 3 на канал. -OpenClaw рекомендує, коли це можливо, запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого варіанта, але сценарії з особистим номером також підтримуються.) +OpenClaw рекомендує, коли це можливо, запускати WhatsApp на окремому номері. (Метадані каналу та процес налаштування оптимізовані для такого сценарію, але конфігурації з особистим номером також підтримуються.) ## Шаблони розгортання - + Це найчистіший операційний режим: - окрема ідентичність WhatsApp для OpenClaw - - чіткіші allowlist для DM і межі маршрутизації - - нижча ймовірність плутанини із самочатом + - чіткіші списки дозволів DM і межі маршрутизації + - менша ймовірність плутанини із самочатом Мінімальний шаблон політики: @@ -132,39 +132,40 @@ OpenClaw рекомендує, коли це можливо, запускати - Онбординг підтримує режим особистого номера та записує базову конфігурацію, дружню до самочату: + Онбординг підтримує режим особистого номера та записує базову конфігурацію, зручну для самочату: - `dmPolicy: "allowlist"` - `allowFrom` містить ваш особистий номер - `selfChatMode: true` - Під час роботи захист самочату спирається на прив’язаний власний номер і `allowFrom`. + Під час виконання захисти самочату спираються на прив’язаний власний номер і `allowFrom`. - - Канал платформи обміну повідомленнями в поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`). + + Канал платформи повідомлень у поточній архітектурі каналів OpenClaw базується на WhatsApp Web (`Baileys`). - Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі chat-channel немає. + Окремого каналу обміну повідомленнями Twilio WhatsApp у вбудованому реєстрі чат-каналів немає. ## Модель виконання -- Gateway керує сокетом WhatsApp і циклом повторного підключення. -- Для вихідного надсилання потрібен активний слухач WhatsApp для цільового облікового запису. +- Gateway керує сокетом WhatsApp і циклом перепідключення. +- Для вихідних відправлень потрібен активний слухач WhatsApp для цільового облікового запису. - Чати статусів і розсилок ігноруються (`@status`, `@broadcast`). -- Прямі чати використовують правила DM-сесій (`session.dmScope`; значення за замовчуванням `main` зводить DM до основної сесії агента). -- Групові сесії ізольовані (`agent::whatsapp:group:`). -- Транспорт WhatsApp Web враховує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Надавайте перевагу конфігурації проксі на рівні хоста, а не специфічним для каналу налаштуванням проксі WhatsApp. +- Прямі чати використовують правила сеансів DM (`session.dmScope`; значення `main` за замовчуванням зводить DM до основного сеансу агента). +- Групові сеанси ізольовані (`agent::whatsapp:group:`). +- Транспорт WhatsApp Web підтримує стандартні змінні середовища проксі на хості Gateway (`HTTPS_PROXY`, `HTTP_PROXY`, `NO_PROXY` / варіанти в нижньому регістрі). Віддавайте перевагу проксі, налаштованому на рівні хоста, а не специфічним налаштуванням проксі WhatsApp для каналу. +- Коли `messages.removeAckAfterReply` увімкнено, OpenClaw очищає реакцію підтвердження WhatsApp після доставки видимої відповіді. -## Хуки Plugin і конфіденційність +## Хуки Plugin і приватність Вхідні повідомлення WhatsApp можуть містити особистий вміст повідомлень, номери телефонів, -ідентифікатори груп, імена відправників і поля кореляції сесій. З цієї причини -WhatsApp не транслює вхідні payload `message_received` у Plugin -без вашої явної згоди: +ідентифікатори груп, імена відправників і поля кореляції сеансів. З цієї причини +WhatsApp не транслює корисне навантаження вхідного хука `message_received` Plugin +, якщо ви явно не ввімкнете це: ```json5 { @@ -178,7 +179,7 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin } ``` -Ви можете обмежити цю згоду одним обліковим записом: +Ви можете обмежити це ввімкнення одним обліковим записом: ```json5 { @@ -196,8 +197,8 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin } ``` -Вмикайте це лише для тих Plugin, яким ви довіряєте отримання вхідного вмісту -повідомлень WhatsApp та ідентифікаторів. +Вмикайте це лише для тих Plugin, яким ви довіряєте отримання вхідного вмісту повідомлень WhatsApp +та ідентифікаторів. ## Керування доступом і активація @@ -212,57 +213,57 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin `allowFrom` приймає номери у стилі E.164 (внутрішньо нормалізуються). - Багатооблікове перевизначення: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над значеннями за замовчуванням на рівні каналу для цього облікового запису. + Перевизначення для кількох облікових записів: `channels.whatsapp.accounts..dmPolicy` (і `allowFrom`) мають пріоритет над значеннями канального рівня за замовчуванням для цього облікового запису. - Деталі поведінки під час виконання: + Подробиці поведінки під час виконання: - - сполучення зберігаються в channel allow-store і об’єднуються з налаштованим `allowFrom` - - якщо allowlist не налаштовано, прив’язаний власний номер дозволяється за замовчуванням - - OpenClaw ніколи не виконує автоматичне сполучення для вихідних `fromMe` DM (повідомлень, які ви надсилаєте собі з прив’язаного пристрою) + - сполучення зберігаються в канальному сховищі дозволів і об’єднуються з налаштованим `allowFrom` + - якщо список дозволів не налаштовано, прив’язаний власний номер дозволяється за замовчуванням + - OpenClaw ніколи не виконує автоматичне сполучення вихідних DM `fromMe` (повідомлень, які ви надсилаєте собі з прив’язаного пристрою) - + Доступ до груп має два рівні: - 1. **Allowlist членства в групі** (`channels.whatsapp.groups`) - - якщо `groups` не вказано, допустимими є всі групи - - якщо `groups` присутній, він працює як allowlist груп (`"*"` дозволено) + 1. **Список дозволів членства в групі** (`channels.whatsapp.groups`) + - якщо `groups` пропущено, усі групи є допустимими + - якщо `groups` присутній, він діє як список дозволів груп (`"*"` дозволено) 2. **Політика відправників групи** (`channels.whatsapp.groupPolicy` + `groupAllowFrom`) - - `open`: allowlist відправників обходиться + - `open`: список дозволів відправників обходиться - `allowlist`: відправник має відповідати `groupAllowFrom` (або `*`) - `disabled`: блокувати всі вхідні групові повідомлення - Резервне значення allowlist відправників: + Резервна поведінка списку дозволів відправників: - якщо `groupAllowFrom` не задано, під час виконання використовується `allowFrom`, якщо він доступний - - allowlist відправників оцінюються до активації за згадкою/відповіддю + - списки дозволів відправників оцінюються до активації за згадкою/відповіддю - Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика під час виконання — `allowlist` (із попередженням у журналі), навіть якщо встановлено `channels.defaults.groupPolicy`. + Примітка: якщо блоку `channels.whatsapp` взагалі немає, резервна групова політика під час виконання — `allowlist` (із попереджувальним записом у журналі), навіть якщо задано `channels.defaults.groupPolicy`. - За замовчуванням для групових відповідей потрібна згадка. + Групові відповіді за замовчуванням потребують згадки. Визначення згадок включає: - - явні згадки ідентичності бота у WhatsApp - - налаштовані regex-шаблони згадок (`agents.list[].groupChat.mentionPatterns`, резервне значення `messages.groupChat.mentionPatterns`) - - неявне визначення відповіді боту (відправник відповіді збігається з ідентичністю бота) + - явні згадки бот-ідентичності в WhatsApp + - налаштовані шаблони regex для згадок (`agents.list[].groupChat.mentionPatterns`, резервно `messages.groupChat.mentionPatterns`) + - неявне виявлення відповіді боту (відправник відповіді збігається з ідентичністю бота) Примітка щодо безпеки: - - цитата/відповідь лише задовольняє перевірку згадки; вона **не** надає авторизацію відправнику - - з `groupPolicy: "allowlist"` відправники поза allowlist усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача з allowlist + - цитування/відповідь лише задовольняє вимогу згадки; це **не** надає авторизацію відправнику + - за `groupPolicy: "allowlist"` відправники, яких немає у списку дозволів, усе одно блокуються, навіть якщо вони відповідають на повідомлення користувача зі списку дозволів - Команда активації на рівні сесії: + Команда активації на рівні сеансу: - `/activation mention` - `/activation always` - `activation` оновлює стан сесії (а не глобальну конфігурацію). Вона обмежена власником. + `activation` оновлює стан сеансу (а не глобальну конфігурацію). Вона обмежена власником. @@ -271,15 +272,15 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin Коли прив’язаний власний номер також присутній у `allowFrom`, активуються запобіжники самочату WhatsApp: -- пропускати read receipts для ходів самочату -- ігнорувати поведінку автоматичного тригера mention-JID, яка інакше сповіщала б вас самих -- якщо `messages.responsePrefix` не задано, відповіді самочату за замовчуванням мають формат `[{identity.name}]` або `[openclaw]` +- пропускати сповіщення про прочитання для ходів самочату +- ігнорувати поведінку автозапуску mention-JID, яка інакше пінгувала б вас самих +- якщо `messages.responsePrefix` не задано, відповіді самочату за замовчуванням мають вигляд `[{identity.name}]` або `[openclaw]` ## Нормалізація повідомлень і контекст - - Вхідні повідомлення WhatsApp загортаються у спільний вхідний envelope. + + Вхідні повідомлення WhatsApp обгортаються у спільний вхідний конверт. Якщо існує цитована відповідь, контекст додається в такому вигляді: @@ -289,12 +290,12 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin [/Replying] ``` - Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, sender JID/E.164). + Поля метаданих відповіді також заповнюються, коли доступні (`ReplyToId`, `ReplyToBody`, `ReplyToSender`, JID/E.164 відправника). - Вхідні повідомлення лише з медіа нормалізуються за допомогою таких заповнювачів: + Вхідні повідомлення лише з медіа нормалізуються із заповнювачами, наприклад: - `` - `` @@ -302,12 +303,12 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin - `` - `` - Тіла location використовують стислий текст координат. Мітки/коментарі location і дані contact/vCard відображаються як fenced недовірені метадані, а не як вбудований текст prompt. + Вміст location використовує стислий текст координат. Мітки/коментарі location та дані contact/vCard відображаються як огороджені ненадійні метадані, а не як вбудований текст prompt. - Для груп необроблені повідомлення можуть буферизуватися та ін’єктуватися як контекст, коли бот нарешті спрацьовує. + Для груп необроблені повідомлення можуть буферизуватися та ін’єктуватися як контекст, коли бота нарешті буде активовано. - ліміт за замовчуванням: `50` - конфігурація: `channels.whatsapp.historyLimit` @@ -316,13 +317,13 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin Маркери ін’єкції: - - `[Повідомлення чату з вашої останньої відповіді — для контексту]` - - `[Поточне повідомлення — дайте відповідь на нього]` + - `[Chat messages since your last reply - for context]` + - `[Current message - respond to this]` - - Read receipts увімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp. + + Сповіщення про прочитання увімкнено за замовчуванням для прийнятих вхідних повідомлень WhatsApp. Вимкнути глобально: @@ -352,53 +353,53 @@ WhatsApp не транслює вхідні payload `message_received` у Plugin } ``` - Для ходів самочату read receipts пропускаються навіть коли вони глобально увімкнені. + Для ходів самочату сповіщення про прочитання пропускаються, навіть коли вони глобально ввімкнені. -## Доставка, розбиття на частини та медіа +## Доставка, поділ на частини та медіа - + - ліміт частини за замовчуванням: `channels.whatsapp.textChunkLimit = 4000` - `channels.whatsapp.chunkMode = "length" | "newline"` - - режим `newline` надає перевагу межам абзаців (порожнім рядкам), а потім повертається до безпечного розбиття за довжиною + - режим `newline` віддає перевагу межам абзаців (порожнім рядкам), а потім переходить до безпечного за довжиною поділу на частини - - підтримуються payload зображень, відео, аудіо (голосове повідомлення PTT) і документів - - аудіомедіа надсилається через payload `audio` Baileys з `ptt: true`, тому клієнти WhatsApp відображають його як голосове повідомлення push-to-talk - - payload відповідей зберігають `audioAsVoice`; вихід голосових повідомлень TTS для WhatsApp залишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM - - рідне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з голосовими повідомленнями - - аудіо не у форматі Ogg, включно з виходом TTS MP3/WebM від Microsoft Edge, транскодується за допомогою `ffmpeg` у 48 кГц моно Ogg/Opus перед доставкою PTT - - `/tts latest` надсилає останню відповідь асистента як одне голосове повідомлення й пригнічує повторне надсилання для тієї самої відповіді; `/tts chat on|off|default` керує автоматичним TTS для поточного чату WhatsApp - - підтримується відтворення анімованих GIF через `gifPlayback: true` під час надсилання відео - - captions застосовуються до першого елемента медіа під час надсилання payload відповіді з кількома медіа, за винятком того, що голосові повідомлення PTT надсилають аудіо спочатку, а видимий текст окремо, оскільки клієнти WhatsApp не завжди коректно відображають captions голосових повідомлень - - джерелом медіа можуть бути HTTP(S), `file://` або локальні шляхи + - підтримуються корисні навантаження image, video, audio (PTT voice-note) і document + - аудіомедіа надсилаються через корисне навантаження Baileys `audio` з `ptt: true`, тож клієнти WhatsApp відображають їх як голосову нотатку push-to-talk + - корисні навантаження відповіді зберігають `audioAsVoice`; вихід TTS voice-note для WhatsApp лишається на цьому шляху PTT, навіть коли провайдер повертає MP3 або WebM + - нативне аудіо Ogg/Opus надсилається як `audio/ogg; codecs=opus` для сумісності з voice-note + - аудіо не у форматі Ogg, включно з виходом Microsoft Edge TTS у форматах MP3/WebM, транскодується за допомогою `ffmpeg` у 48 кГц моно Ogg/Opus перед доставкою PTT + - `/tts latest` надсилає останню відповідь асистента як одну voice-note і пригнічує повторні надсилання для тієї самої відповіді; `/tts chat on|off|default` керує авто-TTS для поточного чату WhatsApp + - анімоване відтворення GIF підтримується через `gifPlayback: true` під час надсилання video + - підписи застосовуються до першого медіаелемента під час надсилання корисних навантажень відповіді з кількома медіа, за винятком PTT voice-note, де аудіо надсилається першим, а видимий текст окремо, тому що клієнти WhatsApp не відображають підписи voice-note послідовно + - джерелом медіа може бути HTTP(S), `file://` або локальні шляхи - обмеження збереження вхідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`) - обмеження надсилання вихідних медіа: `channels.whatsapp.mediaMaxMb` (за замовчуванням `50`) - - перевизначення для облікових записів використовують `channels.whatsapp.accounts..mediaMaxMb` - - зображення автоматично оптимізуються (підбір розміру/якості), щоб відповідати обмеженням - - якщо надсилання медіа не вдається, резервний механізм для першого елемента надсилає текстове попередження замість тихого пропуску відповіді + - перевизначення для облікового запису використовують `channels.whatsapp.accounts..mediaMaxMb` + - зображення автоматично оптимізуються (зміна розміру/підбір якості), щоб вкладатися в обмеження + - у разі помилки надсилання медіа резервний варіант для першого елемента надсилає текстове попередження замість того, щоб мовчки відкинути відповідь ## Цитування відповідей -WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді візуально цитують вхідне повідомлення. Керуйте цим за допомогою `channels.whatsapp.replyToMode`. +WhatsApp підтримує нативне цитування відповідей, коли вихідні відповіді видимо цитують вхідне повідомлення. Це керується через `channels.whatsapp.replyToMode`. | Значення | Поведінка | | ----------- | --------------------------------------------------------------------- | | `"off"` | Ніколи не цитувати; надсилати як звичайне повідомлення | | `"first"` | Цитувати лише перший фрагмент вихідної відповіді | | `"all"` | Цитувати кожен фрагмент вихідної відповіді | -| `"batched"` | Цитувати відкладені пакетні відповіді, залишаючи негайні без цитування | +| `"batched"` | Цитувати поставлені в чергу пакетні відповіді, залишаючи негайні відповіді без цитування | -Значення за замовчуванням — `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts..replyToMode`. +За замовчуванням — `"off"`. Перевизначення для окремих облікових записів використовують `channels.whatsapp.accounts..replyToMode`. ```json5 { @@ -412,14 +413,14 @@ WhatsApp підтримує нативне цитування відповіде ## Рівень реакцій -`channels.whatsapp.reactionLevel` визначає, наскільки широко агент використовує emoji-реакції у WhatsApp: +`channels.whatsapp.reactionLevel` керує тим, наскільки широко агент використовує emoji-реакції у WhatsApp: -| Рівень | Ack-реакції | Реакції, ініційовані агентом | Опис | -| ------------ | ----------- | ---------------------------- | ------------------------------------------------- | -| `"off"` | Ні | Ні | Жодних реакцій | -| `"ack"` | Так | Ні | Лише ack-реакції (підтвердження до відповіді) | -| `"minimal"` | Так | Так (обережно) | Ack + реакції агента з консервативними вказівками | -| `"extensive"`| Так | Так (заохочується) | Ack + реакції агента із заохочувальними вказівками | +| Рівень | Реакції підтвердження | Реакції, ініційовані агентом | Опис | +| ------------ | --------------------- | ---------------------------- | ------------------------------------------------ | +| `"off"` | Ні | Ні | Жодних реакцій | +| `"ack"` | Так | Ні | Лише реакції підтвердження (підтвердження до відповіді) | +| `"minimal"` | Так | Так (обережно) | Підтвердження + реакції агента з обережними настановами | +| `"extensive"`| Так | Так (заохочується) | Підтвердження + реакції агента із заохочувальними настановами | За замовчуванням: `"minimal"`. @@ -437,8 +438,8 @@ WhatsApp підтримує нативне цитування відповіде ## Реакції підтвердження -WhatsApp підтримує негайні ack-реакції після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. -Ack-реакції обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`. +WhatsApp підтримує негайні реакції підтвердження після отримання вхідного повідомлення через `channels.whatsapp.ackReaction`. +Реакції підтвердження обмежуються `reactionLevel` — вони пригнічуються, коли `reactionLevel` має значення `"off"`. ```json5 { @@ -457,8 +458,8 @@ Ack-реакції обмежуються `reactionLevel` — вони приг Примітки щодо поведінки: - надсилаються негайно після прийняття вхідного повідомлення (до відповіді) -- збої журналюються, але не блокують звичайну доставку відповіді -- груповий режим `mentions` реагує на ходи, активовані згадкою; групова активація `always` обходить цю перевірку +- збої записуються в журнал, але не блокують звичайну доставку відповіді +- у груповому режимі `mentions` реакція ставиться на ходах, активованих згадкою; групова активація `always` діє як обхід цієї перевірки - WhatsApp використовує `channels.whatsapp.ackReaction` (застарілий `messages.ackReaction` тут не використовується) ## Кілька облікових записів і облікові дані @@ -470,10 +471,10 @@ Ack-реакції обмежуються `reactionLevel` — вони приг - ідентифікатори облікових записів внутрішньо нормалізуються для пошуку - + - поточний шлях автентифікації: `~/.openclaw/credentials/whatsapp//creds.json` - резервний файл: `creds.json.bak` - - застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для потоків з обліковим записом за замовчуванням + - застаріла автентифікація за замовчуванням у `~/.openclaw/credentials/` усе ще розпізнається/мігрується для сценаріїв з обліковим записом за замовчуванням @@ -484,19 +485,19 @@ Ack-реакції обмежуються `reactionLevel` — вони приг -## Інструменти, дії та запис конфігурації +## Інструменти, дії та записи конфігурації - Підтримка інструментів агента включає дію реакції WhatsApp (`react`). - Обмеження дій: - `channels.whatsapp.actions.reactions` - `channels.whatsapp.actions.polls` -- Запис конфігурації, ініційований каналом, увімкнено за замовчуванням (вимикається через `channels.whatsapp.configWrites=false`). +- Записи конфігурації, ініційовані каналом, увімкнені за замовчуванням (вимикаються через `channels.whatsapp.configWrites=false`). -## Усунення проблем +## Усунення несправностей - - Симптом: статус каналу повідомляє, що під’єднання немає. + + Симптом: статус каналу показує, що прив’язку не виконано. Виправлення: @@ -507,8 +508,8 @@ Ack-реакції обмежуються `reactionLevel` — вони приг - - Симптом: під’єднаний обліковий запис із повторними відключеннями або спробами повторного підключення. + + Симптом: прив’язаний обліковий запис із повторними від’єднаннями або спробами перепідключення. Виправлення: @@ -517,30 +518,30 @@ Ack-реакції обмежуються `reactionLevel` — вони приг openclaw logs --follow ``` - За потреби повторно під’єднайте через `channels login`. + За потреби виконайте повторну прив’язку через `channels login`. - Вихідне надсилання швидко завершується помилкою, якщо для цільового облікового запису немає активного слухача Gateway. + Вихідні надсилання швидко завершуються помилкою, якщо для цільового облікового запису немає активного слухача Gateway. - Переконайтеся, що Gateway запущено і обліковий запис під’єднано. + Переконайтеся, що Gateway запущено і обліковий запис прив’язано. - + Перевіряйте в такому порядку: - `groupPolicy` - `groupAllowFrom` / `allowFrom` - - записи allowlist у `groups` - - обмеження згадками (`requireMention` + шаблони згадок) - - дубльовані ключі в `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` на кожну область + - записи списку дозволів `groups` + - обмеження за згадкою (`requireMention` + шаблони згадок) + - дублікати ключів у `openclaw.json` (JSON5): пізніші записи перевизначають попередні, тому зберігайте лише один `groupPolicy` для кожної області - - Runtime Gateway для WhatsApp має використовувати Node. Bun позначено як несумісний для стабільної роботи Gateway WhatsApp/Telegram. + + Runtime Gateway для WhatsApp має використовувати Node. Bun позначається як несумісний для стабільної роботи Gateway WhatsApp/Telegram. @@ -550,28 +551,28 @@ WhatsApp підтримує системні prompt у стилі Telegram дл Ієрархія визначення для групових повідомлень: -Спочатку визначається ефективна мапа `groups`: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Пошук prompt потім виконується за єдиною отриманою мапою: +Ефективна мапа `groups` визначається спочатку: якщо обліковий запис визначає власну `groups`, вона повністю замінює кореневу мапу `groups` (без глибокого злиття). Потім пошук prompt виконується по отриманій єдиній мапі: -1. **Системний prompt для конкретної групи** (`groups[""].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** у ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. +1. **Системний prompt для конкретної групи** (`groups[""].systemPrompt`): використовується, коли запис конкретної групи існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. 2. **Системний prompt wildcard для груп** (`groups["*"].systemPrompt`): використовується, коли запис конкретної групи повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. Ієрархія визначення для прямих повідомлень: -Спочатку визначається ефективна мапа `direct`: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Пошук prompt потім виконується за єдиною отриманою мапою: +Ефективна мапа `direct` визначається спочатку: якщо обліковий запис визначає власну `direct`, вона повністю замінює кореневу мапу `direct` (без глибокого злиття). Потім пошук prompt виконується по отриманій єдиній мапі: -1. **Системний prompt для конкретного direct-чату** (`direct[""].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** у ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. -2. **Системний prompt wildcard для direct-чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. +1. **Системний prompt для конкретного прямого чату** (`direct[""].systemPrompt`): використовується, коли запис конкретного peer існує в мапі **і** в ньому визначено ключ `systemPrompt`. Якщо `systemPrompt` є порожнім рядком (`""`), wildcard пригнічується і системний prompt не застосовується. +2. **Системний prompt wildcard для прямих чатів** (`direct["*"].systemPrompt`): використовується, коли запис конкретного peer повністю відсутній у мапі або коли він існує, але не визначає ключ `systemPrompt`. -Примітка: `dms` залишається полегшеним контейнером перевизначення історії для окремих DM (`dms..historyLimit`); перевизначення prompt містяться у `direct`. +Примітка: `dms` залишається легковаговим контейнером перевизначення історії для окремих DM (`dms..historyLimit`); перевизначення prompt розміщуються в `direct`. -**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram кореневий `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, які не визначають власний `groups` — щоб бот не отримував групові повідомлення для груп, до яких він не належить. У WhatsApp цей запобіжник не застосовується: кореневі `groups` і `direct` завжди успадковуються обліковими записами, які не мають перевизначення на рівні облікового запису, незалежно від кількості налаштованих облікових записів. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні prompt для груп або direct-чатів на рівні окремого облікового запису, явно визначайте повну мапу під кожним обліковим записом, а не покладайтеся на значення за замовчуванням на кореневому рівні. +**Відмінність від поведінки Telegram з кількома обліковими записами:** У Telegram коренева `groups` навмисно пригнічується для всіх облікових записів у конфігурації з кількома обліковими записами — навіть для тих, які не визначають власну `groups`, — щоб бот не отримував групові повідомлення для груп, до яких він не належить. WhatsApp не застосовує цей захист: кореневі `groups` і `direct` завжди успадковуються обліковими записами, які не визначають перевизначення на рівні облікового запису, незалежно від того, скільки облікових записів налаштовано. У конфігурації WhatsApp з кількома обліковими записами, якщо вам потрібні prompt для груп або прямих чатів на рівні окремого облікового запису, явно визначайте повну мапу під кожним обліковим записом, а не покладайтеся на кореневі значення за замовчуванням. Важлива поведінка: -- `channels.whatsapp.groups` — це і мапа конфігурації окремих груп, і allowlist груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає «усі групи допущені» для цієї області. -- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область допускала всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як значення prompt за замовчуванням. Натомість повторіть prompt у кожному явно дозволеному записі групи. -- Допуск груп і авторизація відправників — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але сам по собі не авторизує кожного відправника в цих групах. Доступ відправників і далі окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. -- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає конфігурацію direct-чату за замовчуванням після того, як DM уже допущено через `dmPolicy` разом із `allowFrom` або правилами pairing-store. +- `channels.whatsapp.groups` — це і мапа конфігурації для окремих груп, і список дозволів груп на рівні чату. На кореневому рівні або на рівні облікового запису `groups["*"]` означає «для цієї області дозволені всі групи». +- Додавайте wildcard `systemPrompt` для груп лише тоді, коли ви вже хочете, щоб ця область дозволяла всі групи. Якщо ви все ще хочете, щоб допустимим був лише фіксований набір ідентифікаторів груп, не використовуйте `groups["*"]` як значення prompt за замовчуванням. Натомість повторіть prompt у кожному явно дозволеному записі групи. +- Допуск груп і авторизація відправників — це окремі перевірки. `groups["*"]` розширює набір груп, які можуть потрапити до обробки груп, але саме по собі не авторизує кожного відправника в цих групах. Доступ відправників усе ще окремо контролюється через `channels.whatsapp.groupPolicy` і `channels.whatsapp.groupAllowFrom`. +- `channels.whatsapp.direct` не має такого самого побічного ефекту для DM. `direct["*"]` лише надає конфігурацію прямого чату за замовчуванням після того, як DM уже було допущено через `dmPolicy` разом із правилами `allowFrom` або сховища pairing. Приклад: @@ -580,31 +581,31 @@ WhatsApp підтримує системні prompt у стилі Telegram дл channels: { whatsapp: { groups: { - // Use only if all groups should be admitted at the root scope. - // Applies to all accounts that do not define their own groups map. - "*": { systemPrompt: "Default prompt for all groups." }, + // Використовуйте лише якщо на кореневому рівні мають бути дозволені всі групи. + // Застосовується до всіх облікових записів, які не визначають власну мапу groups. + "*": { systemPrompt: "Стандартний prompt для всіх груп." }, }, direct: { - // Applies to all accounts that do not define their own direct map. - "*": { systemPrompt: "Default prompt for all direct chats." }, + // Застосовується до всіх облікових записів, які не визначають власну мапу direct. + "*": { systemPrompt: "Стандартний prompt для всіх прямих чатів." }, }, accounts: { work: { groups: { - // This account defines its own groups, so root groups are fully - // replaced. To keep a wildcard, define "*" explicitly here too. + // Цей обліковий запис визначає власну groups, тому коренева groups + // повністю замінюється. Щоб зберегти wildcard, явно визначте тут і "*". "120363406415684625@g.us": { requireMention: false, - systemPrompt: "Focus on project management.", + systemPrompt: "Зосередьтеся на управлінні проєктами.", }, - // Use only if all groups should be admitted in this account. - "*": { systemPrompt: "Default prompt for work groups." }, + // Використовуйте лише якщо в цьому обліковому записі мають бути дозволені всі групи. + "*": { systemPrompt: "Стандартний prompt для робочих груп." }, }, direct: { - // This account defines its own direct map, so root direct entries are - // fully replaced. To keep a wildcard, define "*" explicitly here too. - "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." }, - "*": { systemPrompt: "Default prompt for work direct chats." }, + // Цей обліковий запис визначає власну direct, тому кореневі записи direct + // повністю замінюються. Щоб зберегти wildcard, явно визначте тут і "*". + "+15551234567": { systemPrompt: "Prompt для конкретного робочого прямого чату." }, + "*": { systemPrompt: "Стандартний prompt для робочих прямих чатів." }, }, }, }, @@ -619,13 +620,13 @@ WhatsApp підтримує системні prompt у стилі Telegram дл - [Довідник конфігурації - WhatsApp](/uk/gateway/config-channels#whatsapp) -Важливі поля WhatsApp: +Ключові поля WhatsApp: - доступ: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups` - доставка: `textChunkLimit`, `chunkMode`, `mediaMaxMb`, `sendReadReceipts`, `ackReaction`, `reactionLevel` - кілька облікових записів: `accounts..enabled`, `accounts..authDir`, перевизначення на рівні облікового запису - операції: `configWrites`, `debounceMs`, `web.enabled`, `web.heartbeatSeconds`, `web.reconnect.*` -- поведінка сесій: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` +- поведінка сеансу: `session.dmScope`, `historyLimit`, `dmHistoryLimit`, `dms..historyLimit` - prompt: `groups..systemPrompt`, `groups["*"].systemPrompt`, `direct..systemPrompt`, `direct["*"].systemPrompt` ## Пов’язане @@ -635,4 +636,4 @@ WhatsApp підтримує системні prompt у стилі Telegram дл - [Безпека](/uk/gateway/security) - [Маршрутизація каналів](/uk/channels/channel-routing) - [Маршрутизація кількох агентів](/uk/concepts/multi-agent) -- [Усунення проблем](/uk/channels/troubleshooting) +- [Усунення несправностей](/uk/channels/troubleshooting) diff --git a/docs/uk/gateway/config-agents.md b/docs/uk/gateway/config-agents.md index 1a4aca3a0..949f87b2a 100644 --- a/docs/uk/gateway/config-agents.md +++ b/docs/uk/gateway/config-agents.md @@ -1,22 +1,22 @@ --- read_when: - Налаштування типових параметрів агента (моделі, thinking, робочий простір, Heartbeat, медіа, Skills) - - Налаштування маршрутизації між кількома агентами та прив’язок - - Налаштування поведінки сесії, доставки повідомлень і режиму talk + - Налаштування маршрутизації та прив’язок між кількома агентами + - Налаштування сесії, доставки повідомлень і поведінки режиму talk summary: Типові налаштування агента, маршрутизація між кількома агентами, сесія, повідомлення та конфігурація talk title: Конфігурація — агенти x-i18n: - generated_at: "2026-04-26T03:54:38Z" + generated_at: "2026-04-26T04:44:04Z" model: gpt-5.4 provider: openai - source_hash: 50a008ceb73b83af994e4a7b731e1b214fc01fef22021e88bd6a3cbc46b1891f + source_hash: a01de1a98f1de8b979d27a76a9b3eaf5daced98304dd1e4d9880f03bb047d833 source_path: gateway/config-agents.md workflow: 15 --- -Ключі конфігурації з областю дії агента в `agents.*`, `multiAgent.*`, `session.*`, +Ключі конфігурації в межах агента під `agents.*`, `multiAgent.*`, `session.*`, `messages.*` та `talk.*`. Для каналів, інструментів, середовища виконання Gateway та інших -ключів верхнього рівня див. [Довідник конфігурації](/uk/gateway/configuration-reference). +ключів верхнього рівня див. [Довідник із конфігурації](/uk/gateway/configuration-reference). ## Типові параметри агента @@ -32,7 +32,7 @@ x-i18n: ### `agents.defaults.repoRoot` -Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, підіймаючись угору від робочого простору. +Необов’язковий корінь репозиторію, який показується в рядку Runtime системного запиту. Якщо не задано, OpenClaw автоматично визначає його, піднімаючись угору від робочого простору. ```json5 { @@ -58,9 +58,9 @@ x-i18n: } ``` -- Не вказуйте `agents.defaults.skills`, щоб типово дозволити необмежені Skills. +- Не вказуйте `agents.defaults.skills`, щоб Skills типово не були обмежені. - Не вказуйте `agents.list[].skills`, щоб успадкувати типові значення. -- Установіть `agents.list[].skills: []`, щоб не дозволяти жодних Skills. +- Установіть `agents.list[].skills: []`, щоб не було Skills. - Непорожній список `agents.list[].skills` є остаточним набором для цього агента; він не об’єднується з типовими значеннями. @@ -78,8 +78,8 @@ x-i18n: Керує тим, коли bootstrap-файли робочого простору вставляються в системний запит. Типове значення: `"always"`. -- `"continuation-skip"`: у безпечних ходах продовження (після завершеної відповіді асистента) повторне вставлення bootstrap-файлів робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction усе одно перебудовують контекст. -- `"never"`: вимикає вставлення bootstrap-файлів робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують життєвим циклом свого запиту (власні рушії контексту, нативні середовища виконання, що самі будують контекст, або спеціалізовані bootstrap-free сценарії). Ходи Heartbeat і відновлення після Compaction також пропускають вставлення. +- `"continuation-skip"`: на безпечних ходах продовження (після завершеної відповіді асистента) повторне вставлення bootstrap робочого простору пропускається, що зменшує розмір запиту. Запуски Heartbeat і повторні спроби після Compaction все одно перебудовують контекст. +- `"never"`: вимикає вставлення bootstrap робочого простору та файлів контексту на кожному ході. Використовуйте це лише для агентів, які повністю керують власним життєвим циклом запиту (власні рушії контексту, нативні середовища виконання, що самі будують контекст, або спеціалізовані робочі процеси без bootstrap). Ходи Heartbeat і відновлення після Compaction також пропускають вставлення. ```json5 { @@ -89,7 +89,7 @@ x-i18n: ### `agents.defaults.bootstrapMaxChars` -Максимальна кількість символів для кожного bootstrap-файлу робочого простору до обрізання. Типове значення: `12000`. +Максимальна кількість символів для одного bootstrap-файлу робочого простору перед обрізанням. Типове значення: `12000`. ```json5 { @@ -99,7 +99,7 @@ x-i18n: ### `agents.defaults.bootstrapTotalMaxChars` -Максимальна загальна кількість символів, що вставляються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. +Максимальна сумарна кількість символів, що вставляються з усіх bootstrap-файлів робочого простору. Типове значення: `60000`. ```json5 { @@ -113,8 +113,8 @@ x-i18n: Типове значення: `"once"`. - `"off"`: ніколи не вставляти текст попередження в системний запит. -- `"once"`: вставляти попередження один раз для кожного унікального підпису обрізання (рекомендовано). -- `"always"`: вставляти попередження під час кожного запуску, коли є обрізання. +- `"once"`: вставляти попередження один раз для кожного унікального сигнатурного випадку обрізання (рекомендовано). +- `"always"`: вставляти попередження при кожному запуску, коли є обрізання. ```json5 { @@ -122,24 +122,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.*`: - розмір фрагментів пошуку в пам’яті з індексацією та вставлення. + індексований уривок пошуку в пам’яті та розмір вставлення. Використовуйте відповідне перевизначення для окремого агента лише тоді, коли одному агенту потрібен інший бюджет: @@ -149,7 +149,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.defaults.startupContext` -Керує початковим прологом першого ходу, що вставляється під час базових запусків `/new` і `/reset`. +Керує стартовою прелюдією першого ходу, що вставляється під час звичайних запусків `/new` і `/reset`. ```json5 { @@ -187,18 +187,17 @@ OpenClaw має кілька великих бюджетів запиту/кон } ``` -- `memoryGetMaxChars`: типове обмеження витягу `memory_get` до додавання +- `memoryGetMaxChars`: типове обмеження уривка `memory_get` перед додаванням метаданих обрізання та повідомлення про продовження. -- `memoryGetDefaultLines`: типове вікно рядків для `memory_get`, коли `lines` +- `memoryGetDefaultLines`: типове вікно рядків `memory_get`, коли `lines` не вказано. -- `toolResultMaxChars`: чинне обмеження результатів інструментів, що використовується для збережених результатів і +- `toolResultMaxChars`: активне обмеження результату інструмента, яке використовується для збережених результатів і відновлення при переповненні. -- `postCompactionMaxChars`: обмеження витягу AGENTS.md, що використовується під час вставлення - оновлення після Compaction. +- `postCompactionMaxChars`: обмеження уривка AGENTS.md, яке використовується під час оновлювального вставлення після Compaction. #### `agents.list[].contextLimits` -Перевизначення для окремого агента для спільних параметрів `contextLimits`. Пропущені поля успадковуються +Перевизначення для окремого агента для спільних параметрів `contextLimits`. Не вказані поля успадковуються з `agents.defaults.contextLimits`. ```json5 @@ -225,7 +224,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `skills.limits.maxSkillsPromptChars` -Глобальне обмеження для компактного списку Skills, вставленого в системний запит. Це +Глобальне обмеження для компактного списку Skills, що вставляється в системний запит. Це не впливає на читання файлів `SKILL.md` за потреби. ```json5 @@ -240,7 +239,7 @@ OpenClaw має кілька великих бюджетів запиту/кон #### `agents.list[].skillsLimits.maxSkillsPromptChars` -Перевизначення для окремого агента для бюджету запиту Skills. +Перевизначення бюджету запиту для Skills для окремого агента. ```json5 { @@ -259,11 +258,11 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.imageMaxDimensionPx` -Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень transcript/tool перед викликами провайдера. +Максимальний розмір у пікселях для довшої сторони зображення в блоках зображень транскрипту/інструмента перед викликами провайдера. Типове значення: `1200`. -Менші значення зазвичай зменшують використання vision-токенів і розмір корисного навантаження запиту для сценаріїв із великою кількістю знімків екрана. -Більші значення зберігають більше візуальних деталей. +Нижчі значення зазвичай зменшують використання vision-токенів і розмір запиту для запусків із великою кількістю скриншотів. +Вищі значення зберігають більше візуальних деталей. ```json5 { @@ -273,7 +272,7 @@ OpenClaw має кілька великих бюджетів запиту/кон ### `agents.defaults.userTimezone` -Часовий пояс для контексту системного запиту (не часових міток повідомлень). Якщо не задано, використовується часовий пояс хоста. +Часовий пояс для контексту системного запиту (не часових позначок повідомлень). Якщо не задано, використовується часовий пояс хоста. ```json5 { @@ -323,7 +322,7 @@ OpenClaw має кілька великих бюджетів запиту/кон }, params: { cacheRetention: "long" }, // глобальні типові параметри провайдера embeddedHarness: { - runtime: "pi", // pi | auto | registered harness id, e.g. codex + runtime: "pi", // pi | auto | зареєстрований ідентифікатор harness, наприклад codex fallback: "pi", // pi | none }, pdfMaxBytesMb: 10, @@ -342,54 +341,54 @@ OpenClaw має кілька великих бюджетів запиту/кон - `model`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - Форма рядка задає лише основну модель. - - Форма об’єкта задає основну модель і впорядкований список резервних моделей. + - Форма об’єкта задає основну модель і впорядкований список резервних моделей для перемикання при відмові. - `imageModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується шляхом інструмента `image` як конфігурація моделі бачення. + - Використовується шляхом інструмента `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 або `openai/gpt-image-1.5` для прозорого PNG/WebP-виводу OpenAI. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну авторизацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `FAL_KEY` для `fal/*`). - - Якщо поле не задано, `image_generate` усе одно може визначити типовий варіант провайдера з налаштованою авторизацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації зображень у порядку provider-id. + - Типові значення: `google/gemini-3.1-flash-image-preview` для нативної генерації зображень Gemini, `fal/fal-ai/flux/dev` для fal, `openai/gpt-image-2` для OpenAI Images або `openai/gpt-image-1.5` для виводу OpenAI PNG/WebP із прозорим фоном. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера (наприклад, `GEMINI_API_KEY` або `GOOGLE_API_KEY` для `google/*`, `OPENAI_API_KEY` або OpenAI Codex OAuth для `openai/gpt-image-2` / `openai/gpt-image-1.5`, `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.6`. - - Якщо поле не задано, `music_generate` усе одно може визначити типовий варіант провайдера з налаштованою авторизацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації музики в порядку provider-id. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну авторизацію провайдера/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` усе одно може визначити типовий варіант провайдера з налаштованою авторизацією. Спочатку він пробує поточного типового провайдера, а потім решту зареєстрованих провайдерів генерації відео в порядку provider-id. - - Якщо ви безпосередньо вибираєте `provider/model`, також налаштуйте відповідну авторизацію провайдера/API-ключ. + - Якщо параметр не вказано, `video_generate` усе одно може визначити типове значення провайдера на основі автентифікації. Спочатку він пробує поточного типового провайдера, потім — інших зареєстрованих провайдерів генерації відео в порядку ідентифікаторів провайдерів. + - Якщо ви вибираєте provider/model напряму, також налаштуйте відповідну автентифікацію провайдера/API-ключ. - Вбудований провайдер генерації відео Qwen підтримує до 1 вихідного відео, 1 вхідного зображення, 4 вхідних відео, тривалість до 10 секунд, а також параметри рівня провайдера `size`, `aspectRatio`, `resolution`, `audio` і `watermark`. - `pdfModel`: приймає або рядок (`"provider/model"`), або об’єкт (`{ primary, fallbacks }`). - - Використовується інструментом `pdf` для маршрутизації моделі. - - Якщо поле не задано, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель. + - Використовується інструментом `pdf` для маршрутизації моделей. + - Якщо параметр не вказано, інструмент PDF використовує `imageModel`, а потім визначену модель сесії/типову модель. - `pdfMaxBytesMb`: типове обмеження розміру PDF для інструмента `pdf`, коли `maxBytesMb` не передано під час виклику. -- `pdfMaxPages`: типова максимальна кількість сторінок, яка враховується режимом резервного вилучення в інструменті `pdf`. +- `pdfMaxPages`: типова максимальна кількість сторінок, що враховуються в режимі резервного вилучення для інструмента `pdf`. - `verboseDefault`: типовий рівень verbose для агентів. Значення: `"off"`, `"on"`, `"full"`. Типове значення: `"off"`. - `elevatedDefault`: типовий рівень elevated-output для агентів. Значення: `"off"`, `"on"`, `"ask"`, `"full"`. Типове значення: `"on"`. -- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу за API-ключем або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує псевдонім, потім унікальний збіг серед налаштованих провайдерів для цього точного id моделі і лише після цього повертається до налаштованого типового провайдера (застаріла поведінка для сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари провайдер/модель замість того, щоб показувати застаріле типове значення для видаленого провайдера. +- `model.primary`: формат `provider/model` (наприклад, `openai/gpt-5.5` для доступу через API-ключ або `openai-codex/gpt-5.5` для Codex OAuth). Якщо не вказати провайдера, OpenClaw спочатку пробує псевдонім, потім — унікальний збіг налаштованого провайдера для цього точного ідентифікатора моделі, і лише потім повертається до налаштованого типового провайдера (застаріла поведінка для сумісності, тому краще явно вказувати `provider/model`). Якщо цей провайдер більше не надає налаштовану типову модель, OpenClaw переходить до першої налаштованої пари provider/model замість того, щоб показувати застаріле типове значення від видаленого провайдера. - `models`: налаштований каталог моделей і список дозволених моделей для `/model`. Кожен запис може містити `alias` (скорочення) і `params` (специфічні для провайдера параметри, наприклад `temperature`, `maxTokens`, `cacheRetention`, `context1m`, `responsesServerCompaction`, `responsesCompactThreshold`, `chat_template_kwargs`, `extra_body`/`extraBody`). - - Безпечне редагування: використовуйте `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). + - Безпечні зміни: використовуйте `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` (відповідний id агента) перевизначає за ключами. Подробиці див. у [Кешування запитів](/uk/reference/prompt-caching). -- `params.extra_body`/`params.extraBody`: розширений JSON для наскрізної передачі, який об’єднується з тілами запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, пріоритет має extra body; не нативні маршрути completions після цього все одно видаляють специфічний для OpenAI параметр `store`. -- `params.chat_template_kwargs`: аргументи chat template для vLLM/OpenAI-сумісних середовищ, які об’єднуються з верхньорівневими тілами запитів `api: "openai-completions"`. Для `vllm/nemotron-3-*` із вимкненим thinking OpenClaw автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true`; явні `chat_template_kwargs` перевизначають ці типові значення, а `extra_body.chat_template_kwargs` усе одно має остаточний пріоритет. -- `params.preserveThinking`: опція лише для Z.AI для збереження thinking. Коли її ввімкнено і thinking увімкнений, OpenClaw надсилає `thinking.clear_thinking: false` і повторно відтворює попередній `reasoning_content`; див. [thinking і збережений thinking у Z.AI](/uk/providers/zai#thinking-and-preserved-thinking). -- `embeddedHarness`: типова політика низькорівневого runtime вбудованого агента. Якщо `runtime` не вказано, типово використовується OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово задіяти вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим harness із Plugin брати підтримувані моделі, або зареєстрований id harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні runtime із Plugin, наприклад `codex`, типово завершуються помилкою без резервування, якщо в тій самій області перевизначення не задано `fallback: "pi"`. Зберігайте посилання на моделі в канонічному вигляді `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси runtime provider. Див. [Середовища виконання агента](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору `provider/model`. -- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних моделей), зберігають канонічну форму об’єкта та, за можливості, зберігають наявні списки резервних моделей. -- `maxConcurrent`: максимальна кількість паралельних запусків агентів між сесіями (кожна сесія все одно виконується послідовно). Типове значення: 4. +- Пріоритет об’єднання `params` (конфігурація): `agents.defaults.params` (глобальна база) перевизначається через `agents.defaults.models["provider/model"].params` (для моделі), потім `agents.list[].params` (для відповідного ідентифікатора агента) перевизначає за ключем. Докладніше див. [Кешування запитів](/uk/reference/prompt-caching). +- `params.extra_body`/`params.extraBody`: розширений JSON для наскрізної передачі, що об’єднується в тіла запитів `api: "openai-completions"` для OpenAI-сумісних проксі. Якщо він конфліктує зі згенерованими ключами запиту, перемагає додаткове тіло; маршрути завершень, які не є нативними, після цього все одно видаляють специфічний для OpenAI параметр `store`. +- `params.chat_template_kwargs`: аргументи шаблону чату для vLLM/OpenAI-сумісних систем, що об’єднуються з тілами запитів верхнього рівня `api: "openai-completions"`. Для `vllm/nemotron-3-*` із вимкненим thinking OpenClaw автоматично надсилає `enable_thinking: false` і `force_nonempty_content: true`; явні `chat_template_kwargs` перевизначають ці типові значення, а `extra_body.chat_template_kwargs` усе одно має остаточний пріоритет. +- `params.preserveThinking`: опціональне ввімкнення лише для Z.AI для збереженого thinking. Коли ввімкнено і thinking активний, OpenClaw надсилає `thinking.clear_thinking: false` і повторно відтворює попередній `reasoning_content`; див. [Thinking і збережений thinking у Z.AI](/uk/providers/zai#thinking-and-preserved-thinking). +- `embeddedHarness`: типова політика низькорівневого середовища виконання вбудованого агента. Якщо `runtime` не вказано, типовим є OpenClaw Pi. Використовуйте `runtime: "pi"`, щоб примусово ввімкнути вбудований harness PI, `runtime: "auto"`, щоб дозволити зареєстрованим Plugin harness перебирати підтримувані моделі, або зареєстрований ідентифікатор harness, наприклад `runtime: "codex"`. Установіть `fallback: "none"`, щоб вимкнути автоматичний резервний перехід на PI. Явні середовища виконання Plugin, як-от `codex`, типово завершуються із закритою помилкою, якщо не задати `fallback: "pi"` у тій самій області перевизначення. Зберігайте посилання на моделі в канонічному форматі `provider/model`; вибирайте Codex, Claude CLI, Gemini CLI та інші бекенди виконання через конфігурацію runtime, а не через застарілі префікси провайдера runtime. Див. [Середовища виконання агентів](/uk/concepts/agent-runtimes), щоб зрозуміти, чим це відрізняється від вибору provider/model. +- Засоби запису конфігурації, які змінюють ці поля (наприклад `/models set`, `/models set-image` і команди додавання/видалення резервних варіантів), зберігають канонічну форму об’єкта та, коли можливо, зберігають наявні списки резервних моделей. +- `maxConcurrent`: максимальна кількість паралельних запусків агентів у різних сесіях (кожна сесія все одно виконується послідовно). Типове значення: 4. ### `agents.defaults.embeddedHarness` `embeddedHarness` керує тим, який низькорівневий виконавець обробляє ходи вбудованого агента. -У більшості розгортань слід залишати типовий runtime OpenClaw Pi. +У більшості розгортань слід залишати типове середовище виконання OpenClaw Pi. Використовуйте його, коли довірений Plugin надає нативний harness, наприклад вбудований -harness app-server для Codex. Для загальної моделі див. -[Середовища виконання агента](/uk/concepts/agent-runtimes). +harness сервера застосунку Codex. Для загальної моделі див. +[Середовища виконання агентів](/uk/concepts/agent-runtimes). ```json5 { @@ -405,14 +404,14 @@ harness app-server для Codex. Для загальної моделі див. } ``` -- `runtime`: `"auto"`, `"pi"` або id зареєстрованого 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 фіксується для кожного id сесії після першого вбудованого запуску. Зміни конфігурації/середовища впливають на нові або скинуті сесії, а не на наявний transcript. Застарілі сесії з історією transcript, але без зафіксованого pin, вважаються прив’язаними до PI. `/status` показує фактичний runtime, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. -- Це керує лише вбудованим chat harness. Генерація медіа, бачення, PDF, музика, відео та TTS і далі використовують свої налаштування `provider/model`. +- `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` показує фактичне середовище виконання, наприклад `Runtime: OpenClaw Pi Default` або `Runtime: OpenAI Codex`. +- Це керує лише вбудованим chat-harness. Генерація медіа, vision, PDF, музика, відео та TTS і далі використовують свої параметри provider/model. -**Вбудовані скорочення псевдонімів** (застосовуються лише тоді, коли модель є в `agents.defaults.models`): +**Вбудовані скорочені псевдоніми** (застосовуються лише коли модель є в `agents.defaults.models`): | Псевдонім | Модель | | ------------------- | ------------------------------------------ | @@ -425,15 +424,15 @@ harness app-server для Codex. Для загальної моделі див. | `gemini-flash` | `google/gemini-3-flash-preview` | | `gemini-flash-lite` | `google/gemini-3.1-flash-lite-preview` | -Ваші налаштовані псевдоніми завжди мають пріоритет над типовими. +Ваші налаштовані псевдоніми завжди мають вищий пріоритет за типові. -Для моделей 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, якщо ви не задасте `--thinking off` або самі не визначите `agents.defaults.models["zai/"].params.thinking`. +Моделі Z.AI типово вмикають `tool_stream` для потокового передавання викликів інструментів. Установіть `agents.defaults.models["zai/"].params.tool_stream` у `false`, щоб вимкнути це. +Для моделей Anthropic Claude 4.6 типовим є `adaptive` thinking, якщо явний рівень thinking не задано. ### `agents.defaults.cliBackends` -Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери не працюють. +Необов’язкові CLI-бекенди для резервних запусків лише з текстом (без викликів інструментів). Корисно як запасний варіант, коли API-провайдери недоступні. ```json5 { @@ -451,7 +450,7 @@ harness app-server для Codex. Для загальної моделі див. sessionArg: "--session", sessionMode: "existing", systemPromptArg: "--system", - // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець файлу запиту. + // Або використовуйте systemPromptFileArg, якщо CLI приймає прапорець для файлу запиту. systemPromptWhen: "first", imageArg: "--image", imageMode: "repeat", @@ -468,7 +467,7 @@ harness app-server для Codex. Для загальної моделі див. ### `agents.defaults.systemPromptOverride` -Повністю замінює системний запит, зібраний OpenClaw, на фіксований рядок. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають пріоритет; порожнє значення або значення лише з пробілами ігнорується. Корисно для контрольованих експериментів із запитами. +Замінює весь системний запит, зібраний OpenClaw, фіксованим рядком. Задається на типовому рівні (`agents.defaults.systemPromptOverride`) або для окремого агента (`agents.list[].systemPromptOverride`). Значення для окремого агента мають вищий пріоритет; порожнє значення або значення лише з пробілів ігнорується. Корисно для контрольованих експериментів із запитами. ```json5 { @@ -482,7 +481,7 @@ harness app-server для Codex. Для загальної моделі див. ### `agents.defaults.promptOverlays` -Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки для всіх провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. +Незалежні від провайдера накладки запиту, що застосовуються за сімейством моделей. Ідентифікатори моделей сімейства GPT-5 отримують спільний контракт поведінки для різних провайдерів; `personality` керує лише шаром дружнього стилю взаємодії. ```json5 { @@ -498,9 +497,9 @@ harness app-server для Codex. Для загальної моделі див. } ``` -- `"friendly"` (типове значення) і `"on"` вмикають шар дружнього стилю взаємодії. -- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається увімкненим. -- Застаріле `plugins.entries.openai.config.personality` усе ще зчитується, коли це спільне налаштування не задано. +- `"friendly"` (типово) і `"on"` вмикають шар дружнього стилю взаємодії. +- `"off"` вимикає лише дружній шар; позначений контракт поведінки GPT-5 залишається ввімкненим. +- Застарілий `plugins.entries.openai.config.personality` усе ще зчитується, коли цей спільний параметр не задано. ### `agents.defaults.heartbeat` @@ -511,16 +510,16 @@ harness app-server для Codex. Для загальної моделі див. agents: { defaults: { heartbeat: { - every: "30m", // 0m disables + every: "30m", // 0m вимикає model: "openai/gpt-5.4-mini", includeReasoning: false, - includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt - lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files - isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history) + includeSystemPromptSection: true, // типово: true; false прибирає розділ Heartbeat із системного запиту + lightContext: false, // типово: false; true залишає лише HEARTBEAT.md із bootstrap-файлів робочого простору + isolatedSession: false, // типово: false; true запускає кожен Heartbeat у новій сесії (без історії розмови) session: "main", to: "+15555550123", - directPolicy: "allow", // allow (default) | block - target: "none", // default: none | options: last | whatsapp | telegram | discord | ... + directPolicy: "allow", // allow (типово) | block + target: "none", // типово: none | варіанти: last | whatsapp | telegram | discord | ... prompt: "Read HEARTBEAT.md if it exists...", ackMaxChars: 300, suppressToolErrorWarnings: false, @@ -531,15 +530,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`: політика доставки напряму/у DM. `allow` (типово) дозволяє доставку напряму до цілі. `block` пригнічує доставку напряму до цілі й видає `reason=dm-blocked`. -- `lightContext`: якщо `true`, запуски Heartbeat використовують полегшений bootstrap-контекст і зберігають лише `HEARTBEAT.md` із bootstrap-файлів робочого простору. -- `isolatedSession`: якщо `true`, кожен запуск Heartbeat виконується в новій сесії без попередньої історії розмови. Та сама схема ізоляції, що й у Cron `sessionTarget: "isolated"`. Зменшує вартість токенів на один Heartbeat приблизно зі ~100K до ~2-5K токенів. -- Для окремого агента: задайте `agents.list[].heartbeat`. Якщо `heartbeat` визначено хоча б для одного агента, Heartbeat запускається **лише для цих агентів**. -- Heartbeat виконує повноцінні ходи агента — коротші інтервали спалюють більше токенів. +- `every`: рядок тривалості (ms/s/m/h). Типове значення: `30m` (автентифікація через API-ключ) або `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` @@ -549,16 +548,16 @@ harness app-server для Codex. Для загальної моделі див. defaults: { compaction: { mode: "safeguard", // default | safeguard - provider: "my-provider", // id of a registered compaction provider plugin (optional) + provider: "my-provider", // id зареєстрованого Plugin провайдера Compaction (необов’язково) timeoutSeconds: 900, reserveTokensFloor: 24000, keepRecentTokens: 50000, identifierPolicy: "strict", // strict | off | custom - identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom + identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // використовується, коли identifierPolicy=custom qualityGuard: { enabled: true, maxRetries: 1 }, - postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection - model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override - notifyUser: true, // send brief notices when compaction starts and completes (default: false) + postCompactionSections: ["Session Startup", "Red Lines"], // [] вимикає повторне вставлення + model: "openrouter/anthropic/claude-sonnet-4-6", // необов’язкове перевизначення моделі лише для Compaction + notifyUser: true, // надсилати короткі сповіщення користувачу, коли Compaction починається й завершується (типово: false) memoryFlush: { enabled: true, softThresholdTokens: 6000, @@ -571,21 +570,21 @@ harness app-server для Codex. Для загальної моделі див. } ``` -- `mode`: `default` або `safeguard` (підсумовування фрагментами для довгих історій). Див. [Compaction](/uk/concepts/compaction). -- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` цього провайдера. У разі помилки використовується вбудований варіант. Задання провайдера примусово встановлює `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). -- `timeoutSeconds`: максимальна кількість секунд, дозволених для однієї операції Compaction, після чого OpenClaw її перериває. Типове значення: `900`. -- `keepRecentTokens`: бюджет точки відсікання Pi для дослівного збереження найсвіжішого хвоста transcript. Ручний `/compact` використовує це значення, якщо воно явно задане; інакше ручний Compaction є жорсткою контрольною точкою. +- `mode`: `default` або `safeguard` (підсумовування частинами для довгих історій). Див. [Compaction](/uk/concepts/compaction). +- `provider`: id зареєстрованого Plugin провайдера Compaction. Якщо задано, замість вбудованого підсумовування LLM викликається `summarize()` провайдера. У разі помилки повертається до вбудованого варіанта. Задання провайдера примусово вмикає `mode: "safeguard"`. Див. [Compaction](/uk/concepts/compaction). +- `timeoutSeconds`: максимальна кількість секунд, дозволена для однієї операції Compaction до її переривання OpenClaw. Типове значення: `900`. +- `keepRecentTokens`: бюджет точки відсікання Pi для збереження найсвіжішого хвоста транскрипту дослівно. Ручний `/compact` враховує це, коли значення явно задано; інакше ручний Compaction є жорсткою контрольною точкою. - `identifierPolicy`: `strict` (типово), `off` або `custom`. `strict` додає вбудовані вказівки щодо збереження непрозорих ідентифікаторів під час підсумовування Compaction. -- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, що використовується, коли `identifierPolicy=custom`. -- `qualityGuard`: перевірки з повторною спробою при некоректному виході для підсумків safeguard. Увімкнено типово в режимі safeguard; задайте `enabled: false`, щоб пропустити аудит. -- `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 для збереження довготривалої пам’яті. Пропускається, якщо робочий простір доступний лише для читання. +- `identifierInstructions`: необов’язковий власний текст для збереження ідентифікаторів, який використовується, коли `identifierPolicy=custom`. +- `qualityGuard`: перевірки з повторною спробою при хибному форматі виводу для підсумків safeguard. Типово ввімкнено в режимі safeguard; установіть `enabled: false`, щоб пропустити перевірку. +- `postCompactionSections`: необов’язкові назви розділів AGENTS.md рівня H2/H3 для повторного вставлення після Compaction. Типово `["Session Startup", "Red Lines"]`; установіть `[]`, щоб вимкнути повторне вставлення. Коли параметр не задано або явно задано цю типову пару, старі заголовки `Every Session`/`Safety` також приймаються як резервний варіант для сумісності. +- `model`: необов’язкове перевизначення `provider/model-id` лише для підсумовування Compaction. Використовуйте це, коли основна сесія має залишатися на одній моделі, а підсумки Compaction слід виконувати на іншій; якщо параметр не задано, Compaction використовує основну модель сесії. +- `notifyUser`: якщо `true`, надсилає користувачу короткі сповіщення, коли Compaction починається і коли завершується (наприклад, "Compacting context..." і "Compaction complete"). Типово вимкнено, щоб Compaction залишався безшумним. +- `memoryFlush`: тихий агентний хід перед автоматичним Compaction для збереження тривалих спогадів. Пропускається, коли робочий простір доступний лише для читання. ### `agents.defaults.contextPruning` -Обрізає **старі результати інструментів** із контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. +Обрізає **старі результати інструментів** з контексту в пам’яті перед надсиланням до LLM. **Не** змінює історію сесії на диску. ```json5 { @@ -593,7 +592,7 @@ harness app-server для Codex. Для загальної моделі див. defaults: { contextPruning: { mode: "cache-ttl", // off | cache-ttl - ttl: "1h", // duration (ms/s/m/h), default unit: minutes + ttl: "1h", // тривалість (ms/s/m/h), типова одиниця: хвилини keepLastAssistants: 3, softTrimRatio: 0.3, hardClearRatio: 0.5, @@ -610,24 +609,24 @@ harness app-server для Codex. Для загальної моделі див. - `mode: "cache-ttl"` вмикає проходи обрізання. -- `ttl` визначає, як часто обрізання може виконуватися знову (після останнього торкання кешу). -- Обрізання спочатку м’яко скорочує надто великі результати інструментів, а потім за потреби повністю очищає старіші результати інструментів. +- `ttl` керує тим, як часто обрізання може запускатися знову (після останнього торкання кешу). +- Обрізання спочатку м’яко скорочує завеликі результати інструментів, а потім, за потреби, повністю очищає старіші результати інструментів. **М’яке обрізання** зберігає початок і кінець та вставляє `...` посередині. -**Повне очищення** замінює весь результат інструмента плейсхолдером. +**Повне очищення** замінює весь результат інструмента заповнювачем. Примітки: -- Блоки зображень ніколи не обрізаються й не очищаються. +- Блоки зображень ніколи не обрізаються і не очищаються. - Співвідношення базуються на кількості символів (приблизно), а не на точній кількості токенів. -- Якщо повідомлень асистента менше, ніж `keepLastAssistants`, обрізання пропускається. +- Якщо існує менше ніж `keepLastAssistants` повідомлень асистента, обрізання пропускається. Докладніше про поведінку див. у [Обрізання сесії](/uk/concepts/session-pruning). -### Потокова передача блоками +### Потокове передавання блоками ```json5 { @@ -637,19 +636,19 @@ harness app-server для Codex. Для загальної моделі див. blockStreamingBreak: "text_end", // text_end | message_end blockStreamingChunk: { minChars: 800, maxChars: 1200 }, blockStreamingCoalesce: { idleMs: 1000 }, - humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs) + humanDelay: { mode: "natural" }, // off | natural | custom (використовуйте minMs/maxMs) }, }, } ``` -- Для каналів, окрім Telegram, щоб увімкнути відповіді блоками, потрібно явно задати `*.blockStreaming: true`. -- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих облікових записів). Для Signal/Slack/Discord/Google Chat типове значення `minChars: 1500`. +- Для каналів, відмінних від Telegram, щоб увімкнути відповіді блоками, потрібно явно задати `*.blockStreaming: true`. +- Перевизначення для каналів: `channels..blockStreamingCoalesce` (і варіанти для окремих акаунтів). Для Signal/Slack/Discord/Google Chat типовим є `minChars: 1500`. - `humanDelay`: випадкова пауза між відповідями блоками. `natural` = 800–2500 мс. Перевизначення для окремого агента: `agents.list[].humanDelay`. -Подробиці про поведінку та розбиття на частини див. у [Потокова передача](/uk/concepts/streaming). +Докладніше про поведінку та нарізання блоків див. у [Потокове передавання](/uk/concepts/streaming). -### Індикатори набору +### Індикатори набору тексту ```json5 { @@ -665,7 +664,7 @@ harness app-server для Codex. Для загальної моделі див. - Типові значення: `instant` для прямих чатів/згадок, `message` для групових чатів без згадки. - Перевизначення для сесії: `session.typingMode`, `session.typingIntervalSeconds`. -Див. [Індикатори набору](/uk/concepts/typing-indicators). +Докладніше див. у [Індикатори набору тексту](/uk/concepts/typing-indicators). @@ -717,7 +716,7 @@ harness app-server для Codex. Для загальної моделі див. identityFile: "~/.ssh/id_ed25519", certificateFile: "~/.ssh/id_ed25519-cert.pub", knownHostsFile: "~/.ssh/known_hosts", - // Також підтримуються SecretRef / вбудований вміст: + // Також підтримуються SecretRefs / вбудований вміст: // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" }, // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" }, // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" }, @@ -766,24 +765,24 @@ harness app-server для Codex. Для загальної моделі див. } ``` - + -**Бекенд:** +**Backend:** - `docker`: локальне середовище виконання Docker (типово) -- `ssh`: універсальне віддалене середовище виконання через SSH +- `ssh`: загальне віддалене середовище виконання через SSH - `openshell`: середовище виконання OpenShell -Коли вибрано `backend: "openshell"`, специфічні для середовища виконання налаштування переносяться до +Коли вибрано `backend: "openshell"`, параметри, специфічні для середовища виконання, переносяться до `plugins.entries.openshell.config`. -**Конфігурація SSH-бекенда:** +**Конфігурація SSH backend:** - `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`: вбудований вміст або SecretRefs, які OpenClaw матеріалізує у тимчасові файли під час виконання - `strictHostKeyChecking` / `updateHostKeys`: параметри політики ключів хоста OpenSSH **Пріоритет SSH-автентифікації:** @@ -791,26 +790,26 @@ harness app-server для Codex. Для загальної моделі див. - `identityData` має пріоритет над `identityFile` - `certificateData` має пріоритет над `certificateFile` - `knownHostsData` має пріоритет над `knownHostsFile` -- Значення `*Data`, що спираються на SecretRef, визначаються зі знімка активного середовища виконання секретів до початку сеансу sandbox +- Значення `*Data`, що базуються на SecretRef, визначаються з активного знімка середовища виконання секретів до початку сесії Sandbox -**Поведінка SSH-бекенда:** +**Поведінка SSH backend:** -- одноразово ініціалізує віддалений робочий простір після створення або повторного створення +- один раз ініціалізує віддалений робочий простір після створення або повторного створення - потім зберігає віддалений робочий простір SSH як канонічний -- маршрутизує `exec`, файлові інструменти та шляхи медіа через SSH +- маршрутизує `exec`, файлові інструменти та шляхи до медіа через SSH - не синхронізує віддалені зміни назад на хост автоматично -- не підтримує браузерні контейнери sandbox +- не підтримує браузерні контейнери Sandbox **Доступ до робочого простору:** -- `none`: робочий простір sandbox для відповідної області в `~/.openclaw/sandboxes` -- `ro`: робочий простір sandbox у `/workspace`, робочий простір агента монтується тільки для читання в `/agent` -- `rw`: робочий простір агента монтується з читанням/записом у `/workspace` +- `none`: робочий простір Sandbox у межах області під `~/.openclaw/sandboxes` +- `ro`: робочий простір Sandbox у `/workspace`, робочий простір агента змонтований лише для читання в `/agent` +- `rw`: робочий простір агента змонтований для читання/запису в `/workspace` **Область:** -- `session`: окремий контейнер і робочий простір для кожної сесії -- `agent`: один контейнер і робочий простір для кожного агента (типово) +- `session`: контейнер + робочий простір для кожної сесії +- `agent`: один контейнер + робочий простір для кожного агента (типово) - `shared`: спільний контейнер і робочий простір (без ізоляції між сесіями) **Конфігурація Plugin OpenShell:** @@ -826,10 +825,10 @@ harness app-server для Codex. Для загальної моделі див. from: "openclaw", remoteWorkspaceDir: "/sandbox", remoteAgentWorkspaceDir: "/agent", - gateway: "lab", // optional - gatewayEndpoint: "https://lab.example", // optional - policy: "strict", // optional OpenShell policy id - providers: ["openai"], // optional + gateway: "lab", // необов’язково + gatewayEndpoint: "https://lab.example", // необов’язково + policy: "strict", // необов’язковий id політики OpenShell + providers: ["openai"], // необов’язково autoProviders: true, timeoutSeconds: 120, }, @@ -841,30 +840,30 @@ harness app-server для Codex. Для загальної моделі див. **Режим OpenShell:** -- `mirror`: ініціалізувати віддалене середовище з локального перед `exec`, синхронізувати назад після `exec`; локальний робочий простір залишається канонічним -- `remote`: одноразово ініціалізувати віддалене середовище під час створення sandbox, а потім зберігати віддалений робочий простір як канонічний +- `mirror`: ініціалізує віддалений простір з локального перед exec, синхронізує назад після exec; локальний робочий простір залишається канонічним +- `remote`: один раз ініціалізує віддалений простір під час створення Sandbox, потім віддалений робочий простір залишається канонічним -У режимі `remote` локальні зміни на хості, зроблені поза OpenClaw, не синхронізуються в sandbox автоматично після кроку ініціалізації. -Транспорт — SSH до sandbox OpenShell, але життєвим циклом sandbox і необов’язковою дзеркальною синхронізацією керує Plugin. +У режимі `remote` локальні редагування на хості, зроблені поза OpenClaw, не синхронізуються в Sandbox автоматично після етапу ініціалізації. +Транспортом є SSH до Sandbox OpenShell, але життєвим циклом Sandbox і необов’язковою синхронізацією mirror керує Plugin. -**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує виходу в мережу, доступного для запису кореня та користувача root. +**`setupCommand`** виконується один раз після створення контейнера (через `sh -lc`). Потребує вихідного мережевого доступу, кореневої файлової системи з можливістю запису та користувача root. -**Для контейнерів типовим є `network: "none"`** — установіть `"bridge"` (або власну bridge-мережу), якщо агенту потрібен вихідний доступ. -`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не задасте +**Типово контейнери мають `network: "none"`** — установіть `"bridge"` (або власну мережу bridge), якщо агенту потрібен вихідний доступ. +`"host"` заблоковано. `"container:"` типово заблоковано, якщо ви явно не встановите `sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true` (аварійний режим). -**Вхідні вкладення** розміщуються в `media/inbound/*` активного робочого простору. +**Вхідні вкладення** розміщуються в `media/inbound/*` в активному робочому просторі. -**`docker.binds`** монтує додаткові каталоги хоста; глобальні прив’язки та прив’язки для окремого агента об’єднуються. +**`docker.binds`** монтує додаткові каталоги хоста; глобальні та агентні binds об’єднуються. -**Браузер у sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний запит. Не потребує `browser.enabled` у `openclaw.json`. -Доступ спостерігача noVNC типово використовує автентифікацію VNC, і OpenClaw видає URL із короткоживучим токеном (замість показу пароля в спільному URL). +**Браузер Sandbox** (`sandbox.browser.enabled`): Chromium + CDP у контейнері. URL noVNC вставляється в системний запит. Не потребує `browser.enabled` у `openclaw.json`. +Доступ спостерігача через noVNC типово використовує автентифікацію VNC, і OpenClaw видає URL із короткочасним токеном (замість розкриття пароля у спільному URL). -- `allowHostControl: false` (типово) блокує націлення sandbox-сеансів на браузер хоста. -- `network` типово дорівнює `openclaw-sandbox-browser` (виділена bridge-мережа). Установлюйте `bridge`, лише якщо вам явно потрібна глобальна bridge-зв’язність. -- `cdpSourceRange` за потреби обмежує вхід CDP на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). -- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера sandbox. Якщо задано (включно з `[]`), воно замінює `docker.binds` для контейнера браузера. -- Типові параметри запуску визначені в `scripts/sandbox-browser-entrypoint.sh` і налаштовані для контейнерних хостів: +- `allowHostControl: false` (типово) блокує для сесій Sandbox націлювання на браузер хоста. +- `network` типово дорівнює `openclaw-sandbox-browser` (виділена мережа bridge). Установлюйте `bridge` лише тоді, коли вам явно потрібна загальна підключеність bridge. +- `cdpSourceRange` за потреби обмежує вхідний CDP-трафік на межі контейнера до діапазону CIDR (наприклад, `172.21.0.1/32`). +- `sandbox.browser.binds` монтує додаткові каталоги хоста лише в контейнер браузера Sandbox. Якщо задано (включно з `[]`), він замінює `docker.binds` для контейнера браузера. +- Типові параметри запуску визначено в `scripts/sandbox-browser-entrypoint.sh` і налаштовано для хостів контейнерів: - `--remote-debugging-address=127.0.0.1` - `--remote-debugging-port=` - `--user-data-dir=${HOME}/.chrome` @@ -881,38 +880,38 @@ harness app-server для Codex. Для загальної моделі див. - `--renderer-process-limit=2` - `--no-zygote` - `--metrics-recording-only` - - `--disable-extensions` (типово увімкнено) + - `--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`, коли ввімкнено `noSandbox`. + - плюс `--no-sandbox`, коли ввімкнено `noSandbox`. - Типові значення є базовими для образу контейнера; використовуйте власний образ браузера з власною - entrypoint, щоб змінити типові параметри контейнера. + точкою входу, щоб змінити типові параметри контейнера. -Браузерний sandbox і `sandbox.docker.binds` доступні лише для Docker. +Ізоляція браузера і `sandbox.docker.binds` підтримуються лише для Docker. -Зберіть образи: +Зібрати образи: ```bash -scripts/sandbox-setup.sh # основний образ sandbox +scripts/sandbox-setup.sh # основний образ Sandbox scripts/sandbox-browser-setup.sh # необов’язковий образ браузера ``` ### `agents.list` (перевизначення для окремого агента) -Використовуйте `agents.list[].tts`, щоб надати агенту власного TTS-провайдера, голос, модель, +Використовуйте `agents.list[].tts`, щоб дати агенту власного провайдера TTS, голос, модель, стиль або режим автоматичного TTS. Блок агента виконує глибоке об’єднання поверх глобального -`messages.tts`, тому спільні облікові дані можуть залишатися в одному місці, а окремі -агенти перевизначатимуть лише потрібні їм поля голосу або провайдера. Перевизначення -активного агента застосовується до автоматичних голосових відповідей, `/tts audio`, `/tts status` і -інструмента агента `tts`. Приклади провайдерів і пріоритетність див. у [Перетворення тексту на мовлення](/uk/tools/tts#per-agent-voice-overrides). +`messages.tts`, тому спільні облікові дані можна зберігати в одному місці, а окремі +агенти можуть перевизначати лише потрібні їм поля голосу або провайдера. Перевизначення +активного агента застосовується до автоматичних голосових відповідей, `/tts audio`, `/tts status` +і до інструмента агента `tts`. Приклади провайдерів і пріоритетів див. у [Text-to-speech](/uk/tools/tts#per-agent-voice-overrides). ```json5 { @@ -924,18 +923,18 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б name: "Main Agent", workspace: "~/.openclaw/workspace", agentDir: "~/.openclaw/agents/main/agent", - model: "anthropic/claude-opus-4-6", // or { primary, fallbacks } + model: "anthropic/claude-opus-4-6", // або { primary, fallbacks } thinkingDefault: "high", // перевизначення рівня thinking для окремого агента reasoningDefault: "on", // перевизначення видимості reasoning для окремого агента fastModeDefault: false, // перевизначення fast mode для окремого агента embeddedHarness: { runtime: "auto", fallback: "pi" }, - params: { cacheRetention: "none" }, // перевизначає відповідні defaults.models params за ключем + params: { cacheRetention: "none" }, // перевизначає ключі відповідних defaults.models params tts: { providers: { elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" }, }, }, - skills: ["docs-search"], // replaces agents.defaults.skills when set + skills: ["docs-search"], // замінює agents.defaults.skills, якщо задано identity: { name: "Samantha", theme: "helpful sloth", @@ -966,28 +965,28 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `id`: стабільний id агента (обов’язково). -- `default`: якщо задано кілька, перемагає перший (записується попередження). Якщо не задано жодного, типовим є перший елемент списку. -- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва значення (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не задасте `fallbacks: []`. -- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних перевизначень агента, як-от `cacheRetention`, `temperature` або `maxTokens`, не дублюючи весь каталог моделей. -- `tts`: необов’язкові перевизначення text-to-speech для окремого агента. Цей блок глибоко об’єднується поверх `messages.tts`, тому спільні облікові дані провайдера й політику резервування варто тримати в `messages.tts`, а тут задавати лише значення, специфічні для персони, наприклад провайдера, голос, модель, стиль або автоматичний режим. -- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не задано, агент успадковує `agents.defaults.skills`, якщо він налаштований; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. -- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для окремого повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є допустимими; для Google Gemini `adaptive` зберігає динамічний thinking, яким керує провайдер (`thinkingLevel` пропускається в Gemini 3/3.1, `thinkingBudget: -1` у Gemini 2.5). -- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для окремого повідомлення або сесії. -- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для окремого повідомлення або сесії. -- `embeddedHarness`: необов’язкове перевизначення політики низькорівневого harness для окремого агента. Використовуйте `{ runtime: "codex" }`, щоб зробити один агент лише для Codex, тоді як інші агенти зберігатимуть типовий резервний варіант PI в режимі `auto`. -- `runtime`: необов’язковий дескриптор runtime для окремого агента. Використовуйте `type: "acp"` разом із типовими значеннями `runtime.acp` (`agent`, `backend`, `mode`, `cwd`), коли агент має типово використовувати сесії harness ACP. +- `id`: стабільний ідентифікатор агента (обов’язково). +- `default`: коли задано кілька, перший має пріоритет (записується попередження). Якщо не задано жодного, типовим є перший запис у списку. +- `model`: форма рядка перевизначає лише `primary`; форма об’єкта `{ primary, fallbacks }` перевизначає обидва (`[]` вимикає глобальні резервні моделі). Завдання Cron, які перевизначають лише `primary`, усе одно успадковують типові резервні моделі, якщо ви не встановите `fallbacks: []`. +- `params`: параметри потоку для окремого агента, що об’єднуються поверх вибраного запису моделі в `agents.defaults.models`. Використовуйте це для специфічних для агента перевизначень, таких як `cacheRetention`, `temperature` або `maxTokens`, без дублювання всього каталогу моделей. +- `tts`: необов’язкові перевизначення text-to-speech для окремого агента. Блок глибоко об’єднується поверх `messages.tts`, тому спільні облікові дані провайдера та політику резервного переходу зберігайте в `messages.tts`, а тут задавайте лише значення, специфічні для персони, такі як провайдер, голос, модель, стиль або автоматичний режим. +- `skills`: необов’язковий список дозволених Skills для окремого агента. Якщо не вказано, агент успадковує `agents.defaults.skills`, якщо його задано; явний список замінює типові значення замість об’єднання, а `[]` означає відсутність Skills. +- `thinkingDefault`: необов’язковий типовий рівень thinking для окремого агента (`off | minimal | low | medium | high | xhigh | adaptive | max`). Перевизначає `agents.defaults.thinkingDefault` для цього агента, коли не задано перевизначення для повідомлення або сесії. Вибраний профіль провайдера/моделі визначає, які значення є припустимими; для Google Gemini `adaptive` зберігає динамічний thinking, яким керує провайдер (`thinkingLevel` пропускається для Gemini 3/3.1, `thinkingBudget: -1` для Gemini 2.5). +- `reasoningDefault`: необов’язкова типова видимість reasoning для окремого агента (`on | off | stream`). Застосовується, коли не задано перевизначення reasoning для повідомлення або сесії. +- `fastModeDefault`: необов’язкове типове значення fast mode для окремого агента (`true | false`). Застосовується, коли не задано перевизначення fast mode для повідомлення або сесії. +- `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`: список дозволених id агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). -- Захист успадкування sandbox: якщо сесія запитувача працює в sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без sandbox. -- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: `false`). +- `identity` виводить типові значення: `ackReaction` із `emoji`, `mentionPatterns` із `name`/`emoji`. +- `subagents.allowAgents`: список дозволених ідентифікаторів агентів для `sessions_spawn` (`["*"]` = будь-який; типово: лише той самий агент). +- Захист успадкування Sandbox: якщо сесія ініціатора працює в Sandbox, `sessions_spawn` відхиляє цілі, які запускалися б без Sandbox. +- `subagents.requireAgentId`: коли `true`, блокує виклики `sessions_spawn`, у яких не вказано `agentId` (примушує до явного вибору профілю; типово: false). --- ## Маршрутизація між кількома агентами -Запускайте кілька ізольованих агентів в одному Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). +Запускайте кілька ізольованих агентів усередині одного Gateway. Див. [Multi-Agent](/uk/concepts/multi-agent). ```json5 { @@ -1004,16 +1003,16 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -### Поля відповідності прив’язки +### Поля збігу прив’язки -- `type` (необов’язково): `route` для звичайної маршрутизації (за відсутності `type` типовим є `route`), `acp` для постійних прив’язок розмов ACP. +- `type` (необов’язково): `route` для звичайної маршрутизації (якщо тип відсутній, типово використовується route), `acp` для постійних прив’язок розмов ACP. - `match.channel` (обов’язково) - `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` @@ -1022,11 +1021,11 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б 5. `match.accountId: "*"` (на рівні всього каналу) 6. Типовий агент -У межах кожного рівня перемагає перший відповідний запис у `bindings`. +У межах кожного рівня перший відповідний запис `bindings` має пріоритет. -Для записів `type: "acp"` OpenClaw визначає відповідність за точною ідентичністю розмови (`match.channel` + обліковий запис + `match.peer.id`) і не використовує порядок рівнів маршрутної прив’язки, наведений вище. +Для записів `type: "acp"` OpenClaw виконує зіставлення за точною ідентичністю розмови (`match.channel` + account + `match.peer.id`) і не використовує наведений вище порядок рівнів route-прив’язок. -### Профілі доступу для окремих агентів +### Профілі доступу для окремого агента @@ -1046,7 +1045,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1075,7 +1074,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б - + ```json5 { @@ -1121,7 +1120,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б -Подробиці про пріоритети див. у [Sandbox і Tools для Multi-Agent](/uk/tools/multi-agent-sandbox-tools). +Докладніше про пріоритети див. у [Sandbox і Tools для Multi-Agent](/uk/tools/multi-agent-sandbox-tools). --- @@ -1147,22 +1146,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" } }], @@ -1172,37 +1171,37 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` - + - **`scope`**: базова стратегія групування сесій для контекстів групового чату. - `per-sender` (типово): кожен відправник отримує ізольовану сесію в межах контексту каналу. - - `global`: усі учасники в контексті каналу ділять одну спільну сесію (використовуйте лише тоді, коли потрібен спільний контекст). + - `global`: усі учасники в контексті каналу використовують одну спільну сесію (використовуйте лише тоді, коли потрібен спільний контекст). - **`dmScope`**: як групуються DM. - - `main`: усі DM спільно використовують основну сесію. - - `per-peer`: ізоляція за id відправника між каналами. - - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для багатокористувацьких inbox). + - `main`: усі DM спільно використовують головну сесію. + - `per-peer`: ізоляція за ідентифікатором відправника між каналами. + - `per-channel-peer`: ізоляція за каналом + відправником (рекомендовано для вхідних скриньок із кількома користувачами). - `per-account-channel-peer`: ізоляція за обліковим записом + каналом + відправником (рекомендовано для кількох облікових записів). -- **`identityLinks`**: мапа канонічних id на peer із префіксом провайдера для спільного використання сесії між каналами. -- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за локальним часом; `idle` скидає після `idleMinutes`. Якщо задано обидва варіанти, перемагає той, що спливає раніше. Актуальність щоденного скидання використовує `sessionStartedAt` рядка сесії; актуальність скидання за простоєм використовує `lastInteractionAt`. Фонові/системні записи, як-от Heartbeat, пробудження Cron, сповіщення exec і службові записи Gateway, можуть оновлювати `updatedAt`, але вони не підтримують актуальність щоденних/неактивних сесій. +- **`identityLinks`**: мапа канонічних ідентифікаторів до peer із префіксами провайдерів для спільного використання сесій між каналами. +- **`reset`**: основна політика скидання. `daily` скидає о `atHour` за місцевим часом; `idle` скидає після `idleMinutes`. Якщо налаштовано обидва, спрацьовує те, що закінчиться раніше. Для щоденного скидання свіжість визначається через `sessionStartedAt` у рядку сесії; для скидання за неактивністю — через `lastInteractionAt`. Фонові/системні записи, такі як Heartbeat, пробудження Cron, сповіщення exec і службові записи gateway, можуть оновлювати `updatedAt`, але не підтримують свіжість щоденних/неактивних сесій. - **`resetByType`**: перевизначення за типом (`direct`, `group`, `thread`). Застарілий `dm` приймається як псевдонім для `direct`. -- **`parentForkMaxTokens`**: максимальна кількість `totalTokens` батьківської сесії, дозволена під час створення розгалуженої сесії потоку (типово `100000`). - - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову сесію потоку замість успадкування історії transcript батьківської сесії. - - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти розгалуження від батьківської сесії. -- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для основного кошика direct-chat. -- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей назад між агентами під час обміну агент-агент (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. -- **`sendPolicy`**: відповідність за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона перемагає. -- **`maintenance`**: очищення сховища сесій + керування зберіганням. - - `mode`: `warn` лише видає попередження; `enforce` застосовує очищення. - - `pruneAfter`: поріг давності для застарілих записів (типово `30d`). +- **`parentForkMaxTokens`**: максимальний дозволений `totalTokens` батьківської сесії під час створення форкнутої thread-сесії (типово `100000`). + - Якщо `totalTokens` батьківської сесії перевищує це значення, OpenClaw починає нову thread-сесію замість успадкування історії транскрипту батьківської. + - Установіть `0`, щоб вимкнути цей захист і завжди дозволяти форк батьківської сесії. +- **`mainKey`**: застаріле поле. Runtime завжди використовує `"main"` для головного контейнера прямого чату. +- **`agentToAgent.maxPingPongTurns`**: максимальна кількість відповідей у зворотному напрямку між агентами під час обміну агент-до-агента (ціле число, діапазон: `0`–`5`). `0` вимикає ланцюжок ping-pong. +- **`sendPolicy`**: зіставлення за `channel`, `chatType` (`direct|group|channel`, із застарілим псевдонімом `dm`), `keyPrefix` або `rawKeyPrefix`. Перша заборона має пріоритет. +- **`maintenance`**: очищення сховища сесій + контроль зберігання. + - `mode`: `warn` лише виводить попередження; `enforce` застосовує очищення. + - `pruneAfter`: граничний вік для застарілих записів (типово `30d`). - `maxEntries`: максимальна кількість записів у `sessions.json` (типово `500`). - - `rotateBytes`: обертати `sessions.json`, коли він перевищує цей розмір (типово `10mb`). - - `resetArchiveRetention`: термін зберігання архівів transcript `*.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`**: глобальні типові значення для можливостей сесій, прив’язаних до thread. - `enabled`: головний типовий перемикач (провайдери можуть перевизначати; Discord використовує `channels.discord.threadBindings.enabled`) - - `idleHours`: типове автоматичне зняття фокуса після неактивності в годинах (`0` вимикає; провайдери можуть перевизначати) - - `maxAgeHours`: типове жорстке максимальне життя в годинах (`0` вимикає; провайдери можуть перевизначати) + - `idleHours`: типове автоматичне зняття фокуса через неактивність у годинах (`0` вимикає; провайдери можуть перевизначати) + - `maxAgeHours`: типове жорстке максимальне обмеження віку в годинах (`0` вимикає; провайдери можуть перевизначати) @@ -1213,7 +1212,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, @@ -1228,7 +1227,7 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б }, }, inbound: { - debounceMs: 2000, // 0 disables + debounceMs: 2000, // 0 вимикає byChannel: { whatsapp: 5000, slack: 1500, @@ -1242,36 +1241,36 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б Перевизначення для каналу/облікового запису: `channels..responsePrefix`, `channels..accounts..responsePrefix`. -Визначення (перемагає найспецифічніше): обліковий запис → канал → глобальне. `""` вимикає й зупиняє каскад. `"auto"` виводить `[{identity.name}]`. +Визначення (найспецифічніше має пріоритет): обліковий запис → канал → глобальний. `""` вимикає і зупиняє каскад. `"auto"` виводить `[{identity.name}]`. **Змінні шаблону:** -| Змінна | Опис | Приклад | -| ----------------- | ---------------------- | --------------------------- | -| `{model}` | Коротка назва моделі | `claude-opus-4-6` | +| Змінна | Опис | Приклад | +| ----------------- | ------------------------ | --------------------------- | +| `{model}` | Коротка назва моделі | `claude-opus-4-6` | | `{modelFull}` | Повний ідентифікатор моделі | `anthropic/claude-opus-4-6` | -| `{provider}` | Назва провайдера | `anthropic` | +| `{provider}` | Назва провайдера | `anthropic` | | `{thinkingLevel}` | Поточний рівень thinking | `high`, `low`, `off` | -| `{identity.name}` | Назва identity агента | (те саме, що й `"auto"`) | +| `{identity.name}` | Назва ідентичності агента | (те саме, що й `"auto"`) | Змінні нечутливі до регістру. `{think}` є псевдонімом для `{thinkingLevel}`. -### Реакція-підтвердження +### Реакція підтвердження - Типово використовується `identity.emoji` активного агента, інакше `"👀"`. Установіть `""`, щоб вимкнути. - Перевизначення для каналу: `channels..ackReaction`, `channels..accounts..ackReaction`. -- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення identity. -- Область дії: `group-mentions` (типово), `group-all`, `direct`, `all`. -- `removeAckAfterReply`: видаляє підтвердження після відповіді в Slack, Discord і Telegram. +- Порядок визначення: обліковий запис → канал → `messages.ackReaction` → резервне значення з identity. +- Область: `group-mentions` (типово), `group-all`, `direct`, `all`. +- `removeAckAfterReply`: прибирає підтвердження після відповіді в каналах, що підтримують реакції, як-от Slack, Discord, Telegram, WhatsApp і BlueBubbles. - `messages.statusReactions.enabled`: вмикає реакції статусу життєвого циклу в Slack, Discord і Telegram. - У Slack і Discord, якщо не задано, реакції статусу залишаються ввімкненими, коли активні реакції-підтвердження. - У Telegram, щоб увімкнути реакції статусу життєвого циклу, явно задайте `true`. + У Slack і Discord, якщо параметр не задано, реакції статусу залишаються ввімкненими, коли активні реакції підтвердження. + У Telegram, щоб увімкнути реакції статусу життєвого циклу, явно встановіть `true`. -### Вхідний debounce +### Вхідне дебаунсування -Групує швидкі текстові повідомлення від одного відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування обходять debounce. +Об’єднує швидкі текстові повідомлення від того самого відправника в один хід агента. Медіа/вкладення скидаються негайно. Команди керування оминають дебаунсування. -### TTS (перетворення тексту на мовлення) +### TTS (text-to-speech) ```json5 { @@ -1320,12 +1319,12 @@ 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`. -- Вбудовані мовленнєві провайдери належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin TTS-провайдера, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий id провайдера `edge` приймається як псевдонім для `microsoft`. +- `summaryModel` перевизначає `agents.defaults.model.primary` для автоматичного підсумку. +- `modelOverrides` типово ввімкнено; `modelOverrides.allowProvider` типово дорівнює `false` (вмикається явно). +- Для API-ключів резервними є `ELEVENLABS_API_KEY`/`XI_API_KEY` і `OPENAI_API_KEY`. +- Вбудовані провайдери мовлення належать Plugin. Якщо задано `plugins.allow`, включіть кожен Plugin провайдера TTS, який хочете використовувати, наприклад `microsoft` для Edge TTS. Застарілий ідентифікатор провайдера `edge` приймається як псевдонім для `microsoft`. - `providers.openai.baseUrl` перевизначає кінцеву точку OpenAI TTS. Порядок визначення: конфігурація, потім `OPENAI_TTS_BASE_URL`, потім `https://api.openai.com/v1`. -- Коли `providers.openai.baseUrl` вказує на кінцеву точку не OpenAI, OpenClaw розглядає її як OpenAI-сумісний TTS-сервер і послаблює перевірку моделі/голосу. +- Коли `providers.openai.baseUrl` вказує на кінцеву точку, що не належить OpenAI, OpenClaw трактує її як OpenAI-сумісний сервер TTS і послаблює перевірку моделі/голосу. --- @@ -1360,21 +1359,21 @@ scripts/sandbox-browser-setup.sh # необов’язковий образ б } ``` -- `talk.provider` має відповідати ключу в `talk.providers`, коли налаштовано кілька Talk-провайдерів. -- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності та автоматично мігруються в `talk.providers.`. -- Для voice ID використовуються резервні значення `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. +- `talk.provider` має збігатися з ключем у `talk.providers`, коли налаштовано кілька провайдерів Talk. +- Застарілі плоскі ключі Talk (`talk.voiceId`, `talk.voiceAliases`, `talk.modelId`, `talk.outputFormat`, `talk.apiKey`) призначені лише для сумісності й автоматично мігруються до `talk.providers.`. +- Для voice ID резервними є `ELEVENLABS_VOICE_ID` або `SAG_VOICE_ID`. - `providers.*.apiKey` приймає звичайні текстові рядки або об’єкти SecretRef. -- Резервне значення `ELEVENLABS_API_KEY` застосовується лише тоді, коли API-ключ Talk не налаштовано. -- `providers.*.voiceAliases` дозволяє директивам Talk використовувати дружні назви. -- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовує локальний помічник MLX у macOS. Якщо не задано, у macOS використовується `mlx-community/Soprano-80M-bf16`. -- Відтворення MLX у macOS виконується через вбудований помічник `openclaw-mlx-tts`, якщо він наявний, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. -- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується для розпізнавання мовлення Talk в iOS/macOS. Залиште не заданим, щоб використовувати типове значення пристрою. -- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача перед надсиланням transcript. Якщо не задано, зберігається типове вікно паузи платформи (`700 ms` у macOS і Android, `900 ms` в iOS). +- Резервний варіант `ELEVENLABS_API_KEY` застосовується лише тоді, коли не налаштовано API-ключ Talk. +- `providers.*.voiceAliases` дає змогу директивам Talk використовувати дружні назви. +- `providers.mlx.modelId` вибирає репозиторій Hugging Face, який використовується локальним помічником MLX на macOS. Якщо параметр не задано, macOS використовує `mlx-community/Soprano-80M-bf16`. +- Відтворення MLX на macOS працює через вбудований помічник `openclaw-mlx-tts`, якщо він наявний, або через виконуваний файл у `PATH`; `OPENCLAW_MLX_TTS_BIN` перевизначає шлях до помічника для розробки. +- `speechLocale` задає ідентифікатор локалі BCP 47, який використовується розпізнаванням мовлення Talk на iOS/macOS. Не задавайте параметр, щоб використовувати типову локаль пристрою. +- `silenceTimeoutMs` керує тим, як довго режим Talk чекає після тиші користувача перед надсиланням транскрипту. Якщо параметр не задано, зберігається типове вікно паузи платформи (`700 ms` на macOS і Android, `900 ms` на iOS). --- ## Пов’язане -- [Довідник конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації -- [Конфігурація](/uk/gateway/configuration) — типові завдання та швидке налаштування +- [Довідник із конфігурації](/uk/gateway/configuration-reference) — усі інші ключі конфігурації +- [Конфігурація](/uk/gateway/configuration) — поширені завдання та швидке налаштування - [Приклади конфігурації](/uk/gateway/configuration-examples) diff --git a/docs/uk/gateway/opentelemetry.md b/docs/uk/gateway/opentelemetry.md index 51dcb4e50..23f28dcbe 100644 --- a/docs/uk/gateway/opentelemetry.md +++ b/docs/uk/gateway/opentelemetry.md @@ -1,33 +1,33 @@ --- read_when: - - Ви хочете надсилати використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry - - Ви налаштовуєте трасування, метрики або журнали для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда - - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати інформаційні панелі чи сповіщення + - Ви хочете надсилати дані про використання моделей OpenClaw, потік повідомлень або метрики сесій до колектора OpenTelemetry + - Ви налаштовуєте трасування, метрики або логи для Grafana, Datadog, Honeycomb, New Relic, Tempo чи іншого OTLP-бекенда + - Вам потрібні точні назви метрик, назви спанів або форми атрибутів, щоб створювати панелі моніторингу чи сповіщення summary: Експортуйте діагностику OpenClaw до будь-якого колектора OpenTelemetry через Plugin diagnostics-otel (OTLP/HTTP) -title: Експорт OpenTelemetry +title: експорт OpenTelemetry x-i18n: - generated_at: "2026-04-26T01:42:41Z" + generated_at: "2026-04-26T04:44:05Z" model: gpt-5.4 provider: openai - source_hash: d670d7188d9c075b97743eae82e0aa999ac458a51c978a755e847e0b1648fa44 + source_hash: 2f2389c4efc2984d27e571152ce3cfea2ffeddc99084695f1c6ab6c97e6b7f7b source_path: gateway/opentelemetry.md workflow: 15 --- -OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel`, -використовуючи **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, -працює без змін у коді. Для локальних файлових журналів і способів їх читання див. -[Журналювання](/uk/logging). +OpenClaw експортує діагностику через вбудований Plugin `diagnostics-otel` +з використанням **OTLP/HTTP (protobuf)**. Будь-який колектор або бекенд, що приймає OTLP/HTTP, +працює без змін у коді. Для локальних файлових логів і способів їх читання див. +[Логування](/uk/logging). ## Як це працює разом - **Події діагностики** — це структуровані внутрішньопроцесні записи, які створюються - Gateway і вбудованими плагінами для запусків моделей, потоку повідомлень, сесій, черг + Gateway і вбудованими Plugin для запусків моделей, потоку повідомлень, сесій, черг та exec. - **Plugin `diagnostics-otel`** підписується на ці події та експортує їх як - OpenTelemetry **метрики**, **трасування** і **журнали** через OTLP/HTTP. -- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і сам plugin, - тому внутрішньопроцесні накладні витрати за замовчуванням залишаються майже нульовими. + OpenTelemetry **метрики**, **трасування** і **логи** через OTLP/HTTP. +- Експортери підключаються лише тоді, коли ввімкнено і поверхню діагностики, і Plugin, + тож внутрішньопроцесні витрати за замовчуванням залишаються майже нульовими. ## Швидкий старт @@ -56,7 +56,7 @@ OpenClaw експортує діагностику через вбудовани } ``` -Ви також можете ввімкнути plugin з CLI: +Ви також можете ввімкнути Plugin з CLI: ```bash openclaw plugins enable diagnostics-otel @@ -68,16 +68,16 @@ openclaw plugins enable diagnostics-otel ## Експортовані сигнали -| Сигнал | Що до нього входить | -| ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | -| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запуску, потоку повідомлень, смуг черг, стану сесій, exec і тиску на пам’ять. | -| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | -| **Журнали** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | +| Сигнал | Що він містить | +| ----------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| **Метрики** | Лічильники та гістограми для використання токенів, вартості, тривалості запусків, потоку повідомлень, смуг черги, стану сесій, exec і тиску пам’яті. | +| **Трасування** | Спани для використання моделей, викликів моделей, виконання інструментів, exec, обробки webhook/повідомлень, збирання контексту та циклів інструментів. | +| **Логи** | Структуровані записи `logging.file`, експортовані через OTLP, коли ввімкнено `diagnostics.otel.logs`. | Перемикайте `traces`, `metrics` і `logs` незалежно. Усі три за замовчуванням увімкнені, коли `diagnostics.otel.enabled` має значення true. -## Довідник конфігурації +## Довідник з конфігурації ```json5 { @@ -112,54 +112,54 @@ openclaw plugins enable diagnostics-otel ### Змінні середовища -| Variable | Призначення | -| ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Змінна | Призначення | +| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `OTEL_EXPORTER_OTLP_ENDPOINT` | Перевизначає `diagnostics.otel.endpoint`. Якщо значення вже містить `/v1/traces`, `/v1/metrics` або `/v1/logs`, воно використовується як є. | -| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення кінцевих точок для окремих сигналів, які використовуються, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація для конкретного сигналу має пріоритет над змінною середовища для конкретного сигналу, яка має пріоритет над спільною кінцевою точкою. | -| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | -| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає wire protocol (сьогодні враховується лише `http/protobuf`). | -| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть значення `gen_ai_latest_experimental`, щоб надсилати останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені, низькокардинальні семантичні атрибути незалежно від цього. | -| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | +| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` / `OTEL_EXPORTER_OTLP_METRICS_ENDPOINT` / `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Перевизначення endpoint для конкретного сигналу, що використовується, коли відповідний ключ конфігурації `diagnostics.otel.*Endpoint` не задано. Конфігурація конкретного сигналу має пріоритет над env конкретного сигналу, а той — над спільним endpoint. | +| `OTEL_SERVICE_NAME` | Перевизначає `diagnostics.otel.serviceName`. | +| `OTEL_EXPORTER_OTLP_PROTOCOL` | Перевизначає протокол передачі даних (сьогодні враховується лише `http/protobuf`). | +| `OTEL_SEMCONV_STABILITY_OPT_IN` | Встановіть `gen_ai_latest_experimental`, щоб виводити останній експериментальний атрибут GenAI span (`gen_ai.provider.name`) замість застарілого `gen_ai.system`. Метрики GenAI завжди використовують обмежені семантичні атрибути з низькою кардинальністю незалежно від цього. | +| `OPENCLAW_OTEL_PRELOADED` | Встановіть значення `1`, якщо інший preload або хост-процес уже зареєстрував глобальний OpenTelemetry SDK. Тоді Plugin пропускає власний життєвий цикл NodeSDK, але все одно підключає слухачі діагностики та враховує `traces`/`metrics`/`logs`. | ## Конфіденційність і захоплення вмісту -Необроблений вміст моделей/інструментів **не** експортується за замовчуванням. Спани містять обмежені -ідентифікатори (channel, provider, model, категорія помилки, лише хешовані request id) -і ніколи не включають текст промпту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів або -ключі сесій. +Необроблений вміст моделі/інструментів **не** експортується за замовчуванням. Спани містять +обмежені ідентифікатори (канал, провайдер, модель, категорія помилки, лише хешовані id запитів) +і ніколи не включають текст запиту, текст відповіді, вхідні дані інструментів, вихідні дані інструментів +або ключі сесії. Встановлюйте `diagnostics.otel.captureContent.*` у `true` лише тоді, коли ваш колектор і -політика зберігання схвалені для тексту промптів, відповідей, інструментів або system prompt. -Кожен підключ окремо вмикається за принципом opt-in: +політика зберігання схвалені для тексту запитів, відповідей, інструментів або +системних запитів. Кожен підключ окремо вимагає явного ввімкнення: -- `inputMessages` — вміст запитів користувача. -- `outputMessages` — вміст відповідей моделі. -- `toolInputs` — корисні навантаження аргументів інструментів. -- `toolOutputs` — корисні навантаження результатів інструментів. -- `systemPrompt` — зібраний system/developer prompt. +- `inputMessages` — вміст запиту користувача. +- `outputMessages` — вміст відповіді моделі. +- `toolInputs` — payload аргументів інструменту. +- `toolOutputs` — payload результатів інструменту. +- `systemPrompt` — зібраний системний/розробницький запит. -Коли ввімкнено будь-який підключ, спани моделей та інструментів отримують обмежені, редаговані +Коли ввімкнено будь-який підключ, спани моделі та інструментів отримують обмежені, відредаговані атрибути `openclaw.content.*` лише для цього класу. ## Семплювання та скидання -- **Трасування:** `diagnostics.otel.sampleRate` (лише для root span, `0.0` відкидає все, +- **Трасування:** `diagnostics.otel.sampleRate` (лише для root-span, `0.0` відкидає все, `1.0` зберігає все). - **Метрики:** `diagnostics.otel.flushIntervalMs` (мінімум `1000`). -- **Журнали:** OTLP-журнали враховують `logging.level` (рівень файлового журналу). Редагування - консолі **не** застосовується до OTLP-журналів. Для інсталяцій із великим обсягом - краще використовувати семплювання/фільтрацію на колекторі OTLP, а не локальне семплювання. +- **Логи:** OTLP-логи враховують `logging.level` (рівень файлового логу). Редагування + для консолі **не** застосовується до OTLP-логів. Для інсталяцій із великим обсягом даних слід + надавати перевагу семплюванню/фільтрації колектора OTLP замість локального семплювання. ## Експортовані метрики ### Використання моделі -- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) +- `openclaw.tokens` (лічильник, attrs: `openclaw.token`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.agent`) - `openclaw.cost.usd` (лічильник, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.run.duration_ms` (гістограма, attrs: `openclaw.channel`, `openclaw.provider`, `openclaw.model`) - `openclaw.context.tokens` (гістограма, attrs: `openclaw.context`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`) -- `gen_ai.client.token.usage` (гістограма, метрика GenAI semantic conventions, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) -- `gen_ai.client.operation.duration` (гістограма, секунди, метрика GenAI semantic conventions, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язково `error.type`) +- `gen_ai.client.token.usage` (гістограма, метрика семантичних конвенцій GenAI, attrs: `gen_ai.token.type` = `input`/`output`, `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`) +- `gen_ai.client.operation.duration` (гістограма, секунди, метрика семантичних конвенцій GenAI, attrs: `gen_ai.provider.name`, `gen_ai.operation.name`, `gen_ai.request.model`, необов’язковий `error.type`) ### Потік повідомлень @@ -200,14 +200,14 @@ openclaw plugins enable diagnostics-otel - `openclaw.model.usage` - `openclaw.channel`, `openclaw.provider`, `openclaw.model` - `openclaw.tokens.*` (input/output/cache_read/cache_write/total) - - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, коли ввімкнено найновіші семантичні конвенції GenAI - `gen_ai.request.model`, `gen_ai.operation.name`, `gen_ai.usage.*` - `openclaw.run` - `openclaw.outcome`, `openclaw.channel`, `openclaw.provider`, `openclaw.model`, `openclaw.errorCategory` - `openclaw.model.call` - - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, якщо ввімкнено найновіші GenAI semantic conventions + - `gen_ai.system` за замовчуванням або `gen_ai.provider.name`, коли ввімкнено найновіші семантичні конвенції GenAI - `gen_ai.request.model`, `gen_ai.operation.name`, `openclaw.provider`, `openclaw.model`, `openclaw.api`, `openclaw.transport` - - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA від upstream request id провайдера; сирі id не експортуються) + - `openclaw.provider.request_id_hash` (обмежений хеш на основі SHA для id запиту до висхідного провайдера; сирі id не експортуються) - `openclaw.tool.execution` - `gen_ai.tool.name`, `openclaw.toolName`, `openclaw.errorCategory`, `openclaw.tool.params.*` - `openclaw.exec` @@ -223,26 +223,26 @@ openclaw plugins enable diagnostics-otel - `openclaw.session.stuck` - `openclaw.state`, `openclaw.ageMs`, `openclaw.queueDepth` - `openclaw.context.assembled` - - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту prompt, history, response або ключів сесії) + - `openclaw.prompt.size`, `openclaw.history.size`, `openclaw.context.tokens`, `openclaw.errorCategory` (без вмісту запиту, історії, відповіді чи ключа сесії) - `openclaw.tool.loop` - - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, params або виводу інструмента) + - `openclaw.toolName`, `openclaw.outcome`, `openclaw.iterations`, `openclaw.errorCategory` (без повідомлень циклу, параметрів або виводу інструменту) - `openclaw.memory.pressure` - `openclaw.memory.level`, `openclaw.memory.heap_used_bytes`, `openclaw.memory.rss_bytes` -Коли захоплення вмісту явно ввімкнено, спани моделей та інструментів також можуть -містити обмежені, редаговані атрибути `openclaw.content.*` для конкретних -класів вмісту, які ви явно ввімкнули. +Коли захоплення вмісту явно ввімкнено, спани моделі та інструментів також можуть +містити обмежені, відредаговані атрибути `openclaw.content.*` для конкретних +класів вмісту, які ви ввімкнули. ## Каталог подій діагностики -Події нижче лежать в основі метрик і спанів, наведених вище. Plugins також можуть -підписуватися на них напряму без експорту OTLP. +Наведені нижче події лежать в основі наведених вище метрик і спанів. Plugin також можуть підписуватися +на них безпосередньо без експорту OTLP. **Використання моделі** -- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/channel, - id сесій. `usage` — це облік провайдера/ходу для вартості та телеметрії; - `context.used` — це поточний знімок prompt/context і він може бути меншим за +- `model.usage` — токени, вартість, тривалість, контекст, провайдер/модель/канал, + id сесій. `usage` — це облік провайдера/ходу для вартості й телеметрії; + `context.used` — це поточний знімок запиту/контексту, і він може бути меншим за `usage.total` провайдера, коли залучено кешований ввід або виклики циклу інструментів. **Потік повідомлень** @@ -261,13 +261,13 @@ openclaw plugins enable diagnostics-otel **Exec** - `exec.process.completed` — підсумковий результат, тривалість, ціль, режим, код - виходу та тип збою. Текст команди й робочі каталоги не + завершення та тип помилки. Текст команди й робочі каталоги не включаються. ## Без експортера -Ви можете зберегти події діагностики доступними для plugins або користувацьких приймачів -без запуску `diagnostics-otel`: +Ви можете залишити події діагностики доступними для Plugin або власних приймачів без +запуску `diagnostics-otel`: ```json5 { @@ -276,7 +276,7 @@ openclaw plugins enable diagnostics-otel ``` Для цільового виводу налагодження без підвищення `logging.level` використовуйте -прапорці діагностики. Прапорці нечутливі до регістру та підтримують wildcard-и (наприклад, `telegram.*` або +прапори діагностики. Прапори нечутливі до регістру й підтримують шаблони (наприклад, `telegram.*` або `*`): ```json5 @@ -291,9 +291,9 @@ openclaw plugins enable diagnostics-otel OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway ``` -Вивід прапорців потрапляє до стандартного файла журналу (`logging.file`) і все ще -редагується `logging.redactSensitive`. Повний посібник: -[Прапорці діагностики](/uk/diagnostics/flags). +Вивід прапорів надходить до стандартного файлу журналу (`logging.file`) і все ще +редагується через `logging.redactSensitive`. Повний посібник: +[Прапори діагностики](/uk/diagnostics/flags). ## Вимкнення @@ -306,10 +306,10 @@ OPENCLAW_DIAGNOSTICS=telegram.http,telegram.payload openclaw gateway Ви також можете не додавати `diagnostics-otel` до `plugins.allow` або виконати `openclaw plugins disable diagnostics-otel`. -## Пов’язані матеріали +## Пов’язане -- [Журналювання](/uk/logging) — файлові журнали, консольний вивід, tailing через CLI та вкладка Logs у Control UI -- [Внутрішня будова журналювання Gateway](/uk/gateway/logging) — стилі журналів WS, префікси підсистем і захоплення консолі -- [Прапорці діагностики](/uk/diagnostics/flags) — цільові прапорці журналювання налагодження -- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент пакета підтримки для операторів (окремо від експорту OTEL) -- [Довідник конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` +- [Логування](/uk/logging) — файлові логи, консольний вивід, tailing у CLI та вкладка Logs у Control UI +- [Внутрішня структура логування Gateway](/uk/gateway/logging) — стилі WS-логів, префікси підсистем і захоплення консолі +- [Прапори діагностики](/uk/diagnostics/flags) — прапори цільових налагоджувальних логів +- [Експорт діагностики](/uk/gateway/diagnostics) — інструмент для створення пакетів підтримки операторів (окремо від експорту OTEL) +- [Довідник з конфігурації](/uk/gateway/configuration-reference#diagnostics) — повний довідник полів `diagnostics.*` diff --git a/docs/uk/plugins/manifest.md b/docs/uk/plugins/manifest.md index 56591564e..ee5d52945 100644 --- a/docs/uk/plugins/manifest.md +++ b/docs/uk/plugins/manifest.md @@ -1,47 +1,47 @@ --- read_when: - - Ви створюєте Plugin OpenClaw + - Ви створюєте Plugin для OpenClaw - Вам потрібно надати схему конфігурації Plugin або налагодити помилки валідації Plugin -summary: Маніфест Plugin + вимоги до JSON schema (сувора валідація конфігурації) -title: маніфест Plugin +summary: Вимоги до маніфесту Plugin + JSON schema (сувора валідація конфігурації) +title: Маніфест Plugin x-i18n: - generated_at: "2026-04-26T04:25:16Z" + generated_at: "2026-04-26T04:44:03Z" model: gpt-5.4 provider: openai - source_hash: 8e33fe37d43ea78c941fbce5af3564c4fae5740e04a0dfaa321163f94b5ef876 + source_hash: 6b4988c8d383d27e10d04bc327d45e41714456288922aa1b108e4c5609e4a803 source_path: plugins/manifest.md workflow: 15 --- -Ця сторінка стосується лише **нативного маніфесту Plugin OpenClaw**. +Ця сторінка стосується лише **власного маніфесту Plugin OpenClaw**. -Сумісні формати структури пакунків див. у [Plugin bundles](/uk/plugins/bundles). +Сумісні макети пакетів описано в [Пакети Plugin](/uk/plugins/bundles). -Сумісні формати пакунків використовують інші файли маніфесту: +Сумісні формати пакетів використовують інші файли маніфесту: -- Пакунок Codex: `.codex-plugin/plugin.json` -- Пакунок Claude: `.claude-plugin/plugin.json` або типова структура компонента Claude +- Пакет Codex: `.codex-plugin/plugin.json` +- Пакет Claude: `.claude-plugin/plugin.json` або стандартний макет компонента Claude без маніфесту -- Пакунок Cursor: `.cursor-plugin/plugin.json` +- Пакет Cursor: `.cursor-plugin/plugin.json` -OpenClaw також автоматично виявляє ці структури пакунків, але вони не проходять валідацію +OpenClaw також автоматично виявляє ці макети пакетів, але вони не проходять валідацію за схемою `openclaw.plugin.json`, описаною тут. -Для сумісних пакунків OpenClaw наразі читає метадані пакунка разом із оголошеними -коренями skill, коренями команд Claude, типовими значеннями `settings.json` пакунка Claude, -типовими значеннями LSP пакунка Claude та підтримуваними наборами hook, коли структура -відповідає очікуванням середовища виконання OpenClaw. +Для сумісних пакетів OpenClaw зараз зчитує метадані пакета разом з оголошеними +коренями Skills, коренями команд Claude, значеннями за замовчуванням з `settings.json` пакета Claude, +значеннями LSP за замовчуванням пакета Claude та підтримуваними наборами хуків, якщо макет відповідає +очікуванням середовища виконання OpenClaw. -Кожен нативний Plugin OpenClaw **має** містити файл `openclaw.plugin.json` у +Кожен власний Plugin OpenClaw **повинен** містити файл `openclaw.plugin.json` у **корені Plugin**. OpenClaw використовує цей маніфест для валідації конфігурації -**без виконання коду Plugin**. Відсутні або недійсні маніфести вважаються +**без виконання коду Plugin**. Відсутні або невалідні маніфести вважаються помилками Plugin і блокують валідацію конфігурації. -Повний посібник із системи Plugin див. у [Plugins](/uk/tools/plugin). -Про нативну модель можливостей і поточні рекомендації щодо зовнішньої сумісності: +Дивіться повний посібник із системи Plugin: [Plugins](/uk/tools/plugin). +Для власної моделі можливостей і поточних рекомендацій щодо зовнішньої сумісності: [Модель можливостей](/uk/plugins/architecture#public-capability-model). -## Для чого потрібен цей файл +## Що робить цей файл `openclaw.plugin.json` — це метадані, які OpenClaw зчитує **до завантаження коду вашого Plugin**. Усе нижче має бути достатньо легким для перевірки без запуску @@ -49,17 +49,16 @@ OpenClaw також автоматично виявляє ці структур **Використовуйте його для:** -- ідентичності Plugin, валідації конфігурації та підказок UI конфігурації +- ідентичності Plugin, валідації конфігурації та підказок для UI конфігурації - метаданих автентифікації, онбордингу та налаштування (псевдонім, автоувімкнення, змінні середовища провайдера, варіанти автентифікації) -- підказок активації для поверхонь контрольної площини +- підказок активації для поверхонь control-plane - скороченого володіння сімействами моделей - статичних знімків володіння можливостями (`contracts`) -- метаданих QA runner, які може перевіряти спільний хост `openclaw qa` +- метаданих запускника QA, які може перевіряти спільний хост `openclaw qa` - метаданих конфігурації, специфічних для каналу, що об’єднуються в поверхні каталогу та валідації **Не використовуйте його для:** реєстрації поведінки під час виконання, оголошення -точок входу коду або метаданих встановлення npm. Це має належати коду вашого Plugin -і `package.json`. +точок входу коду або метаданих встановлення npm. Вони належать до коду вашого Plugin і `package.json`. ## Мінімальний приклад @@ -139,70 +138,70 @@ OpenClaw також автоматично виявляє ці структур ## Довідник полів верхнього рівня -| Поле | Обов’язкове | Тип | Що воно означає | +| Поле | Обов’язкове | Тип | Що воно означає | | ------------------------------------ | ----------- | -------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Канонічний ідентифікатор Plugin. Саме цей ідентифікатор використовується в `plugins.entries.`. | +| `id` | Так | `string` | Канонічний id Plugin. Це id, який використовується в `plugins.entries.`. | | `configSchema` | Так | `object` | Вбудована JSON Schema для конфігурації цього Plugin. | -| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений типово. Опустіть це поле або встановіть будь-яке значення, відмінне від `true`, щоб Plugin лишався вимкненим типово. | -| `legacyPluginIds` | Ні | `string[]` | Застарілі ідентифікатори, які нормалізуються до цього канонічного ідентифікатора Plugin. | -| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають автоматично вмикати цей Plugin, коли на них посилаються auth, config або model refs. | -| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | -| `channels` | Ні | `string[]` | Ідентифікатори каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | -| `providers` | Ні | `string[]` | Ідентифікатори провайдерів, якими володіє цей Plugin. | -| `providerDiscoveryEntry` | Ні | `string` | Полегшений шлях до модуля виявлення провайдера, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | -| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автозавантаження Plugin до запуску середовища виконання. | -| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт контрольної площини для майбутнього доступного лише для читання переліку, онбордингу, засобів вибору моделей, псевдонімів і придушення без завантаження середовища виконання Plugin. | -| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, якими володіє маніфест, для маршрутів провайдера, які ядро має класифікувати до завантаження середовища виконання провайдера. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend CLI inference, якими володіє цей Plugin. Використовуються для автоактивації під час запуску на основі явних config refs. | -| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдер або backend CLI, для яких слід перевіряти синтетичний hook auth, що належить Plugin, під час холодного виявлення моделей до завантаження середовища виконання. | -| `nonSecretAuthMarkers` | Ні | `string[]` | Значення-заповнювачі API key, якими володіє вбудований Plugin і які представляють несекретний локальний стан, стан OAuth або облікові дані ambient. | -| `commandAliases` | Ні | `object[]` | Імена команд, якими володіє цей Plugin і які мають видавати діагностику config та CLI з урахуванням Plugin до завантаження середовища виконання. | -| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку auth/status провайдера. Для нових Plugin віддавайте перевагу `setup.providers[].envVars`; OpenClaw і далі читає це поле протягом періоду знецінення. | -| `providerAuthAliases` | Ні | `Record` | Ідентифікатори провайдерів, які мають повторно використовувати інший ідентифікатор провайдера для пошуку auth, наприклад провайдер кодування, який використовує той самий API key базового провайдера та auth-profile. | -| `channelEnvVars` | Ні | `Record` | Полегшені метадані env каналу, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів через env або поверхонь auth, які мають бачити типові допоміжні засоби запуску/конфігурації. | -| `providerAuthChoices` | Ні | `object[]` | Полегшені метадані варіантів auth для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. | -| `activation` | Ні | `object` | Полегшені метадані планувальника активації для завантаження за тригерами провайдера, команди, каналу, маршруту та можливостей. Лише метадані; фактичною поведінкою під час виконання, як і раніше, володіє середовище виконання Plugin. | -| `setup` | Ні | `object` | Полегшені дескриптори setup/onboarding, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | -| `qaRunners` | Ні | `object[]` | Полегшені дескриптори QA runner, які використовує спільний хост `openclaw qa` до завантаження середовища виконання Plugin. | -| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх hook auth, 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` | Метадані конфігурації каналу, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | -| `skills` | Ні | `string[]` | Каталоги Skills для завантаження, відносні до кореня Plugin. | +| `enabledByDefault` | Ні | `true` | Позначає вбудований Plugin як увімкнений за замовчуванням. Не вказуйте це поле або задайте будь-яке значення, відмінне від `true`, щоб Plugin лишався вимкненим за замовчуванням. | +| `legacyPluginIds` | Ні | `string[]` | Застарілі id, які нормалізуються до цього канонічного id Plugin. | +| `autoEnableWhenConfiguredProviders` | Ні | `string[]` | id провайдерів, які мають автоматично вмикати цей Plugin, коли автентифікація, конфігурація або посилання на моделі згадують їх. | +| `kind` | Ні | `"memory"` \| `"context-engine"` | Оголошує ексклюзивний тип Plugin, який використовується `plugins.slots.*`. | +| `channels` | Ні | `string[]` | id каналів, якими володіє цей Plugin. Використовується для виявлення та валідації конфігурації. | +| `providers` | Ні | `string[]` | id провайдерів, якими володіє цей Plugin. | +| `providerDiscoveryEntry` | Ні | `string` | Шлях до легковагового модуля виявлення провайдерів, відносний до кореня Plugin, для метаданих каталогу провайдерів у межах маніфесту, які можна завантажити без активації повного середовища виконання Plugin. | +| `modelSupport` | Ні | `object` | Скорочені метадані сімейства моделей, якими володіє маніфест, що використовуються для автоматичного завантаження Plugin до виконання. | +| `modelCatalog` | Ні | `object` | Декларативні метадані каталогу моделей для провайдерів, якими володіє цей Plugin. Це контракт control-plane для майбутнього read-only переліку, онбордингу, засобів вибору моделей, псевдонімів і приглушення без завантаження середовища виконання Plugin. | +| `providerEndpoints` | Ні | `object[]` | Метадані хостів/baseUrl кінцевих точок, якими володіє маніфест, для маршрутів провайдерів, які ядро має класифікувати до завантаження середовища виконання провайдера. | +| `cliBackends` | Ні | `string[]` | id backend-вузлів інференсу CLI, якими володіє цей Plugin. Використовується для автоактивації під час запуску на основі явних посилань у конфігурації. | +| `syntheticAuthRefs` | Ні | `string[]` | Посилання на провайдерів або backend CLI, для яких під час cold discovery моделей до завантаження середовища виконання слід перевірити синтетичний хук автентифікації, що належить Plugin. | +| `nonSecretAuthMarkers` | Ні | `string[]` | Значення placeholder API key, що належать вбудованому Plugin і представляють не секретний локальний стан, OAuth або стан наявних облікових даних. | +| `commandAliases` | Ні | `object[]` | Назви команд, якими володіє цей Plugin, що мають породжувати обізнану про Plugin конфігурацію та діагностику CLI до завантаження середовища виконання. | +| `providerAuthEnvVars` | Ні | `Record` | Застарілі сумісні метадані env для пошуку автентифікації/статусу провайдера. Для нових Plugin надавайте перевагу `setup.providers[].envVars`; OpenClaw усе ще зчитує це протягом періоду знецінення. | +| `providerAuthAliases` | Ні | `Record` | id провайдерів, які мають повторно використовувати інший id провайдера для пошуку автентифікації, наприклад провайдер для кодування, що спільно використовує API key базового провайдера та профілі автентифікації. | +| `channelEnvVars` | Ні | `Record` | Легковагові метадані env для каналів, які OpenClaw може перевіряти без завантаження коду Plugin. Використовуйте це для налаштування каналів або поверхонь автентифікації, керованих env, які мають бачити загальні помічники запуску/конфігурації. | +| `providerAuthChoices` | Ні | `object[]` | Легковагові метадані варіантів автентифікації для засобів вибору під час онбордингу, визначення пріоритетного провайдера та простого зв’язування прапорців CLI. | +| `activation` | Ні | `object` | Легковагові метадані планувальника активації для завантаження, що запускається провайдером, командою, каналом, маршрутом і можливістю. Лише метадані; фактична поведінка все ще належить середовищу виконання Plugin. | +| `setup` | Ні | `object` | Легковагові дескриптори налаштування/онбордингу, які поверхні виявлення та налаштування можуть перевіряти без завантаження середовища виконання Plugin. | +| `qaRunners` | Ні | `object[]` | Легковагові дескриптори запускників QA, які використовуються спільним хостом `openclaw qa` до завантаження середовища виконання Plugin. | +| `contracts` | Ні | `object` | Статичний знімок вбудованих можливостей для зовнішніх хуків автентифікації, мовлення, транскрипції в реальному часі, голосу в реальному часі, розуміння медіа, генерації зображень, генерації музики, генерації відео, web-fetch, web search і володіння інструментами. | +| `mediaUnderstandingProviderMetadata` | Ні | `Record` | Легковагові значення за замовчуванням для розуміння медіа для id провайдерів, оголошених у `contracts.mediaUnderstandingProviders`. | +| `channelConfigs` | Ні | `Record` | Метадані конфігурації каналів, якими володіє маніфест і які об’єднуються в поверхні виявлення та валідації до завантаження середовища виконання. | +| `skills` | Ні | `string[]` | Каталоги Skill для завантаження, відносні до кореня Plugin. | | `name` | Ні | `string` | Людинозрозуміла назва Plugin. | -| `description` | Ні | `string` | Короткий опис, що показується в поверхнях Plugin. | +| `description` | Ні | `string` | Короткий опис, що показується на поверхнях Plugin. | | `version` | Ні | `string` | Інформаційна версія Plugin. | -| `uiHints` | Ні | `Record` | Мітки UI, placeholders і підказки щодо чутливості для полів конфігурації. | +| `uiHints` | Ні | `Record` | Підписи UI, placeholder-и та підказки щодо чутливості для полів конфігурації. | ## Довідник `providerAuthChoices` -Кожен запис `providerAuthChoices` описує один варіант онбордингу або auth. +Кожен запис `providerAuthChoices` описує один варіант онбордингу або автентифікації. OpenClaw зчитує це до завантаження середовища виконання провайдера. -Потік налаштування провайдера віддає перевагу цим варіантам із маніфесту, а потім, для сумісності, повертається до метаданих wizard під час виконання -та варіантів каталогу встановлення. +Потік налаштування провайдера надає перевагу цим варіантам із маніфесту, а потім для сумісності +повертається до метаданих wizard середовища виконання та варіантів каталогу встановлення. -| Поле | Обов’язкове | Тип | Що воно означає | -| --------------------- | ----------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- | -| `provider` | Так | `string` | Ідентифікатор провайдера, до якого належить цей варіант. | -| `method` | Так | `string` | Ідентифікатор методу auth, до якого треба спрямувати обробку. | -| `choiceId` | Так | `string` | Стабільний ідентифікатор варіанта auth, який використовується в потоках онбордингу та CLI. | -| `choiceLabel` | Ні | `string` | Мітка для користувача. Якщо пропущено, OpenClaw використовує `choiceId`. | -| `choiceHint` | Ні | `string` | Короткий допоміжний текст для засобу вибору. | -| `assistantPriority` | Ні | `number` | Менші значення сортуються раніше в інтерактивних засобах вибору, керованих асистентом. | -| `assistantVisibility` | Ні | `"visible"` \| `"manual-only"` | Приховує варіант із засобів вибору асистента, але залишає доступним ручний вибір через CLI. | -| `deprecatedChoiceIds` | Ні | `string[]` | Застарілі ідентифікатори варіантів, які мають перенаправляти користувачів на цей варіант-заміну. | -| `groupId` | Ні | `string` | Необов’язковий ідентифікатор групи для групування пов’язаних варіантів. | -| `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">` | У яких поверхнях онбордингу має з’являтися цей варіант. Якщо пропущено, типово використовується `["text-inference"]`. | +| Поле | Обов’язкове | Тип | Що воно означає | +| -------------------- | ----------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `provider` | Так | `string` | id провайдера, до якого належить цей варіант. | +| `method` | Так | `string` | id методу автентифікації, до якого слід спрямувати. | +| `choiceId` | Так | `string` | Стабільний id варіанта автентифікації, який використовується в потоках онбордингу та 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` | Внутрішній ключ опції для простих потоків автентифікації з одним прапорцем. | +| `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 володіє ім’ям команди, яке користувачі можуть -помилково додати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw +Використовуйте `commandAliases`, коли Plugin володіє назвою команди часу виконання, яку користувачі +можуть помилково вказати в `plugins.allow` або спробувати запустити як кореневу команду CLI. OpenClaw використовує ці метадані для діагностики без імпорту коду середовища виконання Plugin. ```json @@ -219,32 +218,32 @@ OpenClaw зчитує це до завантаження середовища в | Поле | Обов’язкове | Тип | Що воно означає | | ------------ | ----------- | ----------------- | -------------------------------------------------------------------------- | -| `name` | Так | `string` | Ім’я команди, що належить цьому Plugin. | +| `name` | Так | `string` | Назва команди, яка належить цьому Plugin. | | `kind` | Ні | `"runtime-slash"` | Позначає псевдонім як slash-команду чату, а не кореневу команду CLI. | -| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід пропонувати для операцій CLI, якщо вона існує. | +| `cliCommand` | Ні | `string` | Пов’язана коренева команда CLI, яку слід запропонувати для операцій CLI, якщо вона існує. | ## Довідник `activation` -Використовуйте `activation`, коли Plugin може дешево оголосити, які події -контрольної площини мають включати його до плану активації/завантаження. +Використовуйте `activation`, коли Plugin може недорого оголосити, які події control-plane +мають включати його в план активації/завантаження. -Цей блок — метадані планувальника, а не API життєвого циклу. Він не реєструє -поведінку під час виконання, не замінює `register(...)` і не гарантує, що -код Plugin уже було виконано. Планувальник активації використовує ці поля, щоб -звузити набір кандидатів Plugin перед поверненням до наявних метаданих володіння маніфесту, -таких як `providers`, `channels`, `commandAliases`, `setup.providers`, -`contracts.tools` і hooks. +Цей блок є метаданими планувальника, а не API життєвого циклу. Він не реєструє +поведінку часу виконання, не замінює `register(...)` і не гарантує, що код +Plugin уже виконався. Планувальник активації використовує ці поля, щоб +звузити коло кандидатів Plugin перед поверненням до наявних метаданих +володіння з маніфесту, таких як `providers`, `channels`, `commandAliases`, `setup.providers`, +`contracts.tools` і хуки. Надавайте перевагу найвужчим метаданим, які вже описують володіння. Використовуйте `providers`, `channels`, `commandAliases`, дескриптори setup або `contracts`, коли ці поля виражають зв’язок. Використовуйте `activation` для додаткових підказок планувальнику, які не можна подати через ці поля володіння. -Цей блок містить лише метадані. Він не реєструє поведінку під час виконання і не -замінює `register(...)`, `setupEntry` або інші runtime/plugin entrypoints. -Поточні споживачі використовують його як підказку для звуження перед ширшим завантаженням Plugin, тому -відсутність метаданих активації зазвичай лише погіршує продуктивність; вона не має -змінювати коректність, доки ще існують застарілі fallback на володіння маніфестом. +Цей блок — лише метадані. Він не реєструє поведінку часу виконання та не +замінює `register(...)`, `setupEntry` чи інші точки входу часу виконання/Plugin. +Поточні споживачі використовують його як підказку для звуження кола перед ширшим +завантаженням Plugin, тому відсутність метаданих активації зазвичай лише впливає на продуктивність; +вона не повинна змінювати коректність, доки все ще існують застарілі резервні механізми володіння маніфестом. ```json { @@ -258,37 +257,36 @@ OpenClaw зчитує це до завантаження середовища в } ``` -| Поле | Обов’язкове | Тип | Що воно означає | -| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | -| `onProviders` | Ні | `string[]` | Ідентифікатори провайдерів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCommands` | Ні | `string[]` | Ідентифікатори команд, які мають включати цей Plugin до планів активації/завантаження. | -| `onChannels` | Ні | `string[]` | Ідентифікатори каналів, які мають включати цей Plugin до планів активації/завантаження. | -| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin до планів активації/завантаження. | -| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки можливостей, що використовуються плануванням активації контрольної площини. За можливості віддавайте перевагу вужчим полям. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ---------------- | ----------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------ | +| `onProviders` | Ні | `string[]` | id провайдерів, які мають включати цей Plugin у плани активації/завантаження. | +| `onCommands` | Ні | `string[]` | id команд, які мають включати цей Plugin у плани активації/завантаження. | +| `onChannels` | Ні | `string[]` | id каналів, які мають включати цей Plugin у плани активації/завантаження. | +| `onRoutes` | Ні | `string[]` | Типи маршрутів, які мають включати цей Plugin у плани активації/завантаження. | +| `onCapabilities` | Ні | `Array<"provider" \| "channel" \| "tool" \| "hook">` | Загальні підказки щодо можливостей, які використовуються для планування активації control-plane. За можливості надавайте перевагу вужчим полям. | Поточні активні споживачі: -- планування CLI, запущене командою, повертається до застарілих +- планування CLI, ініційоване командою, повертається до застарілого `commandAliases[].cliCommand` або `commandAliases[].name` -- планування setup/каналу, запущене каналом, повертається до застарілого володіння `channels[]`, - коли явні метадані активації каналу відсутні -- планування setup/runtime, запущене провайдером, повертається до застарілого - володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації провайдера - відсутні +- планування setup/каналу, ініційоване каналом, повертається до застарілого володіння + `channels[]`, коли явні метадані активації каналу відсутні +- планування setup/часу виконання, ініційоване провайдером, повертається до застарілого + володіння `providers[]` і верхньорівневого `cliBackends[]`, коли явні метадані активації провайдера відсутні -Діагностика планувальника може розрізняти явні підказки активації та fallback на +Діагностика планувальника може відрізняти явні підказки активації від резервного володіння маніфестом. Наприклад, `activation-command-hint` означає, що -збіглося `activation.onCommands`, а `manifest-command-alias` означає, що -планувальник натомість використав володіння `commandAliases`. Ці мітки причин призначені для -діагностики хоста й тестів; авторам Plugin слід і далі оголошувати метадані, +спрацювало `activation.onCommands`, тоді як `manifest-command-alias` означає, що +планувальник використав натомість володіння `commandAliases`. Ці мітки причин призначені для +діагностики хоста і тестів; авторам Plugin слід і далі оголошувати ті метадані, які найкраще описують володіння. ## Довідник `qaRunners` -Використовуйте `qaRunners`, коли Plugin додає один або кілька transport runners під -спільним коренем `openclaw qa`. Зберігайте ці метадані легкими та статичними; фактичною -реєстрацією CLI під час виконання, як і раніше, володіє -полегшена поверхня `runtime-api.ts`, що експортує `qaRunnerCliRegistrations`. +Використовуйте `qaRunners`, коли Plugin додає один або кілька транспортних запускників під +спільний корінь `openclaw qa`. Зберігайте ці метадані легковаговими та статичними; фактичною +реєстрацією CLI все одно керує середовище виконання Plugin через легковагову +поверхню `runtime-api.ts`, яка експортує `qaRunnerCliRegistrations`. ```json { @@ -308,8 +306,8 @@ OpenClaw зчитує це до завантаження середовища в ## Довідник `setup` -Використовуйте `setup`, коли поверхням setup та onboarding потрібні легкі метадані Plugin, -якими Plugin володіє, до завантаження середовища виконання. +Використовуйте `setup`, коли поверхням налаштування й онбордингу потрібні недорогі метадані Plugin, +якими він володіє, до завантаження середовища виконання. ```json { @@ -328,61 +326,61 @@ OpenClaw зчитує це до завантаження середовища в } ``` -Верхньорівневий `cliBackends` залишається чинним і далі описує backend CLI inference. -`setup.cliBackends` — це поверхня дескрипторів, специфічна для setup, для -потоків контрольної площини/setup, які мають залишатися лише на рівні метаданих. +Верхньорівневе `cliBackends` залишається валідним і надалі описує backend-вузли інференсу CLI. +`setup.cliBackends` — це специфічна для setup поверхня дескрипторів для +потоків control-plane/setup, які мають залишатися лише метаданими. -Якщо вони присутні, `setup.providers` і `setup.cliBackends` є бажаною -поверхнею пошуку descriptor-first для виявлення setup. Якщо дескриптор лише -звужує набір кандидатів Plugin, а setup все одно потребує багатших runtime hooks під час налаштування, -встановіть `requiresRuntime: true` і залиште `setup-api` як +Якщо `setup.providers` і `setup.cliBackends` присутні, вони є бажаною +поверхнею пошуку на основі дескрипторів для виявлення setup. Якщо дескриптор лише +звужує кандидата Plugin, а setup все ще потребує багатших runtime-хуків часу налаштування, +задайте `requiresRuntime: true` і залиште `setup-api` як резервний шлях виконання. -OpenClaw також включає `setup.providers[].envVars` у типові пошуки auth провайдера та -змінних середовища. `providerAuthEnvVars` і далі підтримується через адаптер сумісності -протягом періоду знецінення, але небудовані Plugin, які все ще його використовують, -отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env setup/status -у `setup.providers[].envVars`. +OpenClaw також включає `setup.providers[].envVars` до загальних пошуків автентифікації провайдера та +env vars. `providerAuthEnvVars` залишається підтримуваним через адаптер сумісності +протягом періоду знецінення, але невбудовані Plugin, які все ще його використовують, +отримують діагностику маніфесту. Нові Plugin мають розміщувати метадані env для setup/статусу +в `setup.providers[].envVars`. OpenClaw також може виводити прості варіанти setup з `setup.providers[].authMethods`, коли запис setup недоступний або коли `setup.requiresRuntime: false` -означає, що runtime setup не потрібне. Явні записи `providerAuthChoices` і далі мають перевагу -для власних міток, прапорців CLI, області онбордингу та метаданих асистента. +оголошує, що runtime setup не потрібне. Явні записи `providerAuthChoices` і далі є пріоритетними +для власних підписів, прапорців CLI, scope онбордингу та метаданих асистента. -Установлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для -поверхні setup. OpenClaw трактує явне `false` як контракт лише на рівні дескриптора +Встановлюйте `requiresRuntime: false` лише тоді, коли цих дескрипторів достатньо для +поверхні setup. OpenClaw трактує явне `false` як контракт лише на основі дескрипторів і не виконуватиме `setup-api` або `openclaw.setupEntry` для пошуку setup. Якщо -Plugin лише з дескрипторами все ж постачає один із цих runtime entrypoints setup, -OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущене -`requiresRuntime` зберігає застарілу поведінку fallback, щоб наявні Plugin, які додали +Plugin лише з дескрипторами все ж містить один із цих runtime-записів setup, +OpenClaw повідомляє додаткову діагностику й продовжує його ігнорувати. Пропущений +`requiresRuntime` зберігає застарілу резервну поведінку, щоб наявні Plugin, які додали дескриптори без цього прапорця, не ламалися. -Оскільки пошук setup може виконувати код `setup-api`, яким володіє Plugin, -нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` мають залишатися унікальними -серед виявлених Plugin. Неоднозначне володіння завершується безпечною відмовою, а не вибором +Оскільки пошук setup може виконувати код `setup-api`, що належить Plugin, +нормалізовані значення `setup.providers[].id` і `setup.cliBackends[]` повинні залишатися унікальними +серед виявлених Plugin. Неоднозначне володіння закривається з помилкою, а не вибирає переможця за порядком виявлення. -Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про дрейф дескриптора, якщо -`setup-api` реєструє провайдера або backend CLI, якого не оголошують дескриптори маніфесту, +Коли runtime setup все ж виконується, діагностика реєстру setup повідомляє про дрейф дескрипторів, якщо +`setup-api` реєструє провайдера або backend CLI, яких дескриптори маніфесту не оголошують, або якщо для дескриптора немає відповідної runtime-реєстрації. Ці діагностики є додатковими і не відхиляють застарілі Plugin. ### Довідник `setup.providers` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------- | ----------- | ---------- | ------------------------------------------------------------------------------------- | -| `id` | Так | `string` | Ідентифікатор провайдера, що відкривається під час setup або onboarding. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `authMethods` | Ні | `string[]` | Ідентифікатори методів setup/auth, які підтримує цей провайдер без завантаження повного runtime. | -| `envVars` | Ні | `string[]` | Змінні середовища, які типові поверхні setup/status можуть перевіряти до завантаження runtime Plugin. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------ | ----------- | ---------- | ------------------------------------------------------------------------------------- | +| `id` | Так | `string` | id провайдера, що показується під час setup або онбордингу. Нормалізовані id мають бути глобально унікальними. | +| `authMethods`| Ні | `string[]` | id методів setup/автентифікації, які цей провайдер підтримує без завантаження повного runtime. | +| `envVars` | Ні | `string[]` | Env vars, які загальні поверхні setup/статусу можуть перевіряти до завантаження runtime Plugin. | ### Поля `setup` -| Поле | Обов’язкове | Тип | Що воно означає | -| ------------------ | ----------- | ---------- | --------------------------------------------------------------------------------------------------- | -| `providers` | Ні | `object[]` | Дескриптори setup провайдерів, доступні під час setup та onboarding. | -| `cliBackends` | Ні | `string[]` | Ідентифікатори backend для часу setup, що використовуються для descriptor-first пошуку setup. Зберігайте нормалізовані ідентифікатори глобально унікальними. | -| `configMigrations` | Ні | `string[]` | Ідентифікатори міграцій конфігурації, якими володіє поверхня setup цього Plugin. | -| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескриптором. | +| Поле | Обов’язкове | Тип | Що воно означає | +| ------------------ | ----------- | ---------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | Ні | `object[]` | Дескриптори setup провайдера, що показуються під час setup і онбордингу. | +| `cliBackends` | Ні | `string[]` | id backend-ів часу setup, що використовуються для пошуку setup спочатку за дескрипторами. Нормалізовані id мають бути глобально унікальними. | +| `configMigrations` | Ні | `string[]` | id міграцій конфігурації, якими володіє поверхня setup цього Plugin. | +| `requiresRuntime` | Ні | `boolean` | Чи потребує setup виконання `setup-api` після пошуку за дескрипторами. | ## Довідник `uiHints` @@ -403,19 +401,19 @@ OpenClaw повідомляє додаткову діагностику й пр Кожна підказка для поля може містити: -| Поле | Тип | Що воно означає | -| ------------- | ---------- | -------------------------------------- | -| `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` | Текст placeholder для полів форми. | ## Довідник `contracts` Використовуйте `contracts` лише для статичних метаданих володіння можливостями, які OpenClaw може -зчитати без імпорту runtime Plugin. +зчитувати без імпорту runtime Plugin. ```json { @@ -436,47 +434,47 @@ OpenClaw повідомляє додаткову діагностику й пр } ``` -Кожен список необов’язковий: +Кожен список є необов’язковим: -| Поле | Тип | Що воно означає | -| -------------------------------- | ---------- | ----------------------------------------------------------------------- | -| `embeddedExtensionFactories` | `string[]` | Ідентифікатори фабрик розширень app-server Codex, наразі `codex-app-server`. | -| `agentToolResultMiddleware` | `string[]` | Ідентифікатори runtime, для яких вбудований Plugin може зареєструвати middleware результатів інструментів. | -| `externalAuthProviders` | `string[]` | Ідентифікатори провайдерів, hook зовнішнього auth-profile яких належить цьому 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, для перевірок вбудованих контрактів. | +| Поле | Тип | Що воно означає | +| -------------------------------- | ---------- | -------------------------------------------------------------------------- | +| `embeddedExtensionFactories` | `string[]` | id фабрик розширень app-server Codex, наразі `codex-app-server`. | +| `agentToolResultMiddleware` | `string[]` | id runtime, для яких вбудований Plugin може реєструвати middleware результатів інструментів. | +| `externalAuthProviders` | `string[]` | id провайдерів, чий хук профілю зовнішньої автентифікації належить цьому Plugin. | +| `speechProviders` | `string[]` | id провайдерів мовлення, якими володіє цей Plugin. | +| `realtimeTranscriptionProviders` | `string[]` | id провайдерів транскрипції в реальному часі, якими володіє цей Plugin. | +| `realtimeVoiceProviders` | `string[]` | id провайдерів голосу в реальному часі, якими володіє цей Plugin. | +| `memoryEmbeddingProviders` | `string[]` | id провайдерів embedding-ів пам’яті, якими володіє цей Plugin. | +| `mediaUnderstandingProviders` | `string[]` | id провайдерів розуміння медіа, якими володіє цей Plugin. | +| `imageGenerationProviders` | `string[]` | id провайдерів генерації зображень, якими володіє цей Plugin. | +| `videoGenerationProviders` | `string[]` | id провайдерів генерації відео, якими володіє цей Plugin. | +| `webFetchProviders` | `string[]` | id провайдерів web-fetch, якими володіє цей Plugin. | +| `webSearchProviders` | `string[]` | id провайдерів web search, якими володіє цей Plugin. | +| `tools` | `string[]` | Назви агентських інструментів, якими володіє цей Plugin, для перевірок вбудованих контрактів. | -`contracts.embeddedExtensionFactories` збережено для фабрик розширень лише для вбудованого -app-server Codex. Вбудовані перетворення результатів інструментів повинні +`contracts.embeddedExtensionFactories` збережено для фабрик розширень +лише для app-server Codex у вбудованому режимі. Вбудовані трансформації результатів інструментів мають оголошувати `contracts.agentToolResultMiddleware` і реєструватися через `api.registerAgentToolResultMiddleware(...)`. Зовнішні Plugin не можуть -реєструвати middleware результатів інструментів, оскільки цей шов може переписувати високодовірений вивід інструмента -до того, як його побачить модель. +реєструвати middleware результатів інструментів, оскільки цей seam може переписувати +вихід інструмента з високим рівнем довіри до того, як модель його побачить. -Plugin провайдерів, що реалізують `resolveExternalAuthProfiles`, повинні оголошувати +Plugin провайдерів, які реалізують `resolveExternalAuthProfiles`, мають оголошувати `contracts.externalAuthProviders`. Plugin без цього оголошення все ще працюють -через застарілий fallback сумісності, але цей fallback повільніший -і буде вилучений після завершення вікна міграції. +через застарілий резервний механізм сумісності, але він повільніший і +буде вилучений після завершення вікна міграції. -Вбудовані провайдери memory embedding повинні оголошувати -`contracts.memoryEmbeddingProviders` для кожного ідентифікатора адаптера, який вони відкривають, включно з +Вбудовані провайдери embedding-ів пам’яті мають оголошувати +`contracts.memoryEmbeddingProviders` для кожного id адаптера, який вони надають, включно з вбудованими адаптерами, такими як `local`. Окремі шляхи CLI використовують цей контракт маніфесту, -щоб завантажувати лише Plugin-власника до того, як повне runtime Gateway +щоб завантажувати лише Plugin-власник до того, як повний runtime Gateway зареєструє провайдерів. ## Довідник `mediaUnderstandingProviderMetadata` -Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер media-understanding має -типові моделі, пріоритет fallback для автоauth або підтримку нативних документів, які -типовим допоміжним засобам ядра потрібні до завантаження runtime. Ключі також мають бути оголошені в +Використовуйте `mediaUnderstandingProviderMetadata`, коли провайдер розуміння медіа має +моделі за замовчуванням, пріоритет резервної автоавтентифікації або вбудовану підтримку документів, які +потрібні загальним помічникам ядра до завантаження runtime. Ключі також мають бути оголошені в `contracts.mediaUnderstandingProviders`. ```json @@ -502,35 +500,35 @@ Plugin провайдерів, що реалізують `resolveExternalAuthPro Кожен запис провайдера може містити: -| Поле | Тип | Що воно означає | -| ---------------------- | ----------------------------------- | ---------------------------------------------------------------------------- | -| `capabilities` | `("image" \| "audio" \| "video")[]` | Медіаможливості, які відкриває цей провайдер. | -| `defaultModels` | `Record` | Типові значення зіставлення можливості з моделлю, які використовуються, коли в конфігурації не вказано модель. | -| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного fallback провайдера на основі облікових даних. | -| `nativeDocumentInputs` | `"pdf"[]` | Нативні входи документів, які підтримує провайдер. | +| Поле | Тип | Що воно означає | +| ---------------------- | ----------------------------------- | ------------------------------------------------------------------------------ | +| `capabilities` | `("image" \| "audio" \| "video")[]` | Можливості медіа, які надає цей провайдер. | +| `defaultModels` | `Record` | Значення модель-за-замовчуванням для можливостей, що використовуються, коли конфігурація не вказує модель. | +| `autoPriority` | `Record` | Менші числа сортуються раніше для автоматичного резервного вибору провайдера на основі облікових даних. | +| `nativeDocumentInputs` | `"pdf"[]` | Вбудовані входи документів, які підтримує провайдер. | ## Довідник `channelConfigs` -Використовуйте `channelConfigs`, коли Plugin каналу потребує легких метаданих конфігурації до -завантаження runtime. Виявлення setup/status каналу лише для читання може використовувати ці метадані +Використовуйте `channelConfigs`, коли Plugin каналу потребує недорогих метаданих конфігурації до +завантаження runtime. Виявлення setup/статусу каналу в режимі лише читання може використовувати ці метадані безпосередньо для налаштованих зовнішніх каналів, коли запис setup недоступний або -коли `setup.requiresRuntime: false` означає, що runtime setup не потрібне. +коли `setup.requiresRuntime: false` оголошує, що runtime setup не потрібне. -`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ користувацької -конфігурації. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. +`channelConfigs` — це метадані маніфесту Plugin, а не новий верхньорівневий розділ +конфігурації користувача. Користувачі, як і раніше, налаштовують екземпляри каналів у `channels.`. OpenClaw зчитує метадані маніфесту, щоб визначити, який Plugin володіє цим налаштованим -каналом, до виконання runtime-коду Plugin. +каналом, до виконання коду runtime Plugin. Для Plugin каналу `configSchema` і `channelConfigs` описують різні шляхи: -- `configSchema` валідує `plugins.entries..config` -- `channelConfigs..schema` валідує `channels.` +- `configSchema` перевіряє `plugins.entries..config` +- `channelConfigs..schema` перевіряє `channels.` -Небудовані Plugin, які оголошують `channels[]`, також повинні оголошувати відповідні -записи `channelConfigs`. Без них OpenClaw все ще може завантажити Plugin, але -поверхні схем конфігурації cold-path, setup і Control UI не знатимуть форму параметрів, -якими володіє канал, доки не виконається runtime Plugin. +Невбудовані Plugin, які оголошують `channels[]`, також мають оголошувати відповідні +записи `channelConfigs`. Без них OpenClaw усе ще може завантажити Plugin, але поверхні схем конфігурації холодного шляху, +setup і Control UI не зможуть знати форму параметрів, якими володіє канал, +доки не виконається runtime Plugin. ```json { @@ -561,18 +559,18 @@ OpenClaw зчитує метадані маніфесту, щоб визначи | Поле | Тип | Що воно означає | | ------------- | ------------------------ | ------------------------------------------------------------------------------------------ | -| `schema` | `object` | JSON Schema для `channels.`. Обов’язкова для кожного оголошеного запису конфігурації каналу. | -| `uiHints` | `Record` | Необов’язкові мітки UI/placeholders/підказки чутливості для цього розділу конфігурації каналу. | -| `label` | `string` | Мітка каналу, що об’єднується в поверхні вибору та перевірки, коли runtime-метадані ще не готові. | +| `schema` | `object` | JSON Schema для `channels.`. Обов’язкове для кожного оголошеного запису конфігурації каналу. | +| `uiHints` | `Record` | Необов’язкові підписи UI/placeholder-и/підказки щодо чутливості для цього розділу конфігурації каналу. | +| `label` | `string` | Підпис каналу, який об’єднується в поверхнях вибору та перевірки, коли метадані runtime ще не готові. | | `description` | `string` | Короткий опис каналу для поверхонь перевірки та каталогу. | -| `preferOver` | `string[]` | Ідентифікатори застарілих або менш пріоритетних Plugin, які цей канал має випереджати в поверхнях вибору. | +| `preferOver` | `string[]` | id застарілих або нижчопріоритетних Plugin, які цей канал має випереджати на поверхнях вибору. | ### Заміна іншого Plugin каналу -Використовуйте `preferOver`, коли ваш Plugin є пріоритетним власником для ідентифікатора каналу, який -також може надавати інший Plugin. Типові випадки: перейменований ідентифікатор Plugin, -окремий Plugin, який замінює вбудований Plugin, або супроводжуваний fork, що -зберігає той самий ідентифікатор каналу для сумісності конфігурації. +Використовуйте `preferOver`, коли ваш Plugin є бажаним власником для id каналу, який +також може надавати інший Plugin. Поширені випадки — перейменований id Plugin, +окремий Plugin, який замінює вбудований Plugin, або підтримуваний форк, що +зберігає той самий id каналу для сумісності конфігурації. ```json { @@ -593,21 +591,21 @@ OpenClaw зчитує метадані маніфесту, щоб визначи } ``` -Коли налаштовано `channels.chat`, OpenClaw враховує і ідентифікатор каналу, і -ідентифікатор пріоритетного Plugin. Якщо менш пріоритетний Plugin було вибрано лише тому, що -він є вбудованим або ввімкненим типово, OpenClaw вимикає його в фактичній -runtime-конфігурації, щоб один Plugin володів каналом і його інструментами. Явний -вибір користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw -зберігає цей вибір і повідомляє про діагностику дубльованого каналу/інструмента замість -тихо змінювати запитаний набір Plugin. +Коли налаштовано `channels.chat`, OpenClaw враховує як id каналу, так і +id пріоритетного Plugin. Якщо Plugin з нижчим пріоритетом був вибраний лише тому, що +він вбудований або увімкнений за замовчуванням, OpenClaw вимикає його в ефективній +runtime-конфігурації, щоб один Plugin володів каналом і його інструментами. Явний вибір +користувача все одно має перевагу: якщо користувач явно вмикає обидва Plugin, OpenClaw +зберігає цей вибір і повідомляє про діагностику дубльованих каналів/інструментів замість +тихої зміни запитаного набору Plugin. -Застосовуйте `preferOver` лише до ідентифікаторів Plugin, які справді можуть надавати той самий канал. -Це не загальне поле пріоритету, і воно не перейменовує ключі користувацької конфігурації. +Тримайте `preferOver` у межах id Plugin, які справді можуть надавати той самий канал. +Це не загальне поле пріоритету і воно не перейменовує ключі конфігурації користувача. ## Довідник `modelSupport` Використовуйте `modelSupport`, коли OpenClaw має виводити ваш Plugin провайдера з -скорочених ідентифікаторів моделей на кшталт `gpt-5.5` або `claude-sonnet-4.6` до завантаження runtime Plugin. +скорочених id моделей, таких як `gpt-5.5` або `claude-sonnet-4.6`, до завантаження runtime Plugin. ```json { @@ -620,26 +618,26 @@ runtime-конфігурації, щоб один Plugin володів кана OpenClaw застосовує такий пріоритет: -- явні посилання `provider/model` використовують метадані маніфесту `providers` власника -- `modelPatterns` мають вищий пріоритет за `modelPrefixes` -- якщо збігаються один небудований Plugin і один вбудований Plugin, перемагає небудований +- явні посилання `provider/model` використовують метадані маніфесту `providers` плагіна-власника +- `modelPatterns` мають пріоритет над `modelPrefixes` +- якщо збігаються один невбудований Plugin і один вбудований Plugin, перемагає невбудований Plugin -- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкаже провайдера +- решта неоднозначностей ігнорується, доки користувач або конфігурація не вкажуть провайдера Поля: | Поле | Тип | Що воно означає | | --------------- | ---------- | ---------------------------------------------------------------------------- | -| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими ідентифікаторами моделей. | -| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими ідентифікаторами моделей після видалення суфікса profile. | +| `modelPrefixes` | `string[]` | Префікси, що зіставляються через `startsWith` зі скороченими id моделей. | +| `modelPatterns` | `string[]` | Джерела regex, що зіставляються зі скороченими id моделей після видалення суфікса профілю. | ## Довідник `modelCatalog` Використовуйте `modelCatalog`, коли OpenClaw має знати метадані моделей провайдера до -завантаження runtime Plugin. Це джерело, яким володіє маніфест, для фіксованих -рядків каталогу, псевдонімів провайдерів, правил придушення та режиму виявлення. -Оновлення під час виконання, як і раніше, належить runtime-коду провайдера, але -маніфест повідомляє ядру, коли потрібне runtime. +завантаження runtime Plugin. Це джерело, яким володіє маніфест, для фіксованих рядків каталогу, +псевдонімів провайдерів, правил приглушення та режиму виявлення. Оновлення runtime +усе ще належить коду runtime провайдера, але маніфест повідомляє ядру, коли runtime +є потрібним. ```json { @@ -690,54 +688,54 @@ OpenClaw застосовує такий пріоритет: Поля верхнього рівня: -| Поле | Тип | Що воно означає | -| -------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | -| `providers` | `Record` | Рядки каталогу для ідентифікаторів провайдерів, якими володіє цей Plugin. Ключі також мають з’являтися у верхньорівневому `providers`. | -| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися до провайдера-власника для планування каталогу або придушення. | -| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin придушує з причини, специфічної для провайдера. | -| `discovery` | `Record` | Чи можна читати каталог провайдера з метаданих маніфесту, оновлювати в кеш або для нього потрібне runtime. | +| Поле | Тип | Що воно означає | +| -------------- | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | +| `providers` | `Record` | Рядки каталогу для id провайдерів, якими володіє цей Plugin. Ключі також мають бути присутні у верхньорівневому `providers`. | +| `aliases` | `Record` | Псевдоніми провайдерів, які мають розв’язуватися у провайдера-власника для планування каталогу або приглушення. | +| `suppressions` | `object[]` | Рядки моделей з іншого джерела, які цей Plugin приглушує з причини, специфічної для провайдера. | +| `discovery` | `Record` | Чи можна каталог провайдера зчитати з метаданих маніфесту, оновити в кеш або чи він вимагає runtime. | Поля провайдера: | Поле | Тип | Що воно означає | | --------- | ------------------------ | ------------------------------------------------------------------ | -| `baseUrl` | `string` | Необов’язковий типовий base URL для моделей у каталозі цього провайдера. | -| `api` | `ModelApi` | Необов’язковий типовий адаптер API для моделей у каталозі цього провайдера. | +| `baseUrl` | `string` | Необов’язковий `baseUrl` за замовчуванням для моделей у каталозі цього провайдера. | +| `api` | `ModelApi` | Необов’язковий адаптер API за замовчуванням для моделей у каталозі цього провайдера. | | `headers` | `Record` | Необов’язкові статичні заголовки, що застосовуються до каталогу цього провайдера. | -| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | +| `models` | `object[]` | Обов’язкові рядки моделей. Рядки без `id` ігноруються. | Поля моделі: | Поле | Тип | Що воно означає | | --------------- | -------------------------------------------------------------- | ---------------------------------------------------------------------------- | -| `id` | `string` | Локальний для провайдера ідентифікатор моделі без префікса `provider/`. | +| `id` | `string` | Локальний для провайдера id моделі, без префікса `provider/`. | | `name` | `string` | Необов’язкова відображувана назва. | | `api` | `ModelApi` | Необов’язкове перевизначення API для окремої моделі. | -| `baseUrl` | `string` | Необов’язкове перевизначення base URL для окремої моделі. | +| `baseUrl` | `string` | Необов’язкове перевизначення `baseUrl` для окремої моделі. | | `headers` | `Record` | Необов’язкові статичні заголовки для окремої моделі. | -| `input` | `Array<"text" \| "image" \| "document">` | Модальності, які приймає модель. | -| `reasoning` | `boolean` | Чи відкриває модель поведінку reasoning. | -| `contextWindow` | `number` | Нативне вікно контексту провайдера. | -| `contextTokens` | `number` | Необов’язкове ефективне обмеження контексту під час виконання, якщо воно відрізняється від `contextWindow`. | +| `input` | `Array<"text" \| "image" \| "document" \| "audio" \| "video">` | Модальності, які приймає модель. | +| `reasoning` | `boolean` | Чи надає модель поведінку reasoning. | +| `contextWindow` | `number` | Власне вікно контексту провайдера. | +| `contextTokens` | `number` | Необов’язкове ефективне runtime-обмеження контексту, якщо воно відрізняється від `contextWindow`. | | `maxTokens` | `number` | Максимальна кількість вихідних токенів, якщо відома. | -| `cost` | `object` | Необов’язкова ціна в USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | +| `cost` | `object` | Необов’язкова вартість у USD за мільйон токенів, включно з необов’язковим `tieredPricing`. | | `compat` | `object` | Необов’язкові прапорці сумісності, що відповідають сумісності конфігурації моделі OpenClaw. | -| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Використовуйте придушення лише тоді, коли рядок взагалі не має з’являтися. | +| `status` | `"available"` \| `"preview"` \| `"deprecated"` \| `"disabled"` | Статус у списку. Приглушуйте лише тоді, коли рядок взагалі не має з’являтися. | | `statusReason` | `string` | Необов’язкова причина, що показується для статусу, відмінного від доступного. | -| `replaces` | `string[]` | Старі локальні для провайдера ідентифікатори моделей, які ця модель замінює. | -| `replacedBy` | `string` | Ідентифікатор локальної для провайдера моделі-заміни для застарілих рядків. | +| `replaces` | `string[]` | Старіші локальні для провайдера id моделей, які ця модель замінює. | +| `replacedBy` | `string` | Локальний для провайдера id моделі-замінника для застарілих рядків. | | `tags` | `string[]` | Стабільні теги, що використовуються засобами вибору та фільтрами. | -Не додавайте до `modelCatalog` дані лише для runtime. Якщо провайдеру потрібен стан -облікового запису, API-запит або виявлення локального процесу, щоб знати повний -набір моделей, оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. +Не розміщуйте в `modelCatalog` дані, які існують лише під час runtime. Якщо провайдеру потрібен +стан облікового запису, API-запит або виявлення локального процесу, щоб знати повний набір моделей, +оголосіть цього провайдера як `refreshable` або `runtime` у `discovery`. ### Індекс провайдерів OpenClaw Індекс провайдерів OpenClaw — це preview-метадані, якими володіє OpenClaw, для провайдерів, чиї Plugin можуть бути ще не встановлені. Він не є частиною маніфесту Plugin. -Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — це -внутрішній контракт fallback, який у майбутньому використовуватимуть поверхні встановлюваних провайдерів +Маніфести Plugin залишаються авторитетним джерелом для встановлених Plugin. Індекс провайдерів — +це внутрішній резервний контракт, який споживатимуть майбутні поверхні встановлюваних провайдерів і засоби вибору моделей до встановлення, коли Plugin провайдера не встановлений. Порядок авторитетності каталогу: @@ -747,100 +745,101 @@ OpenClaw застосовує такий пріоритет: 3. Кеш каталогу моделей після явного оновлення. 4. Preview-рядки індексу провайдерів OpenClaw. -Індекс провайдерів не повинен містити секретів, стану ввімкнення, runtime hooks або -живих даних моделей, специфічних для облікового запису. Його preview-каталоги використовують ту саму -форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають лишатися обмеженими -стабільними метаданими відображення, якщо тільки такі поля runtime-адаптера, як `api`, -`baseUrl`, ціни або прапорці сумісності, навмисно не узгоджені з -маніфестом встановленого Plugin. Провайдери з живим виявленням `/models` повинні -записувати оновлені рядки через явний шлях кешу каталогу моделей замість того, -щоб робити звичайні виклики API провайдера під час стандартного виведення списку або онбордингу. +Індекс провайдерів не повинен містити секрети, стан увімкнення, runtime-хуки або +живі дані моделей, специфічні для облікового запису. Його preview-каталоги використовують ту саму +форму рядка провайдера `modelCatalog`, що й маніфести Plugin, але мають залишатися обмеженими +стабільними метаданими відображення, якщо лише runtime-поля адаптера, такі як `api`, +`baseUrl`, ціни або прапорці сумісності, не підтримуються навмисно узгодженими з +маніфестом встановленого Plugin. Провайдери з live-виявленням через `/models` мають +записувати оновлені рядки через явний шлях кешу каталогу моделей, а не +звертатися до API провайдера під час звичайного відображення списку чи онбордингу. -Застарілі верхньорівневі ключі можливостей більше не рекомендуються. Використовуйте `openclaw doctor --fix`, щоб -перемістити `speechProviders`, `realtimeTranscriptionProviders`, +Застарілі верхньорівневі ключі можливостей більше не рекомендовані. Використовуйте `openclaw doctor --fix`, щоб +перенести `speechProviders`, `realtimeTranscriptionProviders`, `realtimeVoiceProviders`, `mediaUnderstandingProviders`, `imageGenerationProviders`, `videoGenerationProviders`, `webFetchProviders` і `webSearchProviders` під `contracts`; звичайне -завантаження маніфесту більше не трактує ці верхньорівневі поля як володіння -можливостями. +завантаження маніфесту більше не розглядає ці верхньорівневі поля як +володіння можливостями. -## Маніфест порівняно з package.json +## Маніфест проти package.json Ці два файли виконують різні завдання: -| Файл | Використовуйте для | +| Файл | Використовуйте його для | | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів auth і підказок UI, які мають існувати до запуску коду Plugin | -| `package.json` | Метаданих npm, встановлення залежностей і блока `openclaw`, що використовується для entrypoints, контролю встановлення, setup або метаданих каталогу | +| `openclaw.plugin.json` | Виявлення, валідації конфігурації, метаданих варіантів автентифікації та підказок UI, які мають існувати до запуску коду Plugin | +| `package.json` | Метаданих npm, встановлення залежностей і блоку `openclaw`, який використовується для точок входу, обмежень встановлення, setup або метаданих каталогу | Якщо ви не впевнені, куди належить певний фрагмент метаданих, використовуйте таке правило: -- якщо OpenClaw має знати це до завантаження коду Plugin, помістіть це в `openclaw.plugin.json` -- якщо це стосується пакування, файлів входу або поведінки встановлення npm, помістіть це в `package.json` +- якщо OpenClaw має знати це до завантаження коду Plugin, розмістіть це в `openclaw.plugin.json` +- якщо це стосується пакування, файлів точок входу або поведінки встановлення npm, розмістіть це в `package.json` -### Поля `package.json`, що впливають на виявлення +### Поля package.json, що впливають на виявлення -Деякі метадані Plugin до runtime навмисно зберігаються в `package.json` під -блоком `openclaw`, а не в `openclaw.plugin.json`. +Деякі метадані Plugin до runtime навмисно розміщуються в `package.json` у блоці +`openclaw`, а не в `openclaw.plugin.json`. Важливі приклади: -| Поле | Що воно означає | -| ----------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `openclaw.extensions` | Оголошує entrypoints нативного Plugin. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeExtensions` | Оголошує entrypoints built JavaScript runtime для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.setupEntry` | Полегшений entrypoint лише для setup, який використовується під час онбордингу, відкладеного запуску каналу та виявлення channel status/SecretRef лише для читання. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript entrypoint setup для встановлених пакетів. Має залишатися в межах каталогу пакета Plugin. | -| `openclaw.channel` | Полегшені метадані каталогу каналів, наприклад мітки, шляхи документації, псевдоніми та текст для вибору. | -| `openclaw.channel.configuredState` | Полегшені метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного runtime каналу. | -| `openclaw.channel.persistedAuthState` | Полегшені метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже є будь-що, що ввійшло в систему?» без завантаження повного 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` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація недійсна. | -| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналу лише для setup завантажуватися до повного Plugin каналу під час запуску. | +| Поле | Що воно означає | +| ----------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `openclaw.extensions` | Оголошує точки входу власного Plugin. Повинні залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeExtensions` | Оголошує точки входу built JavaScript runtime для встановлених пакетів. Повинні залишатися в межах каталогу пакета Plugin. | +| `openclaw.setupEntry` | Легковагова точка входу лише для setup, що використовується під час онбордингу, відкладеного запуску каналу та read-only виявлення стану каналу/SecretRef. Повинна залишатися в межах каталогу пакета Plugin. | +| `openclaw.runtimeSetupEntry` | Оголошує built JavaScript точку входу setup для встановлених пакетів. Повинна залишатися в межах каталогу пакета Plugin. | +| `openclaw.channel` | Легковагові метадані каталогу каналів, такі як підписи, шляхи до документації, псевдоніми та тексти для вибору. | +| `openclaw.channel.configuredState` | Легковагові метадані перевірки configured-state, які можуть відповісти на запитання «чи вже існує setup лише через env?» без завантаження повного runtime каналу. | +| `openclaw.channel.persistedAuthState` | Легковагові метадані перевірки persisted-auth, які можуть відповісти на запитання «чи вже десь виконано вхід?» без завантаження повного 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` | Дозволяє вузький шлях відновлення перевстановлення вбудованого Plugin, коли конфігурація невалідна. | +| `openclaw.startup.deferConfiguredChannelFullLoadUntilAfterListen` | Дозволяє поверхням каналів лише для setup завантажуватися до повного Plugin каналу під час запуску. | -Метадані маніфесту визначають, які варіанти provider/channel/setup з’являються в +Метадані маніфесту визначають, які варіанти провайдера/каналу/setup з’являються в онбордингу до завантаження runtime. `package.json#openclaw.install` повідомляє онбордингу, як отримати або ввімкнути цей Plugin, коли користувач вибирає один із цих варіантів. Не переносіть підказки встановлення до `openclaw.plugin.json`. -`openclaw.install.minHostVersion` перевіряється під час встановлення та -завантаження реєстру маніфестів. Недійсні значення відхиляються; новіші, але чинні значення пропускають -Plugin на старіших хостах. +`openclaw.install.minHostVersion` застосовується під час встановлення та +завантаження реєстру маніфестів. Невалідні значення відхиляються; новіші, але валідні +значення пропускають Plugin на старіших хостах. -Точне закріплення версії npm уже міститься в `npmSpec`, наприклад +Точне pin-ування версії npm уже міститься в `npmSpec`, наприклад `"npmSpec": "@wecom/wecom-openclaw-plugin@1.2.3"`. Офіційні записи зовнішнього каталогу -мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення безпечно -завершувалися з помилкою, якщо отриманий артефакт npm більше не відповідає закріпленому релізу. -Інтерактивний онбординг і далі пропонує надійні npm-специфікації реєстру, включно з голими -іменами пакетів і dist-tags, для сумісності. Діагностика каталогу може -розрізняти точні, плаваючі, закріплені за цілісністю, без цілісності, з невідповідністю імені пакета та недійсні джерела default-choice. Вона також попереджає, коли -`expectedIntegrity` присутній, але немає чинного джерела npm, яке він може закріпити. +мають поєднувати точні специфікації з `expectedIntegrity`, щоб потоки оновлення +завершувалися з помилкою, якщо завантажений npm-артефакт більше не відповідає +зафіксованому релізу. Інтерактивний онбординг для сумісності все ще пропонує +довірені npm-специфікації реєстру, включно з простими назвами пакетів і dist-tag. Діагностика каталогу може +відрізняти точні, плаваючі, pin-овані за цілісністю, без цілісності, з невідповідністю +назви пакета та невалідні джерела default-choice. Вона також попереджає, коли +`expectedIntegrity` присутній, але немає валідного джерела npm, яке він може зафіксувати. Коли `expectedIntegrity` присутній, -потоки встановлення/оновлення забезпечують його перевірку; коли його пропущено, розв’язання реєстру -фіксується без закріплення цілісності. +потоки встановлення/оновлення примусово його застосовують; коли його пропущено, результат +розв’язання реєстру записується без pin-ування цілісності. -Plugin каналів повинні надавати `openclaw.setupEntry`, коли status, список каналів -або сканування SecretRef мають визначати налаштовані облікові записи без завантаження повного -runtime. Запис setup має відкривати метадані каналу разом із безпечними для setup адаптерами -config, status і secrets; мережеві клієнти, слухачі gateway і transport runtime -слід залишати в основному entrypoint розширення. +Plugin каналів мають надавати `openclaw.setupEntry`, коли статус, список каналів +або сканування SecretRef мають виявляти налаштовані облікові записи без завантаження повного +runtime. Запис setup має надавати метадані каналу разом із безпечними для setup адаптерами +конфігурації, статусу та секретів; мережеві клієнти, слухачі gateway і транспортні runtime +тримайте в основній точці входу розширення. -Поля runtime entrypoint не перевизначають перевірки меж пакета для -полів source entrypoint. Наприклад, `openclaw.runtimeExtensions` не може зробити -завантажуваним шлях `openclaw.extensions`, що виходить за межі пакета. +Поля runtime-точок входу не перевизначають перевірки меж пакета для полів +точок входу джерела. Наприклад, `openclaw.runtimeExtensions` не може зробити +завантажуваним шлях `openclaw.extensions`, що виходить за межі. -`openclaw.install.allowInvalidConfigRecovery` навмисно вузький. Він -не робить довільно зламані конфігурації придатними для встановлення. Сьогодні він лише дозволяє потокам встановлення -відновлюватися після конкретних застарілих збоїв оновлення вбудованого Plugin, таких як -відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для цього ж -вбудованого Plugin. Несуміжні помилки конфігурації, як і раніше, блокують встановлення і відправляють операторів -до `openclaw doctor --fix`. +`openclaw.install.allowInvalidConfigRecovery` навмисно є вузьким. Воно не +робить довільно зламані конфігурації придатними до встановлення. Сьогодні воно лише дозволяє +потокам встановлення відновлюватися після певних застарілих збоїв оновлення вбудованого Plugin, +таких як відсутній шлях до вбудованого Plugin або застарілий запис `channels.` для цього ж +вбудованого Plugin. Непов’язані помилки конфігурації все ще блокують встановлення й відправляють +операторів до `openclaw doctor --fix`. -`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного -модуля перевірки: +`openclaw.channel.persistedAuthState` — це метадані пакета для крихітного модуля +перевірки: ```json { @@ -856,12 +855,12 @@ config, status і secrets; мережеві клієнти, слухачі gatew } ``` -Використовуйте це, коли потокам setup, doctor або configured-state потрібна дешева перевірка auth -типу так/ні до завантаження повного Plugin каналу. Цільовий export має бути невеликою -функцією, яка читає лише збережений стан; не спрямовуйте її через повний barrel runtime -каналу. +Використовуйте це, коли потоки setup, doctor або configured-state потребують недорогої +перевірки автентифікації «так/ні» до завантаження повного Plugin каналу. Цільовий експорт має бути невеликою +функцією, що лише зчитує збережений стан; не спрямовуйте її через повний +barrel runtime каналу. -`openclaw.channel.configuredState` має ту саму форму для дешевих перевірок +`openclaw.channel.configuredState` має ту саму форму для недорогих перевірок configured-state лише через env: ```json @@ -878,57 +877,57 @@ configured-state лише через env: } ``` -Використовуйте це, коли канал може визначати configured-state з env або інших малих -нерuntime-входів. Якщо перевірка потребує повного розв’язання конфігурації або справжнього -runtime каналу, залишайте цю логіку в hook `config.hasConfiguredState` Plugin. +Використовуйте це, коли канал може визначити configured-state через env або інші +невеликі нерuntime-дані. Якщо перевірка потребує повного розв’язання конфігурації або справжнього +runtime каналу, залиште цю логіку в хуку Plugin `config.hasConfiguredState`. -## Пріоритет виявлення (дубльовані ідентифікатори Plugin) +## Пріоритет виявлення (дубльовані id Plugin) -OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явні шляхи, вибрані конфігурацією). Якщо два виявлення мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються, а не завантажуються поруч із ним. +OpenClaw виявляє Plugin з кількох коренів (вбудовані, глобальне встановлення, workspace, явно вибрані в конфігурації шляхи). Якщо два виявлені Plugin мають однаковий `id`, зберігається лише маніфест із **найвищим пріоритетом**; дублікати з нижчим пріоритетом відкидаються замість завантаження поруч із ним. -Пріоритет від найвищого до найнижчого: +Пріоритет, від найвищого до найнижчого: -1. **Вибраний конфігурацією** — шлях, явно закріплений у `plugins.entries.` +1. **Вибраний у конфігурації** — шлях, явно зафіксований у `plugins.entries.` 2. **Вбудований** — Plugin, що постачаються з OpenClaw 3. **Глобальне встановлення** — Plugin, встановлені в глобальний корінь Plugin OpenClaw 4. **Workspace** — Plugin, виявлені відносно поточного workspace Наслідки: -- Fork або застаріла копія вбудованого Plugin, що лежить у workspace, не перекриє вбудовану збірку. -- Щоб справді перевизначити вбудований Plugin локальним, закріпіть його через `plugins.entries.`, щоб він переміг за пріоритетом, а не покладайтесь на виявлення у workspace. -- Відкидання дублікатів журналюється, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. +- Форк або застаріла копія вбудованого Plugin, що лежить у workspace, не затьмарить вбудовану збірку. +- Щоб справді перевизначити вбудований Plugin локальним, зафіксуйте його через `plugins.entries.`, щоб він виграв за пріоритетом, а не покладайтеся на виявлення в workspace. +- Відкидання дублікатів логуються, щоб Doctor і діагностика запуску могли вказати на відкинуту копію. ## Вимоги до JSON Schema -- **Кожен Plugin має постачати JSON Schema**, навіть якщо він не приймає конфігурації. -- Порожня схема прийнятна (наприклад, `{ "type": "object", "additionalProperties": false }`). +- **Кожен Plugin повинен постачатися з JSON Schema**, навіть якщо він не приймає конфігурацію. +- Порожня схема є прийнятною (наприклад, `{ "type": "object", "additionalProperties": false }`). - Схеми перевіряються під час читання/запису конфігурації, а не під час runtime. ## Поведінка валідації -- Невідомі ключі `channels.*` є **помилками**, якщо тільки ідентифікатор каналу не оголошено +- Невідомі ключі `channels.*` є **помилками**, якщо тільки id каналу не оголошено в маніфесті Plugin. - `plugins.entries.`, `plugins.allow`, `plugins.deny` і `plugins.slots.*` - мають посилатися на **виявлювані** ідентифікатори Plugin. Невідомі ідентифікатори — це **помилки**. -- Якщо Plugin встановлений, але має зламаний або відсутній маніфест чи схему, - валідація завершується помилкою, і Doctor повідомляє про помилку Plugin. -- Якщо конфігурація Plugin існує, але Plugin **вимкнено**, конфігурація зберігається, і - в Doctor + логах відображається **попередження**. + повинні посилатися на **виявлювані** id Plugin. Невідомі id є **помилками**. +- Якщо Plugin встановлено, але його маніфест або схема зламані чи відсутні, + валідація завершується помилкою, а Doctor повідомляє про помилку Plugin. +- Якщо конфігурація Plugin існує, але Plugin **вимкнений**, конфігурація зберігається і + в Doctor + логах показується **попередження**. -Повну схему `plugins.*` див. у [Configuration reference](/uk/gateway/configuration). +Див. [Довідник із конфігурації](/uk/gateway/configuration) для повної схеми `plugins.*`. ## Примітки -- Маніфест **обов’язковий для нативних 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 і політику ефективної активації, перш ніж вважати змінну середовища налаштованою. -- Для метаданих runtime wizard, які потребують коду провайдера, див. [Provider runtime hooks](/uk/plugins/architecture-internals#provider-runtime-hooks). -- Якщо ваш Plugin залежить від нативних модулів, задокументуйте кроки збирання та будь-які вимоги до 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`). +- Метадані env vars (`setup.providers[].envVars`, застарілий `providerAuthEnvVars` і `channelEnvVars`) є лише декларативними. Статус, аудит, валідація доставки Cron та інші read-only поверхні все одно застосовують довіру до Plugin і політику ефективної активації, перш ніж вважати env var налаштованою. +- Для метаданих runtime wizard, що потребують коду провайдера, див. [Runtime-хуки провайдера](/uk/plugins/architecture-internals#provider-runtime-hooks). +- Якщо ваш Plugin залежить від native-модулів, задокументуйте кроки збірки та будь-які вимоги до allowlist менеджера пакетів (наприклад, pnpm `allow-build-scripts` + `pnpm rebuild `). ## Пов’язане @@ -940,6 +939,6 @@ OpenClaw виявляє Plugin з кількох коренів (вбудова Внутрішня архітектура та модель можливостей. - Довідник з SDK Plugin і subpath imports. + Довідник SDK Plugin та імпорти підшляхів.