WSL 保姆级攻略 · 在 Windows 上跑 AI Agent

01

在 WSL 里跑 Agent 的三大好处

1

运行更稳，效率更高

很多人遇到过：AI 写 PowerShell 命令频繁报错，不仅执行慢，还特别浪费 token。因为大模型训练语料里的命令行操作大部分是 Linux 和 macOS 风格，在 Linux 环境里出错概率明显更低，效果更好。

2

跟生产环境更一致

写出来的代码最终大概率要部署到 Linux 服务器。如果一开始就在 WSL 里编写和测试，后续部署时环境差异更小，整个流程也更加丝滑。

3

环境隔离更安全

WSL 提供了 Linux 虚拟机与 Windows 宿主机之间的隔离。即使 Agent 在 WSL 里误操作把环境搞坏了，通常也不会影响 Windows 主系统。最坏的情况，也只是删掉这个 WSL 实例、重新创建一个新的子系统。

02

前提：开启 CPU 虚拟化

现阶段大部分电脑默认已开启，可以先确认一下：搜索栏搜索「任务管理器」→ 性能 → CPU，显示「虚拟化：已启用」就没问题。
如果显示未启用，进入 BIOS 设置：Intel 平台找到 VMX 虚拟化平台开关打开；AMD 平台找到 SVM 开关打开。

03

正式安装 WSL

安装步骤

在 Windows 任意位置点击右键 → 在终端打开。
输入命令 wsl --install 并回车。国内网络环境建议在末尾加上 --web-download，提高下载速度。
如果提示需要先重启电脑，就重启一次；重启后重新打开终端，还是执行刚才那条命令，开始正式安装。
接下来填写 Linux 虚拟机的用户名与密码。注意：输入密码时屏幕上不会显示任何内容，但实际上已经输入进去了。输入完回车，再输入一遍回车即完成安装。
命令行颜色变了，就说明进入了 Linux 子系统。输入 exit 可退出。

WSL 默认安装的是 Ubuntu，也是目前最流行的 Linux 发行版。所谓发行版，就是不同团队基于 Linux 内核打造的不同操作系统版本——有点像安卓：底层都是安卓系统，但每个厂商都会在上面定制和封装，形成各自不同的发行版。

04

装其他发行版、开多个实例

wsl -l -o：列出所有在线可安装的 Linux 发行版（l 是 list，o 是 online）。
想装别的发行版：wsl --install -d kali-linux（-d 后面接发行版名字）。
不想装到 C 盘：加上 --location 手动指定安装目录，例如指定到一个 D 盘文件夹。
同一个发行版也可以装多个实例。wsl --install ubuntu --name ubuntu2，用 --name 给第二个实例换个名字，同样可以指定安装路径。
每个实例都有自己的文件系统和配置，互相隔离、互不影响。
wsl -l：列出这台电脑上安装过的所有 Linux 虚拟机。

05

启动、切换与关机

先升级本体

启动之前建议先执行 wsl --update，把 WSL 本体的功能升级到最新，后续操作能保持功能一致。

几种启动方式

输入 wsl：启动默认的 Linux 虚拟机，命令行颜色变了就是启动成功，输入 exit 退出。
输入 wsl -d kali-linux：指定启动某一个虚拟机。
输入 wsl --set-default kali-linux：把它设为默认实例。之后再输入不带参数的 wsl，默认启用的就是它。
更简洁的方式：在 PowerShell 顶部的下拉窗口里，直接找到所有 Linux 实例，点击即可在新窗口启动。
关机很简单：把窗口叉掉。WSL 的命令行窗口被关闭或退出后，对应的 Linux 虚拟机也会自动关机。

06

开发三件套：Git、Node.js、Python

Git

以 Ubuntu 为例，输入 git -v 检查，系统自带了 Git，不用额外安装。

Python

