Slack の設定

ソケットモードを使って、Hermes Agent を Slack のボットとしてつなぎます。ソケットモードは公開された HTTP のエンドポイントではなく WebSocket を使うので、Hermes を動かしている機械が外から見える必要はありません。ファイアウォールの内側でも、手元のノートパソコンでも、非公開のサーバーでも動きます。

全体像

手順 1: Slack アプリを作る

いちばん早いのは、Hermes が作ってくれるマニフェストを貼り付ける方法です。このマニフェストには、組み込みのスラッシュコマンド（/btw、/stop、/model など）、必要な OAuth のスコープ、購読するイベントがすべて書かれており、ソケットモードも有効になります。これらが一度にそろいます。

方法 A: Hermes が作ったマニフェストから作る（おすすめ）

1. マニフェストを作ります。新しい Slack アプリでは Agent ビューを使う必要があります。

hermes slack manifest --agent-view --write

これで ~/.hermes/slack-manifest.json が書き出され、貼り付けの手順が表示されます。Slack の旧来の Assistant ビューをまだ使っている既存のアプリでは、移行の準備が整うまで --agent-view を省けます。

Slack の長い説明文を、手元の UTF-8 のテキストや Markdown のファイルから埋めたいときは --long-description-file を足します。

hermes slack manifest --agent-view \
  --long-description-file AGENTS.md --write

ファイルの中身は、Slack の 175〜4,000 文字の範囲でそのまま使われます。文章を直に渡したいときは --long-description "..." を使います。直に渡す方法とファイルを渡す方法は同時に使えず、どちらも --slashes-only とは組み合わせられません。

1. https://api.slack.com/apps を開き、Create New App → From an app manifest と進みます
2. ワークスペースを選び、JSON の中身を貼り付けて内容を確認し、Next → Create をクリックします
3. 手順 6: アプリをワークスペースに入れる まで飛ばして構いません。スコープ、イベント、スラッシュコマンドはマニフェストが済ませてくれています。

方法 B: 一から作る（手作業）

1. https://api.slack.com/apps を開きます
2. Create New App をクリックします
3. From scratch を選びます
4. アプリの名前（たとえば「Hermes Agent」）を入れ、ワークスペースを選びます
5. Create App をクリックします

アプリの Basic Information のページに移ります。このあとの手順 2 〜 6 に進んでください。

手順 2: ボットトークンのスコープを設定する

サイドバーの Features → OAuth & Permissions を開きます。Scopes → Bot Token Scopes までスクロールして、次のスコープを足します。

任意のスコープ:

手順 3: ソケットモードを有効にする

ソケットモードを使うと、公開の URL を用意せずに WebSocket でつなげます。

1. サイドバーの Settings → Socket Mode を開きます
2. Enable Socket Mode をオンにします
3. アプリレベルトークン を作るよう促されます。

• 名前は hermes-socket のように付けます（名前は何でも構いません）
• connections:write のスコープを足します
• Generate をクリックします

1. トークンを控えます。xapp- で始まる文字列で、これが SLACK_APP_TOKEN になります

手順 4: イベントを購読する

ここは肝心なところです。ボットがどのメッセージを見られるかが、この設定で決まります。

1. サイドバーの Features → Event Subscriptions を開きます
2. Enable Events をオンにします
3. Subscribe to bot events を開いて、次を足します。

1. ページ下部の Save Changes をクリックします

手順 5: メッセージタブを有効にする

これはボットへのダイレクトメッセージを使えるようにする手順です。有効にしていないと、ボットに個人チャットを送ろうとした利用者に 「Sending messages to this app has been turned off」 と表示されます。

1. サイドバーの Features → App Home を開きます
2. Show Tabs までスクロールします
3. Messages Tab をオンにします
4. 「Allow users to send Slash commands and messages from the messages tab」 にチェックを入れます

手順 6: アプリをワークスペースに入れる

1. サイドバーの Settings → Install App を開きます
2. Install to Workspace をクリックします
3. 権限の内容を確認して Allow をクリックします
4. 承認が終わると、xoxb- で始まる Bot User OAuth Token が表示されます
5. このトークンを控えます。これが SLACK_BOT_TOKEN になります

手順 7: 許可リストに載せる利用者 ID を調べる

Hermes は許可リストに Slack の メンバー ID を使います（ユーザー名や表示名ではありません）。

メンバー ID の調べ方は次のとおりです。

1. Slack でその人の名前かアイコンをクリックします
2. View full profile をクリックします
3. ⋮（その他）のボタンをクリックします
4. Copy member ID を選びます

メンバー ID は U01ABC2DEF3 のような形です。少なくとも自分のメンバー ID は必要です。

手順 8: Hermes を設定する

~/.hermes/.env ファイルに次を書き足します。

