Hermes Agent

~/.hermes/config.yaml に名前付きプロバイダーを設定し、api https://api.kunavo.com、transport anthropic_messages を指定して provider: custom:kunavo で選択すると、Hermes Agent は Messages プロトコルを使って Claude に接続し、キャッシュマーカーと出力上限を自身で送信します。

# ~/.hermes/config.yaml
providers:
  kunavo:
    api: https://api.kunavo.com        # origin — the Anthropic SDK adds /v1/messages
    key_env: KUNAVO_API_KEY            # the variable's NAME; the key goes in ~/.hermes/.env
    transport: anthropic_messages
    models:
      claude-sonnet-5:
        context_length: 1000000
        prompt_caching: true
      claude-haiku-4-5:
        context_length: 200000
        prompt_caching: true

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

手順

1. /app/keys でキーを作成してコピーします。キーは一度だけ表示されます。
2. Hermesがシークレットを保存する場所にキーを保存します。hermes config set KUNAVO_API_KEY sk-kn-...を実行すると、キーは~/.hermes/.envに書き込まれます。ブロック内のkey_env行は、その変数名を指定しています。キーそのものをconfig.yamlに記載することはありません。
3. ブロックを~/.hermes/config.yamlに追加します。hermes config editを実行するとファイルが開きます。すでにmodel:セクションがある場合は、そのdefaultとproviderを置き換え、ほかの部分はそのまま残します。
4. または、ウィザードに設定を書き込ませます。チャットセッションの外でターミナルからhermes modelを実行し、Custom endpoint (self-hosted / VLLM / etc.)を選択して、プロンプトに従ってAPIのベースURL、キー、モデル名、APIモード、コンテキスト長を入力します。
5. hermesを起動して、バナーを確認します。そこにモデルとコンテキストウィンドウが表示され、どちらもブロック内の設定と一致している必要があります。
6. メッセージを2件送信し、/usageを開いて各ターンの使用量を確認します。セッション内でモデルを変更するには、/model custom:kunavo:claude-opus-5-5を使います。

Hermes AgentのAIプロバイダーのページで2026年10月5日に確認しました。サードパーティの設定は変更されます。ここに記載されたフィールド名が表示内容と一致しなくなった場合は、このページではなく、そのページを正しい情報源としてください。

クライアントをデバッグする前に確認すること

1回のリクエストで、失敗の原因がエンドポイント、キー、設定ファイルのどれかを特定できます。これがJSONを返すなら、同じベースURLとキーがHermes Agentで機能します。

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

フィールドに入力するモデルID

すべてのテキストモデルにはモデルIDでアクセスできます。現在の一覧はGET /v1/models、価格付きのカタログはモデルページにあります。料金は100万トークンあたりのUSDで、入力 / 出力の順です。

OpenAI互換の通信方式

同じキーで、/v1/chat/completionsを通じて他のすべてのモデルファミリーにも接続できます。その場合、Hermesのドキュメントにある最も簡潔な形式で十分です。provider: customとbase_urlを指定したmodel:ブロックです。これはhermes modelが求める形式でもあります。

# ~/.hermes/config.yaml — the bare form, for an OpenAI-compatible endpoint
model:
  default: gpt-6-sol
  provider: custom
  base_url: https://api.kunavo.com/v1    # this wire keeps /v1
  key_env: KUNAVO_API_KEY
  context_length: 1050000

ここでは、Hermesのドキュメントがローカルサーバーの例で使用している形式に従い、ベースURLに/v1を含めます。また、context_lengthでウィンドウを固定するため、Hermesがそれを検出する必要はありません。両方の通信方式を同時に設定しておくには、この方式専用の名前付きエントリーを用意してtransport: chat_completionsを指定し、/model custom:<name>:<model>で切り替えます。

各通信方式でのプロンプトキャッシュ

Anthropic通信方式では、Hermesがキャッシュマーカーを自動で付加します。カスタムプロバイダーの場合、Hermesのモデルの設定ページでは、上のブロックで使った設定（モデルのprompt_caching: true）を説明し、レイアウトは通信方式に従うとしています。anthropic_messagesではネイティブ形式のブロック、OpenAI互換の通信方式ではエンベロープ形式です。Kunavoの/v1/messagesは送信されたとおりのリクエスト本文を転送し、独自のブレークポイントは追加しません。そのため、この通信方式のマーカーはHermesが付加したものか、まったく存在しないかのどちらかです。

