​

テキスト読み上げ（TTS）

​

対応サービス

• ElevenLabs（プライマリまたはフォールバックのプロバイダー）
• Microsoft（プライマリまたはフォールバックのプロバイダー。現在の同梱実装では node-edge-tts を使用）
• MiniMax（プライマリまたはフォールバックのプロバイダー。T2A v2 APIを使用）
• OpenAI（プライマリまたはフォールバックのプロバイダー。要約にも使用）

​

Microsoft speechに関する注意

​

オプションのキー

• ELEVENLABS_API_KEY（または XI_API_KEY）
• MINIMAX_API_KEY
• OPENAI_API_KEY

​

サービスリンク

• OpenAI Text-to-Speech guide
• OpenAI Audio API reference
• ElevenLabs Text to Speech
• ElevenLabs Authentication
• MiniMax T2A v2 API
• node-edge-tts
• Microsoft Speech output formats

​

デフォルトで有効ですか？

​

設定

​

最小構成（有効化 + プロバイダー）

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

​

OpenAIをプライマリ、ElevenLabsをフォールバックにする場合

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true,
      },
      providers: {
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
        elevenlabs: {
          apiKey: "elevenlabs_api_key",
          baseUrl: "https://api.elevenlabs.io",
          voiceId: "voice_id",
          modelId: "eleven_multilingual_v2",
          seed: 42,
          applyTextNormalization: "auto",
          languageCode: "en",
          voiceSettings: {
            stability: 0.5,
            similarityBoost: 0.75,
            style: 0.0,
            useSpeakerBoost: true,
            speed: 1.0,
          },
        },
      },
    },
  },
}

​

Microsoftをプライマリにする場合（APIキー不要）

{
  messages: {
    tts: {
      auto: "always",
      provider: "microsoft",
      providers: {
        microsoft: {
          enabled: true,
          voice: "en-US-MichelleNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
          rate: "+10%",
          pitch: "-5%",
        },
      },
    },
  },
}

​

MiniMaxをプライマリにする場合

{
  messages: {
    tts: {
      auto: "always",
      provider: "minimax",
      providers: {
        minimax: {
          apiKey: "minimax_api_key",
          baseUrl: "https://api.minimax.io",
          model: "speech-2.8-hd",
          voiceId: "English_expressive_narrator",
          speed: 1.0,
          vol: 1.0,
          pitch: 0,
        },
      },
    },
  },
}

​

Microsoft speechを無効にする

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

​

カスタム制限 + prefsパス

