الانتقال إلى المحتوى الرئيسي

​
WhatsApp (قناة Web)

الحالة: جاهزة للإنتاج عبر WhatsApp Web ‏(Baileys). يمتلك gateway الجلسة (الجلسات) المرتبطة.

​
التثبيت (عند الطلب)

  • يطلب كل من الإعداد التفاعلي (openclaw onboard) وopenclaw channels add --channel whatsapp تثبيت plugin WhatsApp في أول مرة تحددها فيها.
  • يوفّر openclaw channels login --channel whatsapp أيضًا تدفق التثبيت عندما لا يكون plugin موجودًا بعد.
  • قناة التطوير + نسخة git محلية: تكون القيمة الافتراضية هي مسار plugin المحلي.
  • Stable/Beta: القيمة الافتراضية هي حزمة npm ‏@openclaw/whatsapp.
يبقى التثبيت اليدوي متاحًا: 
openclaw plugins install @openclaw/whatsapp

الاقتران

سياسة الرسائل الخاصة الافتراضية هي الاقتران للمرسلين غير المعروفين.

استكشاف أخطاء القنوات وإصلاحها

أدوات التشخيص وخطط الإصلاح عبر القنوات.

تكوين Gateway

أنماط وأمثلة تكوين القنوات الكاملة.

​
الإعداد السريع

1

تكوين سياسة الوصول إلى WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15551234567"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
}
2

ربط WhatsApp ‏(QR)

openclaw channels login --channel whatsapp
لحساب محدد:
openclaw channels login --channel whatsapp --account work
3

بدء تشغيل gateway

openclaw gateway
4

الموافقة على أول طلب اقتران (إذا كنت تستخدم وضع الاقتران)

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>
تنتهي صلاحية طلبات الاقتران بعد ساعة واحدة. الحد الأقصى للطلبات المعلقة هو 3 لكل قناة.
يوصي OpenClaw بتشغيل WhatsApp على رقم منفصل كلما أمكن ذلك. (تم تحسين بيانات تعريف القناة وتدفق الإعداد لهذا الإعداد، لكن الإعدادات التي تستخدم الرقم الشخصي مدعومة أيضًا.)

​
أنماط النشر

هذا هو وضع التشغيل الأنظف:
  • هوية WhatsApp منفصلة لـ OpenClaw
  • حدود أوضح لقوائم السماح بالرسائل الخاصة والتوجيه
  • احتمال أقل لحدوث ارتباك في الدردشة الذاتية
نمط السياسة الأدنى:
{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}
يدعم الإعداد التفاعلي وضع الرقم الشخصي ويكتب خط أساس مناسبًا للدردشة الذاتية:
  • dmPolicy: "allowlist"
  • تتضمن allowFrom رقمك الشخصي
  • selfChatMode: true
في وقت التشغيل، تعتمد وسائل الحماية من الدردشة الذاتية على الرقم الذاتي المرتبط وallowFrom.
قناة منصة المراسلة في بنية قنوات OpenClaw الحالية تستند إلى WhatsApp Web ‏(Baileys).لا توجد قناة مراسلة WhatsApp منفصلة عبر Twilio ضمن سجل قنوات الدردشة المدمج.

​
نموذج وقت التشغيل

  • يمتلك gateway مقبس WhatsApp وحلقة إعادة الاتصال.
  • تتطلب عمليات الإرسال الصادرة وجود مستمع WhatsApp نشط للحساب الهدف.
  • يتم تجاهل محادثات الحالة والبث (@status و@broadcast).
  • تستخدم المحادثات المباشرة قواعد جلسات الرسائل الخاصة (session.dmScope؛ القيمة الافتراضية main تؤدي إلى طي الرسائل الخاصة ضمن الجلسة الرئيسية للوكيل).
  • تكون جلسات المجموعات معزولة (agent:<agentId>:whatsapp:group:<jid>).

​
التحكم في الوصول والتفعيل

يتحكم channels.whatsapp.dmPolicy في الوصول إلى الدردشة المباشرة:
  • pairing (الافتراضي)
  • allowlist
  • open (يتطلب أن تتضمن allowFrom القيمة "*")
  • disabled
تقبل allowFrom أرقامًا بنمط E.164 (ويتم تطبيعها داخليًا).تجاوز الحسابات المتعددة: تكون channels.whatsapp.accounts.<id>.dmPolicy (وallowFrom) لها الأولوية على القيم الافتراضية على مستوى القناة لذلك الحساب.تفاصيل سلوك وقت التشغيل:
  • يتم الاحتفاظ بعمليات الاقتران في مخزن السماح الخاص بالقناة ودمجها مع allowFrom المكوّنة
  • إذا لم يتم تكوين أي قائمة سماح، يُسمح بالرقم الذاتي المرتبط افتراضيًا
  • لا يتم أبدًا إقران الرسائل الخاصة الصادرة fromMe تلقائيًا

