---
read_when:
    - پیاده‌سازی تأییدیه‌های جفت‌سازی Node بدون رابط کاربری macOS
    - افزودن روندهای CLI برای تأیید گره‌های راه دور
    - گسترش پروتکل Gateway با مدیریت Node
summary: جفت‌سازی Node تحت مالکیت Gateway (گزینه B) برای iOS و سایر Nodeهای راه‌دور
title: جفت‌سازی تحت مالکیت Gateway
x-i18n:
    generated_at: "2026-05-06T09:20:13Z"
    model: gpt-5.5
    provider: openai
    source_hash: 75713e04e37dcbae151d170e2eb459d0e9b9a799c64a10db731b61d7b53998b4
    source_path: gateway/pairing.md
    workflow: 16
---

در جفت‌سازی تحت مالکیت 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 (مناسب برای محیط‌های بدون رابط گرافیکی)

```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.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` برگردانده نمی‌شود.
- سطوح دامنه عملگر و بررسی‌های زمان تأیید در
  [دامنه‌های عملگر](/fa/gateway/operator-scopes) خلاصه شده‌اند.
- درخواست‌ها می‌توانند `silent: true` را به‌عنوان راهنمایی برای جریان‌های تأیید خودکار شامل شوند.
- `node.pair.approve` از فرمان‌های اعلام‌شده درخواست در انتظار برای اعمال
  دامنه‌های تأیید اضافی استفاده می‌کند:
  - درخواست بدون فرمان: `operator.pairing`
  - درخواست فرمان غیر exec: `operator.pairing` + `operator.write`
  - درخواست `system.run` / `system.run.prepare` / `system.which`:
    `operator.pairing` + `operator.admin`

<Warning>
جفت‌سازی Node یک جریان اعتماد و هویت به‌همراه صدور توکن است. این جریان سطح فرمان زنده Node را به ازای هر Node پین **نمی‌کند**.

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

</Warning>

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

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

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

این یعنی:

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

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

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

خلاصه‌های منشأگرفته از 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های دقیق فعال‌سازی کنند:

```json5
{
  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 را رد صلاحیت می‌کند. مسیر جفت‌سازی سپس به‌جای اینکه درخواست را بی‌صدا
به‌عنوان اتصال همان میزبان در نظر بگیرد، به تأیید صریح نیاز دارد. برای قانون معادل در
احراز هویت عملگر، [احراز هویت پروکسی مورد اعتماد](/fa/gateway/trusted-proxy-auth) را ببینید.

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

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

- `~/.openclaw/nodes/paired.json`
- `~/.openclaw/nodes/pending.json`

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

نکات امنیتی:

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

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

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

## مرتبط

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