openclaw/docs/channels/slack.md

summary	read_when	title
Slack setup and runtime behavior (Socket Mode + HTTP Events API)	Setting up Slack or debugging Slack socket/HTTP mode	Slack

Slack

Status: production-ready for DMs + channels via Slack app integrations. Default mode is Socket Mode; HTTP Events API mode is also supported.

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

Quick setup

In Slack app settings:

    - enable **Socket Mode**
    - create **App Token** (`xapp-...`) with `connections:write`
    - install app and copy **Bot Token** (`xoxb-...`)
  </Step>

  <Step title="Configure OpenClaw">

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

    Env fallback (default account only):

SLACK_APP_TOKEN=xapp-...
SLACK_BOT_TOKEN=xoxb-...

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

    - set mode to HTTP (`channels.slack.mode="http"`)
    - copy Slack **Signing Secret**
    - set Event Subscriptions + Interactivity + Slash command Request URL to the same webhook path (default `/slack/events`)

  </Step>

  <Step title="Configure OpenClaw HTTP mode">

{
  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.
• userToken (xoxp-...) is config-only (no env fallback) and defaults to read-only behavior (userTokenReadOnly: true).
• 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. For writes, bot token remains preferred; user-token writes are only allowed when `userTokenReadOnly: false` and bot token is unavailable.

Access control and routing

`channels.slack.dmPolicy` controls DM access (legacy: `channels.slack.dm.policy`):

- `pairing` (default)
- `allowlist`
- `open` (requires `channels.slack.allowFrom` to include `"*"`; legacy: `channels.slack.dm.allowFrom`)
- `disabled`

DM flags:

- `dm.enabled` (default true)
- `channels.slack.allowFrom` (preferred)
- `dm.allowFrom` (legacy)
- `dm.groupEnabled` (group DMs default false)
- `dm.groupChannels` (optional MPIM allowlist)

Multi-account precedence:

- `channels.slack.accounts.default.allowFrom` applies only to the `default` account.
- Named accounts inherit `channels.slack.allowFrom` when their own `allowFrom` is unset.
- Named accounts do not inherit `channels.slack.accounts.default.allowFrom`.

Pairing in DMs uses `openclaw pairing approve slack <code>`.

`channels.slack.groupPolicy` controls channel handling:

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

Channel allowlist lives under `channels.slack.channels` and should use stable channel IDs.

Runtime note: if `channels.slack` is completely missing (env-only setup), runtime falls back to `groupPolicy="allowlist"` and logs a warning (even if `channels.defaults.groupPolicy` is set).

Name/ID resolution:

- channel allowlist entries and DM allowlist entries are resolved at startup when token access allows
- unresolved channel-name entries are kept as configured but ignored for routing by default
- inbound authorization and channel routing are ID-first by default; direct username/slug matching requires `channels.slack.dangerouslyAllowNameMatching: true`

Channel messages are mention-gated by default.

Mention sources:

- explicit app mention (`<@botId>`)
- mention regex patterns (`agents.list[].groupChat.mentionPatterns`, fallback `messages.groupChat.mentionPatterns`)
- implicit reply-to-bot thread behavior

Per-channel controls (`channels.slack.channels.<id>`; names only via startup resolution or `dangerouslyAllowNameMatching`):

- `requireMention`
- `users` (allowlist)
- `allowBots`
- `skills`
- `systemPrompt`
- `tools`, `toolsBySender`
- `toolsBySender` key format: `id:`, `e164:`, `username:`, `name:`, or `"*"` wildcard
  (legacy unprefixed keys still map to `id:` only)

Commands and slash behavior

• Native command auto-mode is off for Slack (commands.native: "auto" does not enable Slack native commands).
• Enable native Slack command handlers with channels.slack.commands.native: true (or global commands.native: true).
• When native commands are enabled, register matching slash commands in Slack (/<command> names), with one exception:
  • register /agentstatus for the status command (Slack reserves /status)
• If native commands are not enabled, you can run a single configured slash command via channels.slack.slashCommand.
• Native arg menus now adapt their rendering strategy:
  • up to 5 options: button blocks
  • 6-100 options: static select menu
  • more than 100 options: external select with async option filtering when interactivity options handlers are available
  • if encoded option values exceed Slack limits, the flow falls back to buttons
• For long option payloads, Slash command argument menus use a confirm dialog before dispatching a selected value.

Interactive replies

Slack can render agent-authored interactive reply controls, but this feature is disabled by default.

Enable it globally:

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

Or enable it for one Slack account only:

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

When enabled, agents can emit Slack-only reply directives:

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

These directives compile into Slack Block Kit and route clicks or selections back through the existing Slack interaction event path.

Notes:

• This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
• The interactive callback values are OpenClaw-generated opaque tokens, not raw agent-authored values.
• If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload.

Default slash command settings:

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

Slash sessions use isolated keys:

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

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.
• Channel 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).

Reply threading controls:

• channels.slack.replyToMode: off|first|all (default off)
• channels.slack.replyToModeByChatType: per direct|group|channel
• legacy fallback for direct chats: channels.slack.dm.replyToMode

Manual reply tags are supported:

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

Note: replyToMode="off" disables all reply threading in Slack, including explicit [[reply_to_*]] tags. This differs from Telegram, where explicit tags are still honored in "off" mode. The difference reflects the platform threading models: Slack threads hide messages from the channel, while Telegram replies remain visible in the main chat flow.

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.

Runtime inbound size cap defaults to `20MB` unless overridden by `channels.slack.mediaMaxMb`.

- 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

Slack actions are controlled by channels.slack.actions.*.

Available action groups in current Slack tooling:

Group	Default
messages	enabled
reactions	enabled
pins	enabled
memberInfo	enabled
emojiList	enabled

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.
• Assistant thread status updates (for "is typing..." indicators in threads) use assistant.threads.setStatus and require bot scope assistant:write.
• 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.
• Block actions and modal interactions emit structured Slack interaction: ... system events with rich payload fields:
  • block actions: selected values, labels, picker values, and workflow_* metadata
  • modal view_submission and view_closed events with routed channel metadata and form inputs

Ack reactions

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

Resolution order:

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

Notes:

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

Typing reaction fallback

typingReaction adds a temporary reaction to the inbound Slack message while OpenClaw is processing a reply, then removes it when the run finishes. This is a useful fallback when Slack native assistant typing is unavailable, especially in DMs.

Resolution order:

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

Notes:

• Slack expects shortcodes (for example "hourglass_flowing_sand").
• The reaction is best-effort and cleanup is attempted automatically after the reply or failure path completes.

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",
        "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"
      ]
    }
  }
}

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

- `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` (if you depend on Slack search reads)

Troubleshooting

Check, in order:

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

Useful commands:

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

Check:

- `channels.slack.dm.enabled`
- `channels.slack.dmPolicy` (or legacy `channels.slack.dm.policy`)
- pairing approvals / allowlist entries

openclaw pairing list slack

Validate bot + app tokens and Socket Mode enablement in Slack app settings. 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.

Text streaming

OpenClaw supports Slack native text streaming via the Agents and AI Apps API.

channels.slack.streaming controls live preview behavior:

• off: disable live preview streaming.
• partial (default): replace preview text with the latest partial output.
• block: append chunked preview updates.
• progress: show progress status text while generating, then send final text.

channels.slack.nativeStreaming controls Slack's native streaming API (chat.startStream / chat.appendStream / chat.stopStream) when streaming is partial (default: true).

Disable native Slack streaming (keep draft preview behavior):

channels:
  slack:
    streaming: partial
    nativeStreaming: false

Legacy keys:

• channels.slack.streamMode (replace | status_final | append) is auto-migrated to channels.slack.streaming.
• boolean channels.slack.streaming is auto-migrated to channels.slack.nativeStreaming.

Requirements

1. Enable Agents and AI Apps in your Slack app settings.
2. Ensure the app has the assistant:write scope.
3. A reply thread must be available for that message. Thread selection still follows replyToMode.

Behavior

• First text chunk starts a stream (chat.startStream).
• Later text chunks append to the same stream (chat.appendStream).
• End of reply finalizes stream (chat.stopStream).
• Media and non-text payloads fall back to normal delivery.
• If streaming fails mid-reply, OpenClaw falls back to normal delivery for remaining payloads.

Configuration reference pointers

Primary reference:

• 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
  • compatibility toggle: dangerouslyAllowNameMatching (break-glass; keep off unless needed)
  • channel access: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
  • threading/history: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
  • delivery: textChunkLimit, chunkMode, mediaMaxMb, streaming, nativeStreaming
  • ops/features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

Related

• Pairing
• Channel routing
• Troubleshooting
• Configuration
• Slash commands

Attachment vision reference

This section documents Slack attachment handling for image and file vision flows, including supported types, the inbound pipeline, and known limits.

Supported media types

Media type	Source	Vision pipeline	Notes
JPEG / PNG / GIF / WebP images	Slack file URL	✅ via media-understanding	Size cap: channels.slack.mediaMaxMb (default 20 MB)
PDF files	Slack file URL	✅ via media-understanding	Converted to images before analysis
Other files	Slack file URL	❌ text extraction only	Binary files stored as-is; vision not applied
Thread-root messages	Inherited context	✅ images processed	Reply context inherits parent attachments
Multi-image messages	Multiple files	✅ each processed	Each attachment evaluated independently

Inbound pipeline

When a Slack message with file attachments arrives:

1. OpenClaw downloads the file from Slack's private URL using the bot token (xoxb-...).
2. The file is written to the media store on success.
3. For supported image types, the media-understanding pipeline is invoked.
4. For PDF files, the file is first converted to images via the configured PDF converter, then passed to vision.
5. Vision output (extracted text, descriptions, analysis) is injected into the message context.
6. Thread-root messages propagate their attachments to replies in the same thread via thread_ts inheritance.

Thread-root attachment inheritance

When a message arrives in a thread (has a thread_ts parent):

• If the root message contains image/file attachments, those attachments are available to subsequent replies in the thread.
• The thread-starter media fallback logic ensures root-message attachments are included in context even when the reply message itself has no files.
• This applies to both DM threads and channel threads.

Multi-attachment handling

When a single Slack message contains multiple file attachments:

• Each attachment is processed independently through the media pipeline.
• The vision results are aggregated and all are injected into the message context.
• Processing order follows Slack's file order in the event payload.
• A failure in one attachment's download or vision processing does not block others.

Size and format limits

• Size cap: Default 20 MB per file. Configurable via channels.slack.mediaMaxMb.
• Unsupported formats: Files that Slack cannot serve (expired URLs, quota-exceeded) skip download silently.
• Vision model: Determined by the agent's configured vision provider (e.g., GPT-4o, Claude, Gemini). If no vision-capable model is configured, attachments are stored but not analyzed.

Known limits

Scenario	Current behavior	Workaround
Expired Slack file URL	File skipped; no error shown	Re-upload the file in Slack
Vision model not configured	Attachments stored; no analysis	Configure a vision-capable model in llm.providers
Very large images (> 20 MB)	Skipped per size cap	Increase mediaMaxMb if Slack allows
Forwarded/shared attachments	May not preserve original file URL	Re-share directly in the OpenClaw thread
Image-only root thread (no text)	Attachments still processed	✅ Supported

Related documentation

• Media understanding pipeline
• Epic: #51349 — Slack attachment vision enablement
• Regression tests: #51353
• Live verification: #51354