استریم و قطعه‌بندی

OpenClaw دو لایهٔ مستقل برای استریم دارد و در حال حاضر هیچ استریم واقعیِ تفاضل توکن به پیام‌های کانال وجود ندارد:

• استریم بلوکی (کانال‌ها): هم‌زمان با نوشتن دستیار، بلوک‌های تکمیل‌شده را ارسال می‌کند. این‌ها پیام‌های عادی کانال هستند، نه تفاضل‌های توکن.
• استریم پیش‌نمایش (Telegram/Discord/Slack/Matrix/Mattermost/MS Teams): هنگام تولید، یک پیام پیش‌نمایش موقت را به‌روزرسانی می‌کند (ارسال + ویرایش/افزودن).

استریم بلوکی (پیام‌های کانال)

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

خروجی مدل  └─ text_delta/رویدادها       ├─ (blockStreamingBreak=text_end)       │    └─ قطعه‌بند با افزایش بافر، بلوک‌ها را ارسال می‌کند       └─ (blockStreamingBreak=message_end)            └─ قطعه‌بند در message_end بافر را تخلیه می‌کند                   └─ ارسال به کانال (پاسخ‌های بلوکی)

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

کنترل‌ها (همه زیر agents.defaults هستند، مگر آنکه خلافش ذکر شود):

streaming.chunkMode: "newline" متن را در خطوط خالی (مرز پاراگراف‌ها) تقسیم می‌کند، نه در هر خط جدید؛ و پس از عبور متن از حد، به قطعه‌بندی بر اساس طول بازمی‌گردد.

کانال‌های همراه، این بازنویسی‌ها را به‌شکل channels.<id>.streaming.{chunkMode,block.enabled,block.coalesce} می‌نویسند. شکل‌های تخت *.chunkMode / *.blockStreaming / *.blockStreamingCoalesce در تمام کانال‌های همراه قدیمی محسوب می‌شوند: openclaw doctor --fix آن‌ها را به ساختار تودرتو مهاجرت می‌دهد و طرح‌واره‌های کانال آن‌ها را رد می‌کنند. پیکربندی‌های Plugin خارجی SDK که همچنان از شکل‌های تخت استفاده می‌کنند، تا چرخهٔ انتشار بعدی از طریق یک مسیر بازگشت منسوخ (همراه با هشدار زمان اجرا) به کار ادامه می‌دهند.

معناشناسی مرز برای blockStreamingBreak:

• text_end: بلوک‌ها را به‌محض ارسال توسط قطعه‌بند استریم می‌کند؛ در هر text_end تخلیه می‌شود.
• message_end: تا پایان پیام دستیار صبر می‌کند، سپس خروجی بافرشده را تخلیه می‌کند. اگر متن بافرشده از maxChars فراتر رود، همچنان از قطعه‌بند استفاده می‌کند؛ بنابراین ممکن است در پایان چند قطعه ارسال کند.

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

رسانهٔ استریم‌شده باید از فیلدهای ساختاریافتهٔ محموله، مانند mediaUrl یا mediaUrls استفاده کند؛ متن استریم‌شده به‌عنوان فرمان پیوست تجزیه نمی‌شود. وقتی استریم بلوکی رسانه را زودتر ارسال می‌کند، OpenClaw آن تحویل را برای این نوبت به خاطر می‌سپارد. اگر محمولهٔ نهایی دستیار همان نشانی اینترنتی رسانه را تکرار کند، تحویل نهایی به‌جای ارسال دوبارهٔ پیوست، رسانهٔ تکراری را حذف می‌کند.

محموله‌های نهایی کاملاً یکسان ارسال نمی‌شوند. اگر محمولهٔ نهایی پیرامون رسانه‌ای که قبلاً استریم شده است متن متمایزی اضافه کند، OpenClaw همچنان متن جدید را ارسال می‌کند و درعین‌حال رسانه را فقط یک‌بار تحویل می‌دهد. این کار از تکرار یادداشت‌های صوتی یا فایل‌ها در کانال‌هایی مانند Telegram جلوگیری می‌کند.

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

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

• کران پایین: تا زمانی که بافر >= minChars نشده است، ارسال نکنید (مگر در حالت اجباری).
• کران بالا: شکست پیش از maxChars ترجیح داده می‌شود؛ اگر اجباری باشد، در maxChars تقسیم می‌شود.
• زنجیرهٔ ترجیح شکست: paragraph -> newline -> sentence -> فاصلهٔ خالی -> شکست قطعی.
• حصارهای کد: هرگز داخل حصارها تقسیم نمی‌شود؛ هنگام اجبار در maxChars، حصار بسته و دوباره باز می‌شود تا Markdown معتبر بماند.

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

