SlackをHermes Agentのネイティブ窓口にするManifestを整える
Slackを普段の作業場所にしていると、Hermes Agentも同じ画面から呼び出したくなる。単なる通知ならWebhookでも足りるが、DM、チャンネル、スレッド、slash command、ファイル添付まで扱うには、Slack App側の権限とイベント購読を正しくそろえる必要がある。今回はHermes AgentのSlack用Manifestをプロジェクトに固定し、再作成できる構成とテストを追加した。
実際に行ったことと確認結果
手元の実装では、Hermes Agent公式CLIでAgent view対応のSlack App Manifestを生成し、プロジェクト内に保存した。READMEには、Slackの「From a manifest」からAppを作る手順、Bot TokenとApp-Level Tokenを取得する手順、Hermes Gatewayへ秘密値を登録する手順、再起動後の疎通確認をまとめた。
Manifestには、Socket Mode、Messages Tab、bot user、Hermesの主要slash command、OAuth scope、DM・公開チャンネル・プライベートチャンネル・グループDM向けのevent購読を含めた。実トークンやワークスペース固有IDはManifestに入れず、秘密値はGatewayセットアップで扱う方針にした。
確認として、`python -m unittest tests.test_slack_manifest -v` を実行し、5件すべて成功した。テストでは、Socket ModeとAgent view、Messages Tab、主要コマンド、必要なscopeとevent購読、Manifestに実トークンが混入していないことを検査している。
仕組みの流れ
1. Hermes CLIでSlack用Manifestを生成する。
2. 生成物をプロジェクトに保存し、READMEから参照する。
3. Slack管理画面でManifestを貼り付けてAppを作成する。
4. SlackでBot TokenとApp-Level Tokenを発行する。
5. Hermes Gatewayに秘密値と許可ユーザーを登録する。
6. Gatewayを再起動し、DMと招待済みチャンネルで疎通を確認する。
7. Manifestの重要条件を単体テストで固定する。
画面操作だけでSlack Appを作ると、あとで「どのscopeを入れたか」が曖昧になりやすい。Manifestをコードとして残すことで、別ワークスペースへの再適用や復旧時にも差分を追いやすくなる。
再現手順
公開例ではパスと秘密値を一般化している。
“`bash
cd /path/to/project
hermes slack manifest –agent-view –write slack-app-manifest.json
python -m unittest tests.test_slack_manifest -v
“`
Slack管理画面でCreate an App → From a manifestを選び、生成したJSONを貼り付ける。App作成後、Bot TokenとApp-Level Tokenを取得し、Hermes側へ登録する。
“`bash
hermes gateway setup
hermes gateway restart
hermes gateway status
“`
Slackでは、まずHermesへDMを送り、次に使いたいチャンネルへAppを招待してからメンションする。scopeやeventを変更した場合は、Slack Appを再インストールしてから再確認する。
失敗しやすい点と安全策
チャンネルで反応しない場合は、event購読、履歴系scope、App招待、再インストールのいずれかが抜けていることが多い。Hermes公式ドキュメントでも、DMだけでなくチャンネルやグループDMを扱うには対応するmessage eventと履歴scopeが必要だと説明されている。
安全面では、許可ユーザーを必ずSlack Member IDで制限する。Bot Token、App Token、チャンネルID、ワークスペース固有IDは記事やGitへ残さず、例では`YOUR_SLACK_BOT_TOKEN`、`YOUR_SLACK_APP_TOKEN`、`YOUR_SLACK_MEMBER_ID`のようなプレースホルダーに置き換える。Manifestテストは構成の抜けを見つけるもので、Slack側の実インストール完了までは保証しない。
再現チェックリスト
- [ ] ManifestをHermes CLIから生成し、プロジェクトに保存した。
- [ ] Socket Mode、Messages Tab、slash command、event購読を確認した。
- [ ] 必要なOAuth scopeを確認した。
- [ ] 実トークンや固有IDをManifestや記事へ残していない。
- [ ] scopeやevent変更後にSlack Appを再インストールした。
- [ ] Gatewayを再起動し、DMと招待済みチャンネルで確認した。
- [ ] Manifestの単体テストが成功している。
公式一次情報
- [Hermes Agent: Slack Setup](https://hermes-agent.nousresearch.com/docs/user-guide/messaging/slack)
- [Slack Developer Docs: Using Socket Mode](https://docs.slack.dev/apis/events-api/using-socket-mode/)
- [Slack Developer Docs: App manifest reference](https://docs.slack.dev/reference/app-manifest/)
- [Slack Developer Docs: assistant:write scope](https://docs.slack.dev/reference/scopes/assistant.write/)