Hermes Agent

​

개요

​

사전 준비

​

1. 시스템 및 모델 요구사항

• 터미널 환경: Hermes Agent는 macOS, Linux, Windows(네이티브 또는 WSL2)의 커맨드라인에서 실행됩니다.
• 모델 컨텍스트 요구사항: Hermes Agent는 컨텍스트 길이가 최소 64K(64,000) tokens 이상인 모델 사용을 권장합니다. 시스템 프롬프트와 도구 정의 자체가 상당한 컨텍스트를 차지하기 때문에, 창이 너무 작으면 가득 차서 대화 공간이 남지 않아 시작 시 거부될 수 있습니다. 컨텍스트 관련 오류가 발생하면 컨텍스트가 더 큰 모델로 교체하면 됩니다(EvoLink의 Claude / Gemini 시리즈는 모두 이 요구사항을 충족합니다).

​

2. EvoLink API Key 발급

• EvoLink 콘솔에 로그인합니다
• 콘솔에서 API Keys를 찾아 “새 Key 생성” 버튼을 클릭한 후, 생성된 Key를 복사합니다
• API Key는 보통 sk-로 시작하므로, 잘 보관하세요

​

1단계: Hermes Agent 설치

• macOS / Linux
• Windows

터미널에서 원클릭 설치 스크립트를 실행합니다:

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

설치가 완료되면, 터미널 설정을 다시 불러와 명령어를 적용합니다:

source ~/.zshrc   # 또는 source ~/.bashrc

최초 실행: 설치 방식 선택(Quick 또는 Full)hermes를 처음 실행하면 대화형 설치 마법사가 시작되며, 먼저 어떤 방식으로 Hermes를 설정할지 묻습니다:

• Quick Setup(Nous Portal) —— 무료 Nous OAuth 로그인을 통해 API Key 없이 모델과 도구를 자동으로 구성하므로 가장 빠르게 시작할 수 있습니다. 다만 기본적으로 Nous Portal의 모델을 사용하며 EvoLink가 아닙니다. EvoLink에 연동하려면 설치 완료 후 hermes model을 별도로 실행해 구성해야 합니다(자세한 내용은 2단계 참고).
• Full setup —— 공급업체, 도구, 옵션을 직접 항목별로 구성합니다(자신의 Key 사용). EvoLink에 바로 연동하려는 사용자에게 이 항목을 권장하며, 설치 과정에서 EvoLink의 인터페이스 주소와 Key를 한 번에 입력할 수 있습니다.

아래에서는 Full setup을 선택해 EvoLink에 연동하는 몇 가지 핵심 단계를 설명합니다:

1

Full setup 선택

방향키로 **Full setup — configure every provider, tool & option yourself(bring your own keys)**를 선택하고, Enter를 눌러 확인합니다.

2

공급업체 선택: Custom endpoint

공급업체 목록에서 아래로 내려가 **custom endpoint(enter URL manually)**를 선택합니다. EvoLink가 제공하는 것은 OpenAI 호환 인터페이스이므로, 여기서는 「커스텀 엔드포인트」 방식으로 연동합니다.

3

EvoLink 인터페이스 주소와 API Key 입력

마법사가 순서대로 엔드포인트 정보 입력을 안내합니다:

• API base URL에 입력: https://direct.evolink.ai/v1
• API key에 EvoLink API Key(sk-로 시작) 입력

입력하면 마법사가 자동으로 엔드포인트를 검증합니다. Verified endpoint via https://direct.evolink.ai/v1/models (154 model(s) visible)와 유사한 메시지가 보이면 인터페이스가 연결되고 Key가 유효한 것입니다. 이후 안내에 따라 기본 모델과 도구를 계속 선택하면 됩니다.

예상 결과: 마법사를 완료하면 Installation Complete(설치 완료) 페이지가 표시되며, 설정 파일 위치와 자주 쓰는 명령어가 나열됩니다.

WSL2 및 Android(Termux) 환경에서도 위의 install.sh 스크립트로 동일하게 설치합니다.

PowerShell에서 원클릭 설치 명령어를 실행합니다:

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

