Discord の設定

Hermes Agent はボットとして Discord と連携し、ダイレクトメッセージやサーバーのチャンネルから AI アシスタントと話せるようにします。ボットはメッセージを受け取り、Hermes Agent の処理（ツールの利用、記憶、推論を含みます）を通してその場で返答します。テキスト、音声メッセージ、添付ファイル、スラッシュコマンドに対応しています。

設定の前に、多くの人が知りたい点から説明します。サーバーに入れたあと、Hermes がどう振る舞うかです。

Hermes の振る舞い

Discord のゲートウェイの考え方

Discord での Hermes は、状態を持たずに返事をする Webhook ではありません。メッセージングゲートウェイをひととおり通るので、届いたメッセージはそれぞれ次を経由します。

1. 認可（DISCORD_ALLOWED_USERS）
2. メンションやメンション不要の判定
3. セッションの検索
4. セッションの記録の読み込み
5. ツール、記憶、スラッシュコマンドを含む、通常の Hermes のエージェントの実行
6. Discord への応答の送信

にぎやかなサーバーでの振る舞いが、Discord 側の振り分けと Hermes のセッションの方針の両方で決まるのは、このためです。

Discord でのセッションの考え方

既定では次のとおりです。

• DM ごとに別のセッション
• サーバーのスレッドごとに別のセッションの名前空間
• 共有のチャンネルでは、そのチャンネルの中でユーザーごとに別のセッション

つまり、Alice と Bob がどちらも #research で Hermes と話している場合、見た目には同じ Discord のチャンネルでも、Hermes は既定では別々の会話として扱います。

これは config.yaml で制御します。

group_sessions_per_user: true

部屋全体で 1 つの会話にしたいと明確に決めた場合だけ、false にしてください。

group_sessions_per_user: false

共有のセッションは共同作業の部屋には便利ですが、次のことも意味します。

• 文脈の増え方とトークンの費用を全員で分け合う
• 誰か 1 人のツールを多用する長い作業が、ほかの全員の文脈を膨らませる
• 誰か 1 人の実行中の処理が、同じ部屋のほかの人の追加の質問に割り込む

割り込みと同時実行

Hermes は実行中のエージェントをセッションのキーで管理します。

既定の group_sessions_per_user: true では次のとおりです。

• Alice が自分の実行中の依頼に割り込んでも、そのチャンネルでの Alice のセッションにしか影響しません
• Bob は Alice の履歴を引き継ぐことも、Alice の処理に割り込むこともなく、同じチャンネルで話し続けられます

group_sessions_per_user: false では次のとおりです。

• そのチャンネルやスレッドについて、部屋全体で 1 つの実行枠を共有します
• 別の人からの追加のメッセージが、互いに割り込んだり順番待ちになったりします

この解説では、Discord の開発者ポータルでボットを作るところから最初のメッセージを送るところまで、設定の流れをひととおり見ていきます。

ゲートウェイの WebSocket の健全性

Discord の REST と Gateway の WebSocket は別々の通信路です。REST の応答が成功しても（fetch_user() が HTTP 200 を返しても）、ボットが Gateway のイベントをまだ受け取れる証拠にはなりません。そこで Hermes は、準備完了の状態、クライアントとソケットの終了の状態、ソケットが開いているか、ハートビートの確認からの経過時間、そしてハートビートの遅延が有限かどうかを組み合わせて判断します。

設定した回数だけ連続して不健全と判定されると、アダプターはやり直し可能な致命的イベントを 1 回出します。既存のゲートウェイの再接続の監視が新しいアダプターを作るので、Discord のアダプター側が終わりのない再接続のループをもう 1 つ始めることはありません。

秘密ではない閾値は config.yaml で設定します。

discord:
  websocket_liveness_interval_seconds: 15
  websocket_liveness_failure_threshold: 2
  websocket_heartbeat_ack_max_age_seconds: 60
  websocket_max_latency_seconds: 30

以前の liveness_interval_seconds と liveness_failure_threshold という名前は互換のための別名として残っているだけで、REST での確認を意味しなくなりました。

手順 1: Discord のアプリケーションを作る

1. Discord 開発者ポータル を開き、Discord のアカウントでサインインします。
2. 右上の New Application を押します。
3. アプリケーションの名前（例: 「Hermes Agent」）を入れ、開発者向けの利用規約に同意します。
4. Create を押します。

General Information のページが開きます。Application ID は、あとで招待用の URL を作るときに使うので控えておいてください。

手順 2: ボットを作る

1. 左のサイドバーで Bot を押します。
2. Discord がアプリケーション用のボットのユーザーを自動で作ります。ボットのユーザー名が表示され、変更もできます。
3. Authorization Flow の下で次のようにします。

• Public Bot を ON にします。Discord が用意する招待リンク（おすすめの方法）を使うのに必要です。これで Installation のタブから既定の認可 URL を作れます。
• Require OAuth2 Code Grant は OFF のままにします。

手順 3: 特権 Gateway インテントを有効にする

設定全体でいちばん大事な手順です。正しいインテントを有効にしていないと、ボットは Discord につながるのにメッセージの中身を読めません。

