注：可以直接用该文章让模型自己按照步骤操作安装不容易出错，因为模型没有参考资料安装很容易出现循环依赖。

源码安装-只是为了做一些程序上的扩展，让牛马更好的服务，后面扩展会发文章记录。

一、环境要求

表格

组件	最低版本
Python	3.11+
Node.js	20+
npm	随 Node.js 自带

二、第一步：解压安装包

将 hermes-agent-main.zip 解压到自定义目录，示例路径：

plaintext

D:\ai\hermes\hermes-agent-main\

三、第二步：创建 Python 虚拟环境

请使用 PowerShell 执行，不要使用 CMD，进入项目目录后运行以下命令：

powershell

cd D:\ai\hermes\hermes-agent-main
python -m venv .venv

四、第三步：配置国内 pip 镜像（可选，加速依赖下载）

方式 1：手动创建配置文件

新建文件 %USERPROFILE%\.pip\pip.ini，写入以下内容：

ini

[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn

方式 2：PowerShell 一键创建

powershell

mkdir $env:USERPROFILE\.pip -Force
@"
[global]
index-url = https://pypi.tuna.tsinghua.edu.cn/simple
trusted-host = pypi.tuna.tsinghua.edu.cn
"@ | Out-File -FilePath $env:USERPROFILE\.pip\pip.ini -Encoding UTF8

五、第四步：安装 Hermes Agent

进入项目目录，执行安装命令：

powershell

.\.venv\Scripts\pip install -e ".[cli,cron,pty]"

参数说明

• cli：交互式命令行界面
• cron：定时任务支持
• pty：Windows 伪终端适配

如需完整功能，可使用：

powershell

# 安装全部扩展
pip install -e ".[all]"
# 消息平台扩展
pip install -e ".[messaging]"
# 语音功能扩展
pip install -e ".[voice]"

六、第五步：安装 Node.js 浏览器依赖（可选）

若需要使用浏览器自动化能力，执行以下命令（使用淘宝镜像加速）：

powershell

npm install agent-browser @askjo/camofox-browser --registry=https://registry.npmmirror.com

七、第六步：验证安装是否成功

powershell

.\.venv\Scripts\hermes --version

出现类似如下输出，代表安装成功：

plaintext

Hermes Agent v0.10.0 (2026.4.16)
Project: D:\ai\hermes\hermes-extracted\hermes-agent-main
Python: 3.12.6
OpenAI SDK: 2.41.0

八、第七步：配置大模型提供商（火山方舟豆包为例）

方式 1：交互式向导配置（推荐新手）

powershell

.\.venv\Scripts\hermes setup

根据界面提示，当前版本（Hermes Agent v0.16.0 (2026.6.5)）没有预置火山引擎 Volcengine Ark，那么就选择 29. custom (direct API)  。如下图所示：

下一步如下图所示：

选 1 或直接按 回车 （默认就是 Auto-detect）。

火山方舟兼容 OpenAI 接口，Auto-detect 会自动识别为 Chat Completions 模式。直接回车即可。

下一步接着选择模型（hermes会主动把火山引擎的所有模型拉取过来，选择自己已经开通的）：

到此配置模型已经结束，因为是源码安装，可以打开虚拟环境所在目录执行：

.\.venv\Scripts\hermes setup  进行交互对话，接下来为了更方便可以创建启动脚本或者设置全局变量使用hermes

九、第八步：创建开机启动脚本

在项目根目录新建 start-hermes.bat 启动脚本，内容如下：

batch

@echo off
chcp 65001 >nul
set PYTHONIOENCODING=utf-8
title Hermes Agent
echo ==========================================
echo   Hermes Agent 启动脚本 (Windows)
echo ==========================================
echo.
set HERMES_DIR=%~dp0
call "%HERMES_DIR%.venv\Scripts\activate.bat"
hermes %*
if %errorlevel% neq 0 (
    echo.
    echo Hermes 已退出 (错误码: %errorlevel%)
    pause
)

十、第九步：启动 Hermes

方式 1：双击启动

直接双击 start-hermes.bat 即可运行。

方式 2：命令行手动启动

powershell

cd D:\ai\hermes\hermes-agent-main
.\.venv\Scripts\activate
hermes

常用交互指令：

• /exit：退出程序
• /help：查看全部命令

---

十一、常用命令汇总

表格

命令	功能说明
hermes	启动交互式对话
hermes setup	运行全局配置向导
hermes config show	查看当前所有配置
hermes model	切换模型 / 模型服务商
hermes doctor	检测运行环境与故障
hermes gateway	启动消息网关服务
hermes --version	查看软件版本

---

十二、常见问题解决方案

1. 出现 GBK 编码报错、Emoji 乱码

PowerShell 先执行环境变量配置，再启动程序：

powershell

$env:PYTHONIOENCODING='utf-8'
.\.venv\Scripts\hermes

2. pip 下载速度缓慢

使用清华镜像临时加速：

powershell

pip install -e ".[cli]" -i https://pypi.tuna.tsinghua.edu.cn/simple

3. 无法识别 hermes 命令

检查是否激活虚拟环境：

powershell

.\.venv\Scripts\activate

4. Node.js 依赖安装失败

确认 Node.js 版本 ≥ 20，切换淘宝镜像重试：

powershell

npm install agent-browser --registry=https://registry.npmmirror.com

---

补充：火山方舟豆包配置排错（对应之前报错）

1. 接口地址固定：https://ark.cn-beijing.volces.com/api/v3
2. API Key 必须为 sk_ 开头 的密钥，不要填入接入点 ID
3. Model 字段填写火山方舟「在线推理」中的 ep- 开头接入点 ID，而非纯模型名称
4. 出现 401 密钥格式错误：核对密钥前缀、删除复制时多余空格 / 换行