[備忘録] Hermes AgentをSlackと連携する手順メモ

はじめに

Hermes Agentは、SlackのDMやチャンネルから呼び出して利用できます。

ブラウザの管理画面を毎回開かなくても、普段使っているSlackから次のような依頼を行えます。

• 技術情報を調査してもらう
• 調査結果や技術メモを整理してもらう
• ドキュメントの構成や文章を作成してもらう
• 要件、設計、実装方針を検討してもらう
• コードや設定例の作成を支援してもらう
• Markdown、画像、表計算ファイルなどを生成してもらう

たとえば、調査中に見つけた情報をSlackへ投稿し、その内容を技術メモとして整理したり、設計上の論点を洗い出したり、後からドキュメントへまとめたりできます。

用途は技術調査だけに限りません。Qiita記事のネタ整理や原稿作成、社内共有資料の下書き、実装方法の比較などにも利用できます。

今回は、Hermes AgentとSlackを連携するために、Slackアプリを手動で作成したときの設定手順を備忘録として整理します。

注意

本記事は、2026年7月26日時点の公式情報をもとにした、個人的な技術学習・自己研鑽向けの検証メモです。

Slackの管理画面やHermes Agentの設定方法、必要なScope・Event Subscriptionは今後変更される可能性があります。実際に設定する際は、記事末尾の公式ドキュメントも確認してください。

会社のSlackや業務データを使用する場合は、組織の利用規定や管理者への確認が必要です。

今回の構成

今回の連携では、SlackのSocket Modeを利用します。

Slack
  ↓ メッセージ・メンション
Slackアプリ
  ↓ Socket Mode（WebSocket）
Hermes Agent
  ↓ AIモデル・ツール実行
Slackへ回答・ファイル添付

Socket Modeを利用すると、Slackからイベントを受け取るための公開HTTPエンドポイントを自分で用意せず、WebSocket経由でSlackアプリとHermes Agentを接続できます。

設定では、主に次の値を取得します。

値	形式	用途
Bot User OAuth Token	xoxb-...	Slackへの投稿やメッセージ・ファイルの操作
App-Level Token	xapp-...	Socket Modeによる接続
Slack Member ID	U...	Hermesを利用できるユーザーの制限

先に確認しておきたいこと

Hermes Agentの公式ドキュメントでは、Hermes CLIからSlack App Manifestを生成する方法が推奨されています。

hermes slack manifest --agent-view --write

このコマンドを実行すると、OAuth Scope、Event Subscription、Slash Command、Socket Modeなどを含むManifestが生成されます。

生成されたManifestをSlackの「Create New App」から読み込めば、多くの項目をまとめて登録できます。

一方、次のような環境ではHermes CLIを直接操作できない場合があります。

• ホスティングサービス上のHermes Agentを利用している
• 管理画面へSlackトークンを登録する形式になっている
• Hermesが動作しているサーバーへ直接ログインできない
• 設定内容を理解するため、Slackアプリを手動で作成したい

この記事では、そのような場合にも確認できるように、Slackアプリを「From scratch」から手動作成する方法を扱います。

Hermes CLIを利用できる場合は、手動設定よりも公式のManifest生成機能を利用したほうが、設定漏れや将来の変更へ対応しやすいと思います。

1. Slackアプリを作成する

Slackのアプリ管理画面を開きます。

1. 「Create New App」を選択する
2. 「From scratch」を選択する
3. App Nameを入力する
4. 接続するSlackワークスペースを選択する
5. 「Create App」を選択する

アプリ名は、たとえば次のようにします。

Hermes Agent

会社のSlackでは、アプリの追加に管理者承認が必要な場合があります。

個人検証では、まず個人用または検証用のSlackワークスペースを使用したほうが安全です。

2. Bot Token Scopesを設定する

Slackアプリの管理画面で、次の場所を開きます。

Features
  └ OAuth & Permissions
      └ Scopes
          └ Bot Token Scopes

Hermes Agentの公式ドキュメントでは、次のBot Token Scopeが案内されています。

chat:write
app_mentions:read
channels:history
channels:read
groups:history
im:history
im:read
im:write
mpim:history
mpim:read
users:read
files:read
files:write

主な用途は次のとおりです。

Scope	用途
chat:write	HermesからSlackへメッセージを投稿する
app_mentions:read	チャンネル内の@Hermes Agentを検出する
channels:history	Botが参加している公開チャンネルのメッセージを読む
channels:read	公開チャンネルの基本情報を取得する
groups:history	Botが参加している非公開チャンネルのメッセージを読む
im:history	DMのメッセージ履歴を読む
im:read	DMの基本情報を取得する
im:write	DMを開始・管理する
mpim:history	グループDMのメッセージを読む
mpim:read	グループDMの基本情報を取得する
users:read	Slackユーザーの情報を取得する
files:read	Slackに添付されたファイルや音声を読む
files:write	Hermesが生成したファイルをSlackへアップロードする