Bot のページを下にたどると Privileged Gateway Intents があります。切り替えが 3 つ並んでいます。

Server Members Intent と Message Content Intent の両方を ON にしてください。

• Message Content Intent がないと、ボットはメッセージのイベントを受け取っても本文が空になります。入力した内容が文字どおり見えません。
• Server Members Intent がないと、許可ユーザーの一覧のためにユーザー名を解決できず、誰がメッセージを送ってきたのか判別できないことがあります。

サーバー数について:

• ボットが入っているサーバーが 100 未満なら、インテントは自由に切り替えられます。
• 100 以上のサーバーに入っている場合、特権インテントを使うには Discord への認証の申請が必要です。個人で使う分には関係ありません。

ページの下にある Save Changes を押します。

手順 4: ボットのトークンを取得する

ボットのトークンは、Hermes Agent がボットとしてログインするための認証情報です。Bot のページのまま進めます。

1. Token の欄で Reset Token を押します。
2. Discord のアカウントで二要素認証を有効にしている場合は、2FA のコードを入れます。
3. 新しいトークンが表示されます。すぐにコピーしてください。

トークンは安全な場所（パスワード管理ツールなど）に保管してください。手順 8 で使います。

手順 5: 招待用の URL を作る

ボットをサーバーに招待するには OAuth2 の URL が必要です。作り方は 2 通りあります。

方法 A: Installation のタブを使う（おすすめ）

1. 左のサイドバーで Installation を押します。
2. Installation Contexts で Guild Install を有効にします。
3. Install Link では Discord Provided Link を選びます。
4. Guild Install の Default Install Settings で次のようにします。

• Scopes: bot と applications.commands を選ぶ
• Permissions: 下に挙げた権限を選ぶ

方法 B: 手動の URL

招待用の URL は、次の形で自分で組み立てられます。

https://discord.com/oauth2/authorize?client_id=YOUR_APP_ID&scope=bot+applications.commands&permissions=274878286912

YOUR_APP_ID は、手順 1 の Application ID に置き換えてください。

必要な権限

ボットに最低限必要な権限は次のとおりです。

• View Channels — アクセスできるチャンネルを見る
• Send Messages — メッセージに返信する
• Embed Links — 内容の整った応答を作る
• Attach Files — 画像、音声、出力ファイルを送る
• Read Message History — 会話の文脈を保つ

追加でおすすめの権限

• Send Messages in Threads — スレッドの会話で返信する
• Add Reactions — 受け取ったことを示すリアクションを付ける

権限の数値

手順 6: サーバーに招待する

1. 招待用の URL（Installation のタブから作ったもの、または自分で組み立てたもの）をブラウザで開きます。
2. Add to Server の一覧から自分のサーバーを選びます。
3. Continue を押し、続けて Authorize を押します。
4. 求められたら CAPTCHA に答えます。

認可が終わると、ボットがサーバーのメンバー一覧に現れます（Hermes のゲートウェイを起動するまではオフラインの表示です）。

手順 7: 自分の Discord のユーザー ID を調べる

Hermes Agent は、誰がボットとやり取りできるかを Discord のユーザー ID で制御します。調べ方は次のとおりです。

1. Discord（デスクトップ版か Web 版）を開きます。
2. 設定 → 詳細設定 と進み、開発者モードを ON にします。
3. 設定を閉じます。
4. 自分のユーザー名（メッセージ、メンバー一覧、プロフィールのどれでも）を右クリックし、ユーザー ID をコピーを選びます。

ユーザー ID は 284102345871466496 のような長い数字です。

手順 8: Hermes Agent を設定する

方法 A: 対話式セットアップ（おすすめ）

案内つきのセットアップのコマンドを実行します。

hermes gateway setup

聞かれたら Discord を選び、ボットのトークンとユーザー ID を貼り付けます。

方法 B: 手動で設定する

~/.hermes/.env に次を追加します。

# Required
DISCORD_BOT_TOKEN=your-bot-token
DISCORD_ALLOWED_USERS=284102345871466496

# Multiple allowed users (comma-separated)
# DISCORD_ALLOWED_USERS=284102345871466496,198765432109876543

そのうえでゲートウェイを起動します。

hermes gateway

数秒で Discord 上のボットがオンラインになります。DM か、ボットが見えるチャンネルでメッセージを送って試してください。

設定の一覧

Discord の振る舞いは 2 つのファイルで決まります。認証情報と環境変数レベルの切り替えは ~/.hermes/.env、構造のある設定は ~/.hermes/config.yaml です。両方に書いた場合は、常に環境変数が優先されます。

環境変数（.env）

設定ファイル（config.yaml）

~/.hermes/config.yaml の discord の節は、上の環境変数と同じ内容を扱います。config.yaml の設定は既定値として適用されるので、対応する環境変数がすでに設定されていればそちらが勝ちます。

