---
read_when:
    - تريد إدارة Gateway من متصفح
    - تريد الوصول إلى Tailnet دون أنفاق SSH
sidebarTitle: Control UI
summary: واجهة تحكم مستندة إلى المتصفح لـ Gateway (الدردشة، النشاط، العُقد، الإعدادات)
title: واجهة التحكم
x-i18n:
    generated_at: "2026-07-04T20:34:30Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 883e951b304a104a5cb2d0197199d06e372b1b8a25efdfd082ae190575bf409d
    source_path: web/control-ui.md
    workflow: 16
---

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

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

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

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

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

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

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

<Note>
في عمليات ربط شبكة LAN الأصلية على Windows، قد يظل Windows Firewall أو Group Policy المُدار من المؤسسة يحجب عنوان URL المعلن لشبكة LAN حتى عندما يعمل `127.0.0.1` على مضيف Gateway. شغّل `openclaw gateway status --deep` على مضيف Windows؛ فهو يبلّغ عن المنافذ التي يُحتمل أن تكون محجوبة، وحالات عدم تطابق الملف الشخصي، وقواعد جدار الحماية المحلي التي قد تتجاهلها السياسة.
</Note>

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

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

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

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

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

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

<Steps>
  <Step title="سرد الطلبات المعلقة">
    ```bash
    openclaw devices list
    ```
  </Step>
  <Step title="الموافقة حسب معرّف الطلب">
    ```bash
    openclaw devices approve <requestId>
    ```
  </Step>
</Steps>

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

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

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

تستخدم وكلاء Paperclip التي تتصل عبر مهايئ `openclaw_gateway` تدفق الموافقة نفسه في التشغيل الأول. بعد محاولة الاتصال الأولى، شغّل `openclaw devices approve --latest` لمعاينة الطلب المعلق، ثم أعد تشغيل أمر `openclaw devices approve <requestId>` المطبوع للموافقة عليه. مرّر قيماً صريحة لـ `--url` و`--token` من أجل Gateway بعيد. للحفاظ على ثبات الموافقات عبر عمليات إعادة التشغيل، اضبط `adapterConfig.devicePrivateKeyPem` دائماً في Paperclip بدلاً من السماح له بإنشاء هوية جهاز مؤقتة جديدة في كل تشغيل.

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

</Note>

## إقران جهاز محمول

يمكن لمسؤول مقترن بالفعل إنشاء QR اتصال iOS/Android من دون
فتح طرفية:

<Steps>
  <Step title="فتح إقران الهاتف المحمول">
    اختر **العقد**، ثم انقر على **إقران جهاز محمول** في بطاقة **الأجهزة**.
  </Step>
  <Step title="توصيل الهاتف">
    في تطبيق OpenClaw المحمول، افتح **الإعدادات** ← **Gateway** وامسح رمز QR
    ضوئياً. يمكنك نسخ رمز الإعداد ولصقه بدلاً من ذلك.
  </Step>
  <Step title="تأكيد الاتصال">
    يتصل تطبيق iOS/Android الرسمي تلقائياً. إذا أظهرت **الأجهزة** طلباً
    معلقاً، فراجع دوره ونطاقاته قبل الموافقة عليه.
  </Step>
</Steps>

