chore(i18n): refresh uk translations
This commit is contained in:
openclaw-docs-i18n[bot]
parent
236e5634f6
commit
68702d4efa
@ -1,18 +1,18 @@
|
||||
---
|
||||
read_when:
|
||||
- Зміна поведінки групового чату або керування згадками
|
||||
summary: Поведінка групового чату на різних поверхнях (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
summary: Поведінка групового чату на різних платформах (Discord/iMessage/Matrix/Microsoft Teams/Signal/Slack/Telegram/WhatsApp/Zalo)
|
||||
title: Групи
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T04:24:24Z"
|
||||
generated_at: "2026-04-26T05:36:24Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b9a2351e35560ddbf66ba6879da778936b54fd49b18a6d1146bbf700e07eb3e9
|
||||
source_hash: fa3448638de2f7babb432d0434dd4fb0f3d6ee53cad39627fef313b9023b138c
|
||||
source_path: channels/groups.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
OpenClaw узгоджено обробляє групові чати на різних поверхнях: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
|
||||
OpenClaw однаково обробляє групові чати на різних платформах: Discord, iMessage, Matrix, Microsoft Teams, Signal, Slack, Telegram, WhatsApp, Zalo.
|
||||
|
||||
## Вступ для початківців (2 хвилини)
|
||||
|
||||
@ -21,16 +21,16 @@ OpenClaw «живе» у ваших власних облікових запис
|
||||
|
||||
Поведінка за замовчуванням:
|
||||
|
||||
- Групи обмежені (`groupPolicy: "allowlist"`).
|
||||
- Для груп діють обмеження (`groupPolicy: "allowlist"`).
|
||||
- Відповіді потребують згадки, якщо ви явно не вимкнете керування згадками.
|
||||
|
||||
Простіше кажучи: відправники зі списку дозволених можуть активувати OpenClaw, згадавши його.
|
||||
Простими словами: відправники з allowlist можуть активувати OpenClaw, згадавши його.
|
||||
|
||||
> Коротко
|
||||
>
|
||||
> - **Доступ до прямих повідомлень** контролюється через `*.allowFrom`.
|
||||
> - **Доступ до груп** контролюється через `*.groupPolicy` + списки дозволених (`*.groups`, `*.groupAllowFrom`).
|
||||
> - **Запуск відповіді** контролюється через керування згадками (`requireMention`, `/activation`).
|
||||
> - **Доступ до DM** контролюється через `*.allowFrom`.
|
||||
> - **Доступ до груп** контролюється через `*.groupPolicy` + allowlist-и (`*.groups`, `*.groupAllowFrom`).
|
||||
> - **Запуск відповіді** контролюється керуванням згадками (`requireMention`, `/activation`).
|
||||
|
||||
Швидка схема (що відбувається з повідомленням у групі):
|
||||
|
||||
@ -41,62 +41,62 @@ requireMention? yes -> mentioned? no -> store for context only
|
||||
otherwise -> reply
|
||||
```
|
||||
|
||||
## Видимість контексту та списки дозволених
|
||||
## Видимість контексту та allowlist-и
|
||||
|
||||
У безпеці груп задіяно два різні механізми контролю:
|
||||
У безпеці груп беруть участь два різні механізми:
|
||||
|
||||
- **Авторизація запуску**: хто може активувати агента (`groupPolicy`, `groups`, `groupAllowFrom`, списки дозволених, специфічні для каналу).
|
||||
- **Видимість контексту**: який додатковий контекст передається в модель (текст відповіді, цитати, історія треду, метадані пересилання).
|
||||
- **Авторизація запуску**: хто може активувати агента (`groupPolicy`, `groups`, `groupAllowFrom`, allowlist-и, специфічні для каналу).
|
||||
- **Видимість контексту**: який додатковий контекст передається моделі (текст відповіді, цитати, історія треду, метадані пересилання).
|
||||
|
||||
За замовчуванням OpenClaw надає пріоритет звичайній поведінці чату й здебільшого зберігає контекст таким, яким його отримано. Це означає, що списки дозволених насамперед визначають, хто може запускати дії, а не є універсальною межею редагування для кожного процитованого чи історичного фрагмента.
|
||||
За замовчуванням OpenClaw надає пріоритет звичній поведінці чату й здебільшого зберігає контекст у тому вигляді, у якому його отримано. Це означає, що allowlist-и переважно визначають, хто може запускати дії, а не є універсальною межею редагування для кожного процитованого або історичного фрагмента.
|
||||
|
||||
Поточна поведінка залежить від каналу:
|
||||
|
||||
- Деякі канали вже застосовують фільтрацію додаткового контексту за відправником у певних шляхах (наприклад, ініціалізація тредів у Slack, пошук відповідей/тредів у Matrix).
|
||||
- Інші канали все ще передають контекст цитат/відповідей/пересилань таким, яким його отримано.
|
||||
- Деякі канали вже застосовують фільтрацію додаткового контексту за відправником у певних шляхах (наприклад, початкове наповнення тредів у Slack, пошук відповідей/тредів у Matrix).
|
||||
- Інші канали все ще передають контекст цитат/відповідей/пересилань у тому вигляді, у якому його отримано.
|
||||
|
||||
Напрям посилення захисту (заплановано):
|
||||
|
||||
- `contextVisibility: "all"` (за замовчуванням) зберігає поточну поведінку «як отримано».
|
||||
- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників зі списку дозволених.
|
||||
- `contextVisibility: "allowlist"` фільтрує додатковий контекст до відправників з allowlist.
|
||||
- `contextVisibility: "allowlist_quote"` — це `allowlist` плюс один явний виняток для цитати/відповіді.
|
||||
|
||||
Поки цю модель посилення захисту не буде узгоджено реалізовано в усіх каналах, очікуйте відмінностей залежно від поверхні.
|
||||
Поки цю модель посилення захисту не буде однаково реалізовано в усіх каналах, очікуйте відмінностей залежно від платформи.
|
||||
|
||||
|
||||
|
||||
Якщо ви хочете...
|
||||
|
||||
| Мета | Що налаштувати |
|
||||
| Ціль | Що налаштувати |
|
||||
| -------------------------------------------- | ---------------------------------------------------------- |
|
||||
| Дозволити всі групи, але відповідати лише на @згадки | `groups: { "*": { requireMention: true } }` |
|
||||
| Вимкнути всі відповіді в групах | `groupPolicy: "disabled"` |
|
||||
| Лише певні групи | `groups: { "<group-id>": { ... } }` (без ключа `"*"`) |
|
||||
| Лише ви можете активувати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
| Лише ви можете запускати в групах | `groupPolicy: "allowlist"`, `groupAllowFrom: ["+1555..."]` |
|
||||
|
||||
## Ключі сесій
|
||||
|
||||
- Групові сесії використовують ключі сесій `agent:<agentId>:<channel>:group:<id>` (кімнати/канали використовують `agent:<agentId>:<channel>:channel:<id>`).
|
||||
- Теми форуму Telegram додають `:topic:<threadId>` до ідентифікатора групи, тому кожна тема має власну сесію.
|
||||
- Прямі чати використовують основну сесію (або сесію для кожного відправника, якщо це налаштовано).
|
||||
- Прямі чати використовують основну сесію (або окрему для кожного відправника, якщо це налаштовано).
|
||||
- Heartbeat пропускаються для групових сесій.
|
||||
|
||||
<a id="pattern-personal-dms-public-groups-single-agent"></a>
|
||||
|
||||
## Шаблон: особисті прямі повідомлення + публічні групи (один агент)
|
||||
## Шаблон: особисті DM + публічні групи (один агент)
|
||||
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **прямі повідомлення**, а ваш «публічний» трафік — це **групи**.
|
||||
Так — це добре працює, якщо ваш «особистий» трафік — це **DM**, а «публічний» трафік — це **групи**.
|
||||
|
||||
Чому: у режимі одного агента прямі повідомлення зазвичай потрапляють в **основний** ключ сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете ізоляцію з `mode: "non-main"`, ці групові сесії виконуватимуться в налаштованому бекенді ізоляції, а ваша основна сесія прямих повідомлень залишатиметься на хості. Docker є бекендом за замовчуванням, якщо ви не виберете інший.
|
||||
Чому: у режимі одного агента DM зазвичай потрапляють до **основного** ключа сесії (`agent:main:main`), тоді як групи завжди використовують **неосновні** ключі сесій (`agent:main:<channel>:group:<id>`). Якщо ви ввімкнете ізоляцію з `mode: "non-main"`, ці групові сесії працюватимуть у налаштованому backend пісочниці, тоді як ваша основна DM-сесія залишиться на хості. Якщо ви не виберете інший backend, за замовчуванням використовується Docker.
|
||||
|
||||
Це дає вам один «мозок» агента (спільний робочий простір + пам’ять), але дві моделі виконання:
|
||||
|
||||
- **Прямі повідомлення**: повні інструменти (хост)
|
||||
- **Групи**: ізоляція + обмежені інструменти
|
||||
- **DM**: повний доступ до інструментів (хост)
|
||||
- **Групи**: пісочниця + обмежені інструменти
|
||||
|
||||
> Якщо вам потрібні справді окремі робочі простори/персони («особисте» й «публічне» ніколи не повинні змішуватися), використовуйте другого агента + bindings. Див. [Багатоагентна маршрутизація](/uk/concepts/multi-agent).
|
||||
> Якщо вам потрібні справді окремі робочі простори/персони («особисте» й «публічне» ніколи не мають змішуватися), використовуйте другого агента + bindings. Див. [Маршрутизація кількох агентів](/uk/concepts/multi-agent).
|
||||
|
||||
Приклад (прямі повідомлення на хості, групи в ізоляції + лише інструменти для обміну повідомленнями):
|
||||
Приклад (DM на хості, групи в пісочниці + лише інструменти для повідомлень):
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -121,7 +121,7 @@ otherwise -> reply
|
||||
}
|
||||
```
|
||||
|
||||
Хочете, щоб «групи могли бачити лише теку X» замість «жодного доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в ізоляцію лише шляхи зі списку дозволених:
|
||||
Хочете, щоб «групи могли бачити лише теку X» замість «жодного доступу до хоста»? Залиште `workspaceAccess: "none"` і змонтуйте в пісочницю лише шляхи з allowlist:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -146,17 +146,17 @@ otherwise -> reply
|
||||
Пов’язане:
|
||||
|
||||
- Ключі конфігурації та значення за замовчуванням: [Конфігурація Gateway](/uk/gateway/config-agents#agentsdefaultssandbox)
|
||||
- Налагодження, чому інструмент заблоковано: [Sandbox vs Tool Policy vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- Докладно про bind mounts: [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts)
|
||||
- Налагодження, чому інструмент заблоковано: [Пісочниця vs політика інструментів vs Elevated](/uk/gateway/sandbox-vs-tool-policy-vs-elevated)
|
||||
- Докладніше про bind mounts: [Ізоляція](/uk/gateway/sandboxing#custom-bind-mounts)
|
||||
|
||||
## Мітки відображення
|
||||
## Показувані мітки
|
||||
|
||||
- Мітки інтерфейсу використовують `displayName`, якщо він доступний, у форматі `<channel>:<token>`.
|
||||
- Мітки UI використовують `displayName`, якщо він доступний, у форматі `<channel>:<token>`.
|
||||
- `#room` зарезервовано для кімнат/каналів; групові чати використовують `g-<slug>` (нижній регістр, пробіли -> `-`, зберігати `#@+._-`).
|
||||
|
||||
## Політика груп
|
||||
|
||||
Керує тим, як обробляються повідомлення груп/кімнат для кожного каналу:
|
||||
Керуйте тим, як обробляються повідомлення в групах/кімнатах для кожного каналу:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -205,32 +205,32 @@ otherwise -> reply
|
||||
|
||||
| Політика | Поведінка |
|
||||
| ------------ | ------------------------------------------------------------ |
|
||||
| `"open"` | Групи оминають списки дозволених; керування згадками все ще застосовується. |
|
||||
| `"disabled"` | Повністю блокує всі повідомлення з груп. |
|
||||
| `"allowlist"` | Дозволяє лише групи/кімнати, що відповідають налаштованому списку дозволених. |
|
||||
| `"open"` | Групи оминають allowlist-и; керування згадками все ще діє. |
|
||||
| `"disabled"` | Повністю блокувати всі групові повідомлення. |
|
||||
| `"allowlist"` | Дозволяти лише групи/кімнати, що відповідають налаштованому allowlist. |
|
||||
|
||||
Примітки:
|
||||
|
||||
- `groupPolicy` окрема від керування згадками (яке вимагає @згадок).
|
||||
- `groupPolicy` окремий від керування згадками (яке вимагає @згадок).
|
||||
- WhatsApp/Telegram/Signal/iMessage/Microsoft Teams/Zalo: використовуйте `groupAllowFrom` (резервний варіант: явний `allowFrom`).
|
||||
- Підтвердження прив’язки для прямих повідомлень (записи сховища `*-allowFrom`) застосовуються лише до доступу до прямих повідомлень; авторизація відправників у групах залишається явно керованою через списки дозволених для груп.
|
||||
- Discord: список дозволених використовує `channels.discord.guilds.<id>.channels`.
|
||||
- Slack: список дозволених використовує `channels.slack.channels`.
|
||||
- Matrix: список дозволених використовує `channels.matrix.groups`. Надавайте перевагу ідентифікаторам кімнат або псевдонімам; пошук назв приєднаних кімнат виконується best-effort, а нерозв’язані назви ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom`, щоб обмежити відправників; також підтримуються списки дозволених `users` для окремих кімнат.
|
||||
- Групові прямі повідомлення керуються окремо (`channels.discord.dm.*`, `channels.slack.dm.*`).
|
||||
- Список дозволених Telegram може збігатися з ідентифікаторами користувачів (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменами користувачів (`"@alice"` або `"alice"`); префікси нечутливі до регістру.
|
||||
- Значення за замовчуванням — `groupPolicy: "allowlist"`; якщо ваш список дозволених для груп порожній, групові повідомлення блокуються.
|
||||
- Підтвердження прив’язки DM (записи сховища `*-allowFrom`) застосовуються лише до доступу в DM; авторизація відправника в групі залишається явно визначеною через групові allowlist-и.
|
||||
- Discord: allowlist використовує `channels.discord.guilds.<id>.channels`.
|
||||
- Slack: allowlist використовує `channels.slack.channels`.
|
||||
- Matrix: allowlist використовує `channels.matrix.groups`. Надавайте перевагу ідентифікаторам кімнат або псевдонімам; пошук назв приєднаних кімнат є best-effort, а нерозв’язані назви ігноруються під час виконання. Використовуйте `channels.matrix.groupAllowFrom` для обмеження відправників; також підтримуються allowlist-и `users` для окремих кімнат.
|
||||
- Групові DM контролюються окремо (`channels.discord.dm.*`, `channels.slack.dm.*`).
|
||||
- Allowlist Telegram може відповідати ID користувачів (`"123456789"`, `"telegram:123456789"`, `"tg:123456789"`) або іменам користувачів (`"@alice"` або `"alice"`); префікси нечутливі до регістру.
|
||||
- За замовчуванням використовується `groupPolicy: "allowlist"`; якщо ваш allowlist груп порожній, групові повідомлення блокуються.
|
||||
- Безпека під час виконання: коли блок провайдера повністю відсутній (`channels.<provider>` відсутній), політика груп переходить у fail-closed режим (зазвичай `allowlist`) замість успадкування `channels.defaults.groupPolicy`.
|
||||
|
||||
Швидка ментальна модель (порядок перевірки для повідомлень у групах):
|
||||
Швидка ментальна модель (порядок перевірки для групових повідомлень):
|
||||
|
||||
1. `groupPolicy` (open/disabled/allowlist)
|
||||
2. списки дозволених для груп (`*.groups`, `*.groupAllowFrom`, список дозволених, специфічний для каналу)
|
||||
2. групові allowlist-и (`*.groups`, `*.groupAllowFrom`, allowlist, специфічний для каналу)
|
||||
3. керування згадками (`requireMention`, `/activation`)
|
||||
|
||||
## Керування згадками (за замовчуванням)
|
||||
|
||||
Повідомлення в групах потребують згадки, якщо це не перевизначено для конкретної групи. Значення за замовчуванням зберігаються для кожної підсистеми в `*.groups."*"`.
|
||||
Групові повідомлення вимагають згадки, якщо це не перевизначено для конкретної групи. Значення за замовчуванням для кожної підсистеми зберігаються в `*.groups."*"`.
|
||||
|
||||
Відповідь на повідомлення бота вважається неявною згадкою, якщо канал
|
||||
підтримує метадані відповіді. Цитування повідомлення бота також може вважатися неявною
|
||||
@ -275,28 +275,28 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser.
|
||||
|
||||
Примітки:
|
||||
|
||||
- `mentionPatterns` — це безпечні regex-шаблони, нечутливі до регістру; недійсні шаблони та небезпечні форми вкладених повторень ігноруються.
|
||||
- Поверхні, що надають явні згадки, усе одно проходять; шаблони є резервним варіантом.
|
||||
- Перевизначення для агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів використовують одну групу).
|
||||
- Керування згадками застосовується лише тоді, коли виявлення згадок можливе (налаштовано нативні згадки або `mentionPatterns`).
|
||||
- У групах із постійно дозволеними тихими відповідями чиста порожня відповідь моделі розглядається як тиха, еквівалентна `NO_REPLY`. Групи з керуванням згадками та прямі чати все ще розглядають порожні відповіді як невдалий хід агента.
|
||||
- Значення за замовчуванням для Discord містяться в `channels.discord.guilds."*"` (можна перевизначити для кожного сервера/каналу).
|
||||
- Контекст історії груп рівномірно обгортається між каналами й є **лише pending** (повідомлення, пропущені через керування згадками); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
- `mentionPatterns` — це безпечні regex-шаблони, нечутливі до регістру; недійсні шаблони та небезпечні форми з вкладеним повторенням ігноруються.
|
||||
- Платформи, які надають явні згадки, усе одно проходять; шаблони є резервним варіантом.
|
||||
- Перевизначення для окремого агента: `agents.list[].groupChat.mentionPatterns` (корисно, коли кілька агентів ділять одну групу).
|
||||
- Керування згадками застосовується лише тоді, коли виявлення згадок можливе (є нативні згадки або налаштовано `mentionPatterns`).
|
||||
- Групи, де дозволені тихі відповіді, трактують чисті порожні або лише-міркувальні ходи моделі як тихі, еквівалентні `NO_REPLY`. Прямі чати все ще трактують порожні відповіді як невдалий хід агента.
|
||||
- Значення за замовчуванням для Discord зберігаються в `channels.discord.guilds."*"` (можна перевизначити для конкретної гільдії/каналу).
|
||||
- Контекст історії групи однаково обгортається для всіх каналів і є **лише pending** (повідомлення, пропущені через керування згадками); використовуйте `messages.groupChat.historyLimit` для глобального значення за замовчуванням і `channels.<channel>.historyLimit` (або `channels.<channel>.accounts.*.historyLimit`) для перевизначень. Встановіть `0`, щоб вимкнути.
|
||||
|
||||
## Обмеження інструментів для груп/каналів (необов’язково)
|
||||
|
||||
Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині конкретної групи/кімнати/каналу**.
|
||||
Деякі конфігурації каналів підтримують обмеження того, які інструменти доступні **всередині певної групи/кімнати/каналу**.
|
||||
|
||||
- `tools`: дозволити/заборонити інструменти для всієї групи.
|
||||
- `toolsBySender`: перевизначення для окремих відправників у межах групи.
|
||||
- `toolsBySender`: перевизначення для конкретного відправника всередині групи.
|
||||
Використовуйте явні префікси ключів:
|
||||
`id:<senderId>`, `e164:<phone>`, `username:<handle>`, `name:<displayName>` і шаблон `"*"`.
|
||||
Застарілі ключі без префікса все ще приймаються та зіставляються лише як `id:`.
|
||||
Старі ключі без префікса все ще приймаються й зіставляються лише як `id:`.
|
||||
|
||||
Порядок визначення (найбільш специфічний має пріоритет):
|
||||
Порядок визначення (найбільш специфічне має пріоритет):
|
||||
|
||||
1. збіг `toolsBySender` для групи/каналу
|
||||
2. `tools` групи/каналу
|
||||
2. `tools` для групи/каналу
|
||||
3. збіг `toolsBySender` за замовчуванням (`"*"` )
|
||||
4. `tools` за замовчуванням (`"*"`)
|
||||
|
||||
@ -322,17 +322,17 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної політики інструментів/політики інструментів агента (заборона все одно має пріоритет).
|
||||
- Обмеження інструментів для груп/каналів застосовуються додатково до глобальної/агентної політики інструментів (заборона все одно має пріоритет).
|
||||
- Деякі канали використовують іншу вкладеність для кімнат/каналів (наприклад, Discord `guilds.*.channels.*`, Slack `channels.*`, Microsoft Teams `teams.*.channels.*`).
|
||||
|
||||
## Списки дозволених для груп
|
||||
## Allowlist-и груп
|
||||
|
||||
Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як список дозволених для груп. Використовуйте `"*"` , щоб дозволити всі групи, водночас задавши типову поведінку для згадок.
|
||||
Коли налаштовано `channels.whatsapp.groups`, `channels.telegram.groups` або `channels.imessage.groups`, ключі діють як allowlist груп. Використовуйте `"*"` , щоб дозволити всі групи й водночас задати поведінку згадок за замовчуванням.
|
||||
|
||||
Поширена плутанина: підтвердження прив’язки прямих повідомлень — це не те саме, що авторизація груп.
|
||||
Для каналів, які підтримують прив’язку прямих повідомлень, сховище прив’язки розблоковує лише прямі повідомлення. Групові команди все одно потребують явної авторизації відправника для групи з конфігураційних списків дозволених, таких як `groupAllowFrom`, або документованого резервного варіанту конфігурації для цього каналу.
|
||||
Поширена плутанина: підтвердження прив’язки DM — це не те саме, що авторизація групи.
|
||||
Для каналів, які підтримують прив’язку DM, сховище прив’язки відкриває лише DM. Команди в групах усе одно вимагають явної авторизації відправника групи через allowlist-и конфігурації, такі як `groupAllowFrom`, або задокументований резервний механізм конфігурації для цього каналу.
|
||||
|
||||
Поширені наміри (копіювати/вставити):
|
||||
Поширені сценарії (копіюйте й вставляйте):
|
||||
|
||||
1. Вимкнути всі відповіді в групах
|
||||
|
||||
@ -390,37 +390,37 @@ Telegram, WhatsApp, Slack, Discord, Microsoft Teams і ZaloUser.
|
||||
- `/activation mention`
|
||||
- `/activation always`
|
||||
|
||||
Власник визначається через `channels.whatsapp.allowFrom` (або через власний E.164 бота, якщо не задано). Надсилайте команду як окреме повідомлення. Інші поверхні наразі ігнорують `/activation`.
|
||||
Власник визначається через `channels.whatsapp.allowFrom` (або через власний E.164 бота, якщо не задано). Надсилайте команду як окреме повідомлення. Інші платформи наразі ігнорують `/activation`.
|
||||
|
||||
## Поля контексту
|
||||
|
||||
Для вхідних даних груп установлюються:
|
||||
Для вхідних даних груп встановлюються:
|
||||
|
||||
- `ChatType=group`
|
||||
- `GroupSubject` (якщо відомо)
|
||||
- `GroupMembers` (якщо відомо)
|
||||
- `WasMentioned` (результат керування згадками)
|
||||
- Теми форуму Telegram також включають `MessageThreadId` і `IsForum`.
|
||||
- Теми форуму Telegram також містять `MessageThreadId` і `IsForum`.
|
||||
|
||||
Примітки для конкретних каналів:
|
||||
Примітки для окремих каналів:
|
||||
|
||||
- BlueBubbles може за бажанням доповнювати учасників без імен у групах macOS із локальної бази даних Contacts перед заповненням `GroupMembers`. Це вимкнено за замовчуванням і запускається лише після успішного проходження звичайної перевірки групи.
|
||||
- BlueBubbles може додатково збагачувати дані про неназваних учасників групи macOS із локальної бази контактів перед заповненням `GroupMembers`. Це вимкнено за замовчуванням і запускається лише після проходження звичайної перевірки групових обмежень.
|
||||
|
||||
Системний prompt агента включає вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати таблиць Markdown, мінімізувати порожні рядки, дотримуватися звичайних інтервалів у чаті та не вводити буквально послідовності `\n`. Назви груп і мітки учасників, отримані з каналу, відображаються як обмежені недовірені метадані, а не як вбудовані системні інструкції.
|
||||
Системний промпт агента містить вступ для групи на першому ході нової групової сесії. Він нагадує моделі відповідати як людині, уникати таблиць Markdown, мінімізувати порожні рядки, дотримуватися звичайних інтервалів у чаті та не друкувати буквальні послідовності `\n`. Назви груп і мітки учасників, отримані з каналу, відображаються як недовірені метадані в огородженому блоці, а не як вбудовані системні інструкції.
|
||||
|
||||
## Особливості iMessage
|
||||
|
||||
- Надавайте перевагу `chat_id:<id>` під час маршрутизації або додавання до списку дозволених.
|
||||
- Для маршрутизації або allowlist-ів надавайте перевагу `chat_id:<id>`.
|
||||
- Список чатів: `imsg chats --limit 20`.
|
||||
- Відповіді в групах завжди повертаються до того самого `chat_id`.
|
||||
|
||||
## Системні prompt-и WhatsApp
|
||||
## Системні промпти WhatsApp
|
||||
|
||||
Див. [WhatsApp](/uk/channels/whatsapp#system-prompts) для канонічних правил системних prompt-ів WhatsApp, включно з розв’язанням групових і прямих prompt-ів, поведінкою шаблона `"*"` і семантикою перевизначення облікового запису.
|
||||
Див. [WhatsApp](/uk/channels/whatsapp#system-prompts) для канонічних правил системних промптів WhatsApp, включно з визначенням промптів для груп і прямих чатів, поведінкою wildcard і семантикою перевизначення облікового запису.
|
||||
|
||||
## Особливості WhatsApp
|
||||
|
||||
Див. [Групові повідомлення](/uk/channels/group-messages) для поведінки лише WhatsApp (впровадження історії, подробиці обробки згадок).
|
||||
Див. [Групові повідомлення](/uk/channels/group-messages) для поведінки, специфічної лише для WhatsApp (впровадження історії, подробиці обробки згадок).
|
||||
|
||||
## Пов’язане
|
||||
|
||||
|
||||
@ -1,28 +1,28 @@
|
||||
---
|
||||
read_when:
|
||||
- Робота над функціями Telegram або Webhook
|
||||
summary: Статус підтримки бота Telegram, можливості та конфігурація
|
||||
- Робота над функціями Telegram або Webhook-ами
|
||||
summary: Статус підтримки, можливості та конфігурація бота Telegram
|
||||
title: Telegram
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T16:48:58Z"
|
||||
generated_at: "2026-04-26T05:36:20Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 9509ae437c6017c966d944b6d09af65b106f78ea023174127ac900b8cdc45ede
|
||||
source_hash: b7d269b15bc2d377fa45f0516e435517ed366c0216d0bc31fe4f4bc080a6c726
|
||||
source_path: channels/telegram.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Готовий до продакшену для DM бота та груп через grammY. Long polling — режим за замовчуванням; режим Webhook є опціональним.
|
||||
Готовий до продакшн-використання для DM бота та груп через grammY. Long polling — режим за замовчуванням; режим Webhook — необов’язковий.
|
||||
|
||||
<CardGroup cols={3}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Політика DM за замовчуванням для Telegram — сполучення.
|
||||
<Card title="Зв’язування" icon="link" href="/uk/channels/pairing">
|
||||
Типова політика DM для Telegram — зв’язування.
|
||||
</Card>
|
||||
<Card title="Усунення проблем каналу" icon="wrench" href="/uk/channels/troubleshooting">
|
||||
Міжканальна діагностика та сценарії відновлення.
|
||||
</Card>
|
||||
<Card title="Конфігурація Gateway" icon="settings" href="/uk/gateway/configuration">
|
||||
Повні шаблони та приклади конфігурації каналів.
|
||||
Повні шаблони й приклади конфігурації каналів.
|
||||
</Card>
|
||||
</CardGroup>
|
||||
|
||||
@ -30,9 +30,9 @@ x-i18n:
|
||||
|
||||
<Steps>
|
||||
<Step title="Створіть токен бота в BotFather">
|
||||
Відкрийте Telegram і почніть чат з **@BotFather** (переконайтеся, що хендл точно `@BotFather`).
|
||||
Відкрийте Telegram і почніть чат із **@BotFather** (переконайтеся, що хендл точно `@BotFather`).
|
||||
|
||||
Виконайте `/newbot`, дотримуйтеся підказок і збережіть токен.
|
||||
Виконайте `/newbot`, дотримуйтесь підказок і збережіть токен.
|
||||
|
||||
</Step>
|
||||
|
||||
@ -51,7 +51,7 @@ x-i18n:
|
||||
}
|
||||
```
|
||||
|
||||
Резервний варіант через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням).
|
||||
Резервне значення через env: `TELEGRAM_BOT_TOKEN=...` (лише для облікового запису за замовчуванням).
|
||||
Telegram **не** використовує `openclaw channels login telegram`; налаштуйте токен у config/env, а потім запустіть gateway.
|
||||
|
||||
</Step>
|
||||
@ -64,31 +64,31 @@ openclaw pairing list telegram
|
||||
openclaw pairing approve telegram <CODE>
|
||||
```
|
||||
|
||||
Коди сполучення дійсні протягом 1 години.
|
||||
Коди зв’язування дійсні протягом 1 години.
|
||||
|
||||
</Step>
|
||||
|
||||
<Step title="Додайте бота до групи">
|
||||
Додайте бота до своєї групи, а потім задайте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
Додайте бота до своєї групи, потім налаштуйте `channels.telegram.groups` і `groupPolicy` відповідно до вашої моделі доступу.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Note>
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним варіантом через env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
Порядок визначення токена враховує обліковий запис. На практиці значення з config мають пріоритет над резервним значенням з env, а `TELEGRAM_BOT_TOKEN` застосовується лише до облікового запису за замовчуванням.
|
||||
</Note>
|
||||
|
||||
## Налаштування на боці Telegram
|
||||
## Налаштування з боку Telegram
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Режим приватності та видимість у групах">
|
||||
Для ботів Telegram за замовчуванням увімкнено **Privacy Mode**, який обмежує, які повідомлення групи вони отримують.
|
||||
<Accordion title="Режим конфіденційності та видимість у групах">
|
||||
За замовчуванням боти Telegram працюють у **Privacy Mode**, що обмежує, які повідомлення в групах вони отримують.
|
||||
|
||||
Якщо бот має бачити всі повідомлення в групі, зробіть одне з такого:
|
||||
|
||||
- вимкніть режим приватності через `/setprivacy`, або
|
||||
- вимкніть режим конфіденційності через `/setprivacy`, або
|
||||
- зробіть бота адміністратором групи.
|
||||
|
||||
Після перемикання режиму приватності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміну.
|
||||
Після зміни режиму конфіденційності видаліть бота й додайте його знову в кожну групу, щоб Telegram застосував зміну.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -101,8 +101,8 @@ openclaw pairing approve telegram <CODE>
|
||||
|
||||
<Accordion title="Корисні перемикачі BotFather">
|
||||
|
||||
- `/setjoingroups` щоб дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` для керування видимістю в групах
|
||||
- `/setjoingroups` — дозволити/заборонити додавання до груп
|
||||
- `/setprivacy` — поведінка видимості в групах
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
@ -114,21 +114,21 @@ openclaw pairing approve telegram <CODE>
|
||||
`channels.telegram.dmPolicy` керує доступом до прямих повідомлень:
|
||||
|
||||
- `pairing` (за замовчуванням)
|
||||
- `allowlist` (потрібен принаймні один ID відправника в `allowFrom`)
|
||||
- `allowlist` (потрібен щонайменше один ID відправника в `allowFrom`)
|
||||
- `open` (потрібно, щоб `allowFrom` містив `"*"`)
|
||||
- `disabled`
|
||||
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` підтримуються та нормалізуються.
|
||||
`channels.telegram.allowFrom` приймає числові ID користувачів Telegram. Префікси `telegram:` / `tg:` приймаються та нормалізуються.
|
||||
`dmPolicy: "allowlist"` з порожнім `allowFrom` блокує всі DM і відхиляється валідацією config.
|
||||
Налаштування запитує лише числові ID користувачів.
|
||||
Якщо ви оновилися і ваш config містить записи allowlist у форматі `@username`, виконайте `openclaw doctor --fix`, щоб розв’язати їх (у режимі best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви раніше покладалися на файли allowlist зі сховища сполучення, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для потоків allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
Під час налаштування запитуються лише числові ID користувачів.
|
||||
Якщо ви оновилися й ваша config містить записи allowlist у вигляді `@username`, виконайте `openclaw doctor --fix`, щоб перетворити їх (best-effort; потрібен токен бота Telegram).
|
||||
Якщо ви раніше покладалися на файли allowlist у pairing-store, `openclaw doctor --fix` може відновити записи в `channels.telegram.allowFrom` для сценаріїв allowlist (наприклад, коли `dmPolicy: "allowlist"` ще не має явних ID).
|
||||
|
||||
Для ботів з одним власником віддавайте перевагу `dmPolicy: "allowlist"` з явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень сполучення).
|
||||
Для ботів із одним власником надавайте перевагу `dmPolicy: "allowlist"` із явними числовими ID в `allowFrom`, щоб політика доступу надійно зберігалася в config (замість залежності від попередніх схвалень зв’язування).
|
||||
|
||||
Поширена плутанина: схвалення сполучення для DM не означає, що «цей відправник авторизований всюди».
|
||||
Сполучення надає доступ лише до DM. Авторизація відправника в групах, як і раніше, походить лише з явних allowlist у config.
|
||||
Якщо ви хочете, щоб «я авторизувався один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram до `channels.telegram.allowFrom`.
|
||||
Поширена плутанина: схвалення зв’язування DM не означає, що «цей відправник авторизований усюди».
|
||||
Зв’язування надає доступ лише до DM. Авторизація відправника в групах усе ще визначається явними allowlist у config.
|
||||
Якщо ви хочете, щоб «я був авторизований один раз, і працювали і DM, і команди в групах», додайте свій числовий ID користувача Telegram у `channels.telegram.allowFrom`.
|
||||
|
||||
### Як знайти свій ID користувача Telegram
|
||||
|
||||
@ -138,13 +138,13 @@ openclaw pairing approve telegram <CODE>
|
||||
2. Виконайте `openclaw logs --follow`.
|
||||
3. Прочитайте `from.id`.
|
||||
|
||||
Офіційний спосіб через Bot API:
|
||||
Офіційний метод через Bot API:
|
||||
|
||||
```bash
|
||||
curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
```
|
||||
|
||||
Сторонній спосіб (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
Сторонній метод (менш приватний): `@userinfobot` або `@getidsbot`.
|
||||
|
||||
</Tab>
|
||||
|
||||
@ -154,7 +154,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
1. **Які групи дозволені** (`channels.telegram.groups`)
|
||||
- немає config `groups`:
|
||||
- з `groupPolicy: "open"`: будь-яка група може пройти перевірки ID групи
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи до `groups` (або `"*"`)
|
||||
- з `groupPolicy: "allowlist"` (за замовчуванням): групи блокуються, доки ви не додасте записи в `groups` (або `"*"`)
|
||||
- `groups` налаштовано: працює як allowlist (явні ID або `"*"`)
|
||||
|
||||
2. **Які відправники дозволені в групах** (`channels.telegram.groupPolicy`)
|
||||
@ -162,15 +162,15 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `allowlist` (за замовчуванням)
|
||||
- `disabled`
|
||||
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram повертається до `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (префікси `telegram:` / `tg:` нормалізуються).
|
||||
Не вказуйте ID чатів груп Telegram або супергруп у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
`groupAllowFrom` використовується для фільтрації відправників у групах. Якщо його не задано, Telegram використовує резервне значення з `allowFrom`.
|
||||
Записи `groupAllowFrom` мають бути числовими ID користувачів Telegram (`telegram:` / `tg:` префікси нормалізуються).
|
||||
Не додавайте ID чатів Telegram group або supergroup у `groupAllowFrom`. Від’ємні ID чатів мають бути в `channels.telegram.groups`.
|
||||
Нечислові записи ігноруються для авторизації відправника.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення зі сховища сполучення для DM.
|
||||
Сполучення залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні конкретної групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram повертається до `allowFrom` з config, а не до сховища сполучення.
|
||||
Практичний шаблон для ботів з одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, залиште `groupAllowFrom` незаданим і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка про runtime: якщо `channels.telegram` повністю відсутній, типові значення runtime працюють у fail-closed режимі з `groupPolicy="allowlist"`, якщо явно не задано `channels.defaults.groupPolicy`.
|
||||
Межа безпеки (`2026.2.25+`): авторизація відправника в групах **не** успадковує схвалення DM із pairing-store.
|
||||
Зв’язування залишається лише для DM. Для груп задайте `groupAllowFrom` або `allowFrom` на рівні групи/теми.
|
||||
Якщо `groupAllowFrom` не задано, Telegram використовує резервне значення з config `allowFrom`, а не pairing store.
|
||||
Практичний шаблон для ботів із одним власником: задайте свій ID користувача в `channels.telegram.allowFrom`, не задавайте `groupAllowFrom` і дозвольте цільові групи в `channels.telegram.groups`.
|
||||
Примітка щодо runtime: якщо `channels.telegram` повністю відсутній, runtime за замовчуванням працює в режимі fail-closed з `groupPolicy="allowlist"`, якщо тільки `channels.defaults.groupPolicy` не задано явно.
|
||||
|
||||
Приклад: дозволити будь-якого учасника в одній конкретній групі:
|
||||
|
||||
@ -209,14 +209,14 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
<Warning>
|
||||
Поширена помилка: `groupAllowFrom` — це не allowlist груп Telegram.
|
||||
|
||||
- Вказуйте від’ємні ID груп Telegram або супергруп, наприклад `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Вказуйте ID користувачів Telegram, наприклад `8734062810`, у `groupAllowFrom`, якщо хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише якщо хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
- Додавайте від’ємні ID Telegram group або supergroup, як-от `-1001234567890`, у `channels.telegram.groups`.
|
||||
- Додавайте ID користувачів Telegram, як-от `8734062810`, у `groupAllowFrom`, коли хочете обмежити, хто саме всередині дозволеної групи може звертатися до бота.
|
||||
- Використовуйте `groupAllowFrom: ["*"]` лише тоді, коли хочете, щоб будь-який учасник дозволеної групи міг спілкуватися з ботом.
|
||||
</Warning>
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab title="Поведінка згадування">
|
||||
<Tab title="Поведінка згадок">
|
||||
Відповіді в групах за замовчуванням вимагають згадки.
|
||||
|
||||
Згадка може надходити з:
|
||||
@ -233,7 +233,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Вони оновлюють лише стан сесії. Для збереження використовуйте config.
|
||||
|
||||
Приклад постійної конфігурації:
|
||||
Приклад сталої config:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -247,11 +247,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Як отримати ID групового чату:
|
||||
Отримання ID групового чату:
|
||||
|
||||
- перешліть повідомлення з групи до `@userinfobot` / `@getidsbot`
|
||||
- або прочитайте `chat.id` з `openclaw logs --follow`
|
||||
- або перегляньте Bot API `getUpdates`
|
||||
- або перевірте Bot API `getUpdates`
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
@ -259,20 +259,20 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
## Поведінка runtime
|
||||
|
||||
- Telegram належить процесу gateway.
|
||||
- Маршрутизація детермінована: вхідні відповіді Telegram повертаються назад у Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються в спільний конверт каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Групові сесії ізольовані за ID групи. Для тем форуму додається `:topic:<threadId>`, щоб теми залишалися ізольованими.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із thread-aware ключами сесії та зберігає ID треду для відповідей.
|
||||
- Long polling використовує grammY runner з послідовністю на рівні чату/треду. Загальна паралельність sink runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищено всередині кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски watchdog для long polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки життєздатності `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні все ще трапляються хибні перезапуски через зависання polling під час тривалої роботи. Значення задається в мілісекундах і допускається в межах від `30000` до `600000`; підтримуються перевизначення на рівні облікового запису.
|
||||
- Telegram Bot API не підтримує квитанції про прочитання (`sendReadReceipts` не застосовується).
|
||||
- Маршрутизація детермінована: вхідні відповіді з Telegram повертаються в Telegram (модель не вибирає канали).
|
||||
- Вхідні повідомлення нормалізуються до спільного конверта каналу з метаданими відповіді та заповнювачами медіа.
|
||||
- Сесії груп ізольовані за ID групи. Для forum topics додається `:topic:<threadId>`, щоб ізолювати теми.
|
||||
- Повідомлення DM можуть містити `message_thread_id`; OpenClaw маршрутизує їх із ключами сесії, що враховують thread, і зберігає ID thread для відповідей.
|
||||
- Long polling використовує grammY runner із послідовною обробкою для кожного чату/потоку. Загальна конкурентність sink у runner використовує `agents.defaults.maxConcurrent`.
|
||||
- Long polling захищений у межах кожного процесу gateway, тому лише один активний poller може використовувати токен бота одночасно. Якщо ви все ще бачите конфлікти `getUpdates` 409, імовірно, той самий токен використовує інший gateway OpenClaw, скрипт або зовнішній poller.
|
||||
- Перезапуски watchdog для long polling за замовчуванням спрацьовують після 120 секунд без завершеної перевірки живучості `getUpdates`. Збільшуйте `channels.telegram.pollingStallThresholdMs` лише якщо у вашому розгортанні й далі виникають хибні перезапуски через зависання polling під час довготривалої роботи. Значення задається в мілісекундах і може бути від `30000` до `600000`; підтримуються перевизначення для окремих облікових записів.
|
||||
- Telegram Bot API не підтримує підтвердження прочитання (`sendReadReceipts` не застосовується).
|
||||
|
||||
## Довідник функцій
|
||||
## Довідник можливостей
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Попередній перегляд потокової передачі в реальному часі (редагування повідомлень)">
|
||||
OpenClaw може передавати часткові відповіді в реальному часі:
|
||||
<Accordion title="Попередній перегляд live stream (редагування повідомлень)">
|
||||
OpenClaw може транслювати часткові відповіді в реальному часі:
|
||||
|
||||
- прямі чати: повідомлення попереднього перегляду + `editMessageText`
|
||||
- групи/теми: повідомлення попереднього перегляду + `editMessageText`
|
||||
@ -280,11 +280,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Вимога:
|
||||
|
||||
- `channels.telegram.streaming` має значення `off | partial | block | progress` (за замовчуванням: `partial`)
|
||||
- `progress` зіставляється з `partial` у Telegram (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення інструментів/прогресу повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активний потоковий попередній перегляд)
|
||||
- виявляються застарілі `channels.telegram.streamMode` і булеві значення `streaming`; виконайте `openclaw doctor --fix`, щоб мігрувати їх у `channels.telegram.streaming.mode`
|
||||
- `progress` у Telegram відповідає `partial` (сумісність із міжканальним найменуванням)
|
||||
- `streaming.preview.toolProgress` керує тим, чи оновлення tool/progress повторно використовують те саме відредаговане повідомлення попереднього перегляду (за замовчуванням: `true`, коли активне preview streaming)
|
||||
- застарілі `channels.telegram.streamMode` і булеві значення `streaming` виявляються; виконайте `openclaw doctor --fix`, щоб перенести їх у `channels.telegram.streaming.mode`
|
||||
|
||||
Оновлення попереднього перегляду прогресу інструментів — це короткі рядки «Працюю...», які показуються під час роботи інструментів, наприклад виконання команд, читання файлів, оновлення плану або підсумки патчів. Telegram тримає їх увімкненими за замовчуванням, щоб відповідати випущеній поведінці OpenClaw, починаючи з `v2026.4.22` і пізніше. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки прогресу інструментів, задайте:
|
||||
Оновлення попереднього перегляду tool-progress — це короткі рядки «Працюю...», які показуються під час виконання інструментів, наприклад під час виконання команд, читання файлів, оновлень планування або зведень патчів. У Telegram вони увімкнені за замовчуванням, щоб відповідати випущеній поведінці OpenClaw починаючи з `v2026.4.22`. Щоб зберегти відредагований попередній перегляд для тексту відповіді, але приховати рядки tool-progress, задайте:
|
||||
|
||||
```json
|
||||
{
|
||||
@ -301,18 +301,18 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки стану прогресу інструментів.
|
||||
Використовуйте `streaming.mode: "off"` лише якщо хочете повністю вимкнути редагування попереднього перегляду в Telegram. Використовуйте `streaming.preview.toolProgress: false`, якщо хочете вимкнути лише рядки статусу tool-progress.
|
||||
|
||||
Для відповідей лише з текстом:
|
||||
|
||||
- DM: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- група/тема: OpenClaw зберігає те саме повідомлення попереднього перегляду та виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- DM: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
- group/topic: OpenClaw зберігає те саме повідомлення попереднього перегляду й виконує фінальне редагування на місці (без другого повідомлення)
|
||||
|
||||
Для складних відповідей (наприклад, з медіаконтентом) OpenClaw повертається до звичайної фінальної доставки, а потім очищає повідомлення попереднього перегляду.
|
||||
Для складних відповідей (наприклад, з медіавмістом) OpenClaw використовує резервну звичайну фінальну доставку, а потім прибирає повідомлення попереднього перегляду.
|
||||
|
||||
Потоковий попередній перегляд відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає потік попереднього перегляду, щоб уникнути подвійної потокової передачі.
|
||||
Preview streaming відокремлений від block streaming. Коли для Telegram явно ввімкнено block streaming, OpenClaw пропускає preview stream, щоб уникнути подвійного стримінгу.
|
||||
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично повертається до `sendMessage` + `editMessageText`.
|
||||
Якщо нативний транспорт чернеток недоступний або відхилений, OpenClaw автоматично використовує резервний варіант `sendMessage` + `editMessageText`.
|
||||
|
||||
Потік reasoning лише для Telegram:
|
||||
|
||||
@ -321,32 +321,32 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Форматування та резервний варіант HTML">
|
||||
<Accordion title="Форматування та резервний HTML">
|
||||
Вихідний текст використовує Telegram `parse_mode: "HTML"`.
|
||||
|
||||
- Текст у стилі Markdown рендериться в безпечний для Telegram HTML.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок парсингу в Telegram.
|
||||
- Текст у стилі Markdown відтворюється як HTML, безпечний для Telegram.
|
||||
- Сирий HTML моделі екранується, щоб зменшити кількість помилок розбору в Telegram.
|
||||
- Якщо Telegram відхиляє розібраний HTML, OpenClaw повторює спробу як звичайний текст.
|
||||
|
||||
Попередній перегляд посилань увімкнено за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`.
|
||||
Попередній перегляд посилань увімкнений за замовчуванням і може бути вимкнений через `channels.telegram.linkPreview: false`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нативні команди та користувацькі команди">
|
||||
Реєстрація меню команд Telegram виконується під час запуску через `setMyCommands`.
|
||||
Реєстрація меню команд Telegram виконується під час запуску за допомогою `setMyCommands`.
|
||||
|
||||
Типові значення нативних команд:
|
||||
Типові налаштування нативних команд:
|
||||
|
||||
- `commands.native: "auto"` вмикає нативні команди для Telegram
|
||||
|
||||
Додайте користувацькі записи до меню команд:
|
||||
Додайте власні пункти меню команд:
|
||||
|
||||
```json5
|
||||
{
|
||||
channels: {
|
||||
telegram: {
|
||||
customCommands: [
|
||||
{ command: "backup", description: "Резервне копіювання Git" },
|
||||
{ command: "backup", description: "Резервна копія Git" },
|
||||
{ command: "generate", description: "Створити зображення" },
|
||||
],
|
||||
},
|
||||
@ -356,40 +356,40 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Правила:
|
||||
|
||||
- імена нормалізуються (видаляється початковий `/`, нижній регістр)
|
||||
- імена нормалізуються (видаляється початковий `/`, переводяться в нижній регістр)
|
||||
- допустимий шаблон: `a-z`, `0-9`, `_`, довжина `1..32`
|
||||
- користувацькі команди не можуть перевизначати нативні команди
|
||||
- конфлікти/дублікати пропускаються та логуються
|
||||
- конфлікти/дублікати пропускаються та записуються в журнал
|
||||
|
||||
Примітки:
|
||||
|
||||
- користувацькі команди — це лише записи меню; вони не реалізують поведінку автоматично
|
||||
- користувацькі команди — це лише пункти меню; вони не реалізують поведінку автоматично
|
||||
- команди Plugin/Skills все одно можуть працювати при ручному введенні, навіть якщо не показані в меню Telegram
|
||||
|
||||
Якщо нативні команди вимкнено, вбудовані буде видалено. Користувацькі команди/команди Plugin все ще можуть реєструватися, якщо це налаштовано.
|
||||
Якщо нативні команди вимкнені, вбудовані команди видаляються. Користувацькі команди/команди Plugin усе ще можуть реєструватися, якщо це налаштовано.
|
||||
|
||||
Поширені збої під час налаштування:
|
||||
Поширені збої налаштування:
|
||||
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram усе ще переповнене після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай означає, що вихідні DNS/HTTPS-запити до `api.telegram.org` заблоковані.
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що меню Telegram все ще переповнене навіть після скорочення; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть `channels.telegram.commands.native`.
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай означає, що вихідний DNS/HTTPS до `api.telegram.org` заблокований.
|
||||
|
||||
### Команди сполучення пристрою (Plugin `device-pair`)
|
||||
### Команди зв’язування пристрою (`device-pair` Plugin)
|
||||
|
||||
Коли встановлено Plugin `device-pair`:
|
||||
|
||||
1. `/pair` генерує код налаштування
|
||||
2. вставте код у застосунок iOS
|
||||
3. `/pair pending` показує список очікуваних запитів (зокрема роль/scopes)
|
||||
3. `/pair pending` показує список очікуваних запитів (включно з роллю/scopes)
|
||||
4. схваліть запит:
|
||||
- `/pair approve <requestId>` для явного схвалення
|
||||
- `/pair approve`, коли є лише один запит в очікуванні
|
||||
- `/pair approve`, коли є лише один очікуваний запит
|
||||
- `/pair approve latest` для найновішого
|
||||
|
||||
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен primary Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope використовують префікс ролі, тому цей allowlist оператора задовольняє лише запити оператора; ролі, що не є оператором, як і раніше потребують scopes під власним префіксом ролі.
|
||||
Код налаштування містить короткоживучий bootstrap-токен. Вбудована передача bootstrap зберігає токен первинного Node на `scopes: []`; будь-який переданий токен оператора залишається обмеженим до `operator.approvals`, `operator.read`, `operator.talk.secrets` і `operator.write`. Перевірки bootstrap scope мають префікс ролі, тож цей allowlist оператора задовольняє лише запити оператора; ролям, що не є оператором, усе ще потрібні scopes під префіксом їхньої власної ролі.
|
||||
|
||||
Якщо пристрій повторює спробу зі зміненими даними auth (наприклад роль/scopes/публічний ключ), попередній запит в очікуванні замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
|
||||
Якщо пристрій повторно надсилає запит зі зміненими даними автентифікації (наприклад, роль/scopes/публічний ключ), попередній очікуваний запит замінюється, а новий запит використовує інший `requestId`. Перед схваленням знову виконайте `/pair pending`.
|
||||
|
||||
Докладніше: [Сполучення](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
Докладніше: [Зв’язування](/uk/channels/pairing#pair-via-telegram-recommended-for-ios).
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -408,7 +408,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Перевизначення на рівні облікового запису:
|
||||
Перевизначення для окремого облікового запису:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -434,7 +434,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `all`
|
||||
- `allowlist` (за замовчуванням)
|
||||
|
||||
Застаріле `capabilities: ["inlineButtons"]` зіставляється з `inlineButtons: "all"`.
|
||||
Застаріле `capabilities: ["inlineButtons"]` відповідає `inlineButtons: "all"`.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
|
||||
@ -443,7 +443,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
action: "send",
|
||||
channel: "telegram",
|
||||
to: "123456789",
|
||||
message: "Виберіть варіант:",
|
||||
message: "Оберіть варіант:",
|
||||
buttons: [
|
||||
[
|
||||
{ text: "Так", callback_data: "yes" },
|
||||
@ -459,7 +459,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Дії повідомлень Telegram для агентів та автоматизації">
|
||||
<Accordion title="Дії з повідомленнями Telegram для агентів і автоматизації">
|
||||
Дії інструментів Telegram включають:
|
||||
|
||||
- `sendMessage` (`to`, `content`, необов’язкові `mediaUrl`, `replyToMessageId`, `messageThreadId`)
|
||||
@ -468,9 +468,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `editMessage` (`chatId`, `messageId`, `content`)
|
||||
- `createForumTopic` (`chatId`, `name`, необов’язкові `iconColor`, `iconCustomEmojiId`)
|
||||
|
||||
Дії повідомлень каналу надають ергономічні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
Дії повідомлень каналу надають зручні псевдоніми (`send`, `react`, `delete`, `edit`, `sticker`, `sticker-search`, `topic-create`).
|
||||
|
||||
Елементи керування доступом:
|
||||
Керування обмеженнями:
|
||||
|
||||
- `channels.telegram.actions.sendMessage`
|
||||
- `channels.telegram.actions.deleteMessage`
|
||||
@ -478,17 +478,17 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.actions.sticker` (за замовчуванням: вимкнено)
|
||||
|
||||
Примітка: `edit` і `topic-create` наразі увімкнені за замовчуванням і не мають окремих перемикачів `channels.telegram.actions.*`.
|
||||
Надсилання під час runtime використовують активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного розв’язання SecretRef для кожного надсилання.
|
||||
Надсилання під час runtime використовує активний знімок config/secrets (запуск/перезавантаження), тому шляхи дій не виконують спеціального повторного визначення SecretRef для кожного надсилання.
|
||||
|
||||
Семантика видалення реакцій: [/tools/reactions](/uk/tools/reactions)
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теги тредингу відповідей">
|
||||
Telegram підтримує явні теги тредингу відповідей у згенерованому виводі:
|
||||
<Accordion title="Теги ланцюжків відповідей">
|
||||
Telegram підтримує явні теги ланцюжків відповідей у згенерованому виводі:
|
||||
|
||||
- `[[reply_to_current]]` відповідає на повідомлення, яке ініціювало дію
|
||||
- `[[reply_to:<id>]]` відповідає на конкретний ID повідомлення Telegram
|
||||
- `[[reply_to_current]]` — відповідь на повідомлення, що спричинило спрацювання
|
||||
- `[[reply_to:<id>]]` — відповідь на конкретний ID повідомлення Telegram
|
||||
|
||||
`channels.telegram.replyToMode` керує обробкою:
|
||||
|
||||
@ -496,27 +496,29 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `first`
|
||||
- `all`
|
||||
|
||||
Примітка: `off` вимикає неявний трединг відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
Коли ланцюжки відповідей увімкнені й оригінальний текст або підпис Telegram доступний, OpenClaw автоматично включає нативний уривок цитати Telegram. Telegram обмежує текст нативної цитати до 1024 кодових одиниць UTF-16, тому довші повідомлення цитуються з початку й використовують резервний звичайний reply, якщо Telegram відхиляє цитату.
|
||||
|
||||
Примітка: `off` вимикає неявні ланцюжки відповідей. Явні теги `[[reply_to_*]]` усе одно враховуються.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Теми форуму та поведінка тредів">
|
||||
Супергрупи форуму:
|
||||
<Accordion title="Форумні теми та поведінка потоків">
|
||||
Forum supergroup:
|
||||
|
||||
- ключі сесій тем додають `:topic:<threadId>`
|
||||
- відповіді та індикатор набору тексту спрямовуються в тред теми
|
||||
- ключі сесії теми доповнюються `:topic:<threadId>`
|
||||
- відповіді й індикація набору тексту спрямовуються в потік теми
|
||||
- шлях config теми:
|
||||
`channels.telegram.groups.<chatId>.topics.<threadId>`
|
||||
|
||||
Спеціальний випадок загальної теми (`threadId=1`):
|
||||
|
||||
- надсилання повідомлень пропускає `message_thread_id` (Telegram відхиляє `sendMessage(...thread_id=1)`)
|
||||
- дії індикатора набору тексту все одно включають `message_thread_id`
|
||||
- дії індикації набору тексту все одно включають `message_thread_id`
|
||||
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` належить лише темі й не успадковується з типових значень групи.
|
||||
Успадкування тем: записи тем успадковують налаштування групи, якщо їх не перевизначено (`requireMention`, `allowFrom`, `skills`, `systemPrompt`, `enabled`, `groupPolicy`).
|
||||
`agentId` призначений лише для тем і не успадковується з типових налаштувань групи.
|
||||
|
||||
**Маршрутизація агентів для окремих тем**: кожна тема може маршрутизуватися до іншого агента через `agentId` у config теми. Це дає кожній темі власний ізольований workspace, пам’ять і сесію. Приклад:
|
||||
**Маршрутизація агентів для окремих тем**: Кожна тема може маршрутизуватися до іншого агента через встановлення `agentId` у config теми. Це надає кожній темі власний ізольований робочий простір, пам’ять і сесію. Приклад:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -525,9 +527,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
topics: {
|
||||
"1": { agentId: "main" }, // Загальна тема → агент main
|
||||
"1": { agentId: "main" }, // Загальна тема → основний агент
|
||||
"3": { agentId: "zu" }, // Тема розробки → агент zu
|
||||
"5": { agentId: "coder" } // Перевірка коду → агент coder
|
||||
"5": { agentId: "coder" } // Огляд коду → агент coder
|
||||
}
|
||||
}
|
||||
}
|
||||
@ -536,13 +538,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
}
|
||||
```
|
||||
|
||||
Кожна тема потім має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
Тоді кожна тема має власний ключ сесії: `agent:zu:telegram:group:-1001234567890:topic:3`
|
||||
|
||||
**Постійне прив’язування тем ACP**: теми форуму можуть закріплювати сесії harness ACP через типізовані ACP-прив’язки верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ID з кваліфікатором теми, наприклад `-1001234567890:topic:42`). Наразі це обмежено темами форуму в групах/супергрупах. Див. [ACP Agents](/uk/tools/acp-agents).
|
||||
**Стале прив’язування тем ACP**: Forum topics можуть закріплювати сесії harness ACP через типізовані прив’язки ACP верхнього рівня (`bindings[]` з `type: "acp"` і `match.channel: "telegram"`, `peer.kind: "group"` та ідентифікатором теми, як-от `-1001234567890:topic:42`). Наразі це обмежено forum topics у groups/supergroups. Див. [ACP Agents](/uk/tools/acp-agents).
|
||||
|
||||
**Прив’язане до треду створення ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди напряму. OpenClaw закріплює підтвердження створення в самій темі. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
**Прив’язаний до потоку запуск ACP із чату**: `/acp spawn <agent> --thread here|auto` прив’язує поточну тему до нової сесії ACP; подальші повідомлення маршрутизуються туди безпосередньо. OpenClaw закріплює підтвердження запуску в межах теми. Потрібно `channels.telegram.threadBindings.spawnAcpSessions=true`.
|
||||
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням треду.
|
||||
Контекст шаблону надає `MessageThreadId` і `IsForum`. DM-чати з `message_thread_id` зберігають маршрутизацію DM, але використовують ключі сесії з урахуванням thread.
|
||||
|
||||
</Accordion>
|
||||
|
||||
@ -554,7 +556,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- за замовчуванням: поведінка аудіофайлу
|
||||
- тег `[[audio_as_voice]]` у відповіді агента примусово надсилає як голосове повідомлення
|
||||
- вхідні транскрипти голосових повідомлень оформлюються в контексті агента як машинно згенерований,
|
||||
недовірений текст; виявлення згадок усе одно використовує сирий
|
||||
недовірений текст; виявлення згадок усе ще використовує сирий
|
||||
транскрипт, тож голосові повідомлення з обмеженням за згадкою продовжують працювати.
|
||||
|
||||
Приклад дії повідомлення:
|
||||
@ -591,7 +593,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
Обробка вхідних стікерів:
|
||||
|
||||
- статичний WEBP: завантажується та обробляється (заповнювач `<media:sticker>`)
|
||||
- статичний WEBP: завантажується й обробляється (заповнювач `<media:sticker>`)
|
||||
- анімований TGS: пропускається
|
||||
- відео WEBM: пропускається
|
||||
|
||||
@ -607,9 +609,9 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
- `~/.openclaw/telegram/sticker-cache.json`
|
||||
|
||||
Стікери описуються один раз (коли це можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
Стікери описуються один раз (коли можливо) і кешуються, щоб зменшити кількість повторних викликів vision.
|
||||
|
||||
Увімкніть дії зі стікерами:
|
||||
Увімкнення дій зі стікерами:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -640,7 +642,7 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
{
|
||||
action: "sticker-search",
|
||||
channel: "telegram",
|
||||
query: "cat waving",
|
||||
query: "кіт махає",
|
||||
limit: 5,
|
||||
}
|
||||
```
|
||||
@ -648,13 +650,13 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Сповіщення про реакції">
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисного навантаження повідомлень).
|
||||
Реакції Telegram надходять як оновлення `message_reaction` (окремо від корисних навантажень повідомлень).
|
||||
|
||||
Коли це ввімкнено, OpenClaw ставить у чергу системні події на кшталт:
|
||||
|
||||
- `Додано реакцію Telegram: 👍 від Alice (@alice) на повідомлення 42`
|
||||
|
||||
Конфігурація:
|
||||
Config:
|
||||
|
||||
- `channels.telegram.reactionNotifications`: `off | own | all` (за замовчуванням: `own`)
|
||||
- `channels.telegram.reactionLevel`: `off | ack | minimal | extensive` (за замовчуванням: `minimal`)
|
||||
@ -662,10 +664,10 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
Примітки:
|
||||
|
||||
- `own` означає лише реакції користувачів на повідомлення, надіслані ботом (best-effort через кеш надісланих повідомлень).
|
||||
- Події реакцій усе одно поважають механізми контролю доступу Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID тредів в оновленнях реакцій.
|
||||
- нефорумні групи маршрутизуються до сесії групового чату
|
||||
- групи форуму маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
- Події реакцій усе ще дотримуються керування доступом Telegram (`dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`); неавторизовані відправники відкидаються.
|
||||
- Telegram не надає ID потоку в оновленнях реакцій.
|
||||
- групи не forum маршрутизуються до сесії групового чату
|
||||
- forum groups маршрутизуються до сесії загальної теми групи (`:topic:1`), а не до точної початкової теми
|
||||
|
||||
`allowed_updates` для polling/webhook автоматично включають `message_reaction`.
|
||||
|
||||
@ -679,11 +681,11 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
- `channels.telegram.accounts.<accountId>.ackReaction`
|
||||
- `channels.telegram.ackReaction`
|
||||
- `messages.ackReaction`
|
||||
- резервний варіант через емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
- резервне значення з емодзі ідентичності агента (`agents.list[].identity.emoji`, інакше "👀")
|
||||
|
||||
Примітки:
|
||||
|
||||
- Telegram очікує Unicode-емодзі (наприклад, "👀").
|
||||
- Telegram очікує емодзі Unicode (наприклад, "👀").
|
||||
- Використовуйте `""`, щоб вимкнути реакцію для каналу або облікового запису.
|
||||
|
||||
</Accordion>
|
||||
@ -710,38 +712,38 @@ curl "https://api.telegram.org/bot<bot_token>/getUpdates"
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Long polling проти webhook">
|
||||
За замовчуванням використовується long polling. Для режиму webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково можна вказати `webhookPath`, `webhookHost`, `webhookPort` (типові значення: `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
<Accordion title="Long polling проти Webhook">
|
||||
За замовчуванням використовується long polling. Для режиму Webhook задайте `channels.telegram.webhookUrl` і `channels.telegram.webhookSecret`; необов’язково — `webhookPath`, `webhookHost`, `webhookPort` (за замовчуванням `/telegram-webhook`, `127.0.0.1`, `8787`).
|
||||
|
||||
Локальний слухач прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або свідомо задайте `webhookHost: "0.0.0.0"`.
|
||||
Локальний listener прив’язується до `127.0.0.1:8787`. Для публічного ingress або поставте reverse proxy перед локальним портом, або навмисно задайте `webhookHost: "0.0.0.0"`.
|
||||
|
||||
Режим Webhook перевіряє захисні умови запиту, секретний токен Telegram і JSON-тіло перед тим, як повернути `200` до Telegram.
|
||||
Потім OpenClaw обробляє оновлення асинхронно через ті самі бот-лінії на рівні чату/теми, що й long polling, тож повільні ходи агента не затримують ACK доставки від Telegram.
|
||||
Режим Webhook перевіряє захист запитів, секретний токен Telegram і тіло JSON перед поверненням `200` до Telegram.
|
||||
Потім OpenClaw асинхронно обробляє оновлення через ті самі бот-черги для кожного чату/теми, що використовуються в long polling, тож повільні цикли агента не затримують ACK доставки Telegram.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Ліміти, повторні спроби та цілі CLI">
|
||||
- значення за замовчуванням для `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` віддає перевагу межам абзаців (порожнім рядкам) перед розбиттям за довжиною.
|
||||
- Типове значення `channels.telegram.textChunkLimit` — 4000.
|
||||
- `channels.telegram.chunkMode="newline"` надає перевагу межам абзаців (порожнім рядкам) перед поділом за довжиною.
|
||||
- `channels.telegram.mediaMaxMb` (за замовчуванням 100) обмежує розмір вхідних і вихідних медіафайлів Telegram.
|
||||
- `channels.telegram.timeoutSeconds` перевизначає тайм-аут клієнта Telegram API (якщо не задано, застосовується типове значення grammY).
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в межах від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає її.
|
||||
- додатковий контекст reply/quote/forward наразі передається як отримано.
|
||||
- allowlist Telegram насамперед обмежують те, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- елементи керування історією DM:
|
||||
- `channels.telegram.pollingStallThresholdMs` за замовчуванням дорівнює `120000`; налаштовуйте в діапазоні від `30000` до `600000` лише для хибнопозитивних перезапусків через зависання polling.
|
||||
- Історія контексту групи використовує `channels.telegram.historyLimit` або `messages.groupChat.historyLimit` (за замовчуванням 50); `0` вимикає.
|
||||
- Додатковий контекст reply/quote/forward наразі передається в отриманому вигляді.
|
||||
- Telegram allowlist насамперед обмежують, хто може запускати агента, а не є повною межею редагування додаткового контексту.
|
||||
- Керування історією DM:
|
||||
- `channels.telegram.dmHistoryLimit`
|
||||
- `channels.telegram.dms["<user_id>"].historyLimit`
|
||||
- config `channels.telegram.retry` застосовується до допоміжних засобів надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API.
|
||||
- Config `channels.telegram.retry` застосовується до допоміжних функцій надсилання Telegram (CLI/tools/actions) для відновлюваних помилок вихідного API.
|
||||
|
||||
Ціль надсилання CLI може бути числовим ID чату або іменем користувача:
|
||||
Ціллю надсилання CLI може бути числовий ID чату або ім’я користувача:
|
||||
|
||||
```bash
|
||||
openclaw message send --channel telegram --target 123456789 --message "hi"
|
||||
openclaw message send --channel telegram --target @name --message "hi"
|
||||
```
|
||||
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують теми форуму:
|
||||
Опитування Telegram використовують `openclaw message poll` і підтримують forum topics:
|
||||
|
||||
```bash
|
||||
openclaw message poll --channel telegram --target 123456789 \
|
||||
@ -756,50 +758,50 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
- `--poll-duration-seconds` (5-600)
|
||||
- `--poll-anonymous`
|
||||
- `--poll-public`
|
||||
- `--thread-id` для тем форуму (або використовуйте ціль `:topic:`)
|
||||
- `--thread-id` для forum topics (або використовуйте ціль `:topic:`)
|
||||
|
||||
Надсилання Telegram також підтримує:
|
||||
|
||||
- `--presentation` з блоками `buttons` для вбудованих клавіатур, коли це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'`, щоб запросити закріплену доставку, коли бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи, а не як стиснуті фото чи завантаження анімованих медіа
|
||||
- `--presentation` з блоками `buttons` для вбудованих клавіатур, якщо це дозволяє `channels.telegram.capabilities.inlineButtons`
|
||||
- `--pin` або `--delivery '{"pin":true}'` для запиту закріпленої доставки, якщо бот може закріплювати в цьому чаті
|
||||
- `--force-document`, щоб надсилати вихідні зображення та GIF як документи замість стиснених фото або завантажень анімованих медіа
|
||||
|
||||
Керування доступом до дій:
|
||||
Керування обмеженнями дій:
|
||||
|
||||
- `channels.telegram.actions.sendMessage=false` вимикає вихідні повідомлення Telegram, включно з опитуваннями
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайні надсилання увімкненими
|
||||
- `channels.telegram.actions.poll=false` вимикає створення опитувань Telegram, залишаючи звичайне надсилання увімкненим
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Підтвердження exec у Telegram">
|
||||
Telegram підтримує підтвердження exec у DM затверджувачів і за потреби може публікувати запити у вихідному чаті або темі. Затверджувачі мають бути числовими ID користувачів Telegram.
|
||||
<Accordion title="Погодження exec у Telegram">
|
||||
Telegram підтримує погодження exec у DM погоджувачів і за потреби може публікувати запити в початковому чаті або темі. Погоджувачі мають бути числовими ID користувачів Telegram.
|
||||
|
||||
Шлях config:
|
||||
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного затверджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (повертається до числових ID власників із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.enabled` (автоматично вмикається, коли вдається визначити принаймні одного погоджувача)
|
||||
- `channels.telegram.execApprovals.approvers` (використовує резервне значення з числових owner ID із `allowFrom` / `defaultTo`)
|
||||
- `channels.telegram.execApprovals.target`: `dm` (за замовчуванням) | `channel` | `both`
|
||||
- `agentFilter`, `sessionFilter`
|
||||
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених групах/темах. Коли запит потрапляє в тему форуму, OpenClaw зберігає тему для запиту на підтвердження і подальшої взаємодії. За замовчуванням термін дії підтверджень exec спливає через 30 хвилин.
|
||||
Доставка в канал показує текст команди в чаті; вмикайте `channel` або `both` лише в довірених groups/topics. Коли запит потрапляє у forum topic, OpenClaw зберігає тему для запиту на погодження та подальших повідомлень. За замовчуванням погодження exec спливають через 30 хвилин.
|
||||
|
||||
Вбудовані кнопки підтвердження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID підтверджень із префіксом `plugin:` розв’язуються через підтвердження Plugin; інші спочатку розв’язуються через підтвердження exec.
|
||||
Вбудовані кнопки погодження також вимагають, щоб `channels.telegram.capabilities.inlineButtons` дозволяв цільову поверхню (`dm`, `group` або `all`). ID погоджень із префіксом `plugin:` визначаються через погодження Plugin; інші спочатку визначаються через погодження exec.
|
||||
|
||||
Див. [Підтвердження exec](/uk/tools/exec-approvals).
|
||||
Див. [Погодження exec](/uk/tools/exec-approvals).
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Елементи керування відповідями на помилки
|
||||
## Керування відповідями на помилки
|
||||
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цю поведінку керують два ключі config:
|
||||
Коли агент стикається з помилкою доставки або провайдера, Telegram може або відповісти текстом помилки, або придушити її. Цією поведінкою керують два ключі config:
|
||||
|
||||
| Key | Values | Default | Description |
|
||||
| ----------------------------------- | ----------------- | ------- | ----------------------------------------------------------------------------------------------- |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає дружнє повідомлення про помилку в чат. `silent` повністю придушує відповіді з помилками. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в той самий чат. Запобігає спаму помилками під час збоїв. |
|
||||
| `channels.telegram.errorPolicy` | `reply`, `silent` | `reply` | `reply` надсилає в чат дружнє повідомлення про помилку. `silent` повністю пригнічує відповіді з помилками. |
|
||||
| `channels.telegram.errorCooldownMs` | number (ms) | `60000` | Мінімальний час між відповідями з помилками в одному й тому самому чаті. Запобігає спаму помилками під час збоїв. |
|
||||
|
||||
Підтримуються перевизначення на рівні облікового запису, групи та теми (те саме успадкування, що й для інших ключів config Telegram).
|
||||
Підтримуються перевизначення для окремих облікових записів, груп і тем (те саме успадкування, що й для інших ключів config Telegram).
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -809,7 +811,7 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
errorCooldownMs: 120000,
|
||||
groups: {
|
||||
"-1001234567890": {
|
||||
errorPolicy: "silent", // придушити помилки в цій групі
|
||||
errorPolicy: "silent", // пригнічує помилки в цій групі
|
||||
},
|
||||
},
|
||||
},
|
||||
@ -822,40 +824,40 @@ openclaw message poll --channel telegram --target -1001234567890:topic:42 \
|
||||
<AccordionGroup>
|
||||
<Accordion title="Бот не відповідає на повідомлення групи без згадки">
|
||||
|
||||
- Якщо `requireMention=false`, режим приватності Telegram має дозволяти повну видимість.
|
||||
- Якщо `requireMention=false`, режим конфіденційності Telegram має дозволяти повну видимість.
|
||||
- BotFather: `/setprivacy` -> Disable
|
||||
- потім видаліть бота й додайте його знову до групи
|
||||
- `openclaw channels status` попереджає, коли config очікує повідомлення групи без згадки.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; шаблон `"*"` не можна перевірити через membership-probe.
|
||||
- `openclaw channels status --probe` може перевіряти явні числові ID груп; wildcard `"*"` неможливо перевірити на членство.
|
||||
- швидкий тест сесії: `/activation always`.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Бот узагалі не бачить повідомлень групи">
|
||||
<Accordion title="Бот узагалі не бачить повідомлення групи">
|
||||
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана в списку (або має міститися `"*"`)
|
||||
- коли існує `channels.telegram.groups`, група має бути вказана в списку (або має бути `"*"`)
|
||||
- перевірте членство бота в групі
|
||||
- перегляньте логи: `openclaw logs --follow` для причин пропуску
|
||||
- перегляньте журнали: `openclaw logs --follow` для причин пропуску
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Команди працюють частково або взагалі не працюють">
|
||||
<Accordion title="Команди працюють частково або не працюють взагалі">
|
||||
|
||||
- авторизуйте свою ідентичність відправника (сполучення та/або числовий `allowFrom`)
|
||||
- авторизація команд усе одно застосовується, навіть коли політика групи `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що нативне меню має забагато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками мережі/fetch зазвичай вказує на проблеми доступності DNS/HTTPS до `api.telegram.org`
|
||||
- авторизуйте свою ідентичність відправника (pairing та/або числовий `allowFrom`)
|
||||
- авторизація команд усе ще застосовується, навіть коли політика групи `open`
|
||||
- `setMyCommands failed` з `BOT_COMMANDS_TOO_MUCH` означає, що в нативному меню занадто багато записів; зменште кількість команд Plugin/Skills/користувацьких команд або вимкніть нативні меню
|
||||
- `setMyCommands failed` з помилками network/fetch зазвичай вказує на проблеми з досяжністю DNS/HTTPS до `api.telegram.org`
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Нестабільність polling або мережі">
|
||||
|
||||
- Node 22+ + custom fetch/proxy можуть спричиняти негайну поведінку abort, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку резолвлять `api.telegram.org` в IPv6; несправний вихід через IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо логи містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює такі спроби як відновлювані мережеві помилки.
|
||||
- Якщо логи містять `Polling stall detected`, OpenClaw перезапускає polling і перебудовує транспорт Telegram після 120 секунд без завершеної перевірки життєздатності long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише коли довготривалі виклики `getUpdates` є справними, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS маршрутизуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
- Node 22+ + custom fetch/proxy можуть спричиняти негайне переривання, якщо типи AbortSignal не збігаються.
|
||||
- Деякі хости спочатку визначають `api.telegram.org` в IPv6; несправний вихідний IPv6 може спричиняти періодичні збої Telegram API.
|
||||
- Якщо журнали містять `TypeError: fetch failed` або `Network request for 'getUpdates' failed!`, OpenClaw тепер повторює спроби для них як для відновлюваних мережевих помилок.
|
||||
- Якщо журнали містять `Polling stall detected`, OpenClaw перезапускає polling і заново будує транспорт Telegram після 120 секунд без завершеної перевірки живучості long-poll за замовчуванням.
|
||||
- Збільшуйте `channels.telegram.pollingStallThresholdMs` лише тоді, коли довготривалі виклики `getUpdates` працюють справно, але ваш хост усе ще повідомляє про хибні перезапуски через зависання polling. Стійкі зависання зазвичай вказують на проблеми з proxy, DNS, IPv6 або TLS egress між хостом і `api.telegram.org`.
|
||||
- На VPS-хостах із нестабільним прямим egress/TLS спрямовуйте виклики Telegram API через `channels.telegram.proxy`:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -863,8 +865,8 @@ channels:
|
||||
proxy: socks5://<user>:<password>@proxy-host:1080
|
||||
```
|
||||
|
||||
- Node 22+ за замовчуванням використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — це WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства:
|
||||
- За замовчуванням Node 22+ використовує `autoSelectFamily=true` (крім WSL2) і `dnsResultOrder=ipv4first`.
|
||||
- Якщо ваш хост — WSL2 або явно краще працює лише з IPv4, примусово задайте вибір сімейства:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -873,11 +875,11 @@ channels:
|
||||
autoSelectFamily: false
|
||||
```
|
||||
|
||||
- Відповіді з діапазону RFC 2544 benchmark (`198.18.0.0/15`) уже дозволені
|
||||
за замовчуванням для завантаження медіа Telegram. Якщо довірений fake-IP або
|
||||
- Відповіді з діапазону тестів RFC 2544 (`198.18.0.0/15`) уже дозволені
|
||||
для завантаження медіа Telegram за замовчуванням. Якщо довірений fake-IP або
|
||||
transparent proxy переписує `api.telegram.org` на якусь іншу
|
||||
приватну/внутрішню/special-use адресу під час завантаження медіа, ви можете
|
||||
свідомо ввімкнути обхід лише для Telegram:
|
||||
приватну/внутрішню/спеціального призначення адресу під час завантаження медіа, ви можете
|
||||
явно ввімкнути обхід лише для Telegram:
|
||||
|
||||
```yaml
|
||||
channels:
|
||||
@ -886,25 +888,24 @@ channels:
|
||||
dangerouslyAllowPrivateNetwork: true
|
||||
```
|
||||
|
||||
- Те саме явне ввімкнення доступне на рівні облікового запису в
|
||||
- Такий самий явний параметр доступний для окремого облікового запису в
|
||||
`channels.telegram.accounts.<accountId>.network.dangerouslyAllowPrivateNetwork`.
|
||||
- Якщо ваш proxy резолвить медіахости Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Медіа Telegram уже за замовчуванням дозволяє
|
||||
діапазон RFC 2544 benchmark.
|
||||
- Якщо ваш proxy визначає медіахости Telegram у `198.18.x.x`, спочатку залиште
|
||||
небезпечний прапорець вимкненим. Telegram media вже дозволяє діапазон тестів RFC 2544
|
||||
за замовчуванням.
|
||||
|
||||
<Warning>
|
||||
`channels.telegram.network.dangerouslyAllowPrivateNetwork` послаблює захист Telegram
|
||||
від SSRF для медіа. Використовуйте це лише для довірених середовищ proxy,
|
||||
якими керує оператор, наприклад Clash, Mihomo або Surge з маршрутизацією fake-IP, коли вони
|
||||
синтезують приватні або special-use відповіді поза межами
|
||||
діапазону RFC 2544 benchmark. Залишайте це вимкненим для звичайного публічного доступу до Telegram через інтернет.
|
||||
media від SSRF. Використовуйте це лише в довірених керованих оператором
|
||||
середовищах proxy, таких як Clash, Mihomo або Surge fake-IP routing, коли вони
|
||||
синтезують приватні або спеціальні відповіді поза діапазоном тестів RFC 2544. Для звичайного публічного доступу до Telegram через інтернет залишайте це вимкненим.
|
||||
</Warning>
|
||||
|
||||
- Перевизначення через середовище (тимчасові):
|
||||
- Перевизначення через змінні середовища (тимчасово):
|
||||
- `OPENCLAW_TELEGRAM_DISABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_ENABLE_AUTO_SELECT_FAMILY=1`
|
||||
- `OPENCLAW_TELEGRAM_DNS_RESULT_ORDER=ipv4first`
|
||||
- Перевірка відповідей DNS:
|
||||
- Перевірка DNS-відповідей:
|
||||
|
||||
```bash
|
||||
dig +short api.telegram.org A
|
||||
@ -914,23 +915,23 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
Додаткова допомога: [Усунення проблем каналу](/uk/channels/troubleshooting).
|
||||
Більше довідки: [Усунення проблем каналу](/uk/channels/troubleshooting).
|
||||
|
||||
## Довідник конфігурації
|
||||
## Довідник config
|
||||
|
||||
Основний довідник: [Довідник конфігурації - Telegram](/uk/gateway/config-channels#telegram).
|
||||
Основний довідник: [Configuration reference - Telegram](/uk/gateway/config-channels#telegram).
|
||||
|
||||
<Accordion title="Ключові поля Telegram із високою інформативністю">
|
||||
<Accordion title="Важливі поля Telegram">
|
||||
|
||||
- запуск/auth: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; symbolic links відхиляються)
|
||||
- запуск/автентифікація: `enabled`, `botToken`, `tokenFile`, `accounts.*` (`tokenFile` має вказувати на звичайний файл; символічні посилання відхиляються)
|
||||
- керування доступом: `dmPolicy`, `allowFrom`, `groupPolicy`, `groupAllowFrom`, `groups`, `groups.*.topics.*`, верхньорівневий `bindings[]` (`type: "acp"`)
|
||||
- підтвердження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- погодження exec: `execApprovals`, `accounts.*.execApprovals`
|
||||
- команда/меню: `commands.native`, `commands.nativeSkills`, `customCommands`
|
||||
- трединг/відповіді: `replyToMode`
|
||||
- потокова передача: `streaming` (попередній перегляд), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- потоки/відповіді: `replyToMode`
|
||||
- streaming: `streaming` (preview), `streaming.preview.toolProgress`, `blockStreaming`
|
||||
- форматування/доставка: `textChunkLimit`, `chunkMode`, `linkPreview`, `responsePrefix`
|
||||
- медіа/мережа: `mediaMaxMb`, `timeoutSeconds`, `pollingStallThresholdMs`, `retry`, `network.autoSelectFamily`, `network.dangerouslyAllowPrivateNetwork`, `proxy`
|
||||
- webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- Webhook: `webhookUrl`, `webhookSecret`, `webhookPath`, `webhookHost`
|
||||
- дії/можливості: `capabilities.inlineButtons`, `actions.sendMessage|editMessage|deleteMessage|reactions|sticker`
|
||||
- реакції: `reactionNotifications`, `reactionLevel`
|
||||
- помилки: `errorPolicy`, `errorCooldownMs`
|
||||
@ -939,14 +940,14 @@ dig +short api.telegram.org AAAA
|
||||
</Accordion>
|
||||
|
||||
<Note>
|
||||
Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити маршрутизацію за замовчуванням. Інакше OpenClaw повертається до першого нормалізованого ID облікового запису, і `openclaw doctor` видає попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
Пріоритет для кількох облікових записів: коли налаштовано два або більше ID облікових записів, задайте `channels.telegram.defaultAccount` (або включіть `channels.telegram.accounts.default`), щоб явно визначити типову маршрутизацію. Інакше OpenClaw використовує резервне значення — перший нормалізований ID облікового запису — і `openclaw doctor` виводить попередження. Іменовані облікові записи успадковують `channels.telegram.allowFrom` / `groupAllowFrom`, але не значення `accounts.default.*`.
|
||||
</Note>
|
||||
|
||||
## Пов’язане
|
||||
|
||||
<CardGroup cols={2}>
|
||||
<Card title="Сполучення" icon="link" href="/uk/channels/pairing">
|
||||
Сполучіть користувача Telegram із gateway.
|
||||
<Card title="Зв’язування" icon="link" href="/uk/channels/pairing">
|
||||
Зв’яжіть користувача Telegram із gateway.
|
||||
</Card>
|
||||
<Card title="Групи" icon="users" href="/uk/channels/groups">
|
||||
Поведінка allowlist для груп і тем.
|
||||
|
||||
@ -1,175 +1,147 @@
|
||||
---
|
||||
read_when:
|
||||
- Генерування зображень через агента
|
||||
- Генерування або редагування зображень через агента
|
||||
- Налаштування провайдерів і моделей для генерації зображень
|
||||
- Розуміння параметрів інструмента `image_generate`
|
||||
summary: Генеруйте та редагуйте зображення за допомогою налаштованих провайдерів (OpenAI, OpenAI Codex OAuth, Google Gemini, OpenRouter, LiteLLM, fal, MiniMax, ComfyUI, Vydra, xAI)
|
||||
- Розуміння параметрів інструмента image_generate
|
||||
sidebarTitle: Image generation
|
||||
summary: Генеруйте та редагуйте зображення через image_generate у OpenAI, Google, fal, MiniMax, ComfyUI, OpenRouter, LiteLLM, xAI, Vydra
|
||||
title: Генерація зображень
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T19:29:27Z"
|
||||
generated_at: "2026-04-26T05:36:22Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: fd7cdb5989dc3d09c87f940e423db669ac95c12a7502b23daa25fc73ba4ff85f
|
||||
source_hash: c57d32667eed3d6449628f6f663359ece089233ed0fde5258e2b2e4713192758
|
||||
source_path: tools/image-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Інструмент `image_generate` дає агенту змогу створювати й редагувати зображення за допомогою налаштованих провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
|
||||
Інструмент `image_generate` дає агенту змогу створювати та редагувати зображення за допомогою налаштованих вами провайдерів. Згенеровані зображення автоматично доставляються як медіавкладення у відповіді агента.
|
||||
|
||||
<Note>
|
||||
Інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, задайте API-ключ провайдера або увійдіть через OpenAI Codex OAuth.
|
||||
Інструмент з’являється, лише якщо доступний принаймні один провайдер генерації зображень. Якщо ви не бачите `image_generate` серед інструментів вашого агента, налаштуйте `agents.defaults.imageGenerationModel`, встановіть API-ключ провайдера або увійдіть через OpenAI Codex OAuth.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
1. Задайте API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY` або `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth.
|
||||
2. За потреби задайте бажану модель:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "openai/gpt-image-2",
|
||||
// Необов’язковий типовий тайм-аут запиту до провайдера для image_generate.
|
||||
timeoutMs: 180_000,
|
||||
<Steps>
|
||||
<Step title="Налаштуйте автентифікацію">
|
||||
Встановіть API-ключ принаймні для одного провайдера (наприклад, `OPENAI_API_KEY`, `GEMINI_API_KEY`, `OPENROUTER_API_KEY`) або увійдіть через OpenAI Codex OAuth.
|
||||
</Step>
|
||||
<Step title="Виберіть модель за замовчуванням (необов’язково)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "openai/gpt-image-2",
|
||||
timeoutMs: 180_000,
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
}
|
||||
```
|
||||
|
||||
Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw маршрутизує запити на
|
||||
зображення через той самий OAuth-профіль замість того, щоб спочатку
|
||||
використовувати `OPENAI_API_KEY`. Явне користувацьке налаштування зображень у
|
||||
`models.providers.openai`, наприклад API-ключ або користувацький/Azure base URL,
|
||||
повертає використання прямого маршруту OpenAI Images API. Для OpenAI-сумісних
|
||||
LAN-ендпойнтів, таких як LocalAI, збережіть користувацький
|
||||
`models.providers.openai.baseUrl` і явно ввімкніть
|
||||
`browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`; приватні/внутрішні
|
||||
ендпойнти зображень залишаються заблокованими за замовчуванням.
|
||||
Codex OAuth використовує те саме посилання на модель `openai/gpt-image-2`. Коли налаштовано OAuth-профіль `openai-codex`, OpenClaw спрямовує запити на зображення через цей OAuth-профіль замість того, щоб спочатку намагатися використати `OPENAI_API_KEY`. Явна конфігурація `models.providers.openai` (API-ключ, власний/Azure base URL) знову вмикає маршрут прямого OpenAI Images API.
|
||||
|
||||
3. Попросіть агента: _"Згенеруй зображення дружнього робота-маскота."_
|
||||
</Step>
|
||||
<Step title="Зверніться до агента">
|
||||
_"Згенеруй зображення дружнього робота-маскота."_
|
||||
|
||||
Агент автоматично викликає `image_generate`. Додавання до allow-list інструментів не потрібне — він увімкнений за замовчуванням, коли доступний провайдер.
|
||||
Агент автоматично викликає `image_generate`. Дозвільний список інструментів не потрібен — інструмент увімкнено за замовчуванням, коли провайдер доступний.
|
||||
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
<Warning>
|
||||
Для сумісних з OpenAI LAN-ендпоінтів, таких як LocalAI, зберігайте власний `models.providers.openai.baseUrl` і явно вмикайте `browser.ssrfPolicy.dangerouslyAllowPrivateNetwork: true`. Приватні та внутрішні ендпоінти зображень за замовчуванням залишаються заблокованими.
|
||||
</Warning>
|
||||
|
||||
## Поширені маршрути
|
||||
|
||||
| Ціль | Посилання на модель | Автентифікація |
|
||||
| ---------------------------------------------------- | ------------------------------------------------ | -------------------------------------- |
|
||||
| Генерація зображень OpenAI з оплатою через API | `openai/gpt-image-2` | `OPENAI_API_KEY` |
|
||||
| Генерація зображень OpenAI з автентифікацією через підписку Codex | `openai/gpt-image-2` | OpenAI Codex OAuth |
|
||||
| OpenAI PNG/WebP із прозорим тлом | `openai/gpt-image-1.5` | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| Генерація зображень через OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` |
|
||||
| Генерація зображень через LiteLLM | `litellm/gpt-image-2` | `LITELLM_API_KEY` |
|
||||
| Генерація зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| Ціль | Посилання на модель | Автентифікація |
|
||||
| ---------------------------------------------------- | ------------------------------------------------- | ------------------------------------- |
|
||||
| Генерація зображень OpenAI з API-оплатою | `openai/gpt-image-2` | `OPENAI_API_KEY` |
|
||||
| Генерація зображень OpenAI з автентифікацією через підписку Codex | `openai/gpt-image-2` | OpenAI Codex OAuth |
|
||||
| OpenAI PNG/WebP із прозорим фоном | `openai/gpt-image-1.5` | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| Генерація зображень через OpenRouter | `openrouter/google/gemini-3.1-flash-image-preview` | `OPENROUTER_API_KEY` |
|
||||
| Генерація зображень через LiteLLM | `litellm/gpt-image-2` | `LITELLM_API_KEY` |
|
||||
| Генерація зображень Google Gemini | `google/gemini-3.1-flash-image-preview` | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
|
||||
Той самий інструмент `image_generate` обробляє і генерацію з тексту, і
|
||||
редагування за еталонним зображенням. Використовуйте `image` для одного
|
||||
еталона або `images` для кількох еталонів. Підказки для виводу, які
|
||||
підтримуються провайдером, як-от `quality`, `outputFormat` і `background`,
|
||||
передаються далі, коли це можливо, і позначаються як проігноровані, якщо
|
||||
провайдер їх не підтримує. Поточна вбудована підтримка прозорого тла
|
||||
специфічна для OpenAI; інші провайдери все одно можуть зберігати PNG-альфу,
|
||||
якщо їхній бекенд її повертає.
|
||||
Той самий інструмент `image_generate` обробляє як генерацію з тексту, так і редагування за опорним зображенням. Використовуйте `image` для одного опорного зображення або `images` для кількох опорних зображень. Підтримувані провайдером підказки для виводу, такі як `quality`, `outputFormat` і `background`, передаються далі, коли це доступно, і позначаються як проігноровані, якщо провайдер їх не підтримує. Вбудована підтримка прозорого фону є специфічною для OpenAI; інші провайдери все одно можуть зберігати PNG alpha, якщо їхній бекенд її повертає.
|
||||
|
||||
## Підтримувані провайдери
|
||||
|
||||
| Провайдер | Типова модель | Підтримка редагування | Автентифікація |
|
||||
| --------- | -------------------------------------- | ---------------------------------- | ----------------------------------------------------- |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` |
|
||||
| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_API_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| MiniMax | `image-01` | Так (еталон суб’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, налаштоване workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
| Провайдер | Модель за замовчуванням | Підтримка редагування | Автентифікація |
|
||||
| ---------- | -------------------------------------- | ---------------------------------- | ---------------------------------------------------- |
|
||||
| ComfyUI | `workflow` | Так (1 зображення, налаштовується workflow) | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` для хмари |
|
||||
| fal | `fal-ai/flux/dev` | Так | `FAL_KEY` |
|
||||
| Google | `gemini-3.1-flash-image-preview` | Так | `GEMINI_API_KEY` або `GOOGLE_API_KEY` |
|
||||
| LiteLLM | `gpt-image-2` | Так (до 5 вхідних зображень) | `LITELLM_API_KEY` |
|
||||
| MiniMax | `image-01` | Так (опорне зображення об’єкта) | `MINIMAX_API_KEY` або MiniMax OAuth (`minimax-portal`) |
|
||||
| OpenAI | `gpt-image-2` | Так (до 4 зображень) | `OPENAI_API_KEY` або OpenAI Codex OAuth |
|
||||
| OpenRouter | `google/gemini-3.1-flash-image-preview` | Так (до 5 вхідних зображень) | `OPENROUTER_API_KEY` |
|
||||
| Vydra | `grok-imagine` | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-image` | Так (до 5 зображень) | `XAI_API_KEY` |
|
||||
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні провайдери й моделі під час виконання:
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні провайдери та моделі під час виконання:
|
||||
|
||||
```
|
||||
```text
|
||||
/tool image_generate action=list
|
||||
```
|
||||
|
||||
## Можливості провайдерів
|
||||
|
||||
| Можливість | ComfyUI | fal | Google | MiniMax | OpenAI | Vydra | xAI |
|
||||
| -------------------- | -------------------- | ----------------- | -------------- | ----------------------- | -------------- | ----- | -------------- |
|
||||
| Генерація (макс. кількість) | Визначається workflow | 4 | 4 | 9 | 4 | 1 | 4 |
|
||||
| Редагування / опорне зображення | 1 зображення (workflow) | 1 зображення | До 5 зображень | 1 зображення (опорне зображення об’єкта) | До 5 зображень | — | До 5 зображень |
|
||||
| Керування розміром | — | ✓ | ✓ | — | До 4K | — | — |
|
||||
| Співвідношення сторін | — | ✓ (лише генерація) | ✓ | ✓ | — | — | ✓ |
|
||||
| Роздільна здатність (1K/2K/4K) | — | ✓ | ✓ | — | — | — | 1K, 2K |
|
||||
|
||||
## Параметри інструмента
|
||||
|
||||
<ParamField path="prompt" type="string" required>
|
||||
Підказка для генерації зображення. Обов’язкова для `action: "generate"`.
|
||||
Запит для генерації зображення. Обов’язковий для `action: "generate"`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="action" type="'generate' | 'list'" default="generate">
|
||||
Використовуйте `"list"`, щоб переглянути доступні провайдери й моделі під час виконання.
|
||||
<ParamField path="action" type='"generate" | "list"' default="generate">
|
||||
Використовуйте `"list"`, щоб переглянути доступні провайдери та моделі під час виконання.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="model" type="string">
|
||||
Перевизначення провайдера/моделі, наприклад `openai/gpt-image-2`; використовуйте
|
||||
`openai/gpt-image-1.5` для прозорого тла OpenAI.
|
||||
Перевизначення провайдера/моделі (наприклад, `openai/gpt-image-2`). Використовуйте `openai/gpt-image-1.5` для прозорих фонів в OpenAI.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="image" type="string">
|
||||
Шлях або URL одного еталонного зображення для режиму редагування.
|
||||
Шлях або URL одного опорного зображення для режиму редагування.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="images" type="string[]">
|
||||
Кілька еталонних зображень для режиму редагування (до 5).
|
||||
Кілька опорних зображень для режиму редагування (до 5 у провайдерів, які це підтримують).
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="size" type="string">
|
||||
Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
|
||||
Підказка щодо розміру: `1024x1024`, `1536x1024`, `1024x1536`, `2048x2048`, `3840x2160`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="aspectRatio" type="string">
|
||||
Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
|
||||
Співвідношення сторін: `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9`.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="resolution" type="'1K' | '2K' | '4K'">
|
||||
Підказка щодо роздільної здатності.
|
||||
<ParamField path="resolution" type='"1K" | "2K" | "4K"'>Підказка щодо роздільної здатності.</ParamField>
|
||||
<ParamField path="quality" type='"low" | "medium" | "high" | "auto"'>
|
||||
Підказка щодо якості, якщо провайдер її підтримує.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="quality" type="'low' | 'medium' | 'high' | 'auto'">
|
||||
Підказка щодо якості, якщо провайдер її підтримує.
|
||||
<ParamField path="outputFormat" type='"png" | "jpeg" | "webp"'>
|
||||
Підказка щодо формату виводу, якщо провайдер її підтримує.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="outputFormat" type="'png' | 'jpeg' | 'webp'">
|
||||
Підказка щодо формату виводу, якщо провайдер її підтримує.
|
||||
<ParamField path="background" type='"transparent" | "opaque" | "auto"'>
|
||||
Підказка щодо фону, якщо провайдер її підтримує. Використовуйте `transparent` з `outputFormat: "png"` або `"webp"` для провайдерів, що підтримують прозорість.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="background" type="'transparent' | 'opaque' | 'auto'">
|
||||
Підказка щодо тла, якщо провайдер її підтримує. Використовуйте `transparent` з
|
||||
`outputFormat: "png"` або `"webp"` для провайдерів, що підтримують прозорість.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="count" type="number">
|
||||
Кількість зображень для генерації (1–4).
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="timeoutMs" type="number">
|
||||
Необов’язковий тайм-аут запиту до провайдера в мілісекундах.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="filename" type="string">
|
||||
Підказка щодо імені вихідного файла.
|
||||
</ParamField>
|
||||
|
||||
<ParamField path="count" type="number">Кількість зображень для генерації (1–4).</ParamField>
|
||||
<ParamField path="timeoutMs" type="number">Необов’язковий таймаут запиту до провайдера в мілісекундах.</ParamField>
|
||||
<ParamField path="filename" type="string">Підказка щодо імені вихідного файла.</ParamField>
|
||||
<ParamField path="openai" type="object">
|
||||
Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`.
|
||||
Підказки лише для OpenAI: `background`, `moderation`, `outputCompression` і `user`.
|
||||
</ParamField>
|
||||
|
||||
Не всі провайдери підтримують усі параметри. Коли резервний провайдер
|
||||
підтримує близький варіант геометрії замість точно запитаного, OpenClaw
|
||||
перед надсиланням переналаштовує запит до найближчого підтримуваного розміру,
|
||||
співвідношення сторін або роздільної здатності. Непідтримувані підказки
|
||||
виводу, як-от `quality` або `outputFormat`, відкидаються для провайдерів, які
|
||||
не оголошують таку підтримку, і повідомляються в результаті інструмента.
|
||||
|
||||
Результати інструмента повідомляють про застосовані налаштування. Коли
|
||||
OpenClaw переналаштовує геометрію під час резервного переходу між провайдерами,
|
||||
повернуті значення `size`, `aspectRatio` і `resolution` відображають те, що
|
||||
було фактично надіслано, а `details.normalization` фіксує перетворення від
|
||||
запитаних значень до застосованих.
|
||||
<Note>
|
||||
Не всі провайдери підтримують усі параметри. Коли резервний провайдер підтримує близький варіант геометрії замість точно запитаного, OpenClaw перед відправленням зіставляє запитаний розмір, співвідношення сторін або роздільну здатність із найближчим підтримуваним варіантом. Непідтримувані підказки виводу відкидаються для провайдерів, які не оголошують їх підтримку, і відображаються в результаті інструмента. Результати інструмента повідомляють про застосовані параметри; `details.normalization` фіксує будь-яке перетворення із запитаного значення в застосоване.
|
||||
</Note>
|
||||
|
||||
## Конфігурація
|
||||
|
||||
@ -195,131 +167,157 @@ OpenClaw переналаштовує геометрію під час резе
|
||||
|
||||
### Порядок вибору провайдера
|
||||
|
||||
Під час генерації зображення OpenClaw пробує провайдерів у такому порядку:
|
||||
OpenClaw пробує провайдерів у такому порядку:
|
||||
|
||||
1. **Параметр `model`** з виклику інструмента (якщо агент його вказує)
|
||||
2. **`imageGenerationModel.primary`** з конфігурації
|
||||
3. **`imageGenerationModel.fallbacks`** у вказаному порядку
|
||||
4. **Автовиявлення** — використовуються лише типові значення провайдерів, підкріплені автентифікацією:
|
||||
- спочатку поточний типовий провайдер
|
||||
- далі решта зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів
|
||||
1. **Параметр `model`** із виклику інструмента (якщо агент його вказує).
|
||||
2. **`imageGenerationModel.primary`** із конфігурації.
|
||||
3. **`imageGenerationModel.fallbacks`** по порядку.
|
||||
4. **Автовиявлення** — лише типові значення провайдерів, підкріплені автентифікацією:
|
||||
- спочатку поточний провайдер за замовчуванням;
|
||||
- далі решта зареєстрованих провайдерів генерації зображень у порядку ідентифікаторів провайдерів.
|
||||
|
||||
Якщо провайдер завершується помилкою (помилка автентифікації, ліміт запитів тощо), автоматично пробується наступний налаштований кандидат. Якщо всі завершуються помилкою, помилка містить подробиці кожної спроби.
|
||||
Якщо провайдер завершується помилкою (помилка автентифікації, ліміт швидкості тощо), автоматично пробується наступний налаштований кандидат. Якщо помиляються всі, помилка містить подробиці кожної спроби.
|
||||
|
||||
Примітки:
|
||||
|
||||
- Перевизначення `model` для окремого виклику є точним: OpenClaw пробує лише цю пару провайдер/модель
|
||||
і не переходить до налаштованих primary/fallback або автовиявлених
|
||||
провайдерів.
|
||||
- Автовиявлення враховує автентифікацію. Типове значення провайдера додається до списку кандидатів
|
||||
лише тоді, коли OpenClaw справді може автентифікувати цей провайдер.
|
||||
- Автовиявлення увімкнене за замовчуванням. Задайте
|
||||
`agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете, щоб генерація зображень
|
||||
використовувала лише явні записи `model`, `primary` і `fallbacks`.
|
||||
- Задайте `agents.defaults.imageGenerationModel.timeoutMs` для повільних бекендів зображень.
|
||||
Параметр інструмента `timeoutMs` для окремого виклику перевизначає налаштоване типове значення.
|
||||
- Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні
|
||||
типові моделі та підказки щодо env vars для автентифікації.
|
||||
<AccordionGroup>
|
||||
<Accordion title="Перевизначення моделі для окремого виклику є точним">
|
||||
Перевизначення `model` для окремого виклику пробує лише цей провайдер/цю модель і не переходить до налаштованих primary/fallback або автовиявлених провайдерів.
|
||||
</Accordion>
|
||||
<Accordion title="Автовиявлення враховує автентифікацію">
|
||||
Типове значення провайдера потрапляє до списку кандидатів, лише коли OpenClaw справді може автентифікувати цей провайдер. Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише явні записи `model`, `primary` і `fallbacks`.
|
||||
</Accordion>
|
||||
<Accordion title="Таймаути">
|
||||
Установіть `agents.defaults.imageGenerationModel.timeoutMs` для повільних бекендів зображень. Параметр інструмента `timeoutMs` для окремого виклику перевизначає налаштоване значення за замовчуванням.
|
||||
</Accordion>
|
||||
<Accordion title="Перегляд під час виконання">
|
||||
Використовуйте `action: "list"`, щоб переглянути поточно зареєстрованих провайдерів, їхні моделі за замовчуванням і підказки щодо змінних середовища для автентифікації.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
### Редагування зображень
|
||||
|
||||
OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування еталонних зображень. Передайте шлях або URL еталонного зображення:
|
||||
OpenAI, OpenRouter, Google, fal, MiniMax, ComfyUI і xAI підтримують редагування опорних зображень. Передайте шлях або URL опорного зображення:
|
||||
|
||||
```
|
||||
```text
|
||||
"Згенеруй акварельну версію цього фото" + image: "/path/to/photo.jpg"
|
||||
```
|
||||
|
||||
OpenAI, OpenRouter, Google і xAI підтримують до 5 еталонних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
OpenAI, OpenRouter, Google і xAI підтримують до 5 опорних зображень через параметр `images`. fal, MiniMax і ComfyUI підтримують 1.
|
||||
|
||||
### Моделі зображень OpenRouter
|
||||
## Детальніше про провайдерів
|
||||
|
||||
Генерація зображень через OpenRouter використовує той самий `OPENROUTER_API_KEY` і маршрутизується через image API chat completions OpenRouter. Вибирайте моделі зображень OpenRouter з префіксом `openrouter/`:
|
||||
<AccordionGroup>
|
||||
<Accordion title="OpenAI gpt-image-2 (і gpt-image-1.5)">
|
||||
Для генерації зображень OpenAI за замовчуванням використовується `openai/gpt-image-2`. Якщо налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль, що й для чат-моделей підписки Codex, і надсилає запит на зображення через бекенд Codex Responses. Застарілі базові URL Codex, такі як `https://chatgpt.com/backend-api`, канонізуються до `https://chatgpt.com/backend-api/codex` для запитів на зображення. OpenClaw **не** виконує безшумного резервного переходу до `OPENAI_API_KEY` для цього запиту — щоб примусово використовувати прямий маршрут OpenAI Images API, явно налаштуйте `models.providers.openai` з API-ключем, власним base URL або ендпоінтом Azure.
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "openrouter/google/gemini-3.1-flash-image-preview",
|
||||
Моделі `openai/gpt-image-1.5`, `openai/gpt-image-1` і
|
||||
`openai/gpt-image-1-mini` також можна явно вибрати. Використовуйте
|
||||
`gpt-image-1.5` для PNG/WebP із прозорим фоном; поточний API
|
||||
`gpt-image-2` відхиляє `background: "transparent"`.
|
||||
|
||||
`gpt-image-2` підтримує як генерацію зображень із тексту, так і
|
||||
редагування за опорним зображенням через той самий інструмент
|
||||
`image_generate`. OpenClaw передає до OpenAI `prompt`, `count`, `size`, `quality`, `outputFormat`
|
||||
та опорні зображення. OpenAI **не** отримує
|
||||
`aspectRatio` або `resolution` безпосередньо; коли це можливо, OpenClaw зіставляє
|
||||
їх із підтримуваним `size`, інакше інструмент повідомляє про них як
|
||||
про проігноровані перевизначення.
|
||||
|
||||
Параметри, специфічні для OpenAI, розміщені в об’єкті `openai`:
|
||||
|
||||
```json
|
||||
{
|
||||
"quality": "low",
|
||||
"outputFormat": "jpeg",
|
||||
"openai": {
|
||||
"background": "opaque",
|
||||
"moderation": "low",
|
||||
"outputCompression": 60,
|
||||
"user": "end-user-42"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`openai.background` приймає `transparent`, `opaque` або `auto`;
|
||||
прозорий вивід потребує `outputFormat` `png` або `webp` і
|
||||
моделі зображень OpenAI з підтримкою прозорості. OpenClaw спрямовує типові
|
||||
запити `gpt-image-2` на прозорий фон до `gpt-image-1.5`.
|
||||
`openai.outputCompression` застосовується до виводу JPEG/WebP.
|
||||
|
||||
Підказка верхнього рівня `background` не прив’язана до конкретного провайдера і наразі зіставляється
|
||||
з тим самим полем запиту OpenAI `background`, коли вибрано провайдера OpenAI.
|
||||
Провайдери, які не оголошують підтримку фону, повертають
|
||||
це значення в `ignoredOverrides` замість отримання непідтримуваного параметра.
|
||||
|
||||
Щоб спрямувати генерацію зображень OpenAI через розгортання Azure OpenAI
|
||||
замість `api.openai.com`, див.
|
||||
[ендпоінти Azure OpenAI](/uk/providers/openai#azure-openai-endpoints).
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Моделі зображень OpenRouter">
|
||||
Генерація зображень OpenRouter використовує той самий `OPENROUTER_API_KEY` і
|
||||
спрямовується через image API chat completions від OpenRouter. Вибирайте
|
||||
моделі зображень OpenRouter із префіксом `openrouter/`:
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
imageGenerationModel: {
|
||||
primary: "openrouter/google/gemini-3.1-flash-image-preview",
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
OpenClaw передає до OpenRouter `prompt`, `count`, опорні зображення та
|
||||
підказки `aspectRatio` / `resolution`, сумісні з Gemini.
|
||||
Поточні вбудовані скорочені позначення моделей зображень OpenRouter включають
|
||||
`google/gemini-3.1-flash-image-preview`,
|
||||
`google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`. Використовуйте
|
||||
`action: "list"`, щоб побачити, що надає ваш налаштований Plugin.
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="Подвійна автентифікація MiniMax">
|
||||
Генерація зображень MiniMax доступна через обидва вбудовані шляхи
|
||||
автентифікації MiniMax:
|
||||
|
||||
- `minimax/image-01` для налаштувань з API-ключем
|
||||
- `minimax-portal/image-01` для налаштувань OAuth
|
||||
|
||||
</Accordion>
|
||||
<Accordion title="xAI grok-imagine-image">
|
||||
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів
|
||||
лише з prompt і `/v1/images/edits`, коли присутній `image` або `images`.
|
||||
|
||||
- Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
|
||||
- Кількість: до 4
|
||||
- Опорні зображення: один `image` або до п’яти `images`
|
||||
- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Роздільні здатності: `1K`, `2K`
|
||||
- Вивід: повертається як вкладення зображень під керуванням OpenClaw
|
||||
|
||||
OpenClaw навмисно не надає специфічні для xAI параметри `quality`, `mask`,
|
||||
`user` або додаткові співвідношення сторін, доступні лише в xAI, доки ці елементи керування не з’являться
|
||||
у спільному міжпровайдерному контракті `image_generate`.
|
||||
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Приклади
|
||||
|
||||
<Tabs>
|
||||
<Tab title="Генерація (пейзаж 4K)">
|
||||
```text
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Генерація (прозорий PNG)">
|
||||
```text
|
||||
/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
|
||||
```
|
||||
|
||||
OpenClaw передає до OpenRouter `prompt`, `count`, еталонні зображення та
|
||||
Gemini-сумісні підказки `aspectRatio` / `resolution`. Поточні вбудовані
|
||||
скорочення для моделей зображень OpenRouter включають `google/gemini-3.1-flash-image-preview`,
|
||||
`google/gemini-3-pro-image-preview` і `openai/gpt-5.4-image-2`; використовуйте
|
||||
`action: "list"`, щоб побачити, що надає ваш налаштований Plugin.
|
||||
|
||||
### OpenAI `gpt-image-2`
|
||||
|
||||
За замовчуванням генерація зображень OpenAI використовує `openai/gpt-image-2`. Якщо
|
||||
налаштовано OAuth-профіль `openai-codex`, OpenClaw повторно використовує той самий OAuth-профіль,
|
||||
який застосовується моделями чату Codex за підпискою, і надсилає запит на зображення
|
||||
через бекенд Codex Responses. Застарілі base URL Codex, такі як
|
||||
`https://chatgpt.com/backend-api`, канонікалізуються до
|
||||
`https://chatgpt.com/backend-api/codex` для запитів на зображення. Він не
|
||||
виконує тихого резервного переходу до `OPENAI_API_KEY` для цього запиту. Щоб примусово використати прямий маршрут
|
||||
OpenAI Images API, явно налаштуйте `models.providers.openai` за допомогою API-ключа,
|
||||
користувацького base URL або Azure-ендпойнта. Моделі `openai/gpt-image-1.5`,
|
||||
`openai/gpt-image-1` і `openai/gpt-image-1-mini` усе ще можна
|
||||
вибирати явно. Використовуйте `gpt-image-1.5` для виводу PNG/WebP із прозорим тлом;
|
||||
поточний API `gpt-image-2` відхиляє `background: "transparent"`.
|
||||
|
||||
`gpt-image-2` підтримує як генерацію зображень із тексту, так і редагування за
|
||||
еталонним зображенням через той самий інструмент `image_generate`. OpenClaw передає до OpenAI `prompt`,
|
||||
`count`, `size`, `quality`, `outputFormat` і еталонні зображення.
|
||||
OpenAI не отримує `aspectRatio` або `resolution` безпосередньо; коли це можливо,
|
||||
OpenClaw перетворює їх у підтримуваний `size`, інакше інструмент повідомляє про них як про
|
||||
проігноровані перевизначення.
|
||||
|
||||
Опції, специфічні для OpenAI, містяться в об’єкті `openai`:
|
||||
|
||||
```json
|
||||
{
|
||||
"quality": "low",
|
||||
"outputFormat": "jpeg",
|
||||
"openai": {
|
||||
"background": "opaque",
|
||||
"moderation": "low",
|
||||
"outputCompression": 60,
|
||||
"user": "end-user-42"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`openai.background` приймає значення `transparent`, `opaque` або `auto`; прозорі
|
||||
вихідні файли потребують `outputFormat` `png` або `webp` і OpenAI-сумісної моделі
|
||||
зображень із підтримкою прозорості. OpenClaw маршрутизує типові запити
|
||||
`gpt-image-2` на прозоре тло до `gpt-image-1.5`. `openai.outputCompression` застосовується до виходів JPEG/WebP.
|
||||
|
||||
Підказка `background` верхнього рівня є нейтральною щодо провайдера й наразі зіставляється з тим самим
|
||||
полем запиту OpenAI `background`, коли вибрано провайдера OpenAI.
|
||||
Провайдери, які не оголошують підтримку тла, повертають його в `ignoredOverrides`
|
||||
замість отримання непідтримуваного параметра.
|
||||
|
||||
Коли ви просите агента створити зображення OpenAI з прозорим тлом, очікуваний
|
||||
виклик інструмента має такий вигляд:
|
||||
|
||||
```json
|
||||
{
|
||||
"model": "openai/gpt-image-1.5",
|
||||
"prompt": "A simple red circle sticker on a transparent background",
|
||||
"outputFormat": "png",
|
||||
"background": "transparent"
|
||||
}
|
||||
```
|
||||
|
||||
Явна модель `openai/gpt-image-1.5` зберігає портативність запиту між
|
||||
зведеннями інструментів і harnesses. Якщо агент натомість використовує типову
|
||||
`openai/gpt-image-2` з `openai.background: "transparent"` у публічному маршруті
|
||||
OpenAI або OpenAI Codex OAuth, OpenClaw переписує запит провайдера на
|
||||
`gpt-image-1.5`. Azure і користувацькі OpenAI-сумісні ендпойнти зберігають свої
|
||||
налаштовані назви deployment/model.
|
||||
|
||||
Для безголової генерації через CLI використовуйте еквівалентні прапорці `openclaw infer`:
|
||||
Еквівалентний CLI:
|
||||
|
||||
```bash
|
||||
openclaw infer image generate \
|
||||
@ -330,86 +328,39 @@ openclaw infer image generate \
|
||||
--json
|
||||
```
|
||||
|
||||
Ті самі прапорці `--output-format` і `--background` також доступні в
|
||||
`openclaw infer image edit`; `--openai-background` лишається доступним як
|
||||
специфічний для OpenAI псевдонім. Поточні вбудовані провайдери, окрім OpenAI, не
|
||||
оголошують явного керування тлом, тож для них `background: "transparent"` повідомляється
|
||||
як проігнорований.
|
||||
|
||||
Згенерувати одне горизонтальне зображення 4K:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="A clean editorial poster for OpenClaw image generation" size=3840x2160 count=1
|
||||
```
|
||||
|
||||
Згенерувати прозорий PNG:
|
||||
|
||||
```
|
||||
/tool image_generate action=generate model=openai/gpt-image-1.5 prompt="A simple red circle sticker on a transparent background" outputFormat=png background=transparent
|
||||
```
|
||||
|
||||
Згенерувати два квадратні зображення:
|
||||
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Генерація (два квадратні)">
|
||||
```text
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Two visual directions for a calm productivity app icon" size=1024x1024 count=2
|
||||
```
|
||||
|
||||
Відредагувати одне локальне еталонне зображення:
|
||||
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Редагування (одне опорне зображення)">
|
||||
```text
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Keep the subject, replace the background with a bright studio setup" image=/path/to/reference.png size=1024x1536
|
||||
```
|
||||
|
||||
Редагування з кількома еталонами:
|
||||
|
||||
```
|
||||
</Tab>
|
||||
<Tab title="Редагування (кілька опорних зображень)">
|
||||
```text
|
||||
/tool image_generate action=generate model=openai/gpt-image-2 prompt="Combine the character identity from the first image with the color palette from the second" images='["/path/to/character.png","/path/to/palette.jpg"]' size=1536x1024
|
||||
```
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Щоб маршрутизувати генерацію зображень OpenAI через deployment Azure OpenAI замість
|
||||
`api.openai.com`, див. [Azure OpenAI endpoints](/uk/providers/openai#azure-openai-endpoints)
|
||||
у документації провайдера OpenAI.
|
||||
|
||||
Генерація зображень MiniMax доступна через обидва вбудовані шляхи автентифікації MiniMax:
|
||||
|
||||
- `minimax/image-01` для конфігурацій з API-ключем
|
||||
- `minimax-portal/image-01` для конфігурацій з OAuth
|
||||
|
||||
## Можливості провайдерів
|
||||
|
||||
| Можливість | OpenAI | Google | fal | MiniMax | ComfyUI | Vydra | xAI |
|
||||
| -------------------- | -------------------- | -------------------- | ------------------- | -------------------------- | ---------------------------------- | ------- | -------------------- |
|
||||
| Генерація | Так (до 4) | Так (до 4) | Так (до 4) | Так (до 9) | Так (виходи визначаються workflow) | Так (1) | Так (до 4) |
|
||||
| Редагування/еталони | Так (до 5 зображень) | Так (до 5 зображень) | Так (1 зображення) | Так (1 зображення, еталон суб’єкта) | Так (1 зображення, налаштоване workflow) | Ні | Так (до 5 зображень) |
|
||||
| Керування розміром | Так (до 4K) | Так | Так | Ні | Ні | Ні | Ні |
|
||||
| Співвідношення сторін| Ні | Так | Так (лише генерація) | Так | Ні | Ні | Так |
|
||||
| Роздільна здатність (1K/2K/4K) | Ні | Так | Так | Ні | Ні | Ні | Так (1K/2K) |
|
||||
|
||||
### xAI `grok-imagine-image`
|
||||
|
||||
Вбудований провайдер xAI використовує `/v1/images/generations` для запитів лише з підказкою
|
||||
і `/v1/images/edits`, коли присутні `image` або `images`.
|
||||
|
||||
- Моделі: `xai/grok-imagine-image`, `xai/grok-imagine-image-pro`
|
||||
- Кількість: до 4
|
||||
- Еталони: одне `image` або до п’яти `images`
|
||||
- Співвідношення сторін: `1:1`, `16:9`, `9:16`, `4:3`, `3:4`, `2:3`, `3:2`
|
||||
- Роздільна здатність: `1K`, `2K`
|
||||
- Виходи: повертаються як вкладення зображень, якими керує OpenClaw
|
||||
|
||||
OpenClaw навмисно не надає доступу до властивих xAI параметрів `quality`, `mask`, `user` або
|
||||
додаткових співвідношень сторін, доступних лише нативно, доки ці елементи керування не з’являться в спільному
|
||||
міжпровайдерному контракті `image_generate`.
|
||||
Ті самі прапорці `--output-format` і `--background` також доступні в
|
||||
`openclaw infer image edit`; `--openai-background` залишається
|
||||
специфічним для OpenAI псевдонімом. Вбудовані провайдери, окрім OpenAI, сьогодні не оголошують
|
||||
явного керування фоном, тому `background: "transparent"` для них позначається
|
||||
як проігнороване.
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд інструментів](/uk/tools) — усі доступні інструменти агента
|
||||
- [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal
|
||||
- [ComfyUI](/uk/providers/comfy) — налаштування локального workflow ComfyUI і Comfy Cloud
|
||||
- [fal](/uk/providers/fal) — налаштування провайдера зображень і відео fal
|
||||
- [Google (Gemini)](/uk/providers/google) — налаштування провайдера зображень Gemini
|
||||
- [MiniMax](/uk/providers/minimax) — налаштування провайдера зображень MiniMax
|
||||
- [OpenAI](/uk/providers/openai) — налаштування провайдера OpenAI Images
|
||||
- [Vydra](/uk/providers/vydra) — налаштування зображень, відео та мовлення Vydra
|
||||
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду й TTS
|
||||
- [Довідник конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel`
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і резервне перемикання
|
||||
- [xAI](/uk/providers/xai) — налаштування Grok для зображень, відео, пошуку, виконання коду та TTS
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `imageGenerationModel`
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і аварійне перемикання
|
||||
|
||||
@ -3,110 +3,124 @@ read_when:
|
||||
- Генерація музики або аудіо через агента
|
||||
- Налаштування провайдерів і моделей для генерації музики
|
||||
- Розуміння параметрів інструмента `music_generate`
|
||||
summary: Створюйте музику за допомогою спільних провайдерів, зокрема Plugin на основі робочих процесів
|
||||
sidebarTitle: Music generation
|
||||
summary: Генеруйте музику через `music_generate` у робочих процесах Google Lyria, MiniMax і ComfyUI
|
||||
title: Генерація музики
|
||||
x-i18n:
|
||||
generated_at: "2026-04-25T20:33:46Z"
|
||||
generated_at: "2026-04-26T05:36:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: 1b23ad4c787e404f681c71e48b73d1642d7eeb116c11cc8716ae4f0e7a75677d
|
||||
source_hash: 4eda549dbb93cbfe15e04462e08b7c86ff0718160244e3e5de3b041c62ee81ea
|
||||
source_path: tools/music-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через
|
||||
спільну можливість генерації музики з налаштованими провайдерами, такими як Google,
|
||||
спільну можливість генерації музики з налаштованими провайдерами — наразі це Google,
|
||||
MiniMax і ComfyUI, налаштований через робочі процеси.
|
||||
|
||||
Для сеансів агента на основі спільних провайдерів OpenClaw запускає генерацію музики як
|
||||
фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента, коли
|
||||
трек готовий, щоб агент міг опублікувати готове аудіо назад в оригінальний канал.
|
||||
Для запусків агента з підтримкою сесій OpenClaw запускає генерацію музики як
|
||||
фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента,
|
||||
коли трек готовий, щоб агент міг опублікувати завершене аудіо назад у
|
||||
початковий канал.
|
||||
|
||||
<Note>
|
||||
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні один провайдер генерації музики. Якщо ви не бачите `music_generate` в інструментах вашого агента, налаштуйте `agents.defaults.musicGenerationModel` або вкажіть API-ключ провайдера.
|
||||
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні
|
||||
один провайдер генерації музики. Якщо ви не бачите `music_generate` в
|
||||
інструментах вашого агента, налаштуйте `agents.defaults.musicGenerationModel`
|
||||
або встановіть API-ключ провайдера.
|
||||
</Note>
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
### Генерація на основі спільних провайдерів
|
||||
<Tabs>
|
||||
<Tab title="Спільний із підтримкою провайдера">
|
||||
<Steps>
|
||||
<Step title="Налаштуйте автентифікацію">
|
||||
Встановіть API-ключ принаймні для одного провайдера — наприклад,
|
||||
`GEMINI_API_KEY` або `MINIMAX_API_KEY`.
|
||||
</Step>
|
||||
<Step title="Виберіть модель за замовчуванням (необов’язково)">
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
musicGenerationModel: {
|
||||
primary: "google/lyria-3-clip-preview",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
</Step>
|
||||
<Step title="Зверніться до агента">
|
||||
_"Згенеруй енергійний синт-поп трек про нічну поїздку крізь
|
||||
неонове місто."_
|
||||
|
||||
1. Укажіть API-ключ принаймні для одного провайдера, наприклад `GEMINI_API_KEY` або
|
||||
`MINIMAX_API_KEY`.
|
||||
2. За бажанням укажіть бажану модель:
|
||||
Агент автоматично викликає `music_generate`. Не потрібно
|
||||
додавати інструмент до списку дозволених.
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
```json5
|
||||
{
|
||||
agents: {
|
||||
defaults: {
|
||||
musicGenerationModel: {
|
||||
primary: "google/lyria-3-clip-preview",
|
||||
},
|
||||
},
|
||||
},
|
||||
}
|
||||
```
|
||||
Для прямих синхронних контекстів без запуску агента з підтримкою сесії
|
||||
вбудований інструмент усе одно переходить до вбудованої генерації та
|
||||
повертає фінальний шлях до медіафайлу в результаті інструмента.
|
||||
|
||||
3. Попросіть агента: _"Згенеруй енергійний synthpop-трек про нічну поїздку
|
||||
неоновим містом."_
|
||||
|
||||
Агент автоматично викликає `music_generate`. Дозвільний список інструментів не потрібен.
|
||||
|
||||
Для прямих синхронних контекстів без запуску агента на основі сеансу вбудований
|
||||
інструмент усе одно переходить до вбудованої генерації та повертає фінальний шлях до медіа в результаті інструмента.
|
||||
</Tab>
|
||||
<Tab title="Робочий процес ComfyUI">
|
||||
<Steps>
|
||||
<Step title="Налаштуйте робочий процес">
|
||||
Налаштуйте `plugins.entries.comfy.config.music` із JSON робочого
|
||||
процесу та вузлами prompt/output.
|
||||
</Step>
|
||||
<Step title="Хмарна автентифікація (необов’язково)">
|
||||
Для Comfy Cloud встановіть `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
|
||||
</Step>
|
||||
<Step title="Викличте інструмент">
|
||||
```text
|
||||
/tool music_generate prompt="Теплий ембієнтний синт-луп із м’якою текстурою стрічки"
|
||||
```
|
||||
</Step>
|
||||
</Steps>
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
Приклади запитів:
|
||||
|
||||
```text
|
||||
Generate a cinematic piano track with soft strings and no vocals.
|
||||
Згенеруй кінематографічний фортепіанний трек із м’якими струнними без вокалу.
|
||||
```
|
||||
|
||||
```text
|
||||
Generate an energetic chiptune loop about launching a rocket at sunrise.
|
||||
Згенеруй енергійний чіптюн-луп про запуск ракети на світанку.
|
||||
```
|
||||
|
||||
### Генерація Comfy на основі робочого процесу
|
||||
## Підтримувані провайдери
|
||||
|
||||
Вбудований Plugin `comfy` підключається до спільного інструмента `music_generate` через
|
||||
реєстр провайдерів генерації музики.
|
||||
|
||||
1. Налаштуйте `plugins.entries.comfy.config.music` за допомогою JSON робочого процесу та
|
||||
вузлів prompt/output.
|
||||
2. Якщо ви використовуєте Comfy Cloud, укажіть `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
|
||||
3. Попросіть агента створити музику або викличте інструмент безпосередньо.
|
||||
|
||||
Приклад:
|
||||
|
||||
```text
|
||||
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
|
||||
```
|
||||
|
||||
## Підтримка спільних вбудованих провайдерів
|
||||
|
||||
| Провайдер | Модель за замовчуванням | Еталонні вхідні дані | Підтримувані параметри керування | API-ключ |
|
||||
| Провайдер | Модель за замовчуванням | Еталонні вхідні дані | Підтримувані параметри керування | Автентифікація |
|
||||
| --------- | ----------------------- | -------------------- | ------------------------------------------------------ | -------------------------------------- |
|
||||
| ComfyUI | `workflow` | До 1 зображення | Музика або аудіо, визначені робочим процесом | `COMFY_API_KEY`, `COMFY_CLOUD_API_KEY` |
|
||||
| Google | `lyria-3-clip-preview` | До 10 зображень | `lyrics`, `instrumental`, `format` | `GEMINI_API_KEY`, `GOOGLE_API_KEY` |
|
||||
| MiniMax | `music-2.6` | Немає | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY` або MiniMax OAuth |
|
||||
|
||||
### Матриця оголошених можливостей
|
||||
### Матриця можливостей
|
||||
|
||||
Це явний контракт режимів, який використовується `music_generate`, контрактними тестами
|
||||
та спільним live sweep.
|
||||
Явний контракт режимів, який використовують `music_generate`, контрактні тести та
|
||||
спільний live sweep:
|
||||
|
||||
| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live-ланки |
|
||||
| --------- | ---------- | ------ | ----------------- | ------------------------------------------------------------------------- |
|
||||
| ComfyUI | Так | Так | 1 зображення | Не входить до спільного sweep; покривається `extensions/comfy/comfy.live.test.ts` |
|
||||
| Google | Так | Так | 10 зображень | `generate`, `edit` |
|
||||
| MiniMax | Так | Ні | Немає | `generate` |
|
||||
| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live-режими |
|
||||
| --------- | :--------: | :----: | ----------------- | ---------------------------------------------------------------------------- |
|
||||
| ComfyUI | ✓ | ✓ | 1 зображення | Не входить до спільного sweep; покрито в `extensions/comfy/comfy.live.test.ts` |
|
||||
| Google | ✓ | ✓ | 10 зображень | `generate`, `edit` |
|
||||
| MiniMax | ✓ | — | Немає | `generate` |
|
||||
|
||||
Використовуйте `action: "list"`, щоб переглянути доступні спільні провайдери та моделі
|
||||
під час виконання:
|
||||
Використовуйте `action: "list"`, щоб у середовищі виконання переглянути доступні спільні провайдери та моделі:
|
||||
|
||||
```text
|
||||
/tool music_generate action=list
|
||||
```
|
||||
|
||||
Використовуйте `action: "status"`, щоб переглянути активне завдання музики на основі сеансу:
|
||||
Використовуйте `action: "status"`, щоб перевірити активне музичне завдання з підтримкою сесії:
|
||||
|
||||
```text
|
||||
/tool music_generate action=status
|
||||
@ -115,54 +129,81 @@ Generate an energetic chiptune loop about launching a rocket at sunrise.
|
||||
Приклад прямої генерації:
|
||||
|
||||
```text
|
||||
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true
|
||||
/tool music_generate prompt="Мрійливий lo-fi hip hop із вініловою текстурою та ніжним дощем" instrumental=true
|
||||
```
|
||||
|
||||
## Параметри вбудованого інструмента
|
||||
## Параметри інструмента
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| ----------------- | -------- | ---------------------------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Запит на генерацію музики (обов’язковий для `action: "generate"`) |
|
||||
| `action` | string | `"generate"` (за замовчуванням), `"status"` для поточного завдання сеансу або `"list"` для перегляду провайдерів |
|
||||
| `model` | string | Перевизначення провайдера/моделі, наприклад `google/lyria-3-pro-preview` або `comfy/workflow` |
|
||||
| `lyrics` | string | Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту |
|
||||
| `instrumental` | boolean | Запит на інструментальний результат, якщо провайдер це підтримує |
|
||||
| `image` | string | Шлях або URL одного еталонного зображення |
|
||||
| `images` | string[] | Кілька еталонних зображень (до 10) |
|
||||
| `durationSeconds` | number | Цільова тривалість у секундах, якщо провайдер підтримує підказки тривалості |
|
||||
| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах |
|
||||
| `format` | string | Підказка щодо формату виводу (`mp3` або `wav`), якщо провайдер це підтримує |
|
||||
| `filename` | string | Підказка щодо назви вихідного файла |
|
||||
<ParamField path="prompt" type="string" required>
|
||||
Запит на генерацію музики. Обов’язковий для `action: "generate"`.
|
||||
</ParamField>
|
||||
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
|
||||
`"status"` повертає поточне завдання сесії; `"list"` переглядає провайдерів.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">
|
||||
Перевизначення провайдера/моделі (наприклад, `google/lyria-3-pro-preview`,
|
||||
`comfy/workflow`).
|
||||
</ParamField>
|
||||
<ParamField path="lyrics" type="string">
|
||||
Необов’язковий текст пісні, якщо провайдер підтримує явне введення тексту.
|
||||
</ParamField>
|
||||
<ParamField path="instrumental" type="boolean">
|
||||
Запитує вивід лише інструментальної версії, якщо провайдер це підтримує.
|
||||
</ParamField>
|
||||
<ParamField path="image" type="string">
|
||||
Шлях або URL одного еталонного зображення.
|
||||
</ParamField>
|
||||
<ParamField path="images" type="string[]">
|
||||
Кілька еталонних зображень (до 10 у провайдерів, які це підтримують).
|
||||
</ParamField>
|
||||
<ParamField path="durationSeconds" type="number">
|
||||
Бажана тривалість у секундах, якщо провайдер підтримує підказки щодо тривалості.
|
||||
</ParamField>
|
||||
<ParamField path="format" type='"mp3" | "wav"'>
|
||||
Підказка щодо формату виводу, якщо провайдер це підтримує.
|
||||
</ParamField>
|
||||
<ParamField path="filename" type="string">Підказка для назви вихідного файлу.</ParamField>
|
||||
<ParamField path="timeoutMs" type="number">Необов’язковий тайм-аут запиту до провайдера в мілісекундах.</ParamField>
|
||||
|
||||
Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі обмеження,
|
||||
такі як кількість вхідних даних, перед надсиланням. Коли провайдер підтримує тривалість, але
|
||||
використовує коротший максимум, ніж запитане значення, OpenClaw автоматично обмежує його
|
||||
до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки
|
||||
ігноруються з попередженням, якщо вибраний провайдер або модель не може їх врахувати.
|
||||
<Note>
|
||||
Не всі провайдери підтримують усі параметри. OpenClaw усе одно перевіряє жорсткі
|
||||
обмеження, наприклад кількість вхідних даних, перед надсиланням. Якщо провайдер підтримує
|
||||
тривалість, але використовує коротший максимум, ніж запитане значення, OpenClaw
|
||||
обмежує його до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки
|
||||
ігноруються з попередженням, коли вибраний провайдер або модель не можуть їх виконати.
|
||||
Результати інструмента повідомляють про застосовані налаштування; `details.normalization`
|
||||
містить будь-яке зіставлення між запитаними та фактично застосованими значеннями.
|
||||
</Note>
|
||||
|
||||
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw обмежує
|
||||
тривалість під час переходу до резервного провайдера, повернене `durationSeconds` відображає
|
||||
надіслане значення, а `details.normalization.durationSeconds` показує зіставлення
|
||||
між запитаним і застосованим значенням.
|
||||
## Асинхронна поведінка
|
||||
|
||||
## Асинхронна поведінка для шляху на основі спільних провайдерів
|
||||
Генерація музики з підтримкою сесії виконується як фонове завдання:
|
||||
|
||||
- Запуски агента на основі сеансу: `music_generate` створює фонове завдання, одразу повертає відповідь про запуск/завдання, а готовий трек публікує пізніше в наступному повідомленні агента.
|
||||
- Запобігання дублюванню: поки це фонове завдання має статус `queued` або `running`, наступні виклики `music_generate` у тому самому сеансі повертають статус завдання замість запуску нової генерації.
|
||||
- Перевірка статусу: використовуйте `action: "status"`, щоб переглянути активне музичне завдання на основі сеансу без запуску нового.
|
||||
- Відстеження завдань: використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб переглянути статуси `queued`, `running` і фінальні статуси для генерації.
|
||||
- Пробудження після завершення: OpenClaw додає внутрішню подію завершення назад у той самий сеанс, щоб модель могла сама написати видиме користувачеві повідомлення-продовження.
|
||||
- Підказка для запиту: наступні користувацькі/ручні ходи в тому самому сеансі отримують невелику підказку під час виконання, якщо завдання генерації музики вже триває, щоб модель не викликала `music_generate` повторно навмання.
|
||||
- Режим без сеансу: прямі/локальні контексти без реального сеансу агента все одно виконуються вбудовано та повертають фінальний аудіорезультат у тому самому ході.
|
||||
- **Фонове завдання:** `music_generate` створює фонове завдання, одразу повертає
|
||||
відповідь про запуск/завдання та публікує завершений трек пізніше
|
||||
в наступному повідомленні агента.
|
||||
- **Запобігання дублюванню:** поки завдання має стан `queued` або `running`, наступні
|
||||
виклики `music_generate` у тій самій сесії повертають статус завдання замість
|
||||
запуску іншої генерації. Використовуйте `action: "status"` для явної перевірки.
|
||||
- **Перевірка статусу:** `openclaw tasks list` або `openclaw tasks show <taskId>`
|
||||
перевіряє статуси queued, running і terminal.
|
||||
- **Пробудження після завершення:** OpenClaw вставляє внутрішню подію завершення назад
|
||||
у ту саму сесію, щоб модель могла сама написати видиме користувачеві
|
||||
наступне повідомлення.
|
||||
- **Підказка в запиті:** наступні користувацькі/ручні ходи в тій самій сесії отримують невелику
|
||||
підказку середовища виконання, коли музичне завдання вже виконується, щоб модель
|
||||
не викликала `music_generate` повторно навмання.
|
||||
- **Резервний варіант без сесії:** прямі/локальні контексти без реальної сесії
|
||||
агента виконуються вбудовано та повертають фінальний результат аудіо в тому самому ході.
|
||||
|
||||
### Життєвий цикл завдання
|
||||
|
||||
Кожен запит `music_generate` проходить через чотири стани:
|
||||
|
||||
1. **queued** -- завдання створено, очікує, поки провайдер його прийме.
|
||||
2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера та тривалості).
|
||||
3. **succeeded** -- трек готовий; агент пробуджується та публікує його в розмові.
|
||||
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з деталями помилки.
|
||||
| Стан | Значення |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `queued` | Завдання створено, очікує, поки провайдер його прийме. |
|
||||
| `running` | Провайдер виконує обробку (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості). |
|
||||
| `succeeded` | Трек готовий; агент пробуджується й публікує його в розмові. |
|
||||
| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. |
|
||||
|
||||
Перевірка статусу з CLI:
|
||||
|
||||
@ -172,9 +213,7 @@ openclaw tasks show <taskId>
|
||||
openclaw tasks cancel <taskId>
|
||||
```
|
||||
|
||||
Запобігання дублюванню: якщо для поточного сеансу музичне завдання вже має статус `queued` або `running`, `music_generate` повертає статус наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб виконати явну перевірку без запуску нової генерації.
|
||||
|
||||
## Налаштування
|
||||
## Конфігурація
|
||||
|
||||
### Вибір моделі
|
||||
|
||||
@ -193,37 +232,58 @@ openclaw tasks cancel <taskId>
|
||||
|
||||
### Порядок вибору провайдера
|
||||
|
||||
Під час генерації музики OpenClaw намагається використовувати провайдерів у такому порядку:
|
||||
OpenClaw пробує провайдерів у такому порядку:
|
||||
|
||||
1. параметр `model` з виклику інструмента, якщо агент його вказує
|
||||
2. `musicGenerationModel.primary` із конфігурації
|
||||
3. `musicGenerationModel.fallbacks` по черзі
|
||||
4. Автовизначення лише за допомогою типових значень провайдера на основі автентифікації:
|
||||
- спочатку поточний провайдер за замовчуванням
|
||||
- решта зареєстрованих провайдерів генерації музики в порядку provider-id
|
||||
1. Параметр `model` з виклику інструмента (якщо агент його вказує).
|
||||
2. `musicGenerationModel.primary` з конфігурації.
|
||||
3. `musicGenerationModel.fallbacks` у вказаному порядку.
|
||||
4. Автовизначення лише з використанням типових значень провайдера на основі автентифікації:
|
||||
- спочатку поточний провайдер за замовчуванням;
|
||||
- решта зареєстрованих провайдерів генерації музики в порядку provider-id.
|
||||
|
||||
Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо всі
|
||||
завершуються помилкою, помилка містить деталі кожної спроби.
|
||||
|
||||
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете,
|
||||
щоб генерація музики використовувала лише явні записи `model`, `primary` і `fallbacks`.
|
||||
Встановіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати лише
|
||||
явно вказані записи `model`, `primary` і `fallbacks`.
|
||||
|
||||
## Примітки щодо провайдерів
|
||||
|
||||
- Google використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
|
||||
prompt, необов’язковий текст пісні та необов’язкові еталонні зображення.
|
||||
- MiniMax використовує пакетну кінцеву точку `music_generation`. Поточний вбудований потік
|
||||
підтримує prompt, необов’язковий текст пісні, інструментальний режим, керування тривалістю та
|
||||
вивід mp3 через автентифікацію API-ключем `minimax` або OAuth `minimax-portal`.
|
||||
- Підтримка ComfyUI базується на робочому процесі та залежить від налаштованого графа плюс
|
||||
зіставлення вузлів для полів prompt/output.
|
||||
<AccordionGroup>
|
||||
<Accordion title="ComfyUI">
|
||||
Керується робочим процесом і залежить від налаштованого графа та зіставлення вузлів
|
||||
для полів prompt/output. Вбудований Plugin `comfy` підключається до
|
||||
спільного інструмента `music_generate` через реєстр провайдерів
|
||||
генерації музики.
|
||||
</Accordion>
|
||||
<Accordion title="Google (Lyria 3)">
|
||||
Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
|
||||
prompt, необов’язковий текст пісні та необов’язкові еталонні зображення.
|
||||
</Accordion>
|
||||
<Accordion title="MiniMax">
|
||||
Використовує пакетний ендпойнт `music_generation`. Підтримує prompt, необов’язковий
|
||||
текст пісні, інструментальний режим, керування тривалістю та вивід у форматі mp3 через
|
||||
автентифікацію API-ключем `minimax` або OAuth `minimax-portal`.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Як вибрати правильний шлях
|
||||
|
||||
- **Спільний із підтримкою провайдера** — коли вам потрібні вибір моделі, резервне
|
||||
перемикання між провайдерами та вбудований асинхронний потік завдань/статусу.
|
||||
- **Шлях Plugin (ComfyUI)** — коли вам потрібен власний граф робочого процесу або
|
||||
провайдер, який не входить до спільної вбудованої можливості генерації музики.
|
||||
|
||||
Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте спільну поведінку провайдерів,
|
||||
почніть із [Google (Gemini)](/uk/providers/google) або
|
||||
[MiniMax](/uk/providers/minimax).
|
||||
|
||||
## Режими можливостей провайдера
|
||||
|
||||
Спільний контракт генерації музики тепер підтримує явні оголошення режимів:
|
||||
Спільний контракт генерації музики підтримує явні оголошення режимів:
|
||||
|
||||
- `generate` для генерації лише за prompt
|
||||
- `edit`, коли запит містить одне або більше еталонних зображень
|
||||
- `generate` для генерації лише за prompt.
|
||||
- `edit`, коли запит містить одне або кілька еталонних зображень.
|
||||
|
||||
Нові реалізації провайдерів мають надавати перевагу явним блокам режимів:
|
||||
|
||||
@ -243,20 +303,15 @@ capabilities: {
|
||||
}
|
||||
```
|
||||
|
||||
Застарілих плоских полів, таких як `maxInputImages`, `supportsLyrics` і
|
||||
`supportsFormat`, недостатньо для оголошення підтримки редагування. Провайдери мають
|
||||
явно оголошувати `generate` і `edit`, щоб live-тести, контрактні тести та
|
||||
спільний інструмент `music_generate` могли детерміновано перевіряти підтримку режимів.
|
||||
|
||||
## Вибір правильного шляху
|
||||
|
||||
- Використовуйте шлях на основі спільних провайдерів, коли вам потрібні вибір моделі, перемикання між провайдерами у разі збоїв і вбудований асинхронний потік завдань/статусу.
|
||||
- Використовуйте шлях Plugin, наприклад ComfyUI, коли вам потрібен власний граф робочого процесу або провайдер, який не є частиною спільної вбудованої можливості генерації музики.
|
||||
- Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. [ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільних провайдерів, почніть із [Google (Gemini)](/uk/providers/google) або [MiniMax](/uk/providers/minimax).
|
||||
Застарілі плоскі поля, такі як `maxInputImages`, `supportsLyrics` і
|
||||
`supportsFormat`, **недостатні** для оголошення підтримки редагування. Провайдерам
|
||||
слід явно оголошувати `generate` і `edit`, щоб live-тести, контрактні
|
||||
тести та спільний інструмент `music_generate` могли детерміновано перевіряти
|
||||
підтримку режимів.
|
||||
|
||||
## Live-тести
|
||||
|
||||
Добровільне live-покриття для спільних вбудованих провайдерів:
|
||||
Покриття live-тестами за явною згодою для спільних вбудованих провайдерів:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
|
||||
@ -268,17 +323,16 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.liv
|
||||
pnpm test:live:media music
|
||||
```
|
||||
|
||||
Цей live-файл завантажує відсутні змінні середовища провайдерів із `~/.profile`, за
|
||||
замовчуванням віддає перевагу live/env API-ключам перед збереженими профілями автентифікації та виконує покриття і для
|
||||
`generate`, і для оголошеного `edit`, коли провайдер вмикає режим редагування.
|
||||
Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, за
|
||||
замовчуванням віддає перевагу API-ключам live/env перед збереженими профілями автентифікації
|
||||
та запускає покриття і для `generate`, і для оголошеного `edit`, коли провайдер вмикає режим edit.
|
||||
Поточне покриття:
|
||||
|
||||
Сьогодні це означає:
|
||||
|
||||
- `google`: `generate` плюс `edit`
|
||||
- `google`: `generate` і `edit`
|
||||
- `minimax`: лише `generate`
|
||||
- `comfy`: окреме live-покриття Comfy, не спільний sweep провайдерів
|
||||
|
||||
Добровільне live-покриття для вбудованого музичного шляху ComfyUI:
|
||||
Покриття live-тестами за явною згодою для вбудованого музичного шляху ComfyUI:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
|
||||
@ -289,10 +343,10 @@ Live-файл Comfy також охоплює робочі процеси comfy
|
||||
|
||||
## Пов’язане
|
||||
|
||||
- [Фонові завдання](/uk/automation/tasks) - відстеження завдань для відокремлених запусків `music_generate`
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) - конфігурація `musicGenerationModel`
|
||||
- [Фонові завдання](/uk/automation/tasks) — відстеження завдань для відокремлених запусків `music_generate`
|
||||
- [ComfyUI](/uk/providers/comfy)
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults) — конфігурація `musicGenerationModel`
|
||||
- [Google (Gemini)](/uk/providers/google)
|
||||
- [MiniMax](/uk/providers/minimax)
|
||||
- [Моделі](/uk/concepts/models) - налаштування моделей і перемикання при збоях
|
||||
- [Моделі](/uk/concepts/models) — конфігурація моделей і резервне перемикання
|
||||
- [Огляд інструментів](/uk/tools)
|
||||
|
||||
@ -1,83 +1,102 @@
|
||||
---
|
||||
read_when:
|
||||
- Генерація відео через агента
|
||||
- Налаштування провайдерів і моделей генерації відео
|
||||
- Створення відео через агента
|
||||
- Налаштування провайдерів і моделей для генерації відео
|
||||
- Розуміння параметрів інструмента `video_generate`
|
||||
summary: Генеруйте відео з тексту, зображень або наявних відео за допомогою 14 бекендів провайдерів
|
||||
sidebarTitle: Video generation
|
||||
summary: Створюйте відео за допомогою `video_generate` з тексту, зображень або посилань на відео через 14 бекендів провайдерів
|
||||
title: Генерація відео
|
||||
x-i18n:
|
||||
generated_at: "2026-04-26T01:43:33Z"
|
||||
generated_at: "2026-04-26T05:36:23Z"
|
||||
model: gpt-5.4
|
||||
provider: openai
|
||||
source_hash: b981ca669e92a80fcfb8ff826e0b72edbe673610128afc1d401fa79f95e47c02
|
||||
source_hash: b70f4d47318c822f06d979308a0e1fce87de40be9c213f64b4c815dcedba944b
|
||||
source_path: tools/video-generation.md
|
||||
workflow: 15
|
||||
---
|
||||
|
||||
Агенти OpenClaw можуть генерувати відео з текстових запитів, еталонних зображень або наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із різними варіантами моделей, режимами введення та наборами можливостей. Агент автоматично вибирає правильного провайдера на основі вашої конфігурації та доступних API-ключів.
|
||||
Агенти OpenClaw можуть створювати відео з текстових запитів, еталонних зображень або
|
||||
наявних відео. Підтримуються чотирнадцять бекендів провайдерів, кожен із
|
||||
різними варіантами моделей, режимами введення та наборами функцій. Агент
|
||||
автоматично вибирає відповідного провайдера на основі вашої конфігурації та
|
||||
доступних API-ключів.
|
||||
|
||||
<Note>
|
||||
Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер генерації відео. Якщо ви не бачите його серед інструментів агента, установіть API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
|
||||
Інструмент `video_generate` з’являється лише тоді, коли доступний принаймні один провайдер
|
||||
генерації відео. Якщо ви його не бачите серед інструментів агента, задайте
|
||||
API-ключ провайдера або налаштуйте `agents.defaults.videoGenerationModel`.
|
||||
</Note>
|
||||
|
||||
OpenClaw розглядає генерацію відео як три режими виконання:
|
||||
|
||||
- `generate` для запитів текст-у-відео без еталонних медіа
|
||||
- `imageToVideo`, коли запит містить одне або кілька еталонних зображень
|
||||
- `videoToVideo`, коли запит містить одне або кілька еталонних відео
|
||||
- `generate` — запити text-to-video без еталонних медіафайлів.
|
||||
- `imageToVideo` — запит містить одне або кілька еталонних зображень.
|
||||
- `videoToVideo` — запит містить одне або кілька еталонних відео.
|
||||
|
||||
Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент перевіряє активний
|
||||
режим перед надсиланням і повідомляє про підтримувані режими в `action=list`.
|
||||
Провайдери можуть підтримувати будь-яку підмножину цих режимів. Інструмент
|
||||
перевіряє активний режим перед надсиланням і показує підтримувані режими в `action=list`.
|
||||
|
||||
## Швидкий старт
|
||||
|
||||
1. Установіть API-ключ для будь-якого підтримуваного провайдера:
|
||||
<Steps>
|
||||
<Step title="Налаштуйте автентифікацію">
|
||||
Задайте API-ключ для будь-якого підтримуваного провайдера:
|
||||
|
||||
```bash
|
||||
export GEMINI_API_KEY="your-key"
|
||||
```
|
||||
```bash
|
||||
export GEMINI_API_KEY="your-key"
|
||||
```
|
||||
|
||||
2. За бажанням зафіксуйте типову модель:
|
||||
</Step>
|
||||
<Step title="Виберіть модель за замовчуванням (необов’язково)">
|
||||
```bash
|
||||
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
|
||||
```
|
||||
</Step>
|
||||
<Step title="Попросіть агента">
|
||||
> Згенеруй 5-секундне кінематографічне відео з дружнім лобстером, який катається на серфі на заході сонця.
|
||||
|
||||
```bash
|
||||
openclaw config set agents.defaults.videoGenerationModel.primary "google/veo-3.1-fast-generate-preview"
|
||||
```
|
||||
Агент автоматично викликає `video_generate`. Дозволяти інструмент
|
||||
окремо не потрібно.
|
||||
|
||||
3. Попросіть агента:
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
> Створи 5-секундне кінематографічне відео з доброзичливим лобстером, який серфить на заході сонця.
|
||||
## Як працює асинхронна генерація
|
||||
|
||||
Агент автоматично викликає `video_generate`. Дозвільний список інструментів не потрібен.
|
||||
Генерація відео є асинхронною. Коли агент викликає `video_generate` у
|
||||
сесії:
|
||||
|
||||
## Що відбувається, коли ви генеруєте відео
|
||||
|
||||
Генерація відео є асинхронною. Коли агент викликає `video_generate` у сесії:
|
||||
|
||||
1. OpenClaw надсилає запит провайдеру й одразу повертає ID завдання.
|
||||
1. OpenClaw надсилає запит провайдеру й одразу повертає ідентифікатор завдання.
|
||||
2. Провайдер обробляє завдання у фоновому режимі (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності).
|
||||
3. Коли відео готове, OpenClaw пробуджує ту саму сесію внутрішньою подією завершення.
|
||||
4. Агент публікує готове відео назад в оригінальну розмову.
|
||||
4. Агент публікує готове відео назад у вихідну розмову.
|
||||
|
||||
Поки завдання виконується, дубльовані виклики `video_generate` у тій самій сесії повертають поточний стан завдання замість запуску нової генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб перевірити поступ із CLI.
|
||||
Поки завдання виконується, дубльовані виклики `video_generate` у тій самій
|
||||
сесії повертають поточний статус завдання замість запуску ще однієї
|
||||
генерації. Використовуйте `openclaw tasks list` або `openclaw tasks show <taskId>`, щоб
|
||||
перевірити прогрес через CLI.
|
||||
|
||||
Поза межами запусків агента, прив’язаних до сесії (наприклад, прямих викликів інструмента), інструмент повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу в тому самому ході.
|
||||
Поза запусками агента, прив’язаними до сесії (наприклад, для прямих викликів інструмента),
|
||||
інструмент повертається до вбудованої генерації та повертає фінальний шлях до медіафайлу
|
||||
в тому самому ході.
|
||||
|
||||
Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіа, коли
|
||||
провайдер повертає байти. Типове обмеження на збереження згенерованого відео відповідає
|
||||
ліміту відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для більших рендерів.
|
||||
Коли провайдер також повертає хостований URL результату, OpenClaw може доставити цей URL
|
||||
замість помилки завдання, якщо локальне збереження відхиляє завеликий файл.
|
||||
Згенеровані відеофайли зберігаються в керованому OpenClaw сховищі медіафайлів, якщо
|
||||
провайдер повертає байти. Типове обмеження збереження для згенерованих відео відповідає
|
||||
ліміту для відеомедіа, а `agents.defaults.mediaMaxMb` підвищує його для
|
||||
більших рендерів. Якщо провайдер також повертає розміщений вихідний URL, OpenClaw
|
||||
може передати цей URL замість помилки завдання, якщо локальне збереження
|
||||
відхиляє занадто великий файл.
|
||||
|
||||
### Життєвий цикл завдання
|
||||
|
||||
Кожен запит `video_generate` проходить через чотири стани:
|
||||
| Стан | Значення |
|
||||
| ----------- | ------------------------------------------------------------------------------------------------ |
|
||||
| `queued` | Завдання створено, очікує, поки провайдер його прийме. |
|
||||
| `running` | Провайдер обробляє запит (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності). |
|
||||
| `succeeded` | Відео готове; агент пробуджується та публікує його в розмові. |
|
||||
| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. |
|
||||
|
||||
1. **queued** -- завдання створено, очікує, поки провайдер його прийме.
|
||||
2. **running** -- провайдер виконує обробку (зазвичай від 30 секунд до 5 хвилин залежно від провайдера та роздільної здатності).
|
||||
3. **succeeded** -- відео готове; агент пробуджується й публікує його в розмову.
|
||||
4. **failed** -- помилка провайдера або тайм-аут; агент пробуджується з подробицями помилки.
|
||||
|
||||
Перевірка стану з CLI:
|
||||
Перевіряйте статус через CLI:
|
||||
|
||||
```bash
|
||||
openclaw tasks list
|
||||
@ -85,169 +104,205 @@ openclaw tasks show <taskId>
|
||||
openclaw tasks cancel <taskId>
|
||||
```
|
||||
|
||||
Запобігання дублюванню: якщо для поточної сесії завдання відео вже перебуває у стані `queued` або `running`, `video_generate` повертає стан наявного завдання замість запуску нового. Використовуйте `action: "status"`, щоб явно перевірити стан без запуску нової генерації.
|
||||
Якщо для поточної сесії завдання відео вже має стан `queued` або `running`,
|
||||
`video_generate` повертає статус наявного завдання замість запуску нового.
|
||||
Використовуйте `action: "status"`, щоб перевірити явно без запуску нової
|
||||
генерації.
|
||||
|
||||
## Підтримувані провайдери
|
||||
|
||||
| Провайдер | Типова модель | Текст | Еталонне зображення | Еталонне відео | API-ключ |
|
||||
| -------------------- | ------------------------------ | ----- | ---------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
|
||||
| Alibaba | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` |
|
||||
| BytePlus (1.0) | `seedance-1-0-pro-250528` | Так | До 2 зображень (лише моделі I2V; перший і останній кадр) | Ні | `BYTEPLUS_API_KEY` |
|
||||
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | Так | До 2 зображень (перший і останній кадр через role) | Ні | `BYTEPLUS_API_KEY` |
|
||||
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | Так | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` |
|
||||
| ComfyUI | `workflow` | Так | 1 зображення | Ні | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` |
|
||||
| fal | `fal-ai/minimax/video-01-live` | Так | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео із Seedance reference-to-video | `FAL_KEY` |
|
||||
| Google | `veo-3.1-fast-generate-preview` | Так | 1 зображення | 1 відео | `GEMINI_API_KEY` |
|
||||
| MiniMax | `MiniMax-Hailuo-2.3` | Так | 1 зображення | Ні | `MINIMAX_API_KEY` або MiniMax OAuth |
|
||||
| OpenAI | `sora-2` | Так | 1 зображення | 1 відео | `OPENAI_API_KEY` |
|
||||
| Qwen | `wan2.6-t2v` | Так | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` |
|
||||
| Runway | `gen4.5` | Так | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` |
|
||||
| Together | `Wan-AI/Wan2.2-T2V-A14B` | Так | 1 зображення | Ні | `TOGETHER_API_KEY` |
|
||||
| Vydra | `veo3` | Так | 1 зображення (`kling`) | Ні | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-video` | Так | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` |
|
||||
| Провайдер | Модель за замовчуванням | Текст | Еталонне зображення | Еталонне відео | Автентифікація |
|
||||
| --------------------- | -------------------------------- | :---: | --------------------------------------------------- | ----------------------------------------------- | ---------------------------------------- |
|
||||
| Alibaba | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `MODELSTUDIO_API_KEY` |
|
||||
| BytePlus (1.0) | `seedance-1-0-pro-250528` | ✓ | До 2 зображень (лише моделі I2V; перший і останній кадр) | — | `BYTEPLUS_API_KEY` |
|
||||
| BytePlus Seedance 1.5 | `seedance-1-5-pro-251215` | ✓ | До 2 зображень (перший і останній кадр через role) | — | `BYTEPLUS_API_KEY` |
|
||||
| BytePlus Seedance 2.0 | `dreamina-seedance-2-0-260128` | ✓ | До 9 еталонних зображень | До 3 відео | `BYTEPLUS_API_KEY` |
|
||||
| ComfyUI | `workflow` | ✓ | 1 зображення | — | `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY` |
|
||||
| fal | `fal-ai/minimax/video-01-live` | ✓ | 1 зображення; до 9 із Seedance reference-to-video | До 3 відео з Seedance reference-to-video | `FAL_KEY` |
|
||||
| Google | `veo-3.1-fast-generate-preview` | ✓ | 1 зображення | 1 відео | `GEMINI_API_KEY` |
|
||||
| MiniMax | `MiniMax-Hailuo-2.3` | ✓ | 1 зображення | — | `MINIMAX_API_KEY` або MiniMax OAuth |
|
||||
| OpenAI | `sora-2` | ✓ | 1 зображення | 1 відео | `OPENAI_API_KEY` |
|
||||
| Qwen | `wan2.6-t2v` | ✓ | Так (віддалений URL) | Так (віддалений URL) | `QWEN_API_KEY` |
|
||||
| Runway | `gen4.5` | ✓ | 1 зображення | 1 відео | `RUNWAYML_API_SECRET` |
|
||||
| Together | `Wan-AI/Wan2.2-T2V-A14B` | ✓ | 1 зображення | — | `TOGETHER_API_KEY` |
|
||||
| Vydra | `veo3` | ✓ | 1 зображення (`kling`) | — | `VYDRA_API_KEY` |
|
||||
| xAI | `grok-imagine-video` | ✓ | 1 зображення першого кадру або до 7 `reference_image` | 1 відео | `XAI_API_KEY` |
|
||||
|
||||
Деякі провайдери приймають додаткові або альтернативні змінні середовища API-ключів. Докладніше див. на окремих [сторінках провайдерів](#related).
|
||||
Деякі провайдери приймають додаткові або альтернативні змінні середовища для API-ключів. Докладніше дивіться
|
||||
на окремих [сторінках провайдерів](#related).
|
||||
|
||||
Виконайте `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та
|
||||
Запустіть `video_generate action=list`, щоб під час виконання переглянути доступних провайдерів, моделі та
|
||||
режими виконання.
|
||||
|
||||
### Матриця оголошених можливостей
|
||||
### Матриця можливостей
|
||||
|
||||
Це явний контракт режимів, який використовується `video_generate`, контрактними тестами
|
||||
та спільним live sweep.
|
||||
Явний контракт режимів, який використовують `video_generate`, контрактні тести та
|
||||
спільний live sweep:
|
||||
|
||||
| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live lanes наразі |
|
||||
| --------- | ---------- | -------------- | -------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Alibaba | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
|
||||
| BytePlus | Так | Так | Ні | `generate`, `imageToVideo` |
|
||||
| ComfyUI | Так | Так | Ні | Не у спільному sweep; покриття, специфічне для workflow, розміщено в тестах Comfy |
|
||||
| fal | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` лише при використанні Seedance reference-to-video |
|
||||
| Google | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний sweep Gemini/Veo на основі буфера не приймає це введення |
|
||||
| MiniMax | Так | Так | Ні | `generate`, `imageToVideo` |
|
||||
| OpenAI | Так | Так | Так | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input зараз потребує доступу до inpaint/remix на боці провайдера |
|
||||
| Qwen | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені `http(s)` URL відео |
|
||||
| Runway | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` виконується лише коли вибрана модель — `runway/gen4_aleph` |
|
||||
| Together | Так | Так | Ні | `generate`, `imageToVideo` |
|
||||
| Vydra | Так | Так | Ні | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення |
|
||||
| xAI | Так | Так | Так | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цей провайдер наразі потребує віддалений URL MP4 |
|
||||
| Провайдер | `generate` | `imageToVideo` | `videoToVideo` | Спільні live-режими сьогодні |
|
||||
| --------- | :--------: | :------------: | :------------: | ----------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| Alibaba | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені відео-URL `http(s)` |
|
||||
| BytePlus | ✓ | ✓ | — | `generate`, `imageToVideo` |
|
||||
| ComfyUI | ✓ | ✓ | — | Не входить до спільного sweep; покриття, специфічне для workflow, міститься в тестах Comfy |
|
||||
| fal | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` лише при використанні Seedance reference-to-video |
|
||||
| Google | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки поточний Gemini/Veo sweep на основі буфера не приймає такий ввід |
|
||||
| MiniMax | ✓ | ✓ | — | `generate`, `imageToVideo` |
|
||||
| OpenAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; спільний `videoToVideo` пропущено, оскільки цей шлях org/input наразі потребує доступу до inpaint/remix на боці провайдера |
|
||||
| Qwen | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру потрібні віддалені відео-URL `http(s)` |
|
||||
| Runway | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` виконується лише тоді, коли вибрана модель — `runway/gen4_aleph` |
|
||||
| Together | ✓ | ✓ | — | `generate`, `imageToVideo` |
|
||||
| Vydra | ✓ | ✓ | — | `generate`; спільний `imageToVideo` пропущено, оскільки вбудований `veo3` підтримує лише текст, а вбудований `kling` вимагає віддалений URL зображення |
|
||||
| xAI | ✓ | ✓ | ✓ | `generate`, `imageToVideo`; `videoToVideo` пропущено, оскільки цьому провайдеру наразі потрібен віддалений MP4 URL |
|
||||
|
||||
## Параметри інструмента
|
||||
|
||||
### Обов’язкові
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| -------- | ------ | -------------------------------------------------------------------------- |
|
||||
| `prompt` | string | Текстовий опис відео для генерації (обов’язковий для `action: "generate"`) |
|
||||
<ParamField path="prompt" type="string" required>
|
||||
Текстовий опис відео, яке потрібно згенерувати. Обов’язковий для `action: "generate"`.
|
||||
</ParamField>
|
||||
|
||||
### Вхідні дані вмісту
|
||||
### Вхідні дані контенту
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| ------------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `image` | string | Одне еталонне зображення (шлях або URL) |
|
||||
| `images` | string[] | Кілька еталонних зображень (до 9) |
|
||||
| `imageRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку зображень. Канонічні значення: `first_frame`, `last_frame`, `reference_image` |
|
||||
| `video` | string | Одне еталонне відео (шлях або URL) |
|
||||
| `videos` | string[] | Кілька еталонних відео (до 4) |
|
||||
| `videoRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку відео. Канонічне значення: `reference_video` |
|
||||
| `audioRef` | string | Одне еталонне аудіо (шлях або URL). Використовується, наприклад, для фонового музичного супроводу або еталона голосу, коли провайдер підтримує аудіовходи |
|
||||
| `audioRefs` | string[] | Кілька еталонних аудіо (до 3) |
|
||||
| `audioRoles` | string[] | Необов’язкові підказки ролей для кожної позиції паралельно до об’єднаного списку аудіо. Канонічне значення: `reference_audio` |
|
||||
<ParamField path="image" type="string">Одне еталонне зображення (шлях або URL).</ParamField>
|
||||
<ParamField path="images" type="string[]">Кілька еталонних зображень (до 9).</ParamField>
|
||||
<ParamField path="imageRoles" type="string[]">
|
||||
Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку зображень.
|
||||
Канонічні значення: `first_frame`, `last_frame`, `reference_image`.
|
||||
</ParamField>
|
||||
<ParamField path="video" type="string">Одне еталонне відео (шлях або URL).</ParamField>
|
||||
<ParamField path="videos" type="string[]">Кілька еталонних відео (до 4).</ParamField>
|
||||
<ParamField path="videoRoles" type="string[]">
|
||||
Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку відео.
|
||||
Канонічне значення: `reference_video`.
|
||||
</ParamField>
|
||||
<ParamField path="audioRef" type="string">
|
||||
Одне еталонне аудіо (шлях або URL). Використовується для фонової музики або
|
||||
еталону голосу, якщо провайдер підтримує аудіовхід.
|
||||
</ParamField>
|
||||
<ParamField path="audioRefs" type="string[]">Кілька еталонних аудіо (до 3).</ParamField>
|
||||
<ParamField path="audioRoles" type="string[]">
|
||||
Необов’язкові підказки ролей для кожної позиції, паралельні об’єднаному списку аудіо.
|
||||
Канонічне значення: `reference_audio`.
|
||||
</ParamField>
|
||||
|
||||
Підказки ролей передаються провайдеру без змін. Канонічні значення беруться з
|
||||
<Note>
|
||||
Підказки ролей передаються провайдеру як є. Канонічні значення походять із
|
||||
об’єднання `VideoGenerationAssetRole`, але провайдери можуть приймати додаткові
|
||||
рядки ролей. Масиви `*Roles` не повинні містити більше записів, ніж
|
||||
відповідний список еталонів; помилки на один елемент дають зрозуміле повідомлення.
|
||||
Використовуйте порожній рядок, щоб залишити позицію незаповненою. Для xAI встановіть
|
||||
для кожної ролі зображення значення `reference_image`, щоб використовувати режим генерації
|
||||
`reference_images`; не вказуйте роль або використовуйте `first_frame` для
|
||||
режиму image-to-video з одним зображенням.
|
||||
відповідний список еталонів; помилки на одиницю завершуються зрозумілою помилкою.
|
||||
Використовуйте порожній рядок, щоб залишити слот незаповненим. Для xAI встановіть кожну роль зображення як
|
||||
`reference_image`, щоб використовувати його режим генерації `reference_images`; опустіть
|
||||
роль або використовуйте `first_frame` для image-to-video з одним зображенням.
|
||||
</Note>
|
||||
|
||||
### Керування стилем
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| ----------------- | ------- | -------------------------------------------------------------------------------------- |
|
||||
| `aspectRatio` | string | `1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive` |
|
||||
| `resolution` | string | `480P`, `720P`, `768P` або `1080P` |
|
||||
| `durationSeconds` | number | Цільова тривалість у секундах (округлюється до найближчого підтримуваного провайдером значення) |
|
||||
| `size` | string | Підказка розміру, якщо провайдер це підтримує |
|
||||
| `audio` | boolean | Увімкнути згенероване аудіо у виході, якщо підтримується. Відрізняється від `audioRef*` (входи) |
|
||||
| `watermark` | boolean | Перемикання водяного знака провайдера, якщо підтримується |
|
||||
<ParamField path="aspectRatio" type="string">
|
||||
`1:1`, `2:3`, `3:2`, `3:4`, `4:3`, `4:5`, `5:4`, `9:16`, `16:9`, `21:9` або `adaptive`.
|
||||
</ParamField>
|
||||
<ParamField path="resolution" type="string">`480P`, `720P`, `768P` або `1080P`.</ParamField>
|
||||
<ParamField path="durationSeconds" type="number">
|
||||
Цільова тривалість у секундах (округлюється до найближчого значення, яке підтримує провайдер).
|
||||
</ParamField>
|
||||
<ParamField path="size" type="string">Підказка розміру, якщо провайдер її підтримує.</ParamField>
|
||||
<ParamField path="audio" type="boolean">
|
||||
Увімкнути згенероване аудіо у вихідному результаті, якщо підтримується. Відрізняється від `audioRef*` (вхідні дані).
|
||||
</ParamField>
|
||||
<ParamField path="watermark" type="boolean">Увімкнути або вимкнути водяний знак провайдера, якщо підтримується.</ParamField>
|
||||
|
||||
`adaptive` — це специфічний для провайдера службовий маркер: він передається без змін
|
||||
`adaptive` — це специфічний для провайдера сигнальний маркер: він передається як є
|
||||
провайдерам, які оголошують `adaptive` у своїх можливостях (наприклад, BytePlus
|
||||
Seedance використовує його для автоматичного визначення співвідношення сторін за
|
||||
розмірами вхідного зображення). Провайдери, які цього не оголошують, показують це значення через
|
||||
`details.ignoredOverrides` у результаті інструмента, щоб відкидання було видимим.
|
||||
Seedance використовує його для автоматичного визначення співвідношення сторін із
|
||||
розмірів вхідного зображення). Провайдери, які його не оголошують, показують це значення через
|
||||
`details.ignoredOverrides` у результаті інструмента, щоб було видно, що його пропущено.
|
||||
|
||||
### Розширені
|
||||
### Додатково
|
||||
|
||||
| Параметр | Тип | Опис |
|
||||
| ----------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
||||
| `action` | string | `"generate"` (типово), `"status"` або `"list"` |
|
||||
| `model` | string | Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`) |
|
||||
| `filename` | string | Підказка для назви вихідного файла |
|
||||
| `timeoutMs` | number | Необов’язковий тайм-аут запиту до провайдера в мілісекундах |
|
||||
| `providerOptions` | object | Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`). Провайдери, які оголошують типізовану схему, перевіряють ключі й типи; невідомі ключі або невідповідності змушують пропустити кандидата під час fallback. Провайдери без оголошеної схеми отримують параметри без змін. Виконайте `video_generate action=list`, щоб побачити, що приймає кожен провайдер |
|
||||
<ParamField path="action" type='"generate" | "status" | "list"' default="generate">
|
||||
`"status"` повертає поточне завдання сесії; `"list"` перевіряє провайдерів.
|
||||
</ParamField>
|
||||
<ParamField path="model" type="string">Перевизначення провайдера/моделі (наприклад, `runway/gen4.5`).</ParamField>
|
||||
<ParamField path="filename" type="string">Підказка для імені вихідного файла.</ParamField>
|
||||
<ParamField path="timeoutMs" type="number">Необов’язковий тайм-аут запиту до провайдера в мілісекундах.</ParamField>
|
||||
<ParamField path="providerOptions" type="object">
|
||||
Специфічні для провайдера параметри як JSON-об’єкт (наприклад, `{"seed": 42, "draft": true}`).
|
||||
Провайдери, які оголошують типізовану схему, перевіряють ключі та типи; невідомі
|
||||
ключі або невідповідності пропускають кандидата під час fallback. Провайдери без
|
||||
оголошеної схеми отримують параметри як є. Запустіть `video_generate action=list`,
|
||||
щоб побачити, що приймає кожен провайдер.
|
||||
</ParamField>
|
||||
|
||||
Не всі провайдери підтримують усі параметри. OpenClaw уже нормалізує тривалість до найближчого підтримуваного провайдером значення, а також переназначає трансльовані геометричні підказки, наприклад size-to-aspect-ratio, коли fallback-провайдер має іншу поверхню керування. Справді непідтримувані перевизначення ігноруються за принципом best-effort і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей (наприклад, надто багато еталонних входів) призводять до помилки ще до надсилання.
|
||||
<Note>
|
||||
Не всі провайдери підтримують усі параметри. OpenClaw нормалізує тривалість до
|
||||
найближчого значення, яке підтримує провайдер, і переназначає трансформовані підказки геометрії,
|
||||
наприклад size-to-aspect-ratio, коли fallback-провайдер надає іншу
|
||||
поверхню керування. По-справжньому непідтримувані перевизначення ігноруються за принципом best effort
|
||||
і повідомляються як попередження в результаті інструмента. Жорсткі обмеження можливостей
|
||||
(наприклад, надто багато еталонних вхідних даних) завершуються помилкою ще до надсилання. Результати інструмента
|
||||
показують застосовані налаштування; `details.normalization` фіксує будь-яке
|
||||
перетворення від запитаного до застосованого.
|
||||
</Note>
|
||||
|
||||
Результати інструмента повідомляють про застосовані налаштування. Коли OpenClaw переназначає тривалість або геометрію під час fallback провайдера, повернуті значення `durationSeconds`, `size`, `aspectRatio` і `resolution` відображають те, що було надіслано, а `details.normalization` фіксує перетворення від запитаного до застосованого.
|
||||
Еталонні вхідні дані вибирають режим виконання:
|
||||
|
||||
Еталонні входи також визначають режим виконання:
|
||||
- Немає еталонних медіафайлів → `generate`
|
||||
- Будь-яке еталонне зображення → `imageToVideo`
|
||||
- Будь-яке еталонне відео → `videoToVideo`
|
||||
- Еталонні аудіовхідні дані **не** змінюють визначений режим; вони застосовуються
|
||||
поверх режиму, який вибирають еталонні зображення/відео, і працюють лише
|
||||
з провайдерами, які оголошують `maxInputAudios`.
|
||||
|
||||
- Без еталонних медіа: `generate`
|
||||
- Будь-який еталон зображення: `imageToVideo`
|
||||
- Будь-який еталон відео: `videoToVideo`
|
||||
- Входи еталонного аудіо не змінюють визначений режим; вони застосовуються поверх режиму, який визначають еталони зображень/відео, і працюють лише з провайдерами, які оголошують `maxInputAudios`
|
||||
|
||||
Змішані еталони зображень і відео не є стабільною спільною поверхнею можливостей.
|
||||
Надавайте перевагу одному типу еталона на запит.
|
||||
Змішані еталонні зображення та відео не є стабільною спільною поверхнею можливостей.
|
||||
Рекомендується використовувати один тип еталона на запит.
|
||||
|
||||
#### Fallback і типізовані параметри
|
||||
|
||||
Деякі перевірки можливостей застосовуються на рівні fallback, а не на
|
||||
межі інструмента, щоб запит, який перевищує обмеження основного провайдера,
|
||||
усе ще міг виконатися на fallback, що це підтримує:
|
||||
Деякі перевірки можливостей застосовуються на рівні fallback, а не на межі
|
||||
інструмента, тому запит, який перевищує ліміти основного провайдера, все ще
|
||||
може виконатися на здатному fallback-провайдері:
|
||||
|
||||
- Якщо активний кандидат не оголошує `maxInputAudios` (або оголошує його як
|
||||
`0`), він пропускається, коли запит містить аудіоеталони, і
|
||||
пробується наступний кандидат.
|
||||
- Якщо `maxDurationSeconds` активного кандидата нижчий за запитане
|
||||
`durationSeconds` і кандидат не оголошує список
|
||||
`supportedDurationSeconds`, він пропускається.
|
||||
- Якщо запит містить `providerOptions`, а активний кандидат
|
||||
явно оголошує типізовану схему `providerOptions`, кандидат
|
||||
пропускається, якщо надані ключі відсутні в схемі або типи значень
|
||||
не збігаються. Провайдери, які ще не оголосили схему, отримують
|
||||
параметри без змін (зворотно сумісна пряма передача). Провайдер може
|
||||
явно відмовитися від усіх provider options, оголосивши порожню схему
|
||||
(`capabilities.providerOptions: {}`), що спричиняє такий самий пропуск, як і
|
||||
невідповідність типу.
|
||||
- Активний кандидат, який не оголошує `maxInputAudios` (або `0`), пропускається, якщо
|
||||
запит містить еталонні аудіодані; буде спробувано наступного кандидата.
|
||||
- Якщо `maxDurationSeconds` активного кандидата менше за запитане `durationSeconds`
|
||||
і список `supportedDurationSeconds` не оголошено → кандидата пропускають.
|
||||
- Запит містить `providerOptions`, а активний кандидат явно
|
||||
оголошує типізовану схему `providerOptions` → кандидата пропускають, якщо надані ключі
|
||||
відсутні в схемі або типи значень не збігаються. Провайдери без
|
||||
оголошеної схеми отримують параметри як є (backward-compatible
|
||||
pass-through). Провайдер може відмовитися від усіх provider options,
|
||||
оголосивши порожню схему (`capabilities.providerOptions: {}`), що
|
||||
призводить до того самого пропуску, що й невідповідність типів.
|
||||
|
||||
Перша причина пропуску в запиті журналюється на рівні `warn`, щоб оператори бачили,
|
||||
коли їхній основний провайдер було пропущено; наступні пропуски журналюються на
|
||||
`debug`, щоб довгі ланцюжки fallback не засмічували журнал. Якщо пропущено кожного кандидата,
|
||||
сукупна помилка містить причину пропуску для кожного з них.
|
||||
Перша причина пропуску в запиті записується на рівні `warn`, щоб оператори бачили, коли
|
||||
їхній основний провайдер було пропущено; наступні пропуски записуються на рівні `debug`, щоб
|
||||
довгі ланцюжки fallback не створювали зайвого шуму. Якщо кожного кандидата пропущено, сукупна
|
||||
помилка містить причину пропуску для кожного.
|
||||
|
||||
## Дії
|
||||
|
||||
- **generate** (типово) -- створити відео за заданим запитом і необов’язковими еталонними входами.
|
||||
- **status** -- перевірити стан активного відеозавдання для поточної сесії без запуску нової генерації.
|
||||
- **list** -- показати доступних провайдерів, моделі та їхні можливості.
|
||||
| Дія | Що вона робить |
|
||||
| ---------- | ----------------------------------------------------------------------------------------------------------- |
|
||||
| `generate` | Типова дія. Створює відео з указаного запиту та необов’язкових еталонних вхідних даних. |
|
||||
| `status` | Перевіряє стан поточного відеозавдання для поточної сесії без запуску нової генерації. |
|
||||
| `list` | Показує доступних провайдерів, моделі та їхні можливості. |
|
||||
|
||||
## Вибір моделі
|
||||
|
||||
Під час генерації відео OpenClaw визначає модель у такому порядку:
|
||||
OpenClaw визначає модель у такому порядку:
|
||||
|
||||
1. **Параметр інструмента `model`** -- якщо агент указує його у виклику.
|
||||
2. **`videoGenerationModel.primary`** -- із конфігурації.
|
||||
3. **`videoGenerationModel.fallbacks`** -- пробуються по черзі.
|
||||
4. **Автовизначення** -- використовує провайдерів, які мають дійсну автентифікацію, починаючи з поточного типового провайдера, а потім решту провайдерів в алфавітному порядку.
|
||||
1. **Параметр інструмента `model`** — якщо агент указує його у виклику.
|
||||
2. **`videoGenerationModel.primary`** із конфігурації.
|
||||
3. **`videoGenerationModel.fallbacks`** по черзі.
|
||||
4. **Автовизначення** — провайдери з дійсною автентифікацією, починаючи з
|
||||
поточного провайдера за замовчуванням, а потім решта провайдерів в алфавітному
|
||||
порядку.
|
||||
|
||||
Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо помиляються всі кандидати, помилка містить подробиці кожної спроби.
|
||||
Якщо провайдер завершується помилкою, автоматично виконується спроба з наступним кандидатом. Якщо всі
|
||||
кандидати завершуються помилкою, помилка містить деталі кожної спроби.
|
||||
|
||||
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, якщо хочете,
|
||||
щоб генерація відео використовувала лише явно задані записи `model`, `primary` і `fallbacks`.
|
||||
Установіть `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб використовувати
|
||||
лише явні записи `model`, `primary` і `fallbacks`.
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -266,84 +321,108 @@ Seedance використовує його для автоматичного в
|
||||
|
||||
<AccordionGroup>
|
||||
<Accordion title="Alibaba">
|
||||
Використовує асинхронну кінцеву точку DashScope / Model Studio. Еталонні зображення та відео мають бути віддаленими URL `http(s)`.
|
||||
Використовує асинхронну кінцеву точку DashScope / Model Studio. Еталонні зображення та
|
||||
відео мають бути віддаленими URL `http(s)`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="BytePlus (1.0)">
|
||||
Ідентифікатор провайдера: `byteplus`.
|
||||
|
||||
Моделі: `seedance-1-0-pro-250528` (типова), `seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`, `seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
|
||||
Моделі: `seedance-1-0-pro-250528` (типова),
|
||||
`seedance-1-0-pro-t2v-250528`, `seedance-1-0-pro-fast-251015`,
|
||||
`seedance-1-0-lite-t2v-250428`, `seedance-1-0-lite-i2v-250428`.
|
||||
|
||||
Моделі T2V (`*-t2v-*`) не приймають входи зображень; моделі I2V і загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`. Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V, коли надається зображення.
|
||||
Моделі T2V (`*-t2v-*`) не приймають вхідні зображення; моделі I2V і
|
||||
загальні моделі `*-pro-*` підтримують одне еталонне зображення (перший
|
||||
кадр). Передайте зображення позиційно або встановіть `role: "first_frame"`.
|
||||
Ідентифікатори моделей T2V автоматично перемикаються на відповідний варіант I2V,
|
||||
коли надається зображення.
|
||||
|
||||
Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean — примусово встановлює 480p), `camera_fixed` (boolean).
|
||||
Підтримувані ключі `providerOptions`: `seed` (number), `draft` (boolean —
|
||||
примусово задає 480p), `camera_fixed` (boolean).
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="BytePlus Seedance 1.5">
|
||||
Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера: `byteplus-seedance15`. Модель: `seedance-1-5-pro-251215`.
|
||||
Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
|
||||
Ідентифікатор провайдера: `byteplus-seedance15`. Модель:
|
||||
`seedance-1-5-pro-251215`.
|
||||
|
||||
Використовує уніфікований API `content[]`. Підтримує щонайбільше 2 вхідні зображення (`first_frame` + `last_frame`). Усі входи мають бути віддаленими URL `https://`. Установіть `role: "first_frame"` / `"last_frame"` для кожного зображення або передайте зображення позиційно.
|
||||
Використовує уніфікований API `content[]`. Підтримує не більше 2 вхідних зображень
|
||||
(`first_frame` + `last_frame`). Усі вхідні дані мають бути віддаленими URL `https://`.
|
||||
Встановіть `role: "first_frame"` / `"last_frame"` для кожного зображення або
|
||||
передайте зображення позиційно.
|
||||
|
||||
`aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) передається далі.
|
||||
`aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення.
|
||||
`audio: true` відображається на `generate_audio`. `providerOptions.seed`
|
||||
(number) передається далі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="BytePlus Seedance 2.0">
|
||||
Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark). Ідентифікатор провайдера: `byteplus-seedance2`. Моделі: `dreamina-seedance-2-0-260128`, `dreamina-seedance-2-0-fast-260128`.
|
||||
Потребує Plugin [`@openclaw/byteplus-modelark`](https://www.npmjs.com/package/@openclaw/byteplus-modelark).
|
||||
Ідентифікатор провайдера: `byteplus-seedance2`. Моделі:
|
||||
`dreamina-seedance-2-0-260128`,
|
||||
`dreamina-seedance-2-0-fast-260128`.
|
||||
|
||||
Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень, 3 еталонних відео та 3 еталонних аудіо. Усі входи мають бути віддаленими URL `https://`. Установіть `role` для кожного ресурсу — підтримувані значення: `"first_frame"`, `"last_frame"`, `"reference_image"`, `"reference_video"`, `"reference_audio"`.
|
||||
Використовує уніфікований API `content[]`. Підтримує до 9 еталонних зображень,
|
||||
3 еталонних відео та 3 еталонних аудіо. Усі вхідні дані мають бути віддаленими
|
||||
URL `https://`. Установіть `role` для кожного ресурсу — підтримувані значення:
|
||||
`"first_frame"`, `"last_frame"`, `"reference_image"`,
|
||||
`"reference_video"`, `"reference_audio"`.
|
||||
|
||||
`aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення. `audio: true` відображається в `generate_audio`. `providerOptions.seed` (number) передається далі.
|
||||
`aspectRatio: "adaptive"` автоматично визначає співвідношення сторін із вхідного зображення.
|
||||
`audio: true` відображається на `generate_audio`. `providerOptions.seed`
|
||||
(number) передається далі.
|
||||
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="ComfyUI">
|
||||
Локальне або хмарне виконання на основі workflow. Підтримує text-to-video та image-to-video через налаштований граф.
|
||||
Виконання локально або в хмарі на основі workflow. Підтримує text-to-video та
|
||||
image-to-video через налаштований граф.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="fal">
|
||||
Використовує потік на основі черги для довготривалих завдань. Більшість моделей відео fal приймають одне еталонне зображення. Моделі Seedance 2.0 reference-to-video приймають до 9 зображень, 3 відео та 3 аудіоеталонів, максимум 12 еталонних файлів загалом.
|
||||
Використовує потік із чергою для довготривалих завдань. Більшість відеомоделей fal
|
||||
приймають одне еталонне зображення. Моделі Seedance 2.0 reference-to-video
|
||||
приймають до 9 зображень, 3 відео та 3 еталонних аудіо, але
|
||||
не більше 12 еталонних файлів загалом.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Google (Gemini / Veo)">
|
||||
Підтримує одне еталонне зображення або одне еталонне відео.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="MiniMax">
|
||||
Лише одне еталонне зображення.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="OpenAI">
|
||||
Передається лише перевизначення `size`. Інші перевизначення стилю (`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з попередженням.
|
||||
Передається далі лише перевизначення `size`. Інші перевизначення стилю
|
||||
(`aspectRatio`, `resolution`, `audio`, `watermark`) ігноруються з
|
||||
попередженням.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Qwen">
|
||||
Той самий бекенд DashScope, що й у Alibaba. Еталонні входи мають бути віддаленими URL `http(s)`; локальні файли одразу відхиляються.
|
||||
Той самий бекенд DashScope, що й у Alibaba. Еталонні вхідні дані мають бути віддаленими
|
||||
URL `http(s)`; локальні файли відхиляються одразу.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Runway">
|
||||
Підтримує локальні файли через URI даних. Для video-to-video потрібен `runway/gen4_aleph`. Запуски лише з текстом надають співвідношення сторін `16:9` і `9:16`.
|
||||
Підтримує локальні файли через data URI. Для video-to-video потрібен
|
||||
`runway/gen4_aleph`. Запуски лише з текстом підтримують співвідношення сторін
|
||||
`16:9` і `9:16`.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Together">
|
||||
Лише одне еталонне зображення.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="Vydra">
|
||||
Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути редиректів, які скидають автентифікацію. `veo3` вбудовано лише для text-to-video; `kling` потребує віддалений URL зображення.
|
||||
Використовує `https://www.vydra.ai/api/v1` безпосередньо, щоб уникнути
|
||||
перенаправлень, які скидають автентифікацію. `veo3` вбудовано лише як text-to-video; `kling` потребує
|
||||
віддаленого URL зображення.
|
||||
</Accordion>
|
||||
|
||||
<Accordion title="xAI">
|
||||
Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7 входів `reference_image` через xAI `reference_images` і віддалені потоки редагування/розширення відео.
|
||||
Підтримує text-to-video, image-to-video з одним зображенням першого кадру, до 7
|
||||
входів `reference_image` через xAI `reference_images`, а також потоки
|
||||
віддаленого редагування/розширення відео.
|
||||
</Accordion>
|
||||
</AccordionGroup>
|
||||
|
||||
## Режими можливостей провайдерів
|
||||
|
||||
Спільний контракт генерації відео тепер дає змогу провайдерам оголошувати
|
||||
можливості для конкретних режимів, а не лише плоскі сукупні обмеження. Нові
|
||||
реалізації провайдерів мають надавати перевагу явним блокам режимів:
|
||||
Спільний контракт генерації відео підтримує можливості, специфічні для режиму,
|
||||
а не лише плоскі агреговані ліміти. Нові реалізації провайдерів
|
||||
мають надавати перевагу явним блокам режимів:
|
||||
|
||||
```typescript
|
||||
capabilities: {
|
||||
@ -368,19 +447,19 @@ capabilities: {
|
||||
}
|
||||
```
|
||||
|
||||
Плоских сукупних полів, таких як `maxInputImages` і `maxInputVideos`, недостатньо,
|
||||
щоб оголосити підтримку режимів перетворення. Провайдери мають явно оголошувати
|
||||
`generate`, `imageToVideo` і `videoToVideo`, щоб live-тести,
|
||||
контрактні тести та спільний інструмент `video_generate` могли детерміновано перевіряти
|
||||
підтримку режимів.
|
||||
Плоских агрегованих полів, таких як `maxInputImages` і `maxInputVideos`,
|
||||
**недостатньо**, щоб оголосити підтримку режимів трансформації. Провайдери повинні
|
||||
явно оголошувати `generate`, `imageToVideo` і `videoToVideo`, щоб live-
|
||||
тести, контрактні тести та спільний інструмент `video_generate` могли
|
||||
детерміновано перевіряти підтримку режимів.
|
||||
|
||||
Коли одна модель провайдера має ширшу підтримку еталонних входів, ніж решта,
|
||||
використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або
|
||||
`maxInputAudiosByModel` замість підвищення загального ліміту для всього режиму.
|
||||
Коли одна модель у провайдера має ширшу підтримку еталонних вхідних даних, ніж
|
||||
решта, використовуйте `maxInputImagesByModel`, `maxInputVideosByModel` або
|
||||
`maxInputAudiosByModel` замість підвищення ліміту для всього режиму.
|
||||
|
||||
## Live-тести
|
||||
|
||||
Покриття зі згодою для спільних вбудованих провайдерів:
|
||||
Opt-in live-покриття для спільних вбудованих провайдерів:
|
||||
|
||||
```bash
|
||||
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.live.test.ts
|
||||
@ -392,35 +471,36 @@ OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/video-generation-providers.liv
|
||||
pnpm test:live:media video
|
||||
```
|
||||
|
||||
Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, типово
|
||||
надає перевагу live/env API-ключам над збереженими профілями автентифікації та запускає
|
||||
безпечний для релізу smoke-тест:
|
||||
Цей live-файл завантажує відсутні змінні середовища провайдерів із `~/.profile`, надає
|
||||
перевагу live/env API-ключам перед збереженими профілями автентифікації за замовчуванням і запускає
|
||||
безпечний для релізу smoke-тест за замовчуванням:
|
||||
|
||||
- `generate` для кожного провайдера у sweep, крім FAL
|
||||
- односекундний запит про лобстера
|
||||
- ліміт операції для кожного провайдера з `OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS`
|
||||
(`180000` типово)
|
||||
- `generate` для кожного провайдера у sweep, крім FAL.
|
||||
- Односекундний запит про лобстера.
|
||||
- Ліміт операції для кожного провайдера з
|
||||
`OPENCLAW_LIVE_VIDEO_GENERATION_TIMEOUT_MS` (`180000` за замовчуванням).
|
||||
|
||||
FAL підключається за згодою, оскільки затримка черги на боці провайдера може домінувати над часом релізу:
|
||||
FAL є opt-in, оскільки затримка черги на боці провайдера може домінувати
|
||||
в часі релізу:
|
||||
|
||||
```bash
|
||||
pnpm test:live:media video --video-providers fal
|
||||
```
|
||||
|
||||
Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені режими перетворення,
|
||||
які спільний sweep може безпечно перевіряти з локальними медіа:
|
||||
Установіть `OPENCLAW_LIVE_VIDEO_GENERATION_FULL_MODES=1`, щоб також запускати оголошені
|
||||
режими трансформації, які спільний sweep може безпечно виконувати з локальними медіафайлами:
|
||||
|
||||
- `imageToVideo`, коли `capabilities.imageToVideo.enabled`
|
||||
- `videoToVideo`, коли `capabilities.videoToVideo.enabled` і провайдер/модель
|
||||
приймає локальне відеовведення на основі буфера у спільному sweep
|
||||
- `imageToVideo`, коли `capabilities.imageToVideo.enabled`.
|
||||
- `videoToVideo`, коли `capabilities.videoToVideo.enabled` і
|
||||
провайдер/модель приймає локальне відео на основі буфера у спільному
|
||||
sweep.
|
||||
|
||||
Наразі спільний live lane `videoToVideo` охоплює:
|
||||
|
||||
- `runway`, лише якщо ви виберете `runway/gen4_aleph`
|
||||
Наразі спільний live-режим `videoToVideo` охоплює лише `runway`, якщо ви
|
||||
вибираєте `runway/gen4_aleph`.
|
||||
|
||||
## Конфігурація
|
||||
|
||||
Установіть типову модель генерації відео у своїй конфігурації OpenClaw:
|
||||
Установіть модель генерації відео за замовчуванням у конфігурації OpenClaw:
|
||||
|
||||
```json5
|
||||
{
|
||||
@ -441,21 +521,21 @@ pnpm test:live:media video --video-providers fal
|
||||
openclaw config set agents.defaults.videoGenerationModel.primary "qwen/wan2.6-t2v"
|
||||
```
|
||||
|
||||
## Пов’язані матеріали
|
||||
## Пов’язане
|
||||
|
||||
- [Огляд інструментів](/uk/tools)
|
||||
- [Фонові завдання](/uk/automation/tasks) -- відстеження завдань для асинхронної генерації відео
|
||||
- [Alibaba Model Studio](/uk/providers/alibaba)
|
||||
- [Фонові завдання](/uk/automation/tasks) — відстеження завдань для асинхронної генерації відео
|
||||
- [BytePlus](/uk/concepts/model-providers#byteplus-international)
|
||||
- [ComfyUI](/uk/providers/comfy)
|
||||
- [Довідник із конфігурації](/uk/gateway/config-agents#agent-defaults)
|
||||
- [fal](/uk/providers/fal)
|
||||
- [Google (Gemini)](/uk/providers/google)
|
||||
- [MiniMax](/uk/providers/minimax)
|
||||
- [Моделі](/uk/concepts/models)
|
||||
- [OpenAI](/uk/providers/openai)
|
||||
- [Qwen](/uk/providers/qwen)
|
||||
- [Runway](/uk/providers/runway)
|
||||
- [Together AI](/uk/providers/together)
|
||||
- [Огляд інструментів](/uk/tools)
|
||||
- [Vydra](/uk/providers/vydra)
|
||||
- [xAI](/uk/providers/xai)
|
||||
- [Configuration Reference](/uk/gateway/config-agents#agent-defaults)
|
||||
- [Моделі](/uk/concepts/models)
|
||||
|
||||
Loading…
Reference in New Issue
Block a user