# Discord-specific settings
discord:
  require_mention: true           # Require @mention in server channels
  thread_require_mention: false   # If true, require @mention in threads too (multi-bot threads)
  free_response_channels: ""      # Comma-separated channel IDs (or YAML list)
  auto_thread: true               # Auto-create threads on @mention
  reactions: true                 # Add emoji reactions during processing
  ignored_channels: []            # Channel IDs where bot never responds
  no_thread_channels: []          # Channel IDs where bot responds without threading
  history_backfill: true          # Prepend recent channel scrollback on mention (default: true)
  history_backfill_limit: 50      # Max messages to scan backwards (default: 50)
  missed_message_backfill:        # Replay messages missed while disconnected (opt-in)
    enabled: false
    channels: []                  # Empty uses free_response_channels
    window_seconds: 21600         # Look back at most 6 hours
    limit: 100                    # Global scan cap per reconnect
    max_dispatches: 10            # Recovery dispatch cap per reconnect
  channel_prompts: {}             # Per-channel ephemeral system prompts
  voice_channel_inactivity_timeout_seconds: 300  # Set 0 to stay in VC until explicit /voice leave
  voice_playback_timeout_seconds: 120             # Minimum playback watchdog; long clips get duration+padding
  allow_mentions:                 # What the bot is allowed to ping (safe defaults)
    everyone: false               # @everyone / @here pings (default: false)
    roles: false                  # @role pings (default: false)
    users: true                   # @user pings (default: true)
    replied_user: true            # reply-reference pings the author (default: true)

# Session isolation (applies to all gateway platforms, not just Discord)
group_sessions_per_user: true     # Isolate sessions per user in shared channels

discord.require_mention

型: 真偽値 — 既定: true

有効なとき、ボットはサーバーのチャンネルでは直接 @mentioned されたときだけ応答します。DM はこの設定に関わらず必ず応答します。

discord.thread_require_mention

型: 真偽値 — 既定: false

既定では、ボットがいったんスレッドに参加すると（@mention で自動作成された、あるいは一度返信した）、そのスレッドではあらためて @mentioned されなくても以降のすべてのメッセージに応答し続けます。1 対 1 の会話にはこれが適切な既定です。

ただし、1 つのスレッドに複数のボットがいて、その都度どれか 1 つに話しかける使い方では、この既定が裏目に出ます。スレッドにいるほかのボットまでメッセージのたびに動き、費用がかさみ、チャンネルが騒がしくなります。thread_require_mention: true にすると、スレッド内でメンションを省ける仕組みが無効になり、スレッドもチャンネルと同じ扱いになります。明示的な @mentions はこれまでどおり効きます。

discord:
  require_mention: true
  thread_require_mention: true    # multi-bot setup

discord.free_response_channels

型: 文字列またはリスト — 既定: ""

@mention なしですべてのメッセージに応答するチャンネルの ID です。カンマ区切りの文字列でも、YAML のリストでも書けます。

# String format
discord:
  free_response_channels: "1234567890,9876543210"

# List format
discord:
  free_response_channels:
    - 1234567890
    - 9876543210

スレッドの親のチャンネルがこの一覧にあれば、そのスレッドもメンション不要になります。

メンション不要のチャンネルでは自動でのスレッド作成も行いません。メッセージごとに新しいスレッドを作るのではなく、その場で返信します。こうすることで、チャンネルを気軽な会話の場として使えます。スレッドにしたい場合は、そのチャンネルをメンション不要に含めず、通常の @mention の流れを使ってください。

discord.auto_thread

型: 真偽値 — 既定: true

有効なとき、通常のテキストチャンネルでの @mention ごとに、会話用の新しいスレッドが自動で作られます。本体のチャンネルが散らからず、会話ごとに独立したセッションの履歴を持てます。スレッドができてしまえば、その中の以降のメッセージに @mention は要りません。ボットは自分が参加していることを知っています。複数のボットがいる構成でスレッド内のこの省略をやめたい場合は、thread_require_mention を true にしてください。

すでにあるスレッドや DM に送ったメッセージは、この設定の影響を受けません。discord.free_response_channels や discord.no_thread_channels に挙げたチャンネルも自動でのスレッド作成を行わず、その場での返信になります。

discord.reactions

型: 真偽値 — 既定: true

処理の状況を目で追えるように、ボットがメッセージへ絵文字のリアクションを付けるかどうかを決めます。

• 👀 メッセージの処理を始めたとき
• ✅ 応答が無事に届いたとき
• ❌ 処理の途中でエラーが起きたとき

リアクションが気になる場合や、ボットのロールに Add Reactions の権限がない場合は無効にしてください。

discord.ignored_channels

型: 文字列またはリスト — 既定: []

直接 @mentioned されても絶対に応答しないチャンネルの ID です。これがいちばん優先されます。一覧にあるチャンネルでは、require_mention や free_response_channels などほかの設定に関わらず、すべてのメッセージが黙って無視されます。

# String format
discord:
  ignored_channels: "1234567890,9876543210"

# List format
discord:
  ignored_channels:
    - 1234567890
    - 9876543210

スレッドの親のチャンネルがこの一覧にあれば、そのスレッドのメッセージも無視されます。

discord.no_thread_channels

型: 文字列またはリスト — 既定: []

スレッドを自動で作らず、チャンネルの中で直接応答するチャンネルの ID です。auto_thread が true（既定）のときにだけ効きます。これらのチャンネルでは、新しいスレッドを作らず普通のメッセージのようにその場で返信します。

