Documentação oficial desta página · v0.20.6

Slack

Configuração do Slack

Conecte o Hermes Agent ao Slack como um bot, usando o Socket Mode. O Socket Mode usa WebSockets em vez de endpoints HTTP públicos, então a sua instância do Hermes não precisa estar acessível pela internet — funciona atrás de firewalls, no seu notebook ou num servidor privado.

Aplicativos clássicos do Slack foram descontinuados

Os aplicativos clássicos do Slack (que usam a RTM API) foram totalmente descontinuados em março de 2025. O Hermes usa o SDK Bolt moderno com Socket Mode. Se você tem um app clássico antigo, precisa criar um novo seguindo os passos abaixo.

Visão geral

Componente	Valor
Biblioteca	`slack-bolt` / `slack_sdk` para Python (Socket Mode)
Conexão	WebSocket — nenhuma URL pública necessária
Tokens de autenticação necessários	Bot Token (`xoxb-`) + App-Level Token (`xapp-`)
Identificação de usuário	Member IDs do Slack (por exemplo, `U01ABC2DEF3`)

Passo 1: crie um app do Slack

O caminho mais rápido é colar um manifesto que o Hermes gera para você. Ele declara todo comando de barra embutido (/btw, /stop, /model, …), todo escopo OAuth necessário, toda assinatura de evento, e ainda habilita o Socket Mode — tudo de uma vez.

Opção A: a partir de um manifesto gerado pelo Hermes (recomendado)

Gere o manifesto. Apps novos do Slack precisam usar a visão de Agente:
```
hermes slack manifest --agent-view --write
```
Isso escreve ~/.hermes/slack-manifest.json e imprime as instruções de colagem. Apps existentes que ainda usam a visão de Assistente antiga do Slack podem omitir --agent-view até estarem prontos para migrar.

Para preencher a descrição longa do app no Slack a partir de um arquivo de texto UTF-8 ou Markdown existente, adicione --long-description-file:
```
hermes slack manifest --agent-view \
  --long-description-file AGENTS.md --write
```
O conteúdo do arquivo é preservado exatamente, dentro da faixa de 175 a 4.000 caracteres do Slack. Use --long-description "..." para texto em linha; as opções de texto em linha e de arquivo são mutuamente exclusivas e não podem ser combinadas com --slashes-only.
Vá em https://api.slack.com/apps → Create New App → From an app manifest
Escolha o seu espaço de trabalho, cole o conteúdo JSON, revise e clique em Next → Create
Pule direto para o Passo 6: instale o app no espaço de trabalho. O manifesto já cuidou dos escopos, dos eventos e dos comandos de barra.

Opção B: do zero (manual)

Vá em https://api.slack.com/apps
Clique em Create New App
Escolha From scratch
Digite um nome de app (por exemplo, "Hermes Agent") e selecione o seu espaço de trabalho
Clique em Create App

Você vai cair na página Basic Information do app. Siga com os passos 2 a 6 abaixo.

Passo 2: configure os escopos do Bot Token

Vá em Features → OAuth & Permissions na barra lateral. Role até Scopes → Bot Token Scopes e adicione o seguinte:

Escopo	Para que serve
`chat:write`	Enviar mensagens como o bot
`app_mentions:read`	Detectar quando é mencionado com @ em canais
`channels:history`	Ler mensagens nos canais públicos em que o bot está
`channels:read`	Listar e obter informações sobre canais públicos
`groups:history`	Ler mensagens nos canais privados para os quais o bot foi convidado
`im:history`	Ler o histórico de mensagens diretas
`im:read`	Ver informações básicas de mensagens diretas
`im:write`	Abrir e gerenciar mensagens diretas
`mpim:history`	Ler o histórico de mensagens diretas em grupo (com várias pessoas)
`mpim:read`	Ver informações básicas de mensagens diretas em grupo
`users:read`	Consultar informações de usuário
`files:read`	Ler e baixar arquivos anexados, inclusive notas de voz e áudio
`files:write`	Enviar arquivos (imagens, áudio, documentos)

Escopos faltando = recursos faltando

Sem channels:history e groups:history, o bot não vai receber mensagens em canais — ele só vai funcionar em mensagens diretas. Sem files:read, o Hermes conversa, mas não consegue ler de forma confiável os anexos enviados pelos usuários. Esses são os escopos mais esquecidos.

Escopos opcionais:

Escopo Para que serve

groups:read Listar e obter informações sobre canais privados

assistant:write Mostrar a linha de status de trabalho ("is thinking…") ao lado do nome do bot enquanto ele processa uma mensagem. Sem esse escopo, a chamada assistant.threads.setStatus falha silenciosamente e o Slack exibe os próprios textos genéricos rotativos ("Finding answers…", "Reviewing findings…", …) — o Hermes nunca controla esse texto. Necessário para que typing_status_text tenha algum efeito visível.

Escopo	Para que serve
`groups:read`	Listar e obter informações sobre canais privados
`assistant:write`	Mostrar a linha de status de trabalho ("is thinking…") ao lado do nome do bot enquanto ele processa uma mensagem. Sem esse escopo, a chamada `assistant.threads.setStatus` falha silenciosamente e o Slack exibe os próprios textos genéricos rotativos ("Finding answers…", "Reviewing findings…", …) — o Hermes nunca controla esse texto. Necessário para que `typing_status_text` tenha algum efeito visível.

Passo 3: habilite o Socket Mode

O Socket Mode permite que o bot se conecte por WebSocket, em vez de exigir uma URL pública.

Na barra lateral, vá em Settings → Socket Mode
Ligue Enable Socket Mode
Você vai ser levado a criar um App-Level Token:
- Dê um nome como hermes-socket (o nome não importa)
- Adicione o escopo connections:write
- Clique em Generate
Copie o token — ele começa com xapp-. Esse é o seu SLACK_APP_TOKEN

dica

Você sempre pode achar ou gerar de novo os tokens de nível de app em Settings → Basic Information → App-Level Tokens.

Este passo é crítico — é ele que controla quais mensagens o bot consegue ver.

Na barra lateral, vá em Features → Event Subscriptions
Ligue Enable Events
Expanda Subscribe to bot events e adicione:

Evento	Obrigatório?	Para que serve
`message.im`	Sim	O bot recebe mensagens diretas
`message.mpim`	Sim	O bot recebe mensagens em mensagens diretas em grupo (com várias pessoas) em que foi adicionado
`message.channels`	Sim	O bot recebe mensagens nos canais públicos em que foi adicionado
`message.groups`	Recomendado	O bot recebe mensagens nos canais privados para os quais foi convidado
`app_mention`	Sim	Evita erros do SDK Bolt quando o bot é mencionado com @

Clique em Save Changes no fim da página

Faltar assinatura de evento é o problema de configuração nº 1

Se o bot funciona nas mensagens diretas mas não nos canais, é quase certo que você esqueceu de adicionar message.channels (para canais públicos) e/ou message.groups (para canais privados). Sem esses eventos, o Slack simplesmente nunca entrega as mensagens de canal ao bot.

Passo 5: habilite a aba Messages

Este passo libera as mensagens diretas para o bot. Sem ele, os usuários veem "Sending messages to this app has been turned off" ao tentar mandar mensagem direta para o bot.

