음악 생성

​

빠른 시작

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

/tool music_generate prompt="Warm ambient synth loop with soft tape texture"

Generate a cinematic piano track with soft strings and no vocals.

Generate an energetic chiptune loop about launching a rocket at sunrise.

​

지원되는 제공자

​

기능 매트릭스

/tool music_generate action=list

/tool music_generate action=status

/tool music_generate prompt="Dreamy lo-fi hip hop with vinyl texture and gentle rain" instrumental=true

​

도구 매개변수

​

비동기 동작

• 백그라운드 작업: music_generate는 백그라운드 작업을 만들고, 시작됨/작업 응답을 즉시 반환한 다음, 나중에 후속 에이전트 메시지로 완성된 트랙을 게시합니다.
• 중복 방지: 작업이 queued 또는 running인 동안 같은 세션에서 이후 music_generate 호출은 또 다른 생성을 시작하는 대신 작업 상태를 반환합니다. 명시적으로 확인하려면 action: "status"를 사용하세요.
• 상태 조회: openclaw tasks list 또는 openclaw tasks show <taskId>는 대기 중, 실행 중, 종료 상태를 살펴봅니다.
• 완료 깨우기: OpenClaw는 내부 완료 이벤트를 같은 세션에 다시 주입하여 모델이 사용자 대상 후속 메시지를 직접 작성할 수 있게 합니다.
• 프롬프트 힌트: 같은 세션의 이후 사용자/수동 턴은 음악 작업이 이미 진행 중일 때 작은 런타임 힌트를 받으므로, 모델이 무작정 music_generate를 다시 호출하지 않습니다.
• 세션 없음 폴백: 실제 에이전트 세션이 없는 직접/로컬 컨텍스트는 인라인으로 실행되고 같은 턴에 최종 오디오 결과를 반환합니다.

​

작업 수명 주기

openclaw tasks list
openclaw 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"],
      },
    },
  },
}

​

제공자 선택 순서

1. 도구 호출의 model 매개변수(에이전트가 지정한 경우).
2. 구성의 musicGenerationModel.primary.
3. 순서대로 musicGenerationModel.fallbacks.
4. 인증 기반 제공자 기본값만 사용한 자동 감지:
   • 현재 기본 제공자를 먼저 사용합니다.
   • 나머지 등록된 음악 생성 제공자를 제공자 ID 순서로 사용합니다.

​

제공자 참고 사항

​

올바른 경로 선택

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

​

Provider 기능 모드

• 프롬프트만 사용하는 생성을 위한 generate.
• 요청에 하나 이상의 참조 이미지가 포함될 때의 edit.

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

​

Live 테스트

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

pnpm test:live:media music

• google: generate 및 edit
• fal: generate만
• minimax: generate만
• openrouter: generate 및 edit
• comfy: 공유 provider 스윕이 아닌 별도의 Comfy live 범위

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

​

관련 항목

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