​

تحويل النص إلى كلام (TTS)

​

الخدمات المدعومة

• ElevenLabs (موفّر أساسي أو احتياطي)
• Microsoft (موفّر أساسي أو احتياطي؛ يستخدم التنفيذ المضمّن الحالي node-edge-tts)
• MiniMax (موفّر أساسي أو احتياطي؛ يستخدم API ‏T2A v2)
• OpenAI (موفّر أساسي أو احتياطي؛ ويُستخدم أيضًا للملخصات)

​

ملاحظات حول Microsoft speech

​

المفاتيح الاختيارية

• ELEVENLABS_API_KEY (أو XI_API_KEY)
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

روابط الخدمات

• دليل OpenAI لتحويل النص إلى كلام
• مرجع OpenAI Audio API
• تحويل النص إلى كلام في ElevenLabs
• المصادقة في ElevenLabs
• MiniMax T2A v2 API
• node-edge-tts
• تنسيقات إخراج Microsoft Speech

​

هل هو مفعّل افتراضيًا؟

​

التكوين

​

الحد الأدنى من التكوين (تفعيل + موفّر)

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

​

OpenAI أساسي مع ElevenLabs احتياطي

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

​

Microsoft أساسي (من دون مفتاح API)

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          voice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

​

MiniMax أساسي

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

​

تعطيل Microsoft speech

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

​

حدود مخصصة + مسار التفضيلات

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

​

الرد بالصوت فقط بعد رسالة صوتية واردة

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

​

تعطيل التلخيص التلقائي للردود الطويلة

