الصوت والملاحظات الصوتية

​

ما يعمل

• فهم الوسائط (الصوت): إذا كان فهم الصوت مفعلا (أو مكتشفا تلقائيا)، فإن OpenClaw:
  1. يحدد أول مرفق صوتي (مسار محلي أو URL) وينزله عند الحاجة.
  2. يفرض maxBytes قبل الإرسال إلى كل إدخال نموذج.
  3. يشغل أول إدخال نموذج مؤهل بالترتيب (مزود أو CLI).
  4. إذا فشل أو تم تخطيه (الحجم/المهلة)، يجرب الإدخال التالي.
  5. عند النجاح، يستبدل Body بكتلة [Audio] ويضبط {{Transcript}}.
• تحليل الأوامر: عند نجاح النسخ، يتم ضبط CommandBody/RawBody إلى النص المنسوخ كي تظل أوامر الشرطة المائلة تعمل.
• التسجيل المفصل: في --verbose، نسجل وقت تشغيل النسخ ووقت استبداله للمتن.

​

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

1. نموذج الرد النشط عندما يدعم مزوده فهم الصوت.
2. واجهات CLI المحلية (إذا كانت مثبتة)
   • sherpa-onnx-offline (يتطلب SHERPA_ONNX_MODEL_DIR مع encoder/decoder/joiner/tokens)
   • whisper-cli (من whisper-cpp؛ يستخدم WHISPER_CPP_MODEL أو النموذج الصغير المضمن)
   • whisper (Python CLI؛ ينزل النماذج تلقائيا)
3. مصادقة المزود
   • تتم تجربة إدخالات models.providers.* المضبوطة التي تدعم الصوت أولا
   • ترتيب الرجوع إلى المزودين: OpenAI → Groq → xAI → Deepgram → Google → SenseAudio → ElevenLabs → Mistral

​

أمثلة الإعداد

​

مزود + رجوع 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,
          },
        ],
      },
    },
  },
}

​

مزود فقط مع تقييد النطاق

{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-mini-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-mini-transcribe" }],
      },
    },
  },
}

​

ملاحظات وحدود

• تتبع مصادقة المزود ترتيب مصادقة النماذج القياسي (ملفات المصادقة، متغيرات البيئة، models.providers.*.apiKey).
• تفاصيل إعداد Groq: Groq.
• يلتقط Deepgram قيمة DEEPGRAM_API_KEY عند استخدام provider: "deepgram".
• تفاصيل إعداد Deepgram: Deepgram (نسخ الصوت).
• تفاصيل إعداد Mistral: Mistral.
• يلتقط SenseAudio قيمة SENSEAUDIO_API_KEY عند استخدام provider: "senseaudio".
• تفاصيل إعداد SenseAudio: SenseAudio.
• يمكن لمزودي الصوت تجاوز baseUrl وheaders وproviderOptions عبر tools.media.audio.
• حد الحجم الافتراضي هو 20MB (tools.media.audio.maxBytes). يتم تخطي الصوت زائد الحجم لذلك النموذج وتجربة الإدخال التالي.
• يتم تخطي ملفات الصوت الصغيرة/الفارغة التي تقل عن 1024 بايت قبل النسخ عبر المزود/CLI.
• القيمة الافتراضية لـ maxChars للصوت غير مضبوطة (النص المنسوخ الكامل). اضبط tools.media.audio.maxChars أو maxChars لكل إدخال لاقتطاع المخرجات.
• القيمة التلقائية الافتراضية لـ OpenAI هي gpt-4o-mini-transcribe؛ اضبط model: "gpt-4o-transcribe" للحصول على دقة أعلى.
• استخدم tools.media.audio.attachments لمعالجة عدة ملاحظات صوتية (mode: "all" + maxAttachments).
• يتوفر النص المنسوخ للقوالب باسم {{Transcript}}.
• يكون tools.media.audio.echoTranscript معطلا افتراضيا؛ فعله لإرسال تأكيد النص المنسوخ إلى الدردشة الأصلية قبل معالجة الوكيل.
• يخصص tools.media.audio.echoFormat نص التكرار (العنصر النائب: {transcript}).
• مخرجات stdout الخاصة بـ CLI محددة (5MB)؛ أبق مخرجات CLI موجزة.
• يجب أن تستخدم args الخاصة بـ CLI القيمة {{MediaPath}} لمسار ملف الصوت المحلي. شغل openclaw doctor --fix لترحيل عناصر {input} النائبة المهملة من إعدادات audio.transcription.command الأقدم.

​

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

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

​

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

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

• إذا فشل النسخ أثناء التمهيد (مهلة، خطأ API، وما إلى ذلك)، تتم معالجة الرسالة بناء على اكتشاف الإشارات النصية فقط.
• يضمن هذا ألا يتم إسقاط الرسائل المختلطة (نص + صوت) بشكل غير صحيح أبدا.

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

​

محاذير

• تستخدم قواعد النطاق أول تطابق يفوز. يتم تطبيع chatType إلى direct أو group أو room.
• تأكد من أن CLI لديك يخرج بالرمز 0 ويطبع نصا عاديا؛ يحتاج JSON إلى المعالجة عبر jq -r .text.
• بالنسبة إلى parakeet-mlx، إذا مررت --output-dir، يقرأ OpenClaw الملف <output-dir>/<media-basename>.txt عندما يكون --output-format هو txt (أو محذوفا)؛ تنسيقات المخرجات غير txt ترجع إلى تحليل stdout.
• أبق المهل معقولة (timeoutSeconds، الافتراضي 60s) لتجنب حظر طابور الرد.
• يعالج النسخ التمهيدي أول مرفق صوتي فقط لاكتشاف الإشارات. تتم معالجة الصوت الإضافي أثناء مرحلة فهم الوسائط الرئيسية.

​

ذو صلة

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