python3 --version：同样自带 Python 3。
但直接敲 python 会提示未安装，需要做一点配置，把 python 命令链接到 python3 上。
先 sudo apt update 更新索引，再 sudo apt install python-is-python3 安装即可。

Node.js

输入 node -v 发现还没安装。
到 Node 官网，操作系统选 Linux，安装方式选 nvm（Node.js 版本管理器）。
把官网给的三条命令依次复制到 Ubuntu 中执行，再安装 Node.js 版本 24。
输入 node -v 与 npm -v，成功打印出版本就说明准备好了。

07

在 WSL 里跑 Agent：Pi

Pi 是一个极简的 coding agent，没有复杂的提示词，最大程度减少对 AI 的干扰，而且非常省 token。

在 WSL 里选择 c 的安装方式，复制命令到 WSL 执行，输入 Y 完成安装。
cd ~ 进入用户主目录，然后 mkdir pi-test 创建文件夹，再进入这个文件夹。
输入 pi 启动。它会提示先配置模型，输入 /login，可以选择模型订阅或 API。
选 API 后支持很多厂商的模型，推荐使用 DeepSeek、MiniMax 等；到官网控制台新建 API Key，复制粘贴回来回车即配置成功。
用 /model 可以切换模型。

实测：让 AI 写一个坦克大战

使用 Next.js 框架让它编写一个坦克大战，开发完成后它提示用浏览器访问某个地址就能直接开始游戏。可以直接用 Windows 上的 Edge 浏览器打开这个地址玩到游戏。

知识点：localhost 端口自动转发

WSL 里运行的服务使用的是 Linux 虚拟机的 IP 地址，而 Windows 电脑的 localhost 指向的是宿主机的 IP 地址，两者并不是一回事。理论上在宿主机敲 localhost 不该访问到 WSL 里的服务，这其实是 WSL 的一个特色功能。

当 WSL 检测到 Linux 里有程序监听端口，它就会自动转发到 Windows 宿主机这边 localhost 的相同端口。所以用 localhost 访问宿主机的 3000 端口，请求会自动转发到 Linux 虚拟机的 3000 端口上。

08

用 VS Code 改代码与提交

直接打开工作目录

前提是 Windows 电脑上已安装 VS Code。
先来到工作目录，输入 code .（code 可理解为 VS Code 的简写，点表示打开当前目录）。
这样就用 Windows 上的 VS Code 打开了工作目录，可以直接查看和修改源代码。比如改一下标题，浏览器里就会同步改动，跟在 Windows 上编码调试一样方便。

在 VS Code 里做 Git 操作

找到 Source Control，点击 Manage Trust 信任该目录。
点击 Initialize，把目录初始化成一个 Git 项目。
填写 commit message，完成代码提交。
再点击 Publish，填写仓库名字，回车，右下角提示代码已上传到 GitHub。

让 AI 代做 Git 操作

可以告诉 AI：你现在在 WSL 里，读一下我 Windows 主机上的 Git 设置，然后在 WSL 里也配置一下。
它能读到 Windows 主机的配置，并把配置同步到 WSL 里。
再让 AI 修改坦克大战的标题，它一次完成了修改和提交，VS Code 里也能看到这次提交记录。
让它推送到 GitHub，提交也能正常推送上去。整体体验跟 Windows 上几乎一致，没有学习门槛。

09

两个系统之间的文件互通

在 Windows 里看 Linux 文件

打开资源管理器，左下角有一个企鹅（Linux 图标），下面列出各个发行版，打开后就能浏览 Linux 子系统的文件目录。
例如代码放在 home → 用户名 → pi-test → 坦克大战目录下，所有文件都能用 Windows 资源管理器查看，还能直接用 Windows 软件打开编辑。
更快捷的方式：在某个目录下输入 explorer.exe .（. 表示当前目录），就能用 Windows 资源管理器打开该目录。

在 Linux 里看 Windows 文件

