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

苏格兰黑羊508

1283人浏览 · 2026-04-23 13:37:20

苏格兰黑羊508 · 2026-04-23 13:37:20 发布

项目地址：github.com/NousResearch/hermes-agent

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

版本：0.10.0 | 许可证：MIT

一、Hermes Agent 是什么

Hermes Agent 是由 Nous Research 开发的开源自改进 AI Agent。它不是普通的聊天机器人，而是一个具备闭环学习系统的智能代理：

技能自创建：遇到复杂任务时自动生成新技能，并在使用中持续优化
持久记忆：跨会话的记忆系统，能够记住你是谁、你的偏好和历史对话
多平台接入：同时支持 Telegram、Discord、Slack、WhatsApp、Signal、Email 等
多模型兼容：OpenRouter、OpenAI、Anthropic、NVIDIA NIM、Xiaomi MiMo、Kimi 等 200+ 模型
定时任务：内置 Cron 调度器，支持无人值守的自动化
MCP 集成：可接入任意 MCP Server 扩展能力
低成本运行：可在 $5/月的 VPS 上运行，或通过 Daytona/Modal 实现 Serverless

二、系统要求

项目	最低要求	推荐
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	稳定的外网连接

不支持原生 Windows，Windows 用户请使用 WSL2。

三、部署方式选择

Hermes 提供四种部署方式：

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

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

4.1 执行安装

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

安装器会自动完成以下操作：

检测操作系统（Linux/macOS/WSL2/Termux）
安装 uv（Python 包管理器，如果未安装）
安装 Python 3.11（如果未安装）
克隆仓库到 ~/.hermes/hermes-agent
创建虚拟环境并安装依赖
创建 hermes 命令符号链接到 ~/.local/bin/
运行交互式设置向导

4.2 安装选项

# 跳过设置向导
curl -fsSL ... | bash -s -- --skip-setup

# 不创建虚拟环境（使用系统 Python）
curl -fsSL ... | bash -s -- --no-venv

# 指定安装分支
curl -fsSL ... | bash -s -- --branch dev

# 指定安装目录
curl -fsSL ... | bash -s -- --dir /opt/hermes

4.3 安装后启动

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

# 启动交互式 CLI
hermes

# 启动消息网关（支持 Telegram/Discord/Slack 等）
hermes gateway

# 完整设置向导
hermes setup

4.4 Android/Termux 安装

在 Termux 中执行：

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

Termux 会安装精简版（不含语音依赖），详细指南见 Termux 文档。

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

5.1 安装 uv

uv 是 Hermes 推荐的 Python 包管理器，比 pip 更快：

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

安装后确保 ~/.local/bin 在 PATH 中。

5.2 克隆仓库

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

5.3 快速设置（推荐）

./setup-hermes.sh

这个脚本会自动完成 uv 安装、Python 3.11 配置、venv 创建、依赖安装和命令链接。

5.4 手动步骤（等价于 setup-hermes.sh）

# 创建 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

5.5 依赖组说明

Extra	说明	安装命令
`all`	完整功能	`uv pip install -e ".[all]"`
`messaging`	Telegram/Discord/Slack 等	`uv pip install -e ".[messaging]"`
`cron`	定时任务	`uv pip install -e ".[cron]"`
`mcp`	MCP 集成	`uv pip install -e ".[mcp]"`
`voice`	本地语音识别	`uv pip install -e ".[voice]"`
`tts-premium`	ElevenLabs TTS	`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 部署（推荐生产环境）

6.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

6.2 Docker 运行参数

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`	API 密钥
`-p 8080:8080`	Web API 端口
`gateway start`	启动消息网关

6.3 Docker 容器目录结构

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

6.4 构建优化

Dockerfile 采用多阶段构建：

使用 uv 官方镜像作为基础
Node.js 依赖和 Playwright 浏览器预先缓存
Web 前端（Vite）在构建时编译
非 root 用户运行（UID 10000）

七、方式四：云平台部署

7.1 Daytona（Serverless）

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

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

# 配置 Daytona
daytona create

7.2 Modal（Serverless）

Modal 提供 GPU 和 CPU 的 serverless 运行环境：

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

# 部署
modal deploy hermes_modal.py

7.3 Singularity

适用于 HPC 集群环境：

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

八、配置详解

8.1 配置文件位置

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

8.2 模型配置

# 交互式选择模型
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 — Nous Research 官方
OpenRouter — 200+ 模型，推荐入门
NVIDIA NIM — Nemotron 系列
OpenAI — GPT-4o, o1 等
Anthropic — Claude 3.5 Sonnet
Xiaomi MiMo — 小米大模型
Kimi/Moonshot — 月之暗面
MiniMax — 稀宇科技
Hugging Face — 开源模型
自定义端点 — 任意 OpenAI 兼容 API

8.3 消息网关配置

# 设置 Telegram Bot
hermes gateway setup telegram

# 设置 Discord
hermes gateway setup discord

# 设置 Slack
hermes gateway setup slack

# 启动网关
hermes gateway start

8.4 工具配置

# 查看可用工具
hermes tools

# 启用/禁用工具
hermes tools enable web_search
hermes tools disable code_execution

内置工具包括：

Web 搜索（Exa、Firecrawl）
代码执行（多种终端后端）
文件操作
浏览器自动化（Playwright）
图像生成（FAL）
语音合成（Edge TTS / ElevenLabs）

8.5 环境变量参考

变量	说明
`OPENROUTER_API_KEY`	OpenRouter API 密钥
`OPENAI_API_KEY`	OpenAI API 密钥
`ANTHROPIC_API_KEY`	Anthropic API 密钥
`TELEGRAM_BOT_TOKEN`	Telegram Bot Token
`DISCORD_BOT_TOKEN`	Discord Bot Token
`SLACK_BOT_TOKEN`	Slack Bot Token
`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 密钥、消息平台配置等。

十、日常使用

10.1 CLI 命令速查

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

10.2 对话内命令

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

10.3 定时任务示例

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

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

# 删除任务
hermes cron remove <id>

十一、故障排查

11.1 诊断工具

hermes doctor # 运行完整诊断

11.2 常见问题

Q: Windows 上无法安装？

A: Hermes 不支持原生 Windows，请使用 WSL2。

Q: 安装后 hermes 命令找不到？

A: 确保 ~/.local/bin 在 PATH 中，执行 source ~/.bashrc。

Q: Python 版本不兼容？

A: 必须使用 Python 3.11+，使用 uv python install 3.11 安装。

Q: 消息网关启动失败？

A: 检查对应平台的 Bot Token 是否正确，以及网络是否能访问 Telegram/Discord API。

Q: 如何更新？

A: 执行 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 集成
└── Web Dashboard (Vite)            # Web 管理界面

十三、资源链接

资源	链接
GitHub 仓库	github.com/NousResearch/hermes-agent
官方文档	hermes-agent.nousresearch.com/docs
Discord 社区	discord.gg/NousResearch
Skills Hub	agentskills.io
问题反馈	GitHub Issues
OpenClaw 迁移	`hermes claw migrate`