# Required
SLACK_BOT_TOKEN=xoxb-your-bot-token-here
SLACK_APP_TOKEN=xapp-your-app-token-here
SLACK_ALLOWED_USERS=U01ABC2DEF3              # Comma-separated Member IDs

# Optional
SLACK_HOME_CHANNEL=C01234567890              # Default channel for cron/scheduled messages
SLACK_HOME_CHANNEL_NAME=general              # Human-readable name for the home channel (optional)

対話式の設定を使うこともできます。

hermes gateway setup    # Select Slack when prompted

続いてゲートウェイを起動します。

hermes gateway              # Foreground
hermes gateway install      # Install as a user service
sudo hermes gateway install --system   # Linux only: boot-time system service

手順 9: ボットをチャンネルに招待する

ゲートウェイを起動したら、ボットに返事をしてほしいチャンネルごとに 招待 する必要があります。

/invite @Hermes Agent

ボットが自分からチャンネルに参加することは ありません。チャンネルごとに招待してください。

スラッシュコマンド

Hermes のコマンド（/btw、/stop、/new、/model、/help など）は、すべて Slack 本来のスラッシュコマンドとして使えます。Telegram や Discord での使い勝手とまったく同じです。Slack で / と打つと、入力補助の一覧に Hermes のコマンドが説明つきで並びます。

裏側では、Hermes が Slack アプリのマニフェストを生成し（手順 1 の方法 A を見てください）、COMMAND_REGISTRY にあるコマンドをすべてスラッシュコマンドとして宣言しています。ソケットモードでは、マニフェストの url の項目に関わらず、Slack はコマンドのイベントを WebSocket 経由で届けます。

Agent のメッセージ体験

新しい Slack アプリは、Slack の Agent のメッセージ体験を使います。すでに Assistant として作った Hermes のアプリは、--agent-view を付けてマニフェストを作り直せば移行できます。

hermes slack manifest --agent-view --write

Features → App Manifest でマニフェストを更新し、Slack から求められたらアプリを入れ直します。Agent ビューから Assistant ビューへ戻すことはできません。切り替えたあと、利用者は Slack の再読み込みが必要になることがあります。生成された Agent 向けのマニフェストは message.im、app_home_opened、app_context_changed を購読するので、Hermes はメッセージタブでの個人チャットを見分けられ、そのやり取りとあわせて利用者が今見ている Slack の文脈も受け取れます。Hermes がその文脈として扱うのは目印だけで、見ているチャンネルの履歴を読むことはありません。

更新後にスラッシュコマンドを取り込み直す

Hermes に新しいコマンドが増えたとき（hermes update のあとなど）は、マニフェストを作り直して Slack アプリを更新します。

hermes slack manifest --write

そのうえで Slack 側の操作です。

1. https://api.slack.com/apps を開き、Hermes のアプリを選びます
2. Features → App Manifest → Edit と進みます
3. ~/.hermes/slack-manifest.json の新しい中身を貼り付けます
4. Save します。スコープやスラッシュコマンドが変わっていれば、Slack がアプリの入れ直しを求めてきます。

従来の /hermes <subcommand> も使えます

古いマニフェストとの互換のため、/hermes bg run the tests のような書き方も残っています。Hermes はこれを /bg run the tests と同じように扱います。自由な質問文も使えて、/hermes what's the weather? はふつうのメッセージとして扱われます。

スレッドのなかでコマンドを使う（!cmd の書き方）

Slack 自身が、スレッドの返信のなかでは本来のスラッシュコマンドを受け付けません。スレッドで /queue と打つと、Slack が *「/queue is not supported in threads. Sorry!」* と返します。アプリ側の設定で使えるようにする方法はなく、Slack はそれを Hermes に届けません。

その代わりとして、Hermes は先頭の ! をコマンドの別の書き方として認識します。これはスレッドでも、それ以外の場所でも使えます。ふつうのスレッドの返信として !queue、!stop、!model gpt-5.4 などと打てば、Hermes はスラッシュの形とまったく同じに扱い、同じスレッドで返事をします。

コマンドかどうかを見るのは先頭の 1 語だけなので、!nice work のような何気ないメッセージはそのままエージェントに渡ります。この書き方はメンションのあと（@Hermes !stop）でも、先頭に空白があっても効き、どちらもスレッド内でコマンドとして動きます。

承認を求める表示（危険なコマンドや execute_code の承認）は、ふだんは押せるボタンとして出ます。ボタンを出せず、Hermes が文章での確認に切り替えたときは、その文面が !approve / !deny で返すよう案内します。これがスレッドのなかでも通じる書き方です。

スラッシュコマンドへの返事は本人にだけ見えます

