Gateway
پروتکل پل
چرا وجود داشت
- مرز امنیتی: بهجای کل سطح API در Gateway، فهرست مجاز کوچکی را در معرض دسترسی قرار میداد.
- جفتسازی + هویت Node: پذیرش Node بر عهدهٔ Gateway بود و به یک توکن مختص هر Node پیوند داشت.
- تجربهٔ کاربری کشف: Nodeها میتوانستند Gatewayها را از طریق Bonjour در LAN کشف کنند یا مستقیماً از طریق یک tailnet متصل شوند.
- WS در Loopback: صفحهٔ کنترل کامل WS محلی باقی میماند، مگر اینکه از طریق SSH تونلسازی میشد.
انتقال
- TCP، یک شیء JSON در هر خط (JSONL).
- TLS اختیاری (
bridge.tls.enabled: true). - درگاه پیشفرض شنونده
18790بود.
وقتی TLS فعال بود، رکوردهای TXT کشف شامل bridgeTls=1 بههمراه bridgeTlsSha256 بهعنوان یک راهنمای غیرمحرمانه بودند. رکوردهای TXT مربوط به Bonjour/mDNS احراز هویت نمیشوند؛ کلاینتها بدون تأیید خارج از باند دیگری نمیتوانستند اثر انگشت اعلامشده را بهعنوان پین معتبر در نظر بگیرند.
دستدهی و جفتسازی
- کلاینت
helloرا همراه با فرادادهٔ Node و توکن (اگر از قبل جفت شده باشد) ارسال میکند. - اگر جفت نشده باشد، Gateway با
error(NOT_PAIRED/UNAUTHORIZED) پاسخ میدهد. - کلاینت
pair-requestرا ارسال میکند. - Gateway منتظر تأیید میماند، سپس
pair-okوhello-okرا ارسال میکند.
hello-ok قبلاً serverName را برمیگرداند؛ سطوح Plugin میزبانیشده اکنون از طریق pluginSurfaceUrls در پروتکل کنونی Gateway اعلام میشوند (Canvas/A2UI از pluginSurfaceUrls.canvas استفاده میکند).
فریمها
از کلاینت به Gateway:
req/res: RPC محدودشدهٔ Gateway (گفتوگو، نشستها، پیکربندی، سلامت، بیدارباش صوتی، skills.bins).event: سیگنالهای Node (رونوشت صوتی، درخواست عامل، اشتراک گفتوگو، چرخهٔ حیات exec).
از Gateway به کلاینت:
invoke/invoke-res: فرمانهای Node (canvas.*،camera.*،screen.record،location.get،sms.send).event: بهروزرسانیهای گفتوگو برای نشستهای مشترکشده.ping/pong: زندهنگهداشتن اتصال.
اعمال فهرست مجاز در src/gateway/server-bridge.ts قرار داشت (حذف شده است).
رویدادهای چرخهٔ حیات exec
Nodeها برای نمایش فعالیت تکمیلشدهٔ system.run، exec.finished را منتشر میکردند که Gateway آن را به رویدادهای سیستم نگاشت میکرد (Nodeهای قدیمی همچنین میتوانستند exec.started را منتشر کنند). exec.denied تلاش ردشدهٔ system.run را بدون قرار دادن رویدادی در صف سیستم یا بیدار کردن کار عامل، بهعنوان رد نهایی علامتگذاری میکرد.
فیلدهای بار داده (همه اختیاریاند مگر آنکه ذکر شده باشد):
| فیلد | توضیحات |
|---|---|
sessionKey |
الزامی. نشست عامل برای همبستگی رویداد و در مورد exec.finished، تحویل رویداد سیستم. |
runId |
شناسهٔ یکتای exec برای گروهبندی. |
command |
رشتهٔ فرمان خام یا قالببندیشده. |
exitCode، timedOut، output |
جزئیات تکمیل (فقط در صورت پایانیافتن). |
reason |
دلیل رد (فقط در صورت ردشدن). |
کاربرد تاریخی tailnet
- پل را به یک IP در tailnet متصل کنید:
bridge.bind: "tailnet"در~/.openclaw/openclaw.json(فقط تاریخی؛bridge.*دیگر پیکربندی معتبری نیست). - کلاینتها از طریق نام MagicDNS یا IP در tailnet متصل میشدند.
- Bonjour از شبکهها عبور نمیکند؛ در غیر این صورت، DNS-SD گسترده یا میزبان/درگاه دستی لازم بود.
نسخهبندی
پل بهطور ضمنی نسخهٔ v1 بود و مذاکرهای برای حداقل/حداکثر نداشت. کلاینتهای کنونی Node/اپراتور از پروتکل Gateway مبتنی بر WebSocket استفاده میکنند که بازهٔ نسخهٔ پروتکل را مذاکره میکند.
