외부 API 키 없이 에이전트를 쓰려면 모델을 내 PC의 Ollama에서 가져와야 합니다. 이 글에서는 1편에서 만든 컨테이너의 Hermes Agent를 호스트의 Ollama에 연결합니다. hermes model로 연결하는 과정, 설정 파일에 남는 값, 그리고 직접 부딪힌 문제를 순서대로 기록했습니다. 문제는 모델이 작아서 도구 호출을 못 하는 것이 아니라, 컨텍스트 창이 64K 토큰보다 작으면 Hermes가 아예 시작하지 않는 것이었습니다.
이 글은 Hermes Agent 실무 시리즈의 2편입니다. 1편은 컨테이너에 설치하고 첫 실행하기, 다음 3편은 명령 승인 절차 확인하기입니다.
준비물
| 항목 | 확인한 버전 |
|---|---|
| 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편에서 대시보드를 위해 추가한 환경 변수와 포트도 그대로 들어 있습니다.
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"]
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:
컨테이너가 떠 있는지 확인합니다.
docker compose up -d
docker compose exec hermes hermes --version
1. 도구 호출을 지원하는 모델 고르기
Hermes는 파일과 터미널 같은 도구를 모델의 도구 호출 기능으로 실행합니다. 그래서 모델이 도구 호출을 지원해야 합니다. Ollama는 모델마다 지원 기능을 알려 주므로, 호스트에서 확인합니다.
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

exaone3.5:2.4b는 tools 기능이 없어서 Hermes의 도구를 쓸 수 없습니다. 나머지 둘이 후보입니다. nomic-embed-text는 임베딩 모델이라 대화에 쓰지 않습니다. 컨텍스트 길이 항목은 4단계에서 문제의 원인으로 다시 나옵니다.
2. hermes model로 사용자 지정 엔드포인트 연결하기
컨테이너 안에서 hermes model을 실행합니다. 터미널 화면에서 방향키로 고르는 메뉴입니다.
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까지 연결된 것입니다.

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

먼저 3번 qwen2.5:3b-instruct-q4_K_M을 골랐습니다. 도구 호출을 지원하는 가장 작은 모델이라 결과가 어떻게 되는지 보려는 것입니다.
3. 설정 파일에 남은 값 확인하기
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 한 개를 만들어 두었습니다.
docker compose exec hermes bash -c 'echo hello > ~/practice/memo.txt'
docker compose exec -w /home/agent/practice hermes hermes
입력 칸에 practice 폴더에 어떤 파일이 있는지 알려 주세요.를 적고 Enter를 누르면 화면에는 짧은 오류만 나옵니다.

화면에는 The model request failed와 Something went wrong뿐이어서 원인을 알 수 없습니다. 원인은 로그에 있었습니다.
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).

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
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

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 모델로 바꾸고 첫 대화하기
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

실제 출력에서는 Set model.default 줄 앞에 체크 표시가 붙습니다. 다시 hermes를 열고 같은 질문을 보냅니다.
docker compose exec -w /home/agent/practice hermes hermes

모델이 Find 도구를 호출해 폴더를 검색하고(0.2초), 결과를 읽고 한국어로 답했습니다. 질문부터 답이 끝날 때까지 1분 34초가 걸렸습니다. 모델을 GPU에 올리는 시간이 대부분이고, 이 PC에서 Ollama를 직접 불렀을 때 모델을 올리는 데만 약 30초가 걸렸습니다. 두 번째 질문부터는 이미 올라간 모델을 쓰므로 빠릅니다. 모델이 영어로 생각한 내용(Thought for 6s)이 함께 표시되는데, 이는 이 모델이 추론 기능을 쓰기 때문입니다.
7. 대시보드에서 확인하기
1편의 대시보드가 떠 있다면 Models 화면에서 현재 기본 모델과 사용한 모델을 볼 수 있습니다. 떠 있지 않다면 1편 7단계의 명령으로 먼저 엽니다.

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

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을 만들어 연결해 봅니다.
- 다음 단계: 명령 승인 절차 확인하기에서 에이전트가 명령을 실행하려 할 때 어떻게 멈추는지 봅니다.
확인 범위
- 해 본 것: 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 환경 기준이며 다른 환경에서는 크게 달라질 수 있습니다.
이 글은 Ollama와 로컬 LLM 실습 로드맵의 한 단계입니다.
이 글의 다음 단계
- Open WebUI Ollama 연결: host.docker.internal:11434 고치기Docker로 Open WebUI를 띄워 호스트의 Ollama에 연결하고, 주소를 localhost로 잘못 넣어 모델 목록이 비는 상태를 만든 뒤 원인을 찾아 고칩니다. 환경 변수를 바로잡아도 저장된 설정이 우선해 되돌아오지 않는 동작도 직접 확인합니다.
- n8n으로 웹훅 자동화 만들기: 도커 실행, 워크플로 가져오기, 호출 확인오픈소스 자동화 도구 n8n을 도커로 localhost에만 열어 띄우고, 웹훅을 받아 JSON을 돌려주는 워크플로를 명령줄로 가져와 게시합니다. 게시 전후의 차이, 재시작이 필요했던 점, 한글과 빈 입력과 GET 요청 결과를 확인합니다.