ادغام (ترکیب بلوک‌های استریم‌شده)

وقتی استریم بلوکی فعال است، OpenClaw می‌تواند پیش از ارسال، قطعه‌های بلوکی متوالی را ادغام کند تا ضمن حفظ خروجی تدریجی، از انباشت پیام‌های تک‌خطی بکاهد.

• ادغام پیش از تخلیه، منتظر وقفه‌های بیکاری (idleMs) می‌ماند.
• بافرها به maxChars محدود می‌شوند و در صورت عبور از آن تخلیه می‌شوند.
• minChars تا زمان انباشته‌شدن متن کافی از ارسال قطعه‌های بسیار کوچک جلوگیری می‌کند (تخلیهٔ نهایی همیشه متن باقی‌مانده را ارسال می‌کند).
• جداکننده از blockStreamingChunk.breakPreference به دست می‌آید: paragraph -> \n\n، newline -> \n، sentence -> فاصله.
• بازنویسی‌های کانال از طریق *.streaming.block.coalesce در دسترس‌اند (از جمله پیکربندی‌های هر حساب).
• Discord، Signal و Slack به‌طور پیش‌فرض تا { minChars: 1500, idleMs: 1000 } ادغام می‌کنند، مگر آنکه بازنویسی شده باشد.

آهنگ طبیعی میان بلوک‌ها

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

برای هر عامل از طریق agents.list[].humanDelay بازنویسی کنید. فقط برای پاسخ‌های بلوکی اعمال می‌شود، نه پاسخ‌های نهایی یا خلاصه‌های ابزار.

«استریم قطعه‌ها یا همه‌چیز»

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

استریم بلوکی خاموش است، مگر آنکه *.streaming.block.enabled صریحاً روی true تنظیم شود (استثنا: QQ Bot هیچ کلید streaming.block ندارد و پاسخ‌های بلوکی را استریم می‌کند، مگر آنکه channels.qqbot.streaming.mode برابر "off" باشد). کانال‌ها می‌توانند بدون پاسخ‌های بلوکی، یک پیش‌نمایش زنده (channels.<channel>.streaming.mode) را استریم کنند. پیش‌فرض‌های blockStreaming* زیر agents.defaults قرار دارند، نه در ریشهٔ پیکربندی.

حالت‌های استریم پیش‌نمایش

کلید معیار: channels.<channel>.streaming ({ mode, ... } تودرتو؛ شکل‌های قدیمی بولی/رشته‌ای سطح بالا توسط openclaw doctor --fix بازنویسی می‌شوند).

streaming.mode: "block" یک حالت استریم پیش‌نمایش برای کانال‌های دارای قابلیت ویرایش، مانند Discord و Telegram است؛ این حالت به‌تنهایی تحویل بلوکی کانال را در آن‌ها فعال نمی‌کند. برای پاسخ‌های بلوکی عادی از streaming.block.enabled استفاده کنید. Microsoft Teams استثنا است: انتقال بلوکیِ پیش‌نمایش پیش‌نویس ندارد، بنابراین streaming.mode: "block" استریم بومی را کاملاً غیرفعال می‌کند و پاسخ به‌جای استریم جزئی/پیشرفت بومی، به‌صورت تحویل بلوکی عادی ارائه می‌شود. Mattermost نیز متفاوت است: در حالت block پیش‌نمایش را میان متن تکمیل‌شده و بلوک‌های فعالیت ابزار جابه‌جا می‌کند؛ بنابراین بلوک‌های پیشین به‌جای بازنویسی‌شدن در یک پیش‌نویس قابل‌ویرایش، به‌صورت پست‌های جداگانه قابل‌مشاهده می‌مانند.

نگاشت کانال‌ها

پیکربندی قطعه‌های پیش‌نمایش (streaming.preview.chunk.*، برای مثال زیر channels.discord.streaming یا channels.telegram.streaming) به‌طور پیش‌فرض minChars: 200، maxChars: 800 (محدودشده به textChunkLimit کانال) و breakPreference: "paragraph" است.

مختص Slack:

• channels.slack.streaming.nativeTransport فراخوانی‌های API استریم بومی Slack (chat.startStream/chat.appendStream/chat.stopStream) را هنگامی تغییر وضعیت می‌دهد که channels.slack.streaming.mode="partial" باشد (پیش‌فرض: true).
• استریم بومی Slack و وضعیت رشتهٔ دستیار Slack به یک مقصد رشتهٔ پاسخ نیاز دارند. پیام‌های خصوصی سطح بالا آن پیش‌نمایش رشته‌مانند را نشان نمی‌دهند، اما همچنان می‌توانند از پست‌های پیش‌نمایش پیش‌نویس Slack و ویرایش آن‌ها استفاده کنند.

مهاجرت کلیدهای قدیمی

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

Telegram

• از به‌روزرسانی‌های پیش‌نمایش sendMessage + editMessageText در پیام‌های خصوصی و گروه‌ها/موضوع‌ها استفاده می‌کند؛ متن نهایی همان پیش‌نمایش فعال را درجا ویرایش می‌کند. پیش‌نویس‌های موقتی ۳۰ثانیه‌ای «در حال تایپ» Telegram (sendMessageDraft) برای استریم پاسخ استفاده نمی‌شوند.
• پیش‌نمایش‌های اولیه کوتاه همچنان برای تجربه کاربری اعلان‌های فشاری با تأخیر ادغام می‌شوند، اما پس از تأخیری محدود پدیدار می‌شوند تا اجراهای فعال از نظر بصری ساکت نمانند.
• خروجی‌های نهایی طولانی برای قطعه نخست از پیام پیش‌نمایش دوباره استفاده می‌کنند و فقط قطعه‌های باقی‌مانده را می‌فرستند.
• حالت block در streaming.preview.chunk.maxChars پیش‌نمایش را به پیامی جدید منتقل می‌کند (پیش‌فرض 800، با سقف محدودیت ویرایش 4096 کاراکتری Telegram)؛ حالت‌های دیگر یک پیش‌نمایش را تا 4096 کاراکتر گسترش می‌دهند.
• حالت progress پیشرفت ابزار را در یک پیش‌نویس وضعیت قابل‌ویرایش نگه می‌دارد، وقتی استریم پاسخ فعال است اما هنوز خط ابزاری موجود نیست برچسب وضعیت را پدیدار می‌کند، پیش‌نویس را هنگام تکمیل پاک می‌کند و پاسخ نهایی را از مسیر تحویل عادی می‌فرستد.
• اگر ویرایش نهایی پیش از تأیید متن تکمیل‌شده ناموفق باشد، OpenClaw از تحویل نهایی عادی استفاده می‌کند و پیش‌نمایش منسوخ را پاک می‌کند.
• هنگامی که استریم بلوکی Telegram صراحتاً فعال باشد، برای جلوگیری از استریم دوگانه از استریم پیش‌نمایش صرف‌نظر می‌شود.
• /reasoning stream می‌تواند استدلال را در پیش‌نمایشی موقت بنویسد که پس از تحویل نهایی حذف می‌شود.
• پاسخ‌های نقل‌قول انتخاب‌شده Telegram یک استثنا هستند: وقتی replyToMode برابر با "off" نیست و متن نقل‌قول انتخاب‌شده وجود دارد، OpenClaw برای آن نوبت از استریم پیش‌نمایش پاسخ صرف‌نظر می‌کند (پاسخ نهایی باید از مسیر بومی پاسخ به نقل‌قول عبور کند)، بنابراین خطوط پیش‌نمایش پیشرفت ابزار نمی‌توانند نمایش داده شوند. پاسخ‌ها به پیام جاری بدون متن نقل‌قول انتخاب‌شده همچنان استریم پیش‌نمایش را حفظ می‌کنند. برای جزئیات، مستندات کانال Telegram را ببینید.

Discord

• از ارسال + ویرایش پیام‌های پیش‌نمایش استفاده می‌کند.
• حالت block از قطعه‌بندی پیش‌نویس (draftChunk) استفاده می‌کند.
• هنگامی که استریم بلوکی Discord صراحتاً فعال باشد، از استریم پیش‌نمایش صرف‌نظر می‌شود.
• حالت progress یک رسید کوچک فعالیت -# (تعداد فکرها/فراخوانی‌های ابزار و زمان سپری‌شده) را به پاسخ نهایی می‌افزاید و پس از تحویل آن پاسخ، پیش‌نویس وضعیت را حذف می‌کند تا کانال‌های شلوغ هیچ گزارش ابزار بی‌سرپرستی را بالای پاسخ نگه ندارند. در خروجی‌های نهایی خطا، پیش‌نویس به‌عنوان سابقه نوبت ناموفق حفظ می‌شود.
• محموله‌های نهایی رسانه، خطا و پاسخ صریح، پیش‌نمایش‌های در انتظار را بدون تخلیه پیش‌نویسی جدید لغو می‌کنند و سپس از تحویل عادی استفاده می‌کنند.