本来のスラッシュコマンド（/status、/help など）への返事は 本人にだけ見える形 で届きます（「Only visible to you」）。コマンドの出力でチャンネルが荒れることはありません。「Running /cmd…」という仮の表示は本当の返事に置き換わり、長い返事は続きのメッセージに分けて、やはり本人にだけ見える形で送られます。Slack はこの流れを 5 通までに制限しているので、極端に長い出力は黙って切られるのではなく、途中で打ち切った旨をはっきり添えて終わります。本人だけに見せる経路が失敗したときは、Hermes が別の同じ仕組みの API 経路で送り直します。代わりにチャンネルへ公開で投稿することはありません。（ふつうのメッセージとして打ったコマンド、つまりスレッドでの !cmd や @Hermes /cmd は、ふだんどおり全員に見えるメッセージで返します。）

確認の問いかけ（ワンタップのボタン）

エージェントが選択式の質問をする必要があるとき（clarify のツール）、Slack では Block Kit のボタン として表示されます。選択肢ごとに 1 タップで答えられ、さらに「✏️ Other…」のボタンで自由入力に切り替えられます（次に打ったメッセージが答えになります）。タップすると、そのメッセージがその場で書き換わり、誰が何を選んだかが表示されます。同じ問いかけをもう一度押しても無視されます。ボタンの操作にも、メッセージと同じ利用者の権限の判定がかかります。期限切れの問いかけ（ゲートウェイの再起動や時間切れ）は、押した操作を黙って飲み込まずに、もう一度尋ねるよう案内します。答えの決まっていない問いかけは、ふつうの質問文として表示され、次に打った返事を受け取ります。設定は要りません。rich_blocks の設定に関わらず動きます。

上級者向け: スラッシュコマンドの配列だけを出力する

Slack のマニフェストを自分で管理していて、スラッシュコマンドの一覧だけがほしい場合の書き方です。

hermes slack manifest --slashes-only > /tmp/slashes.json

出てきた配列を、今のマニフェストの features.slash_commands の項目に貼り付けます。

ボットの返事の仕方

場面ごとの Hermes の振る舞いをまとめます。

設定できる項目

手順 8 で入れた必須の環境変数のほかに、~/.hermes/config.yaml で Slack のボットの振る舞いを細かく決められます。

スレッドと返信の振る舞い

platforms:
  slack:
    # Controls how multi-part responses are threaded
    # "off"   — never thread replies to the original message
    # "first" — first chunk threads to user's message (default)
    # "all"   — all chunks thread to user's message
    reply_to_mode: "first"

    extra:
      # Whether to reply in a thread (default: true).
      # When false, channel messages get direct channel replies instead
      # of threads. Messages inside existing threads still reply in-thread.
      reply_in_thread: true

      # Also post thread replies to the main channel
      # (Slack's "Also send to channel" feature).
      # Only the first chunk of the first reply is broadcast.
      reply_broadcast: false

      # Control Slack's automatic link-preview cards without changing or
      # removing clickable links from message text. Omit either key to keep
      # Slack's default behavior for that preview type.
      unfurl_links: false
      unfurl_media: false

      # Render agent messages as Slack Block Kit blocks (default: false).
      # When true, the final agent message is sent with structured blocks —
      # section headers, dividers, true nested lists (via rich_text), and
      # native Block Kit tables — instead of flat mrkdwn text. A plain-text
      # fallback is always sent alongside for notifications/accessibility.
      # Tables exceeding Slack's limits (100 rows / 20 cols / 10k chars)
      # gracefully fall back to aligned monospace.
      rich_blocks: false

      # Append Slack-native feedback controls to final Block Kit replies.
      # Requires rich_blocks: true. Default: false.
      feedback_buttons: false

      # Render live tool calls as Slack-native plan/task cards. This explicit
      # opt-in activates native progress even when text tool_progress is off.
      # If Slack rejects the native stream, Hermes keeps one editable text
      # fallback current for the rest of the turn.
      native_task_cards: false

      # Suggested prompts pinned at the top of Agent view's Messages tab.
      # Either a list of {title, message} rows, or a titled object:
      # {title: "Start here", prompts: [{title: "Plan", message: "..."}]}
      suggested_prompts: []

      # Title Agent/Assistant DM threads from the first user message.
      # Default: true. Set false to leave Slack's default thread titles.
      assistant_thread_titles: true

      # Accept messages posted by other Slack bots (default: "none").
      # "none" ignores bots, "mentions" accepts a bot message only when
      # that message itself @mentions Hermes, and "all" accepts every
      # other bot. Hermes always ignores its own bot user to prevent
      # self-echoes.
      allow_bots: "none"

      # Continuable-cron delivery surface (default: "thread").
      # "in_channel" delivers a continuable cron job FLAT into the channel
      # (no dedicated thread); pair with reply_in_thread: false (and
      # require_mention: false) so a plain reply continues the job.
      # See the cron guide → "Flat, in-channel continuation".
      cron_continuable_surface: thread

