Skip to main content

​
Slack

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

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 Slack app and tokens

In Slack app settings:
  • enable Socket Mode
  • create App Token (xapp-...) with connections:write
  • install app and copy Bot Token (xoxb-...)
2

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-...
3

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.
4

Start gateway

openclaw gateway

​
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)
Pairing in DMs uses openclaw pairing approve slack <code>.

​
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).
  • 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:
  • 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 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.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:
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.
  • 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.

​
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",
        "mpim:history",
        "users:read",
        "app_mentions:read",
        "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.

​
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
    • channel access: groupPolicy, channels.*, channels.*.users, channels.*.requireMention
    • threading/history: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
    • delivery: textChunkLimit, chunkMode, mediaMaxMb
    • ops/features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly