音声とボイスメモ

動作すること

• メディア理解（音声）: 音声理解が有効な場合（または自動検出された場合）、OpenClaw は次を行います。
  1. 最初の音声添付（ローカルパスまたは URL）を見つけ、必要に応じてダウンロードします。
  2. 各モデルエントリに送信する前に maxBytes を適用します。
  3. 対象となる最初のモデルエントリを順番に実行します（プロバイダーまたは CLI）。
  4. 失敗またはスキップ（サイズ/タイムアウト）した場合、次のエントリを試します。
  5. 成功すると、Body を [Audio] ブロックに置き換え、{{Transcript}} を設定します。
• コマンド解析: 文字起こしが成功すると、スラッシュコマンドが引き続き動作するように、CommandBody/RawBody が文字起こしに設定されます。
• 詳細ログ: --verbose では、文字起こしの実行時と本文を置き換えた時点をログに記録します。

自動検出（デフォルト）

モデルを設定していないかつ tools.media.audio.enabled が false に設定されていない場合、 OpenClaw は次の順序で自動検出し、最初に動作したオプションで停止します。

1. アクティブな返信モデル（そのプロバイダーが音声理解をサポートしている場合）。
2. ローカル CLI（インストール済みの場合）
   • sherpa-onnx-offline（encoder/decoder/joiner/tokens を含む SHERPA_ONNX_MODEL_DIR が必要）
   • whisper-cli（whisper-cpp 由来。WHISPER_CPP_MODEL またはバンドルされた tiny モデルを使用）
   • whisper（Python CLI。モデルを自動的にダウンロード）
3. プロバイダー認証
   • 音声をサポートする、設定済みの models.providers.* エントリが先に試されます
   • プロバイダーのフォールバック順序: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

2026-05-22 時点で、Gemini CLI の自動検出はメディア理解ではサポートされなくなりました。Google は Gemini CLI ユーザーを Antigravity CLI に移行しています。音声にはローカルまたはプロバイダーの文字起こしを使用し、画像/動画の CLI フォールバックは Antigravity CLI（agy）に移行してください。

自動検出を無効にするには、tools.media.audio.enabled: false を設定します。 カスタマイズするには、tools.media.audio.models を設定します。 注: バイナリ検出は macOS/Linux/Windows 全体でベストエフォートです。CLI が PATH 上にあることを確認するか（~ は展開されます）、完全なコマンドパスを持つ明示的な CLI モデルを設定してください。

設定例

プロバイダー + CLI フォールバック（OpenAI + Whisper CLI）

{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-mini-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{MediaPath}}"],            timeoutSeconds: 45,          },        ],      },    },  },}

スコープ制御付きプロバイダーのみ

{  tools: {    media: {      audio: {        enabled: true,        scope: {          default: "allow",          rules: [{ action: "deny", match: { chatType: "group" } }],        },        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],      },    },  },}

プロバイダーのみ（Deepgram）

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "deepgram", model: "nova-3" }],      },    },  },}

プロバイダーのみ（Mistral Voxtral）

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],      },    },  },}

プロバイダーのみ（SenseAudio）

{  tools: {    media: {      audio: {        enabled: true,        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],      },    },  },}

文字起こしをチャットにエコー（オプトイン）

{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true, // default is false        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],      },    },  },}

注記と制限

• プロバイダー認証は標準のモデル認証順序（認証プロファイル、環境変数、models.providers.*.apiKey）に従います。
• Groq のセットアップ詳細: Groq。
• provider: "deepgram" が使用される場合、Deepgram は DEEPGRAM_API_KEY を取得します。
• Deepgram のセットアップ詳細: Deepgram（音声文字起こし）。
• Mistral のセットアップ詳細: Mistral。
• provider: "senseaudio" が使用される場合、SenseAudio は SENSEAUDIO_API_KEY を取得します。
• SenseAudio のセットアップ詳細: SenseAudio。
• 音声プロバイダーは、tools.media.audio 経由で baseUrl、headers、providerOptions を上書きできます。
• デフォルトのサイズ上限は 20MB（tools.media.audio.maxBytes）です。上限を超える音声はそのモデルではスキップされ、次のエントリが試されます。
• 1024 バイト未満の極小または空の音声ファイルは、プロバイダー/CLI 文字起こしの前にスキップされます。
• 音声のデフォルト maxChars は未設定です（完全な文字起こし）。出力を短くするには tools.media.audio.maxChars またはエントリごとの maxChars を設定します。
• OpenAI の自動デフォルトは gpt-4o-mini-transcribe です。精度を高めるには model: "gpt-4o-transcribe" を設定します。
• 複数のボイスメモを処理するには tools.media.audio.attachments を使用します（mode: "all" + maxAttachments）。
• 文字起こしはテンプレートで {{Transcript}} として利用できます。
• tools.media.audio.echoTranscript はデフォルトでオフです。有効にすると、エージェント処理の前に元のチャットへ文字起こし確認を送信します。
• tools.media.audio.echoFormat はエコーテキストをカスタマイズします（プレースホルダー: {transcript}）。
• CLI の stdout には上限があります（5MB）。CLI 出力は簡潔に保ってください。
• CLI の args では、ローカル音声ファイルパスに {{MediaPath}} を使用してください。古い audio.transcription.command 設定の非推奨 {input} プレースホルダーを移行するには、openclaw doctor --fix を実行します。

プロキシ環境のサポート

プロバイダーベースの音声文字起こしは、標準の送信プロキシ環境変数に従います。

• HTTPS_PROXY
• HTTP_PROXY
• ALL_PROXY
• https_proxy
• http_proxy
• all_proxy

プロキシ環境変数が設定されていない場合、直接送信が使用されます。プロキシ設定が不正な場合、OpenClaw は警告をログに記録し、直接 fetch にフォールバックします。

グループでのメンション検出

グループチャットに requireMention: true が設定されている場合、OpenClaw はメンションを確認する前に音声を文字起こしするようになりました。これにより、メンションを含むボイスメモも処理できます。

仕組み:

1. 音声メッセージにテキスト本文がなく、グループでメンションが必要な場合、OpenClaw は「事前」文字起こしを実行します。
2. 文字起こしはメンションパターン（例: @BotName、絵文字トリガー）に照合されます。
3. メンションが見つかった場合、メッセージは完全な返信パイプラインに進みます。
4. ボイスメモがメンションゲートを通過できるように、文字起こしがメンション検出に使用されます。

フォールバック動作:

• 事前処理中に文字起こしが失敗した場合（タイムアウト、API エラーなど）、メッセージはテキストのみのメンション検出に基づいて処理されます。
• これにより、混在メッセージ（テキスト + 音声）が誤って破棄されないことを保証します。

Telegram グループ/トピックごとのオプトアウト:

• そのグループの事前文字起こしメンションチェックをスキップするには、channels.telegram.groups.<chatId>.disableAudioPreflight: true を設定します。
• トピックごとに上書きするには、channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight を設定します（スキップするには true、強制的に有効にするには false）。
• デフォルトは false です（メンションゲート条件に一致すると事前処理が有効）。

例: ユーザーが requireMention: true の Telegram グループで、「Hey @Claude, what's the weather?」と言うボイスメモを送信します。ボイスメモが文字起こしされ、メンションが検出され、エージェントが返信します。

注意点

• スコープルールでは最初に一致したものが優先されます。chatType は direct、group、または room に正規化されます。
• CLI が 0 で終了し、プレーンテキストを出力することを確認してください。JSON は jq -r .text 経由で整形する必要があります。
• parakeet-mlx で --output-dir を渡す場合、--output-format が txt（または省略）であれば、OpenClaw は <output-dir>/<media-basename>.txt を読み取ります。txt 以外の出力形式では stdout 解析にフォールバックします。
• 返信キューをブロックしないように、タイムアウト（timeoutSeconds、デフォルト 60 秒）は適切に設定してください。
• 事前文字起こしは、メンション検出のために最初の音声添付のみを処理します。追加の音声はメインのメディア理解フェーズで処理されます。

関連

• メディア理解
• トークモード
• 音声ウェイク