同じ設定は環境変数 SLACK_ALLOW_BOTS=none|mentions|all でも書けます。両方を設定した場合は platforms.slack.extra.allow_bots が優先されます。相手のボットが明示的なメンションなしでも答えてしまう場合、all は避けてください。相手側の返信の決まりしだいで堂々巡りになり得ます。

作業中の状態表示

エージェントがメッセージを処理している間、Slack はスレッドのボット名の横に状態表示を出します。初期状態では Hermes が is thinking... と表示します。これは typing_status_text で変えられます。たとえば Ada という名前の子猫の助手なら次のようになります。

platforms:
  slack:
    # Custom working-state status line (default: "is thinking...").
    typing_status_text: "is pouncing… 🐾"

同じ項目は、Google Chat で目に見える作業中の印のメッセージ（platforms.google_chat.typing_status_text、初期値は "Hermes is thinking…"）にも使えます。ただし Google Chat では、消えていく状態表示ではなく、実際に投稿されたメッセージが返信へ書き換わる形になります。

実行中の状態表示（ツールごと）

初期状態では、状態表示は エージェントの作業に合わせてその場で変わります。固定の is thinking... ではなく、いま何をしているか、たとえば is running pytest tests/…、is reading docs/api.md…、is searching the web for slack api limits… のように出ます。ツールの呼び出しの合間には、固定の文言に戻ります。これは今までの状態更新の間隔に乗るだけなので、Slack の API を余分に呼びません。Slack の初期値である tool_progress: off のままでも動きます。進捗の吹き出しと違って、状態表示は消えるものなので、チャンネルには何も残りません。

これは display.live_status で決めます（全体でも、サービスごとでも設定できます）。

display:
  platforms:
    slack:
      # full = verb + argument ("is running pytest…")   [default]
      # verb = verb only ("is running…") — hides commands/paths,
      #        useful in shared or customer-facing channels
      # off  = static text (typing_status_text or "is thinking...")
      live_status: full

Slack 本来の逐次表示（打っているように見える返信）

Slack の Agents & AI Apps の機能には、返信をその場で打っているように見せる仕組み（chat.startStream / chat.appendStream / chat.stopStream）があります。ほかの場合に使う、編集を重ねる更新よりもずっとなめらかです。streaming.enabled が有効なら（transport が auto か draft）、Hermes は使える場面で自動的にこの仕組みを使います。

• 最初のひとかたまりで送信を始め、以降は差分だけを足していきます（この API は追記しかできません）。流して送ったメッセージが そのまま 最後のメッセージになります。Hermes は chat.stopStream で締めくくり、同じ内容をもう一度投稿することはしません。
• Slack アプリで AI の機能が有効になっていない場合（または assistant:write のスコープがない場合）、最初の失敗を覚えておき、Hermes は編集を重ねる方式に切り替えます。そのとき、直し方を書いた警告をログに 1 行だけ出します。
• 自分で選んで有効にした Block Kit（rich_blocks: true）は、締めくくったメッセージにも適用されます。編集を重ねる方式で仕上げるときと同じです。

逐次表示を有効にする以外に、特別な設定は要りません。

streaming:
  enabled: true       # transport auto/draft lights up Slack native streaming

Slack 本来の作業カード（ツールの進捗をその場で表示）

platforms.slack.extra.native_task_cards: true にすると、実行中のツールの呼び出しが、文字の進捗の吹き出しではなく Slack 本来の 計画・作業のカード（Slack 自身の AI 機能が使っているのと同じ見た目）として表示されます。やり取りごとにカードが 1 枚、ツールの呼び出しごとに 1 行が並び、実行中・完了・エラーの状態がその場で更新されます。

platforms:
  slack:
    extra:
      native_task_cards: true

• これは自分で選んで有効にする進捗表示です。Slack での初期値が tool_progress: off であっても動きます（文字の吹き出しはチャンネルを騒がせますが、Slack 本来のカードはそうなりません）。
• 同じツールを同時に呼んだ場合も、本物のツール呼び出しの ID で結び付けるので、並行する web_search の呼び出しはそれぞれ自分の行に正しい状態が出ます。
• Slack 本来の送信を始められない、または更新できないときは、Hermes は編集を重ねる 1 つのテキストのメッセージに切り替えて、そのやり取りの間じゅう進捗を出し続けます。
• カードの送信は、やり取りが終わるときにちょうど一度だけ止まります。中断や切断のときも同じなので、動いたままの表示が残ることはありません。

セッションの分離

# Global setting — applies to Slack and all other platforms
group_sessions_per_user: true

true（初期値）のときは、共有のチャンネルにいる利用者それぞれが、自分だけの会話のセッションを持ちます。#general で 2 人が Hermes と話しても、履歴と文脈は別々になります。

