Hermes Agent：実践者向けリファレンス（2026年版）

要点： Hermes Agent は、Nous Research が開発するオープンソースの自己改善型 AI エージェントです。CLI とマルチプラットフォームのメッセージング gateway として動作し、永続的なアイデンティティとメモリをディスクに保存します。使用するほど向上する skills を集約し、OpenAI 互換のあらゆる LLM プロバイダー（Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Qwen Cloud、Hugging Face、Google、xAI/SuperGrok、または独自のセルフホスト型エンドポイント）に対応しています。¹²¹⁹ v0.14.0（2026年5月16日）では、grok-4.3 の 1M context に対応した SuperGrok OAuth、OAuth プロバイダー向けの OpenAI 互換ローカルプロキシ（hermes proxy）、ファーストクラスの x_search、PyPI からのインストール対応（v0.19.0 で非推奨化され、現在は1行インストーラーが正式な方法です）、依存関係の遅延インストール、LINE と SimpleX Chat を含む22のメッセージングプラットフォーム、/handoff、書き込み後の LSP セマンティック診断、統合された video_generate、Anthropic 以外のプロバイダーで cua-driver を介して動作する computer_use、ネイティブ Windows ベータ版、そして12件の P0／50件の P1 対応完了が追加されました。¹⁹ 多くの新規ユーザーにとって最も難しいのは、プロバイダー認証です。Hermes は約20のファーストクラスプロバイダーとカスタムエンドポイントに対応しており、認証方法は3つに分かれます（.env の API キー、hermes model を使用する OAuth、または config.yaml のカスタムエンドポイント）。まず理解すべきなのは、この認証モデルです。それ以外のすべては、どのプロバイダーが解決されるかによって決まります。

Hermes Agent はチャットラッパーではなく、完全なエージェントランタイムとして動作します。 ファイルシステムの読み取り、サンドボックス化されたバックエンドでのコマンド実行、ウェブスクレイピング、サブエージェントの起動、スケジュールされた cron ジョブの実行に対応しています。さらに、単一の gateway プロセスから Telegram/Discord/Slack/WhatsApp/Signal/Email とやり取りし、経験に基づいて独自の skills を作成します。¹ CLI は、run_agent.py の会話ループ上に構築されたターミナル UI です。gateway は長時間稼働するプロセスで、メッセージングプラットフォームからのメッセージを同じ会話ループへルーティングします。³

Hermes を気軽に使う場合と使いこなす場合の違いは、次の5つのシステムを理解しているかどうかです。 これらを習得すれば、Hermes は強力な力になります。

1. プロバイダー解決：認証フローが API 呼び出しにどう対応するか
2. 設定の階層：config.yaml + .env + auth.json + SOUL.md + AGENTS.md
3. ツール + toolset システム：エージェントが実行できる操作と、プラットフォームごとの制限
4. Skills システム：エージェントが作成し、進化させる手続き的記憶
5. Gateway + cron + profiles：その場限りではなく、普段利用する場所で Hermes を動かす仕組み

重要なポイント

• プロバイダー認証には1つではなく、3つの方法があります。 .env の API キー、hermes model/hermes auth を使用する OAuth、または config.yaml のカスタムエンドポイントです。慣れ親しんだ方法ではなく、利用するプロバイダーに合った方法を選んでください。
• プロバイダーは1つのコマンドで切り替えられます。 hermes model を実行すると、OAuth ログインを含む、対応するすべてのプロバイダーを対話形式で設定できます。また、/model provider:model を使えば、履歴を失わずにセッションの途中で切り替えられます。²
• ユーザーが編集する設定ファイルは2つです。 ~/.hermes/config.yaml には設定を、~/.hermes/.env にはシークレットを保存します。auth.json、SOUL.md、MEMORY.md、skills/ は Hermes が直接管理します。SOUL.md は手動で編集できますが、それ以外はエージェント自身が更新します。⁴
• Hermes は OpenClaw の後継です。 移行する場合は、hermes claw migrate で30以上のカテゴリにわたる状態を自動的にインポートできます。⁵
• サービス品質は補助モデルによって左右されます。 ビジョン、ウェブ要約、圧縮、メモリのフラッシュには、すべて別の補助 LLM が使われます。デフォルトでは自動検出（OpenRouter → Nous → Codex）によって Gemini Flash が使用されます。いずれも設定されていない場合、補助スロットにメインプロバイダーを指定するまで、これらの機能は通知なく品質が低下します。⁴

v0.14 で変わること

v0.14.0 は、目玉となる1つの機能よりも、セットアップの負担を減らしつつ Hermes を実行できる環境を広げることに重点を置いています。¹⁹ 主な運用上の変更点は次のとおりです。

• インストールと起動が軽量化されました。 PyPI から pip install hermes-agent でインストールでき、負荷の大きなアダプターは初回使用時に遅延インストールされます。また、起動処理の一部を遅延させることで、コールドスタートを約19秒短縮しています。（その後、v0.19.0 で pip インストールは非推奨となりました。インストールをご覧ください。）
• サブスクリプションをローカル API エンドポイントとして利用できます。 hermes proxy を使用すると、Claude Pro、ChatGPT Pro、SuperGrok などの OAuth ベースのプロバイダーを、Codex、Aider、Cline、Continue といったツール向けの OpenAI 互換ローカルエンドポイントに変換できます。
• Gateway の対応範囲が広がりました。 LINE と SimpleX Chat の追加により、対応プラットフォームは22に増えました。Microsoft Teams はエンドツーエンドで接続され、Discord の履歴バックフィルはデフォルトで有効です。また、Telegram/Discord の clarify プロンプトでネイティブボタンを使用できるようになりました。
• 書き込み時の検証が強化されました。 編集後、次のターンに進む前に、ターンごとのファイル変更の要約と、言語サーバーによるセマンティック診断を表示できます。これにより、根拠に基づくエージェント作業へさらに近づきました。
• デスクトップおよびメディアツールが拡充されました。 Anthropic 以外のプロバイダーでも cua-driver を介して computer_use が動作し、video_generate は差し替え可能なバックエンドのもとに統合されました。また、vision_analyze は実際に視覚入力を処理できるモデルへ生のピクセルデータを送信します。

以下の各セクションはすべて、hermes-agent.nousresearch.com/docs の公式ドキュメントと、github.com/NousResearch/hermes-agent のソースツリーに基づいています。すべての事実に関する記述には、その出典となった具体的な公式ページを示す脚注があります。

目的別の案内

Hermes の仕組み：メンタルモデル

Hermes は、どのエントリーポイントからでも呼び出せる単一の会話ループを中心に構成されています。エントリーポイントには、CLI（cli.py）、メッセージング gateway（gateway/run.py）、エディタ連携用の ACP アダプター、バッチランナー、API サーバーがあります。³ いずれも最終的には run_agent.py の AIAgent.run_conversation() を呼び出し、次の処理を行います。

1. prompt_builder.py を介して、SOUL.md、MEMORY.md、USER.md、skills、コンテキストファイル、ツールのガイダンスからシステムプロンプトを構築します³
2. runtime_provider.py で実行時のプロバイダーを決定します。この段階で認証、ベース URL、API モードが選択されます³
3. chat_completions、codex_responses、anthropic_messages のいずれかの API モードでプロバイダーを呼び出します³
4. 返されたツール呼び出しを model_tools.py と中央ツールレジストリ（tools/registry.py）経由でディスパッチします³
5. モデルが最終回答を生成するまでループし、その後セッションを FTS5 対応の SQLite に保存します³

このループを理解することが重要なのは、personality、メモリ、skills、圧縮、フォールバックといったすべての機能が、いずれかの段階に結び付いているためです。設定キーを見て「これは何をするのだろう」と思ったら、たいていは「上記ループの段階 1、2、3、4 のいずれかを調整するノブ」と考えればよいでしょう。

プラットフォームに依存しないコア。 1つの AIAgent クラスが、CLI、gateway、ACP、バッチ、API サーバーを担います。プラットフォームごとの差異はエントリーポイント側にあり、エージェント自体にはありません。³ そのため、ターミナルと Telegram で同じスラッシュコマンドを利用できます。どちらも hermes_cli/commands.py の共通 COMMAND_REGISTRY からディスパッチされる仕組みです。⁶

ディレクトリ構造そのものがシステムです。 Hermes はすべてを ~/.hermes/（デフォルト以外の profiles では $HERMES_HOME）配下に保存します。⁴

~/.hermes/
├── config.yaml        # Settings (model, terminal, TTS, compression, etc.)
├── .env               # API keys and secrets
├── auth.json          # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md            # Primary agent identity (slot #1 in system prompt)
├── memories/          # Persistent memory (MEMORY.md, USER.md)
├── skills/            # Bundled + agent-created + hub-installed skills
├── cron/              # Scheduled jobs
├── sessions/          # Gateway session state
└── logs/              # agent.log, gateway.log, errors.log (secrets auto-redacted)

上記のファイルにはそれぞれ固有の役割があり、役割の重複はありません。「Hermes は X をどこに保存するのか」を知りたい場合、答えはこの中にあります。

v0.19.0（The Quicksilver Release）の新機能

Hermes Agent v0.19.0（タグ v2026.7.20、2026年7月20日）は、伝令神自身の俊足にちなんで名付けられました。このリリースの柱は圧倒的な応答性で、全プラットフォームにおける初回ターンの最初のトークンまでの時間を約80%短縮しています。さらに、ターミナルでの請求管理、パスワードマネージャーを利用したシークレット取得、デフォルトでのスマート承認、観察可能なサブエージェント、クラッシュに強い応答配信が加わりました。v0.18.0 以降の変更規模はプロジェクト史上最大で、約2,245件のコミット、約1,065件のマージ済み PR、約3,300件のクローズ済み issue、450人を超えるコミュニティ貢献者に及びます。²³

• あらゆる環境で、最初のトークンまで約80%高速化。 コールド状態での送信からディスパッチまでの時間は、CLI、gateway、TUI、デスクトップ、cron のすべてで約4.3秒から約0.9秒へ短縮されました。Discord の機能検出をクリティカルパスから外し、Ollama 以外と判明しているプロバイダーでは Ollama のプローブを省略し、エージェント初期化からブロッキング処理を排除しています。体感レイテンシも個別に改善されました。推論モデルは思考過程をデフォルトでリアルタイム配信するようになり（display.show_reasoning は ON）、応答ボックスも行単位ではなくトークン単位で描画されます。²³
• デスクトップと TUI のレンダリングを刷新。 デスクトップアプリには約20件の PR による高速化が施されました。ストリーミング Markdown の分割処理では、インクリメンタルなブロック字句解析により CPU 使用量を14分の1に削減し、レビューペインの差分表示を仮想化しています。大規模な会話履歴でもセッションを軽快に切り替えられ、トークンごにサイドバーやツール行を再レンダリングすることもなくなりました。TUI でも、ストリーミングされる Markdown をブロック単位で逐次レンダリングするようになっています。²³
• pip と Homebrew によるインストールは非推奨。 どちらの方法も「サポート対象外のレガシー」インストールとして扱われるようになりました。すべての画面で警告が表示されますが、操作はブロックされません。PyPI/Homebrew での公開も廃止が予定されています。サポートされる方法はワンラインインストーラーです。pip または brew でインストールした場合は、今のうちに移行を計画してください。²³
• パスワードマネージャーからシークレットを取得可能。 新しいプラグイン可能な SecretSource インターフェースにより、読み込み時に Bitwarden と 1Password（op:// 参照）からシークレットを取得できます。複数のボールトを同時に有効化でき、決定論的な優先順位、競合警告、変数ごとの取得元情報にも対応しています。API キーを平文の .env に保存する必要はもうありません。今後のボールトプロバイダーもプラグインとして追加できます。²³
• スマート承認がデフォルトに。 Hermes がフラグ対象のコマンドを実行しようとすると、毎回確認を求める代わりに、独立した LLM レビュアーが評価します。各判定が適用されるのは、そのコマンドだけです。ユーザー定義の 拒否ルール は YOLO mode でも一致するコマンドをブロックします。/deny <reason> を使うと拒否理由がエージェントに伝わるため、方針を修正できます。また、ルールキーを伴って再導入されたプラグインの pre_tool_call 承認アクションにより、ツール呼び出しを人間の承認ゲートへエスカレーションできます。²³
• ターミナルでの請求管理：/subscription と /topup。 ターミナルを離れずに Nous Portal のプランを管理できます。現在のプランと残りの利用枠を確認し、アップグレードにかかる正確な費用やダウングレードが有効になる時期を事前に確認したうえで、取り消し可能な形で適用できます。デスクトップアプリにも同等の請求設定タブが追加されました。²³
• サブエージェントの作業を確認し、完成した回答を確実に保持。 delegate_task がディスパッチされると、サブエージェントの起動直後から tail -f できるライブトランスクリプトファイルが生成されます。各子エージェントにつき、人が読める形式のログが1つ用意され、すべてのツール呼び出し、結果、ストリーミング応答を確認できます。バックグラウンド委任の完了情報は再起動後も保持されます。また、gateway の最終応答は state.db の 配信義務台帳 に記録され、送信中に gateway が停止した場合は次回起動時に再配信されます。max_async_children 設定オプションは、統合された委任同時実行数の上限を優先するため 非推奨 となりました。²³
• 1つの gateway で複数の profiles を運用。 1つの bot トークンを共有する単一の多重化 gateway で、特定のギルド、チャンネル、スレッドを異なる profiles にルーティングできます。設定、skills、メモリ、シークレットは profile ごとに完全に分離され、GATEWAY_MULTIPLEX_PROFILES によるオーバーライドにも対応します。ルーティングインデックスは state.db に移行し、sessions.json は任意のレガシーミラーとなりました。²³
• プロバイダーとモデルを一挙に拡充。 Fireworks AI が正式対応となり、コスト見積もりとプロバイダー選択画面の第2スロットが追加されました。DeepInfra と Upstage Solar も加わっています。カタログには、GPT-5.6（Sol/Terra/Luna + Pro、エンドツーエンドで接続済み）、grok-4.5（GA）、kimi-k3（kimi-k2.x は廃止）、完全に接続された Claude Sonnet 5 が追加されました。プロバイダーごとの enabled: false フラグと excluded_providers 設定により、未使用のプロバイダーを /model の選択肢と解決処理から除外できます。²³
• 推論 effort をダイヤルのように調整可能。 新しい max と ultra の effort 段階がすべての画面に追加されました。設定でモデルごとに上書きできるほか、MoA プリセットではスロットごとに effort を指定でき（アドバイザーは深く考え、統合モデルは高速性を維持）、補助モデルではタスクごとの effort も設定できます。CLI にはセッション単位の /reasoning も追加されました。²³
• CLI と MCP の機能拡充。 hermes sessions export は Markdown、Quarto、HTML、プロンプトのみ、Hugging Face トレースの各形式で書き出せます。オプトインの --redact による情報除去にも対応しています。/model --once では1ターン限定でモデルを上書きでき、スラッシュ skill の呼び出しは重ねて指定できます（/skill-a /skill-b do XYZ）。--safe-mode はトラブルシューティングを支援し、hermes config get/unset により設定管理機能が充実しました。hermes serve は真のヘッドレスバックエンドとなり、MCP ツールは mcp__server__tool 命名規則を採用しています。²³

v0.18.x からアップグレードする場合、まず2つの変更に注意してください。pip または Homebrew によるインストールでは、サポート対象外のレガシー方式であるという警告が表示されるようになったため、ワンラインインストーラーへ移行しましょう。また、max_async_children は非推奨となり、統合された委任同時実行数の上限に置き換えられました。それ以外はすべて追加的な変更です。アップグレードの主な理由は、初回ターンのレイテンシを約80%短縮したこと、スマート承認、そして完成した回答をクラッシュから守る配信台帳にあります。

v0.18.0 の新機能（The Judgment Release）

Hermes Agent v0.18.0（タグ v2026.7.1、2026年7月1日）は「判断」にちなんで名付けられました。成功したと主張するのではなく、エージェントが自らの作業を検証し、実際に内容を確認できるアンサンブル推論を提供します。また、P0/P1 のバックログをすべて解消し、約692件の最優先項目を12日間で解決しました。²²

• Mixture-of-Agents が正式なモデルに。 MoA をすべてのインターフェースでほかのモデルと同じように選択できるようになり、アンサンブル推論も可視化されました。各参照モデルの完全な出力が、ラベル付きの独立したブロックとしてライブストリーミング表示されます。不透明に統合された回答を受け取るだけでなく、アンサンブルが考える様子を確認できます。²²
• /goal の完了コントラクト。 ゴールの完了を報告する前に、プロジェクトのチェックを実行して作業を自ら検証します。成功したと主張するだけではなく、自分自身にも判断を適用する仕組みです。²²
• /learn — あらゆる内容を説明して skill に。 ワークフローを説明するだけで、再利用可能な skill に変換できます。生成される skill は、リポジトリの CONTRIBUTING.md 規約に自動的に準拠します。²²
• /journey タイムライン。 メモリと skill の変遷を時系列で視覚化し、編集も行えます。デスクトップではメモリグラフも利用できます。²²
• バックグラウンド subagent のファンアウト。 会話を妨げることなく、複数のタスクを委任して同時に実行できます。v0.17.0 の単一バックグラウンド subagent が、複数の subagent からなる体制へと進化しました。²²
• デスクトップ Projects。 プロジェクト、リポジトリ、レーンによる構成モデルを備えた、本格的なコーディング Projects が追加されました。²²
• スケール・トゥ・ゼロ対応 gateway。 アイドル時には gateway を休止でき、シームレスなデプロイに向けてドレイン処理を協調できます。Hermes を常時稼働サービスとして運用する場合に特に有用です。²²
• Google Vertex AI 対応。 GCP サービスアカウントを通じて Gemini を利用でき、OAuth2 トークンも自動更新されます。これにより、プロバイダーカタログに新たな選択肢が加わりました。²²
• /prompt エディターコマンド。 入力行で苦労せずに複数行のプロンプトを作成できるよう、$EDITOR を開きます。²²

v0.17.x からアップグレードしても、CLI に破壊的変更はありません。アップグレードの主な理由は、ゴール自体が検証を行う完了コントラクト、内容を確認できるアンサンブルを備えた正式な MoA、そして skill を取り込むための /learn です。

v0.17.0 の新機能（The Reach Release）

Hermes Agent v0.17.0（タグ v2026.6.19、2026年6月19日）は、エージェントの到達範囲が広がったことにちなんで名付けられました。新しいメッセージングチャンネルやモデルプロバイダーが加わり、デスクトップとダッシュボードからより詳細に制御できます。v0.16.x に機能を追加したリリースであり、CLI の操作体系に変更はありません。²¹

• 新しいメッセージングチャンネル。 iMessage は Photon Spectrum（デバイスコード OAuth、hermes photon login）により、Mac のリレーなしで動作するようになりました。WhatsApp Business Cloud API は、ブリッジプロセスを不要にする Meta 公式アダプターです。SimpleX では、グループ、ネイティブ添付ファイル、テキストのバッチ処理、自動承認に対応しました。さらに、プライバシーを契約で保証するウェイクチャンネル設計を採用した Raft が、同梱のプラットフォームプラグインとして追加されています。²¹
• 新しいモデルとプロバイダー。 カタログに z-ai/glm-5.2（1M コンテキスト）、anthropic/claude-fable-5、laguna-m.1、nemotron-3-ultra、grok-composer-2.5-fast（xAI OAuth 経由で利用する Cursor のモデル、200k コンテキスト）が追加されました。xAI のデフォルトは grok-build-0.1 に変更され、Anthropic の適応型モデルは最新の思考コントラクトに従うようになりました（reasoning フィールドを送信しません）。²¹
• デスクトップとダッシュボード。 デスクトップには、委任した処理をライブストリーミングする「ウォッチウィンドウ」付きのバックグラウンド subagent（delegate_task(background=true)）、Composer のモデルセレクター、再割り当て可能なキーボードショートカット、OS ネイティブの通知、スレッドごとの Composer 下書き、VS Code Marketplace のテーマ、日本語と繁体字中国語の UI が追加されました。ダッシュボードには、config.yaml を編集せずにモデル、skills、MCPs を設定できる完全な profile ビルダー、グローバル profile スイッチャー、セキュリティスキャンを備えて刷新された Skills Hub、フォーム、スラッシュコマンド、会話、ドキュメントに対応するパラメーター化テンプレートの Automation Blueprints、そして OAuth ゲートの背後で 401 を返す安全なログイン機能が追加されました。²¹
• Skills とツール。 image_generate は、対応するすべての画像プロバイダーで、画像を一から生成するだけでなく、元画像の編集と変換も行えるようになりました。memory ツールには operations 配列が追加され、追加、置換、削除を1回の呼び出しでアトミックに一括処理できます。新しい simplify-code skill は、チェスタトンの柵に基づくリスク階層をゲートとして、3つのエージェントによる並列のレビューとクリーンアップを実行します。また、3状態の write_mode は、ブール値の write_approval に置き換えられました。²¹
• アーキテクチャ。 バックグラウンド subagent は直ちにハンドルを返し、結果を新しいターンとして会話へ戻します。ツール呼び出しの途中で確認できる MCP 引き出しハンドラーが追加され、遅れて接続された MCP ツールもターン間で公開されるようになりました（キャッシュセーフ）。cron は Chronos のマネージド cron プロバイダーを備えた、交換可能な CronScheduler になりました。さらに、新しい Managed scope（/etc/hermes）では、管理者がユーザーによる変更を許可しない設定を固定できます。複数 gateway 構成向けの Gateway-Gateway リレーも追加されました。²¹
• 新しいコマンド。 /version、/billing（対話型ターミナル請求情報）、hermes photon login（iMessage 認証）、hermes curator run --consolidate が追加されました。統合処理はオプトインになったため、通常のバックグラウンド整理ではトークンを消費しません。²¹
• セキュリティ。 v0.17.0 では、シェルエスケープの拒否リストを回避できる問題を修正しました。また、承認モジュールや独自ポリシーの gateway アダプターが欠けている場合は安全側に停止し、cron ジョブスクリプトのサブプロセス環境をサニタイズします。リクエストのデバッグダンプではシークレットを秘匿し、MCP の stdio 設定にデータ流出パターンがないか検査します。さらに、CVE を解消するため urllib3 と PyJWT を更新しました。²¹

v0.16.x からアップグレードしても、CLI に破壊的変更はありません。同じエージェントを中心に、新しいチャンネル、モデル、操作画面が追加されたリリースです。リレー不要の iMessage、WhatsApp 公式アダプター、管理者向けの Managed scope が、アップグレードの主な理由となります。

v0.16.0 の新機能（The Surface Release）

Hermes Agent v0.16.0（タグ v2026.6.5、2026年6月5日）は、CLI を中心とするエージェントに新たな操作画面を提供することにちなんで名付けられました。最大の変更点は、Hermes がターミナル専用ではなくなったことです。²⁰

• ネイティブデスクトップアプリ。 Hermes Desktop は、macOS、Linux、Windows に対応する新しい Electron アプリです。ワンクリックでインストールでき、アプリ内で自動更新できます。ストリーミング対応のチャットウィンドウ、ファイルのドラッグ＆ドロップ、クリップボードからの画像貼り付け、Cmd+K パレット、アーカイブと検索機能を備えたセッション一覧、ステータスバーのモデル選択機能を利用できます。安全な WebSocket を介してリモートの Hermes gateway に接続でき、OAuth またはユーザー名とパスワードで認証します。profile ごとにリモートホストを設定でき、profile をまたぐ @session 参照で連携する複数 profile の同時セッションにも対応しています。デスクトップ UI には、型付けされた i18n レイヤー（display.language、デフォルトは英語）を通じて、完全な簡体字中国語（简体中文）翻訳も搭載されています。²⁰
• ブラウザー管理パネル。 ローカルのウェブダッシュボードは、ステータス表示から本格的な管理パネルへと進化しました。有効化／無効化を切り替えられる MCP カタログ、認証情報の管理、webhook と hook の作成、メモリ設定、gateway の制御、更新前チェックとワンクリックの Debug Share を備えた System ページが含まれます。新しい Channels ページでは、Telegram、Discord、Slack など、gateway の全メッセージングプラットフォームをブラウザーから設定できます。認証も交換可能になり、ユーザー名とパスワードによるログイン、汎用のセルフホスト OIDC プロバイダー、セルフホストの OAuth クライアントを登録する hermes dashboard register、リフレッシュトークンによるセッションローテーションに対応しました。²⁰
• 新しい CLI コマンドとスラッシュコマンド。 /undo [N] は直近 N 回分のユーザーターンを、事前入力とソフトデリート付きで巻き戻します。CLI、TUI、各メッセージングプラットフォームで利用できます。デフォルトのインターフェース（cli または tui）を設定できるようになり、--cli で上書きできます。TUI には統合された /model コマンドと Sessions オーバーレイが追加されました。hermes portal は Nous Portal のオンボーディングフローを人が理解しやすくしたエイリアスです。初回実行時には Quick Setup と Full Setup の新しい経路を選べます。さらに、hermes prompt-size と hermes sessions optimize という2つの診断機能も追加されました。²⁰
• 新しいモデルとプロバイダー。 モデル選択には deepseek-v4-flash、MiniMax-M3（1M コンテキスト、ネイティブ MiniMax プロバイダー）、qwen3.7-plus（Nous + OpenRouter）、gemini-3.5-flash（Gemini OAuth + API キー）が追加されました。正式な xAI Grok OAuth プロバイダーもデスクトップランチャーに加わっています。モデル選択はすべての操作画面であいまい検索に対応し、複数のエンドポイントを持つプロバイダーは1行にまとめて表示されます。カタログの更新間隔も、1日ごとから1時間ごとに変更されました。²⁰
• より軽量な skills と段階的開示。 デフォルトの skill セットから、重複するものや使用されていないものが削除されました（Spotify はネイティブプラグインへ、Linear は hermes mcp install linear へ移行し、古くなった項目も複数削除されています）。より多くの skill がオプションに移され、environments: フロントマターによる関連性ゲート（kanban／docker／s6）が追加されました。これにより、特定のコンテキスト向け skill は要求されるまでインデックスに含まれません。NVIDIA/skills は、OpenAI、Anthropic、HuggingFace と並ぶ Skills Hub のデフォルトの信頼済み tap になりました。MCP ツールとプラグインツールでは、段階的な（スコープ限定の）ツール開示に対応しました。トークンを取得できていないにもかかわらず OAuth の成功を誤って報告していた MCP のバグも修正されています。²⁰
• セキュリティ。 v0.16.0 では、CVE-2026-48710（BadHost）に対応済みの Starlette（≥1.0.1）を固定しています。非同期処理では SSRF の URL チェックをイベントループ外へ移し、サブプロセスの環境から Bedrock の推論用ベアラートークンを除去しました。また、bws_cache.json をファイル安全性の読み取りガードに追加し、docker restart/stop/kill を危険パターンの一覧に加え、検証済み skill コンテンツ内の不可視 Unicode をサニタイズします。このリリースでは P0 の問題を2件、P1 の問題を62件解決し、そのうち16件にはセキュリティタグが付いていました。²⁰

