【Hermes】Agent 本地部署完整指南

Hermes Agent 本地部署完整指南

📋 目录

项目简介
系统要求
部署方式
配置指南
功能模块
常见问题

项目简介

Hermes Agent 是由 Nous Research 开发的开源自主 AI 代理（MIT 许可证），其核心设计理念是”一个与你共同成长的 Agent”。

核心特性

特性	说明
🧠 自我学习循环	从经验中创建技能、在使用中改进技能、主动持久化知识
🌐 多平台网关	支持 Telegram、Discord、Slack、WhatsApp、Signal 等消息平台
🛡️ 真沙箱隔离	6 种代码执行后端（Local、Docker、SSH、Daytona、Singularity、Modal）
🎙️ 语音模式	支持终端语音输入和消息应用语音消息
⏱️ 自然语言定时任务	用自然语言描述调度计划（如”每天上午 9 点检查日志”）
⚡ 委派与并行	可生成子代理并行工作，或通过 RPC 调用自己的工具
🔌 插件系统	通过放入 Python 文件扩展功能
📱 模型无关	支持 OpenRouter（200+ 模型）、Anthropic、Vercel AI Gateway、本地 LLM

为什么选择 Hermes

24/7 无人值守自动化：监控服务器、解析数据、测试代码、编写报告
告别”土拨鼠之日”：自动读取历史日志，已了解你的技术栈和项目上下文
安全的代码执行：在隔离沙箱中执行 AI 生成的代码，保护系统安全

系统要求

支持的操作系统

系统	支持状态	说明
Linux	✅ 完全支持	Ubuntu 22.04 推荐
macOS	✅ 完全支持	通过 Homebrew 安装依赖
WSL2	✅ 完全支持	Windows 用户推荐使用 WSL2（Ubuntu 22.04）
Windows 原生	❌ 不支持	需使用 WSL2 或官方 Windows 安装器

⚠️ 重要提示：Hermes Agent 不支持 Windows 原生环境。Windows 用户请使用 WSL2（推荐 Ubuntu 22.04） 或官方 Windows 安装器。

前置依赖

Git（唯一需要手动准备的工具）

# Ubuntu/Debian
sudo apt install git
 
# macOS（Homebrew）
brew install git
 
# 验证安装
git --version

其余依赖（uv、Python 3.11、Node.js v22、ripgrep、ffmpeg 等）均由安装脚本自动处理。

部署方式

Hermes Agent 提供三种部署方式：

方式	适用场景	时间	难度
一键安装	大多数用户，快速上手	2-3 分钟	⭐
手动安装	需要精细控制的环境	10-15 分钟	⭐⭐⭐
Docker 部署	生产环境、完全容器化	5-10 分钟	⭐⭐

方式一：一键安装（推荐）

这是最简单的安装方式，适合大多数用户。

快速安装命令

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

安装过程说明

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

克隆仓库（包含所有子模块）
安装运行时依赖：
- uv（快速 Python 包管理器）
- Python 3.11（无需 sudo）
- Node.js v22（用于浏览器自动化和 WhatsApp 网关）
- ripgrep（高速文件搜索）
- ffmpeg（语音功能音视频处理）
创建虚拟环境
安装 Python 依赖
设置全局 hermes 命令
配置 LLM 提供商

安装后验证

# 使环境变量生效
source ~/.bashrc   # 或 source ~/.zshrc
 
# 验证安装
hermes doctor

预期输出：

✓ Python 3.11.9
✓ Node.js v22.4.0
✓ uv 0.4.1
✓ ripgrep 14.1.0
✓ ffmpeg 6.1.1
✓ ~/.hermes 目录结构
✓ ~/.hermes/.env 配置文件
⚠ 未检测到 API Key，请运行 hermes setup

配置 Hermes

# 运行配置向导
hermes setup

向导会引导你配置以下内容：

LLM 提供商：选择 OpenRouter、Anthropic、OpenAI 或本地推理
API Key：粘贴你的密钥
执行后端：选择 Docker（推荐）或本地后端

开始使用

# 启动 Hermes
hermes

方式二：手动安装

如果你需要更精细的控制，可以按以下步骤手动安装。

第 1 步：克隆仓库

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

⚠️ 注意：--recurse-submodules 参数会同时克隆所有子模块，不可省略。

第 2 步：安装 uv 并创建虚拟环境

# 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# 创建虚拟环境（Python 3.11，uv 会自动下载）
uv venv .venv --python 3.11

💡 提示：Hermes 需要 Python 3.11，无需手动安装，uv 会自动处理。

第 3 步：安装 Python 依赖

# 安装核心功能
uv pip install -e .
 
