지난 글에서는 OpenRouter 가입부터 Credits 충전, API Key 발급과 사용 한도 설정까지 정리했습니다.

이번 글에서는 실제 Agent를 설치하고 OpenRouter와 연결합니다.

전체 구조는 다음과 같습니다.

[OpenRouter]
     │
     │ API Key
     ▼
[Hermes Agent]
     │
     │ Model
     ▼
[DeepSeek V4 Flash]
     │
     ▼
[LLM Response]

Hermes Agent를 설치하고 → OpenRouter를 Provider로 등록하고 → 선택한 LLM을 연결한 뒤 → 실제 대화까지 성공시키는 것

1. Hermes Agent란?

Hermes Agent는 Nous Research가 개발한 오픈소스 AI Agent입니다.

단순한 대화형 챗봇이 아니라 터미널, 파일 작업, 웹 관련 기능, 메모리, Skills 등의 도구를 이용해 여러 단계의 작업을 수행할 수 있도록 설계되어 있습니다.

현재 공식 문서에서는 Hermes를 self-improving AI agent로 소개하고 있으며, 경험을 바탕으로 Skill을 만들고 지속적인 메모리를 활용하는 구조를 제공합니다.

이번 시리즈에서 Hermes Agent를 선택한 이유는 단순히 모델의 답변 품질을 확인하기 위해서가 아닙니다.

앞선 글에서 비교했던 LLM을 실제 Agent 환경에서 사용하고,

Tool Calling
파일 작업
터미널 작업
다단계 추론
반복적인 API 호출
실제 작업 성공 여부
작업당 비용

을 직접 측정하기 위한 테스트 환경으로 사용합니다.

2. 설치 전에 확인할 것

현재 Hermes Agent는 다음 환경에서 설치할 수 있습니다.

Windows
macOS
Linux
WSL2
Android / Termux

공식 문서에서는 Windows와 macOS 사용자의 경우 Hermes Desktop 설치 프로그램을 제공하며, CLI만 사용하는 경우 별도의 설치 명령을 제공합니다.

이번 글에서는 CLI 로 설치를 하겠습니다.

Windows 사용자는 PowerShell에서 설치할 수 있고, Linux/macOS/WSL2에서는 공식 설치 스크립트를 사용할 수 있습니다.

3. Hermes Agent 설치

Step 1. Windows 설치

Windows에서는 PowerShell 또는 Windows Terminal을 실행합니다.

다음 명령을 입력합니다.

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

공식 Windows 설치 프로그램은 관리자 권한 없이 설치할 수 있으며 기본적으로 사용자 영역에 Hermes를 설치합니다. 설치가 완료되면 새로운 터미널을 열어 PATH 변경사항을 적용합니다.

설치가 완료되었다면 다음 명령으로 정상 설치 여부를 확인합니다.

hermes --help 또는 hermes --version

정상적으로 설치되었다면 Hermes CLI 관련 정보가 출력됩니다.

4. Linux / macOS / WSL2 설치

Linux, macOS 또는 WSL2에서는 공식 설치 스크립트를 사용합니다.

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

공식 문서에 따르면 일반적인 Linux/macOS 설치에서는 Git이 필요하며, Linux에서는 curl과 xz-utils도 필요합니다. Python, Node.js, ripgrep, ffmpeg 등은 설치 프로그램이 필요한 경우 자동으로 처리합니다.

설치가 끝나면 Shell을 다시 로드합니다 : source ~/.bashrc

(zsh를 사용한다면: source ~/.zshrc)

그다음 설치 여부를 확인합니다: hermes --version

5. 설치 과정에서 Python을 직접 설치해야 할까?

일반적인 설치라면 별도로 Python 환경을 먼저 만들 필요가 없습니다.

현재 Hermes 설치 프로그램은 uv를 이용해 Python 환경을 구성하고 필요한 의존성을 설치합니다.

공식 설치 문서에서는 Python 3.11을 설치 프로그램이 관리하며, Node.js, ripgrep, ffmpeg 등의 필요한 구성요소도 환경에 맞게 처리한다고 설명합니다.

따라서 처음 설치하는 경우 다음과 같은 방식으로 직접 환경을 구성할 필요가 없습니다.

Python 설치
   ↓
venv 생성
   ↓
