文档说明

本文整合资料，为 Windows 系统通过 WSL2 子系统部署 Hermes Agent 提供全套可落地教程。全程命令可直接复制执行，零基础可轻松跟随操作。

重要提示：Hermes Agent 不支持 Windows 原生直接运行，必须依托 WSL2 + Ubuntu 环境部署。

一、部署环境硬性要求

• 系统版本：Windows 10 2004 及以上 / Windows 11 全版本

• 网络要求：网络稳定，支持正常访问国内网络

• 权限要求：全程需使用管理员权限执行命令

• 磁盘空间：预留至少 10GB 空闲空间

二、前置准备工作

• 临时关闭第三方安全软件、防火墙，避免拦截 WSL2 组件安装

• 确保系统未禁用「虚拟机平台、适用于 Linux 的 Windows 子系统」功能

• 提前准备大模型 API Key（后续初始化需使用）

三、详细部署全流程

步骤1：以管理员身份打开 PowerShell

1. 右键点击电脑开始菜单

2. 选择「Windows PowerShell(管理员)」或「终端(管理员)」

3. 弹出用户账户控制提示，点击「是」完成授权

步骤2：一键安装 WSL2 + Ubuntu 子系统

在管理员 PowerShell 中执行以下命令：

wsl --install

执行说明：

• 系统自动启用虚拟机平台、WSL 相关功能

• 自动下载并安装官方默认 Ubuntu 发行版

• 命令执行完毕后，必须重启电脑，否则无法正常进入 Ubuntu 子系统

步骤3：Ubuntu 首次账号初始化

1. 电脑重启后，从开始菜单打开「Ubuntu」应用

2. 等待系统自动完成初始化部署（耗时约1-3分钟）

3. 按控制台提示，设置自定义用户名和登录密码（密码输入时无屏幕显示，正常输入后回车即可，务必牢记）

步骤4：替换 Ubuntu 24.04 阿里云国内源

进入 Ubuntu 终端，依次执行以下命令，替换官方源为阿里云镜像，解决下载慢、超时问题：

# 备份原有源配置文件
sudo cp /etc/apt/sources.list.d/ubuntu.sources /etc/apt/sources.list.d/ubuntu.sources.bak 

# 替换为阿里云镜像源
sudo sed -i 's|http://archive.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources 

sudo sed -i 's|http://security.ubuntu.com|https://mirrors.aliyun.com|g' /etc/apt/sources.list.d/ubuntu.sources

步骤5：更新系统软件包并升级

sudo apt update && sudo apt upgrade -y

作用：刷新国内源软件列表，升级系统自带依赖，为 Hermes Agent 安装做好环境铺垫。

步骤6：安装 Hermes Agent 必备运行依赖

sudo apt install -y curl git python3.11 python3.11-venv nodejs ripgrep ffmpeg

步骤7：一键安装 Hermes Agent 主程序

使用国内镜像安装脚本，高速稳定部署，无需手动干预：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

脚本将自动完成下载、解压、环境变量配置。

步骤8：初始化配置并启动 Hermes Agent

# 初始化配置，按提示填写模型 API Key 等信息
hermes init 

# 启动 Hermes Agent
hermes

步骤9：环境健康检测（验证部署结果）

hermes doctor

若检测结果全部显示绿色正常，说明部署完成，环境可正常使用。

四、常见问题与报错排查

1. 执行 wsl --install 命令报错

• 原因：Windows 版本过低，或手动禁用了虚拟机相关功能

• 解决：升级 Windows 至要求版本；打开「启用或关闭 Windows 功能」，勾选「虚拟机平台、适用于 Linux 的 Windows 子系统」，重启电脑后重新执行命令。

2. sudo 命令提示权限错误

• 解决：确认终端为管理员身份；核对 Ubuntu 登录密码，确保输入正确。

3. apt 更新超时、下载失败

• 解决：重新执行步骤4的源替换命令；检查网络是否正常，关闭代理拦截。

4. 提示 hermes 命令找不到

• 解决：关闭 Ubuntu 终端并重新打开，让环境变量生效；或重新执行步骤7的安装脚本。

五、日常快速启动方法

部署完成后，后续使用无需重复配置，操作如下：

1. 打开 Windows 终端或 Ubuntu 应用

2. 直接执行命令：

hermes

六、重要注意事项

• 禁止在 Windows 原生 CMD、PowerShell 中直接安装 Hermes Agent，仅支持 WSL2 Ubuntu 环境。

• Ubuntu 登录密码需妥善保存，所有 sudo 管理员操作均需验证该密码。

• 替换镜像源后，必须执行 sudo apt update 命令，否则新源无法生效。

• 后续升级 Hermes Agent，直接重新执行步骤7的安装脚本即可完成覆盖更新。