Slack¶

Status: production-ready for DMs + channels via Slack app integrations. Mode HTTP (API Events)

Slack DMs default to pairing mode. Native command behavior and command catalog. Cross-channel diagnostics and repair playbooks.

Quick setup¶

In Slack app settings:

    ```
    **OAuth & Permissions** → installez l’application et copiez le **Bot User OAuth Token** (`xoxb-...`).
    ```

{
  channels: {
    slack: {
      enabled: true,
      appToken: "xapp-...",
      botToken: "xoxb-...",
    },
  },
}

    ```
        Env fallback (default account only):
    ```

`SLACK_APP_TOKEN=xapp-...`

    </Step>

    <Step title="Subscribe app events">
      Subscribe bot events for:

      - `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`

      Also enable App Home **Messages Tab** for DMs.
    </Step>

    <Step title="Start gateway">

openclaw gateway

    </Step>
  </Steps>

    ```
    Utilisez le mode webhook HTTP lorsque votre Gateway (passerelle) est accessible par Slack via HTTPS (typique pour des deploiements serveur). Le mode HTTP utilise l’API Events + Interactivity + Slash Commands avec une URL de requete partagee.
    ```

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: "xoxb-...",
      signingSecret: "your-signing-secret",
      webhookPath: "/slack/events",
    },
  },
}

  Mode HTTP multi-comptes : definissez `channels.slack.accounts.<id> .mode = "http"` et fournissez un
  `webhookPath` unique par compte afin que chaque application Slack pointe vers sa propre URL.

Token model¶

• botToken + appToken are required for Socket Mode.
• HTTP mode requires botToken + signingSecret.
• Config tokens override env fallback.
• SLACK_BOT_TOKEN / SLACK_APP_TOKEN env fallback applies only to the default account.
• Definir userTokenReadOnly: false permet d’utiliser le token utilisateur pour les operations d’ecriture lorsqu’aucun token de bot n’est disponible, ce qui signifie que les actions s’executent avec l’acces de l’utilisateur installateur.
• Optional: add chat:write.customize if you want outgoing messages to use the active agent identity (custom username and icon). icon_emoji uses :emoji_name: syntax.

For actions/directory reads, user token can be preferred when configured. Meme avec userTokenReadOnly: false, le token du bot reste prefere pour les ecritures lorsqu’il est disponible.

Access control and routing¶

DMs ignorés: l'expéditeur n'est pas approuvé lorsque channels.slack.dm.policy="appairage".

```
Pour autoriser tout le monde : definissez `channels.slack.dm.policy="open"` et `channels.slack.dm.allowFrom=["*"]`.
```

channels.slack.groupPolicy controle la gestion des canaux (open|disabled|allowlist).

```
Pour n’autoriser **aucun canal**, definissez `channels.slack.groupPolicy: "disabled"` (ou conservez une liste d’autorisation vide).
```

Channel messages are mention-gated by default.

```
Le controle des mentions est gere via `channels.slack.channels` (definissez `requireMention` sur `true`) ; `agents.list[].groupChat.mentionPatterns` (ou `messages.groupChat.mentionPatterns`) comptent egalement comme mentions.
```

Commands and slash behavior¶

• Par defaut, le mode natif est desactive pour Slack, sauf si vous definissez channels.slack.commands.native: true (la valeur globale commands.native est "auto", ce qui laisse Slack desactive).
• { channels: { slack: { enabled: true, appToken: "xapp-...", botToken: "xoxb-...", userToken: "xoxp-...", userTokenReadOnly: false, }, }, }
• When native commands are enabled, register matching slash commands in Slack (/<command> names).
• If native commands are not enabled, you can run a single configured slash command via channels.slack.slashCommand.

Default slash command settings:

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

Slash sessions use isolated keys:

• Les commandes slash utilisent des sessions agent:<agentId>:slack:slash:<userId> (prefixe configurable via channels.slack.slashCommand.sessionPrefix).

and still route command execution against the target conversation session (CommandTargetSessionKey).

Threading, sessions, and reply tags¶

• DMs route as direct; channels as channel; MPIMs as group.
• With default session.dmScope=main, Slack DMs collapse to agent main session.
• Les canaux correspondent a des sessions agent:<agentId>:slack:channel:<channelId>.
• Thread replies can create thread session suffixes (:thread:<threadTs>) when applicable.
• channels.slack.thread.historyScope default is thread; thread.inheritParent default is false.
• channels.slack.thread.initialHistoryLimit controls how many existing thread messages are fetched when a new thread session starts (default 20; set 0 to disable).

