English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

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)

    {
  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

    /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
    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" لفحص الموفرين والنماذج المشتركة المتاحة في وقت التشغيل:

    /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

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

    promptstringrequired

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

    action"generate" | "status" | "list"

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

    modelstring

    تجاوز الموفر/النموذج (مثل google/lyria-3-pro-preview, comfy/workflow).

    lyricsstring

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

    instrumentalboolean

    اطلب إخراجًا آليًا فقط عندما يدعم الموفر ذلك.

    imagestring

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

    imagesstring[]

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

    durationSecondsnumber

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

    format"mp3" | "wav"

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

    filenamestring
    timeoutMsnumber

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

    يعمل إنشاء الموسيقى المدعوم بالجلسة كمهمة في الخلفية:

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

    ترتيب اختيار الموفر

    يحاول OpenClaw استخدام الموفرين بهذا الترتيب:

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

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

    عيّن 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 عندما يتضمن الطلب صورة مرجعية واحدة أو أكثر.

    ينبغي لتطبيقات الموفرين الجديدة تفضيل كتل الأوضاع الصريحة:

    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

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

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

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

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

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

    ذات صلة