ゲートウェイ

確認済み実機・内容確認: 2026-09-02 対象バージョン: v0.21.0 対象コミット: c5c9aa8d #hermes#settings#gateway#remote#ssh#cloud

Hermes Desktop が操作するバックエンドを、4 つの接続モード（ローカル / Hermes Cloud / リモート / SSH）から選ぶ。画面の下半分には、このアプリから到達できるゲートウェイを名前付きで登録・切り替える「Registered gateways」セクションがある。

設定 > ゲートウェイ画面

表示値は環境依存の例。リモート URL と登録済みゲートウェイのアドレスはマスクしてある。

接続はマシン単位

ゲートウェイ接続はこの端末単位の設定で、プロファイルごとの接続先は持たない。画面冒頭の説明にも「ゲートウェイ接続はマシン単位の設定で、プロファイルは接続したゲートウェイから検出されます。」と明記されており、他の設定画面にある「適用対象」のプロファイルチップはこの画面には表示されない。プロファイルは接続先のゲートウェイ側から検出され、切り替えはプロファイル管理で行う。

複数のゲートウェイを使い分けたい場合は、プロファイル別の接続先ではなく、下の「登録済みゲートウェイ（Registered gateways）」に接続を追加してセッション画面から切り替える。

接続モード

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

製品既定はローカルゲートウェイ。4 枚のカードは常に同じ 4 種で、「デフォルトゲートウェイを使用」のようなプロファイル継承用のカードは無い。内部的には 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`	`token`（URL 調査結果で上書き）	保存値は `oauth` / `token`。公開 `/api/status` の応答から自動判定
サインイン	OAuth セッション Cookie + WebSocket ticket	未サインイン	設定ファイルへ OAuth トークンを直接保存しない
サインイン済み	`remoteOauthConnected`	`false`	アクセストークンまたは更新トークン Cookie が有効と判定された状態
サインアウト	OAuth セッション Cookie を削除	該当なし	操作・保存キーなし
セッショントークン	`remote.token`	未設定、`remoteTokenSet: false`	`connection.json` では暗号化オブジェクトとして保存。セキュアストレージが無い環境では下記の平文保存の同意が必要
トークンは平文で保存されています	`remoteTokenPlainText`	`false`（`secureTokenStorage: true`）	セッショントークン欄の直下に出る警告バナー。平文で保存中のときだけ表示

平文トークン保存の同意ダイアログ

OS のキーリングサービス（GNOME Keyring / KWallet 等）が見つからない環境で、リモートまたは Hermes Cloud モードのトークン認証に新しいトークンを入力して保存すると、保存の前に確認ダイアログ「ゲートウェイトークンを平文で保存しますか？」が挟まる。4 条件（セキュアストレージ不在・リモート/Cloud モード・トークン認証・新規トークン入力あり）がすべて揃ったときだけ出る。

操作: 「平文で保存」を押すと保存が続行され、トークンはアプリの接続設定ファイルへ暗号化されずに書き込まれる。閉じると保存は行われない。
期待結果: 保存後、セッショントークン欄の直下に警告バナー「トークンは平文で保存されています」が表示され続ける。
対処: バナーの説明どおり GNOME Keyring または KWallet をインストール・有効化してからトークンを保存し直すと暗号化保存に戻る。macOS と Windows は標準でセキュアストレージがあるため、通常この同意は求められない。

接続確認中の全表示

画面表示（主）	内部状態（サブ）	製品初期状態	表示・意味
このゲートウェイの認証方法を確認中…	`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 セッションを削除
OS キーチェーンで保存済みのシークレットを暗号化	IPC `getSecretStorageEncryption` / `setSecretStorageEncryption`	常時（起動失敗リカバリ画面の埋め込み表示では非表示）	トグル。既定オフ。下記「OS キーチェーン暗号化」参照
診断	操作・保存キーなし	常時	ログ操作の見出し
ログを開く	`revealLogs()`	常時	ファイルマネージャーで `desktop.log` を表示

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

OS キーチェーン暗号化

ボタン行の下にあるトグル「OS キーチェーンで保存済みのシークレットを暗号化」で、保存済みのゲートウェイトークンとサインイン資格情報を OS のキーチェーンで暗号化するかを選ぶ。既定はオフ。

状態	保存先	補足
オフ（既定）	現在のユーザーだけが読める通常ファイル	画面の説明どおり「現在のユーザーのみが読める通常ファイルとして保存」される
オン	Keychain Access（macOS）/ GNOME Keyring（Linux）/ Windows DPAPI	切り替え時に保存済みシークレットを再エンコードするため、システムから許可やパスワードを求められることがある

操作: トグルをオンにする。処理中はトグルが一時的に無効になる。
期待結果: 以後の保存はキーチェーン経由になり、既存のシークレットも暗号化し直される。
失敗時: 「シークレット暗号化の設定を変更できませんでした」のエラー通知が出てトグルが元の状態へ戻る。キーチェーンのアクセス許可を拒否していないか、OS 側のキーリングサービスが動いているかを確認する。

このトグルは Electron 側でキーチェーンの利用可否を切り替えるもので、上の「平文トークン保存の同意ダイアログ」とは別の仕組み。同意ダイアログは OS のキーリングサービス自体が見つからないときに出る。

登録済みゲートウェイ（Registered gateways）

診断行の下に、このアプリから到達できる Hermes ゲートウェイを名前付きで登録・管理する「Registered gateways」セクションがある。セクション全体が英語表示（日本語リソース未整備のため英語表示）。以前は設定内の独立した「Connections」ページだったものがこの画面に統合されており、旧ディープリンク ?tab=connections はこのゲートウェイ画面へリダイレクトされる。

