問題の切り分け

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

問題が発生したら、設定を初期化する前に「いつから」「どの画面で」「どの操作だけが失敗するか」を記録します。起動、モデル接続、ツール実行、ファイル操作を分けて確認すると原因を絞り込みやすくなります。

最初に記録する

OSとHermes Desktopのバージョン
問題が起きた時刻
実行した操作
表示されたエラー全文
ローカルバックエンドかリモートバックエンドか
直前に変更した設定、更新、追加したMCPやツール

バージョンは情報から確認できます。

症状別の確認

症状	最初の確認
アプリが起動しない	Desktopログ、更新直後か、空き容量
チャットが応答しない	プロバイダー認証、モデル選択、ネットワーク
ツールだけ失敗する	ツール有効化、APIキー、作業フォルダ、承認
MCPだけ接続できない	サーバーコマンド、環境変数、起動ログ
リモート接続できない	URL、認証方式、バックエンド起動、VPN・Firewall
更新後に挙動が変わった	バージョン、設定バックアップ、変更履歴

セーフモードで切り分ける

トラブルシューティング用の起動フラグ--safe-modeがあります。ユーザー設定（config.yaml）、AGENTS.md・メモリの自動注入、プラグイン、MCPサーバー、shell hooksをすべて無効化して起動し、セーフモード起動ではユーザーが構成したコードが一切実行されません。

前提: ターミナルでhermes CLIを実行できること。
操作:

hermes --safe-mode

期待結果: セーフモードで問題が再現しない場合、原因は設定・プラグイン・MCP・shell hooksなどのカスタマイズ側にあります。1つずつ有効化へ戻して特定します。セーフモードでも再現する場合は、Hermes本体かネットワーク・環境側を疑います。
失敗時の確認先: 後述の「Desktopログを確認する」とhermes doctor。

--safe-modeは内部で環境変数HERMES_SAFE_MODE=1（あわせてHERMES_IGNORE_USER_CONFIG=1・HERMES_IGNORE_RULES=1）を設定します。フラグを渡せない起動経路では、環境変数HERMES_SAFE_MODE=1を直接指定するとプラグイン・MCP・shell hooksの無効化が有効になります（ユーザー設定とAGENTS.md・メモリ注入まで含めて無効化するには--safe-modeフラグを使います）。

設定の確認と切り戻し

hermes config getとhermes config unsetを使うと、設定起因の問題の切り分けと切り戻しがコマンドで完結します。

コマンド	用途
`hermes config get <キー>`	解決済みの設定値を表示します（`--json`でJSON出力）。未設定のキーはエラー終了します
`hermes config unset <キー>`	ユーザー設定（`config.yaml`）や`.env`の値を削除し、既定値へ戻します

前提: ターミナルでhermes CLIを実行できること。
操作の例:

hermes config get model
hermes config get terminal.backend
hermes config unset terminal.backend

期待結果: 「直前に変更した設定」を疑うときは、まずhermes config getで現在値を確認し、hermes config unsetで既定値へ戻してから再現を確認します。値を戻して問題が消えれば、その設定が原因です。
失敗時の確認先: 保存・書き出し・読み込み・リセット。

あわせて、hermes config setで未知の設定キーを指定すると警告が表示されます（保存自体は行われ、近いキー名の候補も提示されます）。hermes doctorは非推奨になった設定キー・環境変数を警告として報告します。設定名のタイプミスや古い設定の残存を疑うときに確認してください。

Desktopログを確認する

公式ガイドでは、Desktopの起動ログはHERMES_HOME/logs/desktop.logに保存されます。CLIが利用できる場合は次のコマンドで追跡できます。

hermes logs desktop -f   # desktop.log（Desktopアプリの起動・バックエンド）
hermes logs gui -f       # gui.log（ダッシュボード関連）

ログとチャットの突き合わせには、設定display.tool_progress: log（ツール呼び出しをチャットに表示せず~/.hermes/logs/tool_calls.logへ記録する。ゲートウェイ経由の利用向け）とdisplay.timestamp_format（タイムスタンプの表示形式）が役立ちます。

ログを共有するときは、APIキー、トークン、ローカルパス、個人情報を削除してください。

診断情報を共有する

hermes debug shareは、システム情報とログをまとめてアップロードし、共有URLを表示します。既定では、アップロード前にログ内の認証情報などを自動でマスク（redact）します。次のオプションがあります。

オプション	動作
`--nous`	公開ペーストサービスの代わりに、Nousの私設診断ストレージへアップロードします。閲覧はNousスタッフなど限られた相手に限定され、14日後に自動削除されます
`--no-redact`	アップロード時の自動マスクを無効化します（既定はマスク有効）
`--local`	アップロードせず、手元にレポートを表示します

--nousの実行時はアップロード内容の説明（プライバシー通知）が表示され、実行の確認を求められます。バンドルにはシステム情報と各ログが含まれ、ログには会話内容やファイルパスが含まれる可能性があります。内容を確認してから実行してください。

設定を確認する順序

初期化する前に

設定のリセットや再インストールを行う前に、設定を書き出し、バージョンとエラーを記録します。