---
read_when:
    - شما درخواست‌های جفت‌سازی دستگاه را تأیید می‌کنید
    - باید توکن‌های دستگاه را چرخش دهید یا لغو کنید
summary: مرجع CLI برای `openclaw devices` (جفت‌سازی دستگاه + چرخش/ابطال توکن)
title: دستگاه‌ها
x-i18n:
    generated_at: "2026-06-27T17:23:28Z"
    model: gpt-5.5
    postprocess_version: locale-links-v1
    provider: openai
    source_hash: 08d6945af4fa2403a97dfec94af7bbd0dc746efe90d3e5b4c9f5c5d6d27d70a4
    source_path: cli/devices.md
    workflow: 16
---

# `openclaw devices`

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

## فرمان‌ها

### `openclaw devices list`

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

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

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

### `openclaw devices remove <deviceId>`

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

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

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

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

دستگاه‌های جفت‌شده را به‌صورت دسته‌ای پاک کنید.

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

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

یک درخواست جفت‌سازی دستگاه در انتظار را با `requestId` دقیق تایید کنید. اگر
`requestId` حذف شود یا `--latest` پاس داده شود، OpenClaw فقط درخواست در انتظار
انتخاب‌شده را چاپ می‌کند و خارج می‌شود؛ پس از بررسی جزئیات، تایید را با شناسه
درخواست دقیق دوباره اجرا کنید.

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

اگر دستگاه از قبل جفت شده باشد و دامنه‌های گسترده‌تر یا نقش گسترده‌تری
درخواست کند، OpenClaw تایید موجود را حفظ می‌کند و یک درخواست ارتقای جدید
در انتظار می‌سازد. ستون‌های `Requested` و `Approved` را در `openclaw devices list`
بررسی کنید، یا از `openclaw devices approve --latest` استفاده کنید تا ارتقای دقیق
را پیش از تایید پیش‌نمایش کنید.

اگر Gateway به‌صورت صریح با
`gateway.nodes.pairing.autoApproveCidrs` پیکربندی شده باشد، درخواست‌های نخستین
`role: node` از IPهای کلاینت مطابق می‌توانند پیش از نمایش در این فهرست تایید
شوند. این سیاست به‌صورت پیش‌فرض غیرفعال است و هرگز برای کلاینت‌های
عملگر/مرورگر یا درخواست‌های ارتقا اعمال نمی‌شود.

تایید نقش‌های دستگاه node یا نقش‌های غیرعملگر دیگر نیازمند `operator.admin`
است. `operator.pairing` فقط برای تایید دستگاه‌های عملگر کافی است، آن هم وقتی
دامنه‌های عملگر درخواست‌شده درون دامنه‌های خود فراخواننده باقی بمانند. برای
بررسی‌های زمان تایید، [دامنه‌های عملگر](/fa/gateway/operator-scopes) را ببینید.

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

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

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

برای Gatewayهای محلی، آخرین درخواست در انتظار را پیش‌نمایش کنید:

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

پیش‌نمایش فرمان دقیق `openclaw devices approve <requestId>` را چاپ می‌کند. جزئیات درخواست را بررسی کنید، سپس همان فرمان را با شناسه درخواست دوباره اجرا کنید تا تایید شود.

برای Gatewayهای راه‌دور یا اعتبارنامه‌های صریح، هنگام پیش‌نمایش و تایید همان گزینه‌ها را پاس دهید:

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

برای جلوگیری از تایید دوباره پس از راه‌اندازی‌های مجدد، به‌جای تولید یک هویت زودگذر جدید در هر اجرا، یک کلید دستگاه پایدار را در پیکربندی آداپتور Paperclip نگه دارید:

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

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

### `openclaw devices reject <requestId>`

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

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

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

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

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

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

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

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

فراخواننده‌های غیرادمینِ دستگاه جفت‌شده فقط می‌توانند توکن دستگاه **خودشان**
را باطل کنند.
ابطال توکن دستگاهی دیگر نیازمند `operator.admin` است.
مجموعه دامنه توکن هدف نیز باید درون دامنه‌های عملگر خود نشست فراخواننده جا
بگیرد؛ فراخواننده‌های فقط-جفت‌سازی نمی‌توانند توکن‌های عملگر admin/write را
باطل کنند.

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

نتیجه ابطال را به‌صورت JSON برمی‌گرداند.

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

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

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

## نکته‌ها

- چرخش توکن یک توکن جدید برمی‌گرداند (حساس). با آن مثل یک راز رفتار کنید.
- این فرمان‌ها به دامنه `operator.pairing` (یا `operator.admin`) نیاز دارند.
  برخی تاییدها همچنین نیاز دارند فراخواننده دامنه‌های عملگری را داشته باشد
  که دستگاه هدف صادر می‌کند یا به ارث می‌برد. نقش‌های دستگاه غیرعملگر نیازمند
  `operator.admin` هستند؛ [دامنه‌های عملگر](/fa/gateway/operator-scopes) را ببینید.
- `gateway.nodes.pairing.autoApproveCidrs` یک سیاست اختیاری Gateway فقط برای
  جفت‌سازی تازه دستگاه node است؛ اختیار تایید CLI را تغییر نمی‌دهد.
- چرخش و ابطال توکن درون مجموعه نقش جفت‌سازی تاییدشده و خط مبنای دامنه
  تاییدشده برای آن دستگاه باقی می‌مانند. یک ورودی توکن کش‌شده سرگردان، هدف
  مدیریت توکن اعطا نمی‌کند.
- برای نشست‌های توکن دستگاه جفت‌شده، مدیریت بین‌دستگاهی فقط برای ادمین است:
  `remove`، `rotate`، و `revoke` فقط برای خود دستگاه مجازند، مگر اینکه
  فراخواننده `operator.admin` داشته باشد.
- تغییر توکن همچنین در دامنه فراخواننده محدود می‌ماند: یک نشست فقط-جفت‌سازی
  نمی‌تواند توکنی را بچرخاند یا باطل کند که در حال حاضر `operator.admin` یا
  `operator.write` را حمل می‌کند.
- `devices clear` عمدا با `--yes` محدود شده است.
- اگر دامنه جفت‌سازی روی local loopback در دسترس نباشد (و `--url` صریحی پاس داده نشده باشد)، list/approve می‌تواند از fallback جفت‌سازی محلی استفاده کند.
- `devices approve` پیش از صدور توکن‌ها به شناسه درخواست صریح نیاز دارد؛ حذف `requestId` یا پاس دادن `--latest` فقط جدیدترین درخواست در انتظار را پیش‌نمایش می‌کند.

## چک‌لیست بازیابی drift توکن

وقتی Control UI یا کلاینت‌های دیگر همچنان با `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` صریح، سپس توکن دستگاه ذخیره‌شده، و بعد توکن bootstrap.
- بازیابی مورداعتماد `AUTH_TOKEN_MISMATCH` می‌تواند برای یک تلاش دوباره محدود، موقتا هم توکن اشتراکی و هم توکن دستگاه ذخیره‌شده را با هم ارسال کند.
- `AUTH_SCOPE_MISMATCH` یعنی توکن دستگاه شناسایی شده اما مجموعه دامنه درخواست‌شده را حمل نمی‌کند؛ پیش از تغییر احراز هویت Gateway اشتراکی، قرارداد تایید جفت‌سازی/دامنه را اصلاح کنید.

مرتبط:

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

## مرتبط

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