---
read_when:
    - إنشاء عملاء العقد أو تصحيحهم (وضع العقدة على iOS/Android/macOS)
    - التحقيق في حالات فشل الاقتران أو مصادقة الجسر
    - تدقيق سطح العقدة الذي تكشفه البوابة
summary: 'بروتوكول الجسر التاريخي (العقد القديمة): TCP JSONL، والاقتران، وRPC محدد النطاق'
title: بروتوكول الجسر
x-i18n:
    generated_at: "2026-04-05T12:42:13Z"
    model: gpt-5.4
    provider: openai
    source_hash: 2bc25c388f3d65944167d05ca78f987c84ca480f0213e3485b118ebf4858c50f
    source_path: gateway/bridge-protocol.md
    workflow: 15
---

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

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

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

- **حد أمني**: يكشف الجسر قائمة سماح صغيرة بدلًا من
  سطح API الكامل للبوابة.
- **الاقتران + هوية العقدة**: تتحكم البوابة في قبول العقدة ويكون
  مرتبطًا برمز مميز لكل عقدة.
- **تجربة الاكتشاف**: يمكن للعقد اكتشاف البوابات عبر Bonjour على LAN، أو الاتصال
  مباشرة عبر tailnet.
- **Loopback WS**: تبقى طبقة التحكم الكاملة عبر WS محلية ما لم يتم نفقها عبر SSH.

## النقل

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

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

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

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

تاريخيًا، كانت `hello-ok` تعيد `serverName` وكان يمكن أن تتضمن
`canvasHostUrl`.

## الإطارات

العميل → البوابة:

- `req` / `res`: ‏RPC للبوابة محدد النطاق (chat، وsessions، وconfig، وhealth، وvoicewake، وskills.bins)
- `event`: إشارات العقدة (نص صوتي منسوخ، وطلب وكيل، واشتراك chat، ودورة حياة exec)

البوابة → العميل:

- `invoke` / `invoke-res`: أوامر العقدة (`canvas.*` و`camera.*` و`screen.record`،
  و`location.get` و`sms.send`)
- `event`: تحديثات chat للجلسات المشتركة
- `ping` / `pong`: keepalive

كانت آلية فرض قائمة السماح القديمة موجودة في `src/gateway/server-bridge.ts` (تمت إزالتها).

## أحداث دورة حياة Exec

يمكن للعقد إصدار أحداث `exec.finished` أو `exec.denied` لإظهار نشاط system.run.
ويتم ربط هذه الأحداث بأحداث نظام في البوابة. (قد تستمر العقد القديمة في إصدار `exec.started`.)

حقول الحمولة (كلها اختيارية ما لم يُذكر خلاف ذلك):

- `sessionKey` (مطلوب): جلسة الوكيل التي ستتلقى حدث النظام.
- `runId`: معرّف exec فريد للتجميع.
- `command`: سلسلة الأمر الخام أو المنسقة.
- `exitCode` و`timedOut` و`success` و`output`: تفاصيل الإكمال (لـ finished فقط).
- `reason`: سبب الرفض (لـ denied فقط).

## استخدام tailnet التاريخي

- اربط الجسر بعنوان IP من tailnet: ‏`bridge.bind: "tailnet"` في
  `~/.openclaw/openclaw.json` (تاريخي فقط؛ `bridge.*` لم يعد صالحًا).
- يتصل العملاء عبر اسم MagicDNS أو عنوان IP من tailnet.
- لا يعبر Bonjour **الشبكات**؛ استخدم المضيف/المنفذ اليدويين أو DNS‑SD واسع النطاق
  عند الحاجة.

## الإصدارات

كان الجسر **v1 ضمنيًا** (من دون تفاوض min/max). هذا القسم
مرجع تاريخي فقط؛ يستخدم عملاء العقدة/المشغلين الحاليون WebSocket
[بروتوكول Gateway](/gateway/protocol).
