Hermes AgentカスタムAPI：プロバイダー、トランスポート、初回呼び出しの確認

Hermes Agentのカスタムエンドポイントは、~/.hermes/config.yaml内のproviders:配下に名前付きのエントリーとして設定する、外向きの接続先です。apiがベースURL、transportが通信プロトコルです。これは、接続の方向が逆になるHermes自身のAPIサーバーとは別のものです。検索結果ではどちらも「Hermes custom API」と呼ばれ、それぞれの公式ドキュメントページが同じ検索語で上位に表示されます。まず接続の方向を明確にしてください。

このページで扱うのは、Nous Research のオープンソースエージェントである Hermes Agentです。2026年9月21日に GitHub API を確認したところ、archived: false、disabled: false、MIT ライセンス、および同日のプッシュが確認できました。最新の公開リリースは Hermes Agent v0.21.3 で、2026年9月14日に v2026.9.14 のタグが付けられており、プレリリースではありません。このページの設定情報は、そのリポジトリと hermes-agent.nousresearch.com を参照しています。hermes-agent.org は nousresearch.com の配下ではないドメインで同じプロジェクトを扱い、Microsoft Clarity のアクセス解析を読み込みます（2026年9月21日確認）。プロジェクト自身が提供するサイトではないため、そこから設定情報を取得しないでください。また、ここで扱うものは Nous のオープンウェイトモデル群である Hermes 3 や Hermes 4 でも、同名の JavaScript エンジンでもありません。

「HermesのカスタムAPI」と呼ばれる、正反対の2つのもの

両方の行は、2026年9月21日に閲覧した Hermes 自身のページ、プロバイダーリファレンスと API サーバーのページから引用しています。自分のインストール環境で確認しておきたい命名上の注意点があります。API サーバーのページでは、それを起動するコマンドとして hermes gateway が記載されていますが、CLI リファレンスでは、hermes gateway は run、start、stop、status のサブコマンドを持つメッセージングサービスの管理コマンドとして説明されています。推測せず、hermes gateway --help を実行してください。以下の内容はすべて外向きの接続についてです。

最小限のアウトバウンド設定

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com/v1   # aliases accepted: base_url, url
    key_env: KUNAVO_API_KEY          # or inline api_key:, or key_cmd:
    transport: chat_completions      # set it by hand; see the transport section
    models:
      claude-sonnet-5:
        prompt_caching: true

model:
  default: claude-sonnet-5
  provider: custom:kunavo

KUNAVO_API_KEY=your-key

プロバイダーリファレンスに沿ってフィールドごとに見ると、設定キーはproviders.<name>、ベースURLのフィールドはapi（base_urlとurlも別名として使用可能）、認証情報はkey_env、インラインのapi_key、またはkey_cmd、プロトコルはtransportです。同じエントリーでは、name、default_model、models、context_length、discover_models、extra_body、extra_headers、session_affinity_header、ssl_ca_cert / ssl_verify、catalog_provider、enabled: falseも指定できます。エントリーはmodel.provider: custom:kunavoで選択するか、セッション中なら/model custom:kunavo:<model-id>で選択してください。

この2つのコマンドは互いに代用できません。チャットセッションの外で実行するhermes modelは、プロバイダー設定の完全なウィザードであり、プロバイダーの追加やキーの入力ができる唯一の手段です。セッション内の/modelは、既存の設定を切り替えるだけです。有効期間の短いトークンを発行する企業向けエンドポイントでは、key_cmdに、トークンを標準出力へそのまま、またはaccess_tokenフィールドを持つJSONとして出力するコマンドを指定します。Hermesはそのコマンドを実行し、トークンを有効期限の少し前までキャッシュします。この方式は、同じエントリーの静的なapi_keyまたはkey_envより優先されます。

フィールドを空欄のままにせず、トランスポートを手動で選択します

プロバイダーリファレンスには、カスタムエントリーのtransportで使用できる3つの値が記載されています。また、hermes modelのCustom Endpointウィザードは現在、プロトコルを明示的に尋ね、その回答をconfig.yamlに保存すると説明されています。URLに基づく自動検出も「フィールドを空欄にした場合のフォールバックとして引き続き行われる」とされています。ドキュメントで明示されている検出ルールは、/anthropicというパスをanthropic_messagesに対応付けるものだけで、KunavoのベースURLはこれに一致しません。ここで読んだどのページにも、残りの判定ロジックは列挙されていません。そのため、動作を推測するのではなく、フィールドを明示的に設定してください。Kunavoは/v1/chat/completions、/v1/messages、/v1/responsesを提供しているため、文書上は各通信方式に対応するルートがあります。