​
سلوك الرقم الشخصي والدردشة الذاتية

عندما يكون الرقم الذاتي المرتبط موجودًا أيضًا في allowFrom، يتم تفعيل ضمانات الدردشة الذاتية في WhatsApp:
  • تخطي إيصالات القراءة في أدوار الدردشة الذاتية
  • تجاهل سلوك التشغيل التلقائي لإشارة JID الذي قد يؤدي بخلاف ذلك إلى تنبيهك لنفسك
  • إذا لم تكن messages.responsePrefix معيّنة، فإن ردود الدردشة الذاتية تستخدم افتراضيًا [{identity.name}] أو [openclaw]

​
تطبيع الرسائل والسياق

تُغلَّف رسائل WhatsApp الواردة في الغلاف الوارد المشترك.إذا وُجد رد مقتبس، يُضاف السياق بهذا الشكل:
[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]
كما تتم تعبئة حقول بيانات تعريف الرد عند توفرها (ReplyToId وReplyToBody وReplyToSender وJID/E.164 الخاص بالمرسل).
يتم تطبيع الرسائل الواردة التي تحتوي على وسائط فقط باستخدام عناصر نائبة مثل:
  • <media:image>
  • <media:video>
  • <media:audio>
  • <media:document>
  • <media:sticker>
يتم تطبيع حمولات الموقع وجهات الاتصال إلى سياق نصي قبل التوجيه.
بالنسبة إلى المجموعات، يمكن تخزين الرسائل غير المعالجة مؤقتًا وحقنها كسياق عندما يتم تشغيل bot أخيرًا.
  • الحد الافتراضي: 50
  • التكوين: channels.whatsapp.historyLimit
  • البديل: messages.groupChat.historyLimit
  • 0 يعطّل الميزة
علامات الحقن:
  • [Chat messages since your last reply - for context]
  • [Current message - respond to this]
تكون إيصالات القراءة ممكّنة افتراضيًا لرسائل WhatsApp الواردة المقبولة.التعطيل عالميًا:
{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}
تجاوز لكل حساب:
{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}
تتخطى أدوار الدردشة الذاتية إيصالات القراءة حتى عند تمكينها عالميًا.

​
التسليم والتجزئة والوسائط

  • حد التجزئة الافتراضي: channels.whatsapp.textChunkLimit = 4000
  • channels.whatsapp.chunkMode = "length" | "newline"
  • يفضل وضع newline حدود الفقرات (الأسطر الفارغة)، ثم يعود إلى التجزئة الآمنة حسب الطول
  • يدعم حمولات الصور والفيديو والصوت (ملاحظة صوتية PTT) والمستندات
  • تتم إعادة كتابة audio/ogg إلى audio/ogg; codecs=opus للتوافق مع الملاحظات الصوتية
  • يتم دعم تشغيل GIF المتحرك عبر gifPlayback: true عند إرسال الفيديو
  • تُطبَّق التسميات التوضيحية على أول عنصر وسائط عند إرسال حمولات رد متعددة الوسائط
  • يمكن أن يكون مصدر الوسائط هو HTTP(S) أو file:// أو مسارات محلية
  • حد حفظ الوسائط الواردة: channels.whatsapp.mediaMaxMb (الافتراضي 50)
  • حد إرسال الوسائط الصادرة: channels.whatsapp.mediaMaxMb (الافتراضي 50)
  • تستخدم تجاوزات كل حساب channels.whatsapp.accounts.<accountId>.mediaMaxMb
  • يتم تحسين الصور تلقائيًا (تغيير الحجم/اجتياز الجودة) لتلائم الحدود
  • عند فشل إرسال الوسائط، يرسل البديل الخاص بأول عنصر تحذيرًا نصيًا بدلًا من إسقاط الرد بصمت

​
مستوى التفاعل

