保姆级教程｜Windows WSL2从零部署Hermes Agent，国内网络零报错完整版，快来试试吧，点击主页也有hermes接入飞书的教程哦，真正的变成生产工具！
 

📖 文章前言

Hermes Agent 是 NousResearch 开源的全能本地AI智能代理，支持联网全网检索、浏览器自动化操控、本地代码运行、终端指令执行、本地文件读写、多模态识图等一站式能力，可脱离网页端，自主完成复杂任务。

核心前置限制：该项目暂无原生Windows编译版本，官方仅适配Linux/macOS系统，Windows用户必须依托WSL2 Linux子系统运行，无需重装系统、无需虚拟机分区，微软原生适配，全程仅需重启一次电脑。

本文专属优化：实测Hermes官方安装脚本、Github源码仓库、通义千问官方接口均存在境外网页解析失败、下载超时问题，全文已全部替换国内加速镜像链接，所有命令直接复制即用，无需手动改源、无需魔法上网，纯零基础适配国内网络。
 

---

⚠️ 前置全局须知（必看）

1. 全程操作分为三大阶段：WSL2系统安装→Ubuntu依赖环境配置→Hermes镜像安装+初始化配置，全程耗时10-15分钟

2. 所有终端粘贴快捷键：Windows Powershell右键粘贴；Ubuntu终端使用Ctrl+Shift+V / 鼠标右键 粘贴

3. 下文所有代码均为国内镜像改写版，规避官方源解析失败、连接超时、拉取中断问题

4. 安全提醒：开启终端执行、文件读写权限后，AI可操控本机文件与指令，仅自用可信场景开启即可

---

第一阶段：一键安装 WSL2（预估5分钟，微软原生命令）

步骤1：管理员身份启动PowerShell

操作流程：按下键盘Win键 → 顶部搜索框输入 PowerShell → 右键搜索结果 → 选择【以管理员身份运行】

弹窗系统权限提示：是否允许此应用更改设备？点击【是】即可。

步骤2：执行一键部署命令

在黑色PowerShell窗口内，粘贴下方专属命令，回车执行：

wsl --install

单行命令全自动完成三件事，无需手动勾选配置：

• 自动开启Windows系统WSL2虚拟化功能

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

• 自动适配系统内核、虚拟化驱动，完成环境绑定

等待进度条跑完，终端无报错即为安装完成。

步骤3：重启电脑生效

命令执行完毕后必须重启电脑，否则WSL2内核无法激活，后续Ubuntu会启动失败。

电脑重启后，首次打开Ubuntu终端，自定义设置用户名、登录密码即可（密码输入不显示，输完直接回车）。

---

第二阶段：Ubuntu先试试官方拉取
 

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

但是大概率会失败：你只需要等待即可，所需的基础环境是可以被下载好的（Python、Node.js 等）

当然如果Python和node也超时可以使用这个
 

2.1 统一管理Python版本（固定适配3.11稳定版）

使用pyenv管控Python，规避系统自带版本冲突，依次复制三条命令执行：

# 1.安装pyenv版本管理工具 curl -fsSL https://pyenv.run | bash #

2.下载适配Hermes的Python3.11版本 pyenv install 3.11

# 3.设置全局默认Python版本 pyenv global 3.11

2.2 统一管理Node.js版本（固定适配22稳定版）

官方nvm境外安装页解析失败，直接使用锁定v0.40.0国内适配安装命令，依次执行：

# 1.安装nvm版本管理器 curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.0/install.sh | bash

# 2.下载适配Hermes的Node22版本 nvm install 22

✅核验方式：输入python -V、node -v，输出版本号即为环境配置成功。
 

---

第三阶段：国内镜像安装 Hermes Agent（彻底规避Github拉取失败）

步骤1：放弃官方安装脚本，使用国内镜像克隆源码

原版Github仓库、install.sh脚本网页解析失败，直接使用ghfast国内加速镜像克隆，一键拉取完整源码：

git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git ~/.hermes/hermes-agent

等待源码下载完成，耗时取决于网络速度，耐心等待即可，无中断报错。

步骤2：首次运行环境选型（新手必选）

源码部署完成后，自动弹出运行环境选择界面，各环境释义、适用场景汇总如下：

可选选项	运行含义	适用场景	新手推荐
Local（默认）	本机子系统直接运行	自用本地部署，最常用	✅首选
Docker	容器隔离运行	不想污染本地环境	❌不推荐
Modal	云端无服务器沙箱运行	调用云端算力	❌不推荐
SSH	远程服务器运行	操控外置服务器	❌不推荐
Daytona	持久化云端开发环境	长期云端项目开发	❌不推荐
Singularity/Apptainer	高性能集群容器运行	专业HPC算力集群	❌不推荐
Keep current (local)	保留本机本地运行配置	沿用已有本地设置	✅可直接回车确认