discord:
  no_thread_channels:
    - 1234567890  # Bot responds inline here

ボットとのやり取り専用のチャンネルで、スレッドがかえって邪魔になる場合に便利です。

discord.channel_prompts

型: 対応表 — 既定: {}

チャンネルごとの一時的なシステムプロンプトです。該当する Discord のチャンネルやスレッドでは毎ターン差し込まれ、会話の記録には残りません。

discord:
  channel_prompts:
    "1234567890": |
      This channel is for research tasks. Prefer deep comparisons,
      citations, and concise synthesis.
    "9876543210": |
      This forum is for therapy-style support. Be warm, grounded,
      and non-judgmental.

挙動:

• スレッドやチャンネルの ID がぴったり一致するものが優先されます。
• スレッドやフォーラムの投稿にメッセージが届き、そのスレッドに設定がない場合、Hermes は親のチャンネルやフォーラムの ID の設定に戻ります。
• プロンプトは実行時に一時的に適用されるので、変更すれば過去の記録を書き換えずに次のターンからすぐ反映されます。

discord.history_backfill

型: 真偽値 — 既定: true

有効なとき、@mention のたびに、取りこぼしたチャンネルのメッセージを拾い直します。require_mention: true では、ボットは自分をタグ付けしたメッセージしか処理しないため、チャンネルのそれ以外のやり取りはセッションの記録から見えません。この補完は、呼ばれた時点でチャンネルの直近の履歴をさかのぼり、ボットの最後の応答から今回のメンションまでのメッセージを集めて文脈に含めます。

場面ごとの挙動は次のとおりです。

• サーバーのチャンネル（require_mention: true のとき）: ボットの最後の応答以降のチャンネルを調べます。ボットが呼ばれていない間にほかの人が書き込んでいた場合に役立ちます。
• スレッド: そのスレッドだけを調べます。Discord の channel.history() はスレッドに対してそのスレッドのメッセージだけを返し、親のチャンネルは含みません。スレッドはたいてい完結した会話なので、これで適切です。
• DM: 行いません。DM はすべてのメッセージがボットを動かすので、セッションの記録はすでに完全です。埋めるべき隙間がありません。
• メンション不要のチャンネルとボット自身が自動で作ったスレッド: 同じ理由で行いません。メンションで絞っていないので隙間が生まれません。

ユーザーごとのセッション（既定の group_sessions_per_user: true）でも効きます。そのユーザーのセッションには、チャンネルのほかの参加者が書いた内容も、タグ付けする前の自分のメッセージも入っていません。補完はその両方を埋めます。

discord:
  history_backfill: true   # default

無効にするには次のようにします。

discord:
  history_backfill: false

> 補足: ボットが処理している*最中*に届いたメッセージ（呼び出しから応答までの間のもの）は拾われません。これは割り切った仕様で、必要なら送り直すか、もう一度タグ付けしてください。

discord.history_backfill_limit

型: 整数 — 既定: 50

チャンネルの文脈を拾い直すときに、さかのぼって調べるメッセージの最大数です。実際にはもっと手前で止まるのが普通で、そのチャンネルでのボット自身の最後のメッセージが、ターンとターンの自然な境目になります。この上限は、直近の履歴にボットのメッセージがない、起動直後や間隔が空いた場合のための安全弁です。

discord:
  history_backfill: true
  history_backfill_limit: 50

discord.missed_message_backfill

型: オブジェクト — 既定: 無効

Discord の WebSocket の再開の猶予は、再起動やネットワークの障害の間に切れることがあります。その間に送られたメッセージは、その場のゲートウェイのイベントとしては届きません。この設定を有効にすると、Discord につなぎ直したあとに Hermes が設定したチャンネルとスレッドの履歴を範囲を限って調べ、まだ処理していないメッセージを、その場のイベントと同じ認可・メンション・チャンネル・重複除去・振り分けの経路に通します。

discord:
  missed_message_backfill:
    enabled: true
    channels: ["123456789012345678"]
    window_seconds: 3600
    limit: 100
    max_dispatches: 10

channels が空のとき、Hermes は discord.free_response_channels を使います。"*" にするのは、到達できるサーバーのテキストチャンネルをすべて調べさせたいときだけにしてください。処理済みの記録はプロファイルごとに gateway/discord_message_recovery.db に保存され、いちど答えたメッセージがあとの再起動で再び処理されるのを防ぎます。

group_sessions_per_user

型: 真偽値 — 既定: true

これは Discord に限らないゲートウェイ全体の設定で、同じチャンネルにいるユーザーどうしのセッションの履歴を分けるかどうかを決めます。

true のとき、#research で話している Alice と Bob は、それぞれ別々の会話を Hermes と持ちます。false のとき、チャンネル全体で 1 つの会話の記録と 1 つの実行枠を共有します。

group_sessions_per_user: true

それぞれのモードの意味は、上の セッションの考え方 の節をご覧ください。

display.tool_progress

型: 文字列 — 既定: "all" — 値: off、new、all、verbose

