Â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. Định vị 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 phiên âm thành công, CommandBody/RawBody được đặt thành bản phiên âm để các lệnh bắt đầu bằng dấu 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 phiên âm chạy và khi nó thay thế nội dung.

​

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

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 (Python CLI; tự động tải mô hình)
3. 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 nhà cung cấp: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

​

Ví dụ cấu hình

​

Dự phòng nhà cung cấp + 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,
          },
        ],
      },
    },
  },
}

​

Chỉ nhà cung cấp với giới hạn 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ỉ nhà cung cấp (Deepgram)

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

​

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

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

​

Chỉ 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 phiên âm vào cuộc trò chuyện (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 (phiên âm â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.
• 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 vượt kích thước sẽ bị bỏ qua cho mô hình đó và mục tiếp theo sẽ được thử.
• Tệp âm thanh nhỏ/trống dưới 1024 byte sẽ bị bỏ qua trước khi phiên âm qua nhà cung cấp/CLI.
• maxChars mặc định cho âm thanh là chưa đặt (bản phiên âm đầy đủ). Đặt tools.media.audio.maxChars hoặc maxChars theo từng mục để cắt bớt đầ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 phiên âm có sẵn cho mẫu dưới dạng {{Transcript}}.
• tools.media.audio.echoTranscript tắt theo mặc định; bật để gửi xác nhận bản phiên âm về cuộc trò chuyện gốc trước khi tác tử 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 khuyến nghị từ cấu hình audio.transcription.command cũ.

​

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

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

​

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

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

• Nếu phiên âm thất bại trong kiểm tra sơ bộ (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 đến chỉ bằng văn bản.
• Điều này đảm bảo 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 channels.telegram.groups.<chatId>.disableAudioPreflight: true để bỏ qua kiểm tra nhắc đến bằng bản phiên âm sơ bộ 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 (bật kiểm tra sơ bộ khi các điều kiện có cổng nhắc đến khớp).

​

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

• Quy tắc phạm vi dùng nguyên tắc khớp đầu tiên 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.
• Phiên âm kiểm tra sơ bộ chỉ xử lý tệp đính kèm âm thanh đầu tiên để phát hiện lượt nhắc đến. Âm thanh bổ sung được xử lý trong giai đoạn hiểu phương tiện chính.

​

Liên quan

• Hiểu phương tiện
• Chế độ trò chuyện
• Kích hoạt bằng giọng nói