Windows下用WSL2运行Hermes Agent：安装配置与踩坑全记录

说实话，我最早对"在 Windows 上跑 Hermes Agent"这件事是有点抗拒的。不是怕工具本身，而是怕环境差异带来的各种乱七八糟的问题。你照着文档抄一行命令，在 Linux 上顺顺利利，到了 Windows 原生终端里就给你表演什么叫"一半能用一半报错"。后来我索性把整套东西迁到 WSL2 里跑，从安装到日常使用都顺畅了很多。这篇东西就把我完整操作过一遍的流程、配置和踩坑记录整理出来，给同样想把 Hermes Agent 放在 Windows 上跑的人做个参考。

先说明一下背景：Hermes Agent 是一个开源的智能体编排框架，简单说就是你给它一个任务定义，它会按照插件化的方式调用命令行、API、脚本等外部能力去执行。它的运行环境更偏向 Linux，尤其是那些依赖 bash 和系统命令才能发挥全部能力的插件，在原生 Windows 下表现很一般。WSL2 恰好是一个很好的中间层：既能保留你习惯的 Windows 桌面环境，又能提供一个完整的 Linux 用户空间。

1. 为什么我把 Hermes Agent 放在 WSL2 里运行

1.1 在原生 Windows 里跑智能体会遇到哪些破事

最早我图省事，直接在 Windows 11 上用 PowerShell 跑 Hermes Agent。前两天的体验还行，但时间一长问题全冒出来了。

最烦人的是路径分隔符。智能体的插件和任务脚本里大量出现 Linux 风格的正斜杠路径，比如~/.hermes/runtime、/tmp/cache这类写法。Windows 原生环境里，反斜杠才是路径分隔符，于是配置解析的时候经常出现两种情况：要么插件在拼路径时拿正斜杠直接拼到盘符后面，拼出一个根本不存在的位置；要么某些 YAML 解析器把反斜杠里的字符当成转义符，直接给你把配置读崩了。你检查半天发现不是逻辑问题，纯粹是环境差异。

第二个问题是 shell 命令的兼容性。Hermes Agent 的任务编排里，有一类插件会直接调用 shell 来执行脚本，这些脚本默认是按 bash 语法写的。bash 里单引号传达意字符串、双引号内做变量展开，这套规则在 cmd 和 PowerShell 里完全不是一回事。Windows 下跑这些任务，轻则参数传递错误，重则整段脚本执行失败，而且报错信息常常让你摸不着头脑。

第三个是常驻进程的管理体验。Windows 上让一个智能体长期运行，无非是"计划任务"或者"服务"两种思路。但 Hermes Agent 的日志、pid 文件、运行时目录都是按 Linux 习惯组织的，强行塞进 Windows 服务框架里，要么权限不对，要么日志轮转失效。等你想排查问题的时候，面对着一堆分散在事件查看器里的条目，效率非常低。

1.2 WSL2 到底给你带来了什么

WSL2 本质是一个轻量级虚拟机，但这个虚拟机和 Windows 之间的集成做得相当深。对跑 Hermes Agent 来说，最值得说的好处是：

• 完整的 Linux 用户空间。bash、coreutils、jq、ffmpeg、systemd 这些工具全都可用，插件里写的 shell 脚本基本不用改。
• 隔离性好。智能体在 WSL2 里随便折腾，都不会碰 Windows 的系统目录和注册表。装错了依赖大不了把发行版删了重来。
• 资源可控。你可以在.wslconfig里限定内存和 CPU 上限，避免它和 Windows 桌面的其他程序抢资源。
• 互操作性好。Windows 侧可以直接调用wsl.exe执行 Linux 命令，Linux 侧可以直接访问挂了载的 Windows 盘符，两边文件互通。

边界也要认清。WSL2 用的是定制精简过的 Linux 内核，某些内核模块不可用。网络默认是 NAT 模式，端口转发策略和普通 Linux 主机不完全一样，部分 UDP 服务和组播协议的行为会有差异。另外，如果你的文件放在/mnt/c这种 Windows 盘符路径下，大量小文件读写时性能衰减很明显。所以我的原则很简单：Hermes Agent 的安装目录、配置目录、运行时目录全部放在 WSL2 内部的 Linux 文件系统里，Windows 侧只承担编辑器和终端入口的角色。

