---
read_when:
    - شما در حال تأیید درخواست‌های جفت‌سازی دستگاه هستید
    - باید توکن‌های دستگاه را جایگزین یا لغو کنید
summary: مرجع CLI برای `openclaw devices` (جفت‌سازی دستگاه + چرخش/لغو توکن)
title: دستگاه‌ها
x-i18n:
    generated_at: "2026-07-12T09:43:36Z"
    model: gpt-5.6
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 83fb10f7a484fec06bfa5e53ae50181b12a9724746176bbace330ec468235494
    source_path: cli/devices.md
    workflow: 16
---

# `openclaw devices`

درخواست‌های جفت‌سازی دستگاه و توکن‌های مختص دستگاه را مدیریت کنید.

## گزینه‌های رایج

- `--url <url>`: نشانی WebSocket مربوط به Gateway (در صورت پیکربندی، مقدار پیش‌فرض `gateway.remote.url` است)
- `--token <token>`: توکن Gateway (در صورت نیاز)
- `--password <password>`: گذرواژه Gateway (احراز هویت با گذرواژه)
- `--timeout <ms>`: مهلت زمانی RPC
- `--json`: خروجی JSON (برای اسکریپت‌نویسی توصیه می‌شود)

<Warning>
وقتی `--url` را تنظیم می‌کنید، CLI برای اطلاعات اعتبارسنجی به پیکربندی یا محیط رجوع نمی‌کند. `--token` یا `--password` را صریحاً وارد کنید، وگرنه فرمان با خطا مواجه می‌شود.
</Warning>

## فرمان‌ها

### `openclaw devices list`

درخواست‌های جفت‌سازی در انتظار و دستگاه‌های جفت‌شده را فهرست می‌کند.

```bash
openclaw devices list
openclaw devices list --json
```

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

نام‌های نمایشی دستگاه‌های جفت‌شده با این ترتیب اولویت انتخاب می‌شوند: برچسب اپراتور (`operatorLabel` از `devices rename`)، سپس `displayName` کلاینت، سپس `clientId` و در نهایت `deviceId`.

### `openclaw devices approve [requestId] [--latest]`

یک درخواست جفت‌سازی در انتظار را با `requestId` دقیق تأیید می‌کند. حذف `requestId` یا ارسال `--latest` فقط جدیدترین درخواست در انتظار را پیش‌نمایش می‌کند و خارج می‌شود (کد ۱)؛ برای تأیید، فرمان را با شناسه دقیق درخواست دوباره اجرا کنید.

```bash
openclaw devices approve
openclaw devices approve <requestId>
openclaw devices approve --latest
```

<Note>
اگر دستگاهی جفت‌سازی را با جزئیات احراز هویت تغییریافته (نقش، دامنه‌ها یا کلید عمومی) دوباره امتحان کند، OpenClaw ورودی در انتظار قبلی را با `requestId` جدید جایگزین می‌کند. درست پیش از تأیید، `openclaw devices list` را اجرا کنید تا شناسه فعلی را دریافت کنید.
</Note>

رفتار تأیید:

- اگر دستگاه از قبل جفت شده باشد و دامنه‌های گسترده‌تر یا نقش دیگری درخواست کند، OpenClaw تأیید موجود را حفظ می‌کند و درخواست ارتقای در انتظار جدیدی می‌سازد. پیش از تأیید، در `openclaw devices list` مقدار `Requested` را با `Approved` مقایسه کنید یا با `--latest` پیش‌نمایش بگیرید.
- تأیید نقش `node` یا هر نقش غیراپراتوری دیگری به `operator.admin` نیاز دارد. برای تأیید دستگاه‌های اپراتوری، `operator.pairing` کافی است، اما فقط هنگامی که دامنه‌های اپراتوری درخواستی در محدوده دامنه‌های خود فراخواننده باقی بمانند. به [دامنه‌های اپراتور](/fa/gateway/operator-scopes) مراجعه کنید.
- اگر `gateway.nodes.pairing.autoApproveCidrs` پیکربندی شده باشد، درخواست‌های بار اول با `role: node` از IPهای کلاینت منطبق می‌توانند پیش از ظاهرشدن در این فهرست به‌طور خودکار تأیید شوند. این قابلیت به‌طور پیش‌فرض غیرفعال است و هرگز برای کلاینت‌های اپراتور/مرورگر یا درخواست‌های ارتقا اعمال نمی‌شود.
- `gateway.nodes.pairing.sshVerify` (به‌طور پیش‌فرض فعال) درخواست‌های بار اول با `role: node` را زمانی به‌طور خودکار تأیید می‌کند که Gateway کلید دستگاه را از طریق SSH به میزبان Node تأیید کند. بنابراین ممکن است درخواست‌ها اندکی پس از ظاهرشدن، به وضعیت تأییدشده تغییر کنند. برای غیرفعال‌کردن تأیید SSH، `sshVerify: false` را تنظیم کنید؛ این گزینه مستقل از `autoApproveCidrs` است، بنابراین برای جفت‌سازی کاملاً دستی، آن را نیز تنظیم‌نشده بگذارید.

