เสียงและข้อความเสียง

การทำงาน

เมื่อเปิดใช้งานการทำความเข้าใจเสียง (หรือตรวจพบโดยอัตโนมัติ) OpenClaw จะ:

1. ค้นหาไฟล์แนบเสียงรายการแรก (พาธภายในเครื่องหรือ URL) และดาวน์โหลดหากจำเป็น
2. บังคับใช้ maxBytes ก่อนส่งไปยังรายการโมเดลแต่ละรายการ
3. เรียกใช้รายการโมเดลแรกที่ใช้ได้ตามลำดับ (ผู้ให้บริการหรือ CLI) หากรายการหนึ่งล้มเหลวหรือถูกข้าม (ขนาด/หมดเวลา) ระบบจะลองรายการถัดไป
4. เมื่อสำเร็จ จะแทนที่ Body ด้วยบล็อก [Audio] และตั้งค่า {{Transcript}}

เมื่อถอดเสียงสำเร็จ CommandBody/RawBody จะถูกตั้งค่าเป็นบทถอดเสียงด้วย เพื่อให้คำสั่งแบบทับยังคงทำงาน เมื่อใช้ --verbose บันทึกจะแสดงเวลาที่มีการถอดเสียงและเวลาที่บทถอดเสียงแทนที่เนื้อหา

การตรวจหาอัตโนมัติ (ค่าเริ่มต้น)

หากคุณยังไม่ได้กำหนดค่าโมเดลและ tools.media.audio.enabled ไม่ใช่ false OpenClaw จะตรวจหาโดยอัตโนมัติตามลำดับต่อไปนี้ และหยุดที่ตัวเลือกแรกที่ใช้งานได้:

1. โมเดลตอบกลับที่ใช้งานอยู่ เมื่อผู้ให้บริการของโมเดลรองรับการทำความเข้าใจเสียง
2. การยืนยันตัวตนของผู้ให้บริการที่กำหนดค่าไว้ — รายการ models.providers.* ใด ๆ ที่มีข้อมูลยืนยันตัวตนสำหรับผู้ให้บริการที่รองรับการถอดเสียง ระบบจะตรวจสอบส่วนนี้ก่อน CLI ภายในเครื่อง ดังนั้นคีย์ API ที่กำหนดค่าไว้จะมีลำดับความสำคัญเหนือไบนารีภายในเครื่องบน PATH เสมอ ลำดับความสำคัญของผู้ให้บริการเมื่อกำหนดค่าไว้หลายราย: Groq, OpenAI, xAI, Deepgram, Google, SenseAudio, ElevenLabs, Mistral
3. CLI ภายในเครื่อง (เฉพาะเมื่อไม่พบการยืนยันตัวตนของผู้ให้บริการ) OpenClaw จะสร้างรายการสำรองตามลำดับ:
   • whisper-cli ก่อนค่าเริ่มต้นของ CPU เฉพาะเมื่อการเรียกใช้โมเดลก่อนหน้านี้ในโปรเซสปัจจุบันตรวจพบ Metal หรือ CUDA
   • sherpa-onnx-offline บนผู้ให้บริการ CPU เริ่มต้น (ต้องมี SHERPA_ONNX_MODEL_DIR ซึ่งประกอบด้วย tokens.txt, encoder.onnx, decoder.onnx และ joiner.onnx)
   • whisper-cli เมื่อ Metal/CUDA รองรับเพียงการบิลด์ หรือยังไม่มีการตรวจพบแบ็กเอนด์ที่เลือก
   • parakeet-mlx บน Apple Silicon (รองรับ MLX แต่ยังไม่มีการตรวจพบการใช้อุปกรณ์)
   • whisper (Python CLI ซึ่งดาวน์โหลดโมเดลโดยอัตโนมัติ)

แหล่งที่มาของการติดตั้ง/ลิงก์เป็นหลักฐานด้านความสามารถ ไม่ใช่หลักฐานด้านการทำงาน โดยตัวมันเองจะไม่เลื่อนตัวเลือกใดให้อยู่ก่อน sherpa ที่ใช้ CPU OpenClaw จะไม่โหลดโมเดลระหว่างการตั้งค่าหรือการตรวจสอบสถานะเพียงเพื่อสำรวจแบ็กเอนด์ whisper.cpp ที่ตรวจพบโดยอัตโนมัติจะเปิดใช้บันทึกการเรียกใช้โมเดลตามปกติ เพื่อให้ OpenClaw บันทึกบรรทัด using … backend จากต้นทางได้ ส่วนรายการ CLI ที่ระบุไว้อย่างชัดเจนจะคงแฟล็กเอาต์พุตตามที่กำหนดค่าไว้

