チームで使う Telegram アシスタントを立ち上げる

このチュートリアルでは、Hermes Agent を動力にした Telegram ボットを、チームの複数のメンバーが使える形で立ち上げます。作り終えるころには、コード、調べもの、サーバー管理、その他なんでも相談できる共用の AI アシスタントが、利用者ごとの認可付きでチームの手元にあります。

何を作るか

こんな Telegram ボットです。

• 許可されたメンバーなら誰でも DM で相談できます。コードレビュー、調べもの、シェルのコマンド、デバッグ
• 自分のサーバーで動き、ツールを一通り使えます。ターミナル、ファイル編集、Web 検索、コード実行
• 利用者ごとのセッション — それぞれが自分の会話の文脈を持ちます
• 標準で安全 — やり取りできるのは承認済みの利用者だけで、認可の方法は 2 通りあります
• 予約実行 — 日々の進捗共有、状態確認、リマインドをチームのチャンネルへ届けます

前提

始める前に、次が揃っていることを確かめてください。

• Hermes Agent をサーバーか VPS にインストール済みであること（手元のノート PC ではなく。ボットは動き続ける必要があります）。まだなら installation guide に従ってください。
• 自分用の Telegram アカウント（ボットの持ち主として）
• LLM プロバイダの設定 — 最低限、OpenAI、Anthropic、あるいは対応する他のプロバイダの API キーを ~/.hermes/.env に置いてください

ステップ 1: Telegram のボットを作る

Telegram のボットづくりは、いつも @BotFather から始まります。ボットを作るための、Telegram 公式のボットです。

1. Telegram を開いて @BotFather を検索するか、t.me/BotFather を開きます

1. /newbot を送ります — BotFather が 2 つのことを聞いてきます:

• 表示名 — 利用者に見える名前です（例: Team Hermes Assistant）
• ユーザー名 — 末尾が bot である必要があります（例: myteam_hermes_bot）

1. ボットのトークンを控えます — BotFather がこんな返事をよこします:

Use this token to access the HTTP API:
7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

このトークンは次のステップで使うので、保存しておいてください。

1. 説明文を設定します（任意ですが、しておくと親切です）:

/setdescription

自分のボットを選び、こんな文言を入れます: `` Team AI assistant powered by Hermes Agent. DM me for help with code, research, debugging, and more. ``

1. コマンドを登録します（任意 — 利用者にコマンドのメニューが出ます）:

/setcommands

自分のボットを選び、これを貼り付けます: `` new - Start a fresh conversation model - Show or change the AI model status - Show session info help - Show available commands stop - Stop the current task ``

ステップ 2: ゲートウェイを設定する

方法は 2 つあります。対話式の設定ウィザード（おすすめ）か、手作業での設定です。

選択肢 A: 対話式の設定（おすすめ）

hermes gateway setup

矢印キーで選びながら、必要なことを一通り済ませられます。Telegram を選び、ボットのトークンを貼り、聞かれたら自分のユーザー ID を入れてください。

選択肢 B: 手作業での設定

~/.hermes/.env に次の行を足します。

# Telegram bot token from BotFather
TELEGRAM_BOT_TOKEN=7123456789:AAH1bGciOiJSUzI1NiIsInR5cCI6Ikp...

# Your Telegram user ID (numeric)
TELEGRAM_ALLOWED_USERS=123456789

自分のユーザー ID を調べる

Telegram のユーザー ID は数値です（ユーザー名ではありません）。調べ方はこうです。

1. Telegram で @userinfobot にメッセージを送ります
2. すぐに、数値のユーザー ID が返ってきます
3. その数字を TELEGRAM_ALLOWED_USERS に書き写します

ステップ 3: ゲートウェイを起動する

まずは試し打ち

まずはゲートウェイをフォアグラウンドで動かし、一通り動くことを確かめます。

hermes gateway

こんな出力が見えるはずです。

[Gateway] Starting Hermes Gateway...
[Gateway] Telegram adapter connected
[Gateway] Cron scheduler started (tick every 60s)

