---
title: "Hermes デスクトップアプリ"
description: "ネイティブの Hermes デスクトップアプリ。ツール出力のストリーミング表示、横並びのプレビュー、ファイルブラウザ、音声、cron、プロファイル、スキル、設定を備えた、Hermes と対話するための作り込まれた環境です。macOS、Windows、Linux に対応します。"
upstream_path: user-guide/desktop.md
upstream_blob: d86d31c0edcb2d2a53917bd6a1adf0faaaf325ba
sources:
  - https://hermes-agent.nousresearch.com/docs/user-guide/desktop
---

# Hermes デスクトップアプリ {#hermes-desktop}

Hermes デスクトップアプリは、CLI やゲートウェイで使うのと **まったく同じ** エージェントを中心に作られたネイティブアプリです。設定も API キーもセッションもスキルも記憶も、すべて共通です。別製品でもなければ機能を削った簡易版でもなく、同じ Hermes Agent のコアと設定をそのまま使い、現代的でよく練られた UI から動かします。ターミナルで `hermes` を使ったことがあれば、そこで整えたものはすでにこのアプリにも入っていますし、ここでの操作はあちらにも反映されます。

**macOS、Windows、Linux** で動きます。

:::tip どのインターフェースがどれか
Hermes には、同じエージェントに話しかけるフロントエンドがいくつかあります。

- **デスクトップアプリ**（このページ） — チャット・設定・管理のために作り込まれた UI を持つネイティブアプリケーションです。
- **CLI**（`hermes`）と **[TUI](/hermes/docs/user-guide/tui/)**（`hermes --tui`） — ターミナル上のインターフェースです。
- **[Web ダッシュボード](/hermes/docs/user-guide/features/web-dashboard/)**（`hermes dashboard`） — ブラウザ上の管理画面です。任意で使える **Chat** タブは、疑似端末を通して TUI を埋め込んでいます。

その場に合うものを選んでください。状態は共有されるので、片方で始めたセッションをもう片方で再開できます。
:::

## インストール {#install}

アプリは [Hermes Desktop の製品ページ](https://hermes-agent.nousresearch.com/desktop) からダウンロードするか、[Hermes Desktop のインストール手順](/hermes/docs/getting-started/installation/)に従ってください。

すでに Hermes を入れているなら、次を実行するだけです。

```bash
hermes desktop
```

現在の設定・キー・セッション・スキルがそのまま使われます。

## アプリに入っているもの {#whats-in-the-app}

デスクトップアプリは、チャットを中心に据えたウィンドウと、移動用の左サイドバーで構成されています。複数のエージェント会話を同時に扱い、メッセージングのプロバイダを設定し、成果物を作り、プロジェクトのフォルダ構成を眺め、複数のプロジェクトを並行して進められるように作られています。

### チャット {#chat}

アプリの中心です。次のことができます。

- **ストリーミング応答** — エージェントが作業する様子を、ツールの動きと構造化されたツール呼び出しの要約とともにその場で表示します。
- **どの Hermes からも同じ会話履歴** — ここで始めたセッションは CLI や TUI で再開できますし、その逆もできます。
- **ファイルのドラッグ＆ドロップ** — チャット領域のどこにでも落とすと、次のメッセージに添付されます。
- **右側のプレビュー欄** — Web ページ・ファイル・ツールの出力を横に並べて表示しながら、そのままチャットを続けられます。
- **入力履歴とキューの編集** — 何も入力していない状態で上下の矢印キーを押すと、前に送ったプロンプトを呼び出して使い回せます。送信待ちに並んだメッセージも、送られる前に編集できます。ターンがキューに並んでいるときに Stop（または Esc）を押すとキューが一時停止し、入力欄の上に展開されます。そこから再開したり、個々の項目を送信・編集・削除したりできます。
- **会話のタイムライン欄** — 長いチャットでは、記録の端にプロンプトごとのマーカーが並んだ細い欄が出ます。マウスを重ねるとプロンプトの一覧が開き、どれかをクリックすると会話のその地点まで一気に移動できます。（数回のやり取りがたまると現れます。）
- **ページ内検索** — **Cmd/Ctrl+F** を押すと検索バーが開き、表示中のチャット記録を検索します。Enter / Shift+Enter（バーが開いている間は Cmd/Ctrl+G / Cmd/Ctrl+Shift+G でも可）で一致箇所を順に移動し、Esc で閉じます。

#### ステータスバー {#status-bar}

チャットの下端に並ぶバーには、セッションの状態がその場で表示され、設定画面を開かずに使えるスイッチが並んでいます。

- **セッションごとの YOLO 切り替え** — このセッションだけ YOLO を入れたり切ったりできます（TUI と同じです）。YOLO は危険なコマンドの承認確認を飛ばすので、何を切っているのかを理解したうえで使ってください。[セキュリティ → YOLO モード](/hermes/docs/user-guide/security/#yolo-mode)を参照してください。
- **コンテキスト使用量メーター** — セッションのコンテキストウィンドウがどれくらい埋まっているかを「％」でその場に表示します。クリックすると **Context Usage** のポップオーバーが開き、種類ごとのトークン内訳（システムプロンプト、ツール定義、スキル、記憶、ルール、MCP、サブエージェントの定義、そして会話そのもの）が見えるので、圧縮が始まる前に何がウィンドウを食っているのかを正確に確かめられます。
- **表示項目のカスタマイズ** — ステータスバーを右クリックして（**Show in status bar**）、何を出すか選べます。コンテキストメーター、ワークスペース、モデル、承認、ターン／セッションのタイマー、ターミナル、Command Center、バックエンドのバージョンなどです。バー自体を隠すこともできます（**Cmd/Ctrl+Shift+S** で切り替わります）。

同梱のローカルバックエンドではなく、別の端末で動いている Hermes に対してチャットしたい場合は、下の[リモートバックエンドに接続する](#connecting-to-a-remote-backend)を参照してください。リモートでホストされたダッシュボードへの接続の全体像（認証の関門、`/api/ws` のチャットソケット、WebSocket のクローズコードの切り分け）は [Web ダッシュボード → Hermes Desktop をリモートバックエンドに接続する](/hermes/docs/user-guide/features/web-dashboard/#connecting-hermes-desktop-to-a-remote-backend)にあります。

#### リポジトリの検出 {#repository-discovery}

Hermes Desktop は、ホームディレクトリを一定の深さまで走査して、Projects サイドバー用にローカルの Git リポジトリを見つけます。この動きは **Settings → Workspace** でプロファイルごとに変えられますし、`config.yaml` でも指定できます。

```yaml
desktop:
  repo_scan_enabled: true
  repo_scan_roots: []
  repo_scan_exclude_paths: []
```

- `repo_scan_enabled: false` にすると、ファイルシステムの走査を完全に止めます。そのプロファイルのディスク検出キャッシュの行は消えますが、明示的に登録したプロジェクトや、意図して開いた Hermes セッションから割り出されたリポジトリは残ります。
- `repo_scan_roots` にフォルダの一覧を指定すると、走査対象をそこに限定できます。空のままなら既定のホームディレクトリ走査が続きます。
- `repo_scan_exclude_paths` には、配下ごと丸ごと飛ばしたいフォルダを指定します。

これらの値を変えると、そのプロファイルのディスク検出キャッシュだけが無効になり、方針に沿った再取得が始まります。**Hide from sidebar** は、項目ごとに手で整理するための別の操作として残ります。

#### モデルを選ぶ {#choosing-a-model}

モデルの選択欄は **入力欄** の中、マイクのすぐ左にあります。クリックすると、モデル・推論の強さ・高速モードを1つのドロップダウンから切り替えられます。

- **入力欄の選択欄は表示上の状態にすぎず、既定値には一切触れません。** 選んだ内容は端末ごとにローカルに覚えられ、新しいチャットや再起動をまたいで **引き継がれます**。既定値に戻ることはありません。一度選んでおけば、次の `Cmd/Ctrl+N` もそのモデルで開きます。チャットが動いている最中に切り替えた場合は、その変更は **いま開いているチャット** に限定されます。どちらの場合も、選択内容はセッションの作成時や切り替え時に一緒に運ばれるだけで、プロファイルの既定値として書き込まれることは **ありません**。（[プロファイル](#sessions--profiles)を切り替えると、そのプロファイル自身の既定値から選び直されます。）
- **既定値は Settings → Model で決めます。** この「main」のモデルが **プロファイルごとの全体の既定値** で、新しいチャット・cron・サブエージェント・補助的な処理はここから始まります。既定値を書き込むのはこの場所だけです。[プロファイル](#sessions--profiles)ごとに、それぞれの既定値を持ちます。
- **モデルごとの強さ／高速モードの記憶。** デスクトップアプリでは、モデルごとに推論の強さと高速モードの選択を覚えていて、そのモデルを選ぶたびにセッションへ適用し直します。これはデスクトップ側の便利機能で、cron やサブエージェントを変えるものではありません。
- **チャットの途中で切り替えるとプロンプトキャッシュがリセットされます。** 動いているチャットの中でモデルを切り替えると、次のメッセージでは会話全体を入力価格そのままで読み直すことになります（プロバイダのプロンプトキャッシュはモデルごとに分かれているためです）。たまになら問題ありませんが、長いチャットでは行ったり来たりするより、新しいモデルで新しいチャットを始めたほうが安く済むことが多いです。

### ファイルブラウザ {#file-browser}

アプリから出ずに作業ディレクトリを見て回り、中身を確認できます。エージェントがファイルを読み書きしたり編集したりする様子を追いかけるのに便利です。最初に開くプロジェクトのディレクトリは `hermes desktop --cwd <path>`（または環境変数 `HERMES_DESKTOP_CWD`）で指定します。

### 成果物 {#artifacts}

**Artifacts** ビューは、セッションが生み出したもの（**画像・ファイル・リンク**）を1つのギャラリーに集め、検索したり眺めたりできるようにします。サイドバー、コマンドパレット（**Artifacts — Browse generated outputs**）、あるいは自分で割り当てた `nav.artifacts` のショートカットから開けます。最近のセッションの出力は自動で取り込まれ、それぞれの成果物にはどのセッションが作ったかが表示され、そのチャットへ戻れます。画像とファイルはプレビューで開き、ダウンロード／ブラウザで開く／コピーの操作ができます。

### ウィンドウ・タブ・ペイン {#windows-tabs-panes}

このアプリは、いくつもの作業を同時に進めるために作られています。

- **タブ** — **Cmd/Ctrl+T** で新しいセッションのタブが開きます。**Ctrl+Tab** / **Ctrl+Shift+Tab** でセッションを順に巡り、**Ctrl+1…9** で最近のセッションに位置で飛べます。**Cmd/Ctrl+W** で選択中のタブを閉じ、**Cmd/Ctrl+Shift+T** で最後に閉じたタブを開き直します。
- **複数のウィンドウ** — **Cmd/Ctrl+Shift+N** で新しいウィンドウが開きます。どのセッションもコンテキストメニュー（**New window**）やコマンドパレットから切り出せます。切り出したウィンドウは、全体のサイドバーなしでそのチャットだけを表示するので、長時間動くセッションを別のモニタに置いておくのに向いています。エージェントの出力は、そのセッションを表示しているすべてのウィンドウに流れ込みます。
- **ペイン** — **Cmd/Ctrl+B** で左サイドバー、**Cmd/Ctrl+J** で右サイドバーを開閉し、**Cmd/Ctrl+\\** で左右どちら側にサイドバーを置くかを入れ替えます。

### ターミナル {#terminal}

右サイドバーの、ファイルブラウザの隣には本物のターミナルがあります。

- **Ctrl+`** でターミナルを表示します（1つも無ければ新しく開きます）。**Ctrl+Shift+`** を押すと、もう1つ増やします。複数のターミナルはタブの列に積み重なり、**Ctrl+Shift+↓/↑** で行き来し、**Ctrl+Shift+W** で選択中のものを閉じます。
- **隠しても shell は生き続けます。** パネルを閉じたり隠したりしても shell は落ちません。開いているターミナルは、明示的に閉じるまでスクロールバックと実行中のプロセスを保ったまま残ります。
- **Add to chat** — ターミナルの出力を選択して入力欄に送り、次のメッセージの材料にできます。

### Git のレビューと worktree {#git-review-worktrees}

Git リポジトリの中で動いているセッションには、ソース管理の画面が組み込まれています。

- **レビューペイン** — **Cmd/Ctrl+G** で作業ツリーのレビューペインを開閉します。ブランチと ahead/behind の状態、変更されたファイル（一覧表示またはツリー表示）、そして **Uncommitted**・**Branch**・**Last turn**（直近のターンでエージェントが変えた分だけ）に絞った差分が見られます。ファイルのステージ／解除、変更の取り消し、コミットメッセージの記入（**Generate commit message** で生成も可）ができ、**Commit** または **Commit & Push** を押せます。GitHub CLI（`gh`）を使った **Create PR** もありますし、**Ask Hermes to open PR** でまるごとエージェントに任せることもできます。ここからブランチの作成と切り替えもできます。
- **worktree** — **Cmd/Ctrl+Shift+B**（またはサイドバーのプロジェクトで **New worktree**）を選ぶと、新しいブランチの上に Git の worktree が作られ、自分のチェックアウトに触れないままエージェントがリポジトリの並行コピーで作業できます。worktree はプロジェクトの下に独自のレーンとして現れます。取り除くときは、worktree のディレクトリごと消す（ブランチは残ります）か、レーンを隠すだけでディスク上には残すかを選べます。コミットしていない変更があるときは強制の選択肢も出ます。

### 記憶グラフ {#memory-graph}

**Memory Graph**（コマンドパレット → *Memory Graph*、またはステータスバーの項目）は、Hermes が自分のために学んだことを対話的に描いた地図です。スキルと記憶が拡大縮小できるノードのグラフとして時系列とともに並び、**All / Used / Learned** で絞り込めます。共有の操作を使うと、地図の配置を短いコードとして書き出して誰かに渡せますし（配置だけで、記憶やスキルの本文は含まれません）、同じ形でコードを読み込めます。

### Quick Entry {#quick-entry}

Quick Entry は、**システムのどこからでもグローバルなホットキーで呼び出せる** 小さな入力欄です。メインウィンドウに切り替えることなく（開いてすらいなくても）プロンプトを飛ばせます。**Settings → Advanced → Quick Entry** で有効にします。既定のショートカットは **Ctrl/Cmd+Shift+Space** で、自分で変えることもできます（修飾キーを最低1つ含める必要があります）。その組み合わせを別のアプリがすでに使っている場合は、設定の行がそう教えてくれるので、別のものを選べます。

### 音声 {#voice}

Hermes に話しかけ、返事を聞けます。ほかの場所で使えるのと同じ[音声モード](/hermes/docs/user-guide/features/voice-mode/)です。macOS では、OS がマイクの利用許可を一度だけ尋ねてきます。

### HUD モード {#hud-mode}

**⌘/Ctrl+Shift+H**（またはタイトルバーのボタン）を押すと、チャットが枠のない常に最前面のフローティングバーとして切り離され、いま作業している画面の上に浮かびます。アプリのウィンドウは脇へ退き、HUD が進行中の会話と入力欄を保ちます。どこに置くかがそのまま文脈になります。バーの位置が、どのアプリのどの画面について尋ねているのかを Hermes に伝えるので、「これ」「ここ」「このページ」がバーの下にあるものを指すようになります。

- **バーを動かす** — macOS と Windows では、入力欄のどこかを **少し長めに押し込んで** からドラッグします。Linux/X11 では、**Ctrl** を押しながらマウスの主ボタンでドラッグすると、その場でつかめます（文字を選択している場所の上からでも効きます）。長押しからのドラッグも引き続き使えます。つかんだまま仮想デスクトップを切り替えるショートカットを押せば、HUD を別の仮想デスクトップへ連れていけます。ネイティブの Wayland では、入力欄のバー自体がコンポジタのドラッグ用のつまみになります（アプリが自分のウィンドウの位置を決められないため、動かす方法はこれだけです）。
- **大きさを変える** — バーのどの辺や角をドラッグしても変えられます。反対側の辺は固定されたままです。ネイティブの Wayland では右辺と下辺だけが使えます。コンポジタが、アプリ自身に最上位ウィンドウの位置を決めさせないためです。
- **配置を戻す** — バーにある取り消しの操作で、既定の大きさに戻ります（X11・macOS・Windows では位置も戻ります）。保存された大きさのせいで HUD が使いものにならなくなったときに使ってください。
- **ポインタに寄せる** — **⌘/Ctrl+Shift+G**（グローバルなホットキーで、どのアプリからでも効きます）を押すと、HUD がカーソルのある場所へ飛んできます。ネイティブの Wayland では何も起きません。配置はコンポジタが握っているためです。
- **終了する** — バーの終了ボタンをクリックするか、もう一度 **⌘/Ctrl+Shift+H** を押します。セッションはそのままで、アプリのウィンドウが戻ってきます。

#### Linux / Wayland {#linux-wayland}

Electron 20 以降は、Wayland セッションではすでにネイティブの Wayland クライアントとして動きます。ドラッグ、クリックの素通し、大きさの変更は、その経路でも働きます。

**Hyprland**（Omarchy を含みます）では、HUD がウィンドウとして配置されたあとに、コンポジタの IPC を通してフローティング扱いにし、最前面に固定します。そうしないと Hyprland がほかのウィンドウと同じようにタイル状に並べてしまい、`always-on-top` は無視され、コンポジタでのドラッグも効きません。追加のウィンドウルールを書く必要はありません。

コンポジタによっては（とくに COSMIC）、ネイティブの Wayland ウィンドウに対して `always-on-top` を無視します。そうした環境で最前面固定を取り戻すには、アプリを XWayland の下で動かしてください。

```yaml
desktop:
  ozone_platform_hint: x11
```

これは起動時に `ELECTRON_OZONE_PLATFORM_HINT` へ橋渡しされます（環境変数を明示的に指定した場合は、そちらが優先されます）。引き換えになるのは、X11 ではマウスを素通しにしたウィンドウを元に戻せないため、HUD がクリックの素通しではなく、ふつうの実体のあるウィンドウのままになる点です。KDE の環境では、X11 の ozone バックエンドでキーボードが効かなくなるという報告もあります。最前面固定がどうしても必要でなければ、この指定は `auto` のままにしておいてください。

### 設定と初期セットアップ {#settings-onboarding}

プロバイダ・モデル・ツール・認証情報を、YAML を編集する代わりに実際の UI から管理できます。初回起動時の案内に沿えば、数秒で最初のメッセージまでたどり着けます。設定画面はプロバイダとキー、モデルの選択、ツールセットの設定、MCP サーバー、ゲートウェイ、セッション管理をひととおり扱います。

- **プロバイダ設定の画面** — 推論プロバイダを管理する専用の場所で、サインインとプロバイダごとの認証情報の保存を Accounts / API キーの形で扱います。
- **メニューにはすべてのプロバイダとモデルが並びます** — GUI は `hermes model` が知っているプロバイダとモデルをすべて表示するので、抜粋ではなく CLI と同じ一覧から選べます。
- **xAI Grok の OAuth** — Grok はランチャーで一級の OAuth プロバイダとして扱われます。ほかの OAuth プロバイダと同じくブラウザの流れでサインインします。
- **GUI からのツールバックエンドのインストール** — ツールバックエンドのセットアップ後の導入手順を、ターミナルに降りずにアプリから直接実行できます。
- **ターミナルのフォント選択** — **Settings → Appearance** でインストール済みのフォントを選べます。`MesloLGS NF` のような Nerd Font なら、対話用のターミナルでもエージェント用のターミナルでも Powerlevel10k の区切りやアイコンがきちんと描画されます。この設定はプロファイルごとに保存されます。
- **補助モデルの警告** — 補助的な処理（タイトル付け、要約などの手伝い）が別のプロバイダに固定されたまま、main のモデルを新しいプロバイダに切り替えた場合、アプリが警告します。知らないうちに2つのプロバイダに作業が分かれてしまうのを防ぐためです。
- **VS Code Marketplace のテーマ** — 組み込みのテーマに加えて、外観の設定から VS Code Marketplace をその場で検索できます。好きなカラーテーマを選ぶと、アプリがダウンロードして変換し、デスクトップのテーマとして導入します。同じ取り込み機能はコマンドパレット（*Install theme*）からも使えますし、取り込んだテーマは外観の設定から削除できます。
- **コンピュータをスリープさせない** — **Settings → Advanced → Keep computer awake** を使うと、端末がスリープしなくなるので、長時間や夜通しのエージェントの実行が止まりません（画面が暗くなることはあります）。これは端末ごとの設定です。

初回起動時の案内は、統一されたオーバーレイのデザインシステムに刷新されました。**Choose provider later** を選べば、プロバイダの設定を後回しにして先にアプリへ入れます。

#### プロファイルごとの設定: 「Applies to」の適用範囲 {#per-profile-settings-the-applies-to-scope}

[プロファイル](/hermes/docs/user-guide/profiles/)が2つ以上あるとき、設定ファイルに紐づく設定ページ（**Model、Workspace、Safety、Memory & Context、Voice、Chat、Advanced、Tools & Keys**）と **Messaging** のオーバーレイの上部に、共通の **Applies to** のチップ列が現れます。ここで、編集がどのプロファイルに効くかを選びます。

- 既定では **いま使っているプロファイル** が選ばれていて、これは以前とまったく同じ挙動です。使っているプロファイルをそのまま編集します。
- 別のプロファイルを選ぶと、アプリ全体を切り替えずに *そのプロファイル* の設定を見て編集できます。選択は設定ページを移動しても保たれます。
- アプリの使用中プロファイルを切り替えると選択はリセットされるので、以前選んだプロファイルに編集が黙って入り続けることはありません。
- プロファイルが2つ未満のときは、チップ列そのものが隠れます。

（Gateways のページはプロファイルの扱いが異なり、**Per-profile overrides** の小見出しで扱います。Capabilities と Scheduled Jobs のビューには、それぞれ独自の適用範囲の選択欄があります。）

### 管理画面 {#management-panes}

ターミナルに降りなくて済むように、Hermes の管理まわりもアプリから扱えます。

- **Skills** — [スキル](/hermes/docs/user-guide/features/skills/)を眺め、導入し、管理します。
- **記憶グラフ（Star Map）** — チャットで `/journey`（別名 `/learning`、`/memory-graph`）と入力すると、学んだスキルと記憶が時間とともに並ぶ対話的な星座図が開き、再生用のつまみで時間を動かせます。ノードはこのパネルからそのまま編集・削除できます（スキルは保管され、記憶は削除されます）。[Learning Journey](/hermes/docs/user-guide/features/memory/#learning-journey-journey) を参照してください。
- **Cron** — [スケジュール実行されるジョブ](/hermes/docs/reference/cli-commands/#hermes-cron)を確認・管理します。
- **Profiles** — [Hermes のプロファイル](/hermes/docs/user-guide/profiles/)（設定・スキル・セッションが分離された単位）を切り替えます。
- **Messaging** — ゲートウェイのチャンネルを設定します。
- **Agents** と **Command Center** — 複数エージェントでの作業を束ねる画面です。

### Bot Mode（組み込み） {#bot-mode-built-in}

**Bot Mode** はアプリに同梱されていて、既定で有効です。「エージェント1つにつきチャット1つ」
の名簿で、[Hermes のプロファイル](/hermes/docs/user-guide/profiles/)それぞれがボットとして並びます。ボットには
それぞれのアバター（幾何学的な顔、アップロードした画像、AI が生成した肖像、ドット絵の
ペット）、それぞれの正規の **Bot Chat** の会話、それぞれの **Routines**
（Hermes の cron に支えられた繰り返しのタスク）があります。名簿は左サイドバーの中で
会話の隣のタブとして置かれ、**Sessions | Bots** のタブ列になっています。
セッション一覧の下に2つ目のペインを積む形ではありません。以前の積み上げ式の
配置を使っていた環境は、一度だけ自動でタブ列へ移されます。自分でペインを
配置していた場合は、その配置はそのままにされます。**Cronjobs**（Routines）の
ペインは、Bots タブが選ばれている間だけチャットの横に出て、Sessions に
戻ると消えます（古いデスクトップのビルドでは常に表示されたままです）。

新しいエージェントは名簿から作れます。
Name / Title / Description に加えて、Advanced を開くと機能の全体（モデル、SOUL、
スキル、ツールセット、MCP サーバー）を指定できます。セクションにまとめたり、
複数のボットが話し合うグループチャットを開いたりもできます。
グループチャットは名簿の中に Discord 風の独立した行として現れ、メンバーの
アバターが重なって並び、人数と直近の発言のプレビュー、そして
「needs you」のバッジが付きます。ボットの行と同じピン留め＋新着順の並びに
混ざって表示されます。グループの行をクリックすると、その部屋が
**メインのチャットウィンドウ** を占めるタブとして開きます（古いデスクトップの
ビルドでは、代わりに bots のサイドパネル内で開きます）。

ボット同士もやり取りします。どのチャットでも `@researcher have a look at this` のように書けば、
いま動いているボットがメッセージを引き渡し、結果を報告します。ボットは互いの
Bot Chat に直接届きます（`hermes -p <bot> chat`）。バックエンドが各ボットの正規の
**Bot Chat** セッションにメッセージングの手順を自動で教え込むので
（設定は `agent.bot_mode_protocol`、既定で有効）、仲間のボットが CLI から
画面なしで開いた場合も含めて、SOUL.md に手を入れなくてもボット同士の
返信と引き渡しが動きます。普段のセッションはそのままです。

Bot Mode のセッション（各ボットの正規の Bot Chat と、グループチャットの
メンバーごとのセッション）は、全体の Sessions サイドバーからは常に隠されます。
自分の会話に混ざるのではなく、Bots ペイン（名簿の行、部屋のビュー、
各ボットのセッション一覧）の中に置かれます。

使っていないボットはしまっておけます。ボットの行を右クリックして **Hide
Bot** を選びます。隠したボットは名簿から消えますが、働き続けます。@メンションは
届きますし、グループチャットの参加状態もそのままです。1つでも隠れたボットが
あると Bots のヘッダーに目のアイコンが出て、クリックすると隠したボットが
薄い表示のまま元の位置に現れます（右クリック → **Unhide Bot** で戻せます）。
隠したボットに未読の動きがあると、目のアイコンに点が付きます。隠しているか
どうかはボットのプロファイルに保存されるので、端末をまたいでも付いてきます。

いらない場合は **Settings → Plugins → Bots** で切ってください。名簿・
routines のペイン・入力欄のミドルウェアがその場で解除され、再起動は不要です。

詳しい手引き（複数の端末にまたがる **Create on** の選択欄を含むエージェントの作成、
接続をまたいだ名簿、ボット同士のメンション、グループチャットで誰が返事をするかの
決め方）は [Bot Mode: A Roster of Agents](/hermes/docs/user-guide/bot-mode/) にあります。

### キーボードと移動 {#keyboard-navigation}

- **コマンドパレット** — **Cmd+K** または **Cmd+P**（Windows / Linux では Ctrl+K / Ctrl+P）を押すと、キーボードだけで操作とページ移動ができます。任意のページや設定の節を開き、タイトルや id でセッションに飛び、モデル・テーマ・配色を切り替え、ターミナルを立ち上げ、ゲートウェイを再起動し、Hermes を更新する、といったことができます。
- **割り当てを変えられるショートカット** — **Settings → Keyboard Shortcuts**（または **Cmd/Ctrl+/**）でショートカットのパネルが開き、ほとんどすべての割り当てを変えられます。プロファイルの切り替え、セッションの移動、表示の切り替え、デスクトップのプラグインが追加したショートカットも対象です。重複した割り当ては衝突として印が付きます。覚えておくとよい既定値をいくつか挙げます。**Cmd/Ctrl+N** で新しいセッション、**Cmd/Ctrl+.** で Command Center、**Cmd/Ctrl+,** で設定、**Cmd/Ctrl+Shift+F** でセッションの検索、**Cmd/Ctrl+1–9** でプロファイルの切り替え、**Shift+X** で明暗の切り替えです。
- **拡大縮小のショートカットの調整** — 画面を半段ずつ拡大縮小できるので、文字の大きさを細かく合わせられます。
- **UI の言語切り替え** — アプリの表示言語をアプリ内で変えられます。簡体字中国語（zh-Hans）も含みます。

### セッションとプロファイル {#sessions-profiles}

- **セッション一覧の作り直し** — 保管の機能を備えた一覧に作り直され、増えても扱いやすいように整理できます。
- **id でセッションを検索** — 特定のセッションを id から直接見つけられます。
- **複数プロファイルの同時セッション** — 複数の[プロファイル](/hermes/docs/user-guide/profiles/)にまたがるセッションを同時に動かせます。別のプロファイルのセッションは、プロファイルをまたぐ `@session` のリンクで参照できます。
- **プロファイルの書き出しと読み込み** — 設定一式を1つのファイルとして渡せます。**⌘K → Export profile…**（またはレールのプロファイルの四角を右クリック）を選ぶと、スキル・記憶・人格・cron・プラグイン・設定を含む `.tar.gz` が書き出されます。API キーは取り除かれます。デスクトップから書き出すと外観と表示まで一緒に入ります。スキン、明暗モード、独自のテーマ、そのプロファイルのレールの色、ウィンドウの配置まで含まれるので、読み込んだ側には送り手と同じ見た目で届きます。読み込みは **⌘K → Import profile…** か、レールの **+** の隣のボタンから行います。上書きが適用され、新しいプロファイルに切り替わります。同じアーカイブは、チャットの `/export` / `/import` でも、shell からの `hermes profile export` / `import` でも使えます。[プロファイルファイルの書き出しと読み込み](/hermes/docs/user-guide/profile-distributions/#export-and-import-a-profile-file)を参照してください。

## 更新 {#updating}

アプリは裏で更新を確認していて、準備ができるとワンクリックでの更新を案内します。

デスクトップアプリと、その相手となる Hermes のバックエンドは、別々のタイミングで更新されます。アプリは自分の端末の中で、バックエンドは動いている場所で更新されます。更新の対象が複数ある場合（リモートのゲートウェイや、登録済みのゲートウェイが複数ある場合）、更新の入り口（About パネルの **Update now**、⌘K の **Update Hermes** の行、更新準備完了の通知）は **すべて** を更新します。まず接続中のバックエンド、次に対象となる登録済みのゲートウェイすべて（Hermes Cloud の項目はプラットフォーム側が管理するため飛ばされます）、そして最後にデスクトップアプリ自身です。クライアントの更新を適用するとアプリが再起動するためこの順になっています。端末が1台だけの環境では、これまでどおりボタン1つで済みます。

バックエンドを更新したあとは、アプリが自分自身のバージョンも確認し直し、GUI が遅れていればワンクリックの **Update desktop app** の操作を添えて知らせます。リモートのバックエンドを更新した結果、古いデスクトップのビルドに気づかず取り残される、ということが起きないようになっています。

[手動での更新手順](https://hermes-agent.nousresearch.com/docs/getting-started/updating)も GUI で使えます。

## アンインストール {#uninstalling}

**Settings → About → Danger zone** を開き、どこまで消すかを選びます。

- **Uninstall Chat GUI only** — デスクトップアプリとそのデータを消します。Hermes エージェント・設定・チャットは残ります。（`hermes uninstall --gui` と同じです。）
- **Uninstall GUI + agent, keep my data** — アプリとエージェントを消しますが、あとで入れ直せるように設定・チャット・秘密情報は残します。（`hermes uninstall` と同じです。）
- **Uninstall everything** — アプリ・エージェント・すべてのユーザーデータを消します。（`hermes uninstall --full` と同じです。）

処理を終えるためにアプリは閉じます（終了後に後片付けが走るので、動いているアプリのバンドルと自身の venv を消せます）。ローカルにエージェントが入っていない場合（たとえばリモートのバックエンドにつないだ GUI だけの「lite」なクライアント）は、エージェントを消す選択肢は自動的に隠れます。

同じことはターミナルからもできます。GUI だけなら `hermes uninstall --gui`、エージェントも消すなら `hermes uninstall` または `hermes uninstall --full` です。

:::note
**ソースのチェックアウト**（`hermes desktop` の開発ビルド）から `hermes uninstall --gui` を実行すると、ワークスペースの `node_modules` と `apps/desktop/{dist,release}` のビルド出力も消えます。これらは GUI のビルド成果物だからです。`hermes desktop`（または `npm install` と再ビルド）で元に戻せますが、デスクトップアプリ自体をいじっている最中なら、あとで依存関係を入れ直すことになると思っておいてください。
:::

## CLI 早見表: `hermes desktop` {#cli-reference-hermes-desktop}

CLI から起動するには `hermes desktop` を実行するだけです。既定では、ワークスペースの Node の依存関係を入れ、いまの OS 向けに展開済みの Electron アプリをビルドし、そのパッケージされた成果物を起動します。

| フラグ               | 説明                                                                                       |
| -------------------- | ----------------------------------------------------------------------------------------- |
| `--skip-build`       | npm のインストールとパッケージを飛ばし、`apps/desktop/release` にある既存の展開済みアプリを起動します |
| `--force-build`      | 内容のスタンプが一致していても、まるごと再ビルドします                                     |
| `--build-only`       | デスクトップアプリをビルドしますが起動はしません（`hermes update` が使います）             |
| `--source`           | パッケージ済みのアプリではなく、`apps/desktop/dist` に対して `electron .` で起動します     |
| `--cwd PATH`         | デスクトップのチャットセッションが最初に開くプロジェクトのディレクトリ（`HERMES_DESKTOP_CWD` を設定します） |
| `--hermes-root PATH` | アプリが使う Hermes のソースの起点を上書きします（`HERMES_DESKTOP_HERMES_ROOT` を設定します） |
| `--ignore-existing`  | バックエンドの解決時に、`PATH` 上にすでにある `hermes` CLI を無視させます                  |
| `--fake-boot`        | 起動時の UI を確かめるために、決まった長さの起動待ちを入れます                             |

## しくみ {#how-it-works}

パッケージされたアプリには、Electron のシェルとネイティブの React 製チャット画面が入っています。初回起動時には、Hermes Agent のランタイムを `HERMES_HOME`（`~/.hermes`、Windows では `%LOCALAPPDATA%\hermes`）へ導入できます。これは **CLI でインストールした場合とまったく同じ配置** で、だからこそ両者は入れ替えて使えます。バックエンドの解決は、まず `HERMES_DESKTOP_HERMES_ROOT` を尊重し、次に完了済みの管理下インストール、次に `PATH` 上で見つかった `hermes`（`--ignore-existing` / `HERMES_DESKTOP_IGNORE_EXISTING=1` が指定されていない場合）、最後に Nix のようなパッケージ作成者向けの明示的な `HERMES_DESKTOP_HERMES` によるコマンドの上書き、という順で進みます。React のレンダラーは、アプリが代わりに起動する画面なしのバックエンドと話します。これは `tui_gateway` の JSON-RPC / WebSocket API を提供する `hermes serve` のプロセスで、`hermes --tui` を埋め込むのではなくエージェントのランタイムを再利用します。デスクトップアプリは **自己完結** していて、自分の `hermes serve` バックエンドを動かし、[Web ダッシュボード](/hermes/docs/user-guide/features/web-dashboard/)を開くことも必要とすることもありません。（`serve` コマンドより古いランタイムでは、画面なしの `dashboard --no-open` へ自動的に切り替わるので、アプリの更新がバックエンドを追い越してしまうことはありません。）インストール・バックエンドの解決・自己更新の処理は Electron のメインプロセスにあります。

## リモートバックエンドに接続する {#connecting-to-a-remote-backend}

既定では、アプリは自分の **ローカル** のバックエンドを起動して面倒を見ます。代わりに、別の端末で動いている Hermes のバックエンド（VPS、自宅のサーバー、Tailscale の向こうにある Mini など）を指すこともできます。

接続まわりはすべて1つの設定ページにまとまっています。**Settings → Gateways** です。（古いビルドでは **Gateway** と **Connections** の別々のページに分かれていました。いまは統合されていて、古い `?tab=connections` のリンクは統合後のページへ転送されます。）

**Settings → Gateways → Connection mode** では、ローカルのゲートウェイ以外の選択肢が示されます。

- **Remote gateway** — 自分で動かしている `hermes serve` バックエンドの URL を入力してサインインします。この節の残りで説明するのはこのやり方です。
- **Hermes Cloud** — Hermes Cloud に一度サインインすれば、アカウントにあるエージェントから選ぶだけです。URL を貼り付ける必要はありません。アプリがエージェントを見つけてきて（アカウントが複数の組織にまたがる場合は組織の選択欄が出ます）、どれかにつなぐとセッションが自動で切り替わります。接続中はステータスバーにクラウドの接続が表示されます。

ゲートウェイの接続は **端末単位** です。Gateways のページは、このデスクトップがどのゲートウェイのバックエンドにつなげるかを管理し、プロファイルは接続したゲートウェイ *から* 見つかります。セッションは一度に1つのゲートウェイを選び、隣のプロファイルのレールでは、そのゲートウェイ上で見つかったプロファイルを選びます。

### 複数接続の登録簿 {#the-multi-connection-registry}

同じ **Settings → Gateways** のページを下に進むと、**Registered gateways** があり、アプリが知っているすべての Hermes ゲートウェイの名前付き一覧を管理できます。ローカルのランタイム、いくつでも登録できるリモートのゲートウェイ（LAN、Tailscale、インターネット）、Hermes Cloud のインスタンス、SSH のホストが、すべて1か所にまとめて保存されます。サイドバーのプロファイルのレール右端にあるプラグのボタン（**Connect another Hermes gateway…**）か、**⌘K → Gateways** から開けます。統合されたエージェントの名簿、`@name-device` の書き方、まとめての更新、プラグイン SDK まで含めた詳しい手引きは、[Desktop を複数の Hermes インスタンスにつなぐ](/hermes/docs/user-guide/multi-connection-desktop/)にあります。

- **接続にはそれぞれ固有の名前が必要です**（「Homelab」「Work laptop」のような端末名です）。同じプロファイル名が複数の登録済みゲートウェイに存在する場合、画面上では `@profile-device` の形で区別されます（例: `@research-homelab`）。
- **Sessions サイドバーからゲートウェイを切り替えられます。** ゲートウェイが2つ以上登録されると名前付きの選択欄が現れ、登録数がいくら増えてもゲートウェイがプロファイルのように見えてしまうことなく扱えます。隣のプロファイルのレールにはそのゲートウェイのエージェントだけが並び、そこで最後に使ったプロファイルを覚えています。プロファイルが多い場合は、それとは別にまとめて表示されます。
- **再起動後に何を開くかを選べます。** **Open on launch** は、これまでどおりの **Primary gateway** を既定として保ちますが、接続に成功したあとに **Last used** のゲートウェイを再開させることもできます。この設定はアプリケーションのバンドルの外に保存されるので、Desktop の更新をまたいでも残ります。
- 接続の **追加・編集・削除・テスト** はこのパネルから行います。**Add** では4種類すべてを選べます。**Local**、**Hermes Cloud**、**Remote gateway**、**SSH** です（アプリが管理するローカルの項目がある間は Local のボタンは押せません。クラウドの追加については、上のサインイン／検出の流れを案内するヒントが出ます）。ローカルの項目はアプリが管理していて、削除できません。**Test** は、その接続の HTTP と WebSocket それぞれの経路を直接調べます。
- **重複は保存時に弾かれます。** **local** の項目は常に1つだけです。リモートとクラウドの項目は正規化した URL（前後の空白を除き、末尾のスラッシュを取り、小文字にしたもの）で重複を判定します。これは両方の種類をまたいで行われます。SSH の項目は、正規化した `user@host:port` とリモートのプロファイルで判定します。
- 登録簿を備えたビルドを初めて動かすと、既存の設定は **自動で取り込まれます**。いまのグローバルな接続と、以前のプロファイルごとの上書き設定が、名前付きの項目になります。以前の設定ファイルはそのまま残るので、古いビルドも動き続けます。
- クラウドの項目は、上の Hermes Cloud のサインイン／検出の流れから作られるもので、手で URL を打ち込むものではありません。
- トークンは OS のキーリングで暗号化して保存されます（キーリングの無い Linux では、明示的に平文を選ぶこともできます）。

横並びの振り分けはすでに動いています。登録済みのゲートウェイはそれぞれ、必要になったときに自分のバックエンドとソケットを開き（接続＋プロファイルごとに管理されます）、プラグイン SDK は統合されたエージェントの名簿を提供し（`host.agents()` / `host.ensureAgent()`）、Gateways のページの **Update all instances** は対象となるすべてのゲートウェイに `hermes update` を一斉に送ります。Hermes Cloud の項目は飛ばされ（プラットフォーム側が更新します）、各インスタンスがそれぞれの結果を報告します。

:::info リモートバックエンドとは動いている `hermes serve` のプロセスです
「リモートバックエンド」とは、リモートの端末で動いている **`hermes serve`** のサーバーのことです。デスクトップアプリが接続する相手はこのプロセスです。そのバックエンドが実際に動いていて届く状態でなければ、この節のことは何も動きません。デスクトップアプリが代わりに起動してくれるわけではありません。リモートのホスト側で、自分（または `systemd` のサービス）が `hermes serve` を動かし続け、アプリはそこにつなぎに行きます。メッセージングのチャンネル（Telegram、Discord など）も使っている場合、**ゲートウェイ** は *別の* 常駐プロセスで、自分で起動します。セットアップ手順のあとの注意書きを参照してください。
:::

接続は2つの側面からできています。バックエンド側では **認証プロバイダ** で守り、アプリ側ではバックエンドの URL を入れてサインインします。バックエンドをループバック以外のアドレスに割り当てると自動的に認証の関門が有効になり、設定した認証プロバイダがデスクトップアプリを通す役目を果たします。

**バックエンドがどこにあるかでプロバイダを選びます。**

- **OAuth（Nous Portal） — 自分の端末の外から届く用途にはこちらが望ましいです。** ログインは Nous のアカウントに対して検証されるので、VPS や公開されたホスト、その他のリモートバックエンドに適した選択肢です。`hermes dashboard register`（または Portal の [`/local-dashboards`](https://portal.nousresearch.com/local-dashboards) ページ）でダッシュボードを登録して OAuth のクライアントを用意し、アプリから **Sign in with Nous Research** でサインインします。自分で ID プロバイダを運用しているなら、自前の OIDC プロバイダでも同じように動きます。
- **ユーザー名とパスワード — ローカルまたは信頼できるネットワークの中だけで使ってください。** バックエンドが同じ信頼できる LAN 上にあるか、VPN（Tailscale など）越しにしか届かない場合の、いちばん簡単な選択肢です。外部の ID プロバイダを使わずに1つの共有の資格情報で守るだけなので、**公開インターネットに晒すダッシュボードには使わないでください**。その場合は OAuth を選びます。

この節の残りでは、信頼できるネットワーク上でいちばん手早く立ち上げられるユーザー名とパスワードのやり方を示します。OAuth のやり方は [Web ダッシュボード → 既定のプロバイダ: Nous Research](/hermes/docs/user-guide/features/web-dashboard/#default-provider-nous-research)を参照してください。

### バックエンド側（リモートの端末）で {#on-the-backend-the-remote-machine}

ユーザー名とパスワードを設定してから、届くアドレスに割り当ててバックエンドを起動します。資格情報は `~/.hermes/.env`（モード 0600 の秘密情報ファイル）に置きます。

```bash
# 1. Set the dashboard login credentials.
cat >> ~/.hermes/.env <<'EOF'
HERMES_DASHBOARD_BASIC_AUTH_USERNAME=admin
HERMES_DASHBOARD_BASIC_AUTH_PASSWORD=choose-a-strong-password
# Recommended: a stable signing secret so sessions survive restarts.
# Without it a random key is generated per boot and you'll be logged out
# on every restart.
HERMES_DASHBOARD_BASIC_AUTH_SECRET=$(openssl rand -base64 32)
EOF
chmod 600 ~/.hermes/.env

# 2. Run the backend bound to a reachable address. The non-loopback bind
#    engages the auth gate; the username/password provider handles login.
hermes serve --host 0.0.0.0 --port 9119
```

デスクトップアプリからつなげるようにしておきたい間は、この `hermes serve` のプロセスを動かし続けてください。止まればアプリはバックエンドに届かなくなります。ログアウトや再起動をまたいで残るように、`systemd` や `tmux`、あるいは好みのプロセス管理の仕組みの下で動かしてください。

これとは別に、メッセージングのチャンネルを使っているなら、リモートのホストで **ゲートウェイが動いていること** も確かめてください。デスクトップアプリが話す相手は `hermes serve` のバックエンドですが、Telegram / Discord / Slack のゲートウェイのセッションは、自分で起動して動かし続ける別のプロセスです。ゲートウェイの設定は [メッセージング](/hermes/docs/user-guide/messaging/)を参照してください。

パスワードを平文のまま置いておきたくない場合は、代わりに `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD_HASH` に scrypt のハッシュを設定します。ハッシュは `python -c "from plugins.dashboard_auth.basic import hash_password; print(hash_password('PW'))"` で計算できます。設定項目の全容（config.yaml のキー、すべての環境変数、レートリミッタ）は [Web ダッシュボード → ユーザー名とパスワードのプロバイダ](/hermes/docs/user-guide/features/web-dashboard/#usernamepassword-provider-no-oauth-idp)にあります。

バックエンドを systemd のサービスとして動かす場合は、ユニットに `EnvironmentFile=%h/.hermes/.env` を指定して、起動時に資格情報が環境へ入るようにしてください。

:::warning
バックエンドは `.env`（API キーや秘密情報）を読み書きし、エージェントのコマンドを実行できます。上に示した **ユーザー名とパスワード** の設定は信頼できるネットワーク向けです。パスワードで守っただけのバックエンドを、公開インターネットに直接晒してはいけません。VPN の内側に置いてください。[Tailscale](https://tailscale.com/) はすっきりした選択肢です。端末の tailscale の IP に割り当て（`--host <tailscale-ip>`）、Remote URL に `http://<tailscale-ip>:9119` を使えば、自分の tailnet からしか届かなくなります。公開インターネット越しにバックエンドへ届かせたい場合は、代わりに **OAuth（Nous Portal）** のプロバイダを使ってください。
:::

### アプリ側で {#in-the-app}

**Settings → Gateways → Remote gateway** で行います。

1. **Remote URL** — `http://<backend-host>:9119` を入れます（リバースプロキシを前に置いているなら `/hermes` のようなパスの接頭辞も使えます）
2. **Sign in** — アプリはバックエンドが名乗るプロバイダを見分けて、ボタンを合わせます。ユーザー名とパスワードのバックエンドなら **Sign in** のボタンが出て、資格情報の入力欄が開きます（手順1で設定した資格情報を入れてください）。OAuth のバックエンドなら **Sign in with `<provider>`**（例: *Sign in with Nous Research*）が出て、そのプロバイダのブラウザでのサインインが走ります。どちらの場合も、最終的にアプリはバックエンドに対して認証済みのセッションを持つことになります。
3. **Save and reconnect** — デスクトップの画面をリモートのバックエンドへ切り替えます。セッションは自動で読み直され、`HERMES_DASHBOARD_BASIC_AUTH_SECRET` を設定していれば再起動をまたいでもサインインしたままになります。

UI を使わずに、アプリを起動する前に環境変数 `HERMES_DESKTOP_REMOTE_URL` でバックエンドの URL を指定することもできます（アプリ内の設定より優先されます）。その場合もサインインは Gateways の設定パネルから行います。

:::note プロファイルごとのリモートホスト
リモートのゲートウェイのホストは[プロファイル](/hermes/docs/user-guide/profiles/)ごとに設定されるので、プロファイルごとに別々のリモートバックエンドを指す（あるいはローカルのままにする）ことができます。プロファイルを切り替えると、アプリがつなぐリモートのホストも切り替わります。
:::

### 困ったとき {#troubleshooting}

- **サインインが 401 や「Invalid credentials」で失敗する** — ユーザー名かパスワードが、バックエンドの `HERMES_DASHBOARD_BASIC_AUTH_USERNAME` / `HERMES_DASHBOARD_BASIC_AUTH_PASSWORD` と一致していません。バックエンドは、存在しないユーザーの場合もパスワードが違う場合も同じ汎用のエラーを返す（どちらなのかを外から探れないようにする）ので、両方を見直してください。関門が有効かどうかは `curl -s http://<host>:9119/api/status | jq '.auth_required, .auth_providers'` で確かめられます。`true` が返り、`"basic"` が含まれているはずです。
- **「Sign in」のボタンが出ず、代わりにセッショントークンを求められる** — バックエンドのユーザー名とパスワードのプロバイダが有効になっていません。`/api/status` の `auth_providers` に `"basic"` が並びません。ユーザー名とパスワード（またはパスワードのハッシュ）の両方が `~/.hermes/.env` に設定されていること、そしてダッシュボードのプロセスがそれを実際に読み込んでいることを確かめてください。
- **再起動のたびにサインアウトされる** — `HERMES_DASHBOARD_BASIC_AUTH_SECRET` に固定の値を設定してください。設定しないと、トークンに署名する鍵が起動のたびに作り直され、すべてのセッションが無効になります。
- **接続が拒否される／タイムアウトする** — バックエンドが `127.0.0.1`（既定）に割り当てられているか、ファイアウォールや VPN がポートを塞いでいます。`0.0.0.0` か tailscale の IP に割り当て、信頼できるネットワークに対してポートを開いてください。

同じ設定を Web ダッシュボード側から見た説明は [Web ダッシュボード → Hermes Desktop をリモートバックエンドに接続する](/hermes/docs/user-guide/features/web-dashboard/#connecting-hermes-desktop-to-a-remote-backend)にあります。環境変数の一覧は [環境変数 → Web ダッシュボードと Hermes Desktop](/hermes/docs/reference/environment-variables/#web-dashboard--hermes-desktop)にまとまっています。

## デスクトップアプリを拡張する {#extending-the-desktop-app}

デスクトップアプリは追加していける作りになっています。ペイン・ページ・サイドバーの
移動項目・ステータスバーの項目・パレットのコマンド・キー割り当て・テーマは、すべて1つの SDK を
通して登録されるので、自分の分も足せます。プラグインは
`$HERMES_HOME/desktop-plugins/<id>/plugin.js` に置く1つの ESM ファイルです。アプリは数秒で読み込み、
保存するたびに再読み込みします。導入済みのプラグインは **Settings → Plugins** からその場で管理できます。

詳しい一覧は [Desktop Plugin SDK](/hermes/docs/developer-guide/desktop-plugin-sdk/) を
参照してください。（これは [Web ダッシュボードのプラグインの仕組み](/hermes/docs/user-guide/features/extending-the-dashboard/)とは別のものです。）

同じ Settings → Plugins のページにある **Agent plugins** の節では、自分で入れた
バックエンド側（エージェント側）の[プラグイン](/hermes/docs/user-guide/features/plugins/)を管理します。user、
git、project、pip、portable の各インストールが対象です。リポジトリに同梱された組み込みのもの（プラットフォームの
アダプタやプロバイダのプラグインなど）はここには並びません。それらは既定で有効な状態で配られ、
それぞれの画面から設定するものなので、この節は自分で足したものだけに絞られています。プロファイルが2つ以上ある場合は、
この節にも独自の **Applies to** の選択欄が付くので、アプリ全体を切り替えずに別のプロファイルの
エージェントプラグインを一覧したり切り替えたりできます（バックエンドの
`plugins.manage` の RPC は、このために任意の `profile` パラメータを受け付けます）。

## 困ったとき {#troubleshooting}

### 失敗したターンはどの層で失敗したかを示します {#failed-turns-name-the-failing-layer}

ターンが失敗すると、チャットには **どの層が失敗したか** を示すエラーカードが
描かれます。プロバイダ／モデル、独自のエンドポイント、ストリーミングの接続、
認証、課金、ゲートウェイ、ローカルのランタイム、ディスクのいずれかで、
ただの汎用的なエラー通知ではありません。カードには、失敗に合わせた復旧の操作が並びます。

- **Retry** — 失敗したターンをその場でやり直します（内容ポリシーによる拒否など、
  やり直しても必ず同じ結果になる場合は表示されません）。
- **Switch provider** — プロバイダ、エンドポイント、認証、課金の失敗のときに
  Settings → Models へ飛びます。
- **Open logs** — ファイルマネージャで `HERMES_HOME/logs` を開きます。リモートや
  Cloud の接続では、このボタンは **Open Desktop logs** になります。失敗したターンの
  ゲートウェイやエージェントのログはリモートの端末にあるため、ローカルの
  Desktop 側のログ（通信の記録）を開きます。
- **Send diagnostics** — 秘密情報を伏せたデバッグ用の一式を、明示的な同意の確認を
  経てから Nous 社内のストレージへ送ります（`hermes debug share --nous` と同じ
  仕組みです。秘密情報は必ず伏せられ、送ったものを見られるのは Nous のスタッフ
  だけで、14 日で自動的に消えます）。送信できると、サポートのやり取りに貼り付け
  られる非公開の閲覧用リンクに加えて、GitHub Issues・Nous Portal のサポート・
  Discord への近道が表示されます。リモートや Cloud の接続では、バックエンド側が
  自分のエージェントとゲートウェイのログをまとめ、そこにローカルの Desktop の
  ログが添えられるので、サポートは両側をそろって見られます。
- **Copy error details** — 短い平文の要約（層、コード、プロバイダ／モデル、
  エラーメッセージ）をコピーします。不具合の報告や Discord に貼り付けられます。

層の判定は、エージェントの再試行の処理が使っているのと同じエラー分類器から
来ているので、メッセージの文面からの推測ではなく実際の失敗の意味を反映します。
この情報を持たない古いバックエンドでも、汎用のタイトルと Retry / Open logs /
Copy error details の操作を備えたカードは表示されます。

起動時のログは `HERMES_HOME/logs/desktop.log` に残ります（バックエンドの出力と、直近の Python のトレースバックが含まれます）。アプリが起動の失敗を報告したら、まずここを見てください。CLI から追いかけることもできます。

```bash
hermes logs gui -f
```

よく使うリセットの手順です。

```bash
# Force a clean first-launch setup (macOS/Linux)
rm "$HOME/.hermes/hermes-agent/.hermes-bootstrap-complete"

# Rebuild a broken Python venv (macOS/Linux)
rm -rf "$HOME/.hermes/hermes-agent/venv"

# Reset a stuck macOS microphone prompt
tccutil reset Microphone com.nousresearch.hermes
```

### 「The host key has CHANGED since you last connected」（SSH のリモート） {#the-host-key-has-changed-since-you-last-connected-ssh-remote}

SSH のリモートを入れ直したり、ホスト鍵が入れ替わったりすると、SSH は接続を
断って失敗し、Desktop は再試行せずにエラーの表示を出したまま止まります
（古い鍵を消さないかぎり、再試行しても成功しないためです）。その変化が
想定どおりであることを確かめてから、古い項目を消して表示から再試行してください。

```bash
ssh-keygen -R <host>
```

項目を消したら **Retry** をクリックする（または Settings → Gateway で接続を
入れ直す）と、止まっていた状態が解除され、次の起動で新しくつなぎに行きます。

### 「Build desktop app」が Electron のダウンロードで止まる {#build-desktop-app-stuck-on-electron-download}

ビルドは Electron のランタイム（約 114&nbsp;MB）を `github.com/electron/electron/releases` からダウンロードします。インストーラが **Build desktop app** の段階で止まり、実行中の出力に `retrying attempt=…` が繰り返し出ている場合は、そのネットワーク（ファイアウォール、プロキシ、地域）で GitHub が塞がれているか制限されています。

インストーラはこれを自分で立て直します。ビルドに失敗すると、(1) 壊れたキャッシュ済みの Electron の zip を消して再試行し、(2) それでも失敗して `ELECTRON_MIRROR` を設定していない場合は、Electron コミュニティで事実上の標準になっているミラー `npmmirror.com` を通してもう一度試します。`@electron/get` はダウンロードの SHASUM を検証しますが、そのチェックサムも同じミラーから来ています。つまり壊れたり途中で切れたりしたダウンロードは捕まえられますが、ミラー自体が乗っ取られた場合は捕まえられません。第三者のホストを信頼したくない場合は、自分で `ELECTRON_MIRROR` を指定してください（下記）。ビルドは、指定されたものを上書きすることはありません。

**自分でミラーを選ぶ**（社内や信頼できるものなど）には、インストールの前に `ELECTRON_MIRROR` を設定するか、手で再ビルドします。ビルドはその指定を尊重し、上書きしません。

```bash
ELECTRON_MIRROR=https://npmmirror.com/mirrors/electron/ \
  bash -c 'cd "$HOME/.hermes/hermes-agent/apps/desktop" && CSC_IDENTITY_AUTO_DISCOVERY=false npm run pack'
```

壊れたキャッシュ済みの zip を手で消すには、次のようにします。

```bash
rm -f "$HOME/Library/Caches/electron"/electron-*.zip   # macOS
rm -f "$HOME/.cache/electron"/electron-*.zip            # Linux
```

## ソースからビルドする {#building-from-source}

アプリ自体に手を入れたい場合は、リポジトリのルートで一度ワークスペースの依存関係を入れてから、`apps/desktop` で開発サーバーを動かします。

```bash
npm install          # from repo root — links apps/desktop, web, apps/shared
cd apps/desktop
npm run dev          # Vite renderer + Electron, which boots the Python backend
```

特定のチェックアウトを指したり、実際の設定から切り離して動かしたりするには、次のようにします。

```bash
HERMES_DESKTOP_HERMES_ROOT=/path/to/clone npm run dev
HERMES_HOME=/tmp/throwaway npm run dev
npm run dev:fake-boot   # exercise the startup overlay with deterministic delays
```

インストーラをビルドするには、次のようにします。

```bash
npm run dist:mac     # DMG + zip
npm run dist:win     # NSIS + MSI
npm run dist:linux   # AppImage + deb + rpm
npm run pack         # unpacked app under release/ (no installer)
```

macOS と Windows の署名および公証は、必要な資格情報が環境にあれば自動的に走ります（macOS では `CSC_LINK` / `CSC_KEY_PASSWORD` / `APPLE_*`、Windows では `WIN_CSC_*` です）。

### macOS の権限とローカルでの再ビルド（TCC） {#macos-permissions-and-local-rebuilds-tcc}

**フォルダごとの確認を、ひとつの設定でまとめて止められます。** macOS は、Hermes が
フォルダに触れるたびに種類ごと（デスクトップ、次にダウンロード、次に書類……）に
確認を出します。**フルディスクアクセス**をひとつ許可すればそのすべてを一度にまかなえ、
Hermes の署名の識別子は変わらないので、更新をまたいでも許可は残り続けます。

1. システム設定 → **プライバシーとセキュリティ → フルディスクアクセス**（または
   `open "x-apple.systempreferences:com.apple.preference.security?Privacy_AllFiles"` を実行します）
2. 使っているターミナルアプリを有効にします。デスクトップ版を使うなら **Hermes.app** も
   有効にします。
3. どちらも一度完全に終了してから起動し直します。

`hermes doctor` は、いま使っているターミナルがすでにこの許可を持っているかどうかを
教えてくれます。持っていない場合は、macOS 上の `hermes setup` がこの案内を表示します。

macOS は、権限の許可（フルディスクアクセス、デスクトップ／ダウンロード／書類、
アクセシビリティ、オートメーション、マイク）を、アプリのパスではなく *コード署名の
識別子* に紐づけて覚えています。ローカルでビルドしたアプリや自己更新したアプリには、
識別子を固定した安定した ad-hoc 署名が付くので、更新をまたいでも許可はそのまま残ります。

一度だけ気をつけたい点があります。識別子を固定する署名の修正（PR #73681）より*前*の
ビルドに与えた許可は、古い cdhash に紐づいた条件を抱えたままです。macOS はそうした
古い許可のスイッチをオンのまま表示しますが、保存されている許可が再ビルドされた
実行ファイルと一致しないため、確認は出続けます。しかも今の確認画面には許可のボタンが
ないので、確かめ直す場所がないように見えます。この状態になったら、古い許可を一度
リセットしてから与え直してください。

```bash
tccutil reset ScreenCapture com.nousresearch.hermes   # repeat per service
```

そのうえで、システム設定に新しく現れた項目をオンにし、Hermes を完全に終了してから
起動し直します。それ以降は安定します。

いちばん確実にしたい場合は、証明書に裏打ちされた識別子を使います。yabai や skhd の
利用者が頼っているのと同じ仕組みです。自己署名のコード署名証明書を一度作って、
それを使うよう Hermes に伝えます。次のコマンドひとつで全部が終わります（ログイン
キーチェーンに証明書を作り、`codesign` からの利用を許可し、設定を書き、
パッケージ済みのアプリに署名し直します）。

```bash
hermes desktop --setup-tcc-identity
```

手作業で行う場合は次のとおりです。

1. キーチェーンアクセス → 証明書アシスタント → **Create a Certificate…**
2. Name: `Hermes Local Signing`、Identity Type: *Self-Signed Root*、
   Certificate Type: **Code Signing**。
3. キーチェーンアクセスで新しい証明書をダブルクリックし、**Trust** で
   **Code Signing** を *Always Trust* にします（読み込んだだけの自己署名証明書は、
   コード署名について信頼するまで有効な署名の識別子になりません。設定後は
   `security find-identity -v -p codesigning` の一覧に出てくるはずです）。
4. `hermes config set desktop.macos_signing_identity "Hermes Local Signing"`

コマンドに `--identity <name>` を付けると、別の名前の証明書を作って使えます
（既定は `Hermes Local Signing` です）。何度実行しても同じ結果になるので、更新の
あとに実行し直せば、設定を指し直して再ビルドされたアプリに署名し直せます。

次の更新から、再ビルドされたアプリはその証明書で署名し直され、TCC の許可は
すべて残ります。Apple Developer のアカウントは要りません。公証済みのリリース
ビルドは自動で見分けられ、署名し直されることはありません。

1点だけ注意があります。署名の識別子を変えると（この修正のあとの最初の更新も
含みます）アプリの識別子が一度変わるので、macOS が最後にもう一度だけ許可を
尋ねてきます。それ以降は安定します。権限がどこかで詰まってしまった場合は、
`tccutil reset All com.nousresearch.hermes` でリセットして許可し直してください。

## 関連ページ {#see-also}

- [CLI ガイド](/hermes/docs/user-guide/cli/) — ターミナル上のインターフェース
- [TUI](/hermes/docs/user-guide/tui/) — `hermes --tui` とダッシュボードのチャットタブで使われる現代的なターミナル UI
- [Web ダッシュボード](/hermes/docs/user-guide/features/web-dashboard/) — チャットタブを埋め込んだブラウザ上の管理画面
- [設定](/hermes/docs/user-guide/configuration/) — デスクトップアプリが読み書きする設定
- [Windows（ネイティブ）](/hermes/docs/user-guide/windows-native/) — Windows へのネイティブなインストール