pip install
   ↓
Node.js 설치
   ↓
추가 패키지 설치

현재 공식 Installer를 사용하는 것이 더 간단합니다.

6. 설치 후 가장 먼저 할 일: hermes doctor

설치가 완료되었다면 다음 명령을 실행합니다 : hermes doctor

hermes doctor는 Hermes 실행에 필요한 환경과 설정 상태를 진단하는 명령입니다.

설치 문제나 환경 문제를 확인할 때 hermes doctor를 사용합니다.

처음 설치한 경우 일부 Provider나 API Key가 설정되지 않았다는 메시지가 표시될 수 있습니다.

이것은 설치 실패와는 다른 문제입니다.

현재 단계에서는 다음 두 가지를 구분해야 합니다.

Hermes 프로그램 설치
        ↓
정상
        ↓
LLM Provider 설정
        ↓
API Key 설정
        ↓
Model 설정

Hermes 자체가 설치된 것과 LLM을 사용할 수 있는 것은 별개의 단계입니다.

7. Hermes Agent의 Provider란?

Hermes에서는 Provider와 Model을 구분해서 이해하는 것이 중요합니다.

예를 들어 이번 구성에서는:

Provider
OpenRouter
    │
    ▼
Model
DeepSeek V4 Flash

입니다.

OpenRouter는 여러 LLM을 하나의 API 인터페이스로 연결하는 Provider 역할을 합니다.

Hermes 공식 문서에서도 OpenRouter를 지원 Provider 중 하나로 제공하며 OPENROUTER_API_KEY를 이용해 연결하도록 설명하고 있습니다.

8. OpenRouter API Key 준비

앞선 글에서 OpenRouter API Key를 발급했습니다.

API Key는 다음과 같은 형태입니다.

sk-or-v1-xxxxxxxxxxxxxxxxxxxxxxxx

실제 Key는 다른 사람에게 공개하면 안 됩니다.

이번 글에서는 이 Key를 Hermes Agent에 연결합니다.

API 생성후 저장한 API값을 가져다 쓴다. 한번 발행된 API키는 재발행해주지 않으므로 잃어버렸을 경우, API를 지우고 다시 생성한다.

9. Hermes에 OpenRouter 연결하기

현재 Hermes에서 Provider를 설정하는 가장 간단한 방법은 다음 명령입니다 : hermes model

공식 문서에서는 hermes model을 Provider와 Model을 설정하는 canonical command로 안내합니다.

이 명령을 실행하면 Provider 선택 과정이 시작됩니다.

hermes model 입력결과 Open Router 가입전 google API를 연동한 화면

목록에서 Open Router(3번)을 선택하기위해 3을 입력합니다.

를 선택합니다.

10. OpenRouter API Key 입력

OpenRouter를 선택하면 API Key를 입력하는 단계가 나타납니다.

여기에 앞에서 발급한 OpenRouter API Key를 입력합니다.

OPENROUTER_API_KEY
        ↓
Hermes Agent
        ↓
OpenRouter

추가로, 다음과 같은 CLI 설정 방법을 제공합니다.

hermes config set OPENROUTER_API_KEY sk-or-...

이 명령을 사용하면 Hermes가 API Key를 비밀정보용 파일에 저장합니다.

11. Hermes의 API Key 저장 위치

Hermes는 일반 설정과 비밀정보를 분리해서 관리합니다.

기본적으로 다음 구조를 사용합니다.

~/.hermes/
│
├── .env
│     └── API Key / Secret
│
├── config.yaml
│     └── Model / Provider / 일반 설정
│
├── auth.json
│     └── OAuth 인증 정보
│
├── memories/
├── skills/
├── sessions/
└── logs/

API Key와 같은 Secret은 ~/.hermes/.env, 일반 설정은 ~/.hermes/config.yaml에 저장한다.

따라서 별도로 다음과 같은 환경변수를 Windows 시스템 전체에 등록하지 않을 경우,

Hermes CLI를 이용해 설정하면 필요한 위치에 저장됩니다.

예:

hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxx

12. 현재 Hermes의 모델 설정 구조

설정이 완료되면 Hermes의 config.yaml에는 Provider와 Model 정보가 저장됩니다.

개념적으로 다음과 같은 구조입니다.

