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

پیش‌نویس‌های پیشرفت، هنگام کار عامل یک پیام کانال را به خط وضعیت زنده تبدیل می‌کنند، نه انبوهی از پاسخ‌های موقت «هنوز در حال کار». با تنظیم channels.<channel>.streaming.mode: "progress"، OpenClaw پس از آغاز کار واقعی پیام را یک‌بار ایجاد می‌کند، هم‌زمان با خواندن، برنامه‌ریزی، فراخوانی ابزارها یا انتظار برای تأیید توسط عامل، آن را ویرایش می‌کند و سپس آن را به پاسخ نهایی تبدیل می‌کند.

در حال کار...📖 از docs/concepts/progress-drafts.md🔎 جست‌وجوی وب: برای "discord edit message"🛠️ Bash: اجرای آزمون‌ها

شروع سریع

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

پیش‌فرض‌ها از اینجا عبارت‌اند از: تأخیر آغاز 5 ثانیه‌ای، خطوط فشرده پیشرفت هنگام انجام کار مفید و جلوگیری از نمایش پیام‌های مستقل قدیمی‌تر پیشرفت برای آن نوبت. پیش‌نویس خطوط خام ابزار از یک برچسب تک‌واژه‌ای خودکار استفاده می‌کند؛ تیتر وضعیت این عنوان زائد را حذف می‌کند، مگر اینکه آن را صراحتاً پیکربندی کنید.

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

آنچه کاربران می‌بینند

برای پیشرفت خام ابزار، برچسب زمانی ظاهر می‌شود که عامل کار معناداری را آغاز کند و در طول تأخیر اولیه مشغول بماند. این برچسب در بالای فهرست جاری خطوط پیشرفت قرار می‌گیرد؛ بنابراین پس از ظاهرشدن تعداد کافی خطوط کار مشخص، از دید خارج می‌شود. تیتر وضعیت فقط وضعیت عامل را با زبان ساده نمایش می‌دهد، مگر اینکه برچسبی صراحتاً پیکربندی شده باشد. پاسخ‌های صرفاً متنی هرگز پیش‌نویس پیشرفت نشان نمی‌دهند؛ یک خط فقط برای به‌روزرسانی‌های واقعی کار ظاهر می‌شود، برای مثال 🛠️ Bash: run tests، 🔎 Web Search: for "discord edit message" یا ✍️ Write: to /tmp/file.

وقتی کانال بتواند با ایمنی این کار را انجام دهد، پاسخ نهایی در همان محل جایگزین پیش‌نویس می‌شود؛ در غیر این صورت OpenClaw پاسخ نهایی را از مسیر تحویل عادی ارسال می‌کند و پیش‌نویس را پاک می‌کند یا به‌روزرسانی آن را متوقف می‌کند (به نهایی‌سازی مراجعه کنید).

انتخاب حالت

channels.<channel>.streaming.mode رفتار قابل‌مشاهده حین پیشرفت را کنترل می‌کند:

وقتی «چه اتفاقی در حال رخ‌دادن است» برای کاربران مهم‌تر از مشاهده استریم توکن‌به‌توکن متن پاسخ است، progress را انتخاب کنید؛ وقتی خود متن پاسخ نشانه پیشرفت است، partial؛ و برای قطعه‌های بزرگ‌تر پیش‌نمایش، block. در Discord و Telegram، streaming.mode: "block" همچنان استریم پیش‌نمایش است، نه تحویل عادی پاسخ بلوکی — برای آن از streaming.block.enabled استفاده کنید.

پیکربندی برچسب‌ها

برچسب‌های پیشرفت زیر channels.<channel>.streaming.progress قرار دارند. برچسب پیش‌فرض خط خام ابزار "auto" است که از برچسب داخلی ساده Working استفاده می‌کند. تیتر وضعیت این برچسب ضمنی را پنهان می‌کند؛ اگر می‌خواهید بالای آن نیز برچسبی باشد، label: "auto" را صراحتاً تنظیم کنید:

در حال کار

استفاده از برچسب ثابت:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          label: "Investigating",        },      },    },  },}

استفاده از مجموعه برچسب‌های خودتان (هنگام label: "auto" همچنان به‌صورت تصادفی/بر اساس بذر انتخاب می‌شود):

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          label: "auto",          labels: ["Checking", "Reading", "Testing", "Finishing"],        },      },    },  },}

پنهان‌کردن برچسب و نمایش فقط خطوط پیشرفت:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          label: false,        },      },    },  },}

کنترل خطوط پیشرفت

خطوط پیشرفت از رویدادهای واقعی اجرا می‌آیند: آغاز ابزارها، به‌روزرسانی موارد، برنامه‌های وظیفه، تأییدها، خروجی فرمان، خلاصه وصله‌ها و فعالیت‌های مشابه عامل. این خطوط به‌طور پیش‌فرض فعال‌اند (progress.toolProgress، پیش‌فرض true).

ابزارها همچنین می‌توانند در حین اجرای یک فراخوانی واحد، پیشرفت نوع‌دار منتشر کنند. به این ترتیب یک واکشی یا جست‌وجوی کند، پیش از بازگرداندن نتیجه نهایی ابزار، پیش‌نویس قابل‌مشاهده را به‌روزرسانی می‌کند. به‌روزرسانی پیشرفت یک نتیجه جزئی ابزار با محتوای خالی مدل و فراداده صریح کانال عمومی است:

{  "content": [],  "progress": {    "text": "Fetching page content...",    "visibility": "channel",    "privacy": "public",    "id": "web_fetch:fetching"  }}

OpenClaw فقط progress.text را در رابط کاربری پیشرفت کانال رندر می‌کند. نتیجه عادی ابزار بعداً همچنان به‌صورت content/details می‌رسد و تنها بخشی است که به مدل بازگردانده می‌شود.

هنگام افزودن پیشرفت به یک ابزار، پیامی کوتاه و عمومی منتشر کنید و آن را تا زمانی به تأخیر بیندازید که عملیات به‌اندازه کافی در انتظار مانده باشد تا مفید واقع شود. web_fetch این کار را دقیقاً با تأخیر 5 ثانیه‌ای انجام می‌دهد:

const clearProgressTimer = scheduleToolProgress(  onUpdate,  { text: "Fetching page content...", id: "web_fetch:fetching" },  5_000,  { signal },); try {  return await runToolWork();} finally {  clearProgressTimer();}

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

حالت جزئیات

OpenClaw برای پیش‌نویس‌های پیشرفت و /verbose از یک قالب‌بند استفاده می‌کند:

{  agents: {    defaults: {      toolProgressDetail: "explain", // explain | raw    },  },}

"explain" پیش‌فرض است و با برچسب‌های مختصر، پیش‌نویس‌ها را پایدار نگه می‌دارد. "raw" در صورت وجود، فرمان زیربنایی را اضافه می‌کند که هنگام اشکال‌زدایی مفید است، اما در گفت‌وگو شلوغ‌تر خواهد بود. برای مثال، فراخوانی node --check /tmp/app.js بر اساس حالت به‌شکل متفاوتی رندر می‌شود:

متن فرمان/اجرا

streaming.progress.commandText (پیش‌فرض "raw") مستقل از حالت جزئیات بالا، میزان جزئیات فرمان نمایش‌داده‌شده کنار خطوط پیشرفت exec/bash را کنترل می‌کند. برای حفظ خط پیشرفت ابزار و در عین حال پنهان‌کردن کامل متن فرمان، آن را روی "status" تنظیم کنید:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          commandText: "status",        },      },    },  },}

مسیر توضیحات

streaming.progress.commentary (پیش‌فرض false) روایت توضیحی/مقدمه پیش از ابزار مدل (💬، برای مثال «بررسی می‌کنم... سپس ...») را با خطوط ابزار در پیش‌نویس درهم می‌آمیزد. برای شکل پیکربندی مشترک بین کانال‌ها، به استریم و قطعه‌بندی مراجعه کنید.

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

تیتر وضعیت

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

در Discord، وقتی یک مدل کمکی برای عامل تعیین شود — یک utilityModel صریح، یا پیش‌فرض مدل کوچک اعلام‌شده ارائه‌دهنده اصلی (OpenAI → gpt-5.6-luna، Anthropic → claude-haiku-4-5) — اگر مدل مقدمه‌ای منتشر نکند یا حدود 20 ثانیه ساکت مانده باشد، متنی پرکننده، کوتاه و ساده ارائه می‌کند (تیتر Telegram در حال حاضر فقط از مقدمه استفاده می‌کند):

