왜 Hermes Agent 웹 검색이 막히는가

⚠️ 실제로 겪었던 이야기

며칠 전까지만 해도 Hermes Agent가 웹 검색을 하다가 "검색 결과를 가져올 수 없습니다"라는 메시지만 반복해서 뱉어내는 바람에 거의 3시간을 허비했다. Firecrawl의 무료 티어는 하루 500회로 금방 바닥나고, Tavily도 유료 전환을 요구했다. "에이전트한테 검색 한 번 시키는데 결제까지 해야 하나?" 싶어서 직접 해결하기로 마음먹었다. Reddit r/hermesagent에서 SearXNG 이야기를 보고 "이거다!" 싶었다. 직접 설치해보니 생각보다 간단했는데, Docker Compose 파일이 최신 버전과 맞지 않아서 한 번 꼬이긴 했다. 그래도 한 번 세팅해두니 그 이후로 검색 차단 문제는 완전히 해결되었다.

Hermes Agent는 Nous Research가 만든 오픈소스 자율형 AI 에이전트다. 47개 이상의 빌트인 도구 중 web_search로 웹 검색이 가능하지만, 실전에서 잘 막힌다.

Hermes의 web_search는 현재 Firecrawl · Tavily · Exa · Parallel 네 가지 백엔드만 지원한다. 전부 유료 API 키가 필요하고, 무료 티어도 금방 소진된다. 웹사이트들이 봇 트래픽을 적극 차단하기 때문에, 에이전트가 검색 결과를 열어보지 못하고 루프에 빠지는 경우가 많다.

2026년 4월 24일 r/hermesagent에서도 동일한 문제가 화제였고, 가장 많이 추천된 해결책이 SearXNG였다.

SearXNG란? — 무료 · 무제한 · 셀프호스팅 메타검색 엔진

SearXNG는 오픈소스 메타검색 엔진이다.

Step 1 — SearXNG Docker 설치 (2026년 4월 기준 새 공식 방법)

1-1. 폴더 생성 및 공식 템플릿 다운로드

# 작업 폴더 생성
mkdir -p [local path]
cd [local path]

# 공식 docker-compose.yml + .env.example 다운로드
curl -fsSL \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/docker-compose.yml \
  -O https://raw.githubusercontent.com/searxng/searxng/master/container/.env.example

# .env 파일 생성
cp .env.example .env

▲ Searxng Terminal

1-2. 포트 설정

Open WebUI가 8080을 쓰고 있다면, SearXNG는 8888로 변경한다.

# .env 파일에 포트 및 바인딩 추가
echo "SEARXNG_PORT=8888" >> .env
echo "SEARXNG_HOST=0.0.0.0" >> .env

1-3. 첫 기동으로 settings.yml 자동 생성

docker compose up -d && sleep 15 && docker compose down

1-4. JSON 포맷 추가 (필수!)

sed -i 's/- html/- html\n    - json/' core-config/settings.yml

1-5. Limiter 비활성화 (로컬 전용)

cat > core-config/limiter.toml << 'EOF'
[botdetection.ip_limit]
link_token = false

[botdetection.ip_lists]
block_ip = []
pass_ip = []
EOF

1-6. settings.yml 추가 설정 확인

core-config/settings.yml을 열어서 다음 항목을 확인하거나 수정한다.

search:
  formats:
    - html
    - json          # ← 이게 있는지 확인

server:
  limiter: false    # ← rate limiter 끄기

redis:
  url: redis://searxng-valkey:6379/0   # ← 새 Compose에서는 컨테이너 이름이 searxng-valkey

1-7. 시작 및 확인

docker compose up -d

# JSON 응답 확인
curl "http://[internal endpoint]/search?q=test&format=json"

results 배열이 포함된 JSON이 출력되면 설치 완료다.

Step 2 — Hermes Agent에 SearXNG 연결 (MCP 방식)

Hermes Agent는 MCP를 네이티브 지원한다. SearXNG용 MCP 서버인 MCP-searxng를 연결하면, Hermes가 web_search 대신 SearXNG를 자율적으로 사용한다.

2-1. uvx로 간편 설정 (권장)

[local path]에 추가:

mcp_servers:
  searxng:
    command: "uvx"
    args: ["mcp-searxng"]
    env:
      SEARXNG_URL: "http://[internal endpoint]"

2-2. git clone 방식 (uvx가 없는 경우)

cd ~
git clone https://github.com/SecretiveShell/MCP-searxng.git
cd MCP-searxng
uv pip install -e .

