Windows 환경에서 Hermes AI 설치하기: Desktop, PowerShell 및 WSL2
Windows 10 및 11 환경에서 Hermes AI를 설치하기 위한 포괄적인 가이드입니다. 네이티브 PowerShell 실행, Hermes Desktop 그래픽 인터페이스, WSL2 환경의 장단점과 구조적 차이를 비교하고, 실행 환경 진단 및 문제 해결 팁을 제공합니다.
목차
Hermes Agent는 Windows 10 및 Windows 11을 지원합니다. 사용자는 PowerShell을 통한 네이티브 실행, Hermes Desktop 그래픽 애플리케이션, WSL2 환경이라는 세 가지 배포 시나리오 중에서 선택할 수 있습니다. 적합한 설치 방식을 선택하려면 사용하는 빌드 도구, 터미널 요구사항 및 파일 시스템 아키텍처를 고려해야 합니다.
설치 방식 선택: 네이티브 환경 vs WSL2
설치하기 전에 먼저 수행할 작업의 런타임 컨텍스트를 명확히 파악하는 것이 중요합니다:
- 네이티브 PowerShell 및 Hermes Desktop은 동일한 데이터 구조를 공유합니다. 소스 코드와 가상 환경은
%LOCALAPPDATA%\hermes\hermes-agent에 위치하며, 사용자 설정, 세션 기록 및 스킬은%LOCALAPPDATA%\hermes에 저장됩니다. 데스크톱 인터페이스와 콘솔 CLI는 상호 교환 가능하며 정확히 동일한 상태에서 작동합니다. - WSL2는 Linux 가상 머신 내부에 환경을 격리하며, 설정 파일은
~/.hermes에 별도로 저장합니다.
아키텍처 선택 예시
- Windows 중심 프로젝트(PowerShell / .NET / 시스템 유틸리티): 호스트 워크플로를 자동화하거나, Windows 작업 스케줄러를 통해 Telegram 또는 Discord 백그라운드 게이트웨이를 실행하고, 로컬 NTFS 파일 시스템에서 작업하는 경우에는 네이티브 PowerShell 또는 Hermes Desktop을 선택하십시오.
- Linux 스택 프로젝트(Docker, Make, POSIX 스크립트): 에이전트가 Linux 바이너리를 컴파일하거나, UNIX 소켓과 통신하거나, 웹 대시보드의 내장 터미널을 통해 세션을 관리해야 한다면 WSL2에 에이전트를 배포하십시오. 네이티브 Windows 빌드에서도 웹 대시보드가 지표 확인 및 구성을 지원하지만,
/chat임베디드 터미널 탭은 POSIX PTY를 요구하므로 WSL2 환경에서만 사용할 수 있습니다.
옵션 1: PowerShell을 통한 네이티브 설치
네이티브 설치 프로그램은 관리자 권한을 요구하지 않으며, uv 패키지 관리자, 격리된 Python 3.11 런타임, 브라우저 자동화 도구용 Node.js 및 PortableGit을 자동으로 설정합니다. 시스템에 Python을 전역으로 별도 설치할 필요가 없습니다.
기본 PowerShell 콘솔을 열고 다음 명령을 실행합니다:
iex (irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)이 스크립트는 현재 사용자의 PATH 환경 변수에 %LOCALAPPDATA%\hermes\bin 경로를 추가합니다. 스크립트 실행이 완료되면 콘솔 창을 닫고 새 터미널 세션을 열어 갱신된 PATH를 적용하십시오. 고급 스크립트 매개변수에 대한 자세한 내용은 공식 Windows Native 가이드를 참조하십시오.
옵션 2: Hermes Desktop 그래픽 클라이언트
Hermes Desktop은 세션 사이드바, 시각적 스킬 그래프, 탭 지원 및 병렬 에이전트 관리 기능을 갖춘 창 기반 인터페이스를 제공합니다.
- Hermes Desktop 문서 페이지에서 설치 프로그램을 다운로드합니다.
- 다운로드한 설치 파일을 실행합니다. 처음 실행할 때 애플리케이션은
%LOCALAPPDATA%\hermes디렉터리 내에서 종속성 설정 스크립트를 자동으로 실행합니다.
PowerShell을 통해 이미 에이전트를 설정해 두었다면, 데스크톱 애플리케이션이 기존 API 키와 저장된 대화 내역을 즉시 불러와 그대로 사용합니다.
옵션 3: WSL2 내부 설치
WSL2는 표준 Linux 환경(ext4 파일 시스템, POSIX 시그널, PTY 지원)을 제공합니다.
1단계. WSL2 환경 준비
관리자 권한으로 실행한 PowerShell 콘솔(관리자 권한으로 실행)에서 다음을 실행합니다:
wsl --install시스템 안내에 따라 컴퓨터를 재부팅한 후 Linux 사용자 이름과 비밀번호를 설정합니다. 그 다음 설치된 배포판의 버전을 확인합니다:
wsl --list --verbose선택한 배포판(기본값: Ubuntu)의 VERSION 열에 2가 표시되어 있는지 확인하십시오.
2단계. Hermes Agent 배포
Ubuntu 터미널을 열고 WSL2 빠른 시작 가이드에 따라 설치 명령을 실행합니다:
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc중요: 작업 중인 저장소 및 프로젝트 파일은 마운트된 Windows 드라이브(
/mnt/c/) 대신 Linux 파일 시스템 내부(예:~/projects/)에 보관하십시오. 9P 프로토콜을 통한 경계 간 파일 호출은 I/O 성능 저하 및git작업 지연을 유발할 수 있습니다.
실행 환경 점검 및 첫 실행
환경 진단 및 실행은 각 환경에 맞는 해당 터미널에서 수행해야 합니다. 네이티브 설치 및 Hermes Desktop의 경우 PowerShell을 사용하고, WSL2의 경우 Ubuntu 터미널을 사용하십시오.
네이티브 설치 및 Hermes Desktop의 경우, 새 PowerShell 세션을 열고 다음 검사를 실행합니다:
Get-Command hermes
hermes --version
hermes doctorWSL2 설치의 경우, Ubuntu 터미널을 열고 진단을 실행합니다:
command -v hermes
hermes --version
hermes doctorhermes doctor 명령은 git, Chromium 브라우저 엔진 및 보조 종속성에 대한 경로 확인 상태를 점검합니다.
채팅 세션을 시작하기 전에 모델 제공자를 구성해야 합니다. 아직 구성하지 않았다면 먼저 hermes setup 명령을 실행하여 모델 제공자를 선택하십시오(네이티브 환경은 PowerShell 창에서, WSL2는 Ubuntu 터미널에서 실행).
설정을 완료한 후 해당 터미널에서 기본 대화를 시작하고 파일 쓰기가 필요하지 않은 작업으로 테스트하십시오. hermes chat은 권한 샌드박싱을 강제하지 않는다는 점에 유의해야 합니다:
hermes chat첫 번째 프롬프트로는 디스크 쓰기가 필요하지 않은 지시문(예: 아키텍처 개념 설명 요청)을 전달해 보십시오. 설정된 모델 제공자가 올바르게 초기화되고 인코딩 오류 없이 스트리밍 텍스트가 정상 출력되는 것이 기대되는 결과입니다.
개별 모델의 선택적 설정과 관련된 자세한 내용은 BetterToken 문서를 참조하십시오.
자주 묻는 문제 및 해결 방법
| 발생한 증상 | 원인 | 해결 방법 |
|---|---|---|
hermes: The term 'hermes' is not recognized | 현재 콘솔 세션에 업데이트된 User PATH가 다시 로드되지 않았습니다. | PowerShell 창을 다시 시작하거나 바이너리를 직접 호출하십시오: & "$env:LOCALAPPDATA\hermes\bin\hermes.exe". |
웹 대시보드의 /chat 탭에 오류 배너가 표시됨 | 네이티브 Windows에는 POSIX PTY 시스템 메커니즘이 없습니다. | 세션 및 작업 관리는 네이티브 환경에서도 정상 작동하지만, /chat의 웹 터미널을 사용하려면 WSL2 내부에서 에이전트를 실행하십시오. |
WinError 193: %1 is not a valid Win32 application | .cmd 래퍼 없이 스크립트를 직접 호출하려고 시도했습니다. | Windows에서는 명시적인 확장자를 붙여 Node 및 npm 도구를 실행하십시오(예: npx.cmd). |
CLI에서 유니코드 문자 대신 물음표(?)가 출력됨 | CP 65001을 지원하지 않는 구형 콘솔 호스트입니다. | Windows Terminal을 사용하십시오. HERMES_DISABLE_WINDOWS_UTF8 환경 변수가 1로 설정되어 있지 않은지 확인하십시오. |
WSL2 내부에서 git status 실행 시 지연 발생 | 프로젝트 작업 디렉터리가 /mnt/c/... 경로에 위치해 있습니다. | 네이티브 ext4 성능을 활용할 수 있도록 작업 저장소를 배포판의 Linux 홈 디렉터리(~/code/...)로 이동하십시오. |