設定 > ゲートウェイ画面の登録済みゲートウェイ一覧

表示値は環境依存の例。登録済みゲートウェイの名前とアドレスはマスクしてある。

セクション見出し下の 2 文が役割を示す。

「Manage this device and every Hermes gateway it can reach through remote, SSH, or Cloud connections.」─ この端末と、リモート / SSH / Cloud で到達できるすべてのゲートウェイをここで管理する。
「Switch gateways from Sessions. Profiles, chats, messaging, and cron jobs stay with their gateway; work on other gateways keeps running.」─ 切り替えはセッション画面から行う。プロファイル・チャット・メッセージング・cron ジョブはそれぞれのゲートウェイに属し、切り替えても他のゲートウェイの作業は動き続ける。

一覧の見方

画面表示（英語）	意味
This device	このアプリが管理するローカルの Hermes ランタイム（説明「The Hermes runtime managed by this app.」）。常に 1 件だけ存在し、削除できない
Current	いま接続しているゲートウェイに付くピル
Primary	起動時の既定として開くゲートウェイに付くピル
App-managed	アプリ管理のローカル接続に付くピル
Test / Reachable	接続テスト。到達できれば「Reachable」、失敗時は「Connection test failed」
Make primary	その接続を Primary にする。すでに Primary の行には表示されない
鉛筆アイコン / ゴミ箱アイコン	編集 / 削除。削除時は確認ダイアログ「Remove this connection?」が出る。削除されるのはこのアプリ上の登録だけで、ゲートウェイ側には何もしない
Add connection	接続を追加する（下記）
Update all instances	登録済みのすべてのインスタンスへ更新を一斉配信する。Hermes Cloud 管理のインスタンスは「Managed by Hermes Cloud」としてスキップされる
Search gateways…	登録数が多いときの絞り込み検索欄

接続の追加・編集

「Add connection」を押すと種別選択付きの入力フォームが開く。

種別（英語）	内容	主な入力欄
Local	このアプリが管理する Hermes ランタイム	追加不可（ローカル接続は常に 1 件。「Local is unavailable」のヒントが出る）
Remote gateway	HTTP(S) で到達できる Hermes ゲートウェイ（LAN・Tailscale・インターネット）	Name、Gateway URL、Extra gateway headers
Hermes Cloud	Hermes Cloud アカウントで検出されるホスト型インスタンス	Name、Gateway URL。ヒントどおり、通常は上の「Hermes Cloud」カードでサインインすれば自動検出されるため、既知の URL を手で登録したいときだけ使う
SSH	SSH 経由で到達する Hermes インストール	Name、SSH host

Name は必須で、一意でなければならない（例「Homelab」「Work laptop」）。
同じ Gateway URL や SSH host がすでに登録されていると「A connection to this gateway URL already exists」等の重複警告が出て保存できない。別名で同じバックエンドを指している場合は「Same backend as “…”」のヒントが付く。
「Extra gateway headers」は、Cloudflare Access のようなアクセスプロキシ越しに接続するときの追加ヘッダー（例 CF-Access-Client-Id / CF-Access-Client-Secret）。HTTP と WebSocket の全リクエストに付与され、値は暗号化して保存される。保存済みの値は「Saved — leave blank to keep」と表示され、空欄のままなら維持される。Hermes 自身が管理する Authorization / Cookie / Host などのヘッダーは無視される。
「Save connection」で保存する。失敗時は「Could not save the connection」の通知が出る。

起動時の復帰先

一覧の下にトグル「At startup, return to Sessions on the last-used gateway」がある。既定はオフ。

状態	起動時の動作
オン	最後に使っていたゲートウェイのセッション画面を開く
オフ（既定）	Primary のゲートウェイでセッション画面を開く（説明「When off, Sessions opens on the Primary gateway.」）

管理された更新（Managed updates）

SSH 種別の接続が 1 件以上登録されているときだけ、ページ末尾に「Managed updates」セクションが現れる（英語表示）。SSH 未登録の環境では表示されない。

Desktop が管理する SSH インストールをトランザクションとして更新する仕組みで、説明文どおり「セッションをドレインし、リモートのチェックアウトを更新し、すべてのプロファイルを復元して、相関 ID 付きのレシートを残す」流れで実行される。

画面表示（英語）	意味
Desktop-managed SSH install	接続ごとの行。右に「Update」ボタン
Updating… / Draining sessions, updating the remote install, and restoring profiles…	実行中
Updated	成功。「Receipt · <結果>」と「<更新前> → <更新後>」のバージョン、「Restored profiles: …」が表示される
Updated — restore failed	更新は完了したがプロファイルの復元に失敗。「Profile “…” not restored: <理由>」を確認する
Refused / Update failed / Update already in progress	拒否・失敗・実行中の二重起動

前提: 対象の SSH 接続で「Test」が通ること。実行中のセッションがあれば区切りのよいところで止めておく（更新時にドレインされる）。
失敗時: 表示された理由と desktop.log（「ログを開く」）を確認し、必要なら SSH ホストに直接ログインして hermes の状態を確認する。

「リモートをテスト」「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 を明示する。

画面に入力欄が無い設定値

ゲートウェイの運用に関わるキーのうち、この画面に入力欄がないもの。config.yaml で設定する。

設定キー	既定	内容
`gateway.loop_watchdog`	オン	ゲートウェイのクラッシュループを検知し、supervisor に再起動させる
`monitoring.gateway_health_export.*`	オフ	ゲートウェイのヘルスと診断情報を OTLP でエクスポートする

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

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

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

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