[local path]:

mcp_servers:
  searxng:
    command: "uv"
    args:
      - "--project"
      - "/home/사용자/MCP-searxng/"
      - "run"
      - "/home/사용자/MCP-searxng/mcp-searxng/main.py"
    env:
      SEARXNG_URL: "http://[internal endpoint]"

2-3. 확인

hermes chat

Hermes 시작 시 mcp_searxng_search 도구가 자동 등록된다.

Step 3 — Open WebUI에서도 SearXNG 연동 (병행 추천)

Hermes의 MCP 경로와 별도로, Open WebUI 자체 Web Search에도 SearXNG를 붙이면 두 가지 독립적인 검색 경로가 생긴다.

Open WebUI 설정

1. Open WebUI 로그인
2. Admin Panel → Settings → Web Search
3. Enable Web Search: ON
4. Web Search Engine: searxng
5. Searxng Query URL: http://host.docker.internal:8888/search?q=<query>
6. Search Result Count: 5~10
7. Save

Step 3.5 — Hermes Agent를 Open WebUI에 연결 (아직 안 했다면)

이미 연결되어 있다면 건너뛰어도 된다.

Hermes 쪽

[local path]에 추가:

API_SERVER_ENABLED=true
API_SERVER_KEY=my-secret-key-12345
API_SERVER_PORT=8642

tmux new -s hermes
hermes gateway

Open WebUI 쪽

1. Admin Settings → Connections → OpenAI
2. + Add Connection
3. URL: http://host.docker.internal:8642/v1 (끝에 /v1 필수)
4. API Key: my-secret-key-12345
5. 체크마크 → Save

Step 4 — Tailscale Funnel로 외부 접속

Tailscale Funnel이 이미 설치되어 있다면 한 줄이면 된다.

4-1. Funnel 활성화

# Open WebUI 포트에 맞춰서:
sudo tailscale funnel --bg https / http://localhost:3000

# 또는 8080이면:
sudo tailscale funnel --bg https / http://[internal endpoint]

4-2. URL 확인

tailscale funnel status

4-3. Funnel vs Serve

# 혼자만 쓴다면 Serve가 더 안전
sudo tailscale serve --bg https / http://localhost:3000

4-4. Funnel 끄기

sudo tailscale funnel https / off

전체 아키텍처

[외부 브라우저 / 모바일]
        │
        ▼
[Tailscale Funnel]  https://my-dgx.xxx.ts.net
        │  암호화 터널 (TLS)
        ▼
┌─── NVIDIA DGX GB10 (128GB 통합 메모리) ────────────────┐
│                                                         │
│   Open WebUI (포트 3000/8080)                           │
│     ├── Hermes Agent API (포트 8642)                    │
│     │     ├── 47+ 빌트인 도구                           │
│     │     ├── MCP-SearXNG ──→ SearXNG (포트 8888)      │
│     │     └── 로컬 LLM (Ollama / vLLM)                 │
│     │                                                   │
│     └── Open WebUI Web Search ──→ SearXNG (포트 8888)  │
│                                                         │
│   SearXNG Docker (searxng-core:8888 + searxng-valkey)  │
│     └── Google · Bing · DuckDuckGo 등 70+ 메타검색     │
│                                                         │
└─────────────────────────────────────────────────────────┘

자주 발생하는 문제와 해결

핵심 요약

Hermes Agent의 기본 web_search는 유료 API 의존 + 봇 차단에 취약하다. SearXNG를 셀프호스팅해서 MCP로 연결하면 무료·무제한·차단 없는 검색이 가능해진다. Open WebUI 레벨에서도 동시 연동하면 두 가지 경로로 활용할 수 있다. 외부 접속은 Tailscale Funnel 한 줄, 보안 강화는 Tailscale Serve로. 전체 스택 비용 0원.

참고 링크

• SearXNG 공식 Docker 설치 가이드 (새 방식)
• Hermes Agent 공식 문서
• Hermes Agent MCP 설정 가이드
• Hermes Agent + Open WebUI 연결 가이드
• Open WebUI + SearXNG 공식 가이드
• MCP-SearXNG GitHub
• Tailscale Funnel 문서
• Open WebUI + Tailscale 통합 가이드
• Hermes Agent SearXNG 백엔드 추가 이슈 #5941

이 글은 2026년 4월 25일 기준으로 작성되었습니다. searxng-docker 리포 아카이브(2026.03.28) 이후 변경된 새 공식 설치법을 반영했습니다.