WhatsApp

​

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

• يطلب الإعداد الأولي (openclaw onboard) و openclaw channels add --channel whatsapp تثبيت Plugin الخاص بـ WhatsApp في أول مرة تختاره فيها.
• يوفّر openclaw channels login --channel whatsapp أيضًا مسار التثبيت عندما لا يكون Plugin موجودًا بعد.
• قناة التطوير + نسخة git: تستخدم مسار Plugin المحلي افتراضيًا.
• المستقر/بيتا: يثبّت Plugin الرسمي @openclaw/whatsapp من ClawHub أولًا، مع npm كخيار احتياطي.
• يُوزَّع وقت تشغيل WhatsApp خارج حزمة OpenClaw الأساسية على npm حتى تبقى اعتماديات وقت التشغيل الخاصة بـ WhatsApp مع Plugin الخارجي.

openclaw plugins install clawhub:@openclaw/whatsapp

​

إعداد سريع

{
  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>

​

الاتصال بمقدم الطلب الحالي باستخدام MeowCaller (تجريبي)

{
  "channels": {
    "whatsapp": {
      "actions": {
        "calls": true
      }
    }
  }
}

git clone --branch feat/send-only-notify https://github.com/steipete/meowcaller.git
cd meowcaller
git checkout 752050471fc2bf7a8cdfbf7dbd3cd4e865d85d3f
mkdir -p "$HOME/.local/bin"
go build -o "$HOME/.local/bin/meowcaller" ./cmd/meowcaller

state_dir="$HOME/.openclaw/credentials/whatsapp-calls/default"
mkdir -p "$state_dir"
chmod 700 "$state_dir"
meowcaller pair --store "$state_dir/wa-voip.db"

• مكالمات صوتية صادرة فردية فقط
• لا أرقام وجهة عشوائية
• لا مصادقة مشتركة مع اتصال الدردشة
• لا مكالمات ذاتية من وضع الرقم الشخصي/الدردشة الذاتية
• الصوت المولّد محدود إلى 60 ثانية
• لا إيصال سماعية من جهة الهاتف يتجاوز اكتمال الإجابة/التشغيل/إنهاء المكالمة في MeowCaller
• يوقف OpenClaw العملية المرافقة بعد نافذة محدودة من 115 إلى 175 ثانية، بما يشمل مراحل اتصال MeowCaller والإجابة والتشغيل والإيقاف

​

أنماط النشر

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

​

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

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

​

مطالبات الموافقة

{
  approvals: {
    exec: {
      enabled: true,
      mode: "session",
    },
    plugin: {
      enabled: true,
      mode: "targets",
      targets: [{ channel: "whatsapp", to: "+15551234567" }],
    },
  },
}

​

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

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

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

​

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

​

ارتباطات ACP المكوّنة

{
  bindings: [
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "direct", id: "+15555550123" },
      },
    },
    {
      type: "acp",
      agentId: "codex",
      match: {
        channel: "whatsapp",
        accountId: "work",
        peer: { kind: "group", id: "120363424282127706@g.us" },
      },
    },
  ],
}

• تطابق المحادثات المباشرة أرقام E.164 مثل +15555550123.
• تطابق المجموعات JIDs مجموعات WhatsApp مثل 120363424282127706@g.us.
• تعمل قوائم سماح المجموعات، وسياسة المرسل، وبوابة الإشارة أو التفعيل قبل أن يضمن OpenClaw وجود جلسة ACP المكوّنة.
• يملك ارتباط ACP مكوّن ومطابق المسار. لا تفرّع مجموعات بث WhatsApp تلك الجولة إلى جلسات 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,
        },
      },
    },
  },
}

​

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

​

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

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

​

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

{
  channels: {
    whatsapp: {
      reactionLevel: "ack",
    },
  },
}

​

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

{
  channels: {
    whatsapp: {
      ackReaction: {
        emoji: "👀",
        direct: true,
        group: "mentions", // always | mentions | never
      },
    },
  },
}

• يُرسل فورًا بعد قبول الوارد (قبل الرد)
• إذا كان ackReaction موجودًا من دون emoji، يستخدم WhatsApp رمز الهوية التعبيري للوكيل الموجَّه إليه، مع الرجوع إلى ”👀”؛ احذف ackReaction أو عيّن emoji: "" لعدم إرسال أي تفاعل إقرار
• تُسجَّل الإخفاقات لكنها لا تمنع تسليم الرد العادي
• يتفاعل وضع المجموعة mentions في الأدوار التي تُشغَّل بالإشارة؛ ويعمل تفعيل المجموعة always كتجاوز لهذا الفحص
• يستخدم WhatsApp ‏channels.whatsapp.ackReaction (لا يُستخدم messages.ackReaction القديم هنا)

​

تفاعلات حالة دورة الحياة

{
  messages: {
    statusReactions: {
      enabled: true,
      emojis: {
        deploy: "🛫",
        build: "🏗️",
        concierge: "💁",
      },
    },
  },
}

• لا يزال channels.whatsapp.ackReaction يتحكم في أهلية تفاعلات الحالة للرسائل المباشرة والمجموعات.
• يستخدم تفاعل حالة قائمة الانتظار رمز الإقرار الفعّال نفسه المستخدم في تفاعلات الإقرار العادية.
• لدى WhatsApp خانة تفاعل واحدة للبوت لكل رسالة، لذلك تستبدل تحديثات دورة الحياة التفاعل الحالي في مكانه.
• يمسح messages.removeAckAfterReply: true تفاعل الحالة النهائي بعد مدة الاحتفاظ المُهيأة للانتهاء/الخطأ.
• تشمل فئات رموز الأدوات التعبيرية tool وcoding وweb وdeploy وbuild وconcierge.

​

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

​

الأدوات والإجراءات وكتابات الإعدادات

• يتضمن دعم أداة الوكيل إجراء تفاعل 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 channels status --probe
openclaw doctor
openclaw logs --follow
openclaw gateway status

cp -a ~/.openclaw/credentials/whatsapp/<accountId> \
  ~/.openclaw/credentials/whatsapp/<accountId>.bak
openclaw channels logout --channel whatsapp --account <accountId>
openclaw channels login --channel whatsapp --account <accountId>

​

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

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

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

• 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.
            "120363406415684625@g.us": {
              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

• الوصول: 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

​

ذات صلة

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