예상 결과: 다운로드 및 설치 정보가 표시되고, 마지막에 설치 성공 안내가 나타납니다.오류가 발생하면: 실행 정책 제한 메시지가 표시되면, 관리자 권한으로 PowerShell을 열거나 먼저 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned를 실행한 후 다시 시도하세요.설치 후 hermes를 처음 실행하면 동일하게 Quick / Full 설치 마법사가 시작되며, EvoLink 연동 단계는 macOS / Linux 탭과 동일합니다(Full setup을 선택하고 마법사에서 EvoLink 인터페이스 주소와 Key를 입력하는 것을 권장).

macOS와 Windows 사용자는 Hermes 공식 사이트에서 Hermes Desktop 데스크톱 설치 패키지를 다운로드하여 더블클릭으로 설치할 수도 있습니다.

​

설치 확인

hermes doctor

​

2단계: EvoLink API 설정(Quick 사용자 또는 재설정)

• ~/.hermes/.env —— API Key 등 비밀 정보를 저장
• ~/.hermes/config.yaml —— 모델, 공급업체 등 비밀이 아닌 설정을 저장

• 설정 마법사(권장)
• 커맨드라인 설정
• 설정 파일 수동 편집

Hermes는 대화형 설정 마법사를 제공하며, 신규 사용자(특히 Quick Setup을 선택한 사용자)에게 적합합니다. 터미널에서 다음을 실행합니다:

hermes model

1

공급업체 선택: Custom endpoint

공급업체 목록에서 아래로 내려가 **custom endpoint(enter URL manually)**를 선택해, EvoLink의 OpenAI 호환 엔드포인트에 연동합니다.

2

인터페이스 주소, Key 입력 및 호환 모드 선택

엔드포인트 정보를 순서대로 입력하고, 검증을 통과한 후 API 호환 모드를 선택합니다:

• API base URL에 입력: https://direct.evolink.ai/v1
• API key에 EvoLink API Key(sk-로 시작) 입력
• API compatibility mode에서 Chat Completions(standard OpenAI-compatible endpoints) 선택

Verified endpoint via https://direct.evolink.ai/v1/models (163 model(s) visible)와 유사한 메시지가 보이면 인터페이스가 연결되고 Key가 유효한 것입니다.

3

기본 모델 선택

마지막으로 기본 모델로 사용할 모델 이름(예: claude-sonnet-4-6, claude-opus-4-8 등)을 입력하고, Enter를 눌러 확인합니다.

마법사는 API Key를 자동으로 ~/.hermes/.env에 기록하고, 모델과 엔드포인트 설정을 ~/.hermes/config.yaml에 기록하므로, 파일을 수동으로 편집할 필요가 없습니다.

hermes model은 Quick 사용자가 EvoLink에 연동하는 가장 핵심적인 단계입니다. 완료하면 바로 다음 단계로 넘어가 사용을 시작할 수 있습니다.

이미 EvoLink API Key를 발급받았다면, 커맨드라인으로 직접 설정을 기록할 수 있습니다.

​

1. API Key 설정(.env에 기록)

hermes config set OPENAI_API_KEY 당신의EvoLink_API_Key

​

2. 인터페이스 주소와 모델 설정(config.yaml에 기록)

hermes config set OPENAI_BASE_URL https://direct.evolink.ai/v1
hermes config set model claude-sonnet-4-6

hermes config set은 API Key 같은 비밀 정보는 자동으로 .env에, 나머지 설정은 config.yaml에 기록하므로, 어느 파일에 기록되는지 신경 쓸 필요가 없습니다.

완료 후 hermes config를 실행해 현재 설정이 올바른지 확인할 수 있습니다.

고급 사용자: 다음 방법은 설정 파일을 직접 편집합니다. 대부분의 사용자에게는 위의 “설정 마법사” 사용을 권장합니다.

​

1. ~/.hermes/.env 편집

~/.hermes/.env를 열거나(없으면 새로 만들어) API Key와 인터페이스 주소를 기록합니다:

OPENAI_API_KEY=당신의EvoLink_API_Key
OPENAI_BASE_URL=https://direct.evolink.ai/v1

​

2. ~/.hermes/config.yaml 편집

~/.hermes/config.yaml을 열거나(없으면 새로 만들어) 메인 모델을 커스텀 엔드포인트로 설정합니다:

model:
  provider: custom
  default: claude-sonnet-4-6
  base_url: https://direct.evolink.ai/v1
  api_mode: chat_completions

⚠️ 중요:

• 당신의EvoLink_API_Key를 실제 API Key로 교체하세요
• base_url은 반드시 https://direct.evolink.ai/v1(EvoLink의 OpenAI 호환 인터페이스 주소)이어야 합니다
• 한글 입력기로 문장 부호(예: 전각 콜론 ：)를 입력하지 마세요

설정 항목 설명:

• provider: custom: 커스텀 OpenAI 호환 엔드포인트(즉, EvoLink) 사용
• base_url: EvoLink API 인터페이스 주소
• api_mode: chat_completions: 표준 Chat Completions 인터페이스 사용
• default: 기본으로 사용할 모델 이름

​

3단계: 사용 시작 및 검증

​

1. Hermes Agent 실행

hermes          # 클래식 커맨드라인 모드

hermes --tui    # 최신 터미널 인터페이스

​

2. 설정 검증

당신은 누구인가요

• AI의 응답 내용(몇 줄의 텍스트)이 보입니다
• 401, 403, API key 무효, context length(컨텍스트 길이) 등의 오류가 나타나지 않습니다

• 401 Unauthorized: API Key가 설정되지 않았거나 유효하지 않음 → ~/.hermes/.env의 OPENAI_API_KEY 확인
• 403 Forbidden: API Key 권한이 부족하거나 만료됨 → API Key 확인
• context length 관련 오류: 선택한 모델의 컨텍스트가 64K 미만 → 요구사항을 충족하는 모델로 교체
• No API key / provider not found: Key를 찾을 수 없음 → hermes config set OPENAI_API_KEY ...를 다시 실행

​

3. 이전 세션 복원

hermes --continue    # 가장 최근 세션 복원
hermes -c            # 약식 형태

​

고급 설정(선택)

​

대체 모델(Fallback)

fallback_providers:
  - provider: custom
    model: claude-sonnet-4-6
    base_url: https://direct.evolink.ai/v1
  - provider: custom
    model: claude-haiku-4-5-20251001
    base_url: https://direct.evolink.ai/v1

​

보조 모델(Auxiliary)

auxiliary:
  title_generation:
    provider: custom
    model: claude-haiku-4-5-20251001
    base_url: https://direct.evolink.ai/v1
    api_key: 당신의EvoLink_API_Key
  compression:
    provider: custom
    model: claude-haiku-4-5-20251001
    base_url: https://direct.evolink.ai/v1
    api_key: 당신의EvoLink_API_Key

​

FAQ

​

1. Hermes Agent란 무엇이며 주로 어떤 용도로 사용되나요?

​

2. Hermes Agent와 Hermes 3 / Hermes 4 모델은 같은 것인가요?

​

3. EvoLink 연동에 왜 provider: custom을 사용하나요?

​

4. 시작 시 컨텍스트 길이(context length)가 부족하다는 메시지가 나오면 어떻게 하나요?

​

5. 401 / 403 오류가 발생하는 일반적인 원인은 무엇인가요?

• 401 오류: OPENAI_API_KEY가 설정되지 않았거나 API Key가 유효하지 않음
• 403 오류: API Key 권한이 부족하거나 만료됨
• ~/.hermes/.env의 Key와, base_url이 https://direct.evolink.ai/v1인지 확인하세요

​

6. 설정을 변경했는데 왜 적용되지 않나요?

• 설정이 올바른 파일에 기록되었는지 확인하세요: API Key는 ~/.hermes/.env, 모델/엔드포인트는 ~/.hermes/config.yaml
• hermes config를 실행해 현재 실제로 적용되는 설정을 확인할 수 있습니다
• config.yaml의 들여쓰기와 문법이 올바른지 확인하세요(YAML은 들여쓰기에 민감합니다)
• Hermes를 다시 시작하세요

​

7. 모델을 어떻게 전환하나요?

• 대화형: hermes model을 실행해 다시 선택
• 커맨드라인: hermes config set model 모델명 실행
• ~/.hermes/config.yaml의 model.default 값을 직접 편집

​

8. EvoLink는 어떤 주요 모델을 지원하나요?

​

9. 사용량은 어떻게 확인하나요?

​

10. 설정 파일과 비밀 키 파일은 각각 어디에 있나요?

• 비밀 키(API Key): ~/.hermes/.env
• 모델 및 공급업체 설정: ~/.hermes/config.yaml
• hermes config edit을 실행하면 설정 파일을 바로 열어 편집할 수 있습니다.

​

11. 커맨드라인 터미널 여는 방법

​

주의사항