WebChat

وضعیت: رابط گفت‌وگوی 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)

پیکربندی کامل: پیکربندی

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).
• gateway.remote.url، gateway.remote.token، gateway.remote.password: هدف gateway راه دور.
• session.*: ذخیره‌سازی نشست و پیش‌فرض‌های کلید اصلی.

مرتبط

• Control UI
• Dashboard