Hermes Agent 安装指南

Windows 11 X64 + WSL2 + Ubuntu 24.04

文档版本：2026.05.07 (最新更新)

Hermes 版本：v0.8.0+ (推荐稳定版)

目标系统：Windows 11 X64 + WSL2

最后更新：2026 年 5 月 7 日

作者：扣子

官方仓库：https://github.com/NousResearch/hermes-agent

官方文档：https://hermes-agent.nousresearch.com/docs

⚠️ 重要提示：执行本指南前请务必执行环境检查流程，确保所有检查项均可观测

0. 前置环境检查

💡 目的：确认系统软硬件是否满足 Hermes 运行环境要求，避免安装过程因环境问题导致失败
📋 检查项目：Windows 版本、虚拟化支持、内存、磁盘空间、WSL 状态

0.1 Windows 系统要求检查

💡 目的：确保 Windows 系统满足 WSL2 运行的基本要求

检查项	最低要求	检查方法	预期结果
操作系统	Windows 11 X64	`winver`	Windows 11 版本 22H2+
虚拟化	必须开启	任务管理器→性能→CPU	虚拟化已启用
内存	8GB+	任务管理器→性能→内存	可用内存 > 4GB
磁盘空间	50GB+	此电脑→C 盘属性	可用空间 > 50GB

0.2 WSL 基础环境检查

💻 执行环境：Windows PowerShell（以管理员身份）
💡 目的：检查 WSL 是否已安装及版本状态，确认 Ubuntu-24.04 发行版可用

执行环境：PowerShell（管理员）

wsl --version

↑ 应显示 WSL 版本号，需 2.0.0+

wsl --list --online

↑ 应显示 Ubuntu-24.04 等可用发行版

wsl --list --verbose

↑ 应显示已安装的 WSL 发行版及状态

0.3 盘符权限检查

💻 执行环境：Windows PowerShell（普通权限即可）
📂 当前路径：任意位置
💡 说明：需要 C 盘权限后才能将文件实际安装到此位置

执行环境：PowerShell

icacls C:\

↑ 应显示当前用户有安全控制权限

dir C:\WSL

↑ 如已存在，应显示其中的文件列表（不存在则报错）

1. WSL2 前置环境配置

💡 目的：配置 WSL2 系统级参数，为 Hermes Agent 运行提供稳定环境
⚠️ 关键说明：Hermes 的 gateway 服务依赖 systemd，WSL2 默认不启用此功能

1.1 WSL2 systemd 启用配置

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：启用 systemd 以支持 Hermes gateway 服务自动启动
📄 配置文件：/etc/wsl.conf

📖 为什么需要 systemd？

Hermes Agent 的 gateway 服务（用于 Web 访问、API 调用等）需要通过 systemd 管理。默认情况下，WSL2 不会启动 systemd，导致 gateway 服务无法正常运行。

执行环境：Bash

sudo bash -c 'cat > /etc/wsl.conf << EOF [boot] systemd=true EOF'

↑ 创建 wsl.conf 配置文件并启用 systemd

cat /etc/wsl.conf

↑ 验证配置文件内容

⚠️ 重要：修改 /etc/wsl.conf 后需要完全关闭 WSL（在 PowerShell 中执行 wsl --shutdown）后重新启动才能生效。

1.2 WSL2 内存限制配置

💻 执行环境：Windows PowerShell
💡 目的：限制 WSL2 使用的内存和 swap 空间，防止 WSL2 占用全部系统资源
📄 配置文件：%USERPROFILE%\.wslconfig（Windows 用户目录）

执行环境：PowerShell

notepad $env:USERPROFILE\.wslconfig

↑ 用记事本打开或创建 .wslconfig 文件

📝 建议的 .wslconfig 配置内容：

[wsl2]
memory=8GB
swap=4GB
processors=4
localhostForwarding=true

执行环境：PowerShell

wsl --shutdown

↑ 重启 WSL 使配置生效

1.3 WSL2 网络模式说明

💡 说明：WSL2 有两种网络模式，理解其区别有助于配置代理和端口转发

网络模式	说明	适用场景
NAT 模式（默认）	WSL2 通过 Windows NAT 访问外部网络	大多数场景，已自动配置
镜像模式	Windows 网络直接镜像到 WSL2	需要 WSL 直接绑定 Windows 网络时启用

💡 提示：如果需要从 WSL2 中使用 Windows 的代理，可以设置 export ALL_PROXY="http://host.docker.internal:7890"（端口号根据实际代理软件调整）。

