Both transports are production-ready and reach feature parity for messaging, slash commands, App Home, and interactivity. Pick by deployment shape, not features.
Concern
Socket Mode (default)
HTTP Request URLs
Public Gateway URL
Not required
Required (DNS, TLS, reverse proxy or tunnel)
Outbound network
Outbound WSS to wss-primary.slack.com must be reachable
No outbound WS; inbound HTTPS only
Tokens needed
Bot token + App-Level Token with connections:write
Bot token + Signing Secret
Dev laptop / behind firewall
Works as-is
Needs a public tunnel (ngrok, Cloudflare Tunnel, Tailscale Funnel) or staging Gateway
Horizontal scaling
One Socket Mode session per app per host; multiple Gateways need separate Slack apps
Stateless POST handler; multiple Gateway replicas can share one app behind a load balancer
Multi-account on one Gateway
Supported; each account opens its own WS
Supported; each account needs a unique webhookPath (default /slack/events) so registrations do not collide
Slash command transport
Delivered over the WS connection; slash_commands[].url is ignored
Slack POSTs to slash_commands[].url; field is required for the command to dispatch
Request signing
Not used (auth is the App-Level Token)
Slack signs every request; OpenClaw verifies with signingSecret
Recovery on connection drop
Slack SDK auto-reconnect is enabled; OpenClaw also restarts failed Socket Mode sessions with bounded backoff. Pong-timeout transport tuning applies.
No persistent connection to drop; retries are per-request from Slack
plugins install registers and enables the plugin. The plugin still does nothing until you configure the Slack app and channel settings below. See Plugins for general plugin behavior and install rules.
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.
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:
{
channels: {
slack: {
mode: "socket",
socketMode: {
clientPingTimeout: 20000,
serverPingTimeout: 30000,
pingPongLoggingEnabled: false,
},
},
},
}
Use this only for Socket Mode workspaces that log Slack websocket pong/server-ping timeouts or run on hosts with known event-loop starvation. 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.
Notes:
socketMode is ignored in HTTP Request URL mode.
Base channels.slack.socketMode settings apply to all Slack accounts unless overridden. Per-account overrides use `channels.slack.accounts.
.socketMode`; because this is an object override, include every socket tuning field you want for that account.
Only clientPingTimeout has an OpenClaw default (15000). serverPingTimeout and pingPongLoggingEnabled are passed to the Slack SDK only when configured.
Socket Mode restart backoff starts around 2 seconds and caps around 30 seconds. Consecutive recoverable start/start-wait failures stop after 12 attempts; after a successful connection, later recoverable disconnects start a fresh retry cycle. Non-recoverable Slack auth errors such as invalid_auth, revoked tokens, or missing scopes fail fast instead of retrying forever.
Surface different features that extend the above defaults.
The default manifest enables the Slack App Home Home tab and subscribes to app_home_opened. When a workspace member opens the Home tab, OpenClaw publishes a safe default Home view with views.publish; no conversation payload or private configuration is included. The Messages tab remains enabled for Slack DMs. The manifest also enables Slack assistant threads with features.assistant_view, assistant:write, assistant_thread_started, and assistant_thread_context_changed; assistant threads route to their own OpenClaw thread sessions and keep Slack-provided thread context available to the agent.
Optional native slash commands
Multiple native slash commands can be used instead of a single configured command with nuance:
Use /agentstatus instead of /status because the /status command is reserved.
No more than 25 slash commands can be made available at once.
Replace your existing features.slash_commands section with a subset of available commands:
”
},
{
“command”: “/model”,
“description”: “Show or set the model”,
“usage_hint”: “[name|#|status]”
},
{
“command”: “/models”,
“description”: “List providers/models”,
“usage_hint”: “[provider] [page] [limit=
|size=
|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”: ”
[input]”
},
{
“command”: “/btw”,
“description”: “Ask a side question without changing session context”,
“usage_hint”: ”
”
},
{
“command”: “/side”,
“description”: “Ask a side question without changing session context”,
“usage_hint”: ”
”
},
{
“command”: “/usage”,
“description”: “Control the usage footer or show cost summary”,
“usage_hint”: “off|tokens|full|cost”
}
]
}
Use the same `slash_commands` list as Socket Mode above, and add `"url": "https://gateway-host.example.com/slack/events"` to every entry. Example:
Repeat that `url` value on every command in the list.
Optional authorship scopes (write operations)
Add the chat:write.customize bot scope if you want outgoing messages to use the active agent identity (custom username and icon) instead of the default Slack app identity.
If you use an emoji icon, Slack expects :emoji_name: syntax.
Optional user-token scopes (read operations)
If you configure channels.slack.userToken, typical read scopes are:
Status is available, configured_unavailable, or missing.
configured_unavailable means 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, signingSecretStatus is included; in Socket Mode, the
required pair is botTokenStatus + appTokenStatus.
Slack actions are controlled by channels.slack.actions.*.
Available action groups in current Slack tooling:
Group
Default
messages
enabled
reactions
enabled
pins
enabled
memberInfo
enabled
emojiList
enabled
Current Slack message actions include 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.
channels.slack.dmPolicy controls DM access. channels.slack.allowFrom is the canonical DM allowlist.
pairing (default)
allowlist
open (requires channels.slack.allowFrom to include "*")
disabled
DM flags:
dm.enabled (default true)
channels.slack.allowFrom
dm.allowFrom (legacy)
dm.groupEnabled (group DMs default false)
dm.groupChannels (optional MPIM allowlist)
Multi-account precedence:
channels.slack.accounts.default.allowFrom applies only to the default account.
Named accounts inherit channels.slack.allowFrom when their own allowFrom is unset.
Named accounts do not inherit channels.slack.accounts.default.allowFrom.
Legacy channels.slack.dm.policy and channels.slack.dm.allowFrom still read for compatibility. openclaw doctor --fix migrates them to dmPolicy and allowFrom when it can do so without changing access.
Pairing in DMs uses `openclaw pairing approve slack
DMs route as direct; channels as channel; MPIMs as group.
Slack route bindings accept raw peer IDs plus Slack target forms such as channel:C12345678, user:U12345678, and <@U12345678>.
With default session.dmScope=main, Slack DMs collapse to agent main session.
Channel sessions: `agent:
:slack:channel:
`.
Ordinary top-level channel messages stay on the per-channel session, even when replyToMode is non-off.
Slack thread replies use the parent Slack thread_ts for session suffixes (`:thread:
), even when outbound reply threading is disabled with replyToMode=“off”`.
OpenClaw seeds an eligible top-level channel root into `agent:
:slack:channel:
:thread:
when that root is expected to start a visible Slack thread, so the root and later thread replies share one OpenClaw session. This applies toapp_mentionevents, explicit bot or configured mention-pattern matches, andrequireMention: false channels with non-offreplyToMode`.
channels.slack.thread.historyScope default is thread; thread.inheritParent default is false.
channels.slack.thread.initialHistoryLimit controls how many existing thread messages are fetched when a new thread session starts (default 20; set 0 to disable).
channels.slack.thread.requireExplicitMention (default false): when true, suppress implicit thread mentions so the bot only responds to explicit @bot mentions inside threads, even when the bot already participated in the thread. Without this, replies in a bot-participated thread bypass requireMention gating.
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:
]]`
For explicit Slack thread replies from the message tool, set replyBroadcast: true with action: "send" and threadId or replyTo to ask Slack to also broadcast the thread reply to the parent channel. This maps to Slack’s chat.postMessagereply_broadcast flag and is only supported for text or Block Kit sends, not media uploads.
When a message tool call runs inside a Slack thread and targets the same channel, OpenClaw normally inherits the current Slack thread according to replyToMode. Set topLevel: true on action: "send" or action: "upload-file" to force a new parent-channel message instead. threadId: null is accepted as the same top-level opt-out.
The Slack provider reads scope from messages.ackReactionScope (default "group-mentions"). There is no Slack-account or Slack-channel-level override today; the value is global to the gateway.
Values:
"all": react in DMs and groups.
"direct": react in DMs only.
"group-all": react on every group message (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.
{
messages: {
ackReaction: "eyes",
ackReactionScope: "all", // react in DMs and groups
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). Set false to keep separate tool/progress messages.
streaming.preview.commandText / streaming.progress.commandText: set to status to keep compact tool-progress lines while hiding raw command/exec text (default: raw).
Hide raw command/exec text while keeping compact progress lines:
{
"channels": {
"slack": {
"streaming": {
"mode": "progress",
"progress": {
"toolProgress": true,
"commandText": "status"
}
}
}
}
}
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, group-chat, and top-level DM roots can still use the normal draft preview when native streaming is unavailable or no reply thread exists.
Top-level Slack DMs stay off-thread by default, so they do not show Slack’s thread-style native stream/status preview; OpenClaw posts and edits a draft preview in the DM instead.
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.
Use draft preview instead of Slack native text streaming:
{
channels: {
slack: {
streaming: {
mode: "partial",
nativeTransport: false,
},
},
},
}
Legacy keys:
channels.slack.streamMode (replace | status_final | append) is a legacy runtime alias for channels.slack.streaming.mode.
boolean channels.slack.streaming is a legacy runtime alias for channels.slack.streaming.mode and channels.slack.streaming.nativeTransport.
legacy channels.slack.nativeStreaming is a runtime alias for channels.slack.streaming.nativeTransport.
Run openclaw doctor --fix to rewrite persisted Slack streaming config to the canonical keys.
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.
.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.
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 4000)
file sends use Slack upload APIs and can include thread replies (thread_ts)
outbound media cap follows channels.slack.mediaMaxMb when configured; otherwise channel sends use MIME-kind defaults from media pipeline
Delivery targets
Preferred explicit targets:
`user:
for DMs -channel:
` 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.
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 so commands.native: "auto" does not enable Slack native commands.
/help
Native argument menus use an adaptive rendering strategy that shows a confirmation modal before dispatching a selected option value:
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
/think
Slash sessions use isolated keys like `agent:
:slack:slash:
and still route command executions to the target conversation session usingCommandTargetSessionKey`.
Slack can render agent-authored interactive reply controls, but this feature is disabled by default.
For new agent, CLI, and plugin output, prefer the shared
presentation buttons or select blocks. They use the same Slack interaction
path while also degrading on other channels.
Enable it globally:
{
channels: {
slack: {
capabilities: {
interactiveReplies: true,
},
},
},
}
Or enable it for one Slack account only:
{
channels: {
slack: {
accounts: {
ops: {
capabilities: {
interactiveReplies: true,
},
},
},
},
},
}
When enabled, agents can still emit deprecated Slack-only reply directives:
[[slack_buttons: Approve:approve, Reject:reject]]
[[slack_select: Choose a target | Canary:canary, Production:production]]
These directives compile into Slack Block Kit and route clicks or selections
back through the existing Slack interaction event path. Keep them for old
prompts and Slack-specific escape hatches; use shared presentation for new
portable controls.
The directive compiler APIs are also deprecated for new producer code:
compileSlackInteractiveReplies(...)
parseSlackOptionsLine(...)
isSlackInteractiveRepliesEnabled(...)
buildSlackInteractiveBlocks(...)
Use presentation payloads and buildSlackPresentationBlocks(...) for new
Slack-rendered controls.
Notes:
This is Slack-specific legacy 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.
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:
:
`.
Or keep an existing callback_id and put `pluginInteractiveData:
”
:
“in the modalprivate_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.
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 render as Slack-native Block Kit prompts.
channels.slack.execApprovals.* remains the native exec approval client enablement and DM/channel routing config.
Exec approval DMs use channels.slack.execApprovals.approvers or commands.ownerAllowFrom.
Plugin approvals use Slack-native buttons when Slack is enabled as a native approval client for the originating session, or when approvals.plugin routes 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 is still enforced: exec-only approvers cannot approve plugin requests unless they are also plugin approvers.
This uses the same shared approval button surface as other channels. When 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.enabled
channels.slack.execApprovals.approvers (optional; falls back to commands.ownerAllowFrom when possible)
Slack auto-enables native exec approvals when enabled is unset or "auto" and at least one
exec approver resolves. Slack can also handle native plugin approvals through this native-client
path when Slack plugin approvers resolve and the request matches the native-client filters. Set
enabled: false to disable Slack as a native approval client explicitly. Set enabled: true to
force native approvals on when approvers resolve. Disabling Slack exec approvals does not disable
native Slack plugin approval delivery that is enabled through approvals.plugin; plugin approval
delivery uses Slack plugin approvers instead.
Default behavior with no explicit Slack exec approval config:
{
commands: {
ownerAllowFrom: ["slack:U12345678"],
},
}
Explicit Slack-native config is only needed when you want to override approvers, add filters, or
opt into origin-chat delivery:
{
channels: {
slack: {
execApprovals: {
enabled: true,
approvers: ["U12345678"],
target: "both",
},
},
},
}
Shared 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 delivery suppresses that fallback only when Slack can handle the plugin
approval request natively.
Same-chat /approve also works in Slack channels and DMs that already support commands. See Exec approvals for the full approval forwarding model.
unfurls: unfurlLinks (default: false), unfurlMedia for chat.postMessage link/media preview control; set unfurlLinks: true to opt back into link previews
- channel allowlist (`channels.slack.channels`) — **keys must be channel IDs** (`C12345678`), 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](/en/channels/ambient-room-events).
usually mean Slack sent an edited Assistant-thread event without a
recoverable human sender in message metadata
Terminal window
openclawpairinglistslack
Socket mode not connecting
Validate bot + app tokens and Socket Mode enablement in 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 shows 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.
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
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)
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.useAccessGroups, DM authorization, channel allowlists,
and per-channel users allowlists. Slack returns ephemeral errors for
blocked slash-command senders, including:
Slack can attach downloaded media to the agent turn when Slack file downloads succeed and size limits permit. Image files can be passed through the media understanding path or directly to a vision-capable reply model; other files are retained as downloadable file context rather than treated as image input.
Size cap: Default 20 MB per file. Configurable via channels.slack.mediaMaxMb.
Download failures: Files that Slack cannot serve, expired URLs, inaccessible files, oversize files, and Slack auth/login HTML responses are skipped instead of being reported as unsupported formats.
Vision model: Image analysis uses the active reply model when it supports vision, or the image model configured at agents.defaults.imageModel.