WhatsApp

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

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

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

يبقى التثبيت اليدوي متاحًا:

openclaw plugins install @openclaw/whatsapp

استخدم الحزمة المجرّدة لمتابعة وسم الإصدار الرسمي الحالي. ثبّت إصدارًا دقيقًا فقط عندما تحتاج إلى تثبيت قابل للتكرار.

على Windows، يحتاج WhatsApp plugin إلى وجود Git في PATH أثناء تثبيت npm لأن إحدى تبعيات Baileys/libsignal الخاصة به تُجلب من عنوان URL خاص بـ git. ثبّت Git for Windows، ثم أعد تشغيل الصدفة وأعد تشغيل التثبيت:

winget install --id Git.Git -e

يعمل Portable Git أيضًا إذا كان دليل bin الخاص به موجودًا في PATH.

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

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

openclaw channels login --channel whatsapp

openclaw channels login --channel whatsapp --account work

openclaw channels add --channel whatsapp --account work --auth-dir /path/to/wa-auth
openclaw channels login --channel whatsapp --account work

openclaw gateway

openclaw pairing list whatsapp
openclaw pairing approve whatsapp <CODE>

# أنماط النشر

{
  channels: {
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15551234567"],
    },
  },
}

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

• يتولى Gateway ملكية مقبس WhatsApp وحلقة إعادة الاتصال.
• يستخدم مراقب إعادة الاتصال نشاط نقل WhatsApp Web، وليس حجم رسائل التطبيق الواردة فقط، لذلك لا تُعاد تهيئة جلسة جهاز مرتبط هادئة لمجرد أن أحدًا لم يرسل رسالة مؤخرًا. لا يزال حد صمت أطول على مستوى التطبيق يفرض إعادة الاتصال إذا استمرت إطارات النقل في الوصول لكن لم تُعالج أي رسائل تطبيق خلال نافذة المراقب؛ وبعد إعادة اتصال عابرة لجلسة نشطة مؤخرًا، يستخدم فحص صمت التطبيق هذا مهلة الرسائل العادية لنافذة الاسترداد الأولى.
• توقيتات مقبس Baileys صريحة ضمن web.whatsapp.*: يتحكم keepAliveIntervalMs في نبضات تطبيق WhatsApp Web، ويتحكم connectTimeoutMs في مهلة مصافحة الفتح، ويتحكم defaultQueryTimeoutMs في مهل استعلامات Baileys.
• تتطلب عمليات الإرسال الصادرة مستمع WhatsApp نشطًا للحساب الهدف.
• تُرفق عمليات الإرسال إلى المجموعات بيانات تعريف الإشارات الأصلية لرموز @+<digits> و@<digits> في النص وتعليقات الوسائط عندما يطابق الرمز بيانات تعريف مشارك WhatsApp الحالية، بما في ذلك المجموعات المدعومة بـ LID.
• يتم تجاهل محادثات الحالة والبث (@status, @broadcast).
• يتبع مراقب إعادة الاتصال نشاط نقل WhatsApp Web، وليس حجم رسائل التطبيق الواردة فقط: تبقى جلسات الأجهزة المرتبطة الهادئة قائمة ما دامت إطارات النقل مستمرة، لكن توقف النقل يفرض إعادة الاتصال قبل مسار قطع الاتصال البعيد اللاحق بكثير.
• تستخدم المحادثات المباشرة قواعد جلسات الرسائل المباشرة (session.dmScope؛ يدمج الافتراضي main الرسائل المباشرة في جلسة الوكيل الرئيسية).
• جلسات المجموعات معزولة (agent:<agentId>:whatsapp:group:<jid>).
• يمكن أن تكون WhatsApp Channels/Newsletters أهدافًا صادرة صريحة باستخدام JID الأصلي @newsletter. تستخدم الإرسالات الصادرة إلى النشرات الإخبارية بيانات تعريف جلسة القناة (agent:<agentId>:whatsapp:channel:<jid>) بدل دلالات جلسات الرسائل المباشرة.
• يراعي نقل WhatsApp Web متغيرات بيئة الوكيل القياسية على مضيف Gateway (HTTPS_PROXY, HTTP_PROXY, NO_PROXY / المتغيرات بالأحرف الصغيرة). فضّل إعداد الوكيل على مستوى المضيف على إعدادات وكيل WhatsApp الخاصة بالقناة.
• عند تفعيل messages.removeAckAfterReply، يمسح OpenClaw تفاعل إقرار WhatsApp بعد تسليم رد مرئي.

