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

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

​

ما الذي يعمل

• فهم الوسائط (الصوت): إذا كان فهم الصوت ممكّنًا (أو تم اكتشافه تلقائيًا)، فإن 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 (واجهة CLI من Python؛ تنزّل النماذج تلقائيًا)
3. Gemini CLI (gemini) باستخدام read_many_files
4. مصادقة المزوّد
   • تتم تجربة إدخالات 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، الافتراضي 60 ثانية) لتجنب حظر طابور الرد.
• لا يعالج النسخ التمهيدي إلا المرفق الصوتي الأول لاكتشاف الإشارات. تتم معالجة الصوت الإضافي أثناء مرحلة فهم الوسائط الرئيسية.

​

ذات صلة

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