カスタムエンドポイントでの有効期間については、Hermesのドキュメントに記載がありません。prompt_caching.cache_ttl（5m、1h、またはauto）は、ネイティブのAnthropic API、OpenRouter、Nous Portalを通じてClaudeを使う場合について説明されていますが、他のエンドポイントについては何も述べられていません。Kunavoは受信したマーカーをそのまま転送し、書き込みには同じ料金を適用します。したがって、実際の使用状況から判断してください。10分間中断した後のターンでもキャッシュ読み取りが表示されるなら、1時間有効なエントリーが保持されていたことになります。

OpenAI互換の通信方式では、Claudeモデルのブレークポイントを、プロンプトがキャッシュ可能な長さに達するとKunavoが自動で設定します。場所はシステムプロンプト、ツール定義、会話の末尾です。クライアントがマーカーを送信するかどうかは問いません。GPTモデルはベンダーによって暗黙的にキャッシュされます。

ブレークポイントをどちら側が配置しても、請求額は同じです。Claude Sonnet 5では、100万トークンあたりのキャッシュ読み取り料金は$0.14で、新規入力料金は$1.40、キャッシュ書き込み料金は$1.75です。この書き込み料金は Claude の入力料金より割高で、エントリーの有効期間を1時間にした場合も同じレートで課金されます。エントリーの有効期間は5分で、読み取りのたびに更新されます。そのため、エージェントの支払額はモデルよりも、次のリクエストがその期間内に届くかどうかに左右されます。各モデルのキャッシュ料金はプロンプトキャッシュのページをご覧ください。

料金体系以上に費用へ影響するHermesの動作があります。Hermesのドキュメントによると、セッション途中でのモデル切り替え、自動フォールバック、認証情報のローテーションはいずれもプロンプトキャッシュをリセットします。そのため次のメッセージでは会話全体が割引なしの通常の入力料金で再読み込みされます。長いセッションを始める前にモデルを選択してください。

常時稼働エージェントの1日あたりの費用

Hermesでは、誰も入力していない間に課金されるのは、スケジュールした処理と、各会話で発生するサイドタスクです。cronのドキュメントによると、スケジュール済みの実行ごとに新しいセッションが開始されるため、実行のたびに指示、ツールスキーマ、添付スキルを含むプロンプト全体に課金されます。プロンプトのサイズは設定によって異なるため、表では前提を明示しています。1回あたり20,000トークン、30分ごとに1回の実行、つまり1日48回です。どちらもご自身の数値に置き換えてください。

その金額は、Hermesのドキュメントに記載された3つの設定で変わります。スケジュール済みジョブは、ジョブ単位のモデル、次にcron.model、それらがなければメインモデルを使用します。そのため、hermes config set cron.model claude-haiku-4-5を設定すれば、モデルが固定されていないジョブをすべて高額なモデルから切り替えられます。ジョブスクリプトが{"wakeAgent": false}を出力すると、その実行回ではモデルをスキップします。エージェントを使わないジョブではモデルを呼び出しません。また、圧縮、タイトル生成、画像認識などのサイドタスクは、auxiliaryで別のモデルに振り分けない限り、メインモデルで実行されます。

# ~/.hermes/config.yaml — what decides the cost of an unattended day
compression:
  threshold_tokens: 256000         # compact here, not at half of a 1M window

auxiliary:
  compression:
    provider: kunavo               # the named entry above
    model: claude-haiku-4-5        # summaries on the cheapest tier
  title_generation:
    provider: kunavo
    model: claude-haiku-4-5

ウィンドウが大きい場合は、threshold_tokensが重要な設定です。デフォルトでは、コンテキスト長の半分に達すると圧縮が始まります。Hermesのドキュメントによると、この設定で1回の呼び出しにかかる費用の上限を固定できます。

エージェントが実際に稼働している時間も、請求額を左右するもう一つの要素です。そこではキャッシュが決め手になります。100回連続してリクエストを送り、毎回100,000トークンのコンテキストを再送し、その上に2,000個の新しいトークンを追加して、800トークンの出力を受け取るとします。Claude Sonnet 5では、コンテキストがキャッシュから読み込まれる場合は約$2.31、各リクエストで新しい入力として請求される場合は約$14.84です。同じ処理、同じモデルでも、ブレークポイントが設定されているか、そしてリクエストの間隔が5分未満かどうかで差が生じます。

