OpenClaw + NapCat: Prática de Integração de Robô de IA no QQ

Dificuldade: Iniciante | Duração: 25 minutos | Resultado: Conecte o QQ ao OpenClaw usando o NapCat e obtenha controle sobre 45 ferramentas de IA

---

Público-alvo

Você já está usando o OpenClaw e experimentou a facilidade de processar tarefas através do Telegram, Discord ou outras plataformas. Agora, quer ir além: permitir que a IA assuma diretamente o controle do QQ. Use linguagem natural para postar anúncios em grupos, consultar membros, banir usuários, dar curtidas e controlar o comportamento do robô em chats privados.

O NapCat é uma ponte baseada no QQ (via protocolo OneBot 11), e o @hyl_aa/napcat é o plugin oficial de canal para conectá-lo ao OpenClaw. Uma vez instalado, seu robô de QQ se torna um Agente de IA com 45 ferramentas prontas para uso.

Este artigo é ideal para:

• Quem já implantou o OpenClaw e quer adicionar o QQ como interface de interação.
• Quem deseja que a IA execute operações de gerenciamento em grupos do QQ (banimento, expulsão, anúncios, etc.).
• Quem tem experiência no desenvolvimento de robôs OneBot ou QQ e quer uma integração rápida com o OpenClaw.

---

Dependências Principais e Ambiente

Repositório GitHub: https://github.com/Aliang1337/openclaw-napcat

---

Estrutura Completa do Projeto

Após a instalação do plugin @hyl_aa/napcat, a estrutura do diretório será a seguinte:

napcat/
├── index.ts                    # Entrada do plugin
├── openclaw.plugin.json        # Metadados do plugin
├── package.json
└── src/
    ├── channel.ts              # Definição do Plugin de Canal e Dock (núcleo de mensagens)
    ├── tools.ts                # Registro das 45 ferramentas do Agente de IA
    ├── api.ts                  # Cliente HTTP API OneBot 11
    ├── monitor.ts              # Monitoramento de mensagens WebSocket + processamento de voz STT
    ├── accounts.ts             # Análise de múltiplas contas
    ├── config-schema.ts        # JSON Schema de configuração + dicas de interface
    ├── probe.ts                # Detecção de conexão / Verificação de saúde
    ├── runtime.ts              # Contexto de tempo de execução
    ├── send.ts                 # Envio de mensagens
    └── types.ts                # Definições de tipos TypeScript

---

Passo a Passo

Passo 1: Instalar o NapCat e concluir o login da conta QQ

Esta etapa não tem relação direta com o OpenClaw; é o processo de instalação do próprio NapCat. Vamos colocar isso para funcionar primeiro.

Vá ao Repositório Oficial do NapCat, encontre o pacote de lançamento correspondente à sua versão do cliente QQ e conclua a instalação seguindo a documentação. O único requisito crítico é: a conta deve estar logada com sucesso e o robô deve estar online.

---

Passo 2: Configurar NapCat para ativar HTTP API + WebSocket Reverso

Após iniciar o NapCat, você precisa ativar dois canais:

HTTP API (usado pelo plugin para enviar mensagens ativamente, porta padrão 3000):

{
  "httpApi": {
    "enable": true,
    "port": 3000
  }
}

WebSocket Reverso (recebe mensagens do QQ e as envia para o OpenClaw):

{
  "reverseWs": {
    "enable": true,
    "urls": ["ws://127.0.0.1:18800"]
  }
}

18800 é a porta WS padrão atribuída ao canal NapCat pelo OpenClaw; o plugin monitorará esta porta ao iniciar. Se várias contas forem configuradas, as portas aumentarão sequencialmente (18800, 18801, 18802...), correspondendo aos channelId napcat, napcat_1, napcat_2, respectivamente.

Reinicie o NapCat após modificar as configurações para que tenham efeito.

---

Passo 3: Instalar o plugin @hyl_aa/napcat

Duas formas:

Opção 1: Instalação via npm (Recomendado)

openclaw plugins install @hyl_aa/napcat

Opção 2: Clone manual

cd ~/.openclaw/extensions
git clone https://github.com/Aliang1337/openclaw-napcat.git napcat
cd napcat && npm install --omit=dev

Após a instalação, reinicie o OpenClaw:

openclaw gateway restart

---

Passo 4: Configurar o canal NapCat no OpenClaw

Use openclaw config edit para abrir o arquivo de configuração e adicionar o bloco channels.napcat:

{
  "channels": {
    "napcat": {
      "httpApi": "http://127.0.0.1:3000",
      "accessToken": "seu_token",
      "selfId": "123456789",
      "dmPolicy": "allowlist",
      "allowFrom": ["QQ_do_amigo"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["numero_do_grupo"]
    }
  }
}

Explicação dos campos:

---

Passo 5: Configurar políticas de acesso dmPolicy / groupPolicy

Estes dois campos controlam quem pode interagir com a IA, sendo as configurações de segurança mais importantes:

dmPolicy (Política de Chat Privado):

groupPolicy (Política de Chat de Grupo):

allowFrom / groupAllowFrom:

• allowFrom: Lista branca de chats privados, insira os números de QQ permitidos (formato string numérica).
• groupAllowFrom: Lista branca de grupos; se deixado vazio, usará os valores de allowFrom.

Configuração mais comum — permitir IA apenas para grupos e amigos específicos:

{
  "channels": {
    "napcat": {
      "dmPolicy": "allowlist",
      "allowFrom": ["10001", "10002"],
      "groupPolicy": "allowlist",
      "groupAllowFrom": ["987654321"]
    }
  }
}

---

Passo 6: Definir tools.profile como "full"

Este é o erro mais comum. O perfil padrão tools.profile do OpenClaw é "coding", que filtra a maioria das ferramentas qq_*, fazendo com que a IA responda "Eu não tenho essa capacidade".

Adicione à configuração:

{
  "tools": {
    "profile": "full"
  }
}

O perfil "full" exporá todas as ferramentas fornecidas pelos canais (incluindo todas as 45 ferramentas qq_*) ao modelo de IA.

---

Passo 7: Reiniciar OpenClaw e verificar conexão

openclaw gateway restart
openclaw gateway status

Verifique nos logs se há informações de conexão bem-sucedida do canal NapCat. Se vir algo como "napcat connected" ou "reverse ws connected", o canal WebSocket entre o NapCat e o OpenClaw foi estabelecido.

Você também pode pedir ao robô para enviar uma mensagem de teste — se a interface HTTP API do NapCat estiver normal, o OpenClaw pode enviar mensagens ativamente para o QQ:

# Teste manual: faça a IA te enviar uma mensagem
# Envie no chat privado do QQ: "Olá"
# A IA deve responder

Se não houver resposta no chat privado, pule para o Passo 1 de "Solução de Problemas Comuns".

---

Passo 8: Chamar ferramentas de IA no QQ

Após validar a conexão, você pode usar linguagem natural no QQ para comandar a IA. Aqui estão alguns cenários típicos:

Envio de mensagens e anúncios:

"Poste um anúncio no grupo: reunião amanhã às 20h"
"Enviar anúncio de grupo: evento cancelado este fim de semana"

A IA chamará qq_send_group_notice, desde que o robô tenha permissões de proprietário ou administrador.

Gerenciamento de membros do grupo:

"Silencie @alguem por 10 minutos"
"Expulse aquela pessoa do grupo"
"Defina Fulano como administrador do grupo"

As ferramentas correspondentes são qq_mute_group_member, qq_kick_group_member e qq_set_group_admin.

Operações de consulta:

"Ver lista de membros do grupo"
"Mostre as últimas 30 mensagens deste grupo"
"Consulte o perfil de @alguem"

A IA chamará qq_get_group_member_list, qq_get_group_msg_history e qq_get_user_info.

Mensagens essenciais e arquivos:

"Defina esta mensagem como essência"
"Veja o que há nos arquivos do grupo"

Curtir mensagens e cutucar:

"Dê uma curtida para 3870871935"
"Dê um cutucão em @alguem"

---

Solução de Problemas Comuns

1. Falha na conexão WebSocket

Sintoma: O log do OpenClaw não mostra "napcat connected" e o robô não responde às mensagens.

Passos de verificação:

# 1. Verifique se o NapCat está rodando normalmente
curl http://127.0.0.1:3000/get_version_info
# Se retornar informações da versão, a HTTP API do NapCat está acessível

# 2. Verifique se a porta do WS reverso está ocupada
netstat -an | grep 18800
# Se outro processo estiver usando esta porta, o NapCat não conectará

# 3. Confirme se o endereço WS na configuração do NapCat está correto
# Deve coincidir com a porta do OpenClaw, padrão: ws://127.0.0.1:18800

Certifique-se de que a porta em reverseWs.urls na configuração do NapCat seja a mesma que o OpenClaw está monitorando.

---

2. Falha na autenticação accessToken

Sintoma: Resposta HTTP 401 ou erro "unauthorized" nos logs.

Verifique se a configuração do token no lado do NapCat e o campo accessToken no OpenClaw são idênticos. Se o NapCat não tiver a verificação de token ativada, deixe o campo accessToken vazio no OpenClaw.

// No NapCat (se houver token)
"accessToken": "meu-token-secreto"

// No OpenClaw deve ser idêntico
"accessToken": "meu-token-secreto"

---

3. @Robô não reconhecido

Sintoma: Enviou "@Robô Olá" no grupo, mas a IA não respondeu.

Ordem de verificação:

1. Confirme se o selfId está configurado com o número de QQ correto do próprio robô.
2. Confirme se groupPolicy não é disabled e se o número do grupo está na lista groupAllowFrom (se estiver no modo allowlist).
3. Confirme se o formato do @ é "@ApelidoDoRobo".
4. Verifique se o canal @hyl_aa/napcat está corretamente configurado no prompt do OpenClaw.

---

4. Ferramentas filtradas pelo perfil (qq_* indisponíveis)

Sintoma: IA responde "Eu não tenho essa capacidade", mas a configuração parece correta.

Este é o erro mais frequente. O padrão tools.profile: "coding" filtra a maioria das ferramentas de canal.

{
  "tools": {
    "profile": "full"
  }
}

Após a alteração, reinicie o OpenClaw e tente acionar o robô novamente no QQ.

---

5. Conflito de portas em múltiplas contas

Sintoma: Configurou uma segunda conta NapCat, mas o segundo robô não recebe mensagens.

Com múltiplas contas no NapCat, tanto a porta HTTP API quanto a porta WS reverso precisam ser incrementadas:

// Primeira conta
{
  "httpApi": { "port": 3000 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18800"] }
}

// Segunda conta
{
  "httpApi": { "port": 3001 },
  "reverseWs": { "urls": ["ws://127.0.0.1:18801"] }
}

O OpenClaw também precisa da configuração de mapeamento para múltiplas contas.

---

6. Falta de resposta devido às políticas dmPolicy / groupPolicy

Sintoma: Nenhuma reação no chat privado ou grupo; a IA parece não receber mensagens.

A causa mais comum é uma política muito restrita:

• dmPolicy: "allowlist" com allowFrom vazio → Ninguém pode acionar o chat privado.
• groupPolicy: "allowlist" com groupAllowFrom vazio → Nenhum grupo pode acionar.

Relaxe a política temporariamente para confirmar se este é o problema:

{
  "channels": {
    "napcat": {
      "dmPolicy": "open",
      "groupPolicy": "open"
    }
  }
}

Se responder normalmente após mudar para open, o problema está na configuração da lista branca.

---

Leituras Adicionais / Direções Avançadas

1. Configuração e Colaboração Multi-contas

O OpenClaw suporta a execução simultânea de várias contas de robô NapCat. Após defini-las no bloco accounts, você pode alternar entre contas usando comandos como /clawspec worker <account-id> (se usado com ClawSpec). Útil para: uma conta para suporte ao cliente e outra como bot de administração.

2. Configuração de Voz STT

Se deseja que a IA processe mensagens de voz, ative o áudio STT na configuração do OpenClaw:

{
  "tools": {
    "media": {
      "audio": {
        "enabled": true
      }
    }
  }
}

Uma vez ativado, as mensagens de voz no QQ serão transcritas automaticamente para texto antes de serem enviadas ao modelo de IA.

3. Prefixo de Resposta de IA Personalizado

Use responsePrefix para adicionar um prefixo a cada resposta da IA:

{
  "channels": {
    "napcat": {
      "responsePrefix": "[AI]"
    }
  }
}

A IA responderá como "[AI] Olá! Como posso ajudar?", facilitando a distinção entre respostas da IA e mensagens de membros do grupo.

4. Coexistência com outros canais OpenClaw

O OpenClaw pode se conectar a vários canais simultaneamente (NapCat + Telegram + Discord, etc.). Cada canal é independente, e o conjunto de ferramentas da IA é exposto uniformemente por tools.profile: "full". Você pode iniciar uma tarefa no Telegram e verificar o progresso no QQ.

5. Controle de Permissões e Segurança

dmPolicy e groupPolicy são apenas controles de acesso básicos. Em ambientes de produção, recomenda-se:

• Usar o modo allowlist para chats privados, adicionando apenas usuários confiáveis.
• Para operações de alto risco em grupos, configure a IA para solicitar confirmação do proprietário antes de agir.
• Verifique regularmente o status de login do NapCat.

6. Conexão com outros clientes compatíveis com OneBot 11

O NapCat não é a única opção. Qualquer cliente QQ que implemente o padrão OneBot 11 (como Lagrange ou LLOneBot) pode ser conectado ao OpenClaw da mesma forma.