よくある質問とトラブル対処

このページにある Python の依存パッケージのコマンドは、 PM で準備したソースのチェックアウトを前提にしています。 依存パッケージを変えたあとは、チェックアウトを有効にし直して Hermes を再起動してください。

よく寄せられる質問と、つまずきやすい箇所の直し方をまとめました。

よくある質問

Hermes ではどの LLM プロバイダーを使えますか

Hermes Agent は OpenAI 互換の API であれば動きます。対応しているプロバイダーは次のとおりです。

• OpenRouter — ひとつの API キーで数百のモデルを使えます（使い分けの自由度を求めるならこれ）
• Nous Portal — Nous Research のサブスクリプション窓口です。OAuth ログイン 1 回で 300 以上のモデルに加えて、Web 検索・画像・音声合成・ブラウザまで使えます（初めての方におすすめ）
• OpenAI — GPT-5.4、GPT-5-codex、GPT-4.1、GPT-4o など
• Anthropic — Claude 系のモデル（API を直接叩く、hermes auth add anthropic で OAuth を通す、OpenRouter を挟む、互換プロキシを立てる、のいずれでも可）
• Google — Gemini 系のモデル（gemini プロバイダーで直接、OpenRouter 経由、互換プロキシのいずれでも可）
• z.ai / ZhipuAI — GLM 系のモデル
• Kimi / Moonshot AI — Kimi 系のモデル
• MiniMax — グローバル版と中国国内版のエンドポイント
• ローカルモデル — Ollama、vLLM、llama.cpp、SGLang など、OpenAI 互換のサーバーであれば何でも

プロバイダーの指定は hermes model を実行するか、~/.hermes/.env を直接編集して行います。プロバイダーごとのキー名は 環境変数 の一覧にすべて載っています。

Windows や Android、手元の環境でも動きますか

対応環境の一覧は 対応プラットフォーム にまとめてあります。

WSL2 で Hermes を動かしています。Windows 側の Chrome を操作する良い方法はありますか

/browser connect を使うより、MCP のブリッジを挟むほうがうまくいきます。

おすすめの組み立て方は次のとおりです。

• Hermes は WSL2 の中で動かす
• Windows 側のログイン済み Chrome はそのまま使う
• cmd.exe か powershell.exe を通して chrome-devtools-mcp を MCP サーバーとして登録する
• Hermes には、そこで生えたブラウザ操作ツールを使わせる

Hermes 本体のブラウザ通信を WSL2 と Windows の境界をまたいで直接つながせるより、この形のほうが安定します。

関連ページ:

• Hermes で MCP を使う
• ブラウザ操作

入力した内容はどこかに送られますか

API リクエストは 自分で設定したプロバイダーだけ に送られます（OpenRouter や、手元で動かしている Ollama など）。Hermes Agent 側が利用状況や解析データを集めることはありません。会話・記憶・スキルはすべて手元の ~/.hermes/ に保存されます。

オフラインやローカルモデルでも使えますか

使えます。hermes model を実行して Custom endpoint を選び、自分のサーバーの URL を入力してください。

hermes model
# Select: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000   ← Hermes minimum; set this to match your server's actual context window

config.yaml に直接書いても構いません。

model:
  default: qwen3.5:27b
  provider: custom
  base_url: http://localhost:11434/v1

Hermes はエンドポイント・プロバイダー・ベース URL を config.yaml に保存するので、再起動しても設定は残ります。ローカルサーバーに読み込んでいるモデルが 1 つだけなら、/model custom が自動で見つけてくれます。config.yaml に provider: custom と書くこともできます。これは何かの別名ではなく、独立したプロバイダーとして扱われます。

Ollama、vLLM、llama.cpp のサーバー、SGLang、LocalAI などで動作します。詳しくは 設定ガイド をご覧ください。

費用はどのくらいかかりますか

Hermes Agent 自体は 無料のオープンソース です（MIT ライセンス）。かかるのは選んだプロバイダーの LLM 利用料だけです。ローカルモデルなら料金は一切かかりません。

複数人で 1 つのインスタンスを使えますか

使えます。メッセージゲートウェイ を通せば、Telegram・Discord・Slack・WhatsApp・Home Assistant から同じ Hermes Agent に複数人がやり取りできます。誰が使えるかは、許可リスト（ユーザー ID を並べる方式）と DM ペアリング（最初に話しかけた人が使用権を取る方式）で制御します。

記憶とスキルは何が違いますか

• 記憶 は 事実 をためます。使う人のこと、進行中のプロジェクト、好みなど、エージェントが知っている情報です。関連しそうな場面で自動的に引き出されます。
• スキル は 手順 をためます。何かをやるときの段取りを書いたものです。似た作業に出くわしたときに呼び出されます。

どちらもセッションをまたいで残ります。詳しくは 記憶 と スキル をご覧ください。

自分の Python プロジェクトから使えますか

使えます。AIAgent クラスを読み込めば、Hermes をプログラムから呼び出せます。

from run_agent import AIAgent

agent = AIAgent(model="anthropic/claude-opus-4.7")
response = agent.chat("Explain quantum computing briefly")

