INTERACTIVE
從 WSL 安裝 Hermes Agent 到控制 Windows Chrome：完整實戰教學
AI 工具教學2026年4月13日

從 WSL 安裝 Hermes Agent 到控制 Windows Chrome：完整實戰教學

Lucus Kuo

·

AI Agent 整合實作者

2026/04/13

從 WSL 安裝 Hermes Agent 到控制 Windows Chrome

這篇教學整理一套完整流程：從 Windows 啟用 WSL、建立 HermesAgent 環境、安裝 Hermes Agent、設定 Google Gemma 4 31B、綁定 Telegram Gateway，到最後讓 Hermes 透過 Playwright CLI 控制 Windows 端的 Chrome 瀏覽器。

本文按照實際排查流程撰寫，包含一開始遇到的 502 Bad Gateway、WSL 網路模式、Chrome Debug Port、Playwright CLI、Telegram session 過大導致 Gemini API 500 等問題。

一、整體架構

完成後的架構如下：

Telegram 使用者
  ↓
Hermes Telegram Gateway
  ↓
Hermes Agent in WSL: HermesAgent
  ↓
playwright-cli
  ↓
Chrome DevTools Protocol, CDP
  ↓
Windows Chrome debug profile

重點是：Hermes 本體跑在 WSL 裡，但它可以透過 CDP endpoint 控制 Windows 裡開啟的 Chrome。

二、安裝與啟用 WSL

先用系統管理員 PowerShell 安裝 WSL：

wsl --install

如果你要指定 Ubuntu：

wsl --install -d Ubuntu

安裝完成後重開機，確認 WSL 可用：

wsl --status
wsl --list --verbose

本文假設你的 WSL distro 名稱是 HermesAgent。之後指令會使用：

wsl -d HermesAgent

如果你的 distro 名稱不同，例如 Ubuntu，請把 HermesAgent 換成自己的名稱。

三、啟用 WSL Mirrored Networking

一開始我們使用 WSL 的 gateway IP，例如 172.22.32.1，但 Hermes 透過該位址連 Chrome debug port 時遇到 502 Bad Gateway。後來確認比較穩定的做法是開啟 WSL mirrored networking，讓 WSL 可以直接透過 127.0.0.1 連到 Windows localhost。

在 Windows 使用者資料夾建立或編輯：

%USERPROFILE%\.wslconfig

加入：

[wsl2]
networkingMode=mirrored

儲存後，在 PowerShell 執行：

wsl --shutdown

重新開啟 WSL 後，Windows 與 WSL 之間的 localhost 行為會更接近同一台機器。

四、準備 WSL 環境

進入 HermesAgent：

wsl -d HermesAgent

更新套件：

sudo apt update
sudo apt upgrade -y

安裝常用工具：

sudo apt install -y git curl wget unzip ca-certificates python3 python3-pip python3-venv ripgrep

確認基本工具：

git --version
python3 --version
curl --version
rg --version

五、安裝 Hermes Agent

將 Hermes Agent 放在 WSL 的 home 目錄下。本文實際使用的位置是：

/root/.hermes/hermes-agent

可使用 GitHub 專案：

git clone https://github.com/nousresearch/hermes-agent ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent

依照專案需求安裝 Python 套件。若專案提供安裝腳本，優先使用官方腳本；若使用 pip editable install，可用：

python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

確認 Hermes 指令：

hermes --help
hermes status

如果 hermes 指令不在 PATH，請把 Hermes bin 路徑加入 PATH。本文後續使用：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"

六、設定 Gemma 4 31B 模型

本文使用 Google Gemini/OpenAI-compatible endpoint 串接 Gemma 4 31B。Hermes 的設定檔位於：

/root/.hermes/config.yaml

模型設定範例：

model:
  default: gemma-4-31b-it
  provider: gemini
  base_url: https://generativelanguage.googleapis.com/v1beta/openai

API key 不建議直接寫進文章或程式碼。請放在：

/root/.hermes/.env

範例：

GOOGLE_API_KEY=你的_API_KEY
GEMINI_API_KEY=你的_API_KEY
GEMINI_BASE_URL=https://generativelanguage.googleapis.com/v1beta/openai

檔案權限建議：

chmod 600 /root/.hermes/.env

七、設定 Telegram Gateway

Hermes 可透過 Telegram Gateway 接收訊息。設定環境變數：

TELEGRAM_BOT_TOKEN=你的_TELEGRAM_BOT_TOKEN
TELEGRAM_ALLOWED_USERS=你的_TELEGRAM_USER_ID
TELEGRAM_HOME_CHANNEL=你的_TELEGRAM_USER_ID

