빠른 시작
이 가이드는 아무 설정도 없는 상태에서 실제로 사용할 수 있는 Hermes 환경까지 안내합니다. 설치하고, provider를 고르고, 채팅이 정상 동작하는지 확인한 뒤, 문제가 생겼을 때 어디부터 확인해야 하는지까지 빠르게 익힙니다.
영상으로 보고 싶다면
Onchain AI Garage가 설치, 설정, 기본 명령을 다루는 Masterclass 영상을 만들었습니다. 문서를 보며 따라 하기보다 영상으로 흐름을 보고 싶다면 이 페이지와 함께 보기 좋습니다. 더 많은 영상은 Hermes Agent Tutorials & Use Cases 재생목록을 참고하세요.
이 문서가 필요한 경우
- Hermes를 처음 설치하며 가장 짧은 성공 경로가 필요할 때
- provider를 바꾸는 중이고 설정 실수로 시간을 쓰고 싶지 않을 때
- 팀, bot, 상시 실행 workflow용으로 Hermes를 구성할 때
- "설치는 됐는데 아무것도 제대로 안 된다" 상태에서 벗어나고 싶을 때
가장 빠른 경로
목표에 맞는 행을 고르세요.
| 목표 | 먼저 할 일 | 다음에 할 일 |
|---|---|---|
| 내 컴퓨터에서 Hermes만 바로 쓰고 싶다 | hermes setup | 실제 채팅을 실행해 응답을 확인 |
| 사용할 provider를 이미 알고 있다 | hermes model | 설정을 저장한 뒤 채팅 시작 |
| bot 또는 상시 실행 구성이 필요하다 | CLI가 동작한 뒤 hermes gateway setup | Telegram, Discord, Slack 또는 다른 platform 연결 |
| 로컬 또는 self-hosted 모델을 쓰고 싶다 | hermes model에서 custom endpoint 선택 | endpoint, model name, context length 확인 |
| 여러 provider fallback을 쓰고 싶다 | 먼저 hermes model | 기본 채팅이 안정화된 뒤 routing/fallback 추가 |
경험칙: Hermes가 일반 채팅 하나를 끝까지 처리하지 못한다면 아직 다른 기능을 얹지 마세요. 먼저 깨끗한 대화 하나를 성공시키고, 그 다음 gateway, cron, skills, voice, routing을 추가하세요.
1. Hermes Agent 설치
옵션 A - pip(가장 간단함):
pip install hermes-agent
hermes postinstall # optional: Node.js, browser, ripgrep, ffmpeg를 설치하고 setup을 실행
PyPI 릴리스는 main의 모든 commit이 아니라 tag가 붙은 버전, 즉 major/minor 릴리스를 따라갑니다. 최신 변경을 바로 쓰고 싶다면 옵션 B를 사용하세요.
옵션 B - git installer(main branch 추적):
# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
휴대폰에 설치한다면, 검증된 수동 경로와 지원되는 extras, Android 전용 제한 사항을 정리한 Termux guide를 참고하세요.
먼저 WSL2를 설치한 다음, WSL2 terminal 안에서 위 명령을 실행하세요.
설치가 끝나면 shell을 다시 로드합니다.
source ~/.bashrc # 또는 source ~/.zshrc
자세한 설치 옵션, 전제 조건, 문제 해결은 Installation guide를 참고하세요.
2. Provider 선택
가장 중요한 설정 단계입니다. hermes model을 실행하면 provider와 model 선택을 대화형으로 진행할 수 있습니다.
hermes model
처음 시작할 때 좋은 선택지는 다음과 같습니다.
| Provider | 설명 | 설정 방법 |
|---|---|---|
| Nous Portal | subscription 기반, 별도 설정이 거의 없음 | hermes model에서 OAuth 로그인 |
| OpenAI Codex | ChatGPT OAuth로 Codex 모델 사용 | hermes model에서 device code 인증 |
| Anthropic | Claude 모델 직접 사용. Max plan + extra usage credits(OAuth) 또는 pay-per-token API key | hermes model에서 OAuth 로그인(Max + extra credits 필요) 또는 Anthropic API key |
| OpenRouter | 여러 모델 provider를 한 API에서 routing | API key 입력 |
| Z.AI | GLM / Zhipu-hosted 모델 | GLM_API_KEY / ZAI_API_KEY 설정 |
| Kimi / Moonshot | Moonshot-hosted coding/chat 모델 | KIMI_API_KEY 또는 Kimi-Coding 전용 KIMI_CODING_API_KEY 설정 |
| Kimi / Moonshot China | 중국 region Moonshot endpoint | KIMI_CN_API_KEY 설정 |
| Arcee AI | Trinity 모델 | ARCEEAI_API_KEY 설정 |
| GMI Cloud | multi-model direct API | GMI_API_KEY 설정 |
| MiniMax (OAuth) | browser OAuth를 통한 MiniMax-M2.7, API key 불필요 | hermes model에서 MiniMax (OAuth) 선택 |
| MiniMax | international MiniMax endpoint | MINIMAX_API_KEY 설정 |
| MiniMax China | 중국 region MiniMax endpoint | MINIMAX_CN_API_KEY 설정 |
| Alibaba Cloud | DashScope를 통한 Qwen 모델 | DASHSCOPE_API_KEY 설정 |
| Hugging Face | unified router를 통한 20개 이상 open model(Qwen, DeepSeek, Kimi 등) | HF_TOKEN 설정 |
| AWS Bedrock | native Converse API로 Claude, Nova, Llama, DeepSeek 사용 | IAM role 또는 aws configure(guide) |
| Kilo Code | KiloCode-hosted 모델 | KILOCODE_API_KEY 설정 |
| OpenCode Zen | 선별 모델을 pay-as-you-go로 사용 | OPENCODE_ZEN_API_KEY 설정 |
| OpenCode Go | open model용 월 $10 subscription | OPENCODE_GO_API_KEY 설정 |
| DeepSeek | DeepSeek API 직접 접근 | DEEPSEEK_API_KEY 설정 |
| NVIDIA NIM | build.nvidia.com 또는 local NIM을 통한 Nemotron 모델 | NVIDIA_API_KEY 설정. 선택: NVIDIA_BASE_URL |
| GitHub Copilot | GitHub Copilot subscription(GPT-5.x, Claude, Gemini 등) | hermes model OAuth 또는 COPILOT_GITHUB_TOKEN / GH_TOKEN |
| GitHub Copilot ACP | local copilot CLI를 실행하는 Copilot ACP agent backend | hermes model(copilot CLI + copilot login 필요) |
| Vercel AI Gateway | Vercel AI Gateway routing | AI_GATEWAY_API_KEY 설정 |
| Custom Endpoint | VLLM, SGLang, Ollama 또는 OpenAI-compatible API | base URL + API key 설정 |
처음이라면 provider 하나를 고르고, 바꿔야 할 이유가 분명하지 않으면 기본값을 그대로 쓰는 편이 좋습니다. 전체 provider 목록과 환경변수, 설정 단계는 Providers 페이지에 있습니다.
Hermes Agent는 최소 64,000 tokens context를 가진 모델이 필요합니다. 더 작은 context window를 가진 모델은 multi-step tool-calling workflow에 필요한 작업 메모리를 유지하지 못하므로 시작 시 거부됩니다. 대부분의 hosted model(Claude, GPT, Gemini, Qwen, DeepSeek)은 이 조건을 쉽게 충족합니다. local model을 실행한다면 context size를 최소 64K로 설정하세요. 예: llama.cpp의 --ctx-size 65536, Ollama의 -c 65536.
hermes model로 언제든 provider를 바꿀 수 있습니다. 특정 provider에 lock-in되지 않습니다. 지원 provider 전체 목록과 설정 세부 정보는 AI Providers를 참고하세요.
설정 저장 방식
Hermes는 secret과 일반 설정을 분리합니다.
- Secrets and tokens -
~/.hermes/.env - Non-secret settings -
~/.hermes/config.yaml
값을 올바른 위치에 넣는 가장 쉬운 방법은 CLI를 사용하는 것입니다.
hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker
hermes config set OPENROUTER_API_KEY sk-or-...
Hermes가 값의 성격에 맞게 올바른 파일로 자동 저장합니다.
3. 첫 채팅 실행
hermes # classic CLI
hermes --tui # modern TUI (recommended)
model, 사용 가능한 tools, skills가 표시된 welcome banner가 보입니다. 처음에는 구체적이고 검증하기 쉬운 prompt를 사용하세요.
Hermes는 두 가지 terminal interface를 제공합니다. classic prompt_toolkit CLI와, modal overlay, mouse selection, non-blocking input을 갖춘 새로운 TUI입니다. 둘은 같은 sessions, slash commands, config를 공유합니다. hermes와 hermes --tui를 각각 실행해 보고 편한 쪽을 고르세요.
Summarize this repo in 5 bullets and tell me what the main entrypoint is.
Check my current directory and tell me what looks like the main project file.
Help me set up a clean GitHub PR workflow for this codebase.
성공 기준:
- banner에 선택한 model/provider가 표시됩니다.
- Hermes가 오류 없이 응답합니다.
- 필요한 경우 tool을 사용할 수 있습니다. 예: terminal, file read, web search.
- 한 턴을 넘어서도 대화가 정상적으로 이어집니다.
여기까지 되면 가장 어려운 부분은 넘긴 것입니다.
4. Session 재개 확인
다음 단계로 넘어가기 전에 resume이 동작하는지 확인하세요.
hermes --continue # 가장 최근 session 재개
hermes -c # short form
방금 사용한 session으로 돌아와야 합니다. 그렇지 않다면 같은 profile 안에 있는지, session이 실제로 저장됐는지 확인하세요. 여러 설정이나 여러 기기를 다룰 때 이 부분이 중요해집니다.
5. 핵심 기능 사용해 보기
Terminal 사용
What's my disk usage? Show the top 5 largest directories.
agent가 사용자를 대신해 terminal command를 실행하고 결과를 보여줍니다.
Slash commands
/를 입력하면 모든 명령의 autocomplete dropdown이 열립니다.
| Command | 기능 |
|---|---|
/help | 사용 가능한 명령 표시 |
/tools | 사용 가능한 tools 목록 표시 |
/model | model을 대화형으로 전환 |
/personality pirate | personality 예시 사용 |
/save | 대화 저장 |
Multi-line input
새 줄을 추가하려면 Alt+Enter, Ctrl+J, Shift+Enter를 누릅니다. Shift+Enter는 terminal이 Enter와 구분되는 sequence를 보낼 때만 동작합니다. 기본적으로 Kitty / foot / WezTerm / Ghostty에서 동작하며, Kitty keyboard protocol을 켜면 iTerm2 / Alacritty / VS Code terminal에서도 사용할 수 있습니다. Alt+Enter와 Ctrl+J는 모든 terminal에서 동작합니다.
Agent 중단
agent가 너무 오래 걸리면 새 메시지를 입력하고 Enter를 누르세요. 현재 작업을 중단하고 새 지시로 전환합니다. Ctrl+C도 사용할 수 있습니다.
6. 다음 layer 추가
기본 채팅이 동작한 뒤에만 추가하세요. 필요한 항목을 고르면 됩니다.
Bot 또는 shared assistant
hermes gateway setup # Interactive platform configuration
Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Microsoft Teams를 연결할 수 있습니다.
Automation and tools
hermes tools- platform별 tool access 조정hermes skills- 재사용 가능한 workflow 검색 및 설치- Cron - bot 또는 CLI 설정이 안정화된 뒤에만 추가
Sandboxed terminal
안전을 위해 agent를 Docker container 또는 remote server에서 실행할 수 있습니다.
hermes config set terminal.backend docker # Docker isolation
hermes config set terminal.backend ssh # Remote server
Voice mode
# Hermes install directory에서 실행합니다.
# curl installer 기준 경로:
# Linux/macOS: ~/.hermes/hermes-agent
# Windows: %LOCALAPPDATA%\hermes\hermes-agent
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"
# 무료 local speech-to-text용 faster-whisper 포함
그 다음 CLI에서 /voice on을 실행합니다. 녹음하려면 Ctrl+B를 누르세요. 자세한 내용은 Voice Mode를 참고하세요.
Skills
hermes skills search kubernetes
hermes skills install openai/skills/k8s
또는 chat session 안에서 /skills를 사용하세요.
MCP servers
# ~/.hermes/config.yaml에 추가
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
Editor integration (ACP)
ACP support는 standard [all] extras에 포함되어 있으므로 curl installer를 사용했다면 이미 들어 있습니다. 다음만 실행하세요.
hermes acp
[all] 없이 설치했다면 먼저 cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]"를 실행하세요.
자세한 내용은 ACP Editor Integration을 참고하세요.
자주 막히는 지점
시간을 가장 많이 쓰게 만드는 문제들입니다.
| 증상 | 가능성 높은 원인 | 해결 |
|---|---|---|
| Hermes는 열리지만 비어 있거나 깨진 응답을 준다 | provider auth 또는 model 선택이 잘못됨 | hermes model을 다시 실행하고 provider, model, auth 확인 |
| custom endpoint가 "동작"하지만 이상한 응답을 준다 | base URL, model name이 틀렸거나 실제로 OpenAI-compatible이 아님 | 별도 client로 endpoint를 먼저 검증 |
| gateway는 시작되지만 아무도 메시지를 보낼 수 없다 | bot token, allowlist, platform 설정이 미완성 | hermes gateway setup 재실행 후 hermes gateway status 확인 |
hermes --continue가 이전 session을 찾지 못한다 | profile이 바뀌었거나 session이 저장되지 않음 | hermes sessions list 확인, 올바른 profile인지 확인 |
| model unavailable 또는 이상한 fallback 동작 | provider routing 또는 fallback 설정이 너무 공격적임 | 기본 provider가 안정화될 때까지 routing 끄기 |
hermes doctor가 config 문제를 표시한다 | config 값 누락 또는 오래된 값 | config를 수정하고, 기능 추가 전에 plain chat 재테스트 |
Recovery Toolkit
뭔가 이상하다면 이 순서로 확인하세요.
hermes doctorhermes modelhermes setuphermes sessions listhermes --continuehermes gateway status
이 순서가 막연히 고장 난 상태에서 다시 알려진 상태로 돌아가는 가장 빠른 경로입니다.
빠른 참조
| Command | Description |
|---|---|
hermes | 채팅 시작 |
hermes model | LLM provider와 model 선택 |
hermes tools | platform별 활성 tool 설정 |
hermes setup | 전체 setup wizard. 한 번에 설정 구성 |
hermes doctor | 문제 진단 |
hermes update | 최신 버전으로 업데이트 |
hermes gateway | messaging gateway 시작 |
hermes --continue | 마지막 session 재개 |
다음 단계
- CLI Guide - terminal interface 익히기
- Configuration - 설정 커스터마이즈
- Messaging Gateway - Telegram, Discord, Slack, WhatsApp, Signal, Email, Home Assistant, Teams 등 연결
- Tools & Toolsets - 사용 가능한 기능 살펴보기
- AI Providers - 전체 provider 목록과 설정 세부 정보
- Skills System - 재사용 가능한 workflow와 knowledge
- Tips & Best Practices - power user tips