任意で追加するScope

必要に応じて、次のScopeも追加できます。

groups:read
assistant:write

• groups:read
  • Botが参加している非公開チャンネルの情報を取得する
• assistant:write
  • Hermesの処理中ステータスをSlack上へ表示する

Scopeを減らしたい場合

すべての機能を利用しない場合は、Scopeを減らすことも考えられます。

ただし、Scopeを削りすぎると、次のような状態になる可能性があります。

• DMでは動くがチャンネルでは反応しない
• 添付ファイルを読み取れない
• Markdownや画像をSlackへ返せない
• 非公開チャンネルだけ動かない

最初は公式ドキュメントの構成で動作確認し、実際の用途に応じて権限を見直すのが分かりやすいと思います。

3. Socket Modeを有効にする

Slackアプリの管理画面で、次の場所を開きます。

Settings
  └ Socket Mode

「Enable Socket Mode」をオンにします。

初めて有効化する場合は、App-Level Tokenの作成画面が表示されます。

次のように設定します。

Token Name
hermes-socket

Scope
connections:write

「Generate」を選択すると、次の形式のトークンが表示されます。

xapp-...

これがHermes Agent側に登録するSLACK_APP_TOKENです。

4. Event Subscriptionsを設定する

Slackアプリの管理画面で、次の場所を開きます。

Features
  └ Event Subscriptions

「Enable Events」をオンにします。

続いて、「Subscribe to bot events」に次のイベントを追加します。

message.im
message.mpim
message.channels
message.groups
app_mention

イベント	用途
message.im	HermesがDMを受け取る
message.mpim	HermesがグループDMを受け取る
message.channels	Hermesが公開チャンネルのメッセージを受け取る
message.groups	Hermesが非公開チャンネルのメッセージを受け取る
app_mention	@Hermes Agentへのメンションを受け取る

追加後、「Save Changes」を選択します。

OAuth Scopeは何を実行できるかを制御し、Event SubscriptionはどのイベントをSlackから受け取るかを制御します。

そのため、Scopeだけを追加しても、対応するイベントを購読していなければメッセージを受け取れません。

DMでは動くのにチャンネルで反応しない場合は、message.channelsまたはmessage.groupsの設定を確認します。

5. App HomeのMessages Tabを有効にする

Hermes AgentへDMを送るため、App HomeのMessages Tabを有効にします。

Slackアプリの管理画面で、次の場所を開きます。

Features
  └ App Home
      └ Show Tabs

次の設定を有効にします。

• Messages Tab
• Allow users to send Slash commands and messages from the messages tab

この設定が無効な場合、ScopeやEvent Subscriptionを正しく設定していても、アプリのDM画面からメッセージを送信できません。

6. Slackアプリをワークスペースへインストールする

Slackアプリの管理画面で、次の場所を開きます。

Settings
  └ Install App

1. 「Install to Workspace」を選択する
2. 要求される権限を確認する
3. 「Allow」を選択する

インストールが完了すると、次の形式のBot User OAuth Tokenが表示されます。

xoxb-...

これがHermes Agent側に登録するSLACK_BOT_TOKENです。

重要

ScopeやEvent Subscriptionを後から変更した場合は、Slackアプリをワークスペースへ再インストールします。

設定を変更したのに動作が変わらない場合は、まず再インストールの有無を確認します。

7. Slack Member IDを取得する

Hermes Agentでは、利用を許可するユーザーをSlack Member IDで指定できます。

Slackで自分のプロフィールを開き、次の操作を行います。

1. 「プロフィールをすべて表示」を開く
2. 「︙」メニューを開く
3. 「メンバーIDをコピー」を選択する

メンバーIDは、次のような形式です。

U01ABC2DEF3

ユーザー名や表示名ではなく、Uから始まるMember IDを使用します。

8. Hermes Agent側へ設定する

取得した値をHermes Agent側へ設定します。

必要な値は次の3つです。

Slack Bot Token
xoxb-...

Slack App Token
xapp-...

Allowed Users
U...

Hermes Agentを自分で構築している場合は、~/.hermes/.envへ次のように設定します。

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U01ABC2DEF3

必要に応じて、定期実行結果などを投稿する既定チャンネルも設定できます。

SLACK_HOME_CHANNEL=C01234567890
SLACK_HOME_CHANNEL_NAME=general

対話形式で設定する場合は、次のコマンドを利用できます。

hermes gateway setup

設定後は、Messaging Gatewayを起動します。

hermes gateway

ユーザーサービスとして登録する場合は、次のコマンドも利用できます。

hermes gateway install

ホスティングサービスを利用している場合は、サービスの管理画面にある対応する入力欄へ登録します。

管理画面の項目名や再起動方法は、サービスによって異なる可能性があります。

9. Hermes Agentをチャンネルへ招待する

DMだけで利用する場合は、アプリのMessages画面からそのまま話しかけます。

チャンネルで使用する場合は、利用するチャンネルごとにHermes Agentを招待します。

/invite @Hermes Agent

Hermes Agentは自動的にすべてのチャンネルへ参加するわけではありません。

利用するチャンネルごとに招待が必要です。

10. 動作を確認する

DMで確認する

Hermes Agentのアプリ画面を開き、次のようなメッセージを送ります。

あなたの役割を簡単に説明してください。

DMでは、通常は@Hermes Agentというメンションを付けなくても応答します。

チャンネルで確認する

Hermes Agentを招待したチャンネルで、次のようにメンションします。

@Hermes Agent このチャンネルで利用できることを説明してください。

チャンネルでは、会話を開始するときにメンションが必要です。

Hermesがスレッド内で応答した後は、そのスレッドで会話を継続する場合、毎回メンションしなくても応答します。

11. ファイル出力を確認する

files:writeを設定している場合は、Hermes Agentが生成したファイルをSlackへ添付できるか確認します。

次のように依頼します。

Hermes AgentとSlackの連携確認結果を、
Markdown形式の簡単な技術メモとして作成してください。

ファイル名は hermes_test.md としてください。

作成したファイルを、保存先のパスだけではなく、
Slackの添付ファイルとして返してください。

Hermes AgentのDeliverable Modeでは、Messaging Gateway上で生成したファイルを、Slackなどのチャットへ添付ファイルとして返せます。

利用例としては、次のような成果物が考えられます。

• 技術調査結果のMarkdown
• 要件や設計の整理資料
• 実装方針の比較表
• PDF、Word、Excel、PowerPointなどの資料
• 説明用の画像や図解
• 複数ファイルをまとめたZIP

ファイルを受け取れない場合は、次を確認します。

• files:writeが追加されているか
• Scope追加後にSlackアプリを再インストールしたか
• Hermes AgentのMessaging Gatewayが起動しているか
• Hermesが実際にファイルを生成しているか
• 利用しているホスティングサービスでファイル添付が利用できるか

よくある設定ミス

DMの入力欄が表示されない

App HomeのMessages Tabを確認します。

Features
  └ App Home
      └ Messages Tab

次の2つを有効にします。

• Messages Tab
• Allow users to send Slash commands and messages from the messages tab

DMでは動くがチャンネルで反応しない

次を確認します。

• channels:history
• groups:history
• message.channels
• message.groups
• app_mention
• チャンネルへHermes Agentを招待したか
• 会話の開始時に@Hermes Agentを付けたか

Scopeを追加したのに動作が変わらない

Slackアプリをワークスペースへ再インストールします。

ScopeやEvent Subscriptionの変更は、アプリを再インストールするまで反映されない場合があります。

xapp-トークンで接続できない

次を確認します。

• Socket Modeが有効になっているか
• App-Level Tokenを使用しているか
• connections:writeが付いているか
• xoxb-とxapp-を逆に登録していないか

利用を許可されていないと表示される

Allowed Usersへ登録した値を確認します。

表示名やユーザー名ではなく、Uから始まるSlack Member IDを使用します。

ファイルの読み書きができない

次のScopeを確認します。

files:read
files:write

• files:read
  • SlackからHermesへ送ったファイルを読み取る
• files:write
  • Hermesが生成したファイルをSlackへ返す

トークンの取り扱い

次の値は認証情報です。

xoxb-...
xapp-...

これらのトークンには、Slackアプリへ付与したScopeに応じた権限があります。

次の場所には記載しないようにします。

• Qiitaの記事本文
• GitHubリポジトリ
• Slackの通常メッセージ
• Teams
• メール
• スクリーンショット
• ソースコード
• 公開する.envや設定ファイル

公開する設定例では、必ず次のようなプレースホルダーへ置き換えます。

SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token
SLACK_ALLOWED_USERS=U0123456789

トークンを誤って公開した場合は、記事やメッセージから削除するだけでなく、Slackアプリの管理画面から対象トークンを失効または再生成します。

