Slack

Run your ZeroClaw agent as a Slack bot. This guide walks you through it step by step. By the end you’ll have a bot in your workspace that answers when people message it or @-mention it.

Who can talk to the agent

Inbound senders are gated against the peer set resolved for the bound agent, drawn from the peer_groups config the agent belongs to. Matching strips a leading @ and is case-insensitive against the channel’s native sender identifier. An empty set denies everyone; a set containing "*" accepts anyone; otherwise only the listed external peers (and peer agents) are accepted. This is separate from gateway pairing (gateway.require_pairing), which authenticates HTTP/WebSocket clients, not chat-channel senders.

A peer group for slack sets channel to slack, lists the allowed senders in external_peers (for slack, the Slack user ID; ["*"] accepts anyone), optionally names peer agents for cross-agent dispatch, an ignore blocklist, and an output_modality (mirror, voice, or text). See Peer Groups for the field reference.

Where to set this:

Quickstart

Slack needs two tokens: a bot token (what the bot speaks with) and an app token (lets the bot connect without you hosting a public URL). Both come from the same app page.

1. Create the Slack app

1. Go to api.slack.com/apps and click Create New App -> From scratch.
2. Name it, pick your workspace, and Create App.

2. Add the permissions the bot needs

1. In the left sidebar, open OAuth & Permissions.
2. Under Scopes -> Bot Token Scopes, add: app_mentions:read, channels:history, chat:write, and channels:read. (Add im:history and im:write too if you want direct messages.)

3. Turn on Socket Mode and get the app token

1. In the left sidebar, open Socket Mode and toggle it on.
2. Slack prompts you to create an app-level token. Name it, give it the connections:write scope, and Generate.
3. Copy the token that starts with xapp-. This is your app_token.

Socket Mode lets the bot hold an outbound connection to Slack, so you don’t need a public webhook URL or any port forwarding. This is the easy path.

4. Install the app and get the bot token

1. Open Install App in the sidebar and click Install to Workspace, then Allow.
2. Back on OAuth & Permissions, copy the Bot User OAuth Token that starts with xoxb-. This is your bot_token.

5. Tell ZeroClaw about both tokens

Both tokens are secrets, so set them through a surface that encrypts them:

channels.slack.<alias>.bot_token is a secret. Stored encrypted, never in plain config.toml. Set it through one of these, which encrypt on write:

zeroclaw config set channels.slack.<alias>.bot_token    # prompts for masked input, stores encrypted

Set app_token the same way (it’s the xapp- token from step 3).

6. Invite the bot and test

In Slack, go to a channel and type /invite @YourBotName. Then send a message or @-mention the bot. Start ZeroClaw (zeroclaw service restart or zeroclaw daemon) and it should reply. If not, see Troubleshooting.

Configuration

The full field list, derived from the live schema. For a basic Socket Mode bot you only set bot_token and app_token.

zeroclaw config set channels.slack.<alias>.app_token    # masked input, stored encrypted

export ZEROCLAW_channels__slack__<alias>__app_token=

zeroclaw config set channels.slack.<alias>.approval_timeout_secs <value>

export ZEROCLAW_channels__slack__<alias>__approval_timeout_secs=

zeroclaw config set channels.slack.<alias>.bot_token    # masked input, stored encrypted

export ZEROCLAW_channels__slack__<alias>__bot_token=

zeroclaw config set channels.slack.<alias>.cancel_reaction <value>

export ZEROCLAW_channels__slack__<alias>__cancel_reaction=

zeroclaw config set channels.slack.<alias>.channel_ids <value>

export ZEROCLAW_channels__slack__<alias>__channel_ids=

zeroclaw config set channels.slack.<alias>.draft_update_interval_ms <value>

export ZEROCLAW_channels__slack__<alias>__draft_update_interval_ms=

zeroclaw config set channels.slack.<alias>.excluded_tools <value>

export ZEROCLAW_channels__slack__<alias>__excluded_tools=

zeroclaw config set channels.slack.<alias>.interrupt_on_new_message <value>

export ZEROCLAW_channels__slack__<alias>__interrupt_on_new_message=

zeroclaw config set channels.slack.<alias>.mention_only <value>

export ZEROCLAW_channels__slack__<alias>__mention_only=

zeroclaw config set channels.slack.<alias>.proxy_url <value>

export ZEROCLAW_channels__slack__<alias>__proxy_url=

zeroclaw config set channels.slack.<alias>.reply_min_interval_secs <value>

export ZEROCLAW_channels__slack__<alias>__reply_min_interval_secs=

zeroclaw config set channels.slack.<alias>.reply_queue_depth_max <value>

export ZEROCLAW_channels__slack__<alias>__reply_queue_depth_max=

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

export ZEROCLAW_channels__slack__<alias>__stream_drafts=

zeroclaw config set channels.slack.<alias>.strict_mention_in_thread <value>

export ZEROCLAW_channels__slack__<alias>__strict_mention_in_thread=

zeroclaw config set channels.slack.<alias>.thread_replies <value>

export ZEROCLAW_channels__slack__<alias>__thread_replies=

zeroclaw config set channels.slack.<alias>.use_markdown_blocks <value>

export ZEROCLAW_channels__slack__<alias>__use_markdown_blocks=

Socket Mode vs HTTP

When app_token is set, the bot uses Socket Mode: it dials out to Slack, so no public URL is required. This is the recommended setup and what the quickstart above uses. Without an app_token, Slack must reach your bot over HTTP, which means hosting a public events endpoint, more setup and more to secure.

Threads and context

When a Slack conversation happens in a thread, that thread is its own conversation. ZeroClaw derives a distinct session key per thread, so every thread carries an independent context window and history: messages in one thread never bleed into another, and the agent does not see a sibling thread’s earlier turns. For Slack this is controlled by thread_replies: when it is on, top-level messages open a thread and each thread is a separate conversation; when off, replies post at the channel root and history is keyed by sender and target instead of by thread.

• Isolation is the point. Each thread’s context is self-contained: it does not leak outside the thread, and nothing from outside the thread leaks in. Parallel threads hold separate conversational state, so unrelated tasks never contaminate each other.
• Long threads grow context. A thread accumulates history while it stays active, so a very long thread eventually fills the model’s context window like any other long conversation. Start a new thread to reset.
• In-flight work is scoped per thread. A new message in one thread does not cancel an in-flight response in another; each thread’s task stands alone.

Set the thread behavior on any surface:

zeroclaw config set channels.slack.<alias>.thread_replies true     # thread replies on
zeroclaw config set channels.slack.<alias>.thread_replies false    # replies at the channel root

strict_mention_in_thread tightens this further: when true, the bot only answers inside a thread if a message there @-mentions it, instead of replying to every message in a thread it’s part of.

Mentions and formatting

• mention_only: when true, the bot only answers messages that @-mention it, keeping it quiet in busy channels.
• use_markdown_blocks: render replies with Slack Block Kit formatting for richer layout. Turn off for plain text.

Streaming

Slack streams replies via the stream_drafts boolean:

• false (default): the whole reply posts as one message once the agent finishes.
• true: the bot posts a placeholder immediately and edits it in place as the answer streams in. draft_update_interval_ms paces the edits; raise it if Slack rate-limits them.

Set it on any surface:

zeroclaw config set channels.slack.<alias>.stream_drafts <value>

draft_update_interval_ms controls how often the streaming draft is edited (raise it if Slack rate-limits the edits), and cancel_reaction sets an emoji users can react with to cancel an in-flight reply.

Troubleshooting

See also

• Who can talk to the agent (peer groups)
• Discord
• Channels overview