Connect Slack to an existing Agent by creating a Slack Communication Connection. You create the Slack app from a manifest, generate its tokens, and paste them into the Connection.
Slack works with both Hermes and OpenClaw. Agent Barn owns the Slack Socket Mode session through the Communications Gateway, and the Agent Runtime never receives Slack credentials.
Overview
Slack is not selected while creating the Agent. The Agent is created headless, and Slack is added afterward as a Connection.
- An Agent can have zero or many Communication Connections.
- The same Agent can have multiple Slack Connections, such as one per workspace.
- Slack works with both Hermes and OpenClaw, because provider support comes from the Slack Platform Plugin.
- The Communications Gateway holds the Socket Mode session, so no public inbound Slack endpoint is required.
- The Agent Runtime never receives the Slack bot or app-level token.
A Slack Connection requires:
- A Slack application with Socket Mode enabled
- The bot scopes and event subscriptions supplied by the manifest
- An app-level token beginning with
xapp- - A bot token beginning with
xoxb- - The application installed in the intended Slack workspace
See Communication Connections for the shared Connection lifecycle, and Compare platform compatibility for how Slack sits beside the other Platforms.
Slack connection model
Slack events reach the Agent through the Communications Gateway rather than directly:
- Slack events
- Slack Platform Plugin
- Communications Gateway
- Communication Delivery
- Hermes or OpenClaw
Replies return through the same path, and the Gateway sends them with the Connection's own credentials. Slack's Socket Mode delivers events over a WebSocket instead of posting them to a public Request URL.
Token types
| Credential | Prefix | Purpose | Required scope |
|---|---|---|---|
| App-level token | xapp- | Opens the Socket Mode connection held by the Communications Gateway | connections:write |
| Bot token | xoxb- | Authenticates Slack Web API calls as the bot | Bot scopes granted at installation |
Slack documents these as separate token types. Both belong to the Communication Connection, and both are required.
Do not use a user token beginning with xoxp-, a signing secret, or an incoming webhook URL.
Before you begin
You need:
- An existing Agent
- Permission to update that Agent and manage its Connection credentials
- Permission to create and install a Slack app in the target workspace
- A Slack bot token beginning with
xoxb- - A Slack app-level token beginning with
xapp-
Slack uses Socket Mode, so the deployment does not require a public inbound Slack webhook.
Your Slack workspace may require administrator approval before an application can be created or installed. Complete that approval first.
Create the Slack app from a manifest
Create the Slack application first, using the manifest that the Connection form provides.
- Open Slack app management.
- Select New App.
- Select From Manifest.
- In Agent Barn, use Copy Slack manifest on the Connection form.
- Paste the copied manifest into Slack.
- Choose the intended workspace.
- Select Next.
- Review the configuration and select Create.
The supplied manifest configures the Slack app, Socket Mode, bot events, and requested scopes. It does not create the app-level token; that is a separate manual step.
For an application that already exists, open Features → App Manifest instead and merge the copied manifest into the current one.
Create the app-level token
The app-level token opens the Socket Mode connection.
- Open Basic Information for the Slack app.
- Find App-Level Tokens.
- Create an app-level token with the
connections:writescope. - Copy the resulting
xapp-token. - Confirm that Socket Mode is enabled.
Slack's connections:write scope allows an app-level token to open the Socket Mode connection. Copy the token when it is generated; Slack does not show it again.
Install the app and copy the bot token
- Open OAuth & Permissions.
- Install the Slack app into the selected workspace.
- Copy the Bot User OAuth Token from OAuth Tokens for Your Workspace.
- Confirm that the value begins with
xoxb-. - Reinstall the app after changing its bot scopes.
- Before install
- No bot token is issued yet
- After install
- A Bot User OAuth Token beginning with
xoxb-is available
Private channels and conversations require the bot to be invited before it can access them. In the private channel, run /invite @bot-name.
Create the Slack Connection
With both tokens in hand, create the Connection on the Agent.
- Open the existing Agent.
- Open its Communication Connections section.
- Choose Slack.
- Enter a Connection display name.
- Paste the
xoxb-bot token into Bot token. - Paste the
xapp-app-level token into App-level token. - Configure the Connection policies.
- Create and enable the Connection.
Use a display name that identifies the workspace or purpose, such as Slack: Support workspace.
An active Slack bot token must not be reused by another Communication Connection where global credential uniqueness applies:
This Slack bot token is already in use by another Communication Connection.Configure the Connection settings
The Slack Platform Plugin supplies these settings on the Connection form.
| Setting | Behavior | Underlying setting |
|---|---|---|
| Default delivery target | One non-retired Connection per Agent may hold the default for scheduled work without a conversation origin. Disabling it retains the slot but prevents default delivery. | default_delivery_target |
| Channel access | open: respond in any channel where the bot is present; allowlist: respond only in the selected allowed channels | group_policy |
| Allowed channels | Slack channel IDs, used when Channel access is allowlist | channel_ids |
| Direct messages | off: ignore direct messages; open: accept from any Slack user; allowlist: accept only from selected users | dm_policy |
| Allowed DM senders | Slack user IDs, used when Direct messages is allowlist | dm_user_ids |
| Thread mention policy | every_message: every channel message, including every thread reply, must mention the bot; start_only: a mention starts the interaction, then unmentioned replies are accepted in threads this Agent and Connection already own | thread_mention_policy |
| Announce steps | Exposed in the schema but not used by the current delivery path to control progress; use Agent-level Hermes verbosity | verbose_mode |
Start narrow. A good first configuration is one allowed channel, direct messages off, and every_message thread mentions.
- Channel access
allowlistwith one test channel- Direct messages
off- Thread mention policy
every_message
Widen the policy after the first successful exchange. See Configure channel access for policy guidance.
Use workspace directory discovery
Slack supports credential-backed directory discovery for channels and active workspace users, so you can pick from the workspace instead of hunting for IDs.
- Draft Slack credentials can be used to load the workspace before the Connection is created.
- A saved Connection can browse its own workspace directory.
- Channel and user suggestions can populate the allowlists.
- Only Slack provider IDs are persisted.
- Manual ID entry remains available.
A directory lookup failure does not expose provider response text or stored credentials, and it does not block you from configuring an allowlist by hand.
A private channel appears only after the bot has been invited to it. Invite the bot in Slack, then load the directory again.
Send a separate Slack message
An Agent can send a separate Slack message when you request it during an active conversation. The message stays on the Communication Connection that received your request. You can name a channel or person in that workspace; it cannot switch to another Connection or workspace. Current channel and direct-message policies still apply. Use provider IDs when names are ambiguous. Group direct messages are not supported for initiated delivery.
A queue receipt means Agent Barn accepted the message for delivery. It does not prove that Slack received it. Use Communication diagnostics to inspect delivery failures and recovery.
Configure the default delivery target
The default gives scheduled work created outside a conversation a destination. It does not redirect jobs that already have a recorded conversation origin.
- Open the Agent's Communication Connections and edit the intended Slack Connection.
- Under Default delivery target, enable Send scheduled results through this Connection.
- Choose Channel or group or Person as the destination type, then select or enter the Default channel or recipient. For Slack, group direct messages are unsupported even though the shared field label includes “group.”
- Save the Connection and keep it enabled. The bot must have access to the destination, and the Connection's channel or direct-message policy must permit it.
Only one non-retired Connection per Agent may hold a default target. To move the default, clear it from the old Connection before setting the new one. Disabling a Connection does not release its default slot, and a disabled Connection cannot deliver through that default. Connection settings reconcile independently of the running Agent; deploying new runtime support still requires a compatible runtime rollout.
Where scheduled results go
Hermes jobs created from a conversation retain that Connection, channel, and thread. Jobs created at startup, outside a conversation, use the configured default. Changing the default does not move a job with a recorded origin.
A Hermes job can target a different thread or the channel root within its originating channel. It cannot change to another channel through this setting. An unsupported destination is refused rather than rerouted. To schedule work for a different channel, create the job from that channel.
OpenClaw completion capture is supported, but its pinned cron hook can report a delivery-channel label without a usable creating-conversation origin. Those unmappable completions are refused. Only completions with no recorded origin use the default; do not treat a default target as a workaround for an unknown origin.
Scheduled work sends its final response through Agent Barn. It does not call the interactive message tool. See the runtime guide for routing details, silence markers, and delivery recovery.
Verify the Connection
Confirm the Connection is enabled and shows no provider error, then run these tests from a controlled channel.
| Test | Expected result |
|---|---|
| Mention the Agent in an allowed channel | The Agent responds |
| Send an unmentioned message in an allowed channel | The Agent does not respond |
| Mention the Agent in a channel outside the allowlist | The Agent does not respond |
Send a direct message while Direct messages is off | The Agent does not respond |
Send a direct message as an allowed user while Direct messages is allowlist | The Agent responds |
Reply in a thread without a mention under every_message | The Agent does not respond |
Reply in an Agent-owned thread without a mention under start_only | The Agent responds |
Then confirm the exchange in Agent Barn:
- Open the Agent.
- Open Conversations.
- Select this Slack Connection.
- Confirm the inbound message and outbound response appear under it.
See Verify your Agent for the full layered verification.
Mention behavior
Mention requirements are a Connection policy, not a fixed Slack rule.
- New channel interactions require a direct bot mention.
- Direct messages do not require a mention, but remain governed by the direct-message policy.
- Thread replies follow the Connection's
thread_mention_policy. - Under
start_only, unmentioned replies are accepted only in a persisted thread already owned by that Agent and Connection.
@release-reviewer Review this deployment.The Slack Platform Plugin also ignores bot events, edit events, and duplicate app_mention deliveries, so the Agent does not answer itself or reply twice to the same mention.
Use every_message for busy shared channels, and start_only where a thread is a deliberate working session with the Agent.
Processing feedback
Slack users may see lightweight feedback while a request is handled:
| Signal | Meaning |
|---|---|
| 👀 | The inbound message was accepted |
| Processing status | The Runtime is working on the request |
| ✅ | The outbound response was delivered successfully |
| ❌ | A terminal Runtime or provider failure occurred |
This feedback is best-effort. It does not replace the durable delivery state shown in the Connection's diagnostics.
Change the Connection later
Slack settings and credentials can be changed at any time without touching the Agent.
- Connection updates increment the Connection revision.
- The Communications Gateway reconciles the Slack session independently.
- Updating the Connection does not rebuild or restart the Agent Runtime.
Use the Connection's diagnostics for provider health, reconnects, rejected messages, retries, and delivery failures. Check Runtime health separately when Slack accepts a message but the Agent produces no reply; that is a Runtime problem, not a provider problem.
Slack app manifest
The Connection form exposes the current manifest through Copy Slack manifest. Copy it from there rather than transcribing it, so the app always matches the installed Slack Platform Plugin.
The manifest configures:
- The Slack app display information and bot user
- Socket Mode
- Bot event subscriptions
- Requested bot scopes
It does not create the app-level token, and it does not install the app.
The manifest requests only bot scopes; no Slack user OAuth token is needed. After adding or changing bot scopes, reinstall the application so the bot token receives the new grants.
Credential management
Both Slack tokens belong to the Communication Connection.
| Credential | Where to manage it | Effect of rotation |
|---|---|---|
| App-level token | Slack app Basic Information, then the Connection credentials | Affects the Socket Mode session |
| Bot token | Slack app OAuth & Permissions, then the Connection credentials | Affects Slack API identity and operations |
Replacing a token requires Agent secret-management permission. Enter the new value on the Connection; the Gateway reconciles the session on the next revision.
Retiring a Slack Connection
Retiring the Connection removes it from active use and releases its provider credential identity where uniqueness applies, while preserving its Conversation history. It does not uninstall the application from Slack.
Afterward:
- Open the Slack application.
- Revoke tokens or uninstall the application when it is no longer needed.
- Remove the bot from any private channels.
- Review the application against your Slack administration policy.
Troubleshooting
Work through these checks first:
- The
xapp-token hasconnections:write - The
xoxb-token comes from the intended workspace - The app was reinstalled after scope changes
- Socket Mode is enabled
- The bot was invited to the relevant private channel
- The channel or sender passes the configured allowlist
- The message satisfies the configured mention policy
- The Connection is enabled and healthy
The app-level token is rejected
Check that it begins with xapp-, belongs to the intended Slack application, carries connections:write, and has not been revoked. Confirm Socket Mode is enabled, then generate a new app-level token if necessary.
The bot token is rejected
Check that it begins with xoxb-, that the application is installed in the intended workspace, and that it has not been revoked. Copy the Bot User OAuth Token, not a user token.
The bot token is already in use
Where global credential uniqueness applies, another Communication Connection already holds this token. Create a separate Slack application for the new Connection, or retire the Connection that holds the existing token.
Slack requires administrator approval
Submit the application through the workspace's normal administration process. The administrator should review the requested bot scopes, event subscriptions, Socket Mode, interactivity, and the intended channels and users.
A channel does not appear in the directory
Confirm that the bot token is valid, that the application has the channel-reading scopes, that it was reinstalled after those scopes were added, and that the channel is not archived.
For a private channel, run /invite @bot-name in Slack, then load the directory again. Manual channel ID entry remains available.
Scopes were added but behavior did not change
Reinstall the Slack application. Updating a manifest changes the application definition, but an already-issued bot token keeps its original grants until the app is installed again.
The Connection shows a provider error
Review the Connection's health and diagnostics. Check whether a token was revoked, the application was uninstalled, Socket Mode was disabled, or workspace authentication requirements changed.
Do not restart the Agent for a provider-session problem. Correct the Slack side or the Connection credentials, and the Gateway reconciles the session.
Slack accepts the message but no reply arrives
If the inbound message appears in Conversations, admission worked and the problem is downstream. Review Agent health and logs for the Runtime, then review the Connection's delivery diagnostics for the outbound reply.
The Agent responds in direct messages but not channels
Check the channel access policy, the allowed channel list, bot membership for private channels, whether the app was reinstalled after scope changes, and whether the message satisfies the configured thread mention policy.
Next steps
After the Slack Connection is working:
- Review the Connection lifecycle
- Configure channel access
- Verify your Agent
- Review Agent health and logs, separately from Connection health
- Compare platform compatibility before adding another Connection
- Set up Telegram
Current limitation: Announce steps
The Slack Connection schema exposes an Announce steps field, but the current delivery path does not use that Connection-level setting to control progress. Hermes progress is controlled by the Agent's verbosity setting. Changing the Slack field alone does not enable or suppress progress. OpenClaw does not support the current progress relay.