---
read_when:
    - تمكين تحويل النص إلى كلام للردود
    - تكوين مزوّد تحويل النص إلى كلام أو سلسلة احتياطية أو شخصية
    - استخدام أوامر أو توجيهات /tts
sidebarTitle: Text to speech (TTS)
summary: تحويل النص إلى كلام للردود الصادرة — المزوّدون، والشخصيات، وأوامر الشرطة المائلة، والمخرجات لكل قناة
title: تحويل النص إلى كلام
x-i18n:
    generated_at: "2026-06-27T18:47:15Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 94835daf766286e937c57828818a4ee0a20e6d5894b7d51d6f98fc7ebdaffe35
    source_path: tools/tts.md
    workflow: 16
---

يمكن لـ OpenClaw تحويل الردود الصادرة إلى صوت عبر **14 مزودًا للكلام**
وتسليم رسائل صوتية أصلية على Feishu وMatrix وTelegram وWhatsApp،
ومرفقات صوتية في كل مكان آخر، وتدفقات PCM/Ulaw للاتصالات الهاتفية وTalk.

TTS هو نصف إخراج الكلام في وضع `stt-tts` الخاص بـ Talk. جلسات Talk
`realtime` الأصلية لدى المزود تُنشئ الكلام داخل مزود الوقت الفعلي بدلًا
من استدعاء مسار TTS هذا، بينما لا تُنشئ جلسات `transcription` استجابة
صوتية للمساعد.

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