v0.15.x からアップグレードしても、CLI 自体に破壊的変更はありません。同じエージェントを中心に、操作画面とプロバイダーを追加したリリースです。ターミナルを使わないユーザー向けに Hermes を運用したい場合や、リモートの gateway をブラウザーから管理したい場合は、デスクトップアプリと管理パネルがアップグレードの理由となります。

インストール

サポートされているインストール方法は、1行インストーラーです。Python、uv、Node.js、ripgrep、ffmpeg、リポジトリのクローン、仮想環境、グローバルな hermes コマンドのセットアップを一括で処理します。⁷

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

v0.19.0以降、pipおよびHomebrewによるインストールは非推奨です。 v0.14.0で導入されたPyPIパッケージ（pip install hermes-agent）とHomebrew formulaは、現在「サポート対象外のレガシー」インストールとされています。Hermesがこれらを検出すると、すべての操作画面で警告が表示されます（操作はブロックされません）。また、PyPI/Homebrewでの公開も廃止される予定です。pipまたはbrewでインストールした場合は、上記のインストーラーへ移行してください。²³

Linux、macOS、WSL2、Android/Termuxで動作します（インストーラーがTermuxを自動検出し、テスト済みのAndroidバンドルに切り替えます）。⁷ v0.14.0では、PowerShellインストーラーによるWindowsネイティブ対応が初期ベータとして追加されました。ただし、Windows向けの手順が成熟するまでは、本番環境にはWSL2の使用を引き続き推奨します。¹⁹

完了したら、次を実行します。

source ~/.bashrc    # or ~/.zshrc
hermes              # Start chatting

唯一の前提条件は git です。インストーラーは、uvを使用してPython 3.11（sudo不要）、Node.js v22（ブラウザー自動化とWhatsAppブリッジ用）、ripgrep、ffmpegを自動的に用意します。⁷

インストールを確認する

hermes version      # Check version
hermes doctor       # Diagnose config/dependency issues
hermes status       # Show current configuration + auth state
hermes dump         # Copy-pasteable setup summary for debugging

hermes doctorを実行すると、不足しているものと、その修正方法が具体的に表示されます。⁷ サポートを求める際にGitHubのissueやDiscordスレッドへ貼り付ける診断コマンドがhermes dumpです。機密情報を伏せたうえで、セットアップ全体をプレーンテキストにまとめます。⁸

手動インストール

Pythonのバージョン指定、特定のextras、Nix/NixOSとの統合など、セットアップを細かく制御する必要がある場合は、上流のインストールガイドに手動手順が詳しく記載されています。⁷ uv pip install -e ".[<extras>]"で組み合わせられる主なオプションのextrasは次のとおりです。

Termuxのインストールコマンドは異なります — uv pipではなく、制約ファイルを指定したpipを使用します。

python -m pip install -e ".[termux]" -c constraints-termux.txt

これは、Androidで.[all]を指定すると、voice extraを介してfaster-whisperが導入されるためです。その依存先であるctranslate2のwheelは、Android向けに公開されていません。⁷

認証とプロバイダー

Hermes は約22のファーストクラスプロバイダーに加え、カスタムエンドポイント（v0.19.0では Fireworks AI、DeepInfra、Upstage Solar を追加）と、3つの異なる認証経路をサポートしています。利用中の環境に合うものを見つけられるよう、認証方法ごとに全体像を整理します。

3つの認証経路

Hermes のすべてのプロバイダーは、次の3つの認証パターンのいずれかに該当します。

経路1 — .env 内の API キー。 ~/.hermes/.env にキーを保存すると、Hermes が起動時に読み取ります。OpenRouter、AI Gateway、z.ai/GLM、Kimi/Moonshot、MiniMax（MiniMax China を含む）、Alibaba Cloud/DashScope、Kilo Code、OpenCode Zen、OpenCode Go、DeepSeek、Hugging Face、Google/Gemini、および大半のサードパーティプロバイダーで使用します。² v0.19.0以降、キーをプレーンテキストファイルに保存する必要はありません。プラグイン可能な SecretSource インターフェースにより、読み込み時に Bitwarden または1Password（op:// 参照）からシークレットを取得できます。複数の保管庫を同時に有効化でき、決定論的な優先順位、競合警告、変数ごとの取得元情報にも対応しています。.env は引き続きフォールバックとして使用されます。（これは、単一のトークンの背後にプロバイダーキーを集約したv0.15.0の Bitwarden Secrets Manager ブートストラップトークンとは異なります。SecretSource はプレーンテキストファイル自体を置き換えるもので、今後の保管庫プロバイダーもプラグインとして追加できます。）²³

経路2 — hermes model または hermes auth を介した OAuth。 デバイスコードフローを開始してブラウザを開き、認証情報を ~/.hermes/auth.json に保存します（Claude Code や Codex CLI などのツールから既存の認証情報をインポートすることも可能です）。Nous Portal、OpenAI Codex（ChatGPT アカウント）、GitHub Copilot、Anthropic（Claude Pro/Max）で使用します。²

経路3 — config.yaml 内のカスタムエンドポイント。 Ollama、vLLM、SGLang、llama.cpp、LM Studio、LiteLLM プロキシ、Together AI、Groq、Azure OpenAI、独自のセルフホストサーバーなど、OpenAI互換のあらゆる API に利用できます。hermes model → Custom endpoint で一度設定すると、config.yaml に永続化されます。²

プロバイダーの完全な対応表

以下は、すべてのファーストクラスプロバイダーと、それぞれの正確なセットアップ手順です。²

v0.19.0以降は、使用しないプロバイダーを除外することもできます。プロバイダーごとの enabled: false フラグと excluded_providers 設定キーにより、/model の選択画面や組み込みのプロバイダー解決処理から削除できます。²³

Anthropic：3つの認証方法

Hermes では Claude に接続するための3つの異なる経路をサポートしており、適切な方法を選ぶことが重要なため、Anthropic については独立したセクションで説明します。アップストリームのドキュメントでは、次のように記載されています。²

# Method 1: API key (pay-per-token)
export ANTHROPIC_API_KEY=***
hermes chat --provider anthropic --model claude-sonnet-4-6

# Method 2: OAuth through hermes model (preferred)
# Uses Claude Code's credential store when available
hermes model

# Method 3: Manual setup-token (fallback/legacy)
export ANTHROPIC_TOKEN=***
hermes chat --provider anthropic

# Auto-detect Claude Code credentials
hermes chat --provider anthropic   # reads Claude Code files automatically

hermes model で Anthropic OAuth を選択すると、Hermes はトークンを ~/.hermes/.env にコピーするのではなく、Claude Code 自体の認証情報ストアを優先します。これにより、更新可能な Claude の認証情報を引き続き更新できます。² 同じマシンですでに Claude Code を使用している場合は、これが最もすっきりした方法です。

config.yaml で Anthropic を恒久的に固定するには、次のようにします。

model:
  provider: "anthropic"
  default: "claude-sonnet-4-6"

--provider claude と --provider claude-code も、--provider anthropic の省略表記として使用できます。²

GitHub Copilot：2つのモード

Copilot は、Copilot API への直接接続（推奨）と、ローカルの Copilot CLI をサブプロセスとして起動する Copilot ACP の2つのモードに対応しています。²

# Direct Copilot API
hermes chat --provider copilot --model gpt-5.4

# Copilot ACP (requires the Copilot CLI in PATH + an existing copilot login)
hermes chat --provider copilot-acp --model copilot-acp

アップストリームのドキュメントによると、認証は次の順序で確認されます。² 1. COPILOT_GITHUB_TOKEN 環境変数 2. GH_TOKEN 環境変数 3. GITHUB_TOKEN 環境変数 4. gh auth token CLI フォールバック 5. hermes model を介した OAuth デバイスコードログイン

トークンの種類が重要です。 Copilot API は、従来型の Personal Access Token（ghp_*）をサポートしていません。対応しているのは、OAuth トークン（gho_*）、きめ細かなPAT（Copilot Requests 権限を持つ github_pat_*）、GitHub App トークン（ghu_*）です。gh auth token が ghp_* トークンを返す場合は、代わりに hermes model を使用して OAuth 経由で認証してください。²

中国のAIプロバイダー（ファーストクラスサポート）

Hermes は、z.ai/GLM、Kimi/Moonshot、MiniMax（グローバルおよび中国向けエンドポイント）、Alibaba Cloud を、専用のプロバイダーIDで組み込みサポートしています。²

# z.ai / ZhipuAI GLM
hermes chat --provider zai --model glm-5                 # Requires: GLM_API_KEY

# Kimi / Moonshot AI
hermes chat --provider kimi-coding --model kimi-for-coding   # Requires: KIMI_API_KEY

# MiniMax (global)
hermes chat --provider minimax --model MiniMax-M2.7          # Requires: MINIMAX_API_KEY

# MiniMax (China)
hermes chat --provider minimax-cn --model MiniMax-M2.7       # Requires: MINIMAX_CN_API_KEY

# Alibaba Cloud / DashScope (Qwen)
hermes chat --provider alibaba --model qwen3.5-plus          # Requires: DASHSCOPE_API_KEY

ベースURLは、GLM_BASE_URL、KIMI_BASE_URL、MINIMAX_BASE_URL、MINIMAX_CN_BASE_URL、DASHSCOPE_BASE_URL の各環境変数で上書きできます。²

Z.AI はエンドポイントを自動検出します。 z.ai/GLM プロバイダーを使用すると、Hermes は複数のエンドポイント（グローバル、中国、コーディング向けの各バリエーション）を検査し、使用中の API キーを受け入れるものを探します。動作するエンドポイントは自動的にキャッシュされるため、大半のユーザーは GLM_BASE_URL を指定する必要がありません。²

xAI (Grok) ではプロンプトキャッシュが自動的に有効になります。 ベースURLに x.ai が含まれている場合、Hermes はすべてのリクエストに x-grok-conv-id ヘッダーを付けます。これにより、会話セッション中は同じサーバーへルーティングされ、キャッシュ済みのシステムプロンプトと履歴が再利用されます。² 自動的に動作するため、設定は不要です。

hermes auth コマンド

hermes auth は、認証情報プールと OAuth 認証情報を管理するためのコマンドです。⁶

hermes auth                              # Interactive wizard
hermes auth list                         # Show all credential pools
hermes auth list openrouter              # Show one provider's pool
hermes auth add openrouter --api-key sk-or-v1-xxx
hermes auth add anthropic --type oauth
hermes auth remove openrouter 2          # Remove by index
hermes auth reset openrouter             # Clear cooldowns

認証情報プールを使用すると、同じプロバイダーに対する複数の API キーまたは OAuth トークンをローテーションできます。コードを変更せずに、複数のキーへレート制限を分散したい場合に便利です。⁶ 従来の hermes login / hermes logout コマンドは削除されました。代わりに hermes auth を使用してください。⁶

カスタムおよびセルフホスト型エンドポイント

Hermes は、OpenAI互換のあらゆる API エンドポイントで動作します。サーバーが /v1/chat/completions を実装していれば、Hermes の接続先として指定できます。²

対話式セットアップ（推奨）：

hermes model
# Select "Custom endpoint (self-hosted / VLLM / etc.)"
# Enter: API base URL, API key, Model name

手動での config.yaml 設定：

model:
  default: your-model-name
  provider: custom
  base_url: http://localhost:8000/v1
  api_key: your-key-or-leave-empty-for-local

どちらの方法でも設定は config.yaml に永続化されます。メインモデル、プロバイダー、ベースURLについては、このファイルが唯一の信頼できる情報源となります。² 従来の環境変数 OPENAI_BASE_URL と LLM_MODEL は、メインモデルの設定には読み込まれなくなりました。hermes model を使用するか、config.yaml を直接編集してください。²（補助モデルの provider: "main" ルーティング経路では、OPENAI_BASE_URL と OPENAI_API_KEY が引き続きフォールバックとして使用されます。その用途で使用中の場合は、安易に削除しないでください。）⁴

セッション中のカスタムエンドポイント切り替え：

/model custom:qwen-2.5             # Custom endpoint with explicit model
/model custom                      # Auto-detect the model from the endpoint
/model custom:local:qwen-2.5       # Named custom provider "local"
/model custom:work:llama3          # Named custom provider "work"
/model openrouter:claude-sonnet-4  # Back to a cloud provider

/model custom（モデル名を付けない形式）は、エンドポイントの /v1/models API を照会し、読み込まれているモデルが1つだけの場合は自動的に選択します。単一モデルを実行するローカルサーバーに便利です。²

ローカル LLM サーバー（セットアップテンプレート）

アップストリームのドキュメントには、Ollama、vLLM、SGLang、llama.cpp、LM Studio の完全なセットアップガイドがあります。ここでは、実際に使用する主要なコマンドを紹介します。いずれも、Hermes の接続先として指定できる、動作可能なエンドポイントを構築するためのものです。²

Ollama — 設定不要で最も簡単なローカル環境：