API の使い方は Python ライブラリガイド にまとまっています。

トラブル対処

インストール時の問題

インストールしたのに hermes: command not found になる

原因: シェルが新しい PATH を読み直していません。

対処:

# Reload your shell profile
source ~/.bashrc    # bash
source ~/.zshrc     # zsh

# Or start a new terminal session

これでも直らないときは、インストール先を確認します。

which hermes
ls ~/.local/bin/hermes

対応していない Python のバージョン

いまの公式のインストールに必要なのは Python 3.14 で、それより新しければどれでもよいわけではありません。 pyproject.toml にある >=3.11,<3.15 の範囲は、古いインストールが 3.14 へ切り替える前に アップデーターを動かせるようにするためのものです。いまの実行環境が 3.11〜3.13 に対応しているという意味ではありません。 インストーラーと配布パッケージには、版を固定した実行系が付いてきます。

ソースから手で環境を作る場合は、 開発環境の準備に従ってください。 インストール済みのアプリやコンテナの中の実行系を入れ替えないでください。 管理されたインストールでエラーが出た場合は、hermes doctor を実行し、そのインストールに合った 更新のしかたを使ってください。

ターミナル操作で node: command not found になる（nvm、pyenv、asdf なども同様）

原因: Hermes は起動時に bash -l を 1 回走らせ、そのセッション用の環境を写し取ります。bash のログインシェルは /etc/profile、~/.bash_profile、~/.profile を読みますが、~/.bashrc は読み込みません。そのため、そこに自分を書き込むツール（nvm、asdf、pyenv、cargo、独自の PATH 追記）は写し取った環境から見えなくなります。systemd 配下で Hermes を動かしている場合や、対話シェルの設定が何も読み込まれていない最小構成のシェルで起きやすい現象です。

対処: Hermes は既定で ~/.bashrc を自動的に読み込みます。それでも足りないとき、たとえば PATH を ~/.zshrc に書いている zsh 利用者や、nvm を単独ファイルから初期化している場合は、追加で読み込ませたいファイルを ~/.hermes/config.yaml に並べてください。

terminal:
  shell_init_files:
    - ~/.zshrc                     # zsh users: pulls zsh-managed PATH into the bash snapshot
    - ~/.nvm/nvm.sh                # direct nvm init (works regardless of shell)
    - /etc/profile.d/cargo.sh      # system-wide rc files
  # When this list is set, the default ~/.bashrc auto-source is NOT added —
  # include it explicitly if you want both:
  #   - ~/.bashrc
  #   - ~/.zshrc

存在しないファイルは何も言わずに読み飛ばされます。読み込みは bash で行われるため、zsh 固有の書き方に頼っているファイルはエラーになることがあります。心配なら、rc ファイル全体ではなく PATH を設定している部分だけ（たとえば nvm の nvm.sh を直接）読ませてください。

こうした初期化ファイルとは別に、ターミナルで実行するすべてのコマンドの PATH には、標準のシステムディレクトリ（/usr/local/bin、/opt/homebrew/bin など）、Hermes が管理するランタイムのディレクトリ、そして存在する場合は ~/.local/bin（pip --user / pipx / uv tool のインストール先）が補われます。これらは自分で設定した項目の後ろに追加されるので、優先順位は変わりません。systemd や GUI のランチャー、Desktop の SSH リモートバックエンドのように、最小限の PATH だけで非対話的に起動されたバックエンドでも、設定なしで動くようになります。

自動読み込みをやめて、ログインシェルの挙動だけに揃えたい場合はこうします。

terminal:
  auto_source_bashrc: false

uv: command not found

原因: パッケージマネージャーの uv が入っていないか、PATH に載っていません。

対処:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

インストール中に permission denied が出る

原因: インストール先に書き込む権限がありません。

対処:

# Don't use sudo with the installer — it installs to ~/.local/bin
# If you previously installed with sudo, clean up:
sudo rm /usr/local/bin/hermes
# Then re-run the standard installer
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

プロバイダーとモデルの問題

「Hermes のポリシー」「Hermes のガードレール」で断られたと言われる

モデルは、自分がなぜ断ったのかを正確には説明できません。断り文句が返答の文章の中にしか出てこないなら、「Hermes 側の隠れたポリシーが原因だ」という説明はモデルの作り話か、選んでいるモデルやプロバイダー側の制限である可能性があります。

Hermes 側の制御はもっとはっきり出ます。ツールの実行がブロックされたときは、禁止されたコマンドやパスを名指ししたツールエラーが返り、承認が要る操作では承認を求める表示が出ます。Hermes がこうした実行制御を、黙って一般的な内容フィルターに読み替えることはありません。ただし Amazon Bedrock Guardrails のように、プロバイダー側の制御を設定している場合はそちらが効きます。

原因を切り分ける手順は次のとおりです。

1. /status を実行して、今どのモデルとプロバイダーが動いているか確かめます。
2. その断りに、実際の Hermes のツールエラーや承認プロンプトが含まれているか見ます。文章だけなら、モデルが挙げた原因を証拠として扱わないでください。
3. 新しいセッションを開き、別のモデルやプロバイダーで試します。モデルを変えると結果が変わるなら、それは Hermes の実行制御ではなくモデルやプロバイダー側の挙動です。
4. 明確なツールエラーが出ているなら、その文面をそのまま添えて報告してください。

