CLI commands
دستگاهها
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 فقط جدیدترین درخواست در انتظار را پیشنمایش میکند و خارج میشود (کد ۱)؛ برای تأیید، فرمان را با شناسه دقیق درخواست دوباره اجرا کنید.
openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latestرفتار تأیید:
- اگر دستگاه از قبل جفت شده باشد و دامنههای گستردهتر یا نقش دیگری درخواست کند، OpenClaw تأیید موجود را حفظ میکند و درخواست ارتقای در انتظار جدیدی میسازد. پیش از تأیید، در
openclaw devices listمقدارRequestedرا باApprovedمقایسه کنید یا با--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الزامی است، فاصلههای ابتدا و انتهای آن حذف میشود، نباید خالی باشد و حداکثر ۶۴ نویسه دارد.- سطوح نمایش (فهرست CLI و موجودی رابط کاربری کنترل) برچسب اپراتور را به نام نمایشی گزارششده توسط کلاینت ترجیح میدهند.
- فراخواننده دستگاه جفتشدهای که مدیر نیست فقط میتواند نام دستگاه خود را تغییر دهد. تغییر نام دستگاهی دیگر به
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داشته باشد. - چرخش توکن، توکن جدیدی (حساس) برمیگرداند؛ با آن مانند یک راز رفتار کنید.
- اگر دامنه جفتسازی روی local loopback در دسترس نباشد و
--urlصریحی ارسال نشده باشد،list/approveمیتوانند به وضعیت جفتسازی محلی رجوع کنند.
فهرست بررسی بازیابی ناهماهنگی توکن
وقتی رابط کاربری کنترل یا کلاینتهای دیگر همچنان با AUTH_TOKEN_MISMATCH، AUTH_DEVICE_TOKEN_MISMATCH یا AUTH_SCOPE_MISMATCH شکست میخورند، از این مراحل استفاده کنید.
-
منبع فعلی توکن Gateway را تأیید کنید:
bash openclaw config get gateway.auth.token -
دستگاههای جفتشده را فهرست کنید و شناسه دستگاه تحت تأثیر را بیابید:
bash openclaw devices list -
توکن اپراتور دستگاه تحت تأثیر را چرخش دهید:
bash openclaw devices rotate --device <deviceId> --role operator -
اگر چرخش کافی نبود، جفتسازی منسوخ را حذف و دوباره تأیید کنید:
bash openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId> -
اتصال کلاینت را با توکن/گذرواژه اشتراکی فعلی دوباره امتحان کنید.
نکتهها:
- ترتیب اولویت عادی احراز هویت هنگام اتصال مجدد: ابتدا توکن/گذرواژه اشتراکی صریح، سپس
deviceTokenصریح، سپس توکن ذخیرهشده دستگاه و در نهایت توکن راهاندازی اولیه. - بازیابی مورداعتماد
AUTH_TOKEN_MISMATCHمیتواند برای یک تلاش مجدد محدود، توکن اشتراکی و توکن ذخیرهشده دستگاه را موقتاً با هم ارسال کند. AUTH_SCOPE_MISMATCHیعنی توکن دستگاه شناسایی شده است، اما مجموعه دامنه درخواستی را ندارد؛ پیش از تغییر احراز هویت اشتراکی 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 را اجرا کنید تا وجود درخواست در انتظار را تأیید کنید.
