# 로컬 Ollama 모델을 Hermes Agent에 연결하기

> 호스트의 Ollama 모델을 hermes model의 사용자 지정 엔드포인트로 연결하고, 컨텍스트가 32K인 작은 모델이 왜 실패하는지 로그로 확인한 뒤, 64K 컨텍스트 Modelfile로 만든 27B 모델에서 도구 호출까지 되는 것을 확인합니다.

- 주소: https://copyandrun.com/blog/hermes-agent-local-ollama/
- 분야: AX
- 발행일: 2026-10-24
- 태그: Hermes Agent, Ollama, 로컬 LLM, 컨텍스트

외부 API 키 없이 에이전트를 쓰려면 모델을 내 PC의 Ollama에서 가져와야 합니다. 이 글에서는 [1편](/blog/hermes-agent-install-in-docker/)에서 만든 컨테이너의 Hermes Agent를 호스트의 Ollama에 연결합니다. `hermes model`로 연결하는 과정, 설정 파일에 남는 값, 그리고 직접 부딪힌 문제를 순서대로 기록했습니다. 문제는 모델이 작아서 도구 호출을 못 하는 것이 아니라, 컨텍스트 창이 64K 토큰보다 작으면 Hermes가 아예 시작하지 않는 것이었습니다.

이 글은 Hermes Agent 실무 시리즈의 2편입니다. 1편은 [컨테이너에 설치하고 첫 실행하기](/blog/hermes-agent-install-in-docker/), 다음 3편은 [명령 승인 절차 확인하기](/blog/hermes-agent-command-approval/)입니다.

## 준비물

| 항목 | 확인한 버전 |
|---|---|
| 1편의 컨테이너 | `cr-hermes-lab`, Hermes Agent v0.22.5 |
| Ollama (호스트) | 0.32.15 |
| 모델 | qwen3.8:27b, qwen2.5:3b-instruct-q4_K_M, exaone3.5:2.4b (모두 미리 받아 둔 모델) |
| GPU | 27B 모델을 올릴 수 있는 환경 (이 글의 환경은 `ollama ps`에서 100% GPU로 표시) |

1편에서 만든 `Dockerfile`과 `docker-compose.yml`을 그대로 씁니다. 아래에 같은 내용을 다시 실었으니, 1편을 건너뛰었다면 이 두 파일로 `docker compose up -d --build`부터 시작할 수 있습니다. 1편에서 대시보드를 위해 추가한 환경 변수와 포트도 그대로 들어 있습니다.

```dockerfile
FROM ubuntu:24.04

ENV DEBIAN_FRONTEND=noninteractive
RUN apt-get update \
 && apt-get install -y --no-install-recommends curl git ca-certificates tar xz-utils sudo less procps tmux \
 && rm -rf /var/lib/apt/lists/*

# 에이전트는 일반 사용자로 실행합니다.
RUN useradd -m -s /bin/bash agent \
 && echo "agent ALL=(ALL) NOPASSWD:ALL" > /etc/sudoers.d/agent
USER agent
WORKDIR /home/agent
ENV PATH="/home/agent/.local/bin:${PATH}"

# 브라우저 도구는 이 실습에서 쓰지 않으므로 건너뜁니다.
RUN curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --non-interactive --skip-browser --skip-computer-use

# 연습용 폴더입니다. 컨테이너 안에서 에이전트가 만지는 파일은 여기에만 둡니다.
RUN mkdir -p /home/agent/practice

CMD ["bash"]
```

```yaml
services:
  hermes:
    build: .
    image: cr-hermes:lab
    container_name: cr-hermes-lab
    tty: true
    stdin_open: true
    working_dir: /home/agent
    volumes:
      - hermes-data:/home/agent/.hermes
      - hermes-practice:/home/agent/practice
    extra_hosts:
      - "host.docker.internal:host-gateway"
    environment:
      HERMES_DASHBOARD_BASIC_AUTH_USERNAME: admin
      HERMES_DASHBOARD_BASIC_AUTH_PASSWORD: lab-only-pass
      HERMES_DASHBOARD_BASIC_AUTH_SECRET: lab-only-secret-0123456789abcdef
    ports:
      - "127.0.0.1:5500:9119"

volumes:
  hermes-data:
  hermes-practice:
```

