WSL2 — Windows 跑 AI Agent 的终极环境¶

Windows 通过 WSL2 获得 Linux 级别的命令行兼容性、GPU 直通、Docker 原生体验和沙盒隔离，成为不输 macOS 的 AI Agent 开发平台。

目录¶

• 核心价值：为什么选 WSL
• 一、WSL2 基础与多实例管理
• 二、AI Agent 开发实战与双系统联动
• 三、硬件加速与 Docker 容器化
• 四、网络优化、GUI 与进阶管理
• 五、行动建议指南
• 参考资料

核心价值：为什么选 WSL¶

AI Agent（如 Claude Code、Codex、Hermes）通过执行命令行操作来完成任务。命令行的"语言"决定了 Agent 的效率。

三大核心优势¶

判断决策树¶

你要在 Windows 上跑 AI Agent？
├── 是 → 用 WSL2（没有第二选择）
│   ├── 需要 GPU 推理？ → WSL2 GPU 直通（nvidia-smi 直接可用）
│   ├── 需要沙盒隔离？ → WSL2 虚拟机天然隔离
│   └── 需要生产一致？ → WSL2 = Linux，无缝衔接
└── 否（仅日常使用） → PowerShell 足够

一、WSL2 基础与多实例管理¶

1.1 前置条件：开启 CPU 虚拟化¶

WSL2 依赖 Hyper-V 虚拟化。安装前必须在 BIOS 中开启：

不开启的后果：wsl --install 报错 "虚拟化未启用"，或实例启动失败。

1.2 快速安装¶

# 以管理员身份打开 PowerShell
wsl --install

# 默认安装最新 Ubuntu，安装后需重启
# 重启后自动进入 Ubuntu 初始化（创建用户名密码）

1.3 自定义安装与多实例¶

视频重点演示了多实例管理——这是 WSL 相比传统虚拟机的核心优势之一。

# 查看可安装的发行版（distro）
wsl -l -o

# 安装到指定盘符（避免占满 C 盘）
wsl --install -d Ubuntu --location D:\WSL\Ubuntu

# 给实例命名（支持同时安装多个隔离环境）
wsl --install -d Ubuntu-22.04 -n agent-dev
wsl --install -d Ubuntu-24.04 -n agent-prod
wsl --install -d Kali-Linux   -n security-lab

多实例隔离的价值：

┌─────────────────────────────────────────┐
│            Windows 主机                  │
│                                         │
│  ┌───────────┐ ┌───────────┐ ┌────────┐│
│  │ agent-dev │ │ agent-prod│ │ kali   ││
│  │ (沙盒实验) │ │ (稳定环境) │ │(安全)  ││
│  │ Python 3.13│ │ Python 3.12│ │ 工具链 ││
│  │ Node 24    │ │ Node 22    │ │        ││
│  └───────────┘ └───────────┘ └────────┘│
│         互相完全隔离，互不影响            │
└─────────────────────────────────────────┘

1.4 实例管理命令速查¶

# 列出已安装实例
wsl -l -v

# 设定默认实例（wsl 命令不带参数时进入的实例）
wsl -s agent-dev

# 关闭特定实例（释放资源）
wsl -t agent-dev

# 关闭所有实例（改配置后需要）
wsl --shutdown

# 删除实例（不可恢复，先备份）
wsl --unregister agent-dev

1.5 启动方式¶

二、AI Agent 开发实战与双系统联动¶

2.1 开发环境三件套¶

# 更新系统
sudo apt update && sudo apt upgrade -y

# 1. Git（WSL2 内置，但建议确认版本）
sudo apt install git

# 2. Python（Ubuntu 默认 python3，需修正命令链接）
sudo apt install python3 python-is-python3 python3-pip

# 3. Node.js via NVM（灵活切换版本，避免 APT 锁定版本）
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
source ~/.bashrc
nvm install --lts        # 安装最新 LTS
nvm install 22           # 或指定版本
nvm use 22

2.2 AI Agent 工具链部署¶

视频演示了多款 Agent 在 WSL 中运行：

Pi 示例（视频中的坦克大战 Demo）：

# Pi 接入 Kimi K2（视频 07:41 演示）
# 国产模型 API 成本低，适合原型开发
pi config set-provider kimi --api-key sk-xxx
pi config set-model kimi-k2

# 让 AI 直接生成一个可玩的游戏
pi "用 HTML+JS 写一个坦克大战游戏，支持键盘控制"

2.3 VS Code 跨系统开发（核心特性）¶

这是 WSL 杀手级功能之一——在 Linux 文件系统上开发，但用 Windows 端的 IDE 编辑。

