Audio / Ghi Âm — 2026-01-17

Những gì hoạt động

Hiểu media (audio): Nếu tính năng hiểu audio được bật (hoặc tự động phát hiện), OpenClaw sẽ:
1. Tìm file audio đính kèm đầu tiên (đường dẫn local hoặc URL) và tải về nếu cần.
2. Kiểm tra maxBytes trước khi gửi đến từng model entry.
3. Chạy model entry đủ điều kiện đầu tiên theo thứ tự (provider hoặc CLI).
4. Nếu thất bại hoặc bỏ qua (do kích thước/timeout), nó sẽ thử entry tiếp theo.
5. Khi thành công, nó thay thế Body bằng block [Audio] và set {{Transcript}}.
Phân tích lệnh: Khi chuyển đổi thành công, CommandBody/RawBody được set thành transcript để các lệnh slash vẫn hoạt động.
Logging chi tiết: Ở chế độ --verbose, hệ thống sẽ log khi transcription chạy và khi nó thay thế body.

Tự động phát hiện (mặc định)

Nếu các bạn không config models và tools.media.audio.enabled không được set thành false, OpenClaw sẽ tự động phát hiện theo thứ tự này và dừng lại ở option đầu tiên hoạt động:

Local CLIs (nếu đã cài)
- sherpa-onnx-offline (cần SHERPA_ONNX_MODEL_DIR với encoder/decoder/joiner/tokens)
- whisper-cli (từ whisper-cpp; dùng WHISPER_CPP_MODEL hoặc tiny model đi kèm)
- whisper (Python CLI; tự động tải models)
Gemini CLI (gemini) dùng read_many_files
Provider keys (OpenAI → Groq → Deepgram → Google)

Để tắt tự động phát hiện, set tools.media.audio.enabled: false. Để tùy chỉnh, set tools.media.audio.models. Lưu ý: Phát hiện binary là best-effort trên macOS/Linux/Windows; đảm bảo CLI nằm trong PATH (hệ thống sẽ expand ~), hoặc set một CLI model rõ ràng với đường dẫn lệnh đầy đủ.

Ví dụ config

Provider + CLI fallback (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,
          },
        ],
      },
    },
  },
}

Chỉ dùng Provider với scope gating

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

Chỉ dùng Provider (Deepgram)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}

Lưu ý & giới hạn

Provider auth tuân theo thứ tự auth model chuẩn (auth profiles, env vars, models.providers.*.apiKey).
Deepgram sẽ lấy DEEPGRAM_API_KEY khi provider: "deepgram" được dùng.
Chi tiết setup Deepgram: Deepgram (audio transcription).
Audio providers có thể override baseUrl, headers, và providerOptions qua tools.media.audio.
Giới hạn kích thước mặc định là 20MB (tools.media.audio.maxBytes). Audio quá khổ sẽ bị bỏ qua cho model đó và entry tiếp theo sẽ được thử.
maxChars mặc định cho audio là không set (transcript đầy đủ). Set tools.media.audio.maxChars hoặc maxChars cho từng entry để cắt ngắn output.
OpenAI mặc định tự động là gpt-4o-mini-transcribe; set model: "gpt-4o-transcribe" để có độ chính xác cao hơn.
Dùng tools.media.audio.attachments để xử lý nhiều ghi âm (mode: "all" + maxAttachments).
Transcript có sẵn cho templates dưới dạng {{Transcript}}.
CLI stdout bị giới hạn (5MB); giữ output CLI ngắn gọn nhé.

Những điểm cần lưu ý

Scope rules dùng first-match wins. chatType được chuẩn hóa thành direct, group, hoặc room.
Đảm bảo CLI của các bạn exits 0 và in plain text; JSON cần được xử lý qua jq -r .text.
Giữ timeout hợp lý (timeoutSeconds, mặc định 60s) để tránh block reply queue.