Gateway

بروتوكول الجسر

لماذا كان موجودًا

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

النقل

TCP، كائن JSON واحد لكل سطر (JSONL).
TLS اختياري (عندما تكون bridge.tls.enabled تساوي true).
كان منفذ المستمع الافتراضي تاريخيًا هو 18790 (الإصدارات الحالية لا تبدأ جسر TCP).

عند تفعيل TLS، تتضمن سجلات TXT الخاصة بالاكتشاف bridgeTls=1 بالإضافة إلى bridgeTlsSha256 كتلميح غير سري. لاحظ أن سجلات Bonjour/mDNS TXT غير موثّقة؛ يجب ألا يعامل العملاء البصمة المُعلن عنها كتثبيت موثوق إلا بقصد صريح من المستخدم أو تحقق آخر خارج النطاق.

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

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

تاريخيًا، كانت hello-ok تعيد serverName؛ أما أسطح Plugin المستضافة فتُعلن الآن عبر pluginSurfaceUrls. يستخدم Canvas/A2UI pluginSurfaceUrls.canvas؛ والاسم البديل المهجور canvasHostUrl ليس جزءًا من البروتوكول المعاد هيكلته.

الإطارات

العميل → Gateway:

req / res: استدعاء RPC محدود النطاق لـ Gateway (chat, sessions, config, health, voicewake, skills.bins)
event: إشارات العقدة (نص صوتي، طلب وكيل، اشتراك دردشة، دورة حياة exec)

Gateway → العميل:

invoke / invoke-res: أوامر العقدة (canvas.*, camera.*, screen.record, location.get, sms.send)
event: تحديثات الدردشة للجلسات المشترَك بها
ping / pong: إبقاء الاتصال حيًا

كان فرض قائمة السماح القديمة موجودًا في src/gateway/server-bridge.ts (أُزيل).

أحداث دورة حياة exec

يمكن للعقد إصدار أحداث exec.finished لإظهار نشاط system.run المكتمل. تُعيَّن هذه إلى أحداث النظام في Gateway. (قد تظل العقد القديمة تصدر exec.started.) قد تصدر العقد exec.denied لمحاولات system.run المرفوضة؛ يقبل Gateway الحدث كرفض نهائي ولا يضيف حدث نظام إلى الطابور ولا يوقظ عمل الوكيل.

حقول الحمولة (كلها اختيارية ما لم يُذكر خلاف ذلك):

sessionKey (مطلوب): جلسة الوكيل لربط الأحداث، ولتسليم حدث النظام في exec.finished.
runId: معرّف exec فريد للتجميع.
command: سلسلة الأمر الخام أو المنسقة.
exitCode, timedOut, success, output: تفاصيل الإكمال (للمكتمل فقط).
reason: سبب الرفض (للمرفوض فقط).

استخدام tailnet التاريخي

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

الإصدارات

كان الجسر v1 ضمنيًا (بدون تفاوض حد أدنى/حد أقصى). هذا القسم مرجع تاريخي فقط؛ يستخدم عملاء العقد/المشغّلين الحاليون بروتوكول WebSocket Gateway.