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

​

ما الذي يفعله

1. يحدد موقع أول مرفق صوتي (مسار محلي أو عنوان URL) وينزّله عند الحاجة.
2. يفرض حد maxBytes قبل الإرسال إلى كل إدخال نموذج.
3. يشغّل أول إدخال نموذج مؤهل بالترتيب (موفّر أو CLI)؛ وإذا فشل إدخال أو تم تخطيه (بسبب الحجم/المهلة)، تُجرَّب الخانة التالية.
4. عند النجاح، يستبدل Body بكتلة [Audio] ويضبط {{Transcript}}.

​

الاكتشاف التلقائي (الافتراضي)

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؛ ينزّل النماذج تلقائيًا)

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

​

أمثلة التهيئة

​

موفّر + خيار 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 من مهام الوسائط؛ وليست مجدولًا لوحدة معالجة الرسومات.

​

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

​

دعم بيئة الوكيل

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

​

اكتشاف الإشارات في المجموعات

1. إذا لم تكن للرسالة الصوتية هيئة نصية وكانت المجموعة تتطلب إشارات، يجري OpenClaw نسخًا مسبقًا لأول مرفق صوتي.
2. يُفحص النص المنسوخ بحثًا عن أنماط الإشارات (مثل @BotName، ومحفزات الرموز التعبيرية).
3. إذا عُثر على إشارة، تتابع الرسالة مسار معالجة الرد الكامل.

• اضبط channels.telegram.groups.<chatId>.disableAudioPreflight: true لتخطي فحوصات إشارات النص المنسوخ المسبقة لتلك المجموعة.
• اضبط channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight للتجاوز حسب الموضوع (true للتخطي، وfalse لفرض التمكين).
• القيمة الافتراضية هي false (يُفعّل الفحص المسبق عندما تتطابق شروط بوابة الإشارة).

​

محاذير

• تستخدم قواعد النطاق مبدأ أول تطابق يفوز؛ وتُطبَّع 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 ثانية) لتجنب حظر قائمة انتظار الردود.
• لا يعالج النسخ المسبق سوى أول مرفق صوتي لاكتشاف الإشارات. وتُعالج المرفقات الصوتية الإضافية خلال مرحلة فهم الوسائط الرئيسية.

​

ذو صلة

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