บอต QQ

QQ Bot เชื่อมต่อกับ OpenClaw ผ่าน QQ Bot API อย่างเป็นทางการ (WebSocket gateway) แชตส่วนตัวแบบ C2C และการกล่าวถึงด้วย @ ในกลุ่มเป็นประเภทแชตหลัก พร้อมรองรับสื่อ หลากหลายรูปแบบ (รูปภาพ เสียง วิดีโอ ไฟล์) ข้อความในช่องกิลด์รองรับเฉพาะ ข้อความและรูปภาพจาก URL ระยะไกลเท่านั้น ส่วนเสียง วิดีโอ การอัปโหลดไฟล์ และรูปภาพ ในเครื่อง/Base64 ไม่พร้อมใช้งานในช่องกิลด์ ไม่รองรับรีแอ็กชันและเธรด ในทุกกรณี

สถานะ: Plugin อย่างเป็นทางการที่ดาวน์โหลดได้

ติดตั้ง

openclaw plugins install @openclaw/qqbot

ตั้งค่าเริ่มต้น

1. ไปที่ QQ Open Platform แล้วสแกนคิวอาร์โค้ดด้วย QQ บนโทรศัพท์เพื่อลงทะเบียน / เข้าสู่ระบบ
2. คลิก Create Bot เพื่อสร้างบอต QQ ใหม่
3. ค้นหา AppID และ AppSecret ในหน้าการตั้งค่าของบอต แล้วคัดลอกค่าเหล่านั้น

4. เพิ่มช่องทาง:

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

5. รีสตาร์ต Gateway

การตั้งค่าแบบโต้ตอบ:

openclaw channels add

วิซาร์ดยังมีการผูกด้วยคิวอาร์โค้ดเป็นทางเลือกแทนการพิมพ์ 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 แบบ Env 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 แบบมีโครงสร้างแทน

การสตรีม

{  channels: {    qqbot: {      streaming: {        mode: "partial", // การสตรีมแบบบล็อก: "partial" (ค่าเริ่มต้น) หรือ "off"        nativeTransport: true, // ใช้ C2C stream_messages API อย่างเป็นทางการของ QQ สำหรับ DM      },    },  },}

• streaming.mode: "off" ปิดใช้งานการสตรีมแบบบล็อกสำหรับบัญชี
• streaming.nativeTransport: true สตรีมการตอบกลับ C2C (DM) ผ่าน stream_messages API อย่างเป็นทางการของ QQ โดยไม่ส่งผลต่อเป้าหมายแบบกลุ่ม/ช่อง
• ค่าสเกลาร์ streaming: true|false แบบเดิมและคีย์ streaming.c2cStreamApi จะย้ายไปยังโครงสร้างนี้ผ่าน openclaw doctor --fix
• /bot-streaming on|off สลับการกำหนดค่าเดียวกันจาก DM

นโยบายการเข้าถึง

• allowFrom / groupAllowFrom กำหนดว่าใครสามารถแชตกับบอตในบริบท C2C / กลุ่มได้ ส่วน dmPolicy / groupPolicy (open | allowlist | disabled) ควบคุมโหมดการบังคับใช้ dmPolicy มีค่าเริ่มต้นเป็น allowlist เมื่อ allowFrom มีรายการที่ระบุชัดเจน (ไม่ใช่ไวลด์การ์ด) มิฉะนั้นจะเป็น open groupPolicy มีค่าเริ่มต้นเป็น allowlist เมื่อ groupAllowFrom หรือ allowFrom มีรายการที่ระบุชัดเจน มิฉะนั้นจะเป็น open
• คำสั่งแบบสแลช "Auth: allowlist" ต้องมีรายการที่ไม่ใช่ไวลด์การ์ดอย่างชัดเจนใน 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 ทั่วไป เมื่อกำหนดค่า TTS แล้ว [[audio_as_voice]] ในการตอบกลับแบบข้อความธรรมดาจะสังเคราะห์ 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 อัปโหลดแบบครั้งเดียว
• หากการอัปเกรดขณะทำงานขัดจังหวะ Gateway ก่อนที่จะเขียน openclaw.json เสร็จ Plugin จะกู้คืน appId / clientSecret ที่ทราบล่าสุดสำหรับบัญชีนั้นจากสแนปช็อตภายในเมื่อเริ่มทำงานครั้งถัดไป (โดยจะไม่ เขียนทับการเปลี่ยนแปลงการกำหนดค่าที่ตั้งใจไว้) จึงไม่จำเป็นต้องสแกนคิวอาร์โค้ด อีกครั้ง

การแก้ไขปัญหา

• Gateway ไม่เริ่มทำงาน / ไม่มีข้อความขาเข้า: ตรวจสอบว่า appId และ clientSecret ถูกต้อง และบอตเปิดใช้งานอยู่บน QQ Open Platform หากข้อมูลประจำตัวขาดหายไป ระบบจะแสดงข้อความ "ไม่ได้กำหนดค่า QQBot (ไม่มี appId หรือ clientSecret)"
• ตั้งค่าด้วย --token-file แล้วยังคงแสดงว่ายังไม่ได้กำหนดค่า: --token-file ตั้งค่า เฉพาะ AppSecret เท่านั้น ยังต้องตั้งค่า appId ในการกำหนดค่าหรือ QQBOT_APP_ID
• การตอบกลับกลุ่มแบบเป็นชุดชนกัน: เมื่อคิวของเพียร์เต็ม คิวขาเข้าจะนำข้อความ ที่บอตสร้างออกก่อนข้อความของมนุษย์ และรวมชุดข้อความกลุ่มปกติ (ที่ไม่ใช่คำสั่ง) เป็นหนึ่งรอบการโต้ตอบพร้อมระบุแหล่งที่มา ดังนั้นข้อความจากบอตจำนวนมาก ไม่ควรทำให้ข้อความของมนุษย์ไม่ได้รับการประมวลผล
• ข้อความเชิงรุกไม่มาถึง: QQ อาจบล็อกข้อความที่บอตเป็นฝ่ายเริ่ม หากผู้ใช้ไม่ได้โต้ตอบในช่วงที่ผ่านมา
• เสียงไม่ได้รับการถอดเสียง: ตรวจสอบว่าได้กำหนดค่า STT และสามารถ เข้าถึงผู้ให้บริการได้

ที่เกี่ยวข้อง

• การจับคู่
• กลุ่ม
• การแก้ไขปัญหาช่องทาง