البروتوكولات وواجهات البرمجة (APIs)

بروتوكول الجسر (Bridge)

بروتوكول الجسر هو بروتوكول نقل قديم للعقد (TCP JSONL). يجب على عملاء العقد الجدد استخدام بروتوكول Gateway WebSocket الموحد بدلاً من ذلك. إذا كنت تبني مشغلاً أو عميل عقدة، فاستخدم بروتوكول البوابة. ملاحظة: إصدارات OpenClaw الحالية لم تعد تتضمن مستمع الجسر (TCP bridge)؛ تم الاحتفاظ بهذا الوثيقة للرجوع التاريخي فقط. مفاتيح التكوين القديمة bridge.* لم تعد جزءًا من مخطط التكوين.

لماذا لدينا الاثنان معًا

  • حدود الأمان: يعرض الجسر قائمة سماح صغيرة بدلاً من سطح واجهة برمجة التطبيقات الكامل للبوابة.
  • الإقران + هوية العقدة: عملية قبول العقدة مملوكة للبوابة ومرتبطة برمز خاص بكل عقدة.
  • تجربة اكتشاف العقد (Discovery UX): يمكن للعقد اكتشاف البوابات عبر Bonjour على الشبكة المحلية (LAN)، أو الاتصال مباشرة عبر شبكة الذيل (tailnet).
  • WebSocket المحلي (Loopback WS): يبقى مستوى التحكم الكامل عبر WebSocket محليًا ما لم يتم نقله عبر 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: استدعاءات برمجة البوابة ذات النطاق (الدردشة، الجلسات، التكوين، الحالة، voicewake، skills.bins)
  • event: إشارات من العقدة (نص صوتي، طلب وكيل، اشتراك دردشة، دورة حياة التنفيذ)

من البوابة → إلى العميل:

  • invoke / invoke-res: أوامر للعقدة (canvas.*, camera.*, screen.record, location.get, sms.send)
  • event: تحديثات الدردشة للجلسات المشتركة فيها
  • ping / pong: إبقاء الاتصال نشطًا (keepalive)

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

أحداث دورة حياة التنفيذ

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

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

الاستخدام عبر شبكة الذيل (Tailnet)

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

إدارة الإصدارات

الجسر حاليًا هو الإصدار الضمني v1 (لا يوجد تفاوض على الحد الأدنى/الأقصى). من المتوقع الحفاظ على التوافق مع الإصدارات السابقة؛ يجب إضافة حقل إصدار بروتوكول الجسر قبل أي تغييرات غير متوافقة.

بروتوكول البوابةOpenAI Chat Completions