Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

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 จะไม่ถูกจัดเก็บเป็นข้อความธรรมดา หากคุณออกจากหน้าโดยไม่บันทึก คุณจะต้องสร้างใหม่อีกครั้ง
  1. เพิ่มช่องทาง:
openclaw channels add --channel qqbot --token "AppID:AppSecret"
  1. รีสตาร์ต 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ค่าสำรองของเฟรมเวิร์ก
STTchannels.qqbot.stttools.media.audio.models[0]
TTSchannels.qqbot.tts, channels.qqbot.accounts.<id>.ttsmessages.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 ได้

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