Slack

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

Mattermost

• در حالت partial، متن تفکر و پاسخ جزئی را در یک پست پیش‌نمایش پیش‌نویس استریم می‌کند که وقتی ارسال پاسخ نهایی ایمن باشد، درجا نهایی می‌شود.
• در حالت progress، تفکر و فعالیت ابزار را در یک پیش‌نمایش وضعیت واحد استریم می‌کند که وقتی ارسال پاسخ نهایی ایمن باشد، درجا نهایی می‌شود.
• در حالت block، میان پست‌های متن تکمیل‌شده و فعالیت ابزار جابه‌جا می‌شود؛ به‌روزرسانی‌های موازی و متوالی ابزار، پست جاری فعالیت ابزار را به‌اشتراک می‌گذارند.
• اگر پست پیش‌نمایش حذف شده باشد یا هنگام نهایی‌سازی به‌شکل دیگری در دسترس نباشد، به ارسال یک پست نهایی تازه بازمی‌گردد.
• محموله‌های نهایی رسانه/خطا پیش از تحویل عادی، به‌روزرسانی‌های در انتظار پیش‌نمایش را لغو می‌کنند و یک پست پیش‌نمایش موقت را تخلیه نمی‌کنند.

Matrix

• وقتی متن نهایی بتواند از رویداد پیش‌نمایش دوباره استفاده کند، پیش‌نمایش‌های پیش‌نویس درجا نهایی می‌شوند.
• خروجی‌های نهایی فقط‌رسانه، خطا و دارای عدم‌تطابق مقصد پاسخ، پیش از تحویل عادی به‌روزرسانی‌های در انتظار پیش‌نمایش را لغو می‌کنند؛ پیش‌نمایش منسوخی که از قبل قابل‌مشاهده است، حذف می‌شود.

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

استریم پیش‌نمایش همچنین می‌تواند شامل به‌روزرسانی‌های پیشرفت ابزار باشد: خطوط وضعیت کوتاهی مانند «در حال جست‌وجوی وب»، «در حال خواندن فایل» یا «در حال فراخوانی ابزار» که هنگام اجرای ابزارها و پیش از پاسخ نهایی، در همان پیام پیش‌نمایش ظاهر می‌شوند. در حالت app-server نرم‌افزار Codex، پیام‌های مقدمه/توضیحات Codex از همین مسیر پیش‌نمایش استفاده می‌کنند؛ بنابراین یادداشت‌های کوتاه پیشرفت مانند «در حال بررسی هستم...» می‌توانند بدون تبدیل‌شدن به بخشی از پاسخ نهایی، در پیش‌نویس قابل‌ویرایش استریم شوند. این کار نوبت‌های چندمرحله‌ای ابزار را از نظر بصری فعال نگه می‌دارد، به‌جای آنکه میان نخستین پیش‌نمایش تفکر و پاسخ نهایی ساکت بمانند.

ابزارهای طولانی‌مدت ممکن است پیش از بازگشت، پیشرفت نوع‌دار منتشر کنند. برای مثال، web_fetch هنگام شروع یک زمان‌سنج پنج‌ثانیه‌ای فعال می‌کند: اگر واکشی همچنان در انتظار باشد، پیش‌نمایش Fetching page content... را نشان می‌دهد؛ اگر واکشی پیش از آن پایان یابد یا لغو شود، هیچ خط پیشرفتی منتشر نمی‌شود. نتیجه نهایی بعدی ابزار همچنان به‌شکل عادی به مدل تحویل داده می‌شود.

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