{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

/tts summary off

​

ملاحظات حول الحقول

• auto: وضع Auto‑TTS (off أو always أو inbound أو tagged).
  • inbound يرسل الصوت فقط بعد رسالة صوتية واردة.
  • tagged يرسل الصوت فقط عندما يتضمن الرد وسوم [[tts]].
• enabled: مفتاح قديم (ينقل doctor هذا إلى auto).
• mode: "final" (الافتراضي) أو "all" (يتضمن ردود الأدوات/الكتل).
• provider: معرّف موفّر speech مثل "elevenlabs" أو "microsoft" أو "minimax" أو "openai" (والاحتياطي تلقائي).
• إذا كان provider غير مضبوط، يستخدم OpenClaw أول موفّر speech مُهيأ وفق ترتيب الاختيار التلقائي في السجل.
• ما زال provider: "edge" القديم يعمل ويُطبَّع إلى microsoft.
• summaryModel: نموذج منخفض الكلفة اختياري للتلخيص التلقائي؛ والإعداد الافتراضي هو agents.defaults.model.primary.
  • يقبل provider/model أو اسمًا مستعارًا لنموذج مُهيأ.
• modelOverrides: السماح للنموذج بإصدار توجيهات TTS (مفعّل افتراضيًا).
  • تكون القيمة الافتراضية لـ allowProvider هي false (تبديل الموفّر يتطلب تفعيلًا صريحًا).
• providers.<id>: إعدادات مملوكة للموفّر ومفهرسة حسب معرّف موفّر speech.
• تُرحَّل تلقائيًا كتل الموفّرين المباشرة القديمة (messages.tts.openai وmessages.tts.elevenlabs وmessages.tts.microsoft وmessages.tts.edge) إلى messages.tts.providers.<id> عند التحميل.
• maxTextLength: حد صارم لإدخال TTS (عدد الأحرف). يفشل /tts audio إذا جرى تجاوزه.
• timeoutMs: مهلة الطلب (مللي ثانية).
• prefsPath: تجاوز لمسار JSON المحلي للتفضيلات (الموفّر/الحد/التلخيص).
• ترجع قيم apiKey إلى متغيرات البيئة (ELEVENLABS_API_KEY/XI_API_KEY وMINIMAX_API_KEY وOPENAI_API_KEY).
• providers.elevenlabs.baseUrl: تجاوز عنوان URL الأساسي لـ API الخاص بـ ElevenLabs.
• providers.openai.baseUrl: تجاوز نقطة نهاية OpenAI TTS.
  • ترتيب التحليل: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • تُعامَل القيم غير الافتراضية على أنها نقاط نهاية TTS متوافقة مع OpenAI، لذلك تُقبل أسماء النماذج والأصوات المخصصة.
• providers.elevenlabs.voiceSettings:
  • stability وsimilarityBoost وstyle: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0 (1.0 = عادي)
• providers.elevenlabs.applyTextNormalization: ‏auto|on|off
• providers.elevenlabs.languageCode: رمز ISO 639-1 من حرفين (مثل en وde)
• providers.elevenlabs.seed: عدد صحيح 0..4294967295 (حتمية بأفضل جهد)
• providers.minimax.baseUrl: تجاوز عنوان URL الأساسي لـ MiniMax API (الافتراضي https://api.minimax.io، ومتغير البيئة: MINIMAX_API_HOST).
• providers.minimax.model: نموذج TTS (الافتراضي speech-2.8-hd، ومتغير البيئة: MINIMAX_TTS_MODEL).
• providers.minimax.voiceId: معرّف الصوت (الافتراضي English_expressive_narrator، ومتغير البيئة: MINIMAX_TTS_VOICE_ID).
• providers.minimax.speed: سرعة التشغيل 0.5..2.0 (الافتراضي 1.0).
• providers.minimax.vol: مستوى الصوت (0, 10] (الافتراضي 1.0؛ ويجب أن يكون أكبر من 0).
• providers.minimax.pitch: إزاحة الطبقة الصوتية -12..12 (الافتراضي 0).
• providers.microsoft.enabled: السماح باستخدام Microsoft speech (الافتراضي true؛ من دون مفتاح API).
• providers.microsoft.voice: اسم الصوت العصبي من Microsoft (مثل en-US-MichelleNeural).
• providers.microsoft.lang: رمز اللغة (مثل en-US).
• providers.microsoft.outputFormat: تنسيق إخراج Microsoft (مثل audio-24khz-48kbitrate-mono-mp3).
  • راجع تنسيقات إخراج Microsoft Speech لمعرفة القيم الصالحة؛ ليست كل التنسيقات مدعومة بواسطة وسيلة النقل المضمّنة المعتمدة على Edge.
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: سلاسل نسب مئوية (مثل +10% و-5%).
• providers.microsoft.saveSubtitles: كتابة ترجمات JSON إلى جانب الملف الصوتي.
• providers.microsoft.proxy: عنوان URL للبروكسي لطلبات Microsoft speech.
• providers.microsoft.timeoutMs: تجاوز مهلة الطلب (مللي ثانية).
• edge.*: اسم مستعار قديم لإعدادات Microsoft نفسها.

​

التجاوزات المدفوعة بالنموذج (مفعّلة افتراضيًا)

Here you go.

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

• provider (معرّف موفّر speech مُسجّل، مثل openai أو elevenlabs أو minimax أو microsoft؛ ويتطلب allowProvider: true)
• voice (صوت OpenAI) أو voiceId (ElevenLabs / MiniMax)
• model (نموذج OpenAI TTS، أو معرّف نموذج ElevenLabs، أو نموذج MiniMax)
• stability وsimilarityBoost وstyle وspeed وuseSpeakerBoost
• vol / volume (مستوى صوت MiniMax، من 0 إلى 10)
• pitch (طبقة MiniMax، من -12 إلى 12)
• applyTextNormalization (auto|on|off)
• languageCode (ISO 639-1)
• seed

{
  messages: {
    tts: {
      modelOverrides: {
        enabled: false,
      },
    },
  },
}

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

​

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

• enabled
• provider
• maxLength (عتبة التلخيص؛ الافتراضي 1500 حرفًا)
• summarize (الافتراضي true)

​

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

• Feishu / Matrix / Telegram / WhatsApp: رسالة صوتية Opus (opus_48000_64 من ElevenLabs، وopus من OpenAI).
  • يُعد 48kHz / 64kbps توازنًا جيدًا للرسائل الصوتية.
• القنوات الأخرى: MP3 (mp3_44100_128 من ElevenLabs، وmp3 من OpenAI).
  • يُعد 44.1kHz / 128kbps التوازن الافتراضي لوضوح الكلام.
• MiniMax: ‏MP3 (نموذج speech-2.8-hd، ومعدل عينة 32kHz). لا يُدعَم تنسيق الملاحظات الصوتية أصلاً؛ استخدم OpenAI أو ElevenLabs إذا كنت تحتاج إلى رسائل صوتية Opus مضمونة.
• Microsoft: يستخدم microsoft.outputFormat (الافتراضي audio-24khz-48kbitrate-mono-mp3).
  • تقبل وسيلة النقل المضمّنة قيمة outputFormat، لكن ليست كل التنسيقات متاحة من الخدمة.
  • تتبع قيم تنسيق الإخراج تنسيقات إخراج Microsoft Speech (بما في ذلك Ogg/WebM Opus).
  • يقبل sendVoice في Telegram ملفات OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج إلى رسائل صوتية Opus مضمونة.
  • إذا فشل تنسيق إخراج Microsoft المُهيأ، يعيد OpenClaw المحاولة باستخدام MP3.

​

سلوك Auto-TTS

• يتخطى TTS إذا كان الرد يحتوي بالفعل على وسائط أو توجيه MEDIA:.
• يتخطى الردود القصيرة جدًا (أقل من 10 أحرف).
• يلخّص الردود الطويلة عند التفعيل باستخدام agents.defaults.model.primary (أو summaryModel).
• يرفق الصوت المُولَّد بالرد.

​

مخطط التدفق

الرد -> هل TTS مفعّل؟
  لا  -> أرسل النص
  نعم -> هل توجد وسائط / MEDIA: / هل الرد قصير؟
          نعم -> أرسل النص
          لا  -> هل الطول > الحد؟
                   لا  -> TTS -> أرفق الصوت
                   نعم -> هل التلخيص مفعّل؟
                            لا  -> أرسل النص
                            نعم -> لخّص (summaryModel أو agents.defaults.model.primary)
                                      -> TTS -> أرفق الصوت

​

استخدام أوامر Slash

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

• تتطلب الأوامر مرسلًا مصرّحًا له (وما زالت قواعد allowlist/المالك سارية).
• يجب أن يكون commands.text أو تسجيل الأوامر الأصلية مفعّلًا.
• off|always|inbound|tagged هي مفاتيح تبديل لكل جلسة (/tts on اسم مستعار لـ /tts always).
• يُخزَّن limit وsummary في التفضيلات المحلية، وليس في التكوين الرئيسي.
• يولّد /tts audio ردًا صوتيًا لمرة واحدة (ولا يفعّل TTS).
• يتضمن /tts status إظهارًا للاحتياطي لآخر محاولة:
  • احتياطي ناجح: Fallback: <primary> -> <used> بالإضافة إلى Attempts: ...
  • فشل: Error: ... بالإضافة إلى Attempts: ...
  • تشخيصات مفصلة: Attempt details: provider:outcome(reasonCode) latency
• تتضمن إخفاقات API الخاصة بـ OpenAI وElevenLabs الآن تفاصيل الخطأ التي جرى تحليلها ومعرّف الطلب (عند إرجاعه من الموفّر)، ويجري إظهار ذلك في أخطاء/سجلات TTS.

​

أداة الوكيل

​

Gateway RPC

• tts.status
• tts.enable
• tts.disable
• tts.convert
• tts.setProvider
• tts.providers