Hermes Agent gateway を Telegram と Slack に接続する setup ガイド

こんにちは、Lena です。正直に言うと、「自分の agent を Telegram につなぐにはどうすればいい？」と聞かれるたびに、私の最初の返事はいつも同じです。あなたの CLI は、もう本当に安定していますか？ この記事は、一般的な bot チュートリアルではなく、実際に Hermes Agent gateway setup を運用しようとしている builder 向けに書いています。中心は Telegram と Slack です。ほかの platform については、必要なところだけ触れます。

Hermes gateway は実際に何をしているのか

CLI と messaging platforms をまたぐ、ひとつの agent

まず概念を整理します。Hermes には2つの入口があります。hermes で起動する terminal UI と、hermes gateway で起動する background process です。gateway は本質的には統一された adapter layer です。設定済みの messaging platforms すべてに同時接続し、すべての message を同じ AIAgent instance にルーティングします。つまり、Telegram から話しかけている agent と、Slack から話しかけている agent は同じ agent であり、同じ session store、memory、skills、cron schedule を共有しています。

official Hermes messaging gateway documentation によると、単一の gateway process で Telegram、Slack、Discord、WhatsApp、Signal、Email、Matrix、Mattermost、そして十数種類のほかの platform を同時に動かせます。それぞれの platform adapter が messages を受け取り、per-chat session store を通してルーティングし、agent に渡します。だから私はいつもこう言います。gateway は fan-out layer であって、別の脳ではありません。

gateway を最初の setup step にしないほうがいい理由

多くの人がつまずくのはここです。Hermes を入れて気分が上がり、そのまま Telegram bot をつなごうとする。そして「message は入っているのに何も返ってこない」理由を3時間 debug することになります。分かります。私もやりました。gateway は上流の3つが正しく設定されていることに依存します。model config、tool config、authorization config です。CLI の時点でどれかが壊れているなら、gateway はその壊れ方をそのまま引き継ぎ、診断を10倍難しくします。なぜなら、あなたが見ているのは情報量の多い terminal log ではなく、Telegram chat だからです。

だから私の経験則は、毎回まったく同じです。CLI が先、gateway はその次。BotFather を開く前に、まずローカルの hermes でクリーンな会話を動かしてください。

platform setup の前に、安定した土台を用意する

local chat、tools、model config を先に検証する

platform token に触れる前に、gateway をホストするマシンで次の checklist を走らせます。理想は小さな VPS です。gateway は 24/7 で動き続ける必要があるので、laptop は向いていません。

hermes model — provider と model に到達できることを確認します。local model を使う場合は、context length が少なくとも 64K あることを確認します。
hermes tools — 本当に必要なものだけを有効にします。tool が増えるたびに、あとで blast radius が広がります。
hermes — 実際の会話を開きます。shell command を実行させ、web search をさせ、file を書かせてみます。出力を見てください。ここで少しでも変なら、Telegram 上では10倍変になります。
hermes doctor — 内蔵 diagnostics に path、permission、dependency の問題を先に拾ってもらいます。

この4つがすべてきれいに通ってから、私は次に進みます。Hermes の maintainer たち自身も project's GitHub repository でこれを強調しています。文書化された流れは setup wizard → CLI → gateway、この順番です。正直、この手順を飛ばすことが、Hermes を諦めるいちばん多い理由だと思います。

Telegram と Slack を順番に setup する

Tokens、permissions、pairing、target routing

では platform の話に入ります。ここでは2つを並べて説明します。概念は似ているからです。app を作り、tokens を取得し、scopes/allowlists を設定し、Hermes に向ける。ただし 実際の手順 はかなり違います。同じものだと思い込むと、silent gateways が生まれます。

Telegram

Telegram は2つのうち、立ち上げが速いほうです。流れ全体が Telegram の中で完結します。

@BotFather との chat を開きます。official Telegram bots documentation によれば、bot を登録して token を取得する公式に認められた唯一の方法です。
/newbot を送り、display name と bot で終わる username を選びます。すると BotFather が 123456789:ABCdef… のような形の token を渡してくれます。
@userinfobot に message を送って、自分の numeric user ID を見つけます。@username と混同しないでください。Hermes は numeric ID で authorization します。
両方を ~/.hermes/.env に入れます。

Plain

