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

​
WhatsApp (قناة الويب)

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

الإقران

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

استكشاف أخطاء القناة

تشخيصات متعددة القنوات وأدلة الإصلاح.

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

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

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

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

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

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

عندما يكون الرقم الذاتي المرتبط موجودًا أيضًا ضمن allowFrom، يتم تفعيل حمايات الدردشة مع الذات:
  • تخطي إيصالات القراءة لدورات الدردشة مع الذات
  • تجاهل سلوك التشغيل التلقائي لمعرّفات الإشارة الذي قد يؤدي إلى تنبيه نفسك
  • إذا لم يتم تعيين 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>
يتم تحويل بيانات الموقع وجهات الاتصال إلى سياق نصي قبل التوجيه.
في المجموعات، يمكن تخزين الرسائل غير المعالجة مؤقتًا وحقنها كسياق عند تشغيل البوت أخيرًا.
  • الحد الافتراضي: 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 عند إرسال الفيديو
  • يتم تطبيق العنوان (Caption) على أول عنصر وسائط عند إرسال رد متعدد الوسائط
  • يمكن أن يكون مصدر الوسائط HTTP(S) أو file:// أو مسارات محلية
  • حد حفظ الوسائط الواردة: channels.whatsapp.mediaMaxMb (الافتراضي 50)
  • حد الوسائط الصادرة للردود التلقائية: agents.defaults.mediaMaxMb (الافتراضي 5MB)
  • يتم تحسين الصور تلقائيًا (تغيير الحجم/الجودة) لتناسب الحدود
  • عند فشل إرسال الوسائط، يتم إرسال تحذير نصي بدلاً من إسقاط الرد بصمت

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

يدعم WhatsApp تفاعلات إقرار فورية عند استلام الرسائل الواردة عبر channels.whatsapp.ackReaction. 
{
  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 + أنماط الإشارة)
يجب تشغيل بيئة WhatsApp في الـ Gateway باستخدام Node. يتم وضع علامة على Bun كغير متوافق للتشغيل المستقر لقنوات WhatsApp/Telegram.

​
مراجع التهيئة

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

​
مرتبط