OneClickClaw.io
Two channels, two levels of difficulty

Connect Hermes Agent to Telegram and Discord

An agent you have to open a terminal to talk to is a project. An agent that answers in an app already on your phone is a tool. This page covers both routes: Telegram, which is the gentler one, and Discord, which has more permissions to get right and is where most people get stuck.

Exact menu names and flags on the Hermes side move between releases. The order below does not, so follow the shape here and take the precise commands from the official Hermes documentation so you are never working from a snapshot that has gone stale.

Telegram, the easier route

Start here if you are choosing. Telegram needs no public address and no certificate on your side, because your server asks Telegram for messages rather than waiting to be contacted. That single design choice removes most of what usually goes wrong.

  1. 1

    Create the bot with BotFather

    In Telegram, message @BotFather and create a new bot. You get a token back. That token is the only credential between a stranger and your agent, so treat it like a password: it goes into your server configuration and nowhere else, never into a screenshot or a chat message.
  2. 2

    Put the token on the machine running Hermes

    The token belongs in your Hermes configuration on the server, not in a file you sync between devices. On a managed plan this is a field in your panel and the file permissions are already set for you.
  3. 3

    Restart the gateway and send one message

    Restart so the new configuration is loaded, then message the bot once. The first message is the real test: it proves the token is valid, the process is running, and outbound network access works. If nothing comes back, the answer is almost always in the gateway log rather than in Telegram.
  4. 4

    Lock down who is allowed to talk to it

    By default a Telegram bot can be messaged by anyone who finds it. Restrict it to your own user or chat ID before you leave it running. This is the step people skip and then discover a stranger has been talking to their agent.

Discord, and the permission that catches everyone

Discord gives you roles, channels, threads, and slash commands, which is exactly why it takes longer to set up. Most of the difficulty is not Hermes at all, it is Discord's own permission model.

  1. 1

    Create an application and a bot user

    In the Discord developer portal, create an application and add a bot to it. This gives you a separate bot token, which is not the same thing as your account and should never be shared.
  2. 2

    Turn on the privileged intents

    Discord hides two things behind explicit switches: seeing who is in a server, and reading message content. An agent that cannot read message content will connect, appear online, and answer nothing, which is the single most common Discord complaint. Enable them in the portal before you invite the bot.
  3. 3

    Invite it with the right scopes

    Generate the invite with both the bot scope and the application commands scope. Missing the second one is why slash commands silently do not appear.
  4. 4

    Run the gateway setup and set an access policy

    Pair the bot with your Hermes gateway, then define who is allowed to use it. Write the policy so that anything not explicitly allowed is refused, rather than the other way round. A Discord server has more surfaces than Telegram, including roles, channel overrides, and forum threads, and each one is a place an open default can surprise you.

If it is online and silent, stop debugging Hermes

A bot that shows green and answers nothing has almost never got a Hermes problem. It is receiving events with the text stripped out. Check the message content intent first, every time, before you touch a single line of configuration.

Why the machine underneath decides how this goes

Both channels assume the agent is there when a message arrives. On a laptop that sleeps, closes, or changes network, it is not, and the failure is silent: the app shows the bot as offline and nothing tells you why.

There is a second, quieter reason. Reaching your agent from outside your own network needs an encrypted connection with a real certificate. Doing that yourself means either a tunnelling service or a certificate you renew by hand. On a hosted plan your agent already has its own subdomain with a certificate that renews itself, so the whole category of problem does not arrive.

That is the practical difference managed hosting makes to this specific page. Not speed, and not features. Fewer things that can be silently wrong.

Channel setup FAQ

Does Telegram need my server to have a public IP address?
No. A Telegram bot works by your server asking Telegram for new messages rather than Telegram pushing them to you, so nothing has to be reachable from outside. That is why Telegram is usually the easier first channel, and why it works from behind a home router when other options do not.
My Discord bot shows as online but never replies. What is wrong?
Almost always the message content intent. Discord treats reading what people write as a privileged permission that is off by default, so the bot connects, appears healthy, and receives nothing it can act on. Turn it on in the developer portal, then restart the gateway so the connection is re-established with the new permission.
Can one agent be in Telegram and Discord at the same time?
Yes. They are separate channels into the same agent, and it keeps one set of memory across both. That is usually the point: you message it from your phone in Telegram and your team reaches the same agent in a Discord channel.
Why does this work on my laptop but not from another device?
Because a plain unencrypted connection is only accepted locally, on your own network or a .local address. Reaching the agent from somewhere else needs a proper encrypted connection with a certificate, which is exactly the piece that a hosted setup with its own subdomain gives you without any tunnelling.
What happens to the channel connection when I move servers?
Your configuration, skills, and memory files move cleanly. Anything tied to the old machine's address does not, so plan on re-pairing each channel once after the move. It takes a few minutes and it is the one part of a migration that catches people out.
Do I need to keep the bot token secret if the bot is private?
Yes, and more than usual. A bot token is not a username and password combination, it is a single string that fully authenticates as the bot. Anyone holding it can read and send messages as your agent, and a private bot is no protection at all if the token is in a screenshot or a pasted log. If you ever suspect it leaked, regenerate it.

Keep exploring

Connect Hermes Agent to Telegram and Discord | OneClickClaw.io