Tools

Генерування музики

Інструмент music_generate дає агенту змогу створювати музику або аудіо через спільну можливість генерації музики з налаштованими провайдерами — наразі це Google, MiniMax і ComfyUI, налаштований через робочі процеси.

Для запусків агента з підтримкою сеансу OpenClaw запускає генерацію музики як фонове завдання, відстежує її в журналі завдань, а потім знову пробуджує агента, коли трек готовий, щоб агент міг повідомити користувача й прикріпити готове аудіо. У групових/канальних чатах, де видима доставка відбувається лише через інструмент повідомлень, агент передає результат через інструмент повідомлень. Якщо агент під час завершення пише лише приватну фінальну відповідь, OpenClaw резервно надсилає згенеровані медіа напряму в канал. Пробудження після завершення явно попереджає агента, що звичайні фінальні відповіді в цих маршрутах є приватними.

Швидкий старт

Спільний із підтримкою провайдерів

Налаштуйте автентифікацію

Задайте ключ API принаймні для одного провайдера — наприклад GEMINI_API_KEY або MINIMAX_API_KEY.

Виберіть стандартну модель (необов’язково)

json5

{  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",      },    },  },}

Попросіть агента

"Згенеруй життєрадісний синті-поп-трек про нічну поїздку крізь неонове місто."

Агент автоматично викликає music_generate. Дозволяти інструмент окремим списком не потрібно.

Для прямих синхронних контекстів без запуску агента з підтримкою сеансу вбудований інструмент усе одно резервно переходить до вбудованої генерації й повертає фінальний шлях до медіафайлу в результаті інструмента.

Робочий процес ComfyUI

Налаштуйте робочий процес

Налаштуйте 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

Параметри інструмента

promptstringrequired

Промпт для генерації музики. Обов’язковий для action: "generate".

action"generate" | "status" | "list"default: generate

"status" повертає поточне сеансове завдання; "list" переглядає провайдерів.

modelstring

Перевизначення провайдера/моделі (наприклад google/lyria-3-pro-preview, comfy/workflow).

lyricsstring

Необов’язковий текст пісні, коли провайдер підтримує явне введення тексту пісні.

instrumentalboolean

Запит на лише інструментальний результат, коли провайдер це підтримує.

imagestring

Шлях або URL одного референсного зображення.

imagesstring[]

Кілька референсних зображень (до 10 у провайдерів, які це підтримують).

durationSecondsnumber

Цільова тривалість у секундах, коли провайдер підтримує підказки тривалості.

format"mp3" | "wav"

Підказка формату виводу, коли провайдер це підтримує.

filenamestring

OPENCLAW_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg Необов’язковий тайм-аут запиту до провайдера в мілісекундах. Якщо його пропущено, OpenClaw використовує agents.defaults.musicGenerationModel.timeoutMs, якщо це налаштовано. Значення нижче 10000ms підвищуються до 10000ms і повідомляються в результаті інструмента. OPENCLAW_DOCS_MARKER:paramClose:

Note

Не всі провайдери підтримують усі параметри. OpenClaw однаково перевіряє жорсткі обмеження, як-от кількість вхідних даних, перед надсиланням. Коли провайдер підтримує тривалість, але має коротший максимум, ніж запитане значення, OpenClaw обмежує його до найближчої підтримуваної тривалості. Справді непідтримувані необов’язкові підказки ігноруються з попередженням, коли вибраний провайдер або модель не може їх виконати. Результати інструмента повідомляють застосовані налаштування; details.normalization фіксує будь-яке відображення запитаних значень у застосовані.

Асинхронна поведінка

Генерація музики з підтримкою сеансу виконується як фонове завдання:

Фонове завдання: music_generate створює фонове завдання, негайно повертає відповідь про запуск/завдання, а пізніше публікує готовий трек у подальшому повідомленні агента.
Запобігання дублюванню: доки завдання має стан queued або running, подальші виклики music_generate у тому самому сеансі повертають статус завдання замість запуску ще однієї генерації. Використовуйте action: "status" для явної перевірки.
Перегляд статусу: openclaw tasks list або openclaw tasks show <taskId> переглядає статуси в черзі, виконання та кінцеві статуси.
Пробудження після завершення: OpenClaw впроваджує внутрішню подію завершення назад у той самий сеанс, щоб модель могла сама написати видиме користувачу подальше повідомлення.
Підказка промпта: наступні користувацькі/ручні ходи в тому самому сеансі отримують невелику runtime-підказку, коли завдання генерації музики вже виконується, щоб модель не викликала music_generate наосліп знову.
Резервний шлях без сеансу: прямі/локальні контексти без справжнього сеансу агента виконуються вбудовано й повертають фінальний аудіорезультат у тому ж ході.

Життєвий цикл завдання

Стан	Значення
`queued`	Завдання створено, очікує, доки провайдер його прийме.
`running`	Провайдер обробляє запит (зазвичай від 30 секунд до 3 хвилин залежно від провайдера й тривалості).
`succeeded`	Трек готовий; агент пробуджується й публікує його в розмові.
`failed`	Помилка провайдера або тайм-аут; агент пробуджується з деталями помилки.

Перевірте статус із CLI:

bash

openclaw tasks listopenclaw tasks show <taskId>openclaw tasks cancel <taskId>

Конфігурація

Вибір моделі

json5

{  agents: {    defaults: {      musicGenerationModel: {        primary: "google/lyria-3-clip-preview",        fallbacks: ["minimax/music-2.6"],      },    },  },}

Порядок вибору провайдера

OpenClaw пробує провайдерів у такому порядку:

Параметр model з виклику інструмента (якщо агент його вказує).
musicGenerationModel.primary з конфігурації.
musicGenerationModel.fallbacks за порядком.
Автовиявлення лише за стандартними провайдерами з налаштованою автентифікацією:
- спочатку поточний стандартний провайдер;
- решта зареєстрованих провайдерів генерації музики в порядку ідентифікаторів провайдерів.

Якщо провайдер завершується помилкою, автоматично пробується наступний кандидат. Якщо помиляються всі, помилка містить деталі кожної спроби.

Задайте agents.defaults.mediaGenerationAutoProviderFallback: false, щоб використовувати лише явні записи model, primary і fallbacks.

Примітки щодо провайдерів

ComfyUI

Керується робочим процесом і залежить від налаштованого графа та зіставлення вузлів для полів промпта/виводу. Вбудований plugin comfy під’єднується до спільного інструмента music_generate через реєстр провайдерів генерації музики.

Google (Lyria 3)

Використовує пакетну генерацію Lyria 3. Поточний вбудований потік підтримує промпт, необов’язковий текст пісні та необов’язкові референсні зображення.

MiniMax

Використовує пакетну кінцеву точку music_generation. Підтримує промпт, необов’язковий текст пісні, інструментальний режим, керування тривалістю та вивід mp3 через автентифікацію minimax за ключем API або OAuth minimax-portal.

Вибір правильного шляху

Спільний із підтримкою провайдерів, коли потрібні вибір моделі, резервне перемикання провайдерів і вбудований асинхронний потік завдань/статусу.
Шлях Plugin (ComfyUI), коли потрібен власний граф робочого процесу або провайдер, який не є частиною спільної вбудованої можливості генерації музики.

Якщо ви налагоджуєте поведінку, специфічну для ComfyUI, див. ComfyUI. Якщо ви налагоджуєте поведінку спільного провайдера, почніть із Google (Gemini) або 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 для зображень і відео, коли ці розділи налаштовано.

Пов’язане

Фонові завдання — відстеження завдань для від’єднаних запусків music_generate
ComfyUI
Довідник конфігурації — конфігурація musicGenerationModel
Google (Gemini)
MiniMax
Моделі — конфігурація моделей і аварійне перемикання
Огляд інструментів

Was this useful?