يتطلب إنشاء رمز إعداد `operator.admin`؛ ويكون الزر معطلاً للجلسات
التي لا تملكه. يحتوي رمز الإعداد على اعتماد تمهيدي قصير الأجل،
لذلك تعامل مع QR والرمز المنسوخ مثل كلمة مرور ما داما صالحين. للإقران
عن بُعد، يجب أن يُحل Gateway إلى `wss://` (على سبيل المثال، عبر Tailscale
Serve/Funnel)؛ أما `ws://` العادي فهو محدود بعناوين loopback وشبكة LAN الخاصة.
راجع [الإقران](/ar/channels/pairing#pair-from-the-control-ui-recommended) للحصول على
تفاصيل الأمان والرجوع الكاملة.

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

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

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

## نقطة نهاية تكوين وقت التشغيل

تجلب واجهة التحكم إعدادات وقت التشغيل الخاصة بها من `/control-ui-config.json`، محلولة نسبةً إلى مسار الأساس لواجهة التحكم في Gateway (على سبيل المثال `/__openclaw__/control-ui-config.json` عندما تُقدَّم الواجهة تحت `/__openclaw__/`). هذه النقطة محمية بمصادقة Gateway نفسها مثل بقية سطح 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`.

يتضمن المظهر أيضاً إعداد حجم نص محلياً في المتصفح. يُخزَّن الإعداد مع بقية تفضيلات واجهة التحكم، وينطبق على نص المحادثة، ونص المؤلف، وبطاقات الأدوات، والأشرطة الجانبية للمحادثة، ويحافظ على إدخالات النص بحجم 16px على الأقل حتى لا يقوم Safari المحمول بالتكبير التلقائي عند التركيز.

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

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

<AccordionGroup>
  <Accordion title="المحادثة والتحدث">
    - الدردشة مع النموذج عبر 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 الأكبر المكوّن، ويوجه توجيه الصوت للتشغيل النشط عبر `talk.client.steer` أو `talk.session.steer`.
    - بث استدعاءات الأدوات + بطاقات مخرجات الأدوات الحية في الدردشة (أحداث الوكيل).
    - علامة تبويب النشاط مع ملخصات محلية في المتصفح، تبدأ بالتنقيح، لنشاط الأدوات الحي من تسليم أحداث `session.tool` / الأداة الحالي.

  </Accordion>
  <Accordion title="القنوات، والمثيلات، والجلسات، والأحلام">
    - القنوات: حالة القنوات المدمجة وقنوات Plugins المرفقة/الخارجية، وتسجيل الدخول عبر 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، والعقد، وموافقات التنفيذ">
    - مهام Cron: سرد/إضافة/تحرير/تشغيل/تمكين/تعطيل + سجل التشغيل (`cron.*`).
    - Skills: الحالة، التمكين/التعطيل، التثبيت، تحديثات مفتاح API (`skills.*`).
    - العقد: سرد + القدرات (`node.list`)، وإنشاء رموز إعداد الهاتف المحمول، والموافقة على إقران الجهاز (`device.pair.*`).
    - موافقات التنفيذ: تحرير قوائم السماح للبوابة أو العقدة + سياسة السؤال لـ `exec host=gateway/node` (`exec.approvals.*`).

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

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

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

  </Accordion>
</AccordionGroup>

## صفحة MCP

صفحة MCP المخصصة هي عرض للمشغل لخوادم MCP المُدارة بواسطة OpenClaw ضمن `mcp.servers`. لا تبدأ عمليات نقل MCP بذاتها؛ استخدمها لفحص الإعدادات المحفوظة وتعديلها، ثم استخدم `openclaw mcp doctor --probe` عندما تحتاج إلى إثبات خادم حي.

سير العمل المعتاد:

1. افتح **MCP** من الشريط الجانبي.
2. تحقق من بطاقات الملخص لإجمالي الخوادم، والمفعلة، وOAuth، وعدد الخوادم المصفاة.
3. راجع كل صف خادم لمعرفة النقل، والتمكين، والمصادقة، والتصفيات، والمهلات، وتلميحات الأوامر.
4. بدّل التمكين عندما يجب أن يبقى الخادم مهيأً ولكن خارج اكتشاف وقت التشغيل.
5. حرر قسم إعدادات `mcp` المحدد النطاق لتعريفات الخوادم، والترويسات، ومسارات TLS/mTLS، وبيانات تعريف OAuth، وتصفيات الأدوات، وبيانات تعريف إسقاط Codex.
6. استخدم **حفظ** لكتابة الإعدادات، أو **حفظ ونشر** عندما يجب على Gateway قيد التشغيل تطبيق الإعدادات المتغيرة.
7. شغّل `openclaw mcp status --verbose`، أو `openclaw mcp doctor --probe`، أو `openclaw mcp reload` من طرفية عندما تحتاج العملية المعدلة إلى تشخيصات ثابتة، أو إثبات حي، أو التخلص من وقت التشغيل المخزن مؤقتًا.

تنقح الصفحة القيم الشبيهة بعناوين URL التي تحمل بيانات اعتماد قبل العرض وتضع أسماء الخوادم بين علامات اقتباس في مقتطفات الأوامر بحيث تظل الأوامر المنسوخة تعمل مع المسافات أو المحارف الخاصة بالصدفة. يوجد مرجع CLI والإعدادات الكامل في [MCP](/ar/cli/mcp).

## تبويب النشاط

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

تحتفظ إدخالات النشاط بملخصات مطهرة ومعاينات إخراج منقحة ومقتطعة فقط. لا تُخزن قيم وسيطات الأدوات في حالة النشاط؛ تعرض واجهة المستخدم أن الوسيطات مخفية وتسجل عدد حقول الوسيطات فقط. تتبع القائمة الموجودة في الذاكرة تبويب المتصفح الحالي، وتبقى عبر التنقل داخل واجهة التحكم، وتُعاد ضبطها عند إعادة تحميل الصفحة، أو تبديل الجلسة، أو **مسح**.

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

<AccordionGroup>
  <Accordion title="دلالات الإرسال والسجل">
    - `chat.send` **غير حاجب**: يقر فورًا بـ `{ runId, status: "started" }` وتتدفق الاستجابة عبر أحداث `chat`. قد يتلقى عملاء واجهة التحكم الموثوقون أيضًا بيانات تعريف اختيارية لتوقيت الإقرار للتشخيصات المحلية.
    - تقبل عمليات رفع الدردشة الصور إضافة إلى الملفات غير الفيديو. تحتفظ الصور بمسار الصورة الأصلي؛ وتُخزن الملفات الأخرى كوسائط مُدارة وتظهر في السجل كروابط مرفقات.
    - تعيد إعادة الإرسال باستخدام `idempotencyKey` نفسه `{ status: "in_flight" }` أثناء التشغيل، و`{ status: "ok" }` بعد الاكتمال.
    - تكون استجابات `chat.history` محدودة الحجم لسلامة واجهة المستخدم. عندما تكون إدخالات النص كبيرة جدًا، قد يقتطع Gateway حقول النص الطويلة، ويحذف كتل بيانات التعريف الثقيلة، ويستبدل الرسائل المفرطة الحجم بعنصر نائب (`[chat.history omitted: message too large]`).
    - عندما تُقتطع رسالة مساعد مرئية في `chat.history`، يستطيع القارئ الجانبي جلب إدخال النص الكامل بعد تطبيع العرض عند الطلب عبر `chat.message.get` باستخدام `sessionKey`، و`agentId` النشط عند الحاجة، و`messageId` الخاص بالنص. إذا كان Gateway لا يزال عاجزًا عن إرجاع المزيد، يعرض القارئ حالة عدم توفر صريحة بدلًا من تكرار المعاينة المقتطعة بصمت.
    - تُحفظ الصور المساعدة/المولدة كمراجع وسائط مُدارة وتُقدّم مرة أخرى عبر عناوين 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` في واجهة التحكم إلى إنشاء نفس جلسة لوحة التحكم الجديدة مثل دردشة جديدة والتبديل إليها، إلا عندما يكون `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"` إضافة إلى ملف تعريف مصادقة `openai` بمفتاح API، أو `talk.realtime.providers.openai.apiKey`، أو `OPENAI_API_KEY`؛ لا تهيئ ملفات تعريف OAuth الخاصة بـ OpenAI صوت الوقت الفعلي. هيّئ Google باستخدام `talk.realtime.provider: "google"` إضافة إلى `talk.realtime.providers.google.apiKey`. لا يتلقى المتصفح أبدًا مفتاح API قياسيًا للمزود. يتلقى OpenAI سر عميل وقت فعلي مؤقتًا لـ WebRTC. يتلقى Google Live رمز مصادقة Live API مقيدًا لمرة واحدة لجلسة WebSocket في المتصفح، مع تعليمات وتصريحات أدوات مقفلة داخل الرمز بواسطة Gateway. يعمل المزودون الذين لا يكشفون إلا جسر وقت فعلي خلفيًا عبر نقل ترحيل Gateway، لذلك تبقى بيانات الاعتماد ومقابس البائع من جانب الخادم بينما ينتقل صوت المتصفح عبر RPCs مصادق عليها من Gateway. يُجمع موجه جلسة الوقت الفعلي بواسطة Gateway؛ ولا يقبل `talk.client.create` تجاوزات تعليمات مقدمة من المستدعي.

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

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

    اختبار دخان حيّ للمشرف: يتحقق `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 والدفع عبر الويب

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

إذا عرضت الصفحة **عدم تطابق البروتوكول** مباشرة بعد تحديث OpenClaw، فأعد أولًا فتح لوحة المعلومات باستخدام `openclaw dashboard` ثم أجرِ تحديثًا قسريًا للصفحة. إذا ظلّت تفشل، فامسح بيانات الموقع لأصل لوحة المعلومات أو اختبر في نافذة متصفح خاصة؛ إذ يمكن لعلامة تبويب قديمة أو لذاكرة تخزين مؤقت لعامل خدمة المتصفح أن تواصل تشغيل حزمة Control UI سابقة للتحديث مقابل Gateway الأحدث.

| السطح                                                | ما يفعله                                                           |
| ----------------------------------------------------- | ------------------------------------------------------------------ |
| `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` (الإعداد الافتراضي `https://openclaw.ai`)

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

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

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

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

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

<Tabs>
  <Tab title="strict">
    يعطّل تنفيذ السكربتات داخل التضمينات المستضافة.
  </Tab>
  <Tab title="scripts (default)">
    يسمح بالتضمينات التفاعلية مع الحفاظ على عزل الأصل؛ هذا هو الإعداد الافتراضي وعادةً ما يكون كافيًا لألعاب/ودجات المتصفح المستقلة.
  </Tab>
  <Tab title="trusted">
    يضيف `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`.

## عرض رسائل Chat

تستخدم رسائل Chat المجمّعة حدًا أقصى افتراضيًا للعرض مناسبًا للقراءة. يمكن لعمليات النشر على الشاشات العريضة تجاوزه دون تعديل 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 على local loopback ودع Tailscale Serve يوكّله عبر HTTPS:

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

    افتح:

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

    افتراضيًا، يمكن لطلبات Control UI/WebSocket Serve المصادقة عبر ترويسات هوية Tailscale (`tailscale-user-login`) عندما تكون `gateway.auth.allowTailscale` بقيمة `true`. يتحقق OpenClaw من الهوية بحل عنوان `x-forwarded-for` باستخدام `tailscale whois` ومطابقته مع الترويسة، ولا يقبل هذه الطلبات إلا عندما يصل الطلب إلى local loopback مع ترويسات `x-forwarded-*` الخاصة بـ Tailscale. بالنسبة إلى جلسات مشغّل Control UI ذات هوية جهاز المتصفح، يتخطى مسار 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 اتصالات Control UI دون هوية جهاز.

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

- توافق HTTP غير آمن خاص بـ localhost فقط مع `gateway.controlUi.allowInsecureAuth=true`
- مصادقة Control UI ناجحة للمشغّل عبر `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` هو مفتاح توافق محلي فقط:

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

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

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

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

  </Accordion>
</AccordionGroup>

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

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

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

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

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

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

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

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

- يعيد `GET /avatar/<agentId>` صورة الصورة الرمزية فقط للمستدعين المصادق عليهم. يعيد `GET /avatar/<agentId>?meta=1` بيانات الصورة الرمزية الوصفية بموجب القاعدة نفسها.
- تُرفض الطلبات غير المصادق عليها إلى أي من المسارين (بما يطابق مسار assistant-media الشقيق). يمنع هذا مسار الصورة الرمزية من تسريب هوية الوكيل على المضيفين المحميين بخلاف ذلك.
- تمرّر Control UI نفسها رمز 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.
    - يجب على عمليات نشر واجهة التحكم العامة غير ذات الحلقة الراجعة تعيين `gateway.controlUi.allowedOrigins` صراحةً (الأصول الكاملة). تُقبل تحميلات LAN/Tailnet الخاصة من نفس الأصل من الحلقة الراجعة، أو RFC1918/link-local، أو `.local`، أو `.ts.net`، أو مضيفي Tailscale CGNAT من دون تمكين الرجوع إلى رأس Host.
    - قد يبذر بدء تشغيل 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) — واجهة مستخدم الطرفية
- [دردشة الويب](/ar/web/webchat) — واجهة دردشة مستندة إلى المتصفح