### `openclaw devices reject <requestId>`

یک درخواست جفت‌سازی دستگاه در انتظار را رد می‌کند.

```bash
openclaw devices reject <requestId>
```

### `openclaw devices remove <deviceId>`

یک ورودی دستگاه جفت‌شده را حذف می‌کند.

```bash
openclaw devices remove <deviceId>
openclaw devices remove <deviceId> --json
```

فراخواننده‌ای که با توکن دستگاه جفت‌شده احراز هویت شده است، فقط می‌تواند ورودی دستگاه **خود** را حذف کند. حذف دستگاهی دیگر به `operator.admin` نیاز دارد.

### `openclaw devices rename --device <id> --name <label>`

یک برچسب اپراتور به دستگاه جفت‌شده اختصاص می‌دهد. برچسب‌ها وضعیت سمت مالک هستند: پس از ترمیم جفت‌سازی و تأیید دوباره نقش باقی می‌مانند و `deviceId` پایدار را تغییر نمی‌دهند.

```bash
openclaw devices rename --device <deviceId> --name "Kitchen Mac"
openclaw devices rename --device <deviceId> --name "Kitchen Mac" --json
```

- `--name` الزامی است، فاصله‌های ابتدا و انتهای آن حذف می‌شود، نباید خالی باشد و حداکثر ۶۴ نویسه دارد.
- سطوح نمایش (فهرست CLI و موجودی رابط کاربری کنترل) برچسب اپراتور را به نام نمایشی گزارش‌شده توسط کلاینت ترجیح می‌دهند.
- فراخواننده دستگاه جفت‌شده‌ای که مدیر نیست فقط می‌تواند نام دستگاه **خود** را تغییر دهد. تغییر نام دستگاهی دیگر به `operator.admin` نیاز دارد.

### `openclaw devices clear --yes [--pending]`

دستگاه‌های جفت‌شده را به‌صورت گروهی پاک می‌کند. اجرای آن به `--yes` منوط است.

```bash
openclaw devices clear --yes
openclaw devices clear --yes --pending
openclaw devices clear --yes --pending --json
```

`--pending` همچنین همه درخواست‌های جفت‌سازی در انتظار را رد می‌کند.

### `openclaw devices rotate --device <id> --role <role> [--scope <scope...>]`

توکن دستگاه را برای یک نقش چرخش می‌دهد و در صورت نیاز دامنه‌های آن را نیز به‌روزرسانی می‌کند.

```bash
openclaw devices rotate --device <deviceId> --role operator --scope operator.read --scope operator.write
```

- نقش هدف باید از قبل در قرارداد جفت‌سازی تأییدشده آن دستگاه وجود داشته باشد؛ چرخش نمی‌تواند نقش تأییدنشده جدیدی صادر کند.
- حذف `--scope` باعث می‌شود در اتصال‌های مجدد بعدی، دامنه‌های تأییدشده ذخیره‌شده در حافظه نهان توکن دوباره استفاده شوند. ارسال مقادیر صریح `--scope`، مجموعه دامنه ذخیره‌شده را برای اتصال‌های مجدد آینده با توکن ذخیره‌شده در حافظه نهان جایگزین می‌کند.
- فراخواننده دستگاه جفت‌شده‌ای که مدیر نیست فقط می‌تواند توکن دستگاه **خود** را چرخش دهد و مجموعه دامنه هدف باید در محدوده دامنه‌های اپراتوری خود فراخواننده باقی بماند؛ چرخش نمی‌تواند توکنی گسترده‌تر از دسترسی موجود فراخواننده صادر یا حفظ کند.

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

### `openclaw devices revoke --device <id> --role <role>`

توکن دستگاه را برای یک نقش باطل می‌کند.

```bash
openclaw devices revoke --device <deviceId> --role node
```

فراخواننده دستگاه جفت‌شده‌ای که مدیر نیست فقط می‌تواند توکن دستگاه **خود** را باطل کند. باطل‌کردن توکن دستگاهی دیگر به `operator.admin` نیاز دارد. مجموعه دامنه هدف نیز باید در محدوده دامنه‌های اپراتوری خود فراخواننده باشد؛ فراخوانندگان دارای دسترسی صرفاً جفت‌سازی نمی‌توانند توکن‌های اپراتوری مدیریتی/نوشتن را باطل کنند.

## نکته‌ها

