الانتقال إلى المحتوى الرئيسي

الأساسيات

بنية البوابة

آخر تحديث: 2026-01-22

نظرة عامة​

  • تملك بوابة واحدة طويلة العمر جميع واجهات المراسلة (WhatsApp عبر Baileys، وTelegram عبر grammY، وSlack، وDiscord، وSignal، وiMessage، وWebChat).
  • تتصل عملاء مستوى التحكم (تطبيق macOS، وCLI، وواجهة الويب، والأتمتة) بالبوابة عبر WebSocket على مضيف الربط المُهيأ (الافتراضي 127.0.0.1:18789).
  • تتصل العقد (macOS/iOS/Android/بدون واجهة) أيضًا عبر WebSocket، لكنها تعلن role: node مع إمكانيات/أوامر صريحة.
  • بوابة واحدة لكل مضيف؛ وهي المكان الوحيد الذي يفتح جلسة WhatsApp.
  • يتم تقديم مضيف اللوحة بواسطة خادم HTTP الخاص بالبوابة تحت:
    • /__openclaw__/canvas/ (HTML/CSS/JS قابلة للتحرير بواسطة الوكيل)
    • /__openclaw__/a2ui/ (مضيف A2UI) يستخدم نفس منفذ البوابة (الافتراضي 18789).

المكونات والتدفقات​

البوابة (البرنامج الخلفي)​

  • تحافظ على اتصالات المزودين.
  • تعرض واجهة برمجة تطبيقات WS مكتوبة (طلبات، ردود، أحداث دفع من الخادم).
  • تتحقق من صحة الإطارات الواردة مقابل مخطط JSON.
  • تصدر أحداثًا مثل agent، chat، presence، health، heartbeat، cron.

العملاء (تطبيق ماك / CLI / واجهة إدارة الويب)​

  • اتصال WS واحد لكل عميل.
  • ترسل طلبات (health، status، send، agent، system-presence).
  • تشترك في الأحداث (tick، agent، presence، shutdown).

العقد (macOS / iOS / Android / بدون واجهة)​

  • تتصل بنفس خادم WS مع role: node.
  • توفر هوية جهاز في connect؛ الاقتران يعتمد على الجهاز (دور node) ويعيش الموافقة في مخزن اقتران الجهاز.
  • تعرض أوامر مثل canvas.*، camera.*، screen.record، location.get.

تفاصيل البروتوكول:

WebChat​

  • واجهة مستخدم ثابتة تستخدم واجهة برمجة تطبيقات WS الخاصة بالبوابة لسجل المحادثة والإرسال.
  • في الإعدادات عن بُعد، تتصل من خلال نفس نفق SSH/Tailscale مثل العملاء الآخرين.

دورة حياة الاتصال (عميل واحد)​

البروتوكول السلكي (ملخص)​

  • النقل: WebSocket، إطارات نصية مع حمولات JSON.
  • يجب أن تكون الإطار الأول connect.
  • بعد المصافحة:
    • الطلبات: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
    • الأحداث: {type:"event", event, payload, seq?, stateVersion?}
  • إذا تم تعيين OPENCLAW_GATEWAY_TOKEN (أو --token)، يجب أن يتطابق connect.params.auth.token أو يُغلق المقبس.
  • مفتاح عدم التأثير مطلوب للطرق ذات الأثر الجانبي (send، agent) لإعادة المحاولة بأمان؛ يحتفظ الخادم بذاكرة تخزين مؤقت قصيرة العمر لإزالة التكرار.
  • يجب أن تتضمن العقد role: "node" بالإضافة إلى الإمكانيات/الأوامر/الأذونات في connect.

الاقتران + الثقة المحلية​

  • تتضمن جميع عملاء WS (المشغلون + العقد) هوية جهاز في connect.
  • تتطلب هويات الأجهزة الجديدة موافقة الاقتران؛ تصدر البوابة رمز جهاز للاتصالات اللاحقة.
  • يمكن الموافقة تلقائيًا على الاتصالات المحلية (العودة المحلية أو عنوان tailnet الخاص بمضيف البوابة نفسه) للحفاظ على تجربة مستخدم سلسة لنفس المضيف.
  • يجب على جميع الاتصالات توقيع قيمة connect.challenge غير المتكررة.
  • تربط الحمولة الموقعة v3 أيضًا platform + deviceFamily؛ تثبت البوابة البيانات الوصفية المقترنة عند إعادة الاتصال وتطلب إصلاح الاقتران لتغييرات البيانات الوصفية.
  • لا تزال الاتصالات غير المحلية تتطلب موافقة صريحة.
  • لا تزال مصادقة البوابة (gateway.auth.*) تنطبق على جميع الاتصالات، محلية أو عن بُعد.

التفاصيل: بروتوكول البوابة، الاقتران، الأمان.

كتابة البروتوكول وإنشاء الشفرة​

  • تحدد مخططات TypeBox البروتوكول.
  • يتم إنشاء مخطط JSON من تلك المخططات.
  • يتم إنشاء نماذج Swift من مخطط JSON.

الوصول عن بُعد​

  • المفضل: Tailscale أو VPN.

  • البديل: نفق SSH

    انسخ

    ssh -N -L 18789:127.0.0.1:18789 user@host

  • تنطبق نفس المصافحة + رمز المصادقة عبر النفق.

  • يمكن تمكين TLS + التثبيت الاختياري لـ WS في الإعدادات عن بُعد.

لقطة العمليات​

  • البدء: openclaw gateway (في المقدمة، السجلات إلى stdout).
  • الصحة: health عبر WS (مضمن أيضًا في hello-ok).
  • الإشراف: launchd/systemd لإعادة التشغيل التلقائي.

الثوابت​

  • تتحكم بوابة واحدة بالضبط في جلسة Baileys واحدة لكل مضيف.
  • المصافحة إلزامية؛ أي إطار أول غير JSON أو غير connect يؤدي إلى إغلاق قاطع.
  • لا يتم إعادة تشغيل الأحداث؛ يجب على العملاء التحديث عند وجود فجوات.

بنية تكامل Piوقت تشغيل الوكيل