Hermes Agent エラー診断完全ガイド｜hermes doctor --fix と 8大トラブル対処法【2026年版】

株式会社Fyveは、AI業務効率化の受託開発を行う会社です。Hermes Agentの本番運用支援を進めるなかで、私たちのもとには「昨日まで動いていたのに突然エラーで止まった」「hermes コマンドを叩いても何も返ってこない」といった切実な問い合わせが日に何件も届きます。

Hermes Agentは複数のLLMプロバイダ・MCP・Docker・gateway（Telegram/Slack等）といった多層のコンポーネントで構成されているため、エラーの原因切り分けが難しく、GitHub Issueにも認証失敗・Docker permission・WebSocket切断など同種の質問が繰り返し投稿されています。

本記事では、私たちが現場で実際に踏んできた失敗と、Hermes公式FAQ・GitHub Issueトラッカーで頻出するトラブルを整理し、hermes doctor --fix による自動修復を起点にした診断フローと、8大トラブルの「症状 → 原因 → 検出 → 対処」を一気通貫でまとめます。

まずやるべきこと：hermes doctor で環境診断

Hermes Agentには hermes doctor という環境診断コマンドが標準で同梱されています。トラブル時はまずこれを実行してください。私たちのサポート現場でも、最初の問診はほぼ100%このコマンドの出力から始めています。

# 環境診断（読み取りのみ）
$ hermes doctor

# 検出した問題のうち自動修復できるものを直す
$ hermes doctor --fix

# 詳細ログ付きで実行
$ hermes doctor --verbose

hermes doctor は以下の項目を順にチェックします。

• Hermes本体・CLIのバージョン整合性
• 各プロバイダ（Anthropic / OpenAI / xAI / Gemini / GitHub Copilot）の認証状態
• ~/.hermes/state.db（メモリDB）の整合性
• MCPサーバー接続テスト
• Docker利用時の HERMES_UID 設定
• gateway（Telegram bot token, Slack token）の到達性
• インストール済みスキルの SKILL.md パース結果

--fix を付けると、権限ズレ・キャッシュ破損・期限切れOAuthトークンの再取得など、安全に自動修復できるものはその場で直してくれます。私たちの体感では、トラブルの3〜4割は hermes doctor --fix だけで解決します。残った問題が「人間が判断すべき本物の原因」です。

トラブル1：モデル認証エラー（プロバイダ別の典型）

症状

Error: Authentication failed for provider 'anthropic'
status: 401 Unauthorized

あるいは xAI で 403 Forbidden、OpenAI codex で NoneType has no attribute 'choices' のように、リクエスト前後の認証段階で落ちるパターンです。

原因

• OAuthトークンの期限切れ（Anthropic Claude CLI連携で頻発）
• 環境変数 ANTHROPIC_API_KEY / OPENAI_API_KEY 等の未設定または値ズレ
• xAI / Geminiのアカウントで複数credentialsが競合（古いキーが先に読まれている）
• GitHub Copilotのサブスクライセンス未付与

検出

$ hermes auth status

Provider         Status        Last verified
anthropic        EXPIRED       2026-05-29 03:11
openai           OK            2026-06-06 09:14
xai              FORBIDDEN     2026-06-04 22:40
gemini           OK            2026-06-06 09:14
copilot          NO_LICENSE    -

対処

# トークン再発行（プロバイダ単位）
$ hermes auth login anthropic
$ hermes auth login xai

# 環境変数の上書きを確認
$ hermes config show | grep -i key

# 競合するcredentialsの削除
$ rm ~/.config/hermes/credentials/gemini.old.json

複数credentialsの競合は私たちも何度かハマっています。~/.config/hermes/credentials/ 配下に古いファイルが残っていないか、必ず目視確認してください。

トラブル2：APIConnectionError / 429 レート制限

症状

APIConnectionError: Connection error.
RetryError[]
status: 429 Too Many Requests