การตรวจหา Gemini CLI โดยอัตโนมัติสำหรับการทำความเข้าใจสื่อถูกแทนที่ด้วยทางเลือกสำรอง Antigravity CLI (agy) ที่ทำงานในแซนด์บ็อกซ์สำหรับรูปภาพ/วิดีโอ ส่วนเสียงจะไม่ใช้ CLI สำรองนอกเหนือจากไบนารีภายในเครื่องข้างต้น

หากต้องการปิดการตรวจหาอัตโนมัติ ให้ตั้งค่า tools.media.audio.enabled: false หากต้องการปรับแต่ง ให้ตั้งค่า tools.media.audio.models

ตรวจสอบการเลือกภายในเครื่องโดยไม่ถอดเสียง:

openclaw capability audio providersopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

รายการผู้ให้บริการจะแสดงตัวเลือกสำรองภายในเครื่องที่ชนะโดยแยกจากการเลือกผู้ให้บริการส่วนกลาง พร้อมฟิลด์แบ็กเอนด์ที่รองรับ ที่ร้องขอ และที่ตรวจพบ หลังจากมีการถอดเสียง /status จะแสดงแบ็กเอนด์ที่ร้องขอหรือที่ตรวจพบในบรรทัดสื่อ รายการ CLI ใน tools.media.audio.models ที่ระบุไว้อย่างชัดเจนยังคงข้ามการเลือกอัตโนมัติ ให้ใช้แฟล็กเฉพาะแบ็กเอนด์ของรายการนั้น เช่น --provider=cuda ของ sherpa หรือ --no-gpu/--device ของ whisper.cpp

ตัวอย่างการกำหนดค่า

ผู้ให้บริการ + CLI สำรอง (OpenAI + Whisper CLI)

{  tools: {    media: {      audio: {        enabled: true,        maxBytes: 20971520,        models: [          { provider: "openai", model: "gpt-4o-transcribe" },          {            type: "cli",            command: "whisper",            args: ["--model", "base", "{{MediaPath}}"],            timeoutSeconds: 45,          },        ],      },    },  },}

เฉพาะผู้ให้บริการพร้อมการควบคุมตามขอบเขต

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

เฉพาะผู้ให้บริการ (Deepgram)

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

เฉพาะผู้ให้บริการ (Mistral Voxtral)

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

เฉพาะผู้ให้บริการ (SenseAudio)

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

ส่งบทถอดเสียงกลับไปยังแชต (เลือกเปิดใช้)

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

หมายเหตุและข้อจำกัด

• การยืนยันตัวตนของผู้ให้บริการเป็นไปตามลำดับการยืนยันตัวตนมาตรฐานของโมเดล (โปรไฟล์การยืนยันตัวตน ตัวแปรสภาพแวดล้อม และ models.providers.*.apiKey)
• รายละเอียดการตั้งค่า Groq: Groq
• Deepgram จะอ่าน DEEPGRAM_API_KEY เมื่อใช้ provider: "deepgram" รายละเอียดการตั้งค่า: Deepgram
• รายละเอียดการตั้งค่า Mistral: Mistral
• SenseAudio จะอ่าน SENSEAUDIO_API_KEY เมื่อใช้ provider: "senseaudio" รายละเอียดการตั้งค่า: SenseAudio
• ผู้ให้บริการเสียงสามารถเขียนทับ baseUrl, headers และ providerOptions ผ่าน tools.media.audio
• ขีดจำกัดขนาดเริ่มต้นคือ 20MB (tools.media.audio.maxBytes) เสียงที่มีขนาดเกินจะถูกข้ามสำหรับโมเดลนั้น และระบบจะลองรายการถัดไป
• ไฟล์เสียงที่มีขนาดต่ำกว่า 1024 ไบต์จะถูกข้ามก่อนการถอดเสียงด้วยผู้ให้บริการ/CLI
• ค่าเริ่มต้นของ maxChars สำหรับเสียงคือ ไม่ได้ตั้งค่า (บทถอดเสียงฉบับเต็ม) ตั้งค่า tools.media.audio.maxChars หรือ maxChars ของแต่ละรายการเพื่อตัดเอาต์พุต
• ค่าเริ่มต้นของการตรวจหา OpenAI โดยอัตโนมัติคือ gpt-4o-transcribe ตั้งค่า model: "gpt-4o-mini-transcribe" เพื่อใช้ตัวเลือกที่ถูกกว่า/เร็วกว่า
• ใช้ tools.media.audio.attachments เพื่อประมวลผลบันทึกเสียงหลายรายการ (mode: "all" พร้อม maxAttachments ซึ่งมีค่าเริ่มต้นเป็น 1)
• เทมเพลตสามารถเข้าถึงบทถอดเสียงได้ในรูปแบบ {{Transcript}}
• tools.media.audio.echoTranscript ปิดอยู่โดยค่าเริ่มต้น เปิดใช้เพื่อส่งข้อความยืนยันบทถอดเสียงกลับไปยังแชตต้นทางก่อนที่เอเจนต์จะประมวลผล
• tools.media.audio.echoFormat ใช้ปรับแต่งข้อความที่ส่งกลับ (ตัวยึดตำแหน่ง: {transcript}; ค่าเริ่มต้น 📝 "{transcript}")
• เอาต์พุตมาตรฐานของ CLI จำกัดไว้ที่ 5MB โปรดทำให้เอาต์พุต CLI กระชับ
• args ของ CLI ควรใช้ {{MediaPath}} สำหรับพาธไฟล์เสียงภายในเครื่อง เรียกใช้ openclaw doctor --fix เพื่อย้ายตัวยึดตำแหน่ง {input} ที่เลิกใช้แล้วจากการกำหนดค่า audio.transcription.command รุ่นเก่า (คีย์ที่เลิกใช้: audio.transcription ถูกแทนที่ด้วย tools.media.audio.models)
• tools.media.concurrency จำกัดจำนวนงานสื่อ แต่ไม่ใช่ตัวจัดตาราง GPU

