ゲートウェイ

確認済み実機・内容確認: 2026-07-22 対象バージョン: v0.19.0 対象コミット: 967e078a #hermes#settings#gateway#remote#ssh#cloud

Hermes Desktop が操作するバックエンドを、4 つの接続モード（ローカル / Hermes Cloud / リモート / SSH）から選ぶ。

適用対象

名前付きプロファイルがある場合に表示される。

画面表示（主）	内部キー・対象（サブ）	製品既定値	動作
適用対象	UI 状態 `scope`、保存キーなし	`null`（すべてのプロファイル）	編集対象を選ぶ見出し。名前付きプロファイルがある場合だけ表示
すべてのプロファイル	`connection.json` の `mode` / `remote.*`	選択中	個別オーバーライドがないプロファイルの既定接続
各プロファイル名	`connection.json` の `profiles.<profile>.*`	エントリなし（グローバル設定を継承）	そのプロファイルが有効なときだけ使う接続。ローカル選択時は該当エントリを削除して既定接続を継承する（SSH 設定があったプロファイルは `mode: local` と `savedSsh` で SSH 設定を保持したまま継承に戻る）

接続モード

画面表示（主）	内部キー（サブ）	製品既定値	内容	推奨
ゲートウェイ接続	操作・保存キーなし	該当なし	ページ見出し	-
env オーバーライド	`HERMES_DESKTOP_REMOTE_URL`。token 認証時の資格情報は `HERMES_DESKTOP_REMOTE_TOKEN`	両方とも未設定、`envOverride: false`	URL 環境変数がグローバル接続を制御している表示。有効時は 4 つのモードカードすべてが無効化される	画面設定を使うなら URL 変数を解除
Connection mode	UI 見出し、保存キーなし	該当なし	モード選択の見出し（英語表示）	-
ローカルゲートウェイ	グローバル: `mode: local`、プロファイル別: `profiles.<profile>` を削除	`mode: local`	Mac 上で専用バックエンドを起動。オフラインでも利用可能	個人利用の標準
Hermes Cloud	グローバル: `mode: cloud` + `remote.url` / `remote.org`、プロファイル別: `profiles.<profile>.mode: cloud`	未選択	Hermes Cloud に一度サインインし、アカウント上のエージェントを選んで接続。URL の貼り付けは不要（カード表示は英語）	Nous のホスト型エージェント利用時
リモートゲートウェイ	グローバル: `mode: remote`、プロファイル別: `profiles.<profile>.mode: remote`	未選択	別マシンやホスト型 Hermes バックエンドへ URL 指定で接続	管理済み環境だけ
SSH で接続	グローバル: `mode: ssh` + SSH ブロック、プロファイル別: `profiles.<profile>.mode: ssh`	未選択	SSH 経由でリモートホスト上に Hermes を起動し、このアプリへトンネルする	鍵ベース SSH アクセスがあるサーバー
リモート URL	グローバル: `remote.url`、プロファイル別: `profiles.<profile>.url`	空欄	ダッシュボードのベース URL。パスプレフィックス対応。リモートゲートウェイ選択時のみ表示	`https://` を使用

製品既定はローカルゲートウェイ。内部的には cloud は remote と同じ接続経路（接続テスト・再接続・プローブ）を使い、区別されるのは設定画面の表示と connection.json への保存だけ。

Hermes Cloud モード

一度 Hermes Cloud（Nous ポータル）にサインインすると、アカウント上のエージェントが一覧表示され、選ぶだけで接続できる。リモートゲートウェイと違い、URL やトークンの入力欄は表示されない。文言は英語表示。

画面表示（主・英語）	内部操作（サブ）	表示条件・動作
Hermes Cloud / Sign in to Hermes Cloud	`cloud.login()`（ポータルのブラウザーセッション）	未サインイン時。サインイン完了後にエージェント探索を自動実行
Signed in to Hermes Cloud + サインアウト	`cloud.logout()`	サインイン済み表示とセッション破棄
Choose an organization / Select	組織を選んで再探索	複数組織に所属している場合だけ組織ピッカーを表示
Your agents / Refresh / Change org	`cloud.discover(org)`	組織内のエージェント一覧。Change org で組織を選び直す
Connect / Connecting…	`cloud.agentSignIn(...)` → `applyConnectionConfig(mode: cloud)`	エージェントを選ぶと追加の確認なしでサインインが引き継がれ、そのエージェントの URL への cloud 接続を保存して即再接続する
Provisioning…	操作不可	エージェント側の準備が完了していない（接続先 URL 未発行）状態
Connected / Status: …	表示のみ	接続中エージェントのバッジと各エージェントの状態表示
No agents found on this account. …	ポータルへの外部リンク	エージェントが 1 つもない場合。ポータルで作成してから Refresh する

