Gateway
بروتوكول الجسر
سبب وجوده
- الحد الأمني: أتاح قائمة سماح صغيرة بدلًا من كامل سطح واجهة برمجة تطبيقات Gateway.
- الإقران + هوية العقدة: كان Gateway يتولى قبول العقدة ويربطها برمز مميز خاص بكل عقدة.
- تجربة الاكتشاف: كان بإمكان العقد اكتشاف بوابات Gateway عبر Bonjour على الشبكة المحلية، أو الاتصال مباشرة عبر شبكة tailnet.
- WebSocket عبر الاسترجاع المحلي: ظل مستوى تحكم WebSocket الكامل محليًا ما لم يُمرَّر عبر نفق SSH.
النقل
- TCP، كائن JSON واحد في كل سطر (JSONL).
- TLS اختياري (
bridge.tls.enabled: true). - كان منفذ الاستماع الافتراضي
18790.
عند تمكين TLS، كانت سجلات TXT الخاصة بالاكتشاف تتضمن bridgeTls=1 بالإضافة إلى bridgeTlsSha256 كتلميح غير سري. سجلات TXT الخاصة بـ Bonjour/mDNS غير موثَّقة؛ لذا لم يكن بإمكان العملاء التعامل مع البصمة المُعلن عنها كتثبيت موثوق دون تحقق آخر عبر قناة خارجية.
المصافحة والإقران
- يرسل العميل
helloمع بيانات العقدة الوصفية والرمز المميز (إذا كانت مقترنة بالفعل). - إذا لم تكن مقترنة، يرد Gateway بـ
error(NOT_PAIRED/UNAUTHORIZED). - يرسل العميل
pair-request. - ينتظر Gateway الموافقة، ثم يرسل
pair-okوhello-ok.
كان hello-ok يعيد سابقًا serverName؛ أما أسطح Plugin المستضافة فيُعلن عنها الآن عبر pluginSurfaceUrls في بروتوكول Gateway الحالي (تستخدم Canvas/A2UI القيمة pluginSurfaceUrls.canvas).
الإطارات
من العميل إلى Gateway:
req/res: استدعاء RPC محدود النطاق لـ Gateway (الدردشة، الجلسات، الإعداد، الصحة، التنبيه الصوتي،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 لإظهار نشاط system.run المكتمل، وكان Gateway يحوّله إلى أحداث نظام (وكان بإمكان العقد القديمة أيضًا إصدار exec.started). كان exec.denied يحدد محاولة system.run المرفوضة كرفض نهائي دون إدراج حدث نظام في قائمة الانتظار أو إيقاظ عمل الوكيل.
حقول الحمولة (كلها اختيارية ما لم يُذكر خلاف ذلك):
| الحقل | ملاحظات |
|---|---|
sessionKey |
مطلوب. جلسة الوكيل لربط الحدث، ولتسليم حدث النظام في حالة exec.finished. |
runId |
معرّف تنفيذ فريد للتجميع. |
command |
سلسلة الأمر الخام أو المنسقة. |
exitCode، timedOut، output |
تفاصيل الإكمال (للعمليات المكتملة فقط). |
reason |
سبب الرفض (للعمليات المرفوضة فقط). |
الاستخدام التاريخي لشبكة tailnet
- اربط الجسر بعنوان IP على شبكة tailnet:
bridge.bind: "tailnet"في~/.openclaw/openclaw.json(للتوثيق التاريخي فقط؛ لم يعدbridge.*إعدادًا صالحًا). - كان العملاء يتصلون عبر اسم MagicDNS أو عنوان IP على شبكة tailnet.
- لا يعبر Bonjour بين الشبكات؛ لذلك كان يلزم استخدام DNS-SD واسع النطاق أو تحديد المضيف/المنفذ يدويًا.
إدارة الإصدارات
كان الجسر يستخدم الإصدار v1 ضمنيًا، دون تفاوض على حد أدنى/أقصى. يستخدم عملاء العُقد/المشغّلين الحاليون بروتوكول Gateway عبر WebSocket، والذي يتفاوض على نطاق إصدارات البروتوكول.