Na barra lateral, vá em Features → App Home
Role até Show Tabs
Ligue a Messages Tab
Marque "Allow users to send Slash commands and messages from the messages tab"

Sem este passo, as mensagens diretas ficam totalmente bloqueadas

Mesmo com todos os escopos e assinaturas de evento corretos, o Slack não vai permitir que os usuários mandem mensagens diretas para o bot enquanto a aba Messages não estiver habilitada. Isso é uma exigência da plataforma Slack, não um problema de configuração do Hermes.

Passo 6: instale o app no espaço de trabalho

Na barra lateral, vá em Settings → Install App
Clique em Install to Workspace
Revise as permissões e clique em Allow
Depois da autorização, você vai ver um Bot User OAuth Token começando com xoxb-
Copie esse token — ele é o seu SLACK_BOT_TOKEN

dica

Se você mudar escopos ou assinaturas de evento depois, precisa reinstalar o app para que as mudanças tenham efeito. A página Install App vai mostrar um aviso pedindo isso.

Passo 7: encontre os IDs de usuário para a lista de permissão

O Hermes usa os Member IDs do Slack (não os nomes de usuário nem os nomes de exibição) na lista de permissão.

Para achar um Member ID:

No Slack, clique no nome ou no avatar do usuário
Clique em View full profile
Clique no botão ⋮ (mais)
Escolha Copy member ID

Os Member IDs se parecem com U01ABC2DEF3. No mínimo, você precisa do seu próprio Member ID.

Passo 8: configure o Hermes

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

# Obrigatório
SLACK_BOT_TOKEN=xoxb-seu-token-de-bot-aqui
SLACK_APP_TOKEN=xapp-seu-token-de-app-aqui
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Member IDs separados por vírgula

# Opcional
SLACK_HOME_CHANNEL=C01234567890              # Canal padrão para mensagens agendadas/cron
SLACK_HOME_CHANNEL_NAME=general              # Nome legível do canal principal (opcional)

Ou rode a configuração interativa:

hermes gateway setup    # Escolha Slack quando for perguntado

Depois inicie o gateway:

hermes gateway              # Em primeiro plano
hermes gateway install      # Instala como serviço de usuário
sudo hermes gateway install --system   # Só no Linux: serviço de sistema que sobe no boot

Cuidado com o esforço de raciocínio no Codex

Em canais de agentes pares do Slack movidos pelo Codex, prefira agent.reasoning_effort: high ou menos. O xhigh pode gastar o turno inteiro em raciocínio oculto e nunca produzir texto visível do assistente; o Hermes agora suprime esses avisos de turno incompleto na discussão e mantém o diagnóstico nos logs do gateway.

Passo 9: convide o bot para os canais

Depois de iniciar o gateway, você precisa convidar o bot para todo canal em que quer que ele responda:

/invite @Hermes Agent

O bot não entra em canais sozinho. Você precisa convidá-lo para cada canal individualmente.

Comandos de barra

Todo comando do Hermes (/btw, /stop, /new, /model, /help, ...) é um comando de barra nativo do Slack — exatamente como funcionam no Telegram e no Discord. Digite / no Slack e o seletor de autocompletar lista todo comando do Hermes com a descrição dele.

Por baixo do capô: o Hermes já traz um manifesto de app do Slack gerado (veja o Passo 1, Opção A) que declara como comando de barra todo comando de COMMAND_REGISTRY. No Socket Mode, o Slack encaminha o evento do comando pelo WebSocket, independentemente do campo url do manifesto.

Experiência de mensagens de Agente

Apps novos do Slack usam a experiência de mensagens de Agente do Slack. Apps Hermes existentes que usam Assistente podem migrar gerando o manifesto de novo com --agent-view:

hermes slack manifest --agent-view --write

Atualize o manifesto em Features → App Manifest e depois reinstale o app, se o Slack pedir. A visão de Agente não pode voltar para a visão de Assistente, e os usuários podem precisar recarregar o Slack à força depois da troca. O manifesto de Agente gerado assina message.im, app_home_opened e app_context_changed, para que o Hermes identifique uma mensagem direta na aba Messages e receba o contexto ativo do Slack do usuário junto com o turno. O Hermes só usa esse contexto como rótulo; ele não lê o histórico do canal que está sendo visto.

Atualizar os comandos de barra depois de atualizações

Quando o Hermes ganha comandos novos (por exemplo, depois de hermes update), gere o manifesto de novo e atualize o seu app do Slack:

hermes slack manifest --write

Depois, no Slack:

Abra https://api.slack.com/apps → o seu app do Hermes
Features → App Manifest → Edit
Cole o novo conteúdo de ~/.hermes/slack-manifest.json
Save. O Slack vai pedir a reinstalação do app se os escopos ou os comandos de barra mudaram.

O antigo `/hermes <subcomando>` continua funcionando

Por compatibilidade com manifestos mais antigos, você ainda pode digitar /hermes btw rode os testes — o Hermes encaminha isso do mesmo jeito que /btw rode os testes. Perguntas livres também funcionam: /hermes como está o tempo? é tratado como uma mensagem comum.

Usar comandos dentro de discussões (o prefixo `!cmd`)

O próprio Slack bloqueia comandos de barra nativos dentro de respostas em discussão — tente /queue numa discussão e o Slack responde "/queue is not supported in threads. Sorry!". Não existe configuração do lado do app que os reabilite; o Slack nunca os entrega ao Hermes.

Como alternativa, o Hermes reconhece um ! inicial como prefixo alternativo de comando, que funciona em discussões (e em qualquer outro lugar). Digite !queue, !stop, !model gpt-5.4 etc. como uma resposta comum na discussão — o Hermes trata igual à forma com barra e responde na mesma discussão.

Só o primeiro token é comparado com a lista de comandos conhecidos, então mensagens casuais como !nice work passam para o agente sem alteração. A forma com exclamação também funciona atrás de uma menção (@Hermes !stop) e com espaço em branco no começo — as duas são despachadas como comandos em discussões.

Os pedidos de aprovação (comando perigoso / aprovação de execute_code) normalmente aparecem como botões interativos. Quando não é possível entregar os botões e o Hermes recorre a um pedido em texto, o texto instrui você a responder com !approve / !deny — a forma que funciona dentro de discussões.

As respostas a comandos de barra são efêmeras

As respostas a um comando de barra nativo (por exemplo, /status, /help) são entregues de forma efêmera — "Only visible to you" — para que a saída de comando nunca lote o canal. O texto provisório "Running /cmd…" é substituído pela resposta real; respostas longas são fatiadas em mensagens efêmeras de acompanhamento. O Slack limita o fluxo de resposta a 5 publicações, então uma saída muito longa é encerrada com um aviso explícito de truncamento, em vez de ser descartada em silêncio. Se o caminho efêmero principal falha, o Hermes tenta de novo por um segundo caminho efêmero da API — uma resposta de comando de barra nunca é publicada no canal de forma pública como plano B. (Comandos digitados como mensagens comuns — !cmd em discussões, @Hermes /cmd — respondem como mensagens visíveis normais.)

Pedidos de esclarecimento (botões de um toque)

