Slack Integration: Socket Mode, HTTP URLs, and Relay Mode

Slack integration handles DMs and channels through Slack app integrations. Socket Mode serves as the default transport, with HTTP Request URLs also available. Relay mode targets managed deployments where a trusted router controls Slack ingress.

• Pairing, Slack DMs operate in pairing mode by default.

• Slash commands, Built-in command behavior and command catalog.

• Channel troubleshooting, Cross-channel diagnostics and repair playbooks.

Choosing a transport

For messaging, slash commands, App Home, and interactivity, Socket Mode and HTTP Request URLs offer equivalent functionality. Choose based on deployment architecture rather than feature differences.

Note

Choose Socket Mode for single-Gateway hosts, dev laptops, and on-prem networks that can reach *.slack.com outbound but cannot accept inbound HTTPS.

Choose HTTP Request URLs when running multiple Gateway replicas behind a load balancer, when outbound WSS is blocked but inbound HTTPS is allowed, or when you already terminate Slack webhooks at a reverse proxy.

Warning

For a single app, Slack may keep multiple Socket Mode connections active and route any payload to any of them. Separate OpenClaw gateways sharing one Slack app must therefore have matching routing and authorization configuration. Otherwise, use a separate Slack app per gateway, a single relay ingress, or HTTP Request URLs behind a load balancer. See Using Socket Mode.

Relay mode

Relay mode decouples Slack ingress from the OpenClaw gateway. A trusted router owns the sole Slack Socket Mode connection, selects a destination gateway, and forwards a typed event over an authenticated websocket. The gateway continues to use its own bot token for outbound Slack Web API calls.

{
  channels: {
    slack: {
      mode: "relay",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      relay: {
        url: "wss://router.example.com/gateway/ws",
        authToken: { source: "env", provider: "default", id: "SLACK_RELAY_AUTH_TOKEN" },
        gatewayId: "team-gateway",
      },
    },
  },
}

Unless it targets localhost, the relay URL must use wss://. Consider the bearer token and router route table part of the Slack authorization boundary: routed events enter the normal Slack message handler as authorized activations. A router-provided slack_identity in the websocket hello frame can set the default outbound username and icon; an explicit identity supplied by the caller still wins. The relay connection reconnects with the same bounded backoff timing as Socket Mode and clears the router-provided identity whenever it disconnects.

Enterprise Grid org-wide installs

With an Enterprise Grid org-wide installation, a single Slack account can receive messages and interactions from every workspace it covers. Choose direct Socket Mode or HTTP Request URLs; relay mode is not supported for enterprise accounts. Both least-privilege manifests below enable the Enterprise message, mention, reaction, pin, channel-created, and channel-renamed event paths, immediate replies, listener-owned status reactions, Slack interactivity for Block Kit actions and modal submissions, and the single /openclaw slash command.

Socket Mode

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "mpim:history",
        "mpim:read",
        "pins:read",
        "reactions:read",
        "reactions:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "org_deploy_enabled": true,
    "socket_mode_enabled": true,
    "interactivity": { "is_enabled": true },
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "channel_created",
        "channel_rename",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "member_joined_channel",
        "member_left_channel",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    }
  }
}

An Enterprise Grid Org Admin or Org Owner must approve the app, install it at the organization level, and select the workspaces the installation covers. Before starting OpenClaw, confirm that the app is available in every intended workspace. Generate an app-level token with connections:write for Socket Mode, then copy the bot token from the org installation. Configure the account that uses the org-installed bot token:

{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      slashCommand: { enabled: true, name: "openclaw" },
      dmPolicy: "open",
      allowFrom: ["*"],
      groupPolicy: "allowlist",
      channels: {
        C0123456789: { requireMention: true },
      },
    },
  },
}

HTTP Request URLs

Use HTTP mode when the Gateway has a public HTTPS endpoint and does not open a Socket Mode connection. Replace the example URL with the Gateway's public webhookPath URL (default /slack/events):

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false,
        "url": "https://gateway-host.example.com/slack/events"
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "mpim:history",
        "mpim:read",
        "pins:read",
        "reactions:read",
        "reactions:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "org_deploy_enabled": true,
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://gateway-host.example.com/slack/events"
    },
    "event_subscriptions": {
      "request_url": "https://gateway-host.example.com/slack/events",
      "bot_events": [
        "app_mention",
        "channel_created",
        "channel_rename",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "member_joined_channel",
        "member_left_channel",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    }
  }
}

An Enterprise Grid Org Admin or Org Owner must approve the app, install it at the organization level, and select the workspaces the installation covers. After Slack verifies the Request URL, copy the org installation's bot token and the app's Basic Information -> App Credentials -> Signing Secret. Configure the enterprise account with the same Request URL path:

{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      signingSecret: {
        source: "env",
        provider: "default",
        id: "SLACK_SIGNING_SECRET",
      },
      slashCommand: { enabled: true, name: "openclaw" },
      webhookPath: "/slack/events",
      dmPolicy: "open",
      allowFrom: ["*"],
      groupPolicy: "allowlist",
      channels: {
        "team:T0123456789:channel:C0123456789": { requireMention: true },
      },
    },
  },
}

For each selected workspace, open it in Slack's web app and copy the T... workspace ID from https://app.slack.com/client/T.../.... Use that workspace ID with the channel's C... ID in every qualified policy key, as shown above.

At startup, OpenClaw uses Slack auth.test to determine whether the token belongs to a workspace installation or an Enterprise Grid org-wide installation. No installation-mode setting is required. Slack remains the source of truth for which workspaces have granted the installation; OpenClaw then applies the configured channel, user, DM, and mention policies to each delivered event. Enterprise installs reject bot-authored message and app_mention events by default. Set allowBots on the account or channel to admit them under the same loop-prevention rules used by workspace installs. OpenClaw retains the org installation's auth.test user_id and bot_id for that check.

Enterprise support accepts direct Socket Mode or HTTP message, mention, membership, reaction, pin, channel-created, channel-renamed, Block Kit action, modal, and configured shortcut and slash-command payloads plus workspace-qualified outbound messages and presence polling. Add any shortcuts to the app manifest's features.shortcuts list; OpenClaw accepts their callback IDs through the same interaction path. The manifest examples register the single /openclaw command; native command mode still requires the administrator-managed command entries described below. Relay mode, channel-ID-change events, App Home, Agent and Assistant lifecycle events, configured ACP bindings, and runtime current-conversation bindings remain unavailable for an enterprise account. Static agent route bindings are supported when a binding without a peer specifies match.teamId, or a peer ID uses team:<team-id>:channel:<channel-id> or team:<team-id>:user:<user-id>. Slack-native approvals that originate from a delivered, workspace-qualified Slack turn are supported; approval buttons use the same listener-owned, workspace-scoped interaction path. Slack action tools are supported for enterprise accounts across every group listed in Actions and gates; the configured channels.slack.actions.* gates and OAuth scopes still apply. Inbound membership, reaction, pin, channel-created, and channel-renamed notifications use validated listener-owned, workspace-scoped event routing. Outbound acknowledgment, typing, and status reactions are also supported through that client and require reactions:write.

OpenClaw records Enterprise Grid destinations as team:<team-id>:channel:<channel-id> or team:<team-id>:user:<user-id>. Current-conversation Slack tool actions inherit that workspace. Detached or proactive calls must provide a workspace-qualified target; bare channel and user IDs fail closed because those IDs can be reused by different workspaces. Actions without a destination parameter, such as member-info and emoji-list, require trusted current Slack conversation context.

Immediate replies follow the same Slack delivery path used for chunks, media, metadata, identity fallback, unfurls, and receipts, but only during the active event turn while the validated listener-owned client is available. The in-memory send queue and thread-participation records are separated by that event's workspace; the client itself is never serialized or persisted.

Enterprise channel policy keys must use team:<team-id>:channel:<channel-id> or the "*" wildcard. dm.groupChannels requires the workspace-qualified form and does not accept "*". A delivered Enterprise event never falls back from its qualified workspace and channel identity to a bare channel ID. Workspace installations retain raw stable channel IDs and channel:<id> compatibility. The channel prefixes slack:, group:, and mpim: fail startup.

