Slack

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

Quick setup

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.

Access control and routing

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

Actions and gates

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

Available action groups in current Slack tooling:

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.

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

Troubleshooting

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

openclaw pairing list slack

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

Related

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