コンテンツにスキップ
OpenClaw

OpenClawの音声合成設定：ElevenLabsやEdge TTSを導入

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

Section titled “サポートされているサービス”

OpenClawは、ElevenLabs、Microsoft、OpenAIを使って、送信する返信内容を音声に変換できます。OpenClawが音声を送信できる環境であれば、どこでも利用可能です。

  • ElevenLabs (メインまたはフォールバックプロバイダー)
  • Microsoft (メインまたはフォールバックプロバイダー。現在の実装では node-edge-tts を使用)
  • OpenAI (メインまたはフォールバックプロバイダー。要約にも使用)

Microsoft 音声に関する注意点

Section titled “Microsoft 音声に関する注意点”

同梱されている Microsoft 音声プロバイダーは、現在 node-edge-tts ライブラリを経由して Microsoft Edge のオンラインニューラル TTS サービスを利用しています。これはローカルではなくホストされたサービスであり、Microsoft のエンドポイントを使用します。API キーは必要ありません。 node-edge-tts は音声設定オプションや出力形式を公開していますが、すべてのオプションがこのサービスでサポートされているわけではありません。以前の edge を使った設定やディレクティブ入力も引き続き動作し、自動的に microsoft へ正規化されます。

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

オプションのキー

Section titled “オプションのキー”

OpenAI または ElevenLabs を使用したい場合は、以下のキーを設定してください。

  • ELEVENLABS_API_KEY (または XI_API_KEY)
  • OPENAI_API_KEY

Microsoft の音声サービスには API キーは 不要 です。

複数のプロバイダーが設定されている場合、選択されたプロバイダーが優先的に使用され、その他はフォールバックオプションとなります。 自動要約（Auto-summary）は、設定された summaryModel (または agents.defaults.model.primary) を使用します。そのため、要約機能を有効にする場合は、そのプロバイダーの認証も済ませておく必要があります。

サービスリンク

Section titled “サービスリンク”

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

Section titled “デフォルトで有効ですか？”

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

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

AI Setup Assistant

次のステップ

Section titled “次のステップ”

設定

Section titled “設定”

TTSの設定は、openclaw.json の messages.tts セクションで行います。 詳細なスキーマについては、Gateway configuration を参照してください。

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

Section titled “最小限の設定（有効化 + プロバイダー指定）”
{
  messages: {
    tts: {
      auto: "always",
      provider: "elevenlabs",
    },
  },
}

OpenAIをメインにし、ElevenLabsをフォールバックにする設定

Section titled “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キー不要）

Section titled “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の音声を無効化する

Section titled “Microsoftの音声を無効化する”
{
  messages: {
    tts: {
      providers: {
        microsoft: {
          enabled: false,
        },
      },
    },
  },
}

カスタム制限と設定パスの指定

Section titled “カスタム制限と設定パスの指定”
{
  messages: {
    tts: {
      auto: "always",
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
    },
  },
}

受信メッセージが音声の場合のみ音声で返信する

Section titled “受信メッセージが音声の場合のみ音声で返信する”
{
  messages: {
    tts: {
      auto: "inbound",
    },
  },
}

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

Section titled “長い返信に対する自動要約を無効化する”
{
  messages: {
    tts: {
      auto: "always",
    },
  },
}

その後、以下のコマンドを実行します：

/tts summary off

各フィールドの解説

Section titled “各フィールドの解説”
  • auto: 自動TTSモード (off, always, inbound, tagged)。
    • inbound: 音声メッセージを受信した後にのみ音声を送信します。
    • tagged: 返信に [[tts]] タグが含まれている場合にのみ音声を送信します。
  • enabled: レガシーな切り替えスイッチです（doctorコマンドによって 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.elevenlabs, messages.tts.microsoft, messages.tts.edge) は、ロード時に自動的に 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, de）。
  • 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: Microsoftの出力フォーマット（例: 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設定に対するレガシーなエイリアスです。

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

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

デフォルトでは、モデルが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,
      },
    },
  },
}

ユーザーごとの設定

Section titled “ユーザーごとの設定”

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

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

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

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

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

Section titled “出力フォーマット（固定）”
  • 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 の動作

Section titled “Auto-TTS の動作”

Auto-TTS を有効にすると、OpenClaw は次のように動作します。

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

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

フロー図

Section titled “フロー図”
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

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

Section titled “スラッシュコマンドの使い方”

使用できるコマンドは /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

注意点：

  • コマンドの実行には権限を持つ送信者である必要があります（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 ツール

Section titled “Agent ツール”

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

Gateway RPC

Section titled “Gateway RPC”

Gateway メソッド：

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

OpenClaw Expert

まだ解決しませんか？

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