1.3 Hermes Agent 对运行环境的基本要求

Hermes Agent 采用的是"主进程 + 插件"的架构。主进程负责任务调度、状态维护和插件通信，插件负责对接各类外部能力。它的硬件门槛不高，但有几个软性要求：

• 64 位 Linux 环境，内核版本建议不低于 5.10，WSL2 默认内核早就超过了。
• Python 3.10 及以上，官方推荐 3.11 或 3.12。部分插件依赖较新的类型注解语法，Python 版本太低会直接装不上。
• 内存建议至少 2GB。单纯跑任务编排和插件调度够用，但你要是并行跑模型推理或数据抓取，那得另说。
• 网络能正常访问 Python 包仓库和插件市场。如果直连速度不理想，可以配置国内镜像源，后面我会讲到。

把这些条件对齐之后，整个安装路线就变得很清晰了：先准备好 WSL2 环境，再装 Hermes Agent 本体，最后把配置和日常使用跑通。

2. 第一步不是装 Hermes，而是把 WSL2 环境调顺

2.1 先确认你的 WSL 版本和内核

很多朋友机器上其实装着旧版 WSL，甚至默认创建的是 WSL1 发行版。WSL1 和 WSL2 在系统调用兼容性上差距很大，Hermes Agent 依赖的很多行为在 WSL1 下会异常。所以第一步先打开 PowerShell，执行：

wsl --version

这个命令会输出 WSL 应用自身和内核的版本信息。如果版本老旧，建议先执行：

wsl --update

把组件更新到当前稳定版。接下来再看已有发行版的情况：

wsl -l -v

输出里有一列叫 VERSION，如果你看到某个发行版显示 1，可以在 PowerShell 里转换：

wsl --set-version <发行版名称> 2

转换过程会保留原有数据，但耗时较长，最好在确认不需要跑任务的时候执行。

2.2 安装 Ubuntu 发行版并做基础初始化

我的选择是 Ubuntu 24.04 LTS。安装可以直接用命令一行搞定：

wsl --install -d Ubuntu-24.04

首次启动时会提示创建用户名和密码。这里有一个小设计：这个用户名不是 root，但默认会被加入 sudo 组。我建议日常操作就用这个普通用户，后面 Hermes Agent 的配置文件和运行时目录都归属这个用户，权限问题会少很多。

基础依赖我习惯一次性装齐：

sudo apt update && sudo apt upgrade -y sudo apt install -y curl wget git jq build-essential python3 python3-venv python3-pip

build-essential有时候不是必须的，但如果你想手动编译某个插件依赖，没有它就很被动。装了不亏。

2.3 开启 systemd，配置 .wslconfig 资源上限

新版 WSL2 默认开启 systemd，如果你用的是旧镜像或者自定义过配置，可以在/etc/wsl.conf里手动加上：

[boot] systemd=true

改完后回到 PowerShell：

wsl --shutdown

再重新进入发行版，让 systemd 生效。为什么强调 systemd？因为 Hermes Agent 常驻运行的最好方式就是做一个 systemd 服务，让系统来管它的启动、崩溃重启和日志，比你手动开个终端挂着要可靠得多。

资源分配我建议直接写进 Windows 用户目录下的.wslconfig文件：

[wsl2] memory=4GB processors=4 swap=2GB localhostForwarding=true

这个文件在 Windows 侧，格式是 INI。memory给多少看你的物理内存。我本地是 16GB，给 WSL2 分 4GB，平时跑 Hermes Agent 再加上几个调试进程没什么压力。localhostForwarding=true一定要保留，后面访问 Web 管理面板或者从 Windows 侧连端口全靠它。

2.4 换源这件事，最好在安装前做

