رابط کاربری کنترل

• گفت‌وگو با مدل از طریق Gateway WS (chat.history, chat.send, chat.abort, chat.inject).
• بازخوانی‌های تاریخچه گفت‌وگو یک پنجره اخیر محدود با سقف متن به‌ازای هر پیام درخواست می‌کنند تا نشست‌های بزرگ پیش از قابل‌استفاده شدن گفت‌وگو مرورگر را مجبور به رندر کردن کل بار رونوشت نکنند.
• صحبت از طریق نشست‌های بلادرنگ مرورگر. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن مرورگر یک‌بارمصرف محدود روی WebSocket استفاده می‌کند، و pluginهای صدای بلادرنگ فقط-بک‌اند از ترابری رله Gateway استفاده می‌کنند. نشست‌های ارائه‌دهنده تحت مالکیت کلاینت با talk.client.create شروع می‌شوند؛ نشست‌های رله Gateway با talk.session.create شروع می‌شوند. رله اعتبارنامه‌های ارائه‌دهنده را روی Gateway نگه می‌دارد در حالی که مرورگر PCM میکروفون را از طریق talk.session.appendAudio استریم می‌کند و فراخوانی‌های ابزار ارائه‌دهنده openclaw_agent_consult را از طریق talk.client.toolCall برای سیاست Gateway و مدل OpenClaw بزرگ‌ترِ پیکربندی‌شده ارسال می‌کند.
• استریم فراخوانی‌های ابزار + کارت‌های خروجی زنده ابزار در Chat (رویدادهای عامل).

• کانال‌ها: وضعیت کانال‌های داخلی به‌علاوه کانال‌های plugin بسته‌بندی‌شده/خارجی، ورود QR، و پیکربندی به‌ازای هر کانال (channels.status, web.login.*, config.patch).
• بازخوانی‌های کاوش کانال، snapshot قبلی را تا پایان بررسی‌های کند ارائه‌دهنده قابل مشاهده نگه می‌دارند، و وقتی یک کاوش یا ممیزی از بودجه UI خود فراتر برود، snapshotهای جزئی برچسب‌گذاری می‌شوند.
• نمونه‌ها: فهرست حضور + بازخوانی (system-presence).
• نشست‌ها: به‌طور پیش‌فرض نشست‌های عامل پیکربندی‌شده را فهرست می‌کند، از کلیدهای نشست عامل پیکربندی‌نشده کهنه fallback می‌کند، و بازنویسی‌های مدل/تفکر/سریع/پرگو/ردیابی/استدلال را به‌ازای هر نشست اعمال می‌کند (sessions.list, sessions.patch).
• رؤیاها: وضعیت Dreaming، کلید فعال/غیرفعال، و خواننده Dream Diary (doctor.memory.status, doctor.memory.dreamDiary, config.patch).

• کارهای Cron: فهرست/افزودن/ویرایش/اجرا/فعال‌سازی/غیرفعال‌سازی + تاریخچه اجرا (cron.*).
• Skills: وضعیت، فعال/غیرفعال، نصب، به‌روزرسانی‌های کلید API (skills.*).
• گره‌ها: فهرست + قابلیت‌ها (node.list).
• تأییدیه‌های اجرا: ویرایش allowlistهای Gateway یا گره + سیاست پرسش برای exec host=gateway/node (exec.approvals.*).

• مشاهده/ویرایش ~/.openclaw/openclaw.json (config.get, config.set).
• اعمال + راه‌اندازی دوباره با اعتبارسنجی (config.apply) و بیدار کردن آخرین نشست فعال.
• نوشتن‌ها شامل یک محافظ هش پایه هستند تا از بازنویسی و از بین بردن ویرایش‌های هم‌زمان جلوگیری شود.
• نوشتن‌ها (config.set/config.apply/config.patch) پیش از اجرا، حل SecretRef فعال را برای ارجاع‌های موجود در بار پیکربندی ارسالی بررسی می‌کنند؛ ارجاع‌های ارسالی فعالِ حل‌نشده پیش از نوشتن رد می‌شوند.
• رندر schema + فرم (config.schema / config.schema.lookup، شامل title / description فیلد، راهنماهای UI منطبق، خلاصه‌های فرزند بلافاصله، فراداده مستندات روی گره‌های آبجکت/ wildcard / آرایه / ترکیب تودرتو، به‌علاوه schemaهای plugin + کانال وقتی در دسترس باشند)؛ ویرایشگر JSON خام فقط وقتی snapshot رفت‌وبرگشت خام امنی داشته باشد در دسترس است.
• اگر یک snapshot نتواند متن خام را با ایمنی رفت‌وبرگشت کند، رابط کاربری Control حالت Form را اجباری می‌کند و حالت Raw را برای آن snapshot غیرفعال می‌سازد.
• گزینه "Reset to saved" در ویرایشگر JSON خام، به‌جای رندر دوباره یک snapshot تخت‌شده، شکل خام‌نوشته‌شده را حفظ می‌کند (قالب‌بندی، نظرها، چینش $include)؛ بنابراین وقتی snapshot بتواند با ایمنی رفت‌وبرگشت کند، ویرایش‌های خارجی از بازنشانی جان سالم به‌در می‌برند.
• مقادیر آبجکت SecretRef ساختاریافته در ورودی‌های متنی فرم به‌صورت فقط‌خواندنی رندر می‌شوند تا از خراب شدن تصادفی آبجکت به رشته جلوگیری شود.