<Steps>
  <Step title="Pick a provider">
    OpenAI وElevenLabs هما أكثر الخيارات المستضافة موثوقية. يعمل Microsoft و
    Local CLI دون مفتاح API. راجع [مصفوفة المزودين](#supported-providers)
    للاطلاع على القائمة الكاملة.
  </Step>
  <Step title="Set the API key">
    صدّر متغير البيئة لمزودك (على سبيل المثال `OPENAI_API_KEY`،
    `ELEVENLABS_API_KEY`). لا يحتاج Microsoft وLocal CLI إلى مفتاح.
  </Step>
  <Step title="Enable in config">
    اضبط `messages.tts.auto: "always"` و`messages.tts.provider`:

    ```json5
    {
      messages: {
        tts: {
          auto: "always",
          provider: "elevenlabs",
        },
      },
    }
    ```

  </Step>
  <Step title="Try it in chat">
    يعرض `/tts status` الحالة الحالية. يرسل `/tts audio Hello from OpenClaw`
    ردًا صوتيًا لمرة واحدة.
  </Step>
</Steps>

<Note>
ميزة Auto-TTS **متوقفة** افتراضيًا. عندما لا يكون `messages.tts.provider` معيّنًا،
يختار OpenClaw أول مزود مكوّن وفق ترتيب الاختيار التلقائي في السجل.
أداة الوكيل المضمنة `tts` مخصصة للنية الصريحة فقط: تبقى المحادثة العادية
نصية ما لم يطلب المستخدم صوتًا، أو يستخدم `/tts`، أو يفعّل الكلام عبر
Auto-TTS/التوجيه.
</Note>

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

| المزود            | المصادقة                                                                                                         | ملاحظات                                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| **Azure Speech**  | `AZURE_SPEECH_KEY` + `AZURE_SPEECH_REGION` (أيضًا `AZURE_SPEECH_API_KEY`, `SPEECH_KEY`, `SPEECH_REGION`)          | إخراج ملاحظات صوتية Ogg/Opus أصلية واتصالات هاتفية.                                       |
| **DeepInfra**     | `DEEPINFRA_API_KEY`                                                                                              | TTS متوافق مع OpenAI. الافتراضي هو `hexgrad/Kokoro-82M`.                                   |
| **ElevenLabs**    | `ELEVENLABS_API_KEY` أو `XI_API_KEY`                                                                             | استنساخ الصوت، متعدد اللغات، حتمي عبر `seed`؛ يُبث لتشغيل الصوت في Discord.               |
| **Google Gemini** | `GEMINI_API_KEY` أو `GOOGLE_API_KEY`                                                                             | TTS دفعي عبر Gemini API؛ واعٍ بالشخصية عبر `promptTemplate: "audio-profile-v1"`.           |
| **Gradium**       | `GRADIUM_API_KEY`                                                                                                | إخراج ملاحظات صوتية واتصالات هاتفية.                                                       |
| **Inworld**       | `INWORLD_API_KEY`                                                                                                | Streaming TTS API. ملاحظات صوتية Opus أصلية واتصالات هاتفية PCM.                          |
| **Local CLI**     | لا شيء                                                                                                           | يشغّل أمر TTS محليًا مكوّنًا.                                                              |
| **Microsoft**     | لا شيء                                                                                                           | TTS عصبي عام من Edge عبر `node-edge-tts`. أفضل جهد، بلا SLA.                               |
| **MiniMax**       | `MINIMAX_API_KEY` (أو خطة الرموز: `MINIMAX_OAUTH_TOKEN`, `MINIMAX_CODE_PLAN_KEY`, `MINIMAX_CODING_API_KEY`)      | T2A v2 API. الافتراضي هو `speech-2.8-hd`.                                                   |
| **OpenAI**        | `OPENAI_API_KEY`                                                                                                 | يُستخدم أيضًا للتلخيص التلقائي؛ يدعم `instructions` الخاصة بالشخصية.                       |
| **OpenRouter**    | `OPENROUTER_API_KEY` (يمكنه إعادة استخدام `models.providers.openrouter.apiKey`)                                  | النموذج الافتراضي `hexgrad/kokoro-82m`.                                                     |
| **Volcengine**    | `VOLCENGINE_TTS_API_KEY` أو `BYTEPLUS_SEED_SPEECH_API_KEY` (AppID/رمز قديم: `VOLCENGINE_TTS_APPID`/`_TOKEN`)     | BytePlus Seed Speech HTTP API.                                                              |
| **Vydra**         | `VYDRA_API_KEY`                                                                                                  | مزود مشترك للصور والفيديو والكلام.                                                          |
| **xAI**           | `XAI_API_KEY`                                                                                                    | TTS دفعي من xAI. الملاحظة الصوتية Opus الأصلية **غير** مدعومة.                             |
| **Xiaomi MiMo**   | `XIAOMI_API_KEY`                                                                                                 | MiMo TTS عبر إكمالات محادثة Xiaomi.                                                        |

إذا تم تكوين عدة مزودين، فسيُستخدم المزود المحدد أولًا وتكون المزودات
الأخرى خيارات احتياطية. يستخدم التلخيص التلقائي `summaryModel` (أو
`agents.defaults.model.primary`)، لذلك يجب أيضًا مصادقة ذلك المزود إذا
أبقيت الملخصات مفعّلة.

<Warning>
يستخدم مزود **Microsoft** المضمن خدمة TTS العصبية عبر الإنترنت الخاصة بـ
Microsoft Edge من خلال `node-edge-tts`. إنها خدمة ويب عامة بلا SLA أو حصة
منشورة — تعامل معها على أنها أفضل جهد. يُطبّع معرّف المزود القديم `edge`
إلى `microsoft` ويعيد `openclaw doctor --fix` كتابة الإعدادات المحفوظة؛
يجب أن تستخدم الإعدادات الجديدة دائمًا `microsoft`.
</Warning>

## التكوين

يوجد تكوين TTS ضمن `messages.tts` في `~/.openclaw/openclaw.json`. اختر
إعدادًا مسبقًا وعدّل كتلة المزود:

<Tabs>
  <Tab title="Azure Speech">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          speakerVoice: "en-US-JennyNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          voiceNoteOutputFormat: "ogg-24khz-16bit-mono-opus",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="ElevenLabs">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Google Gemini">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          speakerVoice: "Kore",
          // Optional natural-language style prompts:
          // audioProfile: "Speak in a calm, podcast-host tone.",
          // speakerName: "Alex",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Gradium">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Inworld">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Local CLI">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Microsoft (no key)">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          speakerVoice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+0%",
          pitch: "+0%",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="MiniMax">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "${MINIMAX_API_KEY}",
          model: "speech-2.8-hd",
          speakerVoiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="OpenAI + ElevenLabs">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      providers: {
        openai: {
          apiKey: "${OPENAI_API_KEY}",
          model: "gpt-4o-mini-tts",
          speakerVoice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
          voiceSettings: { stability: 0.5, similarityBoost: 0.75, style: 0.0, useSpeakerBoost: true, speed: 1.0 },
          applyTextNormalization: "auto",
          languageCode: "en",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="OpenRouter">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Volcengine">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="xAI">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}
```
  </Tab>
  <Tab title="Xiaomi MiMo">
```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}
```
  </Tab>
</Tabs>

بالنسبة إلى Xiaomi `mimo-v2.5-tts-voicedesign`، احذف `speakerVoice` واضبط
`style` على مطالبة تصميم الصوت. يرسل OpenClaw تلك المطالبة كرسالة TTS
`user` ولا يرسل `audio.voice` لنموذج voicedesign.

### تجاوزات الصوت لكل وكيل

استخدم `agents.list[].tts` عندما يجب أن يتحدث وكيل واحد بموفر أو
صوت أو نموذج أو شخصية أو وضع TTS تلقائي مختلف. تدمج كتلة الوكيل بعمق فوق
`messages.tts`، لذلك يمكن أن تبقى بيانات اعتماد الموفر في إعدادات الموفر العامة:

```json5
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: { apiKey: "${ELEVENLABS_API_KEY}", model: "eleven_multilingual_v2" },
      },
    },
  },
  agents: {
    list: [
      {
        id: "reader",
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
      },
    ],
  },
}
```

لتثبيت شخصية لكل وكيل، اضبط `agents.list[].tts.persona` بجانب إعدادات
الموفر — فهي تتجاوز `messages.tts.persona` العامة لذلك الوكيل فقط.

ترتيب الأولوية للردود التلقائية، و`/tts audio`، و`/tts status`، وأداة الوكيل
`tts`:

1. `messages.tts`
2. `agents.list[].tts` النشطة
3. تجاوز القناة، عندما تدعم القناة `channels.<channel>.tts`
4. تجاوز الحساب، عندما تمرر القناة `channels.<channel>.accounts.<id>.tts`
5. تفضيلات `/tts` المحلية لهذا المضيف
6. توجيهات `[[tts:...]]` المضمنة عندما تكون [تجاوزات النموذج](#model-driven-directives) مفعلة

تستخدم تجاوزات القناة والحساب البنية نفسها مثل `messages.tts` وتدمج بعمق
فوق الطبقات السابقة، لذلك يمكن أن تبقى بيانات اعتماد الموفر المشتركة في
`messages.tts` بينما تغير قناة أو حساب بوت صوت المتحدث أو النموذج أو الشخصية
أو الوضع التلقائي فقط:

```json5
{
  messages: {
    tts: {
      provider: "openai",
      providers: {
        openai: { apiKey: "${OPENAI_API_KEY}", model: "gpt-4o-mini-tts" },
      },
    },
  },
  channels: {
    feishu: {
      accounts: {
        english: {
          tts: {
            providers: {
              openai: { speakerVoice: "shimmer" },
            },
          },
        },
      },
    },
  },
}
```

## الشخصيات

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

### شخصية مبسطة

```json5
{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: {
              speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
              modelId: "eleven_multilingual_v2",
            },
          },
        },
      },
    },
  },
}
```

### شخصية كاملة (مطالبة محايدة للموفر)

```json5
{
  messages: {
    tts: {
      auto: "always",
      persona: "alfred",
      personas: {
        alfred: {
          label: "Alfred",
          description: "Dry, warm British butler narrator.",
          provider: "google",
          fallbackPolicy: "preserve-persona",
          prompt: {
            profile: "A brilliant British butler. Dry, witty, warm, charming, emotionally expressive, never generic.",
            scene: "A quiet late-night study. Close-mic narration for a trusted operator.",
            sampleContext: "The speaker is answering a private technical request with concise confidence and dry warmth.",
            style: "Refined, understated, lightly amused.",
            accent: "British English.",
            pacing: "Measured, with short dramatic pauses.",
            constraints: ["Do not read configuration values aloud.", "Do not explain the persona."],
          },
          providers: {
            google: {
              model: "gemini-3.1-flash-tts-preview",
              speakerVoice: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", speakerVoice: "cedar" },
            elevenlabs: {
              speakerVoiceId: "voice_id",
              modelId: "eleven_multilingual_v2",
              seed: 42,
              voiceSettings: {
                stability: 0.65,
                similarityBoost: 0.8,
                style: 0.25,
                useSpeakerBoost: true,
                speed: 0.95,
              },
            },
          },
        },
      },
    },
  },
}
```

### حلّ الشخصية

تُحدد الشخصية النشطة بشكل حتمي:

1. تفضيل `/tts persona <id>` المحلي، إذا كان مضبوطًا.
2. `messages.tts.persona`، إذا كان مضبوطًا.
3. بلا شخصية.

يعمل اختيار الموفر بترتيب الصريح أولًا:

1. التجاوزات المباشرة (CLI، وGateway، وTalk، وتوجيهات TTS المسموح بها).
2. تفضيل `/tts provider <id>` المحلي.
3. `provider` الخاص بالشخصية النشطة.
4. `messages.tts.provider`.
5. الاختيار التلقائي من السجل.

لكل محاولة موفر، يدمج OpenClaw الإعدادات بهذا الترتيب:

1. `messages.tts.providers.<id>`
2. `messages.tts.personas.<persona>.providers.<id>`
3. تجاوزات الطلب الموثوق بها
4. تجاوزات توجيهات TTS التي يصدرها النموذج والمسموح بها

### كيف تستخدم الموفرات مطالبات الشخصية

حقول مطالبة الشخصية (`profile`، و`scene`، و`sampleContext`، و`style`، و`accent`،
و`pacing`، و`constraints`) **محايدة للموفر**. يقرر كل موفر كيفية
استخدامها:

<AccordionGroup>
  <Accordion title="Google Gemini">
    يلف حقول مطالبة الشخصية في بنية مطالبة Gemini TTS **فقط عندما**
    تضبط إعدادات موفر Google الفعالة `promptTemplate: "audio-profile-v1"`
    أو `personaPrompt`. ما زالت حقول `audioProfile` و`speakerName` الأقدم
    تسبق النص كنص مطالبة خاص بـ Google. تُحفظ وسوم الصوت المضمنة مثل
    `[whispers]` أو `[laughs]` داخل كتلة `[[tts:text]]`
    داخل نص Gemini؛ لا ينشئ OpenClaw هذه الوسوم.
  </Accordion>
  <Accordion title="OpenAI">
    يطابق حقول مطالبة الشخصية إلى حقل الطلب `instructions` **فقط عندما**
    لا تكون هناك `instructions` صريحة مهيأة لـ OpenAI. تفوز `instructions`
    الصريحة دائمًا.
  </Accordion>
  <Accordion title="الموفرون الآخرون">
    يستخدمون فقط ربطات الشخصية الخاصة بالموفر تحت
    `personas.<id>.providers.<provider>`. تُتجاهل حقول مطالبة الشخصية
    ما لم ينفذ الموفر تعيين مطالبات شخصية خاصًا به.
  </Accordion>
</AccordionGroup>

### سياسة الرجوع

يتحكم `fallbackPolicy` في السلوك عندما لا تملك الشخصية **أي ربط** للموفر
الذي تجري محاولة استخدامه:

| السياسة            | السلوك                                                                                                                                   |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------- |
| `preserve-persona` | **الافتراضي.** تبقى حقول المطالبة المحايدة للموفر متاحة؛ قد يستخدمها الموفر أو يتجاهلها.                                              |
| `provider-defaults` | تُحذف الشخصية من تحضير المطالبة لتلك المحاولة؛ يستخدم الموفر افتراضاته المحايدة بينما يستمر الرجوع إلى موفرين آخرين.                 |
| `fail`             | تخطَّ محاولة ذلك الموفر مع `reasonCode: "not_configured"` و`personaBinding: "missing"`. تبقى موفرات الرجوع قيد المحاولة.             |

يفشل طلب TTS بأكمله فقط عندما تُتخطى **كل** محاولات الموفرين
أو تفشل.

اختيار موفر جلسة Talk محصور بنطاق الجلسة. يجب على عميل Talk اختيار
معرفات الموفرين، ومعرفات النماذج، ومعرفات الأصوات، واللغات المحلية من
`talk.catalog` وتمريرها عبر جلسة Talk أو طلب التسليم. يجب ألا يؤدي فتح
جلسة صوتية إلى تعديل `messages.tts` أو افتراضات موفر Talk العامة.

## التوجيهات المدفوعة بالنموذج

افتراضيًا، **يمكن** للمساعد إصدار توجيهات `[[tts:...]]` لتجاوز
الصوت أو النموذج أو السرعة لرد واحد، بالإضافة إلى كتلة اختيارية
`[[tts:text]]...[[/tts:text]]` للإشارات التعبيرية التي يجب أن تظهر في
الصوت فقط:

```text
Here you go.

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]
```

عندما يكون `messages.tts.auto` هو `"tagged"`، تكون **التوجيهات مطلوبة**
لتشغيل الصوت. يزيل تسليم الكتل المتدفقة التوجيهات من النص المرئي قبل أن
تراها القناة، حتى عندما تكون مقسمة عبر كتل متجاورة.

يُتجاهل `provider=...` ما لم يكن `modelOverrides.allowProvider: true`.
عندما يعلن رد `provider=...`، تُحلل المفاتيح الأخرى في ذلك التوجيه
بواسطة ذلك الموفر فقط؛ تُزال المفاتيح غير المدعومة ويُبلغ عنها كتحذيرات
توجيه TTS.

**مفاتيح التوجيه المتاحة:**

- `provider` (معرف موفر مسجل؛ يتطلب `allowProvider: true`)
- `speakerVoice` / `speakerVoiceId` (أسماء مستعارة قديمة: `voice`، و`voiceName`، و`voice_name`، و`google_voice`، و`voiceId`)
- `model` / `google_model`
- `stability`، و`similarityBoost`، و`style`، و`speed`، و`useSpeakerBoost`
- `vol` / `volume` (مستوى صوت MiniMax، 0–10)
- `pitch` (درجة صوت MiniMax عددية صحيحة، −12 إلى 12؛ تُقتطع القيم الكسرية)
- `emotion` (وسم عاطفة Volcengine)
- `applyTextNormalization` (`auto|on|off`)
- `languageCode` (ISO 639-1)
- `seed`

**تعطيل تجاوزات النموذج بالكامل:**

```json5
{ messages: { tts: { modelOverrides: { enabled: false } } } }
```

**السماح بتبديل الموفر مع إبقاء عناصر التحكم الأخرى قابلة للتهيئة:**

```json5
{ messages: { tts: { modelOverrides: { enabled: true, allowProvider: true, allowSeed: false } } } }
```

## أوامر الشرطة المائلة

أمر واحد `/tts`. على Discord، يسجل OpenClaw أيضًا `/voice` لأن
`/tts` أمر مدمج في Discord — ما زال نص `/tts ...` يعمل.

```text
/tts off | on | status
/tts chat on | off | default
/tts latest
/tts provider <id>
/tts persona <id> | off
/tts limit <chars>
/tts summary off
/tts audio <text>
```

<Note>
تتطلب الأوامر مرسلًا مصرحًا له (تنطبق قواعد قائمة السماح/المالك) ويجب
تفعيل `commands.text` أو تسجيل الأوامر الأصلية.
</Note>

ملاحظات السلوك:

- يكتب `/tts on` تفضيل TTS المحلي إلى `always`؛ ويكتبه `/tts off` إلى `off`.
- يكتب `/tts chat on|off|default` تجاوزًا لوضع TTS التلقائي محصورًا بنطاق الجلسة للمحادثة الحالية.
- يكتب `/tts persona <id>` تفضيل الشخصية المحلي؛ ويمسحه `/tts persona off`.
- يقرأ `/tts latest` أحدث رد للمساعد من سجل الجلسة الحالية ويرسله كصوت مرة واحدة. يخزن فقط تجزئة ذلك الرد في إدخال الجلسة لمنع إرسال صوت مكرر.
- ينشئ `/tts audio` ردًا صوتيًا لمرة واحدة (لا يبدل TTS إلى وضع التشغيل).
- يُخزن `limit` و`summary` في **التفضيلات المحلية**، وليس في الإعدادات الرئيسية.
- يتضمن `/tts status` تشخيصات الرجوع لأحدث محاولة — `Fallback: <primary> -> <used>`، و`Attempts: ...`، وتفاصيل كل محاولة (`provider:outcome(reasonCode) latency`).
- يعرض `/status` وضع TTS النشط بالإضافة إلى الموفر والنموذج والصوت المهيأة وبيانات التعريف المنقحة لنقطة النهاية المخصصة عندما يكون TTS مفعلًا.

## تفضيلات لكل مستخدم

تكتب أوامر الشرطة المائلة التجاوزات المحلية إلى `prefsPath`. القيمة الافتراضية هي
`~/.openclaw/settings/tts.json`؛ ويمكن تجاوزها بمتغير البيئة `OPENCLAW_TTS_PREFS`
أو `messages.tts.prefsPath`.

| الحقل المخزن | التأثير                                      |
| ------------ | -------------------------------------------- |
| `auto`       | تجاوز TTS التلقائي المحلي (`always`، و`off`، …) |
| `provider`   | تجاوز الموفر الأساسي المحلي                 |
| `persona`    | تجاوز الشخصية المحلي                        |
| `maxLength`  | عتبة التلخيص (افتراضيًا `1500` حرفًا)       |
| `summarize`  | مفتاح التلخيص (افتراضيًا `true`)            |

تتجاوز هذه الإعدادات الفعالة من `messages.tts` بالإضافة إلى كتلة
`agents.list[].tts` النشطة لذلك المضيف.

## تنسيقات الإخراج (ثابتة)

يُدار تسليم صوت TTS حسب قدرات القناة. تعلن Plugins القنوات
ما إذا كان TTS بنمط الصوت يجب أن يطلب من الموفرين هدف `voice-note` أصليًا
أو يحافظ على إنشاء `audio-file` العادي ويضع علامة فقط على الإخراج المتوافق
مع التسليم الصوتي.

- **القنوات القادرة على الملاحظات الصوتية**: تفضّل ردود الملاحظات الصوتية Opus (`opus_48000_64` من ElevenLabs، و`opus` من OpenAI).
  - 48kHz / 64kbps هو توازن جيد لرسائل الصوت.
- **Feishu / WhatsApp**: عند إنتاج رد ملاحظة صوتية بصيغة MP3/WebM/WAV/M4A
  أو ملف صوتي آخر محتمل، يحوّله Plugin القناة إلى 48kHz
  Ogg/Opus باستخدام `ffmpeg` قبل إرسال رسالة الصوت الأصلية. يرسل WhatsApp
  النتيجة عبر حمولة Baileys `audio` مع `ptt: true` و
  `audio/ogg; codecs=opus`. إذا فشل التحويل، يتلقى Feishu الملف الأصلي
  كمرفق؛ ويفشل إرسال WhatsApp بدلًا من نشر حمولة PTT غير متوافقة.
- **القنوات الأخرى**: MP3 (`mp3_44100_128` من ElevenLabs، و`mp3` من OpenAI).
  - 44.1kHz / 128kbps هو التوازن الافتراضي لوضوح الكلام.
- **MiniMax**: MP3 (نموذج `speech-2.8-hd`، ومعدل عينة 32kHz) لمرفقات الصوت العادية. بالنسبة إلى أهداف الملاحظات الصوتية التي تعلنها القناة، يحوّل OpenClaw ملف MiniMax MP3 إلى 48kHz Opus باستخدام `ffmpeg` قبل التسليم عندما تعلن القناة دعم التحويل.
- **Xiaomi MiMo**: MP3 افتراضيًا، أو WAV عند تهيئته. بالنسبة إلى أهداف الملاحظات الصوتية التي تعلنها القناة، يحوّل OpenClaw مخرجات Xiaomi إلى 48kHz Opus باستخدام `ffmpeg` قبل التسليم عندما تعلن القناة دعم التحويل.
- **CLI المحلي**: يستخدم `outputFormat` المهيأ. تُحوَّل أهداف الملاحظات الصوتية إلى Ogg/Opus، وتُحوَّل مخرجات الاتصالات الهاتفية إلى PCM خام أحادي 16 kHz
  باستخدام `ffmpeg`.
- **Google Gemini**: تعيد Gemini API TTS بيانات PCM خام بمعدل 24kHz. يغلّفها OpenClaw بصيغة WAV لمرفقات الصوت، ويحوّلها إلى 48kHz Opus لأهداف الملاحظات الصوتية، ويعيد PCM مباشرةً لـ Talk/الاتصالات الهاتفية.
- **Gradium**: WAV لمرفقات الصوت، وOpus لأهداف الملاحظات الصوتية، و`ulaw_8000` عند 8 kHz للاتصالات الهاتفية.
- **Inworld**: MP3 لمرفقات الصوت العادية، و`OGG_OPUS` أصلي لأهداف الملاحظات الصوتية، و`PCM` خام عند 22050 Hz لـ Talk/الاتصالات الهاتفية.
- **xAI**: MP3 افتراضيًا؛ يمكن أن تكون `responseFormat` إحدى القيم `mp3` أو `wav` أو `pcm` أو `mulaw` أو `alaw`. يستخدم OpenClaw نقطة نهاية TTS الدُفعية عبر REST من xAI ويعيد مرفقًا صوتيًا كاملًا؛ ولا يستخدم مسار هذا المزوّد WebSocket الخاص ببث TTS من xAI. لا يدعم هذا المسار تنسيق Opus الأصلي للملاحظات الصوتية.
- **Microsoft**: يستخدم `microsoft.outputFormat` (الافتراضي `audio-24khz-48kbitrate-mono-mp3`).
  - يقبل النقل المضمّن `outputFormat`، لكن ليست كل التنسيقات متاحة من الخدمة.
  - تتبع قيم تنسيق الإخراج تنسيقات إخراج Microsoft Speech (بما في ذلك Ogg/WebM Opus).
  - يقبل Telegram `sendVoice` صيغ OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج
    إلى رسائل صوتية Opus مضمونة.
  - إذا فشل تنسيق إخراج Microsoft المهيأ، يعيد OpenClaw المحاولة باستخدام MP3.

تنسيقات إخراج OpenAI/ElevenLabs ثابتة لكل قناة (انظر أعلاه).

## سلوك Auto-TTS

عند تفعيل `messages.tts.auto`، يقوم OpenClaw بما يلي:

- يتجاوز TTS إذا كان الرد يحتوي بالفعل على وسائط منظمة.
- يتجاوز الردود القصيرة جدًا (أقل من 10 أحرف).
- يلخّص الردود الطويلة عند تفعيل الملخصات، باستخدام
  `summaryModel` (أو `agents.defaults.model.primary`).
- يرفق الصوت المُنشأ بالرد.
- في `mode: "final"`، يظل يرسل TTS صوتيًا فقط للردود النهائية المتدفقة
  بعد اكتمال تدفق النص؛ تمر الوسائط المُنشأة عبر تطبيع وسائط القناة نفسه
  المستخدم مع مرفقات الرد العادية.

إذا تجاوز الرد `maxLength` وكان التلخيص متوقفًا (أو لا يوجد مفتاح API لنموذج
التلخيص)، يتم تجاوز الصوت وإرسال الرد النصي العادي.

```text
Reply -> TTS enabled?
  no  -> send text
  yes -> has media / short?
          yes -> send text
          no  -> length > limit?
                   no  -> TTS -> attach audio
                   yes -> summary enabled?
                            no  -> send text
                            yes -> summarize -> TTS -> attach audio
