Come configurare Hermes Agent su Slack (Socket Mode)

Perché usare Hermes Agent su Slack

Se il tuo team vive già su Slack, è lì che dovrebbe stare anche il tuo agente AI. Le schede del browser e le dashboard standalone perdono il contesto che canali, thread e messaggi diretti offrono già gratuitamente: chi sta chiedendo, di cosa stava parlando poco prima, e dove deve arrivare la risposta.

Hermes Agent supporta Slack in modo nativo tramite Socket Mode, quindi il runtime può girare sul tuo laptop, su un VPS da $5/mese o dietro un firewall aziendale e trasmettere comunque i messaggi in tempo reale. Non c'è nessun webhook pubblico da esporre, nessun reverse proxy da mantenere e nessuna porta in entrata da aprire. L'agente si connette a Slack, mantiene aperta una WebSocket e consegna ogni messaggio e risposta su quel singolo canale.

Questa guida percorre l'intera configurazione dall'inizio alla fine: creare l'app Slack dal manifest incluso, generare i token bot e app-level, configurare il canale home e l'allowlist, avviare il gateway e le modalità di errore che colpiscono le prime distribuzioni.

Cosa ti serve prima di iniziare

Una distribuzione Slack pulita richiede cinque elementi:

• Un workspace in cui hai i permessi per installare app. La maggior parte dei workspace richiede l'approvazione di un amministratore per le installazioni - controlla Impostazioni e amministrazione → Impostazioni workspace → Permessi se non sei un admin.
• Un'installazione funzionante di Hermes Agent. La guida Docker di Hermes Agent illustra il modo più pulito per avviarne una; se sei su Windows, la configurazione WSL2 è l'equivalente.
• Una chiave API del provider modello. Anthropic, OpenAI, OpenRouter e qualsiasi endpoint compatibile con OpenAI funzionano. Il runtime la usa per rispondere effettivamente ai messaggi.
• Il tuo ID utente Slack numerico per l'allowlist (ne parliamo più avanti).
• Circa 15 minuti per la prima installazione. Le distribuzioni successive richiedono meno di un minuto.

Fase 1 - Generare il manifest dell'app Slack

Le app Slack sono definite da un manifest YAML che dichiara scope, sottoscrizioni agli eventi, slash command e Socket Mode in un colpo solo. Hermes include un manifest calibrato per il suo handler Slack integrato, quindi non devi assemblare la lista degli scope a mano:

hermes slack manifest --write ./hermes-slack-manifest.yaml

Apri https://api.slack.com/apps, clicca su Create New App, scegli From an app manifest, seleziona il tuo workspace e incolla il contenuto di hermes-slack-manifest.yaml. Slack mostra un'anteprima di ciò che verrà creato. Conferma.

Il manifest abilita Socket Mode, dichiara tutti gli eventi a cui Hermes si sottoscrive (app_mention, message.im, message.channels, message.groups, message.mpim), registra i slash command integrati e richiede gli scope bot che il runtime utilizza effettivamente:

• app_mentions:read - ricevere notifica quando qualcuno @menziona il bot in un canale.
• chat:write - inviare risposte e avviare thread.
• im:history, im:read, im:write - conversazioni in messaggio diretto.
• channels:history, groups:history, mpim:history - leggere il contesto nei canali pubblici, privati e nei DM di gruppo in cui il bot è invitato.
• users:read - risolvere gli ID utente in nomi visualizzati per l'UI dell'allowlist e i log di audit.
• commands - registrare la superficie del comando /hermes.

Modificare il manifest dopo l'installazione è possibile. Aggiungere scope dopo l'installazione è l'operazione che causa più errori silenziosi - vedi la sezione sulla risoluzione dei problemi qui sotto.

Fase 2 - Generare il token bot e il token app-level

Slack emette due token distinti per un'app in Socket Mode, e Hermes ha bisogno di entrambi:

Token bot (xoxb-…)

Nelle impostazioni dell'app, vai su OAuth & Permissions → Install to Workspace. Approva gli scope del manifest. Slack emette un token xoxb-…. Copialo.

Token app-level (xapp-…)

Vai su Basic Information → App-Level Tokens → Generate Token and Scopes. Dagli un nome (ad es. hermes-socket), aggiungi lo scope connections:write e clicca su Generate. Slack emette un token xapp-…. Copialo.

I due token svolgono compiti diversi. Il token bot autentica le chiamate API Slack (inviare un messaggio, leggere la cronologia di un canale). Il token app autentica la WebSocket di Socket Mode - senza di esso, il runtime si avvia ma non si connette mai a Slack e il bot resta in silenzio per sempre.

Fase 3 - Trovare il tuo ID utente Slack numerico

Hermes Agent risponde solo agli ID utente presenti in SLACK_ALLOWED_USERS. Questo è il controllo di sicurezza più importante dell'intera configurazione, e richiede ID numerici, non @handle o nomi visualizzati.

Su Slack, clicca sul tuo avatar → Profilo → il menu kebab (⋮) → Copia ID membro. L'ID ha l'aspetto U01ABCD2EFG. Ripeti per ogni collega che vuoi autorizzare.

Omettere l'allowlist equivale a pubblicare la tua chiave API del provider a chiunque si trovi nel tuo workspace. Se un'istanza di Hermes è raggiungibile da un workspace Slack pubblico e l'allowlist è vuota, ogni messaggio in ogni canale in cui il bot è invitato consumerà i tuoi crediti.

Fase 4 - Configurare il runtime Hermes

Apri ~/.hermes/.env (o qualunque .env legga il tuo container) e aggiungi:

SLACK_BOT_TOKEN=xoxb-...your-bot-token...
SLACK_APP_TOKEN=xapp-...your-app-token...
SLACK_ALLOWED_USERS=U01ABCD2EFG,U02HIJK3LMN
SLACK_HOME_CHANNEL=C04XYZ123AB

Una nota su ciascuno:

• SLACK_BOT_TOKEN - il token xoxb-… della Fase 2.
• SLACK_APP_TOKEN - il token xapp-…. Dimenticarlo è la modalità di errore più comune e non produce alcun messaggio di errore - il gateway semplicemente non apre mai la WebSocket.
• SLACK_ALLOWED_USERS - elenco di ID numerici separati da virgola. Il bot ignora tutti gli altri, inclusi gli amministratori e gli account bot.
• SLACK_HOME_CHANNEL (opzionale) - l'ID del canale per i messaggi proattivi, i riepiloghi programmati e le notifiche attivate dalle skill. Fai clic con il tasto destro sul canale in Slack → Visualizza dettagli canale → copia l'ID canale in fondo. Se non impostato, l'output proattivo va nel DM del bot con il primo utente autorizzato.

Esegui chmod 600 ~/.hermes/.env dopo il salvataggio. Entrambi i token concedono accesso in scrittura al tuo workspace; trattali come chiavi SSH.

Fase 5 - Avviare il gateway

Riavvia il gateway in modo che carichi il nuovo ambiente:

hermes gateway restart

Oppure, con Docker Compose:

docker compose restart gateway

Segui i log e cerca l'handshake con Slack:

hermes gateway logs --follow

Cerca due righe, nell'ordine:

slack: connecting to Socket Mode
slack: connected as @your-bot-name (workspace: your-workspace)

Se vedi solo la prima riga e nient'altro dopo, il token xapp-… è errato, mancante o privo dello scope connections:write. Se non vedi nessuna delle due, il gateway non sta caricando il nuovo .env - verifica il percorso del file che il runtime legge.

Fase 6 - Invitare il bot e inviare il primo messaggio

In qualsiasi canale in cui vuoi che il bot partecipi:

/invite @your-bot-name

Il bot vede solo i messaggi nei canali in cui è stato invitato. Questa è una restrizione lato Slack, non di Hermes - anche con channels:history concesso, il bot non legge nessuna cronologia finché non lo /invite.

Invia un DM al bot, oppure @menzionalo nel canale. Hermes risponde nella stessa conversazione, con la memoria persistente e il contesto delle skill intatti. Da qui, ogni funzionalità di Hermes - memoria persistente, attività pianificate, skill personalizzate - funziona esattamente come sulla superficie di consegna Telegram.

Le modalità di errore che colpiscono per prime

Cinque errori spiegano quasi ogni thread di supporto "la configurazione Slack è rotta":

Dimenticare il token xapp-…. Socket Mode non si connette affatto senza di esso, e la dashboard delle app Slack non avvisa. La correzione è una riga nel .env e un riavvio.

Aggiungere scope dopo l'installazione senza reinstallare. I nuovi scope compaiono nella pagina OAuth ma non vengono effettivamente concessi al bot finché non si clicca su Reinstall to Workspace. Il bot mantiene silenziosamente il vecchio set di scope. Se il runtime registra errori missing_scope, è per questo.

Bot non invitato nel canale. Un bot con channels:history non legge comunque nessuna cronologia finché non viene invitato. Il bot risponde immediatamente ai DM ma resta in silenzio nei canali finché non si esegue /invite @your-bot-name.

SLACK_ALLOWED_USERS vuoto. Il comportamento predefinito è ignorare tutti. Questo è un default sicuro intenzionale, ma fa sembrare il bot rotto a chi lo prova per la prima volta e ha dimenticato di aggiungere il proprio ID.

Due processi gateway sullo stesso volume dati. Se avvii un gateway in modalità Slack e uno in modalità Telegram sullo stesso volume /data, l'ordinamento dei messaggi e le scritture in memoria si corrompono in pochi minuti. Esegui un singolo gateway con entrambi i blocchi SLACK_* e TELEGRAM_* impostati nel .env se vuoi entrambe le superfici - il runtime le gestisce entrambe nativamente.

Se un problema sembra legato a Slack ma i sintomi sembrano generici, la guida alla risoluzione dei problemi di Telegram copre i problemi del gateway e del provider sottostanti in modo più approfondito - la maggior parte sono indipendenti dalla superficie.

Slack e Telegram, a confronto

Le due superfici non sono esclusive. Lo stesso runtime Hermes può consegnare su entrambe contemporaneamente - utile quando lo stesso agente serve una chat Telegram personale e un canale Slack di team dallo stesso store di memoria.

Salta la complessità di Slack

I passaggi Slack in sé sono lineari, ma hai ancora il server da gestire: backup, TLS per la dashboard, rotazione dei log e il ritmo degli aggiornamenti. Per un'installazione a scala personale va bene. Per un team che vuole il bot operativo in pochi minuti e senza overhead operativo, Hermify distribuisce un runtime Hermes gestito, cifra i tuoi token Slack a riposo, espone l'allowlist in un'interfaccia invece che in un .env e mantiene la connessione Socket Mode attiva su un server persistente.

Porti il workspace Slack e una chiave del provider modello; la piattaforma gestisce tutto il resto. Se stai valutando questo compromesso, il confronto self-hosted vs hosting gestito analizza i costi e i numeri di manutenzione.

Fonti

• Guida utente Slack di Hermes Agent
• Configurazione del gateway Hermes Agent per Telegram e Slack (EvoMap)
• Come connettere Slack a Hermes Agent (hermes-agent.ai)
• Passo dopo passo: connettere Hermes Agent a Slack via Socket Mode (gist)
• Documentazione sviluppatori Slack Socket Mode
• Riferimento ai tipi di token Slack