WSL2安装Hermes Agent v0.19.0卡在npm install或hermes setup阶段，本质是/dev/shm未挂载导致SharedArrayBuffer初始化阻塞；需手动创建并持久化挂载tmpfs到/dev/shm（指定size=2g），升级WSL2内核至5.15+，执行wsl --shutdown后清理旧环境并运行hermes doctor --fix修复。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
WSL2环境安装Hermes Agent v0.19.0时卡在npm install或hermes setup阶段，光标长时间静止、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启动时会无限等待，直到超时或手动中断。
强制挂载/dev/shm并持久化
第一步：临时挂载（验证是否生效）
在WSL2终端中执行：sudo mkdir -p /dev/shm && sudo mount -t tmpfs tmpfs /dev/shm
第二步：写入fstab实现重启后自动挂载
执行sudo nano /etc/fstab，在文件末尾新增一行：tmpfs /dev/shm tmpfs defaults,size=2g 0 0。注意不要漏掉size=2g参数，否则WSL2默认只分配64MB，v0.19.0多线程加载模型时仍会OOM。
第三步：退出当前shell，重新打开一个WSL2终端，再次运行ls -l /dev/shm。若显示drwxrwxrwt 2 root root 40 Jun 12 10:23 /dev/shm，且权限含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 .