Quando o agente precisa fazer uma pergunta de múltipla escolha (a ferramenta clarify), o Slack a exibe como botões do Block Kit — um toque por opção, mais um botão "✏️ Other…" que muda para o modo de texto livre (a sua próxima mensagem digitada vira a resposta). Depois do toque, a mensagem se atualiza no lugar para mostrar quem respondeu e o que foi escolhido; cliques seguintes no mesmo pedido são ignorados. Os cliques em botão respeitam a mesma autorização de usuário das mensagens, e pedidos expirados (reinício do gateway, tempo esgotado) avisam você a perguntar de novo, em vez de engolir o clique em silêncio. Perguntas de esclarecimento abertas aparecem como uma pergunta simples e aceitam a sua próxima resposta digitada. Nenhuma configuração é necessária — isso funciona independentemente da opção rich_blocks.

Avançado: emitir só o array de comandos de barra

Se você mantém o manifesto do Slack à mão e só quer a lista de comandos de barra:

hermes slack manifest --slashes-only > /tmp/slashes.json

Cole esse array na chave features.slash_commands do seu manifesto existente.

Como o bot responde

Entendendo como o Hermes se comporta em contextos diferentes:

Contexto	Comportamento
Mensagens diretas	O bot responde a toda mensagem — sem precisar de menção com @
Canais	O bot só responde quando é mencionado com @ (por exemplo, `@Hermes Agent que horas são?`). Em canais, o Hermes responde numa discussão anexada àquela mensagem.
Discussões	Se você mencionar o Hermes com @ dentro de uma discussão existente, ele responde nessa mesma discussão. Depois que o bot tem uma sessão ativa numa discussão, as respostas seguintes nessa discussão não precisam de menção com @ — o bot acompanha a conversa naturalmente.

dica

Em canais, sempre mencione o bot com @ para iniciar uma conversa. Depois que o bot está ativo numa discussão, você pode responder nela sem mencioná-lo. Fora das discussões, mensagens sem menção com @ são ignoradas, para evitar ruído em canais movimentados.

Opções de configuração

Além das variáveis de ambiente obrigatórias do Passo 8, você pode personalizar o comportamento do bot do Slack pelo ~/.hermes/config.yaml.

Comportamento de discussão e resposta

platforms:
  slack:
    # Controla como as respostas de várias partes vão para a discussão
    # "off"   — nunca coloca a resposta em discussão na mensagem original
    # "first" — o primeiro pedaço vai em discussão na mensagem do usuário (padrão)
    # "all"   — todos os pedaços vão em discussão na mensagem do usuário
    reply_to_mode: "first"

    extra:
      # Se deve responder em discussão (padrão: true).
      # Quando false, as mensagens de canal recebem respostas diretas no canal,
      # em vez de discussões. Mensagens dentro de discussões existentes continuam
      # respondendo na discussão.
      reply_in_thread: true

      # Também publica as respostas de discussão no canal principal
      # (recurso "Also send to channel" do Slack).
      # Só o primeiro pedaço da primeira resposta é transmitido.
      reply_broadcast: false

      # Controla os cartões automáticos de pré-visualização de link do Slack sem
      # mudar nem remover os links clicáveis do texto da mensagem. Omita qualquer
      # uma das chaves para manter o comportamento padrão do Slack para aquele tipo
      # de pré-visualização.
      unfurl_links: false
      unfurl_media: false

      # Renderiza as mensagens do agente como blocos do Slack Block Kit (padrão: false).
      # Quando true, a mensagem final do agente é enviada com blocos estruturados —
      # cabeçalhos de seção, divisores, listas aninhadas de verdade (via rich_text) e
      # tabelas nativas do Block Kit — em vez de texto mrkdwn plano. Um texto simples
      # de reserva é sempre enviado junto, para notificações e acessibilidade.
      # Tabelas que passam dos limites do Slack (100 linhas / 20 colunas / 10 mil
      # caracteres) caem com elegância para monoespaçado alinhado.
      rich_blocks: false

      # Acrescenta controles nativos de retorno do Slack às respostas finais em Block Kit.
      # Exige rich_blocks: true. Padrão: false.
      feedback_buttons: false

      # Renderiza as chamadas de ferramenta ao vivo como cartões nativos de plano/tarefa
      # do Slack. Essa habilitação explícita liga o progresso nativo mesmo quando o
      # tool_progress em texto está desligado. Se o Slack rejeitar o fluxo nativo, o
      # Hermes mantém um único texto de reserva editável atualizado pelo resto do turno.
      native_task_cards: false

      # Prompts sugeridos fixados no topo da aba Messages da visão de Agente.
      # Uma lista de linhas {title, message} ou um objeto com título:
      # {title: "Comece aqui", prompts: [{title: "Plano", message: "..."}]}
      suggested_prompts: []

      # Dá título às discussões de mensagem direta de Agente/Assistente a partir da
      # primeira mensagem do usuário. Padrão: true. Use false para manter os títulos
      # padrão de discussão do Slack.
      assistant_thread_titles: true

      # Aceita mensagens publicadas por outros bots do Slack (padrão: "none").
      # "none" ignora os bots, "mentions" aceita a mensagem de um bot só quando
      # aquela mensagem menciona o Hermes com @, e "all" aceita todos os outros
      # bots. O Hermes sempre ignora o próprio usuário de bot, para evitar
      # eco de si mesmo.
      allow_bots: "none"

      # Superfície de entrega do cron continuável (padrão: "thread").
      # "in_channel" entrega uma tarefa de cron continuável DIRETO no canal
      # (sem discussão dedicada); combine com reply_in_thread: false (e
      # require_mention: false) para que uma resposta simples continue a tarefa.
      # Veja o guia de cron → "Continuação direta no canal".
      cron_continuable_surface: thread

