Platforms

On this page

Overview
Slack connection model
Before you begin
Choose a setup path
1. Open the hire wizard
2. Choose Slack
3. Prepare the Slack app
4. Generate the app-level token
5. Install the Slack app
6. Connect Agent Barn
7. Configure Slack access
8. Verify the Agent
Slack app manifest
Token management
Slack setup API
Troubleshooting
Next steps

Connect an Agent to Slack by creating a Slack application, enabling Socket Mode, and providing Agent Barn with an app-level token and a bot token.

Both Hermes and OpenClaw support Slack. Each Slack Agent uses its own Slack application and bot identity, so its access policies, credentials, messages, and lifecycle remain independent.

Overview

Agent Barn connects to Slack through Socket Mode. The Agent’s Runtime opens an outbound WebSocket connection to Slack, so the Agent Barn deployment does not need a public Slack event endpoint.

Runtime	Slack support	Slack-specific options
Hermes	Supported	Channel and DM policies, home channel, verbosity, fresh-mention gating
OpenClaw	Supported	Channel and DM policies, fresh-mention gating

A Slack Agent requires:

A Slack application
Socket Mode enabled
The required bot scopes and event subscriptions
An app-level token beginning with xapp-
A bot token beginning with xoxb-
The application installed in the intended Slack workspace
At least one usable Slack location when channel access is restricted

Slack Agents are created in the Stopped state. The hire wizard starts the Agent after you configure or skip its Slack access step.

Slack connection model

Events reach the Agent over an outbound connection, and the Agent replies through the Slack Web API.

Slack events
Socket Mode
Agent Runtime
Slack Web API

The Slack Web API then delivers messages, files, reactions, and other allowed operations. Slack’s Socket Mode delivers events through a WebSocket connection instead of sending them to a public Request URL.

Token types

Credential	Typical prefix	Purpose	Stored for
Configuration access token	Slack-issued configuration token	Creates and updates Slack applications through the App Manifest API	One Agent Barn user
Configuration refresh token	`xoxe-`	Renews the short-lived configuration access token	One Agent Barn user
App-level token	`xapp-`	Opens the Agent’s Socket Mode WebSocket	One Slack Agent
Bot token	`xoxb-`	Authenticates Slack Web API calls as the bot	One Slack Agent

Slack documents these as separate Slack token types. Do not interchange them.

Configuration tokens are optional. They are used only when you want Agent Barn to create Slack applications automatically. The app-level and bot tokens are required for every Slack Agent.

Before you begin

You need:

An Agent Barn Organization
Permission to create an Agent
Permission to create or manage an application in the target Slack workspace
Permission to install the application in that Slack workspace
A published Agent Barn Template
A supported Runtime: Hermes or OpenClaw
A supported model allowed by the Organization
Any credentials required by the selected Template and Skills
A Slack channel for controlled verification
A plan for who may direct-message the Agent

Your Slack workspace may require administrator approval before an application can be created or installed. Complete that approval before beginning the Agent Barn hire flow.

Each active Slack Agent must use a distinct bot token. Plan to create one Slack application per Agent.

Choose a setup path

Agent Barn supports two Slack setup paths.

Create a new Slack app

Recommended

Use this path when you are setting up a new bot and can generate Slack configuration tokens.

Agent Barn creates the application from its Slack manifest, then returns the Slack links you need for the app-level token and installation.

Connect an existing Slack app

Use this path when you already own a suitable Slack application, or cannot use configuration tokens.

You apply the manifest yourself in Slack, and Agent Barn validates the app-level and bot tokens you provide.

Both paths ultimately require you to:

Generate an app-level token.
Install or reinstall the application.
Copy the bot token.
Enter both tokens into Agent Barn.

Agent Barn cannot generate the app-level token or approve the Slack workspace installation on your behalf.

Open the hire wizard

Sign in to Agent Barn.
Select the Organization that will own the Agent.
Select Hire agent in the top navigation.

You can also select Hire a teammate from an empty or existing Agent list.

The hire wizard begins with the Agent’s Template. Complete the initial steps:

Choose a Template.
Choose an exact Template version where the selector is available.
Select the required Skills.
Continue to the Runtime selection.

The Agent’s platform is immutable after creation. To connect an existing non-Slack Agent to Slack, create a new Slack Agent instead of attempting to change its platform.

Choose Slack

Choose a Runtime

Select:

Hermes for the recommended lightweight, plugin-based Runtime.
OpenClaw when its Runtime behavior better fits the Agent.

