文章目录
- [Hermes Agent 全栈安装、配置与Web端架构深度解析（官方命令版·最终优化）](#Hermes Agent 全栈安装、配置与Web端架构深度解析（官方命令版·最终优化）)
-
- [一、核心架构：仓库源码 vs .hermes 配置目录（必懂基础）](#一、核心架构：仓库源码 vs .hermes 配置目录（必懂基础）)
-
- [1. Git 克隆仓库（源码/开发目录）](#1. Git 克隆仓库（源码/开发目录）)
- [2. 本地 .hermes 配置目录（全局持久化目录）](#2. 本地 .hermes 配置目录（全局持久化目录）)
- [二、官方标准安装流程（逐行命令 + 会遇到什么 + 说明）](#二、官方标准安装流程（逐行命令 + 会遇到什么 + 说明）)
- 三、初始化配置（必做！解决401错误）
- [四、三大Web服务：作用 + 启动命令 + 现象](#四、三大Web服务：作用 + 启动命令 + 现象)
-
- [1. Dashboard（核心后端网关 → 必须第一个启动）](#1. Dashboard（核心后端网关 → 必须第一个启动）)
- [2. web 文件夹（专业聊天UI → 主界面）](#2. web 文件夹（专业聊天UI → 主界面）)
- [3. website 文件夹（项目文档）](#3. website 文件夹（项目文档）)
- [五、Windows 极简一键启动脚本（你优化的版本完全正确）](#五、Windows 极简一键启动脚本（你优化的版本完全正确）)
- 六、高频报错速查（实战总结）
- [七、开发调试终极 Checklist](#七、开发调试终极 Checklist)
- 全文总结
Hermes Agent 全栈安装、配置与Web端架构深度解析（官方命令版·最终优化）
一、核心架构：仓库源码 vs .hermes 配置目录（必懂基础）
Hermes Agent 采用程序与数据完全分离设计，这是避免配置丢失、报错的核心前提：
1. Git 克隆仓库（源码/开发目录）
- 路径示例 ：
D:\hermes-agent - 角色：源代码工程、开发环境载体
- 内容 ：后端Python、前端Vue(
web)、文档(website)、插件、脚本 - 作用 ：仅用于开发、编译、环境管理，不存储个人配置
2. 本地 .hermes 配置目录（全局持久化目录）
- 路径 ：
C:\Users\你的用户名\.hermes - 角色：全局配置+数据核心
- 内容 ：
.env(API密钥)、state.db、聊天记录、日志、模型缓存 - 作用 ：运行
hermes命令优先读取此目录；删仓库不丢配置
二、官方标准安装流程（逐行命令 + 会遇到什么 + 说明）
官方推荐环境
- Python 3.11
- uv（官方指定高速包管理器）
- Git
逐行执行（复制即用）
bash
# 1. 克隆官方仓库
git clone https://github.com/NousResearch/hermes-agent.git
# 2. 进入项目根目录
cd hermes-agent
# 3. 安装 uv 高速包管理器（官方指定）
curl -LsSf https://astral.sh/uv/install.sh | sh
# 4. 创建Python 3.11虚拟环境
uv venv venv --python 3.11
# 5. 激活虚拟环境（Linux/Mac）
source venv/bin/activate
# Windows 激活命令（备用）
# venv\Scripts\activate
# 6. 官方完整版安装（含所有功能+开发依赖）
uv pip install -e ".[all,dev]"
# 7. 运行测试（验证安装是否成功）
python -m pytest tests/ -q每一步会遇到什么
git clone：下载项目代码，生成hermes-agent文件夹cd hermes-agent：命令行进入项目根目录- 安装
uv：自动配置高速包管理器，无报错即成功 uv venv：快速创建虚拟环境，生成venv文件夹- 激活环境：命令行前缀出现
(venv)，代表激活成功 - 安装依赖：高速安装所有库，最后显示
Successfully installed - 测试：出现
X passed提示，代表安装完全成功
三、初始化配置（必做！解决401错误）
bash
# 交互式初始化：输入API Key，自动生成 .hermes/.env 配置
hermes setup会遇到：命令行引导填写API密钥，完成后即可正常使用模型
四、三大Web服务：作用 + 启动命令 + 现象
1. Dashboard（核心后端网关 → 必须第一个启动）
- 端口：9119（固定）
- 作用：系统大脑、API网关、调试界面
- 启动命令：
bash
hermes dashboard- 成功现象：显示
Dashboard running on http://localhost:9119
2. web 文件夹（专业聊天UI → 主界面）
- 作用：精美沉浸式聊天界面
- 必须先启动Dashboard才能用
bash
cd web
npm install
npm run dev- 访问：
http://localhost:5173
3. website 文件夹（项目文档）
- 仅用于查看/编辑文档，不用启动，不影响Agent功能
五、Windows 极简一键启动脚本（你优化的版本完全正确）
直接新建 start.bat，复制以下内容，双击一键启动后端：
batch
@echo off
cd /d D:\study\hermes-agent
call venv\Scripts\activate
set GATEWAY_ALLOW_ALL_USERS=true
hermes dashboard
pause✅ 你的理解完全正确：就该这么简洁，无需多余代码
六、高频报错速查（实战总结）
| 报错现象 | 解决方案 |
|---|---|
| 401 User not found | 执行 hermes setup 重新填写API Key |
| 9119端口占用 | 杀死占用进程后重启 |
| 前端一直加载 | 先启动 hermes dashboard |
| 依赖安装失败 | 使用官方 uv 命令，不要用普通pip |
七、开发调试终极 Checklist
- 顺序：先启动后端(Dashboard) → 再启动前端(web)
- 环境：所有
hermes命令必须在(venv)激活状态下执行 - 配置：只改
~/.hermes/.env，不动仓库内配置 - 端口：9119必须留给Dashboard，不可占用
- 备份：备份
.hermes文件夹 = 备份所有数据/设置
全文总结
- 官方标准命令已完整嵌入，直接逐行复制即可完成安装
- 最简流程：克隆 → uv环境 → 安装 → hermes setup → 一键启动后端
- 核心命令 ：
hermes setup（配置）hermes dashboard（后端）npm run dev（前端）
- 启动脚本：你精简的版本完全正确，是本地开发最优方案
- 架构核心 ：仓库管代码，
.hermes管数据，永不丢失配置