# خطافات Plugin والخصوصية

يمكن أن تحتوي رسائل WhatsApp الواردة على محتوى رسائل شخصية، وأرقام هاتف، ومعرفات مجموعات، وأسماء مرسلين، وحقول ربط جلسات. لهذا السبب، لا يبث WhatsApp حمولات خطاف message_received الواردة إلى plugins إلا إذا اخترت ذلك صراحةً:

{
  channels: {
    whatsapp: {
      pluginHooks: {
        messageReceived: true,
      },
    },
  },
}

يمكنك حصر الاشتراك في حساب واحد:

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          pluginHooks: {
            messageReceived: true,
          },
        },
      },
    },
  },
}

فعّل هذا فقط لـ plugins التي تثق بها لتلقي محتوى رسائل WhatsApp الواردة ومعرفاتها.

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

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

عندما يكون رقم الذات المرتبط موجودًا أيضًا في allowFrom، تُفعّل وسائل حماية المحادثة الذاتية في WhatsApp:

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

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

[Replying to <sender> id:<stanzaId>]
<quoted body or media placeholder>
[/Replying]

{
  channels: {
    whatsapp: {
      sendReadReceipts: false,
    },
  },
}

{
  channels: {
    whatsapp: {
      accounts: {
        work: {
          sendReadReceipts: false,
        },
      },
    },
  },
}

# التسليم، والتقسيم إلى أجزاء، والوسائط

# اقتباس الردود

يدعم WhatsApp اقتباس الردود الأصلي، حيث تقتبس الردود الصادرة الرسالة الواردة بشكل مرئي. تحكّم به باستخدام channels.whatsapp.replyToMode.

الافتراضي هو "off". تستخدم التجاوزات لكل حساب channels.whatsapp.accounts.<id>.replyToMode.

{
  channels: {
    whatsapp: {
      replyToMode: "first",
    },
  },
}

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

يتحكم channels.whatsapp.reactionLevel في مدى استخدام الوكيل لتفاعلات الرموز التعبيرية على WhatsApp:

الافتراضي: "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 القديم هنا)

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

# الأدوات والإجراءات وكتابات التهيئة

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

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

openclaw channels login --channel whatsapp
openclaw channels status

{
  web: {
    whatsapp: {
      keepAliveIntervalMs: 15000,
      connectTimeoutMs: 60000,
      defaultQueryTimeoutMs: 60000,
    },
  },
}

openclaw doctor
openclaw logs --follow

# مطالبات النظام

يدعم WhatsApp مطالبات النظام بأسلوب Telegram للمجموعات والمحادثات المباشرة عبر خرائط groups وdirect.

هرمية الحل لرسائل المجموعات:

تُحدَّد خريطة groups الفعالة أولًا: إذا كان الحساب يعرّف groups الخاصة به، فإنها تستبدل خريطة groups الجذرية بالكامل (لا يوجد دمج عميق). ثم يُشغّل البحث عن المطالبة على الخريطة المفردة الناتجة:

1. مطالبة نظام خاصة بالمجموعة (groups["<groupId>"].systemPrompt): تُستخدم عندما يكون إدخال المجموعة المحددة موجودًا في الخريطة و يكون مفتاح systemPrompt الخاص به معرّفًا. إذا كان systemPrompt سلسلة فارغة ("")، فيُحجب حرف البدل ولا تُطبّق أي مطالبة نظام.
2. مطالبة نظام حرف البدل للمجموعات (groups["*"].systemPrompt): تُستخدم عندما يكون إدخال المجموعة المحددة غائبًا تمامًا من الخريطة، أو عندما يكون موجودًا لكنه لا يعرّف مفتاح systemPrompt.

هرمية الحل للرسائل المباشرة:

تُحدَّد خريطة direct الفعالة أولًا: إذا كان الحساب يعرّف direct الخاصة به، فإنها تستبدل خريطة direct الجذرية بالكامل (لا يوجد دمج عميق). ثم يُشغّل البحث عن المطالبة على الخريطة المفردة الناتجة:

1. موجه النظام الخاص بمحادثة مباشرة محددة (direct["<peerId>"].systemPrompt): يُستخدم عندما يكون إدخال النظير المحدد موجودًا في الخريطة و يكون مفتاح systemPrompt الخاص به معرّفًا. إذا كان systemPrompt سلسلة فارغة ("")، فسيتم كبت حرف البدل ولا يُطبَّق أي موجه نظام.
2. موجه نظام حرف البدل للمحادثات المباشرة (direct["*"].systemPrompt): يُستخدم عندما يكون إدخال النظير المحدد غائبًا تمامًا عن الخريطة، أو عندما يكون موجودًا لكنه لا يعرّف مفتاح systemPrompt.

