المقاطع الصوتية والملاحظات الصوتية

ما الذي يفعله

عند تمكين فهم الصوت (أو اكتشافه تلقائيًا)، يقوم 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، قبل الإعدادات الافتراضية لوحدة المعالجة المركزية فقط عندما تكون عملية استدعاء نموذج سابقة في العملية الحالية قد رصدت Metal أو CUDA
   • sherpa-onnx-offline على موفّر وحدة المعالجة المركزية الافتراضي الخاص به (يتطلب SHERPA_ONNX_MODEL_DIR ويحتوي على tokens.txt وencoder.onnx وdecoder.onnx وjoiner.onnx)
   • whisper-cli عندما لا يكون Metal/CUDA إلا مدعومًا عند البناء أو عندما تكون الواجهة الخلفية المحددة غير مرصودة بطريقة أخرى
   • parakeet-mlx على Apple Silicon (قادر على استخدام MLX؛ يظل استخدام الجهاز غير مرصود)
   • whisper ‏(CLI بلغة Python؛ ينزّل النماذج تلقائيًا)

يُعد مصدر التثبيت/الربط دليلًا على القدرة، لا دليلًا على التنفيذ. ولا يقدّم مرشحًا على sherpa العامل بوحدة المعالجة المركزية بمفرده أبدًا. لا يحمّل 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, // القيمة الافتراضية هي false        echoFormat: '📝 "{transcript}"', // اختياري، يدعم {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.
• حد الحجم الافتراضي هو 20 ميغابايت (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}").
• يقتصر stdout الخاص بـ CLI على 5 ميغابايت؛ أبقِ إخراج CLI موجزًا.
• ينبغي أن تستخدم args الخاصة بـ CLI القيمة {{MediaPath}} لمسار ملف الصوت المحلي. شغّل openclaw doctor --fix لترحيل العناصر النائبة المهملة {input} من تهيئات audio.transcription.command القديمة (المفتاح المتقاعد: audio.transcription، وقد استُبدل بـ tools.media.audio.models).
• تحد tools.media.concurrency من مهام الوسائط؛ وليست مجدولًا لوحدة معالجة الرسومات.

تحويل الكلام إلى نص محلي مقيم

يظل تحويل الكلام إلى نص المحلي المكتشف تلقائيًا عمليةً مستقلة لكل طلب. لا يدير OpenClaw حاليًا خادم whisper.cpp مقيمًا لأن حزمة Homebrew القياسية whisper-cpp تعطّل ذلك الخادم، بينما لا يتضمن مثال المنبع قائمة انتظار قبول محدودة مهيأة. تحتاج دورة حياة مقيمة يملكها 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 الافتراضي والتنسيقات الأخرى وقوالب الإخراج المخصصة في استخدام stdout.
• أبقِ المهل معقولة (timeoutSeconds، والقيمة الافتراضية 60 ثانية) لتجنب حظر قائمة انتظار الردود.
• لا يعالج النسخ المسبق سوى أول مرفق صوتي لاكتشاف الإشارات. وتُعالج المرفقات الصوتية الإضافية خلال مرحلة فهم الوسائط الرئيسية.

ذو صلة

• فهم الوسائط
• وضع التحدث
• التنشيط الصوتي