Messaging Gateway

Messaging Gateway 문서는 Hermes Agent 공식 문서(user-guide/messaging/index)를 한국어로 정리한 가이드입니다. Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Yuanbao, Microsoft Teams, LINE, Raft, Webhooks, or any OpenAI-compatible frontend via the API server — architecture and setup overview 명령·설정 키·코드 예시는 공식 문서를 그대로 보존하며, 해석과 절차 안내는 한국어로 제공합니다. 최종 동작은 설치 버전과 공식 원문을 확인하세요.

핵심 요약

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Yuanbao, Microsoft Teams, LINE, Raft, Webhooks, or any OpenAI-compatible frontend via the API server — architecture and setup overview

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

문서 구성

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

Messaging Gateway
Platform Comparison
아키텍처
Intentional Silence Tokens
Quick Setup
Gateway Commands
Optional Linux event-loop watchdog
Chat Commands (Inside Messaging)
Session Management
Session Persistence
Delivery Reliability
Reset Policies
보안
Restrict to specific users (recommended):
Or allow
Or explicitly allow all users (NOT recommended for bots with terminal access):
DM Pairing (Alternative to Allowlists)
The user sees: "Pairing code: XKGH5N7P"
You approve them with:
Other pairing commands:
Admins vs Regular Users
Redirecting the Agent
Queue vs interrupt vs steer (busy-input mode)
Tool Progress Notifications
Message timestamps in model context
Background Sessions
동작 방식
Background Process Notifications
Use Cases
Service Management
Linux (systemd)
Enable lingering (keeps running after logout)
Or install a boot-time system service that still runs as your user
macOS (launchd)
Platform-Specific Toolsets
Operating a multi-platform gateway
/platform command
Automatic circuit breaker
Where to look when a platform is paused
Restart notifications

상세 내용

Messaging Gateway

Chat with Hermes from Telegram, Discord, Slack, WhatsApp, Signal, SMS, Email, Home Assistant, Mattermost, Matrix, DingTalk, Feishu/Lark, WeCom, Weixin, BlueBubbles (iMessage), QQ, Yuanbao, Microsoft Teams, LINE, ntfy, or your browser. The gateway is a single background process that connects to all your configured platforms, handles sessions, runs cron jobs, and delivers voice messages.

Platform Comparison

Platform	Voice	Images	Files	Threads	Reactions	Typing	Streaming
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
Google Chat	—	✅	✅	✅	—	✅	—
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
SMS	—	—	—	—	—	—	—
Email	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	✅	✅	✅
DingTalk	—	✅	✅	—	✅	—	✅
Feishu/Lark	✅	✅	✅	✅	✅	✅	✅
WeCom	✅	✅	✅	—	—	—	—
WeCom Callback	—	—	—	—	—	—	—
Weixin	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—
QQ	✅	✅	✅	—	—	✅	—
Yuanbao	✅	✅	✅	—	—	✅	✅
Microsoft Teams	—	✅	—	✅	—	✅	—
LINE	—	✅	✅	—	—	✅	—
ntfy	—	—	—	—	—	—	—
Raft	—	—	—	—	—	—	—
IRC	—	—	—	—	—	—	—

아키텍처

Each platform adapter receives messages, routes them through a per-chat session store, and dispatches them to the AIAgent for processing. The gateway also runs the cron scheduler, ticking every 60 seconds to execute any due jobs.

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

Intentional Silence Tokens

For group chats, hooks, and automation flows, Hermes supports explicit silence tokens. If the agent's final response is exactly one supported token, the gateway suppresses outbound delivery and sends nothing to the chat.

주요 항목:

[SILENT]
SILENT
NO_REPLY
NO REPLY

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

Quick Setup

The easiest way to configure messaging platforms is the interactive wizard:

hermes gateway setup        # Interactive setup for all messaging platforms

Gateway Commands

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Optional Linux event-loop watchdog

A systemd-managed gateway can opt into process recovery when Python's asyncio event loop stops receiving scheduling time. This covers whole-process stalls that also prevent platform-specific liveness tasks from running:

Regenerate the service unit after changing this setting:

Chat Commands (Inside Messaging)

Command	Description
`/new` or `/reset`	Start a fresh conversation
`/model [provider:model]`	Show or change the model (supports `provider:model` syntax)
`/personality [name]`	Set a personality
`/retry`	Retry the last message
`/undo`	Remove the last exchange
`/status`	Show session info
`/whoami`	Show your slash command access on this scope (admin / user / unrestricted)
`/stop`	Stop the running agent
`/approve`	Approve a pending dangerous command
`/deny`	Reject a pending dangerous command
`/sethome`	Set this chat as the home channel
`/compress`	Manually compress conversation context
`/title [name]`	Set or show the session title
`/resume [name]`	Resume a previously named session
`/usage`	Show token usage for this session (`/usage reset [--force]` redeems a banked Codex limit reset)
`/insights [days]`	Show usage insights and analytics
`/reasoning [level\|show\|hide]`	Change reasoning effort or toggle reasoning display
`/voice [on\|off\|tts\|join\|leave\|status]`	Control messaging voice replies and Discord voice-channel behavior
`/rollback [number]`	List or restore filesystem checkpoints
`/background <prompt>`	Run a prompt in a separate background session
`/reload-mcp`	Reload MCP servers from config
`/update`	Update Hermes Agent to the latest version
`/help`	Show available commands
`/<skill-name>`	Invoke any installed skill

Session Management

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

Session Persistence

Sessions persist across messages until they reset. The agent remembers your conversation context.

Delivery Reliability

Final agent responses are recorded in a durable delivery ledger (state.db) around each platform send. If the gateway crashes or restarts between producing a response and the platform confirming receipt, the next boot redelivers the stored response instead of losing it — or re-running the whole turn.

주요 항목:

A response whose send never started is redelivered as-is.
A response that was mid-send when the gateway died (the platform may or
Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is

Reset Policies

manually or context compression kicks in. If you want automatic resets, opt in with the session_reset section in ~/.hermes/config.yaml:

Mode	Description
`none`	Never auto-reset (default)
`daily`	Reset at a specific hour each day
`idle`	Reset after N minutes of inactivity
`both`	Whichever triggers first

session_reset:
  mode: idle        # "idle", "daily", "both", or "none" (default)
  idle_minutes: 1440  # for idle/both: minutes of inactivity before reset
  at_hour: 4          # for daily/both: hour of day (0-23, local time)

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

보안

By default, the gateway denies all users who are not in an allowlist or paired via DM. This is the safe default for a bot with terminal access.


### Restrict to specific users (recommended):

TELEGRAM_ALLOWED_USERS=123456789,987654321 DISCORD_ALLOWED_USERS=123456789012345678 SIGNAL_ALLOWED_USERS=+155****4567,+155****6543 SMS_ALLOWED_USERS=+155****4567,+155****6543 EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c MATRIX_ALLOWED_USERS=@alice:matrix.org DINGTALK_ALLOWED_USERS=user-id-1 FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy WECOM_ALLOWED_USERS=user-id-1,user-id-2 WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2 TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

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

### Or allow

GATEWAY_ALLOWED_USERS=123456789,987654321

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

### Or explicitly allow all users (NOT recommended for bots with terminal access):

GATEWAY_ALLOW_ALL_USERS=true

DM Pairing (Alternative to Allowlists)

Instead of manually configuring user IDs, unknown users receive a one-time pairing code when they DM the bot. Email is the exception: unknown email senders are ignored unless email pairing is explicitly enabled.

The user sees: "Pairing code: XKGH5N7P"

이 섹션의 세부 항목은 공식 문서 The user sees: "Pairing code: XKGH5N7P"를 참고하세요.

You approve them with:

hermes pairing approve telegram XKGH5N7P

Other pairing commands:

hermes pairing list # View pending + approved users hermes pairing revoke telegram 123456789 # Remove access ```

Admins vs Regular Users

Allowlists answer "can this person reach the bot at all?" The admin / user split answers "now that they're in, what are they allowed to do?"

주요 항목:

Admin — full access. Can run every registered slash command (built-in + plugin) and use every gated capability.
Regular user — restricted access. Can chat with the agent normally, but can only run the slash commands you explicitly enable. The always-allowed floor is /help and /whoami.

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # admins → all slash commands
        user_allowed_commands: [status, model]       # what non-admins may run
        # Optional: separate group/channel scope
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

Redirecting the Agent

Send a message while the agent is working to correct the active turn:

주요 항목:

Model generation restarts with context — reasoning already shown and visible partial text are retained as an ordinary assistant checkpoint
Completed work stays available — prior tool calls and results remain in the turn
Running tools finish safely — the correction is applied at the next tool-result boundary instead of killing the tool
/stop remains a hard stop — use it to cancel the active turn and foreground work

Queue vs interrupt vs steer (busy-input mode)

By default, messaging a busy agent redirects its active turn. Two other modes are available:

주요 항목:

queue — follow-up messages wait and run as the next turn after the current task finishes.
steer — follow-up messages are injected into the current run via /steer, arriving at the agent after the next tool call. No interrupt, no new turn. Falls back to queue behavior if the agent hasn't started yet.

display:
  busy_input_mode: steer   # or queue, or interrupt (default)
  busy_ack_enabled: true   # set to false to suppress the ⚡/⏳/⏩ chat reply entirely

Tool Progress Notifications

Control how much tool activity is displayed in ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # set to true to enable /verbose in messaging
  # How progress is grouped on platforms that support message editing:
  #   accumulate (default) — edit one bubble in place as tools run
  #   separate             — send one message per tool (pre-v0.9 style; noisier)
  # Only applies where tool_progress is already enabled.
  tool_progress_grouping: accumulate   # accumulate | separate

Message timestamps in model context

Off by default. When enabled, Hermes prepends a human-readable timestamp (e.g. [Tue 2026-04-28 13:40:53 CEST]) onto each user message in the model's context so the agent knows when messages were sent — useful for temporal reasoning ("you asked this morning…", noticing a long gap). It is

gateway:
  message_timestamps:
    enabled: false   # set true to show send-times to the model

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

Background Sessions

Run a prompt in a separate background session so the agent works on it independently while your main chat stays responsive:

/background Check all servers in the cluster and report any that are down

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

동작 방식

Each /background prompt spawns a separate agent instance that runs asynchronously:

주요 항목:

Isolated session — the background agent has its own session with its own conversation history. It has no knowledge of your current chat context and receives only the prompt you provide.
Same configuration — inherits your model, provider, toolsets, reasoning settings, and provider routing from the current gateway setup.
Non-blocking — your main chat stays fully interactive. Send messages, run other commands, or start more background tasks while it works.
Result delivery — when the task finishes, the result is sent back to the same chat or channel where you issued the command, prefixed with "✅ Background task complete". If it fails, you'll see "❌ Background task failed" with the error.

Background Process Notifications

When the agent running a background session uses terminal(background=true) to start long-running processes (servers, builds, etc.), the gateway can push status updates to your chat. Control this with display.background_process_notifications in ~/.hermes/config.yaml:

Mode	What you receive
`all`	Running-output updates and the final completion message (default)
`result`	Only the final completion message (regardless of exit code)
`error`	Only the final message when the exit code is non-zero
`off`	No process watcher messages at all

display:
  background_process_notifications: all    # all | result | error | off

HERMES_BACKGROUND_NOTIFICATIONS=result

Use Cases

:::tip Background tasks on messaging platforms are fire-and-forget — you don't need to wait or check on them. Results arrive in the same chat automatically when the task finishes. :::

주요 항목:

Server monitoring — "/background Check the health of all services and alert me if anything is down"
Long builds — "/background Build and deploy the staging environment" while you continue chatting
Research tasks — "/background Research competitor pricing and summarize in a table"
File operations — "/background Organize the photos in ~/Downloads by date into folders"

Service Management

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

Linux (systemd)


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

### Enable lingering (keeps running after logout)

sudo loginctl enable-linger $USER

### Or install a boot-time system service that still runs as your user

sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f bash hermes gateway install # user service sudo loginctl enable-linger $USER # one-time: start at boot, survive logout

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

```text
Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger.

:::danger Don't add a custom `ExecStopPost` kill drop-in
The unit Hermes installs already shuts the gateway down cleanly with `KillMode=mixed` + `KillSignal=SIGTERM`, and uses `Restart=always` with `RestartForceExitStatus` so updates and `/restart` respawn correctly. Do **not** add a systemd drop-in such as `ExecStopPost=/bin/kill -9 $MAINPID` — `ExecStopPost` fires on *every* stop, including clean restarts, so it `SIGKILL`s the freshly spawned instance before it stabilizes and `Restart=always` immediately respawns it. The result is an infinite restart loop (and, on Telegram, a flood of restart messages). If you've added such a drop-in, remove it: `systemctl --user edit hermes-gateway` (or `sudo systemctl edit hermes-gateway` for a system service) and delete the `ExecStopPost` line, then `systemctl --user daemon-reload`.
:::

:::tip Headless VMs: user service + linger avoids root prompts
A system service needs root for every restart — including the automatic gateway restart at the end of `hermes update`. When `hermes update` runs as a non-root user, it tries passwordless `sudo systemctl`; if that's unavailable, it skips the restart and prints the manual `sudo systemctl restart hermes-gateway` command (it never blocks on an interactive password prompt).

For a headless VM you never log into, a **user** service with lingering enabled gives you the same start-at-boot behavior with zero root involvement:

After that, `hermes update` can restart the gateway without any privileges. If you prefer to keep the system service, either run updates with `sudo hermes update`, or grant the service account passwordless sudo for systemctl, e.g. in `sudo visudo -f /etc/sudoers.d/hermes-gateway`:

macOS (launchd)

The generated plist lives at ~/Library/LaunchAgents/ai.hermes.gateway.plist. It includes three environment variables:

주요 항목:

PATH — your full shell PATH at install time, with the venv bin/ and node_modules/.bin prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge.
VIRTUAL_ENV — points to the Python virtualenv so tools can resolve packages correctly.
HERMES_HOME — scopes the gateway to your Hermes installation.

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

Platform-Specific Toolsets

Platform	Toolset	Capabilities
CLI	`hermes-cli`	Full access
Telegram	`hermes-telegram`	Full tools including terminal
Discord	`hermes-discord`	Full tools including terminal
WhatsApp	`hermes-whatsapp`	Full tools including terminal
WhatsApp Cloud API	`hermes-whatsapp`	Full tools including terminal (shares toolset with the Baileys bridge)
Slack	`hermes-slack`	Full tools including terminal
Google Chat	`hermes-google_chat`	Full tools including terminal
Signal	`hermes-signal`	Full tools including terminal
SMS	`hermes-sms`	Full tools including terminal
Email	`hermes-email`	Full tools including terminal
Home Assistant	`hermes-homeassistant`	Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services)
Mattermost	`hermes-mattermost`	Full tools including terminal
Matrix	`hermes-matrix`	Full tools including terminal
DingTalk	`hermes-dingtalk`	Full tools including terminal
Feishu/Lark	`hermes-feishu`	Full tools including terminal
WeCom	`hermes-wecom`	Full tools including terminal
WeCom Callback	`hermes-wecom-callback`	Full tools including terminal
Weixin	`hermes-weixin`	Full tools including terminal
BlueBubbles	`hermes-bluebubbles`	Full tools including terminal
QQBot	`hermes-qqbot`	Full tools including terminal
Yuanbao	`hermes-yuanbao`	Full tools including terminal
Microsoft Teams	`hermes-teams`	Full tools including terminal
API Server	`hermes-api-server`	Full tools (drops `clarify`, `text_to_speech` — programmatic access doesn't have an interactive user)
Webhooks	`hermes-webhook`	Full tools including terminal
Raft	`hermes-raft`	Wake-only channel; agent uses Raft CLI for message I/O

Operating a multi-platform gateway

A gateway typically runs several adapters at once (Telegram + Discord + Slack, etc.). The sections below cover day-2 operations that span all platforms.

/platform command

Once the gateway is running, use the /platform slash command from any connected CLI session or chat to inspect and steer individual adapters without restarting the whole gateway:

/platform list                  # show all adapters and their state
/platform pause <name>          # stop dispatching new messages to one adapter
/platform resume <name>         # re-enable a paused adapter

Automatic circuit breaker

Each adapter is wrapped in a circuit breaker. Repeated retryable failures (network blips, rate-limit replies, 5xx upstream responses, websocket disconnects) cause the breaker to trip — the adapter is auto-paused, an operator notification is sent to the home channel of another live platform when one is configured, and a structured log line is emitted.

Where to look when a platform is paused

Gateway log (~/.hermes/logs/gateway.log or the systemd / launchd unit log). Search for the platform name and circuit breaker, paused, or disabled. The trip event includes the failure count and the last error. 2. /platform list output — shows the current state and last reason. 3. The provider's status page (Telegram bot API status, Discord status, etc.). The breaker tripped because the platform was unhealthy; don't try to resume until it's back.

Restart notifications

When the gateway restarts (or is shut down with in-flight sessions), it can send a one-shot "the agent is back" / "the agent was interrupted" message to each platform's home channel. This is controlled per-platform by the gateway_restart_notification flag in gateway-config.yaml, which defaults to true:

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # opt out for this platform
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification omitted → defaults to true

Typing indicators

While the agent is processing a message, the gateway shows a live typing status on platforms that support it — a "typing…" bubble on Telegram/Discord/Signal, or the "is thinking…" assistant status on Slack. This is controlled per-platform by the typing_indicator flag in gateway-config.yaml, which defaults to true:

gateway:
  platforms:
    slack:
      typing_indicator: false   # don't show "is thinking…" on Slack
    telegram:
      # typing_indicator omitted → defaults to true

Session resume across gateway restarts

When the gateway shuts down with an in-flight tool call or generation, the affected sessions are flagged as restart_interrupted. On the next startup, the gateway schedules an auto-resume for each one — the user gets a short heads-up in the chat ("Send any message after restart and I'll try to resume where you left off.") and the session picks up from the last committed turn when they reply.

Scheduled auto-resume for N restart-interrupted session(s)

Mobile-friendly progress defaults

Telegram is usually a mobile inbox, so the defaults are tuned for that surface:

주요 항목:

tool_progress defaults to off — no per-tool breadcrumb stream filling up the chat.
busy_ack_detail defaults to off — busy-state acknowledgments and long-running heartbeats stay terse (no iteration 21/60 debug detail).
interim_assistant_messages stays on — real mid-turn assistant commentary (the model literally telling you what it's about to do) is signal, not noise.
long_running_notifications stays on — a single edit-in-place "⏳ Working — N min" bubble updates every few minutes so you have a heartbeat instead of staring at typing… for half an hour.

display:
  platforms:
    telegram:
      # Re-enable the tool-progress stream
      tool_progress: new
      # Show "iteration N/M, running: tool" in heartbeats and busy acks
      busy_ack_detail: true
      # Or quiet them entirely
      interim_assistant_messages: false
      long_running_notifications: false

Progress bubble cleanup (opt-in)

Tool-progress messages, the "still working…" heartbeat, and status-callback bubbles can also be auto-deleted after the final response lands. Enable per-platform via display.platforms..cleanup_progress:

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

다음 단계

주요 항목:

Telegram Setup
Discord Setup
Slack Setup
Google Chat Setup
WhatsApp Setup
WhatsApp Business Cloud API Setup
Signal Setup
SMS Setup (Twilio)
Email Setup
Home Assistant Integration
Mattermost Setup
Matrix Setup
DingTalk Setup
Feishu/Lark Setup
WeCom Setup
WeCom Callback Setup
Weixin Setup (WeChat)
BlueBubbles Setup (iMessage)
QQBot Setup
Yuanbao Setup
Microsoft Teams Setup
Teams Meetings Pipeline
Open WebUI + API Server
Raft Setup
IRC Setup
Webhooks

실습 체크리스트

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

자주 쓰는 명령·설정 예시

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

hermes gateway setup        # Interactive setup for all messaging platforms

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Regenerate the service unit after changing this setting:

A positive value makes the generated unit use `Type=notify`,
`NotifyAccess=main`, and the matching `WatchdogSec`. Hermes sends heartbeats
only while its event loop is making timely progress; systemd restarts the
process when they stop. The default `0` keeps the existing `Type=simple`
behavior. This setting is Linux/systemd-only and does not treat an ordinary
platform network disconnect as an event-loop failure.

## Chat Commands (Inside Messaging)

| Command | Description |
|---------|-------------|
| `/new` or `/reset` | Start a fresh conversation |
| `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) |
| `/personality [name]` | Set a personality |
| `/retry` | Retry the last message |
| `/undo` | Remove the last exchange |
| `/status` | Show session info |
| `/whoami` | Show your slash command access on this scope (admin / user / unrestricted) |
| `/stop` | Stop the running agent |
| `/approve` | Approve a pending dangerous command |
| `/deny` | Reject a pending dangerous command |
| `/sethome` | Set this chat as the home channel |
| `/compress` | Manually compress conversation context |
| `/title [name]` | Set or show the session title |
| `/resume [name]` | Resume a previously named session |
| `/usage` | Show token usage for this session (`/usage reset [--force]` redeems a banked Codex limit reset) |
| `/insights [days]` | Show usage insights and analytics |
| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display |
| `/voice [on\|off\|tts\|join\|leave\|status]` | Control messaging voice replies and Discord voice-channel behavior |
| `/rollback [number]` | List or restore filesystem checkpoints |
| `/background <prompt>` | Run a prompt in a separate background session |
| `/reload-mcp` | Reload MCP servers from config |
| `/update` | Update Hermes Agent to the latest version |
| `/help` | Show available commands |
| `/<skill-name>` | Invoke any installed skill |

