Chuyển tới nội dung chính

Hướng dẫn Windows (WSL2)

Hermes Agent hiện hỗ trợ cả Windows gốc và WSL2. Trang này trình bày đường dẫn WSL2; để biết bản cài đặt PowerShell gốc, hãy xem Hướng dẫn dành riêng cho Windows (Bản địa).

Khi nào nên chọn WSL2 thay vì bản gốc:

  • Bạn muốn sử dụng thiết bị đầu cuối được nhúng của trang tổng quan (tab /chat) — khung đó yêu cầu POSIX PTY và chỉ có WSL2.
  • Bạn đang thực hiện công việc phát triển nặng về POSIX và muốn các phiên Hermes của bạn chia sẻ cùng hệ thống tệp/đường dẫn như các công cụ phát triển của bạn.
  • Bạn đã có môi trường WSL2 và không muốn duy trì cài đặt thứ hai.

Khi tiếng bản địa phù hợp (hoặc tốt hơn):

  • Trò chuyện tương tác, cổng (Telegram/Discord/v.v.), bộ lập lịch cron, công cụ trình duyệt, máy chủ MCP và hầu hết các tính năng của Hermes đều chạy nguyên bản trên Windows.
  • Bạn không muốn nghĩ đến việc vượt qua ranh giới WSL↔Windows mỗi khi tham chiếu một tệp hoặc mở một URL.

Trong WSL2 thực tế có hai máy tính đang hoạt động: máy chủ Windows của bạn và máy ảo Linux do WSL quản lý. Hầu hết sự nhầm lẫn đều xuất phát từ việc không chắc chắn mình đang sử dụng cái nào vào bất kỳ lúc nào.

Hướng dẫn này đề cập đến các phần của sự phân chia đó ảnh hưởng cụ thể đến Hermes: cài đặt WSL2, nhận các tệp qua lại giữa Windows và Linux, kết nối mạng theo cả hai hướng và những cạm bẫy mà mọi người thực sự gặp phải.

:::thông tin 简体中文 Hướng dẫn bằng tiếng Trung về đường dẫn cài đặt tối thiểu được duy trì trên cùng trang này — chuyển qua menu ngôn ngữ (trên cùng bên phải) và chọn 简体中文. :::

Tại sao lại là WSL2 (so với Windows gốc)

Bản cài đặt Windows gốc chạy trực tiếp trong Windows: thiết bị đầu cuối Windows của bạn (PowerShell, Windows Terminal, v.v.), đường dẫn hệ thống tệp Windows (C:\Users\…) và các quy trình Windows. Hermes sử dụng Git Bash để chạy các lệnh shell, đó là cách Claude Code và các tác nhân khác xử lý Windows ngày nay - nó vượt qua khoảng cách POSIX-so với Windows mà không cần viết lại toàn bộ.

WSL2 chạy nhân Linux thực trong một máy ảo nhẹ, vì vậy Hermes bên trong nó về cơ bản giống với chạy trên Ubuntu. Điều đó có giá trị khi bạn muốn có một môi trường POSIX thực sự: fork, /tmp, ổ cắm UNIX, ngữ nghĩa tín hiệu, thiết bị đầu cuối được PTY hỗ trợ, các shell như bash/zsh và các công cụ như rg, git, ffmpeg hoạt động theo cách chúng hoạt động trên Linux.

Hậu quả thực tế của WSL2:

  • Hermes CLI, cổng, phiên, bộ nhớ, kỹ năng và thời gian chạy công cụ đều nằm trong máy ảo Linux.
  • Các chương trình Windows (trình duyệt, ứng dụng gốc, Chrome với hồ sơ đăng nhập của bạn) nằm bên ngoài nó.
  • Mỗi khi bạn muốn cả hai nói chuyện — chia sẻ tệp, mở URL, điều khiển Chrome, truy cập máy chủ mô hình cục bộ, đưa cổng Hermes vào điện thoại của bạn — bạn đã vượt qua một ranh giới. Những ranh giới đó chính là nội dung của hướng dẫn này.

Cài đặt WSL2

Từ Admin PowerShell hoặc Windows Terminal:

wsl --install