در حال به‌روزرسانی مدل پیش‌فرض در پیکربندی شما و سپس راه‌اندازی مجدد Gatewayبرای اعمال آن هستم. یک فراخوانی فهرست عامل ناموفق بود و دوباره امتحان می‌شود.

روایت کمکی به‌طور پیش‌فرض فعال است (streaming.progress.narration، پیش‌فرض true) و هرگز به مدل اصلی برنمی‌گردد: فقط با یک utilityModel صریح یا پیش‌فرض اعلام‌شده ارائه‌دهنده برای ارائه‌دهنده اصلی عامل اجرا می‌شود. برای غیرفعال‌کردن کامل مسیریابی کمکی، utilityModel: "" را تنظیم کنید. خطوط ابزار در زیر آن به انباشته‌شدن ادامه می‌دهند و اگر هر دو منبع وضعیت متوقف شوند، بازمی‌گردند. ویرایش‌های پیش‌نویس همچنان منتظر دروازه عادی فعالیت و یک تغییر واقعی متن می‌مانند؛ این کار از چشمک‌زدن در نوبت‌های سریع جلوگیری می‌کند و تکرار ویرایش را در کانال‌های شلوغ کاهش می‌دهد. برای غیرفعال‌کردن فقط متن پرکننده مدل کمکی، narration: false را تنظیم کنید؛ تیترهای مقدمه مدل همچنان فعال می‌مانند:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          narration: false,        },      },    },  },}

ورودی روایت محدود و ویرایش‌شده است: مدل کمکی، متن درخواست ورودی به‌همراه همان خلاصه‌های فشرده و ویرایش‌شده ابزار را دریافت می‌کند که پیش‌نویس رندر می‌کند — هرگز خروجی خام فرمان یا نتایج ابزار را دریافت نمی‌کند. با commandText: "status"، ورودی روایت همچنین متن فرمان exec/bash را حذف می‌کند، مطابق با آنچه پیش‌نویس نشان می‌دهد.

محدودیت خطوط

تعداد خطوطی را که قابل‌مشاهده می‌مانند محدود کنید (پیش‌فرض 8):

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          maxLines: 4,        },      },    },  },}

خطوط پیشرفت به‌طور خودکار فشرده می‌شوند تا هنگام ویرایش پیش‌نویس، بازچینی حباب گفت‌وگو کاهش یابد، و OpenClaw خطوط بلند را کوتاه می‌کند تا ویرایش‌های مکرر پیش‌نویس در هر به‌روزرسانی به‌شکل متفاوتی شکسته نشوند. بودجه پیش‌فرض هر خط 120 نویسه است؛ نثر در مرز واژه بریده می‌شود، در حالی که جزئیات بلند مانند مسیرها یا فرمان‌های خام با سه‌نقطه میانی کوتاه می‌شوند تا پسوند قابل‌مشاهده بماند.

تنظیم بودجه هر خط:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          maxLineChars: 160,        },      },    },  },}

رندر غنی (Slack)

Slack می‌تواند خطوط پیشرفت را به‌جای متن ساده، به‌صورت فیلدهای ساختاریافته Block Kit رندر کند:

{  channels: {    slack: {      streaming: {        mode: "progress",        progress: {          render: "rich",        },      },    },  },}

رندر غنی همیشه همان بدنه متن ساده را در کنار فیلدهای Block Kit ارسال می‌کند؛ بنابراین کلاینت‌هایی که نمی‌توانند شکل غنی‌تر را رندر کنند، همچنان متن فشرده پیشرفت را نمایش می‌دهند.

پنهان‌کردن خطوط ابزار/وظیفه

پیش‌نویس پیشرفت واحد را حفظ کنید، اما خطوط ابزار و وظیفه را پنهان کنید:

{  channels: {    discord: {      streaming: {        mode: "progress",        progress: {          toolProgress: false,        },      },    },  },}

با toolProgress: false، OpenClaw همچنان پیام‌های مستقل قدیمی‌ترِ پیشرفت ابزار را برای آن نوبت سرکوب می‌کند — کانال تا زمان پاسخ نهایی از نظر بصری ساکت می‌ماند، به‌جز برچسب، در صورتی که پیکربندی شده باشد.