## Session Management

### Session Persistence

Sessions persist across messages until they reset. The agent remembers your conversation context.

### Delivery Reliability

Final agent responses are recorded in a durable **delivery ledger**
(`state.db`) around each platform send. If the gateway crashes or restarts
between producing a response and the platform confirming receipt, the next
boot redelivers the stored response instead of losing it — or re-running the
whole turn.

Semantics are honest at-least-once:

- A response whose send **never started** is redelivered as-is.
- A response that was **mid-send** when the gateway died (the platform may or
  may not have received it) is redelivered with a visible
  "♻️ Recovered reply — … may be a duplicate" prefix. Ambiguity is labeled,
  never silently resent.
- Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is
  abandoned. Delivered rows are pruned after 7 days.

Disable with `gateway.delivery_ledger: false` in `config.yaml` (restores the
old behavior: in-flight responses are lost on crash).

### Reset Policies

**By default sessions never auto-reset** — context lives until you `/reset`
manually or context compression kicks in. If you want automatic resets, opt in
with the `session_reset` section in `~/.hermes/config.yaml`:

| Mode | Description |
|------|-------------|
| `none` | Never auto-reset (default) |
| `daily` | Reset at a specific hour each day |
| `idle` | Reset after N minutes of inactivity |
| `both` | Whichever triggers first |

A live background process (started with `terminal(background=true)`) normally
protects its session from resetting so output isn't lost. To stop a forgotten
process — say a preview server — from pinning a session open forever, a
background process older than `bg_process_max_age_hours` (default **24**) no
longer blocks reset. The process is **not** killed, only ignored by the reset
guard. Set it to `0` to disable the cutoff (any live process blocks reset, the
old behavior), or raise it if you run legitimate multi-day jobs whose liveness
should keep the conversation open.

Configure per-platform overrides in `~/.hermes/gateway.json`:

## Security

**By default, the gateway denies all users who are not in an allowlist or paired via DM.** This is the safe default for a bot with terminal access.

Messaging Gateway

핵심 요약

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

문서 구성

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

Messaging Gateway
Platform Comparison
아키텍처
Intentional Silence Tokens
Quick Setup
Gateway Commands
Optional Linux event-loop watchdog
Chat Commands (Inside Messaging)
Session Management
Session Persistence
Delivery Reliability
Reset Policies
보안
Restrict to specific users (recommended):
Or allow
Or explicitly allow all users (NOT recommended for bots with terminal access):
DM Pairing (Alternative to Allowlists)
The user sees: "Pairing code: XKGH5N7P"
You approve them with:
Other pairing commands:
Admins vs Regular Users
Redirecting the Agent
Queue vs interrupt vs steer (busy-input mode)
Tool Progress Notifications
Message timestamps in model context
Background Sessions
동작 방식
Background Process Notifications
Use Cases
Service Management
Linux (systemd)
Enable lingering (keeps running after logout)
Or install a boot-time system service that still runs as your user
macOS (launchd)
Platform-Specific Toolsets
Operating a multi-platform gateway
/platform command
Automatic circuit breaker
Where to look when a platform is paused
Restart notifications

상세 내용

Messaging Gateway

Platform Comparison

Platform	Voice	Images	Files	Threads	Reactions	Typing	Streaming
Telegram	✅	✅	✅	✅	—	✅	✅
Discord	✅	✅	✅	✅	✅	✅	✅
Slack	✅	✅	✅	✅	✅	✅	✅
Google Chat	—	✅	✅	✅	—	✅	—
WhatsApp	—	✅	✅	—	—	✅	✅
Signal	—	✅	✅	—	—	✅	✅
SMS	—	—	—	—	—	—	—
Email	—	✅	✅	✅	—	—	—
Home Assistant	—	—	—	—	—	—	—
Mattermost	✅	✅	✅	✅	—	✅	✅
Matrix	✅	✅	✅	✅	✅	✅	✅
DingTalk	—	✅	✅	—	✅	—	✅
Feishu/Lark	✅	✅	✅	✅	✅	✅	✅
WeCom	✅	✅	✅	—	—	—	—
WeCom Callback	—	—	—	—	—	—	—
Weixin	✅	✅	✅	—	—	✅	✅
BlueBubbles	—	✅	✅	—	✅	✅	—
QQ	✅	✅	✅	—	—	✅	—
Yuanbao	✅	✅	✅	—	—	✅	✅
Microsoft Teams	—	✅	—	✅	—	✅	—
LINE	—	✅	✅	—	—	✅	—
ntfy	—	—	—	—	—	—	—
Raft	—	—	—	—	—	—	—
IRC	—	—	—	—	—	—	—

아키텍처

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

Intentional Silence Tokens

주요 항목:

[SILENT]
SILENT
NO_REPLY
NO REPLY

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

Quick Setup

The easiest way to configure messaging platforms is the interactive wizard:

hermes gateway setup        # Interactive setup for all messaging platforms

Gateway Commands

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Optional Linux event-loop watchdog

Regenerate the service unit after changing this setting:

Chat Commands (Inside Messaging)

Command	Description
`/new` or `/reset`	Start a fresh conversation
`/model [provider:model]`	Show or change the model (supports `provider:model` syntax)
`/personality [name]`	Set a personality
`/retry`	Retry the last message
`/undo`	Remove the last exchange
`/status`	Show session info
`/whoami`	Show your slash command access on this scope (admin / user / unrestricted)
`/stop`	Stop the running agent
`/approve`	Approve a pending dangerous command
`/deny`	Reject a pending dangerous command
`/sethome`	Set this chat as the home channel
`/compress`	Manually compress conversation context
`/title [name]`	Set or show the session title
`/resume [name]`	Resume a previously named session
`/usage`	Show token usage for this session (`/usage reset [--force]` redeems a banked Codex limit reset)
`/insights [days]`	Show usage insights and analytics
`/reasoning [level\|show\|hide]`	Change reasoning effort or toggle reasoning display
`/voice [on\|off\|tts\|join\|leave\|status]`	Control messaging voice replies and Discord voice-channel behavior
`/rollback [number]`	List or restore filesystem checkpoints
`/background <prompt>`	Run a prompt in a separate background session
`/reload-mcp`	Reload MCP servers from config
`/update`	Update Hermes Agent to the latest version
`/help`	Show available commands
`/<skill-name>`	Invoke any installed skill

Session Management

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

Session Persistence

Sessions persist across messages until they reset. The agent remembers your conversation context.

Delivery Reliability

주요 항목:

A response whose send never started is redelivered as-is.
A response that was mid-send when the gateway died (the platform may or
Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is

Reset Policies

manually or context compression kicks in. If you want automatic resets, opt in with the session_reset section in ~/.hermes/config.yaml:

Mode	Description
`none`	Never auto-reset (default)
`daily`	Reset at a specific hour each day
`idle`	Reset after N minutes of inactivity
`both`	Whichever triggers first

session_reset:
  mode: idle        # "idle", "daily", "both", or "none" (default)
  idle_minutes: 1440  # for idle/both: minutes of inactivity before reset
  at_hour: 4          # for daily/both: hour of day (0-23, local time)

{
  "reset_by_platform": {
    "telegram": { "mode": "idle", "idle_minutes": 240 },
    "discord": { "mode": "idle", "idle_minutes": 60 }
  }
}

보안

By default, the gateway denies all users who are not in an allowlist or paired via DM. This is the safe default for a bot with terminal access.


### Restrict to specific users (recommended):

TELEGRAM_ALLOWED_USERS=123456789,987654321 DISCORD_ALLOWED_USERS=123456789012345678 SIGNAL_ALLOWED_USERS=+155****4567,+155****6543 SMS_ALLOWED_USERS=+155****4567,+155****6543 EMAIL_ALLOWED_USERS=trusted@example.com,colleague@work.com MATTERMOST_ALLOWED_USERS=3uo8dkh1p7g1mfk49ear5fzs5c MATRIX_ALLOWED_USERS=@alice:matrix.org DINGTALK_ALLOWED_USERS=user-id-1 FEISHU_ALLOWED_USERS=ou_xxxxxxxx,ou_yyyyyyyy WECOM_ALLOWED_USERS=user-id-1,user-id-2 WECOM_CALLBACK_ALLOWED_USERS=user-id-1,user-id-2 TEAMS_ALLOWED_USERS=aad-object-id-1,aad-object-id-2

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

### Or allow

GATEWAY_ALLOWED_USERS=123456789,987654321

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

### Or explicitly allow all users (NOT recommended for bots with terminal access):

GATEWAY_ALLOW_ALL_USERS=true

DM Pairing (Alternative to Allowlists)

The user sees: "Pairing code: XKGH5N7P"

이 섹션의 세부 항목은 공식 문서 The user sees: "Pairing code: XKGH5N7P"를 참고하세요.

You approve them with:

hermes pairing approve telegram XKGH5N7P

Other pairing commands:

hermes pairing list # View pending + approved users hermes pairing revoke telegram 123456789 # Remove access ```

Admins vs Regular Users

Allowlists answer "can this person reach the bot at all?" The admin / user split answers "now that they're in, what are they allowed to do?"

주요 항목:

Admin — full access. Can run every registered slash command (built-in + plugin) and use every gated capability.
Regular user — restricted access. Can chat with the agent normally, but can only run the slash commands you explicitly enable. The always-allowed floor is /help and /whoami.

gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]                    # admins → all slash commands
        user_allowed_commands: [status, model]       # what non-admins may run
        # Optional: separate group/channel scope
        group_allow_admin_from: ["111"]
        group_user_allowed_commands: [status]

Redirecting the Agent

Send a message while the agent is working to correct the active turn:

주요 항목:

Model generation restarts with context — reasoning already shown and visible partial text are retained as an ordinary assistant checkpoint
Completed work stays available — prior tool calls and results remain in the turn
Running tools finish safely — the correction is applied at the next tool-result boundary instead of killing the tool
/stop remains a hard stop — use it to cancel the active turn and foreground work

Queue vs interrupt vs steer (busy-input mode)

By default, messaging a busy agent redirects its active turn. Two other modes are available:

주요 항목:

queue — follow-up messages wait and run as the next turn after the current task finishes.
steer — follow-up messages are injected into the current run via /steer, arriving at the agent after the next tool call. No interrupt, no new turn. Falls back to queue behavior if the agent hasn't started yet.

display:
  busy_input_mode: steer   # or queue, or interrupt (default)
  busy_ack_enabled: true   # set to false to suppress the ⚡/⏳/⏩ chat reply entirely

Tool Progress Notifications

Control how much tool activity is displayed in ~/.hermes/config.yaml:

display:
  tool_progress: all    # off | new | all | verbose
  tool_progress_command: false  # set to true to enable /verbose in messaging
  # How progress is grouped on platforms that support message editing:
  #   accumulate (default) — edit one bubble in place as tools run
  #   separate             — send one message per tool (pre-v0.9 style; noisier)
  # Only applies where tool_progress is already enabled.
  tool_progress_grouping: accumulate   # accumulate | separate

Message timestamps in model context

gateway:
  message_timestamps:
    enabled: false   # set true to show send-times to the model

💻 `ls -la`...
🔍 web_search...
📄 web_extract...
🐍 execute_code...

Background Sessions

Run a prompt in a separate background session so the agent works on it independently while your main chat stays responsive:

/background Check all servers in the cluster and report any that are down

🔄 Background task started: "Check all servers in the cluster..."
   Task ID: bg_143022_a1b2c3

동작 방식

Each /background prompt spawns a separate agent instance that runs asynchronously:

주요 항목:

Isolated session — the background agent has its own session with its own conversation history. It has no knowledge of your current chat context and receives only the prompt you provide.
Same configuration — inherits your model, provider, toolsets, reasoning settings, and provider routing from the current gateway setup.
Non-blocking — your main chat stays fully interactive. Send messages, run other commands, or start more background tasks while it works.
Result delivery — when the task finishes, the result is sent back to the same chat or channel where you issued the command, prefixed with "✅ Background task complete". If it fails, you'll see "❌ Background task failed" with the error.

Background Process Notifications

Mode	What you receive
`all`	Running-output updates and the final completion message (default)
`result`	Only the final completion message (regardless of exit code)
`error`	Only the final message when the exit code is non-zero
`off`	No process watcher messages at all

display:
  background_process_notifications: all    # all | result | error | off

HERMES_BACKGROUND_NOTIFICATIONS=result

Use Cases

:::tip Background tasks on messaging platforms are fire-and-forget — you don't need to wait or check on them. Results arrive in the same chat automatically when the task finishes. :::

주요 항목:

Server monitoring — "/background Check the health of all services and alert me if anything is down"
Long builds — "/background Build and deploy the staging environment" while you continue chatting
Research tasks — "/background Research competitor pricing and summarize in a table"
File operations — "/background Organize the photos in ~/Downloads by date into folders"

Service Management

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

Linux (systemd)


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

### Enable lingering (keeps running after logout)

sudo loginctl enable-linger $USER

### Or install a boot-time system service that still runs as your user

sudo hermes gateway install --system sudo hermes gateway start --system sudo hermes gateway status --system journalctl -u hermes-gateway -f bash hermes gateway install # user service sudo loginctl enable-linger $USER # one-time: start at boot, survive logout

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

```text
Use the user service on laptops and dev boxes. Use the system service on VPS or headless hosts that should come back at boot without relying on systemd linger.

:::danger Don't add a custom `ExecStopPost` kill drop-in
The unit Hermes installs already shuts the gateway down cleanly with `KillMode=mixed` + `KillSignal=SIGTERM`, and uses `Restart=always` with `RestartForceExitStatus` so updates and `/restart` respawn correctly. Do **not** add a systemd drop-in such as `ExecStopPost=/bin/kill -9 $MAINPID` — `ExecStopPost` fires on *every* stop, including clean restarts, so it `SIGKILL`s the freshly spawned instance before it stabilizes and `Restart=always` immediately respawns it. The result is an infinite restart loop (and, on Telegram, a flood of restart messages). If you've added such a drop-in, remove it: `systemctl --user edit hermes-gateway` (or `sudo systemctl edit hermes-gateway` for a system service) and delete the `ExecStopPost` line, then `systemctl --user daemon-reload`.
:::

:::tip Headless VMs: user service + linger avoids root prompts
A system service needs root for every restart — including the automatic gateway restart at the end of `hermes update`. When `hermes update` runs as a non-root user, it tries passwordless `sudo systemctl`; if that's unavailable, it skips the restart and prints the manual `sudo systemctl restart hermes-gateway` command (it never blocks on an interactive password prompt).

For a headless VM you never log into, a **user** service with lingering enabled gives you the same start-at-boot behavior with zero root involvement:

After that, `hermes update` can restart the gateway without any privileges. If you prefer to keep the system service, either run updates with `sudo hermes update`, or grant the service account passwordless sudo for systemctl, e.g. in `sudo visudo -f /etc/sudoers.d/hermes-gateway`:

macOS (launchd)

The generated plist lives at ~/Library/LaunchAgents/ai.hermes.gateway.plist. It includes three environment variables:

주요 항목:

PATH — your full shell PATH at install time, with the venv bin/ and node_modules/.bin prepended. This ensures user-installed tools (Node.js, ffmpeg, etc.) are available to gateway subprocesses like the WhatsApp bridge.
VIRTUAL_ENV — points to the Python virtualenv so tools can resolve packages correctly.
HERMES_HOME — scopes the gateway to your Hermes installation.

hermes gateway install               # Install as launchd agent
hermes gateway start                 # Start the service
hermes gateway stop                  # Stop the service
hermes gateway status                # Check status
tail -f ~/.hermes/logs/gateway.log   # View logs

Platform-Specific Toolsets

Platform	Toolset	Capabilities
CLI	`hermes-cli`	Full access
Telegram	`hermes-telegram`	Full tools including terminal
Discord	`hermes-discord`	Full tools including terminal
WhatsApp	`hermes-whatsapp`	Full tools including terminal
WhatsApp Cloud API	`hermes-whatsapp`	Full tools including terminal (shares toolset with the Baileys bridge)
Slack	`hermes-slack`	Full tools including terminal
Google Chat	`hermes-google_chat`	Full tools including terminal
Signal	`hermes-signal`	Full tools including terminal
SMS	`hermes-sms`	Full tools including terminal
Email	`hermes-email`	Full tools including terminal
Home Assistant	`hermes-homeassistant`	Full tools + HA device control (ha_list_entities, ha_get_state, ha_call_service, ha_list_services)
Mattermost	`hermes-mattermost`	Full tools including terminal
Matrix	`hermes-matrix`	Full tools including terminal
DingTalk	`hermes-dingtalk`	Full tools including terminal
Feishu/Lark	`hermes-feishu`	Full tools including terminal
WeCom	`hermes-wecom`	Full tools including terminal
WeCom Callback	`hermes-wecom-callback`	Full tools including terminal
Weixin	`hermes-weixin`	Full tools including terminal
BlueBubbles	`hermes-bluebubbles`	Full tools including terminal
QQBot	`hermes-qqbot`	Full tools including terminal
Yuanbao	`hermes-yuanbao`	Full tools including terminal
Microsoft Teams	`hermes-teams`	Full tools including terminal
API Server	`hermes-api-server`	Full tools (drops `clarify`, `text_to_speech` — programmatic access doesn't have an interactive user)
Webhooks	`hermes-webhook`	Full tools including terminal
Raft	`hermes-raft`	Wake-only channel; agent uses Raft CLI for message I/O

Operating a multi-platform gateway

A gateway typically runs several adapters at once (Telegram + Discord + Slack, etc.). The sections below cover day-2 operations that span all platforms.

/platform command

Once the gateway is running, use the /platform slash command from any connected CLI session or chat to inspect and steer individual adapters without restarting the whole gateway:

/platform list                  # show all adapters and their state
/platform pause <name>          # stop dispatching new messages to one adapter
/platform resume <name>         # re-enable a paused adapter

Automatic circuit breaker

Where to look when a platform is paused

Gateway log (~/.hermes/logs/gateway.log or the systemd / launchd unit log). Search for the platform name and circuit breaker, paused, or disabled. The trip event includes the failure count and the last error. 2. /platform list output — shows the current state and last reason. 3. The provider's status page (Telegram bot API status, Discord status, etc.). The breaker tripped because the platform was unhealthy; don't try to resume until it's back.

Restart notifications

gateway:
  platforms:
    telegram:
      home_chat_id: "123456789"
      gateway_restart_notification: false   # opt out for this platform
    discord:
      home_chat_id: "987654321"
      # gateway_restart_notification omitted → defaults to true

Typing indicators

gateway:
  platforms:
    slack:
      typing_indicator: false   # don't show "is thinking…" on Slack
    telegram:
      # typing_indicator omitted → defaults to true

Session resume across gateway restarts

Scheduled auto-resume for N restart-interrupted session(s)

Mobile-friendly progress defaults

Telegram is usually a mobile inbox, so the defaults are tuned for that surface:

주요 항목:

tool_progress defaults to off — no per-tool breadcrumb stream filling up the chat.
busy_ack_detail defaults to off — busy-state acknowledgments and long-running heartbeats stay terse (no iteration 21/60 debug detail).
interim_assistant_messages stays on — real mid-turn assistant commentary (the model literally telling you what it's about to do) is signal, not noise.
long_running_notifications stays on — a single edit-in-place "⏳ Working — N min" bubble updates every few minutes so you have a heartbeat instead of staring at typing… for half an hour.

display:
  platforms:
    telegram:
      # Re-enable the tool-progress stream
      tool_progress: new
      # Show "iteration N/M, running: tool" in heartbeats and busy acks
      busy_ack_detail: true
      # Or quiet them entirely
      interim_assistant_messages: false
      long_running_notifications: false

Progress bubble cleanup (opt-in)

display:
  platforms:
    telegram:
      cleanup_progress: true
    discord:
      cleanup_progress: true

다음 단계

주요 항목:

Telegram Setup
Discord Setup
Slack Setup
Google Chat Setup
WhatsApp Setup
WhatsApp Business Cloud API Setup
Signal Setup
SMS Setup (Twilio)
Email Setup
Home Assistant Integration
Mattermost Setup
Matrix Setup
DingTalk Setup
Feishu/Lark Setup
WeCom Setup
WeCom Callback Setup
Weixin Setup (WeChat)
BlueBubbles Setup (iMessage)
QQBot Setup
Yuanbao Setup
Microsoft Teams Setup
Teams Meetings Pipeline
Open WebUI + API Server
Raft Setup
IRC Setup
Webhooks

실습 체크리스트

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

자주 쓰는 명령·설정 예시

flowchart TB
    subgraph Gateway["Hermes Gateway"]
        subgraph Adapters["Platform adapters"]
            tg[Telegram]
            dc[Discord]
            wa[WhatsApp]
            sl[Slack]
            gc[Google Chat]
            sig[Signal]
            sms[SMS]
            em[Email]
            ha[Home Assistant]
            mm[Mattermost]
            mx[Matrix]
            dt[DingTalk]
    fs[Feishu/Lark]
    wc[WeCom]
    wcb[WeCom Callback]
    wx[Weixin]
    bb[BlueBubbles]
    qq[QQ]
    yb[Yuanbao]
    ms[Microsoft Teams]
    api["API Server<br/>(OpenAI-compatible)"]
    wh[Webhooks]
        end

        store["Session store<br/>per chat"]
        agent["AIAgent<br/>run_agent.py"]
        cron["Cron scheduler<br/>ticks every 60s"]
    end

    tg --> store
    dc --> store
    wa --> store
    sl --> store
    gc --> store
    sig --> store
    sms --> store
    em --> store
    ha --> store
    mm --> store
    mx --> store
    dt --> store
    fs --> store
    wc --> store
    wcb --> store
    wx --> store
    bb --> store
    qq --> store
    yb --> store
    ms --> store
    api --> store
    wh --> store
    store --> agent
    cron --> store

user: side-channel chatter
assistant: [SILENT]   # stored, not delivered
user: next message

hermes gateway setup        # Interactive setup for all messaging platforms

hermes gateway              # Run in foreground
hermes gateway setup        # Configure messaging platforms interactively
hermes gateway install      # Install as a user service (Linux) / launchd service (macOS)
sudo hermes gateway install --system   # Linux only: install a boot-time system service
hermes gateway start        # Start the default service
hermes gateway stop         # Stop the default service
hermes gateway status       # Check default service status
hermes gateway status --system         # Linux only: inspect the system service explicitly

Regenerate the service unit after changing this setting:

A positive value makes the generated unit use `Type=notify`,
`NotifyAccess=main`, and the matching `WatchdogSec`. Hermes sends heartbeats
only while its event loop is making timely progress; systemd restarts the
process when they stop. The default `0` keeps the existing `Type=simple`
behavior. This setting is Linux/systemd-only and does not treat an ordinary
platform network disconnect as an event-loop failure.

## Chat Commands (Inside Messaging)

| Command | Description |
|---------|-------------|
| `/new` or `/reset` | Start a fresh conversation |
| `/model [provider:model]` | Show or change the model (supports `provider:model` syntax) |
| `/personality [name]` | Set a personality |
| `/retry` | Retry the last message |
| `/undo` | Remove the last exchange |
| `/status` | Show session info |
| `/whoami` | Show your slash command access on this scope (admin / user / unrestricted) |
| `/stop` | Stop the running agent |
| `/approve` | Approve a pending dangerous command |
| `/deny` | Reject a pending dangerous command |
| `/sethome` | Set this chat as the home channel |
| `/compress` | Manually compress conversation context |
| `/title [name]` | Set or show the session title |
| `/resume [name]` | Resume a previously named session |
| `/usage` | Show token usage for this session (`/usage reset [--force]` redeems a banked Codex limit reset) |
| `/insights [days]` | Show usage insights and analytics |
| `/reasoning [level\|show\|hide]` | Change reasoning effort or toggle reasoning display |
| `/voice [on\|off\|tts\|join\|leave\|status]` | Control messaging voice replies and Discord voice-channel behavior |
| `/rollback [number]` | List or restore filesystem checkpoints |
| `/background <prompt>` | Run a prompt in a separate background session |
| `/reload-mcp` | Reload MCP servers from config |
| `/update` | Update Hermes Agent to the latest version |
| `/help` | Show available commands |
| `/<skill-name>` | Invoke any installed skill |

## Session Management

### Session Persistence

Sessions persist across messages until they reset. The agent remembers your conversation context.

### Delivery Reliability

Final agent responses are recorded in a durable **delivery ledger**
(`state.db`) around each platform send. If the gateway crashes or restarts
between producing a response and the platform confirming receipt, the next
boot redelivers the stored response instead of losing it — or re-running the
whole turn.

Semantics are honest at-least-once:

- A response whose send **never started** is redelivered as-is.
- A response that was **mid-send** when the gateway died (the platform may or
  may not have received it) is redelivered with a visible
  "♻️ Recovered reply — … may be a duplicate" prefix. Ambiguity is labeled,
  never silently resent.
- Redelivery is bounded: 3 attempts, 24-hour freshness, then the row is
  abandoned. Delivered rows are pruned after 7 days.

Disable with `gateway.delivery_ledger: false` in `config.yaml` (restores the
old behavior: in-flight responses are lost on crash).

### Reset Policies

**By default sessions never auto-reset** — context lives until you `/reset`
manually or context compression kicks in. If you want automatic resets, opt in
with the `session_reset` section in `~/.hermes/config.yaml`:

| Mode | Description |
|------|-------------|
| `none` | Never auto-reset (default) |
| `daily` | Reset at a specific hour each day |
| `idle` | Reset after N minutes of inactivity |
| `both` | Whichever triggers first |

A live background process (started with `terminal(background=true)`) normally
protects its session from resetting so output isn't lost. To stop a forgotten
process — say a preview server — from pinning a session open forever, a
background process older than `bg_process_max_age_hours` (default **24**) no
longer blocks reset. The process is **not** killed, only ignored by the reset
guard. Set it to `0` to disable the cutoff (any live process blocks reset, the
old behavior), or raise it if you run legitimate multi-day jobs whose liveness
should keep the conversation open.

Configure per-platform overrides in `~/.hermes/gateway.json`:

## Security

**By default, the gateway denies all users who are not in an allowlist or paired via DM.** This is the safe default for a bot with terminal access.

Messaging Gateway

핵심 요약

문서 구성

상세 내용

Messaging Gateway

Platform Comparison

아키텍처

Intentional Silence Tokens

Quick Setup

Gateway Commands

Optional Linux event-loop watchdog

Chat Commands (Inside Messaging)

Session Management

Session Persistence

Delivery Reliability

Reset Policies

보안

DM Pairing (Alternative to Allowlists)

The user sees: "Pairing code: XKGH5N7P"

You approve them with:

Other pairing commands:

Admins vs Regular Users

Redirecting the Agent

Queue vs interrupt vs steer (busy-input mode)

Tool Progress Notifications

Message timestamps in model context

Background Sessions

동작 방식

Background Process Notifications

Use Cases

Service Management

Linux (systemd)

macOS (launchd)

Platform-Specific Toolsets

Operating a multi-platform gateway

/platform command

Automatic circuit breaker

Where to look when a platform is paused

Restart notifications

Typing indicators

Session resume across gateway restarts

Mobile-friendly progress defaults

Progress bubble cleanup (opt-in)

다음 단계

실습 체크리스트

자주 쓰는 명령·설정 예시

관련 링크

관련 가이드

Messaging Gateway

핵심 요약

문서 구성

상세 내용

Messaging Gateway

Platform Comparison

아키텍처

Intentional Silence Tokens

Quick Setup

Gateway Commands

Optional Linux event-loop watchdog

Chat Commands (Inside Messaging)

Session Management

Session Persistence

Delivery Reliability

Reset Policies

보안

DM Pairing (Alternative to Allowlists)

The user sees: "Pairing code: XKGH5N7P"

You approve them with:

Other pairing commands:

Admins vs Regular Users

Redirecting the Agent

Queue vs interrupt vs steer (busy-input mode)

Tool Progress Notifications

Message timestamps in model context

Background Sessions

동작 방식

Background Process Notifications

Use Cases

Service Management

Linux (systemd)