BEGINNER WALKTHROUGH  ·  WINDOWS POWERSHELL

실제 화면 6장으로 API 확인부터 연결 검증까지 따라 하는 초보자 가이드

작성 기준  2026.08.22   |   예상 소요  10분   |   환경  Windows PowerShell

이 글은 C:Userssoundopenrouter-ox-alpha 폴더에서 ox_alpha.py 호출이 성공한 다음, 같은 OpenRouter API를 Hermes Agent에 연결해 기본 모델을 stealth/ox-alpha로 바꾸는 과정을 다룹니다.

먼저 구조부터 한눈에 보기

Hermes Agent는 질문과 도구 사용을 관리하고, OpenRouter는 그 요청을 선택한 모델인 Ox Alpha로 전달합니다.

핵심 원칙 — 숫자보다 이름을 본다

캡처에서는 OpenRouter가 3번, stealth/ox-alpha가 35번이지만 Hermes 버전에 따라 번호와 가격 표시는 달라질 수 있습니다. 언제나 OpenRouter와 stealth/ox-alpha라는 이름을 기준으로 선택하세요.

0. PowerShell을 열고 작업 폴더로 이동하기

터미널이 낯설다면 Windows 시작 버튼을 누르고 PowerShell을 검색한 뒤 Windows PowerShell 또는 터미널의 PowerShell 탭을 여세요.

프롬프트가 아래처럼 이미 프로젝트 폴더를 가리키면 이동 명령은 생략해도 됩니다.

  PS C:Userssoundopenrouter-ox-alpha> 

다른 폴더에 있다면 다음 명령으로 이동합니다.

  cd "$HOMEopenrouter-ox-alpha" 

파일이 있는지 확인하려면 다음 명령을 입력합니다.

  Get-ChildItem 

1. 먼저 ox_alpha.py로 API가 작동하는지 확인하기

..venv\Scripts\python.exe .\ox_alpha.py

Ox Alpha의 최종 답변이 출력되면 Python 가상환경, 스크립트, OpenRouter 호출이 모두 정상이라는 뜻입니다. 바로 아래에서 hermes model을 실행해 Hermes 설정으로 넘어갑니다.

그림 1. ox_alpha.py 호출 성공 후 hermes model을 실행한 화면. 변경 전 모델이 glm-5.2여도 오류가 아닙니다.

2. Hermes의 모델 선택기를 열기

  hermes model 

Current model과 Active provider는 지금까지 쓰던 설정입니다. 캡처의 glm-5.2 / Z.AI는 곧 OpenRouter / Ox Alpha로 바뀔 예정이므로 그대로 진행합니다.

3. Provider에서 OpenRouter 선택하기

Select provider 목록에서 OpenRouter를 찾습니다. 이 화면에서는 3번이므로 3을 입력하고 Enter를 누릅니다. 다른 버전에서는 번호가 바뀔 수 있습니다.

그림 2. Provider 선택 목록. 이 캡처에서는 OpenRouter가 3번입니다.

4. OpenRouter API 키 붙여넣기

키가 없다면 OpenRouter API Keys 페이지에서 새 키를 만든 뒤 복사합니다. Hermes가 OPENROUTER_API_KEY를 요청하면 키를 붙여넣고 Enter를 누릅니다.

붙여넣은 키가 별표로 가려지거나 화면에 거의 보이지 않는 것은 정상입니다. API key saved.가 나오면 저장이 끝난 것입니다.

그림 3. OpenRouter API 키 입력과 저장 완료 화면. 실제 키는 별표로 가려져 있습니다.

보안 주의

블로그 캡처에는 sk-or-로 시작하는 실제 키가 한 글자도 보이면 안 됩니다. 유출했다면 OpenRouter 대시보드에서 즉시 해당 키를 폐기하고 새 키를 만드세요.

5. 모델 목록에서 stealth/ox-alpha 선택하기

모델 목록에서 stealth/ox-alpha를 찾습니다. 이 캡처에서는 35번이고 가격 열에 free가 표시되어 있지만, 번호·가격·제공 여부는 시점에 따라 달라질 수 있습니다.

