A Telegram bot brings Hermes onto a device you already carry, but it also exposes an agent entry point to the network. The safe setup has two credentials checks: possession of the bot token and authorization by numeric Telegram user ID.
- Create the bot through BotFather or the Dashboard’s QR flow.
- Store the token only in the active Hermes profile’s secret environment.
- Allowlist numeric user IDs, not usernames.
- Diagnose locally before starting the Gateway.
1. Create the bot and protect the token
In Telegram, open the verified @BotFather account and send /newbot. Choose a display name and a unique username ending in bot. BotFather returns the Bot API token. Anyone holding that token can control the bot, so revoke it through BotFather if it is exposed.
The Dashboard and Desktop app also provide a QR-assisted setup. The manual path remains useful because it makes each trust boundary visible.
Do not paste a real token into an article, issue, shell history, or repository. The chapter fixture contains only variable names:
cp .env.example .envFill the copied file locally. The committed template leaves both values empty.
2. Use a numeric user allowlist
Hermes authorizes Telegram senders by numeric user ID. A username such as @alice can change and is not the required identifier. Obtain the numeric ID through a trusted Telegram ID bot or the QR setup flow, then place it in TELEGRAM_ALLOWED_USERS. Separate multiple IDs with commas.
The minimum environment shape is:
TELEGRAM_BOT_TOKEN=
TELEGRAM_ALLOWED_USERS=Keep ordinary Gateway settings in Hermes configuration and secrets in the profile’s .env. When profiles are in use, configure the intended profile rather than assuming one global home directory.
3. Run the secret-safe diagnostic
The example diagnostic parses a chosen environment file and checks the live hermes gateway --help inventory. It does not call Telegram.
python3 gateway_diagnostic.py --env-file .env --jsonA passing report names TELEGRAM_BOT_TOKEN and TELEGRAM_ALLOWED_USERS, counts allowlisted entries, and confirms run, setup, and status. It never emits the variable values or numeric IDs. A malformed token shape or username-based allowlist fails before any network action.
This check establishes local readiness, not ownership of the bot. Token validity can only be established by a real Telegram connection.
4. Configure and start the Gateway
Use the interactive setup so Hermes writes settings to the correct locations:
hermes gateway setup
hermes gateway status
hermes gateway runhermes gateway run stays attached to the terminal and is convenient for the first connection. For a machine intended to run continuously, install and start the operating-system service deliberately:
hermes gateway install
hermes gateway start
hermes gateway statusService installation changes the host. Read the status and local logs after starting it. Do not publish raw logs without removing credentials and private paths.
5. Complete the connection acceptance check
Send a plain message to the bot from an allowlisted account. Acceptance requires all of these observations:
- the Gateway remains running;
- the inbound message is accepted from the intended numeric user;
- Hermes returns a response to the same chat;
- a non-allowlisted account receives no agent access;
- Gateway diagnostics do not reveal the token.
This final exchange needs a real token and network access, so the repository tests do not fake a successful Telegram response. They prove only the local preflight contract.
6. Handle groups and delivery deliberately
Telegram privacy mode is enabled by default. In groups, the bot normally receives commands, replies directed to it, service messages, and messages available through admin privileges. If ordinary group traffic is required, review BotFather privacy settings and the Hermes chat allowlists. Broader visibility should not imply broader reply permission.
A chat can become the home channel through /sethome; scheduled results can also use explicit delivery targets. Test direct messages first. Add groups, topics, or Cron delivery only after the single-user path is stable.
Webhook mode is intended for public HTTPS deployments that need inbound wakeups. It adds a webhook secret and public endpoint to the threat model. Local, always-on installations can keep the default long-polling mode.
7. Test and troubleshoot without a token
Run the fixture suite:
python3 -m unittest discover -s tests -vThe tests inject a fake command inventory and synthetic token-shaped text, then assert that no value reaches stdout or stderr. They do not read the user’s Hermes home, call BotFather, or reach the Telegram Bot API.
If the Gateway starts but does not answer, check the numeric allowlist, active profile, Gateway status, and group privacy behavior in that order. Regenerate a leaked token before continuing. Chapter 10 moves from one Gateway process to parallel subagents with isolated Git worktrees.
답글 남기기