> ## Documentation Index
> Fetch the complete documentation index at: https://docs2.openclaw.ai/llms.txt
> Use this file to discover all available pages before exploring further.

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

<Warning>
  تمت **إزالة** جسر TCP. لا تشحن إصدارات OpenClaw الحالية مستمع الجسر، ولم تعد مفاتيح إعدادات `bridge.*` موجودة في المخطط. تُحفظ هذه الصفحة للمرجع التاريخي فقط. استخدم [بروتوكول Gateway](/ar/gateway/protocol) لكل عملاء العقد/المشغّلين.
</Warning>

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

* **حدّ الأمان**: يعرّض الجسر قائمة سماح صغيرة بدلًا من
  كامل سطح واجهة 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
غير موثّقة؛ يجب ألا يعامل العملاء البصمة المُعلن عنها كتثبيت
موثوق إلا بقصد صريح من المستخدم أو تحقق آخر خارج النطاق.

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

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 (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](/ar/gateway/protocol).

## ذات صلة

* [بروتوكول Gateway](/ar/gateway/protocol)
* [العقد](/ar/nodes)