ゲートウェイ — Telegram や Discord から話しかける

これは何か

ゲートウェイ（messaging gateway）は、Telegram・Discord・Slack のようなチャットアプリから Hermes に話しかけられるようにする、単一のバックグラウンドプロセスである。設定した数だけプラットフォームアダプタを同時に立ち上げ、チャットごとのセッション管理・cron ジョブの配信・音声メッセージの送受信までを 1 つのプロセスの中でまとめて面倒を見る。CLI（第 4 章）が「自分のターミナルから 1 対 1 で話す」入り口だとすれば、ゲートウェイは「自分以外の人やデバイスからも届く入り口」を増やす仕組みだと考えるとよい。

触る場所は 4 つに整理できる。

• CLI サブコマンド — hermes gateway 系（起動・停止・状態確認・常駐サービス化）
• チャット内のスラッシュコマンド — /whoami や /model など、接続後にチャットの中から打つコマンド
• ~/.hermes/config.yaml の設定キー — プラットフォームごとの許可リスト・権限分離・チャンネルオーバーライドなど、秘密でない設定はここに書く（第 2 章で見た「秘密は .env、それ以外は config.yaml」という区分がここでもそのまま当てはまる）
• ~/.hermes/ 配下のファイル — ボットトークンを置く .env、稼働ログ logs/gateway.log、配信の記録が残る state.db

対応プラットフォームは公式ドキュメントの Platform Comparison 表に一覧がある。voice（音声）・images（画像）・files（ファイル）・threads（スレッド）・reactions（リアクション）・typing（入力中表示）・streaming（応答の逐次更新）の 7 機能について、プラットフォームごとの対応可否がまとめられている。代表的な行を抜粋する。

この表は全部で 28 行あり、WhatsApp（通常版と WhatsApp Cloud API 版で 2 行）・WeCom（通常版と WeCom Callback 版で 2 行）のように同じサービスが接続方式違いで 2 行になっている箇所があるため、実質のサービス数は 26 になる。第 2 章で触れた「アダプタは 25 種類以上」はこの内訳を指している。実装上も 2 系統に分かれており、gateway/platforms/ に置かれた組み込みアダプタ（Signal・Weixin・BlueBubbles・QQBot・WhatsApp Cloud API・Yuanbao・Webhook・API Server など）と、plugins/platforms/ に置かれたプラグイン型プラットフォーム（Telegram・Discord・Slack・WhatsApp・Matrix・Mattermost・Email・SMS など大半のプラットフォーム）に分かれる。使う側から見た挙動の違いはないので、この区別は「コードのどこを読めばよいか」を知りたいとき以外は意識しなくてよい。

いつ使うのか

典型的な使いどころは次の 4 つである。

• 自宅サーバーや VPS で動かしている Hermes に、外出先からスマホの Telegram や Discord アプリ経由で話しかけたい
• チームやグループチャットで、複数人が同じエージェントに Slack・Discord のチャンネル越しにアクセスしたい（権限分離で「誰が何をできるか」を制御する）
• Home Assistant・Microsoft Teams・DingTalk・Feishu/Lark・WeCom のような、すでに使っている業務ツールやスマートホームの入り口に Hermes を統合したい
• cron ジョブ（第 8 章）の実行結果や、バックグラウンドセッション（第 4 章の /bg）の完了通知を、自分の使い慣れたチャットアプリへ配信したい

Hermes に外から話しかける経路はゲートウェイだけではない。似た入り口との使い分けは次のとおり。

API Server は clarify（選択肢を提示して待つツール）や音声合成のような「対話中の人間」を前提にしたツールを外し、それ以外のフル機能を提供する専用のツールセットで動く。プログラム的な呼び出しには受け手がいないため、この違いを意識しておくと動作の差に戸惑わない。

アーキテクチャ — 単一プロセスに集約する

ゲートウェイの核心は「1 つのプロセスが全部を面倒見る」という設計にある。設定したプラットフォームの数だけアダプタが起動するが、それぞれが独立したサービスとして動くわけではない。全アダプタはチャットごとのセッションストアを共有し、そこから run_agent.py が実装する AIAgent に処理を渡す。cron スケジューラも同じプロセス内で 60 秒ごとにティックし、期限が来たジョブを同じセッションストア経由で実行する。

この設計のいちばんの利点は、プラットフォームを何個増やしてもエージェントの人格・メモリ・スキルが分裂しないことである。Telegram で話した内容を Discord から参照することはできない（セッションはチャットごとに分かれる）が、どちらから話しかけても同じ SOUL.md・同じ永続メモリ（第 5 章）を持つ同一のエージェントが応答する。