يتحكم channels.whatsapp.reactionLevel في مدى استخدام الوكيل لتفاعلات emoji على WhatsApp:
المستوىتفاعلات الإقرارالتفاعلات التي يبدأها الوكيلالوصف
"off"لالالا توجد تفاعلات إطلاقًا
"ack"نعملاتفاعلات الإقرار فقط (إيصال ما قبل الرد)
"minimal"نعمنعم (بشكل محافظ)تفاعلات الإقرار + تفاعلات الوكيل مع توجيه محافظ
"extensive"نعمنعم (مشجعة)تفاعلات الإقرار + تفاعلات الوكيل مع توجيه مشجع
الافتراضي: "minimal". تستخدم تجاوزات كل حساب channels.whatsapp.accounts.<id>.reactionLevel. 
{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​
تفاعلات الإقرار

يدعم WhatsApp تفاعلات الإقرار الفورية عند الاستلام الوارد عبر channels.whatsapp.ackReaction. تخضع تفاعلات الإقرار إلى reactionLevel — ويتم إخفاؤها عندما تكون قيمة reactionLevel هي "off". 
{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}
ملاحظات السلوك:
  • تُرسَل فورًا بعد قبول الرسالة الواردة (قبل الرد)
  • يتم تسجيل الإخفاقات لكنها لا تمنع تسليم الرد العادي
  • في وضع المجموعة mentions، يتم التفاعل في الأدوار التي يتم تشغيلها بالإشارة؛ ويعمل تفعيل المجموعة always كتجاوز لهذا الفحص
  • يستخدم WhatsApp الإعداد channels.whatsapp.ackReaction (ولا يُستخدم هنا الإعداد القديم messages.ackReaction)

​
الحسابات المتعددة وبيانات الاعتماد

  • تأتي معرّفات الحسابات من channels.whatsapp.accounts
  • اختيار الحساب الافتراضي: default إذا كان موجودًا، وإلا أول معرّف حساب مكوَّن (مرتب)
  • يتم تطبيع معرّفات الحسابات داخليًا لأغراض البحث
  • مسار المصادقة الحالي: ~/.openclaw/credentials/whatsapp/<accountId>/creds.json
  • ملف النسخة الاحتياطية: creds.json.bak
  • ما زالت مصادقة النظام القديم الافتراضية في ~/.openclaw/credentials/ معرّفًا بها/تُنقل لتدفقات الحساب الافتراضي
يؤدي openclaw channels logout --channel whatsapp [--account <id>] إلى مسح حالة مصادقة WhatsApp لذلك الحساب.في أدلة المصادقة القديمة، يتم الاحتفاظ بـ oauth.json بينما تتم إزالة ملفات مصادقة Baileys.

​
الأدوات والإجراءات وعمليات كتابة التكوين

  • يتضمن دعم أدوات الوكيل إجراء تفاعل WhatsApp ‏(react).
  • بوابات الإجراءات:
    • channels.whatsapp.actions.reactions
    • channels.whatsapp.actions.polls
  • تكون عمليات كتابة التكوين التي تبدأها القناة ممكّنة افتراضيًا (عطّلها عبر channels.whatsapp.configWrites=false).

​
استكشاف الأخطاء وإصلاحها

العَرَض: تشير حالة القناة إلى أنها غير مرتبطة.الإصلاح:
openclaw channels login --channel whatsapp
openclaw channels status
العَرَض: حساب مرتبط مع انقطاعات متكررة أو محاولات إعادة اتصال.الإصلاح:
openclaw doctor
openclaw logs --follow
إذا لزم الأمر، أعد الربط باستخدام channels login.
تفشل عمليات الإرسال الصادرة بسرعة عندما لا يوجد مستمع gateway نشط للحساب الهدف.تأكد من أن gateway يعمل وأن الحساب مرتبط.
تحقق بالترتيب التالي:
  • groupPolicy
  • groupAllowFrom / allowFrom
  • إدخالات قائمة سماح groups
  • ضبط الإشارة (requireMention + أنماط الإشارة)
  • المفاتيح المكررة في openclaw.json ‏(JSON5): تتجاوز الإدخالات اللاحقة الإدخالات السابقة، لذا احتفظ بقيمة groupPolicy واحدة لكل نطاق
يجب أن يستخدم وقت تشغيل WhatsApp gateway بيئة Node. تُصنَّف Bun على أنها غير متوافقة مع التشغيل المستقر لـ WhatsApp/Telegram gateway.

​
مؤشرات مرجع التكوين

المرجع الأساسي: حقول WhatsApp عالية الأهمية:
  • الوصول: dmPolicy وallowFrom وgroupPolicy وgroupAllowFrom وgroups
  • التسليم: textChunkLimit وchunkMode وmediaMaxMb وsendReadReceipts وackReaction وreactionLevel
  • الحسابات المتعددة: accounts.<id>.enabled وaccounts.<id>.authDir والتجاوزات على مستوى الحساب
  • العمليات: configWrites وdebounceMs وweb.enabled وweb.heartbeatSeconds وweb.reconnect.*
  • سلوك الجلسة: session.dmScope وhistoryLimit وdmHistoryLimit وdms.<id>.historyLimit

​
ذو صلة