Windows WSL 安装 Hermes Agent 完整指南
本文详细介绍如何在 Windows 系统上开启 WSL 子系统并使用官方一键安装脚本安装 Hermes Agent，让你在 Windows 环境下也能享受 Linux 的强大功能。
为什么选择 WSL？
Hermes Agent 是一个强大的 AI 代理框架，原生支持 Linux 和 macOS 环境。虽然 Windows 也可以运行，但使用 WSL 有以下优势：
- 完整的 Linux 环境支持，兼容性更好
- 可以使用 Linux 特有的工具和命令
- 性能更优，特别是在处理文件系统和网络操作时
- 与 Windows 文件系统无缝集成
- 官方推荐在 Windows 上使用 WSL2
系统要求
- Windows 版本：Windows 10 版本 2004 及以上（内部版本 19041 及以上）或 Windows 11
- 内存：至少 8GB RAM（推荐 16GB）
- 磁盘空间：至少 10GB 可用空间
- CPU：支持虚拟化（BIOS 中开启 VT-x/AMD-V）
第一步：开启 WSL 功能
- 打开控制面板 → 程序和功能 → 打开或关闭 Windows 功能
- 勾选以下两项：
- ✅ 适用于 Linux 的 Windows 子系统
- ✅ 虚拟机平台
- 点击确定，等待安装完成后重启电脑
第二步：安装 Ubuntu
重启后，以管理员身份打开 PowerShell 或命令提示符，执行：
wsl --install Ubuntu-24.04
安装完成后，系统会自动启动 Ubuntu，要求你设置用户名和密码。
验证 WSL 版本
wsl --version
确保显示的是 WSL 2 版本。如果显示 WSL 1，可以转换：
wsl --set-version Ubuntu-24.04 2
第三步：安装 Hermes Agent
3.1 使用官方一键安装脚本
Hermes Agent 提供了官方一键安装脚本，这是最简单快捷的安装方式：
# 下载并运行官方安装脚本
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
安装脚本会自动完成以下操作：
- 检测系统环境
- 安装必要的依赖
- 下载 Hermes Agent 源码
- 创建虚拟环境
- 安装 Python 依赖
- 配置环境变量
3.2 验证安装
# 检查 Hermes 版本
hermes --version
# 查看帮助信息
hermes --help
# 运行健康检查
hermes doctor
3.3 初始化配置
# 运行交互式设置向导
hermes setup
# 或者分步配置
hermes setup model # 配置模型
hermes setup terminal # 配置终端
hermes setup gateway # 配置消息网关
3.4 配置 API 密钥
# 编辑环境变量文件
hermes config env-path
# 添加 API 密钥（示例）
echo "ANTHROPIC_API_KEY=*** >> ~/.hermes/.env
echo "OPENAI_API_KEY=*** >> ~/.hermes/.env
第四步：启动和使用
4.1 启动交互式会话
# 启动 Hermes Agent 交互模式
hermes
# 或者直接提问
hermes -q "你好，请介绍一下你自己"
4.2 启动消息网关
# 配置消息平台（Telegram、Discord 等）
hermes gateway setup
# 安装为系统服务
hermes gateway install
# 启动网关
hermes gateway start
# 查看状态
hermes gateway status
4.3 常用命令
# 查看配置
hermes config
# 管理工具
hermes tools
# 管理技能
hermes skills list
# 查看会话
hermes sessions list
# 更新 Hermes
hermes update
常见问题与解决方案
问题 1: WSL 安装失败
症状：安装过程中出现错误提示
解决方案：
# 检查虚拟化是否开启
# 在任务管理器 -> 性能 -> CPU 中查看"虚拟化"是否已启用
# 如果未启用，需要在 BIOS 中开启
# 重启电脑，进入 BIOS 设置
# 找到 Intel VT-x 或 AMD-V 选项并启用
# 重新安装 WSL
wsl --install
问题 2: 内存不足
症状：WSL 运行缓慢或崩溃
解决方案：创建 .wslconfig 文件限制 WSL 资源使用
# 在 Windows 用户目录下创建 .wslconfig 文件
# C:\Users\YourUsername\.wslconfig
[wsl2]
memory=8GB # 限制 WSL 最大内存
processors=4 # 限制 CPU 核心数
swap=4GB # 交换空间大小
问题 3: Hermes 命令找不到
症状：运行 hermes 命令提示 "command not found"
解决方案：
# 检查安装路径
ls -la ~/.hermes/
# 重新加载环境变量
source ~/.bashrc
# 或者手动添加到 PATH
export PATH="$HOME/.hermes/bin:$PATH"
# 永久添加到 .bashrc
echo 'export PATH="$HOME/.hermes/bin:$PATH"' >> ~/.bashrc
问题 4: API 密钥配置失败
症状：Hermes 无法连接到 AI 模型
解决方案：
# 检查 .env 文件
cat ~/.hermes/.env
# 重新配置
hermes auth add anthropic
hermes auth add openai
# 验证配置
hermes doctor
问题 5: WSL 与 Windows 文件访问
症状：在 WSL 中访问 Windows 文件很慢
解决方案：
# Windows 文件在 WSL 中挂载在 /mnt/ 下
# 例如：C:\Users 对应 /mnt/c/Users
# 建议将项目文件放在 WSL 文件系统中
# 例如：~/projects/ 而不是 /mnt/c/Users/.../projects/
# 访问 Windows 文件
cd /mnt/c/Users/YourUsername/Documents
# 访问 WSL 文件（从 Windows）
# 在资源管理器地址栏输入：\\wsl$\Ubuntu-22.04\home\yourusername
性能优化建议
1. 使用 WSL2 而不是 WSL1
# 检查 WSL 版本
wsl -l -v
# 转换到 WSL2
wsl --set-version Ubuntu-22.04 2
2. 配置 VS Code 远程开发
使用 VS Code 的 Remote - WSL 扩展可以获得更好的开发体验：
- 代码补全和语法高亮
- 集成终端
- 调试支持
- 扩展同步
3. 定期更新系统
# 更新 WSL 系统
sudo apt update && sudo apt upgrade -y
# 更新 Hermes
hermes update
# 更新 Windows
# 在 Windows 设置中检查更新
4. 备份配置
# 备份 Hermes 配置
tar -czf hermes-backup-$(date +%Y%m%d).tar.gz ~/.hermes/
# 恢复配置
tar -xzf hermes-backup-YYYYMMDD.tar.gz -C ~/
进阶使用
配置多个 AI 模型
# 使用交互式配置
hermes model
# 或者直接编辑配置
hermes config edit
创建自定义技能
# 查看现有技能
hermes skills list
# 创建新技能
mkdir -p ~/.hermes/skills/my-skill
cd ~/.hermes/skills/my-skill
# 创建 SKILL.md 文件
cat > SKILL.md << 'EOF'
---
name: my-skill
description: 我的自定义技能
version: 1.0.0
---
# 我的技能
## 触发条件
- 当用户请求...
## 操作步骤
1. ...
2. ...
EOF
配置消息平台集成
# 配置 Telegram
hermes gateway setup
# 选择 Telegram 并按提示配置
# 需要 Telegram Bot Token
# 启动网关
hermes gateway start
参考资源
总结
通过本教程，你已经成功在 Windows 上配置了 WSL 环境并安装了 Hermes Agent。现在你可以：
- 在 Windows 上使用完整的 Linux 环境
- 运行 Hermes Agent 进行 AI 任务自动化
- 集成各种消息平台（Telegram、Discord 等）
- 创建自定义技能和工具
如果遇到问题，可以查看官方文档或在 GitHub 上提交 issue。祝你使用愉快！
最后更新：2026-07-02