OpenClawのTTS設定ガイド：ElevenLabsやOpenAIを連携

テキスト読み上げ (TTS)

OpenClawでは、ElevenLabs、Microsoft、OpenAIを使用して、送信する返信内容を音声に変換できます。OpenClawが音声を送信できる場所ならどこでも動作します。

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

ElevenLabs（メインまたはフォールバックプロバイダー）
Microsoft（メインまたはフォールバックプロバイダー。現在の実装では node-edge-tts を使用しています）
OpenAI（メインまたはフォールバックプロバイダー。要約にも使用されます）

Microsoft 音声に関する注意点

同梱されている Microsoft 音声プロバイダーは、現在 node-edge-tts ライブラリを介して Microsoft Edge のオンラインニューラル TTS サービスを利用しています。これはホスト型サービス（ローカルではありません）で、Microsoft のエンドポイントを使用し、API キーは不要です。 node-edge-tts は音声設定オプションや出力フォーマットを公開していますが、すべてのオプションがサービスでサポートされているわけではありません。edge を使用したレガシーな設定やディレクティブ入力も引き続き動作し、microsoft に統合されます。

このパスは公開ウェブサービスであり、公開された SLA や制限（クォータ）がないため、ベストエフォートとして扱ってください。保証された制限やサポートが必要な場合は、OpenAI または ElevenLabs を使用してください。

オプションのキー

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

ELEVENLABS_API_KEY（または XI_API_KEY）
OPENAI_API_KEY

Microsoft 音声には API キーは不要です。

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

サービスリンク

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

いいえ。Auto-TTS はデフォルトでオフになっています。設定の messages.tts.auto で有効にするか、セッションごとに /tts always（エイリアス：/tts on）で有効にしてください。

messages.tts.provider が設定されていない場合、OpenClaw はレジストリの自動選択順に従って、最初に設定された音声プロバイダーを選択します。

AI Setup Assistant

設定

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

Microsoft の音声を無効化する