# 或安装所有功能（包括消息平台、定时任务等）
uv pip install -e ".[all]"

可选功能包（Extras）说明：

Extra 名称	包含功能	安装命令
`all`	所有功能	`uv pip install -e ".[all]"`
`messaging`	Telegram & Discord 网关	`uv pip install -e ".[messaging]"`
`cron`	定时任务调度	`uv pip install -e ".[cron]"`
`cli`	终端菜单 UI	`uv pip install -e ".[cli]"`
`modal`	Modal 云执行后端	`uv pip install -e ".[modal]"`
`tts-premium`	ElevenLabs 高质量语音	`uv pip install -e ".[tts-premium]"`
`voice`	终端麦克风输入 + 音频播放	`uv pip install -e ".[voice]"`
`pty`	PTY 终端支持	`uv pip install -e ".[pty]"`
`honcho`	AI 原生记忆（Honcho 集成）	`uv pip install -e ".[honcho]"`
`mcp`	Model Context Protocol 支持	`uv pip install -e ".[mcp]"`
`homeassistant`	Home Assistant 集成	`uv pip install -e ".[homeassistant]"`
`acp`	ACP 编辑器集成	`uv pip install -e ".[acp]"`
`slack`	Slack 消息	`uv pip install -e ".[slack]"`
`dev`	pytest & 测试工具	`uv pip install -e ".[dev]"`

第 4 步：安装可选子模块（如果需要）

# RL 训练后端（可选）
uv pip install -e "./tinker-atropos"

第 5 步：安装 Node.js 依赖（可选）

仅在需要浏览器自动化（Browserbase）和 WhatsApp 网关时需要：

npm install

第 6 步：创建配置目录结构

# 创建目录
mkdir -p ~/.hermes/{cron,sessions,logs,memories,skills,pairing,hooks,image_cache,audio_cache,whatsapp/session}
 
# 复制示例配置文件
cp cli-config.yaml.example ~/.hermes/config.yaml
 
# 创建环境变量文件
touch ~/.hermes/.env

目录结构说明：

目录	用途
`~/.hermes/skills/`	存放自动生成和手动创建的技能文件
`~/.hermes/memory/`	持久记忆数据库（SQLite）
`~/.hermes/personas/`	人格/角色配置文件
`~/.hermes/logs/`	运行日志（AI 的长期记忆基础）
`~/.hermes/plugins/`	自定义工具插件
`~/.hermes/cron/`	定时任务配置
`~/.hermes/sessions/`	会话数据
`~/.hermes/pairing/`	设备配对信息
`~/.hermes/hooks/`	Git 钩子
`~/.hermes/image_cache/`	图片缓存
`~/.hermes/audio_cache/`	音频缓存

第 7 步：添加 API Key

编辑 ~/.hermes/.env，填入你的 API Key（至少填一个）：

# LLM 提供商（至少需要一个）
NOUS_API_KEY=your_key_here
OPENROUTER_API_KEY=sk-or-v1-your-key-here
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=sk-ant-your-key-here
GOOGLE_API_KEY=your-key-here
 
# 可选：启用额外工具
FIRECRAWL_API_KEY=fc-your-key    # 网页搜索与抓取
FAL_KEY=your-fal-key              # 图片生成（FLUX）

或通过 CLI 设置：

hermes config set OPENROUTER_API_KEY sk-or-v1-your-key-here

第 8 步：创建命令软链接

# 创建软链接
sudo ln -sf "$(pwd)/.venv/bin/hermes" /usr/local/bin/hermes
 
# 或使用用户目录（无需 sudo）
mkdir -p ~/.local/bin
ln -sf "$(pwd)/.venv/bin/hermes" ~/.local/bin/hermes

如果 ~/.local/bin 不在 PATH 中，添加到 Shell 配置：

# Bash
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
 
# Zsh
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
 
# Fish
fish_add_path $HOME/.local/bin

第 9 步：验证安装

# 检查版本
hermes --version
 
# 运行诊断
hermes doctor
 
# 测试聊天
hermes chat -q "Hello! What tools do you have available?"

第 10 步：配置提供商

hermes model  # 选择你的 LLM 提供商和模型

方式三：Docker 部署

如果你希望将 Hermes Agent 完全容器化运行。

拉取镜像

docker pull nousresearch/hermes-agent:latest

运行容器

docker run -it \
  -v ~/.hermes:/root/.hermes \
  -e OPENROUTER_API_KEY=your_key_here \
  nousresearch/hermes-agent:latest

使用 Docker Compose（推荐）

创建 docker-compose.yml：

