---
read_when:
    - تغییر رونویسی صوت یا مدیریت رسانه
summary: نحوه بارگیری، رونویسی و درج یادداشت‌های صوتی/پیام‌های صوتی ورودی در پاسخ‌ها
title: صدا و یادداشت‌های صوتی
x-i18n:
    generated_at: "2026-07-12T10:18:12Z"
    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`، پیش از گزینه‌های پیش‌فرض 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` را تنظیم کنید.

<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](/fa/providers/groq).
- هنگام استفاده از `provider: "deepgram"`، ‏Deepgram مقدار `DEEPGRAM_API_KEY` را دریافت می‌کند. جزئیات راه‌اندازی: [Deepgram](/fa/providers/deepgram).
- جزئیات راه‌اندازی Mistral:‏ [Mistral](/fa/providers/mistral).
- هنگام استفاده از `provider: "senseaudio"`، ‏SenseAudio مقدار `SENSEAUDIO_API_KEY` را دریافت می‌کند. جزئیات راه‌اندازی: [SenseAudio](/fa/providers/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`، با مقدار پیش‌فرض ۶۰ ثانیه).
- رونویسی پیش‌بررسی فقط **نخستین** پیوست صوتی را برای تشخیص اشاره پردازش می‌کند. پیوست‌های صوتی اضافی در مرحلهٔ اصلی درک رسانه پردازش می‌شوند.

## مرتبط

- [درک رسانه](/fa/nodes/media-understanding)
- [حالت گفت‌وگو](/fa/nodes/talk)
- [فعال‌سازی صوتی](/fa/nodes/voicewake)