Slack

Stato: pronto per la produzione per DM + canali tramite integrazioni app Slack. La modalita predefinita e Socket Mode; anche la modalita HTTP Events API e supportata.

Setup rapido

Socket Mode (predefinito)

  ### Step 1: Crea app Slack e token
    Nelle impostazioni dell'app Slack:

    - abilita **Socket Mode**
    - crea **App Token** (`xapp-...`) con `connections:write`
    - installa l'app e copia il **Bot Token** (`xoxb-...`)


  ### Step 2: Configura OpenClaw
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}
    Fallback via env (solo account predefinito):
SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...
  ### Step 3: Sottoscrivi gli eventi dell'app
    Sottoscrivi gli eventi bot per:

    - `app_mention`
    - `message.channels`, `message.groups`, `message.im`, `message.mpim`
    - `reaction_added`, `reaction_removed`
    - `member_joined_channel`, `member_left_channel`
    - `channel_rename`
    - `pin_added`, `pin_removed`

    Abilita anche la **Messages Tab** dell'App Home per i DM.


  ### Step 4: Avvia il gateway
openclaw gateway

Modalita HTTP Events API

  ### Step 1: Configura l'app Slack per HTTP

    - imposta la modalita a HTTP (`channels.slack.mode="http"`)
    - copia il **Signing Secret** di Slack
    - imposta Event Subscriptions + Interactivity + Slash command Request URL allo stesso percorso webhook (predefinito `/slack/events`)



  ### Step 2: Configura OpenClaw in modalita HTTP
{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}
  ### Step 3: Usa percorsi webhook unici per HTTP multi-account
    La modalita HTTP per account e supportata.

    Dai a ogni account un `webhookPath` distinto cosi le registrazioni non collidono.

Modello token

  • botToken + appToken sono necessari per Socket Mode.
  • La modalita HTTP richiede botToken + signingSecret.
  • I token nel config sovrascrivono il fallback env.
  • Il fallback env SLACK_BOT_TOKEN / SLACK_APP_TOKEN si applica solo all’account predefinito.
  • userToken (xoxp-...) e solo nel config (nessun fallback env) e predefinito a comportamento sola lettura (userTokenReadOnly: true).
  • Opzionale: aggiungi chat:write.customize se vuoi che i messaggi in uscita usino l’identita dell’agent attivo (username e icona personalizzati). icon_emoji usa la sintassi :emoji_name:.

Suggerimento: Per azioni/letture directory, il user token puo essere preferito quando configurato. Per le scritture, il bot token rimane preferito; le scritture con user-token sono consentite solo quando userTokenReadOnly: false e il bot token non e disponibile.

Controllo degli accessi e routing

Policy DM

`channels.slack.dmPolicy` controlla l'accesso DM (legacy: `channels.slack.dm.policy`):

