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

در جفت‌سازی تحت مالکیت Gateway، Gateway مرجع حقیقت برای این است که کدام Nodeها اجازه پیوستن دارند. رابط‌های کاربری (برنامه 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 یا رابط کاربری).
4. در صورت تأیید، Gateway یک توکن جدید صادر می‌کند (توکن‌ها هنگام جفت‌سازی مجدد چرخش می‌یابند).
5. Node با استفاده از توکن دوباره وصل می‌شود و اکنون «جفت‌شده» است.

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

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

openclaw nodes pending
openclaw nodes approve <requestId>
openclaw nodes reject <requestId>
openclaw nodes status
openclaw 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.pair.verify - راستی‌آزمایی { nodeId, token }.

نکات:

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

# کنترل فرمان Node (۲۰۲۶.۳.۳۱+)

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

این یعنی:

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

# مرزهای اعتماد رویداد Node (۲۰۲۶.۳.۳۱+)

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

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

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

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

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

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

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

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

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

مرز امنیتی:

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

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

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

# کمک‌کننده‌های جفت‌سازی QR

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

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

# محلی‌بودن و هدرهای فورواردشده

جفت‌سازی Gateway یک اتصال را فقط زمانی loopback در نظر می‌گیرد که هم سوکت خام و هم هر شواهد پروکسی بالادستی با آن موافق باشند. اگر درخواستی روی loopback برسد اما هدرهای X-Forwarded-For / X-Forwarded-Host / X-Forwarded-Proto را حمل کند که به یک مبدأ غیرمحلی اشاره دارند، آن شواهد هدر فورواردشده ادعای محلی‌بودن loopback را رد صلاحیت می‌کند. مسیر جفت‌سازی سپس به‌جای اینکه درخواست را بی‌صدا به‌عنوان اتصال همان میزبان در نظر بگیرد، به تأیید صریح نیاز دارد. برای قانون معادل در احراز هویت عملگر، احراز هویت پروکسی مورد اعتماد را ببینید.

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

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

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

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

نکات امنیتی:

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

# رفتار انتقال

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

# مرتبط

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