واجهة التحكم

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

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

تتحدث مباشرة مع WebSocket الخاص بالبوابة على نفس المنفذ.

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

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

• http://127.0.0.1:18789/ (أو http://localhost:18789/)

إذا فشلت الصفحة في التحميل، ابدأ البوابة أولاً: openclaw gateway. يتم توفير المصادقة أثناء مصافحة WebSocket عبر:

• connect.params.auth.token
• connect.params.auth.password تتيح لك لوحة إعدادات لوحة التحكم تخزين رمز مميز؛ كلمات المرور لا يتم الاحتفاظ بها. يقوم معالج الإعداد الأولي بإنشاء رمز بوابة افتراضيًا، لذا الصقه هنا عند الاتصال لأول مرة.

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

عندما تتصل بواجهة التحكم من متصفح أو جهاز جديد، تتطلب البوابة موافقة إقران لمرة واحدة — حتى إذا كنت على نفس شبكة Tailnet مع gateway.auth.allowTailscale: true. هذه إجراء أمان لمنع الوصول غير المصرح به. ما ستراه: "مفصول (1008): مطلوب إقران" للموافقة على الجهاز:

# عرض الطلبات المعلقة
openclaw devices list

# الموافقة باستخدام معرف الطلب
openclaw devices approve <requestId>

بمجرد الموافقة، يتم تذكر الجهاز ولن يحتاج إلى إعادة الموافقة ما لم تقم بإلغائه باستخدام openclaw devices revoke --device <id> --role <role>. راجع أجهزة CLI لدوران الرمز المميز والإلغاء. ملاحظات:

• يتم الموافقة تلقائيًا على الاتصالات المحلية (127.0.0.1).
• تتطلب الاتصالات البعيدة (شبكة محلية LAN، شبكة Tailnet، إلخ.) موافقة صريحة.
• يولد كل ملف تعريف متصفح معرف جهاز فريد، لذا فإن التبديل بين المتصفحات أو مسح بيانات المتصفح سيتطلب إعادة إقران.

دعم اللغة

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

• اللغات المدعومة: en, zh-CN, zh-TW, pt-BR, de, es
• يتم تحميل الترجمات غير الإنجليزية بشكل كسول في المتصفح.
• يتم حفظ اللغة المحددة في تخزين المتصفح وإعادة استخدامها في الزيارات المستقبلية.
• تعود مفاتيح الترجمة المفقودة إلى اللغة الإنجليزية.

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

• الدردشة مع النموذج عبر بوابة WS (chat.history, chat.send, chat.abort, chat.inject)
• بث استدعاءات الأدوات + بطاقات إخراج الأدوات المباشرة في الدردشة (أحداث الوكيل)
• القنوات: WhatsApp/Telegram/Discord/Slack + قنوات الإضافات (Mattermost، إلخ.) الحالة + تسجيل الدخول عبر QR + تهيئة لكل قناة (channels.status, web.login.*, config.patch)
• الحالات: قائمة الحضور + تحديث (system-presence)
• الجلسات: قائمة + تجاوزات التفكير/المفصلة لكل جلسة (sessions.list, sessions.patch)
• مهام cron: قائمة/إضافة/تحرير/تشغيل/تمكين/تعطيل + سجل التشغيل (cron.*)
• المهارات: الحالة، تمكين/تعطيل، تثبيت، تحديثات مفتاح API (skills.*)
• العقد: قائمة + إمكانيات (node.list)
• موافقات التنفيذ: تحرير قوائم السماح للبوابة أو العقدة + سياسة السؤال لـ exec host=gateway/node (exec.approvals.*)
• التهيئة: عرض/تحرير ~/.openclaw/openclaw.json (config.get, config.set)
• التهيئة: تطبيق + إعادة التشغيل مع التحقق (config.apply) وإيقاظ آخر جلسة نشطة
• تتضمن كتابات التهيئة حماية hash أساسي لمنع الكتابة فوق التعديلات المتزامنة
• مخطط التهيئة + عرض النموذج (config.schema، بما في ذلك مخططات الإضافات والقنوات)؛ يبقى محرر JSON الخام متاحًا
• التصحيح: لقطات الحالة/الصحة/النماذج + سجل الأحداث + استدعاءات RPC يدوية (status, health, models.list)
• السجلات: تتبع مباشر لسجلات ملفات البوابة مع التصفية/التصدير (logs.tail)
• التحديث: تشغيل تحديث حزمة/git + إعادة تشغيل (update.run) مع تقرير إعادة تشغيل