啟動 Gateway：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
hermes gateway run

WSL 中若要背景執行：

mkdir -p /root/.hermes/logs
nohup hermes gateway run > /root/.hermes/logs/gateway.log 2>&1 &

確認狀態：

hermes gateway status
tail -80 /root/.hermes/logs/gateway.log

八、安裝 Microsoft Playwright CLI

接著安裝 Microsoft 的 playwright-cli。這是 Hermes 控制瀏覽器的關鍵工具。

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
npm install -g @playwright/cli@latest

建立捷徑：

ln -sf "$HOME/.hermes/node/bin/playwright-cli" "$HOME/.local/bin/playwright-cli"

確認版本：

command -v playwright-cli
playwright-cli --version

本文實測版本：

@playwright/cli 0.1.7

九、安裝 Playwright CLI Skill 給 Hermes

下載 Microsoft playwright-cli 原始碼：

cd /tmp
git clone https://github.com/microsoft/playwright-cli playwright-cli-src

複製官方 skill 到 Hermes skills 目錄：

mkdir -p "$HOME/.hermes/skills/browser"
cp -a /tmp/playwright-cli-src/skills/playwright-cli "$HOME/.hermes/skills/browser/playwright-cli"

Hermes 載入時使用資料夾 ID：

hermes -s playwright-cli chat

注意：Hermes 顯示名稱可能是 hermes-playwright-cli，但實際載入 skill 時應使用資料夾名稱 playwright-cli。

十、安裝 Chrome 給 Playwright CLI 測試

一開始 smoke test 可能會出現：

Error: Chromium distribution 'chrome' is not found at /opt/google/chrome/chrome

可執行：

npx playwright install chrome

確認：

google-chrome --version

本文實測：

Google Chrome 147.0.7727.55

十一、先測 WSL 內建 Chrome

在 WSL 內先測 playwright-cli 本身是否正常：

playwright-cli -s=hermes-smoke open https://example.com
playwright-cli -s=hermes-smoke snapshot
playwright-cli -s=hermes-smoke eval "document.title"
playwright-cli -s=hermes-smoke screenshot --filename=.playwright-cli/hermes-playwright-cli-smoke.png
playwright-cli -s=hermes-smoke close

成功時 document.title 會回傳：

"Example Domain"

十二、建立 Windows Chrome Debug 啟動 BAT

為了讓 Hermes 控制 Windows Chrome，而且記住登入狀態，不建議使用 Windows 主 Chrome profile。應建立 Hermes 專用 Chrome profile。

建立檔案：

C:\Users\KHUser\Desktop\start_chrome_local_debug.bat

內容如下：

@echo off
setlocal

set "PORT=9223"
set "PROFILE=%LOCALAPPDATA%\HermesAgent\ChromeProfile"

set "CHROME_PATH=%ProgramFiles%\Google\Chrome\Application\chrome.exe"
if not exist "%CHROME_PATH%" set "CHROME_PATH=%ProgramFiles(x86)%\Google\Chrome\Application\chrome.exe"
if not exist "%CHROME_PATH%" set "CHROME_PATH=%LOCALAPPDATA%\Google\Chrome\Application\chrome.exe"

if not exist "%CHROME_PATH%" (
  echo [ERROR] Chrome not found.
  pause
  exit /b 1
)

echo [INFO] Starting local-only Chrome debug profile.
echo [INFO] Port: %PORT%
echo [INFO] Profile: %PROFILE%

if not exist "%PROFILE%" mkdir "%PROFILE%"

start "" "%CHROME_PATH%" ^
  --remote-debugging-port=%PORT% ^
  --remote-debugging-address=127.0.0.1 ^
  --user-data-dir="%PROFILE%" ^
  --no-first-run ^
  --no-default-browser-check ^
  about:blank

echo.
echo [OK] Chrome debug mode is starting.
echo [CHECK] Open this URL to verify:
echo http://127.0.0.1:%PORT%/json/version
echo.
pause

這支 bat 的重點是：

--remote-debugging-port=9223
--remote-debugging-address=127.0.0.1
--user-data-dir=%LOCALAPPDATA%\HermesAgent\ChromeProfile

使用固定 profile 後，你在這個 Chrome 分身登入 Google、YouTube 或其他網站，下次再執行同一支 bat，登入狀態會保留。

十三、驗證 Windows Chrome Debug Port

執行 bat 後，在 Windows 瀏覽器打開：

http://127.0.0.1:9223/json/version

成功時會看到類似：