ollama pull qwen2.5-coder:32b
OLLAMA_CONTEXT_LENGTH=32768 ollama serve   # Raise from 4k default
hermes model   # Custom endpoint → http://localhost:11434/v1 → qwen2.5-coder:32b

Ollamaで特に注意すべき点： Ollama のデフォルトのコンテキスト長は非常に短く、VRAMが24GB未満の場合は4,096トークンです。OLLAMA_CONTEXT_LENGTH または Modelfile で引き上げる必要があります。OpenAI互換の API ではクライアントからコンテキスト長を指定できないため、Hermes 側からは設定できません。² エージェント用途では、少なくとも16k～32kに設定してください。

vLLM — 高性能な GPU サービング：

pip install vllm
vllm serve meta-llama/Llama-3.1-70B-Instruct \
  --port 8000 \
  --max-model-len 65536 \
  --tensor-parallel-size 2 \
  --enable-auto-tool-choice \
  --tool-call-parser hermes

ツール呼び出しには、--enable-auto-tool-choice と --tool-call-parser <name> が必要です。対応しているパーサーは、hermes（Qwen 2.5、Hermes 2/3）、llama3_json、mistral、deepseek_v3、deepseek_v31、xlam、pythonic です。これらのフラグがない場合、ツール呼び出しはプレーンテキストとして返されます。²

SGLang — KVキャッシュを再利用するRadixAttentionによる高速サービング：

pip install "sglang[all]"
python -m sglang.launch_server \
  --model meta-llama/Llama-3.1-70B-Instruct \
  --port 30000 \
  --context-length 65536 \
  --tp 2 \
  --tool-call-parser qwen

SGLangで注意すべき点： デフォルトの max_tokens は128です。応答が途中で切れる場合は、サーバー側で --default-max-tokens を設定するか、config.yaml で model.max_tokens を指定してください。²

llama.cpp / llama-server — CPUおよびApple Silicon Metal：

./build/bin/llama-server \
  --jinja -fa \
  -c 32768 \
  -ngl 99 \
  -m models/qwen2.5-coder-32b-instruct-Q4_K_M.gguf \
  --port 8080 --host 0.0.0.0

ツール呼び出しには --jinja が必須です。 これを指定しない場合、llama-server は tools パラメーターを完全に無視します。その結果、モデルは応答テキスト内に JSON を記述してツールを呼び出そうとしますが、Hermes はそれを実際のツール呼び出しとして解析できません。²

LM Studio — GUIを備えたデスクトップアプリ：

LM Studio アプリからサーバーを起動するには、Developerタブで「Start Server」を選択します。CLI を使用する場合は、lms server start（ポート1234で起動）と lms load qwen2.5-coder --context-length 32768 を実行します。² その後、hermes model の接続先を http://localhost:1234/v1 に設定してください。

LM Studioで特に注意すべき点： LM Studio はモデルのメタデータからコンテキスト長を読み取りますが、多くのGGUFモデルではデフォルト値が2048または4096と報告されます。LM Studio のモデル設定では、必ずコンテキスト長を明示的に指定してください。モデル選択画面の横にある歯車アイコンをクリックし、「Context Length」を少なくとも16384（できれば32768）に設定してから、モデルを再読み込みします。²

名前付きカスタムプロバイダー

複数のカスタムエンドポイント（たとえば、ローカル開発サーバーとリモートの GPU サーバー）を使用する場合は、config.yaml で名前付きカスタムプロバイダーとして定義します。²

custom_providers:
  - name: local
    base_url: http://localhost:8080/v1
    # api_key omitted — Hermes uses "no-key-required" for keyless local servers
  - name: work
    base_url: https://gpu-server.internal.corp/v1
    api_key: corp-api-key
    api_mode: chat_completions      # optional, auto-detected from URL
  - name: anthropic-proxy
    base_url: https://proxy.example.com/anthropic
    api_key: proxy-key
    api_mode: anthropic_messages    # for Anthropic-compatible proxies

その後、3要素構文を使用してセッション中に切り替えられます。

/model custom:local:qwen-2.5
/model custom:work:llama3-70b
/model custom:anthropic-proxy:claude-sonnet-4

対話式の hermes model メニューから名前付きカスタムプロバイダーを選択することもできます。²

プラグイン可能なプロバイダーアーキテクチャ（v0.13.0以降）

v0.13.0では、ProviderProfile ABC と plugins/model-providers/ ディレクトリが導入されました。これにより、コアを変更せずにサードパーティの推論プロバイダーを追加できます。¹⁸ OpenAI、Anthropic、Codex のいずれかと互換性のある API モードをプロバイダーが備えていれば、認証経路、ベースURL、モデルカタログ、キャッシュヘッダーを宣言する ProviderProfile サブクラスを実装できます。Hermes は組み込みプロバイダーと同じ runtime_provider.py 経路を介して解決します。これが、v0.13.0でプロバイダーを拡張できるようになった背景にあるアーキテクチャ変更です。プロバイダーを追加するためにコアコードを編集するのではなく、プラグインとして提供できます。

OpenAI互換ローカルプロキシ（v0.14.0以降）

hermes proxy は、Hermes がすでにサインインしている OAuth プロバイダー（Claude Pro、ChatGPT Pro、SuperGrok、または互換性のある別の設定済みプロバイダー）を基盤として、OpenAI互換のローカルエンドポイントを公開します。¹⁹ つまり、Codex CLI、Aider、Cline、Continue、カスタムスクリプトなど、OpenAI形式の API を必要とするツールで、別途 API キーを用意せずに、サブスクリプションに基づく Hermes の認証を再利用できます。このプロキシはローカルの開発者向けインフラストラクチャとして扱ってください。バインド先を慎重に指定し、広範囲に公開せず、プロバイダー固有の利用規約にも注意する必要があります。

コンテキスト長の検出

アップストリームのドキュメントによると、次の2つの設定は頻繁に混同されます。²

• context_length — コンテキストウィンドウ全体（入力と出力を合わせたトークン予算。たとえば Claude Opus 4.7では1,000,000、Sonnet 4.6では200,000）です。Hermes は履歴を圧縮するタイミングの判断に使用します。
• model.max_tokens — 出力上限（モデルが1回の応答で生成できる最大トークン数）です。履歴の長さとは無関係です。

自動検出でウィンドウサイズが正しく判定されない場合は、context_length を設定します。

model:
  default: "qwen3.5:9b"
  base_url: "http://localhost:8080/v1"
  context_length: 131072      # tokens

Hermes は複数の情報源を順番に参照して、コンテキストウィンドウを検出します。設定による上書き → カスタムプロバイダーのモデル別設定 → 永続キャッシュ → エンドポイントの /models → Anthropic の /v1/models → OpenRouter API → Nous Portal → models.dev（3800以上のモデルを収録するコミュニティ管理のレジストリ）→ フォールバックのデフォルト値（128K）の順です。² このシステムはプロバイダーを考慮するため、同じモデルでも提供元によってコンテキスト上限が異なる場合があります（たとえば、claude-opus-4.6 は Anthropic への直接接続では1Mですが、GitHub Copilot では128Kです）。²

プロバイダーのローテーションとフォールバック

認証情報プール。 同じプロバイダーに複数の API キーがある場合は、hermes auth でローテーション戦略を設定します。これにより、複数のキーにレート制限を分散できます。⁶

フォールバックモデル。 プライマリモデルで障害（レート制限、サーバーエラー、認証エラー）が発生した際、Hermes が自動的に切り替える予備の provider:model を設定します。²

fallback_model:
  provider: openrouter            # required
  model: anthropic/claude-sonnet-4  # required
  # base_url: http://localhost:8000/v1    # optional, for custom endpoints
  # api_key_env: MY_CUSTOM_KEY           # optional, env var name

フォールバックでは、会話を失うことなくセッション中にモデルとプロバイダーを切り替えます。実行されるのは1セッションにつき最大1回です。² フォールバックに対応するプロバイダーは、openrouter、nous、openai-codex、copilot、copilot-acp、anthropic、huggingface、zai、kimi-coding、minimax、minimax-cn、deepseek、ai-gateway、opencode-zen、opencode-go、kilocode、alibaba、custom です。²

補助モデル

Hermes は、画像解析、Webページの要約、ブラウザのスクリーンショット解析、危険なコマンドの承認分類、コンテキスト圧縮、セッション検索の要約、skill の照合、MCP ツールのディスパッチ、メモリのフラッシュといった副次的なタスクに、軽量な「補助」モデルを使用します。⁴ デフォルトでは、自動検出（OpenRouter → Nous → Codex）を介して Gemini Flash が使用されます。

補助タスクごとに、使用するモデルとプロバイダーを設定できます。 すべての補助スロットでは、provider、model、base_url という同じ3つの設定項目を使用します。⁴

auxiliary:
  vision:
    provider: "auto"                # "auto", "openrouter", "nous", "codex", "main", etc.
    model: ""                       # e.g. "openai/gpt-4o", "google/gemini-2.5-flash"
    base_url: ""                    # Custom OpenAI-compatible endpoint
    api_key: ""                     # Falls back to OPENAI_API_KEY
    timeout: 30
    download_timeout: 30
  web_extract:
    provider: "auto"
    model: ""
    timeout: 360
  approval:
    provider: "auto"
    model: ""
    timeout: 30
  compression:
    timeout: 120
  session_search: { provider: "auto", model: "", timeout: 30 }
  skills_hub:    { provider: "auto", model: "", timeout: 30 }
  mcp:           { provider: "auto", model: "", timeout: 30 }
  flush_memories:{ provider: "auto", model: "", timeout: 30 }

"main" プロバイダーオプションは、「メインエージェントと同じプロバイダーを使用する」という意味です。使用できるのは、auxiliary:、compression:、fallback_model: の設定内に限られます。トップレベルの model.provider 設定には使用できません。メインモデルとしてカスタムのOpenAI互換エンドポイントを使用する場合は、model: セクションで provider: custom を設定してください。⁴

これが重要な理由： Anthropic OAuth だけを設定し、OpenRouter キーを用意していない場合、デフォルトの補助フォールバックチェーンが最初に OpenRouter を試すため、画像認識、Web要約、圧縮の品質が低下したり、処理に失敗したりします。補助タスク用の OPENROUTER_API_KEY を追加するか、各補助スロットがメインプロバイダーを使用するように再設定してください。

auxiliary:
  vision:
    provider: "main"
  web_extract:
    provider: "main"

これは、Hermes を初めて使うユーザーが遭遇する「機能が何の通知もなく動かない」問題の中で、最もよくある落とし穴です。

設定システム

Hermes には階層型の設定システムがあります。上位の階層が下位の階層を上書きするため、優先順位の理解が欠かせません。また、そのうちの1つは config.yaml からは確認できないグローバルなプロバイダーレジストリです。

設定ファイルの構成

公式ドキュメントによると、Hermes の設定は次のファイルで構成されます。⁴

~/.hermes/
├── config.yaml       # All settings (model, terminal, TTS, compression, memory, toolsets, ...)
├── .env              # Secrets (API keys, bot tokens, passwords)
├── auth.json         # OAuth provider credentials (Nous Portal, Codex, Anthropic)
├── SOUL.md           # Primary agent identity (slot #1 in system prompt)
├── memories/         # Persistent memory (MEMORY.md, USER.md)
├── skills/           # Bundled + agent-created + hub-installed skills
├── cron/             # Scheduled jobs
├── sessions/         # Gateway session state
└── logs/             # agent.log, gateway.log, errors.log (secrets auto-redacted)

config.yaml と .env の両方に設定がある場合、機密情報以外の設定では config.yaml が優先されます。⁴ ルールは次のとおりです。 - 機密情報（API キー、ボットトークン、パスワード）→ .env - それ以外のすべて（モデル、ターミナルバックエンド、圧縮設定、メモリ上限、toolsets）→ config.yaml

シェル形式の変数展開を使うと、config.yaml から機密情報を参照できます。⁴

auxiliary:
  vision:
    api_key: ${GOOGLE_API_KEY}
    base_url: ${CUSTOM_VISION_URL}
  delegation:
    api_key: ${DELEGATION_KEY}

設定の管理

hermes config                # View current configuration
hermes config show           # Same as above
hermes config edit           # Open config.yaml in your editor
hermes config set KEY VAL    # Set a specific value
hermes config get KEY        # Print a single value (v0.19.0+)
hermes config unset KEY      # Remove a key so the default applies again (v0.19.0+)
hermes config path           # Print the config file path
hermes config env-path       # Print the .env file path
hermes config check          # Check for missing options (after updates)
hermes config migrate        # Interactively add missing options

例：⁴

hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...   # Saves to .env

hermes config check と hermes config migrate は、hermes update のたびに実行するコマンドです。まだ設定ファイルに含まれていない新しい設定項目を検出できます。⁶

設定の優先順位

Hermes は複数のソースから設定を読み込みます。複数のソースで同じ値が設定されている場合は、優先順位が最も高いソースが適用されます。⁴

1. CLI 引数 — hermes chat --model anthropic/claude-sonnet-4（実行ごとの上書き）
2. 環境変数 — プロセスの起動時に適用
3. config.yaml — メインの設定ファイル
4. .env — 機密情報のみ
5. 組み込みのデフォルト値 — ほかに値が設定されていない場合に適用

CLI フラグは、その1回の実行では常に最優先されます。長期的な信頼できる情報源は config.yaml です。

ローカライズ（v0.13.0以降）

