WSL 彙整

Q: WSL 專案檔案應該放哪裡？

如果主要在 Linux 命令列工作，專案最好放在 WSL 的 /home 目錄，不要放在 /mnt/c，這樣 I/O 效能和權限行為通常比較穩。

Windows 跑 AI Agent 為什麼要用 WSL？完整環境整理

by Rain Chu | 7 月 15, 2026 | Agent, AI

Windows 跑 AI Agent，真正的關鍵不是把所有工具硬裝進 PowerShell，而是把 Windows 當成桌面和硬體入口，把 Linux 工具鏈交給 WSL 2，這樣做的好處很直接：Python、Node、Docker、Git、CUDA、各種開源 Agent 工具，都會更接近它們原本被設計和測試的環境。

我的判斷是，如果你在 Windows 上做 Codex、Claude Code、Cursor、OpenCode、本地模型或自動化 Agent，WSL 2 幾乎是標準底座，不是因為 Windows 不行，而是 AI Agent 這一波工具鏈大多先從 Linux 生態長出來。

先講結論

Windows 11 或新版 Windows 10 可以用 `wsl –install` 安裝 WSL，預設會走 WSL 2。
AI Agent 專案建議放在 WSL 的 `/home` 目錄，不要長期放在 `/mnt/c`。
VS Code 建議用 Remote WSL，讓編輯器在 Windows，工具鏈在 Linux。
Docker Desktop 可以啟用 WSL 2 backend，適合需要容器化 Agent 服務的人。
NVIDIA GPU 可以在 WSL 2 裡用 CUDA，但重點是安裝 Windows 端驅動，不要在 WSL 裡裝 Linux 顯示驅動。

為什麼 Windows 跑 AI Agent 需要 WSL

Microsoft 對 WSL 的定位很清楚：讓開發者可以在 Windows 上直接使用 Linux distribution、Linux 應用、工具和 Bash 命令列，而且不需要傳統虛擬機或雙系統。對 AI Agent 來說，這剛好補上 Windows 和開源工具鏈之間的落差。

很多 Agent 專案會同時碰到 Python、Node、Playwright、ffmpeg、SQLite、Docker、Git hooks、shell scripts。這些東西在 Linux 裡比較自然，在 Windows 原生環境則容易遇到路徑、權限、編碼、套件編譯和命令差異。

如果你正在使用 Codex 與 ChatGPT Work，或想把 OpenWork 和 OpenCode 桌面工作台跑穩，WSL 可以讓 Windows 變成比較舒服的 Agent 開發機，而不是一直在修環境。

第一步：安裝與確認 WSL 2

Microsoft 官方文件建議，在符合版本的 Windows 上，可以用系統管理員 PowerShell 執行：

wsl --install

安裝後可以用下面指令查看 distribution 和 WSL 版本：

wsl.exe --list --verbose

如果你有多個 Linux distribution，可以用 `wsl.exe –set-default` 設定預設環境。對大多數 AI Agent 使用者，我會建議先用 Ubuntu，原因不是它最酷，而是教學、套件、問題排查和相容性資料最多。

第二步：專案不要放在 /mnt/c

這是最常見的坑。Microsoft 文件明確建議，如果你主要在 Linux 命令列裡工作，專案檔案應該放在 WSL 檔案系統內，例如 `/home/你的帳號/projects`。不要把主要專案放在 `/mnt/c/Users/…` 下面長期開發。

原因是跨 Windows 和 Linux 檔案系統會影響效能，也可能讓檔案權限、大小寫、watcher、node_modules、Python venv 出現奇怪問題。AI Agent 工作流常常有大量小檔案、快取、套件安裝和檔案監看，這種差異會被放大。

簡單說：Linux 工具鏈處理的專案，就放 Linux 檔案系統，需要從 Windows 檔案總管打開時，可以在 WSL 目錄下執行：

explorer.exe .

第三步：VS Code 用 Remote WSL

不要把 VS Code 直接開在 Windows 路徑裡，再讓終端機切來切去。比較乾淨的方式是安裝 VS Code 的 WSL 支援，從 WSL 裡開專案：

code .

這樣 UI 還是在 Windows，但 extension host、terminal、語言服務和套件環境會跑在 WSL。對 Python、Node、Rust、Go、Docker compose、Playwright 這類 Agent 常用工具，這種模式會少很多不必要的摩擦。

第四步：Docker 交給 WSL 2 backend

