---
read_when:
    - اشکال‌زدایی یا پیکربندی دسترسی WebChat
summary: استفاده از میزبان ایستای WebChat local loopback و WS Gateway برای رابط کاربری چت
title: WebChat
x-i18n:
    generated_at: "2026-06-27T19:08:44Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 108dd98f975a2d2e980921bd0f486c3683c18ba6eb37111163af87929a9d7973
    source_path: web/webchat.md
    workflow: 16
---

وضعیت: رابط گفت‌وگوی SwiftUI در macOS/iOS مستقیماً با WebSocket مربوط به Gateway صحبت می‌کند.

## چیستی آن

- یک رابط گفت‌وگوی بومی برای gateway (بدون مرورگر تعبیه‌شده و بدون سرور استاتیک محلی).
- از همان نشست‌ها و قواعد مسیریابی کانال‌های دیگر استفاده می‌کند.
- مسیریابی قطعی: پاسخ‌ها همیشه به WebChat برمی‌گردند.

## شروع سریع

1. gateway را شروع کنید.
2. رابط WebChat (برنامه macOS/iOS) یا زبانه گفت‌وگوی Control UI را باز کنید.
3. مطمئن شوید یک مسیر معتبر احراز هویت gateway پیکربندی شده است (به‌صورت پیش‌فرض راز مشترک،
   حتی روی loopback).

## نحوه کارکرد (رفتار)

- رابط به WebSocket مربوط به Gateway وصل می‌شود و از `chat.history`، `chat.send` و `chat.inject` استفاده می‌کند.
- `chat.history` برای پایداری محدود است: Gateway ممکن است فیلدهای متنی بلند را کوتاه کند، فراداده سنگین را حذف کند و ورودی‌های بیش‌ازحد بزرگ را با `[chat.history omitted: message too large]` جایگزین کند.
- وقتی یک پیام قابل‌مشاهده دستیار در `chat.history` کوتاه شده باشد، Control UI می‌تواند یک خواننده جانبی باز کند و ورودی کاملِ نرمال‌سازی‌شده برای نمایش را در صورت نیاز از طریق `chat.message.get` دریافت کند، بدون اینکه payload پیش‌فرض تاریخچه را افزایش دهد.
- `chat.history` برای فایل‌های نشست append-only مدرن از شاخه فعال رونوشت پیروی می‌کند، بنابراین شاخه‌های بازنویسی رهاشده و نسخه‌های superseded prompt در WebChat رندر نمی‌شوند.
- ورودی‌های Compaction به‌صورت یک جداکننده صریح تاریخچه فشرده‌شده رندر می‌شوند. جداکننده توضیح می‌دهد که رونوشت فشرده‌شده به‌عنوان یک checkpoint حفظ شده است و به کنترل‌های checkpoint نشست‌ها پیوند می‌دهد؛ جایی که اپراتورها در صورت داشتن مجوز می‌توانند از آن نمای فشرده‌شده شاخه بسازند یا بازیابی کنند.
- Control UI مقدار `sessionId` پشتیبانِ Gateway را که توسط `chat.history` برگردانده شده به خاطر می‌سپارد و آن را در فراخوانی‌های بعدی `chat.send` می‌فرستد، بنابراین اتصال‌های مجدد و refresh صفحه همان گفت‌وگوی ذخیره‌شده را ادامه می‌دهند مگر اینکه کاربر یک نشست را شروع یا بازنشانی کند.
- Control UI ارسال‌های تکراری در حال اجرا را برای همان نشست، پیام و پیوست‌ها پیش از تولید یک شناسه اجرای جدید `chat.send` ادغام می‌کند؛ Gateway همچنان درخواست‌های تکراری را که از همان کلید idempotency دوباره استفاده می‌کنند dedupe می‌کند.
- فایل‌های شروع workspace و دستورالعمل‌های در انتظارِ `BOOTSTRAP.md` از طریق Project Context در system prompt عامل ارائه می‌شوند، نه اینکه در پیام کاربر WebChat کپی شوند. کوتاه‌سازی bootstrap فقط یک اعلان بازیابی مختصر در system-prompt اضافه می‌کند؛ شمارش‌های دقیق و knobهای پیکربندی روی سطوح تشخیصی باقی می‌مانند.
- `chat.history` همچنین برای نمایش نرمال‌سازی می‌شود: context فقط‌زمان‌اجرای OpenClaw،
  wrapperهای envelope ورودی، تگ‌های directive تحویل درون‌خطی
  مانند `[[reply_to_*]]` و `[[audio_as_voice]]`، payloadهای XML فراخوانی ابزار به‌صورت متن ساده
  (شامل `<tool_call>...</tool_call>`،
  `<function_call>...</function_call>`، `<tool_calls>...</tool_calls>`،
  `<function_calls>...</function_calls>` و بلوک‌های فراخوانی ابزار کوتاه‌شده)، و
  tokenهای کنترلی مدل ASCII/تمام‌عرضِ نشت‌کرده از متن قابل‌مشاهده حذف می‌شوند،
  و ورودی‌های دستیار که کل متن قابل‌مشاهده‌شان فقط token خاموش دقیق
  `NO_REPLY` / `no_reply` باشد حذف می‌شوند.