{
  "Browser": "Chrome/147.0.7727.55",
  "Protocol-Version": "1.3",
  "webSocketDebuggerUrl": "ws://127.0.0.1:9223/devtools/browser/..."
}

如果這裡沒有 JSON，Hermes 不可能控制 Chrome。請先確認 bat 有成功打開 Chrome。

十四、讓 WSL Hermes 連 Windows Chrome

在 WSL 測試：

wsl -d HermesAgent
curl -fsS http://127.0.0.1:9223/json/version

成功後設定 Playwright endpoint：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
export PLAYWRIGHT_MCP_CDP_ENDPOINT="http://127.0.0.1:9223"

測試開啟 YouTube：

playwright-cli -s=winchrome open https://www.youtube.com
playwright-cli -s=winchrome eval "document.title"

成功時會回傳：

"YouTube"

十五、把 CDP endpoint 寫進 Hermes 環境

為了讓 Telegram Gateway 也吃到這個設定，將 endpoint 寫進：

/root/.hermes/.env

加入：

PLAYWRIGHT_MCP_CDP_ENDPOINT=http://127.0.0.1:9223

確認：

grep -n '^PLAYWRIGHT_MCP_CDP_ENDPOINT=' /root/.hermes/.env

十六、重啟 Telegram Gateway

修改 .env 後，重啟 gateway：

export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
hermes gateway stop
pkill -f "hermes gateway run" || true
PLAYWRIGHT_MCP_CDP_ENDPOINT="http://127.0.0.1:9223" nohup hermes gateway run > /root/.hermes/logs/gateway.log 2>&1 &

確認：

hermes gateway status
tail -60 /root/.hermes/logs/gateway.log

十七、Telegram 測試語句

在 Telegram 對 Hermes 傳：

用 playwright 打開 YouTube，回報目前頁面標題。使用 127.0.0.1:9223。

如果一切正常，Hermes 會透過 playwright-cli 控制 Windows Chrome，並讀取頁面標題。

十八、常見錯誤：502 Bad Gateway

我們一開始使用：

http://172.22.32.1:9223

結果遇到 502 Bad Gateway。這通常表示請求打到某個 gateway 或 proxy，但沒有正確轉到 Chrome。

後來修正方式是啟用 WSL mirrored networking，並改用：

http://127.0.0.1:9223

結論：如果已啟用 mirrored networking，不要再用 172.22.32.1。

十九、常見錯誤：ECONNREFUSED

如果出現 ECONNREFUSED，通常代表 Chrome debug port 沒開。

請重新執行：

C:\Users\KHUser\Desktop\start_chrome_local_debug.bat

再測：

curl http://127.0.0.1:9223/json/version

二十、常見錯誤：Gemini API HTTP 500

後續 Telegram 使用過程中遇到：

API call failed after 3 retries: HTTP 500
Internal error encountered.

檢查 Hermes log 後發現：

provider=gemini
model=gemma-4-31b-it
tokens=~97,400

這代表 Telegram 對話和工具輸出累積太大，Gemma 4 31B 在接近上下文極限時，Google API 可能回 500。

處理方式是開新 session，並調整 Hermes 壓縮設定。

二十一、調整 Hermes 壓縮設定

編輯：

/root/.hermes/config.yaml

將 compression 調整為：

compression:
  enabled: true
  threshold: 0.35
  target_ratio: 0.12
  protect_last_n: 6
  summary_model: google/gemini-3-flash-preview

原本 protect_last_n 如果太大，例如 20，Telegram 工具任務會保留太多最近內容，長期使用容易堆到非常大的上下文。

二十二、清除 Telegram Active Session Mapping

如果 Telegram 對話已經太大，可以移除 active session mapping，讓下一則 Telegram 訊息開新 session。

session mapping 位於：

/root/.hermes/sessions/sessions.json

建議先備份：

cp /root/.hermes/sessions/sessions.json /root/.hermes/sessions/sessions.before-reset.json

然後移除對應 key，例如：

agent:main:telegram:dm:你的_TELEGRAM_USER_ID

清掉 mapping 不等於刪除所有歷史紀錄，只是讓 gateway 下一次建立新 active session。

二十三、最終成功測試

最終可用測試流程：

wsl -d HermesAgent
export PATH="$HOME/.local/bin:$HOME/.hermes/node/bin:$PATH"
export PLAYWRIGHT_MCP_CDP_ENDPOINT="http://127.0.0.1:9223"

curl -fsS http://127.0.0.1:9223/json/version
playwright-cli -s=winchrome open https://www.youtube.com
playwright-cli -s=winchrome eval "document.title"

