صدا و یادداشت‌های صوتی

چه کاری انجام می‌دهد

وقتی درک صوت فعال باشد (یا به‌طور خودکار تشخیص داده شود)، 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، پیش از گزینه‌های پیش‌فرض CPU فقط وقتی فراخوانی قبلی یک مدل در فرایند فعلی، Metal یا CUDA را مشاهده کرده باشد
   • sherpa-onnx-offline روی ارائه‌دهندهٔ پیش‌فرض CPU خود (به SHERPA_ONNX_MODEL_DIR همراه با tokens.txt، encoder.onnx، decoder.onnx و joiner.onnx نیاز دارد)
   • whisper-cli وقتی Metal/CUDA فقط قابلیت ساخت داشته باشد یا بک‌اند انتخاب‌شده به شکل دیگری مشاهده نشده باشد
   • parakeet-mlx روی Apple Silicon (دارای قابلیت MLX؛ استفاده از دستگاه همچنان مشاهده‌نشده باقی می‌ماند)
   • whisper (CLI پایتون؛ مدل‌ها را به‌طور خودکار بارگیری می‌کند)

منشأ نصب/پیوند، مدرک قابلیت است نه مدرک اجرا. این مورد به‌تنهایی هرگز نامزدی را جلوتر از sherpa مبتنی بر CPU قرار نمی‌دهد. OpenClaw هنگام راه‌اندازی یا بررسی وضعیت، صرفاً برای کاوش یک بک‌اند مدلی را بارگذاری نمی‌کند. whisper.cpp که به‌طور خودکار تشخیص داده شده است، گزارش‌های عادی اجرای مدل خود را فعال نگه می‌دارد تا OpenClaw بتواند خط بالادستی using … backend را ثبت کند. ورودی‌های صریح CLI پرچم‌های خروجی پیکربندی‌شدهٔ خود را حفظ می‌کنند.

تشخیص خودکار Gemini CLI برای درک رسانه با یک گزینهٔ بازگشت Antigravity CLI (agy) در محیط ایزوله برای تصویر/ویدئو جایگزین شده است؛ صوت به‌جز فایل‌های اجرایی محلی بالا از گزینهٔ بازگشت CLI استفاده نمی‌کند.

برای غیرفعال‌کردن تشخیص خودکار، tools.media.audio.enabled: false را تنظیم کنید. برای سفارشی‌سازی، tools.media.audio.models را تنظیم کنید.

گزینش محلی را بدون رونویسی صوت بررسی کنید:

openclaw capability audio providersopenclaw 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)

