구독 프록시
구독 프록시는 OpenViking, Karakeep, Open WebUI처럼 OpenAI 호환 Chat Completions를 사용하는 외부 앱이 Hermes에서 관리하는 제공자 구독을 LLM 엔드포인트로 사용할 수 있게 해 주는 로컬 HTTP 서버입니다. 프록시가 올바른 자격 증명을 첨부하고 자동으로 갱신하므로, 앱에는 고정 API 키를 넣을 필요가 없습니다.
이는 API 서버와 다릅니다:
| API 서버 | 구독 프록시 | |
|---|---|---|
| 제공 대상 | 사용자의 에이전트(전체 도구 세트, 메모리, 스킬) | 원시 모델 추론 |
| 사용 사례 | "Hermes를 채팅 백엔드로 사용" | "다른 앱에서 내 Portal 구독 사용" |
| 인증 | API_SERVER_KEY | 임의의 bearer 토큰(프록시가 실제 토큰 첨부) |
| 도구 호출 | 예 — 에이전트가 도구를 실행합니다 | 아니요 — 통과만 수행 |
백엔드로 에이전트가 필요하면 API 서버를 사용하세요. 구독을 통해 모델만 사용하고 싶다면 프록시를 사용하세요.
빠른 시작
1. 제공자 계정에 로그인하세요 (한 번만)
hermes login nous
이 명령은 Nous Portal OAuth 절차를 위해 브라우저를 엽니다. Hermes는 리프레시 토큰을
~/.hermes/auth.json에 저장합니다. 다른 Hermes 제공자 로그인도 같은 위치에 저장됩니다.
2. 프록시 시작
hermes proxy start
Starting Hermes proxy for Nous Portal
Listening on: http://127.0.0.1:8645/v1
Forwarding to: (resolved per-request from your subscription)
Use any bearer token in the client — the proxy attaches your real credential.
이 프로세스는 포그라운드에서 계속 실행해 두세요. 로그아웃 후에도 유지하려면
tmux, nohup, 또는 systemd 유닛을 사용합니다.
3. 앱이 프록시를 바라보도록 설정하세요
OpenAI 호환 앱 설정은 보통 같은 세 가지 항목을 사용합니다.
Base URL: http://127.0.0.1:8645/v1
API key: anything (e.g. "sk-unused")
Model: Hermes-4-70B # or Hermes-4.3-36B, Hermes-4-405B
프록시는 앱에서 들어오는 Authorization 헤더를 무시하고, 업스트림 요청에
실제 Portal 자격 증명을 붙입니다. bearer 토큰이 만료에 가까워지면 자동으로 갱신합니다.
사용 가능한 제공자
hermes proxy providers
현재 포함된 제공자는 nous(Nous Portal)입니다. 다른 OAuth 제공자는
hermes_cli/proxy/adapters/에서 UpstreamAdapter 인터페이스를 구현해 추가할 수 있습니다.
상태 확인
hermes proxy status
Hermes proxy upstream adapters
[nous ] Nous Portal — ready (bearer expires 2026-05-15T06:43:21Z)
not logged in이 보이면 hermes login nous를 실행하세요.
credentials need attention이 보이면 리프레시 토큰이 취소된 상태입니다
(드물지만 Portal 웹 UI에서 로그아웃하면 발생할 수 있습니다). 이 경우 hermes login nous를 다시 실행하면 됩니다.
허용된 경로
프록시는 업스트림이 실제로 제공하는 경로만 전달합니다. Nous의 경우 포털:
| 경로 | 목적 |
|---|---|
/v1/chat/completions | 채팅 완성(스트리밍 + 비스트리밍) |
/v1/completions | 레거시 텍스트 완성 |
/v1/embeddings | 임베딩 |
/v1/models | 모델 목록 |
다른 경로(/v1/images/generations, /v1/audio/speech 등)는 허용된 경로를 안내하는
명확한 오류와 함께 404를 반환합니다. 이렇게 하면 잘못 구성된 클라이언트가 이상한 요청을
업스트림으로 흘려보내는 것을 막을 수 있습니다.
OpenViking을 포털 사용으로 구성하기
OpenViking는 VLM(비전/언어 모델,
메모리 추출에 사용)과 임베딩 모델을 위해 LLM 제공자가 필요한 컨텍스트 데이터베이스입니다.
프록시를 사용하면 vlm.api_base가 로컬 프록시를 바라보게 설정할 수 있습니다.
~/.openviking/ov.conf 편집:
{
"vlm": {
"provider": "openai",
"model": "Hermes-4-70B",
"api_base": "http://127.0.0.1:8645/v1",
"api_key": "unused-proxy-attaches-real-creds"
}
}
그런 다음 터미널 두 개에서 프록시와 openviking-server를 함께 실행하세요.
# Terminal 1
hermes proxy start
# Terminal 2
openviking-server
이제 OpenViking의 VLM 호출은 Portal 구독을 통해 흐릅니다. 임베딩 모델 쪽은 여전히
자체 제공자가 필요할 수 있습니다. Portal은 /v1/embeddings를 제공하지만,
사용 가능한 모델은 구독 등급에 따라 달라지므로 portal.nousresearch.com/models에서 확인하세요.
Karakeep 또는 북마크/요약 앱 설정
Karakeep는 북마크 요약에 OpenAI 호환 API를 사용합니다. 설정에는 다음 값을 넣습니다.
# Karakeep .env
OPENAI_API_BASE_URL=http://127.0.0.1:8645/v1
OPENAI_API_KEY=any-non-empty-string
INFERENCE_TEXT_MODEL=Hermes-4-70B
같은 패턴은 Open WebUI, LobeChat, NextChat 등 다른 OpenAI 호환 클라이언트에서도 동작합니다.
LAN에서 노출
기본적으로 프록시는 127.0.0.1(로컬호스트 전용)에 바인딩됩니다.
네트워크의 다른 기기에서도 사용하게 하려면 다음처럼 실행하세요.
hermes proxy start --host 0.0.0.0 --port 8645
⚠ 주의: 이제 네트워크 안의 누구나 Portal 구독을 사용할 수 있습니다. 프록시는 자체 인증이 없으며 모든 bearer 값을 허용합니다. 신뢰 네트워크 밖으로 노출해야 한다면 적절한 인증을 갖춘 방화벽, VPN, 또는 리버스 프록시 뒤에 두세요.
요청 제한
Portal 등급의 RPM/TPM 제한은 프록시 전체에 적용됩니다. 프록시는 분산하거나 풀링하지 않습니다. 전체 구독 할당량을 가진 단일 bearer처럼 동작합니다. 사용량은 다음에서 모니터링하세요. portal.nousresearch.com.
아키텍처
프록시는 의도적으로 최소화되어 있습니다. 요청마다 다음 순서로 동작합니다.
- 앱에서
POST /v1/chat/completions받기 - 어댑터의 현재 자격 증명을 조회합니다(만료 예정이면 갱신)
- 요청 본문을 그대로 전달하되,
Authorization: Bearer <minted-key>를 붙입니다. - 응답을 변경하지 않고 다시 스트리밍합니다(SSE 유지).
변환도, 요청 본문 기록도, 에이전트 루프도 없습니다. 프록시는 자격 증명을 첨부하는 통과 장치입니다.
미래: 더 많은 OAuth 제공자
어댑터 시스템은 플러그형입니다. HuggingFace, GitHub Copilot의 채팅 엔드포인트,
OAuth 기반 Anthropic 같은 새 제공자를 추가하려면
hermes_cli/proxy/adapters/<provider>.py에서 UpstreamAdapter를 구현하고
adapters/__init__.py에 등록해야 합니다. 프로토콜 수준에서 OpenAI와 호환되지 않는
제공자(예: Anthropic Messages API)는 변환 계층이 필요하며, 이는 현재 형태의 범위를 벗어납니다.