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

• از طریق Gateway WS با مدل چت کنید (chat.history, chat.send, chat.abort, chat.inject).
• تازه‌سازی تاریخچهٔ چت یک پنجرهٔ اخیر محدود با سقف متن برای هر پیام درخواست می‌کند تا نشست‌های بزرگ، مرورگر را مجبور نکنند پیش از قابل استفاده شدن چت، payload کامل رونوشت را render کند.
• از طریق نشست‌های realtime مرورگر گفت‌وگو کنید. OpenAI از WebRTC مستقیم استفاده می‌کند، Google Live از یک توکن یک‌بارمصرف محدود مرورگر روی WebSocket استفاده می‌کند، و Pluginهای صدای realtime فقط backend از انتقال relay در Gateway استفاده می‌کنند. نشست‌های provider که مالکشان کلاینت است با talk.client.create شروع می‌شوند؛ نشست‌های relay در Gateway با talk.session.create شروع می‌شوند. relay، اعتبارنامه‌های provider را روی Gateway نگه می‌دارد در حالی که مرورگر PCM میکروفون را از طریق talk.session.appendAudio stream می‌کند و فراخوانی‌های ابزار provider با نام openclaw_agent_consult را از طریق talk.client.toolCall برای سیاست Gateway و مدل بزرگ‌تر پیکربندی‌شدهٔ OpenClaw ارسال می‌کند.
• فراخوانی‌های ابزار + کارت‌های خروجی زندهٔ ابزار را در چت stream کنید (رویدادهای agent).

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

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

• مشاهده/ویرایش ~/.openclaw/openclaw.json (config.get, config.set).
• اعمال + راه‌اندازی دوباره همراه با اعتبارسنجی (config.apply) و بیدار کردن آخرین نشست فعال.
• نوشتن‌ها شامل یک محافظ base-hash برای جلوگیری از بازنویسی و از بین بردن ویرایش‌های هم‌زمان هستند.
• نوشتن‌ها (config.set/config.apply/config.patch) پیش از اجرا، resolve شدن SecretRefهای فعال را برای refهای موجود در payload پیکربندی ارسالی بررسی می‌کنند؛ refهای فعال ارسالی که resolve نشده باشند پیش از نوشتن رد می‌شوند.
• Schema + render فرم (config.schema / config.schema.lookup، شامل title / description فیلد، hintهای UI تطبیق‌یافته، خلاصه‌های فرزند فوری، فرادادهٔ مستندات روی nodeهای object/wildcard/array/composition تو در تو، به‌همراه schemaهای Plugin + کانال وقتی موجود باشند)؛ ویرایشگر Raw JSON فقط وقتی در دسترس است که snapshot یک رفت‌وبرگشت خام امن داشته باشد.
• اگر یک snapshot نتواند متن خام را با اطمینان رفت‌وبرگشت کند، رابط کاربری کنترل حالت Form را اجباری می‌کند و حالت Raw را برای آن snapshot غیرفعال می‌کند.
• گزینهٔ "بازنشانی به ذخیره‌شده" در ویرایشگر Raw JSON شکل نوشته‌شدهٔ خام را حفظ می‌کند (قالب‌بندی، دیدگاه‌ها، چیدمان $include) به‌جای اینکه یک snapshot تخت را دوباره render کند، تا وقتی snapshot بتواند با اطمینان رفت‌وبرگشت کند، ویرایش‌های خارجی پس از بازنشانی باقی بمانند.
• مقدارهای object ساختاریافتهٔ SecretRef در ورودی‌های متنی فرم به‌صورت فقط‌خواندنی render می‌شوند تا از خرابی تصادفی object-to-string جلوگیری شود.

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

