جفت‌سازی Node

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

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

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

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

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

درخواست‌های در انتظار به‌طور خودکار 5 دقیقه پس از آخرین تلاش مجدد 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، browser.proxy، fs.listDir یا system.execApprovals.get/set:‏ 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) بتواند بدون تعامل از طریق SSH به میزبان Node متصل شود (با کلیدها/عامل؛ SSH متعلق به Tailscale نیز کار می‌کند) و کلید میزبان از قبل مورداعتماد باشد.
• openclaw برای sh -lc غیرتعاملی در PATH راه دور قابل تفکیک باشد.
• IP متصل‌شونده یک نشانی خصوصی، ULA، پیوند-محلی یا CGNAT مستقیم (بدون پراکسی و غیرحلقه‌بازگشت) باشد یا در صورت تنظیم، با sshVerify.cidrs مطابقت داشته باشد.
• همان حداقل شرایط تأیید CIDR مورداعتماد برقرار باشد: فقط جفت‌سازی تازه و بدون دامنه Node؛ ارتقاها، مرورگرها، Control UI و WebChat همیشه اعلان تأیید نمایش می‌دهند.

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

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

سخت‌سازی یا غیرفعال‌سازی:

{  gateway: {    nodes: {      pairing: {        // غیرفعال‌سازی کامل:        sshVerify: false,        // ...یا محدودسازی/تنظیم کاوش:        // 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 بدون دامنه درخواستی واجد شرایط است.
• کلاینت‌های عملگر، مرورگر، Control UI و WebChat دستی باقی می‌مانند.
• ارتقاهای نقش، دامنه، فراداده و کلید عمومی دستی باقی می‌مانند.
• مسیرهای سرآیند پراکسی مورداعتماد حلقه‌بازگشت روی همان میزبان واجد شرایط نیستند، زیرا این مسیر می‌تواند توسط فراخواننده‌های محلی جعل شود.

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

تأییدهای غیرتعاملی منشأ خود را در ردیف دستگاه جفت‌شده ثبت می‌کنند: تأییدهای خط‌مشی محلی همان میزبان با 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 در نظر می‌گیرد. دامنهٔ تأیید خودکار بی‌صدا محدود است: این تأیید فقط برای اتصال‌های مجدد محلی، مورداعتماد و غیروبی اعمال می‌شود که پیش‌تر مالکیت اعتبارنامه‌های محلی یا مشترک را اثبات کرده‌اند؛ از جمله اتصال مجدد برنامه‌های بومی روی همان میزبان پس از تغییر فرادادهٔ نسخهٔ سیستم‌عامل. کلاینت‌های مرورگر/رابط کاربری کنترل و کلاینت‌های راه‌دور همچنان از جریان صریح تأیید مجدد استفاده می‌کنند. ارتقای دامنه (از خواندن به نوشتن/مدیریت) و تغییر کلید عمومی واجد شرایط تأیید خودکار ارتقای فراداده نیستند؛ آن‌ها همچنان درخواست‌های صریح تأیید مجدد باقی می‌مانند.

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

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

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

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

جفت‌سازی Gateway فقط زمانی یک اتصال را loopback در نظر می‌گیرد که هم سوکت خام و هم شواهد پراکسی بالادستی با آن موافق باشند. اگر درخواستی روی loopback وارد شود اما شواهد سرآیند Forwarded، هرگونه X-Forwarded-* یا X-Real-IP را همراه داشته باشد، آن شواهد سرآیند فورواردشده ادعای محلی‌بودن 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 مربوط به دستگاه‌ها