Discord Connection Guide

Quick Setup Flow

1. Create a bot application — go to Discord Developer Portal, create a new application (or use an existing one).
2. Generate a bot token — under Bot → Reset Token, copy the token.
3. Enable intents — in Bot settings:

• Message Content Intent (required for reading messages)
• Presence Intent (optional, for online status)

4. Generate OAuth2 invite URL — use OAuth2 URL Generator and paste into browser.
5. Invite to server — pick your guild from the dropdown.
6. Configure in Hermes — hermes gateway setup or manually configure via config.yaml.

Bot Permissions (Minimal)

For Hermes, you only need:

• Send Messages (0x2)
• Read Message History (0x100000)
• View Channel (0x400)
• Use External Emojis (0x1000000)

Nice to have: Embed Links, Add Reactions, Send Text-to-Speech, Manage Messages.

Shortcut: set permissions to 3558496 ("Moderator" preset).

OAuth2 Scopes

• bot — essential, lets you invite it to servers
• applications.commands — enables slash commands (useful but not strictly required)

Guild Install vs User Install

Guild install is the one that puts the bot into your servers. User install is for apps, not bots. When generating the OAuth2 link, make sure guild is in the scope (usually default).

Gotchas

• Private applications cannot have a default authorization link. Generate manually via OAuth2 URL Generator.
• Message Content Intent must be enabled — without it, the bot reads messages as empty strings and appears silent.
• Presence Intent — optional but useful for seeing when the bot is online/offline.
• Prefer the exact invite URL generated by Discord Developer Portal over improvising OAuth / Code Grant explanations from memory. If the generated link fails, inspect the portal settings rather than guessing about URL semantics.
• Always verify prior state before assuming. Don't assume a server exists, permissions are set, or the bot is already invited — ask first.
• Discord connected is not the same as Discord usable. A successful gateway login only proves the token works. Separately verify that the bot is invited to a guild, can see a text channel, slash commands appear there, and Hermes discovered the channel.
• After adding the bot to a new server, restart the Hermes gateway so channel_directory.json rebuilds against current guild visibility.
• If send_message(action='list') still shows no Discord targets, inspect ~/.hermes/channel_directory.json. If it contains "discord": [] while the bot is present in the server, treat it as a guild/channel discovery or visibility problem, not an auth failure.
• Being connected is not the same as being installed. Connected as <botname>#xxxx only proves the token works. It does NOT mean the bot has been added to the user's server.
• If the bot is in the server but silent, check channel-level permissions before deeper debugging. Minimum useful perms: View Channel, Send Messages, Read Message History, Use Application Commands; Embed Links preferred.
• Always verify prior state before assuming. Don't assume a server exists, permissions are set, or the bot is already invited — ask first.

Invite/First-Use Verification

Invite/First-Use Verification

1. Confirm Hermes shows Discord as configured and the gateway logs show Connected as ....
2. Confirm the user has actually authorized the bot into a server — token connectivity alone is insufficient. Bot API GET /users/@me/guilds should return at least one guild after install.
3. After authorization, restart the Hermes gateway once so it re-discovers guilds/channels.
4. In Discord, confirm the bot appears in the server member list.
5. In a normal text channel, verify channel permissions: View Channel, Send Messages, Read Message History, Use Application Commands.
6. Verify Hermes channel discovery: send_message(action='list') or ~/.hermes/channel_directory.json should show a Discord channel.
7. Test outbound text first with send_message to the discovered channel.
8. Then test a real user mention, e.g. @<botname> test, especially when require_mention: true is enabled in Hermes config.
9. If the bot only reacts with ✅ and no response appears, check authorization (DISCORD_ALLOWED_USERS) before deeper Discord debugging.
10. If Hermes still does not expose Discord send targets, treat that as a discovery/visibility problem, not proof that Discord auth failed.

• Always verify prior state before assuming. Don't assume a server exists, permissions are set, or the bot is already invited — ask first.

Common Failure Pattern: integration requires code grant

When the user reports Discord showing integration requires code grant during install:

1. Stop changing URL encoding by hand. Do not bounce between +, %20, or hand-edited scopes unless Discord's generator itself produced the link.
2. Ask whether the bot has already been added. If yes, stop troubleshooting the invite link and switch to channel/mention verification.
3. Prefer the exact link generated by Discord Developer Portal over a manually reconstructed one.
4. Verify the setting directly if you have the bot token: GET /api/v10/oauth2/applications/@me with bot auth returns bot_require_code_grant. If true, the owner must disable Bot → Authorization Flow → Requires OAuth2 Code Grant in the Developer Portal and save. Bot tokens cannot patch this endpoint (Bots cannot use this endpoint).
5. After disabling Code Grant, re-open the invite URL and complete the guild install. If Discord presents hCaptcha, stop and have the user solve it; then continue automation.
6. Once the bot is added, verify Hermes-side behavior with a first @mention because require_mention: true and user authorization are common follow-on blockers.

Common Failure Pattern: Only ✅ reaction, no text response

A ✅ reaction can mean Hermes received the Discord message but the gateway later dropped it before agent execution. Check gateway logs for Unauthorized user: <id> (<name>) on discord.

Fix path:

1. Get the Discord sender ID from logs or recent channel messages.
2. Add the user to DISCORD_ALLOWED_USERS in the active Hermes env/config. If using .env at gateway startup, ensure the value is present there too.
3. Restart the gateway.
4. Test with a real mention (@<botname> test) and verify logs show no Unauthorized user warning.

