Hermes Agent 完全構築設計図

はじめに：Mac mini を自律型 AI サーバーに変える

Hermes Agent は、Mac mini 上に構築する常駐型 Discord AI ボットです。OpenAI Codex（gpt-5.3-codex）を思考エンジンとし、Discord Gateway 経由でいつでも対話可能な自律エージェントを実現します。本設計図では、仮想環境の展開から LaunchDaemon によるヘッドレス常駐化まで、確実な手順を解説します。

Hermes Agent 完全構築設計図表紙 — Page 1 - Mac miniを最強の常駐型Discord AIボットに変える確実なステップ

この記事で学べること

Hermes Agent の4層システムアーキテクチャ（Hardware → Environment → Core → Interfaces）
Phase 1: コアシステムと Python 仮想環境の展開
認証無限ループの突破（CLI 先行認証のバイパスルート）
Phase 2: Discord Bot の Privileged Intents と OAuth2 設定
Gateway クラッシュの解剖と discord.py の修復
ログ診断マトリクス：致命傷とノイズの分離
Phase 4: LaunchDaemon によるヘッドレス常駐化
ゴールデン・コマンド・ツールキットと最終確認

システム・アーキテクチャの全容

Hermes Agent は単なる CLI ツールではなく、仮想環境、OS のデーモン、外部 API を緻密に連携させる統合システムです。4つのレイヤーが積み重なって動作します。

Hermes Agent 4層アーキテクチャ図 — Page 2 - Interfaces / Core / Environment / Hardware の4層構造

レイヤー	役割	主な要素
Interfaces	外部との接続窓口	OpenAI API (Codex) / Discord Gateway (Bot)
Core (Hermes Agent)	AI の推論・記憶・スキル生成を行う心臓部	hermes_cli.main / エージェントロジック
Environment (Python venv)	隔離された依存関係パッケージ	discord.py / その他 Python パッケージ
Hardware (Mac mini)	プロセス管理と常時稼働	LaunchDaemon によるシステムドメイン管理

Phase 1: コアシステムと仮想環境の展開

Hermes のインストールはワンライナーで始まります。スクリプトが uv / Python / Node.js のコア依存関係を自動解決し、~/.hermes/hermes-agent/venv/ に隔離された仮想環境を構築します。

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
hermes setup

venv ディレクトリ構造

~/.hermes/hermes-agent/venv/
├── bin/
│   ├── python, python3, pip, pip3
│   ├── uv, node, npm
│   └── hermes
├── lib/
│   └── python3.x/
│       └── site-packages/
├── include/
└── pyvenv.cfg

重要：パッケージ追加は venv 内の Python で

今後のパッケージ追加は必ずこの仮想環境内の Python を指定して行ってください。source activate や単なる pip コマンドではパスが通っていない場合に見失う罠があります。仮想環境のフルパス指定が最も確実です。

Diagnostic Checkpoint: 認証無限ループの突破

推奨モデルはエージェント機能に最適化された gpt-5.3-codex です。ただし hermes model コマンドからブラウザ認証に入ると、認証が無限ループに陥るトラップがあります。

認証無限ループと CLI 先行認証のバイパスルート — Page 4 - [Trap] 認証無限ループ vs [Bypass Route] CLI 先行認証

[Trap] 認証無限ループ

hermes model → ブラウザ認証 → 再度認証を求められる… の繰り返しに陥ります。

[Bypass Route] CLI 先行認証

以下の手順で先にブラウザ認証を済ませてからモデルを設定します：

@openai/codex をグローバルインストール
パスを通す（export PATH）
codex login で先行ブラウザ認証
hermes model → 実行・既存トークンのインポート [y/N]: y

Phase 2: Discord Bot インターフェースの要件

Discord 側で Bot を作成し、Privileged Gateway Intents を必ず有効化します。また OAuth2 URL Generator で正しいスコープと権限を設定します。

Privileged Gateway Intents と OAuth2 URL Generator の設定 — Page 5 - Intents（必須3つを ON）と OAuth2 スコープ・権限

Privileged Gateway Intents（必須）

