Hermes 프로바이더 정리 및 로컬 모델 설정

Hermes 프로바이더 정리 및 로컬 모델 설정

[!note] 수정이력

날짜	작성자	내용
2026-05-03 16:00	루키 (hermes)	최초 작성

개요

Hermes /model 피커에 잡다한 프로바이더가 전부 노출되는 문제를 해결하고, 로컬 모델 설정을 정상화한 작업 기록.

---

1. 문제: /model 피커에 불필요한 프로바이더 표시

원인

Hermes /model 피커는 list_authenticated_providers() 함수를 통해 자격증명이 있는 모든 프로바이더를 자동 발견함. 이 감지 경로가 5중으로 겹쳐 있음:

1. PROVIDER_TO_MODELS_DEV — models.dev 매핑 (소스 코드 하드코딩)
2. HERMES_OVERLAYS — Hermes 전용 프로바이더 오버레이
3. CANONICAL_PROVIDERS — 정식 프로바이더 목록 (31개 하드코딩)
4. auth.json의 credential_pool — 과거 사용 자격증명 잔류
5. 환경변수 — .hermes/.env에 설정된 API 키

model_catalog.providers 화이트리스트는 원격 매니페스트 캐시용이라 피커 필터링에 영향 없음.

해결: 자격증명 제거

자격증명이 없는 프로바이더는 has_creds=False가 되어 피커에서 자동 숨김 처리됨.

1) .hermes/.env 에서 불필요한 API 키 제거

# 제거할 키
GEMINI_API_KEY=***
OPENROUTER_API_KEY=***
KIMI_API_KEY=***

# 유지할 키
TELEGRAM_BOT_TOKEN=...
TELEGRAM_ALLOWED_USERS=...
TELEGRAM_HOME_CHANNEL=...
OLLAMA_API_KEY=...
OLLAMA_BASE_URL=https://ollama.com/v1

수정 방법:

# 백업
cp ~/.hermes/.env ~/.hermes/.env.bak.20260503

# .env 파일에서 해당 라인 삭제 후 저장

2) auth.json의 credential_pool에서 불필요 항목 제거

# 백업
cp ~/.hermes/auth.json ~/.hermes/auth.json.bak.20260503

import json

with open("~/.hermes/auth.json", "r") as f:
    data = json.load(f)

pool = data.get("credential_pool", {})
for k in list(pool.keys()):
    if k in ("gemini", "openrouter"):
        del pool[k]

with open("~/.hermes/auth.json", "w") as f:
    json.dump(data, f, indent=2)
    f.write("\n")

3) config.yaml의 providers 섹션에서 중복 제거

providers.ollama와 CANONICAL_PROVIDERS의 ollama-cloud가 같은 엔드포인트(ollama.com/v1)를 가리켜서 피커에 Ollama Cloud (40) + ollama (39) 중복 표시됨.

# providers.ollama 섹션 삭제 (CANONICAL_PROVIDERS가 자동 감지하므로 불필요)

import yaml

with open("~/.hermes/config.yaml", "r") as f:
    config = yaml.safe_load(f)

if "providers" in config and "ollama" in config["providers"]:
    del config["providers"]["ollama"]

with open("~/.hermes/config.yaml", "w") as f:
    yaml.dump(config, f, default_flow_style=False, sort_keys=False, allow_unicode=True)

4) 게이트웨이 재시작

# WSL systemd
sudo -u pinksky bash -c 'export XDG_RUNTIME_DIR=/run/user/$(id -u pinksky); systemctl --user restart hermes-gateway'

# macOS LaunchAgent
launchctl kickstart -k gui/$(id -u)/com.hermes.gateway

결과

정리 전	정리 후
Ollama Cloud (40)	Ollama Cloud (40)
ollama (39)	삭제
OpenRouter (34)	삭제
Google (9)	삭제
Kimi For Coding (7)	삭제
Local (localhost:11434) (1)	Local (localhost:11434) (3)

---

2. 문제: 로컬 모델 선택 시 에러

증상

Error: Model gemma4-a4b-agent:latest was not found in this provider's model listing.

원인

custom_providers에 설정된 model: gemma4-a4b-agent:latest가 로컬 Ollama에 존재하지 않음. 또한 gemma4:31b는 19GB로 RTX 3080 12GB VRAM에서 구동 불가.

해결: 실제 로컬 모델 목록 확인 후 설정

1) 로컬 Ollama 모델 확인

curl -s http://localhost:11434/api/tags | python3 -c 'import json,sys; data=json.load(sys.stdin); [print(m["name"]) for m in data.get("models",[])]'
# 또는
ollama list

2) VRAM에 맞는 모델 선별

RTX 3080 12GB 기준:

모델	크기	VRAM 적합
qwen3.5:latest	6.6GB	✅ 추천
llama3.1:latest	4.9GB	✅ 가능
llama3.2:latest	2.0GB	✅ 경량
gemma4:31b	19GB	❌ VRAM 초과

3) custom_providers 수정

import yaml

with open("~/.hermes/config.yaml", "r") as f:
    config = yaml.safe_load(f)

for cp in config.get("custom_providers", []):
    if cp.get("name") == "Local (localhost:11434)":
        cp["model"] = "qwen3.5:latest"           # 기본 모델
        cp["models"] = {                           # /model에서 선택 가능한 목록
            "qwen3.5:latest": {},
            "llama3.1:latest": {},
            "llama3.2:latest": {}
        }

with open("~/.hermes/config.yaml", "w") as f:
    yaml.dump(config, f, default_flow_style=False, sort_keys=False, allow_unicode=True)

수정 후 config.yaml의 custom_providers는 다음과 같아야 함:

custom_providers:
- api_key: <OLLAMA_API_KEY>
  base_url: http://localhost:11434/v1
  model: qwen3.5:latest
  name: Local (localhost:11434)
  models:
    qwen3.5:latest: {}
    llama3.1:latest: {}
    llama3.2:latest: {}

4) 게이트웨이 재시작

sudo -u pinksky bash -c 'export XDG_RUNTIME_DIR=/run/user/$(id -u pinksky); systemctl --user restart hermes-gateway'

---

3. 빠른 참조: 프로바이더·로컬모델 변경 체크리스트

프로바이더 추가/제거 시

1. ~/.hermes/.env에서 해당 API 키 추가/제거
2. ~/.hermes/auth.json의 credential_pool에서 항목 추가/제거
3. ~/.hermes/config.yaml의 providers/custom_providers 수정
4. 게이트웨이 재시작

로컬 모델 추가/변경 시

1. ollama list로 설치된 모델 확인
2. VRAM 용량 확인 (12GB 초과 시 구동 불가)
3. config.yaml의 custom_providers[].model (기본) 및 models (선택 목록) 수정
4. 게이트웨이 재시작

---

4. 관련 소스 코드 위치

파일	내용
hermes_cli/model_switch.py L981	list_authenticated_providers() — /model 피커 메인 로직
hermes_cli/models.py L768	CANONICAL_PROVIDERS — 정식 프로바이더 31개 하드코딩
hermes_cli/auth.py	PROVIDER_REGISTRY — 프로바이더별 인증 설정
hermes_cli/model_catalog.py	원격 매니페스트 캐시 (model_catalog.providers는 피커 필터링 무관)

---

5. 적용 대상

노드	상태	비고
하늘 (보조컴 WSL, MH-3900x)	✅ 완료	RTX 3080 12GB
분홍 (메인컴 WSL, PS-i14700k)	⏳ 대기	동일 작업 필요
루키 (맥미니 M4 Pro)	N/A	로컬 GPU 없음, Cloud만 사용