Hermes が公式に備えている実行制御は セキュリティ、プロバイダー側の設定は プロバイダー をご覧ください。

「…refused this request because of a policy on your account」

意味: プロバイダーが、再試行しても変わらないアカウント単位の理由でリクエストを拒否しています。アグリゲーターのデータやプライバシーの設定によって、そのモデルのエンドポイントがすべて除外されたか、モデルの上流プロバイダーがアカウントをブロックしているかのどちらかです（たとえば this user has been blocked for a previous policy violation。OpenRouter は、これを見かけ上は成功した HTTP 200 のストリームの中で伝えてくることがあります）。Hermes はそのリクエストを 1 回だけ送り、再試行も認証情報の切り替えもしません。フォールバックの連なりを設定していれば、そちらへ移ります。

対処: 返答に名前が出ているプロバイダーで、アカウントの状態とデータ・プライバシーの設定を確かめるか、/model で別のモデルやプロバイダーに切り替えてください。hermes fallback add を設定しておくと、今後同じようにブロックされたときに自動で予備へ回します。

「Could not open a stream to <host> after N attempts (request X KB)」

意味: そのエンドポイントへの接続は毎回、ストリームのイベントが 1 つも届かないうちに失敗しています。つまり課金は発生していませんし、このあとも通常どおり再試行とフォールバックの流れが走ります。この行には、実際に接続しにいったホスト、試した回数、シリアライズしたあとのリクエストサイズが出ます。障害なのかリクエストサイズの上限なのかを切り分けるのに要る 3 つです。

対処: リクエストが大きく（数百 KB — 長いコーディングのセッションでは、コンテキストが育つとこの大きさに届きます）、短い新規チャットなら通るなら、エンドポイントか、その手前のプロキシが、そのサイズの本文を拒んでいる可能性が高いです。本文サイズの上限を上げるか、/compress を実行してコンテキストを縮めてください。リクエストが小さいなら、エンドポイントに到達できていません。base_url を確かめてから /retry で試し直してください。試行ごとの例外の連なりは logs/agent.log に記録されています。

メッセージへの返事: 「interrupted mid-request」と「not running or is unreachable」と「could not reach」の違い

チャットの画面（Telegram、Discord、Slack など）に、通信のときの生の例外がそのまま出ることはありません。ゲートウェイがそれを 3 種類の短い返事のどれかに置き換えます。どれが返ってきたかで、どこを見ればよいかが分かります。

/model に 1 つのプロバイダーしか出ない・切り替えられない

原因: チャットの中で使う /model は、すでに設定済みの プロバイダー間でしか切り替えられません。OpenRouter しか設定していなければ、/model にはそれしか出てきません。

対処: いったんセッションを抜けて、ターミナルから hermes model を実行し、プロバイダーを追加します。

# Exit the Hermes chat session first (Ctrl+C or /quit)

# Run the full provider setup wizard
hermes model

# This lets you: add providers, run OAuth, enter API keys, configure endpoints

hermes model でプロバイダーを追加したら、新しいチャットを開いてください。/model に設定済みのプロバイダーがすべて並びます。

API キーが通らない

原因: キーが未設定・期限切れ・書き間違い、あるいは別のプロバイダー用のキーです。

対処:

# Check your configuration
hermes config show

# Re-configure your provider
hermes model

# Or set directly
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

モデルが見つからない・使えない

原因: モデル名が間違っているか、そのプロバイダーでは提供されていません。

対処:

# List available models for your provider
hermes model

# Set a valid model
hermes config set model.default anthropic/claude-opus-4.7

# Or specify per-session
hermes chat --model openrouter/meta-llama/llama-3.1-70b-instruct

レート制限（429 エラー）

原因: プロバイダー側の利用制限に引っかかっています。

対処: 少し待ってから再実行してください。日常的に上限に当たるなら、次を検討します。

• プロバイダーのプランを上げる
• 別のモデルやプロバイダーに乗り換える
• hermes chat --provider <alternative> で別の接続先に振り分ける

コンテキスト長を超えた

原因: 会話が長くなってモデルのコンテキスト枠を超えたか、Hermes がそのモデルのコンテキスト長を取り違えています。

対処:

# Compress the current session
/compress

# Or start a fresh session
hermes chat

# Use a model with a larger context window
hermes chat --model openrouter/google/gemini-3-flash-preview

長い会話の 1 回目でこれが出るなら、Hermes がそのモデルのコンテキスト長を誤って判定している可能性があります。何と認識しているか確認してください。

CLI の起動時の行に、検出したコンテキスト長が出ます（例: 📊 Context limit: 128000 tokens）。セッション中なら /usage でも確認できます。

