توليد الموسيقى

تتيح أداة music_generate للوكيل إنشاء موسيقى أو صوت عبر إمكانات إنشاء الموسيقى المشتركة مع المزوّدين المُهيّئين — ComfyUI، fal، Google، MiniMax، وOpenRouter حاليًا. بالنسبة إلى تشغيلات الوكيل المدعومة بجلسة، يبدأ OpenClaw إنشاء الموسيقى كمهمة في الخلفية، ويتتبعها في سجل المهام، ثم يوقظ الوكيل مرة أخرى عندما يصبح المقطع جاهزًا حتى يتمكن الوكيل من إخبار المستخدم وإرفاق الصوت النهائي. يتبع وكيل الإكمال وضع الرد المرئي العادي للجلسة: تسليم الرد النهائي تلقائيًا عند تهيئته، أو message(action="send") عندما تتطلب الجلسة أداة الرسائل. إذا كانت جلسة الطالب غير نشطة أو فشلت إفاقتها النشطة، وكان بعض الصوت المُنشأ لا يزال مفقودًا من رد الإكمال، يرسل OpenClaw احتياطًا مباشرًا قابلًا للتكرار بأمان يتضمن الصوت المفقود فقط.

لا تظهر الأداة المشتركة المضمّنة إلا عند توفر مزوّد واحد على الأقل لإنشاء الموسيقى. إذا لم ترَ music_generate ضمن أدوات وكيلك، فقم بتهيئة agents.defaults.musicGenerationModel أو إعداد مفتاح API لأحد المزوّدين.

البدء السريع

Shared provider-backed
ComfyUI workflow

Configure auth

عيّن مفتاح API لمزوّد واحد على الأقل — مثلًا GEMINI_API_KEY أو MINIMAX_API_KEY.

Pick a default model (optional)