原因

• プロバイダ側のレート制限（無料枠 / 組織単位の上限）
• プロキシ・社内ファイアウォール・VPNでのTLS切断
• Hermes側のリトライ設定が緩く、瞬間的に同時リクエストが集中

検出

# 直近1時間のエラーログを抽出
$ hermes logs --since 1h --level error

# プロバイダ別のリクエスト統計
$ hermes stats --by provider --since 24h

対処

# config.yml にリトライ設定を追加
retry:
  max_attempts: 5
  backoff: exponential
  jitter: true
  respect_retry_after: true

rate_limit:
  per_provider:
    gemini: 50/min
    openai: 200/min

Geminiの429は無料枠の上限に当たっているケースが圧倒的に多いです。本番運用に切り替えるなら有償枠への移行、または別プロバイダへのフォールバック設定を入れてください。

トラブル3：Docker permission（HERMES_UID）

症状

PermissionError: [Errno 13] Permission denied: '/var/hermes/state.db'
chown: changing ownership of '/var/hermes': Operation not permitted

原因

コンテナ内のhermesプロセスのUIDと、ホスト側のボリュームマウント先ディレクトリのUIDが一致していないために起きる、典型的なDocker permission問題です。

検出

# ホスト側のディレクトリ所有者を確認
$ ls -ld /var/hermes
drwxr-xr-x 3 1000 1000 4096 /var/hermes

# コンテナ内のUIDを確認
$ docker exec hermes id
uid=10001(hermes) gid=10001(hermes)

対処

# docker-compose.yml
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    environment:
      HERMES_UID: 1000
      HERMES_GID: 1000
    volumes:
      - /var/hermes:/var/hermes

UID/GIDをホストの所有者と揃えるのが王道です。Docker全般のデプロイ設計については Hermes Agent Docker本番運用ガイド で詳しくまとめています。

トラブル4：MEMORY / state.db 破損

症状

sqlite3.DatabaseError: database disk image is malformed
MemoryStore: failed to load conversation history

原因

• プロセス停止中の強制電源断、コンテナのSIGKILL
• ボリュームの突発的なディスクフル
• 複数Hermesプロセスが同一 state.db を同時にロック

検出と対処

# 整合性チェック
$ sqlite3 ~/.hermes/state.db "PRAGMA integrity_check;"

# 自動修復（バックアップ取得→再構築）
$ hermes memory repair

# 完全初期化（履歴消失するので注意）
$ hermes memory reset --confirm

メモリ消失の根本原因分析・予防策（WALモード設定、定期snapshot）は Hermes Agent メモリ消失トラブル完全対処法 で詳述しています。

トラブル5：MCP接続失敗

症状

$ hermes tools enable filesystem
Error: MCP server 'filesystem' did not respond within 30s
stderr: spawn npx ENOENT

原因

• MCPサーバーの実体（npxバイナリ・Pythonパス）が解決できていない
• 環境変数（APIキー等）がMCP側に渡っていない
• mcp.json のJSONスキーマ違反

対処

# MCPサーバー単体で起動確認
$ npx -y @modelcontextprotocol/server-filesystem /tmp

# Hermes側のMCP定義を検証
$ hermes tools validate

# 詳細ログ付きで再接続
$ hermes tools enable filesystem --verbose

私たちの経験上、最も多いのは PATHが通っていない パターンです。Docker・systemd配下で動かす場合は明示的に PATH を渡してください。

トラブル6：Hermes Desktop の WebSocket 切断

症状

WebSocket connection to 'ws://localhost:8765/hermes' closed.
Reconnecting... (attempt 5/5)
Giving up.

原因

• Desktop側とCLI側のバージョン不整合
• OSのスリープ復帰後、CLIプロセスは生きているがソケットだけ死んでいる
• セキュリティソフト（macOSのLulu、企業EDR）のlocalhost遮断

対処

# プロトコルバージョン確認
$ hermes --version && hermes-desktop --version

