Hermes Agent部署全指南一键安装到生产环境

Hermes Agent是由Nous Research开发的开源自改进AI Agent，区别于普通聊天机器人，它具备闭环学习系统，能自动生成并优化技能、拥有跨会话持久记忆，同时支持多平台接入和200+大模型兼容，最低仅需5美元/月的VPS即可运行。

项目地址：github.com/NousResearch/hermes-agent 官方文档：hermes-agent.nousresearch.com/docs 许可证：MIT

一、系统要求

Hermes Agent支持Linux、macOS和WSL2环境，不支持原生Windows系统，Windows用户需通过WSL2部署。具体软硬件要求如下：

项目	最低要求	推荐配置
Python	3.11+	3.11或3.12
Node.js	22+	22 LTS
操作系统	Linux/macOS/WSL2	Ubuntu 22.04+
内存	2GB RAM	4GB+
磁盘	5GB可用空间	10GB+
网络	可访问GitHub和LLM API	稳定的外网连接

二、四种部署方式对比

根据使用场景和技术能力，可选择以下四种部署方式：

部署方式	适用场景	难度等级
一键安装脚本	快速体验、个人日常使用	简单
手动开发环境	二次开发、代码贡献	中等
Docker部署	生产环境、服务器部署	中等
云平台部署	Serverless、弹性伸缩需求	高级

三、方式一：一键安装脚本（新手推荐）

这是最便捷的部署方式，安装器会自动完成环境检测、依赖安装和基础配置。

3.1 执行基础安装

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

安装器将自动完成：操作系统检测、uv包管理器安装、Python 3.11配置、仓库克隆、虚拟环境创建、依赖安装、命令符号链接生成，最后启动交互式设置向导。

3.2 自定义安装选项

可通过参数调整安装行为：

# 跳过设置向导
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup

# 不创建虚拟环境（使用系统Python）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --no-venv

# 指定安装分支（如开发版）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --branch dev

# 指定安装目录
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --dir /opt/hermes

3.3 安装后启动

# 重新加载shell配置
source ~/.bashrc    # 或 source ~/.zshrc

# 启动交互式终端界面
hermes

# 启动多平台消息网关
hermes gateway

# 重新运行完整设置向导
hermes setup

3.4 Android/Termux安装

在Termux终端中执行相同的一键安装命令即可，Termux会自动安装不含语音依赖的精简版本。

四、方式二：手动开发环境安装

适合需要进行二次开发或自定义修改的用户，推荐使用uv作为Python包管理器。

4.1 安装uv包管理器

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

安装后确保~/.local/bin已添加到系统PATH中。

4.2 克隆仓库并快速设置

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh

该脚本等价于手动完成虚拟环境创建、依赖安装和命令链接。

4.3 手动分步安装

# 创建Python 3.11虚拟环境
uv venv venv --python 3.11
source venv/bin/activate

# 安装核心依赖
uv pip install -e "."

# 安装完整功能（含消息平台、定时任务、语音等）
uv pip install -e ".[all]"

# 仅安装开发依赖
uv pip install -e ".[dev]"

# 运行测试用例
python -m pytest tests/ -q

4.4 依赖组说明

可根据实际需求安装对应功能的依赖：

Extra	功能说明	安装命令
all	完整功能	`uv pip install -e ".[all]"`
messaging	Telegram/Discord/Slack等消息平台	`uv pip install -e ".[messaging]"`
cron	定时任务调度	`uv pip install -e ".[cron]"`
mcp	MCP Server集成	`uv pip install -e ".[mcp]"`
voice	本地语音识别	`uv pip install -e ".[voice]"`
tts-premium	ElevenLabs语音合成	`uv pip install -e ".[tts-premium]"`
web	Web API服务	`uv pip install -e ".[web]"`
modal	Modal云平台部署	`uv pip install -e ".[modal]"`
daytona	Daytona云平台部署	`uv pip install -e ".[daytona]"`
dev	开发测试依赖	`uv pip install -e ".[dev]"`

五、方式三：Docker部署（生产环境推荐）

Docker部署能保证环境一致性，便于管理和迁移，是生产环境的首选方案。