エラーを返さずに黙り込むローカルサーバー（llama.cpp、Ollama）の場合: リクエストが大きすぎるとプロバイダーに拒否されると、Hermes は会話を圧縮してリクエストを組み立て直します。再試行の前に、組み立て直した*リクエスト全体*（システムプロンプト + ツールスキーマ + メッセージ）を測り直し、まだしきい値を超えていれば、回数を区切った圧縮をさらに走らせます。それでも収まらない場合は、llama.cpp が黙って切り詰めてしまうような特大のリクエストを送る代わりに、Context length exceeded: compression could not reduce the rebuilt request below the safe threshold を出してそのターンを終えます（切り詰められると、サーバーのログに stop processing: n_tokens = 65535, truncated = 1 と出ます）。このメッセージが出たときは、ほぼ確実に上に挙げた context_length の設定が原因です。サーバー側で実際に指定している -c / --ctx-size に合わせてください。

「The model server rejected this request as too large, but this conversation is only about N tokens…」と出る場合: ローカルのサーバー（localhost、LAN、Tailscale）が測定値をいっさい示さずに「コンテキスト超過」と言っている一方で、Hermes 自身が見積もったリクエストは、そのモデルについて把握しているウィンドウよりはるかに小さい状態です。そのため Hermes は圧縮もしませんし、会話のせいにもしません。そのターンは再試行できるまま残ります。スロットが 1 つしかないローカルサーバー（LM Studio、Ollama）では、ほぼ必ず、その時点で別のリクエストがサーバーのコンテキストを占有していることが原因です。たいていは、前のセッションから走っている裏側のメモリ見直しです（logs/agent.log に thread=bg-review と出ます）。少し待ってから /retry を実行してください。ほかに Hermes のプロセスが動いていないのに繰り返し出るなら、サーバーが Hermes の想定より小さいウィンドウでモデルを読み込んでいます。サーバー側のコンテキストの設定を上げるか、model.context_length をそれに合わせて下げてください。ホスティング型のプロバイダーでは、このメッセージは出ません。待てば空く共有スロットがないので、同じ拒否が出たらその経路の実際のウィンドウが Hermes の想定より小さいということであり、Hermes は圧縮してから再試行します。

判定を直すには、明示的に指定します。

# In ~/.hermes/config.yaml
model:
  default: your-model-name
  context_length: 131072  # your model's actual context window

独自エンドポイントの場合は、プロバイダーの項目にモデルごとの値を足します。

providers:
  my-server:
    api: "http://localhost:11434/v1"
    models:
      qwen3.5:27b:
        context_length: 64000

（古い設定では custom_providers: というリストを使っていました。今も動きますし、自動で providers: に移し替えられます。）

自動判定の仕組みと、上書きの方法すべては コンテキスト長の検出 をご覧ください。

ターミナルの問題

コマンドが危険と判断されて止まる

原因: Hermes が破壊的な可能性のあるコマンド（rm -rf、DROP TABLE など）を検出しました。安全のための仕組みです。

対処: 確認を求められたらコマンドを読み、問題なければ y と入力して許可します。ほかにこんな手もあります。

• もっと安全なやり方を使うようエージェントに頼む
• 危険と判断されるパターンの一覧は セキュリティのページ にあります

メッセージゲートウェイ経由だと sudo が使えない

原因: メッセージゲートウェイは対話できるターミナルを持たないため、sudo がパスワードを尋ねられません。

対処:

• メッセージ経由では sudo を避け、別のやり方をエージェントに探してもらう
• どうしても sudo が必要なら、/etc/sudoers で特定のコマンドだけパスワードなしで実行できるよう設定する
• 管理作業はターミナル側に切り替える: hermes chat

Docker バックエンドにつながらない

原因: Docker のデーモンが動いていないか、ユーザーに権限がありません。

対処:

# Check Docker is running
docker info

# Add your user to the docker group
sudo usermod -aG docker $USER
newgrp docker

# Verify
docker run hello-world

メッセージ連携の問題

ボットが反応しない

原因: ボットが起動していない、認証が通っていない、あるいは自分が許可リストに入っていません。

対処:

# Check if the gateway is running
hermes gateway status

# Start the gateway
hermes gateway start

# Check logs for errors
cat ~/.hermes/logs/gateway.log | tail -50

メッセージが届かない

原因: ネットワークの問題、ボットのトークンの期限切れ、プラットフォーム側の Webhook 設定の誤りなどです。

対処:

• hermes gateway setup でボットのトークンが有効か確かめる
• ゲートウェイのログを見る: cat ~/.hermes/logs/gateway.log | tail -50
• Webhook を使うプラットフォーム（Slack、WhatsApp）では、自分のサーバーが外から届く状態か確認する

許可リストがよくわからない。誰がボットに話しかけられるのか

原因: 認証モードによって、誰が使えるかが決まります。

対処:

設定は ~/.hermes/config.yaml の、各ゲートウェイの項目で行います。メッセージ連携のページ もご覧ください。

ゲートウェイが起動しない

原因: 依存パッケージの不足、ポートの取り合い、トークンの設定ミスなどです。

対処:

# Install core messaging gateway dependencies
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['messaging'], explicit=True)"  # Telegram, Discord, Slack, and shared gateway deps

# Check for port conflicts
lsof -i :8080

# Verify configuration
hermes config show