{  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.
• هنگام استفاده از provider: "deepgram"، ‏Deepgram مقدار DEEPGRAM_API_KEY را دریافت می‌کند. جزئیات راه‌اندازی: Deepgram.
• جزئیات راه‌اندازی Mistral:‏ Mistral.
• هنگام استفاده از provider: "senseaudio"، ‏SenseAudio مقدار SENSEAUDIO_API_KEY را دریافت می‌کند. جزئیات راه‌اندازی: SenseAudio.
• ارائه‌دهندگان صوت می‌توانند baseUrl، ‏headers و providerOptions را از طریق tools.media.audio بازنویسی کنند.
• سقف اندازهٔ پیش‌فرض ۲۰ مگابایت است (tools.media.audio.maxBytes). صوت بزرگ‌تر از سقف برای آن مدل نادیده گرفته می‌شود و ورودی بعدی امتحان می‌شود.
• فایل‌های صوتی کوچک‌تر از ۱۰۲۴ بایت پیش از رونویسی توسط ارائه‌دهنده/CLI نادیده گرفته می‌شوند.
• مقدار پیش‌فرض maxChars برای صوت تنظیم نشده است (رونویسی کامل). برای کوتاه‌کردن خروجی، tools.media.audio.maxChars یا maxChars هر ورودی را تنظیم کنید.
• پیش‌فرض تشخیص خودکار OpenAI برابر gpt-4o-transcribe است؛ برای گزینه‌ای ارزان‌تر/سریع‌تر، model: "gpt-4o-mini-transcribe" را تنظیم کنید.
• برای پردازش چند یادداشت صوتی از tools.media.audio.attachments استفاده کنید (mode: "all" همراه با maxAttachments، با مقدار پیش‌فرض ۱).
• متن رونویسی با {{Transcript}} در دسترس الگوها قرار دارد.
• tools.media.audio.echoTranscript به‌طور پیش‌فرض خاموش است؛ آن را فعال کنید تا پیش از پردازش عامل، تأییدیهٔ رونویسی به گفت‌وگوی مبدأ بازگردانده شود.
• tools.media.audio.echoFormat متن بازفرست را سفارشی می‌کند (جای‌نگهدار: {transcript}؛ پیش‌فرض 📝 "{transcript}").
• خروجی استاندارد CLI به ۵ مگابایت محدود است؛ خروجی CLI را مختصر نگه دارید.
• args در CLI باید برای مسیر فایل صوتی محلی از {{MediaPath}} استفاده کند. برای مهاجرت جای‌نگهدارهای منسوخ {input} از پیکربندی‌های قدیمی audio.transcription.command، فرمان openclaw doctor --fix را اجرا کنید (کلید کنارگذاشته‌شده: audio.transcription، جایگزین‌شده با tools.media.audio.models).
• tools.media.concurrency تعداد وظایف رسانه‌ای را محدود می‌کند؛ زمان‌بند GPU نیست.

تبدیل گفتار به متن محلی مقیم

تبدیل گفتار به متن محلی که به‌طور خودکار تشخیص داده شده، همچنان برای هر درخواست یک فرایند جداگانه اجرا می‌کند. 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 هشداری ثبت می‌کند و به دریافت مستقیم بازمی‌گردد.

تشخیص اشاره در گروه‌ها

در کانال‌هایی که از پیش‌بررسی صوت پشتیبانی می‌کنند، وقتی برای یک گفت‌وگوی گروهی requireMention: true تنظیم شده باشد، OpenClaw صوت را پیش از بررسی اشاره‌ها رونویسی می‌کند. به‌این‌ترتیب، اگر متن رونویسی یک یادداشت صوتی بدون زیرنویس شامل الگوی اشارهٔ پیکربندی‌شده باشد، می‌تواند از دروازهٔ اشاره عبور کند. مستندات ویژهٔ هر کانال، انتقال‌هایی را شرح می‌دهند که در عوض به اشارهٔ تایپ‌شده نیاز دارند.

نحوهٔ کار:

1. اگر پیام صوتی بدنهٔ متنی نداشته باشد و گروه به اشاره نیاز داشته باشد، OpenClaw نخستین پیوست صوتی را در مرحلهٔ پیش‌بررسی رونویسی می‌کند.
2. متن رونویسی برای یافتن الگوهای اشاره (برای نمونه @BotName یا محرک‌های ایموجی) بررسی می‌شود.
3. اگر اشاره‌ای پیدا شود، پیام وارد خط لولهٔ کامل پاسخ‌گویی می‌شود.

رفتار بازگشت: اگر رونویسی پیش‌بررسی شکست بخورد (مهلت زمانی، خطای API و غیره)، پیام به تشخیص اشاره فقط بر اساس متن بازمی‌گردد تا پیام‌های ترکیبی (متن + صوت) هرگز حذف نشوند.

انصراف برای هر گروه/موضوع Telegram:

• برای ردکردن بررسی اشاره در متن رونویسی پیش‌بررسی برای آن گروه، channels.telegram.groups.<chatId>.disableAudioPreflight: true را تنظیم کنید.
• برای بازنویسی در سطح هر موضوع، channels.telegram.groups.<chatId>.topics.<threadId>.disableAudioPreflight را تنظیم کنید (true برای ردکردن، false برای فعال‌سازی اجباری).
• مقدار پیش‌فرض false است (وقتی شرایط دروازهٔ اشاره برقرار باشد، پیش‌بررسی فعال است).

مثال: کاربری در یک گروه Telegram با requireMention: true یادداشت صوتی‌ای می‌فرستد و می‌گوید «هی @Claude، هوا چطور است؟». یادداشت صوتی رونویسی می‌شود، اشاره تشخیص داده می‌شود و عامل پاسخ می‌دهد.

نکات مهم

• قوانین دامنه از قاعدهٔ نخستین تطابق برنده است استفاده می‌کنند؛ chatType به direct، ‏group یا channel نرمال‌سازی می‌شود.
• مطمئن شوید CLI با کد ۰ خارج می‌شود و متن ساده چاپ می‌کند؛ خروجی 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، قالب‌های دیگر و الگوهای خروجی سفارشی همچنان از خروجی استاندارد استفاده می‌کنند.
• برای جلوگیری از مسدودشدن صف پاسخ، مهلت‌های زمانی را معقول نگه دارید (timeoutSeconds، با مقدار پیش‌فرض ۶۰ ثانیه).
• رونویسی پیش‌بررسی فقط نخستین پیوست صوتی را برای تشخیص اشاره پردازش می‌کند. پیوست‌های صوتی اضافی در مرحلهٔ اصلی درک رسانه پردازش می‌شوند.

مرتبط

• درک رسانه
• حالت گفت‌وگو
• فعال‌سازی صوتی