输入 df -h 查看所有磁盘，能看到 C 盘、D 盘，挂载地址是 /mnt/c、/mnt/d。
cd /mnt/c 就能进入 C 盘根目录；cd /mnt/c/Users/用户名/Desktop 就是桌面，用 ls 列出桌面内容。

在 WSL 里开发项目时，项目文件夹尽量放在 Linux 原生目录里，不要放在 Windows 目录里。跨操作系统读取文件会产生额外的 IO 开销。

把图片拖给 AI 看

在浏览器里截图并保存到桌面，然后直接把图片拖拽进 WSL 的窗口里。图片地址会以挂载卷目录的形式显示过来，对应 C 盘用户桌面的路径。问 AI「看看这个图里有什么」，它在 WSL 里也能正确识别图片。

10

另外三款 Agent：Hermes、Claude Code、Codex

Hermes Agent

非常流行的 Agent 工具，很长一段时间没有 Windows 版本。现在虽然出了原生 Windows 版，但表现一直不太好，可以用 WSL 来安装。

安装方式选择 Linux，复制命令到 WSL 的 Ubuntu 终端执行，这一步选「是」。
输入这台 Linux 虚拟机的密码，接下来选择第二个「完全设置」。
选择模型厂商（例如 DeepSeek），到对应平台的 API 开放平台创建 API Key，复制粘贴回来回车。
选一个模型，选择 keep current；再选择一个即时通信渠道，最简单的就是勾选第三个，然后回车，按提示完成配对。
后面一路使用默认值回车即可；遇到不知道怎么配置的地方，都选择 skip 跳过。
关闭窗口重启一下 WSL，输入 hermes 启动，打个招呼能收到回复就配置完成了。

Claude Code

复制 Claude Code 的安装命令，粘贴进 WSL 回车安装。
输入 claude 启动，官方订阅方式登录。
把提示的地址在浏览器里打开，复制授权码粘贴进 WSL 回车，即配置完成。打招呼能收到回复就成功了。

Codex

最推荐的方式是在 WSL 里运行命令行版本的 Codex，功能一致。到它的 GitHub 首页复制命令，粘贴到 WSL 执行，输入 Y 安装。
安装完成后重启 WSL，输入 codex 启动，用 ChatGPT 登录，打个招呼验证。
不习惯命令行，也可以用 Windows 上的 Codex App（现已改名为 ChatGPT 桌面应用）。
在设置 → 常规 → 智能体环境里，把环境切换成 WSL，终端也切换成 WSL，然后按提示重启。
重启后可以选择一个 Windows 文件夹作为项目文件夹，它会以挂载卷的形式链接到 WSL 里，此时 Codex 使用的都是 Linux 命令。

这种方式目前只能用 Windows 文件夹作为项目文件夹并挂载进 WSL，IO 效率比较低，所以更推荐直接在 WSL 里使用命令行版 Codex。

11

Docker：一句话启动本地服务

Docker 基于 Linux 容器化技术，让程序在不同环境中都能一致运行，大幅简化开发与运维流程。现在 WSL 上最新的发行版已默认启用 systemd，运行 Docker 的体验跟一台真正的 Linux 电脑一致。

来到 Docker 官方部署指南，只需要执行第一个和第四个命令即可完成安装。
本地开发常用 Redis 做高速缓存。在 Windows 上部署 Redis 相当复杂，用 Docker 就非常简单。
在 WSL 里敲 Docker 命令要加 sudo，完整命令形如 sudo docker run -d -p 6379:6379 redis，把端口映射出来，Redis 默认端口是 6379。
用 Windows 上的开源 Redis 客户端，新建连接，Host 填 localhost、端口 6379，直接就能连上。添加一个键并赋值，读写都正常。
关掉 WSL 窗口，Docker 就停止运行，宿主机也连不上了。
用 sudo docker ps -a 查看所有容器，会发现 Redis 容器已停止；用 sudo docker start 接容器 ID，就能重新启动并恢复连接。

12

WSL1 与 WSL2 的本质区别

WSL1：翻译层

