English简体中文繁體中文日本語EspañolPortuguês (BR)한국어DeutschFrançaisالعربيةItalianoTiếng ViệtNederlandsTürkçeУкраїнськаBahasa IndonesiaPolskiفارسیไทย

Nodes and media

Âm thanh và ghi chú thoại

Những gì hoạt động

  • Hiểu phương tiện (âm thanh): Nếu tính năng hiểu âm thanh được bật (hoặc được tự động phát hiện), OpenClaw:
    1. Tìm tệp đính kèm âm thanh đầu tiên (đường dẫn cục bộ hoặc URL) và tải xuống nếu cần.
    2. Áp dụng maxBytes trước khi gửi đến từng mục mô hình.
    3. Chạy mục mô hình đủ điều kiện đầu tiên theo thứ tự (nhà cung cấp hoặc CLI).
    4. Nếu thất bại hoặc bị bỏ qua (kích thước/hết thời gian), nó thử mục tiếp theo.
    5. Khi thành công, nó thay thế Body bằng một khối [Audio] và đặt {{Transcript}}.
  • Phân tích lệnh: Khi chép lời thành công, CommandBody/RawBody được đặt thành bản chép lời để các lệnh gạch chéo vẫn hoạt động.
  • Ghi nhật ký chi tiết: Trong --verbose, chúng tôi ghi nhật ký khi quá trình chép lời chạy và khi nó thay thế phần thân.

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

Nếu bạn không cấu hình mô hình và tools.media.audio.enabled không được đặt thành false, OpenClaw tự động phát hiện theo thứ tự này và dừng ở tùy chọn hoạt động đầu tiên:

  1. Mô hình trả lời đang hoạt động khi nhà cung cấp của nó hỗ trợ hiểu âm thanh.
  2. CLI cục bộ (nếu đã cài đặt)
    • sherpa-onnx-offline (yêu cầu SHERPA_ONNX_MODEL_DIR với encoder/decoder/joiner/tokens)
    • whisper-cli (từ whisper-cpp; dùng WHISPER_CPP_MODEL hoặc mô hình tiny đi kèm)
    • whisper (CLI Python; tự động tải xuống mô hình)
  3. Gemini CLI (gemini) dùng read_many_files
  4. Xác thực nhà cung cấp
    • Các mục models.providers.* đã cấu hình có hỗ trợ âm thanh sẽ được thử trước
    • Thứ tự dự phòng đi kèm: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

Để tắt tự động phát hiện, đặt tools.media.audio.enabled: false. Để tùy chỉnh, đặt tools.media.audio.models. Lưu ý: Phát hiện tệp nhị phân là nỗ lực tốt nhất trên macOS/Linux/Windows; hãy đảm bảo CLI nằm trên PATH (chúng tôi mở rộng ~), hoặc đặt một mô hình CLI rõ ràng với đường dẫn lệnh đầy đủ.

Ví dụ cấu hình

Nhà cung cấp + CLI dự phòng (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 nhà cung cấp với kiểm soát theo phạm vi

{
  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 nhà cung cấp (Deepgram)

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

Chỉ dùng nhà cung cấp (Mistral Voxtral)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}

Chỉ dùng nhà cung cấp (SenseAudio)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
      },
    },
  },
}

Phản hồi bản chép lời vào cuộc trò chuyện (tùy chọn bật)

{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // default is false
        echoFormat: '📝 "{transcript}"', // optional, supports {transcript}
        models: [{ provider: "openai", model: "gpt-4o-mini-transcribe" }],
      },
    },
  },
}

