音声 / ボイスメモ — 2026-01-17

対応状況

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

自動検出（デフォルト）

モデルを設定していない状態で、tools.media.audio.enabled が false に設定されていない場合、 OpenClaw は以下の順序で自動検出を行い、最初に動作したものを使用します。

  1. ローカル CLI（インストール済みの場合）
    • sherpa-onnx-offline（SHERPA_ONNX_MODEL_DIR に encoder/decoder/joiner/tokens が必要）
    • whisper-cli（whisper-cpp から。WHISPER_CPP_MODEL またはバンドルされた tiny モデルを使用）
    • whisper（Python CLI。モデルは自動ダウンロード）
  2. Gemini CLI（gemini）read_many_files を使用
  3. プロバイダキー（OpenAI → Groq → Deepgram → Google）

自動検出を無効にするには、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" }],
      },
    },
  },
}

トランスクリプトをチャットにエコー（オプトイン）

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // デフォルトは false
        echoFormat: '📝 "{transcript}"', // 任意。{transcript} プレースホルダー対応
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

補足事項と制限

  • プロバイダ認証は標準のモデル認証順序に従います（認証プロファイル、環境変数、models.providers.*.apiKey）。
  • provider: "deepgram" 使用時、Deepgram は DEEPGRAM_API_KEY を参照します。
  • Deepgram のセットアップ詳細: Deepgram（音声文字起こし）。
  • Mistral のセットアップ詳細: Mistral。
  • 音声プロバイダは 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 の標準出力は上限 5MB。CLI の出力は簡潔に保ってください。

プロキシ環境のサポート

プロバイダベースの音声文字起こしは、標準のアウトバウンドプロキシ環境変数に対応しています。

  • HTTPS_PROXY
  • HTTP_PROXY
  • https_proxy
  • http_proxy

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

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

グループチャットで 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 グループで「ねえ @Claude、天気は？」というボイスメモを送信した場合、ボイスメモが文字起こしされ、メンションが検出され、エージェントが返信します。

注意点

  • スコープルールは先着優先です。chatType は direct、group、room に正規化されます。
  • CLI が終了コード 0 でプレーンテキストを出力することを確認してください。JSON の場合は jq -r .text で整形が必要です。
  • parakeet-mlx の場合、--output-dir を指定すると、--output-format が txt（または省略時）のとき、OpenClaw は <output-dir>/<media-basename>.txt を読み取ります。txt 以外の出力形式では標準出力のパースにフォールバックします。
  • タイムアウトは適切に設定してください（timeoutSeconds、デフォルト 60 秒）。返信キューのブロックを避けるためです。
  • プリフライト文字起こしはメンション検出のために最初の音声添付ファイルのみを処理します。追加の音声はメインのメディア理解フェーズで処理されます。
arrow_back
前へ
Images
次へ
Camera
arrow_forward