- payloadهای پاسخ دارای پرچم reasoning (`isReasoning: true`) از محتوای دستیار WebChat، متن بازپخش رونوشت و بلوک‌های محتوای صوتی حذف می‌شوند، بنابراین payloadهای فقط‌تفکر به‌صورت پیام قابل‌مشاهده دستیار یا صدای قابل‌پخش نمایش داده نمی‌شوند.
- `chat.inject` یک یادداشت دستیار را مستقیماً به رونوشت اضافه می‌کند و آن را به رابط پخش می‌کند (بدون اجرای عامل).
- اجراهای لغوشده می‌توانند خروجی جزئی دستیار را در رابط قابل‌مشاهده نگه دارند.
- Gateway وقتی خروجی bufferشده وجود داشته باشد، متن جزئی دستیارِ لغوشده را در تاریخچه رونوشت پایدار می‌کند و آن ورودی‌ها را با فراداده لغو علامت‌گذاری می‌کند.
- تاریخچه همیشه از gateway دریافت می‌شود (بدون پایش فایل محلی).
- اگر gateway در دسترس نباشد، WebChat فقط خواندنی است.

### مدل رونوشت و تحویل

WebChat دو مسیر داده جداگانه دارد:

- فایل JSONL نشست، رونوشت پایدار مدل/زمان اجرا است. برای اجراهای عادی عامل، runtime تعبیه‌شده OpenClaw پیام‌های قابل‌مشاهده برای مدلِ `user`، `assistant` و `toolResult` را از طریق مدیر نشست خود پایدار می‌کند. WebChat متن دلخواه تحویل، وضعیت یا helper را در آن رونوشت نمی‌نویسد.
- رویدادهای `ReplyPayload` در Gateway تصویر زنده تحویل هستند. آن‌ها می‌توانند برای نمایش WebChat/کانال، block streaming، تگ‌های directive، embedding رسانه، پرچم‌های TTS/صوت و رفتار fallback رابط نرمال‌سازی شوند. خودشان لاگ canonical نشست نیستند.
- harnessهایی که به پاسخ‌های قابل‌مشاهده از طریق `tools.message` نیاز دارند همچنان از WebChat به‌عنوان sink پاسخ داخلی اجرای جاری استفاده می‌کنند. یک `message.send` بدون هدف از آن اجرای فعال WebChat در همان گفت‌وگو projected می‌شود و در رونوشت نشست mirror می‌شود؛ WebChat به یک کانال خروجی قابل‌استفاده‌مجدد تبدیل نمی‌شود و هرگز `lastChannel` را به ارث نمی‌برد.
- WebChat فقط زمانی ورودی‌های رونوشت دستیار را inject می‌کند که Gateway مالک یک پیام نمایش‌داده‌شده بیرون از یک نوبت عادی عامل تعبیه‌شده باشد: `chat.inject`، پاسخ‌های فرمان غیرعامل، خروجی جزئی لغوشده و مکمل‌های رونوشت رسانه‌ای مدیریت‌شده توسط WebChat.
- `chat.history` رونوشت نشست ذخیره‌شده را می‌خواند و projection نمایش WebChat را اعمال می‌کند. اگر متن زنده دستیار هنگام یک اجرا ظاهر شود اما پس از بارگذاری دوباره تاریخچه ناپدید شود، ابتدا بررسی کنید که آیا JSONL خام شامل متن دستیار است، سپس اینکه آیا projection مربوط به `chat.history` آن را حذف کرده است، و سپس اینکه آیا merge خوش‌بینانه tail در Control UI وضعیت تحویل محلی را با snapshot پایدارشده جایگزین کرده است.
- `chat.message.get` از همان شاخه رونوشت و قواعد projection نمایشِ `chat.history` استفاده می‌کند، شامل scoping عامل فعال، اما یک ورودی رونوشت را با `messageId` هدف می‌گیرد و وقتی محتوای کامل دیگر قابل بازگرداندن نباشد یک دلیل unavailable صادقانه برمی‌گرداند.