很多 AI Agent 工具會需要資料庫、瀏覽器服務、向量資料庫、Redis、sandbox 或 API mock。這時候 Docker 是很自然的選擇。Docker Desktop 支援 WSL 2 backend，可以讓 Windows 上的容器工作流更接近 Linux。

我會把它看成「可複製環境」的保險。今天你在 Windows WSL 跑得起來，明天移到 Linux server 或雲端 VM，踩坑會少很多。這和我之前整理 Docker 跟 command line 一樣使用的方向一致，容器不是炫技，而是讓環境可重現。

第五步：GPU 和 CUDA 要小心裝

如果你要跑本地模型、推理框架或 CUDA 工具，WSL 2 可以吃到 NVIDIA GPU，NVIDIA 官方文件的關鍵提醒是：安裝 Windows 端 NVIDIA 驅動後，CUDA 驅動會映射進 WSL，不要在 WSL 裡安裝 Linux 顯示驅動。

這點很重要。很多人一進 Ubuntu 就照 Linux 教學裝完整 NVIDIA driver，反而把環境弄壞，WSL 裡需要的是相容的 CUDA toolkit 和使用者空間工具，不是另一套 Linux 顯示驅動。

如果你在 Windows 上遠端連自己的 AI server，可以參考我之前寫的 Windows PowerShell 連接 Ollama AI Server。如果是要本機推理，則更需要把 WSL、GPU driver、CUDA 和模型框架的版本關係先整理好。

Windows 跑 AI Agent 的 WSL 檢查表

階段	建議做法	原因
安裝	使用 wsl –install 並確認 WSL 2	取得 Linux 工具鏈與較完整相容性
檔案	專案放在 /home 內	避免 /mnt/c 跨檔案系統拖慢 I/O
開發	VS Code Remote WSL	讓編輯器在 Windows，工具鏈在 Linux
容器	Docker Desktop WSL 2 backend	讓 Agent 工作流更容易複製
GPU	Windows 驅動 + WSL CUDA	避免在 WSL 內安裝 Linux 顯示驅動

我會怎麼配置一台 Windows AI Agent 機

如果是我自己整理一台 Windows AI Agent 工作機，我會照這個順序來：

Windows Terminal 裝好，PowerShell 和 Ubuntu 分開使用。
WSL 2 裝 Ubuntu，專案目錄固定放在 `/home`。
VS Code 用 Remote WSL 開專案。
Python 用 uv 或 venv 管，Node 用 nvm 或 corepack 管。
需要服務就用 Docker compose，不把資料庫亂裝在 Windows 裡。
需要本地模型時，先確認 NVIDIA Windows driver、WSL kernel、CUDA toolkit 和推理框架版本。

如果你的目標是本地大模型推理框架，WSL 可以讓 vLLM、SGLang、llama.cpp、Ollama 周邊工具更接近 Linux 使用方式。如果你的目標是 Agent 開發，WSL 則可以讓 shell、瀏覽器自動化、檔案操作和套件安裝更穩。

我的判斷

Windows 不需要變成 Mac，也不需要硬裝成 Linux。最好的方式是讓 Windows 做它擅長的事：桌面、驅動、硬體管理、遊戲和日常軟體。讓 WSL 做它擅長的事：Linux 工具鏈、開源套件、容器、AI Agent 環境。

真正穩的 Windows AI Agent 工作流，不是把所有東西混在同一個地方，而是把邊界分清楚。Windows 管外層，WSL 管開發環境，Docker 管可重現服務，GPU driver 留在 Windows，專案檔案留在 Linux 檔案系統。這樣才比較不會每次換工具就重修一次環境。

延伸資源

FAQ

Windows 跑 AI Agent 一定要用 WSL 嗎？

不一定，但如果工具鏈偏 Linux、需要 Python、Node、Docker、CUDA 或多個開源套件，WSL 2 通常比純 Windows 環境穩定。

WSL 專案檔案應該放哪裡？

如果主要在 Linux 命令列工作，專案最好放在 WSL 的 `/home` 目錄，不要放在 `/mnt/c`，這樣 I/O 效能和權限行為通常比較穩。

VS Code 可以直接編輯 WSL 專案嗎？

可以。建議使用 VS Code Remote WSL，讓編輯器留在 Windows，語言工具鏈、終端機和套件環境跑在 WSL 裡。

WSL 可以用 NVIDIA GPU 嗎？

可以，但要用支援 WSL 的 Windows NVIDIA 驅動。重點是不要在 WSL 裡安裝 Linux 顯示驅動，CUDA 驅動會從 Windows 端映射進 WSL。

Docker Desktop 和 WSL 2 有什麼關係？

