Open WebUI 통합

Open WebUI (126k★) 가장 인기 있는 AI용 셀프호스팅 채팅 인터페이스. Hermes Agent 내장 API 서버 사용하면 Open WebUI를 에이전트용 세련된 웹 프론트엔드로 사용 가능 — 대화 관리, 사용자 계정, 현대적 채팅 인터페이스 모두 포함.

아키텍처

Open WebUI가 OpenAI에 연결하듯 Hermes Agent API 서버에 연결. Hermes가 전체 툴셋 — 터미널, 파일 작업, 웹 검색, 메모리, skills — 으로 요청 처리 후 최종 응답 반환.

important Runtime location

API 서버는 순수 LLM 프록시 아닌 Hermes 에이전트 런타임. 각 요청마다 Hermes가 API 서버 호스트에서 서버 측 AIAgent 생성. 툴 호출 API 서버 실행 위치에서 실행됨.

예: 노트북이 Open WebUI나 다른 OpenAI 호환 클라이언트를 원격 머신의 Hermes API 서버로 연결 시, pwd, 파일 툴, 브라우저 툴, 로컬 MCP 툴, 기타 워크스페이스 툴은 노트북 아닌 원격 API 서버 호스트에서 실행.

Open WebUI는 Hermes와 서버 대 서버 통신, 따라서 이 통합엔 API_SERVER_CORS_ORIGINS 필요 없음.

빠른 설정

원커맨드 로컬 부트스트랩 (macOS/Linux, Docker 없이)

Hermes + Open WebUI 로컬 연결 및 재사용 가능 런처 원하면 실행:

cd ~/.hermes/hermes-agent
bash scripts/setup_open_webui.sh

스크립트 동작:

~/.hermes/.env에 API_SERVER_ENABLED, API_SERVER_HOST, API_SERVER_KEY, API_SERVER_PORT, API_SERVER_MODEL_NAME 포함 보장
Hermes 게이트웨이 재시작하여 API 서버 기동
~/.local/open-webui-venv에 Open WebUI 설치
~/.local/bin/start-open-webui-hermes.sh에 런처 작성
macOS는 launchd 사용자 서비스 설치; systemd --user 있는 Linux는 거기에 사용자 서비스 설치

기본값:

Hermes API: http://127.0.0.1:8642/v1
Open WebUI: http://127.0.0.1:8080
Open WebUI에 노출되는 모델명: Hermes Agent

유용한 오버라이드:

OPEN_WEBUI_NAME='My Hermes UI' \
OPEN_WEBUI_ENABLE_SIGNUP=true \
HERMES_API_MODEL_NAME='My Hermes Agent' \
bash scripts/setup_open_webui.sh

Linux에서 자동 백그라운드 서비스 설정에는 동작하는 systemd --user 세션 필요. 헤드리스 SSH 박스에서 서비스 설치 건너뛰려면 실행:

OPEN_WEBUI_ENABLE_SERVICE=false bash scripts/setup_open_webui.sh

1. API 서버 활성화

hermes config set API_SERVER_ENABLED true
hermes config set API_SERVER_KEY your-secret-key
``hermes config set`이 플래그 자동으로 `config.yaml`로, 시크릿을 `~/.hermes/.env`로 라우팅. 게이트웨이 이미 실행 중이면 재시작하여 변경 적용:

```bash
hermes gateway stop && hermes gateway

2. Hermes Agent 게이트웨이 시작

hermes gateway

다음 출력 확인:

[API Server] API server listening on http://127.0.0.1:8642

3. API 서버 접근 가능 확인

curl -s http://127.0.0.1:8642/health
# &#123;"status": "ok",...&#125;

