Hermes Agent 연동
Nous Research의 Hermes Agent에서 베이즈 Gateway의 AI 모델을 사용하는 방법을 안내합니다.
Hermes Agent는 OpenAI Chat Completions 형식으로 Gateway의
/v1/gateway/chat/completions/를 호출합니다. 그래서 Gateway /models/ 목록의 채팅(type: llm) 모델을 사용할 수 있습니다.- 공식 레퍼런스: Hermes Agent (GitHub)
시작하기 전에 베이즈 API 키가 필요합니다. 인증 가이드에서 발급 방법을 확인해주세요.
설정
~/.hermes/config.yaml에 Gateway를 커스텀 프로바이더로 등록합니다:API 키를 설정합니다:
환경 변수
CUSTOM_BASE_URL과 OPENAI_API_KEY만으로는 연결되지 않습니다. Hermes Agent는 OPENAI_API_KEY를 openai.com 주소에만 보내고, 다른 주소에는 Bearer no-key-required를 보냅니다. 이 경우 Gateway는 401 authentication_error - Invalid API key를 반환합니다. 위처럼 providers 블록에 api_key_env를 지정해주세요.주요 형식 세부사항
| 필드 | 값 |
|---|---|
model | 기본 모델 ID. GET /v1/gateway/models/가 반환하는 ID를 그대로 씁니다 |
provider | providers 아래에 등록한 프로바이더 이름 |
providers.*.base_url | Gateway Base URL (후행 슬래시 없음) |
providers.*.api_key_env | API 키가 담긴 환경 변수 이름 |
실행
대화형으로 실행합니다:
한 번만 실행하고 끝내려면
-z를 사용합니다:모델을 바꾸려면
config.yaml의 model 값을 다른 모델 ID로 수정합니다. 도구 호출(터미널 도구의 파일 쓰기 등)도 Chat Completions 경로로 그대로 동작합니다.트러블슈팅
| 증상 | 원인 | 해결 |
|---|---|---|
401 authentication_error - Invalid API key | API 키가 전달되지 않음 | providers 블록에 api_key_env를 지정했는지, 그 환경 변수가 현재 셸에 설정되어 있는지 확인해주세요. CUSTOM_BASE_URL + OPENAI_API_KEY 조합은 동작하지 않습니다. |
402 (Credit balance exhausted) | 크레딧 잔액 없음 | 개발자 설정에서 크레딧을 충전해주세요. |
403 Model is not available through the Gateway API | 무료 모델이나 Super Agent를 지정 | 정책상 API로는 호출할 수 없습니다. 다른 유료 모델을 사용해주세요. |
404 Model not found | 존재하지 않는 모델 ID (오타·미제공 모델) | model이 Gateway /models/ 목록에 있는 ID인지 확인해주세요. |
참고
- Claude 모델도 OpenAI 호환 경로로 호출되므로 프롬프트 캐시가 적용되지 않습니다. Claude로 긴 코딩 작업을 한다면 Anthropic 형식을 쓰는 Claude Code가 입력 비용이 적게 듭니다
- 일부 GPT 모델(예:
gpt-5.6-sol)은 OpenAI 호환/chat/completions/에서 도구 호출과 추론 설정을 함께 받지 않아, Hermes Agent의 터미널·파일 도구가 동작하지 않습니다 - 전체 오류 목록은 에러 레퍼런스를 참고하세요
마지막 수정 날짜: Oct 07, 2026