model:
  provider: openrouter
  default: deepseek/deepseek-v4-flash-0731

hermes는 model.provider와 model.default를 이용해 Provider와 기본 모델을 지정하는 구조를 사용합니다.

이 방식이 Provider 인증과 모델 선택을 함께 처리하기 때문입니다.

13. 설정이 제대로 되었는지 확인

설정이 끝났다면 현재 Model 설정을 확인합니다 : hermes config get model

또는: hermes config 를 이용할 수 있습니다.

hermes config get model을 통한 Provider / Model 조회

14. Hermes Agent 실행

이제 실제 Agent를 실행합니다.

가장 기본적인 방법은: hermes

또는 TUI 인터페이스를 사용하려면: hermes --tui 를 사용할 수 있습니다.

15. 첫 번째 테스트는 단순하게

처음부터 파일 수정이나 터미널 자동화 같은 복잡한 작업을 요청하지 않는 것이 좋습니다.

먼저 일반적인 질문을 하나 입력합니다.

예: 안녕하세요. 현재 사용 중인 모델과 Provider를 설명해주세요.

정상적으로 응답한다면 다음 단계로 넘어갑니다 : 현재 작업 디렉터리의 파일 목록을 보여주세요.

그다음: "현재 디렉터리에 test.txt 파일을 만들고 "Hello Hermes"를 저장해주세요" 처럼 단계적으로 테스트합니다.

16. Tool Calling 테스트

일반적인 대화가 정상적으로 작동했다면 이제 Agent의 핵심 기능 중 하나인 Tool 사용을 확인합니다.

예를 들어: 현재 디렉터리에 어떤 파일이 있는지 확인하고 각 파일의 종류를 설명해주세요.

" 현재 디렉터리에 어떤 파일이 있는지 확인하고 각 파일의 종류를 설명해주세요."의 결과

Hermes가 파일 시스템을 확인하기 위해 Tool을 호출한다면 다음과 같은 흐름이 만들어집니다.

사용자 요청
     ↓
Hermes Agent
     ↓
LLM
     ↓
Tool Call
     ↓
파일 시스템
     ↓
Tool 결과
     ↓
LLM
     ↓
최종 응답

17. OpenRouter Provider Routing 설정

API 비용을 조절하기 위해 Provider 를 price로 설정하기 위해서,

1. AppData\Local\hermes\config.yaml를 열거나,

2. "hermes config edit "를 입력해서 띄워주는 파일을 수정한다.

아래내용 추가.

provider_routing:

sort: "price"

require_parameters: true

이후 확인시엔,

1. hermes config get provider_routing.sort 또는

2. hermes config list

3. Get-Content "C:\Users\AppData\Local\hermes\config.yaml"(주소느 Hermes AI 설치경로)

을 입력하여 설정을 확인할 수 있다.

Model 선택
DeepSeek V4 Flash
        ↓
Provider 선택
OpenRouter 내부 Provider
        ↓
Routing
price / throughput / latency

sort: "price"는 DeepSeek V4 Flash보다 더 싼 다른 모델을 선택하는 기능이 아닙니다.

선택한 모델을 제공하는 Provider 중 어느 곳으로 요청을 보낼지 가격 기준으로 정렬하는 설정입니다.

Hermes의 OpenRouter 통합 문서에서도 price, throughput, latency를 Provider Routing 기준으로 제공하고 있습니다.

18. Hermes 설정 파일을 직접 수정해야 할까?

처음에는 권장하지 않습니다.

현재 Hermes에는 설정을 관리할 수 있는 CLI가 있습니다.

hermes config

특정 설정 확인:

hermes config get model

설정 변경:

hermes config set KEY VALUE

설정 검사:

hermes config check

설정 마이그레이션:

hermes config migrate

특히 API Key는:

hermes config set OPENROUTER_API_KEY sk-or-v1-...

처럼 설정하면 Hermes가 Secret을 적절한 위치에 저장합니다.

19. 자주 발생하는 오류

① hermes: command not found

설치 직후 기존 터미널을 계속 사용하면 PATH가 갱신되지 않았을 수 있습니다.

해결:

source ~/.bashrc

또는 터미널을 완전히 종료한 후 다시 실행합니다.

