Eileen'blog

Hermes Agent 安装指南

2026-05-09T05:02:00 文章

📋 目录

  1. 环境准备
  2. 安装 Hermes Agent
  3. 配置 API Key
  4. 启动和使用
  5. Web UI 部署（图形化界面）
  6. 常见问题与解决方案
  7. 快速参考卡片
  8. 有用链接

环境准备

1.1 安装 WSL2（Windows 用户）

具体可以参考另外一篇WSL2安装教程。

以管理员身份打开 PowerShell，执行：

wsl --install

重启电脑后，从开始菜单启动 Ubuntu。

1.2 更新系统

进入 WSL 终端后：

apt update && apt upgrade -y

安装 Hermes Agent

2.1 国内镜像安装（推荐）

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

2.2 安装过程详解

脚本会自动执行以下步骤：

步骤说明预计时间
1/7识别系统环境5秒
2/7准备 Python 运行环境10秒
3/7检查基础工具（ripgrep、ffmpeg）5秒
4/7获取 Hermes 代码（约144MB）1-3分钟
5/7创建虚拟环境30秒
6/7安装 Python 依赖2-5分钟
7/7配置命令和配置文件30秒

配置 API Key

3.1 方式一：配置向导（推荐）

hermes setup

向导流程：

  1. 输入 1（快速设置模式）
  2. 选择模型供应商：DeepSeek 输入 11
  3. 粘贴 API Key（不会显示字符，直接回车）
  4. 选择模型：deepseek-v4-flash 输入 3
  5. 消息平台：选择 2 跳过

3.2 方式二：手动配置

nano ~/.hermes/.env

添加以下内容：

DEEPSEEK_API_KEY=sk-你的真实Key

保存：Ctrl+X → Y → Enter

3.3 验证配置

cat ~/.hermes/.env | grep DEEPSEEK
hermes doctor

启动和使用

4.1 终端聊天（TUI）

hermes

4.2 常用命令

命令功能
hermes启动聊天界面
hermes doctor健康检查
hermes config查看配置
hermes model切换模型
hermes update更新 Hermes

4.3 快捷启动脚本

创建一键启动脚本：

cat > ~/start_hermes.sh << 'EOF'
#!/bin/bash
cd /root/.hermes/hermes-agent
source /root/.bashrc
hermes
EOF

chmod +x ~/start_hermes.sh

以后只需运行：~/start_hermes.sh

4.4 Windows 桌面快捷方式

  1. 桌面右键 → 新建 → 快捷方式
  2. 位置输入：wsl.exe ~/start_hermes.sh
  3. 命名为 Hermes Agent

Web UI 部署（图形化界面）

5.1 方式一：官方仪表盘（最轻量）

# 安装依赖
cd /root/.hermes/hermes-agent
/root/.hermes/hermes-agent/venv/bin/python -m pip install fastapi uvicorn

# 启动
hermes dashboard

浏览器访问：http://localhost:8642

5.2 方式二：Docker 部署（推荐）

这是最稳定、最简单的方式：

docker run -d \
  --name hermes-webui \
  -p 3001:3001 \
  -v ~/.hermes:/app/.hermes \
  -v ~/.hermes-web-ui:/app/data \
  -e HERMES_CONFIG_DIR=/app/.hermes \
  --restart unless-stopped \
  docker.1ms.run/nesquena/hermes-webui:latest

浏览器访问：http://localhost:3001

5.3 方式三：npm 安装 Web UI

# 安装 Node.js
apt update && apt install -y nodejs npm

# 安装 Web UI
npm install -g hermes-web-ui

# 启动
hermes-web-ui start --upstream http://127.0.0.1:18642

浏览器访问：http://localhost:8648

常见问题与解决方案

6.1 安装问题

问题：curl: (7) Failed to connect to raw.githubusercontent.com

原因：GitHub 在国内访问不稳定

解决方案：使用国内镜像

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

问题：安装卡在“正在安装 python3-venv”

原因：系统正在安装虚拟环境组件，需要时间

解决方案：耐心等待 1-3 分钟，不要按 Ctrl+C

问题：安装完成后 hermes: command not found

解决方案：

source ~/.bashrc
# 或
export PATH="$HOME/.local/bin:$PATH"

6.2 配置问题

问题：配置向导提示 API Error 500

原因：API Key 无效、格式错误或余额不足

解决方案：

  1. 检查 Key 是否以 sk- 开头
  2. 登录 DeepSeek 开放平台 确认 Key 有效且有余额
  3. 重新配置：hermes model

问题：.env 文件中有重复的 API Key

解决方案：

sed -i '/DEEPSEEK_API_KEY/d' ~/.hermes/.env
echo "DEEPSEEK_API_KEY=sk-你的Key" >> ~/.hermes/.env

6.3 Web UI 连接问题

问题：Web UI 显示“未连接”

原因：Gateway 服务没有运行

解决方案（Docker 方式，最稳定）：

# 清理旧服务
hermes-web-ui stop 2>/dev/null
hermes gateway stop 2>/dev/null
pkill -f "hermes-web-ui" 2>/dev/null
pkill -f "hermes gateway" 2>/dev/null

# 使用 Docker 运行一体化 Web UI
docker run -d \
  --name hermes-webui \
  -p 3001:3001 \
  -v ~/.hermes:/app/.hermes \
  -v ~/.hermes-web-ui:/app/data \
  -e HERMES_CONFIG_DIR=/app/.hermes \
  --restart unless-stopped \
  docker.1ms.run/nesquena/hermes-webui:latest

问题：hermes gateway run 无法后台运行

原因：该命令需要前台交互式终端

解决方案：使用 screen

apt install -y screen
screen -dmS hermes-gateway bash -c "hermes gateway run; exec bash"

6.4 Docker 相关问题

问题：netstat: command not found

解决方案：

apt install net-tools
# 或使用替代命令
ss -tlnp | grep 18642

问题：Docker 镜像拉取失败

解决方案：使用国内镜像加速

# 使用 Docker 代理镜像
docker pull docker.1ms.run/nesquena/hermes-webui:latest
docker tag docker.1ms.run/nesquena/hermes-webui:latest ghcr.io/nesquena/hermes-webui:latest

问题：hermes-web-ui is already running

解决方案：

hermes-web-ui stop
pkill -f "hermes-web-ui"

6.5 API 错误问题

问题：API Error 500（服务端错误）

原因及解决方案：

  1. API Key 失效 → 重新获取并配置
  2. 账户余额不足 → 登录平台充值
  3. 模型名称错误 → 使用 hermes model 重新选择

快速参考卡片

7.1 安装后验证清单

# 1. 检查命令是否可用
which hermes

# 2. 检查 API Key 配置
cat ~/.hermes/.env | grep DEEPSEEK

# 3. 运行健康检查
hermes doctor

# 4. 测试聊天
hermes -m "你好"

7.2 完整启动流程（Docker Web UI）

# 1. 确保 Docker 运行
docker ps

# 2. 启动 Web UI 容器
docker start hermes-webui

# 3. 浏览器访问
# http://localhost:3001

7.3 文件目录说明

路径内容
~/.hermes/Hermes 主目录
~/.hermes/.envAPI Key 配置文件
~/.hermes/config.yaml模型配置
~/.hermes/hermes-agent/源代码
~/.hermes/logs/日志文件
~/.hermes/skills/技能目录

有用链接

本指南基于 2026年5月 的真实安装过程编写，记录了所有遇到的坑和解决方案。按照这个流程，你应该能在 15-20 分钟内完成从零到 Web UI 的完整部署。

Hermes Agent AI