curl -s -H "Authorization: Bearer your-secret-key" http://127.0.0.1:8642/v1/models
# &#123;"object":"list","data":[&#123;"id":"hermes-agent",...&#125;]&#125;
``/health` 실패 시 게이트웨이가 `API_SERVER_ENABLED=true` 인식 못 한 것 — 재시작. `/v1/models`가 `401` 반환 시 `Authorization` 헤더가 `API_SERVER_KEY`와 불일치.

### 4. Open WebUI 시작 \{#2-start-hermes-agent-gateway}

```bash
docker run -d -p 3000:8080 \
  -e OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1 \
  -e OPENAI_API_KEY=your-secret-key \
  -e ENABLE_OLLAMA_API=false \
  --add-host=host.docker.internal:host-gateway \
  -v open-webui:/app/backend/data \
  --name open-webui \
  --restart always \
  ghcr.io/open-webui/open-webui:main
``ENABLE_OLLAMA_API=false`는 기본 Ollama 백엔드 억제 — 안 그러면 빈 상태로 모델 선택기 어지럽힘. Ollama 실제 같이 실행 중이면 생략.

첫 실행 15–30초 소요: Open WebUI가 처음 시작 시 sentence-transformer 임베딩 모델 (~) 다운로드. UI 열기 전 `docker logs open-webui` 안정될 때까지 대기.

### 5. UI 열기 \{#5-open-the-ui}

**`http://localhost:3000`**로 이동. 관리자 계정 생성 (첫 사용자 관리자 됨). 모델 드롭다운에 에이전트 표시 (프로필 이름 또는 기본 프로필의 경우 **hermes-agent**). 채팅 시작!

## Docker Compose 설정 \{#docker-compose-setup}

영구 설정 원하면 `docker-compose.yml` 생성:

```yaml
services:
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    ports:
      - "3000:8080"
    volumes:
      - open-webui:/app/backend/data
    environment:
      - OPENAI_API_BASE_URL=http://host.docker.internal:8642/v1
      - OPENAI_API_KEY=your-secret-key
      - ENABLE_OLLAMA_API=false
    extra_hosts:
      - "host.docker.internal:host-gateway"
    restart: always

volumes:
  open-webui:

이후:

docker compose up -d

Admin UI로 설정

환경 변수 대신 UI로 연결 설정하려면:

**http://localhost:3000**로 Open WebUI 로그인
프로필 아바타 클릭 → Admin Settings
Connections 이동
OpenAI API 아래 렌치 아이콘 (Manage) 클릭
+ Add New Connection 클릭
입력:
- URL: http://host.docker.internal:8642/v1
- API Key: Hermes의 API_SERVER_KEY와 동일한 값
체크마크 클릭하여 연결 확인
Save

이제 모델 드롭다운에 에이전트 모델 표시 (프로필 이름 또는 기본 프로필은 hermes-agent).

경고

환경 변수는 Open WebUI 첫 실행 시에만 적용. 이후 연결 설정은 내부 DB에 저장. 변경하려면 Admin UI 사용 또는 Docker 볼륨 삭제 후 새로 시작.

API 타입: Chat Completions vs Responses

Open WebUI는 백엔드 연결 시 두 가지 API 모드 지원:

모드	형식	사용 시기
Chat Completions (기본값)	`/v1/chat/completions`	권장. 즉시 동작.
Responses (실험적)	`/v1/responses`	`previous_response_id` 통한 서버 측 대화 상태용.

Chat Completions 사용 (권장)

기본값이며 추가 설정 불필요. Open WebUI가 표준 OpenAI 형식 요청 전송, Hermes Agent가 응답. 각 요청 전체 대화 이력 포함.

Responses API 사용

Responses API 모드 사용:

Admin Settings → Connections → OpenAI → Manage 이동
hermes-agent 연결 편집
API Type을 "Chat Completions"에서 **"Responses (Experimental)"**로 변경
저장

Responses API 사용 시 Open WebUI가 Responses 형식 (input 배열 + instructions)으로 요청 전송, Hermes Agent가 previous_response_id 통해 전체 툴 호출 이력을 턴 간 보존 가능. stream: true 시 Hermes는 스펙 네이티브 function_call와 function_call_output 아이템도 스트리밍 — Responses 이벤트 렌더링하는 클라이언트에서 커스텀 구조화 툴 호출 UI 가능.

노트

Open WebUI는 현재 Responses 모드에서도 대화 이력을 클라이언트 측에서 관리 — previous_response_id 사용 안 하고 각 요청에 전체 메시지 이력 전송. 오늘날 Responses 모드 주요 이점은 구조화된 이벤트 스트림: 텍스트 델타, function_call, function_call_output 아이템이 Chat Completions 청크 대신 OpenAI Responses SSE 이벤트로 도착.

동작 방식

Open WebUI에서 메시지 전송 시:

Open WebUI가 메시지와 대화 이력 포함한 POST /v1/chat/completions 요청 전송
Hermes Agent가 API 서버의 프로필, 모델/프로바이더 설정, 메모리, skills, 설정된 API 서버 툴셋 사용하여 서버 측 AIAgent 인스턴스 생성
에이전트가 요청 처리 — API 서버 호스트에서 툴 (터미널, 파일 작업, 웹 검색 등) 호출 가능
툴 실행 시 인라인 진행 메시지가 UI로 스트리밍되어 에이전트 동작 확인 가능 (예: 💻 ls -la, 🔍 Python 3.12 release)
에이전트 최종 텍스트 응답이 Open WebUI로 스트리밍
Open WebUI가 채팅 인터페이스에 응답 표시

에이전트는 해당 API 서버 Hermes 인스턴스와 동일 툴 및 기능 접근 가능. API 서버 원격이면 툴도 원격.

로컬 워크스페이스 대상 툴 실행 필요하면 Hermes 로컬 실행 후 순수 LLM 프로바이더나 순수 OpenAI 호환 모델 프록시 (예: vLLM, LiteLLM, Ollama, llama.cpp, OpenAI, OpenRouter 등) 연결. "원격 두뇌, 로컬 손" 위한 split-runtime 모드는 #18715에서 추적 중; 현재 API 서버 동작 아님.

Tool Progress

스트리밍 활성화 시 (기본값) 툴 실행 중 짧은 인라인 인디케이터 표시 — 툴 이모지와 핵심 인자. 에이전트 최종 답변 전 응답 스트림에 표시되어 백그라운드 동작 가시성 제공.

설정 레퍼런스

Hermes Agent (API 서버)

변수	기본값	설명
`API_SERVER_ENABLED`	`false`	API 서버 활성화
`API_SERVER_PORT`	`8642`	HTTP 서버 포트
`API_SERVER_HOST`	`127.0.0.1`	바인드 주소
`API_SERVER_KEY`	(필수)	인증용 Bearer 토큰. `OPENAI_API_KEY`와 일치.

Open WebUI

변수	설명
`OPENAI_API_BASE_URL`	Hermes Agent API URL (`/v1` 포함)
`OPENAI_API_KEY`	비어 있으면 안 됨. `API_SERVER_KEY`와 일치.

트러블슈팅

URL에 /v1 접미사 확인: http://host.docker.internal:8642/v1 (그냥 :8642 아님)
게이트웨이 실행 확인: curl http://localhost:8642/health가 {"status": "ok"} 반환해야 함
모델 리스트 확인: curl -H "Authorization: Bearer your-secret-key" http://localhost:8642/v1/models가 hermes-agent 포함 리스트 반환해야 함
Docker 네트워킹: Docker 내부에서 localhost는 호스트 아닌 컨테이너 의미. host.docker.internal 또는 --network=host 사용.
빈 Ollama 백엔드가 선택기 가림: ENABLE_OLLAMA_API=false 생략 시 Open WebUI가 Hermes 모델 위에 빈 Ollama 섹션 표시. -e ENABLE_OLLAMA_API=false로 컨테이너 재시작 또는 Admin Settings → Connections에서 Ollama 비활성화.

연결 테스트 통과하지만 모델 로드 안 됨

거의 항상 /v1 접미사 누락. Open WebUI 연결 테스트는 기본 연결성 체크 — 모델 리스트 동작 검증 안 함.

응답 시간 오래 걸림

Hermes Agent가 최종 응답 전에 여러 툴 호출 (파일 읽기, 명령어 실행, 웹 검색) 실행 중일 수 있음. 복잡한 쿼리에선 정상. 에이전트 완료 시 응답 한 번에 표시.

"Invalid API key" 오류

Open WebUI의 OPENAI_API_KEY가 Hermes Agent의 API_SERVER_KEY와 일치하는지 확인.

경고

Open WebUI는 첫 실행 후 OpenAI 호환 연결 설정을 자체 DB에 영속화. Admin UI에서 잘못된 키 저장했다면 환경 변수만 수정해선 부족 — Admin Settings → Connections에서 저장된 연결 업데이트 또는 삭제, 또는 Open WebUI 데이터 디렉터리/DB 리셋.

프로필 사용한 멀티 유저 설정

사용자별 별도 Hermes 인스턴스 실행 — 각자 설정, 메모리, skills 보유 — 하려면 profiles 사용. 각 프로필이 다른 포트에서 자체 API 서버 실행하며 Open WebUI에 프로필명을 모델로 자동 노출.

1. 프로필 생성 및 API 서버 설정

API_SERVER_*는 YAML config 키 아닌 환경 변수, 각 프로필 .env에 작성. 기본 플랫폼 범위 밖 포트 선택 (8644는 webhook 어댑터, 8645은 wecom-callback, 8646는 msgraph-webhook), 예: 8650+:

hermes profile create alice
cat >> ~/.hermes/profiles/alice/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8650
API_SERVER_KEY=alice-secret
EOF

hermes profile create bob
cat >> ~/.hermes/profiles/bob/.env <<EOF
API_SERVER_ENABLED=true
API_SERVER_PORT=8651
API_SERVER_KEY=bob-secret
EOF

2. 각 게이트웨이 시작

hermes -p alice gateway &
hermes -p bob gateway &

3. Open WebUI에 연결 추가

Admin Settings → Connections → OpenAI API → Manage에서 프로필당 연결 하나씩 추가:

연결	URL	API Key
Alice	`http://host.docker.internal:8650/v1`	`alice-secret`
Bob	`http://host.docker.internal:8651/v1`	`bob-secret`