• اشکال‌زدایی: snapshotهای وضعیت/سلامت/مدل‌ها + گزارش رویداد + فراخوانی‌های دستی RPC (status, health, models.list).
• گزارش رویداد شامل زمان‌بندی‌های بازخوانی/RPC رابط کاربری Control، زمان‌بندی‌های رندر کند گفت‌وگو/پیکربندی، و ورودی‌های پاسخ‌گویی مرورگر برای فریم‌های انیمیشن طولانی یا taskهای طولانی است، وقتی مرورگر آن نوع ورودی‌های PerformanceObserver را ارائه کند.
• گزارش‌ها: tail زنده گزارش‌های فایل Gateway با فیلتر/خروجی گرفتن (logs.tail).
• به‌روزرسانی: اجرای به‌روزرسانی بسته/git + راه‌اندازی دوباره (update.run) با گزارش راه‌اندازی دوباره، سپس نظرسنجی update.status پس از اتصال دوباره برای تأیید نسخه Gateway در حال اجرا.

• برای کارهای ایزوله، پیش‌فرض تحویل روی اعلام خلاصه است. اگر اجرای فقط داخلی می‌خواهید، می‌توانید آن را به none تغییر دهید.
• وقتی announce انتخاب شده باشد، فیلدهای کانال/هدف ظاهر می‌شوند.
• حالت Webhook از delivery.mode = "webhook" با delivery.to تنظیم‌شده روی یک URL معتبر Webhook از نوع HTTP(S) استفاده می‌کند.
• برای کارهای نشست اصلی، حالت‌های تحویل webhook و none در دسترس هستند.
• کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی عامل، گزینه‌های cron دقیق/پراکنده، بازنویسی‌های مدل/تفکر عامل، و کلیدهای تحویل best-effort هستند.
• اعتبارسنجی فرم به‌صورت درون‌خطی با خطاهای سطح فیلد است؛ مقادیر نامعتبر دکمه ذخیره را تا زمان اصلاح غیرفعال می‌کنند.
• برای ارسال یک توکن bearer اختصاصی، cron.webhookToken را تنظیم کنید؛ اگر حذف شود، webhook بدون هدر احراز هویت ارسال می‌شود.
• fallback منسوخ: کارهای قدیمی ذخیره‌شده با notify: true همچنان می‌توانند تا زمان مهاجرت از cron.webhook استفاده کنند.