پاسخ‌های نهایی اجرای عادی عامل باید پایدار باشند، زیرا runtime تعبیه‌شده `message_end` دستیار را می‌نویسد. هر fallback که یک payload نهایی تحویل‌داده‌شده را در رونوشت mirror می‌کند، ابتدا باید از تکرار یک نوبت دستیار که runtime تعبیه‌شده قبلاً نوشته است جلوگیری کند.

## پنل ابزارهای عوامل در Control UI

- پنل Tools در `/agents` متعلق به Control UI دو نمای جداگانه دارد:
  - **همین حالا در دسترس** از `tools.effective(sessionKey=...)` استفاده می‌کند و یک projection فقط‌خواندنی مشتق‌شده از سرور از موجودی نشست جاری را نشان می‌دهد، شامل ابزارهای core، plugin، متعلق به کانال،
    و ابزارهای MCP server که قبلاً کشف شده‌اند.
  - **پیکربندی ابزار** از `tools.catalog` استفاده می‌کند و بر پروفایل‌ها، overrideها و
    معناشناسی catalog متمرکز می‌ماند.
- دسترس‌پذیری زمان اجرا scoped به نشست است. جابه‌جایی نشست‌ها روی همان عامل می‌تواند فهرست
  **همین حالا در دسترس** را تغییر دهد. اگر MCP serverهای پیکربندی‌شده هنوز وصل نشده باشند یا
  از آخرین کشف تغییر کرده باشند، پنل به‌جای شروع بی‌صدای MCP transportها
  از مسیر خواندن، یک اعلان نشان می‌دهد.
- ویرایشگر پیکربندی به‌معنای دسترس‌پذیری زمان اجرا نیست؛ دسترسی مؤثر همچنان از ترتیب تقدم policy
  (`allow`/`deny`، overrideهای هر عامل و provider/channel) پیروی می‌کند.

## استفاده از راه دور

- حالت راه دور WebSocket مربوط به gateway را از طریق SSH/Tailscale tunnel می‌کند.
- نیازی نیست یک سرور WebChat جداگانه اجرا کنید.

## مرجع پیکربندی (WebChat)

پیکربندی کامل: [پیکربندی](/fa/gateway/configuration)

WebChat بخش پیکربندی پایدار ندارد. Gateway از حد نمایش داخلی `chat.history` استفاده می‌کند؛ کلاینت‌های API می‌توانند برای override کردن آن در یک فراخوانی منفرد `chat.history`، مقدار `maxChars` را برای هر درخواست بفرستند. پیکربندی legacy `channels.webchat` و `gateway.webchat` بازنشسته شده است؛ برای حذف آن `openclaw doctor --fix` را اجرا کنید.

گزینه‌های سراسری مرتبط:

- `gateway.port`، `gateway.bind`: میزبان/درگاه WebSocket.
- `gateway.auth.mode`، `gateway.auth.token`، `gateway.auth.password`:
  احراز هویت WebSocket با راز مشترک.
- `gateway.auth.allowTailscale`: زبانه گفت‌وگوی Control UI در مرورگر می‌تواند وقتی فعال باشد از headerهای هویت Tailscale
  Serve استفاده کند.
- `gateway.auth.mode: "trusted-proxy"`: احراز هویت reverse-proxy برای کلاینت‌های مرورگر پشت یک منبع proxy **غیر-loopback** آگاه از هویت (ببینید [احراز هویت Trusted Proxy](/fa/gateway/trusted-proxy-auth)).
- `gateway.remote.url`، `gateway.remote.token`، `gateway.remote.password`: هدف gateway راه دور.
- `session.*`: ذخیره‌سازی نشست و پیش‌فرض‌های کلید اصلی.

## مرتبط

- [Control UI](/fa/web/control-ui)
- [Dashboard](/fa/web/dashboard)