STT ภายในเครื่องแบบคงอยู่

STT ภายในเครื่องที่ตรวจพบโดยอัตโนมัติยังคงใช้หนึ่งโปรเซสต่อหนึ่งคำขอ ปัจจุบัน OpenClaw ไม่ได้จัดการเซิร์ฟเวอร์ whisper.cpp แบบคงอยู่ เนื่องจากแพ็กเกจมาตรฐาน whisper-cpp ของ Homebrew ปิดใช้งานเซิร์ฟเวอร์ดังกล่าว ขณะที่ตัวอย่างจากต้นทางไม่มีการกำหนดค่าคิวรับงานที่มีขอบเขต วงจรชีวิตแบบคงอยู่ที่ Plugin เป็นเจ้าของจำเป็นต้องมีตัวทำงานแบบแพ็กเกจที่ได้รับการดูแล ซึ่งรองรับสุขภาพ/การเริ่มต้น การคงโมเดลไว้ในหน่วยความจำ การจัดคิวแบบมีขอบเขต การยกเลิก/หมดเวลา การทำงานแบบไม่ยืนยันตัวตนเฉพาะ local loopback และไม่มีการสำรองไปยังคลาวด์ ก่อนจึงจะเปิดใช้งานได้อย่างปลอดภัย

การรองรับสภาพแวดล้อมพร็อกซี

การถอดเสียงผ่านผู้ให้บริการรองรับตัวแปรสภาพแวดล้อมมาตรฐานสำหรับพร็อกซีขาออก โดยสอดคล้องกับความหมายของ EnvHttpProxyAgent ใน undici:

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

ตัวแปรตัวพิมพ์เล็กมีลำดับความสำคัญเหนือค่าตัวพิมพ์ใหญ่ รายการ NO_PROXY/no_proxy (ชื่อโฮสต์, *.suffix หรือ host:port) จะข้ามพร็อกซี หากไม่ได้ตั้งค่าตัวแปรสภาพแวดล้อมพร็อกซี ระบบจะเชื่อมต่อขาออกโดยตรง หากการตั้งค่าพร็อกซีล้มเหลว (URL ผิดรูปแบบ) OpenClaw จะบันทึกคำเตือนและสำรองไปใช้การดึงข้อมูลโดยตรง

การตรวจหาการกล่าวถึงในกลุ่ม

ในช่องทางที่รองรับการตรวจสอบเสียงล่วงหน้า OpenClaw จะถอดเสียง ก่อน ตรวจสอบการกล่าวถึง เมื่อตั้งค่า requireMention: true สำหรับแชตกลุ่ม ซึ่งทำให้บันทึกเสียงที่ไม่มีคำบรรยายผ่านเงื่อนไขการกล่าวถึงได้ หากบทถอดเสียงมีรูปแบบการกล่าวถึงที่กำหนดค่าไว้ เอกสารเฉพาะช่องทางจะอธิบายการรับส่งที่กำหนดให้ต้องพิมพ์การกล่าวถึงแทน

