---
read_when:
    - توضیح نحوهٔ کار جریان‌دهی یا قطعه‌بندی در کانال‌ها
    - تغییر رفتار جریان‌دهی بلوکی یا قطعه‌بندی کانال
    - اشکال‌زدایی پاسخ‌های بلوکی تکراری/زودهنگام یا جریان‌دهی پیش‌نمایش کانال
summary: رفتار پخش جریانی + قطعه‌بندی (پاسخ‌های بلوکی، پخش جریانی پیش‌نمایش کانال، نگاشت حالت)
title: جریان‌دهی و قطعه‌بندی
x-i18n:
    generated_at: "2026-05-03T11:34:35Z"
    model: gpt-5.5
    provider: openai
    source_hash: 85f6cb33031a6c818bb709e0ed14d8dd0f8c30a3dd90468a40396b3a515b5e65
    source_path: concepts/streaming.md
    workflow: 16
---

OpenClaw دو لایهٔ streaming جداگانه دارد:

- **streaming بلوکی (کانال‌ها):** هنگام نوشتن دستیار، **بلوک‌های** کامل‌شده را منتشر می‌کند. این‌ها پیام‌های عادی کانال هستند (نه token delta).
- **streaming پیش‌نمایش (Telegram/Discord/Slack):** هنگام تولید، یک **پیام پیش‌نمایش** موقت را به‌روزرسانی می‌کند.

امروز **streaming واقعی token-delta** برای پیام‌های کانال وجود ندارد. streaming پیش‌نمایش مبتنی بر پیام است (ارسال + ویرایش‌ها/افزودن‌ها).

## streaming بلوکی (پیام‌های کانال)

streaming بلوکی خروجی دستیار را به‌محض آماده‌شدن، در قطعه‌های درشت ارسال می‌کند.

```
Model output
  └─ text_delta/events
       ├─ (blockStreamingBreak=text_end)
       │    └─ chunker emits blocks as buffer grows
       └─ (blockStreamingBreak=message_end)
            └─ chunker flushes at message_end
                   └─ channel send (block replies)
```

راهنما:

- `text_delta/events`: رویدادهای stream مدل (ممکن است برای مدل‌های غیر-streaming پراکنده باشد).
- `chunker`: `EmbeddedBlockChunker` که کران‌های حداقل/حداکثر + ترجیح شکست را اعمال می‌کند.
- `channel send`: پیام‌های خروجی واقعی (پاسخ‌های بلوکی).

**کنترل‌ها:**

- `agents.defaults.blockStreamingDefault`: `"on"`/`"off"` (پیش‌فرض خاموش).
- بازنویسی‌های کانال: `*.blockStreaming` (و گونه‌های هر حساب) برای اجبار `"on"`/`"off"` به‌ازای هر کانال.
- `agents.defaults.blockStreamingBreak`: `"text_end"` یا `"message_end"`.
- `agents.defaults.blockStreamingChunk`: `{ minChars, maxChars, breakPreference? }`.
- `agents.defaults.blockStreamingCoalesce`: `{ minChars?, maxChars?, idleMs? }` (ادغام بلوک‌های stream‌شده پیش از ارسال).
- سقف سخت کانال: `*.textChunkLimit` (برای نمونه، `channels.whatsapp.textChunkLimit`).
- حالت قطعه‌بندی کانال: `*.chunkMode` (پیش‌فرض `length`، مقدار `newline` پیش از قطعه‌بندی بر اساس طول، روی خطوط خالی (مرزهای پاراگراف) جدا می‌کند).
- سقف نرم Discord: `channels.discord.maxLinesPerMessage` (پیش‌فرض 17) پاسخ‌های بلند را جدا می‌کند تا از بریده‌شدن UI جلوگیری شود.

**معنای مرزها:**

- `text_end`: به‌محض اینکه chunker منتشر کند، بلوک‌ها را stream کن؛ در هر `text_end` تخلیه کن.
- `message_end`: تا پایان پیام دستیار صبر کن، سپس خروجی بافرشده را تخلیه کن.

`message_end` همچنان اگر متن بافرشده از `maxChars` بیشتر باشد از chunker استفاده می‌کند، بنابراین می‌تواند در پایان چند قطعه منتشر کند.

### تحویل رسانه با streaming بلوکی

دستورهای `MEDIA:` فرادادهٔ عادی تحویل هستند. وقتی streaming بلوکی یک
بلوک رسانه را زودتر ارسال می‌کند، OpenClaw آن تحویل را برای آن نوبت به خاطر می‌سپارد. اگر payload نهایی
دستیار همان URL رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوبارهٔ پیوست،
رسانهٔ تکراری را حذف می‌کند.

