---
read_when:
    - پیاده‌سازی تأیید جفت‌سازی Node بدون رابط کاربری macOS
    - افزودن جریان‌های CLI برای تأیید Nodeهای راه‌دور
    - گسترش پروتکل Gateway با مدیریت Node
summary: 'تأیید قابلیت‌های Node: نحوه دسترسی Nodeها به فرمان‌ها پس از جفت‌سازی دستگاه'
title: جفت‌سازی Node
x-i18n:
    generated_at: "2026-07-16T16:26:03Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    prompt_version: 32
    provider: openai
    source_hash: 9e4221d7ad6aa6a9cd8ae33f2d4330c2aa49783340fcf7a657c20d6a94c126d9
    source_path: gateway/pairing.md
    workflow: 16
---

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

- **جفت‌سازی دستگاه** (نقش `node`) دست‌دهی `connect` را کنترل می‌کند. بخش
  [تأیید خودکار دستگاه بر اساس CIDR مورد اعتماد](#trusted-cidr-device-auto-approval)
  در ادامه و [جفت‌سازی کانال](/fa/channels/pairing) را ببینید.
- **تأیید قابلیت 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 (مناسب برای محیط بدون رابط گرافیکی)

```bash
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.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 و جدیدترین تصویر لحظه‌ای فرمان‌های اعلام‌شده در فهرست مجاز را
  برای مشاهده عملگر به‌روزرسانی می‌کنند.
- سطوح دامنه عملگر و بررسی‌های زمان تأیید در
  [دامنه‌های عملگر](/fa/gateway/operator-scopes) خلاصه شده‌اند.
- `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`

<Warning>
تأیید جفت‌سازی Node، سطح قابلیت مورد اعتماد را ثبت می‌کند. این کار سطح زنده فرمان‌های Node را به‌صورت اختصاصی برای هر Node تثبیت **نمی‌کند**.

- فرمان‌های زنده Node از مواردی می‌آیند که Node هنگام اتصال اعلام می‌کند و با
  سیاست سراسری فرمان‌های Node متعلق به Gateway (`gateway.nodes.allowCommands` و
  `denyCommands`) فیلتر می‌شوند.
- سیاست اجازه و پرسش `system.run` برای هر Node، در
  `exec.approvals.node.*` روی خود Node قرار دارد، نه در رکورد جفت‌سازی.

</Warning>

## کنترل فرمان‌های Node (2026.3.31+)

<Warning>
**تغییر ناسازگار:** از `2026.3.31` به بعد، فرمان‌های Node تا زمانی که جفت‌سازی Node تأیید نشود غیرفعال هستند. جفت‌سازی دستگاه به‌تنهایی دیگر برای ارائه فرمان‌های اعلام‌شده Node کافی نیست.
</Warning>

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

این یعنی:

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

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

<Warning>
**تغییر ناسازگار:** اجراهای آغازشده از Node اکنون در یک سطح مورد اعتماد محدودشده باقی می‌مانند.
</Warning>

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

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

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

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

```json5
{
  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 را
  راستی‌آزمایی کند.

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

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

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

```json5
{
  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
  در مواردی از میزبان‌ها عبور می‌کنند که فرادادهٔ نمایشی هویت ماشین محسوب نمی‌شود، بنابراین
  هرگز به‌طور خودکار حذف نمی‌شوند — برای آن‌ها از پاک‌سازی در رابط کاربری Control UI یا
  `openclaw nodes remove` استفاده کنید.
- جفت‌سازی‌های تأییدشده توسط مالک و جفت‌سازی‌های مبتنی بر QR/کد راه‌اندازی (راه‌اندازی اولیه) هرگز
  به‌طور خودکار حذف نمی‌شوند. رکوردهایی که پیش از وجود اطلاعات منشأ تأیید شده‌اند، حتی
  پس از تأیید مجدد بی‌صدای همان شناسهٔ دستگاه در زمانی دیگر، محافظت‌شده باقی می‌مانند.
- دستگاه‌های متصل فعلی نادیده گرفته می‌شوند تا نشست‌های محلی هم‌زمان با
  پوشه‌های وضعیت جداگانه، تا زمانی که فعال‌اند توکن‌های خود را حفظ کنند. رکوردهایی که
  طی یک دقیقهٔ گذشته تأیید شده‌اند نیز نادیده گرفته می‌شوند تا دست‌دهی‌های هم‌زمان جفت‌سازی
  نتوانند پیش از ثبت اتصال‌هایشان یکدیگر را بازنشسته کنند.
- کلاینت‌های تحت‌تأثیر ذاتاً محلی هستند، بنابراین در اتصال بعدی خود
  بی‌صدا دوباره جفت می‌شوند.

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

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

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

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

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

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

جفت‌سازی Gateway تنها زمانی یک اتصال را لوپ‌بک در نظر می‌گیرد که هم سوکت خام
و هم هرگونه شواهد پراکسی بالادستی با آن موافق باشند. اگر درخواستی از طریق لوپ‌بک برسد اما
حاوی شواهد سرآیند `Forwarded`، هرگونه `X-Forwarded-*` یا `X-Real-IP` باشد،
این شواهد سرآیند فورواردشده ادعای محلی‌بودن لوپ‌بک را رد می‌کند و
مسیر جفت‌سازی به‌جای اینکه درخواست را بی‌صدا اتصال روی همان میزبان تلقی کند،
به تأیید صریح نیاز دارد. برای قاعدهٔ معادل در احراز هویت اپراتور، به
[احراز هویت پراکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) مراجعه کنید.

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

وضعیت جفت‌سازی در رکوردهای دستگاه جفت‌شده در پایگاه دادهٔ مشترک 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 راه دور انجام می‌شود.

## مرتبط

- [جفت‌سازی کانال](/fa/channels/pairing)
- [CLI مربوط به Nodeها](/fa/cli/nodes)
- [CLI مربوط به دستگاه‌ها](/fa/cli/devices)