Skip to main content

Slack

Status: production-ready for DMs + channels via Slack HTTP Events API.

ClawCentral

In ClawCentral, add your Slack credentials in Admin UI → Settings → Tenant Settings → Secrets. Add SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET as key-value pairs (optionally SLACK_APP_TOKEN too). Then set your Slack app's Request URL (Events, Interactivity, and Slash Commands) to https://<tenant>.clawcentral.io/events/slack. For slash commands, use https://<tenant>.clawcentral.io/commands/slack.

Alternatively, ask your agent to configure Slack — it can save credentials directly via the config_write tool when channel write permissions are enabled.

Pairing

Slack DMs default to pairing mode.

Slash commands

Native command behavior and command catalog.

Channel troubleshooting

Cross-channel diagnostics and repair playbooks.

Quick setup​

  1. Create a Slack app

    Go to api.slack.com/apps and click Create New App → From scratch.

    Name your app and choose your workspace.

  2. Configure OAuth scopes and install the app

    Under OAuth & Permissions → Scopes → Bot Token Scopes, add:

    • chat:write
    • channels:history, channels:read
    • groups:history, groups:read
    • 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
    • assistant:write (optional; required for native streaming)

    Click Install to Workspace and copy your Bot Token (xoxb-...).

  3. Copy your Signing Secret

    Go to Basic Information → App Credentials and copy your Signing Secret.

  4. Set your credentials

    ClawCentral: Go to Admin UI → Settings → Tenant Settings → Secrets and add your SLACK_BOT_TOKEN and SLACK_SIGNING_SECRET as key-value pairs. Optionally add SLACK_APP_TOKEN for extended features.

    Self-hosted OpenClaw: Configure via config file:

    {
      channels: {
        slack: {
          enabled: true,
          botToken: "xoxb-...",
          signingSecret: "your-signing-secret",
        },
      },
    }

    Env fallback (default account only):

    SLACK_BOT_TOKEN=xoxb-...
    SLACK_SIGNING_SECRET=...
  5. Enable Event Subscriptions

    In your Slack app settings, go to Event Subscriptions and toggle Enable Events.

    Set the Request URL to:

    • ClawCentral: https://<tenant>.clawcentral.io/events/slack
    • Self-hosted: your gateway URL + /events/slack (or your configured webhookPath)

    Subscribe to these 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

    Also enable App Home → Messages Tab for DMs.

  6. Enable Interactivity

    Go to Interactivity & Shortcuts and toggle it on.

    Set the Request URL to the same URL as your Events endpoint.

  7. Set up Slash Commands (optional)

    Go to Slash Commands and create a command (e.g., /openclaw).

    Set the Request URL to:

    • ClawCentral: https://<tenant>.clawcentral.io/commands/slack
    • Self-hosted: your gateway URL + /commands/slack

    Reinstall the app to your workspace after adding slash commands.

Token model​

  • HTTP mode requires botToken + signingSecret.
  • Config tokens override env fallback.
  • SLACK_BOT_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.
tip

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.

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​

Inbound attachments

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.

Outbound text and files
  • 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
Delivery targets

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:

GroupDefault
messagesenabled
reactionsenabled
pinsenabled
memberInfoenabled
emojiListenabled

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.

App manifest example​

Slack app manifest (HTTP Events API)
{
  "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": {
    "event_subscriptions": {
      "request_url": "https://<tenant>.clawcentral.io/events/slack",
      "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"
      ]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://<tenant>.clawcentral.io/events/slack"
    }
  }
}
Optional user-token scopes (read operations)

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​

No replies in channels

Check, in order:

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

Useful commands (self-hosted only):

openclaw channels status --probe
openclaw logs --follow
openclaw doctor
DM messages ignored

Check:

  • channels.slack.dm.enabled
  • channels.slack.dmPolicy (or legacy channels.slack.dm.policy)
  • pairing approvals / allowlist entries
HTTP mode not receiving events

Validate:

  • signing secret is correct
  • Request URLs are set correctly in Slack app settings (Events, Interactivity, Slash Commands)
  • The Slack app has been reinstalled after URL changes
  • SLACK_SIGNING_SECRET / signingSecret is set correctly
Native/slash commands not firing

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:

    • auth: botToken, signingSecret, 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