Hermes Agent 사용자 지정 API: 공급자, 전송 방식 및 첫 호출 확인

Hermes Agent 사용자 지정 엔드포인트는 providers: 아래에 이름이 지정된 항목으로 아웃바운드 구성되며, ~/.hermes/config.yaml에서 api는 기본 URL이고 transport는 전송 프로토콜입니다. 이는 반대 방향을 가리키는 Hermes 자체 API 서버와는 다른 것입니다. 검색 결과에서는 둘 다 ‘Hermes 사용자 지정 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라고 불리는 서로 반대되는 두 가지

두 행 모두 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>으로 선택할 수 있습니다.

두 명령은 서로 바꿔 사용할 수 없습니다. 채팅 세션 밖에서 실행하는 hermes model는 전체 공급자 설정 마법사이며, 공급자를 추가하거나 키를 입력할 수 있는 유일한 방법입니다. 세션 안의 /model는 이미 존재하는 항목 사이에서만 전환합니다. 짧은 수명의 토큰을 발급하는 엔터프라이즈 엔드포인트의 경우 key_cmd는 표준 출력에 토큰을 표시하는 명령을 지정합니다. 토큰만 출력하거나 access_token 필드를 포함한 JSON으로 출력할 수 있으며, Hermes는 만료 직전까지 이를 실행하고 캐시합니다. 같은 항목의 정적 api_key 또는 key_env보다 적합합니다.

필드를 비워 두지 말고 전송 방식을 직접 선택하세요

공급자 레퍼런스에는 사용자 지정 항목의 transport에 허용되는 세 값이 나와 있습니다. 또한 hermes model 사용자 지정 엔드포인트 마법사가 이제 프로토콜을 명시적으로 묻고 그 답을 config.yaml에 저장하며, URL 기반 자동 감지는 ‘필드를 비워 두었을 때 대체 수단으로 계속 수행된다’고 설명합니다. 문서에 명시된 유일한 감지 규칙은 /anthropic 경로가 anthropic_messages로 매핑된다는 것이며, Kunavo 기본 URL은 이에 해당하지 않습니다. 여기서 확인한 어떤 페이지에도 나머지 휴리스틱이 열거되어 있지 않으므로, 어떻게 동작할지 추측하지 말고 필드를 직접 입력해야 합니다. Kunavo는 /v1/chat/completions, /v1/messages 및 /v1/responses를 제공하므로 문서상 각 전송 방식에 대응하는 경로가 있습니다.

Anthropic 행에는 확신에 찬 답변이 아니라 주의 사항이 필요합니다. Hermes의 Azure Foundry 가이드에는 Anthropic SDK가 모든 요청에 /v1/messages를 추가하기 때문에 /v1가 기본 URL에서 제거된다고 나와 있습니다. 그러나 이 문장은 Azure 제목 아래에 있으며, 공급자 레퍼런스의 자체 예시(api: https://proxy.example.com/anthropic)에는 일반 프록시에 대해 Hermes가 어떤 접미사를 추가하는지 나와 있지 않습니다. 따라서 위의 두 후보 모두 가능하며, 그중 하나는 이중 /v1로 인해 404를 발생시킬 수 있습니다. 첫 번째 호출에서 실제로 기록되는 요청 경로를 확인하세요. 기본 URL 문서는 이 전송 방식에서 발생하는 대부분의 404 뒤에 있는 오리진과 /v1의 혼동을 다룹니다. 인증은 덜 중요한 문제입니다. Kunavo의 Messages 경로는 Authorization: Bearer 및 x-api-key를 모두 허용하므로 일반 프록시에 Anthropic SDK가 어느 헤더를 보내든 허용될 가능성이 높습니다. 다만 Hermes는 이 선택을 문서화하지 않았으므로 ‘가능성이 높다’가 정확한 표현입니다.

이 페이지에서도 어느 쪽으로든 답할 수 없는 열린 질문이 하나 있습니다. Hermes는 codex_responses로 업그레이드하는 GPT-5.x 제품군 모델 이름을 자동으로 변경한다고 문서화하지만, config.yaml가 여전히 chat_completions라고 표시되는 경우에도 그렇습니다. 그러나 이 문장은 provider: azure-foundry 아래에 있으며 모델 이름 감지에 관한 표현으로 작성되어 있습니다. provider: custom의 GPT 슬러그가 같은 동작을 유발하는지는 문서화되어 있지 않습니다. GPT 계열 모델을 선택한다면 첫 번째 호출이 어느 경로로 전송되었는지 기록하세요.

전송 방식별 사용자 지정 엔드포인트가 자동으로 제공하지 않는 것

어느 것도 요금제 게이트가 아닙니다. Hermes Agent는 프로젝트 자체의 홈페이지 FAQ에 따르면 ‘MIT 라이선스에 따른 무료 오픈 소스’이며, providers: 딕셔너리는 요금제 기능이 아니라 일반 구성으로 문서화되어 있습니다. 이는 기능 게이트이며 전송 방식에 따라 달라집니다.

게이트웨이에 특화된 두 가지 우회 방법입니다. 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 참조에는 사용자 지정 엔드포인트 설정에서 실행되는 두 가지 검사도 기록되어 있습니다 — YAML 목록이 아닌 custom_providers 키와, 일치하는 providers: 항목이 없는 레거시 목록 항목입니다. 둘 다 경고만 표시하며 --fix는 이를 다시 작성하지 않습니다.
2. 비용을 지출하기 전에 키가 로드되었는지 확인하십시오. hermes dump는 버전, 제공업체, 모델 및 API 키 존재 여부가 포함된 복사하여 붙여넣을 수 있는 설정 요약을 출력합니다. 모델 ID와 키가 존재한다고 예상하십시오. hermes prompt-size는 오프라인으로 실행되며 시스템 프롬프트와 도구 스키마의 바이트 분석을 보고합니다. 이는 대화 내용에 앞서 매 턴마다 전달되는 고정 부분입니다.
3. 스트리밍하지 않는 텍스트 턴 하나. 응답이 오고 요청이 의도한 경로로 전송되었을 것으로 예상하십시오. “작동”하지만 엉뚱한 내용을 반환하는 사용자 지정 엔드포인트는 Hermes 빠른 시작 문제 해결 표의 항목입니다. 이 표는 잘못된 기본 URL, 잘못된 모델 이름 또는 실제로 OpenAI와 호환되지 않는 엔드포인트를 원인으로 들며, 먼저 별도의 클라이언트에서 엔드포인트를 확인하라고 안내합니다.
4. 스트리밍 턴 하나. 마지막에 한 블록으로 출력되는 대신 점진적인 출력이 제공될 것으로 예상하십시오. 특정 엔드포인트의 스트림 프레이밍이 Hermes의 진행률 구문 분석을 충족하는지는 이 페이지에서 테스트하지 않았습니다.
5. 도구 라운드 하나. 도구가 실행될 것으로 예상하십시오. 호출이 대신 텍스트로 출력된다면 이는 전송 방식이 아니라 서비스를 제공하는 측의 도구 호출 지원 문제입니다.
6. 미터를 읽으십시오. /usage는 세션 내 토큰, 비용 및 컨텍스트 패널입니다. 이를 제공업체 계정에 실제로 기록된 요금과 대조하십시오 — 보고된 토큰을 바탕으로 에이전트가 자체 계산한 금액은 원장이 아니라 추정치입니다. 사용량 문서를 참조하십시오.

단계 실행에 드는 비용과 세션 중간 전환에 드는 비용

위의 6단계에서 총 입력 토큰 26,000개를 보내고 출력 토큰 1,150개를 받는다고 가정하십시오 — 세 번의 호출 각각에 고정 시스템 프롬프트와 도구 스키마가 포함되고, 도구 결과가 한 번 다시 전송됩니다. 이 가정은 설명을 위한 것입니다. hermes prompt-size는 사용자의 고정 프롬프트를 바이트별 내역으로 보고하며, 이는 이 페이지가 추정할 수 있는 숫자보다 실제에 가깝습니다. 요금은 토큰 백만 개당 실시간 Kunavo 카탈로그 가격입니다.

이는 카탈로그 요금에 따른 예시적 토큰 산술이며, 측정된 Hermes 작업도 아니고 청구 한도도 아닙니다. 캐시 쓰기, 외부 도구 및 세금은 제외됩니다. 이 숫자의 요점은 규모가 작다는 것입니다. 일주일간 예약된 작업을 실행한 뒤 잘못된 설정을 발견하는 것보다 라우트를 확인하는 비용이 훨씬 적습니다.

두 번째 숫자는 /model 명령이 숨기는 값입니다. 프롬프트 캐시는 요청을 처리하는 모델을 기준으로 키가 지정되므로, 대화 중간에 모델을 바꾸면 다음 메시지에서 캐시 요금이 아닌 전체 입력 요금으로 대화 전체를 다시 읽습니다. Hermes는 캐시 요금이 약 75~90% 더 저렴하다고 설명합니다. Claude Sonnet 5를 사용하는 120,000토큰 대화에서 토큰 백만 개당 $1.40와 $0.14 캐시 읽기 요금의 차이는 해당 한 번의 턴에 약 $0.151입니다 — 한 번이면 사소하지만 습관이 되면 사소하지 않습니다. Kunavo의 카탈로그 금액은 상한이 아니라 청구 하한입니다. 업스트림이 요금을 보고할 때 청구액은 카탈로그 비용과 업스트림 비용에 해당 마크업을 곱한 금액 중 더 큰 값입니다. 최소 선불 충전 금액은 $10이며 구독은 없습니다. 청구를 참조하십시오.

설정을 다시 되돌리기

Hermes는 되돌리기 경로를 문서화하고 있으며, 이것이 시험 사용의 위험이 낮은 이유입니다. 항목의 enabled: false는 삭제하지 않고 숨깁니다. config.yaml의 시점별 복사본은 backups/config/config.yaml.<reason>.<timestamp>에 기록되며, hermes setup 또는 hermes migrate가 이를 다시 작성하기 전과 파싱할 때마다 생성됩니다. 동일한 반복 기록은 건너뛰고 이유별로 최신 5개만 유지합니다. 이후 파일 파싱에 실패하면 Hermes는 내장 기본값 대신 가장 최근의 정상 복사본을 제공합니다. 설정 참조는 또한 model.base_url를 “제공업체 전환 시 지워짐”으로 표시합니다. 따라서 기본 제공업체로 다시 전환하면 오래된 기본 URL이 파일에 남지 않고 제거되는 것으로 문서화되어 있습니다 — 이를 가정하지 말고 나중에 기록된 값을 확인하십시오.

오래된 튜토리얼에서 비롯된 함정은 세 가지입니다. 레거시 최상위 custom_providers: 목록은 여전히 작동하며 hermes update가 이를 providers: 딕셔너리로 자동 마이그레이션합니다. 이때 레거시 model는 default_model가 되고 레거시 api_mode는 transport가 됩니다. .env의 LLM_MODEL는 완전히 제거되었으며 — config.yaml가 단일 진실 공급원입니다. 또한 OPENAI_BASE_URL는 현재 공식 페이지 두 곳에서 두 가지 방식으로 문서화되어 있습니다. 제공업체 참조에서는 openai-api 제공업체에서만 적용된다고 하고, 환경 변수 참조에서는 사용자 지정 엔드포인트의 기본 URL로 나열합니다. 이 불일치는 해결되지 않았으므로 엔드포인트를 config.yaml에서 설정하고, 해당 환경 변수를 라우트로 사용하지 마십시오.

라우트를 연결하는 대신 제공업체를 선택하는 경우, OpenAI 호환 API에서 호환 표면에 포함되는 것과 포함되지 않는 것을 설명하고, Hermes와 OpenClaw 비교에서 두 에이전트를 비교합니다. 자금이 충전된 키로 이 라우트를 테스트할 준비가 되면 Kunavo 계정을 생성하십시오.

자주 묻는 질문

Hermes Agent 문서 — 제공업체 참조, API 서버 페이지, 모델 설정 페이지, 설정 페이지, CLI 참조, 슬래시 명령 참조, 빠른 시작 및 프로젝트 홈페이지 — 를 2026년 9월 21일에 확인했습니다. 같은 날 GitHub API를 통해 저장소 상태와 최신 릴리스를 대조했습니다. Kunavo의 세 가지 API 라우트는 자체 소스에서 확인했습니다. 모든 달러 금액은 실시간 카탈로그 요금에 기반한 예시적 토큰 산술이며, 측정된 작업 비용이 아닙니다. Hermes 설정은 소스 문서에 근거해 보고하며, Kunavo에 대해 Hermes를 실행한 적은 없습니다.