```

## تنسيقات الإخراج حسب القناة

  | الهدف                                | التنسيق                                                                                                                                |
  | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
  | Feishu / Matrix / Telegram / WhatsApp | تفضّل ردود الملاحظات الصوتية **Opus** (`opus_48000_64` من ElevenLabs، و`opus` من OpenAI). يوازن 48 kHz / 64 kbps بين الوضوح والحجم. |
  | القنوات الأخرى                        | **MP3** (`mp3_44100_128` من ElevenLabs، و`mp3` من OpenAI). الإعداد الافتراضي للكلام هو 44.1 kHz / 128 kbps.                                 |
  | المحادثة / الاتصالات الهاتفية                      | **PCM** الأصلي من المزوّد (Inworld 22050 Hz، وGoogle 24 kHz)، أو `ulaw_8000` من Gradium للاتصالات الهاتفية.                                 |

  ملاحظات حسب المزوّد:

  - **تحويل ترميز Feishu / WhatsApp:** عندما يصل رد ملاحظة صوتية بصيغة MP3/WebM/WAV/M4A، يحوّل Plugin القناة الترميز إلى Ogg/Opus بتردد 48 kHz باستخدام `ffmpeg`. يرسل WhatsApp عبر Baileys مع `ptt: true` و`audio/ogg; codecs=opus`. إذا فشل التحويل: يعود Feishu إلى إرفاق الملف الأصلي؛ ويفشل إرسال WhatsApp بدلاً من نشر حمولة PTT غير متوافقة.
  - **MiniMax / Xiaomi MiMo:** MP3 افتراضيًا (32 kHz لـ MiniMax `speech-2.8-hd`)؛ ويُحوَّل ترميزه إلى Opus بتردد 48 kHz لأهداف الملاحظات الصوتية عبر `ffmpeg`.
  - **CLI المحلي:** يستخدم `outputFormat` المضبوط. تُحوَّل أهداف الملاحظات الصوتية إلى Ogg/Opus ومخرجات الاتصالات الهاتفية إلى PCM أحادي خام بتردد 16 kHz.
  - **Google Gemini:** يعيد PCM خامًا بتردد 24 kHz. يغلّفه OpenClaw كـ WAV للمرفقات، ويحوّل ترميزه إلى Opus بتردد 48 kHz لأهداف الملاحظات الصوتية، ويعيد PCM مباشرةً للمحادثة/الاتصالات الهاتفية.
  - **Inworld:** مرفقات MP3، وملاحظة صوتية أصلية `OGG_OPUS`، و`PCM` خام بتردد 22050 Hz للمحادثة/الاتصالات الهاتفية.
  - **xAI:** MP3 افتراضيًا؛ يمكن أن تكون `responseFormat` هي `mp3|wav|pcm|mulaw|alaw`. يستخدم نقطة نهاية REST الدُفعية الخاصة بـ xAI — ولا يُستخدم WebSocket TTS للبث **مطلقًا**. تنسيق الملاحظات الصوتية الأصلي Opus **غير** مدعوم.
  - **Microsoft:** يستخدم `microsoft.outputFormat` (الافتراضي `audio-24khz-48kbitrate-mono-mp3`). يقبل `sendVoice` في Telegram صيغ OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج إلى رسائل صوتية Opus مضمونة. إذا فشل تنسيق Microsoft المضبوط، يعيد OpenClaw المحاولة باستخدام MP3.

  تنسيقات مخرجات OpenAI وElevenLabs ثابتة لكل قناة كما هو مذكور أعلاه.

  ## مرجع الحقول

  <AccordionGroup>
  <Accordion title="رسائل المستوى الأعلى messages.tts.*">
    <ParamField path="auto" type='"off" | "always" | "inbound" | "tagged"'>
      وضع TTS التلقائي. يرسل `inbound` الصوت فقط بعد رسالة صوتية واردة؛ ويرسل `tagged` الصوت فقط عندما يتضمن الرد توجيهات `[[tts:...]]` أو كتلة `[[tts:text]]`.
    </ParamField>
    <ParamField path="enabled" type="boolean" deprecated>
      مفتاح تبديل قديم. يرحّل `openclaw doctor --fix` هذا إلى `auto`.
    </ParamField>
    <ParamField path="mode" type='"final" | "all"' default="final">
      يتضمن `"all"` ردود الأدوات/الكتل بالإضافة إلى الردود النهائية.
    </ParamField>
    <ParamField path="provider" type="string">
      معرّف مزوّد الكلام. عند عدم تعيينه، يستخدم OpenClaw أول مزوّد مضبوط في ترتيب الاختيار التلقائي للسجل. يُعاد كتابة `provider: "edge"` القديم إلى `"microsoft"` بواسطة `openclaw doctor --fix`.
    </ParamField>
    <ParamField path="persona" type="string">
      معرّف الشخصية النشطة من `personas`. يُطبّع إلى أحرف صغيرة.
    </ParamField>
    <ParamField path="personas.<id>" type="object">
      هوية منطوقة مستقرة. الحقول: `label` و`description` و`provider` و`fallbackPolicy` و`prompt` و`providers.<provider>`. راجع [الشخصيات](#personas).
    </ParamField>
    <ParamField path="summaryModel" type="string">
      نموذج منخفض التكلفة للملخص التلقائي؛ يكون افتراضيًا `agents.defaults.model.primary`. يقبل `provider/model` أو اسمًا مستعارًا لنموذج مضبوط.
    </ParamField>
    <ParamField path="modelOverrides" type="object">
      يسمح للنموذج بإصدار توجيهات TTS. تكون قيمة `enabled` الافتراضية `true`؛ وتكون قيمة `allowProvider` الافتراضية `false`.
    </ParamField>
    <ParamField path="providers.<id>" type="object">
      إعدادات مملوكة للمزوّد ومفهرسة حسب معرّف مزوّد الكلام. يعيد `openclaw doctor --fix` كتابة الكتل المباشرة القديمة (`messages.tts.openai` و`.elevenlabs` و`.microsoft` و`.edge`)؛ لا تثبّت إلا `messages.tts.providers.<id>`.
    </ParamField>
    <ParamField path="maxTextLength" type="number">
      حد صارم لعدد أحرف إدخال TTS. يفشل `/tts audio` إذا تم تجاوزه.
    </ParamField>
    <ParamField path="timeoutMs" type="number">
      مهلة الطلب بالميلي ثانية.
    </ParamField>
    <ParamField path="prefsPath" type="string">
      يتجاوز مسار JSON المحلي للتفضيلات (المزوّد/الحد/الملخص). الافتراضي `~/.openclaw/settings/tts.json`.
    </ParamField>
  </Accordion>

  <Accordion title="Azure Speech">
    <ParamField path="apiKey" type="string">Env: `AZURE_SPEECH_KEY` أو `AZURE_SPEECH_API_KEY` أو `SPEECH_KEY`.</ParamField>
    <ParamField path="region" type="string">منطقة Azure Speech (مثل `eastus`). Env: `AZURE_SPEECH_REGION` أو `SPEECH_REGION`.</ParamField>
    <ParamField path="endpoint" type="string">تجاوز اختياري لنقطة نهاية Azure Speech (الاسم المستعار `baseUrl`).</ParamField>
    <ParamField path="speakerVoice" type="string">ShortName لصوت Azure. الافتراضي `en-US-JennyNeural`. الاسم المستعار القديم: `voice`.</ParamField>
    <ParamField path="lang" type="string">رمز لغة SSML. الافتراضي `en-US`.</ParamField>
    <ParamField path="outputFormat" type="string">قيمة Azure `X-Microsoft-OutputFormat` للصوت القياسي. الافتراضي `audio-24khz-48kbitrate-mono-mp3`.</ParamField>
    <ParamField path="voiceNoteOutputFormat" type="string">قيمة Azure `X-Microsoft-OutputFormat` لمخرجات الملاحظات الصوتية. الافتراضي `ogg-24khz-16bit-mono-opus`.</ParamField>
  </Accordion>

  <Accordion title="ElevenLabs">
    <ParamField path="apiKey" type="string">يعود احتياطيًا إلى `ELEVENLABS_API_KEY` أو `XI_API_KEY`.</ParamField>
    <ParamField path="model" type="string">معرّف النموذج (مثل `eleven_multilingual_v2` و`eleven_v3`).</ParamField>
    <ParamField path="speakerVoiceId" type="string">معرّف صوت ElevenLabs. الاسم المستعار القديم: `voiceId`.</ParamField>
    <ParamField path="voiceSettings" type="object">
      `stability` و`similarityBoost` و`style` (كل منها `0..1`) و`useSpeakerBoost` (`true|false`) و`speed` (`0.5..2.0`، `1.0` = عادي).
    </ParamField>
    <ParamField path="applyTextNormalization" type='"auto" | "on" | "off"'>وضع تطبيع النص.</ParamField>
    <ParamField path="languageCode" type="string">رمز ISO 639-1 مكوّن من حرفين (مثل `en` و`de`).</ParamField>
    <ParamField path="seed" type="number">عدد صحيح `0..4294967295` لتحقيق حتمية بأفضل جهد.</ParamField>
    <ParamField path="baseUrl" type="string">تجاوز عنوان URL الأساسي لواجهة ElevenLabs API.</ParamField>
  </Accordion>

  <Accordion title="Google Gemini">
    <ParamField path="apiKey" type="string">يعود احتياطيًا إلى `GEMINI_API_KEY` / `GOOGLE_API_KEY`. إذا حُذف، يمكن لـ TTS إعادة استخدام `models.providers.google.apiKey` قبل الرجوع الاحتياطي إلى Env.</ParamField>
    <ParamField path="model" type="string">نموذج Gemini TTS. الافتراضي `gemini-3.1-flash-tts-preview`.</ParamField>
    <ParamField path="speakerVoice" type="string">اسم صوت Gemini مسبق الإنشاء. الافتراضي `Kore`. الأسماء المستعارة القديمة: `voiceName` و`voice`.</ParamField>
    <ParamField path="audioProfile" type="string">موجه أسلوب بلغة طبيعية يُضاف قبل النص المنطوق.</ParamField>
    <ParamField path="speakerName" type="string">تسمية اختيارية للمتحدث تُضاف قبل النص المنطوق عندما يستخدم الموجه متحدثًا مسمى.</ParamField>
    <ParamField path="promptTemplate" type='"audio-profile-v1"'>عيّنه إلى `audio-profile-v1` لتغليف حقول موجه الشخصية النشطة في بنية موجه Gemini TTS حتمية.</ParamField>
    <ParamField path="personaPrompt" type="string">نص موجه شخصية إضافي خاص بـ Google يُلحق بملاحظات المدير في القالب.</ParamField>
    <ParamField path="baseUrl" type="string">لا يُقبل إلا `https://generativelanguage.googleapis.com`.</ParamField>
  </Accordion>

  <Accordion title="Gradium">
    <ParamField path="apiKey" type="string">البيئة: `GRADIUM_API_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://api.gradium.ai`.</ParamField>
    <ParamField path="speakerVoiceId" type="string">القيمة الافتراضية Emma (`YTpq7expH9539ERJ`). الاسم البديل القديم: `voiceId`.</ParamField>
  </Accordion>

  <Accordion title="Inworld">
    ### Inworld الأساسي

    <ParamField path="apiKey" type="string">البيئة: `INWORLD_API_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://api.inworld.ai`.</ParamField>
    <ParamField path="modelId" type="string">القيمة الافتراضية `inworld-tts-1.5-max`. أيضًا: `inworld-tts-1.5-mini`، `inworld-tts-1-max`، `inworld-tts-1`.</ParamField>
    <ParamField path="speakerVoiceId" type="string">القيمة الافتراضية `Sarah`. الاسم البديل القديم: `voiceId`.</ParamField>
    <ParamField path="temperature" type="number">درجة حرارة أخذ العينات `0..2`.</ParamField>

  </Accordion>

  <Accordion title="Local CLI (tts-local-cli)">
    <ParamField path="command" type="string">ملف تنفيذي محلي أو سلسلة أمر لتحويل النص إلى كلام عبر CLI.</ParamField>
    <ParamField path="args" type="string[]">وسائط الأمر. تدعم العناصر النائبة `{{Text}}` و`{{OutputPath}}` و`{{OutputDir}}` و`{{OutputBase}}`.</ParamField>
    <ParamField path="outputFormat" type='"mp3" | "opus" | "wav"'>تنسيق مخرجات CLI المتوقع. القيمة الافتراضية `mp3` لمرفقات الصوت.</ParamField>
    <ParamField path="timeoutMs" type="number">مهلة الأمر بالمللي ثانية. القيمة الافتراضية `120000`.</ParamField>
    <ParamField path="cwd" type="string">دليل العمل الاختياري للأمر.</ParamField>
    <ParamField path="env" type="Record<string, string>">تجاوزات بيئية اختيارية للأمر.</ParamField>
  </Accordion>

  <Accordion title="Microsoft (no API key)">
    <ParamField path="enabled" type="boolean" default="true">السماح باستخدام الكلام من Microsoft.</ParamField>
    <ParamField path="speakerVoice" type="string">اسم الصوت العصبي في Microsoft (مثل `en-US-MichelleNeural`). الاسم البديل القديم: `voice`.</ParamField>
    <ParamField path="lang" type="string">رمز اللغة (مثل `en-US`).</ParamField>
    <ParamField path="outputFormat" type="string">تنسيق مخرجات Microsoft. القيمة الافتراضية `audio-24khz-48kbitrate-mono-mp3`. لا يدعم النقل المضمن المستند إلى Edge جميع التنسيقات.</ParamField>
    <ParamField path="rate / pitch / volume" type="string">سلاسل نسب مئوية (مثل `+10%` و`-5%`).</ParamField>
    <ParamField path="saveSubtitles" type="boolean">كتابة ترجمات JSON بجانب ملف الصوت.</ParamField>
    <ParamField path="proxy" type="string">عنوان URL للوكيل لطلبات الكلام من Microsoft.</ParamField>
    <ParamField path="timeoutMs" type="number">تجاوز مهلة الطلب (مللي ثانية).</ParamField>
    <ParamField path="edge.*" type="object" deprecated>اسم بديل قديم. شغّل `openclaw doctor --fix` لإعادة كتابة الإعدادات المحفوظة إلى `providers.microsoft`.</ParamField>
  </Accordion>

  <Accordion title="MiniMax">
    <ParamField path="apiKey" type="string">يرجع إلى `MINIMAX_API_KEY`. مصادقة Token Plan عبر `MINIMAX_OAUTH_TOKEN` أو `MINIMAX_CODE_PLAN_KEY` أو `MINIMAX_CODING_API_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://api.minimax.io`. البيئة: `MINIMAX_API_HOST`.</ParamField>
    <ParamField path="model" type="string">القيمة الافتراضية `speech-2.8-hd`. البيئة: `MINIMAX_TTS_MODEL`.</ParamField>
    <ParamField path="speakerVoiceId" type="string">القيمة الافتراضية `English_expressive_narrator`. البيئة: `MINIMAX_TTS_VOICE_ID`. الاسم البديل القديم: `voiceId`.</ParamField>
    <ParamField path="speed" type="number">`0.5..2.0`. القيمة الافتراضية `1.0`.</ParamField>
    <ParamField path="vol" type="number">`(0, 10]`. القيمة الافتراضية `1.0`.</ParamField>
    <ParamField path="pitch" type="number">عدد صحيح `-12..12`. القيمة الافتراضية `0`. تُقتطع القيم الكسرية قبل الطلب.</ParamField>
  </Accordion>

  <Accordion title="OpenAI">
    <ParamField path="apiKey" type="string">يرجع إلى `OPENAI_API_KEY`.</ParamField>
    <ParamField path="model" type="string">معرّف نموذج تحويل النص إلى كلام في OpenAI (مثل `gpt-4o-mini-tts`).</ParamField>
    <ParamField path="speakerVoice" type="string">اسم الصوت (مثل `alloy` و`cedar`). الاسم البديل القديم: `voice`.</ParamField>
    <ParamField path="instructions" type="string">حقل `instructions` صريح من OpenAI. عند تعيينه، **لا** تُربط حقول موجه الشخصية تلقائيًا.</ParamField>
    <ParamField path="extraBody / extra_body" type="Record<string, unknown>">حقول JSON إضافية تُدمج في أجسام طلبات `/audio/speech` بعد حقول تحويل النص إلى كلام المولدة من OpenAI. استخدم هذا لنقاط النهاية المتوافقة مع OpenAI مثل Kokoro التي تتطلب مفاتيح خاصة بالمزوّد مثل `lang`؛ يتم تجاهل مفاتيح النماذج الأولية غير الآمنة.</ParamField>
    <ParamField path="baseUrl" type="string">
      تجاوز نقطة نهاية تحويل النص إلى كلام في OpenAI. ترتيب الحل: الإعدادات → `OPENAI_TTS_BASE_URL` → `https://api.openai.com/v1`. تُعامل القيم غير الافتراضية كنقاط نهاية لتحويل النص إلى كلام متوافقة مع OpenAI، لذلك تُقبل أسماء النماذج والأصوات المخصصة.
    </ParamField>
  </Accordion>

  <Accordion title="OpenRouter">
    <ParamField path="apiKey" type="string">البيئة: `OPENROUTER_API_KEY`. يمكن إعادة استخدام `models.providers.openrouter.apiKey`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://openrouter.ai/api/v1`. يتم تطبيع `https://openrouter.ai/v1` القديم.</ParamField>
    <ParamField path="model" type="string">القيمة الافتراضية `hexgrad/kokoro-82m`. الاسم البديل: `modelId`.</ParamField>
    <ParamField path="speakerVoice" type="string">القيمة الافتراضية `af_alloy`. الأسماء البديلة القديمة: `voice` و`voiceId`.</ParamField>
    <ParamField path="responseFormat" type='"mp3" | "pcm"'>القيمة الافتراضية `mp3`.</ParamField>
    <ParamField path="speed" type="number">تجاوز السرعة الأصلي لدى المزوّد.</ParamField>
  </Accordion>

  <Accordion title="Volcengine (BytePlus Seed Speech)">
    <ParamField path="apiKey" type="string">البيئة: `VOLCENGINE_TTS_API_KEY` أو `BYTEPLUS_SEED_SPEECH_API_KEY`.</ParamField>
    <ParamField path="resourceId" type="string">القيمة الافتراضية `seed-tts-1.0`. البيئة: `VOLCENGINE_TTS_RESOURCE_ID`. استخدم `seed-tts-2.0` عندما يكون لمشروعك استحقاق TTS 2.0.</ParamField>
    <ParamField path="appKey" type="string">ترويسة مفتاح التطبيق. القيمة الافتراضية `aGjiRDfUWi`. البيئة: `VOLCENGINE_TTS_APP_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">تجاوز نقطة نهاية HTTP لتحويل النص إلى كلام في Seed Speech. البيئة: `VOLCENGINE_TTS_BASE_URL`.</ParamField>
    <ParamField path="speakerVoice" type="string">نوع الصوت. القيمة الافتراضية `en_female_anna_mars_bigtts`. البيئة: `VOLCENGINE_TTS_VOICE`. الاسم البديل القديم: `voice`.</ParamField>
    <ParamField path="speedRatio" type="number">نسبة السرعة الأصلية لدى المزوّد.</ParamField>
    <ParamField path="emotion" type="string">وسم العاطفة الأصلي لدى المزوّد.</ParamField>
    <ParamField path="appId / token / cluster" type="string" deprecated>حقول Volcengine Speech Console القديمة. البيئة: `VOLCENGINE_TTS_APPID` و`VOLCENGINE_TTS_TOKEN` و`VOLCENGINE_TTS_CLUSTER` (القيمة الافتراضية `volcano_tts`).</ParamField>
  </Accordion>

  <Accordion title="xAI">
    <ParamField path="apiKey" type="string">البيئة: `XAI_API_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://api.x.ai/v1`. البيئة: `XAI_BASE_URL`.</ParamField>
    <ParamField path="speakerVoiceId" type="string">القيمة الافتراضية `eve`. الأصوات الحية: `ara` و`eve` و`leo` و`rex` و`sal` و`una`. الاسم البديل القديم: `voiceId`.</ParamField>
    <ParamField path="language" type="string">رمز لغة BCP-47 أو `auto`. القيمة الافتراضية `en`.</ParamField>
    <ParamField path="responseFormat" type='"mp3" | "wav" | "pcm" | "mulaw" | "alaw"'>القيمة الافتراضية `mp3`.</ParamField>
    <ParamField path="speed" type="number">تجاوز السرعة الأصلي لدى المزوّد.</ParamField>
  </Accordion>

  <Accordion title="Xiaomi MiMo">
    <ParamField path="apiKey" type="string">البيئة: `XIAOMI_API_KEY`.</ParamField>
    <ParamField path="baseUrl" type="string">القيمة الافتراضية `https://api.xiaomimimo.com/v1`. البيئة: `XIAOMI_BASE_URL`.</ParamField>
    <ParamField path="model" type="string">القيمة الافتراضية `mimo-v2.5-tts`. البيئة: `XIAOMI_TTS_MODEL`. يدعم أيضًا `mimo-v2-tts` و`mimo-v2.5-tts-voicedesign`.</ParamField>
    <ParamField path="speakerVoice" type="string">القيمة الافتراضية `mimo_default` لنماذج الصوت المسبق الضبط. البيئة: `XIAOMI_TTS_VOICE`. الاسم البديل القديم: `voice`. لا يُرسل لـ `mimo-v2.5-tts-voicedesign`.</ParamField>
    <ParamField path="format" type='"mp3" | "wav"'>القيمة الافتراضية `mp3`. البيئة: `XIAOMI_TTS_FORMAT`.</ParamField>
    <ParamField path="style" type="string">تعليمة نمط اختيارية بلغة طبيعية تُرسل كرسالة المستخدم؛ لا تُنطق. بالنسبة إلى `mimo-v2.5-tts-voicedesign`، يكون هذا موجه تصميم الصوت؛ يوفّر OpenClaw قيمة افتراضية عند حذفه.</ParamField>
  </Accordion>