処理中にチャットへ進捗のメッセージ（「Reading file...」「Running terminal command...」など）を送るかどうかを決めます。すべてのプラットフォームに効く、ゲートウェイ全体の設定です。

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

• off — 進捗のメッセージを出さない
• new — ターンごとに最初のツール呼び出しだけ出す
• all — すべてのツール呼び出しを出す（ゲートウェイのメッセージでは 40 文字に切り詰めます）
• verbose — ツール呼び出しの詳細をすべて出す（メッセージが長くなることがあります）

display.tool_progress_command

型: 真偽値 — 既定: false

有効にすると、ゲートウェイで /verbose のスラッシュコマンドが使えるようになり、config.yaml を編集せずに進捗の表示モード（off → new → all → verbose → off）を切り替えられます。

display:
  tool_progress_command: true

display.reasoning_style

型: 文字列 — 既定（Discord）: "subtext" — 値: code、blockquote、subtext

推論の表示を有効にしたとき、モデルの推論の部分をどう描くかを決めます。Discord の既定は subtext で、Discord 本来の -# による小さな灰色の補助表示を使うため、推論は答えより控えめに見えます。blockquote は > の引用として、code（ほかのプラットフォームでの既定）はコードブロックとして描きます。長い推論は先頭 15 行にまとめられます。

display:
  platforms:
    discord:
      reasoning_style: subtext   # code | blockquote | subtext

スラッシュコマンドの権限管理

既定では、許可されたユーザーは全員がすべてのスラッシュコマンドを実行できます。許可リストを管理者（スラッシュコマンドをすべて使える）と通常のユーザー（明示的に許可したコマンドだけ）に分けるには、Discord のプラットフォームの extra に allow_admin_from と user_allowed_commands を追加します。

gateway:
  platforms:
    discord:
      extra:
        # Existing user allowlist (unchanged)
        allow_from:
          - "123456789012345678"  # admin user ID
          - "999888777666555444"  # regular user ID

        # NEW — admins get all slash commands (built-in + plugin)
        allow_admin_from:
          - "123456789012345678"

        # NEW — non-admin allowed users can only run these slash commands.
        # /help and /whoami are always allowed so users can see their access.
        user_allowed_commands:
          - status
          - model
          - history

        # Optional: separate admin / command lists for server channels
        group_allow_admin_from:
          - "123456789012345678"
        group_user_allowed_commands:
          - status

挙動:

• ある範囲（DM かサーバーのチャンネルか）で allow_admin_from に載っているユーザーは、稼働中のコマンドの登録簿を通じて、登録済みのスラッシュコマンドをすべて実行できます。組み込みのものも、プラグインが登録したものもです。
• allow_admin_from に載っていないユーザーは、user_allowed_commands に書いたコマンドと、常に許可される /help・/whoami だけを実行できます。
• 普通の会話（スラッシュでないメッセージ）には影響しません。管理者でないユーザーも、これまでどおりエージェントと話せます。任意のコマンドを実行できないだけです。
• 以前の設定との互換性: ある範囲で allow_admin_from を設定していなければ、その範囲ではスラッシュコマンドの制限が無効になります。既存の環境は何も変えずにそのまま動きます。
• DM の管理者だからといってサーバーのチャンネルの管理者になるわけではありません。範囲ごとに別々の管理者リストがあります。

/whoami を使うと、現在の範囲、自分の段階（admin / user / unrestricted）、実行できるスラッシュコマンドがわかります。

対話式のモデル選択

Discord のチャンネルで引数なしの /model を送ると、ドロップダウン形式のモデル選択が開きます。

1. プロバイダーの選択 — 利用できるプロバイダーを並べたドロップダウン（最大 25 件）。
2. モデルの選択 — 選んだプロバイダーのモデルを並べた 2 つ目のドロップダウン（最大 25 件）。

選択画面は 120 秒で閉じます。操作できるのは許可されたユーザー（DISCORD_ALLOWED_USERS に載っている人）だけです。モデル名がわかっているなら、/model <name> と直接打ってください。

スキルのネイティブなスラッシュコマンド

Hermes は、導入済みのスキルを Discord のネイティブなアプリケーションコマンドとして自動で登録します。つまり、Discord の / の入力補完に、組み込みのコマンドと並んでスキルが出てきます。

• スキルはそれぞれ Discord のスラッシュコマンドになります（例: /code-review、/ascii-art）
• スキルは任意の args という文字列の引数を受け取れます
• Discord のアプリケーションコマンドはボットごとに 100 件までです。スキルが枠より多い場合、あふれた分はログに警告を出して飛ばされます
• スキルは、/model、/reset、/bg などの組み込みコマンドと一緒に、ボットの起動時に登録されます

追加の設定は要りません。hermes skills install で入れたスキルは、次にゲートウェイを再起動したときに Discord のスラッシュコマンドとして自動で登録されます。

スラッシュコマンドの登録を止める

同じ Discord のアプリケーションに対して複数の Hermes のゲートウェイを動かしている場合（検証用と本番など）、全体のスラッシュコマンドの登録を持つのは 1 つだけにすべきです。そうしないと、最後に起動したものが勝って登録が行ったり来たりします。追従する側のゲートウェイでは登録を切ってください。

