جفت‌سازی تحت مالکیت Gateway

در جفت‌سازی تحت مالکیت Gateway، Gateway مرجع حقیقت برای این است که کدام Nodeها مجاز به پیوستن هستند. UIها (برنامه macOS، کلاینت‌های آینده) فقط فرانت‌اندهایی هستند که درخواست‌های در انتظار را تأیید یا رد می‌کنند.

مهم: Nodeهای WS هنگام connect از جفت‌سازی دستگاه (نقش node) استفاده می‌کنند. node.pair.* یک محل ذخیره جفت‌سازی جداگانه است و دست‌دهی WS را کنترل نمی‌کند. فقط کلاینت‌هایی که صراحتاً node.pair.* را فراخوانی می‌کنند از این جریان استفاده می‌کنند.

مفاهیم

• درخواست در انتظار: یک Node درخواست پیوستن داده است؛ نیازمند تأیید است.
• Node جفت‌شده: Node تأییدشده با توکن احراز هویت صادرشده.
• انتقال: نقطه پایانی WS در Gateway درخواست‌ها را فوروارد می‌کند اما درباره عضویت تصمیم نمی‌گیرد. (پشتیبانی قدیمی پل TCP حذف شده است.)

جفت‌سازی چگونه کار می‌کند

1. یک Node به WS Gateway وصل می‌شود و جفت‌سازی را درخواست می‌کند.
2. Gateway یک درخواست در انتظار ذخیره می‌کند و node.pair.requested را منتشر می‌کند.
3. شما درخواست را تأیید یا رد می‌کنید (CLI یا UI).
4. پس از تأیید، Gateway یک توکن جدید صادر می‌کند (توکن‌ها هنگام جفت‌سازی مجدد چرخش می‌یابند).
5. Node با استفاده از توکن دوباره وصل می‌شود و اکنون «جفت‌شده» است.

درخواست‌های در انتظار پس از 5 دقیقه به‌طور خودکار منقضی می‌شوند.

گردش‌کار CLI (مناسب برای محیط‌های بدون رابط گرافیکی)

openclaw nodes pendingopenclaw nodes approve <requestId>openclaw nodes reject <requestId>openclaw nodes statusopenclaw nodes remove --node <id|name|ip>openclaw nodes rename --node <id|name|ip> --name "Living Room iPad"

nodes status Nodeهای جفت‌شده/متصل و قابلیت‌های آن‌ها را نشان می‌دهد.

سطح API (پروتکل Gateway)

رویدادها:

• node.pair.requested - هنگامی منتشر می‌شود که یک درخواست در انتظار جدید ایجاد شود.
• node.pair.resolved - هنگامی منتشر می‌شود که یک درخواست تأیید/رد/منقضی شود.

متدها:

• node.pair.request - یک درخواست در انتظار ایجاد می‌کند یا از درخواست موجود دوباره استفاده می‌کند.
• node.pair.list - Nodeهای در انتظار + جفت‌شده را فهرست می‌کند (operator.pairing).
• node.pair.approve - یک درخواست در انتظار را تأیید می‌کند (توکن صادر می‌کند).
• node.pair.reject - یک درخواست در انتظار را رد می‌کند.
• node.pair.remove - یک Node جفت‌شده را حذف می‌کند. برای جفت‌سازی‌های مبتنی بر دستگاه، این کار نقش node دستگاه را لغو می‌کند: devices/paired.json را تغییر می‌دهد و نشست‌های نقش-Node آن دستگاه را نامعتبر/قطع می‌کند. یک دستگاه چندنقشی (مثلاً هم‌زمان operator هم دارد) ردیف خود را نگه می‌دارد و فقط نقش node را از دست می‌دهد؛ ردیف دستگاهی که فقط Node است حذف می‌شود. همچنین هر ورودی قدیمی منطبق از جفت‌سازی Node تحت مالکیت Gateway را حذف می‌کند. Authz: operator.pairing می‌تواند ردیف‌های Node غیر-operator را حذف کند؛ فراخواننده‌ای با توکن دستگاه که نقش Node خودش را روی یک دستگاه چندنقشی لغو می‌کند، علاوه بر آن به operator.admin نیاز دارد.
• node.pair.verify - { nodeId, token } را تأیید می‌کند.

نکات:

• node.pair.request برای هر Node همانی است: فراخوانی‌های تکراری همان درخواست در انتظار را برمی‌گردانند.
• درخواست‌های تکراری برای همان Node در انتظار، فراداده ذخیره‌شده Node و آخرین اسنپ‌شات دستورات اعلام‌شده مجازشده برای دیدپذیری operator را نیز تازه‌سازی می‌کنند.
• تأیید همیشه یک توکن تازه تولید می‌کند؛ هیچ توکنی هرگز از node.pair.request برگردانده نمی‌شود.
• سطوح محدوده operator و بررسی‌های زمان تأیید در محدوده‌های operator خلاصه شده‌اند.
• درخواست‌ها می‌توانند silent: true را به‌عنوان راهنما برای جریان‌های تأیید خودکار شامل شوند.
• node.pair.approve از دستورات اعلام‌شده درخواست در انتظار برای اعمال محدوده‌های تأیید اضافی استفاده می‌کند:
  • درخواست بدون دستور: operator.pairing
  • درخواست دستور غیر-exec: operator.pairing + operator.write
  • درخواست system.run / system.run.prepare / system.which: operator.pairing + operator.admin

کنترل دستورات Node (2026.3.31+)

وقتی یک Node برای اولین بار متصل می‌شود، جفت‌سازی به‌طور خودکار درخواست می‌شود. تا زمانی که درخواست جفت‌سازی تأیید نشود، همه دستورات در انتظار Node از آن Node فیلتر می‌شوند و اجرا نخواهند شد. پس از برقراری اعتماد از طریق تأیید جفت‌سازی، دستورات اعلام‌شده Node مطابق سیاست معمول دستورات در دسترس قرار می‌گیرند.

این یعنی:

• Nodeهایی که پیش‌تر برای در معرض قرار دادن دستورات فقط به جفت‌سازی دستگاه متکی بودند، اکنون باید جفت‌سازی Node را کامل کنند.
• دستوراتی که پیش از تأیید جفت‌سازی در صف قرار گرفته‌اند حذف می‌شوند، نه اینکه به تعویق بیفتند.

مرزهای اعتماد رویداد Node (2026.3.31+)

خلاصه‌های منشأگرفته از Node و رویدادهای نشست مرتبط به سطح اعتماد موردنظر محدود می‌شوند. جریان‌های مبتنی بر اعلان یا راه‌اندازی‌شده توسط Node که پیش‌تر به دسترسی گسترده‌تر ابزار host یا نشست متکی بودند، ممکن است نیازمند تنظیم باشند. این سخت‌سازی تضمین می‌کند که رویدادهای Node نتوانند فراتر از آنچه مرز اعتماد Node اجازه می‌دهد، به دسترسی ابزار در سطح host ارتقا پیدا کنند.

به‌روزرسانی‌های پایدار حضور Node از همان مرز هویت پیروی می‌کنند. رویداد node.presence.alive فقط از نشست‌های دستگاه Node احراز هویت‌شده پذیرفته می‌شود و فقط زمانی فراداده جفت‌سازی را به‌روزرسانی می‌کند که هویت دستگاه/Node از قبل جفت شده باشد. مقدارهای خوداعلام‌شده client.id برای نوشتن وضعیت آخرین مشاهده کافی نیستند.

تأیید خودکار (برنامه macOS)

برنامه macOS می‌تواند به‌صورت اختیاری هنگامی یک تأیید خاموش را امتحان کند که:

• درخواست با silent علامت‌گذاری شده باشد، و
• برنامه بتواند یک اتصال SSH به host Gateway را با همان کاربر تأیید کند.

اگر تأیید خاموش شکست بخورد، به اعلان معمول «تأیید/رد» برمی‌گردد.

تأیید خودکار دستگاه با CIDRهای مورد اعتماد

جفت‌سازی دستگاه WS برای role: node به‌صورت پیش‌فرض دستی باقی می‌ماند. برای شبکه‌های خصوصی Node که در آن‌ها Gateway از قبل مسیر شبکه را مورد اعتماد می‌داند، operatorها می‌توانند با CIDRهای صریح یا IPهای دقیق فعال‌سازی کنند:

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

مرز امنیتی:

• وقتی gateway.nodes.pairing.autoApproveCidrs تنظیم نشده باشد غیرفعال است.
• هیچ حالت تأیید خودکار فراگیر برای LAN یا شبکه خصوصی وجود ندارد.
• فقط جفت‌سازی تازه دستگاه با role: node و بدون محدوده‌های درخواستی واجد شرایط است.
• کلاینت‌های operator، مرورگر، Control UI و WebChat دستی باقی می‌مانند.
• ارتقاهای نقش، محدوده، فراداده و کلید عمومی دستی باقی می‌مانند.
• مسیرهای هدر پروکسی مورد اعتماد same-host loopback واجد شرایط نیستند، چون آن مسیر می‌تواند توسط فراخواننده‌های محلی جعل شود.

تأیید خودکار ارتقای فراداده

وقتی دستگاهی که از قبل جفت شده با فقط تغییرات فراداده غیرحساس دوباره وصل می‌شود (برای مثال، نام نمایشی یا راهنماهای پلتفرم کلاینت)، OpenClaw آن را به‌عنوان metadata-upgrade در نظر می‌گیرد. تأیید خودکار خاموش محدود است: فقط برای اتصال‌های مجدد محلی غیرمرورگری مورد اعتماد اعمال می‌شود که از قبل مالکیت اعتبارنامه‌های محلی یا مشترک را ثابت کرده‌اند، از جمله اتصال‌های مجدد برنامه native روی همان host پس از تغییرات فراداده نسخه OS. کلاینت‌های مرورگر/Control UI و کلاینت‌های راه‌دور همچنان از جریان تأیید مجدد صریح استفاده می‌کنند. ارتقاهای محدوده (read به write/admin) و تغییرات کلید عمومی واجد شرایط تأیید خودکار ارتقای فراداده نیستند - آن‌ها به‌عنوان درخواست‌های تأیید مجدد صریح باقی می‌مانند.

ابزارهای کمکی جفت‌سازی QR

/pair qr بار جفت‌سازی را به‌صورت رسانه ساخت‌یافته رندر می‌کند تا کلاینت‌های موبایل و مرورگر بتوانند مستقیماً آن را اسکن کنند.

حذف یک دستگاه همچنین هر درخواست جفت‌سازی در انتظار مانده برای آن شناسه دستگاه را پاک‌سازی می‌کند، بنابراین nodes pending پس از لغو، ردیف‌های بی‌صاحب نشان نمی‌دهد.

محلیت و هدرهای فورواردشده

جفت‌سازی Gateway یک اتصال را فقط زمانی loopback در نظر می‌گیرد که هم سوکت خام و هم هر شاهد پروکسی بالادستی با هم موافق باشند. اگر درخواستی روی loopback برسد اما شواهد هدر Forwarded، هر هدر X-Forwarded-*، یا X-Real-IP را حمل کند، آن شواهد هدر فورواردشده ادعای محلیت loopback را رد صلاحیت می‌کند. سپس مسیر جفت‌سازی به‌جای اینکه درخواست را خاموش به‌عنوان اتصال same-host در نظر بگیرد، نیازمند تأیید صریح است. برای قانون معادل در احراز هویت operator، احراز هویت پروکسی مورد اعتماد را ببینید.

ذخیره‌سازی (محلی، خصوصی)

وضعیت جفت‌سازی زیر دایرکتوری وضعیت Gateway ذخیره می‌شود (پیش‌فرض ~/.openclaw):

• ~/.openclaw/nodes/paired.json
• ~/.openclaw/nodes/pending.json

اگر OPENCLAW_STATE_DIR را بازنویسی کنید، پوشه nodes/ همراه با آن منتقل می‌شود.

نکات امنیتی:

• توکن‌ها محرمانه هستند؛ با paired.json به‌عنوان داده حساس برخورد کنید.
• چرخاندن یک توکن نیازمند تأیید مجدد است (یا حذف ورودی Node).

رفتار انتقال

• انتقال بدون وضعیت است؛ عضویت را ذخیره نمی‌کند.
• اگر Gateway آفلاین باشد یا جفت‌سازی غیرفعال باشد، Nodeها نمی‌توانند جفت شوند.
• اگر Gateway در حالت راه‌دور باشد، جفت‌سازی همچنان در برابر محل ذخیره Gateway راه‌دور انجام می‌شود.

مرتبط

• جفت‌سازی کانال
• Nodeها
• CLI دستگاه‌ها