الاقتران

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

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

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

# 1) اقتران الرسائل المباشرة (الوصول إلى الدردشة الواردة)

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

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

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

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

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

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

openclaw pairing list telegram
openclaw pairing approve telegram <CODE>

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

القنوات المدعومة: bluebubbles, 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/Nodes بلا واجهة)

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

# الاقتران عبر Telegram (موصى به لـ iOS)

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

1. في Telegram، أرسل إلى البوت الخاص بك: /pair
2. يرد البوت برسالتين: رسالة تعليمات ورسالة رمز إعداد منفصلة (سهلة النسخ/اللصق في Telegram).
3. على هاتفك، افتح تطبيق OpenClaw على iOS ← الإعدادات ← Gateway.
4. امسح رمز QR أو الصق رمز الإعداد واتصل.
5. بالعودة إلى Telegram: /pair pending (راجع معرّفات الطلبات، والدور، والنطاقات)، ثم وافق.

رمز الإعداد هو حمولة JSON مشفرة بـ base64 تحتوي على:

• url: عنوان URL لـ WebSocket الخاص بـ Gateway (ws://... أو wss://...)
• bootstrapToken: رمز تمهيد قصير العمر لجهاز واحد يُستخدم لمصافحة الاقتران الأولية

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

• يبقى رمز node الأساسي المسلَّم scopes: []
• أي رمز operator مسلَّم يبقى محدودًا بقائمة سماح التمهيد: operator.approvals, operator.read, operator.talk.secrets, operator.write
• فحوصات نطاق التمهيد مسبوقة بالدور، وليست مجموعة نطاقات مسطحة واحدة: إدخالات نطاق operator لا تلبي إلا طلبات operator، ويجب على الأدوار غير operator أن تطلب النطاقات تحت بادئة دورها الخاصة
• يبقى تدوير/إبطال الرموز لاحقًا محدودًا بكل من عقد الدور الموافق عليه للجهاز ونطاقات operator لجلسة المستدعي

عامل رمز الإعداد مثل كلمة مرور أثناء صلاحيته.

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

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

openclaw devices list
openclaw devices approve <requestId>
openclaw devices reject <requestId>

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

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

# موافقة تلقائية اختيارية على Node عبر CIDR موثوق

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

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

ينطبق هذا فقط على طلبات اقتران role: node الجديدة بلا نطاقات مطلوبة. لا يزال عملاء operator والمتصفح وControl UI وWebChat يتطلبون موافقة يدوية. ولا تزال تغييرات الدور والنطاق والبيانات الوصفية والمفتاح العام تتطلب موافقة يدوية.

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

تُخزَّن ضمن ~/.openclaw/devices/:

• pending.json (قصير العمر؛ تنتهي صلاحية الطلبات المعلقة)
• paired.json (الأجهزة المقترنة + الرموز)

# ملاحظات

• واجهة API القديمة node.pair.* (CLI: openclaw nodes pending|approve|reject|remove|rename) هي مخزن اقتران منفصل مملوك لـ Gateway. لا تزال WS nodes تتطلب اقتران الجهاز.
• سجل الاقتران هو مصدر الحقيقة الدائم للأدوار الموافق عليها. تبقى رموز الجهاز النشطة محدودة بمجموعة الأدوار الموافق عليها هذه؛ ولا ينشئ إدخال رمز عابر خارج الأدوار الموافق عليها وصولًا جديدًا.

# مستندات ذات صلة

• نموذج الأمان + حقن الموجهات: الأمان
• التحديث بأمان (تشغيل الطبيب): التحديث
• تكوينات القنوات:
  • Telegram: Telegram
  • WhatsApp: WhatsApp
  • Signal: Signal
  • iMessage: iMessage
  • BlueBubbles (جسر iMessage قديم): BlueBubbles
  • Discord: Discord
  • Slack: Slack