2. WSL2 安装与配置

💡 目的：在 Windows 上安装 WSL2（Windows Subsystem for Linux）并提供简体中文 Linux 发行版 Hermes
🛠️ 安装内容：WSL2 内核、Ubuntu 24.04 发行版、内存分配、网络配置

2.1 安装 WSL2

💻 执行环境：Windows PowerShell（以管理员身份）
💡 目的：安装 WSL2 内核和虚拟化组件，为 Linux 发行版提供底层支持
⚠️ 注意：执行后需要重启

执行环境：PowerShell（管理员）

wsl --install --no-distribution

↑ 一键安装 WSL 核心，默认使用 WSL2 作为默认版本

dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart

dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart

↑ 备选命令，逐个启用 WSL 可选组件（如上方命令失败）

预期效果：WSL2 内核安装完成，需要重启计算机

验证方式

执行环境：PowerShell

wsl --version

↑ 应显示：WSL 版本 2.x.x，内核版本 5.15.x+

2.2 查看可用的 Ubuntu 发行版

💻 执行环境：Windows PowerShell（管理员或普通权限均可）
💡 目的：↓↓↓ 以下命令 ↓↓↓ 从 Microsoft Store 查询可用的 Ubuntu 发行版列表，确认 Ubuntu 24.04 LTS 可用
📦 发行版选择：Ubuntu 24.04 LTS（长期支持，稳定可靠）

执行环境：PowerShell

wsl --list --online

↑ 显示所有可用的 WSL 发行版列表

wsl --list --online | findstr /i "ubuntu"

↑ 筛选显示 Ubuntu 相关发行版

预期命令输出示例：

NAME                 FRIENDLY VERSION
Ubuntu               Ubuntu              24.04 LTS
Ubuntu-24.04         Ubuntu 24.04 LTS    24.04 LTS
Ubuntu-22.04         Ubuntu 22.04 LTS    22.04 LTS
Ubuntu-20.04         Ubuntu 20.04 LTS    20.04 LTS

✔️ 确认目标：选择 Ubuntu-24.04 发行版安装

2.3 创建 WSL 安装目录

💻 执行环境：Windows PowerShell（管理员）
📂 安装位置：C:\WSL\Ubuntu2404
💡 目的：自定义 WSL 发行版安装目录，便于统一管理和备份

执行环境：PowerShell（管理员）

New-Item -ItemType Directory -Path "C:\WSL\Ubuntu2404" -Force

↑ 创建 WSL 安装目录（如不存在则自动创建）

Test-Path "C:\WSL\Ubuntu2404"

↑ 验证目录是否创建成功

2.4 安装 Ubuntu 24.04 到指定位置

💻 执行环境：Windows PowerShell（管理员或普通权限均可）
📂 安装位置：C:\WSL\Ubuntu2404
💡 目的：↓↓↓ 修改参数 ↓↓↓ 将 Ubuntu 24.04 LTS 安装到 C:\WSL 目录，便于统一管理
📦 发行版选择：Ubuntu 24.04 LTS（长期支持，稳定可靠）

执行环境：PowerShell

wsl --install -d Ubuntu-24.04 --location "C:\WSL\Ubuntu2404"

↑ 从 Microsoft Store 安装 Ubuntu 24.04 LTS 到指定目录

wsl --import Ubuntu-24.04 "C:\WSL\Ubuntu2404" https://aka.ms/wslubuntu2404 --version 2

↑ 可选：手动导入 Ubuntu 24.04 发行版到指定目录

验证方式

执行环境：PowerShell

wsl --list --verbose

↑ 应显示：Ubuntu-24.04 Running（或 Stopped）

wsl -d Ubuntu-24.04 -e uname -r

↑ 验证 WSL 内核版本，确认安装成功

3. 系统环境准备

💻 执行环境：从 Windows PowerShell 启动 WSL2 (Ubuntu 24.04)
💡 目的：在 WSL2 中安装 Hermes 运行所需的系统级工具和依赖项
📦 安装内容：Git、curl、wget、构建工具、Python 开发头、Python 包管理器、Node.js

3.1 启动 WSL 环境

💻 执行环境：Windows PowerShell → WSL2 Bash
💡 目的：从 Windows 终端进入 WSL Ubuntu 命令行，之后的操作在此基础上执行

执行环境：PowerShell

wsl -d Ubuntu-24.04

↑ 从 Windows 终端进入 WSL

ubuntu2404

