bot do QQ

​

Instalação

openclaw plugins install @openclaw/qqbot

​

Configuração inicial

1. Acesse a Plataforma Aberta do QQ e escaneie o código QR com o QQ do celular para se cadastrar / entrar.
2. Clique em Create Bot para criar um novo bot do QQ.
3. Encontre AppID e AppSecret na página de configurações do bot e copie-os.

4. Adicione o canal:

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

5. Reinicie o Gateway.

openclaw channels add

​

Configuração

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: "YOUR_APP_SECRET",
    },
  },
}

• QQBOT_APP_ID
• QQBOT_CLIENT_SECRET

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecretFile: "/path/to/qqbot-secret.txt",
    },
  },
}

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "YOUR_APP_ID",
      clientSecret: { source: "env", provider: "default", id: "QQBOT_CLIENT_SECRET" },
    },
  },
}

• openclaw channels add --channel qqbot --token-file ... define apenas o AppSecret; appId já deve estar definido na configuração ou em QQBOT_APP_ID.
• clientSecret aceita uma string de texto simples, um caminho de arquivo (clientSecretFile) ou um objeto SecretRef estruturado.
• Strings de marcador legadas secretref:... / secretref-env:... são rejeitadas para clientSecret; use um objeto SecretRef estruturado.

​

Transmissão

{
  channels: {
    qqbot: {
      streaming: {
        mode: "partial", // transmissão em blocos: "partial" (padrão) ou "off"
        nativeTransport: true, // usa a API stream_messages C2C oficial do QQ para mensagens diretas
      },
    },
  },
}

• streaming.mode: "off" desativa a transmissão em blocos para a conta.
• streaming.nativeTransport: true transmite respostas C2C (mensagens diretas) pela API oficial stream_messages do QQ; destinos de grupo/canal não são afetados.
• Valores escalares legados streaming: true|false e a chave streaming.c2cStreamApi migram para esse formato por meio de openclaw doctor --fix.
• /bot-streaming on|off alterna a mesma configuração a partir de uma mensagem direta.

​

Política de acesso

• allowFrom / groupAllowFrom controlam quem pode conversar com o bot nos contextos C2C / de grupo. dmPolicy / groupPolicy (open | allowlist | disabled) controlam o modo de aplicação. dmPolicy assume allowlist por padrão quando allowFrom tem uma entrada concreta (sem curinga); caso contrário, open. groupPolicy assume allowlist por padrão quando groupAllowFrom ou allowFrom tem uma entrada concreta; caso contrário, open.
• Os comandos de barra “Auth: allowlist” exigem uma entrada explícita sem curinga em allowFrom (ou groupAllowFrom para invocações em grupo), independentemente de dmPolicy / groupPolicy — consulte Comandos de barra.

​

Configuração de várias contas

{
  channels: {
    qqbot: {
      enabled: true,
      appId: "111111111",
      clientSecret: "secret-of-bot-1",
      accounts: {
        bot2: {
          enabled: true,
          appId: "222222222",
          clientSecret: "secret-of-bot-2",
        },
      },
    },
  },
}

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

​

Chats em grupo

{
  channels: {
    qqbot: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["member_openid"],
      groups: {
        "*": {
          requireMention: true,
          commandLevel: "all",
          historyLimit: 50,
          tools: { deny: ["exec", "read", "write"] },
        },
        GROUP_OPENID: {
          name: "Release room",
          requireMention: false,
          ignoreOtherMentions: true,
          commandLevel: "safety",
          historyLimit: 20,
          prompt: "Keep replies short and operational.",
        },
      },
    },
  },
}

​

Voz (STT / 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" },
            },
          },
        },
      },
    },
  },
}

• sttDirectFormats
• uploadDirectFormats
• transcodeEnabled

​

Formatos de destino

​

Comandos de barra

​

Mídia e armazenamento

• As mídias de entrada, saída e da ponte do Gateway compartilham uma única raiz de payload em ~/.openclaw/media/qqbot (respeitando OPENCLAW_HOME quando definido), portanto uploads, downloads e caches de transcodificação permanecem em um único diretório protegido.
• A entrega de mídia avançada para destinos C2C e de grupo passa por um único caminho sendMedia. Arquivos locais e buffers em memória de 5 MiB ou mais usam os endpoints de upload em partes do QQ; payloads menores e fontes de URL remota/Base64 usam a API de upload em uma única operação.
• Se uma atualização a quente interromper o Gateway antes que ele termine de gravar openclaw.json, o plugin restaurará os últimos appId / clientSecret conhecidos dessa conta a partir de um snapshot interno na próxima inicialização (sem nunca sobrescrever uma alteração intencional da configuração), portanto não será necessário escanear novamente o código QR.

​

Solução de problemas

• O Gateway não inicia / não há mensagens de entrada: verifique se appId e clientSecret estão corretos e se o bot está habilitado na QQ Open Platform. A ausência de uma credencial é indicada como “QQBot não configurado (appId ou clientSecret ausente)”.
• A configuração com --token-file ainda aparece como não configurada: --token-file apenas define o AppSecret. appId ainda precisa ser definido na configuração ou em QQBOT_APP_ID.
• Respostas em rajadas no grupo entram em conflito: quando a fila de um par fica cheia, a fila de entrada descarta mensagens criadas por bots antes das mensagens de pessoas e combina rajadas de mensagens normais (que não sejam comandos) do grupo em um único turno atribuído; assim, uma enxurrada de mensagens de bots não deve impedir o processamento das mensagens de pessoas.
• Mensagens proativas não chegam: o QQ pode bloquear mensagens iniciadas pelo bot se o usuário não tiver interagido recentemente.
• A voz não é transcrita: verifique se o STT está configurado e se o provedor está acessível.

​

Relacionado

• Emparelhamento
• Grupos
• Solução de problemas de canais