Docker Desktop 可以使用 WSL 2 backend，讓 Windows 上的容器工作流更接近 Linux 開發環境，適合需要複製 AI Agent 服務環境的人。

手把手教學安裝 anything-llm (不使用 docker)

by Rain Chu | 5 月 13, 2024 | AI, Chat, Linux, NodeJS, React, Ubuntu, ViteJS, 程式

AnythingLLM是一款全功能的應用程序，支持使用商業或開源的大語言模型（LLM）和向量數據庫建構私有ChatGPT。用戶可以在本地或遠端運行該系統，並利用已有文檔進行智能對話。此應用將文檔分類至稱為工作區的容器中，確保不同工作區間的資料隔離，保持清晰的上下文管理。

特點：多用戶支持、權限管理、內置智能代理（可執行網頁瀏覽、代碼運行等功能）、可嵌入到網站的聊天窗口、多種文檔格式支持、向量數據庫的簡易管理界面、聊天和查詢兩種對話模式、引用文檔內容的展示，以及完善的API支持客戶端定制整合。此外，該系統支持100%雲端部署，Docker部署，且在處理超大文檔時效率高，成本低。

安裝 Anything llm

注意，以下要用 linux 平台安裝，windows 用戶可以用 WSL，推薦用 Ubuntu OS

在自己的 home 目錄下，到 GitHub 中下載原始碼

git clone https://github.com/Mintplex-Labs/anything-llm.git

利用 yarn 作設定資源

cd anything-llm
yarn setup

把環境變數建立起來，後端主機是 NodeJS express

cp server/.env.example server/.env
nano server/.env

密文需要最少12位的字元，檔案的存放路徑也記得改成自己的

JWT_SECRET="my-random-string-for-seeding"
STORAGE_DIR="/your/absolute/path/to/server/storage"

前端的環境變數，先把/api打開即可

# VITE_API_BASE='http://localhost:3001/api' # Use this URL when developing locally
# VITE_API_BASE="https://$CODESPACE_NAME-3001.$GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN/api" # for Github Codespaces
VITE_API_BASE='/api' # Use this URL deploying on non-localhost address OR in docker.

如果你在設定的時候，遇到更新請求，可以跟我著我下面的方法作

把 prisma 更新好

yarn add --dev prisma@latest
yarn add @prisma/client@latest

前端的程式碼

先編譯前端程式碼，前端是由 viteJS + React

cd frontend && yarn build

將編譯好的資料放到 server 的目錄下

cp -R frontend/dist/* server/public/

選項，如果需要用到本地端的 LLM 模型，就把 llama-cpp 下載下來

cd server && npx --no node-llama-cpp download

把資料庫建立好

cd server && npx prisma generate --schema=./prisma/schema.prisma
cd server && npx prisma migrate deploy --schema=./prisma/schema.prisma

Server端是用來處理 api 以及進行向量資料庫的管理以及跟 LLM 交互

Collector 是一個 NodeJS express server，用來作UI處理和解析文檔

cd server && NODE_ENV=production node index.js &
cd collector && NODE_ENV=production node index.js &

更新的指令碼

現在 anything llm 更新速度超快，把這一段指令碼複製起來，方便未來作更新的動作

#!/bin/bash

cd $HOME/anything-llm &&\
git checkout . &&\
git pull origin master &&\
echo "HEAD pulled to commit $(git log -1 --pretty=format:"%h" | tail -n 1)"

echo "Freezing current ENVs"
curl -I "http://localhost:3001/api/env-dump" | head -n 1|cut -d$' ' -f2

echo "Rebuilding Frontend"
cd $HOME/anything-llm/frontend && yarn && yarn build && cd $HOME/anything-llm

echo "Copying to Sever Public"
rm -rf server/public
cp -r frontend/dist server/public

echo "Killing node processes"
pkill node

echo "Installing collector dependencies"
cd $HOME/anything-llm/collector && yarn

echo "Installing server dependencies & running migrations"
cd $HOME/anything-llm/server && yarn
cd $HOME/anything-llm/server && npx prisma migrate deploy --schema=./prisma/schema.prisma
cd $HOME/anything-llm/server && npx prisma generate

echo "Booting up services."
truncate -s 0 /logs/server.log # Or any other log file location.
truncate -s 0 /logs/collector.log

cd $HOME/anything-llm/server
(NODE_ENV=production node index.js) &> /logs/server.log &

cd $HOME/anything-llm/collector
(NODE_ENV=production node index.js) &> /logs/collector.log &