보조컴 WSL2 Hermes Agent 설치 성공기

실제 설치 과정에서 겪은 문제와 해결책
환경: 보조컴 WSL2 Ubuntu 24.04.4 LTS
설치일: 2026-04-19
최종 결과: ✅ Hermes Agent v0.10.0 (2026.4.16) 설치 성공

1. 설치 전 환경

항목	상태
OS	Ubuntu 24.04.4 LTS (WSL2)
Python	3.12.3
Node.js	v22.22.2
Git	2.43.0
Docker	❌ 미설치
Ollama	❌ 미설치
Hermes	❌ 미설치

💡 Docker/Ollama 없어도 Hermes 자체 설치는 가능!

2. 설치 과정

2.1 원클릭 인스톨러 실행

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

2.2 발생한 문제들

🔴 문제 1: 설치 중 SSH 연결 끊김

증상: 의존성 설치 → WhatsApp 브릿지 설치 진행 중 SSH 세션 타임아웃으로 연결 끊김

원인: 설치 시간이 길어지면서 SSH 연결이 끊어짐

해결책:

SSH 재접속 후 설치 상태 확인
다행히 설치 자체는 완료되어 있었음

예방법: 설치 전 tmux 세션에서 실행

tmux new -s hermes-install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
# 끊기면: tmux attach -t hermes-install

🔴 문제 2: PATH 연결 안 됨 (command not found)

증상: 설치는 완료됐는데 hermes 명령어 인식 안 됨

원인: 셸 PATH 갱신이 안 된 상태로 세션 종료

해결책:

source ~/.bashrc
which hermes
# ~/.local/bin/hermes 확인

3. 설치 결과

항목	결과
버전	Hermes Agent v0.10.0 (2026.4.16)
Python	3.11.15 (uv가 자동 설치)
경로	`~/.local/bin/hermes`
상태	✅ 설치 완료

4. WSL2에서 자주 발생하는 문제 & 해결책 종합

4개 서브에이전트(kimi-k2.5, minimax-m2.7, minimax-m2.5, qwen3.5, glm-5.1) 검증 결과 + 실제 경험 종합

4.1 curl 설치 스크립트 실패 (가장 흔함!)

증상:

curl: (7) Failed to connect to raw.githubusercontent.com port 443
curl: (6) Could not resolve host: raw.githubusercontent.com

원인: 네트워크 차단, DNS 해석 실패, 프록시 미설정

해결책 (우선순위별):

① curl/git 자체가 없을 때

sudo apt update && sudo apt install -y curl git

② DNS 수동 설정 (가장 많이 먹힘!)

# WSL2 자동 DNS 비활성화
sudo tee /etc/wsl.conf <<EOF
[network]
generateResolvConf = false
EOF

# 수동 DNS 설정
sudo rm /etc/resolv.conf
sudo tee /etc/resolv.conf <<EOF
nameserver 8.8.8.8
nameserver 1.1.1.1
EOF

# WSL 재시작 (PowerShell에서)
wsl --shutdown

💡 팁: WSL2가 재시작할 때마다 resolv.conf 덮어쓰는 거 방지:
Terminal window
sudo chattr +i /etc/resolv.conf

③ 프록시 설정

export https_proxy=http://127.0.0.1:7890
export http_proxy=http://127.0.0.1:7890

④ GitHub CDN 미러로 우회

curl -fsSL https://fastly.jsdelivr.net/gh/NousResearch/hermes-agent@main/scripts/install.sh | bash

⑤ wget 대체

wget -q https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh -O install.sh
bash install.sh

⑥ hosts 파일 수정

sudo bash -c 'echo "140.82.121.3 raw.githubusercontent.com" >> /etc/hosts'

⑦ 수동 클론 후 설치 (가장 확실!)

git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./scripts/install.sh

4.2 SSH clone에서 무한 대기

증상: → Trying SSH clone... 에서 멈춤

원인: 설치 스크립트가 SSH(포트 22)를 기본 시도 → 회사/공공망에서 차단

해결책:

# 무조건 HTTPS로 클론!
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git

# 또는 SSH를 443포트로 우회
# ~/.ssh/config에 추가:
Host github.com
  Hostname ssh.github.com
  Port 443
  User git

4.3 403 Forbidden / SSH 포트 차단

원인: GitHub SSH 포트 22 차단

해결책:

git config --global url."https://github.com/".insteadOf git@github.com
git config --global url."https://github.com/".insteadOf ssh://git@github.com/

4.4 Python 버전 문제 (설치 멈춤)

증상: Creating virtual environment with Python 3.13... 에서 멈춤, tiktoken pyo3 오류

원인: Python 3.13은 미호환 → 공식 권장은 3.11/3.12