如果你在国内网络环境下，直接连默认仓库下载依赖包会非常难受。apt 源和 pip 源都可以换成国内镜像。

Ubuntu 24.04 的 apt 源配置文件在/etc/apt/sources.list.d/ubuntu.sources。把其中的URIs地址替换成可用的国内镜像地址，然后：

sudo apt update

pip 源可以配置在~/.pip/pip.conf：

[global] index-url = https://pypi.tuna.tsinghua.edu.cn/simple

这步做完，装 Python 依赖的速度会快很多。但注意，Hermes Agent 的插件市场如果也走网络下载，需要单独确认插件市场是否支持镜像地址。有些插件市场不提供国内镜像，那就只能依赖稳定的公网访问了，这也是很多人装完主程序却拉不下来插件的一个重要原因。

3. Hermes Agent 的具体安装步骤

3.1 准备 Python 虚拟环境

先确认 Python 版本：

python3 --version

Ubuntu 24.04 自带 Python 3.12，满足要求。如果你的系统版本较老，Python 还是 3.8 或 3.9，那就先升级 Python 或者安装新版再用，别硬着头皮往下走。

我强烈建议给 Hermes Agent 单独建一个虚拟环境，不要装到系统全局 Python 里：

python3 -m venv ~/hermes-venv source ~/hermes-venv/bin/activate

虚拟环境的好处很直接：Hermes Agent 的插件会带来几十个第三方依赖，它们和系统里其他包的版本要求可能冲突。全部隔离在~/hermes-venv里，想升级就升级，想删掉重建也无所谓。

3.2 用 pip 安装还是官方脚本？我的建议是 pip

Hermes Agent 官方提供了快速安装脚本，通常是一行命令搞定。优点是省事，会自动检测系统环境并创建虚拟环境；缺点是把安装过程封装成了一个黑盒，出了问题不容易定位。我自己更偏向 pip 安装，过程透明，每一步可控：

pip install --upgrade hermes-agent

装完检查：

hermes --version

如果提示命令找不到，先别慌，检查两件事：虚拟环境有没有激活；~/hermes-venv/bin有没有在 PATH 里。前者执行source ~/hermes-venv/bin/activate，后者可以手动加到~/.bashrc的末尾。

3.3 初始化配置目录和第一个配置文件

Hermes Agent 默认会把配置放在~/.hermes下。先手动建好目录结构：

mkdir -p ~/.hermes/config mkdir -p ~/.hermes/runtime mkdir -p ~/.hermes/logs

然后执行：

hermes init

这个命令会生成一个默认的config.yaml，里面有 agent 名称、监听地址、日志级别、插件列表等关键字段。第一次配置别贪多，只做两件事：监听地址改成127.0.0.1，日志级别改成debug。调试阶段用 debug 级别能省下大量排查时间，等稳定了再改回info。

3.4 启动，并让它能开机自启

配置好以后，先手动启动一次：

hermes agent start

正常情况下，几秒后在~/.hermes/logs/agent.log里就能看到启动日志，日志里会打印 agent id 和绑定的端口。再执行：

hermes status

确认主进程在跑、插件加载正常。

接下来为了让它在系统重启后自动恢复，我写了一个 systemd 服务：

[Unit] Description=Hermes Agent After=network.target [Service] Type=simple User=你的用户名 WorkingDirectory=/home/你的用户名 ExecStart=/home/你的用户名/hermes-venv/bin/hermes agent start Restart=always RestartSec=5 [Install] WantedBy=multi-user.target

把文件放到/etc/systemd/system/hermes-agent.service，然后：

sudo systemctl daemon-reload sudo systemctl enable --now hermes-agent

这样一来，只要 WSL2 启动，Hermes Agent 就会被系统自动拉起。崩溃了也会在五秒后自动重启，日志由 systemd 管理，干净很多。

4. 安装完之后，怎么让 Hermes Agent 真正用起来

4.1 先做一遍健康检查，别急着写复杂任务

每次环境变动之后，我建议先跑一遍三连检查：