Fil de reponse

• { channels: { slack: { replyToMode: "off", replyToModeByChatType: { group: "first" }, }, }, }
• { channels: { slack: { replyToMode: "first", replyToModeByChatType: { direct: "off", group: "off" }, }, }, }
• legacy fallback for direct chats: channels.slack.dm.replyToMode

Manual reply tags are supported:

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

Note: replyToMode="off" disables implicit reply threading. Explicit [[reply_to_*]] tags are still honored.

Media, chunking, and delivery¶

Slack file attachments are downloaded from Slack-hosted private URLs (token-authenticated request flow) and written to the media store when fetch succeeds and size limits permit.

```
Les televersements de medias sont limites par `channels.slack.mediaMaxMb` (par defaut 20).
```

- text chunks use channels.slack.textChunkLimit (default 4000) - channels.slack.chunkMode="newline" enables paragraph-first splitting - file sends use Slack upload APIs and can include thread replies (thread_ts) - outbound media cap follows channels.slack.mediaMaxMb when configured; otherwise channel sends use MIME-kind defaults from media pipeline

Preferred explicit targets:

```
- `user:<id>` for DMs
- `channel:<id>` for channels

Slack DMs are opened via Slack conversation APIs when sending to user targets.
```

Actions and gates¶

Les actions d’outils Slack peuvent etre controlees via channels.slack.actions.* :

Available action groups in current Slack tooling:

Groupe d’actions	Par défaut
messages	active
reactions	active
pins	active
memberInfo	active
emojiList	active

Events and operational behavior¶

• Message edits/deletes/thread broadcasts are mapped into system events.
• Reaction add/remove events are mapped into system events.
• Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
• channel_id_changed can migrate channel config keys when configWrites is enabled.
• Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.

React + lister les reactions¶

ackReaction sends an acknowledgement emoji while OpenClaw is processing an inbound message.

Resolution order:

• ouchannels.slack.channels..ackReaction`
• channels.slack.ackReaction
• replyToMode
• agent identity emoji fallback (agents.list[].identity.emoji, else "👀")

Notes

• Slack expects shortcodes (for example "eyes").
• Use "" to disable the reaction for a channel or account.

Manifest and scope checklist¶

{
  "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",
        "groups:read",
        "groups:write",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "users:read",
        "app_mentions:read",
        "reactions:read",
        "reactions:write",
        "pins:read",
        "pins:write",
        "emoji:read",
        "commands",
        "files:read",
        "files:write"
      ],
      "user": [
        "channels:history",
        "channels:read",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "mpim:history",
        "mpim:read",
        "users:read",
        "reactions:read",
        "pins:read",
        "emoji:read",
        "search:read"
      ]
    }
  },
  "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"
      ]
    }
  }
}

If you configure channels.slack.userToken, typical read scopes are:

```
`channels:history`, `groups:history`, `im:history`, `mpim:history`
https://docs.slack.dev/reference/methods/conversations.history
```

Problemes courants¶

Check, in order:

```
`users` : liste d’autorisation utilisateur optionnelle par canal.
```

openclaw channels status --probe
openclaw logs --follow
openclaw doctor

Check:

```
`allowlist` exige que les canaux soient listes dans `channels.slack.channels`.
```

openclaw pairing list slack

Creez une application Slack et activez le Mode socket.

Validate:

```
- signing secret
- webhook path
- Slack Request URLs (Events + Interactivity + Slash Commands)
- unique `webhookPath` per HTTP account
```

Verify whether you intended:

```
- native command mode (`channels.slack.commands.native: true`) with matching slash commands registered in Slack
- or single slash command mode (`channels.slack.slashCommand.enabled: true`)

Also check `commands.useAccessGroups` and channel/user allowlists.
```

Configuration reference pointers¶

Priorite :

• users:read (recherche d’utilisateurs) https://docs.slack.dev/reference/methods/users.info

High-signal Slack fields:

• mode/auth: mode, botToken, appToken, signingSecret, webhookPath, accounts.*
• DM access: dm.enabled, dmPolicy, allowFrom (legacy: dm.policy, dm.allowFrom), dm.groupEnabled, dm.groupChannels
• allow : autoriser/refuser le canal lorsque groupPolicy="allowlist".
• Repli sur messages.groupChat.historyLimit.
• delivery: textChunkLimit, chunkMode, mediaMaxMb
• ops/features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

Related¶

• Pairing
• channel : canaux standards (publics/prives)
• Troubleshooting
• Configuration
• Liste complete des commandes + configuration : Slash commands