payloadهای نهایی کاملاً تکراری سرکوب می‌شوند. اگر payload نهایی متن
متمایزی پیرامون رسانه‌ای اضافه کند که قبلاً stream شده است، OpenClaw همچنان
متن جدید را ارسال می‌کند و رسانه را تک‌تحویلی نگه می‌دارد. این کار از تکرار یادداشت‌های صوتی
یا فایل‌ها در کانال‌هایی مانند Telegram جلوگیری می‌کند، وقتی یک agent هنگام
streaming مقدار `MEDIA:` منتشر می‌کند و provider نیز آن را در پاسخ کامل‌شده می‌آورد.

## الگوریتم قطعه‌بندی (کران‌های پایین/بالا)

قطعه‌بندی بلوکی توسط `EmbeddedBlockChunker` پیاده‌سازی می‌شود:

- **کران پایین:** تا زمانی که buffer >= `minChars` نشده منتشر نکن (مگر با اجبار).
- **کران بالا:** جداسازی پیش از `maxChars` را ترجیح بده؛ اگر اجباری بود، در `maxChars` جدا کن.
- **ترجیح شکست:** `paragraph` → `newline` → `sentence` → `whitespace` → شکست سخت.
- **Code fences:** هرگز داخل fences جدا نکن؛ هنگام اجبار در `maxChars`، fence را ببند + دوباره باز کن تا Markdown معتبر بماند.

`maxChars` به `textChunkLimit` کانال محدود می‌شود، بنابراین نمی‌توانید از سقف‌های هر کانال فراتر بروید.

## هم‌جوشی (ادغام بلوک‌های stream‌شده)

وقتی streaming بلوکی فعال باشد، OpenClaw می‌تواند **قطعه‌های بلوکی پیاپی را**
پیش از ارسال بیرونی ادغام کند. این کار «هرزپیام تک‌خطی» را کاهش می‌دهد و هم‌زمان
خروجی تدریجی ارائه می‌کند.

- هم‌جوشی پیش از تخلیه برای **وقفه‌های بیکاری** (`idleMs`) صبر می‌کند.
- بافرها با `maxChars` سقف‌گذاری می‌شوند و اگر از آن فراتر بروند تخلیه خواهند شد.
- `minChars` جلوی ارسال تکه‌های بسیار کوچک را می‌گیرد تا متن کافی انباشته شود
  (تخلیهٔ نهایی همیشه متن باقی‌مانده را ارسال می‌کند).
- اتصال‌دهنده از `blockStreamingChunk.breakPreference` مشتق می‌شود
  (`paragraph` → `\n\n`، `newline` → `\n`، `sentence` → فاصله).
- بازنویسی‌های کانال از طریق `*.blockStreamingCoalesce` در دسترس‌اند (از جمله پیکربندی‌های هر حساب).
- مقدار پیش‌فرض `minChars` برای coalesce، مگر در صورت بازنویسی، برای Signal/Slack/Discord به 1500 افزایش داده می‌شود.

## ضرباهنگ انسانی بین بلوک‌ها

وقتی streaming بلوکی فعال باشد، می‌توانید بین
پاسخ‌های بلوکی (پس از بلوک اول) یک **مکث تصادفی‌سازی‌شده** اضافه کنید. این باعث می‌شود پاسخ‌های چندحبابی
طبیعی‌تر به نظر برسند.

- پیکربندی: `agents.defaults.humanDelay` (بازنویسی برای هر agent از طریق `agents.list[].humanDelay`).
- حالت‌ها: `off` (پیش‌فرض)، `natural` (800–2500ms)، `custom` (`minMs`/`maxMs`).
- فقط روی **پاسخ‌های بلوکی** اعمال می‌شود، نه پاسخ‌های نهایی یا خلاصه‌های tool.

## «Stream قطعه‌ها یا همه‌چیز»

این به موارد زیر نگاشت می‌شود:

- **Stream قطعه‌ها:** `blockStreamingDefault: "on"` + `blockStreamingBreak: "text_end"` (هم‌زمان با پیشروی منتشر کن). کانال‌های غیر-Telegram همچنین به `*.blockStreaming: true` نیاز دارند.
- **Stream همه‌چیز در پایان:** `blockStreamingBreak: "message_end"` (یک‌بار تخلیه کن، اگر بسیار طولانی باشد احتمالاً در چند قطعه).
- **بدون streaming بلوکی:** `blockStreamingDefault: "off"` (فقط پاسخ نهایی).

