---
read_when:
    - คุณต้องการเชื่อมต่อ OpenClaw กับ QQ
    - คุณต้องตั้งค่าข้อมูลรับรองของ QQ Bot
    - คุณต้องการให้รองรับแชตกลุ่มหรือแชตส่วนตัวของ QQ Bot
summary: การตั้งค่า การกำหนดค่า และการใช้งาน QQ Bot
title: บอต QQ
x-i18n:
    generated_at: "2026-05-04T02:21:41Z"
    model: gpt-5.5
    provider: openai
    source_hash: e17fa0da2f6939ed28cac5f13b3e37e6c63b87a10250ff213f7a86685a6141d6
    source_path: channels/qqbot.md
    workflow: 16
---

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

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

## ติดตั้ง

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

```bash
openclaw plugins install @openclaw/qqbot
```

## ตั้งค่า

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

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

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

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

5. รีสตาร์ต Gateway

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

```bash
openclaw channels add
openclaw configure --section channels
```

## กำหนดค่า

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

```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 แบบ Env SecretRef:

```json5
{
  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 เดียว:

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

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

### แชตกลุ่ม

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

```json5
{
  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`                |

```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` และทำ 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 ได้

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

- [การจับคู่](/th/channels/pairing)
- [กลุ่ม](/th/channels/groups)
- [การแก้ไขปัญหาช่องทาง](/th/channels/troubleshooting)