컨테이너가 떠 있는지 확인합니다.

```bash
docker compose up -d
docker compose exec hermes hermes --version
```

## 1. 도구 호출을 지원하는 모델 고르기

Hermes는 파일과 터미널 같은 도구를 모델의 도구 호출 기능으로 실행합니다. 그래서 모델이 도구 호출을 지원해야 합니다. Ollama는 모델마다 지원 기능을 알려 주므로, 호스트에서 확인합니다.

```bash
ollama list
for m in exaone3.5:2.4b qwen2.5:3b-instruct-q4_K_M qwen3.8:27b; do echo "== $m"; ollama show $m | grep -E "context length|^    (completion|tools|thinking|vision)"; done
```

```
# 기대 출력
NAME                          ID              SIZE      MODIFIED
exaone3.5:2.4b                13644fc3d28e    1.6 GB    7 weeks ago
qwen2.5:3b-instruct-q4_K_M    357c53fb659c    1.9 GB    7 weeks ago
nomic-embed-text:latest       0a109f422b47    274 MB    7 weeks ago
qwen3.8:27b                   22130167c4c2    17 GB     2 months ago

== exaone3.5:2.4b
    context length      32768
    completion
== qwen2.5:3b-instruct-q4_K_M
    context length      32768
    completion
    tools
== qwen3.8:27b
    context length      262144
    completion
    vision
    tools
    thinking
```