Windows에서는 새 PowerShell 또는 Windows Terminal을 열어줍니다. 공식 FAQ에서도 설치 후 PATH 문제일 경우 새 터미널을 열거나 Shell을 다시 로드하도록 안내합니다.

② API key not set

OpenRouter API Key가 제대로 등록되지 않은 경우입니다.

다음 명령으로 다시 설정할 수 있습니다.

hermes config set OPENROUTER_API_KEY sk-or-v1-...

또는:

hermes model

을 실행해 Provider 설정을 다시 진행합니다.

③ 인증 오류

OpenRouter에서 다음과 같은 오류가 발생한다면:

401 Unauthorized
403 Forbidden

다음을 확인합니다.

API Key가 정확한가?
        ↓
OpenRouter Credits가 있는가?
        ↓
API Key가 삭제되거나 만료되지 않았는가?
        ↓
Key의 spending limit을 초과하지 않았는가?

④ Context Length 오류

Hermes는 최소 64K Context를 요구합니다.

따라서 Context Window가 작은 모델을 선택하면 Agent가 정상적으로 실행되지 않을 수 있습니다.

이 경우 OpenRouter의 해당 모델 페이지에서 Context Window를 확인합니다.

⑤ 모델이 작동하지 않는 경우

모델 ID가 잘못되었거나 해당 모델의 Provider가 현재 요청 조건을 지원하지 않을 수 있습니다.

이 경우 먼저 복잡한 Routing 설정을 제거하고 기본 모델 호출부터 확인합니다.

Hermes 공식 Quickstart에서도 기본 Chat이 정상적으로 작동한 후 Routing이나 추가 기능을 구성하는 방식을 권장합니다.

20. 이번 구성의 전체 구조

이번 글에서 만든 시스템을 정리하면 다음과 같습니다.

┌─────────────────────┐
│     User Request    │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│    Hermes Agent     │
│                     │
│ Memory / Skills     │
│ Tool Calling        │
│ Planning            │
└──────────┬──────────┘
           │
           │ API Key
           ↓
┌─────────────────────┐
│     OpenRouter      │
│                     │
│ Credit Management   │
│ Provider Routing    │
│ Model Gateway       │
└──────────┬──────────┘
           ↓
┌─────────────────────┐
│ DeepSeek V4 Flash   │
└──────────┬──────────┘
           ↓
       LLM Response
           │
           ↓
┌─────────────────────┐
│ Hermes Tool Loop    │
└─────────────────────┘

이제 Hermes Agent가 실제로 사용할 수 있는 기본 실행 환경이 만들어졌습니다.

21. 보안 설정은 마지막이 아니라 처음에

Agent를 실제로 사용하기 전에 API 비용과 실행 권한도 함께 확인하는 것이 좋습니다.

특히 Hermes는 일반 Chatbot보다 터미널이나 파일 시스템과 같은 도구를 사용할 수 있기 때문에 다음 두 가지를 별도로 관리해야 합니다.

API 비용

OpenRouter Credits
       ↓
API Key Spending Limit
       ↓
Hermes Agent

로컬 실행 권한

Hermes Agent
       ↓
Terminal / Files / Browser
       ↓
내 컴퓨터 또는 지정된 실행 환경

즉, API Key의 비용 제한과 Agent의 실행 권한은 서로 다른 안전장치입니다.

API Key에 $5 제한을 걸었다고 해서 Hermes가 로컬 시스템에서 수행할 수 있는 작업까지 제한되는 것은 아닙니다.

22. 마무리

이번 글에서는 Hermes Agent를 실제로 설치하고 OpenRouter를 연결했습니다.

전체 과정은 다음과 같습니다.

OpenRouter 가입
      ↓
Credits 충전
      ↓
API Key 발급
      ↓
Hermes Agent 설치
      ↓
hermes model
      ↓
OpenRouter 선택
      ↓
API Key 입력
      ↓
DeepSeek V4 Flash 선택
      ↓
일반 대화 테스트
      ↓
Tool Calling 테스트

여기까지 완료하면 LLM API를 호출할 수 있는 Agent 실행 환경이 만들어집니다.

인공지능(AI) 고등학교

Hermes Agent를 위한 Open Router API 발급기(3) - Hermes Agent 설치부터 OpenRouter API 연결