CLI commands
دستگاهها
openclaw devices
درخواستهای جفتسازی دستگاه و توکنهای محدود به دستگاه را مدیریت کنید.
فرمانها
openclaw devices list
درخواستهای جفتسازی در انتظار و دستگاههای جفتشده را فهرست کنید.
openclaw devices listopenclaw devices list --jsonخروجی درخواست در انتظار، دسترسی درخواستشده را کنار دسترسی فعلی تاییدشده دستگاه نشان میدهد، وقتی دستگاه از قبل جفت شده باشد. این کار ارتقاهای دامنه/نقش را صریح میکند، بهجای اینکه شبیه از دست رفتن جفتسازی به نظر برسد.
openclaw devices remove <deviceId>
یک ورودی دستگاه جفتشده را حذف کنید.
وقتی با توکن دستگاه جفتشده احراز هویت شدهاید، فراخوانهای غیرادمین فقط
میتوانند ورودی دستگاه خودشان را حذف کنند. حذف دستگاهی دیگر نیازمند
operator.admin است.
openclaw devices remove <deviceId>openclaw devices remove <deviceId> --jsonopenclaw devices clear --yes [--pending]
دستگاههای جفتشده را بهصورت دستهای پاک کنید.
openclaw devices clear --yesopenclaw devices clear --yes --pendingopenclaw devices clear --yes --pending --jsonopenclaw devices approve [requestId] [--latest]
یک درخواست جفتسازی دستگاه در انتظار را با requestId دقیق تایید کنید. اگر
requestId حذف شود یا --latest پاس داده شود، OpenClaw فقط درخواست در انتظار
انتخابشده را چاپ میکند و خارج میشود؛ پس از بررسی جزئیات، تایید را با شناسه
درخواست دقیق دوباره اجرا کنید.
اگر دستگاه از قبل جفت شده باشد و دامنههای گستردهتر یا نقش گستردهتری
درخواست کند، OpenClaw تایید موجود را حفظ میکند و یک درخواست ارتقای جدید
در انتظار میسازد. ستونهای Requested و Approved را در openclaw devices list
بررسی کنید، یا از openclaw devices approve --latest استفاده کنید تا ارتقای دقیق
را پیش از تایید پیشنمایش کنید.
اگر Gateway بهصورت صریح با
gateway.nodes.pairing.autoApproveCidrs پیکربندی شده باشد، درخواستهای نخستین
role: node از IPهای کلاینت مطابق میتوانند پیش از نمایش در این فهرست تایید
شوند. این سیاست بهصورت پیشفرض غیرفعال است و هرگز برای کلاینتهای
عملگر/مرورگر یا درخواستهای ارتقا اعمال نمیشود.
تایید نقشهای دستگاه node یا نقشهای غیرعملگر دیگر نیازمند operator.admin
است. operator.pairing فقط برای تایید دستگاههای عملگر کافی است، آن هم وقتی
دامنههای عملگر درخواستشده درون دامنههای خود فراخواننده باقی بمانند. برای
بررسیهای زمان تایید، دامنههای عملگر را ببینید.
openclaw devices approveopenclaw devices approve <requestId>openclaw devices approve --latestتایید اجرای نخست Paperclip / openclaw_gateway
وقتی یک عامل جدید Paperclip برای نخستین بار از طریق آداپتور openclaw_gateway وصل میشود، Gateway ممکن است پیش از موفق شدن اجراها، یک تایید یکباره جفتسازی دستگاه بخواهد. اگر Paperclip خطای openclaw_gateway_pairing_required را گزارش کرد، دستگاه در انتظار را تایید کنید و دوباره تلاش کنید.
برای Gatewayهای محلی، آخرین درخواست در انتظار را پیشنمایش کنید:
openclaw devices approve --latestپیشنمایش فرمان دقیق openclaw devices approve <requestId> را چاپ میکند. جزئیات درخواست را بررسی کنید، سپس همان فرمان را با شناسه درخواست دوباره اجرا کنید تا تایید شود.
برای Gatewayهای راهدور یا اعتبارنامههای صریح، هنگام پیشنمایش و تایید همان گزینهها را پاس دهید:
openclaw devices approve --latest --url <gateway-ws-url> --token <gateway-token>برای جلوگیری از تایید دوباره پس از راهاندازیهای مجدد، بهجای تولید یک هویت زودگذر جدید در هر اجرا، یک کلید دستگاه پایدار را در پیکربندی آداپتور Paperclip نگه دارید:
{ "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 (برای اسکریپتنویسی توصیه میشود).
نکتهها
- چرخش توکن یک توکن جدید برمیگرداند (حساس). با آن مثل یک راز رفتار کنید.
- این فرمانها به دامنه
operator.pairing(یاoperator.admin) نیاز دارند. برخی تاییدها همچنین نیاز دارند فراخواننده دامنههای عملگری را داشته باشد که دستگاه هدف صادر میکند یا به ارث میبرد. نقشهای دستگاه غیرعملگر نیازمندoperator.adminهستند؛ دامنههای عملگر را ببینید. 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 شکست میخورند، از این استفاده کنید.
- منبع فعلی توکن gateway را تایید کنید:
openclaw config get gateway.auth.token- دستگاههای جفتشده را فهرست کنید و شناسه دستگاه آسیبدیده را پیدا کنید:
openclaw devices list- توکن عملگر را برای دستگاه آسیبدیده بچرخانید:
openclaw devices rotate --device <deviceId> --role operator- اگر چرخش کافی نیست، جفتسازی کهنه را حذف کنید و دوباره تایید کنید:
openclaw devices remove <deviceId>openclaw devices listopenclaw devices approve <requestId>- اتصال کلاینت را با توکن/گذرواژه اشتراکی فعلی دوباره امتحان کنید.
نکتهها:
- تقدم عادی احراز هویت اتصال مجدد ابتدا توکن/گذرواژه اشتراکی صریح است، سپس
deviceTokenصریح، سپس توکن دستگاه ذخیرهشده، و بعد توکن bootstrap. - بازیابی مورداعتماد
AUTH_TOKEN_MISMATCHمیتواند برای یک تلاش دوباره محدود، موقتا هم توکن اشتراکی و هم توکن دستگاه ذخیرهشده را با هم ارسال کند. AUTH_SCOPE_MISMATCHیعنی توکن دستگاه شناسایی شده اما مجموعه دامنه درخواستشده را حمل نمیکند؛ پیش از تغییر احراز هویت Gateway اشتراکی، قرارداد تایید جفتسازی/دامنه را اصلاح کنید.
مرتبط:
