Telegram

Telegram 문서는 Hermes Agent 공식 문서(user-guide/messaging/telegram)를 한국어로 정리한 가이드입니다. Set up Hermes Agent as a Telegram bot 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Set up Hermes Agent as a Telegram bot

한국어 가이드 범위: user-guide/messaging/telegram 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Telegram Setup
Step 1: Create a Bot via BotFather
Step 2: Customize Your Bot (Optional)
Online/Offline status indicator (Optional)
Command menu priority and cap (Optional)
Step 3: Privacy Mode (Critical for Groups)
How to disable privacy mode
Observe group chatter without auto-replying
Step 4: Find Your User ID
Step 5: Configure Hermes
Option A: Interactive Setup (Recommended)
Option B: Manual Configuration
Start the Gateway
Sending Generated Files from Docker-backed Terminals
Supported MEDIA: file extensions
Webhook Mode
구성
TELEGRAM_WEBHOOK_PORT=8443 # optional, default 8443
Cloud deployment example (Fly.io)
Proxy Support
Home Channel
Cron deliveries in topic mode
Voice Messages
Incoming Voice (Speech-to-Text)
Outgoing Voice (Text-to-Speech)
Ubuntu/Debian
macOS
Large Files (>20MB) via Local Bot API Server
Step 1: Obtain Telegram API credentials
Step 2: Run the telegram-bot-api server
Step 3: Log the bot out of the public API (one-time)
expected response: {"ok":true,"result":true}
expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}
Step 4: Point Hermes at the local server
Step 5: local_mode — file access on disk
Step 6: Test it
Group Chat Usage
Multiple Hermes bots in one group
default profile
named profiles

상세 내용

Telegram Setup

Hermes Agent integrates with Telegram as a full-featured conversational bot. Once connected, you can chat with your agent from any device, send voice memos that get auto-transcribed, receive scheduled task results, and use the agent in group chats. The integration is built on python-telegram-bot and supports text, voice, images, and file attachments.

Step 1: Create a Bot via BotFather

Every Telegram bot requires an API token issued by @BotFather, Telegram's official bot management tool.

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Step 2: Customize Your Bot (Optional)

These BotFather commands improve the user experience. Message @BotFather and use:

Command	Purpose
`/setdescription`	The "What can this bot do?" text shown before a user starts chatting
`/setabouttext`	Short text on the bot's profile page
`/setuserpic`	Upload an avatar for your bot
`/setcommands`	Define the command menu (the `/` button in chat)
`/setprivacy`	Control whether the bot sees all group messages (see Step 3)

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

Online/Offline status indicator (Optional)

Telegram bots have no real online/offline presence dot — that green dot is a

주요 항목:

The short description is global to the bot (visible to all users), not
Only a clean gateway shutdown (/stop, disconnect) writes "Offline".
Off by default, since it mutates the bot's global profile.

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

Hermes registers its command menu automatically when the Telegram gateway starts. The menu is built from the central slash-command registry plus eligible plugin/skill commands, then capped so Telegram accepts the payload reliably. The default cap is 60 commands — enough to keep all built-in commands plus common skill commands visible.

주요 항목:

my_plugin_command
prepend: put your commands first, then Hermes defaults
append: keep Hermes defaults first, then your commands
replace: use only your list for priority ordering

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

Step 3: Privacy Mode (Critical for Groups)

Telegram bots have a privacy mode that is enabled by default. This is the single most common source of confusion when using bots in groups.

주요 항목:

Messages that start with a / command
Replies directly to the bot's own messages
Service messages (member joins/leaves, pinned messages, etc.)
Messages in channels where the bot is an admin

How to disable privacy mode

Message @BotFather 2. Send /mybots 3. Select your bot 4. Go to Bot Settings → Group Privacy → Turn off

Observe group chatter without auto-replying

For OpenClaw/Yuanbao-style group behavior, configure Telegram so the bot can see ordinary group messages but only responds when directly triggered:

주요 항목:

"-1001234567890"
"-1001234567890"

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

Step 4: Find Your User ID

Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is not your username — it's a number like 123456789.

Step 5: Configure Hermes

이 섹션의 세부 항목은 공식 문서 Step 5: Configure Hermes를 참고하세요.

Option A: Interactive Setup (Recommended)

Select Telegram when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.

hermes gateway setup

Option B: Manual Configuration

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Start the Gateway

The bot should come online within seconds. Send it a message on Telegram to verify.

hermes gateway

Sending Generated Files from Docker-backed Terminals

If your terminal backend is docker, keep in mind that Telegram attachments are sent by the gateway process, not from inside the container. That means the final MEDIA:/... path must be readable on the host where the gateway is running.

주요 항목:

the agent writes a file inside Docker to /workspace/report.txt
the model emits MEDIA:/workspace/report.txt
Telegram delivery fails because /workspace/report.txt only exists inside the
"/home/user/.hermes/cache/documents:/output"
write files inside Docker to /output/...
emit the host-visible path in MEDIA:, for example:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Supported MEDIA: file extensions

The gateway extracts MEDIA:/path/to/file tags from agent replies and ships the referenced file as a platform-native attachment. Supported extensions across all gateway platforms:

Category	Extensions
Images	`png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `tiff`, `svg`
Audio	`mp3`, `wav`, `ogg`, `m4a`, `opus`, `flac`, `aac`
Video	`mp4`, `mov`, `webm`, `mkv`, `avi`
Documents	`pdf`, `txt`, `md`, `csv`, `json`, `xml`, `html`, `yaml`, `yml`, `log`
Office	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`
Archives	`zip`, `rar`, `7z`, `tar`, `gz`, `bz2`
Books / packages	`epub`, `apk`, `ipa`

Webhook Mode

By default, Hermes connects to Telegram using long polling — the gateway makes outbound requests to Telegram's servers to fetch new updates. This works well for local and always-on deployments.

	Polling (default)	Webhook
Direction	Gateway → Telegram (outbound)	Telegram → Gateway (inbound)
Best for	Local, always-on servers	Cloud platforms with auto-wake
Setup	No extra config	Set `TELEGRAM_WEBHOOK_URL`
Idle cost	Machine must stay running	Machine can sleep between messages

구성


> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

### TELEGRAM_WEBHOOK_PORT=8443        # optional, default 8443

When `TELEGRAM_WEBHOOK_URL` is set, the gateway starts an HTTP webhook server instead of polling. When unset, polling mode is used — no behavior change from previous versions.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

| Variable | Required | Description |
|----------|----------|-------------|
| `TELEGRAM_WEBHOOK_URL` | Yes | Public HTTPS URL where Telegram will send updates. The URL path is auto-extracted (e.g., `/telegram` from the example above). |
| `TELEGRAM_WEBHOOK_SECRET` | **Yes** (when `TELEGRAM_WEBHOOK_URL` is set) | Secret token that Telegram echoes in every webhook request for verification. The gateway refuses to start without it — see [GHSA-3vpc-7q5r-276h](https://github.com/NousResearch/hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. |
| `TELEGRAM_WEBHOOK_PORT` | No | Local port the webhook server listens on (default: `8443`). |

### Cloud deployment example (Fly.io)

1. Add the env vars to your Fly.io app secrets:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

```bash
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

fly deploy

Proxy Support

If Telegram's API is blocked or you need to route traffic through a proxy, set a Telegram-specific proxy URL. This takes priority over the generic HTTPS_PROXY / HTTP_PROXY env vars.

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Home Channel

Use the /sethome command in any Telegram chat (DM or group) to designate it as the home channel. Scheduled tasks (cron jobs) deliver their results to this channel.

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

Cron deliveries in topic mode

If you have topic mode enabled in your bot DM, cron messages delivered to the root chat land in the system-only lobby — replying there opens no session and you see the "main chat is reserved for system commands" notice. Create a dedicated forum topic (e.g. Cron) and set:

TELEGRAM_CRON_THREAD_ID=<topic_thread_id>

Voice Messages

이 섹션의 세부 항목은 공식 문서 Voice Messages를 참고하세요.

Incoming Voice (Speech-to-Text)

Voice messages you send on Telegram are automatically transcribed by Hermes's configured STT provider and injected as text into the conversation.

주요 항목:

local uses faster-whisper on the machine running Hermes — no API key required
groq uses Groq Whisper and requires GROQ_API_KEY
openai uses OpenAI Whisper and requires VOICE_TOOLS_OPENAI_KEY

stt:
  enabled: false

[The user sent a voice message: /home/<user>/.hermes/cache/audio/<hash>.ogg]

Outgoing Voice (Text-to-Speech)

When the agent generates audio via TTS, it's delivered as native Telegram voice bubbles — the round, inline-playable kind.

주요 항목:

OpenAI and ElevenLabs produce Opus natively — no extra setup needed
Edge TTS (the default free provider) outputs MP3 and requires ffmpeg to convert to Opus:

Ubuntu/Debian

sudo apt install ffmpeg

macOS

Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but uses the rectangular player instead of a voice bubble).

Large Files (>20MB) via Local Bot API Server

Telegram's public Bot API caps getFile downloads at 20 MB, so any voice note, audio file, video, or document larger than that is silently rejected by Hermes with a "too large" reply. The documented way around this is to run a local telegram-bot-api daemon — the same server software Telegram uses, but running on your network. A local server raises the file ceiling to 2 GB and Hermes auto-lifts its own internal cap when it sees a custom base_url configured.

주요 항목:

Sending long voice memos (45-minute meetings, podcasts) to the bot
Uploading large videos for vision-tool processing
Archiving raw audio for offline pipelines like diarization, alignment, or training data

Step 1: Obtain Telegram API credentials

The local server talks directly to Telegram's MTProto layer (not the public Bot API), so it needs MTProto credentials:

Step 2: Run the telegram-bot-api server

The community-maintained aiogram/telegram-bot-api Docker image is the easiest path. A minimal docker-compose.yaml (use --local mode to enable the higher limits):

주요 항목:

"127.0.0.1:8081:8081" # bind to loopback only; see security note
./tg-bot-api-data:/var/lib/telegram-bot-api

services:
  tg-bot-api:
    image: aiogram/telegram-bot-api:latest
    container_name: tg-bot-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8081"   # bind to loopback only; see security note
    environment:
      TELEGRAM_API_ID: "12345"           # your api_id from Step 1
      TELEGRAM_API_HASH: "abcdef..."     # your api_hash from Step 1
      TELEGRAM_LOCAL: "1"                # enable --local mode (raises 20MB → 2GB)
    volumes:
      - ./tg-bot-api-data:/var/lib/telegram-bot-api

docker compose up -d tg-bot-api
docker logs --tail 20 tg-bot-api

Step 3: Log the bot out of the public API (one-time)

A bot can only be active on one Bot API server at a time. If your bot was already running against api.telegram.org (which it almost certainly was), you must explicitly log it out there before the local server will accept it:

expected response: {"ok":true,"result":true}

bash curl "http://127.0.0.1:8081/bot/getMe"

This is a one-shot migration step — you don't repeat it on every restart. Telegram delivers any messages received after `logOut` through the new server instead.

Verify the local server can talk to Telegram on the bot's behalf:

expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}


### Step 4: Point Hermes at the local server

Add the URLs under `platforms.telegram.extra` in `~/.hermes/config.yaml`:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

- Builds the python-telegram-bot client against the local server
- Auto-lifts its internal document/audio size cap from 20 MB → 2 GB
- Reports the active limit in the "too large" error message (`Maximum: 2048 MB.`) so it's obvious which mode you're in

```yaml
platforms:
  telegram:
    extra:
      base_url: "http://127.0.0.1:8081/bot"
      base_file_url: "http://127.0.0.1:8081/file/bot"
      local_mode: true        # see Step 5 below — only set this if the bot's data
                              # directory is readable by the Hermes process

hermes gateway restart
grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.hermes/logs/gateway.log | tail

Step 5: local_mode — file access on disk

The local server has two ways to deliver files:

주요 항목:

Same machine — telegram-bot-api and Hermes run on the same host. Bind-mount the data volume to a directory that Hermes can read (e.g., /var/lib/telegram-bot-api), and make sure the file ownership matches. The container drops privileges to its internal telegram-bot-api user (uid varies by image); the simplest fix is to add user: "<UID>:<GID>" to the compose service so files are owned by a uid Hermes already runs as.
Different machines — the bot server runs on one host (e.g., a NAS, a separate VM) and Hermes on another. The server's data directory must be shared with the Hermes machine at the same absolute path the server reports (typically /var/lib/telegram-bot-api). NFS works well for this; CIFS/SMB with uid= mount remapping is friendlier if you don't want to deal with uid mismatches at the filesystem level.

[Telegram] Failed to cache voice: Not Found
telegram.error.InvalidToken: Not Found

Step 6: Test it

Send the bot a voice note or audio file that's bigger than 20 MB. Tail the gateway log:

tail -f ~/.hermes/logs/gateway.log | grep -iE "telegram|cache"

Group Chat Usage

Hermes Agent works in Telegram group chats with a few considerations:

주요 항목:

Privacy mode determines what messages the bot can see (see Step 3)
TELEGRAM_ALLOWED_USERS still applies — only authorized users can trigger the bot, even in groups
You can keep the bot from responding to ordinary group chatter with telegram.require_mention: true
With telegram.require_mention: true, group messages are accepted when they are:
replies to one of the bot's messages
@botusername mentions
/command@botusername (Telegram's bot-menu command form that includes the bot name)
matches for one of your configured regex wake words in telegram.mention_patterns
In groups with multiple Hermes bots, telegram.exclusive_bot_mentions keeps routing deterministic. When a message explicitly mentions one or more Telegram bot usernames, only the mentioned bot profiles process it; other Hermes bots ignore it before reply and wake-word fallbacks run. This is enabled by default.
Use telegram.ignored_threads to keep Hermes silent in specific Telegram forum topics, even when the group would otherwise allow free responses or mention-triggered replies
If telegram.require_mention is left unset or false, Hermes keeps the previous open-group behavior and responds to normal group messages it can see

Multiple Hermes bots in one group

If you run several Hermes profiles in the same Telegram group, create one Telegram bot token per profile and start one gateway per profile. Do not reuse the same bot token in multiple running gateways; Telegram will reject concurrent polling for the same token.

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns: []

default profile

hermes gateway start hermes gateway status hermes gateway stop

named profiles

hermes -p research gateway start hermes -p research gateway status hermes -p research gateway stop ```

Troubleshooting: works in DMs but not groups

If the bot responds in a private chat but stays silent in a group, check these gates in order:

Example group trigger configuration

This example allows all the usual direct triggers plus messages that begin with chompy, even if they do not use an @mention. Messages in Telegram topics 31 and 42 are always ignored before the mention and free-response checks run.

주요 항목:

"^\s*chompy\b"
"42"

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns:
    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

Notes on mention_patterns

주요 항목:

Patterns use Python regular expressions
Matching is case-insensitive
Patterns are checked against both text messages and media captions
Invalid regex patterns are ignored with a warning in the gateway logs rather than crashing the bot
If you want a pattern to match only at the start of a message, anchor it with ^

Private Chat Topics (Bot API 9.4)

Telegram Bot API 9.4 (February 2026) introduced Private Chat Topics — bots can create forum-style topic threads directly in 1-on-1 DM chats, no supergroup needed. This lets you run multiple isolated workspaces within your existing DM with Hermes.

Use case

If you work on several long-running projects, topics keep their context separate:

주요 항목:

Topic "Website" — work on your production web service
Topic "Research" — literature review and paper exploration
Topic "General" — miscellaneous tasks and quick questions

구성

:::caution Prerequisites Before adding topics to your config, the user must enable Topics mode in the DM chat with the bot:

주요 항목:

chat_id: 123456789 # Your Telegram user ID
name: General
name: Website
name: Research

Field	Required	Description
`name`	Yes	Topic display name
`icon_color`	No	Telegram icon color code (integer)
`icon_custom_emoji_id`	No	Custom emoji ID for the topic icon
`skill`	No	Skill to auto-load on new sessions in this topic
`thread_id`	No	Auto-populated after topic creation — don't set manually

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Your Telegram user ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # Auto-load a skill in this topic

동작 방식

On gateway startup, Hermes calls createForumTopic for each topic that doesn't have a thread_id yet 2. The thread_id is saved back to config.yaml automatically — subsequent restarts skip the API call 3. Each topic maps to an isolated session key: agent:main:telegram:dm:{chat_id}:{thread_id} 4. Messages in each topic have their own conversation history, memory flush, and context window

Root DM handling

By default, messages sent to the root DM (outside any topic) are processed normally. Set ignore_root_dm: true to turn the root DM into a lobby — normal messages are silently ignored for users who have DM topics configured, while system commands (/start, /help, /status, etc.) still work.

주요 항목:

chat_id: 123456789
name: General

platforms:
  telegram:
    extra:
      ignore_root_dm: true
      dm_topics:
        - chat_id: 123456789
          topics:
            - name: General

Skill binding

Topics with a skill field automatically load that skill when a new session starts in the topic. This works exactly like typing /skill-name at the start of a conversation — the skill content is injected into the first message, and subsequent messages see it in the conversation history.

Multi-session DM mode (/topic)

A ChatGPT-style multi-session DM — one bot, many parallel conversations. Unlike the operator-curated extra.dm_topics above, this mode is user-driven: no config, no pre-declared topic names. The end user flips it on with /topic, then taps the Telegram + button to create as many topics as they want, each one a fully independent Hermes session.

실습 체크리스트

공식 문서와 설치된 Hermes 버전을 대조합니다.
관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

hermes gateway setup

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

핵심 요약

Set up Hermes Agent as a Telegram bot

한국어 가이드 범위: user-guide/messaging/telegram 경로의 설정·명령·제약·예시를 학습용으로 재구성합니다.

문서 구성

공식 문서의 주요 섹션은 다음과 같습니다.

Telegram Setup
Step 1: Create a Bot via BotFather
Step 2: Customize Your Bot (Optional)
Online/Offline status indicator (Optional)
Command menu priority and cap (Optional)
Step 3: Privacy Mode (Critical for Groups)
How to disable privacy mode
Observe group chatter without auto-replying
Step 4: Find Your User ID
Step 5: Configure Hermes
Option A: Interactive Setup (Recommended)
Option B: Manual Configuration
Start the Gateway
Sending Generated Files from Docker-backed Terminals
Supported MEDIA: file extensions
Webhook Mode
구성
TELEGRAM_WEBHOOK_PORT=8443 # optional, default 8443
Cloud deployment example (Fly.io)
Proxy Support
Home Channel
Cron deliveries in topic mode
Voice Messages
Incoming Voice (Speech-to-Text)
Outgoing Voice (Text-to-Speech)
Ubuntu/Debian
macOS
Large Files (>20MB) via Local Bot API Server
Step 1: Obtain Telegram API credentials
Step 2: Run the telegram-bot-api server
Step 3: Log the bot out of the public API (one-time)
expected response: {"ok":true,"result":true}
expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}
Step 4: Point Hermes at the local server
Step 5: local_mode — file access on disk
Step 6: Test it
Group Chat Usage
Multiple Hermes bots in one group
default profile
named profiles

상세 내용

Telegram Setup

Step 1: Create a Bot via BotFather

Every Telegram bot requires an API token issued by @BotFather, Telegram's official bot management tool.

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

Step 2: Customize Your Bot (Optional)

These BotFather commands improve the user experience. Message @BotFather and use:

Command	Purpose
`/setdescription`	The "What can this bot do?" text shown before a user starts chatting
`/setabouttext`	Short text on the bot's profile page
`/setuserpic`	Upload an avatar for your bot
`/setcommands`	Define the command menu (the `/` button in chat)
`/setprivacy`	Control whether the bot sees all group messages (see Step 3)

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

Online/Offline status indicator (Optional)

Telegram bots have no real online/offline presence dot — that green dot is a

주요 항목:

The short description is global to the bot (visible to all users), not
Only a clean gateway shutdown (/stop, disconnect) writes "Offline".
Off by default, since it mutates the bot's global profile.

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

주요 항목:

my_plugin_command
prepend: put your commands first, then Hermes defaults
append: keep Hermes defaults first, then your commands
replace: use only your list for priority ordering

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

Step 3: Privacy Mode (Critical for Groups)

Telegram bots have a privacy mode that is enabled by default. This is the single most common source of confusion when using bots in groups.

주요 항목:

Messages that start with a / command
Replies directly to the bot's own messages
Service messages (member joins/leaves, pinned messages, etc.)
Messages in channels where the bot is an admin

How to disable privacy mode

Message @BotFather 2. Send /mybots 3. Select your bot 4. Go to Bot Settings → Group Privacy → Turn off

Observe group chatter without auto-replying

For OpenClaw/Yuanbao-style group behavior, configure Telegram so the bot can see ordinary group messages but only responds when directly triggered:

주요 항목:

"-1001234567890"
"-1001234567890"

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

Step 4: Find Your User ID

Hermes Agent uses numeric Telegram user IDs to control access. Your user ID is not your username — it's a number like 123456789.

Step 5: Configure Hermes

이 섹션의 세부 항목은 공식 문서 Step 5: Configure Hermes를 참고하세요.

Option A: Interactive Setup (Recommended)

Select Telegram when prompted. The wizard asks for your bot token and allowed user IDs, then writes the configuration for you.

hermes gateway setup

Option B: Manual Configuration

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

Start the Gateway

The bot should come online within seconds. Send it a message on Telegram to verify.

hermes gateway

Sending Generated Files from Docker-backed Terminals

주요 항목:

the agent writes a file inside Docker to /workspace/report.txt
the model emits MEDIA:/workspace/report.txt
Telegram delivery fails because /workspace/report.txt only exists inside the
"/home/user/.hermes/cache/documents:/output"
write files inside Docker to /output/...
emit the host-visible path in MEDIA:, for example:

terminal:
  backend: docker
  docker_volumes:
    - "/home/user/.hermes/cache/documents:/output"

Supported MEDIA: file extensions

The gateway extracts MEDIA:/path/to/file tags from agent replies and ships the referenced file as a platform-native attachment. Supported extensions across all gateway platforms:

Category	Extensions
Images	`png`, `jpg`, `jpeg`, `gif`, `webp`, `bmp`, `tiff`, `svg`
Audio	`mp3`, `wav`, `ogg`, `m4a`, `opus`, `flac`, `aac`
Video	`mp4`, `mov`, `webm`, `mkv`, `avi`
Documents	`pdf`, `txt`, `md`, `csv`, `json`, `xml`, `html`, `yaml`, `yml`, `log`
Office	`docx`, `xlsx`, `pptx`, `odt`, `ods`, `odp`
Archives	`zip`, `rar`, `7z`, `tar`, `gz`, `bz2`
Books / packages	`epub`, `apk`, `ipa`

Webhook Mode

By default, Hermes connects to Telegram using long polling — the gateway makes outbound requests to Telegram's servers to fetch new updates. This works well for local and always-on deployments.

	Polling (default)	Webhook
Direction	Gateway → Telegram (outbound)	Telegram → Gateway (inbound)
Best for	Local, always-on servers	Cloud platforms with auto-wake
Setup	No extra config	Set `TELEGRAM_WEBHOOK_URL`
Idle cost	Machine must stay running	Machine can sleep between messages

구성


> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

### TELEGRAM_WEBHOOK_PORT=8443        # optional, default 8443

When `TELEGRAM_WEBHOOK_URL` is set, the gateway starts an HTTP webhook server instead of polling. When unset, polling mode is used — no behavior change from previous versions.

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

| Variable | Required | Description |
|----------|----------|-------------|
| `TELEGRAM_WEBHOOK_URL` | Yes | Public HTTPS URL where Telegram will send updates. The URL path is auto-extracted (e.g., `/telegram` from the example above). |
| `TELEGRAM_WEBHOOK_SECRET` | **Yes** (when `TELEGRAM_WEBHOOK_URL` is set) | Secret token that Telegram echoes in every webhook request for verification. The gateway refuses to start without it — see [GHSA-3vpc-7q5r-276h](https://github.com/NousResearch/hermes-agent/security/advisories/GHSA-3vpc-7q5r-276h). Generate with `openssl rand -hex 32`. |
| `TELEGRAM_WEBHOOK_PORT` | No | Local port the webhook server listens on (default: `8443`). |

### Cloud deployment example (Fly.io)

1. Add the env vars to your Fly.io app secrets:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

```bash
fly secrets set TELEGRAM_WEBHOOK_URL=https://my-app.fly.dev/telegram
fly secrets set TELEGRAM_WEBHOOK_SECRET=$(openssl rand -hex 32)

[[services]]
  internal_port = 8443
  protocol = "tcp"

  [[services.ports]]
    handlers = ["tls", "http"]
    port = 443

fly deploy

Proxy Support

If Telegram's API is blocked or you need to route traffic through a proxy, set a Telegram-specific proxy URL. This takes priority over the generic HTTPS_PROXY / HTTP_PROXY env vars.

telegram:
  proxy_url: "socks5://127.0.0.1:1080"

TELEGRAM_PROXY=socks5://127.0.0.1:1080

Home Channel

Use the /sethome command in any Telegram chat (DM or group) to designate it as the home channel. Scheduled tasks (cron jobs) deliver their results to this channel.

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="My Notes"

Cron deliveries in topic mode

TELEGRAM_CRON_THREAD_ID=<topic_thread_id>

Voice Messages

이 섹션의 세부 항목은 공식 문서 Voice Messages를 참고하세요.

Incoming Voice (Speech-to-Text)

Voice messages you send on Telegram are automatically transcribed by Hermes's configured STT provider and injected as text into the conversation.

주요 항목:

local uses faster-whisper on the machine running Hermes — no API key required
groq uses Groq Whisper and requires GROQ_API_KEY
openai uses OpenAI Whisper and requires VOICE_TOOLS_OPENAI_KEY

stt:
  enabled: false

[The user sent a voice message: /home/<user>/.hermes/cache/audio/<hash>.ogg]

Outgoing Voice (Text-to-Speech)

When the agent generates audio via TTS, it's delivered as native Telegram voice bubbles — the round, inline-playable kind.

주요 항목:

OpenAI and ElevenLabs produce Opus natively — no extra setup needed
Edge TTS (the default free provider) outputs MP3 and requires ffmpeg to convert to Opus:

Ubuntu/Debian

sudo apt install ffmpeg

macOS

Without ffmpeg, Edge TTS audio is sent as a regular audio file (still playable, but uses the rectangular player instead of a voice bubble).

Large Files (>20MB) via Local Bot API Server

주요 항목:

Sending long voice memos (45-minute meetings, podcasts) to the bot
Uploading large videos for vision-tool processing
Archiving raw audio for offline pipelines like diarization, alignment, or training data

Step 1: Obtain Telegram API credentials

The local server talks directly to Telegram's MTProto layer (not the public Bot API), so it needs MTProto credentials:

Step 2: Run the telegram-bot-api server

The community-maintained aiogram/telegram-bot-api Docker image is the easiest path. A minimal docker-compose.yaml (use --local mode to enable the higher limits):

주요 항목:

"127.0.0.1:8081:8081" # bind to loopback only; see security note
./tg-bot-api-data:/var/lib/telegram-bot-api

services:
  tg-bot-api:
    image: aiogram/telegram-bot-api:latest
    container_name: tg-bot-api
    restart: unless-stopped
    ports:
      - "127.0.0.1:8081:8081"   # bind to loopback only; see security note
    environment:
      TELEGRAM_API_ID: "12345"           # your api_id from Step 1
      TELEGRAM_API_HASH: "abcdef..."     # your api_hash from Step 1
      TELEGRAM_LOCAL: "1"                # enable --local mode (raises 20MB → 2GB)
    volumes:
      - ./tg-bot-api-data:/var/lib/telegram-bot-api

docker compose up -d tg-bot-api
docker logs --tail 20 tg-bot-api

Step 3: Log the bot out of the public API (one-time)

expected response: {"ok":true,"result":true}

bash curl "http://127.0.0.1:8081/bot/getMe"

This is a one-shot migration step — you don't repeat it on every restart. Telegram delivers any messages received after `logOut` through the new server instead.

Verify the local server can talk to Telegram on the bot's behalf:

expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}


### Step 4: Point Hermes at the local server

Add the URLs under `platforms.telegram.extra` in `~/.hermes/config.yaml`:

> 위 내용은 공식 문서의 해당 섹션 요지입니다. 세부 플래그·기본값은 원문을 확인하세요.

주요 항목:

- Builds the python-telegram-bot client against the local server
- Auto-lifts its internal document/audio size cap from 20 MB → 2 GB
- Reports the active limit in the "too large" error message (`Maximum: 2048 MB.`) so it's obvious which mode you're in

```yaml
platforms:
  telegram:
    extra:
      base_url: "http://127.0.0.1:8081/bot"
      base_file_url: "http://127.0.0.1:8081/file/bot"
      local_mode: true        # see Step 5 below — only set this if the bot's data
                              # directory is readable by the Hermes process

hermes gateway restart
grep -E "Using custom Telegram base_url|Using Telegram local_mode" ~/.hermes/logs/gateway.log | tail

Step 5: local_mode — file access on disk

The local server has two ways to deliver files:

주요 항목:

Same machine — telegram-bot-api and Hermes run on the same host. Bind-mount the data volume to a directory that Hermes can read (e.g., /var/lib/telegram-bot-api), and make sure the file ownership matches. The container drops privileges to its internal telegram-bot-api user (uid varies by image); the simplest fix is to add user: "<UID>:<GID>" to the compose service so files are owned by a uid Hermes already runs as.
Different machines — the bot server runs on one host (e.g., a NAS, a separate VM) and Hermes on another. The server's data directory must be shared with the Hermes machine at the same absolute path the server reports (typically /var/lib/telegram-bot-api). NFS works well for this; CIFS/SMB with uid= mount remapping is friendlier if you don't want to deal with uid mismatches at the filesystem level.

[Telegram] Failed to cache voice: Not Found
telegram.error.InvalidToken: Not Found

Step 6: Test it

Send the bot a voice note or audio file that's bigger than 20 MB. Tail the gateway log:

tail -f ~/.hermes/logs/gateway.log | grep -iE "telegram|cache"

Group Chat Usage

Hermes Agent works in Telegram group chats with a few considerations:

주요 항목:

Privacy mode determines what messages the bot can see (see Step 3)
TELEGRAM_ALLOWED_USERS still applies — only authorized users can trigger the bot, even in groups
You can keep the bot from responding to ordinary group chatter with telegram.require_mention: true
With telegram.require_mention: true, group messages are accepted when they are:
replies to one of the bot's messages
@botusername mentions
/command@botusername (Telegram's bot-menu command form that includes the bot name)
matches for one of your configured regex wake words in telegram.mention_patterns
In groups with multiple Hermes bots, telegram.exclusive_bot_mentions keeps routing deterministic. When a message explicitly mentions one or more Telegram bot usernames, only the mentioned bot profiles process it; other Hermes bots ignore it before reply and wake-word fallbacks run. This is enabled by default.
Use telegram.ignored_threads to keep Hermes silent in specific Telegram forum topics, even when the group would otherwise allow free responses or mention-triggered replies
If telegram.require_mention is left unset or false, Hermes keeps the previous open-group behavior and responds to normal group messages it can see

Multiple Hermes bots in one group

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns: []

default profile

hermes gateway start hermes gateway status hermes gateway stop

named profiles

hermes -p research gateway start hermes -p research gateway status hermes -p research gateway stop ```

Troubleshooting: works in DMs but not groups

If the bot responds in a private chat but stays silent in a group, check these gates in order:

Example group trigger configuration

주요 항목:

"^\s*chompy\b"
"42"

telegram:
  require_mention: true
  exclusive_bot_mentions: true
  mention_patterns:
    - "^\\s*chompy\\b"
  ignored_threads:
    - 31
    - "42"

Notes on mention_patterns

주요 항목:

Patterns use Python regular expressions
Matching is case-insensitive
Patterns are checked against both text messages and media captions
Invalid regex patterns are ignored with a warning in the gateway logs rather than crashing the bot
If you want a pattern to match only at the start of a message, anchor it with ^

Private Chat Topics (Bot API 9.4)

Use case

If you work on several long-running projects, topics keep their context separate:

주요 항목:

Topic "Website" — work on your production web service
Topic "Research" — literature review and paper exploration
Topic "General" — miscellaneous tasks and quick questions

구성

:::caution Prerequisites Before adding topics to your config, the user must enable Topics mode in the DM chat with the bot:

주요 항목:

chat_id: 123456789 # Your Telegram user ID
name: General
name: Website
name: Research

Field	Required	Description
`name`	Yes	Topic display name
`icon_color`	No	Telegram icon color code (integer)
`icon_custom_emoji_id`	No	Custom emoji ID for the topic icon
`skill`	No	Skill to auto-load on new sessions in this topic
`thread_id`	No	Auto-populated after topic creation — don't set manually

platforms:
  telegram:
    extra:
      dm_topics:
      - chat_id: 123456789        # Your Telegram user ID
        topics:
        - name: General
          icon_color: 7322096
        - name: Website
          icon_color: 9367192
        - name: Research
          icon_color: 16766590
          skill: arxiv              # Auto-load a skill in this topic

동작 방식

On gateway startup, Hermes calls createForumTopic for each topic that doesn't have a thread_id yet 2. The thread_id is saved back to config.yaml automatically — subsequent restarts skip the API call 3. Each topic maps to an isolated session key: agent:main:telegram:dm:{chat_id}:{thread_id} 4. Messages in each topic have their own conversation history, memory flush, and context window

Root DM handling

주요 항목:

chat_id: 123456789
name: General

platforms:
  telegram:
    extra:
      ignore_root_dm: true
      dm_topics:
        - chat_id: 123456789
          topics:
            - name: General

Skill binding

Multi-session DM mode (/topic)

실습 체크리스트

공식 문서와 설치된 Hermes 버전을 대조합니다.
관련 CLI는 hermes --help 및 하위 명령 --help로 확인합니다.
Gateway·메시징 변경 후 hermes gateway 재시작을 검토합니다.
시크릿·토큰은 환경 변수/시크릿 매니저에만 둡니다.

자주 쓰는 명령·설정 예시

123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

help - Show help information
new - Start a new conversation
sethome - Set this chat as the home channel

gateway:
  platforms:
    telegram:
      extra:
        status_indicator: true
        # Optional custom strings (defaults: "Online" / "Offline"):
        status_online: "🟢 Online"
        status_offline: "🔴 Offline"

platforms:
  telegram:
    extra:
      command_menu:
        max_commands: 60
        priority_mode: prepend  # prepend | append | replace
        priority:
          - my_plugin_command

telegram:
  allowed_chats:
    - "-1001234567890"
  group_allowed_chats:
    - "-1001234567890"
  require_mention: true
  observe_unmentioned_group_messages: true

TELEGRAM_ALLOWED_CHATS=-1001234567890
TELEGRAM_GROUP_ALLOWED_CHATS=-1001234567890
TELEGRAM_OBSERVE_UNMENTIONED_GROUP_MESSAGES=true

hermes gateway setup

TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # Comma-separated for multiple users

핵심 요약

문서 구성

상세 내용

Telegram Setup

Step 1: Create a Bot via BotFather

Step 2: Customize Your Bot (Optional)

Online/Offline status indicator (Optional)

Command menu priority and cap (Optional)

Step 3: Privacy Mode (Critical for Groups)

How to disable privacy mode

Observe group chatter without auto-replying

Step 4: Find Your User ID

Step 5: Configure Hermes

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Start the Gateway

Sending Generated Files from Docker-backed Terminals

Supported MEDIA: file extensions

Webhook Mode

구성

Proxy Support

Home Channel

Cron deliveries in topic mode

Voice Messages

Incoming Voice (Speech-to-Text)

Outgoing Voice (Text-to-Speech)

Ubuntu/Debian

macOS

Large Files (>20MB) via Local Bot API Server

Step 1: Obtain Telegram API credentials

Step 2: Run the telegram-bot-api server

Step 3: Log the bot out of the public API (one-time)

expected response: {"ok":true,"result":true}

expected response: {"ok":true,"result":{"id":...,"is_bot":true,...}}

Step 5: local_mode — file access on disk

Step 6: Test it

Group Chat Usage

Multiple Hermes bots in one group

default profile

named profiles

Troubleshooting: works in DMs but not groups

Example group trigger configuration

Notes on mention_patterns

Private Chat Topics (Bot API 9.4)

Use case

구성

동작 방식

Root DM handling

Skill binding

Multi-session DM mode (/topic)

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Telegram

핵심 요약

문서 구성

상세 내용

Telegram Setup

Step 1: Create a Bot via BotFather

Step 2: Customize Your Bot (Optional)

Online/Offline status indicator (Optional)

Command menu priority and cap (Optional)

Step 3: Privacy Mode (Critical for Groups)

How to disable privacy mode

Observe group chatter without auto-replying

Step 4: Find Your User ID

Step 5: Configure Hermes

Option A: Interactive Setup (Recommended)

Option B: Manual Configuration

Start the Gateway

Sending Generated Files from Docker-backed Terminals

Supported MEDIA: file extensions

Webhook Mode

구성

Proxy Support

Home Channel

Cron deliveries in topic mode

Voice Messages