How-To Guide
Connect Hermes Agent to Discord: Bot Token, Intents, Gateway Test
Connect Hermes Agent to Discord with a bot token, Message Content Intent, channel allowlists, thread/forum checks, provider smoke tests, Web UI status, and one real reply test.
Quick answer
Create a Discord app and bot, invite it to one private test channel with bot plus applications.commands scopes, enable Message Content Intent only if Hermes must read normal channel text, put the token in the active Hermes gateway profile, restart the gateway, and prove the path with one real mention or slash command in the exact channel or thread. If the same Hermes profile cannot answer in the CLI, fix provider credits, API keys, or rate limits before changing Discord permissions. Use FlyHermes when you want Discord access without operating gateway uptime yourself.
This page is the focused implementation checklist for the searcher who wants to connect Hermes Agent to Discord today. It is intentionally narrower than the full Discord setup article: first make one safe channel reply, then expand to forum threads, support channels, cron alerts, or team workflows. Fresh GSC data shows `hermes agent discord`, `connect hermes to discord`, and `hermes discord bot setup` ranking around page one with low CTR, so this checklist now leads with the exact bot-token, intent, gateway, and verification steps people are looking for.
Managed cloud · API costs included · Skill library · Cancel anytime
Before you start:
- ☑Hermes Agent installed and able to answer one CLI test from the same profile that will run the gateway
- ☑A Discord account with permission to create an app, add a bot, and invite it to the target server
- ☑Access to the Discord Developer Portal and the active Hermes profile config/env path
- ☑A private test channel or staff-only thread where you can verify replies before opening public channels
- ☑If the bot must stay online for a team, a VPS/process manager/Docker setup or the managed FlyHermes path
Steps
- 1
Create the Discord application and bot user
Open the Discord Developer Portal, create a new application, add a bot user, and copy the bot token into your password manager. Do not paste the token into chat, tickets, or public config examples.
- 2
Choose the narrowest Discord permission model
For slash-command-first workflows, invite the bot with bot and applications.commands scopes and minimal channel permissions. Enable Message Content Intent only when Hermes must read ordinary channel messages instead of being mentioned or invoked by slash command.
- 3
Invite the bot to one private test channel
Generate the OAuth2 invite, add the bot to a private server or hidden staff channel, and confirm it can see the channel before you expose it to community traffic, support forums, or team-wide threads.
- 4
Configure the active Hermes gateway profile
Run hermes config path and hermes config env-path for the profile that will run the gateway, then add the Discord token and channel allowlist there. If you use profiles, do not put team Discord secrets into a personal/default profile by accident.
- 5
Smoke-test the model provider before Discord
Run hermes chat -q "reply with discord provider ok" using the same profile. If this fails with credits, API-key, rate-limit, or provider errors, Discord is not the broken part yet.
- 6
Restart the gateway and verify status
Restart the gateway after config changes, then check hermes gateway status and the Hermes Web UI/dashboard status surface. A running gateway only proves the process is alive; it does not prove Discord permissions or provider health.
- 7
Send one real mention or slash command
In the private test channel, send the exact command style you plan to use in production. Verify the bot receives the message, starts a Hermes turn, calls the model provider, and posts the reply in the same channel/thread.
- 8
Run the Discord channel/thread proof matrix
Repeat the test in each production surface separately: a normal channel, then a private thread, then a forum post or public support channel. A bot can work in one Discord surface and fail in another because role overrides, thread membership, and Message Content Intent behavior differ.
- 9
Test threads, forums, and public channels separately
Discord forum posts, threads, and public channels can have different permissions from the private test channel. Test the exact production surface before relying on it for support, cron alerts, or team workflows.
- 10
Decide whether to self-host or use FlyHermes
If the hard part is keeping Discord online, rotating provider keys, watching logs, and repairing VPS/Docker restarts, compare the managed FlyHermes path before adding more self-hosted infrastructure.
Pro Tips
- 💡Keep the first Discord test to one private channel, one bot, one Hermes profile, and one model provider. Remove variables before debugging.
- 💡Use a dedicated Hermes profile for Discord if the server has team-specific memory, skills, secrets, or channel prompts.
- 💡When a bot is online but silent, check Message Content Intent, mention policy, channel allowlists, thread permissions, and gateway restart state before regenerating the token.
- 💡When a bot starts a turn but fails mid-reply, inspect provider credits, auxiliary model routes, and rate limits. That is a model-stack problem, not a Discord OAuth problem.
- 💡Use the Hermes Web UI/dashboard as a status checkpoint for profile, provider, memory, cron, and gateway state, then verify success with a real Discord message.
- 💡For busy communities, prefer mention-only or slash-command behavior first; free-response behavior should be explicit and channel-scoped.
- 💡If Discord is tied to daily cron reports or support alerts, test one scheduled delivery into the actual channel/thread instead of only testing a manual chat reply.
- 💡Use FlyHermes when the desired outcome is a reliable Discord agent for a team and you do not want to maintain VPS, Docker, launchd/systemd, provider keys, and gateway logs.
- 💡Weekly buyer-demand note (2026-06-22): recent GSC/dashboard searches, Reddit Claude Code monitor/cost threads, YouTube dashboard walkthroughs, and Discord gateway/support clusters all point to the same decision — self-host if you want control, but use FlyHermes when dashboard visibility, Telegram/Discord uptime, provider credits, and VPS maintenance are the work you do not want to own.
- 💡Before declaring the workflow fixed, open the private Hermes dashboard, select the correct profile, check provider/model/gateway/cron state, and then verify the real channel or scheduled delivery path.
- 💡If the Discord bot is part of a Claude Code alternative workflow, decide whether you want self-hosted gateway maintenance or FlyHermes managed channel uptime before adding more projects to one bot.
- 💡Use the Hermes Web UI as the checkpoint for provider, profile, cron, and gateway state, then prove the integration with one real Discord reply in the exact target channel or topic.
Troubleshooting
❌ Bot is online but does not reply
✅ Check Message Content Intent, mention-only policy, channel allowlists, role permissions, thread/forum permissions, and whether the gateway restarted after the latest config change.
❌ Slash commands do not appear
✅ Confirm the OAuth invite included applications.commands, wait for Discord command propagation, and test in the same server/channel where the bot was invited.
❌ Hermes works in CLI but not Discord
✅ Inspect gateway logs, the Discord platform config, allowed channel IDs, and the active profile. The CLI and gateway may be using different profiles or env files.
❌ Discord receives the message but the agent errors
✅ Separate Discord delivery from model health. Check provider API keys, credit balance, rate limits, auxiliary routes, and context/window errors before changing Discord permissions.
❌ Bot works in a channel but not a thread or forum post
✅ Verify the bot role can view and send messages in that thread/forum, then test the exact message_thread/channel surface. Forum/thread permissions are not always inherited the way you expect.
❌ Docker or VPS setup sees the wrong config
✅ Check mounted volumes, profile paths, env files, and the terminal backend. Use the Docker Discord troubleshooting guide when the container has different files from the host.
❌ Discord needs to stay online for a team
✅ Use a hardened self-hosted process with restart monitoring, logs, backups, and dashboard checks, or use FlyHermes if uptime and provider management are the part you do not want to own.
❌ Dashboard says Discord is connected but no one gets a reply
✅ Treat Web UI status as a checkpoint, not final proof. Send one real message in the exact channel/thread, inspect gateway logs for the inbound event, and split provider failures from Discord permission failures before rotating tokens.
FAQ
What is the fastest way to connect Hermes Agent to Discord?
Create a Discord app and bot, invite it to one private test channel, configure the active Hermes gateway profile with the token and allowed channel, restart the gateway, and send one real mention or slash command.
Does Hermes need Discord administrator permissions?
Usually no. Start with the smallest role and channel permissions that allow the bot to read the test channel and send replies. Add broader permissions only when a workflow proves it needs them.
Do I need Message Content Intent for Hermes Discord?
Enable Message Content Intent only if Hermes must read normal channel messages. If the server uses slash commands or mention-only workflows, keep the permission model narrower.
Why is my Discord bot online but Hermes does not answer?
The bot process can be online while the Hermes provider route, profile, channel allowlist, or gateway session is broken. Check the CLI provider smoke test, gateway status, logs, and exact channel/thread permissions.
Can FlyHermes run the Discord agent for me?
Use FlyHermes when the goal is managed uptime and less VPS/Docker/provider maintenance. Self-host Hermes when you want full runtime control and are comfortable operating the gateway yourself.
Should I test Discord channels and threads separately?
Yes. Normal channels, private threads, public threads, and forum posts can have different role overrides and bot visibility. Prove the exact production surface before using Discord for support, cron alerts, or team workflows.
Related setup and cost guides
Discord integration overview
Use this when you want the product-level Discord gateway capabilities and thread/forum scope before setup.
Full Discord setup article
Long-form tutorial with deeper Developer Portal, permission, Docker, VPS, and team workflow context.
Gateway troubleshooting guide
Use this when Discord, Telegram, or another gateway is connected but not accepting turns or posting replies.
Model provider costs and rate limits
Use this when the Discord bot receives messages but the model route fails due to credits, API keys, or rate limits.
FlyHermes pricing comparison
Compare self-hosted Discord upkeep against the managed cloud path when uptime matters more than runtime control.