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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

البدء السريع

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

​

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

​

الإعداد

{
  messages: {
    tts: {
      auto: "always",
      provider: "azure-speech",
      providers: {
        "azure-speech": {
          apiKey: "${AZURE_SPEECH_KEY}",
          region: "eastus",
          voice: "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",
          voiceId: "EXAVITQu4vr4xnSDxMaL",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "google",
      providers: {
        google: {
          apiKey: "${GEMINI_API_KEY}",
          model: "gemini-3.1-flash-tts-preview",
          voiceName: "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}",
          voiceId: "YTpq7expH9539ERJ",
        },
      },
    },
  },
}

{
  messages: {
    tts: {
      auto: "always",
      provider: "inworld",
      providers: {
        inworld: {
          apiKey: "${INWORLD_API_KEY}",
          modelId: "inworld-tts-1.5-max",
          voiceId: "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,
          voice: "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",
          voiceId: "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",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "${ELEVENLABS_API_KEY}",
          model: "eleven_multilingual_v2",
          voiceId: "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",
          voice: "af_alloy",
          responseFormat: "mp3",
        },
      },
    },
  },
}

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

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

{
  messages: {
    tts: {
      auto: "always",
      provider: "xiaomi",
      providers: {
        xiaomi: {
          apiKey: "${XIAOMI_API_KEY}",
          model: "mimo-v2.5-tts",
          voice: "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: { voiceId: "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: { voice: "shimmer" },
            },
          },
        },
      },
    },
  },
}

​

الشخصيات

​

شخصية بسيطة

{
  messages: {
    tts: {
      auto: "always",
      persona: "narrator",
      personas: {
        narrator: {
          label: "Narrator",
          provider: "elevenlabs",
          providers: {
            elevenlabs: { voiceId: "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",
              voiceName: "Algieba",
              promptTemplate: "audio-profile-v1",
            },
            openai: { model: "gpt-4o-mini-tts", voice: "cedar" },
            elevenlabs: {
              voiceId: "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:voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](laughs) Read the song once more.[[/tts:text]]

• provider (معرّف مزوّد مسجّل؛ يتطلب allowProvider: true)
• 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 القناة إلى Ogg/Opus بتردد 48kHz باستخدام 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 إلى Opus بتردد 48kHz باستخدام ffmpeg قبل التسليم عندما تعلن القناة دعم التحويل.
• Xiaomi MiMo: MP3 افتراضياً، أو WAV عند ضبطه. بالنسبة إلى أهداف الرسائل الصوتية التي تعلنها القناة، يحوّل OpenClaw خرج Xiaomi إلى Opus بتردد 48kHz باستخدام ffmpeg قبل التسليم عندما تعلن القناة دعم التحويل.
• CLI المحلي: يستخدم outputFormat المضبوط. تُحوّل أهداف الرسائل الصوتية إلى Ogg/Opus، ويُحوّل خرج الاتصالات الهاتفية إلى PCM أحادي خام بتردد 16 kHz باستخدام ffmpeg.
• Google Gemini: تعيد TTS في Gemini API ملف PCM خاماً بتردد 24kHz. يغلّفه OpenClaw كملف WAV لمرفقات الصوت، ويحوّله إلى Opus بتردد 48kHz لأهداف الرسائل الصوتية، ويعيد 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).
  • يقبل sendVoice في Telegram صيغ OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج إلى رسائل صوتية مضمونة بصيغة Opus.
  • إذا فشلت صيغة خرج Microsoft المضبوطة، يعيد OpenClaw المحاولة باستخدام MP3.

​

سلوك TTS التلقائي

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

Reply -> TTS enabled?
  no  -> send text
  yes -> has media / 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 مباشرة لـ Talk/الهاتف.
• Inworld: مرفقات MP3، وملاحظة صوتية أصلية OGG_OPUS، وPCM خام بتردد 22050 Hz لـ Talk/الهاتف.
• xAI: MP3 افتراضياً؛ يمكن أن تكون responseFormat هي mp3|wav|pcm|mulaw|alaw. يستخدم نقطة نهاية REST الدفعية من xAI — ولا يُستخدم TTS عبر WebSocket المتدفق. صيغة Opus الأصلية للملاحظات الصوتية غير مدعومة.
• Microsoft: يستخدم microsoft.outputFormat (الافتراضي audio-24khz-48kbitrate-mono-mp3). يقبل sendVoice في Telegram صيغ OGG/MP3/M4A؛ استخدم OpenAI/ElevenLabs إذا كنت تحتاج إلى رسائل صوتية مضمونة بصيغة Opus. إذا فشلت صيغة Microsoft المكوَّنة، يعيد OpenClaw المحاولة باستخدام MP3.

​

مرجع الحقول

​

أداة الوكيل

​

Gateway RPC

​

روابط الخدمة

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

​

ذات صلة

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