---
read_when:
    - إنشاء موسيقى أو صوت عبر الوكيل
    - تهيئة مزودات ونماذج توليد الموسيقى
    - فهم معلمات الأداة music_generate
summary: أنشئ موسيقى باستخدام مزودات مشتركة، بما في ذلك plugins المدعومة بسير العمل
title: توليد الموسيقى
x-i18n:
    generated_at: "2026-04-07T07:23:31Z"
    model: gpt-5.4
    provider: openai
    source_hash: ce8da8dfc188efe8593ca5cbec0927dd1d18d2861a1a828df89c8541ccf1cb25
    source_path: tools/music-generation.md
    workflow: 15
---

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

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

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

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

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

### التوليد المدعوم بمزودات مشتركة

1. اضبط مفتاح API لمزود واحد على الأقل، مثل `GEMINI_API_KEY` أو
   `MINIMAX_API_KEY`.
2. اضبط نموذجك المفضل اختياريًا:

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

3. اطلب من الوكيل: _"أنشئ مقطع synthpop حيويًا عن قيادة ليلية
   عبر مدينة نيون."_

يستدعي الوكيل `music_generate` تلقائيًا. ولا حاجة إلى إدراج الأداة في allow-list.

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

أمثلة على prompts:

```text
Generate a cinematic piano track with soft strings and no vocals.
```

```text
Generate an energetic chiptune loop about launching a rocket at sunrise.
```

### توليد Comfy المعتمد على سير العمل

يتكامل plugin المضمن `comfy` مع الأداة المشتركة `music_generate` عبر
سجل مزودات توليد الموسيقى.

1. هيّئ `models.providers.comfy.music` باستخدام JSON لسير العمل و
   عقد prompt/output.
2. إذا كنت تستخدم Comfy Cloud، فاضبط `COMFY_API_KEY` أو `COMFY_CLOUD_API_KEY`.
3. اطلب من الوكيل إنشاء موسيقى أو استدعِ الأداة مباشرةً.

مثال:

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

## دعم المزودات المضمنة المشتركة

