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")
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 으로 경로를 지정하여 실행하여야 합니다.