version: "3.9"
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    volumes:
      - ~/.hermes:/root/.hermes
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - NOUS_API_KEY=${NOUS_API_KEY}
    stdin_open: true
    tty: true
    restart: unless-stopped

创建 .env 文件：

OPENROUTER_API_KEY=sk-or-v1-your-key-here
NOUS_API_KEY=your_key_here

启动：

docker compose up -d
docker compose exec hermes hermes

配置指南

基础配置命令

命令	说明
`hermes model`	选择 LLM 提供商和模型
`hermes tools`	配置启用的工具
`hermes gateway setup`	设置消息平台（Telegram、Discord 等）
`hermes config set`	设置单个配置值
`hermes setup`	运行完整配置向导
`hermes config check`	检查配置
`hermes config migrate`	迁移配置（如有格式变更）
`hermes status`	检查系统状态
`hermes doctor`	运行诊断工具

连接消息平台

Hermes 可以通过内置的 Messaging Gateway 连接多个消息平台。

连接 Telegram

在 Telegram 中创建 Bot：通过 @BotFather 创建并复制 Token
运行命令：

hermes gateway add telegram --token YOUR_BOT_TOKEN
hermes gateway start

连接 Discord

在 Discord 开发者平台创建应用并获取 Token
运行命令：

hermes gateway add discord --token YOUR_BOT_TOKEN
hermes gateway start

连接 Slack

hermes gateway add slack --token YOUR_BOT_TOKEN
hermes gateway start

配置执行后端

Hermes 支持 6 种代码执行后端：

后端	隔离性	性能	适用场景
Docker	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	生产环境、推荐
Local	⭐	⭐⭐⭐⭐⭐	快速测试（需谨慎）
SSH	⭐⭐⭐	⭐⭐⭐	远程服务器
Daytona	⭐⭐⭐⭐	⭐⭐⭐	云开发环境
Singularity	⭐⭐⭐⭐⭐	⭐⭐⭐⭐	HPC 集群
Modal	⭐⭐⭐⭐	⭐⭐⭐⭐⭐	无服务器执行

配置 Docker 后端（推荐）：

hermes config set backend docker

配置记忆系统

Hermes 使用混合记忆系统：

SQLite FTS5 全文搜索：轻量级、快速查询
Honcho 深度用户分析：理解你的行为模式

编辑 ~/.hermes/config.yaml：

memory:
  fts5_enabled: true
  honcho_enabled: true
  redis_enabled: false  # 如果安装了 Redis，可启用

配置定时任务

Hermes 内置 cron，支持自然语言描述任务：

# 示例：每天上午 9 点检查错误日志并发送 Telegram 摘要
hermes cron add "每天上午 9 点检查生产环境错误日志并通过 Telegram 发送摘要"
 
# 查看所有定时任务
hermes cron list
 
# 删除定时任务
hermes cron remove <task_id>

功能模块

1. 自我学习记忆循环

会话记忆：自动保存每次对话到 SQLite 数据库
技能生成：解决复杂任务时自动创建新技能（agentskills.io 标准）
跨会话记忆：读取历史日志，了解你的技术栈和项目上下文

2. 多平台网关

平台	支持功能
Telegram	文本、语音消息
Discord	文本、语音
Slack	文本、语音
WhatsApp	文本、语音
Signal	文本、语音

3. 语音模式

终端推送对话（Push-to-Talk）
消息应用语音消息
本地转录（faster-whisper），隐私保护

4. 真沙箱隔离

6 种安全后端：

# Docker（推荐）
hermes config set backend docker
 
# 本地执行（需谨慎）
hermes config

小M-Quartz

探索

【Hermes】Agent 本地部署完整指南

📋 目录

项目简介

核心特性

为什么选择 Hermes

系统要求

支持的操作系统

前置依赖

部署方式

方式一：一键安装（推荐）

快速安装命令

安装过程说明

安装后验证

配置 Hermes

开始使用

方式二：手动安装

第 1 步：克隆仓库

第 2 步：安装 uv 并创建虚拟环境

第 3 步：安装 Python 依赖

第 4 步：安装可选子模块（如果需要）

第 5 步：安装 Node.js 依赖（可选）

第 6 步：创建配置目录结构

第 7 步：添加 API Key

第 8 步：创建命令软链接

第 9 步：验证安装

第 10 步：配置提供商

方式三：Docker 部署

拉取镜像

运行容器

使用 Docker Compose（推荐）

配置指南

基础配置命令

连接消息平台

连接 Telegram

连接 Discord

连接 Slack

配置执行后端

配置记忆系统

配置定时任务

功能模块

1. 自我学习记忆循环

2. 多平台网关

3. 语音模式

4. 真沙箱隔离

关系图谱

反向链接