WSL でゲートウェイが切れ続ける、hermes gateway start が失敗する

原因: WSL の systemd 対応は当てになりません。WSL2 では systemd が有効になっていない環境が多く、有効にしても WSL の再起動や Windows のアイドル終了でサービスが落ちることがあります。

対処: systemd のサービスにせず、フォアグラウンドで動かします。

# Option 1: Direct foreground (simplest)
hermes gateway run

# Option 2: Persistent via tmux (survives terminal close)
tmux new -s hermes 'hermes gateway run'
# Reattach later: tmux attach -t hermes

# Option 3: Background via nohup
nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

それでも systemd を試したい場合は、有効になっているか確かめてください。

1. /etc/wsl.conf を開きます（無ければ作ります）
2. 次を書き足します:

[boot]
systemd=true

1. PowerShell から wsl --shutdown を実行します
2. WSL のターミナルを開き直します
3. 確認します。systemctl is-system-running が "running" か "degraded" を返せば大丈夫です

macOS でゲートウェイから Node.js や ffmpeg などが見つからない

原因: launchd のサービスは最小限の PATH（/usr/bin:/bin:/usr/sbin:/sbin）しか受け継ぎません。ここには Homebrew や nvm、cargo など、自分で入れたツールの置き場が含まれていません。WhatsApp ブリッジが node not found で動かない、音声の書き起こしが ffmpeg not found になる、といった形で表面化します。

対処: ゲートウェイは hermes gateway install を実行した時点のシェルの PATH を記録します。ゲートウェイを用意したあとにツールを入れたなら、install をやり直して新しい PATH を取り込ませてください。

hermes gateway install    # Re-snapshots your current PATH
hermes gateway start      # Detects the updated plist and reloads

plist に正しい PATH が入ったかは、こうして確認できます。

/usr/libexec/PlistBuddy -c "Print :EnvironmentVariables:PATH" \
  ~/Library/LaunchAgents/ai.hermes.gateway.plist

速度・負荷の問題

応答が遅い

原因: モデルが大きい、API サーバーが遠い、あるいはツールを盛り込んだシステムプロンプトが重くなっています。

対処:

• もっと速い・小さいモデルを試す: hermes chat --model openrouter/meta-llama/llama-3.1-8b-instruct
• 有効なツールセットを絞る: hermes chat -t "terminal"
• プロバイダーまでの通信の遅さを確認する
• ローカルモデルなら、GPU の VRAM が足りているか確かめる

トークンを使いすぎる

原因: 会話が長い、システムプロンプトが冗長、ツール呼び出しが積み重なってコンテキストが膨らんでいる、などです。

対処:

# See exactly what the fixed prompt costs — breakdown by block
# (system prompt, skills index, memory, tool schemas). Runs offline.
hermes prompt-size

# Compress the conversation to reduce tokens
/compress

# Check session token usage
/usage

まだ何も入力していないのに数字が大きいなら、それは毎回必ず送られる分です。システムプロンプトとツールの定義が該当します。hermes prompt-size で内訳を測ってから削っていきましょう。使っていないツールセットを切り（hermes tools）、要らないスキルを消すか無効にします（hermes skills）。

セッションが長くなりすぎた

原因: 会話が続くとメッセージやツールの出力がたまり、コンテキストの上限に近づきます。

対処:

# Compress current session (preserves key context)
/compress

# Start a new session with a reference to the old one
hermes chat

# Resume a specific session later if needed
hermes chat --continue

MCP の問題

MCP サーバーにつながらない

原因: サーバーの実行ファイルが見つからない、コマンドのパスが違う、実行環境が入っていない、などです。

対処:

# Ensure MCP dependencies are installed (already included in standard install)
cd ~/.hermes/hermes-agent && python -c "import pm; pm.sync_venv(['mcp'], explicit=True)"

# For npm-based servers, ensure Node.js is available
node --version
npx --version

# Test the server manually
npx -y @modelcontextprotocol/server-filesystem /path/to/allowed/dir

~/.hermes/config.yaml の MCP の設定も確かめてください。

mcp_servers:
  filesystem:
    command: "npx"
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/home/user/docs"]

MCP サーバーのツールが出てこない

原因: サーバーは起動したがツールの取得に失敗した、設定でツールが除外されていた、あるいはそのサーバーが期待した MCP の機能に対応していない、などです。

対処:

• ゲートウェイやエージェントのログに MCP の接続エラーが出ていないか確認する
• サーバーが tools/list の RPC に応答するか確かめる
• そのサーバーの下にある tools.include、tools.exclude、tools.resources、tools.prompts、enabled の設定を見直す
• リソースやプロンプトを扱う補助ツールは、セッションがその機能に対応しているときだけ登録されることを覚えておく
• 設定を変えたら /reload-mcp を実行する

# Verify MCP servers are configured
hermes config show | grep -A 12 mcp_servers

# Restart Hermes or reload MCP after config changes
hermes chat

関連ページ:

• MCP（Model Context Protocol）
• Hermes で MCP を使う
• MCP 設定の一覧

MCP がタイムアウトする

原因: MCP サーバーの応答が遅すぎるか、実行中に落ちています。