チャンネル全体で 1 つの会話のセッションを共有する、共同作業の形にしたいときは false にします。この場合、文脈の膨らみとトークンの費用を全員で分け合うことになり、誰か 1 人の /reset が全員のセッションを消してしまう点にも注意してください。

メンションときっかけの振る舞い

slack:
  # Require @mention in channels (this is the default behavior;
  # the Slack adapter enforces @mention gating in channels regardless,
  # but you can set this explicitly for consistency with other platforms)
  require_mention: true

  # Prevent thread auto-engagement: only reply to channel messages that
  # contain an explicit @mention. With this OFF (default), Slack can
  # "auto-engage" — remembering past mentions in a thread and following
  # up on bot-message replies, and resuming active sessions without a
  # fresh mention. With strict_mention ON, every new channel message
  # must @mention the bot before Hermes will respond.
  strict_mention: false

  # Ignore messages addressed to another user: when a channel or thread
  # message *opens* by @mentioning someone other than the bot (e.g.
  # "@rasha can you take this?"), stay silent unless the bot is also
  # mentioned. Only a *leading* mention counts as "addressed to" — a
  # message that references someone mid-sentence ("loop in @rasha")
  # still reaches the bot. Overrides free_response_channels and thread
  # auto-engagement. Opt-in; default off. Env: SLACK_IGNORE_OTHER_USER_MENTIONS.
  ignore_other_user_mentions: false

  # Require an explicit @mention for THREAD replies, while leaving
  # top-level channel messages governed by require_mention /
  # free_response_channels. Narrower than strict_mention: use it when a
  # free-response bot should not join every follow-up in busy threads.
  # Opt-in; default off. Env: SLACK_THREAD_REQUIRE_MENTION.
  thread_require_mention: false

  # Per-channel force-mention override — the opposite direction of
  # free_response_channels. Channels listed here ALWAYS require an
  # explicit @mention, even when require_mention is false globally.
  # Ongoing conversations still auto-follow (mentioned threads, active
  # sessions, bot-authored threads). Comma-separated IDs or a list.
  # Env: SLACK_REQUIRE_MENTION_CHANNELS.
  require_mention_channels: ""

  # Custom mention patterns that trigger the bot
  # (in addition to the default @mention detection)
  mention_patterns:
    - "hey hermes"
    - "hermes,"

  # Text prepended to every outgoing message
  reply_prefix: ""

どのメンションの設定を使えばいいか

これらの関門は組み合わせて働き、それぞれ別の問いに答えます。

目安としては、strict_mention がいちばん大づかみな手段です。thread_require_mention は通常のメッセージの扱いに触れずに、にぎやかなスレッドだけを静かにします。require_mention_channels は、ふだんメンション不要にしているボットで、特定のチャンネルだけ締め直します。ignore_other_user_mentions は、はっきり別の人に宛てたメッセージだけを見送ります。1 対 1 の個人チャットではいつでも返事をし、これらの設定の影響を受けません。

ほかのボットからのメッセージを受け取る（allow_bots）

初期状態では、Hermes はほかの Slack のボットやアプリが書いたメッセージ（Workflow Builder の投稿も含みます）をすべて無視します。複数のエージェントが並ぶワークスペース、つまり複数の Hermes や相手側のボットが 1 つのチャンネルで協力する場合は、allow_bots で受け取るようにします。

platforms:
  slack:
    extra:
      # "none" (default) — ignore all bot/app-authored messages
      # "mentions"       — accept a bot message only when THAT message
      #                    @mentions this bot
      # "all"            — accept every bot message (except the bot's own)
      allow_bots: mentions

環境変数では SLACK_ALLOW_BOTS=none|mentions|all にあたります（両方を設定した場合は設定ファイル側が優先されます）。知らない値は none として扱われます。

mentions のときの判定は次のとおりです。

• 相手のボットのメッセージを受け取るのは、そのメッセージ自体に、このボットへの今の @mention が入っているときだけ です。本文でも Block Kit の部品のなかでも構いません。スレッドの履歴は判定に入りません。そのスレッドで前にメンションされていたこと、ボット自身の発言への返信、動いているスレッドのセッションのいずれも、あとから来るメンションなしの相手ボットのメッセージを通しません。これは意図してそうしています。エージェント同士が「了解」「状況」と返し合う堂々巡りは、これで止まります。
• 人のメッセージには影響しません。そちらにはふだんどおりメンションの判定がかかります。
• どの設定でも、Hermes は自分自身のメッセージを常に無視します。自分の声がこだまして回り続けるのを防ぐためです。

ボット同士の連携では mentions をおすすめします。エージェントはやり取りのたびに、相手をはっきり呼ぶ必要があります。相手のボットの返信の決まりが堂々巡りを起こさないと確かめられない限り、all は避けてください。何にでも答える 2 台のボットは、いつまでも返し合います。判定の対象には、ボット印の付いたメッセージ（bot_id、subtype: bot_message）、アプリから発生したイベント、印の付いていないボットの *利用者*（users.info で確かめます）が含まれるので、相手側の Hermes もワークスペースをまたいで同じように選り分けられます。

複数のボットを厳しく運用するなら、require_mention: true と strict_mention: true を組み合わせます。下の動作確認のひな形も見てください。

リアクションをきっかけにする（reaction_triggers）

初期状態では、絵文字のリアクションは受け取ったことだけ確認して捨てられます。ボットのメッセージに 👍 を付けても何も起きません。リアクションをエージェントの処理に流したいときは slack.reaction_triggers を設定します（reactions:read のスコープと、Slack アプリのマニフェストでの reaction_added / reaction_removed のボットイベントの購読が必要です。hermes slack manifest で作り直してください）。

slack:
  # Opt-in. false/absent (default) = reactions are acked and dropped.
  # true = any reaction ON THE BOT'S OWN MESSAGES routes to the agent.
  reaction_triggers: true
  # Or an explicit emoji allowlist — only these names route, and they may
  # target ANY message (emoji-handoff workflows, e.g. :task: to capture):
  # reaction_triggers: [white_check_mark, thumbsup, task]
  # Optional handoff target: respond in this channel (top-level) or thread
  # (C123:<thread_ts>) instead of the reacted-to message's thread.
  # reaction_trigger_target: C0123456789

環境変数では SLACK_REACTION_TRIGGERS（true / all またはカンマ区切りの一覧）と SLACK_REACTION_TRIGGER_TARGET にあたります。

振る舞いは次のとおりです。

• リアクションは、reaction:added:👍 / reaction:removed:👍 という本文のふつうのやり取りとしてエージェントに届きます（よくある Slack の名前は絵文字に置き換えられ、知らない名前は reaction:added:custom-emoji のようにそのまま渡されます）。リアクションされたメッセージにぶら下げて届くので、エージェントは何に対するリアクションかを把握でき、そのやり取りは返信のときと同じセッションに入ります。
• リアクションを付けた人がそのメッセージの送り主として扱われるので、利用者の権限の判定と allowed_channels の絞り込みが、打ったメッセージとまったく同じようにかかります。無関係な人のリアクションが、その人のメッセージでは動かせない場所でエージェントを動かすことはできません。
• reaction_triggers: true のときに流れるのは、ボット 自身の メッセージに付いたリアクションだけです（承認や確認の流れを想定しています）。絵文字を並べて指定した場合は、その絵文字がどのメッセージからでも流れます。
• ボット自身が付ける処理状況のリアクション（:eyes: など）が戻ってくることはありません。
• この設定とは別に、人が付けたリアクションはすべて reaction:added / reaction:removed のゲートウェイのフックを呼びます。エージェントのやり取りを必要としない見張り役のための仕組みです。

エージェント同士の動作確認

やり取りごとの厳密なメンションを前提にした、複数ボットの Slack 環境では、次のひな形を保ってください。

slack:
  require_mention: true
  strict_mention: true
  allow_bots: mentions
  allowed_channels: ""

ゲートウェイの設定変更、配備、再起動のあとには、次の合成イベントによる動作確認を走らせます。

uv run --frozen pytest -q tests/gateway/test_slack_peer_agent_smoke.py -o addopts=''

この確認はプロセス内で作った擬似的な Slack のイベントだけを使います。実際に Slack へメッセージを送ることはなく、初期状態では本物のボットトークンも要りません。

失敗の種類は次のとおりです。

• config: test_peer_agent_smoke_preflight_contract がひな形とのずれ（require_mention、strict_mention、allow_bots、allowed_channels）を見つけた場合。
• platform_connectivity: アダプターやクライアントが初期化されておらず、振り分けの確認結果をまだ信用できない場合。
• bot_identity: アダプターが自分のボットの利用者 ID を得られておらず、今のメッセージのメンションの判定ができない場合。
• routing_logic: Slack のアダプターが、エージェント同士のやり取りで守るべき決まりのどれか（人のメンションの振り分け、相手ボットの無視、はっきりメンションされた相手ボットの受け入れ、受け身の了解・状況・エラーの抑制）を壊してしまった場合。

この確認が通るのに実際のワークスペースでは振り分けがおかしいときは、振り分けの処理そのものではなく、Slack のトークンやワークスペースとの接続、動かしている環境の状態を調べてください。

チャンネルの許可リスト（allowed_channels）

ボットが動くチャンネルを、決められたものだけに絞れます。多くのチャンネルに招待されているけれど、返事をしてほしいのは一部だけ、というときに便利です。設定すると、一覧にないチャンネルのメッセージは、@mentioned されていても 黙って無視 されます。