新手操作指令：直接按下Enter回车键，默认确认Local本地运行即可。

步骤3：聊天消息平台绑定选型

该界面用于绑定Telegram、Discord远程对话渠道，本地自用无需配置：

1. Set up messaging now (recommended)：立即绑定社交平台，适合远程管控，需配置平台Token

2. Skip — set up later with hermes setup gateway：跳过配置，后续想用再手动开启

✅新手建议：直接选择第二项Skip跳过，不影响本地核心使用。

---

步骤4：AI大模型接入配置（两种方式，国内通义千问专属适配）

Hermes支持两种模型配置模式，新手优先选快速登录，自备密钥选国内通义千问接口，已适配国内Dashscope接口地址。

方式一：简易命令接入通义千问（自备API密钥）

hermes model

操作流程：输入命令→填入阿里通义千问API_KEY→修改官方境外地址为国内专属BaseURL：

https://dashscope.aliyuncs.com/compatible-mode/v1

方式二：全局初始化配置 hermes setup

1. Quick Setup（推荐新手）：Nous官方门户一键OAuth登录，免费免API密钥，自动适配模型与工具，零配置上手

2. Full setup（进阶用户）：自定义全部AI服务商、工具参数，需自备通义千问、OpenAI等平台密钥，自主管控权限

---

步骤5：功能工具权限开关配置

操作规则：上下箭头切换选项、空格键勾选/取消、回车键保存配置；标注[no API key]代表启用后需补充密钥。

功能选项	核心作用	新手推荐状态	备注
Web Search & Scraping	全网搜索、网页抓取	✅勾选启用	Agent核心能力
Browser Automation	自动操控浏览器点击、输入	✅勾选启用	自动化必备
Terminal & Processes	执行本机终端指令	✅勾选启用	⚠️有系统操作权限，自用开启
File Operations	读写修改本地文件	✅勾选启用	⚠️文件管控权限，自用开启
Code Execution	运行Python等代码脚本	✅勾选启用	注意陌生代码安全
Vision / Image Analysis	图片识别理解	⏸️取消勾选	需额外配置识图密钥
Video Analysis / Generation	视频解析生成	❌取消勾选	资源占用极高
Task Planning / Memory	任务记忆、连贯执行	✅勾选启用	提升AI连贯性
Computer Use (macOS)	macOS桌面操控	❌取消勾选	WSL系统无效

配置完成直接回车保存，后续可随时输入hermes setup重新修改工具权限。

---

步骤6：自动化浏览器引擎选型

选项	资费	新手推荐
Local Browser	免费无密钥，本地无头Chromium	✅默认选中，直接回车确认
Nous Subscription / 第三方云浏览器	付费订阅	❌不推荐
Camofox反爬浏览器	免费	⚠️仅爬虫用户选用

确认后自动部署无界面浏览器，支持网页检索、自动点击操作。

步骤7：文本语音朗读（TTS）选型

✅直接确认默认选中的Microsoft Edge TTS：免费音质佳、无需密钥、联网即用；

无需更换付费 ElevenLabs、Nous官方语音服务，无需本地部署离线语音模型，回车确认即可。

步骤8：图像识图能力配置

默认选中Skip跳过识图配置，完全不影响对话、搜素、代码执行核心功能，后续需要图片分析，可通过/hermes setup、/vision命令补充配置密钥即可，直接回车跳过。

步骤9：全网搜索引擎选型（国内免费最优解）

避雷：Nous官方搜索、Firecrawl、Exa均为付费服务，新手直接二选一免费无密钥搜索引擎：

1. DuckDuckGo (ddgs)：Python原生调用，零密钥、不限次数，首选推荐

2. Parallel：托管免费搜索，无需密钥，备选使用

选中后回车确认，全部配置完成，自动进入Hermes对话主界面，即可正常使用。

---

🔧 文末高频报错FAQ（适配本文镜像环境）

1. Q：官方install.sh下载失败？A：直接放弃官方一键脚本，使用文中ghfast镜像git克隆命令即可

2. Q：nvm/pyenv下载超时？A：复制本文对应固定版本安装命令，不要自行更换外网链接

3. Q：通义千问调用失败？A：核对BaseURL是否为本文国内地址，不要使用官方境外接口

4. Q：WSL启动黑屏？A：管理员PowerShell输入wsl --update更新内核，重启即可
    

   

💻 后期常用运维命令

# 重新全局配置Hermes hermes setup # 单独修改AI模型接口 hermes model # 绑定Telegram/Discord消息渠道 hermes setup gateway