</AccordionGroup>

## أداة الوكيل

تحوّل أداة `tts` النص إلى كلام وتعيد مرفقًا صوتيًا لتسليم الرد.
في Feishu وMatrix وTelegram وWhatsApp، يُسلّم الصوت كرسالة صوتية بدلًا من مرفق ملف. يمكن لـ Feishu وWhatsApp تحويل مخرجات تحويل النص إلى كلام غير Opus في هذا المسار عندما يكون `ffmpeg` متاحًا.

يرسل WhatsApp الصوت عبر Baileys كملاحظة صوتية PTT (`audio` مع
`ptt: true`) ويرسل النص المرئي **بشكل منفصل** عن صوت PTT لأن
العملاء لا يعرضون التسميات التوضيحية على الملاحظات الصوتية بشكل متسق.

تقبل الأداة حقلي `channel` و`timeoutMs` اختياريًا؛ `timeoutMs` هو
مهلة طلب المزوّد لكل استدعاء بالمللي ثانية. تتجاوز قيم كل استدعاء
`messages.tts.timeoutMs`؛ وتتجاوز مُهل تحويل النص إلى كلام المضبوطة أي
قيمة افتراضية للمزوّد كتبها Plugin.

## Gateway RPC

| الطريقة           | الغرض                                      |
| ----------------- | ------------------------------------------ |
| `tts.status`      | قراءة حالة تحويل النص إلى كلام الحالية وآخر محاولة. |
| `tts.enable`      | تعيين تفضيل التشغيل التلقائي المحلي إلى `always`. |
| `tts.disable`     | تعيين تفضيل التشغيل التلقائي المحلي إلى `off`. |
| `tts.convert`     | تحويل نص لمرة واحدة → صوت.                |
| `tts.setProvider` | تعيين تفضيل المزوّد المحلي.               |
| `tts.setPersona`  | تعيين تفضيل الشخصية المحلي.               |
| `tts.providers`   | سرد المزوّدين المضبوطين وحالاتهم.         |