1 対 1 の個人チャットはこの絞り込みの対象外です。許可された利用者はいつでもダイレクトメッセージでボットに届きます。グループ DM（MPIM）は対象外ではありません。チャンネルと同じで、MPIM も許可リストに載っていなければ（ID は G で始まります）、そのメッセージは捨てられます。

slack:
  allowed_channels:
    - "C0123456789"   # #ops
    - "C0987654321"   # #incident-response

環境変数（カンマ区切り）で書くこともできます。

SLACK_ALLOWED_CHANNELS="C0123456789,C0987654321"

振る舞いは次のとおりです。

• 空、または未設定 → 制限なし（これまでの動きと完全に同じです）。
• 中身がある → チャンネル ID が一覧に載っている必要があります。載っていないメッセージは、ほかのどの関門（メンションの要否、free_response_channels など）よりも先に捨てられます。
• Slack のチャンネル ID は C（公開）、G（非公開）、D（個人チャット）で始まります。Slack の画面で「Open channel details」→「About」を開くか、API で調べられます。

あわせて読む: 管理者用と利用者用のスラッシュコマンドの分け方。

許可していない利用者への対応

slack:
  # What happens when an unauthorized user (not in SLACK_ALLOWED_USERS) DMs the bot
  # "pair"   — prompt them for a pairing code (default)
  # "ignore" — silently drop the message
  unauthorized_dm_behavior: "pair"

すべてのサービスに共通の設定として書くこともできます。

unauthorized_dm_behavior: "pair"

slack: の下にあるサービスごとの設定は、共通の設定より優先されます。

音声の書き起こし

# Global setting — enable/disable automatic transcription of incoming voice messages
stt_enabled: true

true（初期値）のときは、届いた音声のメッセージが、エージェントの処理に回る前に、設定した書き起こしのサービスで自動的に文字にされます。

設定の全体例

# Global gateway settings
group_sessions_per_user: true
unauthorized_dm_behavior: "pair"
stt_enabled: true

# Slack-specific settings
slack:
  require_mention: true
  unauthorized_dm_behavior: "pair"

# Platform config
platforms:
  slack:
    reply_to_mode: "first"
    extra:
      reply_in_thread: true
      reply_broadcast: false

ホームチャンネル

SLACK_HOME_CHANNEL にチャンネル ID を設定すると、Hermes は予定されたメッセージ、定期実行の結果、そのほか自分から送る通知をそのチャンネルに届けます。チャンネル ID の調べ方は次のとおりです。

1. Slack でチャンネル名を右クリックします
2. View channel details をクリックします
3. いちばん下までスクロールすると、チャンネル ID が表示されています

SLACK_HOME_CHANNEL=C01234567890

そのチャンネルに ボットを招待してある ことを確かめてください（/invite @Hermes Agent）。

定期実行の届け先の指定

定期実行のジョブ（定期実行の案内を見てください）では、Slack への届け先を 3 通りで指定できます。

定期実行の処理がゲートウェイと同じ場所で動いていなくても届きます。Hermes は SLACK_BOT_TOKEN を使う単独の Web API の送信に切り替えます。定期実行の出力にある MEDIA: の添付は、同じ届け先へ Slack 本来のファイル共有としてアップロードされます。

メッセージとメディアを送る（send_message）

エージェントの send_message のツールも同じ形の届け先を受け取ります。チャンネル ID（C… / G…）、個人チャットのやり取り（D…）、利用者 ID だけ（U… / W…）のいずれでも構いません。利用者 ID は、テキストでもメディアでも問いかけでも、どの送信経路でもその人との個人チャットに読み替えられます。MEDIA:<path> の添付（画像・PDF・文書）は Slack 本来のファイル共有としてアップロードされ、添付が 1 つで短いメッセージが添えられている場合は、別のメッセージではなくファイルの説明文として付きます。見つからないファイルは、送信全体を失敗させるのではなく、ファイルごとの警告として報告されます。

複数のワークスペースへの対応

Hermes は、1 つのゲートウェイで 複数の Slack ワークスペース に同時につなげます。ワークスペースごとに、それぞれのボットの利用者 ID で別々に認証します。

設定

SLACK_BOT_TOKEN に、複数のボットトークンを カンマ区切りの一覧 で渡します。

# Multiple bot tokens — one per workspace
SLACK_BOT_TOKEN=xoxb-workspace1-token,xoxb-workspace2-token,xoxb-workspace3-token

# A single app-level token is still used for Socket Mode
SLACK_APP_TOKEN=xapp-your-app-token

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

platforms:
  slack:
    token: "xoxb-workspace1-token,xoxb-workspace2-token"

OAuth のトークンファイル