↑ 或直接在 Ubuntu 终端中输入

3.2 初始化系统

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：更新 APT 软件包列表并安装所有更新，确保使用最新安全补丁和软件版本

执行环境：Bash

sudo apt update && sudo apt upgrade -y

↑ 更新 APT 软件包列表并自动安装更新

验证方式

执行环境：Bash

apt list --upgradable

↑ 应显示：0 个软件包可以升级（所有包已是最新版本）

3.3 安装基础开发工具

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：安装 Hermes 必需的基础开发工具：版本控制、压缩工具、编译环境、Python 开发头、Node.js

执行环境：Bash

sudo apt install -y git curl wget build-essential libssl-dev libffi-dev python3-dev python3-venv python3-pip nodejs npm systemd jq

↑ 安装 Git、cURL、Python 基础开发工具等

验证方式

执行环境：Bash

					git --version
					
					python3 --version
					
					node --version
					
					npm --version

3.4 安装 uv 包管理器

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：Hermes 官方安装脚本使用 uv 而非 pip+venv 管理 Python 环境，uv 速度更快、功能更强
📦 官方脚本：会自动安装 uv，也可手动提前安装

执行环境：Bash

curl -LsSf https://astral.sh/uv/install.sh | sh

↑ 安装 uv 包管理器（官方推荐方式）

source $HOME/.local/bin/env

↑ 加载 uv 环境变量

⚠️ 重要：如果安装过程中出现 ~/.local/bin is not on your PATH 警告，说明 PATH 未包含该目录。Hermes 的可执行文件安装在 ~/.local/bin/，不配置 PATH 将导致 hermes 命令无法直接使用。请务必执行以下命令。

执行环境：Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

↑ 将 ~/.local/bin 持久化添加到 PATH，确保 hermes 等命令开机可用

source ~/.bashrc

↑ 立即生效当前 shell

验证方式

执行环境：Bash

uv --version

↑ 应显示 uv 版本号

3.5 安装 ripgrep

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：官方脚本会检查并建议安装 ripgrep，用于 Hermes 的快速文件搜索功能

执行环境：Bash

sudo apt install -y ripgrep

↑ 安装 ripgrep（快速文件搜索工具）

验证方式

执行环境：Bash

rg --version

↑ 应显示 ripgrep 版本号

3.6 安装 ffmpeg

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：官方脚本会检查并安装 ffmpeg，用于 TTS 语音消息功能（文字转语音）

执行环境：Bash

sudo apt install -y ffmpeg

↑ 安装 ffmpeg（音视频处理工具）

验证方式

执行环境：Bash

ffmpeg -version

↑ 应显示 ffmpeg 版本信息

3.7 安装 Playwright Chromium

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 权限要求：需要 sudo 权限
💡 目的：官方脚本会自动安装 Playwright Chromium，用于浏览器自动化工具（如需要）

执行环境：Bash

sudo apt install -y chromium-browser || sudo apt install -y chromium

↑ 安装 Chromium 浏览器

which chromium || which chromium-browser

↑ 验证 Chromium 安装路径

4. 国内镜像加速配置

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：配置国内镜像源加速下载，解决 GitHub 访问缓慢问题

4.1 配置 GitHub 代理/镜像

💡 说明：通过设置 Git 代理或使用镜像服务加速 GitHub 访问

执行环境：Bash

git config --global url."https://ghproxy.cn/https://github.com".insteadOf "https://github.com"

↑ 使用 ghproxy 镜像加速 GitHub 访问

git config --global url."https://gitclone.com/github.com".insteadOf "https://github.com"

↑ 或使用 gitclone 镜像（可同时配置多个作为备选）

验证方式

执行环境：Bash

git config --global --list | grep url

↑ 应显示配置的 GitHub 镜像地址

4.2 配置 pip 镜像

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：加速 Python 包下载，推荐使用清华或阿里云镜像

执行环境：Bash

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

↑ 配置清华 pip 镜像

pip config set global.index-url https://mirrors.aliyun.com/pypi/simple

↑ 或使用阿里云镜像（二选一）

4.3 配置 npm 镜像

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：加速 Node.js 包下载

执行环境：Bash

npm config set registry https://registry.npmmirror.com

↑ 配置 npmmirror 国内镜像

npm config set registry https://registry.npm.taobao.org

↑ 或使用淘宝镜像（二选一）

4.4 配置系统代理（可选）

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 说明：如果使用代理软件（如 Clash、V2Ray），可配置系统级代理

