Prática com o Hermes Agent: montar um assistente de IA em todas as plataformas (Telegram/Feishu/WeCom corporativo)

Dificuldade: média · Duração: cerca de 20 minutos · Resultado: dominar a configuração principal para integrar o Hermes em todas as plataformas

Você já pensou nisso: um mesmo assistente de IA rodando no Telegram, no Feishu e no WeCom corporativo — e, ainda assim, com apenas uma única implantação? O Hermes Agent faz isso.

Ele é um AI Agent de autoaprendizagem em evolução, open-source, do Nous Research. Um dos seus maiores destaques é uma “mensageira” (gateway) embutida para todas as plataformas. Basta iniciar um processo no servidor para se conectar, ao mesmo tempo, a 10+ plataformas como Telegram, Discord, Slack, Feishu, WeCom, Signal e WhatsApp. As mensagens são roteadas automaticamente, a memória é compartilhada entre plataformas, a configuração é feita uma vez e passa a valer para sempre.

Hoje, vamos conectar juntos as três plataformas mais usadas — Telegram, Feishu ( Lark ) e WeCom corporativo — inteiramente.

---

Público-alvo

Este artigo é indicado para os seguintes desenvolvedores:

• Você tem uma base razoável em Linux / linha de comando e quer hospedar um AI Agent no servidor
• Você é um desenvolvedor independente ou uma equipe pequena e precisa integrar mensagens em múltiplas plataformas
• Você está avaliando o Hermes Agent como alternativa ao OpenClaw

---

Dependências principais e ambiente

---

Estrutura completa do projeto

hermes-agent/
├── scripts/
│   └── install.sh              # Script de instalação “um clique”
└── ~/.hermes/                   # Diretório principal de configuração (gerado automaticamente após a instalação)
    ├── config.yaml              # Configuração principal (modelo, conjunto de ferramentas)
    ├── .env                     # API Keys (não enviar para o Git!)
    ├── skills/                  # Diretório de skills
    ├── memory/                  # Memória persistente
    ├── sessions/                # Histórico de sessões (busca全文 FTS5)
    └── gateway/                 # Configuração do gateway (YAML independente para cada plataforma)
        ├── telegram.yaml
        ├── feishu.yaml
        └── wecom.yaml

---

Passo a passo

Passo 1: instalar o Hermes Agent com um clique

No Linux / macOS / WSL2, execute o script oficial de instalação:

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

O script de instalação trata automaticamente Python, Node.js e todas as dependências, sem intervenção manual durante todo o processo. Ao terminar, recarregue o shell:

source ~/.bashrc    # para usuários bash
source ~/.zshrc     # para usuários zsh

Verifique se a instalação foi concluída com sucesso:

hermes doctor

Passo 2: configurar o provedor de LLM — integrar com Defapi

Em seguida, precisamos informar ao Hermes onde buscar o modelo de linguagem grande. Vamos inserir a API Key no arquivo .env:

hermes config set ANTHROPIC_API_KEY <your-defapi-key>

A Defapi é compatível com o protocolo da interface v1/messages do Anthropic; o Hermes consegue integrar diretamente. Você também pode selecionar o modelo e o Provider de forma interativa usando o comando hermes model:

hermes model
# seleção interativa:
# 1. Nous Portal
# 2. OpenRouter (200+ modelos)
# 3. OpenAI
# 4. Defapi / endpoint personalizado
# 5. Outros...

Se usar Defapi, no menu interativo selecione o endpoint personalizado (Custom) e preencha:

API Endpoint: https://api.defapi.org
Model: anthropic/claude-opus-4.6

Passo 3: integrar a primeira plataforma — Telegram Bot

Esta é a maneira mais fácil de validar, pois a Bot API do Telegram é pública e não exige certificação corporativa.

3.1 Criar o Bot

No Telegram, procure @BotFather, envie /newbot, dê um nome ao Bot conforme as instruções e obtenha o BOT_TOKEN. O formato é algo como 123456789:ABCdefGHIjklMNOpqrsTUVwxyz.

3.2 Configurar o gateway do Hermes

hermes gateway setup
# selecione telegram para entrar na configuração interativa

Ou crie manualmente ~/.hermes/gateway/telegram.yaml:

platform: telegram
enabled: true
bot_token: "123456789:ABCdefGHIjklMNOpqrsTUVwxyz"

# Controle de acesso: permite apenas usuários específicos
allowed_users:
  - your_telegram_username

# Configurações de segurança
require_approval_for_dangerous_tools: true

3.3 Verificar

Após iniciar o gateway, envie uma mensagem para o Bot:

hermes gateway start
# ou rodar em segundo plano:
hermes gateway start --daemon

No Telegram, envie /new para o Bot: ele deve responder com uma mensagem de boas-vindas. Envie também uma mensagem em chinês, por exemplo "你好" (olá/oi em chinês), e veja se a IA responde.

Passo 4: integrar Feishu (app corporativo Lark)

A integração do Feishu é um pouco mais complexa: exige criar um app corporativo na plataforma aberta do Feishu.

