---
read_when:
    - بناء عملاء Node أو تصحيح أخطائهم (وضع Node في iOS/Android/macOS)
    - استقصاء إخفاقات الاقتران أو مصادقة الجسر
    - تدقيق سطح Node الذي يكشفه Gateway
summary: 'بروتوكول الجسر التاريخي (العُقد القديمة): TCP JSONL، والاقتران، وRPC محدد النطاق'
title: بروتوكول الجسر
x-i18n:
    generated_at: "2026-05-07T13:17:30Z"
    model: gpt-5.5
    provider: openai
    source_hash: fc906ca3a8a4ebef9b39c53187bcb4d06b287875b8e8748a168812f9a52e6152
    source_path: gateway/bridge-protocol.md
    workflow: 16
---

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

## سبب وجوده

- **حدّ الأمان**: يعرّض الجسر قائمة سماح صغيرة بدلاً من
  كامل سطح واجهة برمجة تطبيقات 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](/ar/gateway/protocol).

## ذات صلة

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