OpenClaw Manual OpenClaw

OpenClaw Slack Channel

Enterprise
Medium

Connect OpenClaw to Slack using Socket Mode (default) or HTTP Events API. This enterprise-grade integration lets your AI assistant operate in Slack workspaces — handling DMs, channel conversations, reactions, threads, and slash commands. Socket Mode connects via WebSocket with no public URL required; HTTP mode uses Slack's Events API for publicly accessible deployments.

Quick Info
Difficulty Medium
Category Enterprise
Features Supported 5 / 6

Slack Supported Features

Text Messages

Supported

Media & Files

Supported

Reactions

Supported

Threads

Supported

Voice Messages

Not Supported

Group Chat

Supported

Slack Prerequisites

  • A Slack workspace with admin privileges (to install custom apps)
  • A Slack App created at api.slack.com/apps
  • App Token (xapp-...) with connections:write scope (for Socket Mode)
  • Bot Token (xoxb-...) obtained after installing the app to your workspace
  • OpenClaw Gateway running and configured

Slack Quick Setup

1

Create Slack App and enable Socket Mode

Go to api.slack.com/apps and click 'Create New App' → 'From scratch'. Give it a name and select your workspace. Navigate to 'Socket Mode' in the sidebar and enable it. Generate an App-Level Token with the 'connections:write' scope — this gives you the xapp-... token.

2

Configure OAuth scopes and install to workspace

Go to 'OAuth & Permissions', add the required Bot Token Scopes (chat:write, channels:history, channels:read, im:write, im:history, im:read, users:read, reactions:read, reactions:write, files:write, etc.). Click 'Install to Workspace' and authorize. Copy the Bot User OAuth Token (xoxb-...). Then go to 'Event Subscriptions', enable events, and subscribe to: message.channels, message.groups, message.im, message.mpim, app_mention, reaction_added, reaction_removed.

3

Add config, start Gateway, and invite bot

Add the Slack channel configuration to ~/.openclaw/openclaw.json with your appToken and botToken. Start the Gateway — it will connect to Slack via Socket Mode. Invite the bot to your target channels by typing '/invite @YourBotName' in Slack. Send a message to test.

Slack Configuration Example

config.json 
{
  "channels": {
    "slack": {
      "enabled": true,
      "appToken": "xapp-1-YOUR_APP_TOKEN",
      "botToken": "xoxb-YOUR_BOT_TOKEN"
    }
  }
}

Slack Deep Dive

Architecture Overview

OpenClaw connects to Slack through two supported modes: • Socket Mode (default) — Uses a WebSocket connection initiated from your server to Slack. No public URL or firewall configuration needed. Ideal for development, internal deployments, and environments behind NATs. • HTTP Mode (Events API) — Slack pushes events to your server's HTTPS endpoint. Requires a publicly accessible URL. Better for high-availability production deployments with load balancers. In both modes, the bot receives real-time events (messages, reactions, mentions) and responds through the Slack API. Session routing is context-dependent: DMs use the agent's main session, channel conversations create isolated sessions per channel (agent:<agentId>:slack:channel:<channelId>), and slash commands get per-user sessions.
Socket Mode is recommended for most self-hosted setups — it works behind firewalls and NATs with zero networking configuration.
You can set tokens via environment variables: SLACK_APP_TOKEN and SLACK_BOT_TOKEN, or in your config file.

Creating Your Slack App

