بوت QQ

يتصل QQ Bot بـ OpenClaw عبر واجهة QQ Bot API الرسمية (بوابة WebSocket). تُعد المحادثات الخاصة من نوع C2C وإشارات @ في المجموعات نوعَي المحادثة الأساسيين، مع دعم الوسائط الغنية (الصور والصوت والفيديو والملفات). تُدعم رسائل قنوات المجتمعات للنصوص والصور ذات عناوين URL البعيدة فقط؛ ولا تتوفر المقاطع الصوتية أو مقاطع الفيديو أو عمليات رفع الملفات أو الصور المحلية/المشفّرة بـ Base64 في قنوات المجتمعات. لا تُدعم التفاعلات أو سلاسل المحادثات في أي مكان.

الحالة: Plugin رسمي قابل للتنزيل.

التثبيت

openclaw plugins install @openclaw/qqbot

الإعداد

1. انتقل إلى QQ Open Platform وامسح رمز QR ضوئيًا باستخدام تطبيق QQ على هاتفك للتسجيل / تسجيل الدخول.
2. انقر على Create Bot لإنشاء روبوت QQ جديد.
3. ابحث عن AppID وAppSecret في صفحة إعدادات الروبوت وانسخهما.

4. أضف القناة:

openclaw channels add --channel qqbot --token "AppID:AppSecret"

5. أعد تشغيل Gateway.

الإعداد التفاعلي:

openclaw channels add

يوفر المعالج أيضًا الربط بواسطة رمز QR بديلًا عن إدخال AppID/AppSecret يدويًا: امسح الرمز ضوئيًا باستخدام تطبيق الهاتف المرتبط بـ QQ Bot المستهدف لإكمال الربط. يحتفظ OpenClaw ببيانات الاعتماد المُعادة ضمن نطاق إعدادات الحساب.

التهيئة

الحد الأدنى من الإعدادات:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: "YOUR_APP_SECRET",    },  },}

متغيرات البيئة للحساب الافتراضي (الحساب الأعلى مستوى فقط):

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

AppSecret المستند إلى ملف:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecretFile: "/path/to/qqbot-secret.txt",    },  },}

AppSecret باستخدام SecretRef من البيئة:

{  channels: {    qqbot: {      enabled: true,      appId: "YOUR_APP_ID",      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },    },  },}

ملاحظات:

• يعيّن openclaw channels add --channel qqbot --token-file ... قيمة AppSecret فقط؛ ويجب أن تكون appId مضبوطة مسبقًا في الإعدادات أو في QQBOT_APP_ID.
• تقبل clientSecret سلسلة نصية صريحة، أو مسار ملف (clientSecretFile)، أو كائن SecretRef منظمًا.
• تُرفض سلاسل العلامات القديمة secretref:... / secretref-env:... في clientSecret؛ استخدم بدلًا منها كائن SecretRef منظمًا.

سياسة الوصول

• تتحكم allowFrom / groupAllowFrom في مَن يمكنه الدردشة مع الروبوت ضمن سياقات C2C / المجموعات. وتتحكم dmPolicy / groupPolicy ‏(open | allowlist | disabled) في وضع الإنفاذ. تصبح القيمة الافتراضية لـ dmPolicy هي allowlist بمجرد احتواء allowFrom على مُدخل محدد (ليس حرف بدل)، وإلا فتكون open. وتصبح القيمة الافتراضية لـ groupPolicy هي allowlist بمجرد احتواء groupAllowFrom أو allowFrom على مُدخل محدد، وإلا فتكون open.
• تتطلب أوامر الشرطة المائلة ذات «المصادقة: قائمة السماح» مُدخلًا صريحًا ليس حرف بدل في allowFrom (أو groupAllowFrom عند الاستدعاء من مجموعة)، بصرف النظر عن dmPolicy / groupPolicy — راجع أوامر الشرطة المائلة.

إعداد حسابات متعددة

شغّل عدة روبوتات QQ ضمن مثيل OpenClaw واحد:

{  channels: {    qqbot: {      enabled: true,      appId: "111111111",      clientSecret: "secret-of-bot-1",      accounts: {        bot2: {          enabled: true,          appId: "222222222",          clientSecret: "secret-of-bot-2",        },      },    },  },}

