Hermes Agent macOS 설치 방법: 초보자를 위한 설치부터 첫 대화까지

AI를 활용하여 생성한 이미지입니다.

Hermes Agent를 처음 설치하는 macOS 사용자라면 “파이썬부터 설치해야 하나?”, “터미널 명령어를 어디에 입력하나?”, “API 키는 어디에 넣나?”부터 막히기 쉬워요. 이 글은 macOS에서 Hermes Agent를 설치하고, 모델 제공자를 선택하고, 첫 질문이 실제로 동작하는지 확인하는 순서를 처음부터 끝까지 설명해요.[1]

설치 명령은 2026년 9월 6일 Hermes Agent 공식 설치 문서와 플랫폼 지원 문서를 기준으로 정리했어요. 공식 문서에서 현재 macOS는 Apple Silicon 설치를 Tier 1 지원 대상으로 안내하고 있어요.[1][2] Intel Mac은 이 글에서 정상 지원된다고 단정하지 않아요.

먼저 알아둘 것

Hermes Agent는 터미널에서 실행하는 AI 에이전트예요. 단순히 답변만 하는 챗봇이 아니라 파일 작업, 터미널 명령, 웹·브라우저·코드 실행 같은 도구를 설정에 따라 사용할 수 있어요. 따라서 설치가 끝났다는 말은 프로그램 파일이 생겼다는 뜻이고, 실제 사용을 시작하려면 모델 제공자와 도구 권한을 따로 설정해야 해요.[3][4]

macOS 설치는 다음 두 가지 중 하나를 고르면 돼요.[3][7]

• Hermes Desktop 설치기: 데스크톱 앱과 명령줄 앱을 함께 쓰고 싶을 때 적합해요.[1][9]
• CLI 전용 설치: 터미널에서만 간단하게 사용하고 싶을 때 적합해요.[1]

두 방식은 처음부터 모두 설치할 필요가 없어요. 초보자라면 데스크톱 앱을 선호할 경우 공식 다운로드 페이지의 설치기를 쓰고, 터미널 사용이 괜찮다면 CLI 전용 설치 명령을 사용하는 흐름이 가장 단순해요.[1][9]

설치 전 준비

1. 내 Mac이 Apple Silicon인지 확인하기

화면 왼쪽 위의 Apple 메뉴를 누르고 이 Mac에 관하여를 열어 보세요. 칩 또는 프로세서 항목에 Apple M1·M2·M3·M4·M5처럼 표시되면 Apple Silicon Mac이에요. 공식 플랫폼 지원표에서 macOS Apple Silicon이 Tier 1로 안내돼요.[2]

Intel이라고 표시되면 이 글의 명령을 무조건 정상 동작한다고 전제하지 마세요. 공식 지원표에 없는 조합은 설치가 되더라도 특정 기능이나 업데이트에서 문제가 생길 수 있어요.[2]

2. 터미널 열기

가장 쉬운 방법은 키보드에서 Command(⌘)+스페이스바를 누르고 터미널 또는 Terminal을 입력한 다음 Return 키를 누르는 거예요. 검은색 또는 흰색 명령줄 창이 열리면 준비가 된 거예요.[1][2][8]

앞으로 이 글의 회색 명령어 상자에 있는 명령은 한 줄씩 터미널에 붙여 넣고 Return 키를 눌러 실행하면 돼요. 명령어 앞의 $ 기호는 입력하지 마세요.[1][2][8]

3. Git 확인하기

공식 설치 문서는 macOS 같은 비Windows 플랫폼에서 Git을 사전 조건으로 안내해요.[1] 터미널에 다음 명령을 입력해 보세요.

git --version

git version 뒤에 숫자가 나오면 Git을 사용할 수 있는 상태예요. “command not found”가 나오면 macOS가 안내하는 Command Line Tools 설치 창을 따라 설치한 뒤 터미널을 다시 열어 보세요. Apple은 개발 도구를 별도 패키지로 설치하는 방법을 공식 기술 문서에서 안내하고 있어요.[8]

다시 다음 명령을 실행해 버전이 표시되는지 확인하세요.[1][2][8]

git --version