• hermes status确认主进程正常。
• 查看~/.hermes/logs/agent.log尾部几十行，确认没有重复报错。
• 如果开了管理面板，访问http://127.0.0.1:端口/health，确认健康检查接口返回正常的 JSON。

这一步很关键。很多同学装完就急着写复杂的任务编排，一旦出问题，根本分不清是主进程的问题、配置的问题还是插件的问题。先把基础链路打扎实，后面才能少走弯路。

4.2 配置任务编排与插件

Hermes Agent 的任务编排主要由配置文件驱动。我习惯的做法是：先只启用必要的基础插件，再逐步添加依赖插件。例如：

agent: name: my-agent listen: 127.0.0.1:8090 log_level: debug plugins: enabled: - shell - schedule - webhook

这样每次启动只加载三个必要插件，启动速度快，日志也干净。以后想加插件，改配置文件再执行：

hermes agent reload

reload和restart的差别值得记一下：reload只重新读取配置，不中断运行中的任务；restart会停掉所有任务再重新拉起。日常改插件配置用 reload，更新依赖库或者改了核心参数才用 restart。

4.3 把 WSL2 和 Windows 两侧打通

Hermes Agent 跑在 WSL2 里，但它的能力范围并不局限在 Linux 里。两边可以这么协作：

• Linux 侧通过/mnt/c/Users/你的用户名/Desktop/这类路径直接访问 Windows 桌面文件，任务脚本里读 Windows 下的 Excel、日志文件都很方便。
• Windows 侧通过wsl.exe调用 Linux 命令。比如你在 Windows 的脚本或计划任务里执行：

wsl -e hermes --version

• 网络端口互相访问。因为开了localhostForwarding，Windows 浏览器里直接访问http://localhost:8090，就能打开 Hermes Agent 管理面板。

有个细节要单独提醒：WSL2 的虚拟 IP 不是固定的。如果你在代码里硬编码了从 Windows 连 WSL2 的 IP，下次 WSL 重启大概率就失效了。所以跨系统连接，能走 localhost 就走 localhost。只有多台设备访问的场景才需要关注 WSL2 的 IP，通过wsl hostname -I查看。

4.4 一份常用命令速查表

这些命令是我平时用得最多的，直接分享出来：

这里特别说一下优雅停止和强杀的区别。stop会给各插件发送退出信号，让它们有机会保存工作状态并清理临时文件。如果你直接关掉终端或杀掉进程，可能留下半完成的临时文件，下次启动时要额外做清理。

5. 我在 WSL2 场景下踩过的坑和定位思路

5.1 端口能通却连不上：先从 Windows 防火墙查起

有一次我在 Windows 浏览器里访问 Hermes Agent 的管理面板，地址栏输入localhost:8090，结果打不开。但在 WSL2 里用 curl 访问同一个地址是完全通的，说明 agent 本身没问题，问题出在 Windows 侧的连接链路上。

排了一圈之后发现，WSL2 的 localhost 转发依赖 Windows 侧一个叫 vmmem 的进程来监听端口，而 Windows 防火墙默认不会放行这个进程的入站连接。解决办法是用管理员权限在 PowerShell 里加一条防火墙规则：

New-NetFirewallRule -DisplayName "Allow WSL" -Direction Inbound -Action Allow -Program "C:\Windows\System32\vmmem.exe"

注意这里的Program参数指向的是 vmmem 进程，不是某个 Linux 程序。规则加好之后，浏览器立刻就能访问了。如果你以后还遇到"WSL 里服务正常但 Windows 访问不了"的问题，可以优先想想这条链路。

5.2 无故退出还查不到日志：多半是内存被吃完了

Hermes Agent 跑着跑着突然消失，日志里干干净净没有任何异常堆栈，这种情况我遇到过不止一次。后来在 WSL2 里执行dmesg，翻到内核日志才看到 oom-killer 的记录，说明是整个 WSL2 虚拟机的内存被打满了。

WSL2 默认会使用宿主物理内存的 50%，当你同时开着浏览器、IDE、各种服务的时候，这点配额很容易被占满。解决办法不是去调 agent 的参数，而是给 WSL2 定一个明确的内存上限。回到之前说的.wslconfig，把 memory 设成合适值，比如 4GB，swap 设成 2GB，然后执行wsl --shutdown再重进。加了 swap 之后，瞬时内存峰值也有兜底，agent 无故退出的概率会明显下降。

5.3 在 Windows 编辑器里改了配置文件之后，权限直接没了

有次我从 Windows 侧用记事本类工具编辑~/.hermes/config/config.yaml，保存之后再在 WSL2 里执行hermes agent reload，居然提示没有权限读取配置文件。原因很有意思：Windows 编辑器保存文件时，相当于重新创建了一个新文件，这个新文件的所有者变了。原本归属于当前用户的文件，被记事本保存后反而变成了 root 所有。

处理方式很简单：

sudo chown 你的用户名:你的用户名 ~/.hermes/config/config.yaml

另一个常见问题是换行符。Windows 编辑器默认保存为 CRLF 换行，YAML 解析器对 CRLF 的容忍度参差不齐，有的版本会在解析时报错，报错位置还特别诡异。我现在一律在 WSL2 里用vim或 VS Code Remote 编辑配置文件，不碰 Windows 侧的图形编辑器。如果非要用 Windows 工具，记得把换行符改成 LF。

5.4 看着像网络不通，其实是 DNS 配置失效了

还有一个坑比较隐蔽。Agent 的某个插件请求外部 API 时偶尔提示域名解析超时，刚开始我以为是网络波动，排查了半天才发现，WSL2 里的/etc/resolv.conf是自动生成的。Windows 更新或网络切换之后，自动生成的 nameserver 可能已经过期了，导致 WSL2 里的 DNS 解析频繁失败。

遇到类似问题，先在 WSL2 里跑：

cat /etc/resolv.conf

看看 nameserver 是不是还在正常范围。再用nslookup测试一下解析是否正常。临时修复可以手动改 resolv.conf，但 WSL2 启动时会覆盖掉。想固定下来，可以在/etc/wsl.conf里设置：

[network] generateResolvConf = false

然后手动维护一份名为/etc/resolv.conf的文件。做这个之前要慎重，改好了能解决 DNS 飘忽的问题，改坏了整个发行版的所有网络请求都会受影响。

5.5 一个容易被忽略的路径性能问题

最后说一个不是错误但影响体验的点：路径性能。这个我在前面简单提过，但值得展开。如果你把 Hermes Agent 的工作目录放在/mnt/c下的 Windows 盘，跑任务时涉及大量小文件的读写，速度会明显慢于 Linux 原生文件系统，有的场景甚至慢一个数量级。原因在于 /mnt/c 走的是 9P 协议，每次文件操作都要经过一层 Windows 侧的文件系统翻译。

我的建议是：默认把工作目录放在~/hermes-workspace这类 Linux 原生路径下，需要和 Windows 交换文件时再显式复制到/mnt/c。这样既保证了运行时性能，又保留了跨系统文件的便利性。如果你对性能敏感，还可以在.wslconfig里把 Lxss 默认文件系统放到 SSD 上，这里就不展开说了。

整理这些经验的时候，我自己也回忆了一遍当时的迁移过程。最大的感受是：不要在和工具链本身无关的环境问题上消耗精力。Hermes Agent 这类偏向 Linux 生态的智能体框架，放在 WSL2 里跑，本质上就是让它待在最接近官方支持的运行环境中，你省下来的时间可以真正花在任务编排和自动化能力上。

最后分享一个我个人的小习惯：每次对 WSL2 做了配置改动，比如改了.wslconfig或/etc/wsl.conf，我都习惯先执行wsl --shutdown再重进，而不是直接在终端里重启服务。因为 WSL2 的很多底层参数只在虚拟机启动时读取，热切换不生效，容易留下"改了等于没改"的错觉。等你把 WSL2 环境、Hermes Agent 服务、systemd 托管这一套全部理顺，后续的插件安装、任务调度和问题排查都会变得非常省心。