テキスト読み上げ

OpenClaw は、送信する返信を 14 種類の音声プロバイダーで音声に変換し、Feishu、Matrix、Telegram、WhatsApp ではネイティブ音声メッセージとして、それ以外では音声添付として、さらにテレフォニーと Talk では PCM/Ulaw ストリームとして配信できます。

TTS は Talk の stt-tts モードにおける音声出力側です。プロバイダーネイティブの realtime Talk セッションは、この TTS パスを呼び出す代わりにリアルタイムプロバイダー内で音声を合成します。一方、transcription セッションはアシスタントの音声応答を合成しません。

# クイックスタート

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

# サポートされるプロバイダー

複数のプロバイダーが設定されている場合、選択されたプロバイダーが最初に使用され、他のプロバイダーはフォールバックオプションになります。自動要約は summaryModel（または agents.defaults.model.primary）を使用するため、要約を有効のままにする場合は、そのプロバイダーも認証済みである必要があります。

# 設定

TTS 設定は ~/.openclaw/openclaw.json の messages.tts 配下にあります。プリセットを選び、プロバイダーブロックを調整します。

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

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

1 つのエージェントに別のプロバイダー、音声、モデル、ペルソナ、または Auto-TTS モードで話させたい場合は、agents.list[].tts を使用します。エージェントブロックは messages.tts に対してディープマージされるため、プロバイダー認証情報はグローバルプロバイダー設定に置いたままにできます。

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

エージェントごとのペルソナを固定するには、プロバイダー設定と並べて agents.list[].tts.persona を設定します。これはそのエージェントに対してのみ、グローバルな messages.tts.persona を上書きします。

自動返信、/tts audio、/tts status、および tts エージェントツールの優先順位:

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

チャンネルとアカウントの上書きは messages.tts と同じ形を使い、前のレイヤーに対して深くマージされます。そのため、共有プロバイダー認証情報は messages.tts に置いたまま、チャンネルまたはbotアカウントで音声、モデル、ペルソナ、または自動モードだけを変更できます。

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

# ペルソナ

ペルソナは、プロバイダー間で決定論的に適用できる安定した発話アイデンティティです。1つのプロバイダーを優先したり、プロバイダー中立のプロンプト意図を定義したり、音声、モデル、プロンプトテンプレート、シード、音声設定のプロバイダー固有バインディングを保持したりできます。

# 最小構成のペルソナ

