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

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

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

بروتوكول الجسر هو نقل عُقد **قديم** (TCP JSONL). ينبغي لعملاء العُقد الجدد
استخدام بروتوكول Gateway الموحد عبر WebSocket بدلًا من ذلك.

إذا كنت تبني مُشغّلًا أو عميل عُقدة، فاستخدم
[بروتوكول Gateway](/gateway/protocol).

**ملاحظة:** لم تعد إصدارات 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 ضمنيًا** (لا توجد مفاوضة حدّ أدنى/أقصى). يُتوقع التوافق الخلفي؛
أضِف حقل إصدار بروتوكول الجسر قبل أي تغييرات كاسرة.