Audio / ボイスメモ — 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（encoder/decoder/joiner/tokens を含む SHERPA_ONNX_MODEL_DIR が必要）
    • 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" }]
      }
    }
  }
}

注意事項と制限

  • プロバイダー認証は標準的なモデル認証順序に従います（auth プロファイル、環境変数、models.providers.*.apiKey）。
  • Deepgram は provider: "deepgram" を使用すると DEEPGRAM_API_KEY を取得します。
  • Deepgram セットアップの詳細: Deepgram（音声文字起こし）。
  • オーディオプロバイダーは tools.media.audio を介して baseUrl、headers、providerOptions をオーバーライドできます。
  • デフォルトのサイズ上限は 20MB（tools.media.audio.maxBytes）です。サイズ超過の音声はそのモデルでスキップされ、次のエントリが試行されます。
  • オーディオのデフォルト maxChars は未設定（完全なトランスクリプト）です。出力を切り詰めるには tools.media.audio.maxChars またはエントリごとの maxChars を設定します。
  • OpenAI の自動デフォルトは gpt-4o-mini-transcribe です。より高い精度を得るには model: "gpt-4o-transcribe" を設定します。
  • tools.media.audio.attachments を使用して複数のボイスメモを処理します（mode: "all" + maxAttachments）。
  • トランスクリプトはテンプレートで {{Transcript}} として利用できます。
  • CLI の stdout は上限があります（5MB）。CLI の出力は簡潔に保ってください。

注意点

  • スコープルールは最初一致優先です。chatType は direct、group、または room に正規化されます。
  • CLI が終了コード 0 で終了し、プレーンテキストを出力することを確認してください。JSON は jq -r .text でマッサージする必要があります。
  • タイムアウトを合理的に保ってください（timeoutSeconds、デフォルト 60秒）、返信キューのブロックを避けるため。
← ドキュメントに戻る