先说一个核心判断：在 WSL2 环境中安装 Hermes Agent v0.19.0 时，卡在 npm install 或 hermes setup 阶段，绝大多数情况并非网络延迟或磁盘 I/O 瓶颈——典型表现是光标完全停滞，CPU 占用降至零，终端长时间无响应，甚至连错误日志都不输出。根本原因在于 WSL2 默认未挂载 /dev/shm 共享内存路径，而 v0.19.0 新引入的 Worker Thread 并发模型恰好依赖该目录——Node.js 在初始化 SharedArrayBuffer 时会在内核级直接挂起，一直等待那块内存区域出现，结果便是无限等待。

确认是否真正被卡住

先别急着重装，请执行两步确认操作。首先，输入 wsl -l -v 查看 Ubuntu 发行版状态是否为 Running；其次，运行 ls -l /dev/shm。如果返回 ls: cannot access '/dev/shm': No such file or directory，则问题已锁定——WSL2 内核根本没有挂载该目录，v0.19.0 启动时便会陷入无限等待，直到你手动按下 Ctrl+C 或超时。

强制挂载 /dev/shm 并实现持久化

先临时挂载验证可行性：sudo mkdir -p /dev/shm && sudo mount -t tmpfs tmpfs /dev/shm。若此命令能成功执行，说明系统本身无问题，仅缺少自动挂载配置。

接着写入 /etc/fstab 以实现重启后自动生效：sudo nano /etc/fstab，在末尾添加一行 tmpfs /dev/shm tmpfs defaults,size=2g 0 0。注意 size=2g 参数不可省略——WSL2 默认分配给 tmpfs 仅 64MB，v0.19.0 多线程加载模型时内存一紧张便直接触发 OOM，且不给出任何提示。

退出当前 shell，重新打开一个 WSL2 终端，再次运行 ls -l /dev/shm。若看到 drwxrwxrwt 2 root root 40 ... 且权限位包含 t（sticky bit），说明挂载成功，可以继续下一步。

修复 WSL2 内核版本兼容性

推荐做法：将 WSL2 内核升级至 5.15 及以上版本。在 Windows PowerShell（管理员模式）中执行 wsl --update，等待下载完成后，再执行 wsl --shutdown，然后重新打开 Ubuntu 终端。使用 uname -r 确认输出是否为 5.15.x 或更高。低于 5.10 的内核存在 shm 挂载的竞态缺陷，即使手动挂载，在高负载下也可能失效。

兜底方案：若 wsl --update 失败，可从 WSL 官方发布页下载 wsl_update_x64.msi 手动安装。不过旧版内核虽然稳定，但对 v0.19.0 某些新特性的支持有限——仅推荐作为最后手段使用。

【关键前提】无论升级还是降级，务必在操作后执行 wsl --shutdown，否则内核不会真正切换。许多用户卡死就是因为跳过了这一步，以为关闭终端窗口就等同于重启。

清理残留并重新尝试安装

一条命令清除旧环境：rm -rf ~/.hermes ~/.local/bin/hermes ~/code/hermes-agent。然后清空 npm 缓存：npm cache clean --force。重新拉取 v0.19.0 源码：git clone --branch v0.19.0 https://github.com/ai-hermes/hermes-agent.git ~/code/hermes-agent。

进入目录后，先运行诊断命令 hermes doctor --fix。该命令会自动检测 /dev/shm 权限、locale 编码、Python 虚拟环境完整性，并尝试一键修复——比你自己逐一排查省心得多。最后执行安装：cd ~/code/hermes-agent && npm install && npm run build && sudo npm install -g .。如果一切顺利，安装过程应该流畅许多，不再卡在初始化阶段。