トークンの取得と許可リスト

ここから先は、初心者が最初に触ることになる Telegram を代表例にして、接続の最短経路を追う。他のプラットフォームも手順の骨格は同じで、「発行元の管理ツールでボットを作りトークンをもらう」→「hermes gateway setup か .env に登録する」→「許可リストか DM ペアリングでアクセスできる人を絞る」の 3 段階を踏む。

トークンの取得は Telegram の公式ボット管理ツール「@BotFather」に /newbot を送るだけである。表示名とユーザー名（bot で終わる必要がある）を決めると、123456789:ABCdefGHIjklMNOpqrSTUvwxYZ のような API トークンが返る。このトークンを持つ人は誰でもボットを操作できるため、漏れたら BotFather で /revoke して即座に無効化する。

取得したトークンは hermes gateway setup の対話ウィザードで Telegram を選べば、ボットトークンと許可するユーザー ID を聞かれるままに答えるだけで ~/.hermes/.env に書き込まれる。手動で書く場合も、書き込み先は config.yaml ではなく .env になる点は他の秘密情報と同じである。

# ~/.hermes/.env
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ
TELEGRAM_ALLOWED_USERS=123456789    # カンマ区切りで複数指定可

許可リストの環境変数はプラットフォームごとに名前が決まっている。ユーザー ID や電話番号・メールアドレスなど、プラットフォームが識別子として使う値をそのまま並べる。

TELEGRAM_ALLOWED_USERS=123456789,987654321
DISCORD_ALLOWED_USERS=123456789012345678
SIGNAL_ALLOWED_USERS=+15551234567
EMAIL_ALLOWED_USERS=trusted@example.com
GATEWAY_ALLOWED_USERS=123456789     # 全プラットフォーム横断で許可
GATEWAY_ALLOW_ALL_USERS=true        # 全員許可（非推奨）

既定の挙動は「全員拒否」である。許可リストが 1 つも設定されず GATEWAY_ALLOW_ALL_USERS も指定していない場合、すべてのユーザーからのメッセージが拒否され、起動時のログに警告が出る。ターミナル権限を持つボットにとって安全側に倒した設計であり、「動かない」と感じたらまずここを疑うとよい。

DM ペアリングと権限分離

ユーザー ID を事前に調べて許可リストへ手打ちする代わりに、未知のユーザーが DM を送ると 1 回限りのペアリングコードが発行される仕組みもある（メールだけは例外で、ペアリングを明示的に有効にしない限り未知の送信者は無視される）。コードは 1 時間で失効し、レート制限がかかり、暗号学的乱数で生成される。

# ユーザーには「Pairing code: XKGH5N7P」と表示される
hermes pairing approve telegram XKGH5N7P
hermes pairing list                          # 承認待ち・承認済みを確認
hermes pairing revoke telegram 123456789     # アクセスを取り消す

許可リストと DM ペアリングが答えるのは「そもそも Hermes に届くか」という入り口の可否だけである。届いた後に「何をしてよいか」を分けるのが、管理者（admin）/一般ユーザー（user）の権限分離である。DM とグループ/チャンネルはそれぞれ独立した設定を持ち、DM で管理者でもグループでは一般ユーザーということがあり得る。

# ~/.hermes/config.yaml
gateway:
  platforms:
    discord:
      extra:
        allow_from: ["111", "222", "333"]
        allow_admin_from: ["111"]              # 管理者 → 全スラッシュコマンド
        user_allowed_commands: [status, model] # 一般ユーザーが打てるコマンド

allow_admin_from を設定しなければ階層分けそのものが無効になり、許可された全員が管理者と同じ扱いになる（既存の設定を壊さないための後方互換）。この階層が制御するのはスラッシュコマンドの実行範囲だけで、普通の会話（チャットそのもの）は一般ユーザーでも変わらず行える。

自分がどちらの扱いになっているかは、チャット内で /whoami を打てば確認できる。今の適用スコープと階層（admin / user / unrestricted）、打てるコマンドの一覧がそのまま返ってくる。

チャット内コマンドとチャンネルごとの設定

接続後は、プラットフォームを問わず共通のスラッシュコマンドでエージェントを操作する。代表的なものを挙げる（全コマンドは /help で確認できる）。

複数チャンネルを抱える運用では、チャンネルごとに使うモデルやシステムプロンプトを変えられる。安いモデルの雑談チャンネルと、フロンティアモデル＋専門プロンプトの開発チャンネルを、同じ 1 つのゲートウェイで共存させる設定である。