{
  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. レジストリの自動選択。

各プロバイダー試行で、OpenClaw はこの順序で設定をマージします。

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

# プロバイダーがペルソナプロンプトを使用する方法

ペルソナプロンプトフィールド (profile、scene、sampleContext、style、accent、pacing、constraints) はプロバイダー中立です。各プロバイダーがそれらをどう使うかを決めます。

# フォールバックポリシー

fallbackPolicy は、試行されたプロバイダーに対してペルソナにバインディングがない場合の動作を制御します。

TTSリクエスト全体が失敗するのは、試行されたプロバイダーがすべてスキップされるか失敗した場合だけです。

Talkセッションのプロバイダー選択はセッションスコープです。Talkクライアントは talk.catalog からプロバイダーID、モデルID、音声ID、ロケールを選択し、それらをTalkセッションまたはハンドオフリクエストを通じて渡す必要があります。音声セッションを開いても、messages.tts やグローバルなTalkプロバイダーデフォルトを変更してはいけません。

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

デフォルトでは、アシスタントは [[tts:...]] ディレクティブを出力して、単一の返信の音声、モデル、または速度を上書きできます。さらに、音声にだけ現れる表現上の合図用に任意の [[tts:text]]...[[/tts:text]] ブロックを出力できます。

Here you go.

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

messages.tts.auto が "tagged" の場合、音声をトリガーするにはディレクティブが必須です。ストリーミングブロック配信では、隣接するブロックに分割されている場合でも、チャンネルに見える前に表示テキストからディレクティブが取り除かれます。

provider=... は modelOverrides.allowProvider: true でない限り無視されます。返信が provider=... を宣言した場合、そのディレクティブ内の他のキーはそのプロバイダーだけが解析します。サポートされていないキーは取り除かれ、TTSディレクティブ警告として報告されます。

使用可能なディレクティブキー:

• 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 整数ピッチ、−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 です。Discord では、/tts がDiscord組み込みコマンドであるため、OpenClaw は /voice も登録します。テキストの /tts ... は引き続き動作します。

/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モードを表示します。

# ユーザーごとの設定

スラッシュコマンドはローカル上書きを prefsPath に書き込みます。デフォルトは ~/.openclaw/settings/tts.json です。OPENCLAW_TTS_PREFS env var または messages.tts.prefsPath で上書きできます。

これらは、このホストの messages.tts に加えてアクティブな agents.list[].tts ブロックから得られる有効な設定を上書きします。

# 出力形式 (固定)

TTS音声配信はチャンネル機能によって決まります。チャンネルPluginは、音声スタイルTTSでプロバイダーにネイティブな voice-note ターゲットを要求するか、通常の audio-file 合成を維持し、互換性のある出力を音声配信用としてマークするだけにするかを広告します。

• ボイスノート対応チャンネル: ボイスノート返信では 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 ペイロードを投稿するのではなく失敗します。
• BlueBubbles: プロバイダーの合成は通常の音声ファイル経路のままにします。MP3 および CAF 出力は iMessage 音声メモ配信用としてマークされます。
• その他のチャンネル: MP3（ElevenLabs の mp3_44100_128、OpenAI の mp3）。
  • 44.1kHz / 128kbps は音声の明瞭さに対するデフォルトのバランスです。
• MiniMax: 通常の音声添付には MP3（speech-2.8-hd モデル、32kHz サンプルレート）を使います。チャンネルが宣言するボイスノートターゲットでは、そのチャンネルがトランスコードを宣言している場合、OpenClaw は配信前に MiniMax の MP3 を ffmpeg で 48kHz Opus にトランスコードします。
• Xiaomi MiMo: デフォルトは MP3、設定されている場合は WAV です。チャンネルが宣言するボイスノートターゲットでは、そのチャンネルがトランスコードを宣言している場合、OpenClaw は配信前に Xiaomi の出力を ffmpeg で 48kHz Opus にトランスコードします。
• ローカル CLI: 設定された outputFormat を使います。ボイスノートターゲットは Ogg/Opus に変換され、電話出力は ffmpeg で raw 16 kHz mono PCM に変換されます。
• Google Gemini: Gemini API TTS は raw 24kHz PCM を返します。OpenClaw は音声添付用にそれを WAV としてラップし、ボイスノートターゲット用に 48kHz Opus へトランスコードし、Talk/電話用には PCM を直接返します。
• Gradium: 音声添付には WAV、ボイスノートターゲットには Opus、電話には 8 kHz の ulaw_8000 を使います。
• Inworld: 通常の音声添付には MP3、ボイスノートターゲットにはネイティブの OGG_OPUS、Talk/電話には 22050 Hz の raw 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 で再試行します。

OpenAI/ElevenLabs の出力形式はチャンネルごとに固定されています（上記を参照）。

# Auto-TTS の動作

messages.tts.auto が有効な場合、OpenClaw は次のように動作します。

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

返信が maxLength を超え、要約がオフの場合（または要約モデル用の API キーがない場合）、 音声はスキップされ、通常のテキスト返信が送信されます。

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 に変換され、電話出力は raw 16 kHz mono PCM に変換されます。
• Google Gemini: raw 24 kHz PCM を返します。OpenClaw は添付用には WAV としてラップし、ボイスノート対象では 48 kHz Opus にトランスコードし、Talk/電話では PCM をそのまま返します。
• Inworld: MP3 添付、標準の OGG_OPUS ボイスノート、Talk/電話向けの raw PCM 22050 Hz。
• 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 で再試行します。

OpenAI と ElevenLabs の出力形式は、上記のとおりチャンネルごとに固定されています。

# フィールドリファレンス

# エージェントツール

tts ツールはテキストを音声に変換し、返信配信用の音声添付を返します。Feishu、Matrix、Telegram、WhatsApp では、音声はファイル添付ではなくボイスメッセージとして配信されます。Feishu と WhatsApp は、この経路で ffmpeg が利用可能な場合、非 Opus の TTS 出力をトランスコードできます。

WhatsApp は Baileys 経由で PTT ボイスノート（ptt: true 付きの audio）として音声を送信し、クライアントがボイスノートのキャプションを一貫して表示しないため、表示テキストは PTT 音声とは別に送信します。

このツールは任意の channel フィールドと timeoutMs フィールドを受け付けます。timeoutMs は呼び出しごとのプロバイダーリクエストタイムアウト（ミリ秒）です。

# 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