v0.13.0では、CLI と gateway メッセージ向けに、中国語（簡体字）、日本語、ドイツ語、スペイン語、フランス語、ウクライナ語、トルコ語の7つのロケールが追加されました。¹⁸ v0.14.0では、すべての gateway コマンドとWebダッシュボードがローカライズされ、さらに8つのロケールが追加されて合計16となりました。¹⁹ 現在、ドキュメントのローカライズは zh-Hans のみに対応しています。ロケールは LC_ALL / LANG 環境変数、または config.yaml に明示した locale: キーから決定されます。英語が引き続きデフォルトであり、翻訳がまだ対応していない文字列については信頼できる情報源となります。

Profiles — 複数の独立した Hermes インスタンス

Profiles を使うと、設定、セッション、skills、メモリ、gateway PIDがそれぞれ独立した複数の Hermes インスタンスを利用できます。これにより、「仕事用の Hermes」と「個人用の Hermes」を、互いの状態が見えないようにしながら並行して実行できます。⁶

hermes profile list
hermes profile create work --clone                  # Clone from current profile
hermes profile use work                             # Set sticky default
hermes profile alias work --name h-work             # Create wrapper script
hermes profile export work -o work-backup.tar.gz
hermes profile import work-backup.tar.gz --name restored
hermes -p work chat -q "Hello from work profile"    # One-off without switching

各 profile には専用の HERMES_HOME（デフォルトでは ~/.hermes-<name>/）が割り当てられるため、複数の profiles で互いに干渉することなく gateway を同時に実行できます。⁶³

CLI コマンド

このセクションでは、実務者向けにトップレベルの CLI コマンドを解説します。コードに基づく正式なリファレンスについては、アップストリームの「CLI コマンドリファレンス」をご覧ください。⁶

グローバルオプション

hermes [global-options] <command> [subcommand/options]

トップレベルコマンド

hermes chat — メインエントリーポイント

引数なしで hermes を実行すると、対話形式のチャットが始まります。hermes chat は、オプションを指定できる明示的な形式です。⁶

hermes chat -q "Summarize the latest PRs"           # One-shot, non-interactive
hermes chat --provider openrouter --model anthropic/claude-sonnet-4.6
hermes chat --toolsets web,terminal,skills          # Enable specific toolsets
hermes chat --quiet -q "Return only JSON"           # Programmatic mode
hermes chat --worktree -q "Review repo and open a PR"

主なオプション：

hermes setup — 完全セットアップウィザード

完全なセットアップウィザードを実行するか、指定したセクションへ直接移動します。⁶

hermes setup                 # Full wizard
hermes setup model           # Provider and model only
hermes setup terminal        # Terminal backend only
hermes setup gateway         # Messaging platforms only
hermes setup tools           # Tool enable/disable per platform
hermes setup agent           # Agent behavior only
hermes setup --non-interactive
hermes setup --reset         # Reset config to defaults before setup

hermes logs — 構造化ログの照会

hermes logs では、レベル、セッション ID、時間範囲を同時に指定して絞り込めるため、ログファイルに対する tail -f よりも強力です。⁶

hermes logs                          # Last 50 lines of agent.log
hermes logs -f                       # Follow in real time
hermes logs gateway -n 100           # Last 100 lines of gateway.log
hermes logs --level WARNING --since 1h   # Warnings from the last hour
hermes logs --session abc123         # Filter by session ID substring
hermes logs errors --since 30m -f    # Follow errors.log from 30m ago
hermes logs list                     # List all log files with sizes

ログファイルは ~/.hermes/logs/ に保存されます。⁶ - agent.log — エージェントの全アクティビティ（API 呼び出し、ツールのディスパッチ、セッションのライフサイクル、INFO以上） - errors.log — 警告とエラーのみ（agent.log から抽出された一部） - gateway.log — メッセージング gateway のアクティビティ（プラットフォーム接続、ディスパッチ、webhook）

ローテーションは Python の RotatingFileHandler により自動的に行われます。agent.log.1、agent.log.2 などを確認してください。⁶

hermes doctor — 診断

問題が発生した場合、最初に実行するコマンドは hermes doctor [--fix] です。設定の妥当性、依存関係の有無、API キーの利用可否、サービスの状態を確認し、--fix を指定すると自動修復も試みます。⁶

診断情報をほかの人と共有する場合は、hermes dump を使用します。API キーがマスキングされた簡潔なプレーンテキスト形式の概要が生成され、GitHub の issue や Discord のスレッドへそのまま貼り付けられます。⁶

Slash Commands

Slash Commands は、アクティブなチャットセッション（CLI またはメッセージングプラットフォーム）内で実行します。hermes_cli/commands.py の共有 COMMAND_REGISTRY からディスパッチされるため、ほとんどのコマンドはどのインターフェースでも同じように動作します。⁹

セッションの操作

設定とモデル

セッションの途中でプロバイダーを切り替える際は、/model コマンドが中心的な役割を果たします。⁹

/model                              # Show current model and options
/model claude-sonnet-4              # Switch model (auto-detect provider)
/model zai:glm-5                    # Switch provider:model
/model custom:qwen-2.5              # Use model on custom endpoint
/model custom                       # Auto-detect model from custom endpoint
/model custom:local:qwen-2.5        # Named custom provider
/model openrouter:anthropic/claude-sonnet-4   # Back to cloud

v0.19.0 では /model --once が追加されました。1ターンだけモデルを上書きし、応答後に以前のモデルへ自動的に戻ります。²³

ツール、Skills、情報

動的な Skill Slash Commands

インストール済みの skill は、すべて自動的に Slash Command として公開されます。⁹

/gif-search funny cats
/axolotl help me fine-tune Llama 3 on my dataset
/github-pr-workflow create a PR for the auth refactor
/excalidraw       # Just the skill name loads it and lets the agent ask what you need

v0.19.0 以降、Slash Skill の呼び出しは重ねて指定できます。/skill-a /skill-b do XYZ のように入力すると、1回のターンで両方の skills が順番に読み込まれます。連結した名前のオートコンプリートとゴーストテキストにも対応しています。²³

config.yaml では、短い名前を長いプロンプトのエイリアスとして登録するクイックコマンドも定義できます。⁹

quick_commands:
  review: "Review my latest git diff and suggest improvements"
  deploy: "Run the deployment script at scripts/deploy.sh and verify the output"
  morning: "Check my calendar, unread emails, and summarize today's priorities"

その後、CLI で /review、/deploy、または /morning と入力します。

前方一致

コマンドは前方一致に対応しています。/h は /help、/mod は /model として解決されます。複数の候補に一致する場合は、レジストリへの登録順で最初のものが優先されます。完全なコマンド名と登録済みのエイリアスは、常に前方一致より優先されます。⁹

メッセージング固有のコマンド

一部のコマンドは、メッセージングプラットフォーム（Telegram、Discord、Slack、WhatsApp、Signal、Email、Home Assistant）でのみ動作します。⁹

• /status — セッション情報を表示します
• /sethome（エイリアス /set-home）— 現在のチャットをプラットフォームのホームとして設定します
• /approve [session|always] — 保留中の危険なコマンドを承認します
• /deny [reason] — 保留中の危険なコマンドを拒否します。v0.19.0 以降、/deny <reason> は拒否理由をエージェントへ伝えるため、状況を把握しないまま再試行するのではなく、方針を修正できるようになりました²³
• /update — Hermes Agent を最新バージョンに更新します
• /commands [page] — すべてのコマンドと skills をページ単位で閲覧します

また、/skin、/tools、/toolsets、/browser、/config、/cron、/skills、/platforms、/paste、/statusbar、/plugins は CLI 専用です。⁹

ツールと toolset

Hermes には、ウェブ検索、ブラウザ自動化、ターミナル実行、ファイル編集、メモリ、委任、RL トレーニング、メッセージ配信、Home Assistant 連携などを網羅する、幅広い組み込みツールレジストリが備わっています。¹⁰ ツールは論理的な toolset に整理されており、プラットフォームごとに有効または無効にできます。

主なカテゴリー

一般的な toolset 名には、web、terminal、file、browser、vision、image_gen、moa、skills、tts、todo、memory、session_search、cronjob、code_execution、delegation、clarify、homeassistant、rl があります。¹⁰

ツールの管理

hermes chat --toolsets "web,terminal"       # Use specific toolsets
hermes tools                                # Interactive per-platform tool config
hermes tools --summary                      # Print enabled-tools summary

セッション中に /tools disable <name> と /tools enable <name> を使ってツールの有効・無効を切り替えることもできます。変更後は、新しいツール構成を反映するためにセッションがリセットされます。⁹

ターミナルのバックエンド

ターミナルツールでは、6種類の環境でコマンドを実行できます。¹⁰

バックエンドは、hermes config set terminal.backend <name> または config.yaml で切り替えます。

terminal:
  backend: docker      # or: local, ssh, singularity, modal, daytona
  cwd: "."             # Working directory
  timeout: 180         # Command timeout in seconds

SSH バックエンド（セキュリティ上推奨 — エージェントが自身のコードを変更できません）：¹⁰

terminal:
  backend: ssh

# In ~/.hermes/.env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=myuser
TERMINAL_SSH_KEY=~/.ssh/id_rsa

Docker バックエンド：

terminal:
  backend: docker
  docker_image: python:3.11-slim

コンテナリソース（docker、singularity、modal、daytona に適用）：¹⁰

terminal:
  container_cpu: 1
  container_memory: 5120          # MB (default 5GB)
  container_disk: 51200           # MB (default 50GB)
  container_persistent: true      # Persist filesystem across sessions

container_persistent: true を設定すると、インストールしたパッケージ、ファイル、設定がセッションをまたいで保持されます。¹⁰

すべてのコンテナバックエンドには、セキュリティ強化策が適用されます。具体的には、読み取り専用のルートファイルシステム（Docker）、DAC_OVERRIDE、CHOWN、FOWNER を除くすべての Linux capability の削除、権限昇格の禁止、PID 制限（256プロセス）、完全な namespace 分離、volume による永続ワークスペースです。¹⁰

バックグラウンドプロセス

ターミナルツールでは、明示的なプロセス管理を伴うバックグラウンド実行をサポートしています。¹⁰

terminal(command="pytest -v tests/", background=true)
# Returns: {"session_id": "proc_abc123", "pid": 12345}

process(action="list")                            # Show all running processes
process(action="poll", session_id="proc_abc123")  # Check status
process(action="wait", session_id="proc_abc123")  # Block until done
process(action="log", session_id="proc_abc123")   # Full output
process(action="kill", session_id="proc_abc123")  # Terminate
process(action="write", session_id="proc_abc123", data="y")  # Send input

PTY モード（pty=true）を使用すると、Codex や Claude Code などの対話型 CLI ツールを利用できます。¹⁰

Sudo

コマンドに sudo が必要な場合、Hermes がパスワードの入力を求めます（セッション中はキャッシュされます）。または、~/.hermes/.env に SUDO_PASSWORD を設定してください。¹⁰

マルチエージェント Kanban（v0.13.0以降）

v0.13.0では、マルチエージェントの協調が第一級の基本機能になりました。導入されたのは、エージェント間および再起動後もタスク、ステータス、ワーカーの識別情報を追跡できる、永続的な Kanban ボードです。¹⁸ このボードにより、Hermes ワーカーの群れは、途絶えた引き継ぎで停止することなく、実際に作業を完了できるようになります。

Kanban ボードは、目標側では /goal（ターゲットを固定した Ralph ループ）と、生成処理では既存の delegate_task ツールと自然に連携します。その結果、次に何をすべきか、誰が担当しているか、どこで滞っているかについて、すべてのエージェントが単一の信頼できる情報源を共有する群れのパターンが実現します。

Skillsシステム

Skillsは、必要なときにエージェントが読み込めるオンデマンドの知識ドキュメントです。トークン使用量を最小限に抑えるため、段階的開示のパターンに従っており、agentskills.ioのオープン標準と互換性があります。¹¹

すべてのskillsは~/.hermes/skills/に保存されます。ここが主要ディレクトリであり、信頼できる唯一の情報源です。新規インストール時には、同梱のskillsがリポジトリからコピーされます。ハブからインストールしたskillsやエージェントが作成したskillsも、ここに保存されます。¹¹

段階的開示

Level 0: skills_list()           → [{name, description, category}, ...]   (~3k tokens)
Level 1: skill_view(name)        → Full content + metadata                 (varies)
Level 2: skill_view(name, path)  → Specific reference file                 (varies)

エージェントがskillの全内容を読み込むのは、実際に必要になったときだけです。¹¹

SKILL.mdの形式

---
name: my-skill
description: Brief description of what this skill does
version: 1.0.0
platforms: [macos, linux]      # Optional — restrict to OS platforms
metadata:
  hermes:
    tags: [python, automation]
    category: devops
    fallback_for_toolsets: [web]     # Conditional activation
    requires_toolsets: [terminal]    # Conditional activation
    config:                          # Config.yaml settings
      - key: my.setting
        description: "What this controls"
        default: "value"
        prompt: "Prompt for setup"
---

# Skill Title

## When to Use
Trigger conditions for this skill.

## Procedure
1. Step one
2. Step two

## Pitfalls
- Known failure modes and fixes

## Verification
How to confirm it worked.

条件付き有効化

利用可能なツールに応じて、skillsを表示または非表示にできます。これは特に、プレミアムツールを利用できない場合にだけ表示する無料またはローカルの代替手段であるフォールバックskillsに役立ちます。¹¹

