Connect Hermes Agent to Your Slack Workspace

Turn your Slack workspace into an AI-powered command center with an AI Slack agent. Your team can ask questions, trigger automations, and get research done without leaving the tools they already use.

June 16, 2026

Quick answer

Hermes Slack setup starts with one private test channel, a Slack app with only the scopes the workflow needs, the token stored in the active Hermes gateway profile, and one verified reply before you add production channels, scheduled reports, or workflow automation.

Before you start

Hermes Agent installed and running on a publicly accessible server
Slack workspace admin permissions
A public URL or ngrok tunnel for local development

Step 1: Create a Slack app for Hermes

Go to the Slack API dashboard and create a new app. Choose From scratch, name it "Hermes", and select your target workspace. Install it into one private test channel before exposing it to production channels.

Step 2: Add the minimum Slack scopes

Grant only the bot token scopes your workflow actually needs. Navigate to OAuth & Permissions and add:

chat:write — Send messages as Hermes
channels:history — Read channel messages
im:history — Read direct messages
app_mentions:read — Respond when mentioned

Avoid broad workspace access until the first workflow is verified. If you add scopes after the initial install, you'll need to reinstall the app.

Step 3: Store the token in Hermes

After installing the app to your workspace, copy the Bot User OAuth Token. Store it in the active Hermes gateway profile or environment configuration — never in prompts, screenshots, screenshots, or committed repository files.

If you're using the Hermes config.yaml, add the token under the Slack gateway section and set the profile as active.

Step 4: Restart the Hermes gateway

Restart the Hermes gateway process so it picks up the new token and profile. Verify the process is using the correct profile by checking the startup logs. If you're running Hermes with Docker, restart the container.

Step 5: Verify one private channel reply

Send a harmless test message in your private test channel and mention Hermes. Check the gateway logs to confirm the message was received and a response was sent. Once verified, you can add production channels, scheduled reports, or workflow automation.

/invite @hermes
@hermes hello, can you hear me?

Pro tips

Use Socket Mode for local development

Socket Mode in Slack's developer settings doesn't require a public URL and is much easier to set up for testing. Enable it in your app's Settings page.

Restrict Hermes to specific channels

Use slack: allowedChannelIds in your Hermes configuration to prevent the agent from responding in every channel.

Configure response batching

Slack's rate limits are strict. If Hermes sends many messages quickly, configure response batching in the gateway settings to avoid hitting limits.

Troubleshooting

Slack app shows "not responding" when mentioned

Slack requires a response within 3 seconds. Enable async response mode in config.yaml so Hermes acknowledges the message immediately and follows up with the full response.

OAuth scopes error when installing

Make sure you've added all required bot token scopes: chat:write, channels:history, im:history, and app_mentions:read. Missing scopes require reinstalling the app.

Hermes not receiving messages in private channels

Hermes must be explicitly invited to private channels with /invite @hermes. Bot scopes don't grant access to private channels by default.

FAQ

How do I set up Hermes Slack?

Create a Slack app, install it into a private test channel, store the token in the active Hermes gateway profile, restart the gateway, then verify one reply before adding production channels.

Can Hermes post scheduled reports to Slack?

Yes. Use Hermes cron with an explicit delivery target after the Slack gateway is verified. Start with a harmless test report before sending production alerts.

Need help with your AI agent setup?

We build custom AI agents, workflows, and automation for teams on Slack. Book a call and tell us what you need.