본문으로 건너뛰기

윈도우 (WSL2) 가이드

Hermes Agent는 이제 both네이티브 Windows 및 WSL2를 지원합니다. 이 페이지는 WSL2 경로를 다룹니다. 네이티브 PowerShell 설치는 전용**Windows (Native) Guide**를 참조하세요.

기본 WSL2를 선택할 때:

  • 대시보드의 임베디드 터미널 (/chat 탭)을 사용하려면 - 그 팬은 POSIX PTY를 필요로하며 WSL2-only입니다.
  • POSIX-heavy 개발 작업을 수행하고 자신의 테마 세션을 원하여 동일한 파일 시스템 / 경로를 dev 도구로 공유합니다.
  • 당신은 이미 WSL2 환경을 가지고 두 번째 설치를 유지하고 싶지 않습니다.

네트가 괜찮을 때 (더 나은):

  • 대화 형 채팅, 게이트웨이 (Telegram/Discord/etc.), cron 스케줄러, 브라우저 도구, MCP 서버 및 대부분의 Hermes는 Windows에서 기본적으로 실행됩니다.
  • 파일을 참조하거나 URL을 열 때마다 WSL↔Windows 경계를 교차하는 것에 대해 생각하지 마십시오.

WSL2에서 효과적으로 두 개의 컴퓨터가 있습니다. Windows 호스트 및 WSL에 의해 관리되는 Linux VM. 대부분의 혼란은 당신이 어떤 순간에 있는지 확실하지 않습니다.

이 가이드는 헤르메스에 특히 영향을 미치는 분할의 부분을 다룹니다. WSL2를 설치하고 Windows와 Linux간에 파일을 백업하고, 두 방향으로 네트워킹하고, pitfalls 사람들은 실제로 히트합니다.

정보

최소 설치 경로의 중국어 언어 연습이 동일한 페이지에 유지됩니다 - language메뉴 (위 오른쪽)을 통해 전환하고体中文를 선택하세요. 주요 특징

왜 WSL2 (vs. 네이티브 Windows)​

네이티브 Windows는 Windows에서 직접 실행됩니다. Windows 터미널 (PowerShell, Windows Terminal 등), Windows 파일 시스템 경로 (C:\Users\…) 및 Windows 프로세스. Hermes는 Git Bash를 사용하여 쉘 명령을 실행합니다. Claude Code와 다른 에이전트가 Windows를 오늘 처리하는 방법은 다음과 같습니다.

WSL2는 경량 VM에서 실제 리눅스 커널을 실행하므로 Hermes 내부는 Ubuntu에서 실행하는 것과 동일합니다. 그것은 당신이 진짜 POSIX 환경을 원할 때 유용합니다: fork, /tmp, UNIX 소켓, 신호 semantics, PTY-backed 터미널, bash/zsh와 같은 셸, rg, git, ffmpeg는 리눅스에 방법을 행동합니다.

WSL2의 실제 결과:

  • Hermes CLI, Gateway, sessions, Memory, Skill, Tool runtimes 모두 Linux VM 내부에서 라이브합니다.
  • Windows 프로그램 (브라우저, 네이티브 앱, 로그인 프로필이있는 크롬) 외곽.
  • 두 개의 대화를 원할 때마다 - 파일 공유, URL 열기, Chrome 제어, 로컬 모델 서버를 누르고, 휴대폰에 Hermes Gateway를 노출 - 당신은 경계를 교차합니다. 이 가이드는 다음과 같습니다.

WSL2 설치​

Admin PowerShell 또는 Windows 터미널에서:

사이트맵

Windows 10 22H2+ 또는 Windows 11 박스에 WSL2 커널, 가상 머신 플랫폼 기능 및 기본 Ubuntu 디트로를 설치합니다. 신속하게 재부팅. 재부팅 후 Ubuntu는 Linux 사용자 이름 + 암호를 열고 요청합니다. 이것은 새로운 Linux 사용자, Windows 계정과 관련이 없습니다.

WSL2 (법적 WSL1)에서 실제로 확인:

wsl --list --verbose

VERSION 2를 참조하세요. 디트로가 VERSION 1를 보여주는 경우, 변환:

사이트맵

Hermes는 WSL1에서 안정적으로 작동하지 않습니다. - WSL1은 리눅스에서 리눅스 syscalls를 번역하고 일부 행동 (procfs, 신호, 네트워크)는 실제 리눅스에서.

Distro 선택​

Ubuntu (LTS)는 우리가 테스트하는 것입니다. 데비안 작품. Arch and NixOS work for people who want them, 하지만 하나의 라인 설치 프로그램은 데비안 데비안 데비안 데비안 데비안 apt 시스템을 가정 — Nix 설정 가이드 그 경로.

헤르메스 게이트웨이 (그리고 당신이 실행을 유지하고 싶은 다른 것들)는 체계화 된 관리가 용이합니다. 현대 WSL에서, 당신의 디스트로 안쪽에 그것을 한 번 가능하게 합니다:

사이트맵

그런 다음 PowerShell에서:

wsl --shutdown

WSL 터미널을 엽니다. ps -p 1 -o comm=는 systemd를 인쇄해야 합니다.

위의 metadata 마운트 옵션은 중요하지 않습니다. /mnt/c/...의 파일은 실제 Linux 권한 비트를 저장할 수 없습니다. 이는 Windows 경로의 스크립트에서 chmod +x와 같은 것들을 깰 수 있습니다.

WSL 내부 헤르메스 설치​

WSL2 쉘이 오픈되면:

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

installer는 WSL2를 일반 리눅스로 취급합니다. — WSL-specific가 필요하지 않습니다. 전체 레이아웃에 대한 설치을 참조하세요.

파일 시스템: Windows ↔ WSL2 경계를 교차​

이것은 대부분의 사람들을 여행하는 부분입니다. 두 개의 파일 시스템, 그리고 당신은 당신의 파일 문제를 넣어 - 성능, 정확, 그리고 어떤 도구가 볼 수 있습니다.

두 방향​

| 오시는 길 | 오시는 길 | 오시는 길 | |---|---||| | WSL에서 볼 수 있는 윈도우 디스크 | C:\Users\you\Documents | /mnt/c/Users/you/Documents | | 윈도우에서 볼 수 있는 WSL 디스크 | /home/you/code | \\wsl$\Ubuntu\home\you\code(또는 \\wsl.localhost\Ubuntu\...) |

둘 다 진짜, 둘 다 일, 그러나 그들은 동일한 filesystem 아닙니다 - 그들은 후드의 밑에 네트워크 의정서에 의해 Bridged. 그것은 진짜 성과 및 semantic 결과가 있습니다.

# # Hermes와 프로젝트를 넣는 곳

Rule of thumb: Linux 파일 시스템 내에서 모든 Linux-ish를 유지합니다.

  • Your Hermes install (~/.hermes/) - 리눅스 측. installer는 이미 이것을 합니다.
  • WSL - Linux 측 (~/code/..., ~/projects/...)에서 작업하는 git 저장소.
  • 모델, 데이터 세트, venvs - 리눅스 측.

이 규칙을 따르는 것:

  • 빠른 I/O. /mnt/c/...의 작동은 를 통해 이동하고 기본 ext4보다 10 ~ 100 × 느리게됩니다. ~/code에서 ~/code에서 즉시 느낄 10k 파일 저장소에 /mnt/c에서 15 + 초를 취할 수 있습니다.
  • ** 정확한 권한.** 리눅스 권한 비트는 /mnt/c에서 최고의 노력 에뮬레이션입니다. ssh와 같은 것들은 "나쁜 권한"또는 chmod +x로 키가 자동으로 실패하는 것이 일반적입니다. -Reliable file watchers. inotify from is flaky — file watchers (dev server, test runners) routine로 /mnt/c의 변경을 놓습니다.
  • 아니면 감각적인 놀라움. Windows 경로는 기본적으로 case-insensitive; Linux는 case-sensitive입니다. Readme.md와 README.md 모두 프로젝트는 당신이 위에 있는 측에 따라서 다르게 행동합니다.

/mnt/c에 물건을 넣을 때 ** Windows 측에서 살 수있는 파일 - 예를 들어 Windows GUI 응용 프로그램에서 열려면 Windows Chrome의 DevTools MCP가 현재 디렉토리를 Windows-reachable 경로가 필요합니다.

파일을 다시 가져 오기​

Windows에서 → WSL로: 가장 쉬운은 주소 막대기에 있는 Explorer와 유형 \\wsl.localhost\Ubuntu를 여는 것입니다. \home\<you>\...로 드래그 드롭 할 수 있습니다. 또는 PowerShell에서:

사이트맵

**WSL에서 → Windows로: ** /mnt/c/Users/<you>/...에 복사하고 Windows Explorer에서 즉시 보여줍니다:

사이트맵

**Windows 앱에서 WSL 파일을 엽니 다 ** (GUI 편집기, 브라우저 등): explorer.exe 또는 wslview를 사용하세요.

sudo apt install wslu     # once — gives you wslview, wslpath, wslopen, etc.
wslview ~/reports/output.pdf    # opens with the Windows default handler
explorer.exe.                  # opens the current WSL dir in Windows Explorer

두 우주 사이의 경로:

모델 번호: ```bash wslpath -w ~/code/project # → \wsl.localhost\Ubuntu\home\you\code\project wslpath -u 'C:\Users\you' # → /mnt/c/Users/you


### 라인 종료, BOM 및 git

Windows 편집기로 Windows 측에 파일을 편집하면 `CRLF` 라인 종료를 얻을 수 있습니다. 리눅스 측에서 `bash` 또는 Python이 읽을 때, `bad interpreter: /bin/bash^M`와 Python이 BOM'd `.env` 파일에 실패할 수 있습니다.

수정은 WSL 내부의 sane git config (Windows에서 아닙니다):

```bash
git config --global core.autocrlf input
git config --global core.eol lf

이미 CRLF가 있는 파일들:

sudo apt install dos2unix
dos2unix path/to/script.sh

"WSL 내부 또는 /mnt/c에서 혼자?"​

WSL 내부 복제. 항상, 당신은 특정 이유가없는. 전형적인 헤르메스 워크플로우 (hermes chat, 도구는 rg/ripgrep의 재포, 파일 시계, 배경 게이트웨이)가 ~/code/myrepo보다 극적으로 빠르고 신뢰할 수 있습니다.

One 예외: MCP bridges that launch Windows binaries. cmd.exe를 통해 chrome-devtools-mcp를 사용하는 경우 (MCP 가이드: WSL → Windows Chrome, Windows는 Hermes의 현재 작업 디렉토리가 UNC 경고로 불평할 수 있습니다. 그 경우, /mnt/c/에 따라 어딘가에서 헤르메스를 시작하므로 Windows 프로세스에는 드라이브 테터 cwd가 있습니다.

네트워킹: WSL ↔ 윈도우​

WSL2는 자체 네트워크 스택과 경량 VM에서 실행됩니다. 즉, WSL 내부의 localhost는 ** Windows의 localhost와 동일하지 않습니다. 그들은 네트워크의 관점에서 두 개의 별도의 호스트입니다. 당신은 결정해야, 각 서비스, 방향 교통 흐름과 오른쪽 다리를 선택.

두 개의 케이스가 계속됩니다.

Case 1 - WSL의 Hermes는 Windows에서 서비스에 대해 이야기합니다.​

가장 일반적인: 당신은 실행 **올라마, LM 스튜디오, 또는 Windows의 llama 서버 **, 그리고 헤르메스 (WSL 옆에) 그것을 타격해야합니다.

공급자 가이드에서 이 삶을 위한 canonical 방법: WSL2 Local Models →

짧은 버전:

-Windows 11 22H2+: 미러링 네트워크 모드(networkingMode=mirrored%USERPROFILE%\.wslconfig, wsl --shutdown)로 전환합니다. localhost는 두 방향으로 작동합니다.

  • ** Windows 10 이상 빌드: ** Windows 호스트 IP (WSL의 가상 네트워크의 기본 게이트웨이)를 사용하며 0.0.0.0에 Windows binds에 서버를 확인합니다. 127.0.0.1. Windows 방화벽은 일반적으로 포트에 대한 규칙이 필요합니다.

전체 테이블 (Ollama / LM Studio / vLLM / SGLang 바인드 주소, 방화벽 규칙 원 라이너, 동적 IP 헬퍼, 하이퍼-V 방화벽 workaround)의 경우 위의 링크를 따르십시오. - 그것을 복제하지 마십시오.

Case 2 - Windows에서 뭔가 (또는 LAN) WSL에서 헤르메스에 이야기​

이것은 역방향이며 다른 곳에서 더 적은 문서이지만 필요한 것은 다음과 같습니다.

  • Windows 브라우저에서 Hermes ** 웹 대시보드**를 사용하십시오.
  • **OpenAI 호환 API 서버 ** (Windows 측 도구에서 hermes gateway에 의해 제안). API Server 기능 페이지를 참조하십시오.
  • 로컬 웹훅 URL을 핑하는 플랫폼 인 Telegram, Discord 등 ** (Telegram, Discord 등)을 테스트합니다. 보통 cloudflared/ngrok를 사용하므로 포트 포워딩보다는 좋습니다.

Subcase 2a: Windows 호스트 자체에서​

**윈도우 11 22H2 + 미러링 모드 활성화 **, 할 아무것도 없습니다. 0.0.0.0:8080 (또는 127.0.0.1:8080)에 묶는 WSL의 프로세스는 http://localhost:8080의 Windows 브라우저에서 액세스 할 수 있습니다. WSL은 호스트에 다시 바인딩을 게시합니다.

** NAT 모드** (Windows 10 / 이전 Windows 11), WSL2의 기본 "localhost forwarding"은 일반적으로 Linux-side 127.0.0.1 바인드를 Windows localhost로 전달하므로 Hermes 서비스는 Windows에서 --host 127.0.0.1로 시작됩니다. 그렇지 않다면:

  • WSL 내부 0.0.0.0에 Bind.
  • ip -4 addr show eth0 | grep inet를 가진 WSL VM의 IP를 찾아서 Windows에서 그 것을 명중하십시오.

Subcase 2b: 당신의 랜 (전화, 정제, 다른 PC)에 다른 장치에서​

이것은 진짜 고통입니다. 교통 흐름 ** LAN 장치 → Windows 호스트 → WSL VM **, 당신은 모두 hops 설정해야:

  1. ** WSL 내부의 모든 인터페이스에 대한 개요.** 127.0.0.1에서 듣는 과정은 VM 외부에서 결코 도달할 수 없습니다. 0.0.0.0를 사용하십시오.

  2. ** 포트 포워드 윈도우 → WSL VM.** 미러링 모드에서는 자동입니다. NAT 모드에서, 포트 당, Admin PowerShell:

# WSL VM의 현재 IP를 잡아 (NAT 아래 모든 WSL 재시작에 변화)
$wslIp = (wsl hostname -I). 트리밍().Split(' ')[0]

# 앞으로 Windows 항구 8080 → WSL: 8080
netsh 인터페이스 portproxy v4tov4를 추가합니다.
listenaddress=0.0.0.0 listenport=8080 ``
connectaddress=$wslIp connectport=8080 연결

# Windows 방화벽을 통해 허용
새로운 NetFirewallRule -DisplayName "Hermes WSL 8080"`
-Direction Inbound -Protocol TCP -LocalPort 8080 -Action 허용

netsh interface portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080로 나중에 제거하십시오.

  1. ** http://<windows-lan-ip>:8080에서 LAN 장치 포인트. **

NAT 모드에서 각 재시작에 WSL VM IP 편향 때문에, 한 샷 규칙은 다음 wsl --shutdown까지만 살아납니다. 모든 영구적 인 경우, 미러링 모드를 사용하거나 Windows 로그인에서 실행되는 스크립트의 포트 프록시 단계를 넣어.

클라우드 메시징 제공 업체 (Telegram setWebhook, Slack 이벤트 등)의 webhooks에 대해서는 포트 포워딩을 사용하지 마십시오. cloudflared 터널을 사용하십시오. 웹훅 가이드를 참조하십시오.

Windows에서 Hermes 서비스 장기 실행​

Hermes Tool Gateway 및 API 서버는 오래 살아 있는 프로세스입니다. WSL2에서 당신은 그들을 유지하기위한 몇 가지 옵션이 있습니다.

내부 WSL 시스템 (추천)​

위의 설정 섹션에서 시스템화 된 경우, hermes gateway 및 API 서버는 Linux 기계에서 수행하는 방법을 사용합니다. Gateway 설정 마법사를 사용하십시오:

hermes gateway setup

WSL이 시작될 때 시스템화된 사용자 단위를 설치하기 위하여 제안할 것입니다.

##WSL 자체가 Windows 로그인 시작

WSL의 VM은 살아있을 뿐입니다. 터미널 창이 열리지 않고 게이트웨이를 유지하려면, 작업 스케줄러를 통해 Windows 로그인에서 WSL 프로세스를 부팅하십시오.

  • ** 트리거: ** 로그인 (사용자).
  • 액션: 프로그램
  • 프로그램: C:\Windows\System32\wsl.exe
  • 배열: -d Ubuntu --exec /bin/sh -c "sleep infinity"

VM이 살아있어 시스템 관리 게이트웨이가 실행됩니다. Windows 11에서, 더 새로운 wsl --install --no-launch + 자동 시작은 또한 일합니다; sleep infinity 트릭은 휴대용 버전입니다.

GPU passthrough (현지 모델)​

WSL2는 ** NVIDIA** GPU를 기본적으로 WSL 커널 5.10.43+부터 지원하며, Windows에서 표준 NVIDIA 드라이버를 설치합니다. (donot는 WSL 내부의 Linux NVIDIA 드라이버를 설치), WSL 내부 nvidia-smi는 GPU를 볼 수 있습니다. 거기에서, CUDA 툴킷, torch, vllm, sglang, 그리고 llama-server는 일반적인 진짜 GPU에 대하여 구조합니다.

AMD ROCm 및 Intel Arc 지원 내부 WSL2는 여전히 진화하고 외부 Hermes의 테스트 매트릭스 - 현재 드라이버와 함께 작동 할 수 있지만 권장하는 레시피가 없습니다.

Windows-native Local-model 서버 (Windows, LM Studio용 Ollama)를 실행하면 이미 Windows 드라이버를 통해 GPU를 사용하므로 WSL GPU를 모두 추적 할 필요가 없습니다. - 위의 사례 1을 따르고 WSL에서 네트워크에 히트하십시오.

일반적인 pitfalls​

"연결 거부"내 Windows 호스팅 Ollama / LM Studio. WSL2 네트워킹를 참조하십시오. 서버가 127.0.0.1에 바인딩되고 0.0.0.0 (Ollama: OLLAMA_HOST=0.0.0.0)가 필요하거나 방화벽 규칙을 누락했습니다.

** git status / hermes chat의 느린. ** /mnt/c/...의 밑에 아마 일하고 있습니다. ~/code/... (리눅스 측)로 재포를 이동합니다. 빠른 주문-magnitude.

**bad interpreter: /bin/bash^M 스크립트에. ** CRLF 라인은 Windows 편집기에서 끝납니다. dos2unix script.sh 및 WSL git config에서 core.autocrlf input를 설정합니다.

"UNC 경로는 지원되지 않습니다"Windows binaries에서 경고는 MCP를 통해 시작. Hermes의 cwd는 Linux 파일 시스템 내부이며, Windows cmd.exe는 그것을 사용하는 것을 알 수 없습니다. 그 세션에 /mnt/c/...에서 Hermes를 시작하거나 cd가 Windows 실행 가능한 Windows 복구 경로에 Windows 접근 가능한 경로로 래퍼를 사용합니다.

**잠자기 / 난산 후 막 드립. ** WSL2의 시계는 잠에서 주인 이력서 후에 분에 의해 지연될 수 있습니다, 어떤 cert 기초를 두는 (OAuth, HTTPS APIs). 수요에 그것을 수정하십시오:

sudo hwclock -s

또는 ntpdate를 설치하고 로그인에서 실행하십시오.

DNS는 미러링 모드를 활성화하거나 VPN이 연결되면 작동 중지합니다. 미러링 모드 프록시 호스트 네트워크 설정 WSL - Windows DNS가 funky (VPN split-tunnel, Corporate resolver) 인 경우 WSL은 그 상을 수상했습니다. Workaround: 수동으로 resolv.conf (generateResolvConf=false를 /etc/wsl.conf에서 설정한 /etc/resolv.conf를 1.1.1.1 또는 VPN의 DNS로 설정하십시오).

**hermes는 설치 프로그램을 실행한 후 찾을 수 없습니다. ** 설치 프로그램은 ~/.local/bin를 ~/.bashrc를 통해 쉘의 PATH에 추가합니다. source ~/.bashrc (또는 새로운 터미널을 엽니 다) 현재 세션에서 효과를 가져야합니다.

**Windows Defender는 WSL 파일에 느립니다. ** 수비수는 Windows에서 액세스 할 때 브리지를 통해 파일을 스캔합니다. /mnt/c-style Cross-boundary Access의 느린 속도를 확대합니다. WSL 내부에서 WSL 파일을 만 터치하면 이것이 중요하지 않습니다. \\wsl$\...에 대한 Windows 도구를 자주 사용하는 경우 실시간 스캔에서 WSL 디트로 경로를 제외하십시오.

디스크에서 멋진. WSL2는 %LOCALAPPDATA%\Packages\...에서 비소 VHDX로 VM 디스크를 저장합니다. 파일을 삭제할 때 자동 저장하지 않습니다. 공간을 다시 인용하려면: wsl --shutdown, 그 후 관리자 PowerShell 실행 Optimize-VHD -Path <path-to-ext4.vhdx> -Mode Full ( 하이퍼 V 도구 필요) - 또는 간단한 diskpart 경로 WSL 문서에 문서.

다음으로 갈 곳​

-Installation - 실제 설치 단계 (Linux/WSL2/Termux는 모두 동일한 설치 프로그램을 사용합니다).