الانتقال إلى المحتوى الرئيسي

​
الصوت / الملاحظات الصوتية — 2026-01-17

​
ما الذي يعمل

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

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

إذا لم تُكوّن النماذج ولم يتم تعيين tools.media.audio.enabled إلى false، يقوم OpenClaw بالاكتشاف التلقائي بالترتيب التالي ويتوقف عند أول خيار يعمل:
  1. واجهات CLI محلية (إذا كانت مُثبّتة)
    • sherpa-onnx-offline (يتطلب SHERPA_ONNX_MODEL_DIR مع encoder/decoder/joiner/tokens)
    • whisper-cli (من whisper-cpp؛ يستخدم WHISPER_CPP_MODEL أو النموذج الصغير المضمّن)
    • whisper (واجهة Python CLI؛ تُنزّل النماذج تلقائيًا)
  2. Gemini CLI (gemini) باستخدام read_many_files
  3. مفاتيح الموفّرين (OpenAI → Groq → Deepgram → Google)
لتعطيل الاكتشاف التلقائي، عيّن tools.media.audio.enabled: false. للتخصيص، عيّن tools.media.audio.models. ملاحظة: اكتشاف الثنائيات يتم بأفضل جهد عبر macOS/Linux/Windows؛ تأكّد من وجود CLI على PATH (نقوم بتوسيع ~)، أو عيّن نموذج CLI صريحًا بمسار أمر كامل.

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

​
موفّر + احتياطي 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" }],
      },
    },
  },
}

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

  • يتبع توثيق موفّر الخدمة ترتيب توثيق النموذج القياسي (ملفات تعريف المصادقة، متغيرات البيئة، models.providers.*.apiKey).
  • يلتقط Deepgram DEEPGRAM_API_KEY عند استخدام provider: "deepgram".
  • تفاصيل إعداد Deepgram: Deepgram (نسخ الصوت).
  • يمكن لموفّري الصوت تجاوز baseUrl وheaders وproviderOptions عبر tools.media.audio.
  • الحد الافتراضي للحجم هو 20MB (tools.media.audio.maxBytes). يتم تخطي الصوت الأكبر من الحد لذلك النموذج وتجربة الإدخال التالي.
  • القيمة الافتراضية لـ maxChars للصوت غير معيّنة (نص كامل). عيّن tools.media.audio.maxChars أو maxChars لكل إدخال لتقليم الإخراج.
  • الافتراضي التلقائي لـ OpenAI هو gpt-4o-mini-transcribe؛ عيّن model: "gpt-4o-transcribe" لدقة أعلى.
  • استخدم tools.media.audio.attachments لمعالجة عدة ملاحظات صوتية (mode: "all" + maxAttachments).
  • النص المنسوخ متاح للقوالب باسم {{Transcript}}.
  • إخراج stdout لواجهة CLI محدود (5MB)؛ احرص على إبقاء إخراج CLI موجزًا.

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

عند تعيين requireMention: true لمحادثة جماعية، يقوم OpenClaw الآن بتفريغ الصوت قبل التحقق من الإشارات. يتيح ذلك معالجة الملاحظات الصوتية حتى عندما تحتوي على إشارات. كيف يعمل:
  1. إذا لم تحتوي الرسالة الصوتية على نص مكتوب وكانت المجموعة تتطلب إشارات، يقوم OpenClaw بإجراء تفريغ “تمهيدي”.
  2. يتم التحقق من النص المُفرَّغ بحثًا عن أنماط الإشارة (مثل @BotName أو محفزات الإيموجي).
  3. إذا تم العثور على إشارة، تتابع الرسالة عبر مسار الرد الكامل.
  4. يُستخدم النص المُفرَّغ لاكتشاف الإشارات حتى تتمكن الملاحظات الصوتية من تجاوز شرط الإشارة.
سلوك الرجوع الاحتياطي:
  • إذا فشل التفريغ أثناء المرحلة التمهيدية (انتهاء المهلة، خطأ في API، إلخ)، تتم معالجة الرسالة بناءً على اكتشاف الإشارات في النص فقط.
  • يضمن ذلك عدم إسقاط الرسائل المختلطة (نص + صوت) بشكل غير صحيح.
مثال: يرسل مستخدم ملاحظة صوتية تقول “Hey @Claude, what’s the weather?” في مجموعة Telegram مع تعيين requireMention: true. يتم تفريغ الملاحظة الصوتية، واكتشاف الإشارة، ويرد الوكيل.

​
غوشا

  • تستخدم قواعد النطاق مبدأ «أول تطابق يفوز». يتم تطبيع chatType إلى direct أو group أو room.
  • تأكّد من أن واجهة CLI تنهي التنفيذ برمز خروج 0 وتطبع نصًا عاديًا؛ يحتاج JSON إلى تهيئة عبر jq -r .text.
  • حافظ على مهلات زمنية معقولة (timeoutSeconds، الافتراضي 60 ثانية) لتجنّب حجب طابور الردود.
  • تعالج مرحلة التفريغ التمهيدية أول مرفق صوتي فقط لاكتشاف الإشارات. تتم معالجة المقاطع الصوتية الإضافية خلال مرحلة فهم الوسائط الرئيسية.