빠른 시작
Step 1: Hermes 설치
터미널을 열고 다음 명령을 실행합니다:Linux / macOS / WSL2
Android / Termux
네이티브 Windows 시스템은 지원하지 않습니다. WSL2를 설치한 뒤 WSL2에서 Hermes Agent를 실행하세요.
Step2: 공급자 선택
설치가 완료되면 Quick setup -> More providers -> Custom endpoint를 선택합니다.
Step3: AIHubMix 파라미터 설정
- API base URL 입력:
https://aihubmix.com/v1. - AIHUBMIX_API_KEY 입력: sk-***.
- 모델 번호를 입력하여 사용할 모델을 선택합니다.
Step 4: 메시지 플랫폼 설정
필요에 따라 메시지 플랫폼을 설정합니다(Skip을 참고로 사용) -> 실행 여부(Y 선택)
Step 5: 실행 테스트
- 터미널에
hermes를 입력하여 Hermes Agent 대화 화면으로 진입합니다.
- 대화창에 내용을 입력했을 때 모델이 정상적으로 응답하면 설치가 성공한 것입니다.
공식 플러그인으로 연동하기
위의 Custom endpoint 방식은 base URL과 모델 이름을 매번 직접 입력해야 합니다. AIHubMix는 공식 model provider(모델 공급자) 플러그인을 제공합니다. 설치하면 AIHubMix가aihubmix 공급자로 Hermes에 등록되어 --provider aihubmix로 바로 호출할 수 있고, 모델 목록은 AIHubMix의 모델 카탈로그 API에서 자동으로 채워집니다. 이 플러그인은 Hermes의 코어 파일을 전혀 변경하지 않습니다.
소스 코드와 전체 설명: AIhubmix/hermes-provider-aihubmix
설치
플러그인 디렉터리를 Hermes의 model provider 디렉터리로 복사합니다.hermes plugins enable aihubmix를 실행해 plugins.enabled에 기록해야 활성화됩니다.
hermes plugins install AIhubmix/hermes-provider-aihubmix는 이 플러그인에서 동작하지 않습니다. 이 명령은 플러그인을 ~/.hermes/plugins/<저장소 이름>/에 설치하고 저장소 루트에 plugin.yaml이 없다는 경고를 표시하지만, model provider는 ~/.hermes/plugins/model-providers/에서만 검색되므로 플러그인이 등록되지 않습니다. 매니페스트 aihubmix/plugin.yaml에는 kind: model-provider가 선언되어 있으나, 이 명령은 설치 디렉터리를 정할 때 해당 필드를 읽지 않습니다. 위의 두 가지 방법 중 하나를 사용하세요. 이 동작은 Hermes 0.20.5에서 확인했습니다.API Key 설정
hermes setup은 이 환경 변수를 읽고, hermes doctor는 이를 사용해 모델 카탈로그 API 연결을 점검합니다.
사용
/model로 모델을 대화형으로 고를 수도 있습니다.
모델 목록은 AIHubMix의 모델 카탈로그 API에서 가져오며 tools 또는 function_calling이 표시된 항목만 포함합니다. 둘 중 하나만 있어도 됩니다. 이 API를 사용할 수 없으면 플러그인은 일반 /v1/models 목록으로 대체하고, 그것도 불가능하면 내장된 소수의 대체 모델 목록을 사용합니다.
AIHUBMIX_BASE_URL을 설정하면 프록시나 자체 중계 주소를 지정할 수 있습니다. 이 값이 기본 주소와 다르면 플러그인은 일반 경로인 {base_url}/models에서 모델 목록을 가져옵니다.
자주 사용하는 명령어
코드 블록자주 묻는 질문
hermes plugins install 후에 플러그인이 동작하지 않는 이유는 무엇인가요
이 명령은 플러그인을 ~/.hermes/plugins/<저장소 이름>/에 설치하지만, Hermes의 model provider는 ~/.hermes/plugins/model-providers/에서만 검색되므로 플러그인이 등록되지 않습니다. 매니페스트 aihubmix/plugin.yaml에는 kind: model-provider가 선언되어 있으나 이 명령은 설치 디렉터리를 정할 때 해당 필드를 읽지 않기 때문에 설치 자체는 성공으로 표시됩니다. 위의 디렉터리 복사 방식을 사용하거나, pip으로 설치한 뒤 hermes plugins enable aihubmix를 실행하세요.
플러그인 방식과 Custom endpoint 방식의 차이는 무엇인가요
Custom endpoint는 base URL과 모델 이름을 직접 입력해야 합니다. 플러그인은 AIHubMix를 이름이 지정된 공급자aihubmix로 등록하므로 --provider aihubmix로 바로 호출할 수 있고, 모델 목록은 AIHubMix의 모델 카탈로그 API에서 자동으로 채워지며 도구 호출을 지원하는 모델로 필터링됩니다.
/model의 모델 목록이 비어 있거나 적으면 어떻게 하나요
먼저 hermes doctor로 AIHUBMIX_API_KEY가 설정되어 있고 유효한지 확인하세요. 목록에는 tools 또는 function_calling이 표시된 모델만 포함되므로 전체 모델 수보다 적습니다. AIHUBMIX_BASE_URL이 설정되어 있고 기본 주소와 다르면 플러그인은 {base_url}/models에서 목록을 가져옵니다.
업데이트 날짜: 2026-08-25