AI 에이전트 Hermes Agent 로컬 실행 가이드

AI 에이전트 도구를 찾다 보면 Hermes Agent, 즉 헤르메스 에이전트라는 이름을 볼 수 있습니다. Hermes Agent는 Nous Research에서 공개한 오픈소스 AI 에이전트 도구로, 터미널에서 실행하고 LLM 제공자와 연결해 대화형 작업을 수행할 수 있는 구조를 제공합니다. 공식 GitHub 설명에 따르면 Linux, macOS, WSL2, Android Termux에서 설치할 수 있으며, 설치 후 hermes 명령어로 대화를 시작할 수 있습니다.

이 글에서는 헤르메스 설치 방법, 설치 전 준비사항, macOS/Linux/WSL2 설치 절차, 초기 설정 방법, 자주 발생하는 오류 해결법을 초보자도 따라 할 수 있게 정리합니다.

1. 한 줄 요약

헤르메스는 로컬 PC나 서버에서 실행할 수 있는 AI 에이전트 도구이며, Linux, macOS, WSL2 환경에서는 공식 설치 스크립트 한 줄로 설치할 수 있습니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 후에는 셸을 다시 불러오고 hermes 명령어로 실행할 수 있습니다.

source ~/.bashrc
hermes

zsh를 사용한다면 아래처럼 실행합니다.

source ~/.zshrc
hermes

공식 설치 문서는 설치 스크립트가 Python, Node.js, ripgrep, ffmpeg 같은 의존성을 자동으로 처리하며, Git만 사전에 준비하면 된다고 안내합니다.

2. 쉽게 설명하면?

헤르메스는 내 컴퓨터나 서버에서 실행하는 AI 에이전트 도구라고 보면 됩니다.

일반 챗봇은 웹사이트에 접속해서 질문하고 답변을 받는 방식입니다. 반면 Hermes Agent는 내 환경에 설치해서 터미널에서 실행하고, 선택한 LLM 제공자와 연결해 사용할 수 있습니다.

쉽게 비유하면 다음과 같습니다.

구분	쉽게 말하면
일반 챗봇	웹사이트에서 대화하는 AI
Hermes Agent	내 PC나 서버에서 실행하는 AI 에이전트
LLM 제공자	실제 답변을 생성하는 AI 모델 서비스
터미널	명령어로 헤르메스를 실행하는 창
WSL2	Windows에서 Linux처럼 실행할 수 있는 환경

즉, 헤르메스는 “AI 모델 그 자체”라기보다 AI 모델을 내 작업 환경과 연결해서 쓰는 실행 도구에 가깝습니다.

3. 기술적으로는 무슨 뜻인가?

기술적으로 Hermes Agent는 CLI 기반 AI 에이전트입니다.

CLI는 Command Line Interface의 약자로, 마우스로 버튼을 누르는 대신 명령어로 프로그램을 실행하는 방식을 말합니다. Hermes Agent는 hermes라는 명령어를 통해 실행되고, 사용자가 선택한 LLM 제공자와 연결해 대화형 작업을 수행합니다.

구성 요소	설명
Hermes Agent	로컬 또는 서버에서 실행하는 AI 에이전트 도구
CLI	터미널에서 명령어로 실행하는 방식
LLM Provider	OpenRouter, OpenAI, Anthropic, Nous Portal 등 모델 제공자
API Key	모델 제공자를 사용하기 위한 인증 키
Tools	Hermes가 사용할 수 있는 기능 설정
Gateway	Telegram, Discord, Slack 등 메시징 채널 연결 기능

공식 설치 문서는 설치 후 hermes model, hermes tools, hermes gateway setup, hermes config set, hermes setup 같은 명령어로 모델, 도구, 메시징 플랫폼, 설정값을 구성할 수 있다고 안내합니다.

4. 왜 필요한가?

