​

Text-to-speech (TTS)

​

サポートされているサービス

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

​

Microsoft音声に関する注意

​

任意のキー

• 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音声を無効にする

{
  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"（ツール / block返信を含む）。
• provider: "elevenlabs"、"microsoft"、"minimax"、"openai"のようなspeech provider id（フォールバックは自動）。
• providerが未設定の場合、OpenClawはレジストリの自動選択順で最初に設定されたspeech providerを使います。
• レガシーのprovider: "edge"も引き続き動作し、microsoftに正規化されます。
• summaryModel: 自動要約用の任意の低コストモデル。デフォルトはagents.defaults.model.primaryです。
  • provider/modelまたは設定済みmodel aliasを受け付けます。
• modelOverrides: モデルがTTS directiveを出力できるようにします（デフォルトでオン）。
  • allowProviderのデフォルトはfalseです（プロバイダー切り替えはオプトイン）。
• providers.<id>: speech provider idをキーにしたプロバイダー所有設定。
• レガシーの直接プロバイダーブロック（messages.tts.openai、messages.tts.elevenlabs、messages.tts.microsoft、messages.tts.edge）は、読み込み時にmessages.tts.providers.<id>へ自動移行されます。
• maxTextLength: TTS入力のハード上限（文字数）。超過すると/tts audioは失敗します。
• timeoutMs: リクエストタイムアウト（ms）。
• prefsPath: local prefs JSONパスを上書きします（provider / limit / summary）。
• apiKey値はenv var（ELEVENLABS_API_KEY/XI_API_KEY、MINIMAX_API_KEY、OPENAI_API_KEY）へフォールバックします。
• providers.elevenlabs.baseUrl: ElevenLabs API base URLを上書きします。
• providers.openai.baseUrl: OpenAI TTS endpointを上書きします。
  • 解決順序: messages.tts.providers.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
  • デフォルト以外の値はOpenAI互換TTS endpointとして扱われるため、カスタムのmodel名とvoice名を受け付けます。
• 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 base URLを上書きします（デフォルトhttps://api.minimax.io、env: MINIMAX_API_HOST）。
• providers.minimax.model: TTSモデル（デフォルトspeech-2.8-hd、env: MINIMAX_TTS_MODEL）。
• providers.minimax.voiceId: voice識別子（デフォルトEnglish_expressive_narrator、env: 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音声の使用を許可します（デフォルトtrue。APIキー不要）。
• providers.microsoft.voice: Microsoft neural voice名（例: en-US-MichelleNeural）。
• providers.microsoft.lang: 言語コード（例: en-US）。
• providers.microsoft.outputFormat: Microsoft出力形式（例: audio-24khz-48kbitrate-mono-mp3）。
  • 有効な値はMicrosoft Speech output formatsを参照してください。すべての形式がバンドル済みのEdgeバックエンドtransportでサポートされるわけではありません。
• providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: パーセント文字列（例: +10%、-5%）。
• providers.microsoft.saveSubtitles: 音声ファイルと一緒にJSON字幕を書き込みます。
• providers.microsoft.proxy: Microsoft音声リクエスト用のproxy 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 provider id。例: openai、elevenlabs、minimax、microsoft。allowProvider: trueが必要）
• voice（OpenAI voice）またはvoiceId（ElevenLabs / MiniMax）
• model（OpenAI TTS model、ElevenLabs model id、またはMiniMax model）
• 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サンプルレート）。voice-note形式はネイティブにはサポートされません。Opus音声メッセージを確実に使いたい場合はOpenAIまたはElevenLabsを使ってください。
• Microsoft: microsoft.outputFormatを使用します（デフォルトaudio-24khz-48kbitrate-mono-mp3）。
  • バンドル済みtransportはoutputFormatを受け付けますが、すべての形式がサービスで利用可能なわけではありません。
  • 出力形式の値はMicrosoft Speech output formatsに従います（Ogg/WebM Opusを含む）。
  • TelegramのsendVoiceはOGG / MP3 / M4Aを受け付けます。Opus音声メッセージを確実に使いたい場合はOpenAI / ElevenLabsを使ってください。
  • 設定されたMicrosoft出力形式が失敗した場合、OpenClawはMP3で再試行します。

​

自動TTSの挙動

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

​

フロー図

Reply -> TTS enabled?
  no  -> テキストを送信
  yes -> メディア / MEDIA: / 短文か？
          yes -> テキストを送信
          no  -> 長さ > 制限？
                   no  -> TTS -> 音声を添付
                   yes -> 要約は有効か？
                            no  -> テキストを送信
                            yes -> 要約する（summaryModel または agents.defaults.model.primary）
                                      -> TTS -> 音声を添付

​

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

/tts off
/tts always
/tts inbound
/tts tagged
/tts status
/tts provider openai
/tts limit 2000
/tts summary off
/tts audio Hello from OpenClaw

• コマンドには認可されたsenderが必要です（allowlist / ownerルールは引き続き適用されます）。
• commands.textまたはネイティブコマンド登録が有効である必要があります。
• off|always|inbound|taggedはセッションごとのトグルです（/tts onは/tts alwaysのエイリアス）。
• limitとsummaryはメイン設定ではなく、local prefsに保存されます。
• /tts audioは単発の音声返信を生成します（TTSをオンには切り替えません）。
• /tts statusには、直近の試行に対するフォールバック可視性が含まれます:
  • 成功フォールバック: Fallback: <primary> -> <used> と Attempts: ...
  • 失敗: Error: ... と Attempts: ...
  • 詳細診断: Attempt details: provider:outcome(reasonCode) latency
• OpenAIおよびElevenLabsのAPI失敗には、解析済みプロバイダーエラー詳細とリクエストid（プロバイダーが返した場合）が含まれるようになっており、TTSエラー / ログで表示されます。

​

エージェントツール

​

Gateway RPC

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