QQ Bot

Kết nối Hermes với QQ thông qua API Bot QQ chính thức (v2) — hỗ trợ tin nhắn riêng (C2C), đề cập nhóm @, guild và tin nhắn trực tiếp kèm chuyển đổi giọng nói.

Tổng quan

Bộ điều hợp QQ Bot sử dụng API Bot QQ chính thức để:

• Nhận tin nhắn qua kết nối WebSocket liên tục đến QQ Gateway
• Gửi phản hồi văn bản và markdown qua REST API
• Tải xuống và xử lý hình ảnh, tin nhắn giọng nói và tệp đính kèm
• Chuyển đổi tin nhắn giọng nói bằng ASR tích hợp của Tencent hoặc nhà cung cấp STT cấu hình được

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

1. Ứng dụng QQ Bot — Đăng ký tại q.qq.com:

   • Tạo ứng dụng mới và ghi lại App ID và App Secret
   • Bật các intent cần thiết: tin nhắn C2C, tin nhắn @nhóm, tin nhắn Guild
   • Cấu hình bot ở chế độ sandbox để kiểm thử, hoặc publish cho production

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

hermes setup gateway

Chọn QQ Bot từ danh sách nền tảng và làm theo hướng dẫn.

Cấu hình thủ công

Đặt các biến môi trường bắt buộc trong ~/.hermes/.env:

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	App ID của QQ Bot (bắt buộc)	—
QQ_CLIENT_SECRET	App Secret của QQ Bot (bắt buộc)	—
QQ_HOME_CHANNEL	OpenID cho gửi cron/thông báo	—
QQ_HOME_CHANNEL_NAME	Tên hiển thị cho kênh chính	Home
QQ_ALLOWED_USERS	Danh sách OpenID người dùng được phép DM, cách nhau bằng dấu phẩy	mở (tất cả)
QQ_ALLOW_ALL_USERS	Đặt true để cho phép tất cả DM	false
QQ_MARKDOWN_SUPPORT	Bật markdown QQ (msg_type 2)	true
QQ_STT_API_KEY	API key cho nhà cung cấp chuyển giọng nói thành văn bản	—
QQ_STT_BASE_URL	URL cơ sở cho nhà cung cấp STT	https://open.bigmodel.cn/api/coding/paas/v4
QQ_STT_MODEL	Tên mô hình STT	glm-asr

Cấu hình nâng cao

Để kiểm soát chi tiết, thêm cài đặt nền tảng vào ~/.hermes/config.yaml:

platforms:
  qq:
    enabled: true
    extra:
      app_id: "your-app-id"
      client_secret: "your-secret"
      markdown_support: true
      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), v.v.
        baseUrl: "https://open.bigmodel.cn/api/coding/paas/v4"
        apiKey: "your-stt-key"
        model: "glm-asr"

Tin nhắn giọng nói (STT)

Chuyển đổi giọng nói hoạt động theo hai giai đoạn:

1. ASR tích hợp QQ (miễn phí, luôn thử trước) — QQ cung cấp asr_refer_text trong tệp đính kèm tin nhắn giọng nói, sử dụng nhận dạng giọng nói của Tencent

2. Nhà cung cấp STT đã 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 gọi API STT tương thích OpenAI:

   • Zhipu/GLM (zai): Nhà cung cấp mặc định, sử dụng mô hình glm-asr
   • OpenAI Whisper: Đặt QQ_STT_BASE_URL và QQ_STT_MODEL
   • Bất kỳ endpoint 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 nhanh)

Điều này thường có nghĩa:

• App ID / Secret không hợp lệ — Kiểm tra lại thông tin xác thực tại q.qq.com
• Thiếu quyền — Đảm bảo bot đã bật các intent cần thiết
• Bot chỉ sandbox — Nếu bot ở chế độ sandbox, nó chỉ nhận tin nhắn từ kênh kiểm thử sandbox của QQ

Tin nhắn giọng nói không được chuyển đổi

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, xác minh QQ_STT_API_KEY được đặt đúng
3. Kiểm tra nhật ký gateway để tìm thông báo lỗi STT

Tin nhắn không được gửi

• Xác minh intent 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, đảm bảo bot được @đề cập (chính sách nhóm có thể yêu cầu danh sách cho phép)
• Kiểm tra QQ_HOME_CHANNEL cho gửi cron/thông báo

Lỗi kết nối

• Đảm bảo aiohttp và httpx đã được cài đặt: pip install aiohttp httpx
• Kiểm tra kết nối mạng đến api.sgroup.qq.com và WebSocket gateway
• Xem nhật ký gateway để biết thông báo lỗi chi tiết và hành vi kết nối lại