Trên hộp Windows 10 22H2+ hoặc Windows 11 mới, cài đặt này sẽ cài đặt kernel WSL2, tính năng Nền tảng máy ảo và bản phân phối Ubuntu mặc định. Khởi động lại khi được nhắc. Sau khi khởi động lại, Ubuntu sẽ mở và yêu cầu tên người dùng + mật khẩu Linux - đây là người dùng Linux mới, không liên quan đến tài khoản Windows của bạn.

Xác minh rằng bạn thực sự đang sử dụng WSL2 (không phải WSL1 cũ):

wsl --list --verbose

Bạn sẽ thấy PHIÊN BẢN 2. Nếu một bản phân phối hiển thị PHIÊN BẢN 1, hãy chuyển đổi nó:

wsl --set-version Ubuntu 2
wsl --set-default-version 2

Hermes không hoạt động đáng tin cậy trên WSL1 - WSL1 dịch các tòa nhà Linux một cách nhanh chóng và một số hành vi (procfs, tín hiệu, mạng) khác với Linux thực.

Lựa chọn phân phối

Ubuntu (LTS) là thứ chúng tôi thử nghiệm. Debian hoạt động. Arch và NixOS hoạt động cho những người muốn chúng, nhưng trình cài đặt một dòng giả định hệ thống apt bắt nguồn từ Debian — xem hướng dẫn thiết lập Nix để biết đường dẫn đó.

Kích hoạt systemd (được khuyến nghị)

Cổng Hermes (và bất kỳ thứ gì khác mà bạn muốn tiếp tục chạy) sẽ dễ quản lý hơn với systemd. Trên WSL hiện đại, hãy kích hoạt nó một lần trong bản phân phối của bạn:

sudo tee /etc/wsl.conf >/dev/null <<'EOF'
[boot]
systemd=true

[interop]
enabled=true
appendWindowsPath=true

[tự động đếm]
tùy chọn = "siêu dữ liệu,umask=22,fmask=11"
EOF

Sau đó từ PowerShell:

wsl --shutdown

Mở lại thiết bị đầu cuối WSL của bạn. ps -p 1 -o comm= nên in systemd.

Tùy chọn gắn kết siêu dữ liệu ở trên rất quan trọng — nếu không có nó, các tệp trên /mnt/c/... không thể lưu trữ các bit cấp phép Linux thực sự, điều này sẽ phá vỡ những thứ như chmod +x trên các tập lệnh trong đường dẫn Windows.

Cài đặt Hermes bên trong WSL

Khi bạn đã mở shell WSL2:

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

Trình cài đặt coi WSL2 như Linux thuần túy — không cần gì cụ thể về WSL. Xem Cài đặt để biết bố cục đầy đủ.

Hệ thống tập tin: vượt qua ranh giới Windows ↔ WSL2

Đây là phần khiến nhiều người vấp ngã nhất. Có hai hệ thống tệp và vị trí bạn đặt tệp rất quan trọng — về hiệu suất, độ chính xác và những gì công cụ có thể nhìn thấy.

###Hai hướng

DirectionPath insidePath you use
Windows disk, seen from WSLC:\Users\you\Documents/mnt/c/Users/you/Documents
WSL disk, seen from Windows/home/you/code\\wsl$\Ubuntu\home\you\code (or \\wsl.localhost\Ubuntu\... on newer builds)

Cả hai đều là thật, cả hai đều hoạt động, nhưng chúng không phải cùng một hệ thống tệp — chúng được kết nối bằng giao thức mạng 9P bên trong. Điều đó có hiệu suất thực sự và hậu quả ngữ nghĩa.

Nơi đặt Hermes và các dự án của bạn

Quy tắc chung: giữ mọi thứ giống Linux bên trong hệ thống tập tin Linux.

  • Bản cài đặt Hermes của bạn (~/.hermes/) — phía Linux. Trình cài đặt đã thực hiện việc này.
  • Kho git của bạn mà bạn làm việc từ WSL — phía Linux (~/code/..., ~/projects/...).
  • Mô hình, bộ dữ liệu, venv của bạn — phía Linux.

Bạn nhận được gì khi tuân theo quy tắc này:

  • I/O nhanh. Các hoạt động trên /mnt/c/... trải qua 9P và chậm hơn 10–100× so với ext4 gốc. git status trên kho lưu trữ tệp 10k có cảm giác tức thì trong ~/code có thể mất hơn 15 giây trong /mnt/c.
  • Quyền chính xác. Các bit cấp phép Linux là một mô phỏng nỗ lực tốt nhất trên /mnt/c. Những hiện tượng như ssh từ chối một khóa có "quyền xấu" hoặc chmod +x bị lỗi âm thầm là phổ biến.
  • Trình theo dõi tệp đáng tin cậy. inotify trên 9P không ổn định — trình theo dõi tệp (máy chủ nhà phát triển, trình chạy thử) thường xuyên bỏ lỡ các thay đổi trên /mnt/c.
  • Không có bất ngờ nào về phân biệt chữ hoa chữ thường. Đường dẫn Windows theo mặc định không phân biệt chữ hoa chữ thường; Linux phân biệt chữ hoa chữ thường. Các dự án có cả Readme.mdREADME.md hoạt động khác nhau tùy thuộc vào phía bạn.

Chỉ đặt mọi thứ trên /mnt/c khi bạn cần một tệp nằm ở phía Windows - ví dụ: bạn muốn mở tệp đó từ ứng dụng GUI của Windows hoặc DevTools MCP của Windows Chrome cần thư mục hiện tại là đường dẫn mà Windows có thể truy cập.

Lấy file qua lại

Từ Windows → vào WSL: dễ nhất là mở Explorer và nhập \\wsl.localhost\Ubuntu vào thanh địa chỉ. Sau đó, bạn có thể kéo-thả vào \home\<you>\.... Hoặc từ PowerShell:

wsl cp /mnt/c/Users/you/Downloads/file.pdf ~/incoming/

Từ WSL → vào Windows: sao chép vào /mnt/c/Users/<you>/... và nó sẽ hiển thị ngay trong Windows Explorer:

cp ~/reports/output.pdf /mnt/c/Users/you/Desktop/

Mở tệp WSL trong ứng dụng Windows (trình soạn thảo GUI, trình duyệt, v.v.): sử dụng explorer.exe hoặc 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

Chuyển đổi đường dẫn giữa hai vũ trụ:

wslpath -w ~/code/project        # → \\wsl.localhost\Ubuntu\home\you\code\project
wslpath -u 'C:\Users\you' # → /mnt/c/Users/you

Kết thúc dòng, BOM và git

Nếu bạn chỉnh sửa các tệp ở phía Windows bằng trình chỉnh sửa Windows, chúng có thể nhận được phần cuối dòng CRLF. Khi bash hoặc Python ở phía Linux đọc chúng, các tập lệnh shell bị hỏng với trình thông dịch kém: /bin/bash^M và Python có thể bị lỗi trên các tệp .env của BOM.

Cách khắc phục là cấu hình git lành mạnh bên trong WSL (không phải trên Windows):

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

Đối với các tệp đã có CRLF:

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

"Sao chép bên trong WSL hoặc trên /mnt/c?"

Sao chép bên trong WSL. Luôn luôn, trừ khi bạn có lý do cụ thể để không làm vậy. Một quy trình làm việc điển hình của Hermes (hermes chat, công cụ gọi đó là rg/ripgrep kho lưu trữ, trình theo dõi tệp, cổng nền) sẽ nhanh hơn đáng kể và đáng tin cậy hơn đối với ~/code/myrepo so với /mnt/c/Users/you/myrepo.

Một ngoại lệ: Cầu nối MCP khởi chạy các tệp nhị phân Windows. Nếu bạn đang sử dụng chrome-devtools-mcp đến cmd.exe (xem Hướng dẫn MCP: WSL → Windows Chrome), Windows có thể khiếu nại với cảnh báo UNC nếu thư mục làm việc hiện tại của Hermes là ~. Trong trường hợp đó, hãy khởi động Hermes từ đâu đó trong /mnt/c/ để tiến trình Windows có ký tự ổ đĩa cwd.

Kết nối mạng: WSL ↔ Windows

WSL2 chạy trong một máy ảo nhẹ với ngăn xếp mạng riêng. Điều đó có nghĩa là localhost bên trong WSL không giống localhost trên Windows — chúng là hai máy chủ riêng biệt theo quan điểm của mạng. Đối với mỗi dịch vụ, bạn cần phải quyết định hướng giao thông di chuyển và chọn cây cầu phù hợp.

Hai trường hợp xảy ra liên tục.

Trường hợp 1 - Hermes trong WSL nói chuyện với một dịch vụ trên Windows

Phổ biến nhất: bạn đang chạy Ollama, LM Studio hoặc máy chủ llama trên Windows và Hermes (bên trong WSL) cần phải tấn công nó.

Cách thực hiện chuẩn mực cho hoạt động này trong hướng dẫn của nhà cung cấp: Mạng WSL2 cho các mô hình cục bộ →

Phiên bản ngắn:

  • Windows 11 22H2+: bật chế độ kết nối mạng được nhân đôi (networkingMode=mirrored trong %USERPROFILE%\.wslconfig, sau đó wsl --shutdown). localhost sau đó hoạt động theo cả hai hướng.
  • Bản dựng Windows 10 trở lên: sử dụng IP máy chủ Windows (cổng mặc định của mạng ảo WSL) và đảm bảo máy chủ trên Windows liên kết với 0.0.0.0, không chỉ 127.0.0.1. Tường lửa Windows thường cũng cần một quy tắc cho cổng.

Để xem bảng đầy đủ (địa chỉ liên kết Ollama / LM Studio / vLLM / SGLang, một lớp quy tắc tường lửa, trình trợ giúp IP động, cách giải quyết tường lửa Hyper-V), hãy nhấp vào liên kết ở trên — đừng sao chép nó.

Trường hợp 2 - Có gì đó trên Windows (hoặc mạng LAN của bạn) nói chuyện với Hermes trong WSL

Đây là hướng ngược lại và ít được ghi lại ở nơi khác, nhưng đó là những gì bạn cần:

  • Sử dụng trang tổng quan web của Hermes từ trình duyệt Windows.
  • Sử dụng máy chủ API tương thích với OpenAI (được hermes Gateway hiển thị khi API_SERVER_ENABLED=true) từ một công cụ phía Windows. Xem trang tính năng Máy chủ API.
  • Thử nghiệm cổng nhắn tin (Telegram, Discord, v.v.) trong đó nền tảng ping URL webhook cục bộ — thông thường bạn sẽ sử dụng cloudflared/ngrok thay vì chuyển tiếp cổng thô.

Trường hợp con 2a: từ chính máy chủ Windows

Trên Windows 11 22H2+ đã bật chế độ phản chiếu, không có gì để làm. Một quy trình trong WSL liên kết với 0.0.0.0:8080 (hoặc thậm chí 127.0.0.1:8080) có thể truy cập được từ trình duyệt Windows tại http://localhost:8080. WSL tự động xuất bản liên kết trở lại máy chủ.

Trên chế độ NAT (Windows 10 / Windows 11 cũ hơn), "chuyển tiếp localhost" mặc định trong WSL2 thường sẽ chuyển tiếp 127.0.0.1 phía Linux liên kết với localhost của Windows, do đó, dịch vụ Hermes bắt đầu bằng --host 127.0.0.1 thường có thể truy cập được dưới dạng http://localhost:PORT từ Windows. Nếu không:

  • Liên kết rõ ràng với 0.0.0.0 bên trong WSL.
  • Tìm IP của WSL VM với ip -4 addr show eth0 | grep inet và nhấn nó từ Windows.

Trường hợp con 2b: từ một thiết bị khác trong mạng LAN của bạn (điện thoại, máy tính bảng, PC khác)

Đây là nỗi đau thực sự. Luồng lưu lượng Thiết bị LAN → Máy chủ Windows → WSL VM và bạn phải thiết lập cả hai bước nhảy:

  1. Liên kết trên tất cả các giao diện bên trong WSL. Quá trình lắng nghe trên 127.0.0.1 sẽ không bao giờ có thể truy cập được từ bên ngoài VM. Sử dụng 0.0.0.0.

  2. Chuyển tiếp cổng Windows → WSL VM. Ở chế độ phản chiếu, việc này diễn ra tự động. Trong chế độ NAT, bạn phải tự thực hiện việc đó trên mỗi cổng trong PowerShell quản trị:

    # Grab the WSL VM's current IP (it changes on every WSL restart under NAT)
    $wslIp = (wsl hostname -I).Trim().Split(' ')[0]

    # Forward Windows port 8080 → WSL:8080
    netsh interface portproxy add v4tov4 `
    listenaddress=0.0.0.0 listenport=8080 `
    connectaddress=$wslIp connectport=8080

Cho phép nó thông qua Tường lửa Windows

New-NetFirewallRule -DisplayName "Hermes WSL 8080" ` -Hướng vào -Giao thức TCP -LocalPort 8080 -Cho phép hành động


Xóa sau bằng `netsh giao diện portproxy delete v4tov4 listenaddress=0.0.0.0 listenport=8080`.

3. **Trỏ thiết bị LAN vào `http://<windows-lan-ip>:8080`.**

Vì IP WSL VM trôi đi trong mỗi lần khởi động lại ở chế độ NAT nên quy tắc một lần chỉ tồn tại cho đến lần `wsl --shutdown` tiếp theo. Đối với bất kỳ điều gì liên tục, hãy sử dụng chế độ được phản chiếu hoặc đặt bước proxy cổng trong tập lệnh chạy khi đăng nhập Windows.

Đối với webhooks từ các nhà cung cấp dịch vụ nhắn tin trên đám mây (Telegram `setWebhook`, sự kiện Slack, v.v.), đừng chống lại việc chuyển tiếp cổng — hãy sử dụng các đường hầm `cloudflared`. Xem [hướng dẫn về webhooks](/docs/user-guide/messaging/webhooks).

## Chạy dịch vụ Hermes lâu dài trên Windows

Hermes [Cổng công cụ](/docs/user-guide/features/tool-gateway) và máy chủ API là các quy trình tồn tại lâu dài. Trong WSL2, bạn có một số tùy chọn để duy trì chúng.

### Bên trong WSL với systemd (được khuyến nghị)

Nếu bạn đã bật systemd theo phần thiết lập ở trên, ``hermes Gateway` và máy chủ API sẽ hoạt động theo cách chúng hoạt động trên bất kỳ máy Linux nào. Sử dụng trình hướng dẫn thiết lập cổng:

```bash
hermes gateway setup

Nó sẽ đề nghị cài đặt một đơn vị người dùng systemd để cổng tự động xuất hiện khi WSL khởi động.

Làm cho WSL tự khởi động khi đăng nhập Windows

VM của WSL chỉ tồn tại khi có thứ gì đó đang sử dụng nó. Để giữ cho cổng của bạn có thể truy cập được mà không cần mở cửa sổ đầu cuối, hãy khởi động quy trình WSL khi đăng nhập Windows thông qua Trình lập lịch tác vụ:

  • Kích hoạt: Lúc đăng nhập (người dùng của bạn).
  • Hành động: Bắt đầu một chương trình
    • Chương trình: C:\Windows\System32\wsl.exe
    • Đối số: -d Ubuntu --exec /bin/sh -c "sleep infinity"

Điều đó giữ cho VM tồn tại để cổng do systemd quản lý vẫn chạy. Trên Windows 11, các luồng wsl --install --no-launch + tự động khởi động mới hơn cũng hoạt động; thủ thuật ngủ vô cực là phiên bản di động.

Truyền qua GPU (mô hình cục bộ)

WSL2 hỗ trợ NVIDIA GPU nguyên bản kể từ WSL kernel 5.10.43+ — cài đặt trình điều khiển NVIDIA tiêu chuẩn trên Windows (không** cài đặt trình điều khiển NVIDIA Linux bên trong WSL) và nvidia-smi bên trong WSL sẽ thấy GPU. Từ đó, các bộ công cụ CUDA, torch, vllm, sglangllama-server xây dựng dựa trên GPU thực như thường lệ.

Hỗ trợ AMD ROCm và Intel Arc bên trong WSL2 vẫn đang phát triển và nằm ngoài ma trận thử nghiệm của Hermes - nó có thể hoạt động với các trình điều khiển hiện tại nhưng chúng tôi không có công thức để đề xuất.

