Hermes-WebUI 에러(Python의 가상환경)

이틀전(2026년5월10일) Hermes Agent의 WebUI 를 설치와 사용법을 알아보다가 WebUI 사용중 문제가 생겨서 다시 적습니다.

 

문제가 무엇인가 하면, 다른 것은 다 괜찮은데 AI와 채팅 시 아래와 같은 에러가 발생하는 것입니다.

 

Error: AIAgent not available -- check that hermes-agent is on sys.path python: /usr/bin/python HERMES_WEBUI_AGENT_DIR: (not set) sys.path entries mentioning hermes/agent: - /.hermes/hermes-agent - /root/.hermes/hermes-agent - /root/.hermes/hermes-agent - /root/.hermes/hermes-agent - /root/hermes-webui - /root/.hermes/hermes-agent Most common fix: install the agent in editable mode so its modules appear on sys.path: cd /path/to/hermes-agent pip install -e . Then restart the WebUI. Full troubleshooting: docs/troubleshooting.md ("AIAgent not available")

 

WebUI 에서 AI와의 채팅 중 에러

 

Python 가상환경(Virtual Environment)의 필요성

그래서 AI에게 문의해 보니 Python 실행시 가상환경의 문제였습니다.

가상환경(Virtual Environment)이란, 파이썬 패키지를 독립적으로 관리할 수 있도록 도와주는 기능입니다.

같은 컴퓨터에서도 프로젝트마다 다른 패키지 버전을 사용할 수 있게 하는 것입니다.

예를 들어,

프로젝트 A에서는 Django 3.2를 사용하고, B에서는 Django 4.0을 사용하는 것처럼 시스템의 기본 파이썬 패키지와 충돌없이 각 프로젝트 별로 독립적인 환경을 유지하는 것입니니다.

 

그래서, 파이썬 패키지를 설치하다 보면

python3 -m venv venv 또는 python3 -m venv .venv

이렇게 가상환경을 위한 디렉토리를 만들게 되는 것을 볼 수 있습니다.

 

어제의 설명 중에서 4번 외부 접속 부분에서

 

4. 외부 접속

보안상 localhost 에서만 접속가능하게 되어 있기 때문에 로컬 네트워크 상의 다른 컴퓨터에서 접속하기 위해서는 Host 를 변경할 필요가 있습니다. 가장 쉬운 방법은 실행 중인 프로세스를 죽이고,  아래 명령과 같이 호스트를 0.0.0.0으로 지정하면 됩니다.

HERMES_WEBUI_HOST=0.0.0.0  nohup python /root/hermes-webui/server.py > /dev/null 2>&1 &

 

여기서 nohup python /root/~~~/server.py 이렇게 시스템 상의 기본 python 으로 실행 시킨 것이 문제였습니다.

그러니까, Hermes Agent 가 설치한 가상환경의 Python으로 server.py 를 실행하여야 했던 것입니다.

 

HERMES_WEBUI_HOST=0.0.0.0 nohup /root/.hermes/hermes-agent/venv/bin/python \
/root/hermes-webui/server.py > /dev/null 2>&1 &

 

이와같이 Hermes Agent 가 설치된 곳에 있는 가상환경 상의 Python으로 서버를 실행시켜야 합니다.

시스템 상의 기본 python 은 which python을 해보면 /usr/bin/python 에 있는 것으로 나오기 때문에 그냥 python이 아닌

/root/.hermes/hermes-agent/venv/bin/python 으로 경로를 지정하여 실행하여야 합니다.

에러가 복구된 AI와의 채팅