---
read_when:
    - تغییر نحوه نمایش خروجی دستیار در رابط کاربری کنترل
    - اشکال‌زدایی `[embed ...]`، رسانهٔ ساخت‌یافته، پاسخ، یا دستورالعمل‌های ارائهٔ صوتی
summary: پروتکل خروجی غنی برای رسانه‌های ساختاریافته، محتوای جاسازی‌شده، راهنمایی‌های صوتی و پاسخ‌ها
title: پروتکل خروجی غنی
x-i18n:
    generated_at: "2026-07-27T15:54:16Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: cbfe68f38c871f5f6d2811eb52b18d0143606f30283023ae96db64543eed95a1
    source_path: reference/rich-output-protocol.md
    workflow: 16
---

خروجی دستیار، دستورالعمل‌های تحویل/رندر را از طریق چند کانال اختصاصی منتقل می‌کند:

- فیلدهای ساختاریافتهٔ `mediaUrl` / `mediaUrls` برای تحویل پیوست.
- `[[audio_as_voice]]` برای راهنمایی‌های ارائهٔ صوتی.
- `[[reply_to_current]]` / `[[reply_to:<id>]]` برای فرادادهٔ پاسخ.
- `[embed ...]` برای رندر غنی در رابط کاربری کنترل.

فیلدهای ساختاریافتهٔ رسانه و برچسب‌های `[[...]]`، فرادادهٔ تحویل هستند. `[embed ...]` مسیر جداگانهٔ رندر غنی مختص وب است؛ این مسیر نام مستعار رسانه نیست.

## پیوست‌های رسانه‌ای

پیوست‌های راه‌دور باید نشانی‌های URL عمومی `https:` باشند. نام‌های میزبان `http:`، حلقهٔ بازگشتی، پیوند-محلی، خصوصی و داخلی به‌عنوان دستورالعمل پیوست رد می‌شوند؛ واکشی‌کننده‌های رسانه در سمت سرور، محافظ‌های شبکهٔ خود را نیز اعمال می‌کنند.

پیوست‌های محلی مسیرهای مطلق، مسیرهای نسبی به فضای کاری یا مسیرهای `~/` نسبی به پوشهٔ خانگی را می‌پذیرند. این مسیرها همچنان پیش از تحویل از سیاست خواندن فایل عامل و بررسی‌های نوع رسانه عبور می‌کنند.

<Warning>
برای پیوست‌ها از ابزارها، Pluginها، بلوک‌های جریانی، خروجی مرورگر یا کنش‌های پیام، فرمان متنی تولید نکنید. به‌جای آن از فیلدهای ساختاریافتهٔ رسانه استفاده کنید:

```json
{ "message": "تصویر شما اینجاست.", "mediaUrl": "/workspace/image.png" }
```

متن قدیمی پاسخ نهایی ممکن است همچنان برای سازگاری نرمال‌سازی شود، اما این یک پروتکل عمومی برای Plugin/ابزار نیست.
</Warning>

نحو سادهٔ تصویر در Markdown ‏(`![alt](url)`) به‌طور پیش‌فرض به‌صورت متن باقی می‌ماند. کانال‌هایی که می‌خواهند تصاویر Markdown به‌عنوان پاسخ رسانه‌ای در نظر گرفته شوند، این قابلیت را در آداپتور خروجی خود فعال می‌کنند؛ Telegram این کار را انجام می‌دهد، بنابراین `![alt](url)` به یک پیوست رسانه‌ای تبدیل می‌شود.

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

## `[embed ...]`

`[embed ...]` تنها نحو رندر غنی در معرض عامل برای رابط کاربری کنترل است. نمونهٔ خودبسته‌شونده:

```text
[embed ref="cv_123" title="Status" /]
```

قواعد:

- `[view ...]` دیگر برای خروجی جدید معتبر نیست.
- کدهای کوتاه جاسازی فقط در سطح پیام دستیار رندر می‌شوند.
- فقط جاسازی‌های مبتنی بر URL رندر می‌شوند؛ از `ref="..."` یا `url="..."` استفاده کنید.
- کدهای کوتاه جاسازی HTML درون‌خطی با قالب بلوکی رندر نمی‌شوند.
- رابط کاربری وب، کد کوتاه را از متن قابل‌مشاهده حذف می‌کند و محتوای جاسازی‌شده را به‌صورت درون‌خطی رندر می‌کند.

## ساختار رندر ذخیره‌شده

بلوک محتوای نرمال‌شده/ذخیره‌شدهٔ دستیار، یک مورد ساختاریافتهٔ `canvas` است:

```json
{
  "type": "canvas",
  "preview": {
    "kind": "canvas",
    "surface": "assistant_message",
    "render": "url",
    "viewId": "cv_123",
    "url": "/__openclaw__/canvas/documents/cv_123/index.html",
    "title": "وضعیت",
    "preferredHeight": 320
  }
}
```

`present_view` شناسایی نمی‌شود؛ بلوک‌های غنی ذخیره‌شده/رندرشده همیشه از این ساختار `canvas` استفاده می‌کنند.

## مرتبط

- [آداپتورهای RPC](/fa/reference/rpc)
- [Typebox](/fa/concepts/typebox)
