---
read_when:
- Генерація музики або аудіо за допомогою агента
- Налаштування провайдерів і моделей генерації музики
- Розуміння параметрів інструмента music_generate
sidebarTitle: Music generation
summary: Генеруйте музику за допомогою music_generate у робочих процесах Google Lyria, MiniMax і ComfyUI
title: Генерування музики
x-i18n:
generated_at: "2026-05-11T21:01:50Z"
model: gpt-5.5
provider: openai
source_hash: b355dd6f1f41074624b692edb8a597a65ad99fc3ad61d2ed5e32f1b6cf393244
source_path: tools/music-generation.md
workflow: 16
---
Інструмент `music_generate` дає агенту змогу створювати музику або аудіо через
спільну можливість генерації музики з налаштованими провайдерами — наразі це
Google, MiniMax і ComfyUI, налаштований через робочі процеси.
Для запусків агента з підтримкою сеансу OpenClaw запускає генерацію музики як
фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента,
коли трек готовий, щоб агент міг повідомити користувача й прикріпити готове
аудіо. У групових/канальних чатах, де видима доставка відбувається лише через
інструмент повідомлень, агент передає результат через інструмент повідомлень. Якщо
агент під час завершення пише лише приватну фінальну відповідь, OpenClaw
резервно надсилає згенеровані медіа напряму в канал. Пробудження після
завершення явно попереджає агента, що звичайні фінальні відповіді в цих маршрутах
є приватними.
Вбудований спільний інструмент з’являється лише тоді, коли доступний принаймні
один провайдер генерації музики. Якщо ви не бачите `music_generate` серед
інструментів агента, налаштуйте `agents.defaults.musicGenerationModel` або
додайте ключ API провайдера.
## Швидкий старт
Задайте ключ API принаймні для одного провайдера — наприклад
`GEMINI_API_KEY` або `MINIMAX_API_KEY`.
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
},
},
},
}
```
_"Згенеруй життєрадісний синті-поп-трек про нічну поїздку крізь
неонове місто."_
Агент автоматично викликає `music_generate`. Дозволяти інструмент
окремим списком не потрібно.
Для прямих синхронних контекстів без запуску агента з підтримкою сеансу
вбудований інструмент усе одно резервно переходить до вбудованої генерації
й повертає фінальний шлях до медіафайлу в результаті інструмента.
Налаштуйте `plugins.entries.comfy.config.music` із JSON робочого
процесу та вузлами промпта/виводу.
Для Comfy Cloud задайте `COMFY_API_KEY` або `COMFY_CLOUD_API_KEY`.
```text
/tool music_generate prompt="Warm ambient synth loop with soft tape texture"
```
Приклади промптів:
```text
Generate a cinematic piano track with soft strings and no vocals.
```
```text
Generate an energetic chiptune loop about launching a rocket at sunrise.
```
## Підтримувані провайдери
| Провайдер | Стандартна модель | Референсні вхідні дані | Підтримувані параметри керування | Автентифікація |
| -------- | ---------------------- | ---------------------- | --------------------------------------------------------- | -------------------------------------- |
| 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-перевірка:
| Провайдер | `generate` | `edit` | Ліміт редагування | Спільні live-напрями |
| -------- | :--------: | :----: | ----------------- | ----------------------------------------------------------------------- |
| ComfyUI | ✓ | ✓ | 1 зображення | Не входить до спільної перевірки; покрито `extensions/comfy/comfy.live.test.ts` |
| Google | ✓ | ✓ | 10 зображень | `generate`, `edit` |
| MiniMax | ✓ | — | Немає | `generate` |
Використовуйте `action: "list"`, щоб переглянути доступних спільних провайдерів
і моделі під час виконання:
```text
/tool music_generate action=list
```
Використовуйте `action: "status"`, щоб переглянути активне сеансове завдання
генерації музики:
```text
/tool music_generate action=status
```
Приклад прямої генерації:
```text
/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true
```
## Параметри інструмента
Промпт для генерації музики. Обов’язковий для `action: "generate"`.
`"status"` повертає поточне сеансове завдання; `"list"` переглядає провайдерів.
Перевизначення провайдера/моделі (наприклад `google/lyria-3-pro-preview`,
`comfy/workflow`).
Необов’язковий текст пісні, коли провайдер підтримує явне введення тексту пісні.
Запит на лише інструментальний результат, коли провайдер це підтримує.
Шлях або URL одного референсного зображення.
Кілька референсних зображень (до 10 у провайдерів, які це підтримують).
Цільова тривалість у секундах, коли провайдер підтримує підказки тривалості.
Підказка формату виводу, коли провайдер це підтримує.
Підказка щодо імені вихідного файлу.
Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Якщо його пропущено, OpenClaw використовує `agents.defaults.musicGenerationModel.timeoutMs`, якщо це налаштовано. Значення нижче 10000ms підвищуються до 10000ms і повідомляються в результаті інструмента.
Не всі провайдери підтримують усі параметри. OpenClaw однаково перевіряє жорсткі
обмеження, як-от кількість вхідних даних, перед надсиланням. Коли провайдер
підтримує тривалість, але має коротший максимум, ніж запитане значення, OpenClaw
обмежує його до найближчої підтримуваної тривалості. Справді непідтримувані
необов’язкові підказки ігноруються з попередженням, коли вибраний провайдер або
модель не може їх виконати. Результати інструмента повідомляють застосовані
налаштування; `details.normalization` фіксує будь-яке відображення запитаних
значень у застосовані.
## Асинхронна поведінка
Генерація музики з підтримкою сеансу виконується як фонове завдання:
- **Фонове завдання:** `music_generate` створює фонове завдання, негайно
повертає відповідь про запуск/завдання, а пізніше публікує готовий трек у
подальшому повідомленні агента.
- **Запобігання дублюванню:** доки завдання має стан `queued` або `running`,
подальші виклики `music_generate` у тому самому сеансі повертають статус
завдання замість запуску ще однієї генерації. Використовуйте `action: "status"`
для явної перевірки.
- **Перегляд статусу:** `openclaw tasks list` або `openclaw tasks show `
переглядає статуси в черзі, виконання та кінцеві статуси.
- **Пробудження після завершення:** OpenClaw впроваджує внутрішню подію
завершення назад у той самий сеанс, щоб модель могла сама написати видиме
користувачу подальше повідомлення.
- **Підказка промпта:** наступні користувацькі/ручні ходи в тому самому сеансі
отримують невелику runtime-підказку, коли завдання генерації музики вже
виконується, щоб модель не викликала `music_generate` наосліп знову.
- **Резервний шлях без сеансу:** прямі/локальні контексти без справжнього сеансу
агента виконуються вбудовано й повертають фінальний аудіорезультат у тому ж
ході.
### Життєвий цикл завдання
| Стан | Значення |
| ----------- | ------------------------------------------------------------------------------------------------ |
| `queued` | Завдання створено, очікує, доки провайдер його прийме. |
| `running` | Провайдер обробляє запит (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості). |
| `succeeded` | Трек готовий; агент пробуджується й публікує його в розмові. |
| `failed` | Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки. |
Перевірте статус із CLI:
```bash
openclaw tasks list
openclaw tasks show
openclaw tasks cancel
```
## Конфігурація
### Вибір моделі
```json5
{
agents: {
defaults: {
musicGenerationModel: {
primary: "google/lyria-3-clip-preview",
fallbacks: ["minimax/music-2.6"],
},
},
},
}
```
### Порядок вибору провайдера
OpenClaw пробує провайдерів у такому порядку:
1. Параметр `model` з виклику інструмента (якщо агент його вказує).
2. `musicGenerationModel.primary` з конфігурації.
3. `musicGenerationModel.fallbacks` за порядком.
4. Автовиявлення лише за стандартними провайдерами з налаштованою автентифікацією:
- спочатку поточний стандартний провайдер;
- решта зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів.
Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат.
Якщо помиляються всі, помилка містить деталі кожної спроби.
Задайте `agents.defaults.mediaGenerationAutoProviderFallback: false`, щоб
використовувати лише явні записи `model`, `primary` і `fallbacks`.
## Примітки щодо провайдерів
Керується робочим процесом і залежить від налаштованого графа та
зіставлення вузлів для полів промпта/виводу. Вбудований plugin `comfy`
під’єднується до спільного інструмента `music_generate` через реєстр
провайдерів генерації музики.
Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує
промпт, необов’язковий текст пісні та необов’язкові референсні зображення.
Використовує пакетну кінцеву точку `music_generation`. Підтримує промпт,
необов’язковий текст пісні, інструментальний режим, керування тривалістю та
вивід mp3 через автентифікацію `minimax` за ключем API або OAuth
`minimax-portal`.
## Вибір правильного шляху
- **Спільний із підтримкою провайдерів**, коли потрібні вибір моделі, резервне
перемикання провайдерів і вбудований асинхронний потік завдань/статусу.
- **Шлях Plugin (ComfyUI)**, коли потрібен власний граф робочого процесу або
провайдер, який не є частиною спільної вбудованої можливості генерації музики.
Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див.
[ComfyUI](/uk/providers/comfy). Якщо ви налагоджуєте поведінку спільного
провайдера, почніть із [Google (Gemini)](/uk/providers/google) або
[MiniMax](/uk/providers/minimax).
## Режими можливостей провайдера
Спільний контракт генерації музики підтримує явні оголошення режимів:
- `generate` для генерації лише за промптом.
- `edit`, коли запит містить одне або кілька референсних зображень.
Нові реалізації провайдерів мають віддавати перевагу явним блокам режимів:
```typescript
capabilities: {
generate: {
maxTracks: 1,
supportsLyrics: true,
supportsFormat: true,
},
edit: {
enabled: true,
maxTracks: 1,
maxInputImages: 1,
supportsFormat: true,
},
}
```
Застарілих пласких полів, як-от `maxInputImages`, `supportsLyrics` і
`supportsFormat`, **недостатньо**, щоб заявити підтримку редагування.
Провайдери мають явно оголошувати `generate` і `edit`, щоб live-тести,
контрактні тести та спільний інструмент `music_generate` могли
детерміновано перевіряти підтримку режимів.
## Live-тести
Live-покриття для спільних вбудованих провайдерів, яке вмикається явно:
```bash
OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts
```
Обгортка репозиторію:
```bash
pnpm test:live:media music
```
Цей live-файл завантажує відсутні змінні середовища провайдера з `~/.profile`, за замовчуванням надає перевагу live/env API-ключам перед збереженими профілями автентифікації та запускає покриття і для `generate`, і для оголошеного `edit`, коли провайдер вмикає режим редагування. Поточне покриття:
- `google`: `generate` плюс `edit`
- `minimax`: лише `generate`
- `comfy`: окреме live-покриття Comfy, не спільний обхід провайдерів
Увімкнення live-покриття для вбудованого музичного шляху ComfyUI:
```bash
OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts
```
Live-файл Comfy також покриває робочі процеси comfy для зображень і відео, коли ці розділи налаштовано.
## Пов’язане
- [Фонові завдання](/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/tools)