> ## Documentation Index
> Fetch the complete documentation index at: https://openclaw.veiseule.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 音声とボイスノート

# 音声／ボイスノート — 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` が必要）
   * `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 モデルを設定してください。
カスタマイズするには、`tools.media.audio.models` を設定します。
注記: バイナリ検出は macOS／Linux／Windows 全体でベストエフォートです。CLI が `PATH` 上にあること（`~` を展開します）を確認するか、完全なコマンドパスを指定した明示的な CLI モデルを設定してください。

## 設定例

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

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  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,
          },
        ],
      },
    },
  },
}
```

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

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

### プロバイダーのみ（Deepgram）

```json5 theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}
```

## 注記と制限

* プロバイダー認証は、標準のモデル認証順（認証プロファイル、環境変数、`models.providers.*.apiKey`）に従います。
* `provider: "deepgram"` が使用されている場合、Deepgram は `DEEPGRAM_API_KEY` を取得します。
* Deepgram のセットアップ詳細: [Deepgram（音声文字起こし）](/providers/deepgram)。
* 音声プロバイダーは `tools.media.audio` を介して `baseUrl`、`headers`、`providerOptions` を上書きできます。
* デフォルトサイズのキャップは 20MB です(`tools.media.audio.maxBytes`)。 デフォルトのサイズ上限は 20MB（`tools.media.audio.maxBytes`）です。上限超過の音声はそのモデルではスキップされ、次のエントリーが試行されます。 デフォルトのサイズ上限は 20MB（`tools.media.audio.maxBytes`）です。上限超過の音声はそのモデルではスキップされ、次のエントリーが試行されます。
* デフォルトの `maxChars` は**unset** (フルトランスクリプト) です。 音声のデフォルト `maxChars` は**未設定**（全文文字起こし）です。出力をトリミングするには `tools.media.audio.maxChars` またはエントリーごとの `maxChars` を設定してください。 音声のデフォルト `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 出力は簡潔に保ってください。

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

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

**仕組み：**

1. ボイスメッセージにテキスト本文がなく、かつグループでメンションが必須の場合、OpenClaw は「プレフライト」文字起こしを実行します。
2. 文字起こし結果はメンションパターン（例：`@BotName`、絵文字トリガー）に対してチェックされます。
3. メンションが見つかった場合、メッセージは完全な返信パイプラインに進みます。
4. ボイスノートがメンション判定を通過できるよう、文字起こし結果がメンション検出に使用されます。

**フォールバック動作：**

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

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

## Gotchas

* スコープルールでは、最初の試合の勝利を使用します。 スコープルールは先頭一致が優先されます。`chatType` は `direct`、`group`、または `room` に正規化されます。 スコープルールは先頭一致が優先されます。`chatType` は `direct`、`group`、または `room` に正規化されます。
* CLI が終了コード 0 で終了し、プレーンテキストを出力することを確認してください。JSON は `jq -r .text` を介して整形する必要があります。
* 返信キューのブロックを避けるため、タイムアウト（`timeoutSeconds`、デフォルト 60 秒）は適切に設定してください。
* プレフライト文字起こしでは、メンション検出のために**最初の**音声添付ファイルのみが処理されます。 追加の音声は、メインのメディア理解フェーズで処理されます。