Instalação do DingTalk

O Hermes Agent se integra ao DingTalk (钉钉) como chatbot, o que deixa você conversar com o seu assistente de IA por mensagem direta ou em grupos. O bot se conecta pelo Stream Mode do DingTalk — uma conexão WebSocket de longa duração que não exige URL pública nem servidor de webhook — e responde com mensagens formatadas em markdown, pela API de webhook de sessão do DingTalk.

Antes da instalação, a parte que a maioria quer saber: como o Hermes se comporta depois que entra no seu espaço de trabalho do DingTalk.

Como o Hermes se comporta

Contexto	Comportamento
Mensagens diretas (conversa 1:1)	O Hermes responde a toda mensagem. Não precisa de @mention. Cada conversa direta tem a própria sessão.
Grupos	O Hermes responde quando você faz @mention nele. Sem menção, o Hermes ignora a mensagem.
Grupos compartilhados com vários usuários	Por padrão, o Hermes isola o histórico de sessão por usuário dentro do grupo. Duas pessoas conversando no mesmo grupo não compartilham a mesma transcrição, a menos que você desligue isso explicitamente.

Modelo de sessão no DingTalk

Por padrão:

• cada conversa direta ganha a própria sessão
• cada usuário de um grupo compartilhado ganha a própria sessão dentro daquele grupo

Isso é controlado pelo config.yaml:

group_sessions_per_user: true

Coloque false só se você realmente quiser uma conversa compartilhada para o grupo inteiro:

group_sessions_per_user: false

Este guia leva você pelo processo completo — de criar o bot no DingTalk até enviar a primeira mensagem.

Pré-requisitos

Instale os pacotes Python necessários:

cd ~/.hermes/hermes-agent && uv pip install -e ".[dingtalk]"

Ou um por um:

pip install dingtalk-stream httpx alibabacloud-dingtalk

• dingtalk-stream — SDK oficial do DingTalk para o Stream Mode (mensagens em tempo real por WebSocket)
• httpx — cliente HTTP assíncrono usado para enviar respostas por webhooks de sessão
• alibabacloud-dingtalk — SDK da OpenAPI do DingTalk para AI Cards, reações com emoji e download de mídia

Passo 1: crie um app no DingTalk

1. Vá ao console de desenvolvedor do DingTalk.
2. Entre com a sua conta de administrador do DingTalk.
3. Clique em Desenvolvimento de aplicações → Apps personalizados → Criar app por micro-app H5 (ou Robot, dependendo da versão do seu console).
4. Preencha:
   • Nome do app: por exemplo, Hermes Agent
   • Descrição: opcional
5. Depois de criar, vá em Credenciais e informações básicas para achar o Client ID (AppKey) e o Client Secret (AppSecret). Copie os dois.

As credenciais aparecem uma vez só

O Client Secret só é exibido uma vez, quando você cria o app. Se perder, vai precisar gerar de novo. Nunca compartilhe essas credenciais publicamente nem faça commit delas no Git.

Passo 2: habilite a capacidade de robô

1. Na página de configurações do seu app, vá em Adicionar capacidade → Robot.
2. Habilite a capacidade de robô.
3. Em Modo de recepção de mensagens, escolha Stream Mode (recomendado — não precisa de URL pública).

dica

O Stream Mode é a instalação recomendada. Ele usa uma conexão WebSocket de longa duração, iniciada pela sua máquina, então você não precisa de IP público, nome de domínio nem endpoint de webhook. Isso funciona atrás de NAT, de firewalls e em máquinas locais.

Passo 3: descubra o seu User ID do DingTalk

O Hermes Agent usa o seu User ID do DingTalk para controlar quem pode interagir com o bot. Os User IDs do DingTalk são strings alfanuméricas definidas pelo administrador da sua organização.

Para descobrir o seu:

1. Pergunte ao administrador da sua organização no DingTalk — os User IDs são configurados no console de administração do DingTalk, em Contatos → Membros.
2. Como alternativa, o bot registra o sender_id de cada mensagem que chega. Suba o gateway, mande uma mensagem para o bot e procure o seu ID nos logs.

Passo 4: configure o Hermes Agent

Opção A: instalação interativa (recomendada)

Rode o comando de instalação guiada:

hermes gateway setup

Escolha DingTalk quando for perguntado. O assistente pode autorizar por um de dois caminhos:

• Fluxo de dispositivo por QR code (recomendado). Leia com o app do DingTalk no celular o QR que aparece no seu terminal — o Client ID e o Client Secret voltam automaticamente e são escritos em ~/.hermes/.env. Não precisa passar pelo console de desenvolvedor.
• Colar na mão. Se você já tem as credenciais (ou ler o QR code não é prático), cole o seu Client ID, o Client Secret e os IDs de usuário permitidos quando for perguntado.

Aviso sobre a marca openClaw

Como o verification_uri_complete do DingTalk está fixo na identidade openClaw na camada de API, o QR autoriza hoje sob a string de origem openClaw, até a Alibaba / DingTalk-Real-AI registrar um template específico do Hermes no servidor. Isso é só como o DingTalk apresenta a tela de consentimento — o bot que você cria é inteiramente seu e privado do seu tenant.

Opção B: configuração manual

Acrescente o seguinte ao seu arquivo ~/.hermes/.env:

# Obrigatório
DINGTALK_CLIENT_ID=sua-app-key
DINGTALK_CLIENT_SECRET=seu-app-secret

# Segurança: restringe quem pode interagir com o bot
DINGTALK_ALLOWED_USERS=user-id-1

# Vários usuários permitidos (separados por vírgula)
# DINGTALK_ALLOWED_USERS=user-id-1,user-id-2

# Opcional: trava de grupo (igual a Slack/Telegram/Discord/WhatsApp)
# DINGTALK_REQUIRE_MENTION=true
# DINGTALK_FREE_RESPONSE_CHATS=cidABC==,cidDEF==
# DINGTALK_MENTION_PATTERNS=^小马
# DINGTALK_HOME_CHANNEL=cidXXXX==
# DINGTALK_ALLOW_ALL_USERS=true

Ajustes opcionais de comportamento em ~/.hermes/config.yaml:

group_sessions_per_user: true

gateway:
  platforms:
    dingtalk:
      extra:
        # Exige @mention nos grupos antes de o bot responder (igual a Slack/Telegram/Discord).
        # Mensagens diretas ignoram isso — o bot sempre responde em conversas 1:1.
        require_mention: true

        # Lista de permissão por plataforma. Quando definida, só estes IDs de usuário do DingTalk
        # podem interagir com o bot (mesma semântica de DINGTALK_ALLOWED_USERS, mas no escopo daqui
        # em vez do .env).
        allowed_users:
          - user-id-1
          - user-id-2

• group_sessions_per_user: true mantém o contexto de cada participante isolado dentro dos grupos compartilhados
• require_mention: true impede o bot de responder a toda mensagem de grupo — ele só responde quando alguém menciona ele com @
• allowed_users em dingtalk.extra é uma alternativa a DINGTALK_ALLOWED_USERS; use um ou outro (se os dois estiverem definidos, só ficam autorizados os usuários presentes nas duas listas)

Suba o gateway

Com tudo configurado, suba o gateway do DingTalk:

hermes gateway

O bot deve se conectar ao Stream Mode do DingTalk em alguns segundos. Mande uma mensagem para ele — por conversa direta ou num grupo em que ele tenha sido adicionado — para testar.

dica

Você pode rodar o hermes gateway em segundo plano ou como serviço systemd, para uma operação permanente. Veja a documentação de implantação para os detalhes.

Recursos

AI Cards

O Hermes pode responder com AI Cards do DingTalk em vez de mensagens simples em markdown. Os cards oferecem uma exibição mais rica e estruturada e aceitam atualizações em streaming enquanto o agente gera a resposta.

Para habilitar os AI Cards, configure um ID de template de card no config.yaml:

platforms:
  dingtalk:
    enabled: true
    extra:
      card_template_id: "seu-id-de-template-de-card"

Você encontra o ID do template de card no console de desenvolvedor do DingTalk, nas configurações de AI Card do seu app. Com os AI Cards habilitados, todas as respostas são enviadas como cards, com atualização de texto em streaming.

Reações com emoji

O Hermes acrescenta reações com emoji nas suas mensagens automaticamente, para mostrar o estado do processamento:

• 🤔Thinking — acrescentado quando o bot começa a processar a sua mensagem
• 🥳Done — acrescentado quando a resposta termina (substitui a reação Thinking)

Essas reações funcionam tanto em conversas diretas quanto em grupos.