Chave	Padrão	Descrição
`platforms.slack.reply_to_mode`	`"first"`	Modo de discussão para mensagens de várias partes: `"off"`, `"first"` ou `"all"`
`platforms.slack.extra.reply_in_thread`	`true`	Quando `false`, as mensagens de canal recebem respostas diretas em vez de discussões. Mensagens dentro de discussões existentes continuam respondendo na discussão.
`platforms.slack.extra.reply_broadcast`	`false`	Quando `true`, as respostas em discussão também são publicadas no canal principal. Só o primeiro pedaço é transmitido.
`platforms.slack.extra.unfurl_links`	Padrão do Slack	Defina como `false` para suprimir as pré-visualizações automáticas de páginas web vinculadas, mantendo os links clicáveis. Quando qualquer uma das chaves de pré-visualização é definida, as legendas de mídia são publicadas como mensagem separada antes do arquivo (a API de upload do Slack não carrega controles de pré-visualização), e o fluxo nativo de rascunho cai para a entrega baseada em edição.
`platforms.slack.extra.unfurl_media`	Padrão do Slack	Defina como `false` para suprimir as pré-visualizações automáticas de mídia, mantendo os links clicáveis. Valem as mesmas observações de ordem de legenda e de fluxo do `unfurl_links`.
`platforms.slack.extra.rich_blocks`	`false`	Quando `true`, as mensagens do agente são renderizadas como blocos do Block Kit (cabeçalhos, divisores, listas aninhadas de verdade e tabelas nativas). Um texto simples de reserva é sempre enviado. Tabelas acima dos limites do Slack caem para monoespaçado alinhado. Não exige reinstalar o app — é uma mudança só do lado do envio.
`platforms.slack.extra.feedback_buttons`	`false`	Quando `true` junto com `rich_blocks`, acrescenta controles nativos de retorno do Slack às respostas finais.
`platforms.slack.extra.native_task_cards`	`false`	Quando `true`, renderiza as chamadas de ferramenta ao vivo como cartões nativos de plano/tarefa do Slack. É uma habilitação explícita de progresso, independente do padrão `tool_progress: off` do Slack; falhas da API nativa caem para uma única atualização de texto editada continuamente.
`platforms.slack.extra.suggested_prompts`	`[]`	Até quatro prompts `{title, message}` para os pontos de entrada de mensagem direta de Agente/Assistente; aceita uma lista ou `{title, prompts}`.
`platforms.slack.extra.assistant_thread_titles`	`true`	Quando `true`, nomeia as discussões de mensagem direta de Agente/Assistente a partir da primeira mensagem do usuário.
`platforms.slack.extra.allow_bots`	`"none"`	Controla as mensagens de outros bots do Slack: `"none"` as ignora, `"mentions"` aceita a mensagem de um bot só quando aquela mensagem menciona o Hermes com @, e `"all"` aceita todas. Use `"mentions"` para o modo mais seguro de colaboração entre bots. Veja Aceitar mensagens de outros bots.
`platforms.slack.extra.cron_continuable_surface`	`"thread"`	Superfície de entrega das tarefas de cron continuáveis. `"thread"` abre uma discussão dedicada por entrega (padrão); `"in_channel"` entrega direto na linha do tempo do canal. Combine `in_channel` com `reply_in_thread: false` (e `require_mention: false`) para que uma resposta simples no canal continue a tarefa.

A variável de ambiente equivalente é SLACK_ALLOW_BOTS=none|mentions|all. Quando as duas estão definidas, platforms.slack.extra.allow_bots tem precedência. Evite all quando bots pares conseguem responder uns aos outros sem menção explícita, porque as políticas de resposta deles ainda podem criar laços.

Linha de status de trabalho

Enquanto o agente processa uma mensagem, o Slack mostra uma linha de status ao lado do nome do bot na discussão. Por padrão, o Hermes a define como is thinking...; personalize com typing_status_text — por exemplo, uma assistente gatinha chamada Ada:

platforms:
  slack:
    # Linha de status de trabalho personalizada (padrão: "is thinking...").
    typing_status_text: "is pouncing… 🐾"

Chave	Padrão	Descrição
`platforms.slack.typing_status_text`	`"is thinking..."`	Texto da linha de status de trabalho mostrada enquanto o agente processa uma mensagem. Exige o escopo `assistant:write` — sem ele, a chamada de status falha silenciosamente e o Slack exibe o próprio texto genérico, seja qual for o valor definido aqui. Defina `typing_indicator: false` para desligar a linha de status por completo.

Onde o status aparece

O status personalizado aparece no rodapé abaixo do campo de resposta ("NomeDoBot is thinking…"), não em linha na lista de mensagens. As linhas "Generating response…" / "Finding answers…" que o Slack mostra na área de mensagens enquanto um app de IA trabalha são indicadores rotativos do próprio Slack — o assistant.threads.setStatus não controla esses, e os dois podem aparecer ao mesmo tempo.

A mesma chave personaliza a mensagem visível de marcação de estado de trabalho do Google Chat (platforms.google_chat.typing_status_text, padrão "Hermes is thinking…") — note que, no Google Chat, ela é uma mensagem publicada de verdade, que depois é alterada para virar a resposta, e não um status efêmero.

Status ao vivo (por ferramenta)

Por padrão, a linha de status se atualiza ao vivo, conforme o agente trabalha: em vez de um is thinking... estático, ela mostra o que o agente está fazendo agora — is running pytest tests/…, is reading docs/api.md…, is searching the web for slack api limits…. Entre chamadas de ferramenta, ela volta ao texto estático. Isso aproveita a cadência de atualização de status que já existe, então não faz nenhuma chamada extra à API do Slack, e funciona mesmo com tool_progress: off (o padrão do Slack) — diferente das bolhas de progresso, a linha de status é efêmera e não deixa nada para trás no canal.

Controle com display.live_status (global ou por plataforma):

display:
  platforms:
    slack:
      # full = verbo + argumento ("is running pytest…")   [padrão]
      # verb = só o verbo ("is running…") — esconde comandos e caminhos,
      #        útil em canais compartilhados ou voltados ao cliente
      # off  = texto estático (typing_status_text ou "is thinking...")
      live_status: full

Chave	Padrão	Descrição
`display.live_status`	`"full"`	Linha de status ao vivo por ferramenta. `full` mostra o verbo + uma prévia do argumento; `verb` mostra só o verbo (mantém caminhos de arquivo e comandos fora dos canais compartilhados); `off` restaura o texto estático. Exige o escopo `assistant:write`, igual à linha de status estática.

Fluxo nativo (respostas digitadas ao vivo)

O recurso Agents & AI Apps do Slack traz uma superfície nativa de fluxo (chat.startStream / chat.appendStream / chat.stopStream) que exibe a resposta como uma mensagem digitada ao vivo — muito mais suave que as atualizações progressivas por edição usadas nos outros casos. Quando streaming.enabled está ligado (transporte auto ou draft), o Hermes usa o fluxo nativo automaticamente onde ele está disponível:

O fluxo começa no primeiro quadro e só acrescenta deltas (a API só permite acrescentar). A mensagem transmitida é a mensagem final — o Hermes a sela com chat.stopStream em vez de publicar uma resposta final duplicada.
Se o seu app do Slack não tem os recursos de IA habilitados (ou não tem o escopo assistant:write), a primeira falha é guardada em cache e o Hermes volta ao fluxo por edição, com um único aviso de log dizendo qual é a correção.
O Block Kit de habilitação explícita (rich_blocks: true) é aplicado à mensagem selada, igual ao caminho de finalização por edição.

Nenhuma configuração extra é necessária além de habilitar o fluxo:

streaming:
  enabled: true       # o transporte auto/draft acende o fluxo nativo do Slack

Cartões nativos de tarefa (progresso de ferramenta ao vivo)

Com platforms.slack.extra.native_task_cards: true, as chamadas de ferramenta ao vivo aparecem como cartões nativos de plano/tarefa do Slack (a mesma interface que os próprios recursos de IA do Slack usam), em vez de bolhas de progresso em texto: um cartão por turno, uma linha por chamada de ferramenta, com os estados de execução/conclusão/erro de cada tarefa se atualizando no lugar.

platforms:
  slack:
    extra:
      native_task_cards: true

É uma habilitação explícita de progresso — funciona mesmo com o padrão do Slack sendo tool_progress: off (as bolhas de texto lotam canais; os cartões nativos não).
Chamadas concorrentes à mesma ferramenta são correlacionadas pelo ID real da chamada, então chamadas paralelas de web_search recebem cada uma a própria linha, com o status certo.
Se o fluxo nativo não consegue começar ou se atualizar, o Hermes volta para uma única mensagem de texto editada continuamente, para que o progresso siga ao vivo no turno.
O fluxo de cartões é encerrado exatamente uma vez quando o turno termina, inclusive em caso de interrupção ou desconexão, então nenhum indicador ao vivo fica pendurado.