対処:

• MCP サーバーの設定にタイムアウトの項目があれば、値を延ばす
• MCP サーバーのプロセスがまだ生きているか確かめる
• リモートの HTTP MCP サーバーなら、ネットワークがつながっているか確かめる

スキルの問題

デスクトップアプリで Skills Hub のページが読み込めない（403 / ブロック）

原因: ドキュメントのサイト（hermes-agent.nousresearch.com）は Vercel を通して配信されています。Vercel の WAF は、問題があるとみなした一部の家庭向け回線の IP 範囲を拒否します。お使いのネットワークがそうした範囲にあると、このドメインへのリクエストはすべて 403 のブロックページになります。

対処: Skills Hub の選択画面は、まず本来のドメインを試し、だめなら同じ内容の GitHub Pages の配信（nousresearch.github.io/hermes-agent）へ自動で切り替えます。こちらでも同じカタログが見られます。どちらの配信元でもページが開けない場合は、プロキシや DNS フィルター、ファイアウォールが両方のホストをふさいでいないか確かめてください。あわせて、該当する IP 範囲をメンテナーに報告すると、配信側で見直してもらえます。

プロファイル

HERMES_HOME を設定するのと、プロファイルは何が違いますか

プロファイルは HERMES_HOME の上に乗った管理レイヤーです。コマンドを打つたびに HERMES_HOME=/some/path を自分で設定することも *できます* が、プロファイルはその周りの面倒をまとめて引き受けます。ディレクトリ構成を作り、シェルの別名（hermes-work）を生成し、今どのプロファイルが有効かを ~/.hermes/active_profile で管理し、スキルの更新を全プロファイルへ自動で反映します。タブ補完とも連携するので、パスを覚えておく必要もありません。

2 つのプロファイルで同じボットのトークンを使えますか

使えません。メッセージのプラットフォーム（Telegram、Discord など）は、ボットのトークンを 1 か所からしか使わせません。2 つのプロファイルが同じトークンを同時に使おうとすると、あとから起動したゲートウェイが接続に失敗します。プロファイルごとに別のボットを作ってください。Telegram なら @BotFather に話しかけてボットを増やせます。

プロファイル同士で記憶やセッションは共有されますか

されません。プロファイルはそれぞれ独自の記憶・セッションのデータベース・スキルのディレクトリを持ち、互いに完全に切り離されています。今ある記憶やセッションを引き継いで新しいプロファイルを作りたいときは、hermes profile create newname --clone-all で現在のプロファイルの中身をまるごと複製するか、--clone-from <profile> で複製元を指定してください。

この分離は、*同じ* プロファイルや同じ Hermes ホームに対して 2 つのエージェントを走らせてはいけない理由でもあります。どちらも記憶を自動で書き込み、セッションの開始時に相手の書き込みを読み込むため、保存された状態はセッションのたびに崩れていきます。プロファイルにつきエージェントは 1 つです。本当に複数のエージェントで記憶を共有したいなら、外部の記憶プロバイダー を使ってください。

hermes update を実行すると何が起きますか

hermes update は最新のコードを取得し、依存パッケージを 1 回だけ 入れ直します（プロファイルごとではありません）。そのあと、更新されたスキルを全プロファイルへ自動で反映します。hermes update の実行は 1 回で済み、その端末にあるすべてのプロファイルが対象になります。

プロファイルはいくつまで作れますか

上限はありません。プロファイルの実体は ~/.hermes/profiles/ の下のディレクトリで、目印になるファイル（config.yaml、.env、SOUL.md、profile.yaml、auth.json、state.db のいずれか）を 1 つ以上持っているものを指します。それが 1 つもない空のディレクトリ（ログの入れ替えや cron の実行で残ったものなど）はプロファイルとして扱われません。一覧にも出ず、配信もされず、-p <name> で指定すると見つからないと表示され、hermes profile create <name> も、そのディレクトリを移動するか削除するまで上書きを拒みます。実際の上限は、ディスクの空きと、同時に動かせるゲートウェイの数（1 つずつが軽量な Python のプロセスです）で決まります。何十個作っても問題ありませんし、使っていないプロファイルは資源を消費しません。

使い方のパターン

用途ごとに違うモデルを使う（複数モデルの使い分け）

こんなとき: ふだんは GPT-5.4 を使っているけれど、SNS の文章は Gemini や Grok のほうが上手い。そのたびに手でモデルを切り替えるのが面倒、という場面です。

対処: 委任の設定を使います。 Hermes は、サブエージェントだけを別のモデルに自動で振り分けられます。~/.hermes/config.yaml に次のように書きます。

delegation:
  model: "google/gemini-3-flash-preview"   # subagents use this model
  provider: "openrouter"                    # provider for subagents

こうしておくと、「X についての Twitter スレッドを書いて」と頼んで Hermes が delegate_task のサブエージェントを立ち上げたとき、そのサブエージェントは Gemini で動きます。本体の会話は GPT-5.4 のままです。

指示の中で明示しても構いません。たとえば *「製品リリースについての SNS 投稿を書く作業を委任してください。実際の執筆はサブエージェントにやらせてください」* のように書きます。エージェントは delegate_task を使い、委任の設定が自動で効きます。

