บอต QQ

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

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

# ติดตั้ง

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

openclaw plugins install @openclaw/qqbot

# ตั้งค่า

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

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

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

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

5. รีสตาร์ต Gateway

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

openclaw channels add
openclaw 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 ไว้แล้วใน config หรือ QQBOT_APP_ID
• clientSecret ยังรับอินพุต SecretRef ได้ ไม่ใช่แค่สตริงข้อความธรรมดา
• สตริงเครื่องหมาย secretref:/... แบบเดิมไม่ใช่ค่า clientSecret ที่ใช้ได้; ให้ใช้ออบเจ็กต์ SecretRef แบบมีโครงสร้างเหมือนตัวอย่างด้านบน

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

รันบอต 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 ของตัวเอง และดูแลแคช โทเค็นแยกต่างหาก (แยกด้วย 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,
          historyLimit: 50,
          toolPolicy: "restricted",
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

groups["*"] ตั้งค่าเริ่มต้นสำหรับทุกกลุ่ม และรายการ groups.GROUP_OPENID แบบเจาะจงจะแทนที่ค่าเริ่มต้นเหล่านั้นสำหรับหนึ่งกลุ่ม การตั้งค่า กลุ่มประกอบด้วย:

• requireMention: กำหนดให้ต้องมี @mention ก่อนที่บอตจะตอบ ค่าเริ่มต้น: true
• ignoreOtherMentions: ทิ้งข้อความที่กล่าวถึงคนอื่นแต่ไม่ได้กล่าวถึงบอต
• historyLimit: เก็บข้อความกลุ่มล่าสุดที่ไม่ได้กล่าวถึงไว้เป็นบริบทสำหรับรอบถัดไปที่มีการกล่าวถึง ตั้งค่า 0 เพื่อปิดใช้
• toolPolicy: full, restricted หรือ none สำหรับเครื่องมือในขอบเขตกลุ่ม
• name: ป้ายชื่อที่อ่านง่าย ใช้ในบันทึกและบริบทกลุ่ม
• prompt: พรอมป์พฤติกรรมรายกลุ่มที่ต่อท้ายในบริบทของเอเจนต์

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

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

# เสียง (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

{
  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 ทับ config TTS ระดับช่องทาง/ทั่วโลก

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

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

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

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

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

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

# คำสั่งสแลช

คำสั่งในตัวที่ถูกดักก่อนคิว AI:

คำสั่ง	คำอธิบาย
/bot-ping	ทดสอบเวลาแฝง
/bot-version	แสดงเวอร์ชันเฟรมเวิร์ก OpenClaw
/bot-help	แสดงรายการคำสั่งทั้งหมด
/bot-me	แสดง ID ผู้ใช้ QQ ของผู้ส่ง (openid) สำหรับตั้งค่า allowFrom/groupAllowFrom
/bot-upgrade	แสดงลิงก์คู่มืออัปเกรด QQBot
/bot-logs	ส่งออกบันทึก Gateway ล่าสุดเป็นไฟล์
/bot-approve	อนุมัติการดำเนินการ QQ Bot ที่รอดำเนินการ (เช่น การยืนยันการอัปโหลด C2C หรือกลุ่ม) ผ่านโฟลว์เนทีฟ

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

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

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

QQ Bot มาพร้อมเอนจินที่สมบูรณ์ในตัวภายใน Plugin:

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

# การเริ่มต้นใช้งานด้วยรหัส QR

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

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

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

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

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

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

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