บอต 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 bot ใหม่
3. ค้นหา AppID และ AppSecret ในหน้าการตั้งค่าของบอต แล้วคัดลอกค่าเหล่านั้น

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

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

5. รีสตาร์ท Gateway

ความทนทานของข้อมูลขาเข้า

สำหรับเหตุการณ์รอบการสนทนาจาก QQ gateway นั้น OpenClaw จะบันทึกเหตุการณ์ดิบไว้อย่างถาวรก่อนเลื่อนลำดับการดำเนินการต่อของ gateway ที่บันทึกไว้ รอบที่รอดำเนินการหรือลองใหม่ได้จะยังคงอยู่หลังจากรีสตาร์ท Gateway ยังคงประมวลผลตามลำดับแยกในแต่ละการสนทนา และใช้รหัสเหตุการณ์ของผู้ให้บริการเพื่อระงับรายการคิวที่ซ้ำกัน ตราบใดที่ยังมีระเบียนการดำเนินการเสร็จสิ้นที่ใช้งานอยู่หรือเก็บรักษาไว้

หากการรับเข้าแบบคงทนล้มเหลว OpenClaw จะยุติซ็อกเก็ต 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 แบบ 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 bot หลายตัวภายใต้อินสแตนซ์ 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 ยอมรับ:

รายการ QQBot toolPolicy แบบเก่าเลิกใช้งานแล้ว เรียกใช้ 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

รูปแบบเป้าหมาย

คำสั่งแบบสแลช

คำสั่งในตัวที่ถูกสกัดก่อนเข้าสู่คิว 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 ล่าสุดที่ทราบของบัญชีนั้นจากสแนปช็อตภายในเมื่อเริ่มต้นครั้งถัดไป (โดยจะไม่ เขียนทับการเปลี่ยนแปลงการกำหนดค่าที่ตั้งใจไว้) จึงไม่ จำเป็นต้องสแกนรหัส QR ใหม่

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

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

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

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