• Discord، Slack، Telegram و Matrix به‌طور پیش‌فرض، هنگامی که استریم پیش‌نمایش فعال است، پیشرفت ابزار و به‌روزرسانی‌های مقدمه Codex را در ویرایش زنده پیش‌نمایش استریم می‌کنند. Microsoft Teams در گفت‌وگوهای شخصی از استریم بومی پیشرفت خود استفاده می‌کند.
• Telegram از v2026.4.22 با به‌روزرسانی‌های پیش‌نمایش پیشرفت ابزار فعال عرضه شده است؛ فعال نگه‌داشتن آن‌ها این رفتار منتشرشده را حفظ می‌کند.
• Mattermost در حالت‌های partial و progress فعالیت ابزار را در یک پست پیش‌نمایش ادغام می‌کند، یا در حالت block یک پست فعالیت ابزار میان بلوک‌های متنی قرار می‌دهد (بالاتر را ببینید).
• ویرایش‌های پیشرفت ابزار از حالت فعال استریم پیش‌نمایش پیروی می‌کنند؛ وقتی استریم پیش‌نمایش off باشد یا استریم بلوکی کنترل پیام را به‌دست گرفته باشد، از آن‌ها صرف‌نظر می‌شود. در Telegram، streaming.mode: "off" فقط برای خروجی نهایی است: گفت‌وگوی عمومی پیشرفت نیز به‌جای تحویل به‌عنوان پیام‌های وضعیت مستقل سرکوب می‌شود، درحالی‌که درخواست‌های تأیید، محموله‌های رسانه و خطاها همچنان به‌شکل عادی مسیریابی می‌شوند.
• برای حفظ استریم پیش‌نمایش و پنهان‌کردن خطوط پیشرفت ابزار، streaming.preview.toolProgress را برای آن کانال روی false تنظیم کنید (پیش‌فرض true). برای نمایان نگه‌داشتن خطوط پیشرفت ابزار و پنهان‌کردن متن فرمان/اجرا، streaming.preview.commandText را روی "status" یا streaming.progress.commandText را روی "status" تنظیم کنید؛ مقدار پیش‌فرض "raw" است تا رفتار منتشرشده حفظ شود. این خط‌مشی میان کانال‌های پیش‌نویس/پیشرفت که از رندرکننده فشرده پیشرفت OpenClaw استفاده می‌کنند مشترک است، از جمله Discord، Matrix، Microsoft Teams، Mattermost، پیش‌نمایش‌های پیش‌نویس Slack و Telegram. برای غیرفعال‌کردن کامل ویرایش‌های پیش‌نمایش، streaming.mode را روی off تنظیم کنید.

رندر پیش‌نویس پیشرفت

پیش‌نویس‌های حالت پیشرفت (streaming.progress.*) محدود و برای هر کانال قابل‌پیکربندی هستند:

مسیر پیشرفت توضیحات

فراتر از پیشرفت ابزار، رندرکننده فشرده پیشرفت می‌تواند یک مسیر دیگر را در پیش‌نویس نمایش دهد:

• streaming.progress.commentary - توضیحات پیش از ابزار مدل (روایت کوتاهی مانند «بررسی می‌کنم... سپس...») را درهم‌آمیخته با خطوط ابزار در پیش‌نویس پیشرفت رندر می‌کند. در Discord و Telegram در حالت پیشرفت، همین مقدمه حتی وقتی این مسیر اختیاری خاموش است، تیتر وضعیت را تأمین می‌کند؛ کانال‌های دیگر رفتار پیشرفت موجود خود را حفظ می‌کنند. پیش‌نویس‌های پیشرفت را ببینید.

{  "channels": {    "discord": {      "streaming": { "mode": "progress", "progress": { "commentary": true } }    }  }}

خطوط پیشرفت را نمایان نگه دارید، اما متن خام فرمان/اجرا را پنهان کنید:

{  "channels": {    "telegram": {      "streaming": {        "mode": "partial",        "preview": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

همین ساختار را زیر کلید کانال فشرده پیشرفت دیگری استفاده کنید، برای مثال channels.discord، channels.matrix، channels.msteams، channels.mattermost یا پیش‌نمایش‌های پیش‌نویس Slack. برای حالت پیش‌نویس پیشرفت، همین خط‌مشی را زیر streaming.progress قرار دهید:

{  "channels": {    "telegram": {      "streaming": {        "mode": "progress",        "progress": {          "toolProgress": true,          "commandText": "status"        }      }    }  }}

مرتبط

• بازآرایی چرخه عمر پیام - طراحی هدف مشترک برای پیش‌نمایش، ویرایش، استریم و نهایی‌سازی
• پیش‌نویس‌های پیشرفت - پیام‌های قابل‌مشاهده کار در حال انجام که در طول نوبت‌های طولانی به‌روزرسانی می‌شوند
• پیام‌ها - چرخه عمر و تحویل پیام
• تلاش مجدد - رفتار تلاش مجدد هنگام شکست تحویل
• کانال‌ها - پشتیبانی استریم برای هر کانال