执行环境：Bash

export http_proxy="http://172.30.160.1:7890"

export https_proxy="http://172.30.160.1:7890"

↑ 配置 HTTP/HTTPS 代理（IP 和端口根据实际代理软件调整）

💡 提示：WSL2 中 Windows 主机通常通过 172.30.160.1 或 host.docker.internal 访问。
如使用代理软件，可查看其"允许局域网连接"设置获取端口号。

5. Hermes Agent 安装方式

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 说明：以下提供三种安装方式，推荐使用方式一（官方脚本安装）

5.1 方式一：官方脚本安装（推荐）

🎯 官方推荐方式 - 一键安装

官方安装脚本会自动处理：uv 包管理器安装、Python 环境配置、Node.js 安装、依赖安装、Playwright Chromium 安装、配置模板复制等。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用官方一键安装脚本，自动完成所有安装步骤
📦 安装内容：uv、Python 3.11、Node.js 22、ripgrep、ffmpeg、Playwright Chromium、hermes 命令行

5.1.1 安装到默认位置

执行环境：Bash

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

↑ 官方一键安装脚本，自动安装到 ~/.hermes/hermes-agent

5.1.2 安装到 ~/Hermes/ 目录

💡 说明：使用 --dir 和 --hermes-home 参数指定安装目录到 ~/Hermes/

执行环境：Bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --dir ~/Hermes/hermes-agent --hermes-home ~/Hermes

↑ 安装到 ~/Hermes/ 目录结构

5.1.3 官方脚本支持的参数

参数	说明	默认值
`--dir PATH`	安装目录（代码存放位置）	~/.hermes/hermes-agent
`--hermes-home PATH`	数据目录（配置、会话等）	~/.hermes
`--no-venv`	不创建虚拟环境	否
`--skip-setup`	跳过交互式配置向导	否
`--branch NAME`	Git 分支名	main

✅ 安装脚本会自动处理：

安装 uv 包管理器（到 ~/.local/bin/uv）
通过 uv 安装 Python 3.11（如系统没有）
安装 Node.js 22（如系统没有，装到 ~/.hermes/node/）
检查并建议安装 ripgrep 和 ffmpeg
克隆仓库到指定目录
创建 venv 并安装 Python 依赖
安装 Node.js 依赖（npm install）
安装 Playwright Chromium
创建 hermes 命令符号链接
复制配置模板到 ~/.hermes/
运行交互式 setup 向导
可选安装 gateway systemd 服务

验证安装

执行环境：Bash

hermes version

↑ 确认 Hermes 已安装成功，显示版本号

5.2 方式二：Git 镜像拉取安装

🔀 国内加速方式 - 使用 GitHub 镜像

当 GitHub 直接访问困难时，使用国内镜像服务加速克隆，然后手动完成安装。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用国内 GitHub 镜像加速克隆仓库

执行环境：Bash

mkdir -p ~/Hermes

↑ 创建安装目录

cd ~/Hermes

git clone --depth 1 https://ghproxy.cn/https://github.com/NousResearch/hermes-agent.git

↑ 使用 ghproxy 镜像克隆（浅克隆，节省时间）

cd hermes-agent

↑ 进入项目目录

5.2.1 常用 GitHub 镜像地址

镜像名称	地址	使用方式
ghproxy	https://ghproxy.cn	在 Git URL 前加 https://ghproxy.cn/
gitclone	https://gitclone.com	在 Git URL 前加 https://gitclone.com/github.com/
gitee	（需手动同步）	推荐使用 Gitee 导入 GitHub 仓库

5.2.2 使用 Gitee 导入（可选）

💡 说明：如果镜像访问也不稳定，可以使用 Gitee 导入 GitHub 仓库

📝 Gitee 导入步骤：

访问 https://gitee.com 并登录
点击"从 GitHub 导入仓库"
输入：https://github.com/NousResearch/hermes-agent
导入完成后，在 Gitee 仓库页面获取克隆地址
使用 Gitee 地址克隆：git clone https://gitee.com/你的用户名/hermes-agent.git

5.2.3 手动完成安装

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
📂 当前路径：~/Hermes/hermes-agent
💡 目的：克隆完成后，手动完成 Python 环境配置和依赖安装

执行环境：Bash

python3 -m venv venv

↑ 创建 Python 虚拟环境

source venv/bin/activate

↑ 激活虚拟环境

pip install -e .

↑ 以可编辑模式安装 Hermes Agent

npm install

↑ 安装 Node.js 依赖