また、外部のホスティングサービスへトークンを登録する場合は、Slackアプリへ付与した権限の範囲で、そのサービスからSlackへアクセスできる状態になります。

必要以上のScopeを付けず、個人用または検証用ワークスペースから始めるのが安全です。

この手順が陳腐化しやすいポイント

この記事の中でも、特に次の部分は将来変わる可能性があります。

Slack管理画面のメニュー名

Slackの管理画面は更新されることがあります。

次の名称や配置が変わる可能性があります。

• OAuth & Permissions
• Socket Mode
• Event Subscriptions
• App Home
• Install App

画面が記事と異なる場合は、機能名やScope名を手掛かりに探します。

必要なScopeとEvent Subscription

Hermes Agentに機能が追加されると、必要なScopeやイベントが増える可能性があります。

特に次のような変更が入った場合は、公式ドキュメントを再確認します。

• 新しいSlash Commandの追加
• SlackのAgent向けUIの変更
• ファイル処理機能の追加
• リアクションやボタン操作の追加
• Bot同士の連携機能の追加

Slack App Manifest

Hermes Agentの公式ドキュメントでは、手動設定よりもHermesが生成するManifestの利用が推奨されています。

Hermes Agentを更新した場合は、次のコマンドでManifestを再生成できます。

hermes slack manifest --agent-view --write

ManifestをSlackアプリへ反映し、Slackから要求された場合はアプリを再インストールします。

Agent viewと既存アプリ

新しいSlackアプリでは、Hermes Agentの公式手順でAgent viewを使用する構成が案内されています。

既存アプリから移行する場合は、Manifestの再生成やアプリの再インストールが必要になる可能性があります。

Slack側のAIエージェント向けUIとHermes側の対応は変更される可能性があるため、新規作成時は最新の公式手順を確認したほうがよさそうです。

ホスティングサービス側の設定

Hermes Agentをホスティングサービス上で利用している場合、次の部分はサービス側で管理されている可能性があります。

• .envファイル
• Gatewayの起動・再起動
• 常駐サービスの設定
• 生成ファイルの保存先
• Deliverable Mode
• Hermes Agentのバージョン

その場合は、Hermes Agent本体のドキュメントだけでなく、利用しているサービスのヘルプも確認する必要があります。

公開前に再確認する項目

この記事と同様の手順を公開するときは、少なくとも次を確認します。

• Hermes Agent公式のSlack連携ページが更新されていないか
• 必要なBot Token Scopeが変わっていないか
• 必要なEvent Subscriptionが変わっていないか
• Manifest生成コマンドが変わっていないか
• Agent viewに関する記載が変わっていないか
• Slack管理画面の名称が変わっていないか
• トークンやMember IDが画像に映っていないか
• .envや設定画面に実際の認証情報が含まれていないか
• ホスティングサービス固有の仕様を一般仕様として断定していないか

まとめ

Hermes AgentとSlackを連携するには、主に次の設定が必要でした。

1. Slackアプリを作成する
2. Bot Token Scopeを設定する
3. Socket Modeを有効にする
4. Event Subscriptionを設定する
5. App HomeのMessages Tabを有効にする
6. Slackアプリをワークスペースへインストールする
7. xoxb-から始まるBot Tokenを取得する
8. xapp-から始まるApp-Level Tokenを取得する
9. Slack Member IDを取得する
10. Hermes Agentへ3つの値を登録する
11. 利用するチャンネルへBotを招待する
12. DM、チャンネル、ファイル出力を確認する

手動設定では、OAuth Scope、Event Subscription、Messages Tabのどれかが抜けると、部分的にしか動かない状態になりやすいです。

特に覚えておきたいのは、次の点です。

• DMだけ動く場合は、チャンネル用のScopeとイベントを確認する
• DMを送れない場合は、Messages Tabを確認する
• ScopeやEvent Subscriptionを変更した場合は、アプリを再インストールする
• チャンネルでは、会話の開始時に@Hermes Agentを付ける
• ファイルを扱う場合は、files:readとfiles:writeを確認する
• xoxb-とxapp-は秘密情報として安全に管理する

今回は設定内容を理解するために手動設定を整理しましたが、Hermes CLIを利用できる環境では、今後の変更を考えるとManifest生成機能を利用するほうが管理しやすそうです。

Slackを入口にすることで、技術情報の調査、ドキュメント作成、設計や実装方針の検討、成果物の受け取りまで、普段のチャットから進められるようになります。

参考情報

• Slack Setup | Hermes Agent
• Deliverable Mode | Hermes Agent
• CLI Commands Reference | Hermes Agent
• The Events API | Slack Developer Docs
• Tokens | Slack Developer Docs
• Your Apps | Slack API