前提: Nous アカウントと、アカウント上に作成済みの Hermes エージェント。
操作: 「Hermes Cloud」カードを選ぶ → 「Sign in to Hermes Cloud」でブラウザーサインイン →（複数組織なら組織を選択）→ 一覧からエージェントの「Connect」を押す。
期待結果: 「Connected to <エージェント名>.」が通知され、そのまま再接続される。Cloud モードでは画面下部の「リモートをテスト」「次回起動時のために保存」「保存して再接続」ボタン行は表示されない（エージェント選択が保存と再接続を兼ねる）。
失敗時: サインイン失敗・一覧取得失敗は英語のエラー通知（「Hermes Cloud sign-in failed」「Could not load your Hermes Cloud agents」）が出る。ポータルセッションが失効している場合はサインインからやり直す。

選択した組織とエージェントの URL は connection.json に保存され、次回この画面を開いたとき同じ組織の一覧に復帰する。

SSH で接続

「Hermes は SSH 経由でリモート上に起動され、このアプリにトンネルされます。リモート側で何かを起動・公開する必要はありません。ホストへの鍵ベースの SSH アクセスが前提です。」（カードの説明文）。SSH は非対話（BatchMode）で実行されるため、パスフレーズ付き鍵は ssh-agent への読み込みが必要になる。

画面表示（主）	内部キー（サブ）	製品既定値	動作
ホスト	`host`	空欄	`~/.ssh/config` に Host エイリアスがあれば選択式（「ホストを選択…」、「カスタム（手入力）…」で手入力に切り替え）。なければ入力欄で `user@host` またはエイリアスを直接入力。`host:port` 形式も解釈される
ユーザー	`user`	空欄（プレースホルダー「~/.ssh/config から」）	空欄 = `~/.ssh/config` または現在のユーザー
ポート	`port`	空欄（プレースホルダー「22」）	空欄 = 22 または `~/.ssh/config` のポート。22 は保存時に省略される
鍵ファイル	`keyPath`	空欄	秘密鍵のパス。空欄 = ssh-agent または `~/.ssh/config`
Hermes パス（任意）	`remoteHermesPath`	空欄（プレースホルダー「自動検出」）	リモートの hermes バイナリへのフルパス。空欄 = 自動検出

エイリアスを選択すると ssh -G 相当の解決結果からユーザー・ポート・鍵ファイルが自動補完される（空欄のフィールドのみ。ポート 22 は空欄のまま）。ワイルドカード（* ?）や除外（!）を含む Host パターンは候補に出ない。

テストと保存

前提: 対象ホストへ鍵認証で SSH ログインできること（ssh <host> がパスワード入力なしで通る状態）。
操作: ホストを選ぶか入力し、「SSH をテスト」で疎通確認する。保存は共通の「次回起動時のために保存」または「保存して再接続」を使う。
期待結果: テスト成功時は「接続可能: <ホスト>（<プラットフォーム>）— Hermes を検出」と表示される。「保存して再接続」でその場で SSH 接続に切り替わる。
失敗時: 下表のエラー別ガイダンスに従う。解決しない場合は「ログを開く」で desktop.log を確認する。

ホスト鍵の扱い

初回に提示されたホスト鍵を信頼して固定し（trust-on-first-use）、以後の変更は拒否する（カードのツールチップにも明記）。実装は StrictHostKeyChecking=accept-new で、ホスト鍵が変わった場合は接続を失敗させる。

エラー別ガイダンス

エラー種別（内部コード）	画面メッセージ（要旨）
到達不能（`unreachable`）	SSH でそのホストに到達できない。ホスト、ポート、ネットワークを確認する
認証失敗（`auth-failed`）	鍵を ssh-agent に読み込む（`ssh-add`）か、`~/.ssh/config` に IdentityFile を設定する。Hermes は非対話的に ssh を実行する
ホスト鍵変更（`host-key-changed`）	前回の接続以降ホスト鍵が変更されている。想定どおりか確認し、`ssh-keygen -R <host>` を実行してから再接続する
Hermes 未インストール（`hermes-not-found`）	リモートでインストールする（`curl -fsSL https://hermes-agent.nousresearch.com/install.sh \| sh`）か、Hermes パスを設定する
非対応プラットフォーム（`unsupported-platform`）	SSH モードは Linux、macOS、Windows のリモートホストに対応
タイムアウト（`timeout`）	ホストが到達不能、またはスリープ中の可能性
要更新（`update-required`）	Desktop SSH で接続する前にリモートホストの Hermes を更新する

リモート認証

URL 入力後、約 500 ms のデバウンスを経て公開ステータスを調べ、認証方式を自動判定する。

OAuth: ブラウザーで ID プロバイダーへサインイン。
ユーザー名とパスワード: ゲートウェイのログイン画面を使用。
セッショントークン: 自己ホスト型などで REST / WebSocket 用トークンを入力。

保存済みセッショントークンを維持する場合は入力欄を空のままにする。トークンを Vault へ記録しない。

画面表示（主）	内部キー（サブ）	製品既定値	備考
認証	`remote.authMode` または `profiles.<profile>.authMode`	`token`（URL 調査結果で上書き）	保存値は `oauth` / `token`。公開 `/api/status` の応答から自動判定
サインイン	OAuth セッション Cookie + WebSocket ticket	未サインイン	設定ファイルへ OAuth トークンを直接保存しない
サインイン済み	`remoteOauthConnected`	`false`	アクセストークンまたは更新トークン Cookie が有効と判定された状態
サインアウト	OAuth セッション Cookie を削除	該当なし	操作・保存キーなし
セッショントークン	`remote.token` または `profiles.<profile>.token`	未設定、`remoteTokenSet: false`	`connection.json` では Electron の暗号化オブジェクトとして保存