TELEGRAM_BOT_TOKEN=123456789:ABCdef...
TELEGRAM_ALLOWED_USERS=123456789

hermes gateway start を実行し、bot に DM します。数秒以内に返事が来るはずです。

人をよく噛む細かい点があります。あとで teammate を追加したい場合、選択肢は2つです。彼らの numeric IDs を TELEGRAM_ALLOWED_USERS に追加するか、DM pairing を使います。未知の user に一度きりの code を発行し、あなたが hermes pairing approve telegram XKGH5N7P で承認する流れです。この pairing flow は Hermes Telegram setup guide に書かれています。正直、shared assistants ではこちらを default にするほうが良いことが多いです。事前に user IDs を追いかけ回さなくて済みます。

Slack

Slack はもう少し込み入っています。1ステップ飛ばすだけで、bot は online に見えるのに channels では完全に黙ります。

api.slack.com/apps に行き、新しい app を from scratch で作ります。初回は manifest から作らないほうが、学びが早いです。Classic Slack apps は 2025年3月に完全に deprecated されたので、現代の Bolt-based flow を使う必要があります。
OAuth & Permissions → Bot Token Scopes で、最低でも app_mentions:read、chat:write、im:history、im:read、im:write、channels:history、groups:history、mpim:history を追加します。2つの *:history scopes が、最もよく抜けます。これがないと bot は DMs では動きますが、channels のすべてを静かに無視します。
Socket Mode を on にします。Hermes が使う経路はこれですし、ほぼすべての self-hosted setup で正しい選択です。gateway に公開 HTTP endpoint は不要で、WebSocket 経由で外向きに接続します。仕組みと理由は official Slack Socket Mode docs にまとまっています。
Basic Information → App-Level Tokens で、connections:write 付きの token を生成します。これが xapp-… token です。手順2の bot token は xoxb-… token です。両方必要です。
app を workspace に install し、2つの tokens と SLACK_ALLOWED_USERS allowlist を ~/.hermes/.env に入れます。
bot を有効にしたい channel で /invite @YourBot を実行します。招待されていない channel の messages は見えません。

inbound と outbound messaging が動くことを検証する

「hi」と送るだけで完了にしないでください。私はすべての platform で同じ3ステップの検証をします。

Inbound: DM で普通の message を送ります。bot が返答するはずです。
Outbound: agent に multi-step task を頼みます（"search the web for X and summarize"）。streaming/typing indicators を見てください。出ない場合、adapter は接続されていますが、progress events が配線されていません。
Targeted delivery: SLACK_HOME_CHANNEL を設定します（または Telegram で /sethome を実行します）。そのうえで cron job を発火させます。cron が間違った場所に届くなら、問題は schedule ではなく home config です。

両方の platform でこの3つが通れば、本当に完了です。最初だけ通るなら、それは partial setup であり、実運用では失敗します。

platform ごとの failure modes

私の support 時間の大半はここに消えています。なので、少し注意して読んでください。

Auth failures、missing adapters、wrong scopes、silent delivery issues

Telegram failure modes は、たいてい token か allowlist に関係します。revoked された token や打ち間違えた token は、きれいな 401 を返します。分かりやすいです。もっと厄介なのは、token は正しいのに TELEGRAM_ALLOWED_USERS が設定されていない場合です。gateway は安全のため default で全 user を拒否します。だから bot は死んでいるように見えますが、実際には指示されたとおりに動いているだけです。firewall の内側にいるなら、HTTPS_PROXY か Telegram-specific proxy variable を設定してください。gateway は graceful に fallback しますが、外へ出る path はあなたが与える必要があります。

Slack failure modes は scopes に集中します。毎週見るパターンがあります。bot は DMs では返事をするのに、channels を無視する。これはほぼ必ず channels:history か groups:history scope の不足で、さらに bot が channel に invite されていないことも重なっています。両方直す必要があります。片方だけでは足りません。ほかの典型的な罠もあります。

xapp- app-level token を忘れた → Socket Mode がまったく接続しません。
install 後に scopes を追加したが、app を reinstall していない → 新しい scopes は実際には grant されていません。Reinstall は必須です。
2025年3月以前の classic app を使っている → 動きません。from scratch で作り直してください。

