---
read_when:
    - تريد تشغيل Gateway من متصفح
    - تريد الوصول إلى Tailnet من دون أنفاق SSH
sidebarTitle: Control UI
summary: واجهة تحكم مستندة إلى المتصفح لـ Gateway (الدردشة، العُقَد، التكوين)
title: واجهة التحكم
x-i18n:
    generated_at: "2026-05-11T20:44:15Z"
    model: gpt-5.5
    provider: openai
    source_hash: d0033b2666fe76bd23d5585d05b39fdd33f8d15d4e7c16561b5cfd0e75b8d22e
    source_path: web/control-ui.md
    workflow: 16
---

واجهة التحكم هي تطبيق صغير أحادي الصفحة مبني بـ **Vite + Lit** ويقدمه Gateway:

- الافتراضي: `http://<host>:18789/`
- بادئة اختيارية: عيّن `gateway.controlUi.basePath` (مثلًا `/openclaw`)

وهي تتواصل **مباشرة مع Gateway WebSocket** على المنفذ نفسه.

## فتح سريع (محلي)

إذا كان Gateway يعمل على الكمبيوتر نفسه، فافتح:

- [http://127.0.0.1:18789/](http://127.0.0.1:18789/) (أو [http://localhost:18789/](http://localhost:18789/))

إذا فشل تحميل الصفحة، فابدأ Gateway أولًا: `openclaw gateway`.

تُقدَّم المصادقة أثناء مصافحة WebSocket عبر:

- `connect.params.auth.token`
- `connect.params.auth.password`
- ترويسات هوية Tailscale Serve عندما تكون `gateway.auth.allowTailscale: true`
- ترويسات هوية الوكيل الموثوق عندما تكون `gateway.auth.mode: "trusted-proxy"`

تحتفظ لوحة إعدادات لوحة التحكم برمز لجلسة تبويب المتصفح الحالية وعنوان URL المحدد للبوابة؛ ولا تُحفَظ كلمات المرور بشكل دائم. عادةً ينشئ الإعداد الأولي رمز بوابة لمصادقة السر المشترك عند أول اتصال، لكن مصادقة كلمة المرور تعمل أيضًا عندما تكون `gateway.auth.mode` هي `"password"`.

## إقران الجهاز (الاتصال الأول)

عندما تتصل بواجهة التحكم من متصفح أو جهاز جديد، يطلب Gateway عادةً **موافقة إقران لمرة واحدة**. هذا إجراء أمني لمنع الوصول غير المصرح به.

**ما ستراه:** "disconnected (1008): pairing required"

<Steps>
  <Step title="List pending requests">
    ```bash
    openclaw devices list
    ```
  </Step>
  <Step title="Approve by request ID">
    ```bash
    openclaw devices approve <requestId>
    ```
  </Step>
</Steps>

إذا أعاد المتصفح محاولة الإقران مع تفاصيل مصادقة متغيرة (الدور/النطاقات/المفتاح العام)، فسيتم تجاوز الطلب المعلّق السابق وإنشاء `requestId` جديد. أعد تشغيل `openclaw devices list` قبل الموافقة.

إذا كان المتصفح مقترنًا بالفعل وغيّرته من وصول القراءة إلى وصول الكتابة/المسؤول، فسيُعامل ذلك كترقية موافقة، وليس كإعادة اتصال صامتة. يُبقي OpenClaw الموافقة القديمة نشطة، ويحظر إعادة الاتصال الأوسع، ويطلب منك الموافقة صراحةً على مجموعة النطاقات الجديدة.

بعد الموافقة، يتم تذكّر الجهاز ولن يتطلب إعادة الموافقة إلا إذا ألغيتَه باستخدام `openclaw devices revoke --device <id> --role <role>`. راجع [CLI الأجهزة](/ar/cli/devices) لتدوير الرموز والإلغاء.

<Note>
- تتم الموافقة تلقائيًا على اتصالات متصفح local loopback المباشرة (`127.0.0.1` / `localhost`).
- يمكن لـ Tailscale Serve تخطي جولة الإقران لجلسات مشغّل واجهة التحكم عندما تكون `gateway.auth.allowTailscale: true`، وتتحقق هوية Tailscale، ويقدّم المتصفح هوية جهازه.
- لا تزال روابط Tailnet المباشرة، واتصالات متصفح LAN، وملفات تعريف المتصفح التي لا تحتوي على هوية جهاز تتطلب موافقة صريحة.
- ينشئ كل ملف تعريف متصفح معرّف جهاز فريدًا، لذا فإن تبديل المتصفحات أو مسح بيانات المتصفح سيتطلب إعادة الإقران.

</Note>

## الهوية الشخصية (محلية للمتصفح)

تدعم واجهة التحكم هوية شخصية لكل متصفح (اسم عرض وصورة رمزية) تُرفق بالرسائل الصادرة للإسناد في الجلسات المشتركة. وهي تعيش في تخزين المتصفح، وتقتصر على ملف تعريف المتصفح الحالي، ولا تُزامَن مع أجهزة أخرى ولا تُحفَظ على جانب الخادم بما يتجاوز بيانات وصفية عادية لتأليف النصوص في الرسائل التي ترسلها فعليًا. مسح بيانات الموقع أو تبديل المتصفحات يعيدها إلى فارغة.

ينطبق نمط المتصفح المحلي نفسه على تجاوز صورة المساعد الرمزية. تغطي صور المساعد الرمزية المرفوعة الهوية التي يحلها Gateway على المتصفح المحلي فقط، ولا تمر ذهابًا وإيابًا عبر `config.patch`. لا يزال حقل الإعداد المشترك `ui.assistant.avatar` متاحًا للعملاء غير التابعين لواجهة المستخدم الذين يكتبون الحقل مباشرةً (مثل البوابات النصية أو لوحات التحكم المخصصة).

## نقطة نهاية إعداد وقت التشغيل

تجلب واجهة التحكم إعدادات وقت التشغيل الخاصة بها من `/__openclaw/control-ui-config.json`. هذه النقطة النهائية محمية بمصادقة البوابة نفسها مثل بقية سطح HTTP: لا يمكن للمتصفحات غير المصادق عليها جلبها، ويتطلب الجلب الناجح إما رمز/كلمة مرور Gateway صالحين بالفعل، أو هوية Tailscale Serve، أو هوية وكيل موثوق.

## دعم اللغة

يمكن لواجهة التحكم أن تعرّب نفسها عند التحميل الأول بناءً على لغة متصفحك. لتجاوز ذلك لاحقًا، افتح **نظرة عامة -> الوصول إلى Gateway -> اللغة**. يوجد منتقي اللغة في بطاقة الوصول إلى Gateway، وليس ضمن المظهر.

- اللغات المدعومة: `en`, `zh-CN`, `zh-TW`, `pt-BR`, `de`, `es`, `ja-JP`, `ko`, `fr`, `ar`, `it`, `tr`, `uk`, `id`, `pl`, `th`, `vi`, `nl`, `fa`
- تُحمَّل الترجمات غير الإنجليزية بشكل كسول في المتصفح.
- تُحفَظ اللغة المحددة في تخزين المتصفح ويُعاد استخدامها في الزيارات المستقبلية.
- تعود مفاتيح الترجمة المفقودة إلى الإنجليزية.

تُولَّد ترجمات التوثيق لمجموعة اللغات غير الإنجليزية نفسها، لكن منتقي اللغة المدمج في موقع التوثيق من Mintlify يقتصر على رموز اللغات التي يقبلها Mintlify. لا تزال وثائق التايلاندية (`th`) والفارسية (`fa`) تُولَّد في مستودع النشر؛ وقد لا تظهر في ذلك المنتقي إلى أن يدعم Mintlify تلك الرموز.

## سمات المظهر

تحتفظ لوحة المظهر بالسمات المدمجة Claw وKnot وDash، بالإضافة إلى خانة استيراد tweakcn واحدة محلية للمتصفح. لاستيراد سمة، افتح [محرر tweakcn](https://tweakcn.com/editor/theme)، واختر سمة أو أنشئ واحدة، وانقر **مشاركة**، ثم الصق رابط السمة المنسوخ في المظهر. يقبل المستورد أيضًا عناوين URL لسجل `https://tweakcn.com/r/themes/<id>`، وعناوين URL للمحرر مثل `https://tweakcn.com/editor/theme?theme=amethyst-haze`، والمسارات النسبية `/themes/<id>`، ومعرّفات السمات الخام، وأسماء السمات الافتراضية مثل `amethyst-haze`.

تُخزَّن السمات المستوردة فقط في ملف تعريف المتصفح الحالي. ولا تُكتب في إعدادات Gateway ولا تتزامن عبر الأجهزة. يستبدل تغيير السمة المستوردة الخانة المحلية الواحدة؛ ويؤدي مسحها إلى تبديل السمة النشطة مرة أخرى إلى Claw إذا كانت السمة المستوردة محددة.

## ما يمكنها فعله (اليوم)

<AccordionGroup>
  <Accordion title="Chat and Talk">
    - الدردشة مع النموذج عبر Gateway WS (`chat.history`, `chat.send`, `chat.abort`, `chat.inject`).
    - تطلب تحديثات سجل الدردشة نافذة حديثة محدودة مع حدود نصية لكل رسالة حتى لا تجبر الجلسات الكبيرة المتصفح على عرض حمولة النص الكامل قبل أن تصبح الدردشة قابلة للاستخدام.
    - التحدث عبر جلسات المتصفح في الوقت الفعلي. يستخدم OpenAI اتصال WebRTC مباشرًا، ويستخدم Google Live رمز متصفح مقيدًا لمرة واحدة عبر WebSocket، وتستخدم Plugins الصوت الفوري التي تعمل على الخلفية فقط نقل ترحيل Gateway. تبدأ جلسات المزود المملوكة للعميل بـ `talk.client.create`؛ وتبدأ جلسات ترحيل Gateway بـ `talk.session.create`. يحتفظ الترحيل ببيانات اعتماد المزود على Gateway بينما يبث المتصفح PCM الميكروفون عبر `talk.session.appendAudio` ويمرر استدعاءات أدوات المزود `openclaw_agent_consult` عبر `talk.client.toolCall` لسياسة Gateway ونموذج OpenClaw الأكبر المكوّن.
    - بث استدعاءات الأدوات + بطاقات إخراج الأدوات الحية في الدردشة (أحداث الوكيل).

  </Accordion>
  <Accordion title="Channels, instances, sessions, dreams">
    - القنوات: حالة القنوات المدمجة بالإضافة إلى قنوات Plugin المضمنة/الخارجية، وتسجيل الدخول عبر QR، وإعداد كل قناة (`channels.status`, `web.login.*`, `config.patch`).
    - تُبقي تحديثات فحص القنوات اللقطة السابقة مرئية أثناء انتهاء فحوصات المزود البطيئة، وتُوسَم اللقطات الجزئية عندما يتجاوز فحص أو تدقيق ميزانية واجهة المستخدم الخاصة به.
    - المثيلات: قائمة الحضور + التحديث (`system-presence`).
    - الجلسات: تسرد جلسات الوكيل المكوّن افتراضيًا، وتتراجع من مفاتيح جلسات الوكيل غير المكوّن القديمة، وتطبق تجاوزات النموذج/التفكير/السريع/المطوّل/التتبع/الاستدلال لكل جلسة (`sessions.list`, `sessions.patch`).
    - الأحلام: حالة Dreaming، ومفتاح التفعيل/التعطيل، وقارئ Dream Diary (`doctor.memory.status`, `doctor.memory.dreamDiary`, `config.patch`).

  </Accordion>
  <Accordion title="Cron, skills, nodes, exec approvals">
    - مهام Cron: سرد/إضافة/تحرير/تشغيل/تفعيل/تعطيل + سجل التشغيل (`cron.*`).
    - Skills: الحالة، التفعيل/التعطيل، التثبيت، تحديثات مفتاح API (`skills.*`).
    - العقد: القائمة + القدرات (`node.list`).
    - موافقات التنفيذ: تحرير قوائم السماح للبوابة أو العقدة + سياسة السؤال لـ `exec host=gateway/node` (`exec.approvals.*`).

  </Accordion>
  <Accordion title="Config">
    - عرض/تحرير `~/.openclaw/openclaw.json` (`config.get`, `config.set`).
    - التطبيق + إعادة التشغيل مع التحقق (`config.apply`) وإيقاظ آخر جلسة نشطة.
    - تتضمن عمليات الكتابة حارس تجزئة أساسيًا لمنع طمس التحريرات المتزامنة.
    - تُجري عمليات الكتابة (`config.set`/`config.apply`/`config.patch`) فحصًا مسبقًا لحل SecretRef النشط للمراجع في حمولة الإعداد المقدمة؛ وتُرفض المراجع النشطة المقدمة غير المحلولة قبل الكتابة.
    - عرض المخطط + النموذج (`config.schema` / `config.schema.lookup`، بما في ذلك حقلا `title` / `description`، وتلميحات واجهة المستخدم المطابقة، وملخصات الأبناء المباشرين، وبيانات وصفية للتوثيق على عقد الكائنات/أحرف البدل/المصفوفات/التركيبات المتداخلة، بالإضافة إلى مخططات Plugin + القنوات عند توفرها)؛ يتوفر محرر Raw JSON فقط عندما تحتوي اللقطة على رحلة ذهاب وإياب خام آمنة.
    - إذا تعذر على لقطة ما إكمال رحلة ذهاب وإياب آمنة للنص الخام، تفرض واجهة التحكم وضع النموذج وتعطل وضع الخام لتلك اللقطة.
    - يحافظ محرر Raw JSON "إعادة التعيين إلى المحفوظ" على الشكل المؤلف خامًا (التنسيق، التعليقات، تخطيط `$include`) بدلًا من إعادة عرض لقطة مسطحة، لذا تنجو التحريرات الخارجية من إعادة التعيين عندما تستطيع اللقطة إكمال رحلة ذهاب وإياب بأمان.
    - تُعرض قيم كائن SecretRef المهيكلة للقراءة فقط في حقول نص النموذج لمنع تلف الكائن إلى سلسلة نصية عرضيًا.

  </Accordion>
  <Accordion title="Debug, logs, update">
    - التصحيح: لقطات الحالة/الصحة/النماذج + سجل الأحداث + استدعاءات RPC اليدوية (`status`, `health`, `models.list`).
    - يتضمن سجل الأحداث توقيتات تحديث/RPC الخاصة بواجهة التحكم، وتوقيتات عرض الدردشة/الإعداد البطيئة، ومدخلات استجابة المتصفح لإطارات الرسوم المتحركة الطويلة أو المهام الطويلة عندما يكشف المتصفح أنواع إدخال PerformanceObserver تلك.
    - السجلات: متابعة حية لسجلات ملفات Gateway مع التصفية/التصدير (`logs.tail`).
    - التحديث: تشغيل تحديث حزمة/git + إعادة التشغيل (`update.run`) مع تقرير إعادة تشغيل، ثم استطلاع `update.status` بعد إعادة الاتصال للتحقق من إصدار Gateway الجاري تشغيله.

  </Accordion>
  <Accordion title="Cron jobs panel notes">
    - بالنسبة للمهام المعزولة، يكون التسليم الافتراضي هو إعلان الملخص. يمكنك التبديل إلى بلا إذا أردت تشغيلات داخلية فقط.
    - تظهر حقول القناة/الهدف عند تحديد الإعلان.
    - يستخدم وضع Webhook القيمة `delivery.mode = "webhook"` مع تعيين `delivery.to` إلى عنوان URL صالح لـ HTTP(S) webhook.
    - بالنسبة لمهام الجلسة الرئيسية، تتوفر أوضاع تسليم webhook وبلا.
    - تتضمن عناصر التحكم المتقدمة للتحرير الحذف بعد التشغيل، ومسح تجاوز الوكيل، وخيارات cron الدقيقة/المتدرجة، وتجاوزات نموذج/تفكير الوكيل، ومفاتيح تسليم أفضل جهد.
    - يكون التحقق من النموذج مضمّنًا مع أخطاء على مستوى الحقل؛ وتعطل القيم غير الصالحة زر الحفظ إلى أن يتم إصلاحها.
    - عيّن `cron.webhookToken` لإرسال رمز حامل مخصص، وإذا تُرك محذوفًا فسيُرسل webhook دون ترويسة مصادقة.
    - بديل مهمل: يمكن للمهام القديمة المخزنة مع `notify: true` الاستمرار في استخدام `cron.webhook` إلى أن تُرحَّل.

  </Accordion>
</AccordionGroup>

## سلوك الدردشة

<AccordionGroup>
  <Accordion title="دلالات الإرسال والسجل">
    - `chat.send` **غير حاجب**: يقر فورا بـ `{ runId, status: "started" }` وتتدفق الاستجابة عبر أحداث `chat`.
    - تقبل تحميلات الدردشة الصور والملفات غير الفيديوية. تحتفظ الصور بمسار الصورة الأصلي؛ أما الملفات الأخرى فتخزن كوسائط مدارة وتظهر في السجل كروابط مرفقات.
    - تعيد إعادة الإرسال باستخدام `idempotencyKey` نفسه `{ status: "in_flight" }` أثناء التشغيل، و`{ status: "ok" }` بعد الاكتمال.
    - تكون استجابات `chat.history` محدودة الحجم لسلامة واجهة المستخدم. عندما تكون إدخالات النص كبيرة جدا، قد يقتطع Gateway حقول النص الطويلة، ويحذف كتل البيانات الوصفية الثقيلة، ويستبدل الرسائل كبيرة الحجم بعنصر نائب (`[chat.history omitted: message too large]`).
    - تحفظ الصور التي ينتجها المساعد/النظام كإشارات وسائط مدارة وتقدم مرة أخرى عبر عناوين URL لوسائط Gateway مصادق عليها، لذلك لا تعتمد عمليات إعادة التحميل على بقاء حمولات الصور الخام بترميز base64 في استجابة سجل الدردشة.
    - عند عرض `chat.history`، تزيل واجهة التحكم وسوم التعليمات المضمنة المخصصة للعرض فقط من نص المساعد المرئي (مثل `[[reply_to_*]]` و`[[audio_as_voice]]`)، وحمولات 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` لقطة أقدم لفترة وجيزة؛ ويستبدل النص المرجعي تلك الرسائل المحلية عندما يلحق سجل Gateway.
    - أحداث `chat` المباشرة هي حالة التسليم، بينما يعاد بناء `chat.history` من نص الجلسة الدائم. بعد أحداث نهاية الأدوات، تعيد واجهة التحكم تحميل السجل ولا تدمج إلا ذيلا تفاؤليا صغيرا؛ وحد النص موثق في [WebChat](/ar/web/webchat).
    - يضيف `chat.inject` ملاحظة مساعد إلى نص الجلسة ويبث حدث `chat` لتحديثات واجهة المستخدم فقط (بدون تشغيل وكيل، وبدون تسليم قناة).
    - يعرض رأس الدردشة مرشح الوكيل قبل منتقي الجلسة، ويكون منتقي الجلسة مقيدا بالوكيل المحدد. عند تبديل الوكلاء، لا تظهر إلا الجلسات المرتبطة بذلك الوكيل، مع الرجوع إلى جلسة ذلك الوكيل الرئيسية عندما لا تكون لديه جلسات لوحة معلومات محفوظة بعد.
    - في عروض سطح المكتب، تبقى عناصر تحكم الدردشة في صف مضغوط واحد وتنطوي أثناء التمرير لأسفل في النص؛ وتعود عناصر التحكم عند التمرير لأعلى، أو الرجوع إلى الأعلى، أو الوصول إلى الأسفل.
    - تعرض الرسائل النصية المتكررة المتتالية كفقاعة واحدة مع شارة عدد. أما الرسائل التي تحمل صورا أو مرفقات أو مخرجات أدوات أو معاينات لوحة فتبقى غير مطوية.
    - يطبق منتقيا النموذج والتفكير في رأس الدردشة تعديلا فوريا على الجلسة النشطة عبر `sessions.patch`؛ وهما تجاوزان دائمان للجلسة، وليسا خيارين للإرسال لدورة واحدة فقط.
    - إذا أرسلت رسالة بينما لا يزال تغيير منتقي النموذج للجلسة نفسها قيد الحفظ، ينتظر المؤلف تصحيح تلك الجلسة قبل استدعاء `chat.send` حتى يستخدم الإرسال النموذج المحدد.
    - تؤدي كتابة `/new` في واجهة التحكم إلى إنشاء جلسة لوحة معلومات جديدة مماثلة والتبديل إليها مثل New Chat، إلا عندما يكون `session.dmScope: "main"` مهيأ ويكون الأصل الحالي هو جلسة الوكيل الرئيسية؛ في هذه الحالة يعيد ضبط الجلسة الرئيسية في مكانها. وتبقي كتابة `/reset` إعادة الضبط الصريحة في مكانها من Gateway للجلسة الحالية.
    - يطلب منتقي نموذج الدردشة عرض النموذج المهيأ في Gateway. إذا كان `agents.defaults.models` موجودا، فستقود قائمة السماح هذه المنتقي، بما في ذلك إدخالات `provider/*` التي تبقي كتالوجات النطاق الخاص بالمزود ديناميكية. وإلا، يعرض المنتقي إدخالات `models.providers.*.models` الصريحة بالإضافة إلى المزودين ذوي المصادقة القابلة للاستخدام. يظل الكتالوج الكامل متاحا عبر RPC التصحيح `models.list` مع `view: "all"`.
    - عندما تتضمن تقارير استخدام جلسة Gateway الحديثة رموز السياق الحالية، تعرض منطقة مؤلف الدردشة مؤشرا مضغوطا لاستخدام السياق. يتحول إلى نمط تحذيري عند ضغط سياق مرتفع، وعند مستويات Compaction الموصى بها، يعرض زرا مضغوطا يشغل مسار Compaction العادي للجلسة. تخفى لقطات الرموز القديمة حتى يبلغ Gateway عن استخدام حديث مرة أخرى.

  </Accordion>
  <Accordion title="وضع التحدث (الوقت الحقيقي في المتصفح)">
    يستخدم وضع التحدث مزود صوت وقت حقيقي مسجلا. هيئ 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 قياسيا للمزود. يتلقى OpenAI سرا مؤقتا لعميل Realtime من أجل WebRTC. ويتلقى Google Live رمز مصادقة Live API مقيدا للاستخدام مرة واحدة لجلسة WebSocket في المتصفح، مع تعليمات وتصريحات أدوات مقفلة داخل الرمز بواسطة Gateway. المزودون الذين لا يكشفون إلا جسرا خلفيا للوقت الحقيقي يعملون عبر نقل ترحيل Gateway، بحيث تبقى بيانات الاعتماد ومقابس المورد من جهة الخادم بينما ينتقل صوت المتصفح عبر RPCs مصادق عليها من Gateway. يجمع Gateway مطالبة جلسة Realtime؛ ولا يقبل `talk.client.create` تجاوزات تعليمات مقدمة من المستدعي.

    يتضمن مؤلف الدردشة زر خيارات التحدث بجانب زر بدء/إيقاف التحدث. تنطبق الخيارات على جلسة التحدث التالية ويمكنها تجاوز المزود، والنقل، والنموذج، والصوت، وجهد الاستدلال، وعتبة VAD، ومدة الصمت، وحشو البادئة. عندما يكون خيار فارغا، يستخدم Gateway القيم الافتراضية المهيأة حيثما توفرت أو القيمة الافتراضية للمزود. يفرض اختيار ترحيل Gateway مسار الترحيل الخلفي؛ أما اختيار WebRTC فيبقي الجلسة مملوكة للعميل ويفشل بدلا من الرجوع بصمت إلى الترحيل إذا لم يستطع المزود إنشاء جلسة متصفح.

    في مؤلف الدردشة، عنصر تحكم التحدث هو زر الموجات بجانب زر الإملاء بالميكروفون. عند بدء التحدث، يعرض صف حالة المؤلف `Connecting Talk...`، ثم `Talk live` أثناء اتصال الصوت، أو `Asking OpenClaw...` أثناء استشارة استدعاء أداة في الوقت الحقيقي للنموذج الأكبر المهيأ عبر `talk.client.toolCall`.

    اختبار smoke مباشر للمشرفين: يتحقق `OPENAI_API_KEY=... GEMINI_API_KEY=... node --import tsx scripts/dev/realtime-talk-live-smoke.ts` من جسر WebSocket الخلفي لـ OpenAI، وتبادل SDP عبر WebRTC في متصفح OpenAI، وإعداد WebSocket للمتصفح برمز مقيد في Google Live، ومحول متصفح ترحيل Gateway مع وسائط ميكروفون وهمية. يطبع الأمر حالة المزود فقط ولا يسجل الأسرار.

  </Accordion>
  <Accordion title="الإيقاف والإجهاض">
    - انقر **إيقاف** (يستدعي `chat.abort`).
    - أثناء نشاط تشغيل، تصطف المتابعات العادية في قائمة انتظار. انقر **توجيه** على رسالة في قائمة الانتظار لحقن تلك المتابعة في الدورة الجارية.
    - اكتب `/stop` (أو عبارات إجهاض مستقلة مثل `stop` و`stop action` و`stop run` و`stop openclaw` و`please stop`) للإجهاض خارج النطاق.
    - يدعم `chat.abort` القيمة `{ sessionKey }` (بدون `runId`) لإجهاض كل عمليات التشغيل النشطة لتلك الجلسة.

  </Accordion>
  <Accordion title="الاحتفاظ الجزئي بعد الإجهاض">
    - عند إجهاض تشغيل، يمكن أن يظل نص المساعد الجزئي معروضا في واجهة المستخدم.
    - يحفظ Gateway نص المساعد الجزئي المجهض في سجل النص عندما توجد مخرجات مخزنة مؤقتا.
    - تتضمن الإدخالات المحفوظة بيانات وصفية للإجهاض حتى يستطيع مستهلكو النص تمييز الجزئيات المجهضة من مخرجات الاكتمال العادية.

  </Accordion>
</AccordionGroup>

## تثبيت PWA والدفع الويب

تشحن واجهة التحكم `manifest.webmanifest` وعامل خدمة، لذلك تستطيع المتصفحات الحديثة تثبيتها كتطبيق PWA مستقل. يتيح Web Push لـ Gateway إيقاظ PWA المثبت بإشعارات حتى عندما لا تكون علامة التبويب أو نافذة المتصفح مفتوحة.

| السطح                                                | ما يفعله                                                        |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `ui/public/manifest.webmanifest`                      | بيان PWA. تعرض المتصفحات خيار "تثبيت التطبيق" بمجرد أن يصبح قابلا للوصول.   |
| `ui/public/sw.js`                                     | عامل خدمة يتعامل مع أحداث `push` ونقرات الإشعارات. |
| `push/vapid-keys.json` (تحت دليل حالة OpenClaw) | زوج مفاتيح VAPID يولد تلقائيا ويستخدم لتوقيع حمولات Web Push.       |
| `push/web-push-subscriptions.json`                    | نقاط نهاية اشتراك المتصفح المحفوظة.                          |

تجاوز زوج مفاتيح VAPID عبر متغيرات البيئة في عملية Gateway عندما تريد تثبيت المفاتيح (للنشر متعدد المضيفين، أو تدوير الأسرار، أو الاختبارات):

- `OPENCLAW_VAPID_PUBLIC_KEY`
- `OPENCLAW_VAPID_PRIVATE_KEY`
- `OPENCLAW_VAPID_SUBJECT` (افتراضيا `mailto:openclaw@localhost`)

تستخدم واجهة التحكم طرق Gateway هذه المقيدة بالنطاق لتسجيل اشتراكات المتصفح واختبارها:

- `push.web.vapidPublicKey` — يجلب مفتاح VAPID العام النشط.
- `push.web.subscribe` — يسجل `endpoint` بالإضافة إلى `keys.p256dh`/`keys.auth`.
- `push.web.unsubscribe` — يزيل نقطة نهاية مسجلة.
- `push.web.test` — يرسل إشعار اختبار إلى اشتراك المستدعي.

<Note>
Web Push مستقل عن مسار ترحيل APNS في iOS (راجع [التهيئة](/ar/gateway/configuration) للدفع المدعوم بالترحيل) وعن طريقة `push.test` الحالية، التي تستهدف اقتران الأجهزة المحمولة الأصلية.
</Note>

## التضمينات المستضافة

يمكن لرسائل المساعد عرض محتوى ويب مستضافا مضمننا باستخدام الرمز المختصر `[embed ...]`. تتحكم `gateway.controlUi.embedSandbox` في سياسة صندوق عزل iframe:

<Tabs>
  <Tab title="صارم">
    يعطل تنفيذ السكربتات داخل التضمينات المستضافة.
  </Tab>
  <Tab title="سكربتات (افتراضي)">
    يسمح بتضمينات تفاعلية مع الحفاظ على عزل الأصل؛ وهذا هو الخيار الافتراضي ويكون عادة كافيا لألعاب/ودجات المتصفح المستقلة.
  </Tab>
  <Tab title="موثوق">
    يضيف `allow-same-origin` فوق `allow-scripts` للمستندات من الموقع نفسه التي تحتاج عمدا إلى صلاحيات أقوى.
  </Tab>
</Tabs>

مثال:

```json5
{
  gateway: {
    controlUi: {
      embedSandbox: "scripts",
    },
  },
}
```

<Warning>
استخدم `trusted` فقط عندما يحتاج المستند المضمن حقا إلى سلوك من نفس الأصل. بالنسبة لمعظم الألعاب واللوحات التفاعلية التي ينشئها الوكيل، يكون `scripts` هو الخيار الأكثر أمانا.
</Warning>

تبقى عناوين URL الخارجية المطلقة من نوع `http(s)` للتضمين محظورة افتراضيا. إذا كنت تريد عمدا أن تحمل `[embed url="https://..."]` صفحات من طرف ثالث، فاضبط `gateway.controlUi.allowExternalEmbedUrls: true`.

## عرض رسالة الدردشة

تستخدم رسائل الدردشة المجمعة حدا أقصى افتراضيا للعرض سهل القراءة. تستطيع عمليات النشر على الشاشات العريضة تجاوزه دون تعديل CSS المضمنة عبر ضبط `gateway.controlUi.chatMessageMaxWidth`:

```json5
{
  gateway: {
    controlUi: {
      chatMessageMaxWidth: "min(1280px, 82%)",
    },
  },
}
```

تتحقق القيمة قبل وصولها إلى المتصفح. تشمل القيم المدعومة الأطوال والنسب المئوية البسيطة مثل `960px` أو `82%`، بالإضافة إلى تعبيرات العرض المقيدة `min(...)` و`max(...)` و`clamp(...)` و`calc(...)` و`fit-content(...)`.

## وصول Tailnet (موصى به)

<Tabs>
  <Tab title="خدمة Tailscale Serve المدمجة (مفضلة)">
    أبق Gateway على loopback ودع Tailscale Serve يمرره عبر HTTPS:

    ```bash
    openclaw gateway --tailscale serve
    ```

    افتح:

    - `https://<magicdns>/` (أو `gateway.controlUi.basePath` المهيأ لديك)

    افتراضيًا، يمكن لطلبات Serve الخاصة بواجهة التحكم/WebSocket المصادقة عبر ترويسات هوية Tailscale (`tailscale-user-login`) عندما تكون `gateway.auth.allowTailscale` مضبوطة على `true`. يتحقق OpenClaw من الهوية عبر حل عنوان `x-forwarded-for` باستخدام `tailscale whois` ومطابقته مع الترويسة، ولا يقبل ذلك إلا عندما يصل الطلب إلى loopback مع ترويسات Tailscale من نوع `x-forwarded-*`. بالنسبة إلى جلسات مشغّل واجهة التحكم ذات هوية جهاز المتصفح، يتجاوز مسار Serve المتحقق منه هذا أيضًا جولة إقران الجهاز؛ أما المتصفحات بلا جهاز واتصالات دور العقدة فتظل تتبع فحوصات الجهاز العادية. اضبط `gateway.auth.allowTailscale: false` إذا كنت تريد فرض بيانات اعتماد سر مشترك صريحة حتى لحركة Serve. ثم استخدم `gateway.auth.mode: "token"` أو `"password"`.

    بالنسبة إلى مسار هوية Serve غير المتزامن هذا، تُسلسل محاولات المصادقة الفاشلة لعنوان IP العميل نفسه ونطاق المصادقة نفسه قبل عمليات كتابة حدّ المعدّل. لذلك قد تعرض إعادة المحاولة السيئة المتزامنة من المتصفح نفسه `retry later` في الطلب الثاني بدلًا من عدم تطابقين عاديين يتسابقان بالتوازي.

    <Warning>
    تفترض مصادقة Serve بلا رمز أن مضيف Gateway موثوق. إذا كان يمكن تشغيل كود محلي غير موثوق على ذلك المضيف، فافرض مصادقة بالرمز/كلمة المرور.
    </Warning>

  </Tab>
  <Tab title="الربط إلى tailnet + الرمز">
    ```bash
    openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"
    ```

    ثم افتح:

    - `http://<tailscale-ip>:18789/` (أو `gateway.controlUi.basePath` المكوّن لديك)

    الصق السر المشترك المطابق في إعدادات الواجهة (يُرسل كـ `connect.params.auth.token` أو `connect.params.auth.password`).

  </Tab>
</Tabs>

## HTTP غير آمن

إذا فتحت لوحة المعلومات عبر HTTP عادي (`http://<lan-ip>` أو `http://<tailscale-ip>`)، يعمل المتصفح في **سياق غير آمن** ويحظر WebCrypto. افتراضيًا، **يحظر** OpenClaw اتصالات واجهة التحكم من دون هوية جهاز.

الاستثناءات الموثقة:

- توافق HTTP غير الآمن المقتصر على localhost مع `gateway.controlUi.allowInsecureAuth=true`
- مصادقة مشغّل واجهة التحكم الناجحة عبر `gateway.auth.mode: "trusted-proxy"`
- خيار الطوارئ `gateway.controlUi.dangerouslyDisableDeviceAuth=true`

**الإصلاح الموصى به:** استخدم HTTPS (Tailscale Serve) أو افتح الواجهة محليًا:

- `https://<magicdns>/` (Serve)
- `http://127.0.0.1:18789/` (على مضيف Gateway)

<AccordionGroup>
  <Accordion title="سلوك مفتاح المصادقة غير الآمنة">
    ```json5
    {
      gateway: {
        controlUi: { allowInsecureAuth: true },
        bind: "tailnet",
        auth: { mode: "token", token: "replace-me" },
      },
    }
    ```

    `allowInsecureAuth` هو مفتاح توافق محلي فقط:

    - يسمح لجلسات واجهة التحكم على localhost بالمتابعة من دون هوية جهاز في سياقات HTTP غير الآمنة.
    - لا يتجاوز فحوصات الإقران.
    - لا يخفف متطلبات هوية الجهاز البعيدة (غير localhost).

  </Accordion>
  <Accordion title="للطوارئ فقط">
    ```json5
    {
      gateway: {
        controlUi: { dangerouslyDisableDeviceAuth: true },
        bind: "tailnet",
        auth: { mode: "token", token: "replace-me" },
      },
    }
    ```

    <Warning>
    يعطّل `dangerouslyDisableDeviceAuth` فحوصات هوية جهاز واجهة التحكم، وهو تخفيض أمني شديد. أعده سريعًا بعد الاستخدام الطارئ.
    </Warning>

  </Accordion>
  <Accordion title="ملاحظة عن الوكيل الموثوق">
    - يمكن لمصادقة الوكيل الموثوق الناجحة قبول جلسات واجهة التحكم الخاصة بـ **المشغّل** من دون هوية جهاز.
    - لا يمتد ذلك إلى جلسات واجهة التحكم ذات دور العقدة.
    - لا تزال وكلاء reverse proxy عبر loopback على المضيف نفسه لا تفي بمصادقة الوكيل الموثوق؛ راجع [مصادقة الوكيل الموثوق](/ar/gateway/trusted-proxy-auth).

  </Accordion>
</AccordionGroup>

راجع [Tailscale](/ar/gateway/tailscale) للحصول على إرشادات إعداد HTTPS.

## سياسة أمان المحتوى

تأتي واجهة التحكم مع سياسة `img-src` صارمة: لا يُسمح إلا بأصول **نفس المصدر**، وعناوين URL من نوع `data:`، وعناوين URL من نوع `blob:` المُنشأة محليًا. يرفض المتصفح عناوين URL للصور البعيدة من نوع `http(s)` والنسبية إلى البروتوكول ولا يصدر طلبات جلب شبكية.

ما يعنيه ذلك عمليًا:

- لا تزال الصور الرمزية والصور المقدمة ضمن مسارات نسبية (مثل `/avatars/<id>`) تظهر، بما في ذلك مسارات الصور الرمزية المصادق عليها التي تجلبها الواجهة وتحولها إلى عناوين URL محلية من نوع `blob:`.
- لا تزال عناوين URL المضمنة من نوع `data:image/...` تظهر (مفيدة للحمولات داخل البروتوكول).
- لا تزال عناوين URL المحلية من نوع `blob:` التي تنشئها واجهة التحكم تظهر.
- تُزال عناوين URL البعيدة للصور الرمزية التي تصدرها بيانات تعريف القناة في مساعدات الصور الرمزية الخاصة بواجهة التحكم وتُستبدل بالشعار/الشارة المدمجة، لذلك لا يمكن لقناة مخترقة أو خبيثة فرض عمليات جلب صور بعيدة عشوائية من متصفح المشغّل.

لا تحتاج إلى تغيير أي شيء للحصول على هذا السلوك — فهو مفعّل دائمًا وغير قابل للتكوين.

## مصادقة مسار الصورة الرمزية

عند تكوين مصادقة Gateway، تتطلب نقطة نهاية الصورة الرمزية في واجهة التحكم رمز Gateway نفسه كبقية API:

- يعيد `GET /avatar/<agentId>` صورة الصورة الرمزية للمتصلين المصادق عليهم فقط. يعيد `GET /avatar/<agentId>?meta=1` بيانات تعريف الصورة الرمزية وفق القاعدة نفسها.
- تُرفض الطلبات غير المصادق عليها إلى أي من المسارين (بما يطابق مسار وسائط المساعد الشقيق). يمنع ذلك مسار الصورة الرمزية من تسريب هوية الوكيل على المضيفات المحمية بخلاف ذلك.
- تمرر واجهة التحكم نفسها رمز Gateway كترويسة bearer عند جلب الصور الرمزية، وتستخدم عناوين URL مصادقًا عليها من نوع blob بحيث تظل الصورة ظاهرة في لوحات المعلومات.

إذا عطّلت مصادقة Gateway (غير موصى به على المضيفات المشتركة)، يصبح مسار الصورة الرمزية أيضًا غير مصادق عليه، بما يتماشى مع بقية Gateway.

## مصادقة مسار وسائط المساعد

عند تكوين مصادقة Gateway، تستخدم معاينات الوسائط المحلية للمساعد مسارًا من خطوتين:

- يتطلب `GET /__openclaw__/assistant-media?meta=1&source=<path>` مصادقة مشغّل واجهة التحكم العادية. يرسل المتصفح رمز Gateway كترويسة bearer عند التحقق من التوفر.
- تتضمن ردود بيانات التعريف الناجحة `mediaTicket` قصير العمر ومقيّدًا بذلك المسار المصدر المحدد.
- تستخدم عناوين URL للصور والصوت والفيديو والمستندات المعروضة في المتصفح `mediaTicket=<ticket>` بدلًا من رمز Gateway النشط أو كلمة المرور. تنتهي صلاحية التذكرة بسرعة ولا يمكنها تخويل مصدر مختلف.

يحافظ ذلك على توافق عرض الوسائط العادي مع عناصر الوسائط الأصلية في المتصفح من دون وضع بيانات اعتماد Gateway القابلة لإعادة الاستخدام في عناوين URL المرئية للوسائط.

## بناء الواجهة

يقدّم Gateway الملفات الثابتة من `dist/control-ui`. ابنها باستخدام:

```bash
pnpm ui:build
```

قاعدة مطلقة اختيارية (عندما تريد عناوين URL ثابتة للأصول):

```bash
OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build
```

للتطوير المحلي (خادم تطوير منفصل):

```bash
pnpm ui:dev
```

ثم وجّه الواجهة إلى عنوان URL الخاص بـ Gateway WS لديك (مثل `ws://127.0.0.1:18789`).

## صفحة واجهة التحكم الفارغة

إذا حمّل المتصفح لوحة معلومات فارغة ولم تعرض DevTools أي خطأ مفيد، فقد تكون إضافة أو سكربت محتوى مبكر قد منع تطبيق وحدة JavaScript من التقييم. تتضمن الصفحة الثابتة لوحة استرداد HTML عادية تظهر عندما لا يكون `<openclaw-app>` مسجلًا بعد بدء التشغيل.

استخدم إجراء **المحاولة مرة أخرى** في اللوحة بعد تغيير بيئة المتصفح، أو أعد التحميل يدويًا بعد هذه الفحوصات:

- عطّل الإضافات التي تحقن في كل الصفحات، خاصة الإضافات ذات سكربتات محتوى `<all_urls>`.
- جرّب نافذة خاصة، أو ملف تعريف متصفح نظيفًا، أو متصفحًا آخر.
- أبقِ Gateway قيد التشغيل وتحقق من عنوان URL نفسه للوحة المعلومات بعد تغيير المتصفح.

## التصحيح/الاختبار: خادم التطوير + Gateway بعيد

واجهة التحكم هي ملفات ثابتة؛ هدف WebSocket قابل للتكوين ويمكن أن يكون مختلفًا عن أصل HTTP. هذا مفيد عندما تريد خادم تطوير Vite محليًا بينما يعمل Gateway في مكان آخر.

<Steps>
  <Step title="بدء خادم تطوير الواجهة">
    ```bash
    pnpm ui:dev
    ```
  </Step>
  <Step title="الفتح باستخدام gatewayUrl">
    ```text
    http://localhost:5173/?gatewayUrl=ws%3A%2F%2F<gateway-host>%3A18789
    ```

    مصادقة اختيارية لمرة واحدة (إذا لزم الأمر):

    ```text
    http://localhost:5173/?gatewayUrl=wss%3A%2F%2F<gateway-host>%3A18789#token=<gateway-token>
    ```

  </Step>
</Steps>

<AccordionGroup>
  <Accordion title="ملاحظات">
    - يُخزّن `gatewayUrl` في localStorage بعد التحميل ويُزال من عنوان URL.
    - إذا مررت نقطة نهاية كاملة `ws://` أو `wss://` عبر `gatewayUrl`، فقم بترميز قيمة `gatewayUrl` بعنوان URL كي يحلل المتصفح سلسلة الاستعلام بشكل صحيح.
    - ينبغي تمرير `token` عبر جزء عنوان URL (`#token=...`) كلما أمكن. لا تُرسل الأجزاء إلى الخادم، ما يتجنب تسرب سجلات الطلبات وReferer. لا تزال معاملات الاستعلام القديمة `?token=` تُستورد مرة واحدة للتوافق، لكن كخيار احتياطي فقط، وتُزال فورًا بعد التمهيد.
    - تُحفظ `password` في الذاكرة فقط.
    - عند تعيين `gatewayUrl`، لا تعود الواجهة إلى بيانات اعتماد التكوين أو البيئة. قدّم `token` (أو `password`) صراحةً. غياب بيانات الاعتماد الصريحة خطأ.
    - استخدم `wss://` عندما يكون Gateway خلف TLS (Tailscale Serve، وكيل HTTPS، إلخ).
    - يُقبل `gatewayUrl` فقط في نافذة من المستوى الأعلى (غير مضمنة) لمنع clickjacking.
    - يجب على عمليات نشر واجهة التحكم غير loopback تعيين `gateway.controlUi.allowedOrigins` صراحةً (الأصول الكاملة). ويشمل ذلك إعدادات التطوير البعيدة.
    - قد يزرع بدء تشغيل Gateway أصولًا محلية مثل `http://localhost:<port>` و`http://127.0.0.1:<port>` من الربط والمنفذ الفعليين وقت التشغيل، لكن أصول المتصفح البعيدة لا تزال تحتاج إلى إدخالات صريحة.
    - لا تستخدم `gateway.controlUi.allowedOrigins: ["*"]` إلا للاختبار المحلي الخاضع للتحكم الصارم. فهذا يعني السماح لأي أصل متصفح، وليس "مطابقة أي مضيف أستخدمه."
    - يفعّل `gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true` وضع الرجوع إلى أصل ترويسة Host، لكنه وضع أمني خطير.

  </Accordion>
</AccordionGroup>

مثال:

```json5
{
  gateway: {
    controlUi: {
      allowedOrigins: ["http://localhost:5173"],
    },
  },
}
```

تفاصيل إعداد الوصول البعيد: [الوصول البعيد](/ar/gateway/remote).

## ذات صلة

- [لوحة المعلومات](/ar/web/dashboard) — لوحة معلومات Gateway
- [فحوصات الصحة](/ar/gateway/health) — مراقبة صحة Gateway
- [TUI](/ar/web/tui) — واجهة مستخدم طرفية
- [WebChat](/ar/web/webchat) — واجهة دردشة مستندة إلى المتصفح