Both support Slack through Socket Mode. See Choose an Agent runtime for the complete comparison.

Choose the platform

Under Choose your platform, select Slack.

Agent Barn describes this option as:

Slack
Connect via Socket Mode with a bot and app-level token.
Recommended.

Choose the Slack app path

Under Set up your Slack app, choose:

Set up a new Slack bot
I already have a Slack app

Continue with the corresponding instructions below.

Prepare the Slack app

Option A: Create a new Slack app automatically

Agent Barn uses Slack configuration tokens and the App Manifest API to create the application.

Slack configuration tokens are tied to one Slack user and workspace rather than one individual application. Slack issues an access token and refresh token together. The access token is short-lived; Agent Barn stores the pair encrypted and uses the refresh token to obtain a fresh pair when needed. See Slack’s App Manifest configuration-token documentation.

If your Agent Barn account does not have configuration tokens saved:

Open Your Slack apps.
Scroll below the application list to Your App Configuration Tokens.
Select Generate Token.
Select the Slack workspace where the Agent will operate.
Copy the configuration access token.
Copy the configuration refresh token.
Return to Agent Barn.
Paste both tokens under Set up Slack app creation.
Select Save.

The relationship is:

Configuration access token and refresh token Generated together in Slack for one Slack user and workspace
Encrypted Agent Barn account setting Validated before saving, then shown only as a masked preview
Slack App Manifest API Agent Barn refreshes the short-lived access token when it calls Slack
New Slack application Created from the Agent Barn Slack manifest

Agent Barn validates the access token before saving it. The saved value is displayed later only as a masked preview.

You can update or remove these tokens under Account settings → Slack configuration tokens.

Removing the configuration tokens does not disconnect existing Slack Agents. It prevents that Agent Barn user from automatically creating or updating Slack apps until another valid pair is saved.

Define the new bot

Under Build your Slack bot, enter a Bot display name, a Description, and a Background color.

The display name is shown in Slack. Use a name that clearly identifies the Agent’s purpose.

Example bot definition

Display name: Release Reviewer
Description: Reviews release changes and reports operational risks.
Background color: #4A154B

Agent Barn creates the Slack application using the manifest in Slack app manifest.

Option B: Connect an existing Slack app

Open Your Slack apps, select the application, and open Features → App Manifest.

Paste the manifest from Slack app manifest, or merge its settings into the existing manifest. Review especially:

Bot OAuth scopes
Bot event subscriptions
Socket Mode
Interactivity
App Home Messages tab
Bot user
Application display information

Select Save Changes. If Slack reports a manifest validation error, correct it before continuing.

Generate the app-level token

The app-level token opens the Socket Mode connection.

Open the Slack application.
Select Settings → Basic Information.
Scroll to App-Level Tokens.
Select Generate Token and Scopes.
Enter a descriptive token name, such as agent-barn-socket.
Add the connections:write scope.
Select Generate.
Copy the generated token immediately.

App-level token

Prefix: xapp-
Required scope: connections:write
Belongs to: One Slack Agent

Slack’s connections:write scope allows an app-level token to call apps.connections.open and establish the Socket Mode connection.

Agent Barn validates this token by attempting to open a Slack app connection. A missing connections:write scope is rejected.

Install the Slack app

After configuring the application:

Open Settings → Install App.
Select Install to Workspace.
Review the requested permissions.
Select Allow.
Return to the application’s install page.
Copy the Bot User OAuth Token.

Bot token availability

Before install: No bot token is issued yet
After install: A Bot User OAuth Token beginning with xoxb- is available

Slack’s bot-token documentation describes bot tokens as the identity used by an installed application’s bot user.

If the application was already installed and you changed its scopes or event subscriptions:

Select Reinstall to Workspace.
Review the updated permissions.
Approve the reinstallation.
Copy the current bot token.

Do not use a user token beginning with xoxp-, a configuration token, a signing secret, or an incoming webhook URL. Agent Barn requires the Bot User OAuth Token.

Connect Agent Barn

Return to the Connect Slack step in Agent Barn and enter both tokens.

Connect Slack

App-level token: xapp-••••••••
Bot token: xoxb-••••••••

Agent Barn checks the prefix before continuing:

The app-level token must begin with xapp-
The bot token must begin with xoxb-

When the Agent is created, the API performs stronger validation:

The bot token is checked through Slack auth.test.
The app-level token is checked through Slack apps.connections.open.
The bot token is checked for reuse by another active Slack Agent.

If the same bot token is already assigned to an active Agent, Agent Barn rejects it:

This Slack bot token is already in use.
Each agent must use a distinct Slack app.

Continue through the remaining hire steps:

Enter the Agent name.
Choose its model.
Choose Hermes command approval if applicable.
Choose the initial channel policy.
Choose the initial direct-message policy.
Choose Hermes Slack verbosity if applicable.
Assign optional Skills and provide required integration credentials.
Select Hire [Agent name].

Slack Agents are persisted as Stopped before the final Slack access step.

The app-level and bot tokens are encrypted at rest. Read operations do not return their plaintext values.

Configure Slack access

After the Agent is created, the hire wizard opens Set up Slack access. Configure where the Agent may operate before starting it.

Channel access

Policy	Behavior
Allowlist	Respond only in selected Slack channels
Open	Respond in any eligible Slack channel available to the bot

Allowlist is the recommended production setting. When Allowlist is selected:

Search for a Slack channel.
Select the channel.
Add any additional approved channels.
Review the order if the Agent uses Hermes.

Example allowlist configuration

Channel access: Allowlist
First channel: #agent-alerts — home
Second channel: #release-testing
Direct messages: Off

Agent Barn attempts to join selected public channels automatically when the configuration is applied or the Agent starts.

Private channels

A private channel appears in Agent Barn only after the Slack bot has joined it. In the private Slack channel, run /invite @bot-name, then return to Agent Barn and search again.

Direct messages

Policy	Behavior
Off	Ignore Slack direct messages
Allowlist	Accept direct messages only from selected users
Open	Accept direct messages from anyone who can reach the bot

For an allowlist, search for and add each approved Slack user. Direct messages do not require a mention, because they are already addressed to the Agent.

Hermes home channel

For Hermes, the first selected Slack channel acts as the home channel for scheduled or proactive delivery. Use set home to move another selected channel into the first position.

A Hermes Agent without a selected channel has no Slack destination for scheduled or proactive updates.

Hermes verbosity

Hermes Slack Agents also provide Verbose — announces each step and Concise — final answers only. This changes response presentation, not Slack access.

Save and start

Select Save & Start. Agent Barn:

Saves the channel and DM policies.
Attempts to join selected public channels.
Starts the Agent.
Generates Runtime-specific Slack configuration.
Opens the Socket Mode connection.
Begins reporting health.

Selecting Skip for now starts the Agent with its current policy. If the policy is Allowlist with no selected channels and direct messages are Off, users may have no eligible location from which to interact with it.

Closing the final access panel without Save or Skip can leave the Slack Agent Stopped.

Mention behavior

In shared Slack channels, the Agent responds only when explicitly mentioned. A fresh mention is required on every message.

@release-reviewer Review this deployment.

An earlier mention does not authorize later unmentioned messages in the same thread.

Verify the Agent

Wait for the Agent condition to move from Initializing to Working, then run these tests.

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
Send an unmentioned follow-up in the same thread	The Agent does not respond
Mention the Agent again in the thread	The Agent responds
Mention the Agent outside its allowlist	The Agent does not respond
Send a direct message while DMs are Off	The Agent does not respond
Send a direct message as an allowed user while DMs use Allowlist	The Agent responds

After the first successful interaction:

Open the Agent in Agent Barn.
Confirm that its condition is Working.
Open Conversations.
Confirm that the inbound Slack message and outbound response appear.
Open Logs.
Confirm that the Runtime connected to Slack without repeated token or connection errors.

If the Agent remains Initializing or becomes Disconnected, continue with Troubleshooting.

Slack app manifest

This is the Slack application configuration expected by Agent Barn’s current Slack integration. It enables Socket Mode, the bot user, interactivity, the required bot scopes, and the bot event subscriptions. For an existing application, update the display information before applying it.

Use the Copy action to copy the complete manifest.