Isolamento de sessão

# Configuração global — vale para o Slack e para todas as outras plataformas
group_sessions_per_user: true

Quando true (o padrão), cada usuário de um canal compartilhado ganha a própria sessão de conversa isolada. Duas pessoas falando com o Hermes no #general vão ter históricos e contextos separados.

Defina como false se quiser um modo colaborativo em que o canal inteiro compartilha uma única sessão de conversa. Saiba que isso significa que os usuários compartilham o crescimento de contexto e o custo em tokens, e que o /reset de um usuário limpa a sessão de todo mundo.

Comportamento de menção e gatilho

slack:
  # Exige menção com @ nos canais (este é o comportamento padrão;
  # o adaptador do Slack aplica o travamento por menção nos canais de
  # qualquer jeito, mas você pode definir explicitamente, por consistência
  # com as outras plataformas)
  require_mention: true

  # Evita o engajamento automático em discussões: só responde às mensagens de
  # canal que contêm uma menção com @ explícita. Com isso DESLIGADO (padrão), o
  # Slack pode "se engajar sozinho" — lembrando menções passadas numa discussão,
  # dando sequência a respostas de mensagens do bot e retomando sessões ativas
  # sem uma menção nova. Com strict_mention LIGADO, toda mensagem nova de canal
  # precisa mencionar o bot com @ antes que o Hermes responda.
  strict_mention: false

  # Ignora mensagens dirigidas a outro usuário: quando uma mensagem de canal ou
  # discussão *começa* mencionando com @ alguém que não é o bot (por exemplo,
  # "@rasha você pega essa?"), fica em silêncio, a menos que o bot também seja
  # mencionado. Só uma menção *inicial* conta como "dirigida a" — uma mensagem
  # que cita alguém no meio da frase ("chama a @rasha") ainda chega ao bot.
  # Sobrepõe free_response_channels e o engajamento automático em discussão.
  # Habilitação explícita; desligado por padrão. Env: SLACK_IGNORE_OTHER_USER_MENTIONS.
  ignore_other_user_mentions: false

  # Exige menção com @ explícita nas respostas em DISCUSSÃO, deixando as
  # mensagens de canal de nível superior governadas por require_mention /
  # free_response_channels. Mais estreito que strict_mention: use quando um bot
  # de resposta livre não deve entrar em todo acompanhamento de discussões
  # movimentadas. Habilitação explícita; desligado por padrão. Env: SLACK_THREAD_REQUIRE_MENTION.
  thread_require_mention: false

  # Sobrescrita de menção obrigatória por canal — a direção oposta de
  # free_response_channels. Os canais listados aqui SEMPRE exigem uma menção
  # com @ explícita, mesmo quando require_mention é false globalmente.
  # As conversas em andamento continuam sendo acompanhadas automaticamente
  # (discussões com menção, sessões ativas, discussões criadas pelo bot).
  # IDs separados por vírgula ou uma lista.
  # Env: SLACK_REQUIRE_MENTION_CHANNELS.
  require_mention_channels: ""

  # Padrões de menção personalizados que acionam o bot
  # (além da detecção padrão de menção com @)
  mention_patterns:
    - "e aí hermes"
    - "hermes,"

  # Texto colocado no início de toda mensagem de saída
  reply_prefix: ""

Quando usar strict_mention

Defina como true em espaços de trabalho movimentados, onde o comportamento padrão do Slack de "o bot se lembra desta discussão" surpreende os usuários — por exemplo, uma longa discussão de suporte técnico em que o bot ajudou no começo e você prefere que ele fique em silêncio até ser chamado de novo explicitamente. Mensagens diretas e sessões interativas ativas não são afetadas.

Quando usar ignore_other_user_mentions

Defina como true quando o bot acompanha discussões movimentadas (por engajamento automático em discussão ou por free_response_channels) e se intromete em mensagens que as pessoas dirigem umas às outras. É uma ferramenta mais estreita que o strict_mention: acompanhamentos simples numa discussão engajada continuam recebendo resposta; só as mensagens que começam mencionando outra pessoa com @ são puladas. Mensagens diretas 1 para 1 não são afetadas; mensagens diretas em grupo (MPIMs) e canais aplicam a regra, seguindo a política de superfícies compartilhadas descrita abaixo. Tokens de transmissão (@here, @channel) e referências a canal se dirigem à sala, não a uma pessoa, então nunca são pulados.

informação

O Slack suporta os dois padrões: por padrão, é preciso @mencionar para iniciar uma conversa, mas você pode isentar canais específicos com SLACK_FREE_RESPONSE_CHANNELS (IDs de canal separados por vírgula) ou com slack.free_response_channels no config.yaml. Depois que o bot tem uma sessão ativa numa discussão, as respostas seguintes na discussão não precisam de menção. Em mensagens diretas 1 para 1, o bot sempre responde sem precisar de menção.

Mensagens diretas em grupo (MPIMs) são superfícies compartilhadas, não mensagens diretas 1 para 1

Uma mensagem direta 1 para 1 é uma conversa privada com uma pessoa, então é isenta de menção. Uma mensagem direta em grupo (MPIM, com várias pessoas) é uma superfície compartilhada — várias pessoas podem ver e acionar o bot —, então ela obedece aos mesmos controles de operação de um canal: require_mention, strict_mention, free_response_channels e allowed_channels valem todos, e o bot só adiciona as reações :eyes:/:white_check_mark: quando é de fato @mencionado. Para deixar o bot responder livremente numa mensagem direta em grupo específica, adicione o ID de canal dela (que começa com G) a free_response_channels.

Qual opção de menção eu quero?

As opções de travamento se combinam — cada uma responde a uma pergunta diferente:

Opção	Pergunta que ela responde	Padrão	Escopo
`require_mention`	As mensagens de canal de nível superior precisam de menção com @?	`true`	Todos os canais
`free_response_channels`	Quais canais estão isentos de `require_mention`?	nenhum	Canais listados
`require_mention_channels`	Quais canais SEMPRE precisam de menção com @, mesmo quando `require_mention` é `false` ou o canal é de resposta livre? Vence os dois.	nenhum	Canais listados
`thread_require_mention`	As respostas em discussão precisam de menção com @, mesmo quando as mensagens de nível superior não precisam? Discussões com menção não são lembradas.	`false`	Só discussões
`strict_mention`	Toda mensagem de canal (de nível superior e de discussão) precisa de uma menção com @ nova? Desliga todo acompanhamento automático: memória de discussão mencionada, sequência a respostas do bot, retomada de sessão ativa.	`false`	Todos os canais + discussões
`ignore_other_user_mentions`	Uma mensagem que começa mencionando outra pessoa com @ (`@rasha você pega essa?`) deve ser pulada? Sobrepõe a resposta livre e o acompanhamento automático em discussão; referências no meio da frase ainda chegam ao bot.	`false`	Canais + mensagens diretas em grupo

Regras práticas: strict_mention é o martelo mais amplo; thread_require_mention acalma discussões movimentadas sem mexer no travamento de nível superior; require_mention_channels volta a apertar canais individuais num bot que, no geral, é de resposta livre; ignore_other_user_mentions só pula mensagens explicitamente dirigidas a outra pessoa. Mensagens diretas 1 para 1 sempre respondem e não são afetadas por nada disso.

