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.

برای اجراهای عامل مبتنی بر نشست، OpenClaw تولید موسیقی را به‌عنوان یک وظیفه پس‌زمینه آغاز می‌کند، آن را در دفتر وظایف پیگیری می‌کند، سپس وقتی قطعه آماده شد دوباره عامل را بیدار می‌کند تا عامل بتواند به کاربر اطلاع دهد و صدای نهایی را پیوست کند. عامل تکمیل از حالت معمول پاسخ مرئی نشست پیروی می‌کند: تحویل خودکار پاسخ نهایی وقتی پیکربندی شده باشد، یا message(action="send") وقتی نشست به ابزار پیام نیاز دارد. اگر نشست درخواست‌کننده غیرفعال باشد یا بیدارسازی فعال آن شکست بخورد، و هنوز بخشی از صدای تولیدشده در پاسخ تکمیل وجود نداشته باشد، OpenClaw یک جایگزین مستقیم و idempotent را فقط با صدای گمشده ارسال می‌کند.

شروع سریع

Shared provider-backed

  • Configure auth

    برای حداقل یک ارائه‌دهنده یک کلید API تنظیم کنید — برای مثال GEMINI_API_KEY یا MINIMAX_API_KEY.

  • Pick a default model (optional)

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

  • Ask the agent

    "Generate an upbeat synthpop track about a night drive through a neon city."

    عامل به‌صورت خودکار music_generate را فراخوانی می‌کند. نیازی به فهرست مجاز ابزار نیست.

    • برای زمینه‌های مستقیم همگام بدون اجرای عامل مبتنی بر نشست، ابزار داخلی همچنان به تولید درون‌خطی بازمی‌گردد و مسیر رسانه نهایی را در نتیجه ابزار برمی‌گرداند.

    ComfyUI workflow

  • Configure the workflow

    plugins.entries.comfy.config.music را با JSON گردش‌کار و گره‌های پرامپت/خروجی پیکربندی کنید.

  • Cloud auth (optional)

    برای Comfy Cloud، COMFY_API_KEY یا COMFY_CLOUD_API_KEY را تنظیم کنید.

  • Call the tool

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

    • نمونه پرامپت‌ها:

    text
    Generate a cinematic piano track with soft strings and no vocals.
    text
    Generate an energetic chiptune loop about launching a rocket at sunrise.

    ارائه‌دهندگان پشتیبانی‌شده

    ارائه‌دهنده مدل پیش‌فرض ورودی‌های مرجع کنترل‌های پشتیبانی‌شده احراز هویت
    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

    ماتریس قابلیت‌ها

    قرارداد حالت صریح که توسط music_generate، آزمون‌های قرارداد، و جاروب زنده مشترک استفاده می‌شود:

    ارائه‌دهنده generate edit حد ویرایش مسیرهای زنده مشترک
    ComfyUI ✓ ✓ 1 تصویر در جاروب مشترک نیست؛ توسط extensions/comfy/comfy.live.test.ts پوشش داده می‌شود
    fal ✓ — هیچ‌کدام generate
    Google ✓ ✓ 10 تصویر generate, edit
    MiniMax ✓ — هیچ‌کدام generate
    OpenRouter ✓ ✓ 1 تصویر generate, edit

    از action: "list" برای بررسی ارائه‌دهندگان و مدل‌های مشترک موجود در زمان اجرا استفاده کنید:

    text
    /tool music_generate action=list

    از action: "status" برای بررسی وظیفه فعال موسیقی مبتنی بر نشست استفاده کنید:

    text
    /tool music_generate action=status

    نمونه تولید مستقیم:

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

    پارامترهای ابزار

    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" استفاده کنید.
    • جست‌وجوی وضعیت: openclaw tasks list یا openclaw tasks show <taskId> وضعیت‌های در صف، در حال اجرا، و پایانی را بررسی می‌کند.
    • بیدارسازی تکمیل: OpenClaw یک رویداد تکمیل داخلی را دوباره به همان نشست تزریق می‌کند تا مدل خودش بتواند پیام پیگیری روبه‌روی کاربر را بنویسد.
    • راهنمایی پرامپت: نوبت‌های بعدی کاربر/دستی در همان نشست، وقتی یک وظیفه موسیقی از قبل در جریان است، یک راهنمایی کوچک زمان اجرا دریافت می‌کنند تا مدل کورکورانه دوباره music_generate را فراخوانی نکند.
    • جایگزین بدون نشست: زمینه‌های مستقیم/محلی بدون یک نشست واقعی عامل به‌صورت درون‌خطی اجرا می‌شوند و نتیجه صوتی نهایی را در همان نوبت برمی‌گردانند.

    چرخه عمر وظیفه

    وضعیت معنی
    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. تشخیص خودکار فقط با استفاده از پیش‌فرض‌های ارائه‌دهنده دارای احراز هویت:
      • ابتدا ارائه‌دهنده پیش‌فرض فعلی؛
      • ارائه‌دهندگان ثبت‌شده باقی‌مانده تولید موسیقی به‌ترتیب شناسه ارائه‌دهنده.

    اگر یک ارائه‌دهنده شکست بخورد، نامزد بعدی به‌صورت خودکار امتحان می‌شود. اگر همه شکست بخورند، خطا شامل جزئیات هر تلاش است.

    برای استفاده فقط از ورودی‌های صریح model، primary و fallbacks، agents.defaults.mediaGenerationAutoProviderFallback: false را تنظیم کنید.

    یادداشت‌های ارائه‌دهنده

    ComfyUI

    مبتنی بر گردش‌کار است و به گراف پیکربندی‌شده به‌همراه نگاشت گره‌ها برای فیلدهای پرامپت/خروجی وابسته است. Plugin همراه comfy از طریق رجیستری ارائه‌دهنده تولید موسیقی به ابزار مشترک music_generate متصل می‌شود.

    fal

    از endpointهای مدل fal از طریق مسیر احراز هویت ارائه‌دهنده مشترک استفاده می‌کند. ارائه‌دهنده همراه به‌صورت پیش‌فرض از fal-ai/minimax-music/v2.6 استفاده می‌کند و همچنین fal-ai/ace-step/prompt-to-audio و fal-ai/stable-audio-25/text-to-audio را برای درخواست‌های پرامپت به صدا ارائه می‌دهد.

    Google (Lyria 3)

    از تولید دسته‌ای Lyria 3 استفاده می‌کند. جریان همراه فعلی از پرامپت، متن شعر اختیاری، و تصاویر مرجع اختیاری پشتیبانی می‌کند.

    MiniMax

    از endpoint دسته‌ای music_generation استفاده می‌کند. از پرامپت، شعر اختیاری، حالت سازی، و خروجی mp3 از طریق احراز هویت کلید API minimax یا OAuth minimax-portal پشتیبانی می‌کند.

    OpenRouter

    از خروجی صوتی تکمیل‌های چت OpenRouter با streaming فعال استفاده می‌کند. ارائه‌دهنده همراه به‌صورت پیش‌فرض از google/lyria-3-pro-preview استفاده می‌کند و همچنین openrouter/google/lyria-3-clip-preview را ارائه می‌دهد.

    انتخاب مسیر درست

    • مبتنی بر ارائه‌دهنده مشترک وقتی انتخاب مدل، failover ارائه‌دهنده، و جریان داخلی وظیفه/وضعیت ناهمگام را می‌خواهید.
    • مسیر Plugin (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 بتوانند پشتیبانی حالت را به‌صورت قطعی اعتبارسنجی کنند.

    آزمون‌های زنده

    پوشش زنده اختیاری برای ارائه‌دهندگان مشترک همراه:

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

    wrapper مخزن:

    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 همچنین workflowهای تصویر و ویدئوی comfy را زمانی که آن بخش‌ها پیکربندی شده باشند پوشش می‌دهد.

    مرتبط

    Was this useful?
    On this page

    On this page