วิธีการทำงาน:

1. หากข้อความเสียงไม่มีเนื้อหาข้อความและกลุ่มกำหนดให้ต้องมีการกล่าวถึง OpenClaw จะถอดเสียงไฟล์แนบเสียงรายการแรกล่วงหน้า
2. ระบบจะตรวจสอบบทถอดเสียงเพื่อหารูปแบบการกล่าวถึง (เช่น @BotName หรือตัวกระตุ้นด้วยอีโมจิ)
3. หากพบการกล่าวถึง ข้อความจะดำเนินต่อผ่านกระบวนการตอบกลับแบบเต็ม

พฤติกรรมสำรอง: หากการถอดเสียงล่วงหน้าล้มเหลว (หมดเวลา ข้อผิดพลาด API เป็นต้น) ข้อความจะสำรองไปใช้การตรวจหาการกล่าวถึงจากข้อความเท่านั้น เพื่อไม่ให้ข้อความแบบผสม (ข้อความ + เสียง) ถูกทิ้ง

การเลือกปิดใช้ต่อกลุ่ม/หัวข้อ Telegram:

• ตั้งค่า channels.telegram.groups.<chatId>.disableAudioPreflight: true เพื่อข้ามการตรวจสอบการกล่าวถึงในบทถอดเสียงล่วงหน้าสำหรับกลุ่มนั้น
• ตั้งค่า channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight เพื่อเขียนทับค่ารายหัวข้อ (true เพื่อข้าม และ false เพื่อบังคับเปิดใช้)
• ค่าเริ่มต้นคือ false (เปิดใช้การตรวจสอบล่วงหน้าเมื่อเงื่อนไขที่กำหนดให้ต้องกล่าวถึงตรงกัน)

ตัวอย่าง: ผู้ใช้ส่งบันทึกเสียงที่พูดว่า "สวัสดี @Claude อากาศเป็นอย่างไรบ้าง?" ในกลุ่ม Telegram ที่มี requireMention: true ระบบจะถอดเสียงบันทึกเสียง ตรวจพบการกล่าวถึง และเอเจนต์จะตอบกลับ

ข้อควรระวัง

• กฎขอบเขตใช้รายการแรกที่ตรงกันเป็นผลลัพธ์ chatType จะถูกปรับให้อยู่ในรูปแบบ direct, group หรือ channel
• ตรวจสอบให้แน่ใจว่า CLI ของคุณจบการทำงานด้วยรหัส 0 และพิมพ์ข้อความธรรมดา เอาต์พุต JSON ต้องแปลงด้วย jq -r .text
• โหมดเอาต์พุตเป็นไฟล์ที่รู้จักถือเป็นแหล่งข้อมูลที่เชื่อถือได้ หากไฟล์บทถอดเสียงที่อนุมานไว้ว่างเปล่าหรือหายไป ระบบจะไม่สร้างบทถอดเสียง แทนที่จะสำรองไปใช้เอาต์พุตความคืบหน้าของ CLI
• สำหรับ parakeet-mlx ให้ใช้ --output-format txt (หรือ all) ร่วมกับ --output-dir และเทมเพลตเอาต์พุตเริ่มต้น {filename} ระบบยังรองรับตัวแปรสภาพแวดล้อม PARAKEET_OUTPUT_FORMAT และ PARAKEET_OUTPUT_TEMPLATE จากต้นทาง OpenClaw จะอ่าน <output-dir>/<media-basename>.txt ส่วนรูปแบบเริ่มต้น srt รูปแบบอื่น และเทมเพลตเอาต์พุตแบบกำหนดเองจะยังคงใช้เอาต์พุตมาตรฐาน
• กำหนดเวลาหมดเวลาให้เหมาะสม (timeoutSeconds มีค่าเริ่มต้น 60 วินาที) เพื่อหลีกเลี่ยงการปิดกั้นคิวตอบกลับ
• การถอดเสียงล่วงหน้าจะประมวลผลเฉพาะไฟล์แนบเสียง รายการแรก สำหรับการตรวจหาการกล่าวถึง ไฟล์แนบเสียงเพิ่มเติมจะถูกประมวลผลในขั้นตอนหลักของการทำความเข้าใจสื่อ

เนื้อหาที่เกี่ยวข้อง

• การทำความเข้าใจสื่อ
• โหมดสนทนา
• การปลุกด้วยเสียง