Python, Node.js, ripgrep, ffmpeg를 먼저 수동으로 설치할 필요는 없어요. Hermes 공식 설치기는 필요한 의존성을 자동으로 처리한다고 안내해요.[1]

방법 A. Hermes Desktop 설치하기

데스크톱 앱을 함께 쓰고 싶다면 이 방법을 먼저 고려할 수 있어요.[1][9]

1. 공식 다운로드 페이지 열기

브라우저에서 다음 주소를 직접 입력하세요.[1][9]

https://hermes-agent.nousresearch.com/

주소창에 hermes-agent.nousresearch.com이 정확히 표시되는지 확인하세요. 검색 결과의 광고나 제3자 다운로드 사이트에서 설치 파일을 받지 않는 편이 안전해요.[9]

2. macOS 설치기 다운로드

공식 페이지에서 macOS용 Hermes Desktop 설치기를 내려받으세요. 다운로드된 설치 파일을 열고 화면에 표시되는 안내를 따라 설치하면 돼요. 설치 중 macOS가 앱 실행을 막으면, 먼저 파일을 공식 사이트에서 받은 것이 맞는지 확인한 다음 시스템 설정 > 개인정보 보호 및 보안의 차단 안내를 읽어 보세요.[1][9]

출처가 불명확한 앱을 무조건 허용하면 안 돼요. 공식 주소에서 받은 파일인지 확인되지 않으면 설치를 중단하세요.[1][9]

3. 설치 후 앱 실행하기

설치가 끝나면 응용 프로그램 폴더나 Spotlight에서 Hermes Desktop을 실행하세요. 공식 설치 문서는 데스크톱 설치기가 명령줄 애플리케이션과 데스크톱 애플리케이션을 쉽게 설치하는 경로라고 설명해요.[1]

터미널 명령도 사용할 수 있는지 확인하려면 터미널을 새로 열고 다음을 실행하세요.[1][9]

hermes --version

버전 정보가 출력되면 hermes 명령을 찾은 거예요. “command not found”가 나오면 아래 CLI 설치 방법으로 설치 상태와 PATH를 점검할 수 있어요.[1][9]

방법 B. CLI 전용으로 설치하기

데스크톱 앱 없이 터미널에서만 사용하려면 공식 설치 스크립트를 실행하면 돼요. 공식 문서의 macOS·Linux·WSL2 명령은 다음과 같아요.[1][3]

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

명령을 입력하면 설치기가 필요한 구성 요소와 Hermes Agent 저장소, 가상환경, 전역 hermes 명령을 준비해요. 공식 설치 문서는 Python·Node.js·ripgrep·ffmpeg와 가상환경을 설치기가 처리한다고 설명해요.[1]

설치 스크립트가 하는 일

공식 문서에 따르면 설치기는 다음 작업을 자동으로 처리해요.[1]

1. 필요한 Python 실행 환경을 준비해요.[1]
2. Node.js, ripgrep, ffmpeg처럼 기능에 필요한 구성 요소를 확인하거나 설치해요.[1]
3. Hermes Agent 저장소를 내려받아요.[1]
4. Python 가상환경을 만들어요.[1]
5. 터미널에서 쓸 hermes 명령을 연결해요.[1]
6. 모델 제공자와 초기 설정을 진행할 수 있게 해요.[1]

이 때문에 Homebrew로 Python이나 Node.js를 먼저 설치해야만 하는 구조는 아니에요. 다만 기존 시스템 상태와 macOS 권한에 따라 설치 중 추가 안내가 나올 수 있어요.[1]

설치 명령을 실행하기 전에 확인하고 싶다면

터미널 명령을 그대로 파이프로 넘기는 것이 불편하다면 먼저 파일로 내려받아 내용을 확인할 수 있어요.[1]

curl -fsSL https://hermes-agent.nousresearch.com/install.sh -o /tmp/hermes-install.sh
less /tmp/hermes-install.sh

내용을 확인한 뒤 설치를 진행하려면 다음을 실행하세요.[1]

bash /tmp/hermes-install.sh