Telegram を開いて自分のボットを探し、メッセージを送ってみてください。返事があれば成功です。Ctrl+C で止められます。

本番運用: サービスとして入れる

再起動しても動き続ける形にするには、次のようにします。

hermes gateway install
sudo hermes gateway install --system   # Linux only: boot-time system service

これでバックグラウンドのサービスができます。Linux では標準でユーザー単位の systemd サービス、macOS では launchd のサービス、--system を付けた場合は Linux の起動時に立ち上がるシステムサービスになります。

# Linux — manage the default user service
hermes gateway start
hermes gateway stop
hermes gateway status

# View live logs
journalctl --user -u hermes-gateway -f

# Keep running after SSH logout
sudo loginctl enable-linger $USER

# Linux servers — explicit system-service commands
sudo hermes gateway start --system
sudo hermes gateway status --system
journalctl -u hermes-gateway -f

# macOS — manage the service
hermes gateway start
hermes gateway stop
tail -f ~/.hermes/logs/gateway.log

動いていることを確かめる

hermes gateway status

そのうえで、Telegram のボットにテストのメッセージを送ってみてください。数秒のうちに返事が来るはずです。

ステップ 4: チームからの利用を許可する

では、同僚が使えるようにしましょう。やり方は 2 通りあります。

やり方 A: 固定の許可リスト

メンバーそれぞれの Telegram のユーザー ID を集め（@userinfobot にメッセージを送ってもらいます）、カンマ区切りで並べます。

# In ~/.hermes/.env
TELEGRAM_ALLOWED_USERS=123456789,987654321,555555555

変更したらゲートウェイを再起動します。

hermes gateway stop && hermes gateway start

やり方 B: DM ペアリング（チームにはこちらがおすすめ）

DM ペアリングのほうが融通が利きます。ユーザー ID を前もって集める必要がありません。仕組みはこうです。

1. 同僚がボットに DM を送る — 許可リストに載っていないので、ボットは使い捨てのペアリングコードを返します:

🔐 Pairing code: XKGH5N7P
Send this code to the bot owner for approval.

1. 同僚がそのコードをあなたに渡します（Slack、メール、直接など、どんな手段でも構いません）

1. あなたがサーバー上で承認します:

hermes pairing approve telegram XKGH5N7P

1. これで使えるようになります — ボットはその人のメッセージにすぐ応じ始めます

ペアリング済みの利用者を管理する:

# See all pending and approved users
hermes pairing list

# Revoke someone's access
hermes pairing revoke telegram 987654321

# Clear expired pending codes
hermes pairing clear-pending

セキュリティで気をつけること

• ターミナルを使えるボットで GATEWAY_ALLOW_ALL_USERS=true を設定してはいけません。ボットを見つけた人が誰でも、あなたのサーバーでコマンドを実行できてしまいます
• ペアリングコードは 1 時間で期限切れになり、暗号論的な乱数から作られます
• 総当たり攻撃を防ぐため、回数の制限があります。利用者ひとりにつき 10 分に 1 回、プラットフォームごとに未処理のコードは最大 3 件まで
• 承認に 5 回失敗すると、そのプラットフォームは 1 時間ロックされます
• ペアリングのデータはすべて chmod 0600 の権限で保存されます

ステップ 5: ボットを設定する

ホームチャンネルを決める

ホームチャンネルは、ボットが cron ジョブの結果や、自分から送るメッセージを届ける先です。これがないと、予約した作業の出力を送る場所がありません。

方法 1: ボットが参加している Telegram のグループやチャットで /sethome コマンドを実行します。

方法 2: ~/.hermes/.env に手で設定します。

TELEGRAM_HOME_CHANNEL=-1001234567890
TELEGRAM_HOME_CHANNEL_NAME="Team Updates"

チャンネルの ID を調べるには、グループに @userinfobot を追加してください。そのグループのチャット ID を教えてくれます。

ツールの進行状況の表示を決める

ボットがツールを使うときに、どこまで細かく見せるかを決めます。~/.hermes/config.yaml で設定します。

display:
  tool_progress: new    # off | new | all | verbose

利用者はチャットで /verbose コマンドを使い、セッションごとに変えることもできます。

SOUL.md で人格を作る

ボットの話し方を作り込むには、~/.hermes/SOUL.md を編集します。

一通りの案内は Use SOUL.md with Hermes をご覧ください。

# Soul
You are a helpful team assistant. Be concise and technical.
Use code blocks for any code. Skip pleasantries — the team
values directness. When debugging, always ask for error logs
before guessing at solutions.

プロジェクトの前提を渡す

チームで特定のプロジェクトに取り組んでいるなら、コンテキストファイルを作って、使っている技術構成をボットに知らせておきましょう。

<!-- ~/.hermes/AGENTS.md -->
# Team Context
- We use Python 3.12 with FastAPI and SQLAlchemy
- Frontend is React with TypeScript
- CI/CD runs on GitHub Actions
- Production deploys to AWS ECS
- Always suggest writing tests for new code

ステップ 6: 予約実行を設定する

ゲートウェイが動いていれば、繰り返しの作業を予約して、結果をチームのチャンネルへ届けられます。

日々の進捗まとめ

Telegram でボットにこう送ります。

Every weekday at 9am, check the GitHub repository at
github.com/myorg/myproject for:
1. Pull requests opened/merged in the last 24 hours
2. Issues created or closed
3. Any CI/CD failures on the main branch
Format as a brief standup-style summary.

エージェントが自動で cron ジョブを作り、頼んだチャット（あるいはホームチャンネル）へ結果を届けます。

サーバーの状態チェック

Every 6 hours, check disk usage with 'df -h', memory with 'free -h',
and Docker container status with 'docker ps'. Report anything unusual —
partitions above 80%, containers that have restarted, or high memory usage.

予約した作業を管理する

# From the CLI
hermes cron list          # View all scheduled jobs
hermes cron status        # Check if scheduler is running

# From Telegram chat
/cron list                # View jobs
/cron remove <job_id>     # Remove a job

本番運用のコツ

安全のために Docker を使う

チームで共用するボットでは、ターミナルのバックエンドに Docker を使い、エージェントのコマンドをホストではなくコンテナの中で動かしましょう。

# In ~/.hermes/.env
TERMINAL_ENV=docker
TERMINAL_DOCKER_IMAGE=nikolaik/python-nodejs:python3.11-nodejs20

~/.hermes/config.yaml に書くこともできます。

terminal:
  backend: docker
  container_cpu: 1
  container_memory: 5120
  container_persistent: true

こうしておけば、誰かがボットに危ないことを頼んでしまっても、ホスト側は守られます。

ゲートウェイを見張る

# Check if the gateway is running
hermes gateway status

# Watch live logs (Linux)
journalctl --user -u hermes-gateway -f

# Watch live logs (macOS)
tail -f ~/.hermes/logs/gateway.log

Hermes を最新に保つ

Telegram からボットに /update を送ると、最新版を取得して再起動します。サーバー側からやる場合はこうです。

hermes update
hermes gateway stop && hermes gateway start

ログの置き場所

この先へ

これで、チームで使える Telegram アシスタントが動くようになりました。次に進む先をいくつか挙げます。

• Security Guide — 認可、コンテナによる隔離、コマンド承認を詳しく
• Messaging Gateway — ゲートウェイの構造、セッション管理、チャットのコマンドを網羅した一覧
• Telegram Setup — 音声メッセージや音声合成を含む、Telegram 固有の話
• Scheduled Tasks — 配信先の指定や cron 式を使った、踏み込んだ予約実行
• Context Files — プロジェクトの知識を渡す AGENTS.md、SOUL.md、.cursorrules
• Personality — 組み込みの人格プリセットと、自分で決める人物像
• プラットフォームを増やす — 同じゲートウェイで Discord、Slack、WhatsApp を同時に動かせます

*質問や不具合がありますか。GitHub で issue を開いてください。寄稿を歓迎します。*