Hermes에 OpenRouter 폴백 연결하기: 대체 모델 설정과 장애 검증 절차

AI 에이전트를 24시간 켜두면 모델 provider(모델 공급 업체)의 장애로 작업이 멈추는 경우가 생깁니다. 이번에는 OpenRouter를 Hermes의 fallback(대체 모델 전환) 후보로 연결하고 실제 전환을 확인하는 방법을 정리했습니다. 후보를 여러 개 등록하는 것과 한 작업에서 후보 전부를 차례로 실행하는 것은 서로 다른 동작입니다. 설정하기 전에 이 차이부터 확인해야 합니다.

지난 글에서는 에이전트 설정을 GitHub에 자동 백업하는 방법을 다뤘습니다. 백업이 데이터 손실에 대비하는 작업이라면, 이번 폴백 설정은 모델 장애에 대비하는 작업입니다.

AI 에이전트 설정 GitHub 자동 백업

아래 화면과 선택 모델은 당시 운영 기록입니다. 2026년 9월 16일에는 공식 문서의 설정 명령과 turn 단위 동작을 재확인했습니다. 과거에 선택한 모델이 지금도 제공된다는 뜻은 아닙니다. 가격·무료 제공 여부는 현재 모델 카탈로그와 결제 화면에서 확인하세요.

폴백이 필요한 경우

제 에이전트의 메인 provider는 OpenAI Codex입니다. 메인 provider 하나만 등록하면 다음 상황에서 작업이 멈출 수 있습니다.

• 해당 provider의 서버가 죽는 경우
• 구독한 플랜이 만료되는 경우
• 예고 없이 생기는 불의의 이슈

에이전트를 대화형으로만 사용한다면 직접 다시 실행할 수 있습니다. 하지만 자리를 비운 시간에도 돌아가야 하는 자동화는 바로 대응하기 어렵습니다. 새벽 작업이 멈추면 아침에야 확인하게 됩니다. LLM 폴백을 설정하면 메인이 실패했을 때 다음 모델로 전환해 작업을 이어갈 수 있습니다.

다만 새벽 자동화를 cron(예약 작업)으로 돌린다면 하나 확인할 것이 생겼습니다. Hermes 저장소에 2026-09-23 반영된 변경("a pinned job never falls back to the global fallback chain")으로, 작업 자체에 provider나 model을 고정해 둔(pinned) cron 작업은 전역 폴백 체인으로 넘어가지 않습니다. 현재 공식 문서도 "고정하지 않은(unpinned) 작업만 설정한 체인을 물려받는다"고 적고 있습니다. 폴백이 필요한 예약 작업은 작업에 모델을 박아 두지 말고 cron.model·cron.model_provider 설정으로 모델을 고르라는 것이 문서의 안내입니다.

Hermes 공식 문서의 fallback provider 목록에는 OpenRouter, OpenAI Codex, Anthropic, Kimi·Moonshot 등이 올라와 있습니다. 이 중 하나의 계정에서 여러 모델 후보를 비교하기 쉬운 선택지가 OpenRouter입니다.

OpenRouter의 역할

OpenRouter는 여러 모델 제공자를 하나의 API와 결제 계정으로 연결하는 gateway(중개 계층)입니다. 실제 요청은 선택된 provider endpoint로 전달됩니다. 따라서 처리 지역과 데이터 보존 정책은 모델과 provider별로 확인해야 합니다. 계정을 각각 만들지 않고 대체 모델을 비교할 수 있다는 점은 폴백 구성에서 편리했습니다.

가격 비교는 모델 카탈로그에서 볼 수 있습니다. 입력·출력 토큰 가격을 따로 확인하고, 같은 계열명이라도 정확한 모델 ID와 provider를 기록해 둡니다. 아래 화면은 영상 촬영 당시의 예시입니다. 현재 비용 계산에는 선택할 모델의 현재 표시 가격을 사용하세요.

OpenRouter 사용법 1단계: 가입과 API 키 발급

가입 후 다음 순서로 설정합니다.

1. OpenRouter에 가입하고 로그인합니다.
2. Credits 메뉴에서 Add credit을 눌러 충전합니다. 카드 외에 암호화폐 충전도 지원합니다.
3. API keys 메뉴에서 키를 발급하고 복사해 둡니다.

유료 폴백에 쓸 잔액과 무료 모델의 사용 한도는 별개입니다. 결제하기 전에 공식 FAQ와 Credits 화면에서 최소 충전액·수수료·만료 조건을 확인하세요. 무료 모델도 별도 한도가 있으며 구매 이력에 따라 달라질 수 있습니다. 과거 영상에 표시된 금액을 현재 결제 조건으로 사용하지 마세요.