本质是一个翻译层，把 Linux 系统指令翻译成 Windows 内核能理解的系统指令。它不运行真正的 Linux 内核，而是通过 Windows 内核来模拟，因此在某些情况下会出现兼容性问题，比如无法运行 Docker。而且维护这样的翻译层工作量巨大。

WSL2：真正的 Linux 内核

基于 Hyper-V 虚拟化平台，拥有真正的 Linux 内核，可与 Windows 在用户空间进行网络通信、文件共享。
可以运行 Docker，并且得益于 Hyper-V 强大的硬件虚拟化技术，自带显卡直通。
这种架构提高了系统兼容性，也大大降低了开发维护成本。

显卡直通的意思是：在 WSL 里可以直接调用 Windows 宿主机上的显卡，不需要做任何配置。本期介绍的所有功能都基于最新版 WSL2。

13

显卡直通与本地大模型

在 Ubuntu 子系统里输入 nvidia-smi，可以直接看到显卡驱动版本、CUDA 版本、显卡型号（如 RTX 5070）和显存情况。
千万不要往这个 Linux 系统里装任何驱动，它可以直接使用 Windows 宿主机上的显卡驱动，不需要做任何配置。
现阶段大多数 AI 推理框架和深度学习框架都优先支持 Linux，官方文档和安装教程也基本以 Linux 为主。用 WSL 可以把手头的高性能游戏电脑直接变成 AI 开发平台。

实战：在 WSL 里跑 vLLM

vLLM 是目前最炙手可热的 AI 推理框架，操作系统支持里只有 Linux 版本，所有官方文档全部基于该系统编写，用 WSL 就是它的「一等公民」。
按文档先要用 uv 创建虚拟环境：到 uv 官网找到 Linux 安装命令，复制到 WSL 安装。
依次执行文档中的三条命令，完成环境准备。
复制官方文档的启动命令并改一下模型，换成最新的千问 3.5，直接用会报错。
让 AI 帮忙修改启动命令：调整采样器，并在后面约束显存占用量，改完启动成功。
用客户端填上推理端点与提示词测试，推理速度非常快，8 秒就能推理出很多词。

14

图形界面：WSLg 与完整桌面

WSLg：把单个应用显示到 Windows

WSLg 是 WSL 里的图形界面支持组件，可以把 Linux 图形应用直接显示到 Windows 桌面。
它不是完整的桌面系统，通常只用来把单个应用显示到 Windows 里。
例如 GIMP——一款类似 Photoshop 的开源免费图像编辑软件，用 apt 安装后在 WSL 里运行，就能在 Windows 界面里打开并使用它。

完整桌面：Kali 与 Ubuntu

这次不选 Ubuntu，改选 Kali：先更新 apt 索引，再安装 kali-win-kex，然后输入 kex 启动桌面，会以远程连接的方式打开 Kali 桌面，这是一个完整可用的 Linux 操作系统桌面。
Ubuntu 上启动完整桌面需要依次执行若干命令，最后一条命令会显示这台 Linux 虚拟机的 IP 地址。
把 IP 地址复制到 Windows 的「远程桌面连接」里，加上冒号和端口 3389，点击连接即可进入 Ubuntu 虚拟机的桌面。

15

网络：localhost 转发与镜像模式

默认的 NAT 网络模式

WSL 默认采用 NAT 网络模式，Linux 子系统位于 WSL 宿主机内部的虚拟网络里，拥有独立的虚拟 IP 地址。
通过 localhost 端口自动转发，在宿主机里可以用 localhost 访问到 WSL 里启动的应用。
反向访问：在 Windows 的 PowerShell 里输入 ipconfig，找到自己网卡的局域网 IP；然后在 WSL 里用这个 IP 就能访问宿主机上的服务。

镜像网络：让局域网设备也能访问

