Hermes Agent

~/.hermes/config.yaml에 이름이 지정된 공급자를 설정하고 api https://api.kunavo.com, transport anthropic_messages를 지정한 뒤 provider: custom:kunavo로 선택하면 Hermes Agent가 Messages 프로토콜을 통해 Claude를 사용합니다. 이때 Hermes Agent는 자체 캐시 마커와 출력 한도를 전송합니다.

# ~/.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. 메시지를 두 개 보낸 다음 /usage를 열어 각 차례에 사용된 내용을 확인하세요. 세션 내에서 모델을 바꾸려면 /model custom:kunavo:claude-opus-5-5를 사용하세요.

Hermes Agent의 AI 제공자 페이지에서 확인했습니다(2026년 10월 5일 기준). 서드파티 설정은 변경될 수 있으므로, 여기의 필드 이름이 실제 화면과 다르면 이 문서가 아니라 해당 페이지를 기준으로 삼으세요.

클라이언트를 디버깅하기 전에 확인할 사항

한 번의 요청으로 문제가 엔드포인트, 키 또는 구성 파일 중 어디에 있는지 판단할 수 있습니다. 이 요청에서 JSON이 반환되면 동일한 base 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"}]}'

필드에 입력할 model id

모든 텍스트 모델은 model 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

여기서는 기본 URL에 /v1을 유지합니다. 이는 Hermes 문서의 로컬 서버 예시에서 사용하는 형식이며, 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 호환 전송 방식에서 Kunavo는 Claude 모델의 중단점을 직접 설정합니다. 프롬프트가 캐시할 만큼 길면 클라이언트가 마커를 보내는지와 관계없이 시스템 프롬프트, 도구 정의, 대화 끝에 중단점을 둡니다. GPT 모델은 제공업체가 암시적으로 캐시합니다.

중단 지점을 어느 쪽에서 설정하든 청구 금액은 같습니다. Claude Sonnet 5에서 캐시 읽기 요금은 토큰 100만 개당 $0.14이며, 새 입력 요금은 $1.40입니다. 캐시 쓰기 요금은 $1.75입니다. 이는 Claude의 입력 요금보다 높은 쓰기 요금이며, 항목의 수명이 1시간으로 설정된 경우에도 같은 요율로 청구됩니다. 항목은 5분 동안 유지되고 읽을 때마다 수명이 갱신되므로, 에이전트의 지출은 모델보다 다음 요청이 이 시간 내에 도착하는지에 더 크게 좌우됩니다. 각 모델의 캐시 요금은 프롬프트 캐싱 페이지에서 확인할 수 있습니다.

어떤 요율보다도 비용에 더 큰 영향을 미치는 Hermes 동작이 하나 있습니다. Hermes 문서에 따르면 세션 중 모델 전환, 자동 대체 또는 자격 증명 교체가 발생하면 프롬프트 캐시가 초기화되어 다음 메시지에서 전체 대화를 입력 정가로 다시 읽습니다. 긴 세션을 시작하기 전에 모델을 선택하세요.

상시 실행 에이전트의 일일 비용

Hermes에서 아무도 입력하지 않을 때 청구되는 비용은 예약한 작업과 각 대화에서 시작되는 보조 작업의 비용입니다. Hermes의 cron 문서에 따르면 예약 실행마다 새 세션이 시작되므로, 실행될 때마다 지침, 도구 스키마, 첨부된 스킬을 포함한 전체 프롬프트의 비용이 청구됩니다. 프롬프트 크기는 설정에 따라 달라지므로 표에는 가정값을 명시했습니다. 실행당 20,000토큰, 30분마다 한 번 실행하여 하루 48회입니다. 두 값을 모두 실제 수치로 바꾸세요.

이 수치는 Hermes 문서에 나온 세 가지 설정으로 달라집니다. 예약 작업은 작업별 모델을 사용하고, 없으면 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 문서에서는 이 설정을 통해 단일 호출의 비용 상한을 고정하는 방법을 안내합니다.