# サービス再起動
$ hermes service restart

# 別ポートに切り替え
$ hermes config set desktop.port 8775

トラブル7：gateway接続失敗（Telegram / Slack）

症状

gateway[telegram]: 401 Unauthorized
gateway[slack]: not_authed

原因

• bot tokenの誤コピー（前後の空白・改行混入）
• Botのスコープ設定漏れ（Slack：chat:write, im:history 等）
• Webhook URLがHTTPSでない / 公開ホストから到達できない

対処

# gatewayの疎通テスト
$ hermes gateway test telegram
$ hermes gateway test slack

# トークンを安全に再登録（履歴に残さない）
$ read -s TOKEN && hermes gateway set telegram --token "$TOKEN"

tokenはシェル履歴に絶対残さないでください。コミット履歴・.bash_history 経由の漏洩は私たちが Hermes Agent セキュリティ監査ガイド でも繰り返し警告しているリスクです。

トラブル8：スキル読み込みエラー

症状

SkillLoadError: failed to parse SKILL.md at skills/my-skill
yaml: line 4: mapping values are not allowed in this context
ModuleNotFoundError: No module named 'requests'

原因

• SKILL.md 冒頭のYAMLフロントマターの構文ミス
• スキルが依存するライブラリの未インストール
• スキルディレクトリのパーミッション不足

対処

# スキルの構文・依存検査
$ hermes skills validate my-skill

# 依存の自動インストール
$ hermes skills install --resolve-deps my-skill

# 個別の手動デバッグ
$ python -c "import requests"

ログの読み方（hermes logs / journalctl / Docker logs）

トラブルシュートにおいて、ログを正しい場所から取れることは半分以上の勝負です。私たちが現場で常用する読み方を整理します。

# Hermes本体（プロセス内バッファ＋ファイル）
$ hermes logs --since 30m --level warn --json

# systemd管理時
$ journalctl -u hermes -f --since "10 min ago"

# Docker運用時
$ docker logs -f --tail 200 hermes

# 特定リクエストIDで全体串刺し
$ hermes logs --request-id req_01HXY... --include mcp,gateway

--request-id での串刺し検索は、MCPやgatewayを跨いだ非同期処理のトレースに非常に有効です。

自己診断チェックリスト

サポートに投げる前に、私たちが必ず通すチェックリストを共有します。

• hermes doctor --verbose の出力を保存したか
• hermes --version と hermes-desktop --version を控えたか
• 直近1時間の hermes logs --level error を取得したか
• OS / Docker / Pythonのバージョンを記録したか
• 再現手順（最小コマンド列）を整理したか
• APIキー・bot tokenをマスクしたか

解決しない時：GitHub Issueへの書き方

OSSプロジェクトに有効な情報を渡せるかどうかで、回答までの時間は大きく変わります。私たちが社内で運用しているテンプレートを公開します。

### Summary


### Environment
- hermes: x.y.z
- hermes-desktop: x.y.z
- OS: macOS 15.4 / Ubuntu 24.04
- Docker: 27.x（該当時）
- Provider: anthropic / openai / xai / gemini / copilot

### Steps to reproduce
1.
2.
3.

### Expected

### Actual
```

```

### hermes doctor output
```

```

まとめ

Hermes Agentのエラーは、層が多いぶん「どこで落ちているか」さえ特定できれば打ち手は決まっています。私たちの推奨フローはシンプルです。

1. まず hermes doctor --fix を走らせる
2. 残った問題を本記事の8大トラブルに当てはめて切り分ける
3. 解消しなければチェックリストを揃えてIssueに投げる

株式会社Fyveでは、Hermes Agentの本番導入・トラブル時の駆け込み対応・運用設計までを包括的に支援しています。社内で抱えきれない障害が起きたとき、まず hermes doctor の出力を手元に置いて、本記事を辞書代わりに開いていただければと思います。