키 이름은 나중에 알아볼 수 있게 짓는 편이 낫습니다. 저는 어느 기기에 붙인 키인지 구분하려고 Hermes Hostinger처럼 용도와 환경을 이름에 넣습니다.

무료 모델 선택 시 확인할 내용

모델 목록에는 free 표시가 붙은 모델도 있습니다. 다만 무료 모델은 목록과 가용성이 자주 바뀌고 기본 rate limit도 낮아 운영용 폴백 하나만 두기에는 불안정합니다. 당시 사용한 Owl Alpha처럼 무료 후보라도 provider가 입력·출력을 기록하는지 먼저 확인해야 합니다. 현재 제공 여부와 데이터 정책은 provider logging 안내와 선택할 endpoint에서 확인합니다. 따라서 비밀값이나 고객 데이터가 들어가는 자동화에는 사용하지 않습니다.

무료 모델은 이렇게 다루는 편이 안전합니다.

무료 모델도 시험용 후보로 사용할 수 있습니다. 다만 무료 모델 하나만 등록하면 가용성과 데이터 정책을 보장하기 어렵습니다. 민감하지 않은 작업으로 먼저 확인하고, 운영 데이터에는 별도 허용 목록을 두는 편이 안전합니다.

hermes fallback add로 후보 등록

Hermes를 빠져나온 뒤 터미널에서 다음 명령어를 실행합니다.

hermes fallback add

실행하면 provider 목록이 나타납니다. 최초 설정에서 메인으로 선택한 OpenAI Codex가 첫 번째에 있고, 여기에 OpenRouter를 후보로 추가할 수 있습니다. OpenRouter를 선택해 API 키를 등록하면 모델 선택 화면으로 넘어갑니다. 저는 테스트 당시 Owl Alpha를 골랐습니다. 현재 가용성과 logging 정책은 등록하기 전에 다시 확인해야 합니다.

다른 후보를 추가할 때도 같은 명령을 한 번 더 실행합니다. 후보를 두 개 등록했다고 해서 한 요청에서 두 모델이 모두 차례로 호출되는 것은 아닙니다.

hermes fallback add

두 번째 실행부터는 Keep, Replace, Clear 중 하나를 선택하게 됩니다. 같은 OpenRouter 키를 계속 사용한다면 K를 눌러 Keep을 선택합니다. 이어지는 모델 선택 화면에서는 무료가 아닌 저가 유료 모델을 고를 수 있습니다. 저는 테스트 당시 DeepSeek V4 Pro를 다음 후보로 등록했습니다.

이 설정에는 제한이 있습니다. Hermes 공식 문서에 따르면 fallback_providers는 순서가 있는 후보 목록이지만 실제 전환은 turn 단위로 일어납니다. 한 turn 안에서 fallback switch는 최대 한 번입니다. 선택된 fallback 호출까지 실패하면 일반 오류 처리로 끝날 수 있습니다. 다음 사용자 메시지에서는 primary를 다시 시도하지만, 알려진 사용량 제한의 초기화 시각이 지나지 않았다면 fallback을 유지하는 예외가 있습니다.

이 동작은 OpenRouter API의 models 배열을 이용한 model fallback과 구분해야 합니다. Hermes의 후보를 추가했다고 OpenRouter의 별도 요청 옵션까지 설정되는 것은 아닙니다.

fallback list와 remove로 후보 관리

등록 결과는 목록에서 확인합니다.

hermes fallback list

메인 모델과 그 아래의 fallback chain이 순서대로 표시됩니다. 제 경우 메인은 GPT-5.5 Codex, 첫 번째 대체 후보는 무료 모델, 두 번째 후보는 비용이 조금 드는 모델로 나왔습니다. 이 화면을 캡처해 두면 무료 모델 제공이 끝났을 때 교체할 대상을 확인하기 쉽습니다.

아래 캡처의 출력 부분을 복사할 수 있게 텍스트로 옮기면 다음과 같습니다(당시 VPS의 /opt/hermes에서 실행).

