Hermes Agent Web Dashboardの起動と設定：ローカル接続・プロファイル・障害診断
Hermes Agent Web Dashboardの起動と設定に関する実践ガイド。依存関係のインストール、実行環境ごとの制約（Native WindowsとWSL2のPTY差異）、安全なSSHトンネル経由のリモートアクセス、プロファイル管理とモデル設定、および多層的なトラブルシューティング手順を解説します。
目次
グラフィカルなWebインターフェースであるHermes Agent Web Dashboardを使用すると、設定ファイルを直接手動で編集することなく、ブラウザ上からエージェント環境を一元管理できます。このダッシュボードでは、APIアクセスキーの管理、プロファイルの切り替え、過去セッションの確認、そしてシステム環境を手動で変更することなく利用できる組み込みターミナルの起動が可能です。
基本的な起動とシステム依存関係
デフォルトでは、ダッシュボードはループバックインターフェース（loopback）にバインドされます：
hermes dashboardこのコマンドを実行すると、ローカルHTTPサーバーが起動し、既定のブラウザで http://127.0.0.1:9119 が開きます。もしこのポートが他のローカルサービスですでに使用されている場合は、--port フラグでポート番号を上書き指定できます：
hermes dashboard --port 9120 --no-open--no-open フラグを指定するとブラウザの新規タブが自動で開かなくなるため、バックグラウンドプロセスや自動化スクリプトでの実行に適しています。
ベースとなる hermes-agent パッケージには、デフォルトでWebスタックが含まれていません。Linux、macOS、WSL2の各環境では、エージェントの仮想環境に必要な追加コンポーネントをインストールします：
cd ~/.hermes/hermes-agent && uv pip install -e ".[web,pty]"追加パッケージの web は FastAPI と Uvicorn を導入し、pty はPOSIXシステム向けの ptyprocess を追加します。ダッシュボードの静的フロントエンドをビルドするには、アクティブな Node.js 環境が必要です（npm が存在する場合、初回起動時にフロントエンドが自動的にビルドされます）。
プラットフォームの境界：ネイティブWindowsとWSL2
Windows (Native) ガイドによると、ネイティブWindows環境でのインストールでも設定、メトリクス、タスク、およびセッションデータベースの閲覧画面はサポートされています。ただし、組み込みの /chat ターミナルタブはPOSIX PTY（擬似端末）に依存しています。ネイティブWindows環境ではこのインターフェースがサポートされていないため、ブラウザ上で完全な対話型ターミナルセッションを利用するには、WSL2内でエージェントを実行する必要があります。
また、プロセスの分離を意識することも重要です。Webダッシュボードとメッセージングゲートウェイ（TelegramやDiscordなどの各種プラットフォーム向け連携ゲートウェイ）は独立したデーモンとして動作します。Webインターフェースを起動しても、プラットフォーム向けメッセージングゲートウェイが自動的に起動または有効化されることはありません。
プロファイル管理とモデル設定
ダッシュボードはマシンレベルで動作し、設定済みのすべてのプロファイルを一元的に管理します。サイドバーでプロファイルを切り替えると、URLクエリパラメータ ?profile=<name> を介して作業コンテキストが更新されます。
- ConfigおよびAPI Keysセクション：
Configページではconfig.yaml内のパラメータを編集し、変更は Save ボタンをクリックして反映します。これに対し、API Keysページは~/.hermes/.env内の環境変数を管理します。キーの設定や削除は変数ごとに個別に行われ、全体の保存ボタンや全フィールドに対する一括バリデーションは用意されていません。 - プロバイダーとモデルの一貫性：選択したモデルと認証情報は、同一のプロバイダーに厳密に対応している必要があります。サードパーティのOpenAI互換サービスを統合する場合は、アップストリームのパラメータを必ず確認してください。例えば、接続設定、モデルID、必須フィールドについてはBetterTokenガイドで解説されています。なお、サードパーティのプロバイダーは独立したAPIモデルアクセスを提供するのみであり、Hermesダッシュボード自体のホスティングやネットワークトンネルの管理は行いません。
- Sessionsを通じた動作確認：手動でヘルスチェックを行う場合は、読み取り専用の短いプロンプトを送信してください。テストクエリに対してもプロバイダー側で課金が発生する場合がある点にご留意ください。推論の成功は、インターフェース上で実質的な応答を受信し、セッションのメタデータまたはプロバイダー側のログにトークン消費が記録されたことで確認されます。
Sessionsタブの一覧に新しいエントリが表示されたこと自体はセッションレコードが作成されたことを示すに過ぎず、モデルが正常に応答したことの保証にはなりません。
安全なリモートアクセス
デフォルトでは、Webサーバーは 127.0.0.1 のみをリッスンします。外部インターフェースにバインドした場合（--host 0.0.0.0）、認証ゲート（auth gate）が自動的に適用されます。認証プロバイダーが設定されていない場合、エージェントはエラーを出力して終了します（fail-closed）。かつて存在したレガシーな --insecure フラグは、現在では認証のバイパスには使用できません。Hermes Agentの公式ドキュメントに記載されている通り、パブリックまたは外部ネットワークへのバインドには認証の設定が必須となります。
外部ポートを直接公開することなくリモートサーバーに接続する推奨方法は、SSHトンネルを介したローカルポートフォワーディングです（user@your-server はお使いのリモートサーバーのアドレスとユーザー名に置き換えてください）：
ssh -N -L 9119:127.0.0.1:9119 user@your-serverローカル端末側のポート 9119 がすでに他のプロセスで使用されている場合は、代替のローカルポートを指定するバリエーションを使用します：
ssh -N -L 9120:127.0.0.1:9119 user@your-serverこの構成では、リモートホスト上のHermesサーバーはローカルの 127.0.0.1 ループバックインターフェースでのみ動作し続け、すべてのトラフィックはSSHトンネルを介して暗号化されます。作業用端末のブラウザからは http://127.0.0.1:9119（または代替ポートを指定した場合は http://127.0.0.1:9120）でダッシュボードにアクセスできます。
段階的なトラブルシューティング
問題が発生した場合は、スタック全体を一度にテストするのではなく、障害のレイヤーを個別に切り分けることが重要です。
+----------------------------------------------------------------+
| 1. HTTP-транспорт | 127.0.0.1:9119 /api/status |
+------------------------+---------------------------------------+
| 2. Окружение и PTY | Node.js / POSIX ptyprocess (WSL2) |
+------------------------+---------------------------------------+
| 3. Сокеты и каналы | /api/pty (Chat) / /api/ws (Desktop) |
+------------------------+---------------------------------------+
| 4. Провайдер инференса | Ключи API, лимиты и сетевой эндпоинт |
+----------------------------------------------------------------+上記のデシジョンツリーで示されている診断レイヤーは、以下の各層に対応しています：
- レイヤー1（HTTPトランスポート）：
127.0.0.1:9119 /api/status - レイヤー2（環境およびPTY）：Node.js / POSIX ptyprocess (WSL2)
- レイヤー3（ソケットと通信チャネル）：
/api/pty(Chat) //api/ws(Desktop) - レイヤー4（推論プロバイダー）：APIキー、利用制限・残高、ネットワークエンドポイント
- ネットワーク層（HTTP）：
GET /api/statusからの正常なレスポンスは、Uvicorn プロセスが稼働し、HTTPリクエストに応答していることのみを証明します。この認証不要のエンドポイントは、認可を通過したことや対話型チャットインターフェースが利用可能であることを保証するものではありません。 - PTYおよびインターフェース層：
Connection closedエラーにはいくつかの異なる原因が考えられます。ネイティブWindows環境における主な診断上の原因は、POSIX PTYサポートの欠如です（この場合、実行環境をWSL2へ移行します）。他のプラットフォームでは、この現象はPTYに限定されず、システムログやソケット接続の確認が必要です。画面が真っ白になる問題やCSS/スタイルのビルドエラーが発生した場合は、Node.jsのバージョンを確認し、フロントエンドの依存関係を再ビルドしてください。 - ソケットチャネルと認可：ブラウザの組み込みターミナルは
/api/pty経由で通信しますが、リモートDesktopクライアントは/api/ws経由で接続します。クライアントが「バックエンドは到達可能」と報告しているにもかかわらずセッションが応答しない場合は、該当するソケット接続を確認してください。セッションチケットの欠落や期限切れ、あるいはHostヘッダーがバインドアドレスと一致しないことによるDNSリバインディング保護のブロックが原因となることがよくあります。 - モデルプロバイダー層：アクティブなターミナルでプロンプトを送信した後に発生する遅延やエラーメッセージは、通常API層に起因します（
.env内の無効なキー、プロバイダーエンドポイントへの到達不能、クォータ超過や残高不足など）。ただし、プロバイダー側のエラーが発生しているからといって、ダッシュボードサーバー自体が完全に健全であるとは限りません。トラブルシューティング時には、ランタイムの状態やセッションのライフサイクルの確認も必要になる場合があります。
