Hướng dẫn về Windows (Bản địa) — Bản Beta sớm

Early BETA

Hỗ trợ Windows gốc là beta sớm. Nó cài đặt, chạy và vượt qua lint Windows-footgun của chúng tôi, nhưng nó chưa được thử nghiệm trên quy mô mà các đường dẫn Linux/macOS/WSL2 của chúng tôi có. Mong đợi các khía cạnh thô - đặc biệt là xung quanh việc xử lý quy trình con, các đường dẫn lạ và đầu ra bảng điều khiển không phải ASCII. Vui lòng file issues với các bước repro khi bạn chạm vào thứ gì đó. Nếu bạn muốn có một thiết lập đã được thử nghiệm trong trận chiến ngay hôm nay, hãy sử dụng Linux/macOS installer under WSL2.

Hermes chạy nguyên bản trên Windows 10 và Windows 11 — không WSL, không Cygwin, không Docker. Trang này cung cấp thông tin chi tiết: những gì hoạt động tự nhiên, chỉ dành cho WSL, những gì trình cài đặt thực sự làm và các nút dành riêng cho Windows mà bạn có thể cần chạm vào.

Nếu bạn chỉ muốn cài đặt, một lớp lót trên landing page hoặc Installation page là tất cả những gì bạn cần. Hãy quay lại đây khi có điều gì đó làm bạn ngạc nhiên.

Want WSL instead?

