---
read_when:
    - پیکربندی به‌روزرسانی‌های قابل‌مشاهدهٔ پیشرفت برای نوبت‌های گفت‌وگوی طولانی‌مدت
    - انتخاب بین حالت‌های پخش جریانی جزئی، بلوکی و پیشرفت
    - توضیح اینکه OpenClaw چگونه در حالی که کار در حال انجام است یک پیام کانال را به‌روزرسانی می‌کند
    - عیب‌یابی پیش‌نویس‌های پیشرفت، پیام‌های پیشرفت مستقل، یا fallback نهایی‌سازی
summary: 'پیش‌نویس‌های پیشرفت: یک پیام قابل‌مشاهدهٔ کارِ در حال انجام که هنگام اجرای عامل به‌روزرسانی می‌شود'
title: پیش‌نویس‌های پیشرفت
x-i18n:
    generated_at: "2026-06-27T17:36:42Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 7cc005ed39c2a4a6d887748c769c9d2bb9c133aeeda87b2c11bfe5360f364fdd
    source_path: concepts/progress-drafts.md
    workflow: 16
---

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

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

```text
Shelling...
📖 from docs/concepts/progress-drafts.md
🔎 Web Search: for "discord edit message"
🛠️ Bash: run tests
```

از پیش‌نویس‌های پیشرفت زمانی استفاده کنید که در کارهای سنگینِ ابزارمحور یک پیام وضعیت مرتب
و پس از پایان نوبت پاسخ نهایی را می‌خواهید.

## شروع سریع

پیش‌نویس‌های پیشرفت را برای هر کانال با `streaming.mode: "progress"` فعال کنید:

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

معمولاً همین کافی است. OpenClaw یک برچسب خودکار تک‌کلمه‌ای انتخاب می‌کند، صبر می‌کند
تا کار دست‌کم پنج ثانیه طول بکشد یا یک رویداد کاری دوم منتشر کند، در هنگام انجام کار مفید
خطوط پیشرفت فشرده اضافه می‌کند، و گفت‌وگوی پیشرفت مستقلِ تکراری را برای آن نوبت سرکوب می‌کند.

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

یک پیش‌نویس پیشرفت دو بخش دارد:

| بخش           | هدف                                                                               |
| -------------- | ------------------------------------------------------------------------------------- |
| برچسب          | یک خط شروع/وضعیت کوتاه مانند `Working` یا `Shelling`.                          |
| خطوط پیشرفت | به‌روزرسانی‌های اجرای فشرده با همان نمادهای ابزار و قالب‌بند جزئیاتِ خروجی پرجزئیات. |

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

## انتخاب یک حالت

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

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

وقتی کاربران بیشتر به «چه اتفاقی در حال رخ دادن است» اهمیت می‌دهند تا تماشای جریان متن پاسخ به‌صورت توکن‌به‌توکن، `progress` را انتخاب کنید.

وقتی خود پاسخ سیگنال پیشرفت است، `partial` را انتخاب کنید.

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

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

برچسب‌های پیشرفت زیر `channels.<channel>.streaming.progress` قرار دارند.

برچسب پیش‌فرض `auto` است که از مجموعهٔ برچسب‌های تک‌کلمه‌ای داخلی OpenClaw انتخاب می‌کند:

```text
Working
Shelling
Scuttling
Clawing
Pinching
Molting
Bubbling
Tiding
Reefing
Cracking
Sifting
Brining
Nautiling
Krilling
Barnacling
Lobstering
Tidepooling
Pearling
Snapping
Surfacing
```

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

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

از مجموعهٔ برچسب خودکار خودتان استفاده کنید:

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

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

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

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

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

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

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

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

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

```typescript
const clearProgressTimer = scheduleToolProgress(
  onUpdate,
  { text: "Fetching page content...", id: "web_fetch:fetching" },
  5_000,
  { signal },
);

try {
  return await runToolWork();
} finally {
  clearProgressTimer();
}
```

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

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

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

`"explain"` پیش‌فرض است و پیش‌نویس‌ها را با برچسب‌های کوتاهی مانند
`🛠️ check JS syntax for /tmp/app.js` پایدار نگه می‌دارد. `"raw"` در صورت موجود بودن
فرمان/جزئیات زیرین را پیوست می‌کند، که هنگام اشکال‌زدایی مفید است اما در چت شلوغ‌تر است.

برای مثال، همان فرمان بسته به حالت جزئیات متفاوت ظاهر می‌شود:

| حالت      | خط پیشرفت                                                  |
| --------- | -------------------------------------------------------------- |
| `explain` | `🛠️ check JS syntax for /tmp/app.js`                           |
| `raw`     | `🛠️ check JS syntax for /tmp/app.js, node --check /tmp/app.js` |

تعداد خطوطی را که قابل مشاهده می‌مانند محدود کنید:

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

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

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

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

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

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

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

رندر غنی همان جایگزین متن ساده را حفظ می‌کند تا کانال‌ها و کلاینت‌هایی که
از شکل غنی‌تر پشتیبانی نمی‌کنند همچنان بتوانند متن پیشرفت فشرده را نشان دهند.

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

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

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

## رفتار کانال

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

| کانال         | انتقال پیشرفت                     | یادداشت‌ها                                                                 |
| --------------- | -------------------------------------- | --------------------------------------------------------------------- |
| Discord         | یک پیام بفرست، سپس آن را ویرایش کن.        | متن نهایی وقتی در یک پیام پیش‌نمایش امن جا شود درجا ویرایش می‌شود.      |
| Matrix          | یک رویداد بفرست، سپس آن را ویرایش کن.          | پیکربندی جریان‌دهی در سطح حساب، پیش‌نویس‌های سطح حساب را کنترل می‌کند.         |
| Microsoft Teams | جریان بومی Teams در چت‌های شخصی. | `streaming.mode: "block"` به تحویل بلوکی Teams نگاشت می‌شود.               |
| Slack           | جریان بومی یا پست پیش‌نویس قابل ویرایش.  | در دسترس بودن رشته روی امکان استفاده از جریان‌دهی بومی اثر می‌گذارد.     |
| Telegram        | یک پیام بفرست، سپس آن را ویرایش کن.        | پیش‌نویس‌های قابل مشاهدهٔ قدیمی‌تر ممکن است جایگزین شوند تا مهرهای زمانی نهایی مفید بمانند. |
| Mattermost      | پست پیش‌نویس قابل ویرایش.                   | فعالیت ابزار در همان پست به سبک پیش‌نویس ادغام می‌شود.               |

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

## نهایی‌سازی

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

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

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

## عیب‌یابی

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

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

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

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

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

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

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

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

**Teams رفتاری متفاوت از Discord یا Telegram دارد.**

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

## مرتبط

- [جریان‌دهی و قطعه‌بندی](/fa/concepts/streaming)
- [پیام‌ها](/fa/concepts/messages)
- [پیکربندی کانال](/fa/gateway/config-channels)
- [Discord](/fa/channels/discord)
- [Matrix](/fa/channels/matrix)
- [Microsoft Teams](/fa/channels/msteams)
- [Slack](/fa/channels/slack)
- [Telegram](/fa/channels/telegram)