معمارية Gateway

# نظرة عامة

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

# المكوّنات والتدفقات

# Gateway (خفي)

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

# العملاء (تطبيق Mac / 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.

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

• بروتوكول Gateway

# WebChat

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

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

sequenceDiagram
    participant Client
    participant Gateway

    Client->>Gateway: req:connect
    Gateway-->>Client: res (ok)
    Note right of Gateway: or res error + close
    Note left of Client: payload=hello-ok
snapshot: presence + health

    Gateway-->>Client: event:presence
    Gateway-->>Client: event:tick

    Client->>Gateway: req:agent
    Gateway-->>Client: res:agent
ack {runId, status:"accepted"}
    Gateway-->>Client: event:agent
(streaming)
    Gateway-->>Client: res:agent
final {runId, status, summary}

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

• النقل: WebSocket، إطارات نصية بحمولات JSON.
• يجب أن يكون الإطار الأول حتماً connect.
• بعد المصافحة:
  • الطلبات: {type:"req", id, method, params} → {type:"res", id, ok, payload|error}
  • الأحداث: {type:"event", event, payload, seq?, stateVersion?}
• hello-ok.features.methods / events هي بيانات وصفية للاكتشاف، وليست تفريغًا مولّدًا لكل مسار مساعد قابل للاستدعاء.
• تستخدم مصادقة السر المشترك connect.params.auth.token أو connect.params.auth.password، حسب وضع مصادقة Gateway المُكوَّن.
• أوضاع حمل الهوية مثل Tailscale Serve (gateway.auth.allowTailscale: true) أو gateway.auth.mode: "trusted-proxy" غير المعتمدة على loopback تستوفي المصادقة من ترويسات الطلب بدلًا من connect.params.auth.*.
• يعطّل gateway.auth.mode: "none" للدخول الخاص مصادقة السر المشترك بالكامل؛ أبقِ هذا الوضع بعيدًا عن الدخول العام/غير الموثوق.
• مفاتيح عدم التكرار مطلوبة للطرق ذات الآثار الجانبية (send، وagent) لإعادة المحاولة بأمان؛ يحتفظ الخادم بذاكرة تخزين مؤقت قصيرة العمر لإزالة التكرارات.
• يجب أن تتضمن العُقد role: "node" إضافة إلى القدرات/الأوامر/الأذونات في connect.

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

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

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

# كتابة أنواع البروتوكول وتوليد الشيفرة

• تعرّف مخططات TypeBox البروتوكول.
• يُولَّد JSON Schema من تلك المخططات.
• تُولَّد نماذج Swift من JSON Schema.

# الوصول البعيد

• المفضّل: 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 لإعادة التشغيل التلقائي.

# الثوابت

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

# ذو صلة

• حلقة الوكيل — دورة تنفيذ الوكيل بالتفصيل
• بروتوكول Gateway — عقد بروتوكول WebSocket
• قائمة الانتظار — قائمة انتظار الأوامر والتزامن
• الأمان — نموذج الثقة والتحصين