모델 드롭다운에 alice와 bob가 별개 모델로 표시. 관리자 패널에서 Open WebUI 사용자에게 모델 할당 가능 — 각 사용자가 자체 격리된 Hermes 에이전트 보유.

Custom Model Names

모델명은 프로필명 기본값. 오버라이드하려면 프로필 .env에 API_SERVER_MODEL_NAME 설정:

hermes -p alice config set API_SERVER_MODEL_NAME "Alice's Agent"

Linux Docker (Docker Desktop 없이)

Docker Desktop 없는 Linux에서 host.docker.internal는 기본적으로 해석 안 됨. 옵션:

# Option 1: Add host mapping
docker run --add-host=host.docker.internal:host-gateway...

# Option 2: Use host networking
docker run --network=host -e OPENAI_API_BASE_URL=http://localhost:8642/v1...

# Option 3: Use Docker bridge IP
docker run -e OPENAI_API_BASE_URL=http://172.17.0.1:8642/v1...

아키텍처​

빠른 설정​

원커맨드 로컬 부트스트랩 (macOS/Linux, Docker 없이)​

1. API 서버 활성화​

2. Hermes Agent 게이트웨이 시작​

3. API 서버 접근 가능 확인​

Admin UI로 설정​

API 타입: Chat Completions vs Responses​

Chat Completions 사용 (권장)​

Responses API 사용​

동작 방식​

설정 레퍼런스​

Hermes Agent (API 서버)​

Open WebUI​

트러블슈팅​

드롭다운에 모델 표시 안 됨​

연결 테스트 통과하지만 모델 로드 안 됨​

응답 시간 오래 걸림​

"Invalid API key" 오류​

프로필 사용한 멀티 유저 설정​

1. 프로필 생성 및 API 서버 설정​

2. 각 게이트웨이 시작​

3. Open WebUI에 연결 추가​

Linux Docker (Docker Desktop 없이)​