platform をまたいだ failure mode もひとつあります。gateway service 自体が死ぬことです。macOS では hermes gateway install が launched plist を登録します。Linux では通常 systemd unit で包みます。下層の service が supervised されていないなら、あなたの "24/7 assistant" は実際には4時間 assistant です。次にマシンが reboot したときに止まります。

shared assistants の operational guardrails

誰が agent と話せるのか、approval boundaries、blast radius

これは、手遅れになるまで誰も考えたがらない部分です。agent を Telegram や Slack に置いた瞬間、その chat surface に access できる人は誰でも、あなたの server 上で動いている process に command を出せます。ここには本気で敬意を払うべきです。

私が絶対に破らないルールがいくつかあります。

必ず明示的な allowlist を設定する。 TELEGRAM_ALLOWED_USERS と SLACK_ALLOWED_USERS は optional ではありません。ない場合の安全な default は denial ですし、意識的な判断をするまでそのままにするべきです。GATEWAY_ALLOW_ALL_USERS=true は foot-gun です。正当な使い道を私は一度も見たことがありません。
agent は isolated terminal backend で動かす。 Hermes は Docker terminal backend をサポートしており、capabilities を drop し、privilege escalation を無効にします。外部から到達できる agent では、私はこの設定しか使いません。自分の dev box の CLI は raw shell を持っていてもいい。gateway-backed agent はそうであるべきではありません。
tokens は production secrets として扱う。 Bot tokens、app tokens、allowlist files は ~/.hermes/.env に置き、mode は 600、それ以外の場所には置きません。OWASP Secrets Management Cheat Sheet は rotation、centralized storage、least-privilege access をかなり深く扱っています。team 向けにこれを運用するなら、その実践は optional ではなくなります。
destructive actions の approval prompts は残す。 agent が危険なことをしようとしたら、chat 内で確認し、yes を待つべきです。「もっとスムーズにする」ために消さないでください。その prompt に rm -rf から救われたことが、私は何度もあります。
blast radius を制約する。 Cron jobs は SLACK_HOME_CHANNEL か /sethome Telegram channel に配信されます。「visibility」のために public team channel を指定しないでください。operators だけがいる private channel に向け、summary は手動で forward します。

自分以外の誰かに使わせるなら、本番に出す前に次の質問の答えを書いてください。誰が agent と話せるのか。確認なしで何ができるのか。出力はどこに届くのか。誰が tokens を rotate するのか。 4つすべてに一文で答えられないなら、まだ共有する準備はできていません。

FAQ

Slack では xoxb と xapp tokens の両方が必要ですか？

はい。bot token（xoxb-…）は posting messages と Web API calls に使います。app-level token（xapp-…、connections:write 付き）は、Socket Mode の WebSocket を開くためのものです。どちらかが欠けても接続は別々の形で失敗します。bot token がなければ replies がなく、app token がなければ inbound events がまったくありません。

ひとつの Hermes gateway で複数の Slack workspaces を扱えますか？

はい。Hermes は各 team_id をそれぞれの WebClient と bot user ID に mapping するので、ひとつの gateway process が workspace ごとに独立して authenticate できます。これは documented behavior であり、workaround ではありません。

Telegram bot は DMs では返事をしますが、group messages を無視します。なぜですか？

default では、Telegram bots は privacy mode が有効です。つまり、明示的に mention された message、または bot への reply しか見えません。bot にすべての group messages を見せたい場合は、BotFather で privacy mode を無効にしてください（/setprivacy → disable）。または、単に bot を @mention してください。

gateway を laptop で動かしてもいいですか？

いいえ、やめてください。Hermes の大事な点は、laptop に縛られないことです。$5 VPS か、それに近い always-on machine で動かすべきです。そうしないと、ふたを閉じるたびに bot が死に、みんながそれを信頼しなくなります。

gateway setup は cron や profiles の setup と同じですか？

いいえ。ただし重なり合います。gateway が固まると、cron jobs は設定済みの platforms へ自然に届き、personality profiles もすべての surfaces に伝わります。gateway を正しく作れば、agent ecosystem の残りはだいたいそのまま動きます。間違えると、ほかのすべての feature がその壊れ方を引き継ぎます。

これが正直な話です。まず CLI で土台を作り、その上に Telegram や Slack を重ね、誰が到達できるかを lock down する。そして退屈な verification steps を飛ばさないこと。今期あなたが買える、いちばん安い保険です。