Setting up a Slack app requires configuring several components in the Slack API portal: 1. Go to api.slack.com/apps and click 'Create New App' → 'From scratch' 2. Name your app and select the target workspace 3. Enable Socket Mode (Settings → Socket Mode → Enable). Generate an App-Level Token with connections:write scope 4. Add Bot Token Scopes under OAuth & Permissions: • chat:write, im:write — Send and manage messages • channels:history, groups:history, im:history, mpim:history — Read message history • channels:read, groups:read, im:read, mpim:read — Read conversation info • users:read — Look up user profiles • reactions:read, reactions:write — React to messages • pins:read, pins:write — Manage pinned messages • emoji:read — List custom emoji • files:write — Upload files 5. Install the app to your workspace and copy the Bot Token (xoxb-...) 6. Enable Event Subscriptions and subscribe to bot events: • message.channels, message.groups, message.im, message.mpim • app_mention • reaction_added, reaction_removed • member_joined_channel, member_left_channel • channel_rename, pin_added, pin_removed 7. Optionally create a /openclaw slash command under Slash Commands 8. Enable the Messages Tab under App Home for DM support Tip: You can use the provided app manifest to auto-configure all scopes and events at once during app creation.
Keep your tokens secret. The App Token (xapp-...) and Bot Token (xoxb-...) grant full control over your app. If compromised, regenerate them immediately in the Slack API portal.
The manifest option during app creation can set up all required scopes, events, and features in one step.
Make sure to enable Event Subscriptions and subscribe to the required bot events. Without this, the bot will connect but won't receive any messages.

DM Security (Pairing)

Slack DM policies control who can interact with your AI assistant in direct messages. OpenClaw supports two modes: • pairing (default) — Unknown DM senders receive a time-limited pairing code (expires after 1 hour). Approve via 'openclaw pairing approve slack <code>' in your terminal. Once approved, they can chat freely. Maximum 3 pending pairing requests per channel. • open — Anyone who DMs the bot gets a response. Requires dm.allowFrom=["*"] to function. Use with caution in large workspaces. Allowlist entries support multiple formats: • Slack User IDs (e.g., "U01ABCDEF") • @username references • Email addresses You can also check pending pairings with 'openclaw pairing list slack'.
openclaw.json 
{
  "channels": {
    "slack": {
      "enabled": true,
      "appToken": "xapp-...",
      "botToken": "xoxb-...",
      "dm": {
        "policy": "pairing",
        "allowFrom": ["U01ABCDEF", "user@company.com"]
      }
    }
  }
}
Use the pairing policy for workspaces with many users to prevent unauthorized AI usage. Each pairing code expires after 1 hour.
In open mode, set allowFrom to ["*"] to allow all users, or specify individual user IDs/emails to restrict access.

Channel Configuration (Group Policy)