例： 組み込みのduckduckgo-search skillでは、fallback_for_toolsets: [web]を使用しています。FIRECRAWL_API_KEYが設定されている場合はweb toolsetが利用可能になるため、エージェントはweb_searchを使用し、DuckDuckGo skillは非表示のままとなります。APIキーがない場合は、DuckDuckGo skillがフォールバックとして自動的に表示されます。¹¹

エージェント管理のSkills

エージェントはskill_manageツールを介して、自身のskillsを作成、更新、削除できます。これはエージェントの手続き記憶にあたります。複雑なワークフローを解明すると、その手順をskillとして保存し、今後再利用できるようにします。¹¹

エージェントがskillsを作成するタイミング：¹¹ - 複雑なタスク（ツール呼び出しが5回以上）を正常に完了した後 - エラーや行き詰まりを経験し、実際に機能する手順を見つけたとき - ユーザーからアプローチを修正されたとき - 複雑なワークフローを発見したとき

アクション：¹¹

Skillハブ

オンラインレジストリからskillsを閲覧、検索、インストール、管理できます。⁶¹¹

hermes skills browse                          # Browse all hub skills
hermes skills browse --source official        # Browse official optional skills
hermes skills search kubernetes               # Search all sources
hermes skills search react --source skills-sh # Search skills.sh directory
hermes skills inspect openai/skills/k8s       # Preview before installing
hermes skills install openai/skills/k8s       # Install with security scan
hermes skills install skills-sh/anthropics/skills/pdf --force
hermes skills check                           # Check for upstream updates
hermes skills update                          # Reinstall changed hub skills
hermes skills audit                           # Re-scan installed hub skills
hermes skills uninstall k8s
hermes skills publish skills/my-skill --to github --repo owner/repo
hermes skills tap add myorg/skills-repo       # Add custom GitHub source

統合されたハブソース：¹¹

デフォルトのGitHub taps（設定なしで閲覧可能）：openai/skills、anthropics/skills、VoltAgent/awesome-agent-skills、garrytan/gstack。¹¹

セキュリティスキャン

ハブからインストールされたすべてのskillsは、データ流出、プロンプトインジェクション、破壊的なコマンド、サプライチェーンの兆候、その他の脅威を検査するセキュリティスキャナーを通過します。¹¹

信頼レベル：¹¹

コミュニティskillsに対する危険ではないポリシーブロックは、--forceで上書きできます。ただし、dangerousというスキャン判定は上書きできません。¹¹

外部Skillディレクトリ

ローカルディレクトリと並行してスキャンする追加のskillディレクトリをHermesに指定できます。¹¹

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills
    - ${SKILLS_REPO}/skills

パスでは~の展開と${VAR}環境変数の置換に対応しています。外部ディレクトリは読み取り専用です。エージェントがskillを作成または編集するときは、必ず~/.hermes/skills/に書き込みます。両方の場所に同名のskillが存在する場合は、ローカルが優先されます。¹¹

永続メモリ

Hermesには、セッションをまたいで保持される、容量制限付きの厳選されたメモリがあります。エージェントのメモリは2つのファイルで構成され、どちらも~/.hermes/memories/に保存されます。¹²

どちらも、セッション開始時に固定されたスナップショットとしてシステムプロンプトに挿入されます。エージェントはmemoryツールのadd、replace、removeを使って、自身のメモリを管理します。¹²

固定スナップショットパターン： システムプロンプトへの挿入内容はセッション開始時に一度だけ取得され、セッション中には変更されません。これは意図的な設計であり、パフォーマンス向上のためにLLMのプレフィックスキャッシュを維持します。セッション中に加えた変更は直ちにディスクへ保存されますが、次のセッションまではシステムプロンプトに反映されません。¹²

保存する内容

保存するもの（エージェントが能動的に行います）：¹² - ユーザーの好み： 「JavaScriptよりTypeScriptを使いたい」→ user - 環境情報： 「このサーバーではDebian 12とPostgreSQL 16が稼働している」→ memory - 訂正事項： 「Dockerコマンドではsudoを使わない。ユーザーはdockerグループに所属している」→ memory - 規約： 「プロジェクトではタブ、1行120文字、Googleスタイルのdocstringを使用する」→ memory - 完了した作業： 「2026年1月15日にデータベースをMySQLからPostgreSQLへ移行した」→ memory

保存しないもの：¹² - 些細または自明な情報 - 簡単に再確認できる事実 - 生データのダンプ（メモリには大きすぎます） - そのセッション限りの一時的な情報 - コンテキストファイルにすでに含まれている情報

セッション検索

MEMORY.mdとUSER.mdに加えて、エージェントはsession_searchツールを使って過去の会話を検索できます。すべてのCLIセッションとメッセージングセッションは、FTS5全文検索に対応したSQLite（~/.hermes/state.db）に保存されます。クエリを実行すると、関連する過去の会話がGemini Flashによる要約付きで返されます。¹²

外部メモリプロバイダー

MEMORY.mdとUSER.mdを超える高度な永続メモリ向けに、HermesにはHoncho、OpenViking、Mem0、Hindsight、Holographic、RetainDB、ByteRover、Supermemoryという8つの外部メモリプロバイダープラグインが付属しています。¹²

外部プロバイダーは組み込みメモリを置き換えるのではなく、組み込みメモリと並行して動作します。ナレッジグラフ、セマンティック検索、事実の自動抽出、セッションをまたいだユーザーモデリングなどの機能を追加できます。⁶¹²

hermes memory setup         # Pick a provider and configure it
hermes memory status        # Check what's active
hermes memory off           # Disable external provider (built-in only)

一度に有効にできる外部プロバイダーは1つだけです。組み込みメモリは常に有効です。⁶

セッションの自動再開（v0.13.0以降）

v0.13.0では、エージェントの処理が途中で中断されても復帰できるようになりました。gatewayは再起動後に中断されたセッションを自動再開します。/updateによる再起動ではアップグレード後もセッション状態が維持され、開発中にソースファイルが再読み込みされても、新しいセッションを強制せずアクティブなセッションを保ちます。¹⁸ 実用上、長時間実行されるgatewayの処理やcron駆動のジョブは、プロセスが再起動してもコンテキストウィンドウをリセットしなくなります。

Checkpoints v2（v0.13.0以降）

v0.13.0では、状態の永続化が、実際に機能するプルーニング、ディスク保護、孤立したシャドウリポジトリの排除を備えた単一ストア設計へ刷新されました。¹⁸ 以前のcheckpointシステムでは、長時間稼働するprofileでディスク上に状態が蓄積していました。v2ストアでは、ローカルのcheckpointストレージに厳格な上限を設け、その増加を招いていた重複管理を取り除いています。ユーザー側で設定を変更する必要はなく、次回のcheckpoint書き込みからv2のパスが使用されます。

パーソナリティとSOUL.md

SOUL.mdは、Hermesインスタンスの中核となるアイデンティティです。システムプロンプトのスロット#1を占め、ハードコードされたデフォルトのアイデンティティを置き換えます。¹³

Hermesは、デフォルトのSOUL.mdを~/.hermes/SOUL.md（カスタムprofileでは$HERMES_HOME/SOUL.md）に自動作成します。既存のユーザーファイルが上書きされることはありません。HermesがSOUL.mdを読み込む場所はHERMES_HOMEだけであり、現在の作業ディレクトリは検索しません。これにより、プロジェクトが変わっても一貫したパーソナリティを保てます。¹³

SOUL.mdに記述する内容

長期的に維持したい話し方やパーソナリティの指針に使用します。¹³ - トーン - コミュニケーションスタイル - 率直さの度合い - デフォルトの対話スタイル - 文体上避けるべきこと - 不確実性、意見の相違、曖昧さへのHermesの対応方法

次の用途にはあまり適していません：¹³ - 単発のプロジェクト指示 - ファイルパス - リポジトリの規約 - 一時的なワークフローの詳細

これらはSOUL.mdではなく、AGENTS.mdに記述します。

SOUL.mdとAGENTS.mdの違い

これはHermesのアイデンティティ管理において最も重要な違いです。¹³

SOUL.md — アイデンティティ、トーン、スタイル、デフォルトのコミュニケーション方針、パーソナリティに関する振る舞い。

AGENTS.md — プロジェクトのアーキテクチャ、コーディング規約、ツールの好み、リポジトリ固有のワークフロー、コマンド、ポート、パス、デプロイに関する注記。

覚えやすい基準として、どこへでも引き継ぎたいものはSOUL.mdに、特定のプロジェクトに属するものはAGENTS.mdに記述しましょう。¹³

組み込みパーソナリティ

Hermesには、/personalityで切り替えられる組み込みパーソナリティが付属しています。¹³

config.yamlでのカスタムパーソナリティ：¹³

agent:
  personalities:
    codereviewer: >
      You are a meticulous code reviewer. Identify bugs, security issues,
      performance concerns, and unclear design choices. Be precise and constructive.

その後、/personality codereviewerで切り替えます。

SOUL.mdと/personalityの違い

SOUL.mdは基本となる話し方です。/personalityはセッション単位で重ねるオーバーレイです。¹³ 実用的なデフォルト設定をSOUL.mdに記述し、個別指導の会話では/personality teacher、ブレインストーミングでは/personality creativeを使いましょう。

Nous Tool Gateway（v0.10.0以降）

Hermes Agent v0.10.0（2026年4月16日）以降、有料の Nous Portalサブスクライバーは、既存のPortal認証情報を使って、厳選された一連のツールにマネージドアクセスできるようになりました。管理するAPIキーを追加する必要はありません。²⁸ Hermes CLI自体は、引き続きMITライセンスの完全なオープンソースです。変更されたのは、Portal認証によってモデル推論以外の機能も利用できるようになった点です。

gatewayに含まれるもの

仕組み

gatewayは、新しいuse_gateway設定フィールドを使ってツールごとにオプトインします。hermes authにPortal認証情報があり、かつ対象ツールでgatewayを有効にすると、そのツールの呼び出しはPortal経由でルーティングされます。それ以外の場合は、直接設定したAPIキー（存在する場合）が使用されます。

# config.yaml — per-tool gateway opt-in
tools:
  web_search:
    provider: firecrawl
    use_gateway: true          # route via Nous Portal subscription
  image_generation:
    provider: fal
    use_gateway: true

実行時の優先順位： gatewayが利用可能で、ツールにuse_gateway: trueが設定されている場合、直接のAPIキーも設定されていても、Hermesはgatewayを優先します。これは課金に関わる重要な点です。gateway経由の呼び出しでは、直接設定したAPIキーの残高ではなく、Portalサブスクリプションの利用枠が消費されます。

gatewayの有効化

hermes model                      # select Nous Portal (OAuth flow)
hermes tools                      # per-platform tool picker integrates gateway tools
hermes status                     # confirms gateway/subscription detection

サブスクリプションは、hermes authにすでに登録されているPortal OAuth認証情報から自動的に検出されるため、別途ログインする必要はありません。v0.19.0以降は、セッション内からサブスクリプション自体も管理できます。/subscriptionではプランと残りの利用枠を確認でき、アップグレードにかかる正確な費用やダウングレードの適用時期を事前に表示します。さらに、変更予定のバナー表示や取り消し機能付きで変更を適用できます。/topupではクレジットを追加できます。デスクトップアプリにも同等の課金設定タブがあります。²³

料金とアクセス

料金とティア名は、Nous Portalの料金ページ（https://portal.nousresearch.com/pricing）で公開されています。このガイドではティアを列挙しません。ティアはHermes CLIではなくPortal製品側で管理されており、Hermesのリリースとは独立して変更されるためです。https://portal.nousresearch.com/で登録し、現在のティアについては料金ページをご確認ください。

非推奨化に関する注意

• HERMES_ENABLE_NOUS_MANAGED_TOOLS環境変数はv0.10.0で削除されました。マネージドツールはツールごとのuse_gateway設定フィールドで有効化し、Portalサブスクリプションの状態に応じて利用可否が決まります。²⁸

位置づけ：このリリースが意味しないこと

Hermes Agent CLIは、サブスクリプションに加入しなければ使えないものではありません。プロジェクトは引き続きMITライセンスで提供され、すべてのコア機能（CLI、skills、メモリ、messaging gateway、cron、MCP、ローカルダッシュボード、全プロバイダー向けのBYOK）は、料金を支払わなくてもエンドツーエンドで動作します。v0.10.0で追加されたのは、すでにNous Portalを有料利用しているユーザー向けの便利な経路です。無料で使える経路から何かが削除されたわけではありません。

Messaging Gateway