Intent	状態	用途
Message Content Intent	ON	メッセージの読み取りに必須
Server Members Intent	ON	メンバー情報の取得
Presence Intent	ON	オンライン状態の監視

OAuth2 URL Generator

項目	設定値
Scopes	bot, applications.commands
Permissions	Send Messages, Read Message History, Attach Files

Token は一度だけ表示される

Token は「Reset Token」押下時に一度だけ表示されます。確実にコピーすること。

Diagnostic Checkpoint: 2FA 画面のフリーズ

Developer Portal で 6 桁の 2FA コードを入力すると画面が固まり、Token が取得できないケースがあります。以下の3ステップで解決します。

2FA フリーズの Troubleshooting Card — Page 6 - Troubleshooting Card: 2FA 画面フリーズの3段階対処

ステップ	対処法	解決率
1. ハードリロード	`Cmd + Shift + R`（Mac）	9割解決
2. シークレットモード	`Cmd + Shift + N` で拡張機能の干渉を排除	残りの多く
3. 時刻同期	スマートフォンの認証アプリの「時刻の自動設定」をオン	コードのズレを修正

Next Step

Token 取得後、以下のコマンドで Discord Token と User ID を登録します：

hermes gateway setup

Gateway クラッシュの解剖

Gateway が起動直後にクラッシュし、launchd が即座に再起動を試みる無限ループに陥ることがあります。LastExitStatus = 256 が表示される場合、依存パッケージの欠落が原因です。

Gateway クラッシュの循環図と FATAL ERROR — Page 7 - launchd → Gateway 起動 → Discord 接続失敗 → 異常終了 → 再起動の循環

[FATAL ERROR] 依存パッケージの欠落で異常終了

launchd がプロセス管理 → Gateway を起動 → Discord へ接続を試みる → 依存パッケージ欠落で異常終了 → launchd が即座に再起動… のループが発生します。

Diagnostic Command

フォアグラウンドで直接起動し、真のエラーメッセージを画面に露出させます：

hermes gateway run

失われたピース「discord.py」の修復

hermes gateway run で表示される真のエラーが以下の場合、discord.py がインストールされていません。

WARNING: Discord: discord.py not installed
ERROR: Gateway failed to connect any configured messaging platform

修復手順

1. hermes gateway stop
2. /Users/YOUR_USER/.hermes/hermes-agent/venv/bin/python -m pip install -U discord.py

フルパス指定が最も確実

source activate や単なる pip コマンドでは、パスが通っていない場合に見失う罠があります。仮想環境の Python フルパスを直接指定するのが最も確実な方法です。

ログ診断マトリクス：致命傷とノイズの分離

ログに表示される警告やエラーには、致命的なものと安全に無視できるものがあります。テキスト運用であれば、右列の警告は無視して問題ありません。

Fatal Errors vs Safe Warnings の比較マトリクス — Page 9 - 致命的エラー（対応必須）と安全な警告（テキスト運用なら無視可）

分類	ログメッセージ	対応
Fatal Errors (致命的)	`discord.py not installed`	パッケージの直接インストールが必須
Fatal Errors (致命的)	`No adapter available`	パッケージの直接インストールが必須
Safe Warnings (安全)	`Opus codec not found`	音声チャンネル再生（Voice 機能）が無効になっているだけ。テキスト Bot としての基本動作（Gateway）には一切影響しない。
	`PyNaCl is not installed`
	`davey is not installed`

Phase 4: インフラストラクチャの常駐化（ヘッドレス運用）

Mac mini をヘッドレスサーバーとして運用するには、LaunchDaemon（システムドメイン）での登録が必須です。LaunchAgent との違いを理解しましょう。

LaunchAgent vs LaunchDaemon の比較表 — Page 10 - LaunchAgent（デフォルト）vs LaunchDaemon（目標設定）

項目	LaunchAgent（デフォルト）	LaunchDaemon（目標設定）
実行トリガー	ユーザーが GUI (Aqua) にログインした時	Mac の電源が入った時（OS システム起動時）
適性	スリープさせないデスクトップ Mac 向け	画面なし（ヘッドレス）の Mac mini サーバー向け
弱点 / 強み	再起動後、パスワードを入れてログインするまで Bot が沈黙する	ログイン不要で裏側で完全常駐

