Hermes Agent 完整安装部署指南：从零到企业级聊天机器人

Hermes Agent 完整安装部署指南：从零到企业级聊天机器人

作者: Nous Research 社区贡献
适用平台: Linux / macOS / WSL / Termux
项目地址: https://github.com/NousResearch/hermes-agent
官方文档: https://hermes-agent.nousresearch.com/docs/

目录

1. 什么是 Hermes Agent？
2. 系统要求与环境准备
3. 一键安装（网络通畅环境）
4. 离线/加速安装（解决 GitHub 下载慢）
5. 配置模型提供商（LLM Provider）
6. 虚拟环境与插件管理
7. 聊天机器人集成（以钉钉为例）
8. Gateway 服务管理
9. 沙箱环境使用指南
10. 常见问题与排错

1. 什么是 Hermes Agent？

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架。它能在终端、聊天软件和 IDE 中运行，支持调用系统工具、执行代码、浏览网页、读写文件等操作。同类型的项目包括 Claude Code（Anthropic）、Codex（OpenAI）。

核心特性

2. 系统要求与环境准备

硬件要求

前置依赖

# Ubuntu / Debian / WSL
sudo apt update && sudo apt install -y \
    git curl build-essential python3-dev libffi-dev ripgrep ffmpeg

# macOS
brew install git curl python@3.11 ripgrep ffmpeg

# Termux (Android)
pkg install -y git curl clang rust make pkg-config libffi openssl ripgrep ffmpeg python

验证环境

# 检查 Python（需要 3.11+）
python3 --version

# 检查 Git
git --version

# 检查 curl
curl --version

3. 一键安装（网络通畅环境）

如果你的网络能流畅访问 GitHub 和 PyPI，这是最快的方式：

标准安装

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

安装脚本会自动执行以下流程：

1. 检测操作系统（Linux / macOS / Android）
2. 安装 uv（Python 包管理器）
3. 确认或安装 Python 3.11
4. 安装 Git
5. 安装 Node.js 22 LTS（用于浏览器工具）
6. 克隆 git clone NousResearch/hermes-agent.git
7. 创建 Python 虚拟环境（venv）
8. 安装 Python 依赖（pip install -e ".[all]"）
9. 安装 npm 依赖（Playwright 浏览器引擎）
10. 创建 ~/.hermes/ 配置目录结构
11. 拷贝默认配置模板
12. 执行交互式设置向导
13. 可选：安装 Gateway 后台服务

静默安装（跳过向导）

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | \
    bash -s -- --skip-setup --no-venv

指定安装目录

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

安装后的目录结构

安装完成后，关键文件如下：

~/.hermes/                        # 用户数据根目录（HERMES_HOME）
├── config.yaml                   # 主配置文件
├── .env                          # API 密钥（重要！）
├── SOUL.md                       # 人格设定文件
├── skills/                       # 技能缓存目录
├── sessions/                     # 会话历史
├── logs/                         # 日志
│   ├── agent.log
│   ├── errors.log
│   └── gateway.log
├── cron/                         # 定时任务配置
├── image_cache/                  # 图片缓存
├── audio_cache/                  # 音频缓存
├── node/                         # 内置 Node.js
├── hermes-agent/                 # 源码目录（git clone 位置）
│   ├── venv/                     # Python 虚拟环境
│   ├── gateway/platforms/        # 各平台适配器
│   ├── tools/                    # 工具实现
│   └── skills/                   # 内置 skill
└── profiles/                     # 多配置环境

4. 离线/加速安装（解决 GitHub 下载慢）

在国内网络环境下，直接从 GitHub clone 可能非常慢甚至失败。以下是完整的离线安装方案。

4.1 从镜像下载源码包

# 方法一：使用 ghproxy 镜像（推荐）
git clone https://ghproxy.net/https://github.com/NousResearch/hermes-agent.git \
    ~/.hermes/hermes-agent

# 方法二：在 Gitee 等国内平台搜索镜像，或让同事下载后传给你
# 方法三：手动下载 ZIP（从浏览器或 wget）
wget https://ghproxy.net/https://github.com/NousResearch/hermes-agent/archive/refs/heads/main.zip
unzip main.zip -d ~/.hermes/
mv ~/.hermes/hermes-agent-main ~/.hermes/hermes-agent

4.2 修改 install.sh 使其跳过 git clone

核心思路是：在运行 install.sh 之前，先把代码放到目标目录，让脚本检测到已存在的 .git 目录，从而跳过 clone 步骤。

# =============================================
# 方案 A：手动下载 + 修改 install.sh（推荐）
# =============================================

# 第 1 步：从镜像下载源码（假设已有网速好的环境）
# 在目标机器上：
mkdir -p ~/.hermes/hermes-agent
cd ~/.hermes/hermes-agent

# 如果已经在别处下载好了 ZIP，scp 传过来
# scp user@server:~/hermes-agent-main.zip ./

# 或者直接从镜像 clone（比原始 GitHub 快很多）
git clone https://ghproxy.net/https://github.com/NousResearch/hermes-agent.git \
    ~/.hermes/hermes-agent

# 第 2 步：编辑 install.sh，注释掉 clone 相关步骤
# 重点修改 clone_repo() 函数
cat > /tmp/hermes-install-patch.sh << 'PATCH_SCRIPT'
#!/bin/bash
# 安装流程：跳过 git clone，直接 setup