接続確認中の全表示

画面表示（主）	内部状態（サブ）	製品初期状態	表示・意味
このゲートウェイの認証方法を確認中…	`probeStatus: probing`	非表示（`idle`）	URL の公開ステータスを問い合わせている。認証欄はまだ表示されない
このゲートウェイにまだ到達できません。…	`probeStatus: error`	非表示	URL、ネットワーク、TLS、パスを確認する。応答するまで認証方式は確定しない
サインイン	`authMode: oauth`, `remoteOauthConnected: false`	非表示	OAuth またはパスワード認証を開始
サインイン済み	`remoteOauthConnected: true`	非表示	接続セッションが保存され、自動更新の対象になる
セッショントークン	`authMode: token`	リモート URL 未設定のため非表示	セッショントークン入力欄が表示される
env オーバーライド	`envOverride: true`	非表示（`false`）	環境変数が優先され、画面の選択・保存操作が無効化される

起動失敗時の再サインイン

リモートゲートウェイのセッション期限切れでアプリの起動に失敗すると、回復画面「リモートゲートウェイへのサインインが必要です」に**「サインアウトして再サインイン」ボタン**が表示される。押すと保存済みのリモートブラウザーセッションからサインアウトし、サインインウィンドウを開く。あわせて「ゲートウェイ設定」「ローカルゲートウェイを使用」ボタンが並ぶ。

サインイン期限切れ以外のリモート起動失敗では、ヒント「『ゲートウェイ設定』でゲートウェイの URL とサインインを確認するか、ローカルゲートウェイに切り替えてください。」が表示され、「ゲートウェイ設定」ボタンでこの設定画面を回復画面内に埋め込み表示できる。

ボタン

画面表示（主）	内部操作（サブ）	表示条件	動作
リモートをテスト	`testConnectionConfig(...)`、保存キーなし	リモートゲートウェイ選択時のみ	URL、認証、バージョン到達性を確認
SSH をテスト	`testConnectionConfig(...)`（SSH ペイロード）	SSH で接続選択時のみ	SSH 疎通とリモートの Hermes 検出を確認
次回起動時のために保存	`saveConnectionConfig(...)`	Cloud モード以外	`connection.json` へ保存するが、現在の接続は切り替えない
保存して再接続	`applyConnectionConfig(...)`	Cloud モード以外	保存し、その設定で接続を再起動
サインアウト	`oauthLogoutConnectionConfig(...)`	リモートで OAuth サインイン済み	保存されたリモート OAuth セッションを削除
診断	操作・保存キーなし	常時	ログ操作の見出し
ログを開く	`revealLogs()`	常時	ファイルマネージャーで `desktop.log` を表示

デスクトップ接続設定は Electron の userData/connection.json に保存される。

「リモートをテスト」「SSH をテスト」は保存前の疎通確認であり、現在の接続を切り替えない。「保存して再接続」は会話中の接続を再起動するため、実行中タスクがないことを確認する。

環境変数による上書き

HERMES_DESKTOP_REMOTE_URL が設定されていると「env オーバーライド」が表示され、グローバル接続の画面操作（4 つのモードカードを含む）が無効になる。token 認証では HERMES_DESKTOP_REMOTE_TOKEN も必要。HERMES_DESKTOP_REMOTE_TOKEN だけでは env オーバーライド表示は有効にならない。画面から管理へ戻すには URL 変数を解除し、残したくない token 変数も解除してアプリを再起動する。

リモート接続の推奨手順

URL が信頼できる HTTPS ホストか確認する。
「リモートをテスト」で接続先と Hermes バージョンを確認する。
まず「次回起動時のために保存」を使う。
切り替え準備ができたら「保存して再接続」を使う。
問題時はローカルへ戻し、desktop.log を確認する。

セッションの自動リセット（config.yaml 側）

この画面の項目ではないが、config.yaml の session_reset セクションでセッションの自動リセットを設定できる。既定モードは none（自動では行わない）で、アイドル一定時間または毎日決まった時刻での自動リセットに戻すには、session_reset セクションで mode: daily / idle / both を明示する。

多重化とプロファイルルーティング（概要）

1 つの多重化ゲートウェイが 1 つの bot トークンを共有したまま、サーバー（guild）・チャンネル・スレッド単位で受信メッセージを別プロファイルへルーティングできる（config.yaml の profile_routes）。プロファイルごとに設定・スキル・メモリ・シークレットが完全に分離される。ルーティングはプラットフォーム汎用で、Discord に限らない。

環境変数 GATEWAY_MULTIPLEX_PROFILES は多重化の有効 / 無効を運用側から強制する上書きで、1/true/yes/on と 0/false/no/off を解釈する。空文字や未知の値は無視され config.yaml の設定にフォールバックする（env > config > 既定）。

プロファイルの作成・切り替えはプロファイル管理、チャネル側の接続は連携の全体像を参照。