헤르메스 같은 AI 에이전트 도구가 필요한 이유는 단순한 웹 챗봇보다 개인 작업 환경이나 서버 환경에 더 밀접하게 AI를 붙이고 싶기 때문입니다.

예를 들어 다음과 같은 목적이 있을 수 있습니다.

목적	설명
터미널에서 AI 사용	개발자 작업 환경에서 바로 AI를 사용할 수 있음
로컬/서버 실행	개인 PC, VPS, 개발 서버에서 실행 가능
모델 제공자 선택	여러 LLM 제공자 중 원하는 모델을 선택 가능
도구 설정	필요한 기능만 켜고 사용할 수 있음
메시징 연동	Telegram, Discord, Slack 같은 채널과 연결 가능

공식 소개 페이지는 Hermes Agent를 “server에 살면서 기억하고, 여러 메시징 채널을 통해 접근할 수 있는 에이전트”로 설명하며, CLI뿐 아니라 Telegram, Discord, Slack, WhatsApp 같은 채널 연결도 안내합니다.

5. 설치 전 준비사항

설치 전에 아래 항목을 확인하세요.

준비사항	설명
운영체제	Linux, macOS, WSL2, Android Termux
Git	공식 문서 기준 필수 사전 준비사항
터미널	macOS Terminal, Linux shell, WSL2 shell
인터넷 연결	설치 스크립트와 패키지 다운로드 필요
LLM API 키	모델 제공자를 사용할 경우 필요
기본 명령어 지식	`curl`, `source`, `hermes` 명령어 실행 필요

공식 설치 문서는 사전 준비사항으로 Git만 필요하며, 설치 스크립트가 uv, Python 3.11, Node.js v22, ripgrep, ffmpeg를 자동으로 처리한다고 설명합니다.

Git 설치 확인

git --version

Git이 설치되어 있지 않다면 먼저 설치해야 합니다.

macOS에서 Git 설치 예시

xcode-select --install

또는 Homebrew를 사용한다면 다음 명령어를 사용할 수 있습니다.

brew install git

Ubuntu / Debian에서 Git 설치 예시

sudo apt update
sudo apt install git -y

6. macOS 설치 방법

macOS에서는 터미널을 열고 아래 명령어를 실행합니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치가 끝난 뒤 사용하는 셸에 맞게 설정을 다시 불러옵니다.

bash를 사용한다면:

source ~/.bashrc

zsh를 사용한다면:

source ~/.zshrc

설치 확인:

hermes --version

실행:

hermes

공식 Quickstart 문서도 설치 후 셸을 다시 불러온 뒤 hermes 명령어로 대화를 시작하는 흐름을 안내합니다.

7. Linux 설치 방법

Linux에서도 macOS와 같은 설치 명령어를 사용합니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 후 셸을 다시 불러옵니다.

source ~/.bashrc

설치 확인:

hermes --version

실행:

hermes

만약 hermes: command not found가 나오면 아래를 확인합니다.

echo $PATH
ls ~/.local/bin

공식 설치 문서는 hermes: command not found가 발생하면 셸을 다시 불러오거나 PATH 설정을 확인하라고 안내합니다.

8. Windows 설치 방법

Hermes Agent는 네이티브 Windows를 공식 지원하지 않습니다. Windows 사용자는 WSL2를 설치한 뒤, WSL2 안에서 Linux 설치 명령어를 실행해야 합니다. 공식 문서도 네이티브 Windows는 지원하지 않으며 WSL2에서 실행하라고 안내합니다.

Windows 설치 흐름

단계	설명
1	Windows에서 WSL2 설치
2	Ubuntu 같은 Linux 배포판 설치
3	WSL2 터미널 실행
4	Git 설치 확인
5	Hermes 설치 명령어 실행
6	셸 다시 불러오기
7	`hermes` 실행

WSL2 안에서 설치

sudo apt update
sudo apt install git -y
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
source ~/.bashrc
hermes

