テキスト読み上げ（TTS）

OpenClawは、ElevenLabs、OpenAI、またはEdge TTSを使用して、送信する返信を音声に変換できます。 OpenClawが音声を送信できる場所ならどこでも機能し、Telegramでは丸いボイスノート形式で表示されます。

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

• ElevenLabs（プライマリまたはフォールバックプロバイダー）
• OpenAI（プライマリまたはフォールバックプロバイダー、要約にも使用）
• Edge TTS（プライマリまたはフォールバックプロバイダー、node-edge-tts を使用、APIキーがない場合のデフォルト）

Edge TTSの注意事項

Edge TTSは、node-edge-tts ライブラリを介してMicrosoft EdgeのオンラインニューラルTTSサービスを使用します。これはホストされたサービス（ローカルではない）で、Microsoftのエンドポイントを使用し、APIキーは不要です。node-edge-tts は音声設定オプションと出力形式を公開しますが、すべてのオプションがEdgeサービスでサポートされているわけではありません。

Edge TTSは公開されたSLAやクォータのない公開Webサービスであるため、ベストエフォート型として扱ってください。保証された制限とサポートが必要な場合は、OpenAIまたはElevenLabsを使用してください。MicrosoftのSpeech REST APIは、リクエストごとに10分の音声制限を文書化していますが、Edge TTSは制限を公開していないため、同様またはそれ以下の制限を想定してください。

オプションのキー

OpenAIまたはElevenLabsを使用する場合：

• ELEVENLABS_API_KEY（または XI_API_KEY）
• OPENAI_API_KEY

Edge TTSは APIキーを必要としません。APIキーが見つからない場合、OpenClawはデフォルトでEdge TTSを使用します（messages.tts.edge.enabled=false で無効化されていない限り）。

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

サービスリンク

• OpenAI Text-to-Speechガイド
• OpenAI Audio APIリファレンス
• ElevenLabs Text to Speech
• ElevenLabs認証
• node-edge-tts
• Microsoft Speech出力形式

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

いいえ。自動TTSはデフォルトで オフ です。設定で messages.tts.auto を使用するか、セッションごとに /tts always（エイリアス：/tts on）で有効にします。

Edge TTSは、TTSがオンになるとデフォルトで 有効 になり、OpenAIまたはElevenLabsのAPIキーが利用できない場合に自動的に使用されます。

設定

TTS設定は openclaw.json の messages.tts の下にあります。 完全なスキーマはGateway設定にあります。

最小限の設定（有効化 + プロバイダー）

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

OpenAIプライマリ、ElevenLabsフォールバック

{
  messages: {
    tts: {
      auto: "always",
      provider: "openai",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: {
        enabled: true
      },
      openai: {
        apiKey: "openai_api_key",
        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
        }
      }
    }
  }
}

Edge TTSプライマリ（APIキーなし）

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

Edge TTSを無効化

{
  messages: {
    tts: {
      edge: {
        enabled: false
      }
    }
  }
}

カスタム制限 + 設定パス