This is separate from channel permissions: outbound send_message can work while inbound user messages are still denied by Hermes authorization.

7. If Discord presents hCaptcha at final Authorize, stop and ask the user to complete it. Do not attempt CAPTCHA solving. Continue verification afterward.
8. Once the bot is added, verify Hermes-side behavior with a first @mention because require_mention: true is a common default.
9. When the user asks the agent to “handle all of it,” use a safe login handoff: open the Developer Portal, let the user authenticate via QR/passkey/password themselves, then continue. Never type their password or bypass 2FA.
10. Once the bot is added, verify Hermes-side behavior with a first @mention because require_mention: true is a common default.

Profile-specific Discord gateways

When a Hermes profile is created for a specialized Discord bot persona (for example support-bot, spanish-tutor, or another training coach):

1. Prefer a dedicated Discord bot token per long-running profile. Do not leave multiple active gateways sharing the same Discord bot token; it can cause routing, voice joins, slash-command discovery, and session ownership weirdness.
2. Keep the profile's Discord toolset minimal for the job. For training profiles, a good baseline is file, skills, memory, session_search, clarify, and optional tts.
3. Disable unrelated surfaces in that profile (telegram, api_server, etc.) unless explicitly needed, to avoid accidental extra endpoints or port conflicts.
4. Verify profile-specific Discord readiness with:

<profile> tools list --platform discord
<profile> gateway status --full

5. Start foreground first for testing (<profile> gateway run), then install/start the profile gateway only after the bot token and guild/channel permissions are clean.

Hermes Configuration

CRITICAL: Token must be in DISCORD_BOT_TOKEN env var (in .env), not just config.yaml.

The Discord adapter reads the token from DISCORD_BOT_TOKEN environment variable. Setting it only in config.yaml's discord.token is NOT sufficient — the plugin won't pick it up.

# Set the token (writes to .env)
hermes config set DISCORD_BOT_TOKEN YOUR_TOKEN_HERE

# Verify it's there
python3 -c "import os; print('DISCORD_BOT_TOKEN:', 'configured' if os.environ.get('DISCORD_BOT_TOKEN') else 'not set')"

# Restart gateway — the plugin may be stuck in paused state from previous failures
launchctl stop ai.hermes.gateway && launchctl start ai.hermes.gateway

Troubleshooting:

• If hermes status shows Discord as "not configured" but you set the token, check .env for DISCORD_BOT_TOKEN. The config.yaml path (discord.token) is NOT checked by the adapter.
• After setting the token, always restart the gateway. The plugin can get stuck in its paused state (after 10 consecutive failures) and won't retry on subsequent starts.
• Token format: raw bot token (not base64 encoded). Length ~72 chars, contains . separators.

Discord idle typing / apparent LLM polling

If Discord shows <botname> is typing while the user believes Hermes is idle, do not assume repeated model calls. First separate true repeated LLM turns from Discord typing/progress transport:

1. Check ~/.hermes/logs/gateway.log for repeated inbound message: + response ready: pairs. Those indicate actual turns. Memory monitor / cron ticker / platform websocket lines do not.
2. Inspect the Discord adapter typing lifecycle. A persistent /channels/{channel_id}/typing refresh loop can make the bot appear active even when no new prompt is being launched.
3. Prefer a durable one-shot typing-pulse fix over merely telling the user to /reset: Discord send_typing() should send one pulse and leave no background typing task; stop_typing() should remain as stale-task cleanup.
4. Verify with focused Discord typing tests, restart ai.hermes.gateway, then watch at least ~45 seconds of logs for idle behavior.

Discord Voice Setup / Troubleshooting

For /voice join / /voice channel to speak in Discord voice channels on macOS:

1. Verify Hermes can join the voice channel first; logs should show VoiceReceiver started.
2. If voice replies fail with discord.errors.ClientException: ffmpeg was not found, install playback dependencies:

brew install ffmpeg opus

3. Verify from the Hermes venv:

command -v ffmpeg
~/.hermes/hermes-agent/venv/bin/python - <<'PY'
import discord, shutil
print('ffmpeg_path', shutil.which('ffmpeg'))
if not discord.opus.is_loaded():
discord.opus.load_opus('/opt/homebrew/lib/libopus.dylib')
print('opus_loaded', discord.opus.is_loaded())
PY

4. Restart gateway:

launchctl stop ai.hermes.gateway && launchctl start ai.hermes.gateway

5. Confirm the new startup logs no longer show Opus codec not found — voice channel playback disabled.
6. Test from Discord while the user is in a voice channel: /voice join, then send a normal text/voice prompt and listen for TTS playback.

Troubleshooting

• Bot appears silent — check Message Content Intent is enabled in Bot → Privileged Gateway Intents.
• Bot not responding to messages — verify the bot token in config matches the one from the developer portal.
• Invite succeeded but Hermes still shows no Discord targets — verify slash commands appear in a normal text channel, then inspect ~/.hermes/channel_directory.json. If discord is empty, restart the gateway and treat it as channel discovery / visibility rather than auth failure.
• Discord voice joins but does not speak — install ffmpeg and opus, then restart gateway. The smoking-gun log is Auto voice reply failed: ffmpeg was not found.
• Gateway dies on logout — enable linger: sudo loginctl enable-linger $USER.

Reference Files

See Also

• hermes-agent — broader Hermes configuration reference
• platforms docs — all messaging platform setups