# ~/.hermes/config.yaml
platforms:
  discord:
    channel_overrides:
      "123456789012345678":     # チャンネル/スレッド ID
        model: anthropic/claude-sonnet-4.6
        system_prompt: "You are the #dev channel code-review specialist."

チャットでの /model による切り替えはこのチャンネル既定より優先され、Discord のスレッドは親チャンネルの設定を自動的に継承する。なお公式ドキュメントはこの設定を指して「gateway-config.yaml」という呼び方もしているが、そういう名前の別ファイルは存在せず、実体は ~/.hermes/config.yaml 1 ファイルである。上の例のようにトップレベルの platforms: として書いても、gateway: キーの下にネストして書いても同じ設定として受理され、両方が指定された場合はトップレベルが優先される。読み込みの優先順位は環境変数が最も高く、次に config.yaml、最後に旧形式の ~/.hermes/gateway.json（レガシー、config.yaml が上書きする）の順である。

サービス化と障害対応

動作確認が終わったら、ターミナルを閉じても動き続けるように常駐サービス化する。Linux では systemd、macOS では launchd のサービスとして登録される。

Linux（systemd）

hermes gateway install               # ユーザーサービスとして登録
hermes gateway start
hermes gateway status
journalctl --user -u hermes-gateway -f       # ログを見る
sudo loginctl enable-linger $USER            # ログアウト後も動かし続ける

ラップトップや開発機にはユーザーサービスで十分だが、ログインしないヘッドレスな VPS では sudo hermes gateway install --system による起動時システムサービスも選べる。ただしシステムサービスは再起動のたびに root 権限が要るため、hermes update が自動再起動できず手動コマンドの案内で止まることがある。ヘッドレス運用ではユーザーサービス＋loginctl enable-lingerの組み合わせのほうが root 操作なしで同じ「起動時に立ち上がる」状態を作れる。

macOS（launchd）

hermes gateway install               # launchd agent として登録
hermes gateway start
hermes gateway status
tail -f ~/.hermes/logs/gateway.log

生成される plist は ~/Library/LaunchAgents/ai.hermes.gateway.plist に置かれ、インストール時点の PATH・Python 仮想環境の場所・HERMES_HOME を環境変数として埋め込む。Homebrew で ffmpeg を入れ直すなど、インストール後にツールを追加した場合は hermes gateway install を再実行して plist を作り直す必要がある。

複数のプラットフォームを同時運用していると、どれか 1 つだけが不調になることがある。各アダプタは循環ブレーカー（circuit breaker）で保護されており、ネットワーク瞬断・レート制限・5xx・WebSocket 切断のような再試行可能な失敗が連続すると自動的にトリップし、そのアダプタだけを一時停止する。自動では復帰しないのが意図的な設計で、障害が続いているプラットフォームに再接続を延々と試み続ける事態を避けている。復旧を確認したら、チャットまたは CLI から次のコマンドで手動再開する。

/platform list             # 稼働中・一時停止中・ブレーカー作動中を一覧表示
/platform resume telegram  # 手動で再開

停止中のアダプタの原因は ~/.hermes/logs/gateway.log（プラットフォーム名と「circuit breaker」「paused」で検索）と /platform list の出力、そしてプラットフォーム側のステータスページの 3 か所で切り分けるのが早い。

hermes gateway setup

hermes gateway

hermes gateway install
hermes gateway start
hermes gateway status

hermes gateway stop
hermes gateway uninstall

つまずきポイント

理解度チェック

まとめ

• ゲートウェイは単一プロセスで複数のプラットフォームアダプタを束ね、セッションストアを介して同じ AIAgent に処理を渡す。公式の Platform Comparison 表は 28 行・実質 26 サービスに及ぶ
• Telegram なら BotFather でのトークン発行 → hermes gateway setup → DM ペアリングまたは許可リストという最短経路で接続できる
• 既定は deny-all。許可リスト環境変数か DM ペアリングで「誰が届くか」を、allow_admin_from / user_allowed_commands で「届いた後に何ができるか」を別々に制御する
• 常駐サービス化は systemd / launchd で行い、循環ブレーカーは障害時に自動停止するが自動復帰はしない設計になっている
• 次の第 8 章では、このゲートウェイに結果を配信する cron スケジューラを扱う

参考リンク

• user-guide/messaging/index.md（ゲートウェイ全体の公式ドキュメント）
• user-guide/messaging/telegram.md（Telegram セットアップの公式ドキュメント）
• reference/cli-commands.md（hermes gateway サブコマンド一覧）
• Hermes Agent 公式ドキュメント