gateway:
  platforms:
    discord:
      extra:
        slash_commands: false   # default: true

主となるゲートウェイで true のままにしておけば、組み込みのコマンドと導入済みのスキルが / のメニューに出る、通常の挙動になります。

メディアを送る（本文中の MEDIA: の印）

Discord のアダプターは、エージェントの応答に書かれた MEDIA:/path/to/file の印を通じて、よく使うメディアの形式すべてをネイティブのファイルとしてアップロードできます。アダプターはその印を取り除き、ファイルを自動でアップロードします。

Discord の 1 回あたりのアップロードの上限は、サーバーのブーストの段階で変わります（無料で 25 MB、最大 500 MB）。Hermes が HTTP 413 を受け取った場合、黙って失敗するのではなく、ローカルのキャッシュのパスを指すリンクに切り替えます。

どんな種類のファイルでも受け取る

ユーザーがアップロードするファイルは、種類を問わず受け付けます。関門になるのはエージェントへメッセージを送る権限であって、拡張子ではありません。アップロードはすべてダウンロードされて ~/.hermes/cache/documents/ にキャッシュされ、DOCUMENT 型のメッセージのイベントとしてエージェントに渡されるので、terminal（ffprobe、unzip、file、strings など）や read_file で中身を調べられます。

• 既知の種類（PDF、docx/xlsx/pptx、zip、画像・音声・動画など）は、正確な MIME のまま扱われます。
• 知らない種類は、アップロード時に申告された内容種別に、それもなければ application/octet-stream に落ちます。
• UTF-8 として読める小さいファイル（テキスト、コード、設定、HTML、CSS、JSON、YAML など）は、100 KiB までなら中身がプロンプトへ自動で差し込まれます。読み取れないバイナリは、文脈の窓を膨らませないように、パスを指す注記だけが渡されます（Docker や Modal のサンドボックスのターミナル向けには to_agent_visible_cache_path で自動的に読み替えられます）。

受け取る側の制限は、ファイル 1 つあたりのサイズの上限（既定は 32 MiB）だけです。

discord:
  # Optional — raise/disable the per-file size cap. Default is 32 MiB.
  # The whole file is held in memory while being cached, so unlimited
  # uploads carry a real memory cost.
  max_attachment_bytes: 33554432   # bytes; 0 = unlimited

同じことを環境変数で書くと DISCORD_MAX_ATTACHMENT_BYTES=33554432 です（上限なしにするなら 0）。

以前からある discord.allow_any_attachment のフラグは何もしなくなりました。どの種類のファイルも常に受け付けるためで、既存の設定がエラーにならないように残してあるだけです。

対話的な問いかけ（clarify）

どの方針がよいかをたずねる、作業後の感想を集める、判断の前に確認する、といった目的でエージェントが clarify ツールを呼ぶと、Discord では質問が選択肢ごとのボタンとして表示されます。

> ダッシュボードにはどのフレームワークを使いましょうか? > > [1. Next.js] [2. Remix] [3. Astro] [その他（入力する）]

番号のボタンを押して答えるか、その他を押して自由に入力します（そのチャンネルで次に送ったメッセージが答えになります）。選択肢のない自由回答の clarify では、ボタンは出ず、次のメッセージがそのまま答えになります。

いちど選ぶとボタンは押せなくなるので、二重に押して二重に答えてしまうことはありません。回答の待ち時間は ~/.hermes/config.yaml の agent.clarify_timeout で設定します（既定は 600 秒）。時間内に答えないと、エージェントは待ち続けるのではなく、代わりの合図を受けて先へ進みます。

ホームチャンネル

ボットが自発的なメッセージ（cron ジョブの出力、リマインダー、通知など）を送る「ホームチャンネル」を指定できます。設定の方法は 2 つあります。

スラッシュコマンドを使う

ボットがいる Discord のチャンネルで /sethome と打ちます。そのチャンネルがホームチャンネルになります。

手動で設定する

~/.hermes/.env に次を追加します。

DISCORD_HOME_CHANNEL=123456789012345678
DISCORD_HOME_CHANNEL_NAME="#bot-updates"

ID の部分は実際のチャンネル ID に置き換えてください（開発者モードを有効にして、右クリック → チャンネル ID をコピー）。

音声メッセージ

Hermes Agent は Discord の音声メッセージに対応しています。

• 受け取った音声メッセージは、設定した音声認識のプロバイダーで自動的に文字起こしされます。ローカルの faster-whisper（キー不要）、Groq Whisper（GROQ_API_KEY）、OpenAI Whisper（VOICE_TOOLS_OPENAI_KEY）が使えます。
• 音声合成: /voice tts を使うと、テキストの返信と一緒に読み上げの音声も送られます。
• Discord のボイスチャンネル: Hermes はボイスチャンネルに入り、話している人の声を聞き、そのチャンネルで話し返すこともできます。

設定と運用の詳しい手順は次をご覧ください。

• 音声モード
• Hermes で音声モードを使う

ボイスチャンネルの音の演出（環境音と口頭の受け答え）