# 在 WSL 终端，项目目录下直接输入
cd ~/projects/my-agent
code .
# ↑ 自动启动 Windows 端 VS Code，远程挂载当前 Linux 目录

┌─ Windows 端 ──────────────┐    ┌─ WSL2 Linux ─────────────┐
│                            │    │                           │
│  VS Code GUI              │◄──►│  ~/projects/my-agent/     │
│  （渲染、编辑、Git UI）    │ SSH│  （实际文件、编译、运行）  │
│                            │    │                           │
│  git commit/push 在这里    │    │  python app.py 在这里     │
└────────────────────────────┘    └───────────────────────────┘
         UI 跑在 Windows                     代码跑在 Linux

2.4 双向文件读写¶

# Linux → Windows：用文件资源管理器打开当前目录
explorer.exe .
# ↑ 直接弹出 Windows 文件管理器，显示 Linux 文件

# Windows → Linux：自动挂载在 /mnt/
ls /mnt/c/Users/        # 访问 C 盘
ls /mnt/d/Projects/     # 访问 D 盘

2.5 最佳实践：文件位置选择¶

跨系统文件操作的性能损耗来自 DrvFs 的 9P 协议。开发项目务必放在 Linux 原生目录。

✅ 正确：cd ~/projects/my-app && code .
❌ 错误：cd /mnt/c/Users/you/my-app && code .

三、硬件加速与 Docker 容器化¶

3.1 GPU 直通（免配置）¶

WSL2 对 NVIDIA GPU 的支持是开箱即用的——无需在 Linux 内安装驱动，只要 Windows 端装了 NVIDIA 驱动。

# 直接验证（如果输出 GPU 信息说明直通成功）
nvidia-smi

# 期望输出：
# +-----------------------------------------------------------------------------+
# | NVIDIA-SMI xxx     Driver Version: xxx       CUDA Version: 12.x            |
# | GPU  Name        Persistence-M| Bus-Id      Disp.A | Volatile Uncorr. ECC |
# |   0  RTX 4090    On           | 00000000:01 ... Off |
# +-----------------------------------------------------------------------------+

3.2 本地大模型推理（vLLM）¶

GPU 直通后，WSL 可作为本地 LLM 推理的一等公民：

# 安装 vLLM（高性能推理引擎）
pip install vllm

# 启动 OpenAI 兼容 API 服务
vllm serve Qwen/Qwen2.5-7B-Instruct \
  --port 8000 \
  --gpu-memory-utilization 0.9

# Windows 端直接访问（localhost 自动转发）
curl http://localhost:8000/v1/chat/completions \
  -d '{"model":"Qwen/Qwen2.5-7B-Instruct","messages":[{"role":"user","content":"hi"}]}'

3.3 Docker：无需 Docker Desktop¶

WSL2 默认启用 systemd，可在终端直接运行 docker 命令，省去笨重的 Docker Desktop。

# 确认 systemd 已启用（Ubuntu 22.04+ 默认启用）
systemctl list-unit-files --type=service | head

# 安装 Docker CE（不要装 Docker Desktop）
sudo apt install docker.io
sudo usermod -aG docker $USER
# 重新登录后生效

# 一键启动 Redis（开发常用）
docker run -d --name redis -p 6379:6379 redis:latest
docker exec redis redis-cli ping   # PONG

Docker 方案对比：

四、网络优化、GUI 与进阶管理¶

4.1 网络模式¶

WSL2 有两种网络模式，适用场景不同。

默认 NAT 模式：
┌─ Windows (192.168.1.100) ─────┐
│                               │
│  localhost:8000 ──自动转发──► │ WSL (172.x.x.x):8000
│                               │
│  局域网其他设备 ✗ 无法访问     │
└───────────────────────────────┘

镜像模式（Mirrored）：
┌─ Windows (192.168.1.100) ─────┐
│                               │
│  WSL 共享 Windows 的 IP        │
│  192.168.1.100:8000 直接可达   │
│                               │
│  局域网其他设备 ✓ 可访问       │
└───────────────────────────────┘

开启镜像模式（需 Windows 11 22H2+）：

# 文件位置：%UserProfile%\.wslconfig（即 C:\Users\<你>\.wslconfig）
[wsl2]
networkingMode=mirrored

# 可选：忽略端口冲突（mirrored 模式下 Windows 和 Linux 共享 IP）
[experimental]
ignoredPorts=3000,8000,5173

改完执行 wsl --shutdown 重启生效。

4.2 配置文件分工：.wslconfig vs wsl.conf¶