## روابط الخدمة

- [دليل تحويل النص إلى كلام في OpenAI](https://platform.openai.com/docs/guides/text-to-speech)
- [مرجع واجهة برمجة تطبيقات الصوت في OpenAI](https://platform.openai.com/docs/api-reference/audio)
- [تحويل النص إلى كلام عبر REST في Azure Speech](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech)
- [مزوّد Azure Speech](/ar/providers/azure-speech)
- [تحويل النص إلى كلام في ElevenLabs](https://elevenlabs.io/docs/api-reference/text-to-speech)
- [مصادقة ElevenLabs](https://elevenlabs.io/docs/api-reference/authentication)
- [Gradium](/ar/providers/gradium)
- [واجهة برمجة تطبيقات تحويل النص إلى كلام في Inworld](https://docs.inworld.ai/tts/tts)
- [واجهة برمجة تطبيقات MiniMax T2A v2](https://platform.minimaxi.com/document/T2A%20V2)
- [واجهة برمجة تطبيقات HTTP لتحويل النص إلى كلام في Volcengine](/ar/providers/volcengine#text-to-speech)
- [تركيب الكلام في Xiaomi MiMo](/ar/providers/xiaomi#text-to-speech)
- [node-edge-tts](https://github.com/SchneeHertz/node-edge-tts)
- [تنسيقات مخرجات الكلام في Microsoft](https://learn.microsoft.com/azure/ai-services/speech-service/rest-text-to-speech#audio-outputs)
- [تحويل النص إلى كلام في xAI](https://docs.x.ai/developers/rest-api-reference/inference/voice#text-to-speech-rest)

## ذو صلة

- [نظرة عامة على الوسائط](/ar/tools/media-overview)
- [توليد الموسيقى](/ar/tools/music-generation)
- [توليد الفيديو](/ar/tools/video-generation)
- [أوامر Slash](/ar/tools/slash-commands)
- [Plugin المكالمات الصوتية](/ar/plugins/voice-call)