picoclaw/docs/channels/wecom/wecom_aibot/README.pt-br.md

Voltar ao README

WeCom AI Bot

O WeCom AI Bot é uma forma oficial de integração de conversas com IA fornecida pelo WeCom. Suporta conversas privadas e em grupo, possui um protocolo de resposta em streaming integrado e suporta o envio proativo da resposta final via response_url após um timeout.

Comparação com outros canais WeCom

Recurso	WeCom Bot	WeCom App	WeCom AI Bot
Chat privado	✅	✅	✅
Chat em grupo	✅	❌	✅
Saída em streaming	❌	❌	✅
Push proativo em timeout	❌	✅	✅
Complexidade de configuração	Baixa	Alta	Média

Configuração

{
  "channels": {
    "wecom_aibot": {
      "enabled": true,
      "token": "YOUR_TOKEN",
      "encoding_aes_key": "YOUR_43_CHAR_ENCODING_AES_KEY",
      "webhook_path": "/webhook/wecom-aibot",
      "allow_from": [],
      "welcome_message": "你好！有什么可以帮助你的吗？",
      "max_steps": 10
    }
  }
}

Campo	Tipo	Obrigatório	Descrição
token	string	Sim	Token de verificação de callback, configurado na página de gerenciamento do AI Bot
encoding_aes_key	string	Sim	Chave AES de 43 caracteres, gerada aleatoriamente na página de gerenciamento do AI Bot
webhook_path	string	Não	Caminho do webhook (padrão: /webhook/wecom-aibot)
allow_from	array	Não	Lista de permissão de IDs de usuários; array vazio permite todos os usuários
welcome_message	string	Não	Mensagem de boas-vindas enviada quando o usuário abre o chat; deixe vazio para desativar
reply_timeout	int	Não	Timeout de resposta em segundos (padrão: 5)
max_steps	int	Não	Número máximo de etapas de execução do agente (padrão: 10)

Configuração passo a passo

1. Faça login no Console de Administração do WeCom
2. Acesse "Gerenciamento de Apps" → "AI Bot", depois crie ou selecione um AI Bot
3. Na página de configuração do AI Bot, preencha as informações de "Recebimento de Mensagens":
   • URL: http://<your-server-ip>:18790/webhook/wecom-aibot
   • Token: Gerado aleatoriamente ou personalizado
   • EncodingAESKey: Clique em "Gerar Aleatoriamente" para obter uma chave de 43 caracteres
4. Insira o Token e o EncodingAESKey no arquivo de configuração do PicoClaw, inicie o serviço e volte ao console de administração para salvar (o WeCom enviará uma requisição de verificação)

Tip

O servidor precisa ser acessível pelos servidores do WeCom. Se estiver em uma intranet ou desenvolvendo localmente, use ngrok ou frp para tunelamento.

Protocolo de resposta em streaming

O WeCom AI Bot usa um protocolo de "pull em streaming", diferente da resposta única de um webhook padrão:

Usuário envia uma mensagem
  │
  ▼
PicoClaw retorna imediatamente {finish: false} (Agente começa a processar)
  │
  ▼
WeCom faz pull aproximadamente a cada 1 segundo com {msgtype: "stream", stream: {id: "..."}}
  │
  ├─ Agente não concluído → retorna {finish: false} (continuar aguardando)
  │
  └─ Agente concluído → retorna {finish: true, content: "conteúdo da resposta"}

Tratamento de timeout (tarefa excede 30 segundos):

Se o processamento do agente demorar mais de aproximadamente 30 segundos (a janela máxima de polling do WeCom é de 6 minutos), o PicoClaw irá:

1. Fechar imediatamente o stream e exibir ao usuário: "⏳ 正在处理中，请稍候，结果将稍后发送。"
2. O agente continua executando em segundo plano
3. Após a conclusão do agente, a resposta final é enviada proativamente ao usuário via response_url incluído na mensagem

response_url é emitido pelo WeCom, válido por 1 hora, pode ser usado apenas uma vez, sem necessidade de criptografia — basta fazer um POST com o corpo da mensagem em markdown diretamente.

Mensagem de boas-vindas

Quando welcome_message está configurado, o PicoClaw responde automaticamente com essa mensagem quando um usuário abre a janela de chat com o AI Bot (evento enter_chat). Deixe vazio para ignorar silenciosamente.

"welcome_message": "你好！我是 PicoClaw AI 助手，有什么可以帮你？"

Perguntas frequentes

Falha na verificação da URL de callback

• Confirme que o firewall do servidor tem a porta correspondente aberta (padrão 18790)
• Confirme que token e encoding_aes_key estão preenchidos corretamente
• Verifique os logs do PicoClaw para ver se uma requisição GET do WeCom foi recebida

Mensagens sem resposta

• Verifique se allow_from está restringindo acidentalmente o remetente
• Procure por context canceled ou erros do agente nos logs
• Confirme que a configuração do agente (ex.: model_name) está correta

Nenhum push final recebido para tarefas longas

• Confirme que o callback da mensagem inclui response_url (suportado apenas pelo novo WeCom AI Bot)
• Confirme que o servidor consegue fazer requisições de saída (precisa fazer POST para response_url)
• Verifique nos logs as palavras-chave response_url mode e Sending reply via response_url

Referências

• Documentação de integração do WeCom AI Bot
• Descrição do protocolo de resposta em streaming
• Resposta proativa via response_url