Aceitar mensagens de outros bots (`allow_bots`)

Por padrão, o Hermes ignora toda mensagem escrita por outro bot ou app do Slack (inclusive as publicações do Workflow Builder). Para espaços de trabalho multiagente — várias instâncias do Hermes ou bots pares colaborando num canal —, habilite explicitamente com allow_bots:

platforms:
  slack:
    extra:
      # "none" (padrão) — ignora todas as mensagens escritas por bot/app
      # "mentions"      — aceita a mensagem de um bot só quando AQUELA mensagem
      #                   menciona este bot com @
      # "all"           — aceita toda mensagem de bot (menos as do próprio bot)
      allow_bots: mentions

Equivalente em variável de ambiente: SLACK_ALLOW_BOTS=none|mentions|all (a chave de configuração vence quando as duas estão definidas). Valores desconhecidos são tratados como none.

Como o modo mentions trava:

Uma mensagem de bot par é aceita só quando a própria mensagem contém uma @menção atual deste bot — no texto dela ou nos blocos do Block Kit dela. O histórico da discussão não conta: ter sido mencionado antes na discussão, respostas às mensagens do próprio bot e sessões de discussão ativas não admitem mensagens posteriores de bot par sem menção. Isso é deliberado — é o que quebra os laços de confirmação e status entre agentes.
As mensagens humanas não são afetadas; o travamento normal de menção vale para elas.
O Hermes sempre ignora as próprias mensagens, em todo modo, para evitar laços de eco.

mentions é o modo recomendado para colaboração entre bots: cada agente precisa chamar o outro explicitamente a cada turno. Evite all, a menos que a política de resposta de todo bot par seja segura contra laços — dois bots que respondem a tudo vão responder um ao outro para sempre. A detecção cobre mensagens de bot rotuladas (bot_id, subtype: bot_message), eventos originados de app e usuários de bot sem rótulo (sondados via users.info), então agentes Hermes pares são filtrados de forma consistente entre espaços de trabalho.

Em instalações estritas com vários bots, combine com require_mention: true e strict_mention: true — veja o perfil de verificação rápida abaixo.

Gatilhos por reação (`reaction_triggers`)

Por padrão, as reações com emoji são confirmadas e descartadas — um 👍 numa mensagem do bot não faz nada. Defina slack.reaction_triggers para encaminhar as reações ao laço do agente (exige o escopo reactions:read mais as assinaturas de evento de bot reaction_added/reaction_removed no manifesto do seu app do Slack — gere de novo com hermes slack manifest):

slack:
  # Habilitação explícita. false/ausente (padrão) = reações confirmadas e descartadas.
  # true = qualquer reação NAS PRÓPRIAS MENSAGENS DO BOT vai para o agente.
  reaction_triggers: true
  # Ou uma lista explícita de emojis permitidos — só esses nomes são encaminhados, e
  # podem estar em QUALQUER mensagem (fluxos de passagem por emoji, por exemplo :task: para capturar):
  # reaction_triggers: [white_check_mark, thumbsup, task]
  # Alvo opcional de passagem: responde neste canal (nível superior) ou discussão
  # (C123:<thread_ts>) em vez da discussão da mensagem que recebeu a reação.
  # reaction_trigger_target: C0123456789

Equivalentes em variável de ambiente: SLACK_REACTION_TRIGGERS (true/all ou uma lista separada por vírgula) e SLACK_REACTION_TRIGGER_TARGET.

Comportamento:

A reação chega como um turno normal do agente, com o texto reaction:added:👍 / reaction:removed:👍 (os nomes comuns do Slack são traduzidos para unicode; nomes desconhecidos passam como estão, por exemplo reaction:added:custom-emoji), em discussão sob a mensagem que recebeu a reação, para que o agente veja a que se reagiu e o turno caia na mesma sessão em que cairia uma resposta.
Quem reagiu vira o usuário da mensagem, então a autorização de usuário e o travamento de allowed_channels valem exatamente como nas mensagens digitadas — a reação de um usuário qualquer não pode acionar o agente onde a mensagem dele não poderia.
Com reaction_triggers: true, só as reações nas mensagens do próprio bot são encaminhadas (fluxos de aprovação/confirmação). Com uma lista explícita de emojis permitidos, os emojis listados são encaminhados a partir de qualquer mensagem.
As reações de ciclo de vida do próprio bot (:eyes: etc.) nunca voltam para ele.
Independentemente dessa habilitação, toda reação humana dispara os hooks do gateway reaction:added/reaction:removed para observadores que não precisam de turnos do agente.

Verificação rápida de agentes pares

Em instalações do Slack com vários bots que dependem de menções estritas a cada turno, mantenha o seguinte perfil:

slack:
  require_mention: true
  strict_mention: true
  allow_bots: mentions
  allowed_channels: ""

Depois de mudanças de configuração, implantações ou reinícios do gateway, rode este alvo sintético de verificação rápida:

uv run --frozen pytest -q tests/gateway/test_slack_peer_agent_smoke.py -o addopts=''

Esse alvo usa apenas eventos sintéticos do Slack, no próprio processo. Ele não manda mensagens reais para o Slack e, por padrão, não exige tokens de bot de verdade.

Grupos de falha:

config: o test_peer_agent_smoke_preflight_contract pegou uma divergência de perfil (require_mention, strict_mention, allow_bots ou allowed_channels).
platform_connectivity: o adaptador/cliente não foi inicializado, então a verificação de roteamento ainda não é um sinal confiável.
bot_identity: o adaptador nunca resolveu o ID de usuário do bot, então as verificações de menção na mensagem atual não têm como funcionar.
routing_logic: o adaptador do Slack regrediu em um dos invariantes de agente par (roteamento de menção humana, ignorar bot par, admitir menção explícita de par, ou suprimir confirmações/status/erros passivos).

Se esse alvo passa mas um espaço de trabalho real ainda encaminha mensagens errado, investigue a conectividade de token/espaço de trabalho do Slack e o estado da implantação em execução, fora da lógica de roteamento em si.

Lista de canais permitidos (`allowed_channels`)

Restrinja o bot a um conjunto fixo de canais do Slack — útil quando o bot é convidado para muitos canais mas só deve responder em alguns. Quando definida, as mensagens de canais que NÃO estão na lista são ignoradas em silêncio, mesmo que o bot seja @mencionado.

Mensagens diretas 1 para 1 são isentas desse filtro, então usuários autorizados sempre conseguem falar com o bot numa mensagem direta. Mensagens diretas em grupo (MPIMs) não são isentas — como os canais, uma MPIM precisa estar na lista (o ID dela começa com G) ou as mensagens dela são descartadas.

slack:
  allowed_channels:
    - "C0123456789"   # #ops
    - "C0987654321"   # #resposta-a-incidentes

Ou por variável de ambiente (separada por vírgula):

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

Comportamento:

Vazia / não definida → sem restrição (totalmente compatível com o que já existia).
Não vazia → o ID do canal precisa estar na lista, ou a mensagem é descartada antes que qualquer outro travamento (exigência de menção, free_response_channels etc.) rode.
Os IDs de canal do Slack começam com C (público), G (privado) ou D (mensagem direta). Consulte-os pelo painel "Open channel details" → "About" da interface do Slack, ou pela API.

