Interactive HTML Tutorial

맥에서 Hermes 시작하기: 첫 설치부터 Telegram 연동, SOUL까지

터미널이 익숙하지 않은 분도 따라올 수 있도록, Hermes 설치부터 첫 대화, 대시보드, Telegram 연동, 프로필, SOUL 설정까지 단계별로 정리했습니다.

설치 첫 대화 스킬 대시보드 Telegram

1. Hermes 설치하기

공식 문서의 macOS 설치 명령어는 한 줄입니다. 복사 버튼을 눌러 터미널에 붙여넣으세요.

설치 명령어

터미널 앱을 열고 아래 명령어를 그대로 실행합니다.

Terminal 
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
설치가 끝난 뒤 터미널이 “hermes 명령을 못 찾는다”고 하면, 터미널 창을 완전히 닫고 새 터미널을 다시 여세요. 초보자에게는 이 방법이 가장 덜 헷갈립니다.

설치 전 체크

AI Provider 선택

Hermes는 설치만으로 끝나지 않고, 어떤 AI 모델을 쓸지 연결해야 합니다. 처음에는 대화형 설정 명령어를 쓰면 안전합니다.

아래 명령어를 터미널에 입력하면 모델 선택 화면이 열립니다. 무엇을 골라야 할지 모르겠다면 ? 선택 도움 탭을 먼저 열어보세요.

Provider 설정 마법사 
hermes model

Claude Code 기반 사용자라면: 잘 모르겠으면 Claude CLI/OAuth 방식으로 시작하세요. API Key 방식은 “구독료에 포함된 사용”이 아니라 Anthropic API 사용량으로 별도 청구될 수 있습니다.

구독형
Claude CLI/OAuth 흐름을 우선 사용
API Key
사용량 기반 별도 청구 가능
추천
처음에는 하나의 방식만 연결

ChatGPT/Codex 계정이 익숙하다면: OpenAI Codex를 선택하고 OAuth 방식으로 로그인합니다. 브라우저에 표시되는 코드 입력 화면이 나오면 그대로 따라가면 됩니다.

API Key를 직접 넣는 방식은 별도의 API 과금으로 이어질 수 있습니다. Codex를 쓰려는 목적이면 OAuth 경로를 먼저 고르세요.

여러 모델을 한곳에서 쓰고 싶다면: OpenRouter API 키를 준비한 뒤 Hermes 설정 중 입력합니다. 초보자는 먼저 하나의 Provider만 연결하고 정상 대화가 되는지 확인하세요.

OpenRouter는 편하지만 API Key 기반입니다. 즉, OpenRouter 계정의 크레딧/사용량 정책에 따라 별도로 비용이 나갈 수 있습니다.

Qwen, DeepSeek, Ollama 같은 로컬 모델을 쓰고 싶다면: 모델 서버를 직접 띄우고 Hermes에서 Custom Endpoint를 연결해야 합니다. 처음 설치하는 사용자는 이 탭을 건너뛰어도 됩니다.

로컬 모델은 보통 컨텍스트 길이, base URL, 모델 이름을 직접 맞춰야 합니다. 공식 문서는 최소 64K 토큰 컨텍스트를 요구한다고 안내합니다.
로컬 모델 안내 페이지 보기
잘 모르겠고 Claude 구독을 쓰고 있다면: Claude CLI 방식 Claude 구독으로 쓰려는 경우 API Key를 새로 넣기보다 Claude CLI/OAuth 흐름을 우선 선택하세요. 구독 범위 안에서 쓰는 경로와 API 사용량 과금 경로를 섞지 않는 것이 핵심입니다.
ChatGPT/Codex 쪽이 익숙하다면: OpenAI Codex OAuth Codex는 API Key를 복사해 넣는 방식보다 브라우저에서 로그인하는 OAuth 방식으로 연결하는 쪽이 초보자에게 편합니다.
회사 카드나 개인 API Key를 넣는다면: 별도 과금 확인 Anthropic, OpenAI, OpenRouter API Key를 넣으면 대화할 때마다 해당 Provider의 API 사용량이 따로 청구될 수 있습니다.
핵심은 “하나만 골라서 먼저 성공시키기”입니다. 첫 대화가 정상 작동하기 전에는 Gateway, Telegram, Cron 같은 다음 기능은 생각하지 마세요.

2. 첫 대화 실행하기

설치와 모델 연결이 끝났다면 이제 Hermes를 실제로 열어봅니다.

기본 CLI

가장 단순한 실행 방식입니다. 아래 명령어를 터미널에 입력하면 Hermes 대화창이 열립니다.

Classic CLI
hermes

추천 화면 모드

TUI는 Hermes를 터미널을 통해서 채팅할 수 있는 모드로 실행한다고 생각하시면 돼요. 공식 문서는 이 방식을 추천합니다. 아래 명령어를 터미널에 입력하세요.

Modern TUI
hermes --tui

이어서 열기

방금 대화를 다시 불러오는 명령어입니다. 터미널에 아래 명령어를 입력하면 최근 세션으로 돌아갑니다.

Resume
hermes --continue

TUI로 Hermes를 열면 이렇게 생겼어요

TUI는 Hermes를 터미널을 통해서 채팅할 수 있는 모드로 실행한다고 생각하시면 돼요. 아래 버튼을 눌러 Hermes에서 해볼 첫 질문을 시뮬레이션해 보세요.

