Tools

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

تتيح أداة music_generate للوكيل إنشاء موسيقى أو صوت عبر إمكانات توليد الموسيقى المشتركة مع المزوّدين المكوّنين — Google، MiniMax، وComfyUI المكوّن عبر سير العمل حاليًا.

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

البدء السريع

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`	حتى صورة واحدة	موسيقى أو صوت معرّف بواسطة سير العمل	`COMFY_API_KEY`, `COMFY_CLOUD_API_KEY`
Google	`lyria-3-clip-preview`	حتى 10 صور	`lyrics`, `instrumental`, `format`	`GEMINI_API_KEY`, `GOOGLE_API_KEY`
MiniMax	`music-2.6`	لا شيء	`lyrics`, `instrumental`, `durationSeconds`, `format=mp3`	`MINIMAX_API_KEY` أو MiniMax OAuth

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

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

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

استخدم 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_DOCS_MARKER:paramOpen:IHBhdGg9InRpbWVvdXRNcyIgdHlwZT0ibnVtYmVyIg مهلة طلب المزوّد الاختيارية بالمللي ثانية. عند حذفها، يستخدم OpenClaw agents.defaults.musicGenerationModel.timeoutMs إذا كان مكوّنًا. تُرفع القيم الأقل من 10000ms إلى 10000ms ويُبلّغ عنها في نتيجة الأداة. OPENCLAW_DOCS_MARKER:paramClose:

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

يعمل توليد الموسيقى المدعوم بجلسة كمهمة خلفية:

مهمة خلفية: تنشئ 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: ["minimax/music-2.6"],      },    },  },}

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

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

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

إذا فشل مزوّد، تتم تجربة المرشح التالي تلقائيًا. إذا فشل الجميع، يتضمن الخطأ تفاصيل من كل محاولة.

عيّن agents.defaults.mediaGenerationAutoProviderFallback: false لاستخدام إدخالات model وprimary وfallbacks الصريحة فقط.

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

ComfyUI

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

Google (Lyria 3)

يستخدم توليد Lyria 3 الدفعي. يدعم التدفق المضمّن الحالي المطالبة، ونص الكلمات الاختياري، والصور المرجعية الاختيارية.

MiniMax

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

اختيار المسار الصحيح

مدعوم بمزوّد مشترك عندما تريد اختيار النموذج، وتجاوز فشل المزوّد، وتدفق المهمة/الحالة غير المتزامن المضمّن.
مسار Plugin (ComfyUI) عندما تحتاج إلى رسم بياني مخصص لسير العمل أو مزوّد ليس جزءًا من إمكانية الموسيقى المضمّنة المشتركة.

إذا كنت تصحح سلوكًا خاصًا بـ ComfyUI، فراجع ComfyUI. إذا كنت تصحح سلوكًا مشتركًا للمزوّد، فابدأ بـ Google (Gemini) أو MiniMax.

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

يدعم عقد توليد الموسيقى المشترك تصريحات وضع صريحة:

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

غلاف المستودع:

bash

pnpm test:live:media music

يحمّل هذا الملف الحي متغيرات بيئة المزوّد الناقصة من ~/.profile، ويفضّل مفاتيح API الحية/من البيئة على ملفات تعريف المصادقة المخزنة افتراضيًا، ويشغّل تغطية كل من generate وedit المعلنة عندما يفعّل المزوّد وضع التحرير. التغطية حاليًا:

google: generate بالإضافة إلى edit
minimax: generate فقط
comfy: تغطية حية منفصلة لـ Comfy، وليست ضمن المسح المشترك للمزوّدين

فعّل اختياريًا التغطية الحية لمسار الموسيقى المضمّن في ComfyUI:

bash

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

يغطي ملف Comfy الحي أيضًا سير عمل الصور والفيديو في comfy عندما تكون تلك الأقسام مهيأة.

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

البدء السريع

Shared provider-backed

Configure auth

Pick a default model (optional)

Ask the agent

ComfyUI workflow

Configure the workflow

Cloud auth (optional)

Call the tool

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

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

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

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

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

التكوين

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

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

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

اختيار المسار الصحيح

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

الاختبارات الحية

ذات صلة

Molty