Enterprise user policy entries in allowFrom, reactionAllowlist, and per-channel users accept raw stable Slack user IDs, slack:<user-id>, user:<user-id>, team:<team-id>:user:<user-id>, or "*". Unqualified entries compare only the user ID and can match an org-wide user in any workspace. Qualified entries compare both the workspace and user ID. Enterprise toolsBySender keys accept raw stable user IDs, id:<user-id>, channel:slack:<user-id>, or "*". Names, slugs, display names, and email addresses fail startup. IDs must use Slack's canonical uppercase prefix and body (for example, C0123456789 or U0123456789); lowercase and short lookalikes fail startup. Enterprise accounts cannot enable dangerouslyAllowNameMatching. Enterprise accounts may set the global mentionPatterns.mode. Enterprise mentionPatterns.allowIn and mentionPatterns.denyIn entries use team:<team-id>:channel:<channel-id>; bare channel IDs fail startup because they can be reused across workspaces. Workspace installs retain the existing bare-channel scoped mention-pattern behavior. Each accepted workspace gets separate routing, session, transcript, dedupe, history, and cache identity even when Slack IDs overlap. Within the message stream, ordinary user messages and user-authored file_share events are supported; other message subtypes are rejected before authorization or system-event handling.

Enterprise DMs support the same disabled, open, allowlist, and pairing policies as workspace installs. Pairing approvals are stored as team:<team-id>:user:<user-id> and are applied only to events from that workspace. Explicit account allowFrom entries can omit the workspace for an org-wide user ID or include it to limit access to one workspace; channel and sender policy continues to apply to channel messages.

Install

openclaw plugins install @openclaw/slack

The plugin gets registered and enabled through plugins install. Until you set up the Slack app and channel settings described below, it remains inactive. For general plugin install rules, see Plugins.

Quick setup

The manifests in this section create a workspace-scoped installation. For an Enterprise Grid organization installation, use the dedicated org-wide manifest and workflow instead.

Socket Mode (default)

Create a new Slack app

Go to api.slack.com/apps → Create New App → From a manifest → select your workspace → paste one of the manifests below → Next → Create.

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "app_home": {
      "home_tab_enabled": true,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "OpenClaw connects Slack Agent View conversations to OpenClaw agents.",
      "suggested_prompts": [
        { "title": "What can you do?", "message": "What can you help me with?" },
        {
          "title": "Summarize this channel",
          "message": "Summarize the recent activity in this channel."
        },
        { "title": "Draft a reply", "message": "Help me draft a reply." }
      ]
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "assistant:write",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "emoji:read",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:read",
        "pins:write",
        "reactions:read",
        "reactions:write",
        "usergroups:read",
        "users:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "channel_rename",
        "member_joined_channel",
        "member_left_channel",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    }
  }
}

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "app_home": {
      "home_tab_enabled": true,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "OpenClaw connects Slack Agent View conversations to OpenClaw agents.",
      "suggested_prompts": [
        { "title": "What can you do?", "message": "What can you help me with?" },
        {
          "title": "Summarize this channel",
          "message": "Summarize the recent activity in this channel."
        },
        { "title": "Draft a reply", "message": "Help me draft a reply." }
      ]
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "assistant:write",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "message.channels",
        "message.groups",
        "message.im"
      ]
    }
  }
}

Note

Recommended matches the Slack plugin's full feature set: App Home, slash commands, files, reactions, pins, group DMs, and emoji/usergroup reads. Pick Minimal when workspace policy restricts scopes, it covers DMs, channel/group history, mentions, and slash commands but drops files, reactions, pins, group-DM (mpim:*), emoji:read, and usergroups:read. See Manifest and scope checklist for per-scope rationale and additive options like extra slash commands.

Once the app is created by Slack:

• Basic Information -> App-Level Tokens -> Generate Token and Scopes: add connections:write, save, copy the App-Level Token.
• Install App -> Install to Workspace: copy the Bot User OAuth Token.

Configure OpenClaw

Recommended SecretRef setup:

export SLACK_APP_TOKEN=slack-app-token-example
export SLACK_BOT_TOKEN=slack-bot-token-example
cat > slack.socket.patch.json5 <<'JSON5'
{
  channels: {
    slack: {
      enabled: true,
      mode: "socket",
      appToken: { source: "env", provider: "default", id: "SLACK_APP_TOKEN" },
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
    },
  },
}
JSON5
openclaw config patch --file ./slack.socket.patch.json5 --dry-run
openclaw config patch --file ./slack.socket.patch.json5

Default-account credential fallback after channels.slack is configured:

SLACK_APP_TOKEN=slack-app-token-example
SLACK_BOT_TOKEN=slack-bot-token-example

Start gateway

openclaw gateway

HTTP Request URLs

Create a new Slack app

Open api.slack.com/apps → Create New App → From a manifest → select your workspace → paste one of the manifests below → replace https://gateway-host.example.com/slack/events with your public Gateway URL → Next → Create.

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "app_home": {
      "home_tab_enabled": true,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "OpenClaw connects Slack Agent View conversations to OpenClaw agents.",
      "suggested_prompts": [
        { "title": "What can you do?", "message": "What can you help me with?" },
        {
          "title": "Summarize this channel",
          "message": "Summarize the recent activity in this channel."
        },
        { "title": "Draft a reply", "message": "Help me draft a reply." }
      ]
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false,
        "url": "https://gateway-host.example.com/slack/events"
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "assistant:write",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "emoji:read",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:read",
        "pins:write",
        "reactions:read",
        "reactions:write",
        "usergroups:read",
        "users:read"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://gateway-host.example.com/slack/events",
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "channel_rename",
        "member_joined_channel",
        "member_left_channel",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://gateway-host.example.com/slack/events",
      "message_menu_options_url": "https://gateway-host.example.com/slack/events"
    }
  }
}

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "app_home": {
      "home_tab_enabled": true,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "OpenClaw connects Slack Agent View conversations to OpenClaw agents.",
      "suggested_prompts": [
        { "title": "What can you do?", "message": "What can you help me with?" },
        {
          "title": "Summarize this channel",
          "message": "Summarize the recent activity in this channel."
        },
        { "title": "Draft a reply", "message": "Help me draft a reply." }
      ]
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false,
        "url": "https://gateway-host.example.com/slack/events"
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "assistant:write",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "users:read"
      ]
    }
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://gateway-host.example.com/slack/events",
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "message.channels",
        "message.groups",
        "message.im"
      ]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://gateway-host.example.com/slack/events",
      "message_menu_options_url": "https://gateway-host.example.com/slack/events"
    }
  }
}

Note

The Recommended tier covers everything the Slack plugin offers; Minimal strips out files, reactions, pins, group-DM (mpim:*), emoji:read, and usergroups:read for constrained workspaces. Per-scope explanations live in the Manifest and scope checklist.

Info

All three URL fields (slash_commands[].url, event_subscriptions.request_url, and interactivity.request_url / message_menu_options_url) resolve to the same OpenClaw endpoint. Slack's manifest schema demands separate names for them, yet OpenClaw dispatches by payload type, so a single webhookPath (default /slack/events) suffices. In HTTP mode, slash commands lacking slash_commands[].url quietly do nothing.

Once Slack has created the app:

• Basic Information → App Credentials: grab the Signing Secret to verify requests.
• Install App -> Install to Workspace: copy the Bot User OAuth Token.

Configure OpenClaw

Recommended SecretRef setup:

export SLACK_BOT_TOKEN=slack-bot-token-example
export SLACK_SIGNING_SECRET=...
cat > slack.http.patch.json5 <<'JSON5'
{
  channels: {
    slack: {
      enabled: true,
      mode: "http",
      botToken: { source: "env", provider: "default", id: "SLACK_BOT_TOKEN" },
      signingSecret: { source: "env", provider: "default", id: "SLACK_SIGNING_SECRET" },
      webhookPath: "/slack/events",
    },
  },
}
JSON5
openclaw config patch --file ./slack.http.patch.json5 --dry-run
openclaw config patch --file ./slack.http.patch.json5

Note

Use distinct webhook paths for multi-account HTTP

Assign each account its own webhookPath (default /slack/events) so registrations never overlap.

Start gateway

openclaw gateway

User identity (post as a real person)

With user identity, OpenClaw can read and post as the human who grants the Slack app authorization. The userToken serves as the acting identity; a separate companion Slack app handles Events API traffic via Socket Mode or an HTTP Request URL. That companion app needs neither a bot user nor a bot token.

Configure the companion app this way:

1. In OAuth & Permissions -> User Token Scopes, add these user-scoped permissions:

   • history: channels:history, groups:history, im:history, mpim:history
   • conversation lookup: channels:read, groups:read, im:read, mpim:read
   • people: users:read
   • posting: chat:write (the authorizing user appears as the sender)
   • opening DMs: im:write, mpim:write