ملاحظات لوحة مهام cron:

• للمهام المعزولة، يكون التسليم الافتراضي هو الإعلان عن الملخص. يمكنك التبديل إلى لا شيء إذا كنت تريد تشغيلات داخلية فقط.
• تظهر حقول القناة/الهدف عند اختيار الإعلان.
• يستخدم وضع Webhook delivery.mode = "webhook" مع تعيين delivery.to إلى عنوان URL صالح لـ webhook HTTP(S).
• لمهام الجلسة الرئيسية، أوضاع التسليم webhook ولا شيء متاحة.
• تتضمن عناصر التحكم المتقدمة للتحرير حذف بعد التشغيل، مسح تجاوز الوكيل، خيارات cron الدقيقة/المتقطعة، تجاوزات نموذج/تفكير الوكيل، وتبديلات التسليم بأفضل جهد.
• التحقق من صحة النموذج مضمن مع أخطاء على مستوى الحقل؛ تعطل القيم غير الصالحة زر الحفظ حتى يتم إصلاحها.
• اضبط cron.webhookToken لإرسال رمز مميز حامل مخصص، إذا تم حذفه يتم إرسال webhook بدون رأس مصادقة.
• تراجع قديم: يمكن للمهام القديمة المخزنة مع notify: true الاستمرار في استخدام cron.webhook حتى يتم ترحيلها.

سلوك الدردشة

• chat.send غير معيق: يتم الإقرار به فورًا بـ { runId, status: "started" } ويتم بث الاستجابة عبر أحداث chat.
• إعادة الإرسال بنفس idempotencyKey تُرجع { status: "in_flight" } أثناء التشغيل، و { status: "ok" } بعد الانتهاء.
• استجابات chat.history محدودة الحجم لأمان واجهة المستخدم. عندما تكون إدخالات النص كبيرة جدًا، قد تقوم البوابة بقطع حقول النص الطويلة، وحذف كتل البيانات الوصفية الثقيلة، واستبدال الرسائل كبيرة الحجم بعنصر نائب ([chat.history omitted: message too large]).
• chat.inject يلحق ملاحظة مساعد بنص الجلسة ويبث حدث chat للتحديثات الخاصة بواجهة المستخدم فقط (لا تشغيل وكيل، لا تسليم قناة).
• إيقاف:
  • انقر إيقاف (يستدعي chat.abort)
  • اكتب /stop (أو عبارات إيقاف مستقلة مثل stop, stop action, stop run, stop openclaw, please stop) للإجهاض خارج النطاق
  • يدعم chat.abort { sessionKey } (بدون runId) لإجهاض جميع عمليات التشغيل النشطة لتلك الجلسة
• الاحتفاظ الجزئي عند الإجهاض:
  • عند إجهاض عملية تشغيل، لا يزال يمكن عرض نص المساعد الجزئي في واجهة المستخدم
  • تقوم البوابة باستمرار نص المساعد الجزئي المجهض في سجل النص عند وجود إخراج مخزن مؤقت
  • تتضمن الإدخالات المستمرة بيانات وصفية للإجهاض حتى يتمكن مستهلكو النص من التمييز بين الأجزاء المجهضة وإخراج الإكمال العادي

الوصول عبر شبكة Tailnet (موصى به)

Tailscale Serve المدمج (مفضل)