5.1 快速启动

# 克隆仓库
git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent

# 构建镜像
docker build -t hermes-agent .

# 运行容器
docker run -it \
-v hermes-data:/opt/data \
-e HERMES_HOME=/opt/data \
hermes-agent

5.2 生产环境运行参数

docker run -d \
--name hermes \
-v hermes-data:/opt/data \
-e HERMES_UID=$(id -u) \
-e HERMES_GID=$(id -g) \
-e OPENROUTER_API_KEY=sk-or-xxx \
-p 8080:8080 \
hermes-agent gateway start

参数	说明
`-v hermes-data:/opt/data`	数据持久化卷，保存配置、记忆和日志
`-e HERMES_UID/GID`	映射宿主机用户权限，避免文件权限问题
`-e OPENROUTER_API_KEY`	配置LLM API密钥
`-p 8080:8080`	暴露Web API端口
`gateway start`	启动多平台消息网关

5.3 容器目录结构

/opt/hermes/          # 应用代码
/opt/data/            # 持久化数据
├── .env              # 环境变量和API密钥
├── config.yaml       # 主配置文件
├── SOUL.md           # Agent角色设定
├── cron/             # 定时任务配置
├── sessions/         # 会话数据
├── logs/             # 运行日志
├── hooks/            # 钩子脚本
├── memories/         # 持久记忆文件
├── skills/           # 自定义技能目录
├── skins/            # 界面主题
├── plans/            # 计划任务
├── workspace/        # 工作目录
└── home/             # 子进程HOME目录

5.4 构建优化

官方Dockerfile采用多阶段构建，使用uv官方镜像作为基础，预先缓存Node.js依赖和Playwright浏览器，Web前端在构建时编译，并以非root用户（UID 10000）运行，提升安全性。

六、方式四：云平台部署

6.1 Daytona（Serverless）

Daytona提供按需唤醒的容器环境，空闲时几乎不产生费用：

# 安装Daytona扩展
uv pip install -e ".[daytona]"

# 配置并创建实例
daytona create

6.2 Modal（Serverless）

Modal提供GPU和CPU的Serverless运行环境，适合需要高性能计算的场景：

# 安装Modal扩展
uv pip install -e ".[modal]"

# 部署到Modal
modal deploy hermes_modal.py

6.3 Singularity

适用于HPC集群环境：

singularity build hermes.sif docker://hermes-agent:latest
singularity run hermes.sif

七、核心配置详解

7.1 配置文件位置

所有配置文件默认存放在~/.hermes目录下：

文件	路径	说明
config.yaml	`~/.hermes/config.yaml`	主配置文件
.env	`~/.hermes/.env`	环境变量和API密钥
SOUL.md	`~/.hermes/SOUL.md`	Agent角色和人格设定

7.2 模型配置

Hermes Agent支持200+大模型，可通过命令快速切换：

# 交互式选择模型
hermes model

# 直接设置模型参数
hermes config set model.provider openrouter
hermes config set model.model anthropic/claude-3.5-sonnet
hermes config set model.api_key sk-or-xxx

支持的模型提供商包括：Nous Portal、OpenRouter、NVIDIA NIM、OpenAI、Anthropic、小米MiMo、Kimi、MiniMax、Hugging Face，以及任意OpenAI兼容的自定义端点。

7.3 消息网关配置

可快速接入多个主流消息平台：

# 设置Telegram Bot
hermes gateway setup telegram

# 设置Discord Bot
hermes gateway setup discord

# 设置Slack Bot
hermes gateway setup slack

# 启动所有配置的网关
hermes gateway start

7.4 工具配置

内置40+实用工具，可按需启用或禁用：

# 查看所有可用工具
hermes tools

# 启用Web搜索工具
hermes tools enable web_search

# 禁用代码执行工具
hermes tools disable code_execution

内置工具包括：Web搜索（Exa、Firecrawl）、代码执行、文件操作、浏览器自动化、图像生成、语音合成等。

7.5 常用环境变量