Windows에서 AI 에이전트 도구를 많이 사용할 계획이라면, 네이티브 Windows보다 WSL2 환경을 익혀두는 것이 좋습니다.

9. Android Termux 설치 방법

Hermes Agent는 Android Termux 환경도 지원합니다. 공식 설치 문서는 Android/Termux에서도 같은 설치 스크립트를 사용할 수 있으며, 설치 스크립트가 Termux를 감지해 전용 설치 흐름을 사용한다고 설명합니다.

Termux에서 실행:

pkg update
pkg install git -y
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

다만 Android 환경은 일반 PC보다 제약이 많습니다. 처음 설치한다면 macOS, Linux, WSL2 환경을 먼저 추천합니다.

10. 설치 후 초기 설정

설치 후에는 모델 제공자와 사용할 도구를 설정해야 합니다.

전체 설정 마법사를 실행하려면:

hermes setup

모델 제공자를 선택하려면:

hermes model

도구 설정:

hermes tools

개별 설정값 지정:

hermes config set

공식 설치 문서는 hermes setup을 전체 설정 마법사로, hermes model, hermes tools, hermes gateway setup, hermes config set을 개별 설정 명령어로 안내합니다.

API 키 설정 주의

LLM 제공자를 사용할 때는 API 키가 필요할 수 있습니다.

API 키는 비밀번호처럼 관리해야 합니다.

공개 저장소에 올리지 않기
화면 공유 중 노출하지 않기
권한이 넓은 키를 함부로 공유하지 않기
테스트용 키와 운영용 키 분리하기
사용하지 않는 키는 폐기하기

11. 설치 확인 명령어

설치 후 아래 명령어를 사용해 정상 설치 여부를 확인합니다.

hermes --version

도움말 확인:

hermes --help

진단 도구 실행:

hermes doctor

공식 설치 문서는 문제가 있을 때 hermes doctor를 실행하면 무엇이 빠졌는지 확인할 수 있다고 설명합니다.

12. 자주 발생하는 오류와 해결 방법

오류 상황	원인	해결 방법
`hermes: command not found`	PATH 설정 미반영	`source ~/.bashrc` 또는 터미널 재시작
`API key not set`	모델 제공자 키 미설정	`hermes model` 또는 설정 명령어로 키 입력
Git 없음	Git 미설치	`git --version` 확인 후 설치
Windows에서 실행 실패	네이티브 Windows 미지원	WSL2 안에서 설치
설치 중 패키지 오류	네트워크 또는 의존성 문제	인터넷 확인 후 재시도
설정이 꼬임	설정값 누락 또는 변경	`hermes config check`, `hermes doctor` 실행

공식 설치 문서는 API key not set 오류가 발생하면 hermes model로 제공자를 구성하거나 설정 명령어로 키를 지정하라고 안내합니다.

13. Hermes Agent 주요 명령어

명령어	설명
`hermes`	대화형 CLI 시작
`hermes setup`	전체 설정 마법사 실행
`hermes model`	LLM 제공자와 모델 선택
`hermes tools`	사용할 도구 설정
`hermes gateway setup`	메시징 플랫폼 연결 설정
`hermes gateway`	게이트웨이 실행
`hermes doctor`	설치와 설정 문제 진단
`hermes update`	Hermes Agent 업데이트

공식 GitHub README와 소개 페이지는 hermes, hermes model, hermes tools, hermes config set 등을 Getting Started 명령어로 제시합니다.

14. 헤르메스와 오픈클로의 차이

사용자가 이전에 OpenClaw도 함께 봤다면, Hermes Agent와 OpenClaw를 비교해서 이해하면 좋습니다.

구분	Hermes Agent	OpenClaw
성격	로컬/서버 기반 AI 에이전트	AI 에이전트 플랫폼
실행 방식	CLI 중심, 게이트웨이 확장	로컬/채널 연동 중심
Windows	WSL2 권장	프로젝트별 문서 확인 필요
모델 연결	여러 LLM 제공자 연결	여러 모델 제공자 연결 가능
주요 관심	메모리, 스킬, 터미널 작업, 메시징	에이전트 실행과 채널 연결