Nếu bạn thích môi trường POSIX thực (dành cho terminal nhúng của bảng điều khiển, ngữ nghĩa `fork

, trình xem tệp kiểu Linux, v.v.), hãy xem Windows (WSL2) Guide. Cả hai cùng tồn tại rõ ràng: dữ liệu gốc nằm trong

%LOCALAPPDATA%\Hermes

, dữ liệu WSL nằm trong

~/.Hermes

.

Cài đặt nhanh

Mở PowerShell (hoặc Windows Terminal) và chạy:

iex (irm https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.ps1)

`
``Không cần quyền quản trị. Trình cài đặt đi tới 

%LOCALAPPDATA%\Hermes\
` và thêm 
`Hermes
` vào **ĐƯỜNG DẪNNgười dùng** của bạn — mở một terminal mới sau khi quá trình cài đặt kết thúc.

**Tùy chọn trình cài đặt** (yêu cầu biểu mẫu scriptblock để truyền tham số):

`powershell
& ([scriptblock]::Create((irm https://raw.GitHubusercontent.com/NousResearch/Hermes-agent/main/scripts/install.ps1))) -NoVenv -SkipSetup -Branch main

`

| Tham số | Mặc định | Mục đích |
|---|---|---|
| 

`
-Branch
` | 
`main
` | Sao chép một nhánh cụ thể (hữu ích cho việc thử nghiệm PR) |
| 

-Commit
` | bỏ đặt | Ghim cài đặt vào một cam kết cụ thể SHA (ghi đè 

-Branch

) |
| 

-Tag
` | bỏ đặt | Ghim cài đặt vào thẻ git cụ thể (ví dụ: 
`v0.14.0

) |
| 

-NoVenv
` | tắt | Bỏ qua việc tạo venv (nâng cao - bạn tự quản lý Python) |
| 

-SkipSetup
` | tắt | Bỏ qua trình hướng dẫn 
`Hermes setup
` sau cài đặt |
| 

-HermesHome
` | 

%LOCALAPPDATA%\Hermes
` | Ghi đè thư mục dữ liệu |
| 

-InstallDir
` | 

%LOCALAPPDATA%\Hermes\Hermes-agent
` | Ghi đè vị trí mã |

Trình cài đặt tự động thử lại các lệnh tìm nạp git không ổn định và loại bỏ BOM khỏi mọi tải trọng 
`install.ps1
` đã tải xuống, do đó BOM UTF-8 được chọn trong quá trình truyền HTTP không còn phá vỡ biểu mẫu 

[scriptblock]::Create((irm ...))
` nữa.

### Trình cài đặt máy tính để bàn (thay thế)

Một trình cài đặt GUI mỏng cũng có sẵn — hữu ích nếu bạn muốn bấm đúp vào 

.exe
` hơn là mở PowerShell. Tải xuống Hermes Desktop, chạy trình cài đặt và trong lần khởi chạy đầu tiên, GUI sẽ gọi 
`install.ps1
` để cung cấp Python (thông qua 
`uv

), Node, PortableGit và phần còn lại của bootstrap phụ thuộc được mô tả bên dưới. Sau lần chạy đầu tiên, ứng dụng dành cho máy tính để bàn và 
`Hermes
` CLI được cài đặt PowerShell chia sẻ cùng một bản cài đặt 

%LOCALAPPDATA%\Hermes\Hermes-agent
` và thư mục dữ liệu 

%USERPROFILE%\.Hermes
` — tự do chuyển đổi giữa GUI và CLI.

Sử dụng trình cài đặt trên máy tính để bàn khi bạn muốn có trải nghiệm cài đặt Windows quen thuộc hoặc bạn đang giao Hermes cho một người không phải là nhà phát triển; sử dụng lớp lót PowerShell khi bạn đã ở trong một terminal.

### Khởi động phụ thuộc (
`dep_ensure

)

Trong lần khởi chạy đầu tiên (và theo yêu cầu khi phát hiện thấy một công cụ bị thiếu), Hermes chạy một trình khởi động Python nhỏ - 
`Hermes_CLI/dep_ensure.py

 - để kiểm tra và cài đặt một cách lười biếng các phần phụ thuộc không phải Python mà nó cần. Trên Windows, những cái có liên quan là:

| Phụ thuộc | Tại sao Hermes cần nó |
|---|---|
| **Git di động** | Cung cấp 
`bash.exe
` cho công cụ đầu cuối và 
`git
` cho bản sao trong phiên. Được cung cấp tại thời điểm cài đặt, không phải bởi 
`dep_ensure

. |
| **Node.js 22** | Cần thiết cho công cụ trình duyệt (
`agent-browser

), cầu nối web của TUI và cầu nối WhatsApp. |
| **ffmpeg** | Chuyển đổi định dạng âm thanh cho tin nhắn TTS/thoại. |
| **ripgrep** | Tìm kiếm tệp nhanh - quay lại 
`grep
` nếu không có. |
| **gói npm** |

agent-browser

, Playwright Chrome và mọi bộ công cụ Node deps đều được cài đặt một lần trong lần sử dụng công cụ trình duyệt đầu tiên. |Mỗi dep có một bài kiểm tra kiểu 
`shutil.which(...)

; nếu thiếu tệp nhị phân và quá trình chạy có tính tương tác, 
`dep_ensure
` sẽ đề xuất cài đặt nó (chuyển sang 
`scripts\install.ps1 -ensure ``<dep>
` để biết logic cài đặt thực tế). Các lần chạy không tương tác (gateway, cron, khởi chạy máy tính để bàn không đầu) bỏ qua lời nhắc và thay vào đó hiển thị lỗi 
`this feature needs ``<dep>
` rõ ràng.

## Trình cài đặt thực sự làm gì

Từ trên xuống dưới, theo thứ tự:
1. **Bootstraps 
`uv

** — Trình quản lý Python nhanh của Astral. Đã cài đặt vào 

%USERPROFILE%\.local\bin

.
2. **Cài đặt Python 3.11** qua 
`uv

. Không cần Python hiện có.
3. **Cài đặt Node.js 22** (winget nếu có, nếu không thì tarball Node di động được giải nén trong 

%LOCALAPPDATA%\Hermes\node

). Được sử dụng cho công cụ trình duyệt và cầu nối WhatsApp.
4. **Cài đặt Git di động** — nếu 
`git
` đã có trên PATH thì trình cài đặt sẽ sử dụng nó; nếu không, nó sẽ tải **PortableGit** đã được cắt bớt, độc lập (~45 MB, từ bản phát hành 
`git-for-Windows
` chính thức) xuống 

%LOCALAPPDATA%\Hermes\git

. Không có quản trị viên, không có sổ đăng ký trình cài đặt Windows, không can thiệp vào bất kỳ thứ gì khác trên hộp.
5. **Sao chép repo** thành 

%LOCALAPPDATA%\Hermes\Hermes-agent
` và tạo một virtualenv bên trong nó.
6. **
`uv pip install
` theo cấp độ** — thử 

.[all]
` trước, sau đó quay lại các nhóm nhỏ hơn dần dần (

[messaging,dashboard,ext]
` → 

[messaging]
` → 

.

) nếu 
`git+https
` xuất hiện trên GitHub có giới hạn tốc độ. Ngăn chặn chế độ lỗi "một mảnh khiến bạn phải cài đặt trần".
7. **Tự động cài đặt SDK nhắn tin** đã khóa 

.env
` — nếu có 
`Telegram_BOT_TOKEN
` / 
`Discord_BOT_TOKEN
` / 
`Slack_BOT_TOKEN
` / 
`Slack_APP_TOKEN
` / 
`WhatsApp_ENABLED

, hãy chạy 
`Python -m ensurepip --upgrade
` và các lệnh gọi 
`pip install
` được nhắm mục tiêu để SDK của mỗi nền tảng thực sự là có thể nhập khẩu.
8. **Đặt 
`Hermes_GIT_BASH_PATH

** thành 
`bash.exe
` đã phân giải để Hermes tìm thấy nó một cách xác định trong vỏ mới.
9. **Thêm 

%LOCALAPPDATA%\Hermes\bin
` vào PATH của người dùng** — hiển thị lệnh 
`Hermes
` sau khi bạn mở một terminal mới.
10. **Chạy 
`Hermes setup

** — trình hướng dẫn chạy lần đầu thông thường (kiểu máy, nhà cung cấp, bộ công cụ). Bỏ qua với 

-SkipSetup

.

:::tip[Skip provider hunting on Windows]
Windows gốc vẫn còn ở giai đoạn thử nghiệm đầu tiên và thiết lập khóa API cho mỗi công cụ (Firecrawl, FAL, Sử dụng trình duyệt, OpenAI TTS) là phần phức tạp nhất để có được một tác nhân hữu ích. Đăng ký [Nous Portal](/docs/user-guide/features/tool-gateway) bao gồm mô hình **và** tất cả các công cụ đó thông qua một lần đăng nhập OAuth. Sau khi trình cài đặt hoàn tất, hãy chạy 
`Hermes setup --portal
` để kết nối mọi thứ.
:::

## Ma trận tính năng

Mọi thứ ngoại trừ ngăn terminal nhúng của bảng điều khiển đều chạy tự nhiên trên Windows.

| Tính năng | Windows gốc | WSL2 |
|---|---|---|
| CLI (
`Hermes chat

, 
`Hermes setup

, 
`Hermes gateway

, …) | ✓ | ✓ |
| TUI tương tác (
`Hermes --TUI

) | ✓ | ✓ |
| Cổng nhắn tin (Telegram, Discord, Slack, WhatsApp, hơn 15 nền tảng) | ✓ | ✓ |
| Lập lịch Cron | ✓ | ✓ |
| Công cụ trình duyệt (Chromium qua Node) | ✓ | ✓ |
| Máy chủ MCP (stdio và HTTP) | ✓ | ✓ |
| OLlama địa phương / LM Studio / máy chủ Llama | ✓ | ✓ (thông qua mạng WSL) |
| Trang tổng quan web (phiên, công việc, số liệu, cấu hình) | ✓ | ✓ |
| Bảng điều khiển Khung terminal nhúng 

/chat
` | ✗ (cần POSIX PTY) | ✓ |
| Tự động khởi động khi đăng nhập | ✓ (nhiệm vụ) | ✓ (systemd) |

Tab 

/chat
` của bảng thông tin nhúng terminal thực thông qua POSIX PTY (
`ptyprocess

). Windows gốc không có nguyên thủy tương đương; 
`pywinpty

/Windows ConPTY của Python sẽ hoạt động nhưng là một triển khai riêng biệt - coi như công việc trong tương lai. **Phần còn lại của trang tổng quan hoạt động nguyên bản** — chỉ một tab đó hiển thị biểu ngữ "sử dụng WSL2 cho mục này".

## Cách Hermes chạy lệnh shell trên Windows

Công cụ đầu cuối của Hermes chạy lệnh thông qua **Git Bash**, chiến lược tương tự mà Claude Code sử dụng. Điều này giúp vượt qua khoảng cách POSIX-so với Windows mà không cần viết lại mọi công cụ.

Thứ tự giải quyết cho 
`bash.exe

:
1. Biến môi trường 
`Hermes_GIT_BASH_PATH
` nếu được đặt.
2. 

%LOCALAPPDATA%\Hermes\git\usr\bin\bash.exe
` (PortableGit do trình cài đặt quản lý).
3. 

%LOCALAPPDATA%\Hermes\git\bin\bash.exe
` (bố cục Git-for-Windows cũ hơn).
4. Cài đặt hệ thống Git-for-Windows (

%ProgramFiles%\Git\bin\bash.exe

, v.v.).
5. MSYS2, Cygwin hoặc bất kỳ 
`bash.exe
` nào trên PATH là phương án cuối cùng.

Trình cài đặt đặt 
`Hermes_GIT_BASH_PATH
` một cách rõ ràng để các phiên PowerShell mới không cần phải khám phá lại. Ghi đè nó nếu bạn muốn Hermes sử dụng một bash cụ thể - ví dụ: Git Bash hệ thống của bạn hoặc bash được lưu trữ trên WSL thông qua một liên kết tượng trưng.**Cạm bẫy:** Bố cục của MinGit khác với trình cài đặt Git-for-Windows đầy đủ — bash nằm trong 
`usr\bin\bash.exe

, không phải 
`bin\bash.exe

. Hermes kiểm tra cả hai. Nếu bạn đang giải nén zip MinGit theo cách thủ công, hãy đảm bảo bạn chọn biến thể **non-busybox** (
`MinGit-*-64-bit.zip

, không phải 
`MinGit-*-busybox*.zip

) — busybox xây dựng 
`ash
` thay vì 
``` bash
` và hầu hết các coreutils đều bị thiếu.

## Bảng điều khiển UTF-8 trên Windows

Stdio mặc định của Python trên Windows sử dụng trang mã hoạt động của bảng điều khiển (thường là cp1252 hoặc cp437). Biểu ngữ, danh sách lệnh gạch chéo, nguồn cấp công cụ, bảng Rich và mô tả kỹ năng của Hermes đều chứa Unicode. Nếu không có sự can thiệp, bất kỳ sự cố nào trong số đó sẽ xảy ra với 
`UnicodeEncodeError: 'charmap' codec can't encode character…

.

Bản sửa lỗi nằm trong 
`Hermes_CLI/stdio.py::configure_Windows_stdio()

, được gọi sớm ở mọi điểm vào (
`CLI.py::main

, 
`Hermes_CLI/main.py::main

, 
`gateway/run.py::main

). Nó:
1. Lật trang mã bảng điều khiển sang CP_UTF8 (65001) thông qua 
`kernel32.SetConsoleCP
` / 
`SetConsoleOutputCP

.

2. Định cấu hình lại 
`sys.stdout
` / 
`sys.stderr
` / 
`sys.stdin
` thành UTF-8 với 
`errors='replace'

.
3. Đặt 
`PythonIOENCODING=utf-8
` và 
`PythonUTF8=1
` (thông qua 
`setdefault

, vì vậy các giá trị người dùng rõ ràng sẽ giành chiến thắng) để các quy trình con Python con kế thừa UTF-8.
4. Đặt 
`EDITOR=notepad
` nếu cả 
`EDITOR
` và 
`VISUAL
` đều không được đặt (xem phần Trình chỉnh sửa bên dưới).

Bình thường. Không hoạt động trên máy không phải Windows.

**Chọn không tham gia:** 
`Hermes_DISABLE_Windows_UTF8=1
` trong môi trường quay trở lại đường dẫn stdio cp1252 cũ. Hữu ích cho việc chia đôi một lỗi mã hóa; không chắc là cài đặt đúng trong hoạt động bình thường.

## Trình chỉnh sửa (
`Ctrl-X Ctrl-E

, 

/edit

)

Trước #21561, nhấn 
`Ctrl-X Ctrl-E
` hoặc gõ 

/edit
` một cách im lặng không làm gì trên Windows. nhắc_toolkit có danh sách dự phòng tuyệt đối POSIX được mã hóa cứng (

/usr/bin/nano

, 

/usr/bin/pico

, 

/usr/bin/vi

, ...) không bao giờ giải quyết được trên Windows - ngay cả khi đã cài đặt Git cho Windows đầy đủ.

Miếng chêm stdio Windows của Hermes hiện đặt 
`EDITOR=notepad
` làm mặc định. Notepad đi kèm với mọi cài đặt Windows và hoạt động như một trình chỉnh sửa chặn - 
`subprocess.call(["notepad", file])
` chặn cho đến khi cửa sổ đóng lại.

**Phần ghi đè của người dùng vẫn thắng** (chúng được kiểm tra trước cài đặt mặc định):

| Biên tập viên | Lệnh PowerShell |
|---|---|
| Mã VS |

$env:EDITOR = "code --wait"
` |
| Ghi chú++ |

$env:EDITOR = "'C:\Program Files\Notepad++\notepad++.exe' -multiInst -nosession"
` |
| Neovim |

$env:EDITOR = "nVim"
` |
| xoắn ốc |

$env:EDITOR = "hx"
` |

Cờ 

--wait
` trên VS Code rất quan trọng — nếu không có cờ này, trình soạn thảo sẽ quay lại ngay lập tức và Hermes nhận lại bộ đệm trống.

Đặt nó vĩnh viễn trong hồ sơ PowerShell của bạn:

``` powershell

# In $PROFILE
$env:EDITOR = "code --wait"

`
``Hoặc dưới dạng biến môi trường Người dùng trong Cài đặt hệ thống để mọi shell mới sẽ chọn nó.

## 
`Ctrl+Enter
` cho dòng mới trong CLI

Windows Terminal chuyển 
`Ctrl+Enter
` dưới dạng chuỗi khóa chuyên dụng. Hermes liên kết nó với "chèn dòng mới" để bạn có thể soạn lời nhắc nhiều dòng trong CLI mà không quay lại 
`Esc

-then-
`Enter

. Hoạt động trong Windows Terminal, terminal tích hợp VS Code và bất kỳ máy chủ bảng điều khiển Windows hiện đại nào tôn trọng trình tự thoát VT.

Trên bảng điều khiển 
`cmd.exe
` cũ, 
`Ctrl+Enter
` chuyển thành 
`Enter
` đơn giản — thay vào đó hãy sử dụng 
`Esc Enter
` hoặc nâng cấp lên Windows Terminal (miễn phí và được cài đặt theo mặc định trên Windows 11).

## Chạy cổng khi đăng nhập Windows``Hermes gateway install
` trên Windows sử dụng **Tác vụ theo lịch** với dự phòng thư mục Khởi động — không cần quản trị viên.

### Cài đặt

``` powershell
Hermes gateway install

`
``Điều gì xảy ra dưới mui xe:
1. 
`schtasks /Create /SC ONLOGON /RL LIMITED /TN HermesGateway
` — đăng ký một tác vụ chạy khi bạn đăng nhập với các quyền tiêu chuẩn (không nâng cao). Không có lời nhắc UAC.

2. Nếu nhiệm vụ bị chặn bởi chính sách nhóm, hãy quay lại viết lối tắt 
`start /min cmd.exe /d /c <wrapper
` vào 

%APPDATA%\Microsoft\Windows\Start Menu\Programs\Startup

. Hiệu ứng tương tự, hơi thô hơn.
3. Tạo ra cổng **được tách ra qua 
`Pythonw.exe

** — không phải 
`Python.exe

. 
`Pythonw.exe
` không có bảng điều khiển kèm theo, giúp nó miễn nhiễm với các chương trình phát sóng 
`CTRL_C_EVENT
` từ các tiến trình anh em (một vấn đề thực sự thường giết chết cổng khi bạn Ctrl+C bất kỳ thứ gì trong cùng một nhóm tiến trình).

Cờ được sử dụng khi sinh sản: 
`DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP | CREATE_NO_WINDOW | CREATE_BREAKAWAY_FROM_JOB

.

### Quản lý

``` powershell
Hermes gateway status      # Merged view: schtasks + Startup folder + running PID
Hermes gateway start       # Starts the scheduled task now
Hermes gateway stop        # Graceful SIGTERM equivalent (TerminateProcess via psutil)
Hermes gateway restart
Hermes gateway uninstall   # Removes schtasks entry, Startup shortcut, pid file

`

`Hermes gateway status
` không có hiệu lực — hãy gọi nó hàng nghìn lần liên tiếp và nó sẽ không bao giờ vô tình giết chết cổng. (Trước PR #21561, điều đó đã âm thầm thực hiện, thông qua 
`os.kill(pid, 0)
` va chạm với 
`CTRL_C_EVENT
` ở cấp độ C - xem "nội bộ quản lý quy trình" bên dưới nếu bạn quan tâm đến câu chuyện.)

### Tại sao không phải là Dịch vụ Windows?

Các dịch vụ yêu cầu quyền quản trị viên để cài đặt và gắn vòng đời của cổng vào việc khởi động máy chứ không phải thông tin đăng nhập của người dùng. Người dùng Hermes điển hình muốn: đăng nhập → cổng khả dụng, đăng xuất → cổng biến mất. Nhiệm vụ theo lịch trình thực hiện chính xác điều đó mà không cần nâng cao. Nếu bạn thực sự muốn có một dịch vụ, hãy sử dụng 
`nssm
` hoặc 
`sc create
` theo cách thủ công — nhưng có thể bạn sẽ không làm như vậy.

## Bố cục dữ liệu

| Đường dẫn | Nội dung |
|---|---|
| 

%LOCALAPPDATA%\Hermes\Hermes-agent\
` | Kiểm tra Git + venv. An toàn với 
`Remove-Item -Recurse
` và cài đặt lại. |
| 

%LOCALAPPDATA%\Hermes\git\
` | PortableGit (chỉ khi trình cài đặt cung cấp nó). |
| 

%LOCALAPPDATA%\Hermes\node\
` | Node.js di động (chỉ khi trình cài đặt cung cấp nó). |
| 

%LOCALAPPDATA%\Hermes\bin\
` | Miếng chêm 
`Hermes.cmd

, được thêm vào PATH của người dùng. |
| 

%USERPROFILE%\.Hermes\
` | Cấu hình, xác thực, kỹ năng, phiên, nhật ký của bạn. **Sống sót sau khi cài đặt lại.** |

Việc phân chia là có chủ ý: 

%LOCALAPPDATA%\Hermes
` là cơ sở hạ tầng dùng một lần (bạn có thể loại bỏ nó và một lớp lót sẽ khôi phục nó). 

%USERPROFILE%\.Hermes
` là dữ liệu của bạn — cấu hình, bộ nhớ, kỹ năng, lịch sử phiên — và có hình dạng giống hệt với bản cài đặt Linux. Phản chiếu nó giữa các máy móc và Hermes của bạn sẽ di chuyển cùng bạn.

**Ghi đè 
`Hermes_HOME

:** đặt biến môi trường để trỏ đến một thư mục dữ liệu khác. Hoạt động tương tự như trên Linux.

## Công cụ trình duyệt

Công cụ trình duyệt sử dụng 
`agent-browser
` (trình trợ giúp Node) để điều khiển Chrome. Trên Windows:
- Trình cài đặt đặt 
`agent-browser
` trên PATH qua npm.

- 
`shutil.which("agent-browser", path=...)
` tự động chọn miếng chêm 

.cmd

 - 
`CreateProcessW
` không thể thực thi shebang không có phần mở rộng, vì vậy Hermes luôn phân giải sang trình bao bọc 

.CMD

. Đừng gọi tập lệnh shebang theo cách thủ công; luôn đi qua 

.cmd

.
- Playwright Chrome được cài đặt tự động trong lần chạy đầu tiên (
`npx playwright install chromium

). Nếu quá trình cài đặt không thành công, 
`Hermes doctor
` sẽ hiển thị gợi ý khắc phục.

## Chạy Hermes trên Windows — những lưu ý thực tế

### PATH sau khi cài đặt

Trình cài đặt thêm 

%LOCALAPPDATA%\Hermes\bin
` vào **ĐƯỜNG DẪNNgười dùng** của bạn thông qua 

[Environment]::SetEnvironmentVariable

. Các terminal hiện tại không nhận được điều này - hãy mở cửa sổ PowerShell mới (hoặc tab Windows Terminal) sau khi cài đặt. Đóng và mở lại, không dùng 

$env:PATH += …
` bằng tay trừ khi bạn biết mình đang làm gì.

Xác minh:

``` powershell
Get-Command Hermes        # should print C:\Users\<you\AppData\Local\Hermes\bin\Hermes.cmd
Hermes --version

`

### Biến môi trường

Hermes tôn trọng cả hai biến môi trường 

$env:X
` (phạm vi quy trình) và Người dùng (vĩnh viễn, được đặt trong Thuộc tính hệ thống → Biến môi trường). Đặt khóa API trong 

%USERPROFILE%\.Hermes\.env
` là đường dẫn thông thường - giống như Linux:

`
OpenRouter_API_KEY=sk-or-...
Telegram_BOT_TOKEN=...

`
``Đừng đặt bí mật vào các biến môi trường Người dùng trừ khi bạn đặc biệt muốn mọi quy trình Windows nhìn thấy chúng (đó không phải là điều bạn muốn).

### Các biến env dành riêng cho Windows

Những điều này chỉ ảnh hưởng đến cài đặt Windows gốc:

| Biến | Hiệu ứng |
|---|---|
| 
`Hermes_GIT_BASH_PATH
` | Ghi đè khám phá bash.exe. Trỏ vào bất kỳ bash nào - Git-for-Windows đầy đủ, bash WSL thông qua liên kết tượng trưng, ​​MSYS2, Cygwin. Trình cài đặt sẽ tự động thiết lập điều này. |
| 
`Hermes_DISABLE_Windows_UTF8
` | Đặt thành 
`1
` để tắt miếng chêm stdio UTF-8 và quay lại trang mã miền địa phương. Hữu ích cho việc chia đôi một lỗi mã hóa. |
| 
`EDITOR
` / 
`VISUAL
` | Trình chỉnh sửa của bạn cho 

/edit
` và 
`Ctrl-X Ctrl-E

. Hermes mặc định là 
`notepad
` nếu cả hai đều không được đặt. |

## Gỡ cài đặt

Từ PowerShell:

`powershell
Hermes uninstall

`
``Đó là đường dẫn rõ ràng - xóa mục nhập schtasks, lối tắt thư mục Khởi động, miếng chêm 
`Hermes.cmd

, xóa 

%LOCALAPPDATA%\Hermes\Hermes-agent\
` và cắt bớt PATH của người dùng. Nó chỉ để lại 

%USERPROFILE%\.Hermes\
` (cấu hình, xác thực, kỹ năng, phiên, nhật ký của bạn) trong trường hợp bạn cài đặt lại.

Để hạt nhân hóa mọi thứ:

`powershell
Hermes uninstall
Remove-Item -Recurse -Force "$env:USERPROFILE\.Hermes"
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\Hermes"

`
``Lệnh phụ 
`Hermes uninstall
` CLI cũng xử lý trường hợp mục nhập schtasks được đăng ký dưới một tên tác vụ khác (cài đặt cũ hơn) — nó tìm kiếm theo đường dẫn cài đặt thay vì theo tên tác vụ được mã hóa cứng.

## Nội bộ quản lý quy trình

Đây là tài liệu cơ bản - bỏ qua trừ khi bạn đang gỡ lỗi một điều kỳ lạ "nó đang tự giết chết".Trên Linux và macOS, thành ngữ POSIX 
`os.kill(pid, 0)
` là kiểm tra quyền không hoạt động: "PID này có hoạt động không và tôi có thể báo hiệu cho nó không?" Trên Windows, 
`os.kill
` của Python ánh xạ 
`sig=0
` tới 
`CTRL_C_EVENT
` — chúng xung đột ở giá trị số nguyên 0 — và định tuyến nó qua 
`GenerateConsoleCtrlEvent(0, pid)

, phát sóng Ctrl+C tới **toàn bộ nhóm quy trình bảng điều khiển** chứa PID mục tiêu. Đó là [bpo-14484](https://bugs.Python.org/issue14484), mở từ năm 2012. Nó sẽ không được sửa vì việc thay đổi nó sẽ phá vỡ các tập lệnh phụ thuộc vào hành vi hiện tại.

Hậu quả: bất kỳ đường dẫn mã nào có nội dung "kiểm tra xem PID này có còn hoạt động hay không" thông qua 
`os.kill(pid, 0)
` trên Windows đều âm thầm tiêu diệt mục tiêu. Hermes đã di chuyển mọi trang web như vậy (14 trên 11 tệp) sang 
`gateway.status._pid_exists()

, sử dụng 
`psutil.pid_exists()
` (sau đó sử dụng 
`OpenProcess + GetExitCodeProcess
` trên Windows - không có tín hiệu). Nếu bạn đang viết plugin hoặc bản vá, hãy sử dụng trực tiếp 
`psutil.pid_exists()
` hoặc 
`gateway.status._pid_exists()
` — không bao giờ sử dụng 
`os.kill(pid, 0)

.

scripts/check-Windows-footguns.py
` thực thi điều này trong CI: mọi cuộc gọi 
`os.kill(pid, 0)
` mới đều không vượt qua kiểm tra 
`Windows footguns (blocking)
` trừ khi dòng mang dấu 

`
# Windows-footgun: ok — <reason>

.

## Những cạm bẫy thường gặp`**
`Hermes: command not found
` ngay sau khi cài đặt.**
Mở một cửa sổ PowerShell mới. Trình cài đặt đã thêm 

%LOCALAPPDATA%\Hermes\bin
` vào PATH của người dùng, nhưng các shell hiện có cần phải được khởi động lại để tiếp tục. Trong thời gian chờ đợi, bạn có thể chạy 

& "$env:LOCALAPPDATA\Hermes\bin\Hermes.cmd"

.

**
`WinError 193: %1 is not a valid Win32 application
` khi chạy công cụ.**
Bạn đã thực hiện một lệnh gọi tập lệnh shebang bỏ qua miếng chêm 

.cmd

. Hermes giải quyết các lệnh thông qua 
`shutil.which(cmd, path=local_bin)
` nên PATHEXT chọn 

.CMD
` — thay vào đó, nếu bạn đang gọi công cụ thông qua đường dẫn được mã hóa cứng, hãy chuyển sang biến thể 

.cmd
` (ví dụ: 
`npx.cmd

, không phải 
`npx

).

**

[scriptblock]::Create(...)
` không thành công với 
`The assignment expression is not valid

.**
Bản tải xuống 
`install.ps1
` của bạn đã nhận được BOM UTF-8. Biểu mẫu 
`irm | iex
` tự động loại bỏ BOM; 

[scriptblock]::Create((irm ...))
` thì không. Chạy lại với biểu mẫu 
`irm | iex
` đơn giản hoặc tải xuống tập lệnh theo cách thủ công và lưu tập lệnh mà không cần BOM qua 

[IO.File]::WriteAllText($path, $text, (New-Object Text.UTF8Encoding $false))

.

**Cổng sẽ không tiếp tục chạy sau khi khởi động lại.**
Kiểm tra 
`Hermes gateway status

 - nó hợp nhất mục nhập schtasks, lối tắt thư mục Khởi động (nếu được sử dụng) và PID trực tiếp. Nếu schtasks đã được đăng ký nhưng không chạy, chính sách nhóm có thể đang chặn trình kích hoạt 
`ONLOGON

. Chạy 
`schtasks /Query /TN HermesGateway /V /FO LIST
` để xem lý do lỗi của tác vụ hoặc quay lại đường dẫn thư mục Khởi động bằng cách gỡ cài đặt và cài đặt lại với 
`Hermes_GATEWAY_FORCE_STARTUP=1

.

**

/edit
` vẫn không làm gì sau khi cài đặt 

$env:EDITOR

.**
Bạn chỉ đặt nó trong quy trình hiện tại; đóng và mở lại shell hoặc đặt nó ở phạm vi Người dùng trong Thuộc tính hệ thống → Biến môi trường. Xác minh bằng 
`echo $env:EDITOR
` trong cửa sổ PowerShell mới.

**Công cụ trình duyệt khởi chạy nhưng công cụ đã hết thời gian chờ.**
Chrome được cài đặt tự động trong lần chạy đầu tiên. Nếu quá trình cài đặt không thành công (GitHub bị giới hạn tốc độ, trục trặc CDN của Playwright), hãy chạy 
`Hermes doctor

 - nó sẽ hiển thị Crom bị thiếu và in lệnh 
`npx playwright install chromium
` chính xác để khắc phục.

**
`agent-browser
` không thành công với lỗi phiên bản Node kỳ lạ.**
Trình cài đặt cung cấp Nút 22 tại 

%LOCALAPPDATA%\Hermes\node
` nhưng PATH của bạn trước tiên có thể có hệ thống cũ hơn Nút 18. Di chuyển thư mục nút của Hermes sớm hơn trên PATH hoặc xóa cài đặt hệ thống nếu bạn không sử dụng Nút ở nơi khác.

**Các ký tự tiếng Trung / tiếng Nhật / tiếng Ả Rập hiển thị dưới dạng 

?
` trong CLI.**
Miếng chêm stdio UTF-8 không kích hoạt. Kiểm tra xem 
`Hermes_DISABLE_Windows_UTF8
` KHÔNG được đặt (
`Get-ChildItem env:Hermes_DISABLE_Windows_UTF8

). Nếu nó trống và bạn vẫn thấy 

?
` thì máy chủ bảng điều khiển (
`cmd.exe
` rất cũ) có thể không hỗ trợ UTF-8 chút nào — hãy chuyển sang Windows Terminal.

**Cổng không thể gửi ảnh Telegram — "
`BadRequest: payload contains invalid characters

".**
Điều này không liên quan đến Windows nhưng đôi khi xuất hiện đầu tiên ở đó. Thông thường, điều đó có nghĩa là đường dẫn tệp của bạn chứa dấu gạch chéo ngược không thoát trong phần nội dung JSON. Telegram sẽ nhận được các đường dẫn mà Hermes bình thường hóa chứ không phải các đường dẫn thô của Windows — nếu bạn thấy điều này bên trong một plugin tùy chỉnh, hãy đảm bảo rằng bạn đang đi qua đường dẫn do Hermes cung cấp chứ không phải 
`str(Path(...))
` từ đầu vào của người dùng.**Sự kỳ lạ về mã hóa "Hoạt động trên máy khác của tôi" sau 
`git pull

.**
Nếu bạn chỉnh sửa cấu hình Hermes hoặc một kỹ năng trên Windows bằng trình chỉnh sửa không phải UTF-8 (Notepad trên các phiên bản Windows cũ hơn, một số IME Trung Quốc), tệp có thể đã được lưu bằng BOM. Hermes chấp nhận 
`utf-8-sig
` trên hầu hết các lần đọc cấu hình, nhưng BOM bên trong vô hướng YAML được gấp lại (
`description: >

) âm thầm phá vỡ phân tích cú pháp YAML. Lưu lại tệp dưới dạng UTF-8 đơn giản không có BOM.

## Đi đâu tiếp theo
- **[Installation](../getting-started/installation.md)** — trang cài đặt đầy đủ, bao gồm Linux/macOS/WSL2/Termux.
- **[Windows (WSL2) Guide](./Windows-wsl-quickstart.md)** — nếu bạn muốn ngữ nghĩa POSIX hoặc khung terminal bảng điều khiển.
- **[CLI Reference](../reference/CLI-commands.md)** — mọi lệnh phụ 
`Hermes

.
- **[FAQ](../reference/faq.md)** — các câu hỏi phổ biến không dành riêng cho Windows.
- **[Messaging Gateway](./messaging/index.md)** — chạy Telegram/Discord/Slack trên Windows.