{
  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 تلقائيًا. لا حاجة إلى قائمة سماح للأداة.

بالنسبة إلى السياقات المتزامنة المباشرة من دون تشغيل وكيل مدعوم بجلسة، تظل الأداة المضمّنة ترجع إلى الإنشاء المضمّن وتعيد مسار الوسائط النهائي في نتيجة الأداة.

Configure the workflow

قم بتهيئة plugins.entries.comfy.config.music باستخدام سير عمل JSON وعُقد المطالبة/الإخراج.

Cloud auth (optional)

بالنسبة إلى Comfy Cloud، عيّن COMFY_API_KEY أو COMFY_CLOUD_API_KEY.

Call the tool

/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.

المزوّدون المدعومون

المزوّد	النموذج الافتراضي	مُدخلات مرجعية	عناصر التحكم المدعومة	المصادقة
ComfyUI	`workflow`	حتى صورة واحدة	موسيقى أو صوت حسب تعريف سير العمل	`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`	حتى صورة واحدة	`lyrics`, `instrumental`, `durationSeconds`, `format`	`OPENROUTER_API_KEY`

مصفوفة الإمكانات

عقد الوضع الصريح الذي تستخدمه music_generate، واختبارات العقد، والمسح المباشر المشترك:

المزوّد	`generate`	`edit`	حد التعديل	المسارات المباشرة المشتركة
ComfyUI	✓	✓	صورة واحدة	غير موجود في المسح المشترك؛ تغطيه `extensions/comfy/comfy.live.test.ts`
fal	✓	—	لا شيء	`generate`
Google	✓	✓	10 صور	`generate`, `edit`
MiniMax	✓	—	لا شيء	`generate`
OpenRouter	✓	✓	صورة واحدة	`generate`, `edit`

استخدم action: "list" لفحص المزوّدين والنماذج المشتركة المتاحة في وقت التشغيل:

/tool music_generate action=list

استخدم action: "status" لفحص مهمة الموسيقى النشطة المدعومة بجلسة:

/tool music_generate action=status

مثال على الإنشاء المباشر:

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

معاملات الأداة

prompt

string

مطلوب

مطالبة إنشاء الموسيقى. مطلوبة من أجل action: "generate".

action

"generate" | "status" | "list"

افتراضي:"generate"

يعيد "status" مهمة الجلسة الحالية؛ ويفحص "list" المزوّدين.

model

string

تجاوز المزوّد/النموذج (مثل google/lyria-3-pro-preview، comfy/workflow).

lyrics

string

كلمات اختيارية عندما يدعم المزوّد إدخال كلمات صريحًا.

instrumental

boolean

اطلب إخراجًا آليًا فقط عندما يدعمه المزوّد.

image

string

مسار صورة مرجعية واحدة أو URL.

images

string[]

صور مرجعية متعددة (حتى 10 لدى المزوّدين الداعمين).

durationSeconds

number

المدة المستهدفة بالثواني عندما يدعم المزوّد تلميحات المدة.

format

"mp3" | "wav"

تلميح تنسيق الإخراج عندما يدعمه المزوّد.

filename

string

تلميح اسم ملف الإخراج.

لا يدعم كل المزوّدين كل المعاملات. لا يزال OpenClaw يتحقق من الحدود الصارمة مثل أعداد المُدخلات قبل الإرسال. عندما يدعم مزوّد المدة لكنه يستخدم حدًا أقصى أقصر من القيمة المطلوبة، يقيّد OpenClaw القيمة إلى أقرب مدة مدعومة. يتم تجاهل التلميحات الاختيارية غير المدعومة فعلًا مع تحذير عندما يتعذر على المزوّد أو النموذج المحدد احترامها. تبلغ نتائج الأداة عن الإعدادات المطبّقة؛ ويلتقط details.normalization أي ربط من المطلوب إلى المطبّق.

مهلات طلبات المزوّد هي تهيئة للمشغّل فقط. يستخدم 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:

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

ترتيب اختيار المزوّد

يجرب OpenClaw المزوّدين بهذا الترتيب:

معامل model من استدعاء الأداة (إذا حدده الوكيل).
musicGenerationModel.primary من التهيئة.
musicGenerationModel.fallbacks بالترتيب.
الاكتشاف التلقائي باستخدام افتراضيات المزوّد المدعومة بالمصادقة فقط:
- المزوّد الافتراضي الحالي أولًا؛
- بقية مزوّدي إنشاء الموسيقى المسجلين بترتيب معرّف المزوّد.

إذا فشل مزوّد، تتم تجربة المرشح التالي تلقائيًا. إذا فشل الجميع، يتضمن الخطأ تفاصيل من كل محاولة. عيّن agents.defaults.mediaGenerationAutoProviderFallback: false لاستخدام إدخالات model وprimary وfallbacks الصريحة فقط.

ملاحظات المزوّدين

ComfyUI

يعتمد على سير العمل وعلى الرسم البياني المُهيأ مع ربط العُقد لحقول المطالبة/الإخراج. يتصل Plugin comfy المضمّن بأداة music_generate المشتركة عبر سجل مزوّدي إنشاء الموسيقى.

fal

يستخدم نقاط نهاية نموذج 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

يستخدم نقطة نهاية الدُفعات music_generation. يدعم المطالبة والكلمات الاختيارية والوضع الآلي وإخراج mp3 عبر مصادقة مفتاح API لـ minimax أو OAuth لـ minimax-portal.

OpenRouter

يستخدم إخراج صوت إكمالات دردشة OpenRouter مع تفعيل البث. يجعل المزوّد المضمّن google/lyria-3-pro-preview افتراضيًا ويعرض أيضًا openrouter/google/lyria-3-clip-preview.

اختيار المسار المناسب

مدعوم بمزوّد مشترك عندما تريد اختيار النموذج، وتجاوز فشل المزوّد، وتدفق المهمة/الحالة غير المتزامن المضمّن.
مسار 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 ليست كافية للإعلان عن دعم التحرير. ينبغي للمزوّدات التصريح بـ generate وedit صراحةً حتى تتمكن الاختبارات المباشرة، واختبارات العقد، وأداة music_generate المشتركة من التحقق من دعم الأوضاع بشكل حتمي.

الاختبارات المباشرة

تغطية مباشرة اختيارية للمزوّدات المشتركة المضمّنة:

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 عندما تكون تلك الأقسام مهيّأة.

​البدء السريع

​المزوّدون المدعومون

​مصفوفة الإمكانات

​معاملات الأداة

​السلوك غير المتزامن

​دورة حياة المهمة

​التهيئة

​اختيار النموذج

​ترتيب اختيار المزوّد

​ملاحظات المزوّدين

​اختيار المسار المناسب

​أوضاع إمكانات المزوّد

​الاختبارات المباشرة

​ذات صلة

البدء السريع

المزوّدون المدعومون

مصفوفة الإمكانات

معاملات الأداة

السلوك غير المتزامن

دورة حياة المهمة

التهيئة

اختيار النموذج

ترتيب اختيار المزوّد

ملاحظات المزوّدين

اختيار المسار المناسب

أوضاع إمكانات المزوّد

الاختبارات المباشرة

ذات صلة