Regional platforms

บอต QQ

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

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

ติดตั้ง

bash

openclaw plugins install @openclaw/qqbot

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

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

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

bash

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

รีสตาร์ต Gateway

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

bash

openclaw channels add

ตัวช่วยตั้งค่ายังมีการผูกบัญชีด้วยคิวอาร์โค้ดเป็นทางเลือกแทนการพิมพ์ AppID/AppSecret ด้วยตนเอง โดยสแกนโค้ดด้วยแอปบนโทรศัพท์ที่เชื่อมโยงกับ QQ Bot เป้าหมายเพื่อดำเนินการ ผูกบัญชีให้เสร็จสมบูรณ์ OpenClaw จะเก็บข้อมูลประจำตัวที่ได้รับไว้ภายใต้ขอบเขต การกำหนดค่าของบัญชี

กำหนดค่า

การกำหนดค่าขั้นต่ำ:

json5

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

ตัวแปรสภาพแวดล้อมสำหรับบัญชีเริ่มต้น (เฉพาะบัญชีระดับบนสุด):

QQBOT_APP_ID
QQBOT_CLIENT_SECRET

AppSecret ที่อ้างอิงจากไฟล์:

json5

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

AppSecret แบบ SecretRef จากตัวแปรสภาพแวดล้อม:

json5

{  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
คำสั่งแบบทับที่มี "การยืนยันตัวตน: allowlist" ต้องมีรายการที่ระบุชัดเจนและไม่ใช่ไวลด์การ์ดใน allowFrom (หรือ groupAllowFrom สำหรับการเรียกใช้จากกลุ่ม) โดยไม่ขึ้นกับ dmPolicy / groupPolicy — ดู คำสั่งแบบทับ

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

เรียกใช้ QQ bot หลายตัวภายใต้อินสแตนซ์ OpenClaw เดียว:

json5

{  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:

bash

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

แชตกลุ่ม

การรองรับกลุ่มใช้ OpenID ของกลุ่ม QQ ไม่ใช่ชื่อที่แสดง เพิ่มบอตลงใน กลุ่ม จากนั้นกล่าวถึงบอตหรือกำหนดค่าให้กลุ่มทำงานโดยไม่ต้องกล่าวถึง

json5

{  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`	`true`	กำหนดให้ต้องกล่าวถึงด้วย `@` ก่อนที่บอตจะตอบกลับ
`commandLevel`	`all`	กำหนดว่าคำสั่งแบบทับในตัวใดเรียกใช้ในกลุ่มได้ (ดูด้านล่าง)
`ignoreOtherMentions`	`false`	ละทิ้งข้อความที่กล่าวถึงบุคคลอื่นแต่ไม่ได้กล่าวถึงบอต
`historyLimit`	`50`	จำนวนข้อความล่าสุดที่ไม่ได้กล่าวถึงซึ่งเก็บไว้เป็นบริบทสำหรับรอบถัดไปที่กล่าวถึง `0` ปิดใช้งานประวัติ
`tools`	—	อนุญาต/ปฏิเสธเครื่องมือสำหรับทั้งกลุ่ม
`toolsBySender`	—	การแทนที่เครื่องมือตามผู้ส่งแต่ละราย ดู กลุ่ม
`name`	คำนำหน้า openid	ป้ายชื่อที่อ่านเข้าใจง่ายซึ่งใช้ในบันทึกและบริบทกลุ่ม
`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 หากมีการแทนที่โหมด การเปิดใช้งานระดับเซสชัน ค่านั้นจะมีลำดับความสำคัญเหนือการกำหนดค่า

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

เสียง (STT / TTS)

STT และ TTS รองรับการกำหนดค่าสองระดับพร้อมการถอยกลับตามลำดับความสำคัญ:

การตั้งค่า	เฉพาะ Plugin	การถอยกลับของเฟรมเวิร์ก
STT	`channels.qqbot.stt`	`tools.media.audio.models[0]`
TTS	`channels.qqbot.tts`, `channels.qqbot.accounts.<id>.tts`	`messages.tts`

json5

{  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

รูปแบบปลายทาง

รูปแบบ	คำอธิบาย
`qqbot:c2c:OPENID`	แชตส่วนตัว (C2C)
`qqbot:group:GROUP_OPENID`	แชตกลุ่ม
`qqbot:channel:CHANNEL_ID`	ช่องกิลด์

คำสั่งแบบทับ

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

คำสั่ง	การยืนยันตัวตน	ขอบเขต	คำอธิบาย
`/bot-ping`	—	ทุกบริบท	ทดสอบเวลาแฝง
`/bot-help`	—	ทุกบริบท	แสดงรายการคำสั่งทั้งหมด
`/bot-me`	—	ส่วนตัวเท่านั้น	แสดงรหัสผู้ใช้ QQ (openid) ของผู้ส่งสำหรับตั้งค่า `allowFrom` / `groupAllowFrom`
`/bot-version`	—	ส่วนตัวเท่านั้น	แสดงเวอร์ชันเฟรมเวิร์ก OpenClaw และเวอร์ชัน Plugin
`/bot-upgrade`	—	ส่วนตัวเท่านั้น	แสดงลิงก์คู่มืออัปเกรด QQBot
`/bot-approve`	allowlist	ส่วนตัวเท่านั้น	จัดการการกำหนดค่าการอนุมัติการเรียกใช้คำสั่ง (เปิด / ปิด / เสมอ / รีเซ็ต / สถานะ)
`/bot-logs`	allowlist	ส่วนตัวเท่านั้น	ส่งออกบันทึกล่าสุดของ gateway เป็นไฟล์
`/bot-clear-storage`	allowlist	ส่วนตัวเท่านั้น	ลบไฟล์ดาวน์โหลดที่แคชไว้ภายใต้ไดเรกทอรีสื่อ QQBot
`/bot-streaming`	allowlist	ส่วนตัวเท่านั้น	สลับเปิด/ปิดการตอบกลับแบบสตรีมใน C2C
`/bot-group-allways`	allowlist	ส่วนตัวเท่านั้น	สลับโหมดการเปิดใช้งานกลุ่มเริ่มต้น (ต้องกล่าวถึงเทียบกับเปิดใช้งานตลอดเวลา)

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

คำสั่งที่มี "การยืนยันตัวตน: allowlist" ยังกำหนดให้ 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 แล้วและสามารถ เข้าถึงผู้ให้บริการได้

เนื้อหาที่เกี่ยวข้อง

Was this useful?

บอต QQ

ติดตั้ง

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

กำหนดค่า

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

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

แชตกลุ่ม

เสียง (STT / TTS)

รูปแบบปลายทาง

คำสั่งแบบทับ

สื่อและพื้นที่จัดเก็บ

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

เนื้อหาที่เกี่ยวข้อง

On this page

Molty