الاختلاف عن سلوك الحسابات المتعددة في Telegram: في Telegram، يتم كبت groups الجذر عمدًا لكل الحسابات في إعداد متعدد الحسابات، حتى الحسابات التي لا تعرّف groups خاصة بها، وذلك لمنع البوت من تلقي رسائل مجموعات لا ينتمي إليها. لا يطبّق WhatsApp هذا الحارس: تُورَّث groups الجذر وdirect الجذر دائمًا من الحسابات التي لا تعرّف تجاوزًا على مستوى الحساب، بغض النظر عن عدد الحسابات المهيأة. في إعداد WhatsApp متعدد الحسابات، إذا أردت موجهات مجموعات أو محادثات مباشرة لكل حساب، فعرّف الخريطة الكاملة ضمن كل حساب صراحةً بدل الاعتماد على الافتراضيات على مستوى الجذر.

سلوك مهم:

• channels.whatsapp.groups هي خريطة تهيئة لكل مجموعة وقائمة سماح للمجموعات على مستوى الدردشة في الوقت نفسه. في نطاق الجذر أو الحساب، يعني groups["*"] أن "كل المجموعات مسموح لها بالدخول" في ذلك النطاق.
• لا تضف systemPrompt لمجموعة بحرف بدل إلا عندما تريد بالفعل أن يسمح ذلك النطاق بدخول كل المجموعات. إذا كنت لا تزال تريد أن تكون مجموعة ثابتة فقط من معرّفات المجموعات مؤهلة، فلا تستخدم groups["*"] كافتراضي للموجه. بدلًا من ذلك، كرر الموجه في كل إدخال مجموعة مسموح به صراحةً.
• قبول المجموعة وتفويض المرسل فحصان منفصلان. يوسّع groups["*"] مجموعة المجموعات التي يمكنها الوصول إلى معالجة المجموعات، لكنه لا يفوّض بحد ذاته كل مرسل في تلك المجموعات. لا يزال وصول المرسلين مضبوطًا بشكل منفصل بواسطة channels.whatsapp.groupPolicy وchannels.whatsapp.groupAllowFrom.
• لا يملك channels.whatsapp.direct التأثير الجانبي نفسه للرسائل المباشرة. يوفّر direct["*"] فقط تهيئة افتراضية لدردشة مباشرة بعد قبول الرسالة المباشرة بالفعل بواسطة dmPolicy مع allowFrom أو قواعد مخزن الاقتران.

مثال:

{
  channels: {
    whatsapp: {
      groups: {
        // Use only if all groups should be admitted at the root scope.
        // Applies to all accounts that do not define their own groups map.
        "*": { systemPrompt: "Default prompt for all groups." },
      },
      direct: {
        // Applies to all accounts that do not define their own direct map.
        "*": { systemPrompt: "Default prompt for all direct chats." },
      },
      accounts: {
        work: {
          groups: {
            // This account defines its own groups, so root groups are fully
            // replaced. To keep a wildcard, define "*" explicitly here too.
            "[email protected]": {
              requireMention: false,
              systemPrompt: "Focus on project management.",
            },
            // Use only if all groups should be admitted in this account.
            "*": { systemPrompt: "Default prompt for work groups." },
          },
          direct: {
            // This account defines its own direct map, so root direct entries are
            // fully replaced. To keep a wildcard, define "*" explicitly here too.
            "+15551234567": { systemPrompt: "Prompt for a specific work direct chat." },
            "*": { systemPrompt: "Default prompt for work direct chats." },
          },
        },
      },
    },
  },
}

# مؤشرات مرجع التهيئة

المرجع الأساسي:

• مرجع التهيئة - WhatsApp

حقول 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.*, web.whatsapp.*
• سلوك الجلسة: session.dmScope, historyLimit, dmHistoryLimit, dms.<id>.historyLimit
• الموجهات: groups.<id>.systemPrompt, groups["*"].systemPrompt, direct.<id>.systemPrompt, direct["*"].systemPrompt

# ذو صلة

• الاقتران
• المجموعات
• الأمن
• توجيه القنوات
• توجيه الوكلاء المتعددين
• استكشاف الأخطاء وإصلاحها