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

# سبب وجوده

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

# النقل

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

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

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

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

تاريخياً، كان hello-ok يعيد serverName؛ أما أسطح Plugin المستضافة فتُعلن الآن من خلال pluginSurfaceUrls. يستخدم Canvas/A2UI pluginSurfaceUrls.canvas؛ والاسم المستعار المهمل 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 (تاريخي فقط؛ لم يعد bridge.* صالحاً).
• يتصل العملاء عبر اسم MagicDNS أو عنوان IP على tailnet.
• لا يعبر Bonjour الشبكات؛ استخدم المضيف/المنفذ اليدوي أو DNS-SD واسع النطاق عند الحاجة.

# ضبط الإصدارات

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

# ذات صلة

• بروتوكول Gateway
• العُقد