공식 문서의 한 줄 설치 방식과 같은 스크립트를 사용하는지 URL을 다시 확인하세요. /tmp에 저장된 설치 파일은 작업이 끝난 뒤 지워도 돼요.[1]

설치 직후 셸 다시 불러오기

설치가 끝났는데 hermes를 찾지 못하면 터미널이 이전 PATH를 계속 사용하고 있을 수 있어요. macOS 기본 셸인 zsh 설정을 다시 읽어 보세요.[1][3]

source ~/.zshrc

그다음 다음 명령을 실행하세요.[1][3]

hermes --version

그래도 찾지 못하면 현재 명령 경로를 확인해 보세요.[1][3]

command -v hermes

아무 경로도 출력되지 않으면 터미널을 완전히 닫았다가 새로 열고 다시 실행하세요. 공식 설치기는 전역에서 쓸 수 있는 hermes 명령을 설정하지만, 기존 셸이 새 PATH를 읽어야 반영될 수 있어요.[1]

설치가 제대로 됐는지 확인하기

1. 도움말 출력

hermes --help

도움말에 setup, model, doctor, config, tools, gateway 같은 명령이 보이면 CLI가 실행되고 있는 상태예요. Hermes CLI에는 대화, 모델 선택, 설정, 진단, 게이트웨이 관리 명령이 따로 있어요.[3]

2. 진단 실행

hermes doctor

doctor는 설치와 설정 상태를 확인하는 진단 명령이에요. 오류가 나오면 무시하고 다음 단계로 넘어가기보다, 표시된 누락 항목을 먼저 해결하세요. 현재 버전의 CLI에도 hermes doctor --fix와 실시간 점검용 --live 옵션이 제공돼요.[3]

실시간 점검은 실제 외부 도구나 네트워크 호출을 할 수 있으므로, 처음에는 기본 진단부터 실행하는 편이 좋아요. 문제가 계속될 때만 공식 문서와 오류 메시지를 함께 확인하세요.[3]

가장 쉬운 초기 설정: Nous Portal

공식 퀵스타트와 설치 문서는 새 설치 후 다음 명령을 가장 빠른 경로로 안내해요.[1][3][4]

hermes setup --portal

이 명령은 OAuth 로그인 흐름을 시작하고, Nous 모델 제공자와 Tool Gateway를 설정하는 방식이에요. 공식 문서는 한 번의 Portal 설정으로 모델과 웹 검색·이미지 생성·TTS·브라우저 도구를 포함한 Tool Gateway를 구성할 수 있다고 설명해요.[1][4]

브라우저가 열리면 화면의 공식 로그인 절차를 따라가세요. 비밀번호나 인증 코드를 이 채팅이나 파일에 붙여 넣지 마세요. 로그인 과정이 끝나면 터미널로 돌아와 설정 완료 메시지를 확인하세요.[3][4]

Portal을 사용하지 않을 때

다른 모델 제공자의 API 키나 OAuth를 사용하려면 다음 명령을 실행하세요.[3][4]

hermes model

화면에 표시되는 제공자 목록에서 원하는 항목을 선택하고 안내에 따라 설정하면 돼요. Hermes 공식 제공자 문서는 OpenRouter, Anthropic, OpenAI Codex, Google, DeepSeek, xAI, Qwen OAuth, 로컬 모델과 사용자 지정 OpenAI 호환 엔드포인트 등 여러 경로를 지원한다고 설명해요.[5]

API 키를 직접 설정할 때는 키를 공개 저장소나 일반 문서에 적지 마세요. Hermes 공식 설정 문서는 API 키와 토큰 같은 비밀값은 .env에, 모델·터미널·도구 설정은 config.yaml에 저장하도록 구분해요.[4]

첫 대화 실행하기

설정이 끝난 뒤 가장 먼저 짧은 질문으로 연결 상태를 확인하세요.[3]

hermes chat -q "안녕하세요. 설치 확인을 위해 한 문장으로 답해 주세요."

정상적으로 답변이 나오면 단일 질문 실행이 성공한 거예요. 계속 대화하려면 인자 없이 hermes를 실행하세요.[3]

hermes