委任を挟まずその場だけ切り替えたいなら、CLI で /model を使います。

/model google/gemini-3-flash-preview    # switch for this session
# ... write your content ...
/model openai/gpt-5.4                   # switch back

委任の仕組みについては サブエージェントへの委任 をご覧ください。

1 つの WhatsApp 番号で複数のエージェントを動かす（チャットごとの割り当て）

こんなとき: OpenClaw では、独立したエージェントを特定の WhatsApp のチャットに結び付けられました。家族の買い物リストのグループにひとつ、個人のチャットにもうひとつ、という具合です。Hermes でも同じことができるでしょうか。

今のところの制限: Hermes のプロファイルは、それぞれ専用の WhatsApp 番号とセッションを必要とします。同じ番号の中で、チャットごとに別のプロファイルを割り当てることはできません。WhatsApp のブリッジ（Baileys）は、1 番号につき認証済みのセッションを 1 つしか持てないためです。

回避策:

1. 1 つのプロファイルで人格を切り替える。 AGENTS.md という文脈ファイルをチャットごとに用意するか、/personality コマンドでふるまいを変えます。エージェントは今どのチャットにいるかを認識できるので、それに合わせられます。

1. 決まった作業は cron に任せる。 買い物リストの管理なら、特定のチャットを見張ってリストを更新する cron ジョブを組めば、別のエージェントを立てる必要はありません。

1. 番号を分ける。 本当に独立したエージェントが要るなら、プロファイルごとに WhatsApp 番号を用意します。Google Voice のようなサービスの仮想番号でも動きます。

1. Telegram か Discord を使う。 こちらのプラットフォームは、チャットごとの割り当てにもっと素直に対応しています。Telegram のグループや Discord のチャンネルごとにセッションが分かれますし、同じアカウントで複数のボットのトークン（プロファイルごとに 1 つ）を動かせます。

詳しくは プロファイル と WhatsApp の設定 をご覧ください。

Telegram の表示を絞る（ログや思考の過程を隠す）

こんなとき: 最終的な答えだけが欲しいのに、Telegram にゲートウェイの実行ログや Hermes の思考の過程、ツール呼び出しの詳細まで出てきてしまう、という場面です。

対処: config.yaml の display.tool_progress で、ツールの動きをどこまで見せるかを決められます。

display:
  tool_progress: "off"   # options: off, new, all, verbose

• off — 最終的な返答だけ。ツール呼び出しも思考の過程もログも出しません。
• new — 新しいツール呼び出しが起きたときに、短い 1 行で知らせます。
• all — 結果を含め、ツールの動きをすべて出します。
• verbose — ツールに渡した引数と出力まで、細かく全部出します。

メッセージのプラットフォームでは、たいてい off か new がちょうどいいはずです。config.yaml を編集したら、ゲートウェイを再起動すると反映されます。

セッションごとに /verbose コマンドで切り替えることもできます（有効にしている場合）。

display:
  tool_progress_command: true   # enables /verbose in the gateway

Telegram でスキルを整理する（スラッシュコマンドの上限）

こんなとき: Telegram にはスラッシュコマンド 100 個という上限があり、スキルが増えて超えそうになっています。Telegram では使わないスキルを無効にしたいのに、hermes skills config の設定が効いていないように見えます。

対処: hermes skills config を使うと、プラットフォームごとにスキルを無効にできます。設定は config.yaml に書き込まれます。

skills:
  disabled: []                    # globally disabled skills
  platform_disabled:
    telegram: [skill-a, skill-b]  # disabled only on telegram

変更したら、ゲートウェイを再起動してください（hermes gateway restart を実行するか、落として立ち上げ直します）。Telegram のボットのコマンド一覧は、起動時に組み直されます。

スレッドを共有するセッション（複数人で 1 つの会話）

こんなとき: Telegram や Discord のスレッドで、複数の人がボットに話しかけています。そのスレッドでのやり取りを、人ごとに分かれたセッションではなく、ひとつづきの会話にしたい、という場面です。

今のところの動き: ほとんどのプラットフォームで、Hermes はユーザー ID ごとにセッションを分けます。つまり人ごとに別の会話の文脈を持ちます。プライバシーと文脈の切り分けのために、そう設計されています。

回避策:

1. Slack を使う。 Slack ではセッションがユーザーではなくスレッド単位で分かれます。同じスレッドにいる人たちはひとつの会話を共有します。まさに求めている動きで、いちばん自然な選択です。

1. 代表者ひとりが窓口になるグループにする。 「担当者」を決めてその人が質問を取り次げば、セッションはひとつにまとまります。ほかの人は読むだけになります。

1. Discord のチャンネルを使う。 Discord ではセッションがチャンネル単位で分かれるので、同じチャンネルにいる人は文脈を共有します。共有したい会話には専用のチャンネルを用意してください。

Hermes を別の端末へ移す

こんなとき: ひとつの端末でスキルや cron ジョブ、記憶を育ててきて、それを新しい Linux 機にまるごと移したい、という場面です。

