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

​
بروتوكول الجسر (نقل العُقد القديمة)

بروتوكول الجسر هو نقل عُقد قديم (TCP JSONL). ينبغي لعملاء العُقد الجدد استخدام بروتوكول Gateway الموحد عبر WebSocket بدلًا من ذلك. إذا كنت تبني مُشغّلًا أو عميل عُقدة، فاستخدم بروتوكول Gateway. ملاحظة: لم تعد إصدارات OpenClaw الحالية تُضمّن مستمع جسر TCP؛ ويُحتفَظ بهذه الوثيقة للمرجعية التاريخية. لم تعد مفاتيح التهيئة القديمة bridge.* جزءًا من مخطط التهيئة.

​
لماذا لدينا الاثنان معًا

  • حدّ أمني: يعرِض الجسر قائمة سماح صغيرة بدلًا من السطح الكامل لواجهة برمجة تطبيقات الـ Gateway.
  • الإقران + هوية العُقدة: قبول العُقد مملوك للـ Gateway ومرتبط برمز مميّز لكل عُقدة.
  • تجربة الاكتشاف: يمكن للعُقد اكتشاف الـ Gateway عبر Bonjour على الشبكة المحلية، أو الاتصال مباشرة عبر tailnet.
  • WS عبر loopback: يبقى مستوى التحكم الكامل عبر WebSocket محليًا ما لم يتم تمريره عبر SSH.

​
النقل

  • TCP، كائن JSON واحد لكل سطر (JSONL).
  • TLS اختياري (عندما يكون bridge.tls.enabled مفعّلًا).
  • كان منفذ الاستماع الافتراضي القديم هو 18790 (الإصدارات الحالية لا تبدأ جسر TCP).
عند تمكين TLS، تتضمن سجلات TXT للاكتشاف bridgeTls=1 بالإضافة إلى bridgeTlsSha256 لكي تتمكن العُقد من تثبيت الشهادة. لاحظ أن سجلات Bonjour/mDNS TXT غير موثَّقة؛ يجب ألا يتعامل العملاء مع البصمة المُعلَن عنها على أنها بصمة معتمدة دون نية صريحة من المستخدم أو تحقق آخر خارج النطاق.

​
المصافحة + الإقران

  1. يرسل العميل hello مع بيانات تعريف العُقدة + الرمز المميّز (إن كانت مقترنة مسبقًا).
  2. إذا لم تكن مقترنة، يردّ الـ Gateway بـ error (NOT_PAIRED/UNAUTHORIZED).
  3. يرسل العميل pair-request.
  4. ينتظر الـ Gateway الموافقة، ثم يرسل pair-ok و hello-ok.
يعيد hello-ok القيمة serverName وقد يتضمن canvasHostUrl.

​
الإطارات

من العميل → الـ Gateway:
  • req / res: استدعاء RPC للـ Gateway ضمن نطاق محدد (الدردشة، الجلسات، التهيئة، الصحة، voicewake، skills.bins)
  • event: إشارات العُقدة (نصّ الصوت، طلب الوكيل، الاشتراك في الدردشة، دورة حياة التنفيذ)
من الـ Gateway → العميل:
  • invoke / invoke-res: أوامر العُقدة (canvas.*، camera.*، screen.record، location.get، sms.send)
  • event: تحديثات الدردشة للجلسات المُشترَك فيها
  • ping / pong: إبقاء الاتصال حيًا
كان تطبيق قائمة السماح القديمة موجودًا في src/gateway/server-bridge.ts (أُزيل).

​
أحداث دورة حياة التنفيذ

يمكن للعُقد إصدار أحداث exec.finished أو exec.denied لإظهار نشاط system.run. تُعيَّن هذه إلى أحداث نظام داخل الـ Gateway. (قد تواصل العُقد القديمة إصدار exec.started.) حقول الحمولة (جميعها اختيارية ما لم يُذكر خلاف ذلك):
  • sessionKey (مطلوب): جلسة الوكيل التي ستتلقى حدث النظام.
  • runId: معرّف تنفيذ فريد للتجميع.
  • command: سلسلة الأمر الخام أو المنسّقة.
  • exitCode، timedOut، success، output: تفاصيل الإكمال (عند الانتهاء فقط).
  • reason: سبب الرفض (عند الرفض فقط).

​
استخدام tailnet

  • اربط الجسر بعنوان IP ضمن tailnet: bridge.bind: "tailnet" في ~/.openclaw/openclaw.json.
  • يتصل العملاء عبر اسم MagicDNS أو عنوان IP ضمن tailnet.
  • لا يعبر Bonjour الشبكات؛ استخدم المضيف/المنفذ يدويًا أو DNS‑SD واسع النطاق عند الحاجة.

​
الإصدارات

الجسر حاليًا v1 ضمنيًا (لا توجد مفاوضة حدّ أدنى/أقصى). يُتوقع التوافق الخلفي؛ أضِف حقل إصدار بروتوكول الجسر قبل أي تغييرات كاسرة.