4.1 Criar um app na plataforma aberta do Feishu

1. Abra Plataforma aberta do Feishu e crie um app corporativo
2. Em «Credenciais e informações básicas», obtenha App ID e App Secret
3. Ative a capacidade «Robô»

4.2 Configurar subscrição de eventos

No «Subscrição de eventos» do app:

• URL de endereço do pedido: preencha https://你的域名/gateway/feishu/webhook
• Seleção de evento: im.message.receive_v1 (para receber mensagens)

4.3 Instalar o app na empresa

Em «Gerenciamento de versão e publicação», crie uma versão e publique; caso contrário, o Bot não consegue receber mensagens.

4.4 Configurar o gateway do Hermes

hermes gateway setup
# selecione feishu; preencha App ID e App Secret na interação

Edite manualmente ~/.hermes/gateway/feishu.yaml:

platform: feishu
enabled: true
app_id: "cli_xxxxxxxxxxxxxx"
app_secret: "xxxxxxxxxxxxxxxxxxxx"
verification_token: "your_verification_token"

# Criptografia de mensagens (opcional, mas recomendado)
encrypt_key: "your_encrypt_key"

# Grupos e usuários permitidos
allowed_chats: []
require_mention: false

4.5 Verificar

No Feishu, envie /new para o Bot e veja se há resposta. O formato de mensagens do Feishu é diferente do Telegram: o Bot suporta cartões de mensagem com texto rico, e o Hermes adapta automaticamente.

Passo 5: integrar WeCom corporativo (WeCom)

O modo de integração do WeCom é parecido com o do Feishu: também segue o padrão de callback via Webhook.

5.1 Criar um app no painel administrativo do WeCom

1. Faça login em Painel administrativo do WeCom
2. Vá em «Gerenciamento de aplicativos» → «Criar aplicativo» → selecione «Corporativo criado»
3. Obtenha AgentId, Secret e o CorpId da empresa
4. Configure «IPs confiáveis da empresa» para o IP do seu servidor

5.2 Configurar o recebimento de mensagens

Nas configurações do app, ative o modo «Receber mensagens»:

• Preencha URL: https://你的域名/gateway/wecom/webhook
• Selecione «Modo compatível» ou «Modo de eventos»

5.3 Configurar o gateway do Hermes

# ~/.hermes/gateway/wecom.yaml
platform: wecom
enabled: true
corp_id: "wwxxxxxxxxxxxxxx"
agent_id: "1000001"
corp_secret: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
encrypt_mode: "safe"    # No modo seguro, é necessário configurar encoding_aes_key
encoding_aes_key: "your_32_char_aes_key"

5.4 Verificar

No WeCom, encontre seu aplicativo e envie uma mensagem de teste.

Passo 6: iniciar o gateway e rodar os três em uma vez

Depois que todas as plataformas estiverem configuradas, inicie o gateway com um único comando:

hermes gateway start

O Hermes carrega automaticamente todas as configurações de plataformas habilitadas em ~/.hermes/gateway/ e inicia em paralelo todos os adaptadores. Se alguma plataforma falhar ao iniciar (por exemplo, Token incorreto), isso não afeta o funcionamento normal das demais.

Use hermes gateway status para ver o status de execução de cada plataforma:

Platform  Status   Users   Messages
telegram  ● online   3         142
feishu    ● online   7          89
wecom     ● online   2          15

Pare o gateway com Ctrl+C ou rode em segundo plano com --daemon:

hermes gateway start --daemon

Passo 7: validar mensagens entre múltiplas plataformas

Agora você pode enviar mensagens para o Bot em cada uma das três plataformas para testar:

# Telegram
/new
你好，介绍一下你自己

# Feishu
/new
你是谁？

# WeCom
/new
有什么我能帮你的？

As três respostas são totalmente consistentes, com memória compartilhada — o que você disser no Telegram, o Feishu e o WeCom também sabem. Esse é o valor mais central do Hermes: uma configuração, experiência unificada em todas as plataformas.

---

Solução de problemas (FAQ)

1. O Telegram Bot não recebe mensagens

Sintoma: o Bot não responde de forma alguma; ao verificar os logs, não aparece nenhum registro.

Passos de verificação:

# 1. Confirme se o Token está correto
hermes config get telegram.bot_token

# 2. Confirme que a porta não está em uso
ss -tlnp | grep 8080

# 3. Se você usou modo webhook, verifique a configuração da Telegram Bot API
# A URL do webhook precisa ser acessível publicamente; para desenvolvimento local, use ngrok para o tunelamento
ngrok http 8080

# 4. Reinicialize o webhook (às vezes o Bot fica preso no webhook antigo)
curl -X POST "https://api.telegram.org/bot<YOUR_TOKEN>/deleteWebhook"

2. Falha na validação do callback do Feishu

Sintoma: a plataforma aberta do Feishu mostra «Validação da URL de callback falhou».

Passos de verificação:

# 1. Confirme se a URL pública está acessível
curl -X GET "https://your-domain.com/gateway/feishu/webhook"

# 2. Verifique a verificação de assinatura do Feishu
# O Feishu usa criptografia AES para mensagens; encrypt_key precisa ser igual ao configurado no painel
# Veja os logs do Hermes:
hermes logs --platform feishu

3. Mensagens no WeCom sem resposta

Sintoma: a mensagem é enviada, mas não há nenhuma resposta; não aparece nada nos logs.

Passos de verificação:

# 1. Confirme se CorpId / AgentId / Secret estão corretos
# 2. O mais importante: verifique a lista de permissões de IP
# O WeCom exige que o IP do servidor que chama a API esteja na lista de IPs confiáveis

# 3. Teste a obtenção do AccessToken
curl "https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=wwxxx&corpsecret=secret"

# Se retornar "errmsg": "ip not in whitelist", significa que o IP não foi liberado

4. O modelo não responde

Sintoma: a mensagem é recebida pelo Bot, mas a IA não responde; fica sempre “thinking”.

Passos de verificação:

# 1. Teste se a API Key é válida
curl -X POST "https://api.defapi.org/api/v1/messages" \
  -H "Authorization: Bearer <your-key>" \
  -H "Content-Type: application/json" \
  -d '{"model":"anthropic/claude-opus-4.6","messages":[{"role":"user","content":"hi"}],"max_tokens":10}'

# 2. Verifique a configuração do modelo
hermes config get model

# 3. Verifique fallback_providers (recomendado configurar)
# Em ~/.hermes/config.yaml, adicione um Provider de backup:
fallback_providers:
  - provider: openrouter
    api_key: "${OPENROUTER_API_KEY}"

5. Erro ao executar ferramentas

Sintoma: o Bot responde dizendo que não consegue executar uma determinada ação.

Passos de verificação:

# 1. Verifique o conjunto de ferramentas atualmente habilitado
hermes tools

# 2. Habilite o conjunto de ferramentas necessário
hermes tools enable web_search
hermes tools enable terminal

# 3. Comandos perigosos exigem confirmação manual
# Verifique a configuração:
hermes config get approval_required
# Se estiver como true, todos os comandos perigosos precisarão da sua aprovação manual

6. Conflito de concorrência entre múltiplas plataformas

Sintoma: uma plataforma recebe a mensagem, mas as outras não respondem.

Passos de verificação:

No Hermes v0.6.0, o mecanismo token-lock pode evitar que dois adaptadores de plataforma usem o mesmo Bot Token em conflito. Porém, se você estiver executando vários instâncias do mesmo Bot em máquinas diferentes, esse problema pode aparecer.

# Confirme que apenas uma instância do Hermes gateway está em execução
ps aux | grep hermes
pkill -f hermes-agent

# Depois, reinicie
hermes gateway start

---

Leitura adicional / caminhos avançados

Migrar do OpenClaw

Se você já usa OpenClaw, o Hermes oferece uma ferramenta oficial de migração, capaz de importar automaticamente SOUL.md, MEMORY.md, Skills, API Keys e configurações das plataformas de mensagens:

hermes claw migrate              # migração completa interativa
hermes claw migrate --dry-run    # primeiro faça uma prévia
hermes claw migrate --preset user-data  # não migra informações sensíveis

Modo MCP Server

O Hermes v0.6.0 adicionou a capacidade de MCP Server, permitindo expor ferramentas do Hermes para o exterior com um único comando:

hermes mcp serve
# suporta dois protocolos de transporte: stdio e Streamable HTTP

Após conectar, IDEs como Cursor, VS Code e Zed conseguem chamar todas as ferramentas e capacidades de diálogo do Hermes via protocolo MCP.

Sistema de Skills personalizado

O sistema de Skills do Hermes permite criar skills automaticamente a partir de descrições em linguagem natural. Também é possível escrever manualmente:

# Ver skills existentes
hermes skills

# Navegar pelo Skills Hub (mercado de skills da comunidade)
/skills

# Instalar skills da comunidade a partir de agentskills.io

Tarefas agendadas (Cron)

Configure tarefas com linguagem natural; o Hermes executa automaticamente e envia os resultados para qualquer plataforma:

# Todo dia às 8h, enviar um relatório do clima para o Telegram
/cron "Every day at 8am, summarize today's weather and send to me" --platform telegram

---

Conclusão

O design do gateway para múltiplas plataformas do Hermes Agent é muito elegante — você só precisa manter uma única configuração para fazer a mesma instância do Agent rodar em qualquer plataforma de mensagens. A memória é compartilhada entre plataformas, a configuração é resolvida uma vez e o uso de recursos é muito menor do que rodar vários Bots independentes.

Se você ainda usa o OpenClaw, ou está procurando um AI Agent open-source que realmente “entregue”, vale a pena gastar 20 minutos para testar o Hermes. Com o Claude Opus 4.6 com preço reduzido do Defapi, o custo mensal pode ser comprimido para 50% do original, enquanto a experiência não perde qualidade.