QQ बॉट

QQ Bot आधिकारिक QQ Bot API (WebSocket gateway) के माध्यम से OpenClaw से जुड़ता है। C2C निजी चैट और समूह @-उल्लेख प्राथमिक चैट प्रकार हैं, जिनमें समृद्ध मीडिया (इमेज, वॉइस, वीडियो, फ़ाइलें) शामिल है। गिल्ड चैनल संदेश केवल टेक्स्ट और रिमोट-URL इमेज के लिए समर्थित हैं; वॉइस, वीडियो, फ़ाइल अपलोड और स्थानीय/Base64 इमेज गिल्ड चैनलों में उपलब्ध नहीं हैं। प्रतिक्रियाएँ और थ्रेड कहीं भी समर्थित नहीं हैं।

स्थिति: आधिकारिक डाउनलोड योग्य Plugin।

इंस्टॉल करें

openclaw plugins install @openclaw/qqbot

सेटअप

1. QQ Open Platform पर जाएँ और पंजीकरण / लॉग इन करने के लिए अपने फ़ोन के QQ से QR कोड स्कैन करें।
2. नया QQ bot बनाने के लिए Create Bot पर क्लिक करें।
3. bot के सेटिंग पेज पर AppID और AppSecret ढूँढें और उन्हें कॉपी करें।

4. चैनल जोड़ें:

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

5. Gateway को पुनः आरंभ करें।

इनबाउंड स्थायित्व

QQ gateway टर्न इवेंट के लिए, OpenClaw सहेजे गए gateway रिज़्यूम क्रम को आगे बढ़ाने से पहले रॉ इवेंट को स्थायी रूप से संग्रहीत करता है। लंबित या पुनः प्रयास योग्य टर्न Gateway के पुनः आरंभ होने के बाद भी बने रहते हैं, प्रत्येक वार्तालाप के अनुसार क्रमबद्ध रहते हैं, और सक्रिय या सुरक्षित रखा गया पूर्णता रिकॉर्ड मौजूद रहने तक डुप्लिकेट कतार प्रविष्टियों को रोकने के लिए प्रदाता इवेंट ID का उपयोग करते हैं।

यदि स्थायी प्रवेश विफल होता है, तो OpenClaw क्रम को आगे बढ़ाए बिना वर्तमान gateway सॉकेट समाप्त कर देता है। इसके बाद पुनः कनेक्ट/रिज़्यूम पथ अप्रतिबद्ध इवेंट को फिर से अनुरोध कर सकता है। कतार-से-एजेंट सीमा पर डिलीवरी अब भी कम-से-कम एक बार होती है, इसलिए हैंडऑफ़ के दौरान क्रैश होने पर कोई टर्न फिर से चल सकता है।

इंटरैक्टिव सेटअप:

openclaw channels add

विज़ार्ड AppID/AppSecret को मैन्युअल रूप से टाइप करने के विकल्प के रूप में QR-कोड बाइंडिंग भी प्रदान करता है: बाइंडिंग पूरी करने के लिए लक्षित 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",    },  },}

Env SecretRef AppSecret:

{  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 ऑब्जेक्ट का उपयोग करें।

स्ट्रीमिंग

{  channels: {    qqbot: {      streaming: {        mode: "partial", // ब्लॉक स्ट्रीमिंग: "partial" (डिफ़ॉल्ट) या "off"        nativeTransport: true, // DM के लिए QQ की आधिकारिक C2C stream_messages API का उपयोग करें      },    },  },}

• streaming.mode: "off" खाते के लिए ब्लॉक स्ट्रीमिंग अक्षम करता है।
• streaming.nativeTransport: true QQ की आधिकारिक stream_messages API के माध्यम से C2C (DM) उत्तर स्ट्रीम करता है; समूह/चैनल लक्ष्य अप्रभावित रहते हैं।
• लेगेसी streaming: true|false स्केलर और streaming.c2cStreamApi कुंजी openclaw doctor --fix के माध्यम से इस संरचना में माइग्रेट होते हैं।
• /bot-streaming on|off DM से इसी कॉन्फ़िगरेशन को टॉगल करता है।

पहुँच नीति

• allowFrom / groupAllowFrom नियंत्रित करते हैं कि C2C / समूह संदर्भों में bot से कौन चैट कर सकता है। dmPolicy / groupPolicy (open | allowlist | disabled) प्रवर्तन मोड नियंत्रित करते हैं। allowFrom में कोई ठोस (गैर-वाइल्डकार्ड) प्रविष्टि होने पर dmPolicy का डिफ़ॉल्ट allowlist होता है, अन्यथा open। groupAllowFrom या allowFrom में से किसी में ठोस प्रविष्टि होने पर groupPolicy का डिफ़ॉल्ट allowlist होता है, अन्यथा open।
• "Auth: allowlist" स्लैश कमांड के लिए allowFrom में (या समूह आमंत्रणों के लिए groupAllowFrom में) स्पष्ट गैर-वाइल्डकार्ड प्रविष्टि आवश्यक है, चाहे dmPolicy / groupPolicy कुछ भी हो — स्लैश कमांड देखें।

एकाधिक-खाता सेटअप

एक ही OpenClaw इंस्टेंस के अंतर्गत कई QQ bot चलाएँ:

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

प्रत्येक खाता appId द्वारा कुंजीबद्ध एक पृथक WebSocket कनेक्शन, API क्लाइंट और टोकन कैश का स्वामी होता है। लॉग पंक्तियों को स्वामी खाता ID से टैग किया जाता है, ताकि एक Gateway के अंतर्गत कई bot चलाने पर निदान अलग-अलग रखा जा सके।

CLI के माध्यम से दूसरा bot जोड़ें:

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

समूह चैट

समूह समर्थन डिस्प्ले नामों के बजाय QQ समूह OpenID का उपयोग करता है। bot को किसी समूह में जोड़ें, फिर उसका उल्लेख करें या समूह को बिना उल्लेख के चलने के लिए कॉन्फ़िगर करें।

{  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 यह स्वीकार करता है:

पुरानी QQBot toolPolicy प्रविष्टियाँ सेवानिवृत्त हो चुकी हैं। उन्हें tools में माइग्रेट करने के लिए openclaw doctor --fix चलाएँ।

सक्रियण मोड mention और always हैं। requireMention: true, mention से मैप होता है; requireMention: false, always से मैप होता है। सत्र-स्तरीय सक्रियण ओवरराइड मौजूद होने पर कॉन्फ़िगरेशन पर प्राथमिकता पाता है।

इनबाउंड कतार प्रति पीयर होती है। समूह पीयर को बड़ी कतार सीमा मिलती है (सीधे पीयर के लिए 20 की तुलना में 50), कतार भरने पर मानव-लिखित संदेशों से पहले bot-लिखित संदेशों को हटाया जाता है, और सामान्य समूह संदेशों के बर्स्ट को एक एट्रिब्यूटेड टर्न में मर्ज किया जाता है। स्लैश कमांड किसी भी मर्ज बैच से स्वतंत्र होकर एक-एक करके चलते हैं।

वॉइस (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 ओवरराइड tts जैसी ही संरचना का उपयोग करते हैं और चैनल/वैश्विक TTS कॉन्फ़िगरेशन पर डीप-मर्ज होते हैं।

STT अनुरोध डिफ़ॉल्ट रूप से 60 सेकंड के बाद टाइम आउट होते हैं। Plugin-विशिष्ट STT चयनित models.providers.<id>.timeoutSeconds ओवरराइड का उपयोग करता है। फ़्रेमवर्क ऑडियो STT चयनित ऑडियो-सक्षम tools.media.models[] प्रविष्टि के timeoutSeconds का, और फिर चयनित प्रदाता ओवरराइड का उपयोग करता है।

इनबाउंड QQ वॉइस अटैचमेंट एजेंटों के समक्ष ऑडियो मीडिया मेटाडेटा के रूप में प्रस्तुत किए जाते हैं, जबकि रॉ वॉइस फ़ाइलों को सामान्य MediaPaths से बाहर रखा जाता है। सादे-टेक्स्ट उत्तर में [[audio_as_voice]] TTS संश्लेषित करता है और TTS कॉन्फ़िगर होने पर मूल QQ वॉइस संदेश भेजता है।

आउटबाउंड ऑडियो अपलोड/ट्रांसकोड व्यवहार को channels.qqbot.audioFormatPolicy के साथ भी समायोजित किया जा सकता है:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

लक्ष्य प्रारूप

स्लैश कमांड

AI कतार से पहले इंटरसेप्ट किए जाने वाले अंतर्निहित कमांड:

उपयोग सहायता के लिए किसी भी कमांड के अंत में ? जोड़ें (उदाहरण के लिए /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 स्रोत एकल-प्रयास अपलोड API का उपयोग करते हैं।
• यदि कोई हॉट अपग्रेड openclaw.json का लेखन पूरा होने से पहले Gateway को बाधित करता है, तो Plugin अगली शुरुआत पर आंतरिक स्नैपशॉट से उस खाते के अंतिम ज्ञात appId / clientSecret को पुनर्स्थापित करता है (किसी जानबूझकर किए गए कॉन्फ़िगरेशन परिवर्तन को कभी अधिलेखित नहीं करता), इसलिए QR कोड को फिर से स्कैन करना आवश्यक नहीं है।

समस्या निवारण

• Gateway शुरू नहीं होता / कोई इनबाउंड संदेश नहीं: सत्यापित करें कि appId और clientSecret सही हैं और QQ Open Platform पर बॉट सक्षम है। क्रेडेंशियल अनुपलब्ध होने पर "QQBot कॉन्फ़िगर नहीं है (appId या clientSecret अनुपलब्ध है)" दिखाई देता है।
• --token-file के साथ सेटअप अब भी कॉन्फ़िगर नहीं दिखाता: --token-file केवल AppSecret सेट करता है। appId को अभी भी कॉन्फ़िगरेशन या QQBOT_APP_ID में सेट करना आवश्यक है।
• अचानक बड़ी संख्या में आए समूह उत्तर टकराते हैं: किसी पीयर की कतार भरने पर इनबाउंड कतार मनुष्यों द्वारा लिखे संदेशों से पहले बॉट द्वारा लिखे संदेशों को हटाती है और सामान्य (गैर-कमांड) समूह संदेशों के समूह को एक श्रेयांकित टर्न में मिला देती है, ताकि बॉट संदेशों की बाढ़ से मानव संदेशों को संसाधन मिलना बंद न हो।
• सक्रिय रूप से भेजे गए संदेश नहीं पहुँच रहे: यदि उपयोगकर्ता ने हाल में इंटरैक्ट नहीं किया है, तो QQ बॉट द्वारा आरंभ किए गए संदेशों को अवरुद्ध कर सकता है।
• आवाज़ का लिप्यंतरण नहीं हुआ: सुनिश्चित करें कि STT कॉन्फ़िगर किया गया है और प्रदाता तक पहुँचा जा सकता है।

संबंधित

• पेयरिंग
• समूह
• चैनल समस्या निवारण