빠른 시작
이 가이드는 제로 상태에서 실제 사용 후에도 작동하는 Hermes 설정까지 안내합니다. 설치하고, 공급자를 선택하고, 작동 중인 채팅을 확인하고, 문제가 발생했을 때 무엇을 해야 하는지 정확히 알아보세요.
시청을 선호하시나요?
Onchain AI Garage는 설치, 설정 및 기본 명령에 대한 마스터클래스 연습을 함께 제공합니다. 동영상으로 따라하고 싶다면 이 페이지와 함께 사용하면 좋습니다. 자세한 내용은 전체 Hermes 에이전트 튜토리얼 및 사용 사례 재생 목록을 참조하세요.
이것은 누구를 위한 것인가
- 새로운 제품이며 작업 설정에 대한 최단 경로를 원함
- 공급자를 전환하고 구성 실수로 시간을 낭비하고 싶지 않습니다.
- 팀, 봇 또는 상시 작동 워크플로를 위한 Hermes 설정
- "설치했지만 여전히 아무 작업도 수행하지 않음"에 지쳤습니다.
가장 빠른 경로
목표와 일치하는 행을 선택하세요.
| 목표 | 이 작업을 먼저 수행하세요. | 그럼 이렇게 하세요 |
|---|---|---|
| 난 그냥 Hermes가 내 컴퓨터에서 작동하길 바랄 뿐이야 | hermes setup | 실제 채팅을 실행하고 응답하는지 확인하세요. |
| 나는 이미 내 서비스 제공자를 알고 있습니다. | hermes model | 구성을 저장한 후 채팅을 시작하세요 |
| 봇이나 Always-On 설정을 원합니다 | hermes gateway setup CLI 작동 후 | Telegram, Discord, Slack 또는 기타 플랫폼 연결 |
| 로컬 또는 자체 호스팅 모델을 원합니다 | hermes model → 커스텀 엔드포인트 | 엔드포인트, 모델 이름, 컨텍스트 길이 확인 |
| 다중 공급자 대체를 원함 | hermes model 첫 번째 | 기본 채팅이 작동한 후에만 라우팅 및 대체를 추가하세요. |
경험 법칙: Hermes가 일반 채팅을 완료할 수 없는 경우 아직 더 많은 기능을 추가하지 마세요. 먼저 하나의 깔끔한 대화를 진행한 다음 게이트웨이, 크론, 기술, 음성 또는 라우팅을 계층화하세요.
1. 헤르메스 에이전트 설치
옵션 A — pip(가장 간단함):
pip install hermes-agent
hermes postinstall # optional: installs Node.js, browser, ripgrep, ffmpeg + runs setup
PyPI 릴리스는 main의 모든 커밋이 아니라 태그가 지정된 버전(주/부 릴리스)을 추적합니다. 최신 기술을 사용하려면 옵션 B를 사용하세요.
옵션 B — git 설치 프로그램(메인 브랜치 추적):
# Linux / macOS / WSL2 / Android (Termux)
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
Android / Termux
휴대폰에 설치하는 경우 테스트된 수동 경로, 지원되는 추가 기능 및 현재 Android 관련 제한 사항은 전용 Termux 가이드를 참조하세요.
Windows Users
WSL2를 먼저 설치한 다음, WSL2 터미널 내에서 위 명령을 실행하세요.
완료되면 셸을 다시 로드합니다.
source ~/.bashrc # or source ~/.zshrc
자세한 설치 옵션, 필수 구성 요소, 문제 해결 방법은 설치 가이드를 참조하세요.
2. 제공자를 선택하세요
가장 중요한 단일 설정 단계입니다. 대화식으로 선택 사항을 살펴보려면 hermes model을 사용하세요.
hermes model
좋은 기본값:
| 공급자 | 그것은 무엇입니까 | 설정 방법 |
|---|---|---|
| 누스 포털 | 구독 기반, 제로 구성 | hermes model을 통한 OAuth 로그인 |
| OpenAI 코덱스 | ChatGPT OAuth, Codex 모델 사용 | hermes model을 통한 장치 코드 인증 |
| 인류학 | Claude 모델 직접 — 최대 요금제 + 추가 사용량 크레딧(OAuth) 또는 토큰당 지불을 위한 API 키 | hermes model → OAuth 로그인(Max + 추가 크레딧 필요) 또는 Anthropic API 키 |
| 오픈라우터 | 여러 모델에 걸친 다중 공급자 라우팅 | API 키를 입력하세요 |
| Z.AI | GLM / Zhipu 호스팅 모델 | GLM_API_KEY / ZAI_API_KEY 설정 |
| 키미/문샷 | Moonshot에서 호스팅하는 코딩 및 채팅 모델 | KIMI_API_KEY(또는 Kimi-Coding 관련 KIMI_CODING_API_KEY) 설정 |
| 키미 / 문샷 차이나 | 중국 지역 Moonshot 엔드포인트 | KIMI_CN_API_KEY 설정 |
| 아르시 AI | 트리니티 모델 | ARCEEAI_API_KEY 설정 |
| GMI 클라우드 | 다중 모델 직접 API | GMI_API_KEY 설정 |
| MiniMax(OAuth) | 브라우저 OAuth를 통한 MiniMax-M2.7 - API 키가 필요하지 않습니다. | hermes model → MiniMax(OAuth) |
| 미니맥스 | 국제 MiniMax 엔드포인트 | MINIMAX_API_KEY 설정 |
| 미니맥스 차이나 | 중국 지역 MiniMax 엔드포인트 | MINIMAX_CN_API_KEY 설정 |
| 알리바바 클라우드 | DashScope를 통한 Qwen 모델 | DASHSCOPE_API_KEY 설정 |
| 껴안는 얼굴 | 통합 라우터(Qwen, DeepSeek, Kimi 등)를 통한 20개 이상의 개방형 모델 | HF_TOKEN 설정 |
| AWS 베드락 | 기본 Converse API를 통한 Claude, Nova, Llama, DeepSeek | IAM 역할 또는 aws configure (가이드) |
| 킬로 코드 | KiloCode 호스팅 모델 | KILOCODE_API_KEY 설정 |
| 오픈코드 젠 | 선별된 모델에 대한 종량제 액세스 | OPENCODE_ZEN_API_KEY 설정 |
| 오픈코드 고 | 오픈 모델 월 $10 구독 | OPENCODE_GO_API_KEY 설정 |
| 딥시크 | 직접 DeepSeek API 액세스 | DEEPSEEK_API_KEY 설정 |
| 엔비디아 님 | build.nvidia.com 또는 로컬 NIM을 통한 Nemotron 모델 | NVIDIA_API_KEY 설정(선택 사항: NVIDIA_BASE_URL) |
| GitHub 부조종사 | GitHub Copilot 구독(GPT-5.x, Claude, Gemini 등) | hermes model 또는 COPILOT_GITHUB_TOKEN / GH_TOKEN을 통한 OAuth |
| GitHub 부조종사 ACP | Copilot ACP 에이전트 백엔드(로컬 copilot CLI 생성) | hermes model (copilot CLI + copilot login 필요) |
| Vercel AI 게이트웨이 | Vercel AI 게이트웨이 라우팅 | AI_GATEWAY_API_KEY 설정 |
| 커스텀 엔드포인트 | VLLM, SGLang, Ollama 또는 모든 OpenAI 호환 API | 기본 URL + API 키 설정 |
대부분의 최초 사용자의 경우: 공급자를 선택하고 변경 이유를 모르는 경우 기본값을 수락합니다. 환경 변수 및 설정 단계가 포함된 전체 공급자 카탈로그는 공급자 페이지에 있습니다.
Minimum context: tokens
Hermes 에이전트에는 최소 64,000개의 토큰 컨텍스트가 있는 모델이 필요합니다. 창이 더 작은 모델은 다단계 도구 호출 워크플로우를 위한 충분한 작업 메모리를 유지할 수 없으며 시작 시 거부됩니다. 대부분의 호스팅 모델(Claude, GPT, Gemini, Qwen, DeepSeek)은 이를 쉽게 충족합니다. 로컬 모델을 실행하는 경우 컨텍스트 크기를 최소 로 설정하세요(예: llama.cpp의 경우 --ctx-size 65536, Ollama의 경우 -c 65536).
팁
hermes model을 사용하면 언제든지 제공업체를 변경할 수 있습니다. — 종속되지 않습니다. 지원되는 모든 공급자의 전체 목록과 설정 세부 정보는 AI 공급자를 참조하세요.
설정이 저장되는 방식
Hermes는 비밀을 일반 구성과 분리합니다.
- 비밀번호 및 토큰 →
~/.hermes/.env - 비밀이 아닌 설정 →
~/.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-...
올바른 값이 자동으로 올바른 파일로 이동됩니다.
3. 첫 번째 채팅 실행
hermes # classic CLI
hermes --tui # modern TUI (recommended)
모델, 사용 가능한 도구 및 기술이 포함된 환영 배너가 표시됩니다. 구체적이고 확인하기 쉬운 프롬프트를 사용하세요.
Pick your interface
Hermes는 클래식 prompt_toolkit CLI와 모달 오버레이, 마우스 선택 및 비차단 입력을 갖춘 최신 TUI라는 두 가지 터미널 인터페이스를 제공합니다. 둘 다 동일한 세션, 슬래시 명령 및 구성을 공유합니다. 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.
```
**성공의 모습:**
- 배너에는 선택한 모델/공급업체가 표시됩니다.
- 헤르메스는 오류 없이 대답합니다.
- 필요한 경우 도구를 사용할 수 있습니다(터미널, 파일 읽기, 웹 검색).
- 1턴 이상 정상적으로 대화가 이어집니다.
그것이 효과가 있다면 가장 어려운 부분을 지나친 것입니다.
## 4. 세션 작동 확인 \{#4-verify-sessions-work}
계속 진행하기 전에 이력서가 제대로 작동하는지 확인하세요.
```bash
hermes --continue # Resume the most recent session
hermes -c # Short form
```
방금 진행한 세션으로 돌아가게 됩니다. 그렇지 않은 경우 동일한 프로필에 있는지, 세션이 실제로 저장되었는지 확인하세요. 이는 나중에 여러 설정이나 기계를 조작할 때 중요합니다.
## 5. 주요 기능을 사용해 보세요 \{#5-try-key-features}
### 터미널 사용 \{#use-the-terminal}
```
❯ What's my disk usage? Show the top 5 largest directories.
```
에이전트는 사용자를 대신하여 터미널 명령을 실행하고 결과를 표시합니다.
### 슬래시 명령 \{#slash-commands}
모든 명령의 자동 완성 드롭다운을 보려면 `/`을 입력하세요.
| 명령 | 기능 |
|---------|-------------|
| `/help` | 사용 가능한 모든 명령 표시 |
| `/tools` | 사용 가능한 도구 나열 |
| `/model` | 대화형으로 모델 전환 |
| `/personality pirate` | 재미있는 성격을 시험해 보세요 |
| `/save` | 대화를 저장하세요 |
### 다중 라인 입력 \{#multi-line-input}
새 줄을 추가하려면 `Alt+Enter`, `Ctrl+J` 또는 `Shift+Enter`을 누르세요. `Shift+Enter`에는 고유한 시퀀스로 전송하는 터미널이 필요합니다(기본적으로 Kitty/foot/WezTerm/Ghostty, Kitty 키보드 프로토콜이 활성화되면 iTerm2/Alacritty/VS Code 터미널). `Alt+Enter` 및 `Ctrl+J`은 모든 터미널에서 작동합니다.
### 에이전트 중단 \{#interrupt-the-agent}
에이전트가 너무 오래 걸리는 경우 새 메시지를 입력하고 Enter를 누르세요. 그러면 현재 작업이 중단되고 새 지침으로 전환됩니다. `Ctrl+C`도 작동합니다.
## 6. 다음 레이어 추가 \{#6-add-the-next-layer}
기본 채팅이 작동한 후에만 가능합니다. 필요한 것을 선택하세요:
### 봇 또는 공유 어시스턴트 \{#bot-or-shared-assistant}
```bash
hermes gateway setup # Interactive platform configuration
```
연결 [텔레그램](/docs/user-guide/messaging/telegram), [Discord](/docs/user-guide/messaging/discord), [Slack](/docs/user-guide/messaging/slack), [WhatsApp](/docs/user-guide/messaging/whatsapp), [Signal](/docs/user-guide/messaging/signal), [이메일](/docs/user-guide/messaging/email) 또는 [홈 어시스턴트](/docs/user-guide/messaging/homeassistant) 또는 [Microsoft Teams](../user-guide/features/voice-mode.md).
### 자동화 및 도구 \{#automation-and-tools}
- `hermes tools` — 플랫폼별 도구 액세스 조정
- `hermes skills` — 재사용 가능한 워크플로 검색 및 설치
- Cron — 봇 또는 CLI 설정이 안정된 후에만
### 샌드박스 터미널 \{#sandboxed-terminal}
안전을 위해 Docker 컨테이너 또는 원격 서버에서 에이전트를 실행하십시오.
```bash
hermes config set terminal.backend docker # Docker isolation
hermes config set terminal.backend ssh # Remote server
```
### 음성 모드 \{#voice-mode}
```bash
# From the Hermes install directory (the curl installer placed it at
# ~/.hermes/hermes-agent on Linux/macOS or %LOCALAPPDATA%\hermes\hermes-agent on Windows):
cd ~/.hermes/hermes-agent
uv pip install -e ".[voice]"
# Includes faster-whisper for free local speech-to-text
```
그런 다음 CLI에서: `/voice on`. 녹음하려면 `Ctrl+B`을 누르세요. [음성 모드](../user-guide/features/acp.md)를 참조하세요.
### 기술 \{#skills}
```bash
hermes skills search kubernetes
hermes skills install openai/skills/k8s
```
또는 채팅 세션 내에서 `/skills`을 사용하세요.
### MCP 서버 \{#mcp-servers}
```yaml
# Add to ~/.hermes/config.yaml
mcp_servers:
github:
command: npx
args: ["-y", "@modelcontextprotocol/server-github"]
env:
GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
```
### 에디터 통합(ACP) \{#editor-integration-acp}
ACP 지원은 표준 `[all]` 추가 기능과 함께 제공되므로 컬 설치 프로그램에 이미 포함되어 있습니다. 그냥 실행하세요:
```bash
hermes acp
```
(`[all]` 없이 설치한 경우 먼저 `cd ~/.hermes/hermes-agent && uv pip install -e ".[acp]"`을 실행하세요.)
[ACP 편집기 통합](../user-guide/cli.md)을 참조하세요.
---
## 일반적인 실패 모드 \{#common-failure-modes}
가장 많은 시간을 낭비하는 문제는 다음과 같습니다.
| 증상 | 가능한 원인 | 수정 |
|---|---|---|
| Hermes가 열렸지만 비어 있거나 깨진 응답을 제공합니다. | 공급자 인증 또는 모델 선택이 잘못되었습니다. | `hermes model`을 다시 실행하고 공급자, 모델 및 인증을 확인하세요. |
| 사용자 정의 엔드포인트는 "작동"하지만 쓰레기를 반환합니다. | 기본 URL, 모델 이름이 잘못되었거나 실제로 OpenAI와 호환되지 않음 | 먼저 별도의 클라이언트에서 엔드포인트를 확인하세요. |
| 게이트웨이가 시작되었지만 아무도 메시지를 보낼 수 없습니다. | 봇 토큰, 허용 목록 또는 플랫폼 설정이 완료되지 않았습니다. | `hermes gateway setup`을 다시 실행하고 `hermes gateway status`을 확인하세요. |
| `hermes --continue`은 이전 세션을 찾을 수 없습니다. | 전환된 프로필 또는 세션이 저장되지 않았습니다. | `hermes sessions list`을 확인하고 올바른 프로필에 있는지 확인하세요. |
| 모델을 사용할 수 없거나 이상한 대체 동작 | 공급자 라우팅 또는 대체 설정이 너무 공격적입니다. | 기본 공급자가 안정될 때까지 라우팅을 계속 중단하세요. |
| `hermes doctor` 플래그 구성 문제 | 구성 값이 누락되었거나 오래되었습니다. | 구성을 수정하고 기능을 추가하기 전에 일반 채팅을 다시 테스트하세요. |
## 복구 툴킷 \{#recovery-toolkit}
뭔가 기분이 좋지 않으면 다음 순서를 사용하십시오.
1. `hermes doctor`
2. `hermes model`
3. `hermes setup`
4. `hermes sessions list`
5. `hermes --continue`
6. `hermes gateway status`
이 시퀀스를 통해 "깨진 느낌"에서 알려진 상태로 빠르게 돌아갈 수 있습니다.
---
## 빠른 참조 \{#quick-reference}
| 명령 | 설명 |
|---------|-------------|
| `hermes` | 채팅 시작 |
| `hermes model` | LLM 제공업체와 모델을 선택하세요 |
| `hermes tools` | 플랫폼별로 활성화할 도구 구성 |
| `hermes setup` | 전체 설정 마법사(모든 것을 한 번에 구성) |
| `hermes doctor` | 문제 진단 |
| `hermes update` | 최신 버전으로 업데이트 |
| `hermes gateway` | 메시징 게이트웨이 시작 |
| `hermes --continue` | 마지막 세션 재개 |
## 다음 단계 \{#next-steps}
- **[CLI 가이드](../user-guide/configuration.md)** — 터미널 인터페이스 마스터
- **[구성](../user-guide/messaging/index.md)** — 설정을 사용자 정의하세요
- **[메시징 게이트웨이](../user-guide/features/tools.md)** — Telegram, Discord, Slack, WhatsApp, Signal, 이메일, Home Assistant, Teams 등을 연결하세요
- **[도구 및 도구 세트](../integrations/providers.md)** — 사용 가능한 기능 살펴보기
- **[AI 제공업체](../user-guide/features/skills.md)** — 전체 제공업체 목록 및 설정 세부정보
- **[스킬 시스템](../guides/tips.md)** — 재사용 가능한 작업 흐름 및 지식
- **[팁 및 모범 사례](../guides/tips.md)** — 고급 사용자 팁