npx playwright install chromium

↑ 安装 Playwright Chromium（如需要浏览器功能）

⚠️ 重要：如果 hermes 命令提示找不到，需要手动添加 PATH：

执行环境：Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

↑ 将 ~/.local/bin 添加到 PATH

source ~/.bashrc

↑ 立即生效

验证安装

执行环境：Bash

hermes version

↑ 确认 Hermes 已安装成功，显示版本号

5.3 方式三：源码下载安装

📦 直接下载方式 - GitHub Releases

不想使用 Git 时，可以直接从 GitHub Releases 页面下载源码压缩包，解压后本地安装。

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：通过下载源码包方式安装，无需 Git

执行环境：Bash

mkdir -p ~/Hermes && cd ~/Hermes

↑ 创建并进入安装目录

curl -L https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz -o hermes-agent.tar.gz

↑ 下载 main 分支源码（tar.gz 格式）

tar -xzf hermes-agent.tar.gz

↑ 解压源码包

mv hermes-agent-main hermes-agent

↑ 重命名目录

cd hermes-agent

↑ 进入项目目录

5.3.1 使用镜像加速下载

执行环境：Bash

curl -L https://ghproxy.cn/https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.tar.gz -o hermes-agent.tar.gz

↑ 使用 ghproxy 镜像加速下载

5.3.2 手动完成安装

执行环境：Bash

python3 -m venv venv && source venv/bin/activate

↑ 创建并激活虚拟环境

pip install -e .

↑ 以可编辑模式安装

npm install && npx playwright install chromium

↑ 安装 Node 依赖和 Playwright（如需要）

⚠️ 重要：如果 hermes 命令提示找不到，需要手动添加 PATH：

执行环境：Bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc

↑ 将 ~/.local/bin 添加到 PATH

source ~/.bashrc

↑ 立即生效

验证安装

执行环境：Bash

hermes version

↑ 确认 Hermes 已安装成功，显示版本号

6. 安装后验证

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：验证 Hermes Agent 安装成功，所有组件正常工作

6.1 验证 Hermes 命令

执行环境：Bash

hermes version

↑ 应显示 Hermes 版本号，确认安装成功

hermes --help

↑ 应显示 Hermes 可用命令列表

6.2 验证 Gateway 服务

💡 说明：如果使用官方脚本安装了 gateway systemd 服务，可以验证服务状态

执行环境：Bash

systemctl --user status hermes-gateway.service

↑ 查看 gateway 服务状态（如已安装 systemd 服务）

journalctl --user -u hermes-gateway.service -f

↑ 查看 gateway 服务日志（Ctrl+C 退出）

6.3 启动首次配置

💡 说明：首次使用前建议运行 setup 向导配置 API Key 等参数

执行环境：Bash

hermes setup

↑ 运行交互式配置向导

7. 常用命令参考

7.1 Hermes 基础命令

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
🔐 虚拟环境：建议激活
💡 目的：Hermes 命令的基本用法，包括对话、会话管理和历史会话

执行环境：Bash

hermes version

↑ 查看 Hermes 版本号，确认安装成功

hermes chat

↑ 开始新的对话会话

hermes --continue

↑ 继续上一个未完成的会话

hermes --resume <session_id>

↑ 恢复指定 ID 的历史会话

hermes setup

↑ 运行初始化配置向导（API Key 等）

7.2 配置管理

💡 目的：查看或修改 Hermes 配置文件 (config.yaml) 中的参数，支持字段直接编辑文件

执行环境：Bash

hermes config

↑ 显示当前配置参数

hermes config set <key> <value>

↑ 设置指定配置项的新值

hermes config get <key>

↑ 获取指定配置项的当前值

hermes config delete <key>

↑ 删除指定配置项，恢复默认值

7.3 会话管理

💡 目的：管理历史对话会话，支持查看、删除和导出会话记录

执行环境：Bash

hermes sessions

↑ 列出所有历史会话

hermes sessions delete <session_id>

↑ 删除指定会话记录

hermes sessions export <session_id>

↑ 导出指定会话为文件

7.4 技能管理

💡 目的：管理 Hermes 的技能库，包括预设模板、自定义技能或特定任务执行

执行环境：Bash

hermes skills

↑ 列出所有可用技能

hermes skills enable <skill_name>

↑ 启用指定技能

hermes skills disable <skill_name>

↑ 禁用指定技能

hermes skills create <skill_name>

↑ 创建自定义技能模板

8. 卸载与更新

