> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gravitex.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Hermes Agents

> Hermes Agent — 셀프 호스팅 자기 학습 AI 에이전트 연동 가이드 (GravitexAI)

## 1. 개요

**Hermes Agent**는 [Nous Research](https://nousresearch.com/)가 만든 오픈소스(MIT) 셀프 호스팅 AI 에이전트로, **사용자와 함께 성장하는** 에이전트입니다. IDE에 묶인 코딩 copilot도, 단일 API를 감싼 챗봇도 아닙니다. 자체 서버에서 실행되며, 학습한 내용을 기억하고 오래 실행될수록 더 강력해집니다.

**GravitexAI**(OpenAI 호환 API)와 함께 하나의 키로 GPT, Claude, Gemini, DeepSeek 및 400개 이상의 선도 모델에 Hermes가 접근할 수 있습니다.

<CardGroup cols={2}>
  <Card title="영구 메모리" icon="brain">
    세션 간 프로젝트와 솔루션을 기억
  </Card>

  <Card title="자동 Skill 합성" icon="wand-magic-sparkles">
    경험에서 재사용 가능한 Skill 생성
  </Card>

  <Card title="멀티 플랫폼 도달" icon="message-circle">
    Telegram / Discord / Slack / WhatsApp / Signal / Email / CLI
  </Card>

  <Card title="실제 샌드박싱" icon="shield">
    Local / Docker / SSH / Singularity / Modal 백엔드
  </Card>
</CardGroup>

<Info>
  Website: [hermes-agent.nousresearch.com](https://hermes-agent.nousresearch.com) ｜ Repo: [github.com/NousResearch/hermes-agent](https://github.com/NousResearch/hermes-agent) ｜ License: MIT
</Info>

## 2. 핵심 기능

* **영구 메모리** — 로컬 벡터 저장소가 대화 및 프로젝트 지식을 보존
* **학습 루프** — 성공한 솔루션이 재사용 가능한 Skill로 정제됨
* **예약 자동화** — 자연어로 cron job 설명
* **위임 서브에이전트** — 격리된 터미널 및 Python RPC, 컨텍스트 오염 없음
* **전체 웹 제어** — 브라우저 자동화, 비전, 이미지 생성, TTS
* **실제 샌드박스** — local, Docker, SSH, Singularity, Modal

## 3. 사전 요구사항

* [GravitexAI 콘솔](https://maas.gravitex.ai/#/keys)에서 API 키 생성
* 서버 또는 워크스테이션: Linux / macOS / WSL2 / Android (Termux)
* Windows 사용자: PowerShell (초기 베타)

<Warning>
  Hermes Agent는 **≥ 64K 토큰 컨텍스트를 지원하는 모델**이 필요합니다. Claude, GPT, Gemini, DeepSeek 모두 해당됩니다.
</Warning>

## 4. 설치

한 명령으로 모든 것을 처리합니다:

<CodeGroup>
  ```bash Linux / macOS / WSL2 / Termux theme={null}
  curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
  source ~/.zshrc   # or source ~/.bashrc
  ```

  ```powershell Windows PowerShell (beta) theme={null}
  irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
  ```
</CodeGroup>

모든 의존성은 `~/.hermes/hermes-agent` 아래에 배치됩니다. 수동 `pip install`은 필요 없습니다.

## 5. GravitexAI 설정

Hermes Agent는 **Custom Endpoint** 경로를 통해 OpenAI 호환 서비스에 연결합니다.

### 옵션 A — 대화형 CLI (권장)

```bash theme={null}
hermes model
```

\*\*Custom endpoint (self-hosted / VLLM / etc.)\*\*를 선택하고 다음을 입력합니다:

| Field        | Value                                     |
| ------------ | ----------------------------------------- |
| API Base URL | `https://api.gravitex.ai/v1`              |
| API Key      | GravitexAI 키 (`sk-...`)                   |
| Model name   | `claude-sonnet-4-6` (또는 GravitexAI 모델 ID) |

설정은 `~/.hermes/config.yaml`에 저장됩니다.

### 옵션 B — config.yaml 수동 편집

`~/.hermes/config.yaml`을 열고 다음을 추가합니다:

```yaml theme={null}
model:
  provider: custom
  model: claude-sonnet-4-6
  base_url: https://api.gravitex.ai/v1
  api_key: sk-your-gravitexai-key
```

<Tip>
  `base_url`이 설정되면 Hermes는 `provider`를 무시하고 엔드포인트를 직접 호출합니다. API 키는 `model.api_key`에서 읽으며, 없으면 `OPENAI_API_KEY` 환경 변수로 대체됩니다.
</Tip>

### 옵션 C — 환경 변수

```bash theme={null}
export OPENAI_BASE_URL=https://api.gravitex.ai/v1
export OPENAI_API_KEY=sk-your-gravitexai-key
hermes model   # the Custom Endpoint wizard will pick them up
```

### 옵션 D — 여러 명명된 엔드포인트

여러 엔드포인트를 미리 선언하고 런타임에 전환:

```yaml theme={null}
custom_providers:
  - name: gravitex
    base_url: https://api.gravitex.ai/v1
    key_env: GRAVITEX_API_KEY
    api_mode: chat_completions
  - name: gravitex-anthropic
    base_url: https://api.gravitex.ai/anthropic
    key_env: GRAVITEX_API_KEY
    api_mode: anthropic_messages
```

`hermes model`로 전환하거나 `model.provider: gravitex`를 직접 설정하세요.

## 6. 실행 및 확인

```bash theme={null}
hermes setup     # first-run wizard (skip if already configured)
hermes doctor    # health check: validates key & /models
hermes start     # launch the gateway
```

이제 CLI, Telegram, Discord, Slack 등 연결된 채널에서 Hermes와 대화할 수 있습니다.

## 7. 추천 모델

| Use case | Model ID                    | Notes                    |
| -------- | --------------------------- | ------------------------ |
| 복잡한 작업   | `claude-sonnet-4-6`         | 최고의 tool calling 및 장기 작업 |
| 코딩       | `deepseek-v3-2-251201`      | 우수한 코드, 우수한 가성비          |
| 일상 채팅    | `gpt-5.5`                   | 강력한 올라운더                 |
| 긴 컨텍스트   | `gemini-3.1-pro-preview`    | 대용량 컨텍스트 윈도우             |
| 저지연      | `claude-haiku-4-5-20251001` | 빠른 응답                    |
| 심층 추론    | `claude-opus-4-7`           | 복잡한 추론, 알고리즘 / 논리        |

모든 모델은 [GravitexAI 마켓플레이스](https://maas.gravitex.ai/#/models)에서 확인하세요.

## 8. 메시징 채널

| Platform | Config location              |
| -------- | ---------------------------- |
| Telegram | `channels.telegram.token`    |
| Discord  | `channels.discord.bot_token` |
| Slack    | `channels.slack.bot_token`   |
| WhatsApp | QR 스캔                        |
| Signal   | linked-device QR             |
| Email    | SMTP / IMAP                  |
| CLI      | `hermes chat`                |

## 9. 확장

### Skills

```bash theme={null}
hermes skills search kubernetes
hermes skills install openai/skills/k8s
```

Hermes는 **세션에서 Skill을 자동 합성**하고 나중에 재사용합니다 — 대부분의 에이전트 프레임워크와 차별화되는 기능입니다.

### MCP 서버

`~/.hermes/config.yaml`에 MCP 도구 추가:

```yaml theme={null}
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
```

### 샌드박스 백엔드

```yaml theme={null}
sandbox:
  backend: docker   # local / docker / ssh / singularity / modal
```

## 10. 명령어

| Command                             | Purpose               |
| ----------------------------------- | --------------------- |
| `hermes setup`                      | 첫 실행 마법사              |
| `hermes model`                      | provider 및 모델 선택 / 전환 |
| `hermes doctor`                     | 상태 점검                 |
| `hermes start` / `stop` / `restart` | gateway 제어            |
| `hermes chat`                       | 터미널 채팅                |
| `hermes skills`                     | skill 관리              |
| `hermes logs --follow`              | 로그 tail               |
| `hermes update`                     | 업그레이드                 |

## 11. 문제 해결

<AccordionGroup>
  <Accordion title="401 / invalid API key">
    * `~/.hermes/config.yaml`의 `api_key`에 불필요한 문자가 없는지 확인
    * 여러 `*_API_KEY` 환경 변수가 있을 때 Hermes는 각 키를 해당 base URL에 범위 지정함
  </Accordion>

  <Accordion title="404 / endpoint not found">
    * `chat_completions` 모드: `base_url`은 반드시 `/v1`로 끝나야 함
    * 네이티브 Claude 프로토콜은 `https://api.gravitex.ai/anthropic`과 `api_mode: anthropic_messages` 사용
  </Accordion>

  <Accordion title="Context too short">
    Hermes는 ≥ 64K 컨텍스트가 필요합니다. `claude-sonnet-4-6`, `gpt-5.4`, `gemini-3.1-pro-preview` 등을 사용하세요.
  </Accordion>

  <Accordion title="설정 변경이 무시됨">
    `config.yaml`이 단일 진실 공급원입니다. `.env`에 오래된 `OPENAI_BASE_URL`이 남아 있으면 `hermes setup`을 실행하여 마이그레이션을 트리거하세요.
  </Accordion>
</AccordionGroup>