{
  "title": "Audio / Voice Notes — 2026-01-17",
  "content": "* **Media understanding (audio)**: If audio understanding is enabled (or auto‑detected), OpenClaw:\n  1. Locates the first audio attachment (local path or URL) and downloads it if needed.\n  2. Enforces `maxBytes` before sending to each model entry.\n  3. Runs the first eligible model entry in order (provider or CLI).\n  4. If it fails or skips (size/timeout), it tries the next entry.\n  5. On success, it replaces `Body` with an `[Audio]` block and sets `{{Transcript}}`.\n* **Command parsing**: When transcription succeeds, `CommandBody`/`RawBody` are set to the transcript so slash commands still work.\n* **Verbose logging**: In `--verbose`, we log when transcription runs and when it replaces the body.\n\n## Auto-detection (default)\n\nIf you **don’t configure models** and `tools.media.audio.enabled` is **not** set to `false`,\nOpenClaw auto-detects in this order and stops at the first working option:\n\n1. **Local CLIs** (if installed)\n   * `sherpa-onnx-offline` (requires `SHERPA_ONNX_MODEL_DIR` with encoder/decoder/joiner/tokens)\n   * `whisper-cli` (from `whisper-cpp`; uses `WHISPER_CPP_MODEL` or the bundled tiny model)\n   * `whisper` (Python CLI; downloads models automatically)\n2. **Gemini CLI** (`gemini`) using `read_many_files`\n3. **Provider keys** (OpenAI → Groq → Deepgram → Google)\n\nTo disable auto-detection, set `tools.media.audio.enabled: false`.\nTo customize, set `tools.media.audio.models`.\nNote: Binary detection is best-effort across macOS/Linux/Windows; ensure the CLI is on `PATH` (we expand `~`), or set an explicit CLI model with a full command path.\n\n### Provider + CLI fallback (OpenAI + Whisper CLI)\n\n### Provider-only with scope gating\n\n### Provider-only (Deepgram)\n\n* Provider auth follows the standard model auth order (auth profiles, env vars, `models.providers.*.apiKey`).\n* Deepgram picks up `DEEPGRAM_API_KEY` when `provider: \"deepgram\"` is used.\n* Deepgram setup details: [Deepgram (audio transcription)](/providers/deepgram).\n* Audio providers can override `baseUrl`, `headers`, and `providerOptions` via `tools.media.audio`.\n* Default size cap is 20MB (`tools.media.audio.maxBytes`). Oversize audio is skipped for that model and the next entry is tried.\n* Default `maxChars` for audio is **unset** (full transcript). Set `tools.media.audio.maxChars` or per-entry `maxChars` to trim output.\n* OpenAI auto default is `gpt-4o-mini-transcribe`; set `model: \"gpt-4o-transcribe\"` for higher accuracy.\n* Use `tools.media.audio.attachments` to process multiple voice notes (`mode: \"all\"` + `maxAttachments`).\n* Transcript is available to templates as `{{Transcript}}`.\n* CLI stdout is capped (5MB); keep CLI output concise.\n\n* Scope rules use first-match wins. `chatType` is normalized to `direct`, `group`, or `room`.\n* Ensure your CLI exits 0 and prints plain text; JSON needs to be massaged via `jq -r .text`.\n* Keep timeouts reasonable (`timeoutSeconds`, default 60s) to avoid blocking the reply queue.",
  "code_samples": [
    {
      "code": "### Provider-only with scope gating",
      "language": "unknown"
    },
    {
      "code": "### Provider-only (Deepgram)",
      "language": "unknown"
    }
  ],
  "headings": [
    {
      "level": "h2",
      "text": "What works",
      "id": "what-works"
    },
    {
      "level": "h2",
      "text": "Auto-detection (default)",
      "id": "auto-detection-(default)"
    },
    {
      "level": "h2",
      "text": "Config examples",
      "id": "config-examples"
    },
    {
      "level": "h3",
      "text": "Provider + CLI fallback (OpenAI + Whisper CLI)",
      "id": "provider-+-cli-fallback-(openai-+-whisper-cli)"
    },
    {
      "level": "h3",
      "text": "Provider-only with scope gating",
      "id": "provider-only-with-scope-gating"
    },
    {
      "level": "h3",
      "text": "Provider-only (Deepgram)",
      "id": "provider-only-(deepgram)"
    },
    {
      "level": "h2",
      "text": "Notes & limits",
      "id": "notes-&-limits"
    },
    {
      "level": "h2",
      "text": "Gotchas",
      "id": "gotchas"
    }
  ],
  "url": "llms-txt#audio-/-voice-notes-—-2026-01-17",
  "links": []
}