8.1 卸载 Hermes Agent

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：完全卸载 Hermes Agent 及相关配置

执行环境：Bash

hermes uninstall

↑ 官方交互式卸载命令，按提示确认即可

↑ 如果 hermes uninstall 不可用，可手动执行以下命令：

rm -rf ~/.hermes

↑ 删除配置和数据目录（如 ~/.hermes 存在）

rm -rf ~/Hermes/hermes-agent

↑ 删除安装目录（根据实际安装位置调整）

rm -f ~/.local/bin/hermes

↑ 删除 hermes 命令符号链接

8.2 更新 Hermes Agent

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：更新到最新版本

方式一：使用 Git 更新

执行环境：Bash

cd ~/Hermes/hermes-agent && git pull

↑ 拉取最新代码

pip install -e . --upgrade

↑ 重新安装并更新依赖

方式二：使用官方脚本更新

执行环境：Bash

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

↑ 重新运行安装脚本即可更新到最新版本

9. 排错指南

💡 目的：列出常见安装问题及解决方案

9.1 安装相关问题

问题：官方安装脚本下载失败

症状：curl 或 wget 下载 install.sh 超时或连接失败

解决方案：

使用镜像地址：curl -fsSL https://ghproxy.cn/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash
检查网络代理设置
尝试手动克隆仓库后运行本地脚本

问题：pip 安装依赖失败

症状：pip install 报错，提示某个包安装失败

解决方案：

配置 pip 镜像：pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple
更新 pip：pip install --upgrade pip
使用 uv 替代 pip：uv pip install -e .

问题：npm install 失败

症状：npm 安装依赖时报错

解决方案：

配置 npm 镜像：npm config set registry https://registry.npmmirror.com
清除缓存后重试：npm cache clean --force && npm install

9.2 运行相关问题

问题：hermes 命令找不到

症状：执行 hermes 提示 command not found

解决方案：

确认虚拟环境已激活：source venv/bin/activate
检查 PATH 环境变量：echo $PATH
使用完整路径执行：./venv/bin/hermes
检查是否安装成功：pip show hermes-agent

问题：systemctl 命令失败（systemd 未启用）

症状：执行 systemctl --user 命令报错

解决方案：

确认 /etc/wsl.conf 中已配置 systemd=true
完全关闭 WSL：wsl --shutdown
重新启动 WSL 后再试

问题：WSL2 占用过多内存

症状：WSL2 使用后系统变卡，内存占用过高

解决方案：

在 Windows 用户目录创建 .wslconfig 文件
添加配置：memory=8GB、swap=4GB
执行 wsl --shutdown 重启 WSL

问题：Playwright Chromium 安装失败

症状：npx playwright install chromium 报错

解决方案：

安装系统依赖：sudo apt install -y chromium-browser
或手动下载 Chromium：npx playwright install chromium --with-deps
跳过 Playwright 安装，后续不需要浏览器功能时可以忽略此步骤

问题：权限被拒绝（Permission denied）

症状：安装或运行时提示权限错误

解决方案：

使用 sudo 运行需要管理员权限的命令
检查文件权限：ls -la
修复权限：chmod +x 需要的脚本

9.3 查看日志

💡 目的：通过日志排查问题

执行环境：Bash

hermes --verbose

↑ 启用详细输出模式

journalctl --user -u hermes-gateway.service --since "1 hour ago"

↑ 查看 gateway 服务最近 1 小时日志

cat ~/.hermes/logs/*.log

↑ 查看 Hermes 日志文件

附录 A：快速安装脚本

💻 执行环境：WSL2 Bash (Ubuntu 24.04)
💡 目的：使用官方一键安装脚本自动化完成全部安装流程，适合快速测试或全新安装

A.1 标准安装（推荐默认位置）

执行环境：Bash

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

↑ 官方一键安装脚本，自动完成环境配置、依赖安装、初始化设置

A.2 安装到 ~/Hermes/ 目录

执行环境：Bash

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --dir ~/Hermes/hermes-agent --hermes-home ~/Hermes

↑ 自定义安装目录参数

A.3 使用镜像加速安装

执行环境：Bash

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

↑ 使用 ghproxy 镜像加速下载

📕 文档验证：

安装完成后，可通过以下命令验证：

执行环境：Bash

hermes version

↑ 确认 Hermes 安装成功

systemctl --user status hermes-gateway.service

↑ 确认 gateway 服务运行（如已安装）

如遇到问题，查看日志或联系技术支持。