---
read_when:
    - تغيير نسخ الصوت أو معالجة الوسائط
summary: كيفية تنزيل المقاطع الصوتية/الملاحظات الصوتية الواردة ونسخها نصيًا وإدراجها في الردود
title: المقاطع الصوتية والملاحظات الصوتية
x-i18n:
    generated_at: "2026-07-12T06:06:13Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: cb382f4219620d906bfa76ebddc690b174a3b24f80f815be92e915b363d17792
    source_path: nodes/audio.md
    workflow: 16
---

## ما الذي يفعله

عند تمكين فهم الصوت (أو اكتشافه تلقائيًا)، يقوم 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`.

<Note>
يُجرى اكتشاف الملفات التنفيذية بأفضل جهد ممكن عبر macOS/Linux/Windows. تأكد من وجود CLI في `PATH` (يجري توسيع `~`)، أو اضبط نموذج CLI صريحًا بمسار أمر كامل.
</Note>

افحص الاختيار المحلي دون نسخ الصوت:

```bash
openclaw capability audio providers
openclaw 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)

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-transcribe" },
          {
            type: "cli",
            command: "whisper",
            args: ["--model", "base", "{{MediaPath}}"],
            timeoutSeconds: 45,
          },
        ],
      },
    },
  },
}
```

### موفّر فقط مع تقييد النطاق

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        scope: {
          default: "allow",
          rules: [{ action: "deny", match: { chatType: "group" } }],
        },
        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],
      },
    },
  },
}
```

### موفّر فقط (Deepgram)

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "deepgram", model: "nova-3" }],
      },
    },
  },
}
```

### موفّر فقط (Mistral Voxtral)

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "mistral", model: "voxtral-mini-latest" }],
      },
    },
  },
}
```

### موفّر فقط (SenseAudio)

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        models: [{ provider: "senseaudio", model: "senseaudio-asr-pro-1.5-260319" }],
      },
    },
  },
}
```

### إعادة إرسال النص المنسوخ إلى الدردشة (اشتراك اختياري)

```json5
{
  tools: {
    media: {
      audio: {
        enabled: true,
        echoTranscript: true, // القيمة الافتراضية هي false
        echoFormat: '📝 "{transcript}"', // اختياري، يدعم {transcript}
        models: [{ provider: "openai", model: "gpt-4o-transcribe" }],
      },
    },
  },
}
```

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

- تتبع مصادقة الموفّر ترتيب مصادقة النموذج القياسي (ملفات تعريف المصادقة، ومتغيرات البيئة، و`models.providers.*.apiKey`).
- تفاصيل إعداد Groq: ‏[Groq](/ar/providers/groq).
- يلتقط Deepgram قيمة `DEEPGRAM_API_KEY` عند استخدام `provider: "deepgram"`. تفاصيل الإعداد: [Deepgram](/ar/providers/deepgram).
- تفاصيل إعداد Mistral: ‏[Mistral](/ar/providers/mistral).
- يلتقط SenseAudio قيمة `SENSEAUDIO_API_KEY` عند استخدام `provider: "senseaudio"`. تفاصيل الإعداد: [SenseAudio](/ar/providers/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 ثانية) لتجنب حظر قائمة انتظار الردود.
- لا يعالج النسخ المسبق سوى **أول** مرفق صوتي لاكتشاف الإشارات. وتُعالج المرفقات الصوتية الإضافية خلال مرحلة فهم الوسائط الرئيسية.

## ذو صلة

- [فهم الوسائط](/ar/nodes/media-understanding)
- [وضع التحدث](/ar/nodes/talk)
- [التنشيط الصوتي](/ar/nodes/voicewake)