默认情况下，局域网里的其他设备（比如手机）没法访问 WSL 里的服务。
在 C:\Users\用户名 目录下新建一个名为 .wslconfig 的文件，这是 WSL 的全局配置文件。
用记事本打开，加入两行配置，把 WSL 的网络模式从 NAT 切换成镜像网络，保存。
把所有 WSL 窗口关闭，等待一分钟让 WSL 完成重启。
镜像模式下，Windows 宿主机的网卡会直接镜像一份给 WSL 使用，两者处于相同的网络环境、使用相同的局域网 IP。
再以管理员身份运行 PowerShell，粘贴命令修改 WSL 的防火墙设置，让它能被局域网设备访问。
手机上打开浏览器，输入宿主机 IP 加端口 3000，就能成功访问 WSL 里启动的服务。

镜像模式还有个好处：让网络结构变得更简单。如果你在使用 WSL 过程中遇到一些奇怪的网络问题，可以试试切换成镜像模式，看看能不能解决。

16

两个配置文件，别搞混

.wslconfig

这是一个 Windows 文件，属于全局通用配置，对所有的 WSL 虚拟机都生效。
位置在 C:\Users\用户名\.wslconfig。
主要用途：修改内存、内核、启动方式，以及前面介绍的网络模式等。

wsl.conf

这是一个 Linux 文件，存放在 Linux 系统里面，只对单个虚拟机生效。
主要用途：修改挂载卷、systemd 的启用、默认用户设置等。
操作示例：在 Ubuntu 里进入 /etc 目录，用 sudo vi wsl.conf 编辑，找到自动挂载相关设置，把标签加上并设为关闭自动挂载。
这样虚拟机里就不会再自动挂载 C 盘和 D 盘，AI 操作时也无法看到 Windows 上的文件，可以进一步提高安全性。
保存后把虚拟机关闭，官方文档要求至少等待 8 秒让虚拟机完全重启，再输入 df -h 查看，挂载卷里就没有 Windows 目录了，配置生效。

17

备份、克隆与命令行互通

导出与备份

wsl --export 虚拟机名压缩包名.tar，例如把 Ubuntu 导出为一个 tar 压缩包，就完成了一次完整备份。
有了备份包，随时可以还原回来。

导入与克隆

输入 wsl --import，后面依次填写名字、安装路径、压缩包地址，回车即可把虚拟机重新导入回来。
用导入导出的方法，可以把虚拟机迁移到其他的 Windows 电脑上。
还可以把一个虚拟机克隆好几份：再导入一遍，换个新名字和新路径，比如 ubuntu2、ubuntu3，同一个虚拟机就变成了多份互不影响的实例。

命令行互通：Windows 与 Linux 混写

在 Windows 里甚至可以调用 Linux 命令。打开 PowerShell，先执行 Windows 命令 Get-ChildItem，显示当前文件夹的所有内容。

想对输出做过滤，但不确定 Windows 版本的写法，而 Linux 版本的过滤是 grep——于是可以直接混写：Windows 命令后面接管道符，再用 wsl grep 接筛选条件。前半部分是 Windows 命令，后半部分是 Linux 命令，一样达成了想要的效果。

Windows 命令管道符 wsl grep 一步到位

18

行动建议

先确认 CPU 虚拟化是否已启用，没开就进 BIOS 打开 VMX 或 SVM。
一条 wsl --install 装好 Ubuntu，国内网络记得加 --web-download。
装完先执行 wsl --update，再补齐 Git、Node.js、Python 三件套。
把项目文件夹放在 Linux 原生目录里，避免跨系统读取带来的额外 IO 开销。
Agent 优先在 WSL 命令行里跑；不习惯命令行，再把桌面应用的环境切到 WSL。
需要局域网设备调试时，切换成镜像网络模式，并配好防火墙设置。
重要环境定期用导入导出做备份，还能顺手克隆出多个隔离实例。

WSL 让 Windows 同时获得两大操作系统的优势：用 Windows 的界面与生态，跑 Linux 的命令行与生产环境。