음악 생성

# 비동기 동작

세션 기반 음악 생성은 백그라운드 작업으로 실행됩니다.

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

# 작업 수명 주기

CLI에서 상태 확인:

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

# 구성

# 모델 선택

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

# 공급자 선택 순서

OpenClaw는 다음 순서로 공급자를 시도합니다.

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

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

명시적 model, primary, fallbacks 항목만 사용하려면 agents.defaults.mediaGenerationAutoProviderFallback: false를 설정하세요.

# 공급자 참고 사항

# 올바른 경로 선택

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

ComfyUI 관련 동작을 디버깅하는 경우 ComfyUI를 참조하세요. 공유 공급자 동작을 디버깅하는 경우 Google (Gemini) 또는 MiniMax에서 시작하세요.

# 공급자 기능 모드

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

• 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를 명시적으로 선언해야 합니다.

# 라이브 테스트

공유 번들 공급자에 대한 선택형 라이브 커버리지:

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

저장소 래퍼:

pnpm test:live:media music

이 라이브 파일은 누락된 공급자 환경 변수를 ~/.profile에서 로드하고, 기본적으로 저장된 인증 프로필보다 라이브/환경 API 키를 우선하며, 공급자가 편집 모드를 활성화한 경우 generate와 선언된 edit 커버리지를 모두 실행합니다. 현재 커버리지:

• google: generate와 edit
• minimax: generate만
• comfy: 공유 provider 스윕이 아닌 별도의 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
• 모델 — 모델 구성 및 장애 조치
• 도구 개요