qqbot

#QQ Bot

Kết nối Hermes với QQ thông qua API QQ Bot chính thức (v2) — hỗ trợ tin nhắn riêng tư (C2C), @-đề cập nhóm, bang hội và tin nhắn trực tiếp với tính năng ghi âm giọng nói.

Tổng quan

Bộ điều hợp QQ Bot sử dụng Official QQ Bot API để:

• Nhận tin nhắn qua kết nối WebSocket liên tục tới Cổng QQ
• Gửi văn bản và trả lời đánh dấu thông qua REST API
• Tải xuống và xử lý hình ảnh, tin nhắn thoại và tệp đính kèm
• Phiên âm tin nhắn thoại bằng ASR tích hợp của Tencent hoặc nhà cung cấp STT có thể định cấu hình

Điều kiện tiên quyết

1. Ứng dụng QQ Bot — Đăng ký tại q.qq.com:
   • Tạo một ứng dụng mới và ghi lại ID ứng dụng và Bí mật ứng dụng của bạn
   • Kích hoạt các ý định cần thiết: Tin nhắn C2C, Tin nhắn nhóm @, Tin nhắn bang hội
   • Định cấu hình bot của bạn ở chế độ hộp cát để thử nghiệm hoặc xuất bản để sản xuất
2. Phụ thuộc — Bộ điều hợp yêu cầu aiohttp và `httpx

:

   pip install aiohttp httpx

## Cấu hình

### Thiết lập tương tác

`bash
Hermes gateway setup

`
``Chọn **QQ Bot** từ danh sách nền tảng và làm theo lời nhắc.

### Cấu hình thủ công

Đặt các biến môi trường cần thiết trong 

~/.Hermes/.env

:

`bash
QQ_APP_ID=your-app-id
QQ_CLIENT_SECRET=your-app-secret

`

## Biến môi trường

| Biến | Mô tả | Mặc định |
|---|---|---|
| 
`QQ_APP_ID
` | ID ứng dụng QQ Bot (bắt buộc) | — |
| 
`QQ_CLIENT_SECRET
` | Bí mật ứng dụng QQ Bot (bắt buộc) | — |
| 
`QQBOT_HOME_CHANNEL
` | OpenID để gửi cron/thông báo | — |
| 
`QQBOT_HOME_CHANNEL_NAME
` | Tên hiển thị cho kênh chủ |

Home
` |
| 
`QQ_ALLOWED_USERS
` | OpenID người dùng được phân tách bằng dấu phẩy để truy cập DM | mở (tất cả người dùng) |
| 
`QQ_GROUP_ALLOWED_USERS
` | OpenID nhóm được phân tách bằng dấu phẩy để truy cập nhóm | — |
| 
`QQ_ALLOW_ALL_USERS
` | Đặt thành 
`true
` để cho phép tất cả DM | 
`false
` |
| 
`QQ_PORTAL_HOST
` | Ghi đè máy chủ cổng thông tin QQ (được đặt thành 
`sandbox.q.qq.com
` để định tuyến hộp cát) | 
`q.qq.com
` |
| 
`QQ_STT_API_KEY
` | Khóa API cho nhà cung cấp dịch vụ chuyển giọng nói thành văn bản | — |
| 
`QQ_STT_BASE_URL
` | (Không đọc trực tiếp - thay vào đó hãy đặt 
`platforms.qqbot.extra.stt.baseUrl
` trong 
`config.yaml

) | không có |
| 
`QQ_STT_MODEL
` | Tên mẫu STT |

glm-asr
` |

## Cấu hình nâng cao

Để kiểm soát chi tiết hơn, hãy thêm cài đặt nền tảng vào 

~/.Hermes/config.yaml

:

`YAML
platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "your-app-id"
      CLIent_secret: "your-secret"
      markdown_support: true       # enable QQ markdown (msg_type 2). Config-only; no env-var equivalent.
      dm_policy: "open"          # open | allowlist | disabled
      allow_from:

        - "user_openid_1"
      group_policy: "open"       # open | allowlist | disabled
      group_allow_from:
        - "group_openid_1"
      stt:
        provider: "zai"          # zai (GLM-ASR), OpenAI (Whisper), etc.
        baseUrl: "https://open.bigmodel.cn/API/coding/paas/v4"
        APIKey: "your-stt-key"
        model: "glm-asr"

`

## Tin nhắn thoại (STT)

Phiên âm giọng nói hoạt động theo hai giai đoạn:
1. **QQ tích hợp ASR** (miễn phí, luôn được thử trước) — QQ cung cấp 
`asr_refer_text
` trong tệp đính kèm tin nhắn thoại, sử dụng tính năng nhận dạng giọng nói của chính Tencent
2. **Nhà cung cấp STT được định cấu hình** (dự phòng) — Nếu ASR của QQ không trả về văn bản, bộ điều hợp sẽ gọi API STT tương thích với OpenAI:
- **Zhipu/GLM (zai)**: Nhà cung cấp mặc định, sử dụng model 
`glm-asr

   - **OpenAI Whisper**: Đặt 
`QQ_STT_BASE_URL
` và 
`QQ_STT_MODEL

   - Bất kỳ điểm cuối STT tương thích OpenAI nào

## Khắc phục sự cố

### Bot ngắt kết nối ngay lập tức (ngắt kết nối nhanh)

Điều này thường có nghĩa là:
- **ID ứng dụng / Bí mật không hợp lệ** — Kiểm tra kỹ thông tin đăng nhập của bạn tại q.qq.com
- **Thiếu quyền** — Đảm bảo bot đã bật các ý định cần thiết
- **bot chỉ có hộp cát** — Nếu bot ở chế độ hộp cát, nó chỉ có thể nhận tin nhắn từ kênh thử nghiệm hộp cát của QQ

### Tin nhắn thoại chưa được phiên âm
1. Kiểm tra xem 
`asr_refer_text
` tích hợp của QQ có trong dữ liệu đính kèm không
2. Nếu sử dụng nhà cung cấp STT tùy chỉnh, hãy xác minh 
`QQ_STT_API_KEY
` được đặt chính xác
3. Kiểm tra nhật ký cổng xem có thông báo lỗi STT không

### Tin nhắn chưa được gửi
- Xác minh **ý định** của bot được bật tại q.qq.com
- Kiểm tra 
`QQ_ALLOWED_USERS
` nếu quyền truy cập DM bị hạn chế
- Đối với tin nhắn nhóm, hãy đảm bảo bot được **@đề cập** (chính sách nhóm có thể yêu cầu đưa vào danh sách cho phép)
- Kiểm tra 
`QQBOT_HOME_CHANNEL
` để gửi thông báo/cron`###Lỗi kết nối
- Đảm bảo đã cài đặt 
`aiohttp
` và 
`httpx

: 
`pip install aiohttp httpx

- Kiểm tra kết nối mạng với 
`API.sgroup.qq.com
` và cổng WebSocket
- Xem lại nhật ký cổng để biết thông báo lỗi chi tiết và hành vi kết nối lại