テキスト読み上げ

​

クイックスタート

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

​

対応プロバイダー

​

設定

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

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

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

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

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

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

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

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

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

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

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

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

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

​

エージェントごとの音声オーバーライド

{
  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. tts
2. 有効な agents.entries.*.tts
3. チャンネルが channels.<channel>.tts をサポートしている場合のチャンネル上書き
4. チャンネルが channels.<channel>.accounts.<id>.tts を渡す場合のアカウント上書き
5. このホストのローカルな /tts 設定
6. モデル駆動ディレクティブが有効な場合のインライン [[tts:...]] ディレクティブ

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

​

ペルソナ

​

最小構成のペルソナ

{
  tts: {
    auto: "always",
    persona: "narrator",
    personas: {
      narrator: {
        label: "ナレーター",
        provider: "elevenlabs",
        providers: {
          elevenlabs: {
            speakerVoiceId: "EXAVITQu4vr4xnSDxMaL",
            modelId: "eleven_multilingual_v2",
          },
        },
      },
    },
  },
}

​

完全なペルソナ（プロバイダー固有の調整）

{
  tts: {
    auto: "always",
    persona: "alfred",
    personas: {
      alfred: {
        label: "アルフレッド",
        description: "辛口ながら温かみのある、英国執事風のナレーター。",
        provider: "google",
        fallbackPolicy: "preserve-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. 設定されている場合、tts.persona。
3. ペルソナなし。

1. 直接上書き（CLI、Gateway、Talk、許可された TTS ディレクティブ）。
2. ローカル設定の /tts provider <id>。
3. 有効なペルソナの provider。
4. tts.provider。
5. レジストリによる自動選択。

1. tts.providers.<id>
2. tts.personas.<persona>.providers.<id>
3. 信頼されたリクエストによる上書き
4. 許可された、モデルが出力した TTS ディレクティブによる上書き

​

カスタムペルソナの調整

​

フォールバックポリシー

​

モデル駆動ディレクティブ

どうぞ。

[[tts:speakerVoiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]]（笑う）その歌をもう一度読んでください。[[/tts:text]]

• provider（登録済みのプロバイダー ID。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 をオンには切り替えません）。
• /tts limit <chars> は 100～4096 を受け付けます（4096 は Telegram のキャプション／メッセージの最大値）。範囲外の値は拒否されます。
• limit と summary はメイン設定ではなく、ローカル設定に保存されます。
• /tts status には、最新の試行に関するフォールバック診断（Fallback: <primary> -> <used>、Attempts: ...、および試行ごとの詳細（provider:outcome(reasonCode) latency））が含まれます。
• /status は、TTS が有効な場合に、有効な TTS モードと、設定済みのプロバイダー、モデル、音声、サニタイズ済みカスタムエンドポイントのメタデータを表示します。

​

ユーザーごとの設定

​

出力形式

• Feishu / WhatsApp のトランスコード： 音声メモへの返信が MP3/WebM/WAV/M4A またはその他の音声ファイルと思われる形式で届いた場合、チャネル Plugin はネイティブ音声メッセージを送信する前に、ffmpeg（libopus、64 kbps）を使用して 48 kHz Ogg/Opus にトランスコードします。WhatsApp は、ptt: true および audio/ogg; codecs=opus を指定した Baileys の audio ペイロードを通じて結果を送信します。トランスコードに失敗した場合、Feishu はエラーを捕捉し、元のファイルを通常の添付ファイルとして送信する方式にフォールバックします。WhatsApp にはフォールバックがないため、互換性のない PTT ペイロードを投稿する代わりに、送信自体が失敗します。
• MiniMax： 通常の音声添付ファイルには MP3（speech-2.8-hd モデル、32 kHz サンプルレート）を使用し、チャネルが音声メモ対応として通知しているターゲットでは ffmpeg を使用して 48 kHz Opus にトランスコードします。
• Xiaomi MiMo： デフォルトでは MP3、設定されている場合は WAV を使用します。チャネルが音声メモ対応として通知しているターゲットでは ffmpeg を使用して 48 kHz Opus にトランスコードします。
• ローカル CLI： 設定された outputFormat を使用します。音声メモのターゲットは Ogg/Opus に変換され、電話出力は ffmpeg を使用して raw 16 kHz モノラル PCM に変換されます。
• Google Gemini： raw 24 kHz PCM を返します。OpenClaw は音声添付ファイル用にこれを WAV としてラップし、音声メモのターゲット用に 48 kHz Opus にトランスコードし、Talk/電話用には PCM を直接返します。
• Gradium： 音声添付ファイルには WAV、音声メモのターゲットには Opus、電話には 8 kHz の ulaw_8000 を使用します。
• Inworld： 通常の音声添付ファイルには MP3、音声メモのターゲットにはネイティブの OGG_OPUS、Talk/電話には 22050 Hz の raw PCM を使用します。
• xAI： デフォルトでは MP3 を使用します。音声ファイルの合成では、バッファリング出力とストリーミング出力の両方に mp3、wav、pcm、mulaw、または alaw を使用できます。xAI の pcm、mulaw、および alaw の出力はヘッダーのない raw 音声であるため、音声メモのターゲットではストリーミングおよびバッファリング時のフォールバックに MP3 を使用します。バッファリング合成では xAI のバッチ REST /v1/tts エンドポイントを使用し、textToSpeechStream ではネイティブの wss://api.x.ai/v1/tts を使用します。これはリアルタイム音声の契約ではありません。ネイティブ Opus 音声メモ形式はサポートされていません。
• Microsoft： microsoft.outputFormat（デフォルトは audio-24khz-48kbitrate-mono-mp3）を使用します。
  • バンドルされたトランスポートは outputFormat を受け付けますが、サービスからすべての形式を利用できるわけではありません。
  • 出力形式の値は Microsoft Speech の出力形式（Ogg/WebM Opus を含む）に従います。
  • Telegram の sendVoice は OGG/MP3/M4A を受け付けます。Opus 音声メッセージを確実に使用する必要がある場合は OpenAI/ElevenLabs を使用してください。
  • 設定された Microsoft の出力形式が失敗した場合、OpenClaw は MP3 で再試行します。
  • 明示的な音声の上書きが設定されておらず、デフォルトの英語音声が使用されている場合、返信テキストで CJK が大部分を占めていれば、OpenClaw は中国語ニューラル音声（zh-CN-XiaoxiaoNeural、zh-CN ロケール）に自動的に切り替えます。

​

自動 TTS の動作

• 返信に構造化メディアがすでに含まれている場合は、TTS をスキップします。
• 非常に短い返信（10 文字未満）はスキップします。
• 要約が有効な場合、summaryModel（または agents.defaults.model.primary）を使用して 長い返信を要約します。
• 生成された音声を返信に添付します。
• mode: "final" では、テキストストリームの完了後も、ストリーミングされた最終返信に対して 音声のみの TTS を送信します。生成されたメディアには、通常の返信添付ファイルと同じ チャネルメディア正規化が適用されます。

• 要約オン（デフォルト）で要約モデルが利用可能な場合：テキストを 約 maxLength 文字に要約し、その要約を音声合成します。
• 要約オフ、要約に失敗した場合、または要約モデル用の API キーが利用できない場合： テキストを maxLength 文字に切り詰め、切り詰めたテキストを 音声合成します。

返信 -> TTS は有効？
  いいえ -> テキストを送信
  はい   -> メディアを含む / 短い？
            はい   -> テキストを送信
            いいえ -> 長さ > 上限？
                      いいえ -> TTS -> 音声を添付
                      はい   -> 要約が有効かつ利用可能？
                                いいえ -> 切り詰め -> TTS -> 音声を添付
                                はい   -> 要約 -> TTS -> 音声を添付

​

フィールドリファレンス

​

エージェントツール

​

Gateway RPC

​

サービスへのリンク

• OpenAI テキスト読み上げガイド
• OpenAI Audio API リファレンス
• Azure Speech REST テキスト読み上げ
• Azure Speech プロバイダー
• ElevenLabs テキスト読み上げ
• ElevenLabs 認証
• Gradium
• Inworld TTS API
• MiniMax T2A v2 API
• Volcengine TTS HTTP API
• Xiaomi MiMo 音声合成
• node-edge-tts
• Microsoft Speech の出力形式
• xAI テキスト読み上げ

​

関連項目

• メディアの概要
• 音楽生成
• 動画生成
• スラッシュコマンド
• 音声通話 Plugin