Veja também: a divisão de comandos de barra entre administrador e usuário.

Tratamento de usuários não autorizados

slack:
  # O que acontece quando um usuário não autorizado (fora de SLACK_ALLOWED_USERS) manda mensagem direta ao bot
  # "pair"   — pede a ele um código de pareamento (padrão)
  # "ignore" — descarta a mensagem em silêncio
  unauthorized_dm_behavior: "pair"

Você também pode definir isso globalmente, para todas as plataformas:

unauthorized_dm_behavior: "pair"

A configuração específica de plataforma, sob slack:, tem precedência sobre a global.

Transcrição de voz

# Configuração global — liga/desliga a transcrição automática das mensagens de voz recebidas
stt_enabled: true

Quando true (o padrão), as mensagens de áudio recebidas são transcritas automaticamente pelo provedor de STT configurado, antes de serem processadas pelo agente.

Exemplo completo

# Configurações globais do gateway
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Configurações específicas do Slack
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Configuração de plataforma
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

Canal principal

Defina SLACK_HOME_CHANNEL com o ID de um canal em que o Hermes vai entregar mensagens agendadas, resultados de tarefas de cron e outras notificações proativas. Para achar um ID de canal:

Clique com o botão direito no nome do canal, no Slack
Clique em View channel details
Role até o fim — o Channel ID aparece ali

SLACK_HOME_CHANNEL=C01234567890

Confirme que o bot foi convidado para o canal (/invite @Hermes Agent).

Direcionamento da entrega de cron

As tarefas de cron (veja o guia de cron) podem mirar o Slack de três jeitos:

Valor de `deliver:`	Onde chega
`slack`	O canal principal (`SLACK_HOME_CHANNEL`)
`slack:C0123456789`	Um canal específico, por ID
`slack:U0123456789`	A mensagem direta daquele usuário — o ID de usuário puro é resolvido automaticamente para uma conversa direta (exige o escopo `im:write`)

A entrega funciona mesmo quando o processo de cron não está junto do gateway — o Hermes recorre a um enviador autônomo pela Web API, usando o SLACK_BOT_TOKEN. Os anexos MEDIA: da saída do cron são enviados como compartilhamentos nativos de arquivo do Slack, para o mesmo alvo.

Enviar mensagens e mídia (`send_message`)

A ferramenta send_message do agente aceita os mesmos formatos de alvo: um ID de canal (C…/G…), uma conversa direta (D…) ou um ID de usuário puro (U…/W…), que é resolvido para a mensagem direta do usuário em todo caminho de envio — texto, mídia e pedidos interativos igualmente. Os anexos MEDIA:<caminho> (imagens, PDFs, documentos) são enviados como compartilhamentos nativos de arquivo; quando uma mensagem curta acompanha um único anexo, ela vai como legenda do arquivo, em vez de uma mensagem separada. Arquivos faltando são relatados como avisos, arquivo por arquivo, em vez de fazer o envio inteiro falhar.

Suporte a vários espaços de trabalho

O Hermes pode se conectar a vários espaços de trabalho do Slack ao mesmo tempo, com uma única instância de gateway. Cada espaço de trabalho é autenticado de forma independente, com o próprio ID de usuário de bot.

Configuração

Forneça vários tokens de bot como uma lista separada por vírgulas em SLACK_BOT_TOKEN:

# Vários tokens de bot — um por espaço de trabalho
SLACK_BOT_TOKEN=xoxb-token-espaco1,xoxb-token-espaco2,xoxb-token-espaco3

# Um único token de nível de app ainda é usado para o Socket Mode
SLACK_APP_TOKEN=xapp-seu-token-de-app

Ou no ~/.hermes/config.yaml:

platforms:
  slack:
    token: "xoxb-token-espaco1,xoxb-token-espaco2"

Arquivo de tokens OAuth

Além dos tokens no ambiente ou na configuração, o Hermes também carrega tokens de um arquivo de tokens OAuth em:

~/.hermes/slack_tokens.json

Esse arquivo é um objeto JSON que mapeia IDs de time para entradas de token:

{
  "T01ABC2DEF3": {
    "token": "xoxb-token-do-espaco-aqui",
    "team_name": "Meu Espaço de Trabalho"
  }
}

Os tokens desse arquivo são combinados com quaisquer tokens vindos de SLACK_BOT_TOKEN. Tokens duplicados são removidos automaticamente.

Como funciona

O primeiro token da lista é o token principal, usado na conexão de Socket Mode (AsyncApp).
Cada token é autenticado por auth.test na inicialização. O gateway mapeia cada team_id ao próprio WebClient e bot_user_id.
Quando chega uma mensagem, o Hermes usa o cliente correto daquele espaço de trabalho para responder.
O bot_user_id principal (do primeiro token) é usado por compatibilidade com recursos que esperam uma única identidade de bot.

Mensagens de voz

O Hermes suporta voz no Slack:

Entrada: as mensagens de voz/áudio são transcritas automaticamente pelo provedor de STT configurado: faster-whisper local, Groq Whisper (GROQ_API_KEY) ou OpenAI Whisper (VOICE_TOOLS_OPENAI_KEY)
Saída: as respostas de TTS são enviadas como anexos de arquivo de áudio

Prompts por canal

Atribua prompts de sistema efêmeros a canais específicos do Slack. O prompt é injetado em tempo de execução a cada turno — nunca é gravado no histórico da transcrição —, então as mudanças valem na hora.

slack:
  channel_prompts:
    "C01RESEARCH": |
      Você é um assistente de pesquisa. Foque em fontes acadêmicas,
      citações e síntese concisa.
    "C02ENGINEERING": |
      Modo de revisão de código. Seja preciso sobre casos de borda e
      implicações de desempenho.

As chaves são IDs de canal do Slack (encontre-os nos detalhes do canal → "About" → role até o fim). Todas as mensagens do canal correspondente recebem o prompt injetado como instrução de sistema efêmera.

Vínculos de skill por canal

Carregue uma skill automaticamente sempre que uma sessão nova começar num canal ou mensagem direta específica. Diferente dos prompts por canal (que são injetados a cada turno), os vínculos de skill injetam o conteúdo da skill como mensagem de usuário no início da sessão — ele passa a fazer parte do histórico da conversa e não precisa ser recarregado nos turnos seguintes.

Isso é ideal para mensagens diretas ou canais com um propósito dedicado (cartões de memorização, um bot de perguntas e respostas de um domínio, um canal de triagem de suporte etc.), em que você não quer que o próprio seletor de skills do modelo decida se carrega a skill a cada resposta curta.

slack:
  channel_skill_bindings:
    # Canal de mensagem direta — sempre roda no modo "german-flashcards"
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Canal de pesquisa — pré-carrega várias skills, em ordem
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Forma curta: uma única skill como texto
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

Observações:

O vínculo casa pelo ID do canal. Em mensagens de discussão num canal vinculado, a discussão herda o vínculo do canal pai.
A skill é carregada só no início da sessão (sessão nova ou depois de uma reinicialização automática). Se você mudar o vínculo, rode /new ou espere a sessão se reiniciar sozinha para que a mudança valha.
Combine com channel_prompts para dar tom e restrições por canal em cima das instruções da skill.