{
  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"、"openai"、または "edge"（フォールバックは自動）。
• provider が 未設定 の場合、OpenClawは openai（キーがある場合）、次に elevenlabs（キーがある場合）、 それ以外は edge を優先します。
• summaryModel：自動要約用のオプションの安価なモデル、デフォルトは agents.defaults.model.primary。
  • provider/model または設定されたモデルエイリアスを受け入れます。
• modelOverrides：モデルがTTSディレクティブを発行できるようにします（デフォルトでオン）。
• maxTextLength：TTS入力のハードキャップ（文字数）。超過すると /tts audio が失敗します。
• timeoutMs：リクエストタイムアウト（ミリ秒）。
• prefsPath：ローカル設定JSONパスを上書き（プロバイダー/制限/要約）。
• apiKey 値は環境変数（ELEVENLABS_API_KEY/XI_API_KEY、OPENAI_API_KEY）にフォールバックします。
• elevenlabs.baseUrl：ElevenLabs API Base URLを上書きします。
• elevenlabs.voiceSettings：
  • stability、similarityBoost、style：0..1
  • useSpeakerBoost：true|false
  • speed：0.5..2.0（1.0 = 通常）
• elevenlabs.applyTextNormalization：auto|on|off
• elevenlabs.languageCode：2文字のISO 639-1（例：en、de）
• elevenlabs.seed：整数 0..4294967295（ベストエフォート決定論）
• edge.enabled：Edge TTSの使用を許可（デフォルト true、APIキー不要）。
• edge.voice：Edgeニューラル音声名（例：en-US-MichelleNeural）。
• edge.lang：言語コード（例：en-US）。
• edge.outputFormat：Edge出力形式（例：audio-24khz-48kbitrate-mono-mp3）。
  • 有効な値についてはMicrosoft Speech出力形式を参照してください。すべての形式がEdgeでサポートされているわけではありません。
• edge.rate / edge.pitch / edge.volume：パーセント文字列（例：+10%、-5%）。
• edge.saveSubtitles：音声ファイルと一緒にJSON字幕を書き込みます。
• edge.proxy：Edge TTSリクエスト用のプロキシURL。
• edge.timeoutMs：リクエストタイムアウトの上書き（ミリ秒）。

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

デフォルトでは、モデルは単一の返信に対してTTSディレクティブを発行 できます。 messages.tts.auto が tagged の場合、これらのディレクティブは音声をトリガーするために必要です。

有効な場合、モデルは単一の返信の音声を上書きするために [[tts:...]] ディレクティブを発行でき、さらにオプションで [[tts:text]]...[[/tts:text]] ブロックを提供して、音声のみに表示される表現豊かなタグ（笑い声、歌の合図など）を提供できます。

返信ペイロードの例：

どうぞ。

[[tts:provider=elevenlabs voiceId=pMsXgVXv3BLzUgSXRplE model=eleven_v3 speed=1.1]]
[[tts:text]](笑い) もう一度歌を読んでください。[[/tts:text]]

利用可能なディレクティブキー（有効な場合）：

• provider（openai | elevenlabs | edge）
• voice（OpenAI音声）または voiceId（ElevenLabs）
• model（OpenAI TTSモデルまたはElevenLabsモデルID）
• stability、similarityBoost、style、speed、useSpeakerBoost
• applyTextNormalization（auto|on|off）
• languageCode（ISO 639-1）
• seed

すべてのモデル上書きを無効化：

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

オプションの許可リスト（タグを有効にしたまま特定の上書きを無効化）：

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

ユーザーごとの設定

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

保存されるフィールド：

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

これらはそのホストの messages.tts.* を上書きします。

出力形式（固定）

• Telegram：Opusボイスノート（ElevenLabsから opus_48000_64、OpenAIから opus）。
  • 48kHz / 64kbpsは良いボイスノートのトレードオフで、丸い吹き出しに必要です。
• その他のチャネル：MP3（ElevenLabsから mp3_44100_128、OpenAIから mp3）。
  • 44.1kHz / 128kbpsは音声の明瞭さのデフォルトバランスです。
• Edge TTS：edge.outputFormat を使用（デフォルト audio-24khz-48kbitrate-mono-mp3）。
  • node-edge-tts は outputFormat を受け入れますが、すべての形式がEdgeサービスから利用できるわけではありません。
  • 出力形式の値はMicrosoft Speech出力形式に従います（Ogg/WebM Opusを含む）。
  • TelegramのsendVoiceはOGG/MP3/M4Aを受け入れます。保証されたOpusボイスノートが必要な場合はOpenAI/ElevenLabsを使用してください。
  • 設定されたEdge出力形式が失敗した場合、OpenClawはMP3で再試行します。

OpenAI/ElevenLabsの形式は固定されています。TelegramはボイスノートUXのためにOpusを期待します。

自動TTS動作

有効な場合、OpenClawは：

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

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

フロー図

返信 -> TTSが有効？
  いいえ  -> テキストを送信
  はい -> メディア / MEDIA: / 短い？
          はい -> テキストを送信
          いいえ  -> 長さ > 制限？
                   いいえ  -> TTS -> 音声を添付
                   はい -> 要約が有効？
                            いいえ  -> テキストを送信
                            はい -> 要約（summaryModelまたはagents.defaults.model.primary）
                                      -> TTS -> 音声を添付

スラッシュコマンドの使用

単一のコマンドがあります：/tts。 有効化の詳細については、スラッシュコマンドを参照してください。

Discordの注意：/tts はDiscordの組み込みコマンドであるため、OpenClawはそこでネイティブコマンドとして /voice を登録します。テキスト /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

注意事項：

• コマンドには認証された送信者が必要です（許可リスト/所有者ルールが引き続き適用されます）。
• commands.text またはネイティブコマンド登録が有効になっている必要があります。
• off|always|inbound|tagged はセッションごとのトグルです（/tts on は /tts always のエイリアスです）。
• limit と summary はメイン設定ではなく、ローカル設定に保存されます。
• /tts audio はワンオフの音声返信を生成します（TTSをオンにしません）。

エージェントツール

tts ツールはテキストを音声に変換し、MEDIA: パスを返します。結果がTelegram互換の場合、ツールには [[audio_as_voice]] が含まれるため、Telegramはボイスバブルを送信します。

Gateway RPC

Gatewayメソッド：

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