대화 화면에서 질문을 입력하고 Return 키를 누르면 돼요. 종료 방법은 현재 CLI 화면의 안내를 따르세요. 단일 질문만 실행하고 싶을 때는 hermes chat -q를 사용하면 돼요.[3]

첫 사용에서 도구를 바로 모두 켜지 않아도 돼요

Hermes Agent는 도구를 사용할 수 있지만, 처음부터 브라우저·터미널·코드 실행·메시징 게이트웨이를 모두 켤 필요는 없어요. 먼저 일반 채팅이 되는지 확인한 뒤 필요한 도구만 설정하세요. 공식 퀵스타트도 기본 대화가 동작한 다음 게이트웨이·cron·skills·voice·routing을 추가하라고 안내해요.[3]

도구 설정은 다음 명령으로 확인할 수 있어요.[3][4]

hermes tools

현재 구성과 경로를 확인할 때는 다음 명령이 유용해요.[3][4]

hermes config show
hermes config path
hermes config env-path

설정을 직접 YAML 파일로 고치기보다 hermes config set을 사용하는 편이 안전해요. 공식 설정 문서는 이 명령이 일반 설정은 config.yaml에, API 키 같은 비밀값은 .env에 올바르게 연결한다고 설명해요.[4]

macOS에서 알아둘 폴더

기본 설치·설정 위치는 다음과 같아요.[4]

~/.hermes/config.yaml   일반 설정
~/.hermes/.env          API 키와 비밀값
~/.hermes/state.db      세션과 메시지 상태
~/.hermes/skills/       설치된 스킬
~/.hermes/logs/         로그

Finder에서 ~는 현재 사용자 홈 폴더를 뜻해요. 터미널에서는 다음 명령으로 Hermes 홈 폴더를 열 수 있어요.[4]

open ~/.hermes

.env에는 인증정보가 들어갈 수 있으므로 내용을 복사해 공개 채팅·이슈·스크린샷에 올리지 마세요. 설정을 확인할 때는 값 전체보다 키 이름과 오류 메시지만 공유하는 편이 안전해요.[4][6]

보안 설정을 처음부터 확인하기

Hermes는 기본적으로 명령 실행 승인과 비밀값 보호를 고려한 설정을 사용해요. 공식 보안 문서는 secret redaction이 기본 활성화되어 있고, 명령 승인 모드는 기본적으로 smart라고 설명해요.[6]

현재 설정을 확인하려면 다음을 실행하세요.[4][6]

hermes config get security.redact_secrets
hermes config get approvals.mode

권장 확인값은 다음과 같아요.[4][6]

security.redact_secrets = true
approvals.mode = smart

값을 명시적으로 설정하려면 다음처럼 실행할 수 있어요.[4][6]

hermes config set security.redact_secrets true
hermes config set approvals.mode smart

--yolo나 approvals.mode: off는 승인 프롬프트를 건너뛰는 설정이에요. 처음 설치한 사용자는 이 옵션을 사용하지 않는 편이 안전해요. secret redaction과 명령 승인 설정은 서로 별개이므로, 하나를 바꿨다고 다른 보호 기능까지 꺼지는 것은 아니에요.[6]

macOS 설치 문제 해결

hermes: command not found

다음 순서로 확인하세요.

source ~/.zshrc
command -v hermes
hermes --version

그래도 안 되면 터미널을 새로 열고 다시 실행하세요. 설치가 중간에 실패했다면 오류의 마지막 20줄을 별도로 저장해 확인하되, API 키가 포함된 출력은 공유하지 마세요.[1][3][5]

git: command not found

Git이 설치되어 있지 않으면 macOS의 Command Line Tools 설치 안내가 나타날 수 있어요. Apple 공식 안내에 따라 설치한 뒤 다음 명령을 다시 실행하세요.[8]

xcode-select --install
git --version

Portal 로그인 뒤 모델 응답이 없음

먼저 기본 진단을 실행하세요.[1][3][5]

hermes doctor
hermes model

선택한 제공자와 모델이 저장됐는지 확인하고, 브라우저 로그인 완료 여부와 네트워크 상태를 점검하세요. API 키 방식을 사용했다면 키가 만료됐거나 다른 제공자의 키를 넣지 않았는지도 확인해야 해요.[3][5]