環境変数や設定ファイルのトークンに加えて、Hermes は次の場所にある OAuth のトークンファイル からもトークンを読み込みます。

~/.hermes/slack_tokens.json

このファイルは、チーム ID とトークンの情報を対応させた JSON のオブジェクトです。

{
  "T01ABC2DEF3": {
    "token": "xoxb-workspace-token-here",
    "team_name": "My Workspace"
  }
}

このファイルのトークンは、SLACK_BOT_TOKEN で指定したトークンとまとめて扱われます。重複するトークンは自動で取り除かれます。

しくみ

• 一覧の 最初のトークン が主のトークンで、ソケットモードの接続（AsyncApp）に使われます。
• 起動時に、それぞれのトークンが auth.test で認証されます。ゲートウェイは team_id ごとに専用の WebClient と bot_user_id を対応させます。
• メッセージが届くと、Hermes はそのワークスペースに合ったクライアントを使って返事をします。
• 主の bot_user_id（最初のトークンのもの）は、ボットの身元が 1 つであることを前提にした機能との互換のために使われます。

ボイスメッセージ

Hermes は Slack でも音声に対応しています。

• 受け取り: 音声のメッセージは、設定した書き起こしのサービスで自動的に文字にされます。手元で動く faster-whisper、Groq の Whisper（GROQ_API_KEY）、OpenAI の Whisper（VOICE_TOOLS_OPENAI_KEY）が使えます
• 送り出し: 読み上げの応答は、音声ファイルの添付として送られます

チャンネルごとの指示

特定の Slack チャンネルに、その場限りのシステムの指示を割り当てられます。この指示はやり取りのたびに実行時に差し込まれ、会話の記録には残らないので、変更はすぐに効きます。

slack:
  channel_prompts:
    "C01RESEARCH": |
      You are a research assistant. Focus on academic sources,
      citations, and concise synthesis.
    "C02ENGINEERING": |
      Code review mode. Be precise about edge cases and
      performance implications.

見出しにあたるのは Slack のチャンネル ID です（チャンネルの詳細 →「About」を開いて下までスクロールすると分かります）。そのチャンネルのすべてのメッセージに、この指示がその場限りのシステムの指示として差し込まれます。

チャンネルごとのスキルの割り当て

特定のチャンネルや個人チャットで新しいセッションが始まるたびに、スキルを自動で読み込ませられます。やり取りのたびに差し込まれるチャンネルごとの指示とは違い、スキルの割り当てはスキルの内容を セッションの開始時に 利用者のメッセージとして差し込みます。それが会話の履歴の一部になるので、以降のやり取りで読み込み直す必要はありません。

用途がはっきり決まっている個人チャットやチャンネル（暗記カード、特定分野の質問応答、サポートの一次受けなど）で、短い返信のたびにモデル自身の判断で読み込むかどうかを決めさせたくない場合に向いています。

slack:
  channel_skill_bindings:
    # DM channel — always runs in "german-flashcards" mode
    - id: "D0ATH9TQ0G6"
      skills:
        - german-flashcards
    # Research channel — preload multiple skills in order
    - id: "C01RESEARCH"
      skills:
        - arxiv
        - writing-plans
    # Short form: single skill as a string
    - id: "C02SUPPORT"
      skill: hubspot-on-demand

補足です。

• 割り当てはチャンネル ID で判定します。割り当てのあるチャンネルのスレッドのメッセージは、親のチャンネルの割り当てを引き継ぎます。
• スキルが読み込まれるのはセッションの開始時（新しいセッション、または自動でのリセットのあと）だけです。割り当てを変えたときは、/new を実行するか、セッションが自動でリセットされるのを待つと反映されます。
• スキルの指示に加えて、チャンネルごとの口調や制約を足したいときは channel_prompts と組み合わせてください。

困ったときは

チェックリスト

チャンネルでボットが動かないときは、次の すべて を確かめてください。

1. ✅ message.channels のイベントを購読している（公開チャンネル用）
2. ✅ message.groups のイベントを購読している（非公開チャンネル用）
3. ✅ app_mention のイベントを購読している
4. ✅ channels:history のスコープを足している（公開チャンネル用）
5. ✅ groups:history のスコープを足している（非公開チャンネル用）
6. ✅ スコープやイベントを足したあとにアプリを 入れ直した
7. ✅ ボットをチャンネルに 招待した（/invite @Hermes Agent）
8. ✅ メッセージでボットに @メンションしている

安全に使うために

• トークンは ~/.hermes/.env（ファイルの権限は 600）に置きます
• Slack アプリの設定から、トークンを定期的に入れ替えます
• Hermes の設定ディレクトリに誰が触れるかを見直します
• ソケットモードでは公開のエンドポイントを出さずに済むので、攻撃されうる面がひとつ減ります