テキスト読み上げ

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（登録済み provider id。allowProvider: true が必要）
• voice / voiceName / voice_name / google_voice / voiceId
• model / google_model
• stability, similarityBoost, style, speed, useSpeakerBoost
• vol / volume（MiniMax volume、0–10）
• pitch（MiniMax の整数 pitch、−12 から 12。小数値は切り捨て）
• emotion（Volcengine emotion タグ）
• 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 は現在のチャットに対して、セッションスコープの auto-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 モードに加え、設定済みの provider、model、voice、サニタイズ済みのカスタムエンドポイントメタデータを表示します。

​

ユーザーごとの設定

​

出力形式（固定）

• ボイスノート対応チャンネル: ボイスノート返信は Opus（ElevenLabs の opus_48000_64、OpenAI の opus）を優先します。
  • 48kHz / 64kbps は音声メッセージとしてバランスのよいトレードオフです。
• Feishu / WhatsApp: ボイスノート返信が MP3/WebM/WAV/M4A または別の音声ファイルと思われる形式で生成された場合、チャンネルPluginはネイティブ音声メッセージを送信する前に、ffmpeg で 48kHz Ogg/Opus にトランスコードします。WhatsApp は Baileys の audio ペイロードで ptt: true と audio/ogg; codecs=opus を付けて結果を送信します。変換に失敗した場合、Feishu は元の ファイルを添付ファイルとして受信します。WhatsApp の送信は、互換性のない PTT ペイロードを投稿するのではなく失敗します。
• その他のチャンネル: MP3（ElevenLabs の mp3_44100_128、OpenAI の mp3）。
  • 44.1kHz / 128kbps は音声の明瞭さに対するデフォルトのバランスです。
• MiniMax: 通常の音声添付ファイルには MP3（speech-2.8-hd モデル、32kHz サンプルレート）を使用します。チャンネルが通知するボイスノート対象では、チャンネルがトランスコードを通知している場合、OpenClaw は配信前に ffmpeg で MiniMax MP3 を 48kHz Opus にトランスコードします。
• Xiaomi MiMo: デフォルトでは MP3、設定されている場合は WAV を使用します。チャンネルが通知するボイスノート対象では、チャンネルがトランスコードを通知している場合、OpenClaw は配信前に ffmpeg で Xiaomi 出力を 48kHz Opus にトランスコードします。
• ローカル CLI: 設定された outputFormat を使用します。ボイスノート対象は Ogg/Opus に変換され、電話出力は ffmpeg で生の 16 kHz モノラル PCM に変換されます。
• Google Gemini: Gemini API TTS は生の 24kHz PCM を返します。OpenClaw は音声添付ファイル用にそれを WAV としてラップし、ボイスノート対象用に 48kHz Opus にトランスコードし、Talk/電話用には PCM を直接返します。
• Gradium: 音声添付ファイルには WAV、ボイスノート対象には Opus、電話には 8 kHz の ulaw_8000 を使用します。
• Inworld: 通常の音声添付ファイルには MP3、ボイスノート対象にはネイティブ OGG_OPUS、Talk/電話には 22050 Hz の生 PCM を使用します。
• xAI: デフォルトでは MP3 です。responseFormat は mp3、wav、pcm、mulaw、または alaw にできます。OpenClaw は xAI のバッチ REST TTS エンドポイントを使用し、完全な音声添付ファイルを返します。xAI のストリーミング TTS WebSocket は、このプロバイダーパスでは使用されません。ネイティブ 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 で再試行します。

​

Auto-TTS の動作

• 返信にすでにメディアまたは MEDIA: ディレクティブが含まれている場合、TTS をスキップします。
• 非常に短い返信（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は ffmpeg で 48 kHz Ogg/Opus にトランスコードします。WhatsApp は Baileys 経由で ptt: true と audio/ogg; codecs=opus を付けて送信します。変換に失敗した場合: Feishu は元のファイルを添付するようにフォールバックします。WhatsApp の送信は、互換性のない PTT ペイロードを投稿するのではなく失敗します。
• MiniMax / Xiaomi MiMo: デフォルトは MP3（MiniMax speech-2.8-hd は 32 kHz）。ボイスノート対象では ffmpeg によって 48 kHz Opus にトランスコードされます。
• ローカル CLI: 設定された outputFormat を使用します。ボイスノート対象は Ogg/Opus に変換され、電話出力は生の 16 kHz モノラル PCM に変換されます。
• Google Gemini: 生の 24 kHz PCM を返します。OpenClaw は添付ファイル用には WAV としてラップし、ボイスノート対象用には 48 kHz Opus にトランスコードし、Talk/電話用には PCM を直接返します。
• Inworld: MP3 添付ファイル、ネイティブ OGG_OPUS ボイスノート、Talk/電話用には 22050 Hz の生 PCM。
• xAI: デフォルトでは MP3 です。responseFormat は mp3|wav|pcm|mulaw|alaw にできます。xAI のバッチ REST エンドポイントを使用します。ストリーミング WebSocket TTS は使用されません。ネイティブ Opus ボイスノート形式はサポートされていません。
• Microsoft: microsoft.outputFormat（デフォルト audio-24khz-48kbitrate-mono-mp3）を使用します。Telegram sendVoice は OGG/MP3/M4A を受け付けます。Opus 音声メッセージを確実に必要とする場合は OpenAI/ElevenLabs を使用してください。設定された 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