يمتلك كل حساب اتصال WebSocket وعميل API وذاكرة تخزين مؤقت للرموز المميزة معزولة، ومفهرسة بواسطة appId. تُوسم أسطر السجل بمعرّف الحساب المالك بحيث تبقى بيانات التشخيص قابلة للفصل عند تشغيل عدة روبوتات ضمن Gateway واحد.

أضف روبوتًا ثانيًا عبر CLI:

openclaw channels add --channel qqbot --account bot2 --token "222222222:secret-of-bot-2"

محادثات المجموعات

يستخدم دعم المجموعات معرّفات OpenID لمجموعات QQ، وليس أسماء العرض. أضف الروبوت إلى مجموعة، ثم أشر إليه أو اضبط المجموعة لتعمل دون إشارة.

{  channels: {    qqbot: {      groupPolicy: "allowlist",      groupAllowFrom: ["member_openid"],      groups: {        "*": {          requireMention: true,          commandLevel: "all",          historyLimit: 50,          tools: { deny: ["exec", "read", "write"] },        },        GROUP_OPENID: {          name: "Release room",          requireMention: false,          ignoreOtherMentions: true,          commandLevel: "safety",          historyLimit: 20,          prompt: "Keep replies short and operational.",        },      },    },  },}

تضبط groups["*"] القيم الافتراضية لكل مجموعة؛ ويتجاوز مُدخل groups.GROUP_OPENID المحدد تلك القيم الافتراضية لمجموعة واحدة. إعدادات المجموعات:

تقبل commandLevel ما يلي:

أُلغيت مُدخلات toolPolicy القديمة في QQBot. شغّل openclaw doctor --fix لترحيلها إلى tools.

أوضاع التنشيط هي mention وalways. تقابل requireMention: true الوضع mention، وتقابل requireMention: false الوضع always. ويتغلب تجاوز التنشيط على مستوى الجلسة، عند وجوده، على الإعدادات.

يُخصَّص طابور الرسائل الواردة لكل نظير. تحصل نظائر المجموعات على حد طابور أكبر (50 مقابل 20 للنظائر المباشرة)، وتُزال الرسائل التي كتبها الروبوت قبل رسائل البشر عند امتلائه، وتُدمج دفعات رسائل المجموعة العادية في دور واحد مع تحديد أصحابها. تعمل أوامر الشرطة المائلة واحدًا تلو الآخر، بمعزل عن أي دفعة دمج.

الصوت (STT / TTS)

يدعم STT وTTS تهيئة من مستويين مع رجوع احتياطي حسب الأولوية:

{  channels: {    qqbot: {      stt: {        provider: "your-provider",        model: "your-stt-model",      },      tts: {        provider: "your-provider",        model: "your-tts-model",        voice: "your-voice",      },      accounts: {        "qq-main": {          tts: {            providers: {              openai: { voice: "shimmer" },            },          },        },      },    },  },}

اضبط enabled: false على أي منهما لتعطيله. تستخدم تجاوزات TTS على مستوى الحساب البنية نفسها التي تستخدمها messages.tts، وتُدمج بعمق فوق إعدادات TTS الخاصة بالقناة/العامة.

تنتهي مهلة طلبات STT بعد 60 ثانية افتراضيًا. يستخدم STT الخاص بالـ Plugin تجاوز models.providers.<id>.timeoutSeconds للمزود المحدد. ويستخدم STT الصوتي لإطار العمل tools.media.audio.models[0].timeoutSeconds، ثم tools.media.audio.timeoutSeconds، ثم تجاوز المزود المحدد.

تُعرض مرفقات QQ الصوتية الواردة للوكلاء كبيانات وصفية لوسائط صوتية، مع إبقاء ملفات الصوت الخام خارج MediaPaths العامة. تؤدي [[audio_as_voice]] في رد نصي عادي إلى توليد TTS وإرسال رسالة صوتية أصلية في QQ عند تهيئة TTS.

يمكن أيضًا ضبط سلوك رفع/تحويل ترميز الصوت الصادر باستخدام channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

تنسيقات الوجهة

أوامر الشرطة المائلة

