Production-ready for DMs and channels via Slack app integrations. Default mode is Socket Mode; HTTP Request URLs are also supported.Documentation Index
Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt
Use this file to discover all available pages before exploring further.
Pairing
Slack DMs default to pairing mode.
Slash commands
Native command behavior and command catalog.
Channel troubleshooting
Cross-channel diagnostics and repair playbooks.
Quick setup
- Socket Mode (default)
- HTTP Request URLs
Create a new Slack app
In Slack app settings press the Create New App button:
- choose from a manifest and select a workspace for your app
- paste the example manifest from below and continue to create
- generate an App-Level Token (
xapp-...) withconnections:write - install app and copy the Bot Token (
xoxb-...) shown
Socket Mode transport tuning
OpenClaw sets the Slack SDK client pong timeout to 15 seconds by default for Socket Mode. Override the transport settings only when you need workspace- or host-specific tuning:clientPingTimeout is the pong wait after the SDK sends a client ping; serverPingTimeout is the wait for Slack server pings. App messages and events remain application state, not transport liveness signals.
Manifest and scope checklist
The base Slack app manifest is the same for Socket Mode and HTTP Request URLs. Only thesettings block (and the slash command url) differs.
Base manifest (Socket Mode default):
settings with the HTTP variant and add url to each slash command. Public URL required:
Additional manifest settings
Surface different features that extend the above defaults.Optional native slash commands
Optional native slash commands
Multiple native slash commands can be used instead of a single configured command with nuance:
- Use
/agentstatusinstead of/statusbecause the/statuscommand is reserved. - No more than 25 slash commands can be made available at once.
features.slash_commands section with a subset of available commands:- Socket Mode (default)
- HTTP Request URLs
Optional authorship scopes (write operations)
Optional authorship scopes (write operations)
Optional user-token scopes (read operations)
Optional user-token scopes (read operations)
If you configure
channels.slack.userToken, typical read scopes are:channels:history,groups:history,im:history,mpim:historychannels:read,groups:read,im:read,mpim:readusers:readreactions:readpins:reademoji:readsearch:read(if you depend on Slack search reads)
Token model
botToken+appTokenare required for Socket Mode.- HTTP mode requires
botToken+signingSecret. botToken,appToken,signingSecret, anduserTokenaccept plaintext strings or SecretRef objects.- Config tokens override env fallback.
SLACK_BOT_TOKEN/SLACK_APP_TOKENenv fallback applies only to the default account.userToken(xoxp-...) is config-only (no env fallback) and defaults to read-only behavior (userTokenReadOnly: true).
- Slack account inspection tracks per-credential
*Sourceand*Statusfields (botToken,appToken,signingSecret,userToken). - Status is
available,configured_unavailable, ormissing. configured_unavailablemeans the account is configured through SecretRef or another non-inline secret source, but the current command/runtime path could not resolve the actual value.- In HTTP mode,
signingSecretStatusis included; in Socket Mode, the required pair isbotTokenStatus+appTokenStatus.
Actions and gates
Slack actions are controlled bychannels.slack.actions.*.
Available action groups in current Slack tooling:
| Group | Default |
|---|---|
| messages | enabled |
| reactions | enabled |
| pins | enabled |
| memberInfo | enabled |
| emojiList | enabled |
send, upload-file, download-file, read, edit, delete, pin, unpin, list-pins, member-info, and emoji-list. download-file accepts Slack file IDs shown in inbound file placeholders and returns image previews for images or local file metadata for other file types.
Access control and routing
- DM policy
- Channel policy
- Mentions and channel users
channels.slack.dmPolicy controls DM access (legacy: channels.slack.dm.policy):pairing(default)allowlistopen(requireschannels.slack.allowFromto include"*"; legacy:channels.slack.dm.allowFrom)disabled
dm.enabled(default true)channels.slack.allowFrom(preferred)dm.allowFrom(legacy)dm.groupEnabled(group DMs default false)dm.groupChannels(optional MPIM allowlist)
channels.slack.accounts.default.allowFromapplies only to thedefaultaccount.- Named accounts inherit
channels.slack.allowFromwhen their ownallowFromis unset. - Named accounts do not inherit
channels.slack.accounts.default.allowFrom.
openclaw pairing approve slack <code>.Threading, sessions, and reply tags
- DMs route as
direct; channels aschannel; MPIMs asgroup. - With default
session.dmScope=main, Slack DMs collapse to agent main session. - Channel sessions:
agent:<agentId>:slack:channel:<channelId>. - Thread replies can create thread session suffixes (
:thread:<threadTs>) when applicable. channels.slack.thread.historyScopedefault isthread;thread.inheritParentdefault isfalse.channels.slack.thread.initialHistoryLimitcontrols how many existing thread messages are fetched when a new thread session starts (default20; set0to disable).channels.slack.thread.requireExplicitMention(defaultfalse): whentrue, suppress implicit thread mentions so the bot only responds to explicit@botmentions inside threads, even when the bot already participated in the thread. Without this, replies in a bot-participated thread bypassrequireMentiongating.
channels.slack.replyToMode:off|first|all|batched(defaultoff)channels.slack.replyToModeByChatType: perdirect|group|channel- legacy fallback for direct chats:
channels.slack.dm.replyToMode
[[reply_to_current]][[reply_to:<id>]]
replyToMode="off" disables all reply threading in Slack, including explicit [[reply_to_*]] tags. This differs from Telegram, where explicit tags are still honored in "off" mode. Slack threads hide messages from the channel while Telegram replies stay visible inline.Ack reactions
ackReaction sends an acknowledgement emoji while OpenClaw is processing an inbound message.
Resolution order:
channels.slack.accounts.<accountId>.ackReactionchannels.slack.ackReactionmessages.ackReaction- agent identity emoji fallback (
agents.list[].identity.emoji, else ”👀”)
- Slack expects shortcodes (for example
"eyes"). - Use
""to disable the reaction for the Slack account or globally.
Text streaming
channels.slack.streaming controls live preview behavior:
off: disable live preview streaming.partial(default): replace preview text with the latest partial output.block: append chunked preview updates.progress: show progress status text while generating, then send final text.streaming.preview.toolProgress: when draft preview is active, route tool/progress updates into the same edited preview message (default:true). Setfalseto keep separate tool/progress messages.
channels.slack.streaming.nativeTransport controls Slack native text streaming when channels.slack.streaming.mode is partial (default: true).
- A reply thread must be available for native text streaming and Slack assistant thread status to appear. Thread selection still follows
replyToMode. - Channel and group-chat roots can still use the normal draft preview when native streaming is unavailable.
- Top-level Slack DMs stay off-thread by default, so they do not show the thread-style preview; use thread replies or
typingReactionif you want visible progress there. - Media and non-text payloads fall back to normal delivery.
- Media/error finals cancel pending preview edits; eligible text/block finals flush only when they can edit the preview in place.
- If streaming fails mid-reply, OpenClaw falls back to normal delivery for remaining payloads.
channels.slack.streamMode(replace | status_final | append) is auto-migrated tochannels.slack.streaming.mode.- boolean
channels.slack.streamingis auto-migrated tochannels.slack.streaming.modeandchannels.slack.streaming.nativeTransport. - legacy
channels.slack.nativeStreamingis auto-migrated tochannels.slack.streaming.nativeTransport.
Typing reaction fallback
typingReaction adds a temporary reaction to the inbound Slack message while OpenClaw is processing a reply, then removes it when the run finishes. This is most useful outside of thread replies, which use a default “is typing…” status indicator.
Resolution order:
channels.slack.accounts.<accountId>.typingReactionchannels.slack.typingReaction
- 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.
Media, chunking, and delivery
Inbound attachments
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
Outbound text and files
- text chunks use
channels.slack.textChunkLimit(default 4000) channels.slack.chunkMode="newline"enables paragraph-first splitting- file sends use Slack upload APIs and can include thread replies (
thread_ts) - outbound media cap follows
channels.slack.mediaMaxMbwhen configured; otherwise channel sends use MIME-kind defaults from media pipeline
Delivery targets
Delivery targets
Preferred explicit targets:
user:<id>for DMschannel:<id>for channels
Commands and slash behavior
Slash commands appear in Slack as either a single configured command or multiple native commands. Configurechannels.slack.slashCommand to change command defaults:
enabled: falsename: "openclaw"sessionPrefix: "slack:slash"ephemeral: true
channels.slack.commands.native: true or commands.native: true in global configurations instead.
- Native command auto-mode is off for Slack so
commands.native: "auto"does not enable Slack native commands.
- up to 5 options: button blocks
- 6-100 options: static select menu
- more than 100 options: external select with async option filtering when interactivity options handlers are available
- exceeded Slack limits: encoded option values fall back to buttons
agent:<agentId>:slack:slash:<userId> and still route command executions to the target conversation session using CommandTargetSessionKey.
Interactive replies
Slack can render agent-authored interactive reply controls, but this feature is disabled by default. Enable it globally:[[slack_buttons: Approve:approve, Reject:reject]][[slack_select: Choose a target | Canary:canary, Production:production]]
- This is Slack-specific UI. Other channels do not translate Slack Block Kit directives into their own button systems.
- The interactive callback values are OpenClaw-generated opaque tokens, not raw agent-authored values.
- If generated interactive blocks would exceed Slack Block Kit limits, OpenClaw falls back to the original text reply instead of sending an invalid blocks payload.
Exec 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 approvals use
channels.slack.execApprovals.*for native DM/channel routing. - Plugin approvals can still resolve through the same Slack-native button surface when the request already lands in Slack and the approval id kind is
plugin:. - Approver authorization is still enforced: only users identified as approvers can approve or deny requests through Slack.
interactivity is enabled in your Slack app settings, approval prompts render as Block Kit buttons directly in the conversation.
When those buttons are present, they are the primary approval UX; OpenClaw
should only include a manual /approve command when the tool result says chat
approvals are unavailable or manual approval is the only path.
Config path:
channels.slack.execApprovals.enabledchannels.slack.execApprovals.approvers(optional; falls back tocommands.ownerAllowFromwhen possible)channels.slack.execApprovals.target(dm|channel|both, default:dm)agentFilter,sessionFilter
enabled is unset or "auto" and at least one
approver resolves. Set enabled: false to disable Slack as a native approval client explicitly.
Set enabled: true to force native approvals on when approvers resolve.
Default behavior with no explicit Slack exec approval config:
approvals.exec forwarding is separate. Use it only when exec approval prompts must also
route to other chats or explicit out-of-band targets. Shared approvals.plugin forwarding is also
separate; Slack-native buttons can still resolve plugin approvals when those requests already land
in Slack.
Same-chat /approve also works in Slack channels and DMs that already support commands. See Exec approvals for the full approval forwarding model.
Events and operational behavior
- Message edits/deletes are mapped into system events.
- Thread broadcasts (“Also send to channel” thread replies) are processed as normal user messages.
- Reaction add/remove events are mapped into system events.
- Member join/leave, channel created/renamed, and pin add/remove events are mapped into system events.
channel_id_changedcan migrate channel config keys whenconfigWritesis enabled.- Channel topic/purpose metadata is treated as untrusted context and can be injected into routing context.
- Thread starter and initial thread-history context seeding are filtered by configured sender allowlists when applicable.
- Block actions and modal interactions emit structured
Slack interaction: ...system events with rich payload fields:- block actions: selected values, labels, picker values, and
workflow_*metadata - modal
view_submissionandview_closedevents with routed channel metadata and form inputs
- block actions: selected values, labels, picker values, and
Configuration reference
Primary reference: Configuration reference - Slack.High-signal Slack fields
High-signal Slack fields
- mode/auth:
mode,botToken,appToken,signingSecret,webhookPath,accounts.* - DM access:
dm.enabled,dmPolicy,allowFrom(legacy:dm.policy,dm.allowFrom),dm.groupEnabled,dm.groupChannels - compatibility toggle:
dangerouslyAllowNameMatching(break-glass; keep off unless needed) - channel access:
groupPolicy,channels.*,channels.*.users,channels.*.requireMention - threading/history:
replyToMode,replyToModeByChatType,thread.*,historyLimit,dmHistoryLimit,dms.*.historyLimit - delivery:
textChunkLimit,chunkMode,mediaMaxMb,streaming,streaming.nativeTransport,streaming.preview.toolProgress - ops/features:
configWrites,commands.native,slashCommand.*,actions.*,userToken,userTokenReadOnly
Troubleshooting
No replies in channels
No replies in channels
Check, in order:
groupPolicy- channel allowlist (
channels.slack.channels) requireMention- per-channel
usersallowlist
DM messages ignored
DM messages ignored
Check:
channels.slack.dm.enabledchannels.slack.dmPolicy(or legacychannels.slack.dm.policy)- pairing approvals / allowlist entries
- Slack Assistant DM events: verbose logs mentioning
drop message_changedusually mean Slack sent an edited Assistant-thread event without a recoverable human sender in message metadata
Socket mode not connecting
Socket mode not connecting
Validate bot + app tokens and Socket Mode enablement in Slack app settings.If
openclaw channels status --probe --json shows botTokenStatus or
appTokenStatus: "configured_unavailable", the Slack account is
configured but the current runtime could not resolve the SecretRef-backed
value.HTTP mode not receiving events
HTTP mode not receiving events
Validate:
- signing secret
- webhook path
- Slack Request URLs (Events + Interactivity + Slash Commands)
- unique
webhookPathper HTTP account
signingSecretStatus: "configured_unavailable" appears in account
snapshots, the HTTP account is configured but the current runtime could not
resolve the SecretRef-backed signing secret.Native/slash commands not firing
Native/slash commands not firing
Verify whether you intended:
- native command mode (
channels.slack.commands.native: true) with matching slash commands registered in Slack - or single slash command mode (
channels.slack.slashCommand.enabled: true)
commands.useAccessGroups and channel/user allowlists.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.