Hermesは、単一のgatewayプロセスから22のメッセージングプラットフォームに接続する常駐gatewayプロセスとして実行できます。対応するのは、Telegram、Discord、Slack、WhatsApp、Signal、SMS、Email、Home Assistant、Mattermost、Matrix、DingTalk、Feishu/Lark、WeCom、Weixin（WeChat）、BlueBubbles（iMessage）、QQBot、Microsoft Teams、Tencent Yuanbao、Google Chat、LINE、SimpleX Chat、および汎用Webhookアダプターです。^327171819 v0.9.0では、BlueBubbles経由のiMessage（Webhookの自動登録、セットアップウィザード、クラッシュ耐性）と、iLink Bot APIによるネイティブWeChat対応が追加され、エンタープライズアプリ向けのWeComコールバックモードも導入されました。¹⁶ v0.11.0ではQQBotが追加されました。²⁷ v0.12.0ではMicrosoft TeamsとTencent Yuanbaoが追加されました。¹⁷ v0.13.0では、20番目のプラットフォームとしてGoogle Chatが追加されました。同じプラグイン可能なアダプターアーキテクチャを採用しており、IRCとMicrosoft Teamsも、汎用のenv_enablement_fn / cron_deliver_env_varプラグインフックを備えた新しいアダプターパターンへ移行しました。¹⁸ v0.14.0ではLINEとSimpleX Chatが追加され、Graph認証、Webhookリスナー、パイプラインランタイム、送信処理を含むMicrosoft Teamsスタックもエンドツーエンドで完成しました。¹⁹ v0.17.0（2026年6月19日）では、Photon Spectrumによるリレー不要のiMessageが追加されました（hermes photon loginによるデバイスコードOAuthを使用し、MacやBlueBubblesのリレーは不要です）。さらに、公式のWhatsApp Business Cloud APIアダプター（ブリッジプロセス要件を置き換え）、SimpleXのグループとネイティブ添付ファイル、バンドル済みプラットフォームプラグインとしてのRaftも追加されました。²¹

セットアップ

hermes gateway setup                # Interactive platform configuration
hermes gateway install              # Install as user service (systemd/launchd)
hermes gateway start                # Start the installed service
hermes gateway stop
hermes gateway restart
hermes gateway status
hermes gateway run                  # Run in foreground (debugging)

対話形式のセットアップでは、APIトークン、bot ID、チャンネルマッピング、許可リストなど、各プラットフォームへの接続手順が案内されます。⁶

メッセージの流れ

上流のアーキテクチャドキュメントによると、次のように処理されます。³

Platform event → Adapter.on_message() → MessageEvent
  → GatewayRunner._handle_message()
    → authorize user
    → resolve session key
    → create AIAgent with session history
    → AIAgent.run_conversation()
    → deliver response back through adapter

すべてのメッセージングプラットフォームは、CLIと同じAIAgent会話ループを通じて実行されます。 そのため、どちらでもスラッシュコマンドが同じように機能し、Telegramでスケジュールしたcronジョブの出力をDiscordへ配信できます。プラットフォームによる違いは、処理経路の末端部分にしかありません。³

v0.19.0では、profileベースのメッセージルーティングと永続的な配信が追加されました。 1つのbotトークンを共有する単一の多重化gatewayで、特定のギルド、チャンネル、スレッドを異なるprofilesへルーティングできます。各profileの設定、skills、メモリ、シークレットは完全に分離され、GATEWAY_MULTIPLEX_PROFILESによるオーバーライドにも対応します。また、一連の堅牢化により、1つのprofileの設定ミスでgateway全体が停止することはなくなりました。内部では、ルーティングインデックスがstate.dbへ移行し（sessions.jsonは現在、任意のレガシーミラーです）、最終応答はプラットフォームへの送信前後に、永続的な配信義務台帳へ記録されます。完成した応答の送信時にgatewayがクラッシュしても、黙って失われることなく、次回起動時に再配信されます。²³

ユーザー認証とペアリング

hermes pairing list                    # Show pending and approved users
hermes pairing approve <platform> <code>
hermes pairing revoke <platform> <user-id>
hermes pairing clear-pending

ペアリングコードにより、見知らぬ第三者がgatewayと勝手に会話するのを防げます。ユーザーがメッセージングプラットフォームからペアリングコードを送信し、管理者がhermes pairing approveで承認します。それ以降、そのユーザーは認証済みとなります。⁶

スケジュールタスク（Cron）

Hermesには、ジョブをシェルコマンドではなくエージェントタスクとして扱う、本格的なcronシステムがあります。各スケジュールジョブは、設定されたプロンプトと任意で添付されたskillsを使用して、新しいAIAgent上で実行され、結果を任意のプラットフォームへ配信します。³⁶

hermes cron list
hermes cron create --prompt "Check HN for AI news and summarize" --schedule "0 9 * * *" --deliver telegram
hermes cron edit <id>
hermes cron pause <id>
hermes cron resume <id>
hermes cron run <id>         # Trigger now on the next tick
hermes cron remove <id>
hermes cron status           # Check if scheduler is running
hermes cron tick             # Run due jobs once and exit

メッセージングチャット内で会話形式により作成することもできます。

Every morning at 9am, check Hacker News for AI news and send me a summary on Telegram.

エージェントは自身のツールを使ってcronジョブを設定します。ジョブはJSONに永続化され、再起動後も保持されます。³

MCP連携

Hermesは、クライアントとサーバーの両方としてModel Context Protocolをサポートしています。⁶

クライアントとして — Hermesを外部のMCPサーバーに接続し、利用できるツールを拡張します。

hermes mcp add <name> --url https://example.com/mcp
hermes mcp add <name> --command npx --args "-y,@modelcontextprotocol/server-github"
hermes mcp list
hermes mcp test <name>
hermes mcp remove <name>
hermes mcp configure <name>   # Toggle individual tool selection

または、config.yamlで手動設定します。¹⁴

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

v0.19.0以降、MCPツールはmcp__server__tool命名規則に従ってモデルへ公開されます。すべてのツール名にサーバー名が含まれるため、2つのサーバーが同名のツールを公開しても競合しません。また、MCPサーバーのログ通知はagent.logに出力されます。²³

サーバーとして — Hermesの会話を他のエージェントへ公開します。

hermes mcp serve
hermes mcp serve -v    # Verbose

Context Compression

Hermes は、モデルのコンテキストウィンドウ内に収まるよう、長い会話を自動的に圧縮します。圧縮用の要約処理は独立した LLM 呼び出しであり、任意のプロバイダーやエンドポイントを指定できます。⁴

compression:
  enabled: true
  threshold: 0.50                           # Compress at this % of context limit
  target_ratio: 0.20                        # Fraction to preserve as recent tail
  protect_last_n: 20                        # Min recent messages to keep uncompressed
  summary_model: "google/gemini-3-flash-preview"
  summary_provider: "auto"                  # "auto", "openrouter", "nous", "codex", "main", etc.
  summary_base_url: null                    # Custom OpenAI-compatible endpoint

プロバイダーのオプション：⁴

summary_model は、圧縮時に会話の中間部分全体を受け取るため、メインモデルと同等以上のコンテキスト長に対応している必要があります。⁴

バジェット逼迫時の警告

多数のツール呼び出しを伴う複雑なタスクでは、エージェントが気づかないうちにイテレーションのバジェット（デフォルト：90ターン）を使い切ることがあります。バジェットが逼迫すると、モデルに次の警告が自動表示されます。⁴

ストリームのタイムアウト

LLM のストリーミング接続には2層のタイムアウトがあり、ローカルプロバイダー（localhost、LAN IP）に合わせて自動調整されます。⁴

ローカルの LLM では、大きなコンテキストのプリフィルに数分かかり、最初のトークンが生成されるまで待つことがあるため、ローカルエンドポイントのソケット読み取りタイムアウトは30分に延長されます。⁴

ローカルWebダッシュボード（v0.9.0以降）

Hermes Agent をローカルで管理するためのブラウザベースのダッシュボードです。設定の構成、セッションの監視、skill の閲覧、gateway の管理を、設定ファイルやターミナルに触れることなく行えます。¹⁶ hermes dashboard で起動します。GUIを好む新規ユーザーにとって、最も簡単な導入方法です。

バックグラウンドプロセスの監視（v0.9.0以降）

watch_patterns を使用すると、バックグラウンドプロセスの出力を監視するパターンを設定し、一致した際にリアルタイムで通知を受け取れます。¹⁶ エラーの監視、特定のイベント（「ポートでリッスン中」など）の待機、ビルドログの確認を、ポーリングなしで行えます。バックグラウンドタスクの完了を通知するv0.8.0の notify_on_complete と組み合わせることで、Hermes はバックグラウンドプロセスを包括的に可観測化できるようになりました。¹⁵

プラグイン可能な context engine（v0.9.0以降）

コンテキスト管理は、hermes plugins を通じて差し替え可能なスロットになりました。エージェントが各ターンで参照する内容を制御するカスタム context engine に切り替え、フィルタリング、要約、ドメイン固有のコンテキスト注入を行えます。¹⁶ これにより、コンテキスト戦略がエージェントのコアループから分離され、プロジェクトやドメインごとにカスタマイズできます。

バックアップと復元（v0.9.0以降）

hermes backup は、設定、セッション、skills、メモリを含む完全なアーカイブを作成します。hermes import は、バックアップアーカイブから復元します。¹⁶ マシン間の移行、大きな変更を行う前のスナップショット作成、検証済みの設定をチームメンバーと共有する場合に利用できます。

Termux / Androidのサポート（v0.9.0以降）

Hermes はTermuxを介してAndroid上でネイティブに動作します。Android向けに調整されたインストールパス、モバイル画面向けのTUI最適化、音声バックエンドのサポート、/image コマンドを端末上で利用できます。¹⁶

セキュリティ強化（v0.13.0以降）

v0.13.0では8件のP0セキュリティ問題が解消され、1つのデフォルト設定がユーザーに有利な方向へ変更されました。¹⁸ 続くv0.14.0では、さらに12件のP0と50件のP1が解消されています。これには、sudoの総当たり攻撃およびsudo-stdinへの対策、危険なコマンドを回避できる問題の修正、モデルへ再注入する前のツールエラーのサニタイズ、ダッシュボードプラグインの API 認証、skillsハブのSSRF対策、インストール時のサプライチェーンアドバイザリースキャンが含まれます。¹⁹

Hermes環境を運用している場合、v0.13.0とv0.14.0は単なる機能追加ではなく、セキュリティ上重要なアップグレードとして扱ってください。v0.13.0ではDiscordのguild間バイパスと2つのTOCTOUウィンドウが解消され、v0.14.0ではsudoの処理、ツールエラーの再注入、プラグインの API、skillsハブのSSRF、依存関係のアドバイザリーに対して、さらなるセキュリティ強化が施されています。

実務者向けアーキテクチャ

このセクションは、内部で何が起きているのかを理解し、デバッグや拡張、パフォーマンスの検討に役立てたい方を対象としています。上流のアーキテクチャドキュメントをまとめたものです。³

エントリーポイント → AIAgent

Hermes のすべてのエントリーポイントは、最終的に AIAgent.run_conversation() を呼び出します。

┌──────────────────────────────────────────────────────────────────┐
│                        Entry Points                              │
│                                                                  │
│  CLI (cli.py)    Gateway (gateway/run.py)    ACP (acp_adapter/)  │
│  Batch Runner    API Server                  Python Library     │
└──────────┬──────────────┬───────────────────────┬────────────────┘
           │              │                       │
           ▼              ▼                       ▼
┌──────────────────────────────────────────────────────────────────┐
│                     AIAgent (run_agent.py)                       │
│                                                                  │
│  ┌─────────────┐  ┌──────────────┐  ┌──────────────┐             │
│  │ Prompt      │  │ Provider     │  │ Tool         │             │
│  │ Builder     │  │ Resolution   │  │ Dispatch     │             │
│  └──────┬──────┘  └──────┬───────┘  └──────┬───────┘             │
│         │                │                 │                    │
│  ┌──────┴───────┐ ┌──────┴───────┐  ┌──────┴───────┐             │
│  │ Compression  │ │ 3 API Modes  │  │ Tool Registry│             │
│  │ & Caching    │ │ chat_compl   │  │ 47 tools     │             │
│  │              │ │ codex_resp   │  │ 20 toolsets  │             │
│  │              │ │ anthropic    │  │              │             │
│  └──────────────┘ └──────────────┘  └──────────────┘             │
└──────────────────────────────────────────────────────────────────┘

上流のアーキテクチャドキュメントを基にした図です。³

バナーに表示される「28 tools」に対して、「47 tools / 20 toolsets」とは何を意味するのでしょうか。「47 tools」は、上流リポジトリのツールレジストリ全体の総数です。つまり、すべての toolset にわたって、Hermes にソースコードが同梱されている全ツールを数えたものです。実際に実行中の CLI では、起動バナーにそれより少ない数が表示されます（このガイドの検証に使用した環境では 28 tools / 89 skills と表示されます）。これはバグではありません。多くの toolset はオプトイン形式であり、メッセージングプラットフォームのアダプター、ブラウザ自動化、高負荷のスクレイピングツールなどを利用するには、config.yaml の toolsets: で明示的に有効化する必要があります。レジストリの総数は「利用可能なもの」、バナーの数は「現在の profile で有効なもの」を表します。有効な toolset は hermes tools --list で確認できます。個々の toolset を有効または無効にするには、~/.hermes/config.yaml の toolsets: ブロックを使用してください（実行中のセッション内では /tools list、/tools enable <name>、/tools disable <name> も使用できます。ツールを削除するとセッションがリセットされ、エージェントがツールマニフェストを再構築します）。

3つの API モード

Hermes はプロバイダーごとの差異を3つの API モードに抽象化し、実行時に自動で選択します。³

runtime_provider.py のリゾルバーは、18以上のプロバイダーについて (provider, model) の組み合わせを (api_mode, api_key, base_url) にマッピングし、OAuth フロー、認証情報プール、エイリアス解決を処理します。³

CLI セッション内のデータフロー

User input → HermesCLI.process_input()
  → AIAgent.run_conversation()
    → prompt_builder.build_system_prompt()
    → runtime_provider.resolve_runtime_provider()
    → API call (chat_completions / codex_responses / anthropic_messages)
    → tool_calls? → model_tools.handle_function_call() → loop
    → final response → display → save to SessionDB

