جفت‌سازی Node

جفت‌سازی Node دو لایه دارد که هر دو در رکورد دستگاه جفت‌شده در پایگاه داده وضعیت SQLite متعلق به Gateway ذخیره می‌شوند:

• جفت‌سازی دستگاه (نقش node) دست‌دهی connect را کنترل می‌کند. بخش تأیید خودکار دستگاه با CIDR مورد اعتماد در ادامه و جفت‌سازی کانال را ببینید.
• تأیید قابلیت Node (node.pair.*) تعیین می‌کند یک Node متصل اجازه دارد کدام قابلیت‌ها/فرمان‌های اعلام‌شده را ارائه دهد. Gateway مرجع نهایی است؛ رابط‌های کاربری (برنامه macOS و رابط کنترل) پیشانه‌هایی هستند که درخواست‌های در انتظار را تأیید یا رد می‌کنند.

مخزن مستقل سابق جفت‌سازی Node (nodes/paired.json با یک توکن برای هر Node، که در ژانویهٔ ۲۰۲۶ از مسیر اتصال کنار گذاشته شد) حذف شده است: Gatewayها هنگام راه‌اندازی، هر ردیف باقی‌مانده را یک‌بار در رکوردهای دستگاه ادغام می‌کنند و فایل‌های قدیمی را با پسوند .migrated بایگانی می‌کنند. پشتیبانی از پل TCP قدیمی حذف شده است.

تأیید قابلیت چگونه کار می‌کند

1. یک Node به WS متعلق به Gateway متصل می‌شود (جفت‌سازی دستگاه این مرحله را کنترل می‌کند).
2. Gateway سطح قابلیت‌ها/فرمان‌های اعلام‌شده را با سطح تأییدشده مقایسه می‌کند؛ سطح‌های جدید یا گسترش‌یافته یک درخواست در انتظار را در رکورد دستگاه ذخیره می‌کنند و رویداد node.pair.requested را منتشر می‌کنند.
3. شما درخواست را تأیید یا رد می‌کنید (از طریق CLI یا رابط کاربری).
4. تا زمان تأیید، فرمان‌های Node فیلترشده باقی می‌مانند؛ تأیید، سطح اعلام‌شده را با رعایت سیاست عادی فرمان‌ها در دسترس قرار می‌دهد.

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

گردش‌کار 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.list - فهرست‌کردن Nodeهای در انتظار و جفت‌شده (operator.pairing).
• node.pair.approve - تأیید یک درخواست در انتظار.
• node.pair.reject - رد یک درخواست در انتظار.
• node.pair.remove - حذف یک Node جفت‌شده. این کار نقش node دستگاه را در مخزن دستگاه‌های جفت‌شده لغو می‌کند، سطح تأییدشده Node را نیز همراه آن حذف می‌کند و نشست‌های نقش Node آن دستگاه را نامعتبر/قطع می‌کند. دستگاهی با چند نقش (برای مثال دستگاهی که نقش operator را نیز دارد) ردیف خود را حفظ می‌کند و فقط نقش node را از دست می‌دهد؛ ردیف دستگاهی که فقط Node است حذف می‌شود. مجوزدهی: operator.pairing می‌تواند ردیف‌های Node فاقد نقش اپراتور را حذف کند؛ فراخوانی که با توکن دستگاه، نقش Node خودش را روی دستگاهی چندنقشی لغو می‌کند، علاوه بر آن به operator.admin نیز نیاز دارد.
• node.rename - تغییر نام نمایشی یک Node جفت‌شده که به اپراتور نشان داده می‌شود.

حذف‌شده در 2026.7: node.pair.request و node.pair.verify. درخواست‌های در انتظار هنگام اتصال Nodeها توسط خود Gateway ایجاد می‌شوند و توکن مستقل هر Node که این متدها برای آن استفاده می‌شدند دیگر وجود ندارد؛ احراز هویت Node از توکن جفت‌سازی دستگاه استفاده می‌کند.

نکته‌ها:

• اتصال‌های مجدد با سطحی بدون تغییر، درخواست در انتظار را دوباره استفاده می‌کنند؛ درخواست‌های تکراری، فراداده ذخیره‌شده Node و آخرین تصویر فوری از فرمان‌های اعلام‌شده در فهرست مجاز را برای مشاهده اپراتور به‌روزرسانی می‌کنند.
• سطوح دامنه اپراتور و بررسی‌های زمان تأیید در دامنه‌های اپراتور خلاصه شده‌اند.
• node.pair.approve برای اعمال دامنه‌های تأیید اضافی، از فرمان‌های اعلام‌شده در درخواست در انتظار استفاده می‌کند:
  • درخواست بدون فرمان: operator.pairing
  • درخواست فرمان غیر اجرایی: 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 که پیش‌تر به دسترسی گسترده‌تر به ابزارهای میزبان یا نشست متکی بودند، ممکن است به تنظیم نیاز داشته باشند. این مقاوم‌سازی مانع از آن می‌شود که رویدادهای Node فراتر از آنچه مرز اعتماد Node اجازه می‌دهد، به دسترسی ابزار در سطح میزبان ارتقا یابند.

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

تأیید خودکار دستگاه با راستی‌آزمایی SSH (پیش‌فرض)

جفت‌سازی نخستین دستگاه با role: node از یک نشانی خصوصی/CGNAT زمانی به‌طور خودکار تأیید می‌شود که Gateway بتواند مالکیت دستگاه را از طریق SSH اثبات کند: Gateway به میزبان درخواست‌کننده جفت‌سازی متصل می‌شود (BatchMode، StrictHostKeyChecking=yes)، فرمان openclaw node identity --json را در آنجا اجرا می‌کند و فقط زمانی تأیید می‌کند که شناسه دستگاه راه‌دور و کلید عمومی آن دقیقاً با درخواست در انتظار مطابقت داشته باشند. تطابق کلید عامل ایمنی این روش است: صرفاً در دسترس بودن هرگز باعث تأیید نمی‌شود؛ بنابراین هم‌مستأجران NAT، کاربران دیگر روی یک میزبان مشترک و جعل در LAN همگی به اعلان عادی هدایت می‌شوند.

به‌طور پیش‌فرض فعال است. الزامات فعال‌شدن آن:

• کاربر فرایند Gateway (یا sshVerify.user) بتواند بدون تعامل به میزبان Node از طریق SSH متصل شود (کلیدها/عامل؛ SSH روی Tailscale نیز کار می‌کند) و کلید میزبان از قبل مورد اعتماد باشد.
• openclaw در PATH راه‌دور برای sh -lc غیرتعاملی قابل شناسایی باشد.
• IP متصل‌شونده، یک نشانی مستقیم (بدون پراکسی و غیر local loopback) از نوع خصوصی، ULA، پیوند-محلی یا CGNAT باشد، یا در صورت تنظیم sshVerify.cidrs با آن مطابقت داشته باشد.
• همان حداقل شرایط تأیید CIDR مورد اعتماد برقرار باشد: فقط جفت‌سازی تازه و بدون دامنه Node؛ ارتقاها، مرورگرها، رابط کنترل و WebChat همیشه اعلان تأیید نمایش می‌دهند.

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

دستگاه‌های تأییدشده مقدار approvedVia: "ssh-verified" را ثبت می‌کنند و نخستین سطح قابلیت اعلام‌شده آن‌ها نیز در همان مرحله تأیید می‌شود — تطابق کلید از قبل اثبات می‌کند که Node تحت حساب اپراتور روی دستگاهی متعلق به او اجرا می‌شود؛ این همان ادعایی است که تأیید دستی قابلیت بیان می‌کند. ارتقاهای بعدی سطح همچنان اعلان تأیید نمایش می‌دهند.

برای مقاوم‌سازی یا غیرفعال‌سازی:

{  gateway: {    nodes: {      pairing: {        // Disable entirely:        sshVerify: false,        // ...or scope/tune the probe:        // sshVerify: { user: "me", identity: "~/.ssh/probe", timeoutMs: 7000, cidrs: ["10.0.0.0/8"] },      },    },  },}

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

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

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

اگر تأیید بی‌صدا ناموفق باشد، به اعلان عادی Approve/Reject بازمی‌گردد.

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

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

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

مرز امنیتی:

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

پاک‌سازی جایگزینی جفت‌سازی بی‌صدا

تأییدهای غیرتعاملی منشأ خود را در ردیف دستگاه جفت‌شده ثبت می‌کنند: تأییدهای سیاست محلی همان میزبان با silent، تأییدهای Node با CIDR مورد اعتماد با trusted-cidr و تأییدهای Node با راستی‌آزمایی SSH با ssh-verified. کارخواه‌هایی که دایرکتوری وضعیتشان موقتی است (خانه‌های موقت، کانتینرها، محیط‌های ایزوله هر اجرا) در هر اجرا یک جفت‌کلید تازه دستگاه می‌سازند و هر اجرا بی‌صدا به‌عنوان دستگاهی کاملاً جدید دوباره جفت می‌شود — بدون پاک‌سازی، فهرست جفت‌شده‌ها در هر اجرا یک ردیف منسوخ بیشتر خواهد داشت.

هنگامی که Gateway جفت‌سازی یک دستگاه محلی را بی‌صدا تأیید می‌کند، رکوردهای قدیمی‌تر تأییدشده با silent را که به همان خوشه کارخواه تعلق دارند (clientId، clientMode و نام نمایشی یکسان) و در حال حاضر متصل نیستند، کنار می‌گذارد. کارخواه‌های محلی روی خود میزبان Gateway اجرا می‌شوند، بنابراین کلید خوشه نمی‌تواند با دستگاه دیگری مطابقت داشته باشد. توکن‌های ردیف‌های کنارگذاشته‌شده فوراً لغو می‌شوند؛ هر ورودی مطابق از جفت‌سازی قدیمی Node پاک می‌شود و رویداد حذف node.pair.resolved به‌صورت همگانی منتشر می‌شود.

محدوده‌ها:

• فقط رکوردهایی که آخرین تأییدشان محلی و روی همان میزبان (silent) بوده است، چه به‌عنوان محرک و چه به‌عنوان هدف، واجد شرایط هستند. جفت‌سازی‌های CIDR مورد اعتماد و راستی‌آزمایی‌شده با SSH میان میزبان‌ها انجام می‌شوند؛ در این حالت فراداده نمایشی هویت دستگاه نیست، بنابراین هرگز به‌طور خودکار حذف نمی‌شوند — برای آن‌ها از پاک‌سازی رابط کنترل یا openclaw nodes remove استفاده کنید.
• جفت‌سازی‌های تأییدشده توسط مالک و جفت‌سازی‌های کد QR/کد راه‌اندازی (مقداردهی اولیه) هرگز به‌طور خودکار حذف نمی‌شوند. رکوردهایی که پیش از وجود اطلاعات منشأ تأیید شده‌اند، حتی پس از تأیید بی‌صدای دوباره همان شناسه دستگاه نیز محافظت‌شده باقی می‌مانند.
• دستگاه‌های متصل فعلی نادیده گرفته می‌شوند؛ بنابراین نشست‌های محلی هم‌زمان با دایرکتوری‌های وضعیت جداگانه، تا زمانی که فعال‌اند توکن‌های خود را حفظ می‌کنند. رکوردهایی که در یک دقیقه گذشته تأیید شده‌اند نیز نادیده گرفته می‌شوند تا دست‌دهی‌های هم‌زمان جفت‌سازی نتوانند پیش از ثبت اتصال‌هایشان، یکدیگر را کنار بگذارند.
• کارخواه‌های تحت تأثیر بنا بر طراحی محلی هستند، بنابراین در اتصال بعدی خود بی‌صدا دوباره جفت می‌شوند.

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

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

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

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

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

محلی‌بودن و سرآیندهای هدایت‌شده

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

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

وضعیت جفت‌سازی در رکوردهای دستگاه جفت‌شده در پایگاه دادهٔ وضعیت مشترک SQLite، در پوشهٔ وضعیت Gateway (پیش‌فرض ~/.openclaw) نگهداری می‌شود:

• ~/.openclaw/state/openclaw.sqlite (دستگاه‌های جفت‌شده همراه با احراز هویت دستگاه، سطوح تأییدشدهٔ Node، درخواست‌های معلق سطح، درخواست‌های معلق جفت‌سازی دستگاه و توکن‌های راه‌اندازی اولیه)

اگر OPENCLAW_STATE_DIR را بازنویسی کنید، پایگاه داده نیز همراه آن جابه‌جا می‌شود. Gatewayهایی که از نسخه‌های دارای ذخیره‌گاه‌های JSON ارتقا یافته‌اند، هنگام راه‌اندازی آن‌ها را وارد می‌کنند و بایگانی‌های devices/*.json.migrated و nodes/*.json.migrated را باقی می‌گذارند.

نکات امنیتی:

• توکن‌های دستگاه اطلاعات محرمانه هستند؛ پایگاه دادهٔ وضعیت را حساس تلقی کنید.
• چرخش توکن دستگاه با openclaw devices rotate / device.token.rotate انجام می‌شود.

رفتار انتقال

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

مرتبط

• جفت‌سازی کانال
• CLI مربوط به Nodeها
• CLI مربوط به دستگاه‌ها