{
  "display_information": {
    "name": "Your Agent Name",
    "description": "Your Agent description.",
    "background_color": "#4A154B"
  },
  "features": {
    "app_home": {
      "home_tab_enabled": false,
      "messages_tab_enabled": true,
      "messages_tab_read_only_enabled": false
    },
    "bot_user": {
      "display_name": "Your Agent Name",
      "always_online": true
    }
  },
  "oauth_config": {
    "scopes": {
      "bot": [
        "app_mentions:read",
        "bookmarks:read",
        "canvases:read",
        "canvases:write",
        "channels:history",
        "channels:join",
        "channels:read",
        "chat:write",
        "chat:write.customize",
        "chat:write.public",
        "emoji:read",
        "files:read",
        "files:write",
        "groups:history",
        "groups:read",
        "im:history",
        "im:read",
        "im:write",
        "mpim:history",
        "mpim:read",
        "mpim:write",
        "pins:read",
        "pins:write",
        "reactions:read",
        "reactions:write",
        "search:read.users",
        "users:read",
        "users:read.email"
      ]
    },
    "pkce_enabled": false
  },
  "settings": {
    "event_subscriptions": {
      "bot_events": [
        "app_mention",
        "channel_rename",
        "member_joined_channel",
        "member_left_channel",
        "message.channels",
        "message.groups",
        "message.im",
        "message.mpim",
        "pin_added",
        "pin_removed",
        "reaction_added",
        "reaction_removed"
      ]
    },
    "interactivity": {
      "is_enabled": true
    },
    "org_deploy_enabled": false,
    "socket_mode_enabled": true,
    "token_rotation_enabled": false,
    "is_mcp_enabled": false
  }
}

The manifest enables only bot scopes. Agent Barn does not require a Slack user OAuth token.

After adding or changing bot scopes, reinstall the application so the bot token receives the new grants.

Token management

The Slack credentials have separate ownership and lifecycles.

Credential	Where to manage it	Effect of removal or rotation
Configuration tokens	Agent Barn Account settings, and the Slack app-management page	Affects automatic application creation and best-effort application updates
App-level token	Slack application Basic Information, and Agent Configuration	Affects Socket Mode connectivity
Bot token	Slack application Install App or OAuth settings, and Agent Configuration	Affects Slack API identity and operations

Configuration tokens

Agent Barn stores configuration access and refresh tokens per user, not per Organization or Agent. Stored configuration tokens are:

Encrypted at rest
Validated before saving
Displayed only as a masked preview
Reused for future Slack app creation by that user
Rotated through Slack’s refresh-token API when used

Slack states that configuration access tokens expire after 12 hours and provides the refresh token for rotation. See Configuring apps with app manifests.

Deleting these tokens does not revoke an existing Agent’s app-level or bot token.

App-level and bot tokens

App-level and bot tokens belong to the individual Slack Agent. To replace one:

Generate or obtain the new token in Slack.
Open the Agent.
Select Configuration → Keys & integrations.
Select Edit.
Enter the new token.
Apply the change.

For a Running Agent, credential changes use Apply & Restart. For a Stopped Agent or an Agent in Error, they use Apply.

Credential changes require agent.secret.manage. Restarting a Running Agent also requires lifecycle authority.

Agent Barn validates any newly submitted Slack token before saving it.

Removing a Slack Agent

Retiring an Agent releases its bot token for reuse inside Agent Barn, but it does not uninstall the application from Slack.

After retiring the Agent:

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.

Slack setup API

The relevant endpoints have different credential scopes.