成功結果：

"YouTube"

二十四、日常使用流程

之後日常使用只需要三件事：

1. 開啟 Windows Chrome Debug Profile

C:\Users\KHUser\Desktop\start_chrome_local_debug.bat

2. 確認 Hermes Gateway 正在跑

wsl -d HermesAgent
hermes gateway status

3. 在 Telegram 下指令

用 playwright 控制 Windows Chrome，打開 YouTube 並回報頁面標題。使用 127.0.0.1:9223。

二十五、安全建議

不要把 Chrome debug port 綁到 0.0.0.0，除非你非常清楚防火牆與網路暴露風險。

建議使用：

--remote-debugging-address=127.0.0.1

也不要直接使用平常主 Chrome 的 user data profile，避免 Hermes 影響你的日常瀏覽器。建議使用獨立 profile：

%LOCALAPPDATA%\HermesAgent\ChromeProfile

結語

這套流程完成後，Hermes 就能從 Telegram 接收任務，透過 WSL 裡的 playwright-cli 控制 Windows Chrome。最關鍵的三個設定是 WSL mirrored networking、Chrome debug port 9223、以及 PLAYWRIGHT_MCP_CDP_ENDPOINT=http://127.0.0.1:9223。

如果遇到 502，優先檢查是否仍在使用舊的 172.22.32.1；如果遇到 Gemini HTTP 500，優先檢查 Telegram session 是否過大，並切新 session 或調整壓縮設定。

FAQ

常見問題

Hermes 可以控制 Windows Chrome 嗎？+
可以。Hermes 跑在 WSL 裡，透過 playwright-cli 連到 Windows Chrome 的 CDP endpoint，例如 http://127.0.0.1:9223，就能控制 Windows Chrome 裡的網頁。
為什麼不建議使用 172.22.32.1:9223？+
實測中 172.22.32.1 容易遇到 502 Bad Gateway。啟用 WSL mirrored networking 後，應改用 http://127.0.0.1:9223。
Chrome 登入狀態會保留嗎？+
會，只要 bat 使用固定的 --user-data-dir，例如 %LOCALAPPDATA%\HermesAgent\ChromeProfile，登入狀態就會保留。
Gemini API HTTP 500 是 Chrome 壞掉嗎？+
通常不是。若 Hermes log 顯示 tokens 接近十萬，代表 Telegram session 太大，Gemma 4 31B 可能在大型上下文下回 500。可切新 session 並調整 compression 設定。

Next Step

如果這篇內容剛好對到你現在的問題，下一步就不要只停在閱讀。

你可以直接把目前的流程、卡點或想導入的方向告訴我們；如果你還在評估，也可以先去看〈 英特 Ai 〉或其他正式解決方案，確認哪一條路最適合現在的公司狀況。

延伸閱讀

NVIDIA 免費模型清單怎麼做？從 API 串接到自動刷新機制的完整教學
AI 工具教學
2026/04/30

NVIDIA 免費模型清單怎麼做？從 API 串接到自動刷新機制的完整教學

本文以網站後端工程角度，完整教學如何設計 NVIDIA 免費模型清單的自動刷新機制，涵蓋 API 串接、raw snapshot、normalized catalog、upsert、missing tracking、public read API、admin refresh API 與背景排程，幫助團隊把模型清單做成真正可維護的同步服務。

Read Article
NVIDIA Free Endpoint 模型全解析：功能、用途、適用情境與實戰評價
AI 工具教學
2026/04/22

NVIDIA Free Endpoint 模型全解析：功能、用途、適用情境與實戰評價

本文整理目前 NVIDIA Build 平台上最值得關注的 Free Endpoint 模型，從通用 LLM、coding 與 agent 模型、多模態模型，到 embedding、rerank、安全與語音模型，逐一分析其功能、用途、適用情境與主觀評價，幫助開發者用系統化視角完成模型選型。

Read Article
NVIDIA 免費 AI API 上手：GLM、MiniMax、Kimi 與 DeepSeek 串接實戰
AI 工具教學
2026/04/21

NVIDIA 免費 AI API 上手：GLM、MiniMax、Kimi 與 DeepSeek 串接實戰

本文整理 NVIDIA 免費 AI API 的實際使用方式，先用最短篇幅說明如何申請 API Key，再列出目前可直接測試的免費模型，並提供 GLM、MiniMax、Kimi 與 DeepSeek 的實作串接範例，幫助團隊更有效率地完成模型選型與工作流驗證。

Read Article
Line
1