CLI commands
الأجهزة
openclaw devices
إدارة طلبات إقران الأجهزة والرموز المميزة المقيّدة بنطاق الجهاز.
الخيارات الشائعة
--url <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. لذلك قد تتحول الطلبات إلى حالة الموافقة بعد وقت قصير من ظهورها. عيّنsshVerify: falseلتعطيل التحقق عبر SSH؛ وهذا مستقل عن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، وقائمة أجهزة واجهة التحكم) تسمية المشغّل على اسم العرض الذي يبلّغ عنه العميل.
- يمكن لمستدعٍ غير إداري يستخدم جهازًا مقترنًا إعادة تسمية جهازه الخاص فقط. تتطلب إعادة تسمية جهاز آخر النطاق
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>لتجنّب إعادة الموافقة بعد كل عملية إعادة تشغيل، هيّئ قيمة adapterConfig.devicePrivateKeyPem دائمة في Paperclip بدلًا من السماح له بإنشاء هوية جهاز مؤقتة جديدة في كل تشغيل:
{ "adapterConfig": { "devicePrivateKeyPem": "<ed25519-private-key-pkcs8-pem>" }}إذا استمر فشل الموافقة، شغّل openclaw devices list أولًا للتأكد من وجود طلب معلّق.
