Pular para o conteúdo principal

Documentação oficial desta página · v0.20.6

QQ Bot

Conecte o Hermes ao QQ pela API oficial de bots (v2) — com suporte a conversas privadas (C2C), menções em grupo, guildas e mensagens diretas, mais transcrição de áudio.

Visão geral​

O adaptador usa a API oficial de bots do QQ para:

  • receber mensagens por uma conexão WebSocket persistente com o gateway do QQ
  • enviar respostas em texto e markdown pela API REST
  • baixar e processar imagens, mensagens de voz e arquivos anexados
  • transcrever mensagens de voz com o reconhecimento embutido da Tencent, ou com um provedor de transcrição configurável

Pré-requisitos​

  1. Aplicação de bot no QQ — cadastre em q.qq.com:

    • crie uma aplicação nova e anote o App ID e o App Secret
    • habilite as intenções necessárias: mensagens C2C, menções em grupo, mensagens de guilda
    • configure o bot em modo sandbox para testar, ou publique para produção

  2. Dependências — o adaptador precisa de aiohttp e httpx:

    pip install aiohttp httpx

Configuração​

Configuração interativa​

hermes gateway setup

Escolha QQ Bot na lista de plataformas e siga as perguntas.

Configuração manual​

Defina as variáveis obrigatórias em ~/.hermes/.env:

QQ_APP_ID=seu-app-id
QQ_CLIENT_SECRET=seu-app-secret

Variáveis de ambiente​

VariávelDescriçãoPadrão
QQ_APP_IDApp ID do bot (obrigatória)—
QQ_CLIENT_SECRETApp Secret do bot (obrigatória)—
QQBOT_HOME_CHANNELOpenID para entrega de cron e notificações—
QQBOT_HOME_CHANNEL_NAMENome de exibição do canal principalHome
QQ_ALLOWED_USERSOpenIDs de usuário com acesso a mensagem direta, separados por vírgulaaberto (todos)
QQ_GROUP_ALLOWED_USERSOpenIDs de grupo com acesso, separados por vírgula—
QQ_ALLOW_ALL_USERStrue libera todas as mensagens diretasfalse
QQ_PORTAL_HOSTTroca o host do portal do QQ (use sandbox.q.qq.com para o sandbox)q.qq.com
QQ_STT_API_KEYChave do provedor de transcrição—
QQ_STT_BASE_URL(Não é lida diretamente — defina platforms.qqbot.extra.stt.baseUrl no config.yaml)—
QQ_STT_MODELModelo de transcriçãoglm-asr

Configuração avançada​

Para controle fino, acrescente as opções da plataforma em ~/.hermes/config.yaml:

platforms:
  qqbot:
    enabled: true
    extra:
      app_id: "seu-app-id"
      client_secret: "seu-secret"
      markdown_support: true       # liga o markdown do QQ (msg_type 2). Só por configuração; sem variável equivalente.
      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: "sua-chave-de-transcricao"
        model: "glm-asr"

Mensagens de voz​

A transcrição acontece em duas etapas:

  1. Reconhecimento embutido do QQ (gratuito, sempre tentado primeiro) — o QQ fornece o campo asr_refer_text nos anexos de voz, usando o reconhecimento de fala da própria Tencent.
  2. Provedor configurado (reserva) — se o reconhecimento do QQ não devolver texto, o adaptador chama uma API de transcrição compatível com a da OpenAI:
    • Zhipu/GLM (zai): provedor padrão, com o modelo glm-asr
    • Whisper da OpenAI: defina QQ_STT_BASE_URL e QQ_STT_MODEL
    • qualquer endpoint de transcrição compatível com o formato da OpenAI

Resolução de problemas​

O bot desconecta na hora​

Costuma significar:

  • App ID ou Secret inválidos — confira as credenciais em q.qq.com
  • Permissões faltando — garanta que as intenções necessárias estão habilitadas
  • Bot só em sandbox — em modo sandbox, ele só recebe mensagens do canal de teste do QQ

Mensagens de voz não são transcritas​

  1. Confira se o asr_refer_text do QQ está presente nos dados do anexo
  2. Se você usa um provedor próprio, confirme se o QQ_STT_API_KEY está definido
  3. Procure mensagens de erro de transcrição nos logs do gateway

Mensagens não chegam​

  • Confira se as intenções do bot estão habilitadas em q.qq.com
  • Verifique o QQ_ALLOWED_USERS, se o acesso por mensagem direta estiver restrito
  • Em grupos, o bot precisa ser mencionado (a política de grupo pode exigir lista de permissão)
  • Confira o QQBOT_HOME_CHANNEL, para entrega de cron e notificações

Erros de conexão​

  • Garanta que aiohttp e httpx estão instalados: pip install aiohttp httpx
  • Confira a conectividade com api.sgroup.qq.com e com o gateway WebSocket
  • Veja os logs do gateway, com as mensagens detalhadas de erro e o comportamento de reconexão