这是 WSL 配置最易混淆的点。两个文件作用域完全不同。

典型 .wslconfig（全局 VM 资源管理）：

# C:\Users\<你>\.wslconfig
[wsl2]
memory=8GB              # 限制 WSL VM 最大内存（默认占主机 50%）
processors=4            # 分配 CPU 核数
swap=4GB                # 交换空间
networkingMode=mirrored # 镜像网络模式

[experimental]
autoMemoryReclaim=gradual  # 自动回收空闲内存
sparseVhd=true             # VHD 稀疏化（节省磁盘）

典型 wsl.conf（单实例配置）：

# /etc/wsl.conf（在 WSL 实例内编辑，需 sudo）
[boot]
systemd=true           # 启用 systemd（Ubuntu 22.04+ 默认启用）

[automount]
enabled=true           # 自动挂载 Windows 盘到 /mnt/
# 关闭可防止 AI Agent 读取主机文件（安全加固）
# enabled=false

[interop]
enabled=true           # 允许调用 Windows 程序（如 explorer.exe）
appendWindowsPath=true # 将 Windows PATH 加入 Linux $PATH

安全加固提示：如果担心 AI Agent 通过 /mnt/c/ 读写主机文件，可在 wsl.conf 中设 automount enabled=false，完全切断对 Windows 文件系统的访问。

4.3 GUI 图形支持（WSLg）¶

WSLg 让 Linux GUI 应用直接显示在 Windows 桌面上，无需额外 X Server。

# 安装 GIMP（图像编辑器）
sudo apt install gimp
gimp   # 直接弹窗，像原生 Windows 应用一样

# 单应用模式：适合偶尔需要 GUI 工具的场景

如果需要完整桌面环境（多个应用 + 任务栏）：

4.4 系统备份与迁移¶

# 导出实例为 tar 包（备份/迁移）
wsl --export agent-dev D:\Backup\agent-dev-20260725.tar

# 从 tar 包导入（恢复/克隆到新机器）
wsl --import agent-dev-new D:\WSL\agent-dev-new D:\Backup\agent-dev-20260725.tar

# 典型工作流：配好环境 → 导出黄金镜像 → 随时克隆

4.5 混合命令混血¶

Windows 和 Linux 命令可通过管道互相传递，这是 WSL 独有的跨系统协作能力。

# PowerShell 中调用 Linux 命令
wsl ls -la /mnt/c/Projects | Select-String "agent"

# Linux 中调用 Windows 命令（interop 启用时）
Get-Item # PowerShell 命令的结果 → 管道传给 grep
# 实测示例：
powershell.exe -Command "Get-Process" | grep python

五、行动建议指南¶

快速上手清单¶

1. 确认虚拟化：重启进 BIOS，开启 Intel VT-x 或 AMD SVM
2. 安装 WSL2：管理员 PowerShell 执行 wsl --install，重启
3. 规划目录：项目放在 ~/projects/（Linux 原生），不要放 /mnt/c/
4. 装开发三件套：git + python-is-python3 + NVM 管 Node
5. 部署 Agent：Claude Code / Codex / Hermes 任选，都在 Linux 内原生运行
6. 验证 GPU：nvidia-smi 有输出说明直通成功
7. 按需开镜像网络：有移动端调试需求时配置 .wslconfig
8. 打黄金镜像：环境配好后 wsl --export 备份，随时恢复/克隆

配置决策树¶

你的需求是什么？
├── 日常 AI Agent 开发
│   └── wsl --install → 装三件套 → code . 开始
├── 需要局域网访问（手机调试等）
│   └── .wslconfig 加 networkingMode=mirrored
├── 需要本地大模型推理
│   └── 确认 nvidia-smi → pip install vllm → vllm serve
├── 需要数据库/中间件
│   └── apt install docker.io → docker run redis/mysql/...
├── 担心 AI Agent 乱动主机文件
│   └── wsl.conf 设 automount enabled=false
└── 要换机器 / 要备份
    └── wsl --export → 拷 .tar → 新机器 wsl --import

参考资料¶

• 视频：Windows跑AI Agent，WSL才是终极答案 — 技术爬爬虾
• 微软官方：WSL Advanced settings（.wslconfig / wsl.conf 完整参数表）
• 微软官方：WSL Networking（NAT vs Mirrored 模式详解）
• Pi CLI（轻量 Agent，支持 Kimi/DeepSeek）

相关笔记¶

• [[Claude-Code-配置与使用]]
• [[Hermes-Agent-配置指南]]
• [[vLLM-本地大模型部署]]