ボットがボイスチャンネルにいるとき、もっと会話らしい雰囲気にできます。作業を始める前に短く「let me look into that」と口頭で受け答えし、ツールを動かしている間は控えめな「考え中」の環境音を下に流します。話し始めると環境音が下がり、話し終わると戻ります。Grok の音声モードに近い感じです。

discord.py は 1 つの接続につき 1 つの音声の流れしか再生できないので、Hermes は送信側にソフトウェアのミキサーを入れて、環境音のループ、受け答え、音声合成の返信を 1 つの流れにまとめます。互いを打ち消さず重なって聞こえます。

これは既定では無効です。config.yaml で有効にします。

discord:
  voice_fx:
    enabled: true          # master switch
    ambient_enabled: true  # idle "thinking" bed while tools run
    ambient_path: ""       # custom loop file (any audio format); "" = built-in synthesised pad
    ambient_gain: 0.18     # idle bed loudness (0.0–1.0)
    duck_gain: 0.06        # ambient loudness while the bot is speaking
    speech_gain: 1.0       # TTS / acknowledgement loudness
    ack_enabled: true      # speak a short phrase before the first tool call of a turn
    ack_phrases:           # picked at random; set to [] to disable the spoken ack
      - "Let me look into that."
      - "One moment."
      - "Checking on that now."

補足:

• 明示的な /voice leave か手動での切断まで、ボットをボイスチャンネルに残しておきたい場合は voice_channel_inactivity_timeout_seconds: 0 を設定します。既定は従来どおり、300 秒の無操作で自動的に退出します。
• voice_playback_timeout_seconds は下限であって、長い音声合成に対する上限ではありません。Hermes は生成した音声の長さを調べ、設定した下限より長ければ duration + 30s だけ待ちます。
• 口頭の受け答えはターンにつき 1 回まで、ボットがボイスチャンネルにいてミキサーが動いているときだけ鳴ります。設定した音声合成のプロバイダーを使います。
• ambient_path には ffmpeg が読める形式のファイルを指定でき、切れ目なく繰り返されます。空のままにすると、組み込みの合成音が使われます（素材は不要です）。
• 設定はすべて .env ではなく config.yaml にあります。秘密ではなく振る舞いの設定だからです。
• voice_fx.enabled が false のときは、音声の再生は従来の一度きりの経路になり、何も変わりません。

フォーラムチャンネル

Discord のフォーラムチャンネル（種別 15）はメッセージを直接受け付けません。フォーラムへの投稿はすべてスレッドである必要があります。Hermes はフォーラムチャンネルを自動で見分け、そこへ送る必要があるときは新しいスレッドの投稿を作ります。そのため、テキストの返信、音声合成、画像、音声メッセージ、添付ファイルはどれも、エージェント側で特別なことをせずに動きます。

• スレッドの名前はメッセージの 1 行目から作られます（マークダウンの見出しの記号は取り除き、100 文字で切ります）。添付だけのメッセージのときは、ファイル名がスレッド名になります。
• 添付は新しいスレッドの最初のメッセージに一緒に載ります。別途アップロードする手順も、途中まで送られる状態もありません。
• 1 回の送信につき 1 つのスレッド: フォーラムへの送信ごとに新しいスレッドができます。同じフォーラムに続けて送れば、別々のスレッドになります。
• 判別は 3 段構え: まずチャンネルの一覧のキャッシュ、次にプロセス内の判定のキャッシュ、最後の手段として GET /channels/{id} の実際の問い合わせです（その結果はプロセスが生きている間は覚えておきます）。

一覧を更新すると（対応しているプラットフォームでの /channels refresh、またはゲートウェイの再起動）、ボットの起動後に作られたフォーラムチャンネルもキャッシュに入ります。

うまくいかないとき

ボットはオンラインなのにメッセージへ反応しない

原因: Message Content Intent が無効になっているか、アクセスの方針が何も設定されておらず Discord の認可が安全側に倒れて拒否しています。

対処:

1. 開発者ポータル → 自分のアプリ → Bot → Privileged Gateway Intents と進み、Message Content Intent を有効にして Save Changes を押します。
2. Discord のアクセスの方針が少なくとも 1 つ設定されているか確認します。

# recommended: allow specific users
DISCORD_ALLOWED_USERS=284102345871466496

# or allow a trusted guild/dev bot to behave like pre-0.18 Discord
DISCORD_ALLOW_ALL_USERS=true

1. ゲートウェイを再起動します。

hermes gateway restart

ゲートウェイのログでは Discord に接続できていて REST API の確認も通るのに、届いたメッセージがすべて無反応なら、~/.hermes/logs/gateway.log に次の警告が出ていないか探してください。

No Discord access policy configured; inbound Discord messages will be denied by default.

Hermes 0.18 は、外から届く経路のアダプターでは意図的に安全側へ倒れます。DISCORD_ALLOWED_USERS も DISCORD_ALLOWED_ROLES も DISCORD_ALLOWED_CHANNELS も、明示的な全許可のフラグもない Discord のボットは、接続には成功しますが、通常のメッセージの処理より前に届いたユーザーを拒否します。