Nếu bạn đang chạy máy chủ mô hình cục bộ Windows gốc (Ollama cho Windows, LM Studio) đã sử dụng GPU của bạn thông qua trình điều khiển Windows thì bạn hoàn toàn không cần chuyển tiếp GPU WSL — chỉ cần làm theo Trường hợp 1 ở trên và truy cập nó qua mạng từ WSL.

Những cạm bẫy thường gặp

"Kết nối bị từ chối" với Ollama / LM Studio được lưu trữ trên Windows của tôi. Xem Mạng WSL2. Chín mươi phần trăm thời gian máy chủ bị ràng buộc với 127.0.0.1 và cần 0.0.0.0 (Ollama: OLLAMA_HOST=0.0.0.0), hoặc bạn đang thiếu quy tắc tường lửa.

Sự chậm chạp nghiêm trọng trên git status / hermes chat trong một repo. Có thể bạn đang làm việc với /mnt/c/.... Di chuyển repo sang ~/code/... (phía Linux). Thứ tự cường độ nhanh hơn.

trình thông dịch kém: /bin/bash^M trên tập lệnh. Kết thúc dòng CRLF từ trình soạn thảo Windows. dos2unix script.sh và đặt core.autocrlf input trong cấu hình git WSL của bạn.

Cảnh báo "Đường dẫn UNC không được hỗ trợ" từ các tệp nhị phân Windows được khởi chạy qua MCP. Cwd của Hermes nằm trong hệ thống tệp Linux và Windows cmd.exe không biết phải làm gì với nó. Khởi động Hermes từ /mnt/c/... cho phiên đó hoặc sử dụng trình bao bọc cd cho đường dẫn có thể truy cập của Windows trước khi gọi tệp thực thi Windows.

Đồng hồ trôi sau khi ngủ/ngủ đông. Đồng hồ của WSL2 có thể bị trễ vài phút sau khi máy chủ tiếp tục từ chế độ ngủ, điều này phá vỡ mọi thứ dựa trên chứng chỉ (API OAuth, HTTPS). Sửa theo yêu cầu:

sudo hwclock -s

Hoặc cài đặt ntpdate và chạy nó khi đăng nhập.

DNS ngừng hoạt động sau khi bật chế độ phản chiếu hoặc khi kết nối VPN. Chế độ phản chiếu proxy lưu trữ các cài đặt mạng vào WSL — nếu DNS của Windows hoạt động kém (đường hầm phân chia VPN, trình phân giải công ty), WSL sẽ kế thừa điều đó. Cách giải quyết: ghi đè resolv.conf theo cách thủ công (đặt generateResolvConf=false trong /etc/wsl.conf, sau đó viết /etc/resolv.conf của riêng bạn bằng 1.1.1.1 hoặc DNS của VPN của bạn).

không tìm thấy hermes sau khi chạy trình cài đặt. Trình cài đặt thêm ~/.local/bin vào PATH của shell của bạn thông qua ~/.bashrc. Bạn cần source ~/.bashrc (hoặc mở một thiết bị đầu cuối mới) để nó có hiệu lực trong phiên hiện tại.

Bộ bảo vệ Windows hoạt động chậm trên các tệp WSL. Bộ bảo vệ quét các tệp qua cầu 9P khi được truy cập từ Windows, điều này làm tăng độ chậm của việc truy cập xuyên ranh giới kiểu /mnt/c. Nếu bạn chỉ chạm vào các tệp WSL từ bên trong WSL thì điều này không thành vấn đề. Nếu bạn thường xuyên sử dụng các công cụ Windows để chống lại \\wsl$\..., hãy cân nhắc loại trừ đường dẫn phân phối WSL khỏi quá trình quét trong thời gian thực.

Hết đĩa. WSL2 lưu trữ đĩa VM của nó dưới dạng VHDX thưa thớt trong %LOCALAPPDATA%\Packages\.... Nó phát triển nhưng không tự động thu nhỏ khi bạn xóa tập tin. Để lấy lại dung lượng: wsl --shutdown, sau đó từ Quản trị viên PowerShell chạy Optimize-VHD -Path <path-to-ext4.vhdx> -Mode Full (yêu cầu các công cụ Hyper-V) — hoặc đường dẫn diskpart đơn giản hơn được ghi lại trên tài liệu WSL.

Đi đâu tiếp theo