**نکتهٔ کانال:** streaming بلوکی **خاموش است مگر اینکه**
`*.blockStreaming` به‌صراحت روی `true` تنظیم شود. کانال‌ها می‌توانند بدون پاسخ‌های بلوکی، یک پیش‌نمایش زنده
(`channels.<channel>.streaming`) را stream کنند.

یادآوری محل پیکربندی: پیش‌فرض‌های `blockStreaming*` زیر
`agents.defaults` قرار دارند، نه پیکربندی ریشه.

## حالت‌های streaming پیش‌نمایش

کلید canonical: `channels.<channel>.streaming`

حالت‌ها:

- `off`: streaming پیش‌نمایش را غیرفعال کن.
- `partial`: یک پیش‌نمایش واحد که با آخرین متن جایگزین می‌شود.
- `block`: پیش‌نمایش در گام‌های قطعه‌بندی‌شده/افزوده‌شده به‌روزرسانی می‌شود.
- `progress`: پیش‌نمایش پیشرفت/وضعیت هنگام تولید، پاسخ نهایی در پایان.

### نگاشت کانال

| کانال      | `off` | `partial` | `block` | `progress`             |
| ---------- | ----- | --------- | ------- | ---------------------- |
| Telegram   | ✅    | ✅        | ✅      | به `partial` نگاشت می‌شود |
| Discord    | ✅    | ✅        | ✅      | به `partial` نگاشت می‌شود |
| Slack      | ✅    | ✅        | ✅      | ✅                     |
| Mattermost | ✅    | ✅        | ✅      | ✅                     |

فقط Slack:

- `channels.slack.streaming.nativeTransport` وقتی `channels.slack.streaming.mode="partial"` باشد فراخوانی‌های API streaming بومی Slack را تغییر می‌دهد (پیش‌فرض: `true`).
- streaming بومی Slack و وضعیت thread دستیار Slack به هدف thread پاسخ نیاز دارند. DMهای سطح بالا آن پیش‌نمایش سبک thread را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌ها و ویرایش‌های پیش‌نمایش draft Slack استفاده کنند.

مهاجرت کلید legacy:

- Telegram: مقدارهای legacy `streamMode` و مقدارهای scalar/boolean `streaming` توسط مسیرهای سازگاری doctor/config شناسایی و به `streaming.mode` مهاجرت می‌شوند.
- Discord: `streamMode` + `streaming` boolean به‌صورت خودکار به enum `streaming` مهاجرت می‌کنند.
- Slack: `streamMode` به‌صورت خودکار به `streaming.mode` مهاجرت می‌کند؛ `streaming` boolean به‌صورت خودکار به `streaming.mode` به‌علاوهٔ `streaming.nativeTransport` مهاجرت می‌کند؛ `nativeStreaming` قدیمی به‌صورت خودکار به `streaming.nativeTransport` مهاجرت می‌کند.

### رفتار زمان اجرا

Telegram:

- از `sendMessage` + به‌روزرسانی‌های پیش‌نمایش `editMessageText` در DMها و group/topics استفاده می‌کند.
- وقتی پیش‌نمایش حدود یک دقیقه قابل مشاهده بوده باشد، به‌جای ویرایش در محل، یک پیام نهایی تازه ارسال می‌کند، سپس پیش‌نمایش را پاک می‌کند تا timestamp مربوط به Telegram تکمیل پاسخ را منعکس کند.
- وقتی streaming بلوکی Telegram به‌صراحت فعال باشد، streaming پیش‌نمایش رد می‌شود (برای جلوگیری از streaming دوگانه).
- `/reasoning stream` می‌تواند reasoning را در پیش‌نمایش بنویسد.

Discord:

- از ارسال + ویرایش پیام‌های پیش‌نمایش استفاده می‌کند.
- حالت `block` از قطعه‌بندی draft (`draftChunk`) استفاده می‌کند.
- وقتی streaming بلوکی Discord به‌صراحت فعال باشد، streaming پیش‌نمایش رد می‌شود.
- رسانهٔ نهایی، خطا و payloadهای explicit-reply، پیش‌نمایش‌های معلق را بدون تخلیهٔ draft جدید لغو می‌کنند، سپس از تحویل عادی استفاده می‌کنند.

Slack:

- `partial` در صورت دسترس‌بودن می‌تواند از streaming بومی Slack (`chat.startStream`/`append`/`stop`) استفاده کند.
- `block` از پیش‌نمایش‌های draft به سبک append استفاده می‌کند.
- `progress` از متن پیش‌نمایش وضعیت و سپس پاسخ نهایی استفاده می‌کند.
- DMهای سطح بالا بدون thread پاسخ، به‌جای streaming بومی Slack از پست‌ها و ویرایش‌های پیش‌نمایش draft استفاده می‌کنند.
- streaming پیش‌نمایش بومی و draft پاسخ‌های بلوکی را برای آن نوبت سرکوب می‌کند، بنابراین یک پاسخ Slack فقط توسط یک مسیر تحویل stream می‌شود.
- payloadهای نهایی رسانه/خطا و نهایی‌های progress پیام‌های draft یک‌بارمصرف ایجاد نمی‌کنند؛ فقط نهایی‌های متن/بلوک که می‌توانند پیش‌نمایش را ویرایش کنند، متن draft معلق را تخلیه می‌کنند.

Mattermost:

- thinking، فعالیت tool و متن پاسخ جزئی را در یک پست پیش‌نمایش draft واحد stream می‌کند که وقتی ارسال پاسخ نهایی امن باشد در محل نهایی می‌شود.
- اگر پست پیش‌نمایش حذف شده باشد یا در زمان نهایی‌سازی به هر دلیل در دسترس نباشد، به ارسال یک پست نهایی تازه برمی‌گردد.
- payloadهای نهایی رسانه/خطا پیش از تحویل عادی، به‌جای تخلیهٔ یک پست پیش‌نمایش موقت، به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند.

Matrix:

- پیش‌نمایش‌های draft وقتی متن نهایی بتواند از رویداد پیش‌نمایش دوباره استفاده کند، در محل نهایی می‌شوند.
- نهایی‌های فقط‌رسانه، خطا و عدم‌تطابق هدف پاسخ، پیش از تحویل عادی به‌روزرسانی‌های پیش‌نمایش معلق را لغو می‌کنند؛ یک پیش‌نمایش قدیمی که از قبل قابل مشاهده باشد redacted می‌شود.

### به‌روزرسانی‌های پیش‌نمایش پیشرفت tool

streaming پیش‌نمایش همچنین می‌تواند شامل به‌روزرسانی‌های **پیشرفت tool** باشد — خط‌های وضعیت کوتاهی مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل»، یا «در حال فراخوانی tool» — که هنگام اجرای toolها، پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. این کار باعث می‌شود نوبت‌های چندمرحله‌ای tool از نظر بصری زنده بمانند، نه اینکه بین نخستین پیش‌نمایش thinking و پاسخ نهایی خاموش باشند.

سطح‌های پشتیبانی‌شده:

- **Discord**، **Slack**، **Telegram**، و **Matrix** وقتی streaming پیش‌نمایش فعال باشد، به‌صورت پیش‌فرض پیشرفت tool را در ویرایش پیش‌نمایش زنده stream می‌کنند.
- Telegram از `v2026.4.22` با به‌روزرسانی‌های پیش‌نمایش پیشرفت tool فعال منتشر شده است؛ فعال نگه‌داشتن آن‌ها رفتار منتشرشده را حفظ می‌کند.
- **Mattermost** از قبل فعالیت tool را در پست پیش‌نمایش draft واحد خود ادغام می‌کند (بالا را ببینید).
- ویرایش‌های پیشرفت tool از حالت فعال streaming پیش‌نمایش پیروی می‌کنند؛ وقتی streaming پیش‌نمایش `off` باشد یا وقتی streaming بلوکی پیام را در اختیار گرفته باشد، رد می‌شوند. در Telegram، `streaming.mode: "off"` فقط نهایی است: گفت‌وگوی پیشرفت generic نیز به‌جای تحویل به‌عنوان پیام‌های مستقل «در حال کار...»، سرکوب می‌شود، در حالی که درخواست‌های approval، payloadهای رسانه و خطاها همچنان به‌صورت عادی مسیریابی می‌شوند.
- برای نگه‌داشتن streaming پیش‌نمایش اما پنهان‌کردن خط‌های پیشرفت tool، `streaming.preview.toolProgress` را برای آن کانال روی `false` تنظیم کنید. برای غیرفعال‌کردن کامل ویرایش‌های پیش‌نمایش، `streaming.mode` را روی `off` تنظیم کنید.

نمونه:

```json
{
  "channels": {
    "telegram": {
      "streaming": {
        "mode": "partial",
        "preview": {
          "toolProgress": false
        }
      }
    }
  }
}
```

## مرتبط

- [پیام‌ها](/fa/concepts/messages) — چرخهٔ عمر پیام و تحویل
- [تلاش مجدد](/fa/concepts/retry) — رفتار تلاش مجدد هنگام شکست تحویل
- [کانال‌ها](/fa/channels) — پشتیبانی streaming به‌ازای هر کانال