| المزود | النموذج الافتراضي | المدخلات المرجعية | عناصر التحكم المدعومة | مفتاح API |
| -------- | ---------------------- | ---------------- | --------------------------------------------------------- | -------------------------------------- |
| 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.5+`           | لا شيء            | `lyrics`, `instrumental`, `durationSeconds`, `format=mp3` | `MINIMAX_API_KEY`                      |

### مصفوفة القدرات المعلنة

هذا هو عقد الأوضاع الصريح الذي تستخدمه `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
```

## معلمات الأداة المضمنة

| المعلمة | النوع | الوصف |
| ----------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `prompt`          | string   | prompt لتوليد الموسيقى (مطلوب لـ `action: "generate"`) |
| `action`          | string   | `"generate"` (الافتراضي)، أو `"status"` لمهمة الجلسة الحالية، أو `"list"` لفحص المزودات |
| `model`           | string   | تجاوز provider/model، مثل `google/lyria-3-pro-preview` أو `comfy/workflow` |
| `lyrics`          | string   | كلمات اختيارية عندما يدعم المزود إدخال كلمات صريحة |
| `instrumental`    | boolean  | طلب إخراج آلي فقط عندما يدعمه المزود |
| `image`           | string   | مسار أو URL لصورة مرجعية واحدة |
| `images`          | string[] | صور مرجعية متعددة (حتى 10) |
| `durationSeconds` | number   | المدة المستهدفة بالثواني عندما يدعم المزود تلميحات المدة |
| `format`          | string   | تلميح تنسيق الإخراج (`mp3` أو `wav`) عندما يدعمه المزود |
| `filename`        | string   | تلميح اسم ملف الإخراج |

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

تبلغ نتائج الأداة عن الإعدادات المطبقة. وعندما يقيّد OpenClaw المدة أثناء fallback بين المزودات، تعكس القيمة المعادة `durationSeconds` القيمة المرسلة، بينما تعرض `details.normalization.durationSeconds` خريطة المطلوب إلى المطبق.

## السلوك غير المتزامن للمسار المدعوم بالمزود المشترك

- تشغيلات الوكيل المدعومة بالجلسة: تنشئ `music_generate` مهمة في الخلفية، وتعيد فورًا استجابة بدء/مهمة، ثم تنشر المقطع النهائي لاحقًا في رسالة متابعة من الوكيل.
- منع التكرار: ما دامت تلك المهمة في الخلفية ما تزال `queued` أو `running`، فإن استدعاءات `music_generate` اللاحقة في الجلسة نفسها تعيد حالة المهمة بدلًا من بدء توليد آخر.
- البحث عن الحالة: استخدم `action: "status"` لفحص مهمة الموسيقى النشطة المدعومة بالجلسة دون بدء مهمة جديدة.
- تتبع المهام: استخدم `openclaw tasks list` أو `openclaw tasks show <taskId>` لفحص الحالة المنتظرة، والجارية، والنهائية لعملية التوليد.
- الإيقاظ عند الاكتمال: يحقن OpenClaw حدث اكتمال داخليًا مرة أخرى في الجلسة نفسها حتى يتمكن النموذج من كتابة رسالة المتابعة الموجهة للمستخدم بنفسه.
- تلميح prompt: تحصل أدوار المستخدم/الأدوار اليدوية اللاحقة في الجلسة نفسها على تلميح صغير في وقت التشغيل عندما تكون مهمة موسيقى قيد التنفيذ بالفعل حتى لا يستدعي النموذج `music_generate` مرة أخرى بشكل أعمى.
- fallback بدون جلسة: لا تزال السياقات المباشرة/المحلية بدون جلسة وكيل حقيقية تعمل بشكل مضمّن وتعيد نتيجة الصوت النهائية في الدور نفسه.

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

تمر كل طلبات `music_generate` عبر أربع حالات:

1. **queued** -- تم إنشاء المهمة وتنتظر أن يقبلها المزود.
2. **running** -- يعالجها المزود (عادةً من 30 ثانية إلى 3 دقائق حسب المزود والمدة).
3. **succeeded** -- أصبح المقطع جاهزًا؛ يستيقظ الوكيل وينشره في المحادثة.
4. **failed** -- خطأ من المزود أو انتهاء مهلة؛ يستيقظ الوكيل مع تفاصيل الخطأ.

تحقق من الحالة من CLI:

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

منع التكرار: إذا كانت هناك مهمة موسيقى `queued` أو `running` بالفعل للجلسة الحالية، فإن `music_generate` تعيد حالة المهمة الموجودة بدلًا من بدء مهمة جديدة. استخدم `action: "status"` للتحقق صراحةً بدون تشغيل توليد جديد.

## الإعدادات

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

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

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

عند توليد الموسيقى، يحاول OpenClaw استخدام المزودات بهذا الترتيب:

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

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

اضبط `agents.defaults.mediaGenerationAutoProviderFallback: false` إذا كنت تريد أن
يستخدم توليد الموسيقى فقط الإدخالات الصريحة `model` و`primary` و`fallbacks`.

## ملاحظات خاصة بالمزودات

- يستخدم Google توليد Lyria 3 الدفعي. ويدعم التدفق المضمن الحالي
  prompt، ونص كلمات اختياري، وصورًا مرجعية اختيارية.
- يستخدم MiniMax نقطة النهاية الدفعية `music_generation`. ويدعم التدفق المضمن الحالي
  prompt، وكلمات اختيارية، ووضعًا آليًا فقط، وتوجيه المدة، و
  إخراج mp3.
- دعم ComfyUI يعتمد على سير العمل ويعتمد على الرسم البياني المضبوط بالإضافة إلى
  تعيين العقد لحقول prompt/output.

## أوضاع قدرات المزود

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

- `generate` للتوليد المعتمد على prompt فقط
- `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` من التحقق من دعم الأوضاع بشكل حتمي.

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

- استخدم المسار المدعوم بالمزود المشترك عندما تريد اختيار النموذج، وfallback بين المزودات، وتدفق المهمة/الحالة غير المتزامن المضمن.
- استخدم مسار plugin مثل ComfyUI عندما تحتاج إلى رسم بياني مخصص لسير العمل أو مزود ليس جزءًا من قدرة الموسيقى المشتركة المضمنة.
- إذا كنت تصحح سلوكًا خاصًا بـ ComfyUI، فراجع [ComfyUI](/ar/providers/comfy). وإذا كنت تصحح سلوك المزودات المشتركة، فابدأ من [Google (Gemini)](/ar/providers/google) أو [MiniMax](/ar/providers/minimax).

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

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

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

## ذو صلة

- [المهام في الخلفية](/ar/automation/tasks) - تتبع المهام لتشغيلات `music_generate` المنفصلة
- [مرجع الإعدادات](/ar/gateway/configuration-reference#agent-defaults) - إعدادات `musicGenerationModel`
- [ComfyUI](/ar/providers/comfy)
- [Google (Gemini)](/ar/providers/google)
- [MiniMax](/ar/providers/minimax)
- [النماذج](/ar/concepts/models) - إعدادات النماذج وfailover
- [نظرة عامة على الأدوات](/ar/tools)
