بنية البوابة

آخر تحديث: 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وقت تشغيل الوكيل