2. In Event Subscriptions -> Subscribe to events on behalf of users, add these user events. Keep them out of the bot-events list:

   • message.channels
   • message.groups
   • message.im
   • message.mpim

3. Pick one event transport:

   • Socket Mode: turn on Socket Mode and generate an app-level token with connections:write. Set it as appToken.
   • HTTP Request URL: aim Event Subscriptions at the public OpenClaw Slack endpoint and copy Basic Information -> App Credentials -> Signing Secret. Set it as signingSecret.

4. Install or reinstall the app, authorize it as the intended human, and drop the resulting user OAuth token into userToken.

Socket Mode configuration:

{
  channels: {
    slack: {
      postAs: "user",
      userToken: "<xoxp>",
      appToken: "<xapp>",
    },
  },
}

HTTP Request URL configuration:

{
  channels: {
    slack: {
      postAs: "user",
      mode: "http",
      userToken: "<xoxp>",
      signingSecret: "<signing-secret>",
      webhookPath: "/slack/events",
    },
  },
}

Warning

DMs and group DMs only work through the user-scope event subscription described above. A bot cannot enter a human 1:1 DM or get added to an existing group DM. The companion app stays invisible: other Slack members see messages from the authorizing human, never from an OpenClaw bot.

OpenClaw automatically discards user-scope message events that the resolved human identity authored, so its own sent messages never trigger self-replies.

Socket Mode transport tuning

For Socket Mode, OpenClaw sets the Slack SDK client pong timeout to 15 seconds. This value is baked in and cannot be changed by operators.

Notes:

• The channels.slack.socketMode object, which includes clientPingTimeout, serverPingTimeout, and pingPongLoggingEnabled, is deprecated and no longer read at runtime. openclaw doctor flags retired layout tuning knobs with a generic notice instead of a per-key path. openclaw doctor --fix deletes those three fields wherever they sit, at the channel root and under accounts.<accountId>, and removes the socketMode object once it becomes empty. Any other key you placed inside it stays untouched, so remove it manually.
• App messages and events count as application state, not as transport liveness signals.
• Socket Mode restart backoff starts near 2 seconds and tops out near 30 seconds. Recoverable start, start-wait, and disconnect failures keep retrying until the channel stops. Permanent account and credential problems, such as invalid auth, revoked tokens, or missing scopes, fail fast rather than retrying endlessly.

Manifest and scope checklist

The base Slack app manifest stays identical for Socket Mode and HTTP Request URLs. Only the settings block (and the slash command url) changes.

Base manifest (Socket Mode default):

{
  "display_information": {
    "name": "OpenClaw",
    "description": "Slack connector for OpenClaw"
  },
  "features": {
    "bot_user": { "display_name": "OpenClaw", "always_online": true },
    "app_home": {
      "home_tab_enabled": true,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "agent_view": {
      "agent_description": "OpenClaw connects Slack Agent View conversations to OpenClaw agents.",
      "suggested_prompts": [
        { "title": "What can you do?", "message": "What can you help me with?" },
        {
          "title": "Summarize this channel",
          "message": "Summarize the recent activity in this channel."
        },
        { "title": "Draft a reply", "message": "Help me draft a reply." }
      ]
    },
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false
      }
    ]
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "assistant:write",
        "channels:history",
        "channels:read",
        "chat:write",
        "commands",
        "emoji:read",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:read",
        "pins:write",
        "reactions:read",
        "reactions:write",
        "usergroups:read",
        "users:read"
      ]
    }
  },
  "settings": {
    "socket_mode_enabled": true,
    "event_subscriptions": {
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "channel_rename",
        "member_joined_channel",
        "member_left_channel",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    }
  }
}

For HTTP Request URLs mode, swap settings for the HTTP variant and append url to each slash command. A public URL is required:

{
  "features": {
    "slash_commands": [
      {
        "command": "/openclaw",
        "description": "Send a message to OpenClaw",
        "should_escape": false,
        "url": "https://gateway-host.example.com/slack/events"
      }
    ]
  },
  "settings": {
    "event_subscriptions": {
      "request_url": "https://gateway-host.example.com/slack/events",
      "bot_events": [
        "app_home_opened",
        "app_mention",
        "app_context_changed",
        "channel_rename",
        "member_joined_channel",
        "member_left_channel",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    },
    "interactivity": {
      "is_enabled": true,
      "request_url": "https://gateway-host.example.com/slack/events",
      "message_menu_options_url": "https://gateway-host.example.com/slack/events"
    }
  }
}

Additional manifest settings

Surface different features that extend the above defaults.

The default manifest turns on the Slack App Home Home tab and registers for app_home_opened. When a workspace member opens the Home tab, OpenClaw sends a safe default Home view containing views.publish; neither conversation payload nor private configuration appears there. With single slash command mode active, the command hint relies on channels.slack.slashCommand.name; installations using native commands or no slash commands leave that hint out. The Messages tab stays enabled for Slack DMs. New apps adopt Slack Agent View via features.agent_view, assistant:write, and app_context_changed. Every visible Agent View root maps to its own OpenClaw thread session, and Slack's ordered active-view entities reach the agent only as untrusted context.

Apps already using features.assistant_view may retain their existing manifest. For those installs, OpenClaw continues to manage assistant_thread_started and assistant_thread_context_changed. Since Slack makes the Assistant View to Agent View migration irreversible and forces a hard refresh afterward, do not swap out assistant_view on an existing app unless you plan to migrate the entire workspace.

Optional native slash commands

Instead of one configured command with nuance, you can rely on multiple native slash commands:

• Choose /agentstatus over /status, because the /status command is reserved.

• A Slack app can register at most 25 slash commands at any given time (Slack platform limit).

  OpenClaw sets up handlers for enabled native commands, yet manifest entries stay administrator-managed and are not synced at runtime. Manually add /login to the manifest; the example below includes it in place of the optional /side alias to keep the count at 25. /login can be placed anywhere, but pairing codes are issued only in private chats or the Web UI.

  Swap your current features.slash_commands section for a subset of available commands:

  Socket Mode (default)

  {
    "slash_commands": [
      {
        "command": "/new",
        "description": "Start a new session",
        "usage_hint": "[model]"
      },
      {
        "command": "/reset",
        "description": "Reset the current session"
      },
      {
        "command": "/compact",
        "description": "Compact the session context",
        "usage_hint": "[instructions]"
      },
      {
        "command": "/stop",
        "description": "Stop the current run"
      },
      {
        "command": "/session",
        "description": "Manage thread-binding expiry",
        "usage_hint": "idle <duration|off> or max-age <duration|off>"
      },
      {
        "command": "/think",
        "description": "Set the thinking level",
        "usage_hint": "<level>"
      },
      {
        "command": "/verbose",
        "description": "Toggle verbose output",
        "usage_hint": "on|off|full"
      },
      {
        "command": "/fast",
        "description": "Show or set fast mode",
        "usage_hint": "[status|on|off]"
      },
      {
        "command": "/reasoning",
        "description": "Toggle reasoning visibility",
        "usage_hint": "[on|off|stream]"
      },
      {
        "command": "/elevated",
        "description": "Toggle elevated mode",
        "usage_hint": "[on|off|ask|full]"
      },
      {
        "command": "/exec",
        "description": "Show or set exec defaults",
        "usage_hint": "host=<auto|sandbox|gateway|node> security=<deny|allowlist|full> ask=<off|on-miss|always> node=<id>"
      },
      {
        "command": "/approve",
        "description": "Approve or deny pending approval requests",
        "usage_hint": "<id> <decision>"
      },
      {
        "command": "/model",
        "description": "Show or set the model",
        "usage_hint": "[name|#|status]"
      },
      {
        "command": "/models",
        "description": "List providers/models",
        "usage_hint": "[provider] [page] [limit=<n>|size=<n>|all]"
      },
      {
        "command": "/help",
        "description": "Show the short help summary"
      },
      {
        "command": "/commands",
        "description": "Show the generated command catalog"
      },
      {
        "command": "/tools",
        "description": "Show what the current agent can use right now",
        "usage_hint": "[compact|verbose]"
      },
      {
        "command": "/agentstatus",
        "description": "Show runtime status, including provider usage/quota when available"
      },
      {
        "command": "/tasks",
        "description": "List active/recent background tasks for the current session"
      },
      {
        "command": "/context",
        "description": "Explain how context is assembled",
        "usage_hint": "[list|detail|json]"
      },
      {
        "command": "/whoami",
        "description": "Show your sender identity"
      },
      {
        "command": "/skill",
        "description": "Run a skill by name",
        "usage_hint": "<name> [input]"
      },
      {
        "command": "/btw",
        "description": "Ask a side question without changing session context",
        "usage_hint": "<question>"
      },
      {
        "command": "/login",
        "description": "Pair Codex login",
        "usage_hint": "[codex|openai]"
      },
      {
        "command": "/usage",
        "description": "Control the usage footer or show cost summary",
        "usage_hint": "off|tokens|full|cost"
      }
    ]
  }
  

  HTTP Request URLs

  Apply the same slash_commands list as Socket Mode above, and append "url": "https://gateway-host.example.com/slack/events" to each entry. Example:

  {
    "slash_commands": [
      {
        "command": "/new",
        "description": "Start a new session",
        "usage_hint": "[model]",
        "url": "https://gateway-host.example.com/slack/events"
      },
      {
        "command": "/help",
        "description": "Show the short help summary",
        "url": "https://gateway-host.example.com/slack/events"
      }
    ]
  }
  

  Put that url value on every command in the list.

Optional authorship scopes (write operations)

Add the chat:write.customize bot scope when you want outgoing messages to adopt the active agent identity (custom username and icon) rather than the default Slack app identity.

If an emoji icon is used, Slack requires :emoji_name: syntax.

Optional user-token scopes (read operations)

With channels.slack.userToken configured, typical read scopes include:

• 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 (only if your setup relies on Slack search reads)

Token model

• Bot identity by default calls for botToken plus appToken when Socket Mode is active, or botToken and signingSecret in HTTP mode.
• User identity relies on userToken with appToken for Socket Mode, or userToken and signingSecret for HTTP mode. No bot token is involved here.
• Relay mode combines botToken with relay.url, relay.authToken, and relay.gatewayId; neither an app token nor a signing secret is used.
• Plaintext strings or SecretRef objects are accepted by botToken, appToken, signingSecret, relay.authToken, and userToken.
• Config tokens take precedence over env fallback.
• The env fallback for SLACK_BOT_TOKEN, SLACK_APP_TOKEN, and SLACK_USER_TOKEN only affects the default account individually.
• userToken starts with read-only behavior, which is userTokenReadOnly: true.

How status snapshots behave:

• Per-credential *Source and *Status fields are tracked during Slack account inspection, covering botToken, appToken, signingSecret, and userToken.
• Status can be available, configured_unavailable, or missing.
• When the account is set up via SecretRef or another non-inline secret source, but the actual value could not be resolved along the current command or runtime path, configured_unavailable is reported.
• In HTTP mode, signingSecretStatus appears. For Socket Mode, bot identity uses botTokenStatus plus appTokenStatus, while user identity relies on userTokenStatus and appTokenStatus.

Tip

With bot identity, an optional user token can be preferred for actions and directory reads; writes keep using the bot token unless userTokenReadOnly: false permits fallback. For postAs: "user", both reads and writes consistently use userToken.

Actions and gates

The channels.slack.actions.* setting governs Slack actions.

Action groups currently available in Slack tooling:

Among current Slack message actions are send, upload-file, download-file, read, edit, delete, pin, unpin, list-pins, member-info, and emoji-list. Slack file IDs shown in inbound file placeholders are what download-file takes, returning image previews for images or local file metadata for other file types.

Workspace custom emoji and aliases can be discovered through emoji-list:

{ "action": "emoji-list", "channel": "slack", "limit": 25 }

Sorting by shortcode name applies to the results. limit is set to 100 by default and cannot go beyond that:

{
  "ok": true,
  "emojis": [
    { "name": "celebrate", "identifier": "celebrate", "aliasOf": "party" },
    { "name": "party", "identifier": "party" }
  ]
}

Use the value of identifier directly as the react emoji; wrapping it in colons is optional. channels.slack.actions.emojiList governs discovery independently from the reactions gate, and the emoji:read scope must be present on the app.

Access control and routing

DM policy

Access to DMs is governed by channels.slack.dmPolicy. The authoritative DM allowlist is channels.slack.allowFrom.

• pairing (default)
• allowlist
• open (needs channels.slack.allowFrom to contain "*")
• disabled

DM-related flags:

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

Note

Only group DMs that Slack already routes to the app are filtered by dm.groupEnabled and dm.groupChannels. These cannot expose a group DM the app was never added to. Either convert the group DM into a private channel and invite the app, or have the app start a new MPDM using conversations.open. Refer to Group DMs (MPDMs) and bots.

Precedence across multiple accounts:

• When omitted, account-level dmPolicy and groupPolicy fall back to the channel root. Explicit account policies take priority; if neither scope is set, the defaults stay pairing and allowlist in that order.
• userTokenReadOnly also falls back to the channel value when absent, with its default remaining true.
• Only the default account is affected by channels.slack.accounts.default.allowFrom.
• Named accounts use channels.slack.allowFrom whenever their own allowFrom is not configured.
• Named accounts do not inherit channels.slack.accounts.default.allowFrom.

For compatibility, legacy channels.slack.dm.policy and channels.slack.dm.allowFrom are still consulted. When access would remain unchanged, openclaw doctor --fix converts them to dmPolicy and allowFrom.

DM pairing relies on openclaw pairing approve slack <code>.

Channel policy

Channel behavior is managed through channels.slack.groupPolicy:

• open
• allowlist
• disabled

The channel allowlist is stored under channels.slack.channels and config keys must be stable Slack channel IDs (such as C12345678). Enterprise Grid org installs need team:<team-id>:channel:<channel-id> so policies cannot span workspaces.

Upon being invited to an allowed channel, OpenClaw sends a brief introduction based on the channel name, purpose or topic, and recent messages that are available. Introductions can be turned off with channels.slack.joinIntro: false, while channels.slack.accounts.<accountId>.joinIntro overrides the channel-wide setting. They are on by default and do not require a mention, but they never bypass channel access policy or appear in direct messages.

Without a channels.slack block, the Gateway will not auto-start Slack from SLACK_* environment variables. After the block is present, those variables act as fallback credentials for the default account. Choosing --ambient-channels opts into env-only auto-configuration, which relies on groupPolicy="allowlist" and emits a warning even when channels.defaults.groupPolicy is set.

Resolving names and IDs:

• allowlist entries for channels and DMs are resolved during startup if token access permits
• unresolved channel-name entries remain as configured but are ignored for routing by default
• inbound authorization and channel routing default to ID-first behavior; direct username/slug matching requires channels.slack.dangerouslyAllowNameMatching: true

Warning

Keys based on names (#channel-name or channel-name) fail to resolve under groupPolicy: "allowlist". Since channel lookup defaults to ID-first, any name-based key will never route, and every message in that channel gets silently dropped. This is unlike groupPolicy: "open", where routing does not depend on the channel key, so a name-based key seems functional.

The Slack channel ID must always be used as the key. To locate it: right-click the channel in Slack → Copy link, and the ID (C...) sits at the end of the URL.

Valid:

{
  channels: {
    slack: {
      groupPolicy: "allowlist",
      channels: {
        C12345678: { enabled: true, requireMention: true },
      },
    },
  },
}

Invalid (silently dropped under groupPolicy: "allowlist"):

{
  channels: {
    slack: {
      groupPolicy: "allowlist",
      channels: {
        "#eng-my-channel": { enabled: true, requireMention: true },
      },
    },
  },
}

Mentions and channel users

By default, channel messages are gated on mentions.

Sources for mentions:

• direct app mention (<@botId>)
• Slack user-group mention (<!subteam^S...>) when the bot user belongs to that group; usergroups:read is required
• mention regex patterns (agents.entries.*.groupChat.mentionPatterns, with messages.groupChat.mentionPatterns as fallback)
• replies to the bot's own Slack message (implicitMentions.replyToBot)
• follow-ups in threads where the bot took part (implicitMentions.threadParticipation)

Per-channel settings (channels.slack.channels.<id>; names only through startup resolution or dangerouslyAllowNameMatching):

• requireMention
• ignoreOtherMentions
• replyToMode (off|first|all|batched; for this channel, it overrides the account/chat-type reply mode)
• users (allowlist)
• allowBots
• skills
• systemPrompt
• tools, toolsBySender
• toolsBySender key syntax: channel:, id:, e164:, username:, name:, or "*" wildcard (legacy keys without prefixes still resolve only to id:)

ignoreOtherMentions (defaulting to false) discards channel messages that mention another user or user group but not this bot. DMs and group DMs (MPIMs) remain untouched. The filter needs a resolved bot user ID from auth.test; when that identity is missing (for instance, a user-token-only identity), the gate fails open and messages pass through as-is.

allowBots takes a cautious stance for channels and private channels: bot-authored room messages are accepted only if the sending bot is explicitly listed in that room's users allowlist, or if at least one explicit Slack owner ID from channels.slack.allowFrom is currently a room member. Wildcards and display-name owner entries do not count as owner presence. Owner presence relies on Slack conversations.members; ensure the app has the appropriate read scope for the room type (channels:read for public channels, groups:read for private channels). If the member lookup fails, OpenClaw drops the bot-authored room message.

Accepted bot-authored Slack messages share bot loop protection. Set channels.defaults.botLoopProtection for the default budget, then adjust with channels.slack.botLoopProtection or channels.slack.channels.<id>.botLoopProtection when a workspace or channel requires a different limit.

Group DMs (MPDMs) and bots

Slack group DMs, also known as multi-person direct messages or MPDMs, are not channels an app can join through being mentioned. Typing @YourBot in an existing group DM neither adds the app nor makes the conversation visible to it.

• If the app was part of the group DM from creation, Slack sends message.mpim events, and OpenClaw can respond when DM policy permits.
• If the app is mentioned in an existing group DM where it holds no membership, the bot token cannot see the conversation at all. Slack Web API calls like conversations.info, conversations.members, and conversations.history fail with method- and context-dependent access or not-found errors, the MPDM is absent from conversations.list?types=mpim, and no event reaches OpenClaw.
• OpenClaw activates in MPDMs through delivered message.mpim events. app_mention events do not place the app into DM or MPDM contexts.
• dm.groupEnabled and dm.groupChannels only filter MPDMs Slack already delivers to the app. They cannot grant membership or visibility into a group DM the app was never part of. No OpenClaw config setting lets the app see a group DM it never joined.

To add the app to a group DM, choose one of these Slack-supported methods:

1. Start by turning the group DM into a private channel. After that, have someone who is already in it send the app an invite using /invite @YourBot. If the invite goes through the API, it has to use conversations.invite with a token whose actor is both a member and permitted to invite the app.
2. Let the app start a new MPDM with conversations.open, using a bot token that has mpim:write, and put the human recipients into users. Slack automatically includes the bot user that made the call.

Threading, sessions, and reply tags

• Direct messages are routed as direct; channels use channel; MPIMs come through as group.
• Route bindings in Slack accept raw peer IDs as well as Slack target formats like channel:C12345678, user:U12345678, and <@U12345678>.
• When session.dmScope=main is left at its default, regular Slack DMs get folded into the agent's main session. Agent View roots and existing Assistant View threads stay separate as :thread:<threadTs> sessions.
• Sessions tied to channels: agent:<agentId>:slack:channel:<channelId>.
• Even when replyToMode is not off, ordinary top-level channel messages remain on the per-channel session.
• Replies in Slack channels, MPIMs, Agent View, and Assistant View threads use the parent Slack thread_ts to build session suffixes (:thread:<threadTs>). For ordinary DMs, reply threads are just a UI feature on the base DM session.
• OpenClaw puts an eligible top-level channel root into agent:<agentId>:slack:channel:<channelId>:thread:<rootTs> when that root is expected to kick off a visible Slack thread, so the root and its thread replies end up in one OpenClaw session. This covers app_mention events, explicit bot or configured mention-pattern matches, and requireMention: false channels where replyToMode is not off.
• The default for channels.slack.thread.historyScope is thread; for thread.inheritParent it is false.
• channels.slack.thread.initialHistoryLimit sets how many existing thread messages get pulled in when a new thread session begins (default 20; use 0 to turn it off).
• channels.slack.implicitMentions.replyToBot decides whether a reply to the bot's own message skips mention gating (default true).
• channels.slack.implicitMentions.threadParticipation decides whether follow-ups in a thread where the bot has replied skip mention gating (default true). Set it to false to force a new explicit mention in those follow-ups. openclaw doctor --fix migrates the old channels.slack.thread.requireExplicitMention key to this positive canonical flag.
• Account-level overrides are at channels.slack.accounts.<id>.implicitMentions; shared defaults are at channels.defaults.implicitMentions.

Controls for reply threading:

• channels.slack.channels.<id>.replyToMode: per-channel override for Slack channel and private-channel messages
• channels.slack.replyToMode: off|first|all|batched (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>]]

For explicit Slack thread replies from the message tool, set replyBroadcast: true with action: "send" and threadId or replyTo to have Slack also post the thread reply to the parent channel. That maps to Slack's chat.postMessage reply_broadcast flag and works only for text or Block Kit sends, not media uploads.

When a message tool call executes within a Slack thread and points at the same channel, OpenClaw typically adopts the current Slack thread based on the active account, chat-type, or per-channel replyToMode. Automatic replies and same-channel send or upload-file calls follow that same per-channel override. To force a fresh parent-channel message, set topLevel: true on action: "send" or action: "upload-file". threadId: null works as the identical top-level opt-out.

Note

Optional outbound Slack reply threading is turned off by replyToMode="off", including explicit [[reply_to_*]] tags. Since Agent View and Assistant View are Slack-managed threaded experiences, their replies and status stay on the visible root no matter what this setting says. Other inbound Slack thread sessions are not flattened by it. This is unlike Telegram, where explicit tags remain honored in "off" mode. Slack threads hide messages from the channel, but Telegram replies stay visible inline.

Ack reactions

While OpenClaw processes an inbound message, ackReaction sends an acknowledgement emoji. The when of that emoji is controlled by ackReactionScope.

By default, the acknowledgement remains static while Slack's native agent/assistant thread status shows progress with rotating loading messages. Set messages.statusReactions.enabled: true to opt into the queued/thinking/tool/done/error reaction lifecycle instead.

Emoji (ackReaction)

Resolution order:

• channels.slack.accounts.<accountId>.ackReaction
• channels.slack.ackReaction
• messages.ackReaction
• agent identity emoji fallback (agents.entries.*.identity.emoji, else "eyes" / 👀)

Notes:

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

Scope (messages.ackReactionScope)

The Slack provider pulls scope from messages.ackReactionScope (default "group-mentions"). No Slack-account or Slack-channel-level override exists today; the value applies globally to the gateway.

Values:

• "all": react in DMs and groups, including ambient room events.
• "direct": react in DMs only.
• "group-all": react on every group message except ambient room events (no DMs).
• "group-mentions" (default): react in groups, but only when the bot is mentioned (or in group mentionables that opted in). DMs are excluded.
• "off" / "none": never react.

Note

With the default scope ("group-mentions"), ack reactions do not fire in direct messages or ambient room events. To see the configured ackReaction (for example "eyes") on inbound Slack DMs and quiet room events, set messages.ackReactionScope to "all". messages.ackReactionScope is read at Slack provider startup, so a gateway restart is required for the change to take effect.

{
  messages: {
    ackReaction: "eyes",
    ackReactionScope: "all", // react in DMs and groups
  },
}

Text streaming

Live preview behavior is governed by channels.slack.streaming:

• off: disable live preview streaming.
• partial: replace preview text with the latest partial output. Set this to restore the previous default behavior.
• block: append chunked preview updates.
• progress (default): show structured progress in one native task card when Slack supports it, with a Block Kit session-card fallback.
• streaming.preview.toolProgress: when draft preview is active, route tool/progress updates into the same edited preview message (default: true). Set false to keep separate tool/progress messages.
• streaming.preview.commandText / streaming.progress.commandText: status keeps compact tool-progress lines while hiding raw command/exec text (default); set raw to opt into command text.

Hide raw command/exec text while keeping compact progress lines:

{
  "channels": {
    "slack": {
      "streaming": {
        "mode": "progress",
        "progress": {
          "toolProgress": true,
          "commandText": "status"
        }
      }
    }
  }
}

When channels.slack.streaming.mode is partial, channels.slack.streaming.nativeTransport controls Slack native text streaming (default: true).

In progress mode, Slack's native agent card is the default: the whole turn is one streamed message that interleaves narration with a live plan/task card and finishes with the assistant's answer in that same message. The card appears only once a turn does real work, tool or plan activity still running after a short delay, so a plain question is answered without one.

Set channels.slack.streaming.progress.nativeTaskCards to false to fall back to the Block Kit session card, which posts a separate message showing title, narration, plan checklist, recent activity, tool/file totals, and elapsed time, and finalizes to success or error.

Set channels.slack.streaming.progress.style to "compact" to get a single plain-text progress draft instead of either card option. When you use the other progress controls listed below, commentary shows up as italic text only, and a qualifying final text answer overwrites that same Slack message:

{
  channels: {
    slack: {
      streaming: {
        mode: "progress",
        progress: {
          style: "compact",
          label: false,
          commentary: true,
          toolProgress: false,
        },
      },
    },
  },
}

If the reply can't safely replace the draft, Slack falls back to standard final delivery. That covers media, errors, oversized text, split block payloads, custom outbound identity, or an edit failure.

Both surfaces attach the session with Open in OpenClaw, but only when the link is actually usable: gateway.publicOrigin must be configured (the externally reachable Gateway origin), and the Control UI can't be turned off via gateway.controlUi.enabled: false. Installations where publicOrigin stays unset, meaning there's no route from Slack to OpenClaw, receive no link instead of a broken one. When the Control UI lives under a path prefix, gateway.controlUi.basePath needs to be set as well.

• For native text streaming and Slack assistant thread status to appear, a reply thread has to be available. Thread selection continues to honor replyToMode.
• When native streaming isn't available or no reply thread exists, channel, group-chat, and top-level DM roots can still rely on the normal draft preview.
• Top-level Slack DMs remain off-thread by default, so they don't display Slack's thread-style native stream/status preview; instead, OpenClaw posts and edits a draft preview in the DM.
• Custom outbound username/icon settings keep portable previews active. OpenClaw keeps the preview or session card app-authored and delivers the customized final separately. Slack doesn't permit deletion of impersonated messages.
• Media and non-text payloads revert to normal delivery.
• Media/error finals cancel any pending preview edits; eligible text/block finals flush only when they can edit the preview in place.
• If streaming fails mid-reply, OpenClaw switches to normal delivery for the remaining payloads.

Use draft preview rather than Slack native text streaming:

{
  channels: {
    slack: {
      streaming: {
        mode: "partial",
        nativeTransport: false,
      },
    },
  },
}

Explicitly select Slack native progress task cards:

{
  channels: {
    slack: {
      streaming: {
        mode: "progress",
        progress: {
          nativeTaskCards: true,
        },
      },
    },
  },
}

Legacy keys:

• channels.slack.streamMode (replace | status_final | append) serves as a legacy alias for channels.slack.streaming.mode.
• boolean channels.slack.streaming is a legacy alias for channels.slack.streaming.mode and channels.slack.streaming.nativeTransport.
• top-level channels.slack.chunkMode and channels.slack.nativeStreaming are legacy aliases for channels.slack.streaming.chunkMode and channels.slack.streaming.nativeTransport.
• Legacy aliases aren't read at runtime; run openclaw doctor --fix to rewrite persisted Slack streaming config to the canonical keys.

Typing reaction fallback

While OpenClaw is processing a reply, typingReaction adds a temporary reaction to the inbound Slack message, then removes it once the run finishes. This works best outside of thread replies, which use a default "is typing..." status indicator.

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.

Voice input

To talk to OpenClaw in Slack today, send a Slack audio clip to the OpenClaw app. Slackbot's dictation microphone is a separate Slack-owned feature, not an app API.

• Slackbot voice dictation lives inside the user's private Slackbot conversation. Slack turns the recording into a Slackbot prompt but does not emit an audio file, dictation event, prompt, or input-source marker to third-party Slack apps through the Events API. The OpenClaw Slack plugin cannot enable or receive it.
• Slack audio clips are stored Slack files that can be posted in an OpenClaw DM, channel, or thread. OpenClaw downloads an accessible clip with the bot token, normalizes Slack's clip MIME metadata, and sends it through the shared audio transcription pipeline. The recommended app manifest includes the required files:read scope.

Audio clips and Slackbot dictation have different privacy semantics: clips follow Slack file-retention policy and OpenClaw downloads them for transcription, while Slack says dictation audio is not stored.

In a channel with requireMention: true, a captionless audio clip can satisfy the gate by speaking a configured mention pattern (agents.entries.*.groupChat.mentionPatterns, falling back to messages.groupChat.mentionPatterns). OpenClaw authorizes the sender before downloading or transcribing the clip, then admits it only when the transcript matches. A failed or nonmatching speculative transcript is discarded with the downloaded clip; it is not retained in channel history. Native Slack @bot identity cannot be inferred from speech, so configure a spoken-name pattern or include a typed mention. If transcript echoing is enabled, the echo is sent only after admission.

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. File placeholders include the Slack fileId so agents can fetch the original file with download-file.

Downloads use bounded idle and total timeouts. If Slack file retrieval stalls or fails, OpenClaw keeps processing the message and falls back to the file placeholder.

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

Outbound text and files

• text chunks use channels.slack.textChunkLimit (default 8000, capped at Slack's own message-length limit)
• channels.slack.streaming.chunkMode="newline" enables paragraph-first splitting
• file sends use Slack upload APIs and can include thread replies (thread_ts)
• long file captions use the first Slack-safe text chunk as the upload comment and send remaining chunks as follow-up messages
• 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

Text/block-only Slack DMs can post directly to user IDs; file uploads and threaded sends open the DM via Slack conversation APIs first because those paths require a concrete conversation ID.

Commands and slash behavior

Slash commands appear in Slack as either a single configured command or multiple native commands. Configure channels.slack.slashCommand to change command defaults:

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

/openclaw /help

Native commands require additional manifest settings in your Slack app and are enabled with channels.slack.commands.native: true or commands.native: true in global configurations instead.

• Native command auto-mode is off for Slack, meaning commands.native: "auto" does not turn on Slack native commands.

/help

Native argument menus appear in this priority order:

• 3-5 short-enough options: an overflow ("...") menu
• more than 100 options, with async option filtering available: external select
• 1-2 options, or any option whose encoded value is too long for a select: button blocks
• otherwise (6-100 options, or more than 100 without async filtering): static select menu, chunked at 100 options per menu

/think

Slash sessions rely on isolated keys like agent:<agentId>:slack:slash:<userId> and continue to direct command executions to the target conversation session via CommandTargetSessionKey.

Native charts

Slack's public data_visualization Block Kit block renders line, bar, area, and pie charts in messages. OpenClaw maps the portable presentation chart block to that native shape; no additional OAuth scope, file upload, image renderer, or Slack configuration is required beyond normal chat:write message access.

{
  "blocks": [
    {
      "type": "chart",
      "chartType": "bar",
      "title": "Quarterly revenue",
      "categories": ["Q1", "Q2"],
      "series": [{ "name": "Revenue", "values": [120, 145] }],
      "xLabel": "Quarter"
    }
  ]
}

Slack's limits are enforced before native rendering:

• title and optional axis labels: 50 characters
• pie: 1-12 positive segments
• line/bar/area: 1-12 uniquely named series and 1-20 shared categories
• segment, category, and series labels: 20 characters
• every series must contain one finite value for every category; non-pie values may be negative

Every native chart also carries a top-level text representation for screen readers, notifications, session mirroring, and clients that cannot render the block. Standard presentation sends to other OpenClaw channels receive that same deterministic chart data as text unless they advertise native chart support. If Slack rejects the chart with invalid_blocks during a phased rollout, OpenClaw removes the rejected native data blocks, keeps any sibling controls, and sends the complete chart representation as visible text.

Slack currently accepts up to two data_visualization blocks per message. When a presentation contains more than two valid charts, OpenClaw keeps their order and continues native rendering in follow-up messages, with no more than two charts in each message.

Slack's developer launch documents the block as an app-facing Block Kit feature and publishes no paid plan restriction. The Business+/Enterprise eligibility language applies to Slackbot's automatic AI chart generation, which is separate from an app sending an already-structured Block Kit chart. Charts are message-only blocks, not App Home, modal, or Canvas content.

Native tables

Slack's current data_table Block Kit block renders structured rows and columns in messages. OpenClaw maps an explicit portable presentation table block to data_table; it does not use Slack's legacy table block. No additional OAuth scope or Slack configuration is required beyond normal chat:write message access.

{
  "blocks": [
    {
      "type": "table",
      "caption": "Open pipeline",
      "headers": ["Account", "Stage", "ARR"],
      "rows": [
        ["Acme", "Won", 125000],
        ["Globex", "Review", 82000]
      ],
      "rowHeaderColumnIndex": 0
    }
  ]
}

OpenClaw maps header and string cells to Slack raw_text cells. Numeric cells map to raw_number, with the finite numeric value preserved for native sorting and filtering. rowHeaderColumnIndex, when present, marks that zero-based column as Slack row headers.

Slack's published data_table limits are enforced before native rendering:

• 1-20 columns
• 1-100 data rows, plus the header row
• the same number of cells in every row
• at most 10,000 aggregate characters across all table cells in one message

Multiple valid table blocks can render natively while the message remains within the aggregate character limit. A table that cannot render within the native envelope becomes complete deterministic text instead of losing rows or cells. If that text exceeds one Slack message, sends and slash responses use ordered text chunks. Table edits fail with an explicit size error instead of silently truncating rows from an existing message.

Every native table produced from portable presentation also carries a top-level text representation for screen readers, notifications, session mirroring, and clients that cannot render the block. Raw chart and table values stay literal in the fallback, so cell data such as <@U123> does not become a Slack mention. If Slack rejects native chart or table blocks with invalid_blocks, OpenClaw removes every native data block in one bounded recovery step, retains valid sibling blocks such as buttons and selects, and sends complete visible chart and table text with Slack formatting disabled. Slash-command delivery tracks Slack's five-call response_url budget across the command. Before each reply batch, it selects a complete plan that fits the remaining calls or fails before posting that batch.

Only explicit presentation table blocks are promoted to native tables. Markdown pipe tables remain authored text; OpenClaw does not guess at table structure or cell types. Existing trusted Slack-native producers can continue to pass raw blocks through channelData.slack.blocks; OpenClaw derives fallback text from valid raw data_table cells, while malformed custom blocks may degrade to their caption or general Block Kit fallback. Portable agent, CLI, and plugin output should use presentation.

Slack clients can also deliver pasted spreadsheet content as a legacy table block in the message's top-level blocks or attachments. OpenClaw renders those inbound cells as delimiter-safe TSV for live agent input, thread context, and Slack read actions. Only native table blocks are admitted from ordinary attachments; link-unfurl and other non-forwarded attachment text remains excluded.

Plugin-owned modal submissions

Slack plugins that register an interactive handler can also receive modal view_submission and view_closed lifecycle events before OpenClaw compacts the payload for the agent-visible system event. Use one of these routing patterns when opening a Slack modal:

• Set callback_id to openclaw:<namespace>:<payload>.
• Or keep an existing callback_id and put pluginInteractiveData: "<namespace>:<payload>" in the modal private_metadata.

The handler receives ctx.interaction.kind as view_submission or view_closed, normalized inputs, and the full raw stateValues object from Slack. Callback-id-only routing is enough to invoke the plugin handler; include the existing modal private_metadata user/session routing fields when the modal should also produce an agent-visible system event. The agent receives a compact, redacted Slack interaction: ... system event. If the handler returns systemEvent.summary, systemEvent.reference, or systemEvent.data, those fields are included in that compact event so the agent can reference plugin-owned storage without seeing the complete form payload.

Native approvals in Slack

Slack can act as a native approval client with interactive buttons and interactions, instead of falling back to the Web UI or terminal.

• Exec and plugin approvals can be presented as Slack-native Block Kit prompts.
• channels.slack.execApprovals.* continues to serve as the native exec approval client enablement and DM/channel routing configuration.
• Exec approval DMs rely on channels.slack.execApprovals.approvers or commands.ownerAllowFrom.
• Plugin approvals appear as Slack-native buttons when Slack is set as a native approval client for the originating session, or when approvals.plugin directs to the originating Slack session or a Slack target.
• Plugin approval DMs use Slack plugin approvers from channels.slack.allowFrom, named-account allowFrom, or the account default route.
• Approver authorization remains enforced: exec-only approvers cannot approve plugin requests unless they also qualify as plugin approvers.

For Enterprise Grid org installs, the validated workspace from the originating event is preserved for the approval prompt, approver DM, button callback, and final message update. Approval delivery fails closed when an org-installed account lacks that event-owned workspace scope.

This shares the same approval button surface as other channels. With interactivity enabled in your Slack app settings, approval prompts show as Block Kit buttons directly in the conversation. When these buttons appear, they take precedence as the primary approval UX; OpenClaw should only include a manual /approve command when the tool result indicates chat approvals are unavailable or manual approval is the sole option.

Config path:

• channels.slack.execApprovals.enabled
• channels.slack.execApprovals.approvers (optional; falls back to commands.ownerAllowFrom when possible)
• channels.slack.execApprovals.target (dm | channel | both, default: dm)
• agentFilter, sessionFilter

Slack native exec approvals require enabled: true or "auto" plus at least one resolved exec approver. Leaving enabled unset or setting it to false turns off native exec approval delivery. Slack can also manage native plugin approvals via this native-client path when Slack plugin approvers resolve and the request matches its filters. Disabling Slack exec approvals does not affect native plugin approval delivery enabled through approvals.plugin, which relies on Slack plugin approvers instead.

Minimal Slack-native configuration using command owners as approvers:

{
  channels: {
    slack: {
      execApprovals: { enabled: "auto" },
    },
  },
  commands: {
    ownerAllowFrom: ["slack:U12345678"],
  },
}

To override approvers, add filters, or opt into origin-chat delivery:

{
  channels: {
    slack: {
      execApprovals: {
        enabled: true,
        approvers: ["U12345678"],
        target: "both",
      },
    },
  },
}

Shared approvals.exec forwarding operates independently. Use it only when exec approval prompts must also reach other chats or explicit out-of-band targets. Shared approvals.plugin forwarding is likewise separate; Slack native delivery suppresses that fallback only when Slack can handle the plugin approval request natively.

Same-chat /approve also functions in Slack channels and DMs that already support commands. See Exec approvals for the complete approval forwarding model.

Events and operational behavior

• Message edits/deletes are converted into system events.
• Thread broadcasts ("Also send to channel" thread replies) are handled as standard user messages.
• Reaction add/remove events are converted into system events.
• Member join/leave, channel created/renamed, and pin add/remove events are converted into system events.
• When the bot joins an allowed channel, it posts a single introduction based on the channel name, purpose or topic, and available recent messages. Introductions are on by default, never run in direct messages, and can be turned off with channels.slack.joinIntro: false or overridden per account with channels.slack.accounts.<accountId>.joinIntro. See group join introductions for the history limits, once-per-room behavior, and untrusted-content handling.
• Optional presence polling can map an observed human participant's away to active transition into the participant's most recently active eligible Slack session. The default is off.
• channel_id_changed can migrate channel config keys when configWrites is enabled.
• Channel topic/purpose metadata is considered untrusted context and can be injected into routing context.
• Agent View app_context entities are validated in Slack relevance order and exposed only as structured untrusted context; an omitted context clears the turn rather than reusing stale entities.
• Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable.
• Dedicated Web API reads used for probes, scope discovery, conversation classification, and delivery reconciliation have a 30-second deadline per request attempt. Transient failures can still retry, so the full operation may take longer. Shared Bolt and mutation-capable clients do not receive this default deadline because Slack may commit a mutation before a late response reaches OpenClaw.
• Block actions, shortcuts, and modal interactions emit structured Slack interaction: ... system events with rich payload fields:
  • block actions: selected values, labels, picker values, and workflow_* metadata
  • global shortcuts: callback and actor metadata, routed to the actor's direct session
  • message shortcuts: callback, actor, channel, thread, and selected-message context
  • modal view_submission and view_closed events with routed channel metadata and form inputs

Define global or message shortcuts in your Slack app configuration and use any non-empty callback ID. OpenClaw acknowledges matching shortcut payloads, applies the same DM/channel sender policy as other Slack interactions, and queues the sanitized event for the routed agent session. Trigger IDs and response URLs are redacted from agent context.

Presence events

Slack does not send presence changes through the Events API or Socket Mode. OpenClaw can instead poll users.getPresence for human participants whose messages passed normal Slack access and routing checks.

{
  channels: {
    slack: {
      presenceEvents: {
        mode: "auto",
        prompt: "Do not send a greeting. Stay silent.",
      },
      channels: {
        C0123456789: { presenceEvents: { mode: "on" } },
        C0987654321: { presenceEvents: { mode: "off" } },
      },
    },
  },
}

• off (default): no presence timer or Slack API calls.
• auto: monitor DMs, MPIMs, and Slack threads active in the last 24 hours with at most 8 observed human participants. Top-level channel sessions are excluded.
• on: monitor the same conversations without the participant cap and include top-level channel sessions. Use a per-channel override to force or suppress one channel.

OpenClaw polls at most 45 unique workspace-user pairs per minute per Slack account, seeds the first result without waking the agent, and only wakes on an observed away to active transition. A durable 8-hour cooldown applies per Slack account, workspace, and user, even if that person participates in several threads. The event routes only to that person's most recently active eligible conversation and tells the agent to consult memory/wiki and known timezone context before deciding whether to send one short greeting. The agent may stay silent.

The event includes observed_away_at_ms, observed_active_at_ms, and observed_away_duration_ms. The duration is the elapsed time between the first sampled away state in the current monitor run and the later sampled active state. It is not exact time away because presence can change between polls, and the observation starts fresh after the monitor restarts or the target expires. The event records what Slack reported, not whether the person was at their keyboard; Slack can mark someone away automatically or manually, and users.getPresence does not distinguish those cases for another user.

presenceEvents.prompt takes over from the standard welcome message once the event details have been provided. The setting configured at the account level is what applies by default, though channels.<channel-id>.presenceEvents.prompt lets you change it for a single channel. Whatever custom text you supply is passed through exactly as written, with a hard ceiling of 20,000 characters, which mirrors the default per-file AGENTS.md bootstrap cap. If you want to skip event-specific instructions entirely, set it to an empty string so workspace-level directives like AGENTS.md can dictate how the event is handled. The presence facts are always part of the output.

For the bot token, users:read is required, and it comes preconfigured in the recommended manifest. When an Enterprise Grid org-wide install is used, a workspace-scoped polling client gets created only after an authorized event points to that workspace; presence state, cooldowns, and delivery targets stay separated on a per-workspace basis.

Configuration reference

Primary reference: Configuration reference - Slack.

High-signal Slack fields

• mode/auth: postAs, mode, botToken, appToken, userToken, 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, implicitMentions.*
• group introductions: joinIntro, accounts.*.joinIntro (default: true)
• threading/history: replyToMode, replyToModeByChatType, thread.*, historyLimit, dmHistoryLimit, dms.*.historyLimit
• presence wakes: presenceEvents.mode, presenceEvents.prompt, channels.*.presenceEvents.* (off|auto|on; default off)
• delivery: textChunkLimit, streaming.chunkMode, mediaMaxMb, streaming, streaming.nativeTransport, streaming.preview.toolProgress
• unfurls: unfurlLinks (default: false), unfurlMedia for chat.postMessage link/media preview control; set unfurlLinks: true to opt back into link previews
• ops/features: configWrites, commands.native, slashCommand.*, actions.*, userToken, userTokenReadOnly

Troubleshooting

No replies in channels

Verify the following, in this sequence:

• groupPolicy
• channel allowlist (channels.slack.channels), keys must be channel IDs (C12345678) or workspace-qualified channel targets (team:<team-id>:channel:<channel-id>), not names (#channel-name). Name-based keys silently fail under groupPolicy: "allowlist" because channel routing is ID-first by default. To find an ID: right-click the channel in Slack → Copy link, the C... value at the end of the URL is the channel ID.
• requireMention
• per-channel users allowlist
• messages.groupChat.visibleReplies: normal group/channel requests default to "automatic". If you opted into "message_tool" and logs show assistant text with no message(action=send) call, the model missed the visible message-tool path. Final text stays private in this mode; inspect the gateway verbose log for suppressed payload metadata, or set it to "automatic" if you want every normal assistant final reply posted through the legacy path.
• messages.groupChat.unmentionedInbound: if it is "room_event", unmentioned allowed channel chatter is ambient context and stays silent unless the agent calls the message tool. See Ambient room events.

{
  messages: {
    groupChat: {
      visibleReplies: "automatic",
    },
  },
}

Handy commands:

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

DM messages ignored

Confirm:

• channels.slack.dm.enabled
• channels.slack.dmPolicy (or legacy channels.slack.dm.policy)
• pairing approvals / allowlist entries (dmPolicy: "open" still requires channels.slack.allowFrom: ["*"])
• group DMs use MPIM handling; enable channels.slack.dm.groupEnabled and, if configured, include the MPIM in channels.slack.dm.groupChannels
• Slack Assistant DM events: verbose logs mentioning drop message_changed usually mean Slack sent an edited Assistant-thread event without a recoverable human sender in message metadata

openclaw pairing list slack

Socket mode not connecting

Check bot and app tokens plus Socket Mode activation in the Slack app settings. The App-Level Token needs connections:write, and the Bot User OAuth Token bot token must belong to the same Slack app/workspace as the app token.

If openclaw channels status --probe --json reports botTokenStatus or appTokenStatus: "configured_unavailable", the Slack account is configured but the current runtime could not resolve the SecretRef-backed value.

Logs such as slack socket mode failed to start; retry ... are recoverable start failures. Missing scopes, revoked tokens, and invalid auth fail fast instead. A slack token mismatch ... log means the bot token and app token appear to belong to different Slack apps; fix the Slack app credentials.

HTTP mode not receiving events

Confirm:

• signing secret
• webhook path
• Slack Request URLs (Events + Interactivity + Slash Commands)
• unique webhookPath per HTTP account
• the public URL terminates TLS and forwards requests to the Gateway path
• the Slack app request_url path exactly matches channels.slack.webhookPath (default /slack/events)

If signingSecretStatus: "configured_unavailable" appears in account snapshots, the HTTP account is configured but the current runtime could not resolve the SecretRef-backed signing secret.

A repeated slack: webhook path ... already registered log means two HTTP accounts are using the same webhookPath; give each account a distinct path.

Native/slash commands not firing

Check what you meant to set up:

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

Slack does not create or remove slash commands automatically. commands.native: "auto" does not enable Slack native commands; use true and create the matching commands in the Slack app. In HTTP mode, every Slack slash command must include the Gateway URL. In Socket Mode, command payloads arrive over the websocket and Slack ignores slash_commands[].url.

Also check commands.allowFrom (when configured), DM authorization, channel allowlists, and per-channel users allowlists. Access-group entries in channel allowlists are resolved automatically. Slack returns ephemeral errors for blocked slash-command senders, including:

• This channel is not allowed.
• You are not authorized to use this command here.

Attachment media reference

Slack can attach downloaded media to the agent turn when Slack file downloads succeed and size limits permit. Audio clips can be transcribed, image files can pass through the media-understanding path or directly to a vision-capable reply model, and other files remain available as downloadable file context.

Supported media types

Inbound pipeline

When a Slack message with file attachments arrives:

1. OpenClaw pulls the file from Slack's private URL with the bot token.
2. A successful fetch writes the file into the media store.
3. Downloaded media paths and content types are appended to the inbound context.
4. Audio clips go to the shared transcription pipeline; image-capable model/tool paths can draw image attachments from the same context.
5. All other files stay reachable as file metadata or media references for tools that support them.

Thread-root attachment inheritance

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

• If the reply carries no direct media and the root message it references has files, Slack can pull those root files in as thread-starter context.
• Root files are hydrated only while a new or reset thread session is being seeded. Later text-only replies reuse the existing session context and do not reattach root files as fresh media.
• Direct reply attachments outrank root-message attachments.
• A root message holding only files and no text is shown with an attachment placeholder so the fallback can still include its files.

Multi-attachment handling

When one Slack message contains multiple file attachments:

• Each attachment moves through the media pipeline on its own.
• Downloaded media references are gathered into the message context.
• Processing order follows Slack's file order in the event payload.
• A download failure for one attachment does not stop the others.
• Failed or blocked files stay in the agent context with a bounded reason, and each failed file emits one warning after any URL refresh retry.
• Files past the eight-file limit are never downloaded. Their references carry an omitted: 8-file limit reason. Long unavailable-file lists are visibly truncated, while the notice keeps the total unavailable attachment count.

Size, download, and model limits

• Size cap: Default 20 MB per file. Adjustable via channels.slack.mediaMaxMb.
• Audio transcription cap: the chosen audio-capable tools.media.models[] entry's maxBytes also applies when the downloaded file is sent to a transcription provider or CLI.
• Download failures: Files Slack cannot serve, expired URLs, inaccessible files, oversize files, and Slack auth/login HTML responses are skipped rather than reported as unsupported formats.
• Vision model: Image analysis uses the active reply model when it supports vision, or the image model set at agents.defaults.imageModel.

Known limits

Related documentation

• Media understanding pipeline
• Audio and voice notes
• PDF tool

Related

• Pairing, Pair a Slack user to the gateway.

• Groups, Channel and group DM behavior.

• Channel routing, Route inbound messages to agents.

• Security, Threat model and hardening.

• Configuration, Config layout and precedence.

• Slash commands, Command catalog and behavior.