음악 생성

음악 생성 프롬프트입니다. action: "generate"에 필수입니다.

"status"는 현재 세션 작업을 반환하고, "list"는 제공자를 확인합니다.

제공자/모델 재정의입니다(예: google/lyria-3-pro-preview, comfy/workflow).

제공자가 명시적 가사 입력을 지원할 때 사용할 선택적 가사입니다.

제공자가 지원할 때 인스트루멘털 전용 출력을 요청합니다.

단일 참조 이미지 경로 또는 URL입니다.

여러 참조 이미지입니다(지원하는 제공자에서 최대 10개).

제공자가 길이 힌트를 지원할 때 사용할 목표 길이(초)입니다.

제공자가 지원할 때 사용할 출력 형식 힌트입니다.

제공자 요청 시간 제한은 운영자 구성 전용입니다. 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를 포함한 전체 상태 머신은 백그라운드 작업을 참조하세요. 대부분의 음악 실행은 다음 상태를 거칩니다.

CLI에서 상태를 확인합니다.

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

구성

모델 선택

{  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. 인증 기반 제공자의 기본값만 사용한 자동 감지:
   • 현재 기본 텍스트 모델 제공자가 음악 생성도 제공하는 경우 해당 제공자를 먼저 사용
   • 나머지 등록된 음악 생성 제공자를 제공자 ID의 알파벳순으로 사용

제공자에 실패하면 다음 후보를 자동으로 시도합니다. 모두 실패하면 오류에 각 시도의 세부 정보가 포함됩니다.

명시적 model, primary, fallbacks 항목만 사용하려면 agents.defaults.mediaGenerationAutoProviderFallback: false로 설정합니다.

제공자 참고 사항

적합한 경로 선택

• 모델 선택, 제공자 장애 조치, 기본 제공 비동기 작업/상태 흐름이 필요하면 공유 제공자 기반 경로를 사용합니다.
• 사용자 지정 워크플로 그래프나 공유 번들 음악 기능에 포함되지 않은 제공자가 필요하면 **Plugin 경로(ComfyUI)**를 사용합니다.

ComfyUI 관련 동작을 디버깅하는 경우 ComfyUI를 참조하세요. 공유 제공자 동작을 디버깅하는 경우 fal, Google (Gemini), MiniMax, OpenRouter부터 확인하세요.

제공자 기능 모드

공유 음악 생성 계약은 명시적인 모드 선언을 지원합니다.

• 프롬프트만 사용하는 생성에는 generate를 사용합니다.
• 요청에 하나 이상의 참조 이미지가 포함되면 edit를 사용합니다.

새 제공자 구현에서는 명시적인 모드 블록을 사용하는 것이 좋습니다.

capabilities: {  generate: {    maxTracks: 1,    supportsLyrics: true,    supportsFormat: true,  },  edit: {    enabled: true,    maxTracks: 1,    maxInputImages: 1,    supportsFormat: true,  },}

maxInputImages, supportsLyrics, supportsFormat 같은 기존의 평면 필드만으로는 편집 지원을 알리기에 충분하지 않습니다. 제공자는 실시간 테스트, 계약 테스트, 공유 music_generate 도구가 모드 지원을 결정론적으로 검증할 수 있도록 generate와 edit를 명시적으로 선언해야 합니다.

실시간 테스트

공유 번들 제공자(fal, Google, MiniMax, OpenRouter)의 선택적 실시간 테스트 범위:

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

동일한 테스트 파일을 실행하는 동등한 저장소 래퍼:

pnpm test:live:media:music

이 실시간 테스트 파일은 기본적으로 저장된 인증 프로필보다 이미 내보낸 제공자 환경 변수를 우선 사용하며, 제공자가 편집 모드를 활성화한 경우 generate와 선언된 edit 테스트를 모두 실행합니다. 현재 테스트 범위:

• google: generate 및 edit
• fal: generate만
• minimax: generate만
• openrouter: generate 및 edit
• comfy: 공유 제공자 전체 테스트가 아닌 별도의 Comfy 실시간 테스트 범위

번들 ComfyUI 음악 경로의 선택적 실시간 테스트 범위:

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

Comfy 실시간 테스트 파일은 해당 섹션이 구성된 경우 comfy 이미지 및 비디오 워크플로도 테스트합니다.

관련 항목

• 백그라운드 작업 — 분리 실행된 music_generate의 작업 추적
• ComfyUI
• 구성 참조 — musicGenerationModel 구성
• Google (Gemini)
• MiniMax
• 모델 — 모델 구성 및 장애 조치
• 도구 개요