![ollama list로 받아 둔 모델을 보고 ollama show로 각 모델의 컨텍스트 길이와 tools 지원 여부를 확인한 터미널](https://copyandrun.com/img/hermes-agent-local-ollama/01-ollama-list.png)

`exaone3.5:2.4b`는 `tools` 기능이 없어서 Hermes의 도구를 쓸 수 없습니다. 나머지 둘이 후보입니다. `nomic-embed-text`는 임베딩 모델이라 대화에 쓰지 않습니다. 컨텍스트 길이 항목은 4단계에서 문제의 원인으로 다시 나옵니다.

## 2. hermes model로 사용자 지정 엔드포인트 연결하기

컨테이너 안에서 `hermes model`을 실행합니다. 터미널 화면에서 방향키로 고르는 메뉴입니다.

```bash
docker compose exec hermes hermes model
```

공급자 목록이 길게 나오고, 맨 아래쪽에 `Local models`, `Custom endpoint (enter URL manually)`, `Reasoning effort for the current model...`, `Configure auxiliary models...`, `Leave unchanged`가 있습니다. 이 글에서는 `Custom endpoint (enter URL manually)`를 골랐습니다. 목록 맨 위에서 위쪽 화살표를 4번 누르면 맨 아래로 넘어가 그 항목에 닿습니다. `Local models` 항목은 모델을 새로 내려받을 수 있는 메뉴로 보여서 이 글에서는 열어 보기만 하고 선택하지 않았습니다.

이어서 묻는 값은 다음과 같습니다.

| 질문 | 입력한 값 |
|---|---|
| API base URL | `http://host.docker.internal:11434/v1` |
| API key [optional] | 비워 둠 (Enter) |
| API compatibility mode | `2` (Chat Completions) |
| Select model | 목록 번호 또는 모델 이름 |
| Context length in tokens | 비워 둠 (자동 감지) |
| Display name | 기본값 (Enter) |
| Select reasoning effort | `Skip (keep current)` |

엔드포인트 주소를 넣으면 Hermes가 `/v1/models`로 접속해 보고 `Verified endpoint ... (5 model(s) visible)`이라고 알려 줍니다. 이 메시지가 나오면 컨테이너에서 호스트의 Ollama까지 연결된 것입니다.

![hermes model에서 Custom endpoint로 호스트 Ollama 주소를 입력하자 엔드포인트가 확인되고 API 호환 모드를 묻는 화면](https://copyandrun.com/img/hermes-agent-local-ollama/03-custom-endpoint.png)

호환 모드에서 `2`를 고르면 Ollama가 가진 모델 목록이 번호와 함께 나옵니다.

![호환 모드를 Chat Completions로 고르자 Ollama의 모델 목록이 번호와 함께 나오고 모델 선택을 기다리는 화면](https://copyandrun.com/img/hermes-agent-local-ollama/04-model-choice.png)

먼저 3번 `qwen2.5:3b-instruct-q4_K_M`을 골랐습니다. 도구 호출을 지원하는 가장 작은 모델이라 결과가 어떻게 되는지 보려는 것입니다.

## 3. 설정 파일에 남은 값 확인하기

```bash
docker compose exec hermes bash -lc 'hermes config get model'
```

```
# 기대 출력
default: qwen2.5:3b-instruct-q4_K_M
provider: custom
base_url: http://host.docker.internal:11434/v1
api_mode: chat_completions
```

`~/.hermes/config.yaml`에는 같은 정보가 `model:` 항목과 `custom_providers:` 목록에 함께 들어갑니다. `custom_providers`의 이름은 입력한 주소에서 따온 `Host.docker.internal:11434`로 만들어졌습니다. 이 목록의 `model` 값은 `hermes model`을 실행하던 때의 모델로 남아서, 나중에 `hermes config set model.default`로 모델만 바꾸면 두 값이 달라집니다. 실제로 쓰이는 값은 `model.default` 쪽이었습니다.

## 4. 작은 모델의 실패 확인하기

연습용 폴더에서 `hermes`를 열고 파일 목록을 물어봅니다. 연습용 폴더에는 미리 `memo.txt` 한 개를 만들어 두었습니다.

```bash
docker compose exec hermes bash -c 'echo hello > ~/practice/memo.txt'
docker compose exec -w /home/agent/practice hermes hermes
```

입력 칸에 `practice 폴더에 어떤 파일이 있는지 알려 주세요.`를 적고 Enter를 누르면 화면에는 짧은 오류만 나옵니다.

![질문을 보내자 모델 요청이 실패했다는 문구만 나오고 원인은 보이지 않는 Hermes 화면](https://copyandrun.com/img/hermes-agent-local-ollama/05-small-model-fail.png)

화면에는 `The model request failed`와 `Something went wrong`뿐이어서 원인을 알 수 없습니다. 원인은 로그에 있었습니다.

```bash
docker compose exec hermes bash -c 'grep -h ValueError ~/.hermes/logs/errors.log | tail -1 | fold -s -w 100'
```

```
# 기대 출력
ValueError: Model qwen2.5:3b-instruct-q4_K_M has a context window of 32,768 tokens, which is below
the minimum 64,000 required by Hermes Agent.  Your local server is serving a 32,768-token window.
Start it with at least 64K context (llama.cpp: -c 64000; vLLM: --max-model-len; Ollama:
OLLAMA_CONTEXT_LENGTH=64000 or a Modelfile num_ctx), or set model.ollama_num_ctx in config.yaml to
the window it really serves (at least 64K).
```

![errors.log의 ValueError가 모델의 컨텍스트 창 32,768 토큰이 Hermes가 요구하는 최소 64,000 토큰보다 작다고 알려 주는 터미널](https://copyandrun.com/img/hermes-agent-local-ollama/06-context-error-log.png)

Hermes Agent는 컨텍스트 창이 64,000 토큰 이상인 모델만 받습니다. 시스템 프롬프트와 도구 정의가 매 요청마다 들어가기 때문입니다. 이 글의 환경에서 27B 모델에 첫 질문 하나를 보낸 뒤 상태 줄이 `~14.5K/65.5K`로 표시되었으니, 질문 한 줄에도 약 1만 4천 토큰이 이미 쓰인 셈입니다. 32K 모델은 몇 번만 오가도 가득 찹니다. 이것은 모델이 작아서 생기는 문제가 아니라 창 크기의 문제입니다.

## 5. 컨텍스트를 키운 모델 만들기

Ollama에서는 Modelfile의 `num_ctx`로 창 크기를 정합니다. 호스트에 Modelfile 두 개를 만듭니다. 먼저 3B 모델의 창을 키워 보는 시도입니다.

```
FROM qwen2.5:3b-instruct-q4_K_M
PARAMETER num_ctx 65536
```

다음은 27B 모델용입니다. 이 모델은 원래 262,144 토큰까지 지원하므로 65,536으로 줄이는 것입니다.

```
FROM qwen3.8:27b
PARAMETER num_ctx 65536
```

```bash
ollama create qwen2.5-3b-64k -f Modelfile.qwen25-3b-64k
ollama create qwen3.8-27b-64k -f Modelfile.qwen3-27b-64k
ollama list | grep -E "NAME|64k"
```

```
# 기대 출력
NAME                          ID              SIZE      MODIFIED
qwen3.8-27b-64k:latest        67a1c5bfe600    17 GB     Less than a second ago
qwen2.5-3b-64k:latest         2a0925b836d7    1.9 GB    5 minutes ago
```

![ollama create로 qwen3.8-27b-64k 모델을 만들고 목록에서 64k 모델 두 개를 확인한 터미널](https://copyandrun.com/img/hermes-agent-local-ollama/02-modelfile-create.png)

3B 모델의 64K 버전을 Hermes에 `-m qwen2.5-3b-64k`로 지정해 같은 질문을 보내 보았습니다. 이번에는 컨텍스트 오류가 나오지 않았습니다. Hermes가 모델 정보에서 65,536 토큰을 읽었기 때문입니다. 그런데 `ollama ps`의 CONTEXT 열은 실제로 올라간 창을 보여 주고, 이 모델은 `32768`이었습니다. Ollama는 모델이 학습한 길이(32,768)를 넘는 `num_ctx`를 그 길이로 줄여서 올리는 것으로 보입니다. 이 설정에서는 150초가 지나도 응답이 오지 않아서 중단했고, 응답이 안 온 원인은 확인하지 못했습니다. 로그에는 `"qwen2.5-3b-64k" does not support thinking`이라는 400 응답이 한 번 있었고, Hermes가 추론 설정을 빼고 요청을 다시 보냈습니다. 이 400 응답은 오류가 아니라 자동 복구 동작이었습니다.

정리하면, 3B 모델은 Modelfile로 창을 늘려도 Ollama가 32K로 올리기 때문에 이 방법으로는 쓸 수 없었습니다. 262,144 토큰을 지원하는 27B 모델은 65,536으로 줄여서 올릴 수 있었습니다.

## 6. 27B 모델로 바꾸고 첫 대화하기

```bash
docker compose exec hermes bash -lc 'hermes config set model.default qwen3.8-27b-64k; hermes config get model'
```

```
# 기대 출력
Set model.default = qwen3.8-27b-64k in /home/agent/.hermes/config.yaml
default: qwen3.8-27b-64k
provider: custom
base_url: http://host.docker.internal:11434/v1
api_mode: chat_completions
```

![hermes config set으로 model.default를 qwen3.8-27b-64k로 바꾸고 config get으로 확인한 터미널](https://copyandrun.com/img/hermes-agent-local-ollama/07-config-set-model.png)

실제 출력에서는 `Set model.default` 줄 앞에 체크 표시가 붙습니다. 다시 `hermes`를 열고 같은 질문을 보냅니다.

```bash
docker compose exec -w /home/agent/practice hermes hermes
```

![27B 모델이 Find 도구로 practice 폴더를 검색해 memo.txt 한 개가 있다고 한국어로 답한 Hermes 화면](https://copyandrun.com/img/hermes-agent-local-ollama/08-first-chat.png)

모델이 `Find` 도구를 호출해 폴더를 검색하고(0.2초), 결과를 읽고 한국어로 답했습니다. 질문부터 답이 끝날 때까지 1분 34초가 걸렸습니다. 모델을 GPU에 올리는 시간이 대부분이고, 이 PC에서 Ollama를 직접 불렀을 때 모델을 올리는 데만 약 30초가 걸렸습니다. 두 번째 질문부터는 이미 올라간 모델을 쓰므로 빠릅니다. 모델이 영어로 생각한 내용(`Thought for 6s`)이 함께 표시되는데, 이는 이 모델이 추론 기능을 쓰기 때문입니다.

## 7. 대시보드에서 확인하기

1편의 대시보드가 떠 있다면 Models 화면에서 현재 기본 모델과 사용한 모델을 볼 수 있습니다. 떠 있지 않다면 1편 7단계의 명령으로 먼저 엽니다.

![대시보드 Models 화면에서 메인 모델이 custom 공급자의 qwen3.8-27b-64k로 표시되고 사용한 모델이 두 개로 집계된 모습](https://copyandrun.com/img/hermes-agent-local-ollama/09-dashboard-models.png)

1편에서는 기본값인 `anthropic/claude-opus-4.6`이 보였는데, 이제 `custom · qwen3.8-27b-64k`가 메인 모델입니다. 사용한 모델 목록에는 5단계에서 시험한 `qwen2.5-3b-64k`도 세션 1건으로 남아 있습니다.

![대시보드 Sessions 화면에 27B 모델의 세션과 3B 모델의 실패한 세션이 최근 순서로 나열된 모습](https://copyandrun.com/img/hermes-agent-local-ollama/10-dashboard-sessions.png)

Sessions 화면에는 4단계에서 실패한 3B 세션(2 msgs)과 성공한 27B 세션(4 msgs)이 같이 남습니다. 이 기록은 `~/.hermes/sessions`에 저장되며, 5편에서 다시 다룹니다.

## 자주 막히는 곳

| 증상 | 원인과 해결 |
|---|---|
| 질문을 보내면 `The model request failed`만 나옵니다 | 화면에는 원인이 안 나옵니다. `~/.hermes/logs/errors.log` 끝부분을 봅니다. 컨텍스트 창이 64,000보다 작다는 `ValueError`가 이 글에서 겪은 원인이었습니다 |
| `Verified endpoint`가 나오지 않습니다 | 컨테이너 안에서 `curl http://host.docker.internal:11434/api/tags`가 되는지 봅니다. `docker-compose.yml`의 `extra_hosts` 줄이 빠졌거나 Ollama가 `127.0.0.1`에만 열려 있는지 확인합니다 |
| 모델 목록에 만든 모델이 안 보입니다 | `hermes model`은 실행할 때 `/v1/models`를 새로 읽습니다. `ollama list`에 있는지 먼저 확인합니다 |
| 첫 대화가 매우 느립니다 | 큰 모델을 처음 올리는 시간입니다. `ollama ps`에서 모델이 올라가 있는지 보고, 올라간 뒤에 다시 물어봅니다 |
| 로그에 `does not support thinking` 400 응답이 있습니다 | Hermes가 추론 설정을 빼고 같은 요청을 다시 보내므로 따로 할 일은 없습니다 |

## 이어서 해 볼 것

- **창 크기 비교**: `ollama ps`의 CONTEXT 열과 Hermes 상태 줄의 `~14.5K/65.5K`를 질문마다 비교하며, 질문이 쌓일수록 창이 차는 속도를 봅니다.
- **다른 모델**: 도구 호출을 지원하고 학습 길이가 64K 이상인 다른 모델이 있으면 같은 방식으로 Modelfile을 만들어 연결해 봅니다.
- **다음 단계**: [명령 승인 절차 확인하기](/blog/hermes-agent-command-approval/)에서 에이전트가 명령을 실행하려 할 때 어떻게 멈추는지 봅니다.

## 확인 범위

- **해 본 것:** 2026-10-24, Hermes Agent v0.22.5(2026.9.24)와 호스트 Ollama 0.32.15에서 직접 실행했습니다. `hermes model`의 사용자 지정 엔드포인트 연결, 설정 값, 64K 최소 컨텍스트 오류, 27B 모델의 도구 호출과 한국어 응답, 대시보드 화면은 모두 실행 결과입니다. 최소 컨텍스트 요건은 오류 메시지로 확인했습니다.
- **해 보지 않은 것:** 3B 모델의 64K 버전 응답, `exaone3.5:2.4b`의 Hermes 연결, `Local models` 메뉴, 이 글에서 쓰지 않은 다른 공급자.
- **읽을 때 주의:** 응답 시간은 이 PC의 GPU 환경 기준이며 다른 환경에서는 크게 달라질 수 있습니다.