LaunchDaemon .plist ブループリント

/Library/LaunchDaemons/ai.hermes.gateway.plist に配置する設定ファイルの全容です。3つの重要ポイントに注意してください。

LaunchDaemon plist ファイルの全容と注釈 — Page 11 - plist ファイルの重要ポイント3点

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
  "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key>
  <string>ai.hermes.gateway</string>

  <key>UserName</key>
  <string>dirac</string>

  <key>ProgramArguments</key>
  <array>
    <string>/Users/dirac/.pyenv/versions/hermes-venv/bin/python</string>
    <string>-m</string>
    <string>hermes_cli.main</string>
    <string>gateway</string>
    <string>run</string>
    <string>--replace</string>
  </array>

  <key>EnvironmentVariables</key>
  <dict>
    <key>HOME</key>
    <string>/Users/dirac</string>
    <key>PATH</key>
    <string>/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin</string>
    <key>LANG</key>
    <string>en_US.UTF-8</string>
  </dict>

  <key>RunAtLoad</key>
  <true/>
  <key>KeepAlive</key>
  <true/>
</dict>
</plist>

plist の3つの重要ポイント

UserName: root 権限での暴走を防ぐため、必ず Hermes をインストールしたユーザー名を指定
ProgramArguments: venv 内の Python フルパスと hermes_cli.main gateway run --replace を正確に指定
EnvironmentVariables: Daemon は環境変数が薄いため、HOME, PATH, LANG (en_US.UTF-8) を明示的に追加し安定化させる

システム・ドメインへのサービス登録シーケンス

plist ファイルを配置した後、4ステップでシステムドメインに登録します。

サービス登録の4ステップ — Page 12 - Clean up → Permissions → Bootstrap → Kickstart

1. Clean up: 古い Agent の削除

Agent を含み、古い Agent の削除は、それたい Agent の登録を削除してます。

launchctl bootout gui/$(id -u) ~/Library/LaunchAgents/ai.hermes.gateway.plist 2>/dev/null

2. Permissions: 権限の適正化

権限の適正化を通信し、LaunchDaemon に適した権限に適正を出す。

sudo chown root:wheel /Library/LaunchDaemons/ai.hermes.gateway.plist

3. Bootstrap: システムへの登録

システムドメインへの登録を実行します。

sudo launchctl bootstrap system /Library/LaunchDaemons/ai.hermes.gateway.plist

4. Kickstart: プロセスの強制起動

プロセスの強制起動により、プロセスを始められるように起動できます。

sudo launchctl kickstart -k system/ai.hermes.gateway

ゴールデン・コマンド・ツールキット

運用で必要なコマンドを3つのカテゴリに整理しました。

Status Check / Log Monitoring / Restart & Stop の3カテゴリ — Page 13 - 状態確認・ログ監視・再起動/停止の3カテゴリ

Status Check（状態確認）

sudo launchctl print system/ai.hermes.gateway

state = running が表示されればシステム起動成功。

Log Monitoring（ログ監視）

tail -n 50 ~/.hermes/logs/gateway.error.log

（Note: hermes gateway logs は存在しないため、直接ファイルを tail すること）

Restart & Stop（再起動・停止）

sudo launchctl bootout system /Library/LaunchDaemons/ai.hermes.gateway.plist

停止時は上記を実行。再起動は bootstrap と kickstart のシーケンスを再実行する。

最終確認 - Online への到達

すべてのフェーズが完了したら、以下の3つを確認しましょう。

最終確認チェックリストと Discord 画面 — Page 14 - Hermes Agent がオンラインになった Discord の画面

最終チェックリスト

✅ Online Status: メンバーリストで Hermes Agent が緑色（オンライン）になっているか
✅ Allowlist Verification: 自分（登録した User ID）のメッセージにのみ反応するか。本番運用は User ID 指定を強く推奨
✅ Silence Voice Warnings: 音声警告のログノイズが気になる場合は、Discord 上で /voice off を実行

これで Mac mini は、再起動後も完全自動で稼働する自己改善型 AI エージェントのホストとなりました。