対処:

1. 新しい端末に Hermes Agent を入れます。

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

1. 移す元の端末 で、まるごとのバックアップを作ります。

hermes backup

zip の書庫が ~/hermes-backup-<timestamp>.zip に保存されます。 まるごとのバックアップには、Hermes のデータの置き場所にある設定、認証情報、記憶、スキル、セッション、 プロファイルが入ります。アプリや実行環境そのもののイメージではありません。

1. その zip を新しい端末へコピーして読み込ませます。

# On the source machine
scp ~/hermes-backup-<timestamp>.zip newmachine:~/

# On the new machine
hermes import ~/hermes-backup-<timestamp>.zip

1. 新しい端末で hermes setup を実行し、API キーとプロバイダーの設定が効いているか確かめます。

プロファイルを 1 つだけ別の端末へ移す

こんなとき: インストール全体ではなく、特定のプロファイルだけを移したい、あるいは誰かに渡したい、という場面です。

# On the source machine
hermes profile export work ./work-backup.tar.gz

# Copy the file to the target machine, then:
hermes profile import ./work-backup.tar.gz work

読み込んだプロファイルには、書き出したときの設定・記憶・セッション・スキルがすべて入っています。移した先の環境が違う場合は、パスを直したりプロバイダーの認証をやり直したりが必要になることがあります。

hermes backup と hermes profile export の違い

| 項目 | hermes backup | hermes profile export |

| :--- | :--- | :--- |

| 使う場面 | 端末まるごとの引っ越し | 特定のプロファイルの持ち出し・受け渡し |

| 範囲 | Hermes のデータの置き場所（下に挙げるものは除きます） | プロファイル 1 つ分のディレクトリ |

| 入るもの | 全プロファイル、全体の設定、API キー、セッション | プロファイル 1 つ分: SOUL.md、記憶、セッション、スキル |

| 認証情報 | 入ります（.env と auth.json） | 入りません（安全に渡せるよう取り除かれます） |

| 形式 | .zip | .tar.gz |

まるごとのバックアップから除かれるもの:

• ソースのチェックアウト、依存パッケージの環境、ダウンロードしたツール・モデル・実行環境。
• ビルドのキャッシュ、チェックポイント、以前のバックアップ、手早く取ったスナップショット。
• ブラウザのプロファイル。実際のブラウザの認証情報のコピーも含みます。
• バイトコード、SQLite の付随ファイル、gateway.pid、cron.pid、.backup.lock。

hermes backup --quick は、まるごとの書庫ではなく、選んだ状態ファイルだけを保存します。 端末を引っ越す前のまるごとのバックアップの代わりにはなりません。

まるごとのバックアップでは、コピーに失敗したファイルが報告されます。つまり、データが欠けたまま 書庫ができていることもありえます。移す元のインストールを消す前に、飛ばされたファイルの報告を確かめてください。 戻したパッケージの宣言をもとに、PM が依存パッケージをもう一度ダウンロードできます。バイトコードと SQLite の付随ファイルは手元で作り直されます。除かれるものがあっても、.env と auth.json はまるごとのバックアップに入ったままです。

手作業でやる場合（rsync）: 自分でファイルをコピーしたいなら、コードのリポジトリを除いてください。

rsync -av --exclude='hermes-agent' ~/.hermes/ newmachine:~/.hermes/

インストール後にシェルを読み直すと permission denied になる

こんなとき: Hermes のインストーラーを実行したあと、source ~/.zshrc が permission denied で失敗します。

原因: たいていは ~/.zshrc（または ~/.bashrc）のファイル権限がおかしいか、インストーラーがうまく書き込めなかったときに起きます。Hermes に固有の問題ではなく、シェルの設定ファイルの権限の問題です。

対処:

# Check permissions
ls -la ~/.zshrc

# Fix if needed (should be -rw-r--r-- or 644)
chmod 644 ~/.zshrc

# Then reload
source ~/.zshrc

# Or just open a new terminal window — it picks up PATH changes automatically

インストーラーが PATH の行を書き足したのに権限が合っていない、という場合は、自分で書き足すこともできます。

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc

最初の実行で Error 400 になる

こんなとき: セットアップは問題なく終わったのに、最初のチャットが HTTP 400 で失敗します。

原因: たいていはモデル名の食い違いです。設定したモデルがそのプロバイダーに存在しないか、API キーにそのモデルを使う権限がありません。

対処:

# Check what model and provider are configured
hermes config show | head -20

# Re-run model selection
hermes model

# Or test with a known-good model
hermes chat -q "hello" --model anthropic/claude-opus-4.7

OpenRouter を使っているなら、API キーに残高があるか確かめてください。OpenRouter の 400 は、そのモデルが有料プラン限定であるか、モデル ID の打ち間違いであることがよくあります。

それでも解決しないときは

ここに載っていない問題に当たったら、次を試してください。

1. 既存の報告を探す: GitHub Issues
2. コミュニティに聞く: Nous Research Discord
3. 不具合として報告する: OS、Python のバージョン（python3 --version）、Hermes のバージョン（hermes --version）、そしてエラーメッセージの全文を添えてください