1.    목록에서 stealth/ox-alpha가 보이면 그 항목의 번호를 입력하고 Enter를 누릅니다.

2.    목록에 없다면 Enter custom model name을 선택합니다.

3.    직접 입력 창에 stealth/ox-alpha를 정확히 입력합니다.

그림 4. 모델 목록의 stealth/ox-alpha. 이 캡처에서는 35번이며 free로 표시됩니다.

모델 ID를 그대로 입력하세요

Ox Alpha, ox-alpha처럼 짧게 쓰지 말고 OpenRouter 형식인 stealth/ox-alpha 전체를 입력하는 것이 안전합니다.

6. Hermes Agent 시작 화면 확인하기

선택이 끝나면 Hermes가 바로 열릴 수 있습니다. 열리지 않으면 아래 둘 중 하나를 실행하세요.

  hermes 

  hermes --tui 

시작 화면 왼쪽 아래에 ox-alpha가 보이면 선택한 모델이 적용된 것입니다. 현재 작업 폴더도 C:\Users\sound\openrouter-ox-alpha로 표시됩니다.

그림 5. Hermes Agent 시작 화면. 왼쪽 아래의 ox-alpha 표시로 선택 모델을 확인할 수 있습니다.

화면 아래의 262 commits behind는 연결 실패가 아니라 업데이트 알림입니다. API 설정을 검증한 뒤 별도로 업데이트해도 됩니다.

7. 실제 대화로 연결 상태 검증하기

Hermes 입력창에 다음처럼 물어봅니다.

현재 사용 중인 provider와 model 이름을 정확히 알려줘.

아래 두 줄이 나오면 목표한 연결이 완료된 것입니다.

Provider

openrouter

Model

stealth/ox-alpha

그림 6. Hermes가 현재 provider는 openrouter, model은 stealth/ox-alpha라고 답한 연결 확인 화면.

가장 확실한 확인법

대화 속 자기 보고만 보지 말고 Hermes 화면의 모델 표시와 hermes model의 현재 설정도 함께 확인하세요. 세 곳이 모두 OpenRouter / stealth/ox-alpha를 가리키면 됩니다.

Python 테스트와 Hermes 설정은 왜 둘 다 필요한가

ox_alpha.py는 내 OpenRouter 키와 API 호출 코드가 정상인지 확인하는 독립 테스트입니다. Hermes Agent는 자신의 설정 저장소를 사용하므로 Python 스크립트가 성공했더라도 hermes model 안에서 키와 모델을 한 번 더 지정해야 합니다.

문제가 생겼을 때

빠른 재실행 명령

다음 날 다시 사용할 때는 프로젝트 폴더로 이동한 뒤 Hermes만 실행하면 됩니다.

  cd "$HOMEopenrouter-ox-alpha" 

  hermes --tui 

이미 OpenRouter 키와 모델이 저장되어 있다면 hermes model을 매번 다시 실행할 필요는 없습니다.

고급 사용자를 위한 한 줄 실행

OpenRouter 키가 Hermes에 저장된 뒤라면 다음처럼 provider와 model을 명시해 채팅을 시작할 수도 있습니다.

  hermes chat --provider openrouter --model stealth/ox-alpha 

마무리

정리하면 순서는 간단합니다. PowerShell에서 프로젝트 폴더를 확인하고, ox_alpha.py로 API를 시험한 뒤, hermes model에서 OpenRouter와 stealth/ox-alpha를 차례로 선택합니다. 마지막으로 Hermes 화면과 대화 응답에서 provider와 model을 확인하면 연결이 끝납니다.

공식 참고 자료

·      OpenRouter 공식 — Hermes Agent 연동 가이드

·      OpenRouter — API 키 관리

·      OpenRouter — 모델 목록

·      Nous Research — Hermes Agent GitHub

추천 해시태그

#OpenRouter #OxAlpha #HermesAgent #NousResearch #AI에이전트 #생성형AI #LLM #API연결 #OpenAI호환API #윈도우PowerShell #파워셸 #코딩에이전트 #AI자동화 #무료AI모델 #AI튜토리얼 #초보자AI #터미널사용법 #모델설정 #개발도구 #에이전트워크플로