root@...:/opt/hermes# hermes fallback list

  Primary: gpt-5.5  (via openai-codex)

  Fallback chain (2 entries):
    1. openrouter/owl-alpha  (via openrouter)  [https://openrouter.ai/api/v1]
    2. deepseek/deepseek-v4-pro  (via openrouter)  [https://openrouter.ai/api/v1]

  Tried in order when the primary fails (rate-limit, 5xx, connection errors).

마지막 줄이 폴백이 언제 동작하는지에 대한 Hermes 자신의 설명입니다. 사용 한도 초과(rate-limit), 서버 오류(5xx), 연결 오류일 때 1번부터 차례로 시도합니다.

빼고 싶은 모델이 생기면 제거합니다.

hermes fallback remove

저가 모델의 한계

제 환경에서는 Hermes의 복잡한 작업에 가장 싼 모델을 쓰면 지시 누락이 늘었습니다. 이건 모든 모델에 적용되는 보편 법칙이 아니라 작업별로 다시 검증해야 할 관찰입니다.

skill을 하나만 호출하는 단순한 작업에서는 저가 모델도 사용할 만했습니다. 하지만 여러 skill을 함께 실행하면 결과가 달라졌습니다. 여러 skill이 context window(모델이 한 번에 읽어 들이는 작업 공간)에 한꺼번에 올라가면서 지시를 빠뜨리거나 중간 단계를 건너뛰는 경우가 생겼습니다. 이런 작업에서는 어느 정도 성능이 있는 모델이 필요했습니다.

제가 구성한 폴백 체인의 목적은 비용 절감보다 작업 중단 시간을 줄이는 데 있습니다. 메인 모델이 돌아올 때까지 자동화가 완전히 멈추지 않게 하는 설정입니다. 이때 대체 모델의 결과 품질이 메인과 같은지는 별도로 확인해야 합니다.

2026-10-02 다시 확인한 모델 상태

위 체인을 만든 지 몇 주 만에 상황이 바뀌어서 기록해 둡니다. OpenRouter는 키 없이도 공개 모델 목록을 조회할 수 있어서, 등록한 후보가 아직 살아 있는지 명령 한 줄로 확인할 수 있습니다.

curl -s https://openrouter.ai/api/v1/models | python3 -c "
import json,sys
ids={m['id']:m for m in json.load(sys.stdin)['data']}
print(len(ids), 'models /', sum(i.endswith(':free') for i in ids), 'free')
for want in ['openrouter/owl-alpha','deepseek/deepseek-v4-pro']:
    m=ids.get(want)
    print(want, '->', '없음' if not m else m['pricing']['prompt']+' / '+m['pricing']['completion'])
"

2026-10-02에 돌린 결과입니다.

465 models / 17 free
openrouter/owl-alpha -> 없음
deepseek/deepseek-v4-pro -> 0.0000002088 / 0.0000004176

• 1번 후보였던 무료 모델 openrouter/owl-alpha는 목록에서 사라졌습니다. 체인에 남겨 두면 1번에서 실패한 뒤 2번으로 넘어가므로 바로 작업이 멈추지는 않지만, 한 단계를 헛도는 셈이라 교체하거나 지우는 게 맞습니다. 위에서 "무료 모델은 목록과 가용성이 자주 바뀐다"고 쓴 내용이 몇 주 만에 실제로 일어났습니다.
• 2번 후보 DeepSeek V4 Pro는 남아 있지만 가격이 바뀌었습니다. 응답의 가격은 토큰 1개당 달러라서 100만을 곱하면 입력 약 $0.21, 출력 약 $0.42 / 100만 토큰입니다. 위 가격 비교 캡처(입력 $0.435, 출력 $0.87)의 절반 수준입니다. 같은 계열에 deepseek-v4-pro-0813, deepseek-v4.1-flash 같은 새 ID도 생겼습니다.

이 확인을 예약 작업으로 걸어 두면, 후보가 사라졌을 때 장애가 나기 전에 먼저 알 수 있습니다.

장애 상황과 결과 검증

fallback list는 후보가 저장됐는지만 보여줍니다. 실제 작업이 대체 모델에서 끝나는지는 별도로 시험해야 합니다. 운영 키를 폐기하거나 운영 서비스를 끊지 말고, 외부 발송과 파일 변경을 비활성화한 시험 환경에서 오류 응답을 재현합니다. 다음 표는 실행할 검증 시나리오이며 실제 통과 결과는 아닙니다.

시험 입력은 “다음 세 문장을 각각 한 줄로 요약하되 원문의 숫자를 보존하라”처럼 정답 조건을 확인하기 쉬운 것으로 시작합니다. 그다음 실제 자동화와 같은 출력 형식과 도구 사용이 필요한 시험으로 넓힙니다. 민감 정보는 가상 값으로 바꿉니다. 응답이 왔다는 사실만으로 기존 작업 품질을 유지했다고 볼 수 없습니다.

외부 발송이 있는 작업은 재시도 때 같은 메시지를 두 번 보내지 않는지도 별도로 검증해야 합니다. 모델 전환과 업무 전체의 재실행은 다르기 때문입니다. 전환 시각·작업 ID·사용 모델을 남기되 로그에 API 키나 고객 원문을 넣지 않습니다. 호출 비용과 사람이 수정한 시간까지 확인한 뒤 운영 후보를 선택하세요.

시험 환경에서 남길 최소 기록

이 글의 장애 표는 실제 통과 로그가 아니라 검증 절차입니다. 운영 provider를 끊거나 키를 폐기하지 말고, 메신저·예약 작업·외부 발송을 연결하지 않은 별도 시험 환경에서 진행하세요.

1. hermes --version과 hermes fallback list 결과를 저장하고, 시험할 대체 후보 하나를 확인합니다. 키 값은 기록하지 않습니다.
2. 정상 상태에서 “사과 3개, 배 2개를 JSON으로 정리하라”처럼 기대 값이 명확한 입력을 보냅니다. 숫자와 JSON 구조를 직접 확인합니다.
3. 시험 환경의 primary endpoint가 인증 오류를 반환하도록 구성한 뒤 같은 입력을 다시 보냅니다. 인증 오류는 즉시 전환 대상이라는 공식 동작 설명과 실제 로그를 대조합니다. endpoint 설정 방법은 사용하는 provider에 따라 다릅니다.
4. 전환 알림, 실제 provider/model, 응답과 소요 시간을 함께 기록합니다. 목록에 후보가 있다는 사실만으로 성공 처리하지 않습니다.
5. 시험 설정을 정상으로 되돌린 뒤 새 메시지를 보냅니다. primary 복귀 여부와 제한 초기화 시각에 따른 예외를 확인합니다.

아래는 복사해서 채울 기록 양식입니다. 빈칸을 예시 성공 값으로 채우지 않았습니다.

검증 시각 / Hermes 버전:
시험 환경 / 외부 작업 비활성화 확인:
primary provider:model / 대체 후보 provider:model:
입력 / 기대 출력:
primary 오류 종류:
실제 전환 알림 / 선택 모델:
실제 출력 / 누락·형식 오류 / 소요 시간:
다음 메시지의 primary 복귀 여부:
판정: 통과 / 실패 / 미실행

HTTP 오류가 발생했는지, 모델 전환이 됐는지, 업무 결과가 맞는지를 따로 판정합니다. 이 글은 설정과 검증 절차를 제공하며 독자 환경의 전환 성공까지 보장하지 않습니다.

환경에 따른 폴백 구성

저는 로컬 mini PC와 VPS 두 곳에서 에이전트를 돌리고 있습니다. 두 환경 모두 폴백을 걸어두지만 판단 기준은 다릅니다.

• 자동화 규모가 작고 언제든 직접 다시 돌릴 수 있는 환경이라면 무료 모델 하나만 걸어두거나 아예 안 걸어도 큰 문제는 없습니다.
• 자리를 비운 사이에도 돌아야 하는 작업이라면 개인정보 처리 정책을 확인한 유료 후보를 포함하고, 장애 상황을 강제로 만들어 실제 전환을 시험합니다.
• 여러 skill이 얽힌 복잡한 작업이 메인이라면 대체 후보는 가격만으로 정하지 말고 실제 작업의 지시 준수와 도구 실행을 확인하는 편이 낫습니다. 후보 순서가 한 turn 안에서 모두 호출된다는 뜻은 아닙니다.

폴백 구성은 작업 환경에 따라 달라집니다. 작업이 멈췄을 때 몇 시간까지 기다릴 수 있는지 먼저 계산하고, 그 시간에 맞춰 체인을 구성하는 편이 좋습니다.

전체 세팅 과정은 원본 영상에서 화면으로 확인할 수 있습니다.

원본 영상에서 전체 과정 보기

다음 글 예고 & Reference

CLAUDE.md를 5가지 기준으로 진단하고 개선하는 방법도 함께 확인하세요. 대체 모델이 지시를 빠뜨릴 때는 모델 비교와 함께 프로젝트 규칙이 분명한지도 살펴볼 수 있습니다.

Reference

• Hermes 공식 문서: Fallback Providers
• OpenRouter FAQ: 가격·수수료·무료 한도
• OpenRouter Free Models Router
• OpenRouter provider logging
• OpenRouter model catalog
• 원본 영상: 왕초보를 위한 24/7 돌아가는 Hermes Agent 전체 설정 튜토리얼
• 관련 글: AI 에이전트 설정을 GitHub에 안전하게 백업하기