Ajustes de exibição

Você pode personalizar o comportamento de exibição do DingTalk de forma independente das outras plataformas:

display:
  platforms:
    dingtalk:
      show_reasoning: false   # Mostra o raciocínio do modelo nas respostas
      streaming: true         # Liga as respostas em streaming (funciona com AI Cards)
      tool_progress: all      # Mostra o progresso das ferramentas (all/new/off)
      interim_assistant_messages: true  # Mostra as mensagens de comentário intermediárias

Para desligar o progresso das ferramentas e as mensagens intermediárias e ter uma experiência mais limpa:

display:
  platforms:
    dingtalk:
      tool_progress: off
      interim_assistant_messages: false

Resolução de problemas

O bot não responde às mensagens

Causa: a capacidade de robô não está habilitada, ou o DINGTALK_ALLOWED_USERS não inclui o seu User ID.

Solução: confira se a capacidade de robô está habilitada nas configurações do app e se o Stream Mode está selecionado. Verifique se o seu User ID está em DINGTALK_ALLOWED_USERS. Reinicie o gateway.

Erro "dingtalk-stream not installed"

Causa: o pacote Python dingtalk-stream não está instalado.

Solução: instale:

pip install dingtalk-stream httpx

"DINGTALK_CLIENT_ID and DINGTALK_CLIENT_SECRET required"

Causa: as credenciais não estão definidas no ambiente nem no arquivo .env.

Solução: confira se DINGTALK_CLIENT_ID e DINGTALK_CLIENT_SECRET estão corretos em ~/.hermes/.env. O Client ID é a sua AppKey, e o Client Secret é o seu AppSecret do console de desenvolvedor do DingTalk.

O stream cai / laços de reconexão

Causa: instabilidade de rede, manutenção da plataforma DingTalk ou problema de credencial.

Solução: o adaptador reconecta sozinho com recuo exponencial (2s → 5s → 10s → 30s → 60s). Confira se as suas credenciais são válidas e se o seu app não foi desativado. Verifique se a sua rede permite conexões WebSocket de saída.

O bot está offline

Causa: o gateway do Hermes não está rodando, ou não conseguiu conectar.

Solução: confira se o hermes gateway está rodando. Olhe a saída do terminal atrás de mensagens de erro. Problemas comuns: credenciais erradas, app desativado, dingtalk-stream ou httpx não instalados.

"No session_webhook available"

Causa: o bot tentou responder mas não tem uma URL de webhook de sessão. Isso costuma acontecer quando o webhook expirou ou o bot foi reiniciado entre receber a mensagem e enviar a resposta.

Solução: mande uma mensagem nova para o bot — cada mensagem que chega fornece um webhook de sessão novo para as respostas. Essa é uma limitação normal do DingTalk; o bot só consegue responder a mensagens que recebeu há pouco.

Segurança

aviso

Sempre defina DINGTALK_ALLOWED_USERS para restringir quem pode interagir com o bot. Sem isso, o gateway nega todos os usuários por padrão, por segurança. Só acrescente User IDs de pessoas em quem você confia — usuários autorizados têm acesso total às capacidades do agente, incluindo uso de ferramentas e acesso ao sistema.

Para mais informações sobre proteger a sua implantação do Hermes Agent, veja o guia de segurança.

Observações

• Stream Mode: não precisa de URL pública, nome de domínio nem servidor de webhook. A conexão é iniciada pela sua máquina por WebSocket, então funciona atrás de NAT e de firewalls.
• AI Cards: opcionalmente, responda com AI Cards ricos em vez de markdown simples. Configure via card_template_id.
• Reações com emoji: reações 🤔Thinking/🥳Done automáticas para o estado do processamento.
• Respostas em markdown: as respostas são formatadas no markdown do DingTalk, para exibição com texto rico.
• Suporte a mídia: imagens e arquivos das mensagens que chegam são resolvidos automaticamente e podem ser processados pelas ferramentas de visão.
• Deduplicação de mensagens: o adaptador deduplica mensagens numa janela de 5 minutos, para não processar a mesma mensagem duas vezes.
• Reconexão automática: se a conexão do stream cai, o adaptador reconecta sozinho, com recuo exponencial.
• Limite de tamanho da mensagem: as respostas são limitadas a 20.000 caracteres por mensagem. Respostas maiores são truncadas.

---