رفتار کانال

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

نهایی‌سازی

وقتی پاسخ نهایی آماده باشد، OpenClaw تلاش می‌کند چت را مرتب نگه دارد:

• در حالت progress در Discord، پاسخ نهایی به‌صورت یک پیام جدید ارسال می‌شود و یک رسید فعالیت کوچک -# به آن افزوده می‌شود (برای مثال -# 🧠 2 thoughts · 🛠️ 5 tool calls · ⏱️ 12s)؛ پس از تحویل آن پاسخ، پیش‌نویس وضعیت حذف می‌شود. در کانال‌های شلوغ، هیچ گزارش ابزار یتیمی بالای پاسخ باقی نمی‌ماند؛ در پاسخ‌های نهایی خطادار، پیش‌نویس به‌عنوان سابقه قابل‌مشاهده نوبت ناموفق حفظ می‌شود.
• اگر پیش‌نویس بتواند با ایمنی به پاسخ نهایی تبدیل شود (حالت‌های partial/block)، OpenClaw آن را در جای خود ویرایش می‌کند.
• اگر کانال از استریمینگ بومی پیشرفت استفاده کند، OpenClaw هنگامی که انتقال بومی متن نهایی را بپذیرد، آن استریم را نهایی می‌کند.
• در غیر این صورت (رسانه، درخواست تأیید، مقصد پاسخ صریح، تعداد بیش‌ازحد قطعه‌ها، یا ویرایش/ارسال ناموفق)، OpenClaw پاسخ نهایی را به‌جای بازنویسی پیش‌نویس، از مسیر عادی تحویل کانال ارسال می‌کند.

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

عیب‌یابی

فقط پاسخ نهایی را می‌بینم.

بررسی کنید که channels.<channel>.streaming.mode برای حساب یا کانالی که پیام را پردازش کرده است، progress باشد. برخی مسیرهای گروهی یا پاسخ به نقل‌قول، هنگامی که کانال نتواند پیام درست را با ایمنی ویرایش کند، پیش‌نمایش پیش‌نویس را برای یک نوبت غیرفعال می‌کنند.

برچسب را می‌بینم، اما خطوط ابزار را نمی‌بینم.

streaming.progress.toolProgress را بررسی کنید. اگر مقدار آن false باشد، OpenClaw رفتار تک‌پیش‌نویسی را حفظ می‌کند، اما خطوط پیشرفت ابزار و وظیفه را پنهان می‌کند.

به‌جای پیش‌نویس ویرایش‌شده، یک پیام نهایی جدید می‌بینم.

این همان بازگشت ایمنی توصیف‌شده در نهایی‌سازی است. این وضعیت ممکن است برای پاسخ‌های رسانه‌ای، پاسخ‌های طولانی، مقصدهای پاسخ صریح، پیش‌نویس‌های قدیمی Telegram، نبود مقصد رشته Slack، پیام‌های پیش‌نمایش حذف‌شده، یا نهایی‌سازی ناموفق استریم بومی رخ دهد.

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

هرگاه پیش‌نویسی فعال باشد، حالت پیشرفت پیام‌های مستقل پیش‌فرضِ پیشرفت ابزار را سرکوب می‌کند. اگر پیام‌های مستقل همچنان ظاهر می‌شوند، تأیید کنید که نوبت واقعاً از حالت progress استفاده می‌کند، نه streaming.mode: "off" یا مسیر کانالی که نمی‌تواند برای آن پیام پیش‌نویس ایجاد کند.

رفتار Teams با Discord یا Telegram متفاوت است.

Microsoft Teams در چت‌های شخصی، به‌جای انتقال عمومی پیش‌نمایشِ ارسال و ویرایش، از یک استریم بومی استفاده می‌کند و streaming.mode: "block" را به تحویل بلوکی Teams نگاشت می‌کند، زیرا مانند Discord و Telegram حالت بلوکی پیش‌نمایش پیش‌نویس ندارد.

مرتبط

• استریمینگ و قطعه‌بندی
• پیام‌ها
• پیکربندی کانال
• Discord
• Matrix
• Microsoft Teams
• Slack
• Telegram
• Mattermost