起動時の「Privileged intents」／PrivilegedIntentsRequired のエラー

原因: 開発者ポータルで有効にしていない特権 Gateway インテントを Hermes が要求しています。Discord はそれを理由に WebSocket の接続を拒否します。Hermes は常に Message Content Intent を要求します。また、許可リストに（数値の ID ではなく）ユーザー名を使っている場合や DISCORD_ALLOWED_ROLES を設定している場合は Server Members Intent も要求します。Presence Intent は不要です。

対処:

1. 開発者ポータル → 自分のアプリ → Bot → Privileged Gateway Intents と進みます。
2. Message Content Intent を有効にします（必須）。ユーザー名やロールの許可リストを使っている場合は Server Members Intent も有効にします。
3. Save Changes を押し、ゲートウェイを再起動します（hermes gateway restart）。

ゲートウェイのログには、Hermes が要求したインテントの名前が出ます。有効にするまで Discord は接続を拒み続けます。これはポータルの設定の誤りであって、ネットワークが不安定なわけではありません。

特定のチャンネルでボットがメッセージを見られない

原因: ボットのロールに、そのチャンネルを見る権限がありません。

対処: Discord でそのチャンネルの設定 → 権限 と進み、View Channel と Read Message History を有効にしたボットのロールを追加します。

403 Forbidden のエラー

原因: ボットに必要な権限が足りていません。

対処: 手順 5 の URL を使って正しい権限で招待し直すか、サーバー設定 → ロール でボットのロールの権限を手動で調整します。

ボットがオフライン

原因: Hermes のゲートウェイが動いていないか、トークンが正しくありません。

対処: hermes gateway が動いているか確認します。.env の DISCORD_BOT_TOKEN も確かめてください。最近トークンをリセットしたなら、書き換えが必要です。

「User not allowed」／ボットに無視される

原因: ユーザー ID が DISCORD_ALLOWED_USERS に入っていません。

対処: ~/.hermes/.env の DISCORD_ALLOWED_USERS に自分のユーザー ID を追加し、ゲートウェイを再起動します。

同じチャンネルにいる人どうしで、意図せず文脈が共有される

原因: group_sessions_per_user が無効になっているか、その場面のメッセージについてプラットフォームがユーザー ID を出せていません。

対処: ~/.hermes/config.yaml に次を設定し、ゲートウェイを再起動します。

group_sessions_per_user: true

部屋で 1 つの会話を共有したいのであれば、無効のままで構いません。ただし、記録も割り込みの挙動も共有になることは想定しておいてください。

セキュリティ

ロールによる権限管理

個々のユーザーの一覧ではなくロールで権限を管理しているサーバー（運営チーム、サポート担当、社内ツールなど）では、DISCORD_ALLOWED_ROLES にロール ID をカンマ区切りで指定します。そのロールを持つメンバーは許可されます。

# ~/.hermes/.env — works alongside or instead of DISCORD_ALLOWED_USERS
DISCORD_ALLOWED_ROLES=987654321098765432,876543210987654321

意味は次のとおりです。

• ユーザーの許可リストとは OR。 ユーザーの ID が DISCORD_ALLOWED_USERS にあるか、DISCORD_ALLOWED_ROLES のどれかのロールを持っていれば許可されます。
• Server Members Intent が自動で有効になる。 DISCORD_ALLOWED_ROLES を設定すると、接続時に Members のインテントが有効になります。Discord がメンバーの記録にロールの情報を載せて送るのに必要です。
• 名前ではなくロール ID。 Discord で取得します。ユーザー設定 → 詳細設定 → 開発者モードを ON にして、ロールを右クリック → ロール ID をコピー です。
• DM での判定。 DM では、共通して入っているサーバーを調べます。どこか 1 つでも共有するサーバーで許可されたロールを持っていれば、DM でも許可されます。

運営チームの入れ替わりが多いときは、この形がおすすめです。.env の編集もゲートウェイの再起動もなしに、ロールを与えた瞬間から新しい担当者が使えます。

メンションの制御

既定では、返信にその文字列が含まれていても、Hermes はボットが @everyone、@here、ロールのメンションで通知を飛ばすのを止めます。書き方のまずいプロンプトや、ユーザーの発言をそのまま繰り返した文が、サーバー全体に通知を飛ばすのを防ぐためです。個々の @user への通知と、返信の参照による通知（「〜への返信」の小さな表示）は普通の会話に必要なので有効のままです。

この既定は、環境変数でも config.yaml でも緩められます。

# ~/.hermes/config.yaml
discord:
  allow_mentions:
    everyone: false      # allow the bot to ping @everyone / @here
    roles: false         # allow the bot to ping @role mentions
    users: true          # allow the bot to ping individual @users
    replied_user: true   # ping the author when replying to their message

# ~/.hermes/.env — env vars win over config.yaml
DISCORD_ALLOW_MENTION_EVERYONE=false
DISCORD_ALLOW_MENTION_ROLES=false
DISCORD_ALLOW_MENTION_USERS=true
DISCORD_ALLOW_MENTION_REPLIED_USER=true

Hermes Agent の運用を安全にする方法については、セキュリティの手引き をご覧ください。