الأوامر المضمنة التي يجري اعتراضها قبل طابور الذكاء الاصطناعي:

ألحق ? بأي أمر للحصول على مساعدة الاستخدام (مثلًا /bot-upgrade ?).

تتطلب أوامر «المصادقة: قائمة السماح» أيضًا وجود openid الخاص بالمُرسِل ضمن قائمة allowFrom صريحة لا تحتوي على حرف بدل (تكون لـ groupAllowFrom الأولوية عند إصدار الأوامر من مجموعة، مع الرجوع إلى allowFrom). يسمح حرف البدل allowFrom: ["*"] بالدردشة، لكنه لا يسمح بهذه الأوامر. يؤدي تشغيل أحدها خارج محادثة خاصة، أو دون تخويل، إلى إرجاع تلميح بدلًا من إسقاط الرسالة بصمت.

تقتصر الأوامر /bot-me و/bot-version و/bot-upgrade على المحادثات الخاصة، لكنها لا تتطلب قائمة السماح — إذ يمكن لأي مُرسِل C2C تشغيلها.

عندما تستخدم موافقات التنفيذ في QQ Bot آلية الرجوع الافتراضية إلى المحادثة نفسها، تتبع نقرات أزرار الموافقة الأصلية قائمة السماح الصريحة نفسها للأوامر غير المحتوية على أحرف بدل. لمنح صلاحية الموافقة فقط من دون صلاحية أوسع لتنفيذ الأوامر، اضبط channels.qqbot.execApprovals.approvers. تكون موافقات التنفيذ الأصلية مفعّلة افتراضيًا.

الوسائط والتخزين

• تشترك وسائط الوارد والصادر وجسر Gateway في جذر حمولة واحد ضمن ~/.openclaw/media/qqbot (مع مراعاة OPENCLAW_HOME عند تعيينه)، بحيث تظل عمليات الرفع والتنزيل وذاكرات التخزين المؤقت لتحويل الترميز ضمن دليل واحد محمي.
• يمر تسليم الوسائط الغنية إلى أهداف C2C والمجموعات عبر مسار sendMedia واحد. تستخدم الملفات المحلية والمخازن المؤقتة في الذاكرة التي يبلغ حجمها 5 MiB أو أكثر نقاط نهاية الرفع المجزأ في QQ؛ بينما تستخدم الحمولات الأصغر والمصادر ذات عناوين URL البعيدة أو Base64 واجهة برمجة تطبيقات الرفع أحادي العملية.
• إذا قطعت ترقية فورية عمل Gateway قبل أن ينتهي من كتابة openclaw.json، يستعيد Plugin آخر قيمتَي appId / clientSecret معروفتين لذلك الحساب من لقطة داخلية عند بدء التشغيل التالي (من دون الكتابة فوق أي تغيير مقصود في الإعدادات)، ولذلك لا يلزم إعادة مسح رمز QR.

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

• لا يبدأ Gateway / لا توجد رسائل واردة: تحقق من صحة appId و clientSecret ومن تمكين البوت على QQ Open Platform. يظهر فقدان بيانات اعتماد بالرسالة "QQBot غير مُعدّ (appId أو clientSecret مفقود)".
• لا يزال الإعداد باستخدام --token-file يظهر على أنه غير مُعدّ: لا يعيّن --token-file سوى AppSecret. ويجب مع ذلك تعيين appId في الإعدادات أو QQBOT_APP_ID.
• تتعارض ردود المجموعة المتدفقة: تستبعد قائمة انتظار الوارد الرسائل التي أنشأها البوت قبل الرسائل البشرية عندما تمتلئ قائمة انتظار أحد الأقران، وتدمج دفعات رسائل المجموعة العادية (غير الأوامر) في دور واحد منسوب إلى مرسليه، بحيث لا يؤدي تدفق محادثات البوت إلى حرمان الرسائل البشرية من المعالجة.
• الرسائل الاستباقية لا تصل: قد يحظر QQ الرسائل التي يبدأها البوت إذا لم يتفاعل المستخدم مؤخرًا.
• لا يُنسخ الصوت نصيًا: تأكد من إعداد STT وإمكانية الوصول إلى المزوّد.

ذو صلة

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