Slack¶

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

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** → installieren Sie die App und kopieren Sie das **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>

    ```
    Verwenden Sie den HTTP-Webhook-Modus, wenn Ihr Gateway für Slack über HTTPS erreichbar ist (typisch für Server-Deployments). Der HTTP-Modus verwendet die Events API + Interactivity + Slash Commands mit einer gemeinsamen Request-URL.
    ```

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

    </Step>

    <Step title="Use unique webhook paths for multi-account HTTP">
      Per-account HTTP mode is supported.

      Give each account a distinct `webhookPath` so registrations do not collide.
    </Step>
  </Steps>

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.
Beispiel mit explizit gesetztem userTokenReadOnly (User-Token-Schreibzugriffe erlauben):
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. Selbst mit userTokenReadOnly: false bleibt das Bot-Token für Schreibzugriffe bevorzugt, wenn es verfügbar ist.

Access control and routing¶

DMs werden ignoriert: Absender nicht freigegeben bei channels.slack.dm.policy="pairing".

```
Um alle zuzulassen: Setzen Sie `channels.slack.dm.policy="open"` und `channels.slack.dm.allowFrom=["*"]`.
```

channels.slack.groupPolicy steuert die Kanalbehandlung (open|disabled|allowlist).

```
Um **keine Kanäle** zuzulassen, setzen Sie `channels.slack.groupPolicy: "disabled"` (oder behalten Sie eine leere Allowlist).
```

Channel messages are mention-gated by default.

```
Erwähnungs-Gating wird über `channels.slack.channels` gesteuert (setzen Sie `requireMention` auf `true`); `agents.list[].groupChat.mentionPatterns` (oder `messages.groupChat.mentionPatterns`) zählen ebenfalls als Erwähnungen.
```

Commands and slash behavior¶

Slack-Slash-Commands werden in der Slack-App verwaltet und nicht automatisch entfernt.
{ 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).
Wenn Sie native Commands aktivieren, fügen Sie einen slash_commands-Eintrag pro Command hinzu, den Sie bereitstellen möchten (entsprechend der /help-Liste). Überschreiben Sie dies mit channels.slack.commands.native.

Default slash command settings:

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

Slash sessions use isolated keys:

Slash Commands verwenden agent:<agentId>:slack:slash:<userId>-Sitzungen (Präfix konfigurierbar über channels.slack.slashCommand.sessionPrefix).

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

Threading, sessions, and reply tags¶

Gruppen-DMs threaden, Kanäle im Root belassen:
With default session.dmScope=main, Slack DMs collapse to agent main session.
Kanäle werden auf agent:<agentId>:slack:channel:<channelId>-Sitzungen abgebildet.
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.historyLimit (oder channels.slack.accounts.*.historyLimit) steuert, wie viele aktuelle Kanal-/Gruppennachrichten in den Prompt eingebettet werden.

Antwort-Threading

{ channels: { slack: { replyToMode: "off", replyToModeByChatType: { group: "first" }, }, }, }
{ channels: { slack: { replyToMode: "first", replyToModeByChatType: { direct: "off", group: "off" }, }, }, }
Legacy channels.slack.dm.replyToMode wird weiterhin als Fallback für direct akzeptiert, wenn kein Chat-Typ-Override gesetzt ist.

Manual reply tags are supported:

[[reply_to_current]]
[[reply_to:<id>]] — Antwort auf eine bestimmte Nachrichten-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.

```
Medien-Uploads sind durch `channels.slack.mediaMaxMb` begrenzt (Standard: 20).
```

Ausgehender Text wird in Blöcke von channels.slack.textChunkLimit aufgeteilt (Standard: 4000).

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¶

Slack-Tool-Aktionen können mit channels.slack.actions.* eingeschränkt werden:

Available action groups in current Slack tooling:

Aktionsgruppe	Standard
messages	aktiviert
reactions	aktiviert
pins	aktiviert
memberInfo	aktiviert
emojiList	aktiviert

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.

Reagieren + Reaktionen auflisten¶

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

Resolution order:

Für Multi-Account setzen Sie channels.slack.accounts.<id>.ackReaction
channels.slack.ackReaction
replyToMode
agent identity emoji fallback (agents.list[].identity.emoji, else "👀")

Hinweise

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](https://docs.slack.dev/reference/methods/conversations.history)
```

Fehlerbehebung¶

Check, in order:

```
`users`: optionale kanalweise Benutzer-Allowlist.
```

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

Check:

```
`allowlist` erfordert, dass Kanäle in `channels.slack.channels` aufgeführt sind.
```

openclaw pairing list slack

Erstellen Sie eine Slack-App und aktivieren Sie den Socket-Modus.

Validate:

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

Verify whether you intended:

```
Verbunden, aber keine Kanalantworten: Kanal durch `groupPolicy` blockiert oder nicht in der `channels.slack.channels`-Allowlist.
```

Configuration reference pointers¶

Priorität:

Configuration reference - Slack

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: Kanal erlauben/verbieten, wenn groupPolicy="allowlist".
Fällt zurück auf messages.groupChat.historyLimit.
delivery: textChunkLimit, chunkMode, mediaMaxMb
ops/features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

Pairing
channel: Standardkanäle (öffentlich/privat)
Für den Triage-Ablauf: /channels/troubleshooting.
Configuration
Vollständige Command-Liste + Konfiguration: Slash commands