해결책:

# uv로 강제 Python 3.11 지정
uv venv venv --python 3.11

→ 설치 스크립트가 uv로 자동 처리하지만, 수동 설치 시 명시 필요

4.5 uv 설치 실패

증상: uv: command not found

해결책:

curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc
uv --version  # 확인

4.6 권한 에러 (Permission denied)

원인: sudo로 이전 설치를 해서 권한 꼬임

해결책:

# sudo로 설치된 흔적 정리
sudo rm -f /usr/local/bin/hermes
# 일반 유저로 재설치 (sudo 없이!)

⚠️ 절대 sudo로 설치하지 말 것! Hermes는 사용자 디렉토리에 설치됨

4.7 command not found (설치 후)

원인: 셸 PATH 갱신 안 됨

해결책:

source ~/.bashrc   # 또는 source ~/.zshrc

# 여전히 안 되면 수동 추가
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
which hermes
ls ~/.local/bin/hermes

4.8 WSL2 가상화 비활성화

증상: WSL 자체가 안 켜짐

해결책:

BIOS에서 Intel VT-x / AMD-V 활성화
Windows 기능에서 “Linux용 Windows 하위 시스템” + “가상 머신 플랫폼” 체크
wsl --update 로 WSL 커널 업데이트
재부팅

4.9 WSL2에서 게이트웨이 시작 실패

증상: hermes gateway start 실행 후 바로 종료

원인: WSL2의 systemd 지원 불안정

해결책:

포그라운드 + tmux (가장 안정!)

tmux new -s hermes 'hermes gateway run'
# 재접속: tmux attach -t hermes

nohup 백그라운드

nohup hermes gateway run > ~/.hermes/logs/gateway.log 2>&1 &

systemd 활성화 (선택)

# /etc/wsl.conf에 추가
[boot]
systemd=true
# PowerShell에서: wsl --shutdown 후 재시작
systemctl is-system-running  # 확인

💡 실전 팁: Windows 절전 모드 환경에서는 tmux가 훨씬 안정적!

4.10 v0.8.0 RedactingFormatter 버그

증상: NameError: name 'RedactingFormatter' is not defined

원인: gateway/run.py에 클래스 임포트 누락

해결책:

nano ~/.hermes/hermes-agent/gateway/run.py

파일 상단에 추가:

import logging
import re

class RedactingFormatter(logging.Formatter):
    def format(self, record):
        msg = super().format(record)
        patterns = [r'sk-[a-zA-Z0-9]{32,}', r'key-[a-zA-Z0-9]{20,}']
        for pattern in patterns:
            msg = re.sub(pattern, "[REDACTED]", msg)
        return msg

→ 또는 hermes update로 패치 버전 받기

5. 문제 발생 시 대처 순서 (빠른 참조)

순서	문제	1순위 해결책
1	curl/git 없음	`sudo apt install -y curl git`
2	DNS 해석 실패	`/etc/resolv.conf` → 8.8.8.8 + `chattr +i`
3	SSH clone에서 멈춤	HTTPS로 수동 클론
4	프록시 환경	`export https_proxy=...`
5	Python 3.13 호환성	uv가 자동으로 3.11 설정
6	uv 없음	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
7	command not found	`source ~/.bashrc`
8	권한 꼬임	sudo 흔적 지우고 일반 유저로 재설치
9	게이트웨이 안 켜짐	tmux + `hermes gateway run`
10	v0.8.0 버그	`hermes update` 또는 run.py 수정

6. 권장 설치 순서 (WSL2 Ubuntu 24.04)

# 1. WSL2 네트워크 확인
ping 8.8.8.8
ping google.com

# 2. DNS 문제 있으면 수정 (위 4.1 참조)

# 3. 기본 도구 확인
git --version && curl --version && python3 --version

# 4. tmux 세션에서 설치 (SSH 끊김 방지!)
tmux new -s hermes-install
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 5. 실패하면 수동 설치
git clone --recurse-submodules https://github.com/NousResearch/hermes-agent.git
cd hermes-agent && ./scripts/install.sh

# 6. 셸 리로드
source ~/.bashrc

# 7. 설치 확인
hermes version
hermes doctor

# 8. 모델 설정
hermes model

7. 다음 단계 (아직 안 함)

Ollama 서버 연결
모델 설정 (hermes model)
Telegram 봇 연동

⚠️ 2026-04-20 업데이트: Ollama는 이제 맥미니에서 구동됨. 보조컴 WSL에 Ollama를 설치할 필요 없이 맥미니 Ollama로 연결 가능. model.base_url을 맥미니 Tailscale IP로 변경 필요.

[!note] 수정이력 | 2026-04-20 11:01, 미미