Configuration
الاقتران
"الإقران" هو خطوة الموافقة الصريحة على الوصول في OpenClaw. يُستخدم في موضعين:
- إقران الرسائل المباشرة (من يُسمح له بالتحدث إلى الروبوت)
- إقران Node (أي الأجهزة/العُقد يُسمح لها بالانضمام إلى شبكة Gateway)
سياق الأمان: الأمان
1) إقران الرسائل المباشرة (وصول الدردشة الواردة)
عند تكوين قناة بسياسة رسائل مباشرة pairing، يحصل المرسلون غير المعروفين على رمز قصير ولا تتم معالجة رسالتهم حتى توافق عليها.
سياسات الرسائل المباشرة الافتراضية موثقة في: الأمان
dmPolicy: "open" تكون عامة فقط عندما تتضمن قائمة السماح الفعالة للرسائل المباشرة "*".
يتطلب الإعداد والتحقق وجود حرف البدل هذا لتكوينات الفتح العام. إذا كانت الحالة
الحالية تحتوي على open مع إدخالات allowFrom محددة، فسيظل وقت التشغيل يقبل
هؤلاء المرسلين فقط، ولا توسّع موافقات مخزن الإقران وصول open.
رموز الإقران:
- 8 أحرف، كبيرة، بلا أحرف ملتبسة (
0O1I). - تنتهي بعد ساعة واحدة. لا يرسل الروبوت رسالة الإقران إلا عند إنشاء طلب جديد (تقريبًا مرة واحدة في الساعة لكل مرسل).
- طلبات إقران الرسائل المباشرة المعلقة محدودة افتراضيًا بـ 3 لكل قناة؛ وتُتجاهل الطلبات الإضافية حتى تنتهي صلاحية أحدها أو تتم الموافقة عليه.
الموافقة على مرسل
openclaw pairing list telegramopenclaw pairing approve telegram <CODE>إذا لم يتم تكوين مالك أوامر بعد، فإن الموافقة على رمز إقران رسائل مباشرة تُمهّد أيضًا
commands.ownerAllowFrom للمرسل الموافق عليه، مثل telegram:123456789.
يمنح ذلك الإعدادات لأول مرة مالكًا صريحًا للأوامر ذات الامتيازات ومطالبات موافقة
التنفيذ. بعد وجود مالك، تمنح موافقات الإقران اللاحقة وصول الرسائل المباشرة فقط؛
ولا تضيف المزيد من المالكين.
القنوات المدعومة: discord، feishu، googlechat، imessage، irc، line، matrix، mattermost، msteams، nextcloud-talk، nostr، openclaw-weixin، signal، slack، synology-chat، telegram، twitch، whatsapp، zalo، zalouser.
مجموعات مرسلين قابلة لإعادة الاستخدام
استخدم accessGroups في المستوى الأعلى عندما ينبغي تطبيق مجموعة المرسلين الموثوقين نفسها على
عدة قنوات رسائل أو على قوائم سماح الرسائل المباشرة والمجموعات معًا.
تستخدم المجموعات الثابتة type: "message.senders" وتتم الإشارة إليها باستخدام
accessGroup:<name> من قوائم السماح الخاصة بالقناة:
{ accessGroups: { operators: { type: "message.senders", members: { discord: ["discord:123456789012345678"], telegram: ["987654321"], whatsapp: ["+15551234567"], }, }, }, channels: { telegram: { dmPolicy: "allowlist", allowFrom: ["accessGroup:operators"] }, whatsapp: { groupPolicy: "allowlist", groupAllowFrom: ["accessGroup:operators"] }, },}مجموعات الوصول موثقة بالتفصيل هنا: مجموعات الوصول
مكان حفظ الحالة
تُخزّن ضمن ~/.openclaw/credentials/:
- الطلبات المعلقة:
<channel>-pairing.json - مخزن قائمة السماح المعتمدة:
- الحساب الافتراضي:
<channel>-allowFrom.json - الحساب غير الافتراضي:
<channel>-<accountId>-allowFrom.json
- الحساب الافتراضي:
سلوك نطاق الحساب:
- الحسابات غير الافتراضية تقرأ/تكتب ملف قائمة السماح المحدد النطاق الخاص بها فقط.
- الحساب الافتراضي يستخدم ملف قائمة السماح غير المحدد النطاق على مستوى القناة.
تعامل معها باعتبارها حساسة (فهي تتحكم في الوصول إلى مساعدك).
2) إقران أجهزة Node (iOS/Android/macOS/العُقد بلا واجهة)
تتصل العُقد بـ Gateway باعتبارها أجهزة مع role: node. ينشئ Gateway
طلب إقران جهاز يجب الموافقة عليه.
الإقران من واجهة التحكم (موصى به)
استخدم جلسة واجهة تحكم متصلة مسبقًا لديها وصول operator.admin:
- افتح واجهة التحكم وحدد العُقد.
- في الأجهزة، انقر على إقران جهاز محمول.
- على هاتفك، افتح تطبيق OpenClaw ← الإعدادات ← Gateway.
- امسح رمز QR أو الصق رمز الإعداد، ثم اتصل.
تتم الموافقة تلقائيًا على تطبيقات OpenClaw الرسمية لنظامي iOS وAndroid عندما تتطابق بيانات تعريف رمز الإعداد الخاصة بها. إذا عرضت الأجهزة طلبًا معلقًا (على سبيل المثال لعميل غير رسمي أو بيانات تعريف غير متطابقة)، فراجع دوره ونطاقاته قبل الموافقة عليه.
يُعطّل الزر عندما لا تمتلك جلسة واجهة التحكم الحالية وصول المسؤول. استخدم مسار موافقة CLI أدناه من مضيف Gateway في هذه الحالة.
الإقران عبر Telegram
إذا كنت تستخدم Plugin device-pair، يمكنك إجراء إقران الجهاز لأول مرة بالكامل من Telegram:
- في Telegram، أرسل رسالة إلى روبوتك:
/pair - يرد الروبوت برسالتين: رسالة تعليمات ورسالة رمز إعداد منفصلة (سهلة النسخ/اللصق في Telegram).
- على هاتفك، افتح تطبيق OpenClaw لنظام iOS ← الإعدادات ← Gateway.
- امسح رمز QR أو الصق رمز الإعداد واتصل.
- يتصل تطبيق الجوال الرسمي تلقائيًا. إذا أظهر
/pair pendingطلبًا، فراجع دوره ونطاقاته قبل الموافقة عليه.
رمز الإعداد هو حمولة JSON مرمّزة بـ base64 تحتوي على:
url: عنوان WebSocket URL الخاص بـ Gateway (ws://...أوwss://...)bootstrapToken: رمز تمهيد قصير العمر لجهاز واحد يُستخدم لمصافحة الإقران الأولية
يحمل رمز التمهيد هذا ملف تعريف تمهيد الإقران المدمج:
- يسمح ملف تعريف الإعداد المدمج بخط الأساس الجديد لرمز QR/رمز الإعداد فقط:
nodeبالإضافة إلى تسليم محدود لـoperator - يظل رمز
nodeالذي تم تسليمهscopes: [] - يقتصر رمز
operatorالذي تم تسليمه علىoperator.approvals، وoperator.read، وoperator.talk.secrets، وoperator.write - لا يُمنح
operator.adminعبر تمهيد QR/رمز الإعداد؛ فهو يتطلب مسار إقران أو رمز عامل منفصلًا ومعتمدًا - يظل تدوير/إبطال الرموز لاحقًا مقيدًا بكل من عقد الدور المعتمد للجهاز ونطاقات العامل الخاصة بجلسة المستدعي
تعامل مع رمز الإعداد مثل كلمة مرور أثناء صلاحيته.
بالنسبة إلى Tailscale أو الإقران العام أو غيره من إقران الجوال البعيد، استخدم Tailscale Serve/Funnel
أو عنوان Gateway URL آخر بصيغة wss://. لا تُقبل رموز إعداد النص الصريح ws:// إلا
لـ local loopback، وعناوين الشبكة المحلية الخاصة، ومضيفي Bonjour بصيغة .local، ومضيف محاكي Android.
لا تزال عناوين Tailnet CGNAT، وأسماء .ts.net، والمضيفون العامون
تفشل بإغلاق آمن قبل إصدار QR/رمز الإعداد.
الموافقة على جهاز Node
openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>عندما تُرفض موافقة صريحة لأن جلسة الجهاز المقترن التي توافق
فُتحت بنطاق الإقران فقط، يعيد CLI محاولة الطلب نفسه باستخدام
operator.admin. يتيح ذلك لجهاز مقترن حالي قادر على الإدارة استعادة إقران
جديد لواجهة التحكم/المتصفح دون تعديل devices/paired.json يدويًا. لا يزال
Gateway يتحقق من الاتصال المعاد؛ وتبقى الرموز التي لا يمكنها المصادقة
باستخدام operator.admin محظورة.
إذا حاول الجهاز نفسه مجددًا بتفاصيل مصادقة مختلفة (على سبيل المثال
دور/نطاقات/مفتاح عام مختلف)، فسيتم تجاوز الطلب المعلق السابق وإنشاء
requestId جديد.
موافقة تلقائية اختيارية على Node عبر CIDR موثوق
يبقى إقران الجهاز يدويًا افتراضيًا. بالنسبة إلى شبكات Node المحكمة التحكم، يمكنك الاشتراك في الموافقة التلقائية لأول مرة على Node باستخدام CIDR صريحة أو عناوين IP دقيقة:
{ gateway: { nodes: { pairing: { autoApproveCidrs: ["192.168.1.0/24"], }, }, },}ينطبق هذا فقط على طلبات إقران role: node الجديدة بلا نطاقات
مطلوبة. لا يزال عملاء العامل والمتصفح وواجهة التحكم وWebChat يتطلبون موافقة
يدوية. ولا تزال تغييرات الدور والنطاق والبيانات التعريفية والمفتاح العام تتطلب موافقة
يدوية.
تخزين حالة إقران Node
تُخزّن ضمن ~/.openclaw/devices/:
pending.json(قصير العمر؛ تنتهي صلاحية الطلبات المعلقة)paired.json(الأجهزة المقترنة + الرموز)
ملاحظات
- واجهة API القديمة
node.pair.*(CLI:openclaw nodes pending|approve|reject|remove|rename) هي مخزن إقران منفصل يملكه Gateway. لا تزال عُقد WS تتطلب إقران جهاز. - سجل الإقران هو مصدر الحقيقة الدائم للأدوار المعتمدة. تبقى رموز الأجهزة النشطة مقيدة بمجموعة الأدوار المعتمدة تلك؛ ولا ينشئ إدخال رمز شارد خارج الأدوار المعتمدة وصولًا جديدًا.
