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

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

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

## گردش‌کار 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` دستگاه را لغو می‌کند: `devices/paired.json` را تغییر می‌دهد و
  نشست‌های نقش-Node آن دستگاه را نامعتبر/قطع می‌کند. یک دستگاه **چندنقشی**
  (مثلاً هم‌زمان `operator` هم دارد) ردیف خود را نگه می‌دارد و فقط نقش `node`
  را از دست می‌دهد؛ ردیف دستگاهی که فقط Node است حذف می‌شود. همچنین هر ورودی قدیمی منطبق
  از جفت‌سازی Node تحت مالکیت Gateway را حذف می‌کند. Authz: `operator.pairing` می‌تواند
  ردیف‌های Node غیر-operator را حذف کند؛ فراخواننده‌ای با توکن دستگاه که نقش Node **خودش** را روی
  یک دستگاه چندنقشی لغو می‌کند، علاوه بر آن به `operator.admin` نیاز دارد.
- `node.pair.verify` - `{ nodeId, token }` را تأیید می‌کند.

نکات:

- `node.pair.request` برای هر Node همانی است: فراخوانی‌های تکراری همان
  درخواست در انتظار را برمی‌گردانند.
- درخواست‌های تکراری برای همان Node در انتظار، فراداده ذخیره‌شده Node
  و آخرین اسنپ‌شات دستورات اعلام‌شده مجازشده برای دیدپذیری operator را نیز تازه‌سازی می‌کنند.
- تأیید **همیشه** یک توکن تازه تولید می‌کند؛ هیچ توکنی هرگز از
  `node.pair.request` برگردانده نمی‌شود.
- سطوح محدوده operator و بررسی‌های زمان تأیید در
  [محدوده‌های operator](/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 (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 که پیش‌تر به دسترسی گسترده‌تر ابزار host یا نشست متکی بودند، ممکن است نیازمند تنظیم باشند. این سخت‌سازی تضمین می‌کند که رویدادهای Node نتوانند فراتر از آنچه مرز اعتماد Node اجازه می‌دهد، به دسترسی ابزار در سطح host ارتقا پیدا کنند.

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

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

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

- درخواست با `silent` علامت‌گذاری شده باشد، و
- برنامه بتواند یک اتصال SSH به host Gateway را با همان کاربر تأیید کند.

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

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

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

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

مرز امنیتی:

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

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

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

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

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

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

## محلیت و هدرهای فورواردشده

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