{
  messages: {
    tts: {
      providers: {
        microsoft: {
          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: レガシーな切り替えスイッチです（起動時に auto へ移行されます）。
mode: "final" (デフォルト) または "all" (ツールやブロックの返信も含む)。
provider: "elevenlabs", "microsoft", "openai" などのプロバイダー ID です（フォールバックは自動で行われます）。
provider が未設定の場合、OpenClaw はレジストリの自動選択順に従って、最初に設定されているプロバイダーを使用します。
レガシーな provider: "edge" も引き続き動作し、microsoft に正規化されます。
summaryModel: 自動要約用のオプションの軽量モデルです。デフォルトは agents.defaults.model.primary です。
- provider/model 形式、または設定済みのモデルエイリアスを指定できます。
modelOverrides: モデルが TTS ディレクティブを発行することを許可します（デフォルトで有効）。
- allowProvider: デフォルトは false です（プロバイダーの切り替えを許可する場合はオプトインが必要です）。
providers.<id>: プロバイダー ID ごとの固有設定です。
レガシーなプロバイダー設定ブロック（messages.tts.openai など）は、読み込み時に messages.tts.providers.<id> へ自動移行されます。
maxTextLength: TTS 入力の最大文字数制限です。これを超えると /tts audio は失敗します。
timeoutMs: リクエストのタイムアウト時間（ミリ秒）です。
prefsPath: ローカル設定（プロバイダー、制限、要約）の JSON パスを上書きします。
apiKey: 設定がない場合は環境変数 (ELEVENLABS_API_KEY/XI_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: ISO 639-1 形式の 2 文字コード（例: en, ja）。
providers.elevenlabs.seed: 0 から 4294967295 の整数（決定性を高めるためのベストエフォート値）。
providers.microsoft.enabled: Microsoft 音声の使用を許可します（デフォルトは true、API キーは不要）。
providers.microsoft.voice: Microsoft ニューラル音声名（例: en-US-MichelleNeural）。
providers.microsoft.lang: 言語コード（例: en-US）。
providers.microsoft.outputFormat: 出力フォーマット（例: audio-24khz-48kbitrate-mono-mp3）。
- 有効な値については Microsoft Speech の出力フォーマットを確認してください。すべてのフォーマットが同梱の Edge ベースのトランスポートでサポートされているわけではありません。
providers.microsoft.rate / providers.microsoft.pitch / providers.microsoft.volume: パーセント文字列（例: +10%, -5%）。
providers.microsoft.saveSubtitles: 音声ファイルと一緒に JSON 形式の字幕を保存します。
providers.microsoft.proxy: Microsoft 音声リクエスト用のプロキシ URL です。
providers.microsoft.timeoutMs: リクエストタイムアウトの上書き設定（ミリ秒）です。
edge.*: 同じ Microsoft 設定のレガシーなエイリアスです。

モデル主導のオーバーライド（デフォルトで有効）

デフォルトでは、モデルは 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（登録済みのプロバイダー ID。例: openai, elevenlabs, microsoft。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,
      },
    },
  },
}

AI Setup Assistant

次のステップ

ユーザーごとの設定

Slash commands を使用すると、ローカルのオーバーライド設定が prefsPath に書き込まれます。デフォルトの保存先は ~/.openclaw/settings/tts.json ですが、OPENCLAW_TTS_PREFS または messages.tts.prefsPath を使って保存場所を変更することも可能です。

保存されるフィールドは以下の通りです：

enabled
provider
maxLength（要約を開始するしきい値。デフォルトは 1500 文字）
summarize（デフォルトは true）

これらの設定は、そのホストにおける messages.tts.* の設定よりも優先して適用されます。

出力フォーマット（固定）

各チャネルで使用される音声フォーマットは、以下のように固定されています。

Feishu / Matrix / Telegram / WhatsApp: Opus ボイスメッセージ（ElevenLabs の場合は opus_48000_64、OpenAI の場合は opus）を使用します。
- 48kHz / 64kbps は、ボイスメッセージとして音質とデータ量のバランスが非常に優れています。
その他のチャネル: MP3（ElevenLabs の場合は mp3_44100_128、OpenAI の場合は mp3）を使用します。
- 44.1kHz / 128kbps は、音声の明瞭さを保つための標準的な設定です。
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 の動作

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に関する注意点：Discordには標準で /tts コマンドが存在するため、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

注意点：

コマンドの実行には権限を持つ送信者である必要があります（allowlistやオーナー設定のルールが適用されます）。
commands.text またはネイティブコマンドの登録が有効になっている必要があります。
off|always|inbound|tagged はセッションごとの切り替え設定です（/tts on は /tts always のエイリアスとして機能します）。
limit と summary はメインの config ではなく、ローカルの prefs に保存されます。
/tts audio は単発のオーディオ返信を生成するためのもので、TTS 設定をオンに切り替えることはありません。
/tts status には、最新の試行におけるフォールバックの状況が含まれます：
- 成功時のフォールバック表示：Fallback: <primary> -> <used> および Attempts: ...
- 失敗時：Error: ... および Attempts: ...
- 詳細な診断情報：Attempt details: provider:outcome(reasonCode) latency
OpenAI と ElevenLabs の API 失敗時に、プロバイダーから返された詳細なエラー内容と request id が解析されるようになりました。これらは TTS のエラーやログに表示されます。

Agent ツール

tts ツールはテキストを音声に変換し、返信用のオーディオ添付ファイルを返します。チャンネルが Feishu, Matrix, Telegram, WhatsApp のいずれかである場合、オーディオはファイル添付ではなくボイスメッセージとして配信されます。

Gateway RPC

Gateway メソッドは以下の通りです：

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

OpenClaw Expert

まだ解決しませんか？

このページで解決しない場合は、OpenClaw Expertに直接質問してください。