Solução de problemas

Problema	Solução
O bot não responde a mensagens diretas	Confirme que `message.im` está nas suas assinaturas de evento e que o app foi reinstalado
O bot funciona nas mensagens diretas, mas não nos canais	O problema mais comum. Adicione `message.channels` e `message.groups` às assinaturas de evento, reinstale o app e convide o bot para o canal com `/invite @Hermes Agent`
O bot não responde a menções com @ nos canais	1) Confira se o evento `message.channels` está assinado. 2) O bot precisa ter sido convidado para o canal. 3) Garanta que o escopo `channels:history` foi adicionado. 4) Reinstale o app depois de mudar escopos ou eventos
O bot ignora mensagens em canais privados	Adicione a assinatura de evento `message.groups` e o escopo `groups:history`, depois reinstale o app e use `/invite` no bot
O bot não responde em mensagens diretas em grupo (com várias pessoas)	Adicione a assinatura de evento `message.mpim` e o escopo `mpim:history` (mais `mpim:read`), depois reinstale o app. Sem `message.mpim`, o Slack nunca entrega ao bot as mensagens diretas em grupo — mesmo que as 1 para 1 funcionem.
"Sending messages to this app has been turned off" nas mensagens diretas	Habilite a Messages Tab nas configurações de App Home (veja o Passo 5)
Erros "not_authed" ou "invalid_auth"	Gere de novo o seu Bot Token e o App Token e atualize o `.env`
O bot responde, mas não consegue publicar num canal	Convide o bot para o canal com `/invite @Hermes Agent`
O bot conversa, mas não consegue ler imagens/arquivos enviados	Adicione `files:read` e depois reinstale o app. O Hermes agora mostra diagnósticos de acesso a anexo na própria conversa quando o Slack devolve falhas de escopo, autenticação ou permissão.
Erro `missing_scope`	Adicione o escopo necessário em OAuth & Permissions e depois reinstale o app
O socket cai com frequência	Verifique a sua rede; o Bolt reconecta sozinho, mas conexões instáveis causam lentidão
Mudei escopos/eventos, mas nada mudou	Você precisa reinstalar o app no seu espaço de trabalho depois de qualquer mudança de escopo ou de assinatura de evento

Lista rápida de verificação

Se o bot não está funcionando nos canais, confirme todos os itens a seguir:

✅ O evento message.channels está assinado (para canais públicos)
✅ O evento message.groups está assinado (para canais privados)
✅ O evento app_mention está assinado
✅ O escopo channels:history foi adicionado (para canais públicos)
✅ O escopo groups:history foi adicionado (para canais privados)
✅ O app foi reinstalado depois de adicionar escopos/eventos
✅ O bot foi convidado para o canal (/invite @Hermes Agent)
✅ Você está mencionando com @ o bot na sua mensagem

Segurança

aviso

Sempre defina SLACK_ALLOWED_USERS com os Member IDs dos usuários autorizados. Sem essa configuração, o gateway vai negar todas as mensagens por padrão, como medida de segurança. Nunca compartilhe os seus tokens de bot — trate-os como senhas.

Os tokens devem ficar guardados em ~/.hermes/.env (permissões de arquivo 600)
Gire os tokens periodicamente, pelas configurações do app do Slack
Audite quem tem acesso ao diretório de configuração do seu Hermes
O Socket Mode significa que nenhum endpoint público fica exposto — uma superfície de ataque a menos

Configuração do Slack

Visão geral​

Passo 1: crie um app do Slack​

Opção A: a partir de um manifesto gerado pelo Hermes (recomendado)​

Opção B: do zero (manual)​

Passo 2: configure os escopos do Bot Token​

Passo 3: habilite o Socket Mode​

Passo 4: assine os eventos​

Passo 5: habilite a aba Messages​

Passo 6: instale o app no espaço de trabalho​

Passo 7: encontre os IDs de usuário para a lista de permissão​

Passo 8: configure o Hermes​

Passo 9: convide o bot para os canais​

Comandos de barra​

Experiência de mensagens de Agente​

Atualizar os comandos de barra depois de atualizações​

O antigo /hermes <subcomando> continua funcionando​

Usar comandos dentro de discussões (o prefixo !cmd)​

As respostas a comandos de barra são efêmeras​

Pedidos de esclarecimento (botões de um toque)​

Avançado: emitir só o array de comandos de barra​

Como o bot responde​

Opções de configuração​

Comportamento de discussão e resposta​

Linha de status de trabalho​

Status ao vivo (por ferramenta)​

Fluxo nativo (respostas digitadas ao vivo)​

Cartões nativos de tarefa (progresso de ferramenta ao vivo)​

Isolamento de sessão​

Comportamento de menção e gatilho​

Qual opção de menção eu quero?​

Aceitar mensagens de outros bots (allow_bots)​

Gatilhos por reação (reaction_triggers)​

Verificação rápida de agentes pares​

Lista de canais permitidos (allowed_channels)​

Tratamento de usuários não autorizados​

Transcrição de voz​

Exemplo completo​

Canal principal​

Direcionamento da entrega de cron​

Enviar mensagens e mídia (send_message)​

Suporte a vários espaços de trabalho​

Configuração​

Arquivo de tokens OAuth​

Como funciona​

Mensagens de voz​

Prompts por canal​

Vínculos de skill por canal​

Solução de problemas​

Lista rápida de verificação​

Segurança​

Visão geral

Passo 1: crie um app do Slack

Opção A: a partir de um manifesto gerado pelo Hermes (recomendado)

Opção B: do zero (manual)

Passo 2: configure os escopos do Bot Token

Passo 3: habilite o Socket Mode

Passo 4: assine os eventos

Passo 5: habilite a aba Messages

Passo 6: instale o app no espaço de trabalho

Passo 7: encontre os IDs de usuário para a lista de permissão

Passo 8: configure o Hermes

Passo 9: convide o bot para os canais

Comandos de barra

Experiência de mensagens de Agente

Atualizar os comandos de barra depois de atualizações

O antigo `/hermes <subcomando>` continua funcionando

Usar comandos dentro de discussões (o prefixo `!cmd`)

As respostas a comandos de barra são efêmeras

Pedidos de esclarecimento (botões de um toque)

Avançado: emitir só o array de comandos de barra

Como o bot responde

Opções de configuração

Comportamento de discussão e resposta

Linha de status de trabalho

Status ao vivo (por ferramenta)

Fluxo nativo (respostas digitadas ao vivo)

Cartões nativos de tarefa (progresso de ferramenta ao vivo)

Isolamento de sessão

Comportamento de menção e gatilho

Qual opção de menção eu quero?

Aceitar mensagens de outros bots (`allow_bots`)

Gatilhos por reação (`reaction_triggers`)

Verificação rápida de agentes pares

Lista de canais permitidos (`allowed_channels`)

Tratamento de usuários não autorizados

Transcrição de voz

Exemplo completo

Canal principal

Direcionamento da entrega de cron

Enviar mensagens e mídia (`send_message`)

Suporte a vários espaços de trabalho

Configuração

Arquivo de tokens OAuth

Como funciona

Mensagens de voz

Prompts por canal

Vínculos de skill por canal

Solução de problemas

Lista rápida de verificação

Segurança