에이전트가 실제로 작동하는 시간은 청구액의 나머지 한 축이며, 이때는 캐시가 비용을 좌우합니다. 연속해서 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 코드와 함께 거부되며, 해당 요청에는 요금이 청구되지 않습니다. 거부는 지갑 잔액이 0이 되기 전에 발생합니다. 각 요청에서 먼저 최악의 경우에 드는 비용, 즉 프롬프트와 허용된 최대 응답의 비용을 예약하기 때문입니다. 따라서 에이전트가 더 큰 출력 한도를 요청할수록 호출이 더 일찍 거부되기 시작합니다. 오류에는 balance_usd 및 needed_usd 필드를 통해 금액이 얼마나 부족했는지 표시됩니다.

제공업체 오류에 대한 Hermes Agent의 대응은 대체 체인입니다. config.yaml의 fallback_providers에 설정하며, hermes fallback로 관리하고 턴마다 순서대로 시도합니다. 문서에 따르면 기본 모델에서는 속도 제한, 서버 오류, 인증 실패, 404가 대체 체인을 작동시키는 조건이며, 보조 작업의 체인에서는 용량 오류에 해당하는 HTTP 402도 다음 제공업체로 넘기는 조건입니다. 대체 제공업체가 설정되지 않았을 때 402가 발생하면 해당 턴이 어떻게 처리되는지는 설명되어 있지 않습니다. 있는 그대로 해석해 턴과 그에 따른 예약 작업이 실패한다고 예상하고, 대체된 턴은 프롬프트 캐시가 없는 상태로 시작한다는 점도 기억하세요.

에이전트가 무인 상태에서 이 상황에 빠지지 않도록 하는 설정은 두 가지이며, 각각 다른 역할을 합니다.

• 자동 충전, 결제 아래에서 설정하세요. 카드를 한 번 저장한 다음 세 가지 금액을 설정합니다. 이 잔액 아래로 내려가면 충전할 기준 금액, 매번 추가할 금액, 월간 한도입니다. 그러면 API 호출로 잔액이 기준 금액 아래로 내려간 뒤 몇 초 안에 지갑이 충전됩니다. 지갑 잔액이 부족한 동안 도착한 요청은 해당 결제가 완료될 때까지 대기한 다음 거부되지 않고 처리됩니다. 결제를 진행할 수 없는 경우(카드 승인 거절, 월간 한도 도달) 또는 한 번의 요청에서 충전 후 지갑 잔액보다 많은 금액을 예약하는 경우에는 402가 계속 반환됩니다. 자동 결제를 이용하려면 카드 또는 Link가 필요합니다. Alipay, WeChat Pay, Pix 및 기타 현지 결제 수단은 자동으로 청구할 수 없습니다.
• 키별 월간 한도는 API 키 아래에서 설정하세요. 에이전트 전용 키를 발급하고 해당 키가 매월 1일부터 말일까지 사용할 수 있는 최대 금액을 설정합니다. 그 금액을 초과하면 해당 키의 호출은 402와 함께 거부되고 요금이 청구되지 않으며, 다른 키는 계속 작동합니다. 이는 폭주하는 루프를 제한하기 위해 필요한 상한이며, 모든 키가 같은 지갑을 사용하므로 지갑만으로는 설정할 수 없습니다.

충전 기준액은 요청 하나에 예약되는 금액보다 높게 설정하고, 충전액은 최소 금액이 아니라 에이전트의 하루치 비용을 기준으로 정하세요. 최소 충전액은 $10이며, 위에 제시된 상시 실행 에이전트의 하루 비용 중앙값은 $12.67입니다. 자동 충전 한도는 결제 페이지에서, 전체 오류 본문은 오류 페이지에서 확인할 수 있습니다.

관련 가이드

• Hermes Agent 맞춤 API — 아웃바운드 제공자가 인바운드 API 서버와 다른 이유, transport 필드에 대한 설명, 첫 호출에서 확인할 항목을 살펴보세요.
• Hermes Agent 요금 — 토큰 요금 외에 실행에 드는 비용을 안내합니다.
• Hermes 컨텍스트 압축 시간 초과 — 요약 생성기가 멈췄을 때 발생하는 오류의 의미와 복구 방법을 안내합니다.
• Hermes와 OpenClaw 비교 — 다른 에이전트인 OpenClaw에도 동일하게 설정하는 방법은 OpenClaw 페이지를 참조하세요.