​

음악 생성

​

빠른 시작

​

공유 provider 기반 생성

1. 예를 들어 GEMINI_API_KEY 또는 MINIMAX_API_KEY처럼 최소 하나의 provider에 대한 API 키를 설정합니다.
2. 필요하면 선호하는 모델을 설정합니다:

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

3. agent에게 요청합니다: “네온 도시를 가로지르는 야간 드라이브에 대한 경쾌한 신스팝 트랙을 생성해 줘.”

보컬 없이 부드러운 스트링이 들어간 영화 같은 피아노 트랙을 생성해 줘.

일출에 로켓을 발사하는 내용을 담은 에너지 넘치는 칩튠 루프를 생성해 줘.

​

워크플로 기반 Comfy 생성

1. 워크플로 JSON 및 프롬프트/출력 노드로 models.providers.comfy.music를 구성합니다.
2. Comfy Cloud를 사용한다면 COMFY_API_KEY 또는 COMFY_CLOUD_API_KEY를 설정합니다.
3. agent에게 음악 생성을 요청하거나 tool을 직접 호출합니다.

/tool music_generate prompt="따뜻한 앰비언트 신스 루프와 부드러운 테이프 질감"

​

공유 번들 provider 지원

​

선언된 기능 매트릭스

/tool music_generate action=list

/tool music_generate action=status

/tool music_generate prompt="비닐 질감과 부드러운 빗소리가 들어간 몽환적인 lo-fi hip hop" instrumental=true

​

기본 제공 tool 파라미터

​

공유 provider 기반 경로의 비동기 동작

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

​

Task 수명 주기

1. queued — task가 생성되었고 provider가 수락하기를 기다리는 중입니다.
2. running — provider가 처리 중입니다(일반적으로 provider와 길이에 따라 30초에서 3분).
3. succeeded — 트랙이 준비되었고, agent가 깨어나 대화에 게시합니다.
4. failed — provider 오류 또는 시간 초과이며, agent가 오류 세부 정보와 함께 깨어납니다.

openclaw tasks list
openclaw tasks show <taskId>
openclaw tasks cancel <taskId>

​

구성

​

모델 선택

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

​

Provider 선택 순서

1. agent가 지정한 경우 tool 호출의 model 파라미터
2. config의 musicGenerationModel.primary
3. 순서대로 musicGenerationModel.fallbacks
4. 인증 기반 provider 기본값만 사용한 자동 감지:
   • 현재 기본 provider 먼저
   • 남은 등록된 음악 생성 provider를 provider-id 순서로

​

Provider 참고 사항

• Google은 Lyria 3 배치 생성을 사용합니다. 현재 번들 흐름은 프롬프트, 선택적 가사 텍스트, 선택적 참조 이미지를 지원합니다.
• MiniMax는 배치 music_generation 엔드포인트를 사용합니다. 현재 번들 흐름은 프롬프트, 선택적 가사, 기악 모드, 길이 조정, mp3 출력을 지원합니다.
• ComfyUI 지원은 워크플로 기반이며, 구성된 그래프와 프롬프트/출력 필드용 노드 매핑에 따라 달라집니다.

​

Provider 기능 모드

• 프롬프트만으로 생성하는 generate
• 요청에 하나 이상의 참조 이미지가 포함될 때의 edit

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

​

올바른 경로 선택

• 모델 선택, provider 페일오버, 기본 제공 비동기 task/status 흐름이 필요하면 공유 provider 기반 경로를 사용하세요.
• 사용자 지정 워크플로 그래프가 필요하거나 공유 번들 음악 기능에 포함되지 않은 provider가 필요하면 ComfyUI 같은 plugin 경로를 사용하세요.
• ComfyUI 전용 동작을 디버깅하는 경우 ComfyUI를 참고하세요. 공유 provider 동작을 디버깅하는 경우 Google (Gemini) 또는 MiniMax부터 시작하세요.

​

라이브 테스트

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

pnpm test:live:media music

• google: generate와 edit
• minimax: generate만
• comfy: 공유 provider sweep이 아닌 별도의 Comfy 라이브 커버리지

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

​

관련 문서

• Background Tasks - 분리된 music_generate 실행을 위한 task 추적
• Configuration Reference - musicGenerationModel config
• ComfyUI
• Google (Gemini)
• MiniMax
• Models - 모델 구성 및 페일오버
• Tools Overview