- `pairing` (predefinito)
- `allowlist`
- `open` (richiede che `channels.slack.allowFrom` includa `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `disabled`

Flag DM:

- `dm.enabled` (predefinito true)
- `channels.slack.allowFrom` (preferito)
- `dm.allowFrom` (legacy)
- `dm.groupEnabled` (DM di gruppo predefinito false)
- `dm.groupChannels` (allowlist MPIM opzionale)

Precedenza multi-account:

- `channels.slack.accounts.default.allowFrom` si applica solo all'account `default`.
- Gli account nominati ereditano `channels.slack.allowFrom` quando il proprio `allowFrom` non e impostato.
- Gli account nominati non ereditano `channels.slack.accounts.default.allowFrom`.

Il pairing nei DM usa `openclaw pairing approve slack <code>`.

Policy canali

`channels.slack.groupPolicy` controlla la gestione dei canali:

- `open`
- `allowlist`
- `disabled`

L'allowlist canali vive sotto `channels.slack.channels` e dovrebbe usare ID canale stabili.

Nota runtime: se `channels.slack` e completamente assente (setup solo env), il runtime torna a `groupPolicy="allowlist"` e registra un avviso (anche se `channels.defaults.groupPolicy` e impostato).

Risoluzione nome/ID:

- le voci dell'allowlist canali e dell'allowlist DM vengono risolte all'avvio quando l'accesso al token lo consente
- le voci nome-canale non risolte vengono mantenute come configurate ma ignorate per il routing per impostazione predefinita
- l'autorizzazione in ingresso e il routing canale sono ID-first per impostazione predefinita; il matching diretto per username/slug richiede `channels.slack.dangerouslyAllowNameMatching: true`

Menzioni e utenti canale

I messaggi nei canali sono filtrati per menzione per impostazione predefinita.

Fonti di menzione:

- menzione esplicita dell'app (`<@botId>`)
- pattern regex di menzione (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- comportamento implicito di risposta al bot nei thread

Controlli per canale (`channels.slack.channels.<id>`; nomi solo tramite risoluzione all'avvio o `dangerouslyAllowNameMatching`):

- `requireMention`
- `users` (allowlist)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- formato chiave `toolsBySender`: `id:`, `e164:`, `username:`, `name:`, o wildcard `"*"`
  (le chiavi legacy senza prefisso mappano solo a `id:`)

Comandi e comportamento slash

  • La modalita auto dei comandi nativi e disattivata per Slack (commands.native: "auto" non abilita i comandi nativi Slack).
  • Abilita i gestori comandi nativi Slack con channels.slack.commands.native: true (o globale commands.native: true).
  • Quando i comandi nativi sono abilitati, registra i comandi slash corrispondenti in Slack (nomi /<comando>), con un’eccezione:
    • registra /agentstatus per il comando status (Slack riserva /status)
  • Se i comandi nativi non sono abilitati, puoi eseguire un singolo comando slash configurato tramite channels.slack.slashCommand.
  • I menu argomenti nativi ora adattano la loro strategia di rendering:
    • fino a 5 opzioni: blocchi bottoni
    • 6-100 opzioni: menu select statico
    • piu di 100 opzioni: select esterno con filtro opzioni asincrono quando i gestori opzioni di interattivita sono disponibili
    • se i valori opzione codificati superano i limiti Slack, il flusso torna ai bottoni
  • Per payload opzioni lunghi, i menu argomenti dei comandi slash usano un dialogo di conferma prima di inviare un valore selezionato.

Risposte interattive

Slack puo renderizzare controlli di risposta interattiva creati dall’agent, ma questa funzionalita e disabilitata per impostazione predefinita.

Abilitala globalmente:

{
  channels: {
    slack: {
      capabilities: {
        interactiveReplies: true,
      },
    },
  },
}

O abilitala per un solo account Slack:

{
  channels: {
    slack: {
      accounts: {
        ops: {
          capabilities: {
            interactiveReplies: true,
          },
        },
      },
    },
  },
}

Quando abilitato, gli agent possono emettere direttive di risposta specifiche per Slack:

  • [[slack_buttons: Approve:approve, Reject:reject]]
  • [[slack_select: Choose a target | Canary:canary, Production:production]]

Queste direttive vengono compilate in Slack Block Kit e instradano clic o selezioni attraverso il percorso eventi di interazione Slack esistente.

Note:

  • Questa e UI specifica per Slack. Gli altri canali non traducono le direttive Block Kit di Slack nei propri sistemi di bottoni.
  • I valori callback interattivi sono token opachi generati da OpenClaw, non valori raw scritti dall’agent.
  • Se i blocchi interattivi generati supererebbero i limiti di Slack Block Kit, OpenClaw torna alla risposta testuale originale invece di inviare un payload blocchi non valido.

Impostazioni predefinite comando slash:

  • enabled: false
  • name: "openclaw"
  • sessionPrefix: "slack:slash"
  • ephemeral: true

Le sessioni slash usano chiavi isolate:

  • agent:<agentId>:slack:slash:<userId>

e instradano comunque l’esecuzione comandi verso la sessione di conversazione target (CommandTargetSessionKey).

Threading, sessioni e tag di risposta

  • I DM instradano come direct; i canali come channel; gli MPIM come group.
  • Con il session.dmScope=main predefinito, i DM Slack collassano nella sessione principale dell’agent.
  • Sessioni canale: agent:<agentId>:slack:channel:<channelId>.
  • Le risposte nei thread possono creare suffissi di sessione thread (:thread:<threadTs>) quando applicabile.
  • Il channels.slack.thread.historyScope predefinito e thread; il thread.inheritParent predefinito e false.
  • channels.slack.thread.initialHistoryLimit controlla quanti messaggi thread esistenti vengono recuperati quando una nuova sessione thread inizia (predefinito 20; imposta 0 per disabilitare).

Controlli threading risposte:

  • channels.slack.replyToMode: off|first|all (predefinito off)
  • channels.slack.replyToModeByChatType: per direct|group|channel
  • fallback legacy per chat dirette: channels.slack.dm.replyToMode

I tag di risposta manuali sono supportati:

  • [[reply_to_current]]
  • [[reply_to:<id>]]

Nota: replyToMode="off" disabilita tutto il threading delle risposte in Slack, inclusi i tag espliciti [[reply_to_*]]. Questo differisce da Telegram, dove i tag espliciti vengono comunque rispettati in modalita "off". La differenza riflette i modelli di threading delle piattaforme: i thread Slack nascondono i messaggi dal canale, mentre le risposte Telegram rimangono visibili nel flusso principale della chat.

Media, segmentazione e consegna

Allegati in ingresso 
Gli allegati file Slack vengono scaricati da URL privati ospitati su Slack (flusso di richiesta autenticata con token) e scritti nel media store quando il fetch riesce e i limiti di dimensione lo permettono.

Il limite dimensione in ingresso runtime e predefinito a `20MB` a meno che non sia sovrascritto da `channels.slack.mediaMaxMb`.
Testo e file in uscita 
- i segmenti testo usano `channels.slack.textChunkLimit` (predefinito 4000)
- `channels.slack.chunkMode="newline"` abilita la divisione per paragrafi prioritaria
- gli invii file usano le API di upload Slack e possono includere risposte thread (`thread_ts`)
- il limite media in uscita segue `channels.slack.mediaMaxMb` quando configurato; altrimenti gli invii canale usano i default per tipo MIME dalla pipeline media
Target di consegna 
Target espliciti preferiti:

- `user:<id>` per i DM
- `channel:<id>` per i canali

I DM Slack vengono aperti tramite le API conversazione Slack quando si invia a target utente.

Azioni e gate

Le azioni Slack sono controllate da channels.slack.actions.*.

Gruppi di azioni disponibili negli strumenti Slack attuali:

GruppoPredefinito
messagesabilitato
reactionsabilitato
pinsabilitato
memberInfoabilitato
emojiListabilitato

Eventi e comportamento operativo

  • Le modifiche/cancellazioni/broadcast thread dei messaggi sono mappati in eventi di sistema.
  • Gli eventi di aggiunta/rimozione reazione sono mappati in eventi di sistema.
  • Gli eventi di ingresso/uscita membri, creazione/rinomina canale e aggiunta/rimozione pin sono mappati in eventi di sistema.
  • Gli aggiornamenti stato thread dell’assistente (per indicatori “sta scrivendo…” nei thread) usano assistant.threads.setStatus e richiedono lo scope bot assistant:write.
  • channel_id_changed puo migrare le chiavi di configurazione canale quando configWrites e abilitato.
  • I metadati topic/scopo del canale sono trattati come contesto non fidato e possono essere iniettati nel contesto di routing.
  • Le azioni sui blocchi e le interazioni modali emettono eventi di sistema strutturati Slack interaction: ... con campi payload ricchi:
    • azioni blocco: valori selezionati, etichette, valori picker e metadati workflow_*
    • eventi modali view_submission e view_closed con metadati canale instradato e input form

Reazioni di conferma

ackReaction invia un emoji di conferma mentre OpenClaw sta elaborando un messaggio in ingresso.

Ordine di risoluzione:

  • channels.slack.accounts.<accountId>.ackReaction
  • channels.slack.ackReaction
  • messages.ackReaction
  • fallback emoji identita agent (agents.list[].identity.emoji, altrimenti ”👀”)

Note:

  • Slack si aspetta shortcode (ad esempio "eyes").
  • Usa "" per disabilitare la reazione per l’account Slack o globalmente.

Reazione typing di fallback

typingReaction aggiunge una reazione temporanea al messaggio Slack in ingresso mentre OpenClaw sta elaborando una risposta, poi la rimuove quando l’esecuzione termina. E un fallback utile quando il typing nativo dell’assistente Slack non e disponibile, specialmente nei DM.

Ordine di risoluzione:

  • channels.slack.accounts.<accountId>.typingReaction
  • channels.slack.typingReaction

Note:

  • Slack si aspetta shortcode (ad esempio "hourglass_flowing_sand").
  • La reazione e best-effort e la pulizia viene tentata automaticamente dopo il completamento della risposta o del percorso di errore.

Manifest e checklist scope

Esempio manifest app Slack 
{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": {
      "display_name": "OpenClaw",
      "always_online": false
    },
    "app_home": {
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "chat:write",
        "channels:history",
        "channels:read",
        "groups:history",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "assistant:write",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "reaction_added",
        "reaction_removed",
        "member_joined_channel",
        "member_left_channel",
        "channel_rename",
        "pin_added",
        "pin_removed"
      ]
    }
  }
}
Scope user-token opzionali (operazioni di lettura) 
Se configuri `channels.slack.userToken`, gli scope di lettura tipici sono:

- `channels:history`, `groups:history`, `im:history`, `mpim:history`
- `channels:read`, `groups:read`, `im:read`, `mpim:read`
- `users:read`
- `reactions:read`
- `pins:read`
- `emoji:read`
- `search:read` (se dipendi dalle letture di ricerca Slack)

Risoluzione problemi

Nessuna risposta nei canali 
Controlla, in ordine:

- `groupPolicy`
- allowlist canali (`channels.slack.channels`)
- `requireMention`
- allowlist `users` per canale

Comandi utili:
openclaw channels status --probe
openclaw logs --follow
openclaw doctor
Messaggi DM ignorati 
Controlla:

- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (o legacy `channels.slack.dm.policy`)
- approvazioni pairing / voci allowlist
openclaw pairing list slack
Socket mode non si connette 
Valida i token bot + app e l'abilitazione Socket Mode nelle impostazioni dell'app Slack.
Modalita HTTP non riceve eventi 
Valida:

- signing secret
- percorso webhook
- URL di richiesta Slack (Events + Interactivity + Slash Commands)
- `webhookPath` unico per account HTTP
Comandi nativi/slash non funzionano 
Verifica se intendevi:

- modalita comandi nativi (`channels.slack.commands.native: true`) con comandi slash corrispondenti registrati in Slack
- o modalita singolo comando slash (`channels.slack.slashCommand.enabled: true`)

Controlla anche `commands.useAccessGroups` e allowlist canale/utente.

Streaming testo

OpenClaw supporta lo streaming testo nativo Slack tramite l’API Agents and AI Apps.

channels.slack.streaming controlla il comportamento dell’anteprima live:

  • off: disabilita lo streaming anteprima live.
  • partial (predefinito): sostituisce il testo anteprima con l’ultimo output parziale.
  • block: appende aggiornamenti anteprima a blocchi.
  • progress: mostra testo stato avanzamento durante la generazione, poi invia il testo finale.

channels.slack.nativeStreaming controlla l’API di streaming nativa Slack (chat.startStream / chat.appendStream / chat.stopStream) quando streaming e partial (predefinito: true).

Disabilita lo streaming nativo Slack (mantieni il comportamento anteprima bozza):

channels:
  slack:
    streaming: partial
    nativeStreaming: false

Chiavi legacy:

  • channels.slack.streamMode (replace | status_final | append) viene auto-migrato a channels.slack.streaming.
  • channels.slack.streaming booleano viene auto-migrato a channels.slack.nativeStreaming.

Requisiti

  1. Abilita Agents and AI Apps nelle impostazioni della tua app Slack.
  2. Assicurati che l’app abbia lo scope assistant:write.
  3. Deve essere disponibile un thread di risposta per quel messaggio. La selezione thread segue comunque replyToMode.

Comportamento

  • Il primo segmento testo avvia uno stream (chat.startStream).
  • I segmenti testo successivi appendono allo stesso stream (chat.appendStream).
  • La fine della risposta finalizza lo stream (chat.stopStream).
  • I payload media e non-testuali tornano alla consegna normale.
  • Se lo streaming fallisce durante la risposta, OpenClaw torna alla consegna normale per i payload rimanenti.

Riferimenti configurazione

Riferimento primario:

  • Riferimento configurazione - Slack

    Campi Slack ad alto segnale:

    • modalita/auth: mode, botToken, appToken, signingSecret, webhookPath, accounts.*
    • accesso DM: dm.enabled, dmPolicy, allowFrom (legacy: dm.policy, dm.allowFrom), dm.groupEnabled, dm.groupChannels
    • toggle compatibilita: dangerouslyAllowNameMatching (break-glass; mantieni disattivato se non necessario)
    • accesso canali: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
    • threading/storico: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
    • consegna: textChunkLimit, chunkMode, mediaMaxMb, streaming, nativeStreaming
    • ops/funzionalita: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

Correlati

arrow_back
Precedente
Synology Chat
Successivo
Telegram
arrow_forward