テキスト読み上げ（TTS）

OpenClaw は ElevenLabs、OpenAI、Edge TTS を使って、送信メッセージを音声に変換できます。 OpenClaw が音声を送信できるチャネルならどこでも動作し、Telegram では丸いボイスノートバブルで表示されます。

対応サービス

ElevenLabs（プライマリまたはフォールバック）
OpenAI（プライマリまたはフォールバック、サマリーにも使用）
Edge TTS（プライマリまたはフォールバック、node-edge-tts を使用、API キー不要時のデフォルト）

Edge TTS の補足

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

Edge TTS は公開のウェブサービスであり、SLA やクォータが公開されていないため、ベストエフォートとして扱ってください。保証された制限とサポートが必要な場合は、OpenAI または ElevenLabs を使用してください。Microsoft の Speech REST API では1リクエストあたり10分の音声制限が記載されています。Edge TTS には制限が公開されていないため、同等以下の制限を想定してください。citeturn0search3

任意のキー

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）を使用するため、サマリーを有効にする場合はそのプロバイダーも認証済みである必要があります。

サービスリンク

デフォルトで有効か？

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

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

設定

TTS の設定は openclaw.json の messages.tts 配下にあります。完全なスキーマは Gateway configuration を参照してください。

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

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

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 ディレクティブを出力可能にする（デフォルトでオン）。
- allowProvider はデフォルト false（プロバイダー切り替えはオプトイン）。
maxTextLength: TTS 入力のハード上限（文字数）。超過時に /tts audio は失敗。
timeoutMs: リクエストタイムアウト（ミリ秒）。
prefsPath: ローカルプリファレンス JSON のパスをオーバーライド（プロバイダー/制限/サマリー）。
apiKey の値は環境変数にフォールバック（ELEVENLABS_API_KEY/XI_API_KEY、OPENAI_API_KEY）。
elevenlabs.baseUrl: ElevenLabs API ベース URL のオーバーライド。
openai.baseUrl: OpenAI TTS エンドポイントのオーバーライド。
- 解決順序: messages.tts.openai.baseUrl -> OPENAI_TTS_BASE_URL -> https://api.openai.com/v1
- デフォルト以外の値は OpenAI 互換 TTS エンドポイントとして扱われるため、カスタムモデル名とボイス名が使えます。
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 output formats を参照。Edge ですべてのフォーマットがサポートされているわけではありません。
edge.rate / edge.pitch / edge.volume: パーセント文字列（例: +10%、-5%）。
edge.saveSubtitles: 音声ファイルと一緒に JSON 字幕を書き出す。
edge.proxy: Edge TTS リクエスト用のプロキシ URL。
edge.timeoutMs: リクエストタイムアウトのオーバーライド（ミリ秒）。

モデル駆動オーバーライド（デフォルトでオン）

デフォルトでは、モデルは1回の返信につき TTS ディレクティブを出力できます。 messages.tts.auto が tagged の場合、音声をトリガーするにはこれらのディレクティブが必要です。

有効にすると、モデルは [[tts:...]] ディレクティブでその返信のボイスをオーバーライドでき、[[tts:text]]...[[/tts:text]] ブロックで音声専用の表現タグ（笑い声、歌のキューなど）を提供できます。

provider=... ディレクティブは modelOverrides.allowProvider: true でないと無視されます。

返信ペイロードの例:

Here you go.

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

使用可能なディレクティブキー（有効時）:

provider（openai | elevenlabs | edge、allowProvider: true が必要）
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: true,
        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 サービスですべてのフォーマットが利用できるわけではありません。citeturn2search0
- 出力フォーマットの値は Microsoft Speech output formats に従います（Ogg/WebM Opus を含む）。citeturn1search0
- Telegram の sendVoice は OGG/MP3/M4A を受け付けます。Opus ボイスノートを保証したい場合は OpenAI/ElevenLabs を使用してください。citeturn1search1
- 設定した Edge 出力フォーマットが失敗した場合、OpenClaw は MP3 でリトライします。

OpenAI/ElevenLabs のフォーマットは固定です。Telegram はボイスノート UX のために Opus を期待します。

自動 TTS の挙動

有効にすると、OpenClaw は以下のように動作します。

返信にすでにメディアまたは MEDIA: ディレクティブが含まれている場合、TTS をスキップ。
極端に短い返信（10文字未満）はスキップ。
有効時、長文返信を agents.defaults.model.primary（または summaryModel）でサマリー化。
生成した音声を返信に添付。

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

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

コマンドは /tts 1つだけです。有効化の詳細は Slash commands を参照してください。

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 は1回限りの音声返信を生成します（TTS をオンにするわけではありません）。

エージェントツール

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

Gateway RPC

Gateway メソッド:

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