{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

​

受信した音声メッセージの後だけ音声で返信する

{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

​

長い返信の自動要約を無効にする

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

/tts summary off

​

フィールドに関する注意

• auto: 自動TTSモード（off、always、inbound、tagged）。
  • inbound は、受信した音声メッセージの後にのみ音声を送信します。
  • tagged は、返信に [[tts]] タグが含まれている場合にのみ音声を送信します。
• enabled: 従来のトグル（doctorがこれを auto に移行します）。
• mode: "final"（デフォルト）または "all"（ツール/ブロック返信を含む）。
• provider: "elevenlabs"、"microsoft"、"minimax"、"openai" などのspeechプロバイダーID（フォールバックは自動）。
• provider が 未設定 の場合、OpenClawはレジストリの自動選択順で最初に設定されたspeechプロバイダーを使用します。
• 従来の provider: "edge" も引き続き機能し、microsoft に正規化されます。
• summaryModel: 自動要約用のオプションの低コストモデル。デフォルトは agents.defaults.model.primary。
  • provider/model または設定済みのモデルエイリアスを受け付けます。
• modelOverrides: モデルがTTSディレクティブを出力できるようにします（デフォルトでオン）。
  • allowProvider のデフォルトは false（プロバイダー切り替えはオプトイン）。
• providers.<id>: speechプロバイダーIDをキーにした、プロバイダー所有の設定。
• 従来の直接プロバイダーブロック（messages.tts.openai、messages.tts.elevenlabs、messages.tts.microsoft、messages.tts.edge）は、読み込み時に messages.tts.providers.<id> に自動移行されます。
• maxTextLength: TTS入力のハード上限（文字数）。超過すると /tts audio は失敗します。
• timeoutMs: リクエストタイムアウト（ms）。
• prefsPath: ローカル設定JSONパス（provider/limit/summary）を上書きします。
• apiKey の値は環境変数（ELEVENLABS_API_KEY/XI_API_KEY、MINIMAX_API_KEY、OPENAI_API_KEY）にフォールバックします。
• providers.elevenlabs.baseUrl: ElevenLabs APIのベースURLを上書きします。
• providers.openai.baseUrl: OpenAI TTSエンドポイントを上書きします。
  • 解決順: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • デフォルト以外の値はOpenAI互換のTTSエンドポイントとして扱われるため、カスタムのモデル名と音声名を使用できます。
• providers.elevenlabs.voiceSettings:
  • stability、similarityBoost、style: 0..1
  • useSpeakerBoost: true|false
  • speed: 0.5..2.0（1.0 = 通常）
• providers.elevenlabs.applyTextNormalization: auto|on|off
• providers.elevenlabs.languageCode: 2文字のISO 639-1（例: en、de）
• providers.elevenlabs.seed: 整数 0..4294967295（ベストエフォートの決定性）
• providers.minimax.baseUrl: MiniMax APIのベースURLを上書きします（デフォルト https://api.minimax.io、環境変数: MINIMAX_API_HOST）。
• providers.minimax.model: TTSモデル（デフォルト speech-2.8-hd、環境変数: MINIMAX_TTS_MODEL）。
• providers.minimax.voiceId: 音声識別子（デフォルト English_expressive_narrator、環境変数: MINIMAX_TTS_VOICE_ID）。
• providers.minimax.speed: 再生速度 0.5..2.0（デフォルト 1.0）。
• providers.minimax.vol: 音量 (0, 10]（デフォルト 1.0。0より大きい必要があります）。
• providers.minimax.pitch: ピッチシフト -12..12（デフォルト 0）。
• providers.microsoft.enabled: Microsoft speechの使用を許可します（デフォルト true。APIキー不要）。
• providers.microsoft.voice: Microsoftニューラル音声名（例: en-US-MichelleNeural）。
• providers.microsoft.lang: 言語コード（例: en-US）。
• providers.microsoft.outputFormat: Microsoftの出力形式（例: audio-24khz-48kbitrate-mono-mp3）。
  • 有効な値はMicrosoft Speech output formatsを参照してください。同梱のEdgeベース転送では、すべての形式がサポートされるわけではありません。
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: パーセント文字列（例: +10%、-5%）。
• providers.microsoft.saveSubtitles: 音声ファイルと一緒にJSON字幕を書き込みます。
• providers.microsoft.proxy: Microsoft speechリクエスト用のプロキシURL。
• providers.microsoft.timeoutMs: リクエストタイムアウトの上書き（ms）。
• edge.*: 同じMicrosoft設定の従来エイリアス。

​

モデル駆動の上書き（デフォルトでオン）

Here you go.

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

• provider（登録済みspeechプロバイダーID。たとえば openai、elevenlabs、minimax、microsoft。allowProvider: true が必要）
• voice（OpenAI voice）または voiceId（ElevenLabs / MiniMax）
• model（OpenAI TTSモデル、ElevenLabsモデルID、またはMiniMaxモデル）
• stability、similarityBoost、style、speed、useSpeakerBoost
• vol / volume（MiniMax volume、0-10）
• pitch（MiniMax pitch、-12から12）
• applyTextNormalization（auto|on|off）
• languageCode（ISO 639-1）
• seed

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

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

​

ユーザーごとの設定

• enabled
• provider
• maxLength（要約しきい値。デフォルト1500文字）
• summarize（デフォルト true）

​

出力形式（固定）

• Feishu / Matrix / Telegram / WhatsApp: Opus音声メッセージ（ElevenLabsでは opus_48000_64、OpenAIでは opus）。
  • 48kHz / 64kbps は音声メッセージに適したバランスです。
• その他のチャネル: MP3（ElevenLabsでは mp3_44100_128、OpenAIでは mp3）。
  • 44.1kHz / 128kbps は音声明瞭度に対するデフォルトのバランスです。
• MiniMax: MP3（speech-2.8-hd モデル、32kHzサンプルレート）。音声ノート形式はネイティブサポートされません。Opus音声メッセージを確実に使いたい場合はOpenAIまたはElevenLabsを使用してください。
• Microsoft: microsoft.outputFormat を使用します（デフォルト audio-24khz-48kbitrate-mono-mp3）。
  • 同梱の転送は outputFormat を受け付けますが、すべての形式がサービスから利用できるわけではありません。
  • 出力形式の値はMicrosoft Speech output formatsに従います（Ogg/WebM Opusを含む）。
  • Telegramの sendVoice はOGG/MP3/M4Aを受け付けます。Opus音声メッセージを確実に使いたい場合はOpenAI/ElevenLabsを使用してください。
  • 設定されたMicrosoft出力形式が失敗した場合、OpenClawはMP3で再試行します。

​

自動TTSの動作

• 返信にすでにメディアまたは MEDIA: ディレクティブが含まれている場合はTTSをスキップします。
• 非常に短い返信（10文字未満）ではTTSをスキップします。
• 長い返信は、有効な場合、agents.defaults.model.primary（または summaryModel）を使って要約します。
• 生成された音声を返信に添付します。

​

フロー図

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 (summaryModel or agents.defaults.model.primary)
                                      -> TTS -> attach audio

​

スラッシュコマンドの使い方

/tts off
/tts on
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

• コマンドには認可された送信者が必要です（許可リスト/オーナールールは引き続き適用されます）。
• commands.text またはネイティブコマンド登録が有効である必要があります。
• 設定 messages.tts.auto は off|always|inbound|tagged を受け付けます。
• /tts on はローカルTTS設定を always に書き込みます。/tts off は off に書き込みます。
• inbound または tagged をデフォルトにしたい場合は設定を使用してください。
• limit と summary は、メイン設定ではなくローカル設定に保存されます。
• /tts audio は1回限りの音声返信を生成します（TTSをオンには切り替えません）。
• /tts status には、最新の試行に対するフォールバックの可視性が含まれます:
  • 成功時のフォールバック: Fallback: <primary> -> <used> と Attempts: ...
  • 失敗時: Error: ... と Attempts: ...
  • 詳細診断: Attempt details: provider:outcome(reasonCode) latency
• OpenAIおよびElevenLabsのAPI失敗には、解析済みのプロバイダーエラー詳細とリクエストID（プロバイダーから返された場合）が含まれるようになり、TTSエラー/ログに表示されます。

​

Agent tool

​

Gateway RPC

• tts.status
• tts.enable
• tts.disable
• tts.convert
• tts.setProvider
• tts.providers