規模感を示すため、推定ではなく実測値を紹介します。常時稼働エージェントを実行しているKunavoアカウント全体では、稼働日のコスト中央値は$12.67、90パーセンタイルの日は約$163です。これらは2026年10月5日までに、その日の適用料金で請求された金額です。対象は少数のグループなので、ご自身のエージェントの予測値ではなく、金額の幅の参考としてご覧ください。

残高がなくなった場合

Kunavoはプリペイド方式です。すべての呼び出しはウォレットから支払われるため、あなたが眠っている間も稼働するエージェントは、その間にウォレット残高を使い切ります。ウォレットで支払えないリクエストは、どちらの通信方式でもHTTP 402とコードinsufficient_balanceを返して拒否され、料金は発生しません。残高がゼロになる前に拒否が起こるのは、各リクエストの処理前に、プロンプトと許可される最大応答量を合わせた最悪ケースの費用が確保されるためです。そのため、エージェントが要求する出力上限が大きいほど、呼び出しは早く拒否され始めます。エラーには、不足額がbalance_usdとneeded_usdで示されます。

プロバイダーでエラーが発生した場合、Hermes Agentはフォールバックチェーンを使います。config.yaml内のfallback_providersを、hermes fallbackで管理し、ターンごとに順番に試します。ドキュメントでは、メインモデルについて、レート制限、サーバーエラー、認証失敗、404がフォールバックの発動条件として挙げられています。また、サイドタスクでは、HTTP 402を含む容量不足エラーがチェーン内の次のプロバイダーへ移る条件として記載されています。フォールバックが設定されていない場合に402でターンがどうなるかは説明されていません。単純に解釈して、ターンは失敗し、スケジュール済みジョブも失敗すると見込んでください。フォールバックしたターンは、プロンプトキャッシュが空の状態から始まることにも留意してください。

エージェントを無人稼働させる際に、この状態を防ぐ設定が2つあります。それぞれ役割が異なります。

• 自動チャージ、請求で設定します。カードを一度登録し、3つの数値を設定します。補充を開始する残高のしきい値、1回あたりの補充額、月間上限です。これにより、利用によって残高がしきい値を下回ると、数秒以内にウォレットが補充されます。ウォレットの残高が不足している間に届いたリクエストは、その請求が完了するまで待機し、その後、拒否されずに処理されます。請求を実行できない場合（カードが拒否された場合や月間上限に達した場合）、または1件のリクエストで補充後のウォレット残高を超える金額が予約される場合は、402が返されます。自動課金にはカードまたはLinkが必要です。Alipay、WeChat Pay、Pixなどの現地決済方法は自動課金できません。
• キーごとの月間上限をAPI キーで設定します。エージェント専用のキーを発行し、そのキーが暦月内に使用できる金額の上限を設定します。上限を超えると、そのキーからの呼び出しは402で拒否され、課金は発生しません。他のキーは引き続き利用できます。これにより、制御不能なループによる支出を制限できます。すべてのキーが同じウォレットを利用するため、ウォレットではこの制限を設定できません。

チャージのしきい値は、1回のリクエストで確保される金額より高く設定してください。チャージ額は最低額ではなく、エージェントの1日分の費用を目安に決めます。最小チャージ額は$10で、上記の常時稼働エージェントの1日あたりの費用の中央値は$12.67です。自動チャージの制限は請求ページ、エラーの全内容はエラーページをご覧ください。

関連ガイド

• Hermes AgentのカスタムAPI — 外部向けプロバイダーが受信APIサーバーとは異なる理由、transportフィールドの説明、最初の呼び出しで実行する確認項目。
• Hermes Agentの料金 — トークン料金以外に実行にかかる費用を説明します。
• Hermesのコンテキスト圧縮がタイムアウトする場合 — 要約処理が停止したときのエラーの意味と復旧方法を説明します。
• HermesとOpenClawの比較 — もう一方のエージェントでの同じ設定方法は、OpenClawのページをご覧ください。