OpenClawDocs
View as MarkdownView this page as plain textOpen in ChatGPTAsk questions about this pageOpen in ClaudeAsk questions about this page

Tools

Генерация музыки

Инструмент music_generate создаёт музыку или аудио с помощью общей возможности генерации музыки на базе ComfyUI, fal, Google, MiniMax и OpenRouter.

При запусках агента с поддержкой сеанса music_generate запускается как фоновая задача, отслеживает ход выполнения в журнале задач, а затем пробуждает агента, когда трек готов, чтобы тот мог сообщить пользователю и прикрепить готовое аудио. Агент завершения следует контракту видимого ответа сеанса: автоматически отправляет итоговый ответ, если это настроено, либо использует message(action="send"), когда сеанс требует применения инструмента сообщений. Если сеанс инициатора неактивен или его не удаётся пробудить, а созданное аудио по-прежнему отсутствует в ответе, 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="Тёплый эмбиентный синтезаторный цикл с мягкой плёночной текстурой"

    • Примеры запросов:

    text
    Создай кинематографичный фортепианный трек с мягкими струнными без вокала.
    text
    Создай энергичный чиптюн-цикл о запуске ракеты на рассвете.

    Используйте action: "list" для просмотра доступных провайдеров и моделей, а action: "status" — для просмотра активной музыкальной задачи с поддержкой сеанса:

    text
    /tool music_generate action=list/tool music_generate action=status

    Пример прямой генерации:

    text
    /tool music_generate prompt="Мечтательный lo-fi-хип-хоп с виниловой текстурой и лёгким дождём" instrumental=true

    Поддерживаемые провайдеры

    Провайдер Модель по умолчанию Входные референсы Поддерживаемые параметры Аутентификация
    ComfyUI workflow До 1 изображения Музыка или аудио, определяемые рабочим процессом COMFY_API_KEY, COMFY_CLOUD_API_KEY
    fal fal-ai/minimax-music/v2.6 Нет lyrics, instrumental, durationSeconds, format FAL_KEY или FAL_API_KEY
    Google lyria-3-clip-preview До 10 изображений lyrics, instrumental, format GEMINI_API_KEY, GOOGLE_API_KEY
    MiniMax music-2.6 Нет lyrics, instrumental, format (только mp3) MINIMAX_API_KEY или MiniMax OAuth
    OpenRouter google/lyria-3-pro-preview До 1 изображения lyrics, instrumental, durationSeconds, format OPENROUTER_API_KEY

    MiniMax регистрирует два идентификатора провайдера с общими моделями: minimax для аутентификации по ключу API и minimax-portal для OAuth. Ссылки на модели соответствуют способу аутентификации (minimax/music-2.6 и minimax-portal/music-2.6 соответственно); см. MiniMax.

    Помимо модели по умолчанию на базе MiniMax, fal также предоставляет fal-ai/ace-step/prompt-to-audio (wav, без текста песни и без переключателя инструментального режима) и fal-ai/stable-audio-25/text-to-audio (wav, только запрос). Модель Google по умолчанию lyria-3-clip-preview выводит только mp3; lyria-3-pro-preview также поддерживает wav. MiniMax также предоставляет music-2.6-free, music-cover и music-cover-free. OpenRouter также предоставляет google/lyria-3-clip-preview.

    Матрица возможностей

    Явный контракт режимов, используемый music_generate, контрактными тестами и общей проверкой в реальной среде:

    Провайдер generate edit Ограничение редактирования Общие проверки в реальной среде
    ComfyUI ✓ ✓ 1 изображение Не входит в общую проверку; охватывается extensions/comfy/comfy.live.test.ts
    fal ✓ — Нет generate
    Google ✓ ✓ 10 изображений generate, edit
    MiniMax ✓ — Нет generate
    OpenRouter ✓ ✓ 1 изображение generate, edit

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

    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 использует agents.defaults.musicGenerationModel.timeoutMs, если он настроен, повышает значения ниже 120000ms до 120000ms, а в остальных случаях устанавливает для запросов к провайдеру тайм-аут по умолчанию 300000ms.

    Асинхронное поведение

    Генерация музыки с поддержкой сеанса выполняется как фоновая задача:

    • Фоновая задача: music_generate создаёт фоновую задачу, немедленно возвращает ответ о запуске и задаче, а позднее публикует готовый трек в последующем сообщении агента.
    • Предотвращение дубликатов: пока задача находится в состоянии queued или running, последующие вызовы music_generate в том же сеансе возвращают состояние задачи вместо запуска новой генерации. Для явной проверки используйте action: "status". Недавно завершённый совпадающий запрос также дедуплицируется в течение 2 минут.
    • Проверка состояния: openclaw tasks list или openclaw tasks show <taskId> показывает состояние в очереди, выполнения и завершения.
    • Пробуждение после завершения: OpenClaw внедряет внутреннее событие завершения обратно в тот же сеанс, чтобы модель могла самостоятельно написать последующий ответ пользователю.
    • Подсказка в запросе: последующие пользовательские или ручные обращения в том же сеансе получают небольшую подсказку среды выполнения, если музыкальная задача уже выполняется, чтобы модель не вызывала music_generate повторно вслепую.
    • Резервный вариант без сеанса: прямые или локальные контексты без настоящего сеанса агента выполняются синхронно и возвращают итоговое аудио в том же обращении.

    Жизненный цикл задачи

    Музыкальная задача использует те же состояния, что и общий реестр задач (полную схему состояний, включая timed_out, cancelled и lost, см. в разделе Фоновые задачи). Большинство музыкальных задач проходит следующие состояния:

    Состояние Значение
    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: ["fal/fal-ai/minimax-music/v2.6", "minimax/music-2.6"],      },    },  },}

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

    OpenClaw пробует провайдеров в следующем порядке:

    1. Параметр model из вызова инструмента (если агент его указал).
    2. musicGenerationModel.primary из конфигурации.
    3. musicGenerationModel.fallbacks по порядку.
    4. Автоматическое обнаружение только по значениям провайдеров по умолчанию с настроенной аутентификацией:
      • сначала текущий провайдер текстовой модели по умолчанию, если он также предоставляет генерацию музыки;
      • затем остальные зарегистрированные провайдеры генерации музыки в алфавитном порядке по идентификатору провайдера.

    Если провайдер завершается с ошибкой, следующий кандидат пробуется автоматически. Если все попытки завершаются неудачно, ошибка содержит подробности каждой из них.

    Задайте agents.defaults.mediaGenerationAutoProviderFallback: false, чтобы использовать только явные записи model, primary и fallbacks.

    Примечания о провайдерах

    ComfyUI

    Управляется рабочим процессом и зависит от настроенного графа и сопоставления узлов с полями промпта и вывода. Встроенный плагин comfy подключается к общему инструменту music_generate через реестр провайдеров генерации музыки.

    fal

    Использует конечные точки моделей fal через общий механизм аутентификации провайдеров. Встроенный провайдер по умолчанию использует fal-ai/minimax-music/v2.6, а также предоставляет fal-ai/ace-step/prompt-to-audio и fal-ai/stable-audio-25/text-to-audio для запросов преобразования промпта в аудио. Тексты песен и инструментальный режим поддерживаются только моделью MiniMax; две другие модели работают только с промптами.

    Google (Lyria 3)

    Использует пакетную генерацию Lyria 3. Текущий встроенный процесс поддерживает промпт, необязательный текст песни и необязательные эталонные изображения. Модель lyria-3-clip-preview, используемая по умолчанию, выводит только mp3; модель lyria-3-pro-preview также поддерживает wav.

    MiniMax

    Использует пакетную конечную точку music_generation. Поддерживает промпт, необязательный текст песни, инструментальный режим и вывод mp3 с аутентификацией либо по API-ключу minimax, либо через OAuth minimax-portal. Также предоставляет модели music-2.6-free, music-cover и music-cover-free.

    OpenRouter

    Использует аудиовывод завершений чата OpenRouter с включённой потоковой передачей. Встроенный провайдер по умолчанию использует google/lyria-3-pro-preview, а также предоставляет openrouter/google/lyria-3-clip-preview.

    Выбор подходящего пути

    • На основе общего провайдера — если вам нужны выбор модели, переключение на резервного провайдера и встроенный асинхронный процесс задач и статусов.
    • Путь плагина (ComfyUI) — если вам нужен пользовательский граф рабочего процесса или провайдер, который не входит в общую встроенную возможность генерации музыки.

    Если вы отлаживаете поведение, специфичное для ComfyUI, см. ComfyUI. Если вы отлаживаете поведение общего провайдера, начните с fal, Google (Gemini), MiniMax или OpenRouter.

    Режимы возможностей провайдеров

    Общий контракт генерации музыки поддерживает явные объявления режимов:

    • 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, чтобы тесты в реальной среде, контрактные тесты и общий инструмент music_generate могли детерминированно проверять поддержку режимов.

    Тесты в реальной среде

    Опциональное тестирование в реальной среде для общих встроенных провайдеров (fal, Google, MiniMax, OpenRouter):

    bash
    OPENCLAW_LIVE_TEST=1 pnpm test:live -- extensions/music-generation-providers.live.test.ts

    Эквивалентная обёртка репозитория, запускающая тот же тестовый файл:

    bash
    pnpm test:live:media:music

    Этот файл тестов в реальной среде по умолчанию использует уже экспортированные переменные окружения провайдера раньше сохранённых профилей аутентификации и выполняет тестирование как generate, так и объявленного edit, когда провайдер включает режим редактирования. Текущее покрытие:

    • google: generate и edit
    • fal: только generate
    • minimax: только generate
    • openrouter: generate и edit
    • comfy: отдельное тестирование Comfy в реальной среде, не входящее в общую проверку провайдеров

    Опциональное тестирование в реальной среде для встроенного пути генерации музыки ComfyUI:

    bash
    OPENCLAW_LIVE_TEST=1 COMFY_LIVE_TEST=1 pnpm test:live -- extensions/comfy/comfy.live.test.ts

    Файл тестов Comfy в реальной среде также охватывает рабочие процессы с изображениями и видео, если соответствующие разделы настроены.

    Связанные материалы

    Was this useful?
    On this page

    On this page