Configuration

الاقتران

"الاقتران" هو خطوة الموافقة الصريحة على الوصول في OpenClaw. ويُستخدم في موضعين:

اقتران الرسائل الخاصة (من يُسمح له بالتحدث إلى البوت)
اقتران Node (ما الأجهزة/العُقد التي يُسمح لها بالانضمام إلى شبكة Gateway)

سياق الأمان: الأمان

1) اقتران الرسائل الخاصة (الوصول إلى المحادثات الواردة)

عند تهيئة قناة بسياسة رسائل خاصة pairing، يتلقى المرسلون غير المعروفين رمزًا قصيرًا، ولا تُعالَج رسالتهم حتى تتم الموافقة عليهم.

سياسات الرسائل الخاصة الافتراضية موثقة في: الأمان

لا تكون dmPolicy: "open" عامة إلا عندما تتضمن قائمة السماح الفعلية للرسائل الخاصة "*". يتطلب الإعداد والتحقق ذلك الحرف البديل للتهيئات المفتوحة للعامة. إذا كانت الحالة الحالية تحتوي على open مع إدخالات allowFrom محددة، فإن وقت التشغيل يظل يسمح لهؤلاء المرسلين فقط، ولا توسّع الموافقات في مخزن الاقتران نطاق الوصول إلى open.

رموز الاقتران:

8 أحرف، بأحرف كبيرة، ومن دون أحرف ملتبسة (0O1I).
تنتهي صلاحيتها بعد ساعة واحدة. لا يرسل البوت رسالة الاقتران إلا عند إنشاء طلب جديد (مرة واحدة تقريبًا كل ساعة لكل مرسل).
يقتصر عدد طلبات اقتران الرسائل الخاصة المعلّقة على 3 لكل حساب قناة؛ وتُتجاهل الطلبات الإضافية حتى تنتهي صلاحية أحدها أو تتم الموافقة عليه.

الموافقة على مرسل

bash

openclaw pairing list telegramopenclaw pairing approve telegram &lt;CODE&gt;

أضف --notify إلى أمر الموافقة لإبلاغ مقدم الطلب على القناة نفسها. تقبل القنوات متعددة الحسابات --account <id>.

إذا لم يكن مالك الأوامر قد هُيّئ بعد، فإن الموافقة على رمز اقتران رسالة خاصة تؤدي أيضًا إلى تمهيد commands.ownerAllowFrom للمرسل الموافق عليه، مثل telegram:123456789. يوفر ذلك للإعدادات التي تُجرى لأول مرة مالكًا صريحًا للأوامر ذات الامتيازات ولمطالبات الموافقة على التنفيذ. بعد وجود مالك، لا تمنح موافقات الاقتران اللاحقة سوى الوصول إلى الرسائل الخاصة؛ ولا تضيف مزيدًا من المالكين.

القنوات المدعومة (أي Plugin قناة مثبّت يعلن دعم الاقتران؛ ويمكن للإضافات الخارجية مثل openclaw-weixin إضافة المزيد): discord، feishu، googlechat، imessage، irc، line، matrix، mattermost، msteams، nextcloud-talk، nostr، signal، slack، sms، synology-chat، telegram، twitch، whatsapp، zalo، zalouser.

مجموعات المرسلين القابلة لإعادة الاستخدام

استخدم accessGroups على المستوى الأعلى عندما ينبغي تطبيق مجموعة المرسلين الموثوقين نفسها على قنوات رسائل متعددة أو على قوائم السماح للرسائل الخاصة والمجموعات معًا.

تستخدم المجموعات الثابتة type: "message.senders" ويُشار إليها بواسطة accessGroup:<name> من قوائم السماح للقنوات:

json5