• برای کارهای isolated، پیش‌فرض delivery اعلام خلاصه است. اگر اجراهای فقط داخلی می‌خواهید، می‌توانید آن را به none تغییر دهید.
• فیلدهای کانال/هدف وقتی announce انتخاب شده باشد ظاهر می‌شوند.
• حالت Webhook از delivery.mode = "webhook" با delivery.to تنظیم‌شده روی یک URL معتبر webhook از نوع HTTP(S) استفاده می‌کند.
• برای کارهای نشست اصلی، حالت‌های delivery یعنی webhook و none در دسترس هستند.
• کنترل‌های ویرایش پیشرفته شامل حذف پس از اجرا، پاک کردن بازنویسی agent، گزینه‌های cron exact/stagger، بازنویسی‌های مدل/تفکر agent، و کلیدهای best-effort delivery هستند.
• اعتبارسنجی فرم به‌صورت inline با خطاهای سطح فیلد انجام می‌شود؛ مقدارهای نامعتبر تا زمان اصلاح، دکمهٔ ذخیره را غیرفعال می‌کنند.
• cron.webhookToken را تنظیم کنید تا یک bearer token اختصاصی ارسال شود؛ اگر حذف شود webhook بدون سرآیند احراز هویت ارسال می‌شود.
• fallback منسوخ: کارهای legacy ذخیره‌شده با 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، رابط کاربری کنترل برچسب‌های دستور درون‌خطیِ صرفاً نمایشی را از متن قابل مشاهدهٔ دستیار حذف می‌کند (برای نمونه [[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 از رونوشت پایدار نشست بازسازی می‌شود. پس از رویدادهای نهایی ابزار، رابط کاربری کنترل تاریخچه را دوباره بارگذاری می‌کند و فقط یک دنبالهٔ خوش‌بینانهٔ کوچک را ادغام می‌کند؛ مرز رونوشت در WebChat مستند شده است.
• chat.inject یک یادداشت دستیار را به رونوشت نشست اضافه می‌کند و یک رویداد chat را برای به‌روزرسانی‌های فقط UI پخش می‌کند (بدون اجرای عامل، بدون تحویل کانال).
• سربرگ گفتگو فیلتر عامل را پیش از انتخابگر نشست نشان می‌دهد، و انتخابگر نشست به عامل انتخاب‌شده محدود می‌شود. تغییر عامل‌ها فقط نشست‌های وابسته به آن عامل را نشان می‌دهد و وقتی هنوز هیچ نشست داشبورد ذخیره‌شده‌ای ندارد به نشست اصلی همان عامل بازمی‌گردد.
• در عرض‌های دسکتاپ، کنترل‌های گفتگو در یک ردیف فشرده می‌مانند و هنگام پیمایش به پایین رونوشت جمع می‌شوند؛ پیمایش به بالا، بازگشت به ابتدای صفحه، یا رسیدن به انتها کنترل‌ها را بازمی‌گرداند.
• پیام‌های پیاپی و تکراریِ فقط متنی به‌صورت یک حباب با نشان شمارش رندر می‌شوند. پیام‌هایی که تصویر، پیوست، خروجی ابزار، یا پیش‌نمایش canvas دارند جمع نمی‌شوند.
• انتخابگرهای مدل و تفکر در سربرگ گفتگو نشست فعال را فوراً از طریق sessions.patch وصله می‌کنند؛ آن‌ها بازنویسی‌های پایدار نشست هستند، نه گزینه‌های ارسال فقط برای یک نوبت.
• تایپ کردن /new در رابط کاربری کنترل همان نشست تازهٔ داشبورد را مانند گفتگوی جدید ایجاد می‌کند و به آن تغییر می‌دهد. تایپ کردن /reset بازنشانی صریحِ درجا در Gateway را برای نشست فعلی حفظ می‌کند.
• انتخابگر مدل گفتگو نمای مدل پیکربندی‌شدهٔ Gateway را درخواست می‌کند. اگر agents.defaults.models وجود داشته باشد، همان allowlist انتخابگر را هدایت می‌کند. در غیر این صورت انتخابگر ورودی‌های صریح models.providers.*.models به‌همراه ارائه‌دهندگانی با احراز هویت قابل استفاده را نشان می‌دهد. کاتالوگ کامل از طریق RPC اشکال‌زدایی models.list با view: "all" همچنان در دسترس است.
• وقتی گزارش‌های تازهٔ مصرف نشست Gateway فشار بالای زمینه را نشان می‌دهند، ناحیهٔ نویسندهٔ گفتگو یک اعلان زمینه نشان می‌دهد و در سطوح توصیه‌شدهٔ Compaction، یک دکمهٔ فشرده نمایش می‌دهد که مسیر عادی Compaction نشست را اجرا می‌کند. snapshotهای کهنهٔ توکن تا زمانی که Gateway دوباره مصرف تازه را گزارش کند پنهان می‌مانند.

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

در نویسندهٔ گفتگو، کنترل گفتار دکمهٔ موج‌ها کنار دکمهٔ دیکتهٔ میکروفون است. وقتی گفتار شروع می‌شود، ردیف وضعیت نویسنده 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 تبادل SDP مربوط به WebRTC مرورگر OpenAI، راه‌اندازی WebSocket مرورگر با توکن محدود Google Live، و آداپتور مرورگر relay در Gateway را با رسانهٔ میکروفون جعلی بررسی می‌کند. این دستور فقط وضعیت ارائه‌دهنده را چاپ می‌کند و secretها را ثبت نمی‌کند.

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

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

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

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

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

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

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

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