정확한 차이는 각 프로젝트 버전에 따라 달라질 수 있으므로, 실제 설치 시점의 공식 문서를 확인하는 것이 좋습니다.

15. 헤르메스 설치 후 무엇을 해볼까?

처음 설치했다면 복잡한 자동화보다 간단한 작업부터 테스트하는 것이 좋습니다.

실습	목적
기본 대화 실행	설치와 모델 연결 확인
문서 요약 요청	언어 모델 응답 품질 확인
간단한 코드 설명 요청	개발 보조 기능 확인
`hermes model` 실행	모델 제공자 변경 방법 확인
`hermes doctor` 실행	환경 진단 방법 확인

처음에는 “한 가지 모델 + 터미널 대화” 정도로 시작하고, 이후 필요하면 메시징 게이트웨이나 추가 도구 설정으로 확장하는 것이 좋습니다.

16. 자주 묻는 질문

Q1. Hermes Agent는 AI 모델인가요?

아닙니다. Hermes Agent는 AI 모델 자체가 아니라, LLM 제공자와 연결해 사용할 수 있는 AI 에이전트 도구입니다.

Q2. Windows에서 설치할 수 있나요?

네이티브 Windows는 공식 지원하지 않습니다. Windows 사용자는 WSL2를 설치한 뒤 WSL2 안에서 설치해야 합니다.

Q3. Python이나 Node.js를 직접 설치해야 하나요?

공식 문서 기준으로는 Git만 준비하면 되고, 설치 스크립트가 Python 3.11, Node.js v22, uv, ripgrep, ffmpeg 등을 자동으로 처리합니다.

Q4. 설치 후 바로 사용할 수 있나요?

설치 후 LLM 제공자와 API 키 설정이 필요할 수 있습니다. hermes setup 또는 hermes model 명령어로 설정할 수 있습니다.

Q5. 로컬 LLM과 연결할 수 있나요?

공식 문서는 모델 제공자 선택과 자체 엔드포인트 사용 가능성을 안내합니다. 로컬 LLM 연동 가능 여부와 방식은 사용하는 Hermes 버전과 모델 실행 환경에 따라 확인해야 합니다.

Q6. 설치가 제대로 되었는지 어떻게 확인하나요?

hermes --version, hermes --help, hermes doctor 명령어로 확인할 수 있습니다.

Q7. 서버에 설치해도 되나요?

가능합니다. Hermes Agent는 로컬 PC뿐 아니라 서버 환경에서도 사용할 수 있는 구조로 소개됩니다. 다만 서버에 설치할 때는 API 키, 로그, 접근 권한, 업데이트 정책을 신중하게 관리해야 합니다.

17. 정리

헤르메스, 즉 Hermes Agent는 Nous Research에서 공개한 오픈소스 AI 에이전트 도구입니다. Linux, macOS, WSL2, Android Termux에서 설치할 수 있으며, 공식 설치 스크립트 한 줄로 기본 설치를 시작할 수 있습니다.

가장 기본 설치 명령어는 다음과 같습니다.

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

설치 후에는 셸을 다시 불러오고 hermes를 실행합니다.

source ~/.bashrc
hermes

Windows 사용자는 네이티브 Windows가 아니라 WSL2 환경에서 설치해야 합니다. 설치 후에는 hermes setup, hermes model, hermes tools, hermes doctor 같은 명령어를 사용해 모델 제공자, 도구, 환경 상태를 설정하고 확인할 수 있습니다.

처음 사용하는 경우에는 터미널에서 기본 대화부터 시작하고, 이후 모델 변경, 도구 설정, 메시징 게이트웨이 연결로 확장하는 것이 좋습니다.

Hermes Agent 설치 방법