you@macmini ~ % hermes --tui
Hermes Agent ready. Model: anthropic/claude...

You →

성공 기준

3. 기본 스킬 사용해 보기

스킬은 Hermes 에이전트가 어떤 일을 수행하는 설명서라고 생각하면 됩니다. 스킬은 직접 만들 수도 있고, 남들이 만든 걸 가져다 쓸 수도 있어요. 처음에는 검색하고 설치하는 흐름만 익히면 됩니다.

1

스킬 검색

예시는 웹 검색처럼 이해하기 쉬운 키워드입니다. 아래 명령어를 터미널에 입력하고, 실제로는 원하는 분야의 단어로 바꾸면 됩니다.

Skill search
hermes skills search web
2

스킬 설치

검색 결과에서 설치하고 싶은 스킬 이름을 확인한 뒤, 아래 명령어처럼 터미널에 입력해 설치합니다. 검색결과의-스킬-이름 부분은 Hermes가 보여준 실제 스킬 이름으로 바꿔주세요.

Skill install
hermes skills install 검색결과의-스킬-이름
3

채팅 안에서 스킬 보기

이건 터미널 명령어가 아니라 Hermes 대화창 안에 입력하는 명령입니다. Hermes가 열린 상태에서 아래처럼 /skills를 입력하세요.

Slash command
/skills

슬래시 명령어 연습

Hermes 안에서 /를 입력하면 명령어 자동완성이 뜹니다.

  • /help: 사용 가능한 명령 보기
  • /tools: 사용 가능한 도구 보기
  • /model: 모델 다시 선택
  • /save: 대화 저장
퀴즈: 모델을 바꾸고 싶을 때 입력할 명령어는?

4. 대시보드로 열어서 만져보기

웹 대시보드는 브라우저에서 Hermes 설정, API 키, 세션, 로그, 스킬을 볼 수 있는 화면입니다. 공식 문서 기준 기본 주소는 http://127.0.0.1:9119입니다.

대쉬보드는 대략 이렇게 생겼어요. 왼쪽에는 메뉴가 있고, 오른쪽 넓은 화면에서 모델 설정, 사용량, 세션, 스킬 같은 정보를 확인합니다.

Hermes Agent Web UI 대시보드 참고 화면. 왼쪽 메뉴와 모델 설정, 사용량 그래프, 모델 카드가 보입니다.

대시보드 실행

아래 명령어를 터미널에 입력하면 로컬 웹 서버가 켜지고 브라우저가 열립니다. 데이터는 내 컴퓨터의 localhost에서만 동작합니다.

Dashboard
hermes dashboard

대시보드 의존성(dependency)이 없다는 안내가 나오면 아래 명령어를 터미널에 입력하세요. 여기서 의존성은 대시보드를 열 때 함께 필요한 추가 프로그램이라는 뜻입니다. 설치가 끝나면 다시 hermes dashboard를 실행하세요.

Dashboard extras
pip install 'hermes-agent[web,pty]'
주의: --host 0.0.0.0 또는 --insecure 옵션은 같은 네트워크의 다른 사람이 접근할 수 있어 초보자에게 권장하지 않습니다.

대시보드에서 볼 것

  • Status: 설치 상태와 최근 세션
  • Chat: 브라우저 안에서 Hermes 대화 화면 사용
  • Config: 설정 파일을 폼으로 수정
  • API Keys: Provider 키 관리
  • Skills: 스킬 검색과 활성화

대쉬보드의 구성을 살펴보고 메뉴별로 어떤 화면이 있는지 알아보세요.

대시보드 구성 살펴보기 http://127.0.0.1:9119

6. 막혔을 때 순서대로 확인

문제가 생기면 여러 기능을 한꺼번에 고치려 하지 말고, 공식 문서의 복구 순서대로 하나씩 확인하세요.

자주 쓰는 복구 명령어

문제가 생겼을 때는 아래 명령어 묶음을 터미널에 한 줄씩 입력하세요. “위에서 아래로” 실행하고, 앞 단계에서 문제가 풀리면 다음 단계로 넘어가지 않아도 됩니다.

진단 순서
hermes doctor
hermes model
hermes setup
hermes sessions list
hermes --continue
hermes gateway status
hermes doctor 현재 설치, 설정 파일, Provider 연결 상태를 점검합니다. “뭐가 문제인지 모르겠다” 싶을 때 첫 번째로 실행합니다.
hermes model Claude, Codex, OpenRouter 같은 모델 연결을 다시 고릅니다. 로그인이나 API Key가 잘못된 것 같을 때 씁니다.
hermes setup 전체 설정 마법사를 다시 엽니다. 처음 설치 흐름을 다시 밟는다고 생각하면 됩니다.
hermes sessions list 저장된 대화 목록을 확인합니다. 이어서 열 대화가 실제로 저장되어 있는지 볼 때 씁니다.
hermes --continue 가장 최근 대화를 이어서 엽니다. 방금 하던 작업으로 돌아갈 때 쓰는 명령어입니다.
hermes gateway status Telegram, Discord 같은 메신저 연동 서버가 켜져 있는지 확인합니다. 이번 1, 2장에서는 아직 몰라도 됩니다.

다음 장 예고

Telegram까지 확인했다면 아래 페이지로 이어서 볼 수 있습니다.