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

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

هنگامی که درک صوت فعال باشد (یا به‌طور خودکار تشخیص داده شود)، 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.models اضافه کنید.

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

openclaw capability audio providersopenclaw doctor --lint --only core/doctor/local-audio-acceleration --severity-min info

فهرست موجودی ارائه‌دهندگان، گزینه برنده بازگشت محلی را جدا از انتخاب سراسری ارائه‌دهنده، به‌همراه فیلدهای بک‌اندِ دارای قابلیت، درخواست‌شده و مشاهده‌شده گزارش می‌کند. پس از اجرای رونویسی، /status بک‌اند درخواست‌شده یا مشاهده‌شده را در خط رسانه گزارش می‌کند. ورودی‌های صریح CLI دارای قابلیت صوت در tools.media.models همچنان انتخاب خودکار را دور می‌زنند؛ از پرچم‌های ویژه بک‌اند آن‌ها مانند --provider=cuda برای sherpa یا --no-gpu/--device برای whisper.cpp استفاده کنید.

نمونه‌های پیکربندی

ارائه‌دهنده + گزینه بازگشت CLI (OpenAI + Whisper CLI)

{  tools: {    media: {      models: [        { provider: "openai", model: "gpt-4o-transcribe", capabilities: ["audio"] },        {          type: "cli",          command: "whisper",          args: ["--model", "base", "{{AttachmentPath}}"],          timeoutSeconds: 45,          capabilities: ["audio"],        },      ],      audio: { enabled: true, preferredModel: "openai/gpt-4o-transcribe" },    },  },}

فقط ارائه‌دهنده (Deepgram)

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

فقط ارائه‌دهنده (Mistral Voxtral)

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

فقط ارائه‌دهنده (SenseAudio)

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

بازتاب متن رونویسی‌شده در گفت‌وگو (اختیاری)

{  tools: {    media: {      audio: {        enabled: true,        echoTranscript: true,        echoFormat: '📝 "{transcript}"',      },    },  },}

نکات و محدودیت‌ها

• احراز هویت ارائه‌دهنده از ترتیب استاندارد احراز هویت مدل پیروی می‌کند (پروفایل‌های احراز هویت، متغیرهای محیطی، models.providers.*.apiKey).
• جزئیات راه‌اندازی Groq: Groq.
• هنگام استفاده از provider: "deepgram"، Deepgram مقدار DEEPGRAM_API_KEY را دریافت می‌کند. جزئیات راه‌اندازی: Deepgram.
• جزئیات راه‌اندازی Mistral: Mistral.
• هنگام استفاده از provider: "senseaudio"، SenseAudio مقدار SENSEAUDIO_API_KEY را دریافت می‌کند. جزئیات راه‌اندازی: SenseAudio.
• ارائه‌دهندگان صوت می‌توانند از پیش‌فرض‌های زیر tools.media.audio استفاده کنند یا baseUrl، headers، providerOptions و محدودیت‌ها را در ورودی tools.media.models[] خود بازنویسی کنند.
• سقف داخلی اندازه صوت 20MB است. بازنویسی maxBytes در سطح ورودی می‌تواند آن را تغییر دهد؛ صوت بیش‌ازحد بزرگ برای آن مدل نادیده گرفته می‌شود و ورودی بعدی امتحان می‌شود.
• فایل‌های صوتی کوچک‌تر از 1024 بایت پیش از رونویسی ارائه‌دهنده/CLI نادیده گرفته می‌شوند.
• مقدار پیش‌فرض maxChars برای صوت تنظیم‌نشده است (متن رونویسی کامل). برای کوتاه‌کردن خروجی، tools.media.audio.maxChars یا maxChars را در سطح هر ورودی تنظیم کنید.
• پیش‌فرض تشخیص خودکار OpenAI برابر با gpt-4o-transcribe است؛ برای گزینه‌ای ارزان‌تر/سریع‌تر، model: "gpt-4o-mini-transcribe" را تنظیم کنید.
• متن رونویسی‌شده با نام {{Transcript}} در دسترس قالب‌ها است.
• tools.media.audio.echoTranscript به‌طور پیش‌فرض خاموش است؛ echoFormat یک جای‌نگهدار {transcript} می‌پذیرد.
• خروجی استاندارد CLI به 5MB محدود است؛ خروجی CLI را مختصر نگه دارید.
• args مربوط به CLI باید برای مسیر فایل صوتی محلی از {{AttachmentPath}} استفاده کند. برای مهاجرت جای‌نگهدارهای منسوخ {input} از پیکربندی‌های قدیمی‌تر audio.transcription.command، openclaw doctor --fix را اجرا کنید (کلید بازنشسته: audio.transcription، جایگزین‌شده با tools.media.models). {{MediaPath}} همچنان یک نام مستعار سازگاری منسوخ است.
• tools.media.concurrency وظایف رسانه‌ای را محدود می‌کند؛ زمان‌بند GPU نیست.

STT محلی مقیم

STT محلی تشخیص‌داده‌شده به‌طور خودکار همچنان برای هر درخواست یک فرایند جداگانه اجرا می‌کند. OpenClaw در حال حاضر یک سرور مقیم whisper.cpp را مدیریت نمی‌کند، زیرا بسته استاندارد Homebrew با نام whisper-cpp آن سرور را غیرفعال می‌کند و نمونه بالادستی نیز صف پذیرش محدودشده پیکربندی‌شده‌ای ندارد. پیش از آنکه بتوان چرخه‌عمر مقیم تحت مالکیت Plugin را با ایمنی فعال کرد، به یک worker بسته‌بندی‌شده و نگه‌داری‌شده با سلامت/راه‌اندازی، اقامت مدل، صف‌بندی محدود، لغو/مهلت زمانی، عملیات بدون احراز هویت فقط روی 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 با کد 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، قالب‌های دیگر و قالب‌های خروجی سفارشی همچنان از خروجی استاندارد استفاده می‌کنند.
• مهلت‌های زمانی را معقول نگه دارید (timeoutSeconds، پیش‌فرض 60s) تا صف پاسخ‌دهی مسدود نشود.
• رونویسی پیش‌بررسی برای تشخیص اشاره فقط نخستین پیوست صوتی را پردازش می‌کند. پیوست‌های صوتی اضافی در مرحله اصلی درک رسانه پردازش می‌شوند.

مرتبط

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