احتفظ بالبوابة على loopback ودع Tailscale Serve يعمل كوكيل لها مع HTTPS:

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 مع رؤوس x-forwarded-* الخاصة بـ Tailscale. اضبط gateway.auth.allowTailscale: false (أو فرض gateway.auth.mode: "password") إذا كنت تريد مطالبة برمز/كلمة مرور حتى لحركة مرور Serve. تفترض مصادقة Serve بدون رمز أن مضيف البوابة موثوق به. إذا كان هناك كود محلي غير موثوق قد يعمل على ذلك المضيف، فاطلب مصادقة الرمز/كلمة المرور.

الربط بشبكة tailnet + رمز

openclaw gateway --bind tailnet --token "$(openssl rand -hex 32)"

ثم افتح:

• http://<tailscale-ip>:18789/ (أو gateway.controlUi.basePath الذي قمت بتكوينه)

الصق الرمز في إعدادات واجهة المستخدم (يتم إرساله كـ connect.params.auth.token).

HTTP غير الآمن

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

• https://<magicdns>/ (Serve)
• http://127.0.0.1:18789/ (على مضيف البوابة)

سلوك تبديل المصادقة غير الآمنة:

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

allowInsecureAuth لا يتجاوز هوية جهاز واجهة التحكم أو فحوصات الإقران. لحالات الطوارئ فقط:

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

dangerouslyDisableDeviceAuth يعطل فحوصات هوية جهاز واجهة التحكم وهو تخفيض شديد للأمان. ارجع بسرعة بعد الاستخدام الطارئ. راجع Tailscale للحصول على إرشادات إعداد HTTPS.

بناء واجهة المستخدم

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

pnpm ui:build # يقوم بتثبيت تبعات واجهة المستخدم تلقائيًا في التشغيل الأول

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

OPENCLAW_CONTROL_UI_BASE_PATH=/openclaw/ pnpm ui:build

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

pnpm ui:dev # يقوم بتثبيت تبعات واجهة المستخدم تلقائيًا في التشغيل الأول

ثم وجه واجهة المستخدم إلى عنوان URL لـ WebSocket الخاص بالبوابة (مثال: ws://127.0.0.1:18789).

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

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

1. ابدأ خادم تطوير واجهة المستخدم: pnpm ui:dev
2. افتح عنوان URL مثل:

http://localhost:5173/?gatewayUrl=ws://<gateway-host>:18789

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

http://localhost:5173/?gatewayUrl=wss://<gateway-host>:18789#token=<gateway-token>

ملاحظات:

• يتم تخزين gatewayUrl في localStorage بعد التحميل وإزالته من عنوان URL.
• يتم استيراد token إلى الذاكرة للتبويب الحالي وإزالته من عنوان URL؛ لا يتم تخزينه في localStorage.
• يتم الاحتفاظ بـ password في الذاكرة فقط.
• عند تعيين gatewayUrl، لا تعود واجهة المستخدم إلى بيانات اعتماد التكوين أو البيئة. قدم token (أو password) صراحةً. يُعد عدم وجود بيانات اعتماد صريحة خطأ.
• استخدم wss:// عندما تكون البوابة خلف TLS (Tailscale Serve، وكيل HTTPS، إلخ.).
• يتم قبول gatewayUrl فقط في نافذة من المستوى الأعلى (غير مضمنة) لمنع سرقة النقر.
• يجب على نُشر واجهة التحكم غير loopback تعيين gateway.controlUi.allowedOrigins صراحةً (الأصول الكاملة). يتضمن ذلك إعدادات التطوير البعيدة.
• gateway.controlUi.dangerouslyAllowHostHeaderOriginFallback=true يمكّن وضع التراجع لأصل رأس المضيف، ولكنه وضع أمان خطير.

مثال:

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

تفاصيل إعداد الوصول البعيد: الوصول البعيد.

الويبلوحة التحكم