Connect Slack to an agent

Connect Slack when your team already lives there: the agent joins as a bot, answers when it is mentioned or messaged directly, and can post in the channels you invite it to.

Qoren connects Slack apps in socket mode. The agent opens the connection to Slack itself, so you do not need a public web address or a request URL.

This page is about chatting with one agent in Slack. To wake agents on Slack events and let them read threads and post through Qoren's own tools, with the key kept off the agent's machine, connect Slack as an integration instead: see connect Slack as an integration.

Before you start#

• A Hermes or OpenClaw agent that has finished setting up. Codex and OpenCode agents cannot use chat channels yet.
• Permission to create and install apps in your Slack workspace. On many workspaces that means a Slack admin.

Create the Slack app#

Qoren gives you a Slack app manifest, so Slack sets the app up in one step: every scope, event and setting the agent needs, with the app named after your agent. Slack's own references are app manifests, socket mode and token types.

1. Open the agent, click Settings, then Connections. Under Channels, pick Slack from Add a gateway….
2. Click Create the Slack app (1). Slack opens its create app page, prefilled with the manifest. Pick your workspace and choose Create.

12

3. In the new app, open Install App, install it to your workspace and approve it. Copy the Bot User OAuth Token, which starts with xoxb-.
4. Open Basic Information. Under App-Level Tokens, choose Generate Token and Scopes, name it, add the connections:write scope and generate it. Copy the token, which starts with xapp-.
5. Copy the member ID of each person who should be able to message the agent: in Slack, open their profile, click the ⋮ menu and choose Copy member ID. A member ID starts with U.

Already made the app by hand? Click Copy manifest (2), open the app's App Manifest page in Slack, replace everything with it and save. Reinstall the app when Slack asks, so the new scopes take effect.

Set the app up by hand instead#

These steps make the same app as the manifest.

1. Go to api.slack.com/apps, click Create New App, choose From scratch, name it and pick your workspace.
2. Open OAuth & Permissions. Under Bot Token Scopes, add app_mentions:read, channels:history, channels:read, chat:write, commands, files:read, files:write, groups:history, groups:read, im:history, im:read, im:write, mpim:history, mpim:read, reactions:write and users:read. users:read lets the agent see each person's name, so it knows who it is talking to instead of seeing only a Slack member ID. The mpim scopes cover group direct messages, files:read lets it read what you attach, and reactions:write lets it react to a message while it works on it and once it has replied (see chat reactions).
3. Open Socket Mode and turn it on. Slack asks you to create an App-Level Token: give it the connections:write scope and copy the value that starts with xapp-.
4. Open Event Subscriptions, turn it on, and under Subscribe to bot events add app_mention, message.channels, message.groups, message.im and message.mpim. Without message.mpim, group direct messages never reach the agent. Without message.channels and message.groups, it answers only in direct messages.
5. Open Interactivity & Shortcuts and turn on Interactivity, so the agent's buttons, such as approvals, work.
6. Open Slash Commands, choose Create New Command, and create /hermes with any short description. It runs the agent's commands, such as /hermes new to start a fresh conversation.
7. Open App Home. Under Show Tabs, turn on Messages Tab and tick Allow users to send Slash commands and messages from the messages tab. Without it, Slack blocks direct messages to the bot.
8. Install the app to your workspace (Install App, at the top of OAuth & Permissions) and approve it. Copy the Bot User OAuth Token, which starts with xoxb-.
9. Optional: the Signing Secret under Basic Information. Socket mode does not need it.
10. Copy the member IDs of the people who should be able to message the agent, as in step 5 of the manifest steps.

Connect the app in Qoren#

1. Back on the Slack form (open the agent's Settings, Connections, and pick Slack under Channels if it is not open), paste the xoxb- token into Bot token (xoxb-) (1).
2. Paste the xapp- token into App-level token (xapp-) (2).
3. Under Who can message the agent (3), choose who it answers. Specific people is the safe choice: paste the member IDs you copied, separated by commas. Everyone lets anyone who can reach the bot use the agent, guests and people in shared channels included. Nobody is the default, and the form flags it as not recommended: the agent ignores every message until you allow someone.
4. Optional: set Home channel (4) to where the agent should post scheduled results and messages it starts on its own. Use a channel ID, which is at the bottom of the channel's details (invite the bot to that channel too), or a member ID for that person's direct messages. Without one, the agent asks in Slack for /hermes sethome to pick a chat.
5. Leave Signing secret (5) blank unless you have one you want to keep with the agent.

12345

6. Click Save changes at the bottom of the page.

Each token field also has Use vault, to pick a token you saved in the Vault instead of pasting it. The form checks each value as you type: a bot token must start with xoxb-, an app-level token with xapp-, and a member ID with U or W, or you see "Not in the expected format." A channel ID or a display name is not a member ID.

Invite the bot and test it#

1. Wait for the panel to say Saved. Under Connections, Slack should turn to Connected (1), with the bot's name underneath.

1

2. In Slack, open each channel the agent should work in and run /invite @your-bot-name. A bot only sees channels it has been invited to.
3. Mention the bot in that channel, or send it a direct message. The reply comes from your agent.

Troubleshooting#

• Needs attention. The agent could not sign in to Slack; the reason is on the card. The usual causes are a token copied from the wrong place (the two tokens swapped, or a user token instead of the bot token), or an app-level token without the connections:write scope. Paste fresh tokens and click Save changes.
• Connected, but it never answers anyone. Check Who can message the agent. With Nobody, or a list of member IDs that leaves you out, the agent ignores the message. Choose Specific people and add your member ID, or Everyone, then click Save changes.
• Slack says "Sending messages to this app has been turned off". Turn on the Messages Tab under App Home, as in step 5 above.
• Connected, but silent in a channel. Invite the bot to that channel with /invite, and check the app has the scopes and the message.channels event (message.groups for a private channel) from the steps above. If you added scopes or events after installing, Slack asks you to reinstall the app before they take effect.
• Silent in group direct messages. The app is missing the message.mpim event or the mpim:history and mpim:read scopes, which apps set up from an earlier version of this page do not have. Click Copy manifest on the Slack form, paste it over the app's App Manifest page, save, and reinstall the app.
• Answers, but never reacts to messages. The app is missing the reactions:write bot scope, which apps set up before Qoren added chat reactions do not have. Paste Qoren's manifest over the app's App Manifest page, or add the scope under OAuth & Permissions, then reinstall the app to your workspace: Slack only applies a new scope after a reinstall.
• Answers direct messages but not channel posts. In a channel, the agent answers when someone mentions it. Mention it by name.
• Posts every tool call it runs. Set Slack to Final reply only or Progress updates under Chat replies in the agent's Settings, Connections. See choose what the chat sees.

For anything else, see what to do when an agent is not responding.