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

​

البدء السريع

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

​

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

​

التكوين

{
  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",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
      providers: {
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  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",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "gradium",
      providers: {
        gradium: {
          apiKey: "${GRADIUM_API_KEY}",
          speakerVoiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          speakerVoiceId: "Sarah",
          temperature: 0.7,
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "tts-local-cli",
      providers: {
        "tts-local-cli": {
          command: "say",
          args: ["-o", "{{OutputPath}}", "{{Text}}"],
          outputFormat: "wav",
          timeoutMs: 120000,
        },
      },
    },
  },
}

{
  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%",
        },
      },
    },
  },
}

{
  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,
        },
      },
    },
  },
}

{
  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",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "openrouter",
      providers: {
        openrouter: {
          apiKey: "${OPENROUTER_API_KEY}",
          model: "hexgrad/kokoro-82m",
          speakerVoice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "volcengine",
      providers: {
        volcengine: {
          apiKey: "${VOLCENGINE_TTS_API_KEY}",
          resourceId: "seed-tts-1.0",
          speakerVoice: "en_female_anna_mars_bigtts",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xai",
      providers: {
        xai: {
          apiKey: "${XAI_API_KEY}",
          speakerVoiceId: "eve",
          language: "en",
          responseFormat: "mp3",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          speakerVoice: "mimo_default",
          format: "mp3",
        },
      },
    },
  },
}

​

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

{
  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" },
          },
        },
      },
    ],
  },
}

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

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

​

الشخصيات

​

شخصية مبسطة

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

​

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

{
  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. الاختيار التلقائي من السجل.

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

​

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

​

سياسة الرجوع

​

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

Here you go.

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

• 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

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

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

​

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

/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>

• يكتب /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 مفعلًا.

​

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

​

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

• القنوات القادرة على الملاحظات الصوتية: تفضّل ردود الملاحظات الصوتية 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.

​

سلوك Auto-TTS

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

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 / 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.

​

مرجع الحقول

​

أداة الوكيل

​

Gateway RPC

​

روابط الخدمة

• دليل تحويل النص إلى كلام في OpenAI
• مرجع واجهة برمجة تطبيقات الصوت في OpenAI
• تحويل النص إلى كلام عبر REST في Azure Speech
• مزوّد Azure Speech
• تحويل النص إلى كلام في ElevenLabs
• مصادقة ElevenLabs
• Gradium
• واجهة برمجة تطبيقات تحويل النص إلى كلام في Inworld
• واجهة برمجة تطبيقات MiniMax T2A v2
• واجهة برمجة تطبيقات HTTP لتحويل النص إلى كلام في Volcengine
• تركيب الكلام في Xiaomi MiMo
• node-edge-tts
• تنسيقات مخرجات الكلام في Microsoft
• تحويل النص إلى كلام في xAI

​

ذو صلة

• نظرة عامة على الوسائط
• توليد الموسيقى
• توليد الفيديو
• أوامر Slash
• Plugin المكالمات الصوتية