• chat.send غیرمسدودکننده است: بلافاصله با { runId, status: "started" } تأیید می‌کند و پاسخ از طریق رویدادهای chat جریان می‌یابد.
• بارگذاری‌های چت تصویرها به‌علاوه فایل‌های غیر ویدیویی را می‌پذیرند. تصویرها مسیر تصویر بومی را نگه می‌دارند؛ فایل‌های دیگر به‌عنوان رسانه مدیریت‌شده ذخیره می‌شوند و در تاریخچه به‌صورت پیوندهای پیوست نمایش داده می‌شوند.
• ارسال دوباره با همان idempotencyKey هنگام اجرا { status: "in_flight" } و پس از تکمیل { status: "ok" } را برمی‌گرداند.
• پاسخ‌های chat.history برای ایمنی UI از نظر اندازه محدود می‌شوند. وقتی ورودی‌های رونوشت بیش از حد بزرگ باشند، Gateway ممکن است فیلدهای متنی طولانی را کوتاه کند، بلوک‌های فراداده سنگین را حذف کند، و پیام‌های بیش‌ازحد بزرگ را با یک جانگهدار ([chat.history omitted: message too large]) جایگزین کند.
• تصویرهای دستیار/تولیدشده به‌عنوان ارجاع‌های رسانه مدیریت‌شده پایدار می‌شوند و از طریق URLهای رسانه احرازهویت‌شده Gateway دوباره ارائه می‌شوند، بنابراین بارگذاری‌های مجدد به باقی‌ماندن payloadهای تصویر base64 خام در پاسخ تاریخچه چت وابسته نیستند.
• هنگام رندر کردن chat.history، UI کنترل برچسب‌های دستور درون‌خطی صرفاً نمایشی را از متن قابل‌مشاهده دستیار حذف می‌کند (برای مثال [[reply_to_*]] و [[audio_as_voice]])، payloadهای XML فراخوانی ابزار در متن ساده (از جمله <tool_call>...</tool_call>، <function_call>...</function_call>، <tool_calls>...</tool_calls>، <function_calls>...</function_calls>، و بلوک‌های کوتاه‌شده فراخوانی ابزار)، و توکن‌های کنترل مدل ASCII/تمام‌عرض نشت‌کرده را حذف می‌کند، و ورودی‌های دستیار را که کل متن قابل‌مشاهده‌شان فقط توکن خاموش دقیق NO_REPLY / no_reply یا توکن تأیید Heartbeat یعنی HEARTBEAT_OK است حذف می‌کند.
• در طول یک ارسال فعال و تازه‌سازی نهایی تاریخچه، نمای چت پیام‌های خوش‌بینانه محلی کاربر/دستیار را قابل‌مشاهده نگه می‌دارد اگر chat.history برای مدتی کوتاه یک snapshot قدیمی‌تر برگرداند؛ رونوشت مرجع پس از آنکه تاریخچه Gateway به‌روز شد، آن پیام‌های محلی را جایگزین می‌کند.
• رویدادهای زنده chat وضعیت تحویل هستند، درحالی‌که chat.history از رونوشت ماندگار نشست بازسازی می‌شود. پس از رویدادهای نهایی ابزار، UI کنترل تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنباله خوش‌بینانه کوچک را ادغام می‌کند؛ مرز رونوشت در WebChat مستند شده است.
• chat.inject یک یادداشت دستیار را به رونوشت نشست اضافه می‌کند و یک رویداد chat را برای به‌روزرسانی‌های صرفاً UI پخش می‌کند (بدون اجرای عامل، بدون تحویل کانال).
• سربرگ چت فیلتر عامل را پیش از انتخابگر نشست نشان می‌دهد، و انتخابگر نشست بر اساس عامل انتخاب‌شده محدود می‌شود. تغییر عامل‌ها فقط نشست‌های وابسته به آن عامل را نشان می‌دهد و وقتی هنوز هیچ نشست داشبورد ذخیره‌شده‌ای ندارد، به نشست اصلی آن عامل برمی‌گردد.
• در عرض‌های دسکتاپ، کنترل‌های چت در یک ردیف فشرده می‌مانند و هنگام پیمایش به پایین رونوشت جمع می‌شوند؛ پیمایش به بالا، بازگشت به بالای صفحه، یا رسیدن به پایین، کنترل‌ها را بازیابی می‌کند.
• پیام‌های متنی تکراری پیاپی به‌صورت یک حباب با نشان شمارش رندر می‌شوند. پیام‌هایی که تصویر، پیوست، خروجی ابزار، یا پیش‌نمایش canvas دارند جمع نمی‌شوند.
• انتخابگرهای مدل و تفکر در سربرگ چت نشست فعال را بلافاصله از طریق sessions.patch وصله می‌کنند؛ آن‌ها overrideهای پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت.
• اگر هنگام ذخیره شدن تغییر انتخابگر مدل برای همان نشست پیامی بفرستید، composer پیش از فراخوانی chat.send منتظر وصله آن نشست می‌ماند تا ارسال از مدل انتخاب‌شده استفاده کند.
• تایپ کردن /new در UI کنترل همان نشست تازه داشبورد New Chat را ایجاد می‌کند و به آن جابه‌جا می‌شود، مگر وقتی session.dmScope: "main" پیکربندی شده باشد و والد فعلی نشست اصلی عامل باشد؛ در آن حالت، نشست اصلی را درجا بازنشانی می‌کند. تایپ کردن /reset بازنشانی درجای صریح Gateway را برای نشست فعلی نگه می‌دارد.
• انتخابگر مدل چت نمای مدل پیکربندی‌شده Gateway را درخواست می‌کند. اگر agents.defaults.models موجود باشد، آن فهرست مجاز انتخابگر را هدایت می‌کند، از جمله ورودی‌های provider/* که کاتالوگ‌های محدود به provider را پویا نگه می‌دارند. در غیر این صورت انتخابگر ورودی‌های صریح models.providers.*.models به‌علاوه providerهایی با احراز هویت قابل‌استفاده را نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی models.list با view: "all" همچنان در دسترس است.
• وقتی گزارش‌های تازه مصرف نشست Gateway شامل توکن‌های زمینه فعلی باشند، ناحیه composer چت یک نشانگر فشرده مصرف زمینه را نشان می‌دهد. در فشار بالای زمینه به سبک هشدار تغییر می‌کند و، در سطوح پیشنهادی Compaction، یک دکمه فشرده نشان می‌دهد که مسیر عادی Compaction نشست را اجرا می‌کند. snapshotهای قدیمی توکن پنهان می‌شوند تا زمانی که Gateway دوباره مصرف تازه را گزارش کند.

حالت گفت‌وگو از یک provider صدای بی‌درنگ ثبت‌شده استفاده می‌کند. OpenAI را با talk.realtime.provider: "openai" به‌علاوه یکی از talk.realtime.providers.openai.apiKey، OPENAI_API_KEY، یا پروفایل OAuth openai-codex پیکربندی کنید؛ Google را با talk.realtime.provider: "google" به‌علاوه talk.realtime.providers.google.apiKey پیکربندی کنید. مرورگر هرگز یک کلید API استاندارد provider دریافت نمی‌کند. OpenAI یک secret موقت کلاینت Realtime برای WebRTC دریافت می‌کند. Google Live یک توکن احراز هویت Live API محدود و یک‌بارمصرف برای یک نشست WebSocket مرورگر دریافت می‌کند، همراه با دستورالعمل‌ها و اعلان‌های ابزار که توسط Gateway در توکن قفل شده‌اند. providerهایی که فقط یک پل بی‌درنگ backend ارائه می‌کنند از مسیر انتقال relay Gateway عبور می‌کنند، بنابراین credentials و socketهای فروشنده در سمت سرور می‌مانند، درحالی‌که صدای مرورگر از طریق RPCهای احرازهویت‌شده Gateway جابه‌جا می‌شود. پرامپت نشست Realtime توسط Gateway ساخته می‌شود؛ talk.client.create overrideهای دستورالعمل ارائه‌شده از سوی فراخواننده را نمی‌پذیرد.

composer چت یک دکمه گزینه‌های گفت‌وگو کنار دکمه شروع/توقف گفت‌وگو دارد. گزینه‌ها روی نشست گفت‌وگوی بعدی اعمال می‌شوند و می‌توانند provider، انتقال، مدل، صدا، میزان تلاش استدلال، آستانه VAD، مدت سکوت، و padding پیشوند را override کنند. وقتی گزینه‌ای خالی باشد، Gateway در صورت وجود از پیش‌فرض‌های پیکربندی‌شده یا از پیش‌فرض provider استفاده می‌کند. انتخاب relay Gateway مسیر relay backend را اجباری می‌کند؛ انتخاب WebRTC نشست را در مالکیت کلاینت نگه می‌دارد و اگر provider نتواند نشست مرورگر بسازد، به‌جای fallback خاموش به relay، شکست می‌خورد.

در composer چت، کنترل گفت‌وگو دکمه موج‌ها کنار دکمه دیکته میکروفون است. وقتی گفت‌وگو شروع می‌شود، ردیف وضعیت composer ابتدا Connecting Talk...، سپس هنگام اتصال صدا Talk live، یا هنگام مشورت یک فراخوانی ابزار بی‌درنگ با مدل بزرگ‌تر پیکربندی‌شده از طریق talk.client.toolCall، Asking OpenClaw... را نشان می‌دهد.

smoke زنده نگه‌دارنده: OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts پل WebSocket backend OpenAI، تبادل SDP مرورگر WebRTC OpenAI، راه‌اندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر relay Gateway را با رسانه میکروفون جعلی تأیید می‌کند. این دستور فقط وضعیت provider را چاپ می‌کند و secretها را log نمی‌کند.

• روی توقف کلیک کنید (chat.abort را فراخوانی می‌کند).
• وقتی یک اجرا فعال است، پیگیری‌های عادی در صف قرار می‌گیرند. روی هدایت در یک پیام صف‌شده کلیک کنید تا آن پیگیری را به نوبت در حال اجرا تزریق کنید.
• برای لغو خارج از باند، /stop را تایپ کنید (یا عبارت‌های لغو مستقل مانند stop، stop action، stop run، stop openclaw، please stop).
• chat.abort از { sessionKey } (بدون runId) برای لغو همه اجراهای فعال آن نشست پشتیبانی می‌کند.

• وقتی یک اجرا لغو می‌شود، متن بخشی دستیار هنوز می‌تواند در UI نمایش داده شود.
• Gateway وقتی خروجی bufferشده وجود داشته باشد، متن بخشی لغوشده دستیار را در تاریخچه رونوشت پایدار می‌کند.
• ورودی‌های پایدارشده شامل فراداده لغو هستند تا مصرف‌کنندگان رونوشت بتوانند بخش‌های لغو را از خروجی تکمیل عادی تشخیص دهند.

{  gateway: {    controlUi: { allowInsecureAuth: true },    bind: "tailnet",    auth: { mode: "token", token: "replace-me" },  },}

allowInsecureAuth فقط یک toggle سازگاری محلی است:

• اجازه می‌دهد نشست‌های localhost رابط کاربری کنترل در بافت‌های HTTP ناامن بدون هویت دستگاه ادامه پیدا کنند.
• بررسی‌های جفت‌سازی را دور نمی‌زند.
• الزامات هویت دستگاه راه دور (غیر localhost) را آسان‌تر نمی‌کند.

• احراز هویت trusted-proxy موفق می‌تواند نشست‌های اپراتور رابط کاربری کنترل را بدون هویت دستگاه بپذیرد.
• این موضوع به نشست‌های رابط کاربری کنترل با نقش node تعمیم پیدا نمی‌کند.
• پراکسی‌های معکوس loopback روی همان میزبان همچنان احراز هویت trusted-proxy را برآورده نمی‌کنند؛ احراز هویت پراکسی قابل اعتماد را ببینید.

• gatewayUrl پس از load در localStorage ذخیره و از URL حذف می‌شود.
• اگر یک endpoint کامل ws:// یا wss:// را از طریق gatewayUrl ارسال می‌کنید، مقدار gatewayUrl را URL-encode کنید تا مرورگر query string را درست parse کند.
• هر وقت ممکن است، token باید از طریق fragment URL (#token=...) ارسال شود. fragmentها به server ارسال نمی‌شوند، که از نشت در request-log و Referer جلوگیری می‌کند. query paramهای قدیمی ?token= همچنان برای سازگاری یک‌بار import می‌شوند، اما فقط به‌عنوان fallback، و بلافاصله پس از bootstrap حذف می‌شوند.
• password فقط در حافظه نگه داشته می‌شود.
• وقتی gatewayUrl تنظیم شده باشد، UI به اعتبارنامه‌های config یا environment fallback نمی‌کند. token (یا password) را صریحاً ارائه کنید. نبود اعتبارنامه‌های صریح یک خطا است.
• وقتی Gateway پشت TLS قرار دارد (Tailscale Serve، پراکسی HTTPS و غیره)، از wss:// استفاده کنید.
• gatewayUrl فقط در یک پنجره top-level پذیرفته می‌شود (نه embedded) تا از clickjacking جلوگیری شود.
• استقرارهای رابط کاربری کنترل غیر loopback باید gateway.controlUi.allowedOrigins را به‌صورت صریح تنظیم کنند (originهای کامل). این شامل setupهای dev راه دور نیز می‌شود.
• startup مربوط به Gateway ممکن است originهای محلی مانند http://localhost:<port> و http://127.0.0.1:<port> را از bind و port مؤثر runtime مقداردهی اولیه کند، اما originهای مرورگر راه دور همچنان به entryهای صریح نیاز دارند.
• از gateway.controlUi.allowedOrigins: ["*"] جز برای آزمون محلی کاملاً کنترل‌شده استفاده نکنید. معنای آن اجازه دادن به هر origin مرورگر است، نه «مطابقت با هر میزبانی که استفاده می‌کنم».
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true حالت fallback origin بر پایه سرآیند Host را فعال می‌کند، اما یک حالت امنیتی خطرناک است.