API 키를 잘못 입력했을 때

키를 화면에 다시 출력하거나 이 채팅에 붙여 넣지 마세요. 사용하는 제공자의 인증 설정을 hermes model 또는 hermes auth로 다시 진행하세요. 키가 노출됐다고 의심되면 해당 제공자 콘솔에서 즉시 폐기하고 새 키를 발급하세요.[5][6]

설정 파일을 직접 고친 뒤 오류가 생겼을 때

YAML 들여쓰기를 직접 수정했다면 문법 오류가 생길 수 있어요. 먼저 다음을 실행하세요.[1][3][5]

hermes config check

가능하면 hermes config set과 hermes config unset을 사용해 설정을 바꾸세요. 공식 설정 문서도 설정 파일을 직접 편집하기보다 전용 명령을 사용하는 흐름을 안내해요.[4]

설치 후 업데이트와 제거

설치가 끝난 뒤 최신 버전으로 업데이트하려면 공식 CLI의 업데이트 명령을 확인하세요.[1][3]

hermes update

사용 중인 버전에 따라 업데이트 전후에 hermes doctor를 실행해 상태를 비교하는 편이 좋아요.[3]

제거가 필요할 때는 먼저 공식 제거 명령의 도움말을 확인하세요.[1][3]

hermes uninstall --help

설치 프로그램을 제거하는 것과 ~/.hermes 아래의 설정·세션·스킬·로그를 삭제하는 것은 다른 작업이에요. 데이터까지 지우기 전에는 백업 여부를 먼저 확인하세요. 인증정보와 과거 세션이 남아 있을 수 있으므로 무심코 홈 폴더 전체를 삭제하지 마세요.[1][4]

설치 완료 체크리스트

다음 항목을 모두 확인하면 macOS 기본 설치와 첫 대화가 끝난 거예요.[1][3]

• [ ] Apple 메뉴에서 Mac의 칩 정보를 확인했어요.[1][3]
• [ ] git --version이 정상적으로 출력돼요.[1][3]
• [ ] 공식 사이트에서 Hermes Desktop을 설치했거나 공식 install.sh를 실행했어요.[1][3]
• [ ] 새 터미널에서 hermes --version이 실행돼요.[1][3]
• [ ] hermes doctor에 치명적인 오류가 없어요.[1][3]
• [ ] hermes setup --portal 또는 hermes model로 제공자를 설정했어요.[1][3]
• [ ] hermes chat -q로 실제 답변을 한 번 받았어요.[1][3]
• [ ] security.redact_secrets와 approvals.mode를 확인했어요.[1][3]
• [ ] ~/.hermes/.env와 인증정보를 공개하지 않았어요.[1][3]

마무리

macOS에서 Hermes Agent를 시작하는 가장 짧은 흐름은 git 확인, 공식 설치기 또는 install.sh 실행, hermes doctor, hermes setup --portal, 그리고 짧은 hermes chat -q 테스트예요. 설치가 됐다는 이유만으로 모든 도구와 메시징 기능이 바로 켜지는 것은 아니므로, 기본 대화를 먼저 성공시킨 뒤 필요한 기능을 하나씩 추가하는 편이 좋아요.[1][3]

Hermes는 일반 설정과 인증정보를 분리해 관리하고, 명령 승인과 secret redaction 같은 보호 기능을 제공해요. 초보자라면 설정 파일을 직접 고치기보다 hermes model, hermes tools, hermes config set, hermes doctor를 중심으로 사용하면 문제를 좁혀 가기 쉬워요.[4][6]

Sources

• [1] Hermes Agent 공식 설치 가이드
• [2] Hermes Agent 공식 플랫폼 지원
• [3] Hermes Agent 공식 퀵스타트
• [4] Hermes Agent 공식 설정 가이드
• [5] Hermes Agent 공식 AI 제공자 가이드
• [6] Hermes Agent 공식 보안 가이드
• [7] Hermes Agent 공식 GitHub 저장소
• [8] Apple 공식 Command Line Tools 안내
• [9] Hermes Agent 공식 다운로드 페이지