Anthropic の行には、断定的な回答ではなく注意書きが必要です。Hermes の Azure Foundry ガイドには、Anthropic SDK がすべてのリクエストに /v1/messages を付加するため、ベース URL から /v1 が取り除かれると記載されています。ただし、この文は Azure の見出しの下にあり、プロバイダーリファレンス自体の例（api: https://proxy.example.com/anthropic）にも、汎用プロキシに対して Hermes がどの接尾辞を付加するかは記載されていません。そのため、上記の候補はどちらも考えられ、そのうち一方では /v1 が二重になって 404 が発生する可能性があります。最初の呼び出しで実際に記録されるリクエストパスを確認してください。ベース URL のドキュメントでは、この通信方式で発生する大半の 404 の原因となる、オリジンと /v1 の取り違えを説明しています。認証についての懸念は比較的小さいです。Kunavo の Messages ルートは Authorization: Bearer と x-api-key の両方を受け付けるため、Anthropic SDK が汎用プロキシに対してどちらのヘッダーを送信しても受け付けられるはずです。ただし、Hermes はその選択を文書化していないため、「はず」という表現が正確です。

このページでも、どちらとも答えられない未解決の疑問が1つあります。Hermesのドキュメントには、GPT-5.x系のモデル名を使う場合、config.yamlにchat_completionsと書かれていても、通信方式が通知なくcodex_responsesへ切り替わると記載されています。ただし、この文はモデル名による検出として説明されている一方で、provider: azure-foundryの項目にあります。provider: customでGPTのモデル識別子を指定した場合にも同じ切り替えが起こるかは、文書化されていません。GPT系のモデルを選ぶ場合は、最初の呼び出しがどのルートに送られたかを記録してください。

カスタムエンドポイントでは自動的に得られない機能（トランスポート別）

これらはいずれも料金プランによる制限ではありません。プロジェクト自身のホームページFAQによると、Hermes Agentは「MITライセンスの無料オープンソース」です。また、providers:辞書は、特定の料金プランの機能ではなく通常の設定として文書化されています。これらは機能の対応状況による制限であり、通信方式によって異なります。

ゲートウェイ専用の回避策が 2 つあります。catalog_provider は Hermes のプロバイダー ID または models.dev ID を受け付け、そのエントリのモデルに、該当カタログのメタデータを継承させます。これは検索専用であり、リクエストは引き続きあなたの api URL にあなたのキーを使って送信されます。また discover_models: false は /models プローブを完全にスキップし、エントリに列挙したモデルだけを使用します。検出が不安定または遅い場合の修正策です。Kunavo の /v1/models 応答が Hermes のプローブを満たすかどうかは、ここではテストされていません。満たさない場合、コンテキスト検出は 128K のデフォルトにフォールバックします。これらの設定の背後にあるコスト上の考え方、つまり補助スロット、委任ワーカー、キャッシュの継続性については、ここでは繰り返さず Hermes Agent の料金で説明しています。

実際の作業を移行する前に実行する段階的な検証手順

これは、期待される観測結果とともにあなたが実行する手順であり、Kunavo が取得した結果ではありません。 Kunavo に対する Hermes の実行は行われておらず、Hermes 用の Kunavo セットアップガイドもありません。このページの内容を、テスト済みの統合として読まないでください。作業中は使用中のルートを利用可能な状態に保ってください。

1. プロバイダーを追加してから診断します。 hermes model で追加し、hermes doctor で設定および依存関係の問題を診断します。CLI リファレンスには、カスタムエンドポイントの設定に対して実行される 2 つのチェックが記載されています。custom_providers キーが YAML リストではない場合と、対応する providers: エントリがないレガシーリスト項目です。どちらも警告のみで、--fix は書き換えません。
2. 費用をかける前に、キーが読み込まれていることを確認します。 hermes dump は、バージョン、プロバイダー、モデル、API キーの有無を含む、コピーして貼り付け可能なセットアップ概要を出力します。モデル ID と、キーが存在することを確認してください。hermes prompt-size はオフラインで実行され、システムプロンプトとツールスキーマのバイト内訳を報告します。これは会話内容の前に、毎回送信される固定部分です。
3. ストリーミングなしのテキストターンを 1 回。 応答が返り、リクエストが意図したパスに送信されることを確認してください。「動作する」ものの無意味な内容を返すカスタムエンドポイントは、Hermes の クイックスタートのトラブルシューティング表にある項目です。そこでは、誤ったベース URL、誤ったモデル名、実際には OpenAI 互換ではないエンドポイントが原因として挙げられ、まず別のクライアントでエンドポイントを確認するよう案内しています。
4. ストリーミングターンを 1 回。 最後に 1 つのブロックで出力されるのではなく、段階的に出力されることを確認してください。特定のエンドポイントのストリームフレーミングが Hermes の進捗解析を満たすかどうかは、このページではテストしていません。
5. ツールラウンドを 1 回。 ツールが実行されることを確認してください。呼び出しが代わりにテキストとして出力される場合、それはトランスポートではなく、サービス提供側のツール呼び出しサポートの問題です。
6. メーターを確認します。 /usage は、セッション内のトークン、コスト、コンテキストのパネルです。エージェント自身が報告トークンを基に計算した値は推定値であり、台帳ではありません。プロバイダーアカウントに実際に記録された請求額と照合してください。使用量ドキュメントを参照してください。

手順全体のコストと、セッション途中で切り替えるコスト

上記 6 手順で、合計 26,000 入力トークンを送信し、1,150 出力トークンを受信するとします。これは 3 回の呼び出しそれぞれで固定システムプロンプトとツールスキーマを送信し、さらにツール結果を 1 回再送する想定です。この想定は説明用です。hermes prompt-size はあなた自身の固定プロンプトのバイト内訳を報告するため、このページで推測する数値より実態に近い情報が得られます。料金は 100 万トークンあたりの最新の Kunavo カタログ価格です。

これはカタログ料金に基づく説明用のトークン計算であり、測定された Hermes タスクでも請求上限でもありません。キャッシュ書き込み、外部ツール、税金は含みません。この数値の要点は小ささです。ルートの検証にかかる費用は、スケジュールされた作業を 1 週間実行した後に設定ミスを発見する費用よりはるかに低くなります。

2 つ目の数値は、/model コマンドが隠しているものです。プロンプトキャッシュはリクエストを処理するモデルに紐付くため、会話途中でモデルを変更すると、次のメッセージではキャッシュ料金ではなく、会話全体が通常の入力料金で再読み込みされます。Hermes の説明では、キャッシュ料金は通常の入力料金よりおよそ 75〜90% 安くなります。Claude Sonnet 5 を使用した 120,000 トークンの会話では、100 万トークンあたりの $1.40 と $0.14 のキャッシュ読み取り料金の差は、その 1 ターンだけで約 $0.151 です。1 回なら軽微ですが、習慣になると軽微ではありません。Kunavo のカタログ金額は上限ではなく請求下限です。上流が請求額を報告した場合、請求額はカタログコストと、適用されるマークアップを掛けた上流コストのうち大きい方になります。最低額は、サブスクリプションなしの $10 前払いチャージです。請求を参照してください。

設定を元に戻す

Hermes には取り消し手順が文書化されているため、試行のリスクは低いです。エントリで enabled: false を設定すると、削除せずに非表示にできます。config.yaml の時点コピーは、hermes setup または hermes migrate が書き換える前、および解析時に backups/config/config.yaml.<reason>.<timestamp> へ保存されます。同一内容の繰り返しはスキップされ、理由ごとに最新の 5 件だけが保持されます。後でファイルの解析に失敗した場合、Hermes は組み込みデフォルトではなく、最新の正常なコピーを提供します。設定リファレンスでは model.base_url に「プロバイダー切り替え時にクリア」とも記載されています。したがって、組み込みプロバイダーへ戻すと古いベース URL がファイルに残らず削除されることが文書化されています。思い込みで済ませず、後から書き込まれた値を確認してください。

3 つの落とし穴は古いチュートリアルに由来します。レガシーのトップレベル custom_providers: リストは今も機能し、hermes update が自動的に providers: 辞書へ移行します。その際、レガシーの model は default_model に、レガシーの api_mode は transport になります。.env 内の LLM_MODEL は完全に削除されており、config.yaml が唯一の信頼できる情報源です。また OPENAI_BASE_URL は、現在の公式ページ 2 つで異なる方法により文書化されています。プロバイダーリファレンスでは openai-api プロバイダーにのみ適用されるとされ、環境変数リファレンスではカスタムエンドポイントのベース URL として記載されています。この不一致は未解決です。したがって、エンドポイントは config.yaml で設定し、その環境変数をルートとして使用しないでください。

プロバイダーを接続するのではなく選ぶ場合は、OpenAI 互換 APIで互換サーフェスに含まれるものと含まれないものを確認し、Hermes と OpenClawで 2 つのエージェントを比較できます。このルートを残高のあるキーでテストする準備ができたら、Kunavo アカウントを作成してください。

よくある質問

Hermes Agent のドキュメント（プロバイダーリファレンス、API サーバーページ、モデル設定ページ、設定ページ、CLI リファレンス、スラッシュコマンドリファレンス、クイックスタート、プロジェクトホームページ）を 2026 年 9 月 21 日に確認しました。リポジトリの状態と最新リリースは、同日に GitHub API と照合しました。Kunavo の 3 つの API ルートは、Kunavo 自身のソースで確認しました。すべての金額は、最新のカタログ料金に基づく説明用のトークン計算であり、測定されたタスクコストではありません。Hermes の設定はソースドキュメントに基づいて報告しており、Kunavo に対する Hermes の実行は行っていません。