پروتکل پل

چرا وجود داشت

• مرز امنیتی: پل به‌جای سطح کامل API مربوط به gateway، یک فهرست مجاز کوچک را در معرض استفاده قرار می‌دهد.
• جفت‌سازی + هویت نود: پذیرش نود تحت مالکیت gateway است و به یک توکن برای هر نود گره خورده است.
• تجربهٔ کاربری کشف: نودها می‌توانند gatewayها را از طریق Bonjour روی LAN کشف کنند، یا مستقیماً از طریق یک tailnet وصل شوند.
• 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 را منتشر کنند تا فعالیت تکمیل‌شدهٔ system.run را نمایان کنند. این‌ها در gateway به رویدادهای سیستم نگاشت می‌شوند. (نودهای قدیمی ممکن است همچنان exec.started را منتشر کنند.) نودها ممکن است برای تلاش‌های ردشدهٔ system.run، رویداد exec.denied را منتشر کنند؛ gateway این رویداد را به‌عنوان رد نهایی می‌پذیرد و هیچ رویداد سیستمی را در صف نمی‌گذارد یا کار عامل را بیدار نمی‌کند.

فیلدهای بار داده (همه اختیاری‌اند مگر اینکه ذکر شده باشد):

• sessionKey (الزامی): نشست عامل برای هم‌بستگی رویداد و، برای exec.finished، تحویل رویداد سیستم.
• runId: شناسهٔ اجرای یکتا برای گروه‌بندی.
• 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 ضمنی بود (بدون مذاکرهٔ حداقل/حداکثر). این بخش فقط ارجاع تاریخی است؛ کلاینت‌های نود/اپراتور فعلی از WebSocket پروتکل Gateway استفاده می‌کنند.

مرتبط

• پروتکل Gateway
• نودها