{  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"] },  },}

مجموعات الوصول موثقة بالتفصيل هنا: مجموعات الوصول

مكان تخزين الحالة

تُخزَّن في قاعدة بيانات حالة SQLite المشتركة في ~/.openclaw/state/openclaw.sqlite:

الطلبات المعلّقة في channel_pairing_requests
المرسلون الموافق عليهم في channel_pairing_allow_entries

سلوك تحديد النطاق حسب الحساب:

يُحدَّد مفتاح كل طلب ومرسل موافق عليه حسب القناة والحساب
لا يقرأ وقت التشغيل سوى صفوف SQLite الأساسية؛ ولا يدمج الملفات القديمة

كانت إصدارات Gateway الأقدم تكتب <channel>-pairing.json و <channel>-<accountId>-allowFrom.json ضمن ~/.openclaw/credentials/. تستورد عملية ترحيل بدء التشغيل وopenclaw doctor --fix هذه الملفات إلى SQLite وتزيل كل مصدر بعد نجاح الاستيراد. تعامل مع قاعدة بيانات SQLite على أنها حساسة لأن هذه الصفوف تتحكم في الوصول إلى مساعدك.

2) اقتران أجهزة Node (عُقد iOS/Android/macOS/من دون واجهة)

تتصل العُقد بـ Gateway باعتبارها أجهزة باستخدام role: node. ينشئ Gateway طلب اقتران جهاز يجب الموافقة عليه.

الاقتران من Control UI (موصى به)

استخدم جلسة Control UI متصلة بالفعل ولديها صلاحية الوصول operator.admin:

افتح Control UI وانتقل إلى Settings → Devices.
في صفحة Devices، انقر على Pair mobile device.
أبقِ Full access (recommended)، أو حدد Limited access لاستبعاد عناصر التحكم الإدارية في Gateway.
انقر على Create setup code.
افتح تطبيق OpenClaw على هاتفك ← Settings ← Gateway.
امسح رمز QR ضوئيًا أو الصق رمز الإعداد، ثم اتصل.

تتم الموافقة تلقائيًا على تطبيقي OpenClaw الرسميين لنظامي iOS وAndroid عندما تتطابق بيانات رمز الإعداد الوصفية الخاصة بهما. إذا عرض Pending approval طلبًا (على سبيل المثال، لعميل غير رسمي أو بيانات وصفية غير متطابقة)، فراجع دوره ونطاقاته قبل الموافقة عليه.

يُعطَّل الزر عندما لا تمتلك جلسة Control UI الحالية صلاحية وصول المسؤول. استخدم مسار الموافقة عبر CLI أدناه من مضيف Gateway في هذه الحالة.

الاقتران عبر Telegram

إذا كنت تستخدم Plugin ‏device-pair، فيمكنك إجراء اقتران الجهاز لأول مرة بالكامل من Telegram:

أرسل رسالة إلى البوت في Telegram: ‏/pair
يرد البوت برسالتين: رسالة إرشادات ورسالة رمز إعداد منفصلة (يسهل نسخها ولصقها في Telegram).
افتح تطبيق OpenClaw لنظام iOS على هاتفك ← Settings ← Gateway.
امسح رمز QR ضوئيًا (/pair qr) أو الصق رمز الإعداد واتصل.
يتصل تطبيق الهاتف الرسمي تلقائيًا. إذا عرض /pair pending طلبًا، فراجع دوره ونطاقاته قبل الموافقة عليه.

رمز الإعداد هو حمولة JSON مرمّزة باستخدام base64 وتحتوي على:

url: عنوان URL لاتصال WebSocket الخاص بـ Gateway ‏(ws://... أو wss://...)
urls: مسارات LAN/Tailnet المرتبة التي يمكن لتطبيق الهاتف تجربتها، عند توفرها
bootstrapToken: رمز تمهيد مميز للاستخدام مرة واحدة لمصافحة الاقتران الأولية؛ ينهي Gateway صلاحيته بعد 10 دقائق

شغّل /pair cleanup لإبطال رموز الإعداد غير المستخدمة بعد اكتمال الاقتران.

يحمل رمز التمهيد المميز هذا ملف تعريف تمهيد الاقتران المضمّن:

إعداد wss:// آمن (أو اتصال استرجاع على المضيف نفسه) يستخدم افتراضيًا node مع وصول كامل إلى operator للهاتف الأصلي
يظل رمز node المميز المُمرَّر scopes: []
يتضمن رمز operator المميز الافتراضي المُمرَّر operator.admin، وoperator.approvals، وoperator.read، وoperator.talk.secrets، و operator.write
يستبعد كل من Limited access في Control UI وopenclaw qr --limited النطاق operator.admin مع الإبقاء على نطاقات المشغّل الأخرى
يستخدم إعداد ws:// بنص صريح عبر LAN ملف التعريف المحدود نفسه تلقائيًا؛ هيّئ wss:// أو Tailscale Serve وأنشئ رمزًا جديدًا للوصول الكامل
يظل تدوير الرمز المميز أو إبطاله لاحقًا مقيدًا بعقد الدور الموافق عليه للجهاز ونطاقات المشغّل لجلسة المستدعي معًا

تعامل مع رمز الإعداد ككلمة مرور ما دام صالحًا.

تعرض صفحتا Settings → Gateway في iOS وAndroid وصولاً Full أو Limited. لترقية هاتف محدود، هيّئ أولًا مسار wss:// آمنًا أو Tailscale Serve، ثم أنشئ رمز إعداد جديدًا للوصول الكامل، وامسحه ضوئيًا أو الصقه في صفحة الإعدادات تلك، وأعد الاتصال.

لاقتران الهواتف عن بُعد عبر Tailscale أو الشبكات العامة أو غيرها، استخدم Tailscale Serve/Funnel أو عنوان URL آخر لـ Gateway يستخدم wss://. لا تُقبل رموز إعداد ws:// ذات النص الصريح إلا لاتصال الاسترجاع وعناوين LAN الخاصة ومضيفي Bonjour ‏.local ومضيف محاكي Android. تحصل المسارات ذات النص الصريح غير الاسترجاعية على وصول محدود. تظل عناوين CGNAT في Tailnet وأسماء .ts.net والمضيفون العموميون مرفوضة افتراضيًا قبل إصدار رمز QR/رمز الإعداد.

بالنسبة إلى عناوين URL للإعداد gateway.bind=lan، يكتشف OpenClaw جذور HTTPS الدائمة لـ Tailscale Serve التي تنوب عن منفذ الاسترجاع الخاص بـ Gateway النشط، ويعلن عنها إلى جانب مسار LAN. لا يضيف أمر الإعداد هذا المسار الاحتياطي إلا لـ lan؛ بينما يحتفظ custom وtailnet بمساراتهما المُعلنة صراحةً. يختبر تطبيق iOS المسارات المُعلنة بالترتيب ويحفظ أول نقطة نهاية يمكن الوصول إليها.

الموافقة على جهاز Node

bash

openclaw devices listopenclaw devices approve <requestId>openclaw devices reject <requestId>

عند رفض موافقة صريحة لأن جلسة الجهاز المقترن التي تجري الموافقة فُتحت بنطاق مخصص للاقتران فقط، تعيد CLI محاولة الطلب نفسه باستخدام operator.admin. يتيح ذلك لجهاز مقترن حالي يمتلك قدرات المسؤول استعادة اقتران جديد لـ Control UI/المتصفح دون تعديل مخزن الاقتران يدويًا. يظل Gateway يتحقق من الاتصال المُعاد؛ وتظل الرموز المميزة التي لا يمكنها المصادقة باستخدام operator.admin محظورة.

إذا أعاد الجهاز نفسه المحاولة بتفاصيل مصادقة مختلفة (مثل دور/نطاقات/مفتاح عام مختلف)، يُستبدل الطلب المعلّق السابق ويُنشأ requestId جديد.

الموافقة التلقائية الاختيارية على عُقد CIDR الموثوقة

يظل اقتران الأجهزة يدويًا افتراضيًا. لشبكات العُقد الخاضعة لرقابة صارمة، يمكنك الاشتراك في الموافقة التلقائية على العُقد لأول مرة باستخدام نطاقات CIDR أو عناوين IP محددة صراحةً:

json5

{  gateway: {    nodes: {      pairing: {        autoApproveCidrs: ["192.168.1.0/24"],      },    },  },}

لا ينطبق هذا إلا على طلبات اقتران role: node الجديدة التي لا تتضمن نطاقات مطلوبة. يظل المشغّلون والمتصفحات وعملاء Control UI وWebChat بحاجة إلى موافقة يدوية. كما تظل تغييرات الدور والنطاق والبيانات الوصفية والمفتاح العام بحاجة إلى موافقة يدوية.

تخزين حالة اقتران Node