音声とボイスメモ

​

機能

1. 最初の音声添付ファイル（ローカルパスまたは URL）を見つけ、必要に応じてダウンロードします。
2. 各モデルエントリへ送信する前に maxBytes を適用します。
3. 対象となる最初のモデルエントリを順番に実行します（プロバイダーまたは CLI）。エントリが失敗またはスキップ（サイズ/タイムアウト）された場合は、次のエントリを試します。
4. 成功すると、Body を [Audio] ブロックに置き換え、{{Transcript}} を設定します。

​

自動検出（デフォルト）

1. アクティブな返信モデル。そのプロバイダーが音声理解をサポートしている場合。
2. 設定済みプロバイダー認証 — 音声文字起こしをサポートするプロバイダーで認証が利用可能な任意の models.providers.* エントリ。これはローカル CLI より前に確認されるため、設定済みの API キーは常に PATH 上のローカルバイナリより優先されます。 複数設定されている場合のプロバイダー優先順位: Groq、OpenAI、xAI、Deepgram、Google、SenseAudio、ElevenLabs、Mistral。
3. ローカル CLI（プロバイダー認証が解決されなかった場合のみ）。次の順序で確認されます。
   • sherpa-onnx-offline（tokens.txt、encoder.onnx、decoder.onnx、joiner.onnx を含む SHERPA_ONNX_MODEL_DIR が必要）
   • whisper-cli（whisper-cpp 由来。WHISPER_CPP_MODEL またはバンドルされた tiny モデルを使用）
   • whisper（Python CLI。モデルを自動的にダウンロード）

​

設定例

​

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

{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-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-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-transcribe" }],
      },
    },
  },
}

​

注記と制限

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

​

プロキシ環境のサポート

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

​

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

1. ボイスメッセージにテキスト本文がなく、グループがメンションを要求している場合、OpenClaw は最初の音声添付ファイルの事前文字起こしを実行します。
2. 文字起こし結果でメンションパターン（例: @BotName、絵文字トリガー）を確認します。
3. メンションが見つかった場合、メッセージは完全な返信パイプラインへ進みます。

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

​

注意点

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

​

関連

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