上流のアーキテクチャページからの図です。³

プロンプトの構築順序

プロンプトスタックには、次の要素が含まれます。¹³

1. SOUL.md（エージェントのアイデンティティ。利用できない場合は組み込みのフォールバックを使用）
2. ツールを考慮した動作ガイダンス
3. メモリおよびユーザーコンテキスト（MEMORY.md、USER.md）
4. skills のガイダンス
5. コンテキストファイル（AGENTS.md、.cursorrules）
6. タイムスタンプ
7. プラットフォーム固有の書式設定ヒント
8. /personality など、任意のシステムプロンプトオーバーレイ

基盤となるのは SOUL.md であり、それ以外のすべての要素はこの上に積み重なります。¹³

セッションストレージ

セッションストレージは SQLite ベースで、FTS5 全文検索に対応しています。セッションには系譜追跡（圧縮をまたぐ親子関係）、プラットフォームごとの分離、競合処理を備えたアトミック書き込みがあります。³

プラグインシステム

検出元は、~/.hermes/plugins/（ユーザー）、.hermes/plugins/（プロジェクト）、pip エントリーポイントの3つです。プラグインは、コンテキスト API を通じてツール、フック、CLI コマンドを登録します。メモリプロバイダーは、plugins/memory/ 配下にある特殊なプラグイン形式です。³

hermes plugins                       # Interactive enable/disable UI
hermes plugins install <repo>        # Install from Git URL or owner/repo
hermes plugins enable <name>
hermes plugins disable <name>
hermes plugins list

デザイン原則

上流のアーキテクチャページでは、次のように説明されています。³

OpenClaw からの移行

Hermes Agent は OpenClaw の後継です。既存の OpenClaw 環境から移行する場合は、次のコマンドを使用します。⁶⁵

hermes claw migrate --dry-run                    # Preview what would be migrated
hermes claw migrate --preset full                # Full migration including API keys
hermes claw migrate --preset user-data --overwrite   # User data only, no secrets
hermes claw migrate --source /custom/path        # Non-default OpenClaw location

hermes claw migrate は、デフォルトで ~/.openclaw から読み込み（従来の ~/.clawdbot および ~/.moldbot ディレクトリも自動検出します）、~/.hermes に書き込みます。⁶

直接インポートされる項目（30以上のカテゴリー）：SOUL.md、MEMORY.md、USER.md、AGENTS.md、4つのソースディレクトリにある skills、デフォルトモデル、カスタムプロバイダー、MCP サーバー、メッセージングプラットフォームのトークンと許可リスト（Telegram、Discord、Slack、WhatsApp、Signal、Matrix、Mattermost）、エージェントのデフォルト設定（推論強度、圧縮、対人応答の遅延、タイムゾーン、サンドボックス）、セッションのリセットポリシー、承認ルール、TTS 設定、ブラウザ設定、ツール設定、実行タイムアウト、コマンド許可リスト、gateway 設定、および3つのソースにある API キーです。⁶

手動確認用にアーカイブされる項目： cron ジョブ、プラグイン、フック／Webhook、メモリバックエンド（QMD）、skills レジストリ設定、UI／アイデンティティ、ログ、マルチエージェント構成、チャンネルバインディング、IDENTITY.md、TOOLS.md、HEARTBEAT.md、BOOTSTRAP.md。⁶

API キーは、設定値 → ~/.openclaw/.env → auth-profiles.json の優先順で、3つのソースを確認して解決されます。⁶

トラブルシューティング

「推論プロバイダーが設定されていません。hermes model を実行してプロバイダーとモデルを選択してください」

新規インストールで最初に遭遇するエラーです。Hermes では、使用するプロバイダーがまだ確定していません。つまり、3つの認証方法のいずれからも利用可能なプロバイダーを取得できていないということです。次を実行してください。

hermes model

対話形式の選択画面では、Nous Portal、GitHub Copilot、Anthropic、OpenAI Codex の OAuth デバイスコードフローや、セルフホスト型サーバー用のカスタムエンドポイントなど、サポートされているすべてのプロバイダーを順に設定できます。すでにプロバイダーが設定されているはずの場合は、hermes doctor を実行すると、Hermes が実際に認識できている認証情報を確認できます。よくある原因は、API キーの設定場所が間違っていること（シェルプロファイルではなく、.env または hermes config set で設定します）、~/.hermes/auth.json 内の OAuth 認証情報が期限切れになっていること、あるいは config.yaml のカスタムエンドポイントから base_url が欠落していることです。認証方法については、認証とプロバイダーで詳しく説明しています。²⁷

「API キーが設定されていません」

hermes model を実行して対話形式でプロバイダーを設定するか、hermes config set OPENROUTER_API_KEY your_key を実行してください。hermes doctor コマンドを使えば、不足しているキーを正確に確認できます。⁷

起動時に「コンテキスト上限：2048トークン」と表示される（ローカルモデル）

Hermes はサーバーの /v1/models エンドポイントからコンテキスト長を自動検出しますが、多くのローカルサーバーは低いデフォルト値を返します。config.yaml で明示的に設定してください。²

model:
  default: your-model
  provider: custom
  base_url: http://localhost:11434/v1
  context_length: 32768

ツール呼び出しが実行されず、テキストとして表示される

サーバーでツール呼び出しが有効になっていないか、サーバー側の実装を通じたツール呼び出しにモデルが対応していません。²

応答が文の途中で途切れる

原因は次の2つが考えられます。²

1. サーバー側の出力上限（max_tokens）が低い — SGLang のデフォルトは応答ごとに128トークンです。サーバーで --default-max-tokens を設定するか、config.yaml の model.max_tokens を設定してください。
2. コンテキストの枯渇 — モデルがコンテキストウィンドウを使い切っています。model.context_length を増やすか、Hermes のコンテキスト圧縮を有効にしてください。

WSL2 から Windows 上のモデルサーバーに接続すると「接続が拒否されました」と表示される

WSL2 は独自のサブネットを持つ仮想ネットワークアダプターを使用します。そのため、WSL2 内の localhost は Windows ホストではなく Linux VM を指します。対処方法は2つあります。²

ミラーリングネットワーク（Windows 11 22H2以降）：%USERPROFILE%\.wslconfig を編集します。

[wsl2]
networkingMode=mirrored

その後、wsl --shutdown を実行して再起動します。これで localhost が双方向で機能するようになります。

ホストIPへのフォールバック（古いバージョンの Windows）：WSL2 内から Windows ホストのIPアドレスを取得し、localhost の代わりに使用します。

ip route show | grep -i default | awk '{ print $3 }'
# Use that IP as the base_url host

さらに、モデルサーバーを 127.0.0.1 ではなく 0.0.0.0 にバインドする必要があります。Ollama では OLLAMA_HOST=0.0.0.0 を設定し、llama-server／SGLang では --host 0.0.0.0 を追加します。LM Studio では「Serve on Network」を有効にしてください。²

各種ファイルはどこにありますか？

ここでは hermes status と hermes dump が役立ちます。hermes logs list を実行すると、すべてのログファイルとそのサイズが表示されます。hermes config path は設定ファイルの場所を、hermes config env-path は .env の場所を出力します。⁶

よくある質問

Hermes Agent と Claude Code の違いは何ですか？

Claude Code は Anthropic 公式の CLI であり、Anthropic モデル専用です。Hermes Agent は Nous Research が開発するオープンソースのエージェントフレームワークで、OpenAI 互換のあらゆるプロバイダーに対応しています。Nous Portal、OpenRouter、Anthropic、GitHub Copilot、z.ai、Kimi、MiniMax、DeepSeek、Hugging Face、Google、または独自のセルフホスト型エンドポイントを利用できます。¹² また Hermes には、Claude Code にはない Telegram／Discord／Slack／WhatsApp／Signal 用のメッセージング gateway も搭載されています。

Hermes で Anthropic の API キーを使用できますか？

はい。次の3つの方法があります。²

1. ~/.hermes/.env に ANTHROPIC_API_KEY を設定し、hermes chat --provider anthropic --model claude-sonnet-4-6 を実行します
2. hermes model を実行して Anthropic を選択します。利用可能な場合、Hermes は Claude Code の認証情報ストアを使用します
3. フォールバックとして、手動で ANTHROPIC_TOKEN（セットアップトークンまたは OAuth トークン）を設定します

同じマシンですでに Claude Code を使用している場合は、方法2がおすすめです。更新可能な Claude 認証情報を、そのまま更新可能な状態に保てます。

会話を失わずにプロバイダーを切り替えるにはどうすればよいですか？

セッション内で /model provider:model を使用してください。会話履歴、メモリ、skill はすべて引き継がれます。⁹

/model zai:glm-5
/model openrouter:anthropic/claude-sonnet-4
/model custom:local:qwen-2.5

Anthropic を設定しましたが、ビジョン／Web／圧縮機能が動作しません

補助モデルのフォールバックが原因です。ビジョン、Web要約、圧縮などの補助タスクでは、別の補助 LLM が使用されます。デフォルトでは、自動検出（OpenRouter → Nous → Codex）によって Gemini Flash が選ばれます。これらがどれも設定されておらず、Anthropic しか利用できない場合、各機能は通知なく縮退動作します。⁴

対処するには、補助タスク用の OPENROUTER_API_KEY を追加するか、補助スロットがメインプロバイダーを使用するよう再設定してください。なお、コンテキスト圧縮は独立したトップレベルの compression: ブロックにあり、auxiliary.compression.provider ではなく summary_provider を指定します。auxiliary.compression スロットで設定できるのは timeout のみです。完全な修正例は次のとおりです。

auxiliary:
  vision:      { provider: "main" }
  web_extract: { provider: "main" }

compression:
  summary_provider: "main"

SOUL.md と AGENTS.md の違いは何ですか？

SOUL.md は、エージェントのアイデンティティを定義するファイルです。トーン、スタイル、コミュニケーションのデフォルト設定を記述します。~/.hermes/SOUL.md に配置され、どこでも適用されます。一方、AGENTS.md はプロジェクト固有のファイルです。アーキテクチャ、規約、コマンド、パスなどを記述し、プロジェクトディレクトリに配置します。¹³ どこでも適用したい内容は SOUL.md に、特定のプロジェクトに属する内容は AGENTS.md に記述してください。

複数の Hermes インスタンスを並行して実行するにはどうすればよいですか？

profile を使用します。各 profile には、それぞれ専用の HERMES_HOME、設定、メモリ、セッション、gateway PID が割り当てられます。⁶

hermes profile create work --clone
hermes profile use work                 # Sticky default
hermes -p work chat -q "..."            # One-off without switching
hermes profile alias work --name h-work # Wrapper script

Hermes はローカル LLM に対応していますか？

はい。カスタムエンドポイント経由で利用できます。Hermes は、Ollama、vLLM、SGLang、llama.cpp／llama-server、LM Studio、LocalAI、Jan、独自サーバーなど、OpenAI 互換のあらゆるサーバーに対応しています。² サーバーごとの設定については、カスタムおよびセルフホスト型エンドポイントをご覧ください。

起動バナーに表示されるツール数が、このガイドに記載されている Hermes のツール数より少ないのはなぜですか？

このガイドに記載されている47ツール／20 toolset は、アップストリームのアーキテクチャレジストリに基づく数です。これは、Hermes がすべての toolset にわたってソースコードを同梱しているツールの総数を表します。実行中の環境では、起動時にデフォルトの toolset セットだけが有効になるため、バナーに表示される数は少なくなります（このガイドで使用した参照環境では28ツールと表示されます）。メッセージング gateway アダプター、ブラウザー自動化、高負荷のスクレイピングスタック、複数の専門的な連携機能など、多くの toolset は明示的な有効化が必要です。読み込むには、~/.hermes/config.yaml の toolsets: に明示的に追加してください。レジストリの総数は「有効にすれば利用できるもの」、バナーの総数は「現在の profile で実際に読み込まれたもの」を示します。hermes tools --list を使用すると、有効な toolset と、利用可能だが無効になっている toolset を確認できます。実行中に個別の toolset を切り替えるには、/tools enable <name> と /tools disable <name> を使用します（無効化するとセッションがリセットされ、変更後の構成に合わせてエージェントのツールマニフェストが再構築されます）。

プライマリプロバイダーで障害が発生した場合、Hermes はどのようにモデルをフォールバックしますか？

config.yaml に fallback_model ブロックを設定します。²

fallback_model:
  provider: openrouter
  model: anthropic/claude-sonnet-4

プライマリで障害（レート制限、サーバーエラー、認証エラー）が発生すると、Hermes は会話履歴を失うことなく、セッションの途中でフォールバックへ切り替えます。切り替えはセッションごとに最大1回です。

エージェントは時間とともに自身の skill を改善できますか？

はい。それが Hermes Agent の「自己改善」機能です。エージェントは skill_manage ツールを使用して、skill の作成、更新、削除を行えます。簡単ではないワークフローを解明すると、その手順を skill として保存し、今後再利用します。¹¹ エージェントが skill を作成するのは、複雑なタスク（ツール呼び出しが5回以上）の完了後、エラーに遭遇して有効な手順を発見したとき、ユーザーからアプローチを修正されたとき、または簡単ではないワークフローを発見したときです。

IDEとの連携機能はありますか？

はい。Hermes は VS Code、Zed、JetBrains 向けの ACP（Agent Client Protocol）サーバーとして実行できます。⁶

pip install -e '.[acp]'
hermes acp

変更履歴

参考文献