- این فرمان‌ها به دامنه `operator.pairing` (یا `operator.admin`) نیاز دارند. نقش‌های دستگاه غیراپراتوری همیشه به `operator.admin` نیاز دارند؛ به [دامنه‌های اپراتور](/fa/gateway/operator-scopes) مراجعه کنید.
- چرخش و ابطال توکن در محدوده مجموعه نقش‌های جفت‌سازی تأییدشده و خط پایه دامنه دستگاه باقی می‌مانند. یک ورودی توکن سرگردان در حافظه نهان، هدفی برای مدیریت توکن ایجاد نمی‌کند.
- برای نشست‌های توکن دستگاه جفت‌شده، مدیریت بین‌دستگاهی (`remove`، `rename`، `rotate`، `revoke`) فقط به دستگاه خود محدود است، مگر آنکه فراخواننده `operator.admin` داشته باشد.
- چرخش توکن، توکن جدیدی (حساس) برمی‌گرداند؛ با آن مانند یک راز رفتار کنید.
- اگر دامنه جفت‌سازی روی local loopback در دسترس نباشد و `--url` صریحی ارسال نشده باشد، `list`/`approve` می‌توانند به وضعیت جفت‌سازی محلی رجوع کنند.

## فهرست بررسی بازیابی ناهماهنگی توکن

وقتی رابط کاربری کنترل یا کلاینت‌های دیگر همچنان با `AUTH_TOKEN_MISMATCH`، `AUTH_DEVICE_TOKEN_MISMATCH` یا `AUTH_SCOPE_MISMATCH` شکست می‌خورند، از این مراحل استفاده کنید.

1. منبع فعلی توکن Gateway را تأیید کنید:

   ```bash
   openclaw config get gateway.auth.token
   ```

2. دستگاه‌های جفت‌شده را فهرست کنید و شناسه دستگاه تحت تأثیر را بیابید:

   ```bash
   openclaw devices list
   ```

3. توکن اپراتور دستگاه تحت تأثیر را چرخش دهید:

   ```bash
   openclaw devices rotate --device <deviceId> --role operator
   ```

4. اگر چرخش کافی نبود، جفت‌سازی منسوخ را حذف و دوباره تأیید کنید:

   ```bash
   openclaw devices remove <deviceId>
   openclaw devices list
   openclaw devices approve <requestId>
   ```

5. اتصال کلاینت را با توکن/گذرواژه اشتراکی فعلی دوباره امتحان کنید.

نکته‌ها:

- ترتیب اولویت عادی احراز هویت هنگام اتصال مجدد: ابتدا توکن/گذرواژه اشتراکی صریح، سپس `deviceToken` صریح، سپس توکن ذخیره‌شده دستگاه و در نهایت توکن راه‌اندازی اولیه.
- بازیابی مورداعتماد `AUTH_TOKEN_MISMATCH` می‌تواند برای یک تلاش مجدد محدود، توکن اشتراکی و توکن ذخیره‌شده دستگاه را موقتاً با هم ارسال کند.
- `AUTH_SCOPE_MISMATCH` یعنی توکن دستگاه شناسایی شده است، اما مجموعه دامنه درخواستی را ندارد؛ پیش از تغییر احراز هویت اشتراکی Gateway، قرارداد تأیید جفت‌سازی/دامنه را اصلاح کنید.

مرتبط:

- [عیب‌یابی احراز هویت داشبورد](/fa/web/dashboard#if-you-see-unauthorized-1008)
- [عیب‌یابی Gateway](/fa/gateway/troubleshooting#dashboard-control-ui-connectivity)

## تأیید اجرای نخست Paperclip / `openclaw_gateway`

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

```bash
openclaw devices approve --latest
```

پیش‌نمایش، فرمان دقیق `openclaw devices approve <requestId>` را چاپ می‌کند؛ جزئیات را بررسی کنید، سپس همان فرمان را با شناسه درخواست دوباره اجرا کنید تا آن را تأیید کنید. برای Gateway راه دور یا اطلاعات اعتبارسنجی صریح، هنگام پیش‌نمایش و تأیید همان گزینه‌ها را ارسال کنید:

```bash
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>
```

برای جلوگیری از نیاز به تأیید دوباره پس از هر راه‌اندازی مجدد، به‌جای آنکه Paperclip در هر اجرا هویت موقت جدیدی برای دستگاه تولید کند، یک `adapterConfig.devicePrivateKeyPem` پایدار را در Paperclip پیکربندی کنید:

```json
{
  "adapterConfig": {
    "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>"
  }
}
```

اگر تأیید همچنان شکست می‌خورد، ابتدا `openclaw devices list` را اجرا کنید تا وجود درخواست در انتظار را تأیید کنید.

## مرتبط

- [مرجع CLI](/fa/cli)
- [Nodeها](/fa/nodes)