变量	说明
OPENROUTER_API_KEY	OpenRouter API密钥
OPENAI_API_KEY	OpenAI API密钥
ANTHROPIC_API_KEY	Anthropic API密钥
TELEGRAM_BOT_TOKEN	Telegram Bot令牌
DISCORD_BOT_TOKEN	Discord Bot令牌
SLACK_BOT_TOKEN	Slack Bot令牌
ELEVENLABS_API_KEY	ElevenLabs API密钥
HERMES_HOME	自定义数据目录（默认~/.hermes）

八、从OpenClaw迁移

如果之前使用过OpenClaw，Hermes提供一键自动迁移工具：

# 交互式迁移（首次安装时自动检测）
hermes claw migrate

# 预览迁移内容
hermes claw migrate --dry-run

# 仅迁移用户数据（不含密钥）
hermes claw migrate --preset user-data

# 覆盖已有配置
hermes claw migrate --overwrite

迁移内容包括：SOUL.md角色设定、持久记忆、自定义技能、API密钥、消息平台配置等。

九、日常使用指南

9.1 CLI命令速查

hermes                    # 启动交互式终端界面
hermes -q "你好"          # 直接提问（非交互式）
hermes model              # 切换大模型
hermes tools              # 管理工具
hermes config set         # 修改配置
hermes gateway            # 管理消息网关
hermes setup              # 运行完整设置向导
hermes update             # 更新到最新版本
hermes doctor             # 运行系统诊断
hermes skills             # 管理自定义技能
hermes cron               # 管理定时任务

9.2 对话内命令

在对话中可直接使用以下命令：

命令	作用
/new	开始新会话
/reset	重置当前会话
/model	临时切换模型
/personality	切换人格设定
/retry	重试最后一条回复
/undo	撤销上一步操作
/compress	压缩上下文窗口
/usage	查看token用量
/skills	浏览可用技能
/stop	停止当前任务

9.3 定时任务示例

内置Cron调度器，支持无人值守的自动化任务：

# 添加每日9点生成昨日工作总结并发送到Slack
hermes cron add "0 9 * * *" "生成昨日工作总结并发送到 Slack"

# 查看所有定时任务
hermes cron list

# 删除指定ID的定时任务
hermes cron remove <id>

十、故障排查

10.1 系统诊断工具

运行以下命令可自动检测并修复常见问题：

hermes doctor

10.2 常见问题解决

Windows上无法安装：Hermes不支持原生Windows，请使用WSL2环境。
hermes命令找不到：确保~/.local/bin已添加到PATH，执行source ~/.bashrc重新加载配置。
Python版本不兼容：必须使用Python 3.11+，可通过uv python install 3.11安装指定版本。
消息网关启动失败：检查对应平台的Bot Token是否正确，以及网络是否能访问相关API。
版本更新：执行hermes update，或手动执行git pull && uv pip install -e ".[all]"。

十一、架构概览

Hermes Agent采用模块化架构设计，各组件职责清晰：

├── CLI (prompt_toolkit + Rich)     # 交互式终端界面
├── Gateway                          # 多平台消息网关
│   ├── Telegram Bot
│   ├── Discord Bot
│   ├── Slack Bot
│   ├── WhatsApp
│   ├── Signal
│   └── Email
├── Agent Loop                       # ReAct核心循环
│   ├── LLM Client (多提供商兼容)
│   ├── Tool Registry (40+内置工具)
│   ├── Skill System (自动创建与优化)
│   └── Memory Manager (跨会话持久记忆)
├── Cron Scheduler                   # 定时任务调度器
├── MCP Client                       # MCP Server集成
└── Web Dashboard (Vite)            # Web管理界面

十二、官方资源

GitHub仓库：github.com/NousResearch/hermes-agent
官方文档：hermes-agent.nousresearch.com/docs
Discord社区：discord.gg/NousResearch
技能中心：agentskills.io
问题反馈：GitHub Issues

在部署Hermes Agent时，推荐搭配TreeRouter API中转站使用。TreeRouter能统一管理Hermes Agent支持的200+大模型API，解决跨平台网络访问不稳定的问题，提供低延迟、高可用的中转服务。