บอต QQ

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

สถานะ: Plugin ที่ดาวน์โหลดได้ รองรับข้อความส่วนตัว แชตกลุ่ม ช่องกิลด์ และ สื่อ ไม่รองรับรีแอ็กชันและเธรด

ติดตั้ง

ติดตั้ง QQ Bot ก่อนตั้งค่า:

openclaw plugins install @openclaw/qqbot

ตั้งค่า

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

AppSecret ไม่ได้จัดเก็บเป็นข้อความล้วน หากคุณออกจากหน้าโดยไม่ได้บันทึกไว้ คุณจะต้องสร้างรายการใหม่อีกครั้ง

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

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

5. รีสตาร์ต Gateway

เส้นทางตั้งค่าแบบโต้ตอบ:

openclaw channels addopenclaw configure --section channels

กำหนดค่า

คอนฟิกขั้นต่ำ:

{  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" },    },  },}

หมายเหตุ:

• การสำรองไปใช้ env ใช้กับบัญชี QQ Bot เริ่มต้นเท่านั้น
• openclaw channels add --channel qqbot --token-file ... ระบุเฉพาะ AppSecret เท่านั้น; ต้องตั้งค่า AppID ไว้แล้วในคอนฟิกหรือ QQBOT_APP_ID
• clientSecret ยังรับอินพุต SecretRef ได้ ไม่ใช่เฉพาะสตริงข้อความล้วน
• สตริงมาร์กเกอร์ secretref:/... แบบเก่าไม่ใช่ค่า clientSecret ที่ถูกต้อง; ใช้อ็อบเจ็กต์ SecretRef แบบมีโครงสร้างเหมือนตัวอย่างด้านบน

การตั้งค่าหลายบัญชี

เรียกใช้ 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 ของตนเองและดูแลแคชโทเค็นอิสระ (แยกกันด้วย appId)

เพิ่มบอตตัวที่สองผ่าน CLI:

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

แชตกลุ่ม

การรองรับแชตกลุ่มของ QQ Bot ใช้ 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 ที่ระบุชัดเจนจะแทนที่ค่าเริ่มต้นเหล่านั้นสำหรับกลุ่มหนึ่ง การตั้งค่ากลุ่มประกอบด้วย:

• requireMention: ต้องมี @mention ก่อนที่บอตจะตอบกลับ ค่าเริ่มต้น: true
• commandLevel: ควบคุมว่าคำสั่งสแลชในตัวใดบ้างที่เรียกใช้ในกลุ่มได้ ค่าเริ่มต้น: all ซึ่งคงพฤติกรรมกลุ่ม QQBot ที่มีอยู่เดิมเมื่อ ไม่ได้ระบุการตั้งค่านี้
• ignoreOtherMentions: ทิ้งข้อความที่กล่าวถึงคนอื่นแต่ไม่ได้กล่าวถึงบอต
• historyLimit: เก็บข้อความกลุ่มล่าสุดที่ไม่ได้กล่าวถึงไว้เป็นบริบทสำหรับเทิร์นถัดไปที่มีการกล่าวถึง ตั้งค่า 0 เพื่อปิดใช้
• tools: อนุญาต/ปฏิเสธเครื่องมือสำหรับทั้งกลุ่ม
• toolsBySender: การแทนที่เครื่องมือกลุ่มรายผู้ส่ง; ดู กลุ่ม
• name: ป้ายชื่อที่เป็นมิตรซึ่งใช้ในล็อกและบริบทกลุ่ม
• prompt: พรอมป์พฤติกรรมรายกลุ่มที่ต่อท้ายบริบทของเอเจนต์

commandLevel รับค่า:

• all: คงคำสั่งในตัวที่รู้จักให้ใช้งานได้เหมือนเดิม บางคำสั่งอาจ ยังซ่อนจากเมนู แต่ผู้ใช้ที่ได้รับอนุญาตยังคงเรียกใช้ในกลุ่มได้
• safety: อนุญาตคำสั่งการทำงานร่วมกันทั่วไป เช่น /help, /btw และ /stop; ขอให้ผู้ใช้เรียกใช้คำสั่งอ่อนไหว เช่น /config, /tools และ /bash ในแชตส่วนตัว
• strict: อนุญาตเฉพาะการควบคุมเซสชันกลุ่มที่จำเป็นสำหรับการทำงานกลุ่มแบบเข้มงวด /stop ยังคงเป็นคำสั่งเร่งด่วนเพื่อให้ผู้ส่งที่ได้รับอนุญาตสามารถขัดจังหวะ การรันที่กำลังทำงานอยู่ได้

รายการ toolPolicy ของ QQBot แบบเก่าถูกเลิกใช้แล้ว เรียกใช้ openclaw doctor --fix เพื่อย้ายไปเป็น tools

โหมดการเปิดใช้งานคือ mention และ always requireMention: true แมปเป็น mention; requireMention: false แมปเป็น always การแทนที่การเปิดใช้งาน ระดับเซสชัน หากมี จะมีผลเหนือคอนฟิก

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

เสียง (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 และ deep-merge ทับคอนฟิก TTS ระดับช่องทาง/ส่วนกลาง

ไฟล์แนบเสียง QQ ขาเข้าจะแสดงต่อเอเจนต์เป็นเมทาดาทาสื่อเสียง ขณะเดียวกัน เก็บไฟล์เสียงดิบออกจาก MediaPaths ทั่วไป ข้อความตอบกลับแบบข้อความล้วน [[audio_as_voice]] จะสังเคราะห์ TTS และส่งข้อความเสียง QQ แบบเนทีฟเมื่อ กำหนดค่า TTS แล้ว

พฤติกรรมอัปโหลด/แปลงรหัสเสียงขาออกยังปรับแต่งได้ด้วย channels.qqbot.audioFormatPolicy:

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

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

แต่ละบอตมีชุด OpenID ผู้ใช้ของตนเอง OpenID ที่ได้รับโดยบอต A ไม่สามารถ ใช้ส่งข้อความผ่านบอต B ได้

คำสั่งสแลช

คำสั่งในตัวที่ดักก่อนเข้าคิว AI:

ต่อท้าย ? กับคำสั่งใดก็ได้เพื่อดูวิธีใช้ (เช่น /bot-upgrade ?)

คำสั่งผู้ดูแล (/bot-me, /bot-upgrade, /bot-logs, /bot-clear-storage, /bot-streaming, /bot-approve) ใช้ได้เฉพาะข้อความส่วนตัวและต้องมี openid ของผู้ส่งในรายการ allowFrom แบบระบุชัดเจนที่ไม่ใช่ไวลด์การ์ด ไวลด์การ์ด allowFrom: ["*"] อนุญาตให้แชตได้แต่ไม่ให้สิทธิ์เข้าถึงคำสั่งผู้ดูแล ข้อความกลุ่มจะตรวจเทียบกับ groupAllowFrom ก่อน และสำรองไปใช้ allowFrom การเรียกใช้คำสั่งผู้ดูแลในกลุ่มจะส่งคำใบ้กลับแทนที่จะทิ้งอย่างเงียบ ๆ

เมื่อการอนุมัติ exec ของ QQ Bot ใช้การสำรองแชตเดียวกันแบบเริ่มต้น การคลิก ปุ่มอนุมัติแบบเนทีฟจะใช้ allowlist คำสั่งแบบระบุชัดเจนที่ไม่ใช่ไวลด์การ์ดเดียวกัน หากต้องการให้สิทธิ์เฉพาะการอนุมัติโดยไม่ให้สิทธิ์คำสั่งที่กว้างกว่า ให้กำหนดค่า channels.qqbot.execApprovals.approvers

สถาปัตยกรรมเอนจิน

QQ Bot มาพร้อมเอนจินแบบครบในตัวภายใน Plugin:

• แต่ละบัญชีเป็นเจ้าของสแตกทรัพยากรที่แยกอิสระ (การเชื่อมต่อ WebSocket, ไคลเอนต์ API, แคชโทเค็น, รากที่เก็บสื่อ) ที่ระบุด้วย appId บัญชีต่าง ๆ ไม่แชร์สถานะขาเข้า/ขาออกกัน
• ตัวบันทึกล็อกหลายบัญชีติดแท็กบรรทัดล็อกด้วยบัญชีเจ้าของ เพื่อให้การวินิจฉัยแยกกันได้เมื่อคุณเรียกใช้บอตหลายตัวภายใต้ gateway เดียว
• เส้นทางบริดจ์ขาเข้า ขาออก และ gateway ใช้รากเพย์โหลดสื่อเดียวกันภายใต้ ~/.openclaw/media ดังนั้นการอัปโหลด ดาวน์โหลด และแคชการแปลงรหัสจึงอยู่ภายใต้ไดเรกทอรีที่มีการป้องกันเดียว แทนที่จะเป็นโครงสร้างแยกตามซับซิสเต็ม
• การส่งสื่อสมบูรณ์ผ่านเส้นทาง sendMedia เดียวสำหรับเป้าหมาย C2C และกลุ่ม ไฟล์ในเครื่องและบัฟเฟอร์ที่เกินเกณฑ์ไฟล์ขนาดใหญ่ใช้เอนด์พอยต์อัปโหลดแบบแบ่งชิ้นของ QQ ส่วนเพย์โหลดที่เล็กกว่าใช้ API สื่อแบบครั้งเดียว
• ข้อมูลลับสามารถสำรองและกู้คืนเป็นส่วนหนึ่งของสแนปชอตข้อมูลลับมาตรฐานของ OpenClaw ได้; เอนจินจะแนบสแตกทรัพยากรของแต่ละบัญชีใหม่เมื่อกู้คืน โดยไม่ต้องจับคู่คิวอาร์โค้ดใหม่

การเริ่มใช้งานด้วยคิวอาร์โค้ด

อีกทางเลือกแทนการวาง AppID:AppSecret ด้วยตนเอง เอนจินรองรับโฟลว์การเริ่มใช้งานด้วยคิวอาร์โค้ดสำหรับเชื่อม QQ Bot กับ OpenClaw:

1. เรียกใช้เส้นทางตั้งค่า QQ Bot (เช่น openclaw channels add --channel qqbot) และเลือกโฟลว์คิวอาร์โค้ดเมื่อระบบถาม
2. สแกนคิวอาร์โค้ดที่สร้างขึ้นด้วยแอปโทรศัพท์ที่ผูกกับ QQ Bot เป้าหมาย
3. อนุมัติการจับคู่บนโทรศัพท์ OpenClaw จะคงข้อมูลลับที่ส่งกลับไว้ใน credentials/ ภายใต้ขอบเขตบัญชีที่ถูกต้อง

พรอมป์การอนุมัติที่บอตสร้างเอง (เช่น โฟลว์ "อนุญาตการดำเนินการนี้หรือไม่?" ที่เปิดเผยโดย QQ Bot API) จะแสดงเป็นพรอมป์ OpenClaw แบบเนทีฟ ซึ่งคุณสามารถยอมรับด้วย /bot-approve แทนการตอบผ่านไคลเอนต์ QQ ดิบ

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

• บอตตอบกลับว่า "gone to Mars": ยังไม่ได้กำหนดค่าข้อมูลประจำตัว หรือยังไม่ได้เริ่ม Gateway
• ไม่มีข้อความขาเข้า: ตรวจสอบว่า appId และ clientSecret ถูกต้อง และเปิดใช้งาน บอตบน QQ Open Platform แล้ว
• ตอบกลับตัวเองซ้ำ: OpenClaw บันทึกดัชนีอ้างอิงขาออกของ QQ เป็น รายการที่บอตเขียน และละเว้นเหตุการณ์ขาเข้าที่ msgIdx ปัจจุบันตรงกับ บัญชีบอตเดียวกันนั้น วิธีนี้ป้องกันลูปเสียงสะท้อนจากแพลตฟอร์ม ขณะยังอนุญาตให้ผู้ใช้ อ้างอิงหรือตอบกลับข้อความก่อนหน้าของบอตได้
• ตั้งค่าด้วย --token-file แล้วยังแสดงว่ายังไม่ได้กำหนดค่า: --token-file ตั้งค่าเฉพาะ AppSecret เท่านั้น คุณยังต้องมี appId ใน config หรือ QQBOT_APP_ID
• ข้อความเชิงรุกไม่มาถึง: QQ อาจสกัดข้อความที่บอตเริ่มส่งเอง หาก ผู้ใช้ไม่ได้โต้ตอบเมื่อเร็วๆ นี้
• เสียงไม่ถูกถอดความ: ตรวจสอบว่าได้กำหนดค่า STT แล้ว และผู้ให้บริการเข้าถึงได้

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

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