Ghi chú và giới hạn

  • Xác thực nhà cung cấp tuân theo thứ tự xác thực mô hình tiêu chuẩn (hồ sơ xác thực, biến môi trường, models.providers.*.apiKey).
  • Chi tiết thiết lập Groq: Groq.
  • Deepgram nhận DEEPGRAM_API_KEY khi dùng provider: "deepgram".
  • Chi tiết thiết lập Deepgram: Deepgram (chép lời âm thanh).
  • Chi tiết thiết lập Mistral: Mistral.
  • SenseAudio nhận SENSEAUDIO_API_KEY khi dùng provider: "senseaudio".
  • Chi tiết thiết lập SenseAudio: SenseAudio.
  • Các nhà cung cấp âm thanh có thể ghi đè 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). Âm thanh quá kích thước sẽ bị bỏ qua cho mô hình đó và mục tiếp theo sẽ được thử.
  • Các tệp âm thanh rất nhỏ/trống dưới 1024 byte sẽ bị bỏ qua trước khi chép lời bằng nhà cung cấp/CLI.
  • maxChars mặc định cho âm thanh là chưa đặt (toàn bộ bản chép lời). Đặt tools.media.audio.maxChars hoặc maxChars theo từng mục để cắt gọn đầu ra.
  • Mặc định tự động của OpenAI là gpt-4o-mini-transcribe; đặt model: "gpt-4o-transcribe" để có độ chính xác cao hơn.
  • Dùng tools.media.audio.attachments để xử lý nhiều ghi chú thoại (mode: "all" + maxAttachments).
  • Bản chép lời có sẵn cho mẫu dưới dạng {{Transcript}}.
  • tools.media.audio.echoTranscript mặc định tắt; bật nó để gửi xác nhận bản chép lời về cuộc trò chuyện gốc trước khi agent xử lý.
  • tools.media.audio.echoFormat tùy chỉnh văn bản phản hồi (placeholder: {transcript}).
  • stdout của CLI bị giới hạn (5MB); giữ đầu ra CLI ngắn gọn.
  • args của CLI nên dùng {{MediaPath}} cho đường dẫn tệp âm thanh cục bộ. Chạy openclaw doctor --fix để di chuyển các placeholder {input} đã ngừng dùng từ cấu hình audio.transcription.command cũ hơn.

Hỗ trợ môi trường proxy

Chép lời âm thanh dựa trên nhà cung cấp tôn trọng các biến môi trường proxy gửi ra tiêu chuẩn:

  • HTTPS_PROXY
  • HTTP_PROXY
  • ALL_PROXY
  • https_proxy
  • http_proxy
  • all_proxy

Nếu không đặt biến môi trường proxy nào, kết nối ra trực tiếp sẽ được dùng. Nếu cấu hình proxy sai định dạng, OpenClaw ghi cảnh báo và quay về tải trực tiếp.

Phát hiện nhắc đến trong nhóm

Khi requireMention: true được đặt cho cuộc trò chuyện nhóm, OpenClaw hiện chép lời âm thanh trước khi kiểm tra các lượt nhắc. Điều này cho phép xử lý ghi chú thoại ngay cả khi chúng chứa lượt nhắc.

Cách hoạt động:

  1. Nếu một tin nhắn thoại không có phần thân văn bản và nhóm yêu cầu lượt nhắc, OpenClaw thực hiện chép lời "preflight".
  2. Bản chép lời được kiểm tra theo các mẫu nhắc đến (ví dụ: @BotName, kích hoạt bằng emoji).
  3. Nếu tìm thấy lượt nhắc, tin nhắn tiếp tục đi qua toàn bộ quy trình trả lời.
  4. Bản chép lời được dùng để phát hiện lượt nhắc để ghi chú thoại có thể vượt qua cổng lượt nhắc.

Hành vi dự phòng:

  • Nếu chép lời thất bại trong preflight (hết thời gian, lỗi API, v.v.), tin nhắn được xử lý dựa trên phát hiện lượt nhắc chỉ bằng văn bản.
  • Điều này đảm bảo rằng các tin nhắn hỗn hợp (văn bản + âm thanh) không bao giờ bị loại bỏ sai.

Tắt theo từng nhóm/chủ đề Telegram:

  • Đặt channels.telegram.groups.<chatId>.disableAudioPreflight: true để bỏ qua kiểm tra lượt nhắc bằng bản chép lời preflight cho nhóm đó.
  • Đặt channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight để ghi đè theo từng chủ đề (true để bỏ qua, false để buộc bật).
  • Mặc định là false (preflight được bật khi điều kiện có cổng lượt nhắc khớp).

Ví dụ: Một người dùng gửi ghi chú thoại nói "Hey @Claude, what's the weather?" trong một nhóm Telegram với requireMention: true. Ghi chú thoại được chép lời, lượt nhắc được phát hiện, và agent trả lời.

Những điểm dễ vấp

  • Quy tắc phạm vi dùng khớp đầu tiên sẽ thắng. chatType được chuẩn hóa thành direct, group hoặc room.
  • Đảm bảo CLI của bạn thoát với mã 0 và in văn bản thuần; JSON cần được xử lý qua jq -r .text.
  • Với parakeet-mlx, nếu bạn truyền --output-dir, OpenClaw đọc <output-dir>/<media-basename>.txt khi --output-format là txt (hoặc bị bỏ qua); các định dạng đầu ra không phải txt quay về phân tích stdout.
  • Giữ thời gian chờ hợp lý (timeoutSeconds, mặc định 60 giây) để tránh chặn hàng đợi trả lời.
  • Chép lời preflight chỉ xử lý tệp đính kèm âm thanh đầu tiên để phát hiện lượt nhắc. Âm thanh bổ sung được xử lý trong giai đoạn hiểu phương tiện chính.

Liên quan