Method and endpoint	Purpose
`GET /auth/me/slack-config-token`	Return whether the current user has Slack configuration tokens, and show a masked preview
`PUT /auth/me/slack-config-token`	Validate and save the current user’s configuration access and refresh tokens
`DELETE /auth/me/slack-config-token`	Remove the current user’s stored configuration tokens
`POST /organizations/{organization_id}/slack/apps`	Create a Slack application from the Agent Barn manifest
`POST /organizations/{organization_id}/agents`	Create the Slack Agent with its bot and app-level tokens
`GET /agents/{agent_id}/slack/channels`	List channels available to the Slack bot
`GET /agents/{agent_id}/slack/users`	List active Slack users for DM access selection
`PUT /agents/{agent_id}`	Update Slack credentials or access policy while the Agent is not Running

 Configuration tokens belong to the authenticated Agent Barn user, and follow that user’s own lifecycle. Bot and app-level tokens belong to the Agent, and are replaced through Agent Configuration.
 Create a Slack application
 The application-creation request accepts:
   Create Slack application  
 {
  "name": "Release Reviewer",
  "description": "Reviews release changes and reports operational risks.",
  "background_color": "#4A154B"
}
 
  Agent Barn returns the Slack application ID and direct Slack administration links for installation and app-level-token creation.
 Create a Slack Agent
 A Slack Agent creation request includes fields such as:
   Create Slack Agent  
 {
  "name": "Release Reviewer",
  "platform": "slack",
  "agent_type": "hermes",
  "template_key": "tpl-000000000000",
  "template_version": 1,
  "model": "litellm/openrouter/example-model",
  "slack_app_token": "REDACTED",
  "slack_bot_token": "REDACTED",
  "slack_group_policy": "allowlist",
  "slack_dm_policy": "off",
  "slack_verbose_mode": true,
  "skill_ids": []
}
 
  Use real published Template and model identifiers. Never place real token values in documentation, shell history, or source control.
 The API creates Slack Agents in the Stopped state. Configure their channels, and then start them explicitly.

  Troubleshooting
  Agent Barn rejects the configuration token
 Confirm that you entered a Slack configuration access token, not:
  An xapp- app-level token
 An xoxb- bot token
 An xoxp- user token
 
 Generate a new token pair under Your App Configuration Tokens on the Slack application-management page. Paste both the access token and its corresponding refresh token.
 
  Slack app creation reports an expired token
 Update the configuration access and refresh tokens in Agent Barn Account settings.
 If the refresh token was already rotated elsewhere, generate a new pair in Slack and replace both values.
 
  App-level token is rejected
 Check that:
  It begins with xapp-
 It belongs to the intended Slack application
 It has the connections:write scope
 It has not been revoked
 Socket Mode is enabled
 
 Generate a new app-level token if necessary.
 
  Bot token is rejected
 Check that:
  It begins with xoxb-
 The application is installed in the intended Slack workspace
 It has not been revoked
 The installing account is active
 Any required enterprise authentication is complete
 
 Copy the Bot User OAuth Token, not a user token.
 
  Bot token is already in use
 Each active Slack Agent requires a distinct Slack application and bot token. Create another Slack application, install it, and use its tokens for the new Agent.
 A retired Agent releases its token for reuse inside Agent Barn, but reusing bot identities between Agents can make Slack history and operational ownership confusing.
 
  Slack requires administrator approval
 Submit the application for approval through the Slack workspace’s normal administration process. The administrator should review:
  The full bot-scope list
 The event subscriptions
 Socket Mode
 Interactivity
 The intended channels and users
 The Agent’s purpose and data-handling policy
 
 Continue after the application can be installed.
 
  A channel does not appear in Agent Barn
 Confirm that:
  The bot token is valid
 The application has channels:read and groups:read
 The application was reinstalled after those scopes were added
 The channel is not archived
 A private channel has invited the bot
 
 For a private channel, run /invite @bot-name, then return to Agent Barn and search again.
 
  The bot cannot join a public channel
 Confirm that the installed bot token includes channels:join.
 Agent Barn’s join attempt is best effort. Invite the bot manually if the Slack workspace’s policies prevent automatic joining.
 
  The Agent responds in direct messages but not channels
 Check:
  The channel policy
 The selected channel allowlist
 Bot membership for private channels
 Whether the application was reinstalled after scope changes
 Whether the message explicitly mentions the Agent
 
 A Slack channel message requires a fresh mention.
 
  The Agent responds to the first thread message but not later replies
 Mention the Agent again in each reply.
   Thread reply  
 @release-reviewer Please check the follow-up change.
 
  Slack thread participation does not remove mention gating.
 
  The Agent remains Initializing
 Open Logs and look for:
  Invalid bot token
 Invalid app-level token
 Missing connections:write
 Socket Mode connection failure
 No channels configured
 Platform connection timeout
 
 Correct the credentials or application configuration, then Pause and Start the Agent.
 
  The Agent shows Disconnected
 The Slack connection may have failed after previously working. Check whether:
  An app-level or bot token was revoked
 Slack is reachable from the Agent Runtime
 Slack workspace authentication requirements changed
 The application was uninstalled
 Socket Mode remains enabled
 
 Review Agent health and logs.
 
  Scopes were added but behavior did not change
 Reinstall the Slack application.
 Changing a manifest updates the application definition, but an already-issued bot token does not automatically receive newly requested scopes.
 
  Renaming the Agent did not rename the Slack app
 Agent Barn attempts to rename an automatically managed Slack application when the Agent name changes, but the Slack update is best effort and requires usable configuration tokens for the current user.
 Rename the application manually in Slack if the automatic update cannot be completed.
 
 
  Next steps
 After the Slack Agent is working:
  Configure channel access
 Verify your Agent
 Review Agent health and logs
 Configure an Agent
 Set up Telegram