openclaw devices

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

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

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

فرمان‌ها

openclaw devices list

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

openclaw devices listopenclaw devices list --json

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

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

openclaw devices approve [requestId] [--latest]

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

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

رفتار تأیید:

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

openclaw devices reject <requestId>

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

openclaw devices reject <requestId>

openclaw devices remove <deviceId>

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

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

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

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

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

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

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

openclaw devices clear --yes [--pending]

دستگاه‌های جفت‌شده را به‌صورت گروهی پاک می‌کند. این عملیات با --yes محدود شده است.

openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --json

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

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

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

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

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

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

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

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

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

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

نکات

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

چک‌لیست بازیابی ناهماهنگی توکن

وقتی Control UI یا سایر کلاینت‌ها پیوسته با AUTH_TOKEN_MISMATCH، AUTH_DEVICE_TOKEN_MISMATCH یا AUTH_SCOPE_MISMATCH مواجه می‌شوند، از این راهنما استفاده کنید.

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

   openclaw config get gateway.auth.token

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

   openclaw devices list

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

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

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

   openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>

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

نکات:

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

مرتبط:

• عیب‌یابی احراز هویت داشبورد
• عیب‌یابی Gateway

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

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

openclaw devices approve --latest

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

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

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

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

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

مرتبط

• مرجع CLI
• Nodeها