Channel policies control which Slack channels the bot operates in and how it behaves: Top-level groupPolicy: • open — Bot responds in all channels it's invited to • disabled — Bot ignores all channel messages • allowlist — Bot only responds in explicitly configured channels Per-channel configuration lets you fine-tune behavior for individual channels: • allow — Enable/disable the channel in allowlist mode • requireMention — Whether the bot needs to be @mentioned to respond • users — User allowlist for this specific channel • skills — Restrict which skills/tools are available in this channel • systemPrompt — Custom AI instructions for this channel • allowBots — Whether to process messages from other bots (default: false) • enabled — Enable/disable the channel entirely
openclaw.json 
{
  "channels": {
    "slack": {
      "groupPolicy": "allowlist",
      "channels": {
        "C01ABCDEF": {
          "allow": true,
          "requireMention": true,
          "users": ["U01ABCDEF"],
          "skills": ["search", "docs"],
          "systemPrompt": "Keep answers short and technical."
        },
        "#general": {
          "allow": true,
          "requireMention": true
        }
      }
    }
  }
}
Channel keys can be either channel IDs (C01ABCDEF) or channel names (#general). IDs are more reliable as they survive channel renames.
Use per-channel systemPrompt to give the AI different personalities or instructions for different channels — e.g., technical in #engineering, casual in #watercooler.

Reply Threading

OpenClaw supports flexible reply threading in Slack, controlling whether the bot responds in the main channel or creates threads. Global replyToMode: • off (default) — Replies in the main channel. Only threads when the triggering message is already in a thread. • first — First reply goes to a thread, subsequent replies go to the main channel. • all — All replies are sent as thread responses. Per-chat-type overrides via replyToModeByChatType: • direct — 1:1 DM conversations • group — Group DM / MPIM conversations • channel — Standard Slack channels Manual thread control via reply tags: • [[reply_to_current]] — Reply to the message that triggered the bot • [[reply_to:<message_id>]] — Reply to a specific message ID
openclaw.json 
{
  "channels": {
    "slack": {
      "replyToMode": "off",
      "replyToModeByChatType": {
        "direct": "all",
        "group": "first",
        "channel": "off"
      }
    }
  }
}
For busy channels, use replyToMode: 'all' to keep conversations organized in threads and avoid cluttering the main channel.
Per-chat-type overrides let you thread DMs but keep channel replies inline, or vice versa.

User Token (Optional)

In addition to the Bot Token, you can optionally configure a User Token (xoxp-...) for enhanced read access. The User Token provides richer data for history, pins, reactions, custom emoji, and member information. Token usage priority: • Read operations — User Token is preferred; falls back to Bot Token if unavailable • Write operations — Bot Token is always used by default The userTokenReadOnly flag (default: true) ensures the User Token is never used for write operations. Set it to false only if you want the AI to act as the user (requires additional write scopes on the User Token). To add a User Token, configure user token scopes in OAuth & Permissions under 'User Token Scopes' — typically read-only scopes like channels:history, channels:read, users:read, reactions:read, pins:read, emoji:read, search:read.
openclaw.json 
{
  "channels": {
    "slack": {
      "enabled": true,
      "appToken": "xapp-...",
      "botToken": "xoxb-...",
      "userToken": "xoxp-...",
      "userTokenReadOnly": true
    }
  }
}
Setting userTokenReadOnly to false allows the AI to perform write operations (send messages, add reactions, pin messages) as the installing user rather than the bot. Only enable this if you understand the security implications.

Slash Commands & App Home

OpenClaw supports Slack slash commands and App Home configuration: Slash Commands: Create a /openclaw command in the Slack API portal under 'Slash Commands'. In Socket Mode, no request URL is needed — Slack routes the command through the WebSocket connection. If using native commands, create additional slash commands as needed. App Home: Enable the 'Messages Tab' under App Home to allow users to DM the bot directly from its app page. This provides a clean, dedicated interface for 1:1 conversations. Session Routing: • DMs → main session (agent:main:main) • Channel messages → agent:<agentId>:slack:channel:<channelId> • Slash commands → agent:<agentId>:slack:slash:<userId> Delivery targets for cron/CLI: • user:<userId> — Send a DM to a specific user • channel:<channelId> — Post to a specific channel
openclaw.json 
{
  "channels": {
    "slack": {
      "slashCommand": {
        "enabled": true,
        "name": "openclaw",
        "sessionPrefix": "slack:slash",
        "ephemeral": true
      }
    }
  }
}
Ephemeral slash command responses are only visible to the user who invoked the command. Set ephemeral: false to make responses visible to everyone in the channel.
The Messages Tab in App Home must be enabled for DM functionality — without it, users can't start conversations with the bot.

Permissions & Scopes

Slack uses OAuth scopes to control what your app can do. Here are the required and optional scopes: Bot Token Required Scopes: • chat:write — Send, update, and delete messages • im:write — Open DM conversations • channels:history, groups:history, im:history, mpim:history — Read message history • channels:read, groups:read, im:read, mpim:read — Read conversation info • users:read — Look up user profiles • reactions:read, reactions:write — Read and add reactions • pins:read, pins:write — Manage pinned messages • emoji:read — List custom workspace emoji • files:write — Upload files and media User Token Optional Scopes (read-only): • channels:history, groups:history, im:history, mpim:history — Enhanced history access • channels:read, groups:read, im:read, mpim:read — Enhanced conversation info • users:read — User profile lookup • reactions:read, pins:read, emoji:read — Read reactions, pins, emoji • search:read — Search messages and files
Start with just the Bot Token scopes. Add the User Token and its scopes only if you need enhanced read capabilities (like search:read).
The provided app manifest includes all recommended scopes — use it during app creation for the fastest setup.

HTTP Mode (Events API)

If your Gateway is publicly accessible via HTTPS, you can use HTTP mode instead of Socket Mode. In HTTP mode, Slack pushes events directly to your server endpoint. Setup steps: 1. Create the Slack app but do NOT enable Socket Mode 2. Get the Signing Secret from 'Basic Information' → 'App Credentials' 3. Install the app to get the Bot Token 4. Under 'Event Subscriptions', set the Request URL to: https://your-gateway-host/slack/events 5. Under 'Interactivity & Shortcuts', set the same Request URL 6. Under 'Slash Commands', set the Request URL to the same endpoint HTTP mode does not require an App Token — it uses the Signing Secret to verify that incoming requests are genuinely from Slack.
openclaw.json 
{
  "channels": {
    "slack": {
      "enabled": true,
      "mode": "http",
      "botToken": "xoxb-...",
      "signingSecret": "your-signing-secret",
      "webhookPath": "/slack/events"
    }
  }
}
For HTTP mode, all three endpoints (Events, Interactivity, Slash Commands) should point to the same URL: https://your-host/slack/events.
Use the Signing Secret (not the App Token) for HTTP mode. The Signing Secret verifies request authenticity via HMAC-SHA256 signatures.
HTTP mode requires a valid SSL certificate and a publicly accessible endpoint. Make sure your server is reachable from Slack's IP ranges.

Advanced Configuration

OpenClaw provides several advanced settings for fine-tuning Slack behavior: History & Context: • historyLimit (default: 50) — Number of recent messages included in AI context. Set to 0 to disable history injection. Text & Media: • textChunkLimit (default: 4000) — Maximum characters per message chunk for long responses • chunkMode: "newline" — Split at paragraph boundaries instead of hard character limits • mediaMaxMb (default: 20) — Maximum media file size in megabytes Tool Action Gates: Control which Slack operations the agent can perform: • reactions: true — React to and list reactions • messages: true — Read, send, edit, and delete messages • pins: true — Pin, unpin, and list pinned messages • memberInfo: true — Look up workspace member information • emojiList: true — List custom workspace emoji Security Notes: • Write operations default to Bot Token, maintaining application-level permission isolation • When userTokenReadOnly is false and a User Token is configured, writes may use the User Token (acting as the installing user) • When enabling allowBots on a channel, combine with requireMention and user allowlists to prevent bot-to-bot response loops
openclaw.json 
{
  "channels": {
    "slack": {
      "historyLimit": 50,
      "textChunkLimit": 4000,
      "chunkMode": "newline",
      "mediaMaxMb": 20,
      "actions": {
        "reactions": true,
        "messages": true,
        "pins": true,
        "memberInfo": true,
        "emojiList": true
      }
    }
  }
}

Slack Configuration Reference

enabled
Type: boolean Default: true

Enable or disable the Slack channel

mode
Type: string Default: "socket"

Connection mode. Options: socket (Socket Mode, default), http (Events API)

appToken
Type: string Default: ""

Slack App-Level Token (xapp-...) for Socket Mode. Can also use SLACK_APP_TOKEN env var

botToken
Type: string Default: ""

Slack Bot User OAuth Token (xoxb-...). Can also use SLACK_BOT_TOKEN env var

userToken
Type: string Default: ""

Optional Slack User Token (xoxp-...) for enhanced read access

userTokenReadOnly
Type: boolean Default: true

Restrict User Token to read-only operations. Set false to allow writes as the installing user

signingSecret
Type: string Default: ""

Signing Secret for HTTP mode request verification (from Basic Information → App Credentials)

webhookPath
Type: string Default: "/slack/events"

Webhook endpoint path for HTTP mode

dm.policy
Type: string Default: "pairing"

DM access control policy. Options: pairing (code-based approval), open (anyone can DM)

dm.allowFrom
Type: string[] Default: []

Users allowed to DM the bot. Supports user IDs, @usernames, emails, and wildcard (*)

dm.enabled
Type: boolean Default: true

Whether to accept direct messages

dm.groupEnabled
Type: boolean Default: false

Enable group DM (MPIM) handling

dm.groupChannels
Type: string[] Default: []

Allowed group DM channel IDs

groupPolicy
Type: string Default: "open"

Channel handling policy. Options: open (all channels), disabled (no channels), allowlist (configured only)

channels.<id>.allow
Type: boolean Default: true

Allow or deny this channel in allowlist mode

channels.<id>.requireMention
Type: boolean Default: false

Whether the bot needs @mention to respond in this channel

channels.<id>.users
Type: string[] Default: []

User allowlist for this channel (IDs, @usernames, or emails)

channels.<id>.skills
Type: string[] Default: []

Restrict available skills in this channel (empty = all skills)

channels.<id>.systemPrompt
Type: string Default: ""

Custom AI system prompt for this channel

channels.<id>.allowBots
Type: boolean Default: false

Process messages from other bots in this channel

replyToMode
Type: string Default: "off"

Reply threading mode. Options: off (main channel), first (thread first reply), all (thread all replies)

replyToModeByChatType
Type: object Default: {}

Per-chat-type threading overrides. Keys: direct, group, channel. Values: off, first, all

reactionNotifications
Type: string Default: "off"

Which reactions trigger agent notifications. Options: off, own, all

historyLimit
Type: number Default: 50

Number of recent messages to include as AI context. Set to 0 to disable

textChunkLimit
Type: number Default: 4000

Maximum characters per message chunk for long AI responses

chunkMode
Type: string Default: "split"

How to split long responses. Options: split (hard limit), newline (paragraph boundaries)

mediaMaxMb
Type: number Default: 20

Maximum media file size in megabytes

slashCommand.enabled
Type: boolean Default: true

Enable slash command handling

slashCommand.name
Type: string Default: "openclaw"

The slash command name (without /)

slashCommand.ephemeral
Type: boolean Default: true

Whether slash command responses are visible only to the invoker

Slack Frequently Asked Questions

Slack Troubleshooting

Bot doesn't respond in channels

The channel is blocked by groupPolicy, or the bot isn't in the allowlist, or the bot hasn't been invited to the channel.

Check your groupPolicy setting. If using 'allowlist', make sure the channel ID or name is configured with 'allow: true'. Verify the bot has been invited to the channel (/invite @YourBotName). Check Gateway logs for 'blocked by group policy' messages.
DMs to the bot are ignored

DM policy is set to 'pairing' and the sender hasn't been approved, or the Messages Tab isn't enabled in App Home.

If using pairing mode, check pending pairings with 'openclaw pairing list slack' and approve via 'openclaw pairing approve slack <code>'. Enable the Messages Tab in App Home (Slack API portal → App Home → Show Tab). Verify dm.policy is not set to 'disabled'.
Socket Mode connection fails or keeps disconnecting

The App Token (xapp-...) is invalid or expired, or there's a network issue between your server and Slack.

Verify your App Token is correct and has the connections:write scope. Regenerate the App Token in the Slack API portal if needed. Check Gateway logs for WebSocket connection errors. Ensure your server has stable internet access to wss://wss-primary.slack.com.
API errors (missing_scope or invalid_auth)

The Bot Token is missing required OAuth scopes, or the token has been revoked/regenerated.

Go to OAuth & Permissions in the Slack API portal and verify all required scopes are added. If scopes were recently added, reinstall the app to your workspace to apply the new permissions. Check that the token in your config matches the current token in the portal.
Slash commands show 'dispatch_failed' or don't appear

The slash command wasn't created in the Slack API portal, or the request URL is misconfigured (HTTP mode).

Create the /openclaw command under Slash Commands in the API portal. For Socket Mode, no URL is needed. For HTTP mode, set the Request URL to https://your-host/slack/events. After adding the command, you may need to reinstall the app to the workspace.
Messages are truncated or sent as multiple chunks

Long AI responses exceed OpenClaw's textChunkLimit (default: 4,000 characters) and are automatically split into multiple messages. Note: Slack's own limits are 3,000 characters per section block and 40,000 characters per message text field.

This is expected behavior. Adjust textChunkLimit to control chunk size (default: 4000). Set chunkMode to 'newline' to split at paragraph boundaries for more natural chunking. Consider instructing the AI to keep responses concise via systemPrompt.
View Full Documentation Back to All Channels

Related Channels

Feishu / Lark

Medium

OpenClaw Feishu/Lark integration via WebSocket

Setup Guide

Google Chat

Medium

OpenClaw Google Chat API app via HTTP endpoint

Setup Guide

Microsoft Teams

Medium

OpenClaw enterprise integration via Bot Framework

Setup Guide