国内环境从零部署 Hermes Agent 完全指南

TL;DR: 国内服务器部署 Hermes Agent 的完整指南，解决 GitHub 访问受阻、PyPI 镜像配置、matrix 依赖缺失、全局命令 PATH 等问题。

背景

Hermes Agent 是 NousResearch 开源的 AI Agent 项目，支持 skills、tools、记忆等强大功能。在国内服务器部署时，主要面临两个网络挑战：

GitHub 无法直接访问 — git clone 超时
PyPI 官方源速度慢 — 需要切换国内镜像

本文记录在腾讯云 Ubuntu 24.04 服务器上完整部署 Hermes Agent v0.11.0 的实际操作步骤，所有命令均经过验证。

服务器环境

OS: Ubuntu 24.04 LTS (GNU/Linux 6.8.0 x86_64)
配置: 2核 3.6GB RAM
远程: SSH (port 22)
用户: ubuntu

一、系统准备

1.1 更新软件源（使用腾讯云镜像）

sudo apt update && sudo apt upgrade -y

腾讯云 Ubuntu 24.04 默认已配置 mirrors.cn.qq.com 源，无需手动更换。

1.2 安装基础依赖

sudo apt install -y python3-pip python3-venv git curl build-essential sshpass

sshpass：用于非交互式 SSH 密码认证（本文演示用）
build-essential：部分 Python 包需要编译

二、获取源码（GitHub 访问受阻的解决方案）

关键问题：git clone https://github.com/NousResearch/hermes-agent.git 在国内服务器上会超时。

方案一：下载 Release 源码包（推荐）

# 下载 v2026.4.23 版本源码包
wget https://codeload.github.com/NousResearch/hermes-agent/tar.gz/refs/tags/v2026.4.23 -O /tmp/hermes-agent.tar.gz

# 解压并移动到用户目录
tar -xzf /tmp/hermes-agent.tar.gz -C /tmp/
mv /tmp/hermes-agent-*/ ~/hermes-agent/

原理：codeload.github.com 是 GitHub 官方的代码下载服务，通常比 github.com 本身更容易访问。本方案已验证可用，下载速度约 11MB/s。

方案二：Gitee 镜像（不推荐）

理论上可以将 GitHub 仓库 fork 到 Gitee 再 clone，但经实测 NousResearch/hermes-agent 在 Gitee 上未找到镜像。

三、配置 Python 镜像

3.1 安装 uv 包管理器

uv 是新一代 Python 包管理器，速度远快于 pip：

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

或者从国内镜像安装：

wget https://mirrors.sjtug.sjtu.edu.cn/astral-sh/uv/install.sh -O /tmp/uv-install.sh
bash /tmp/uv-install.sh

安装后确保 uv 在 PATH 中：

export PATH="$HOME/.local/bin:$PATH"
uv --version  # 应显示版本号

3.2 配置 PyPI 镜像

创建或修改 ~/.bashrc，添加以下环境变量：

echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
echo 'export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
source ~/.bashrc

镜像说明：清华 TUNA 镜像 (pypi.tuna.tsinghua.edu.cn) 是国内最稳定的 PyPI 镜像之一，本文全程使用该镜像。

四、安装 Hermes Agent

4.1 创建 Python 虚拟环境

cd ~/hermes-agent
python3 -m venv venv
source venv/bin/activate

4.2 安装依赖（关键步骤）

uv pip install -e '.[modal,daytona,dev,messaging,cron,slack,cli,tts-premium,voice,pty,honcho,mcp,homeassistant,sms,acp,mistral,bedrock,dingtalk,feishu,termux]' --index-url https://pypi.tuna.tsinghua.edu.cn/simple

⚠️ 关于 `[all]` 额外依赖组

hermes-agent[all] 包含 matrix 依赖组，而 matrix 需要 mautrix[encryption]，后者依赖 python-olm。python-olm 在国内 PyPI 镜像上不存在，会导致安装失败。

因此推荐使用上面的命令，手动指定需要的额外依赖，跳过 matrix。

4.3 可选额外依赖说明

依赖组	说明
`modal`	Modal 云计算平台支持
`daytona`	Daytona Sandbox 支持
`dev`	开发测试工具（pytest, debugpy 等）
`messaging`	Telegram, Discord, Slack 等消息平台
`feishu`	飞书支持
`dingtalk`	钉钉支持
`voice`	本地语音识别（faster-whisper）
`tts-premium`	ElevenLabs 高级语音合成
`cron`	定时任务支持
`mcp`	Model Context Protocol 支持
`acp`	Agent Client Protocol 支持

五、验证安装

5.1 激活虚拟环境后验证

cd ~/hermes-agent
source venv/bin/activate
hermes --version

输出示例：

Hermes Agent v0.11.0 (2026.4.23)
Project: /home/ubuntu/hermes-agent
Python: 3.12.3
OpenAI SDK: 2.32.0

运行健康检查：

hermes doctor

5.2 配置全局命令（推荐）

每次都激活虚拟环境比较麻烦，建议创建全局软链接：

mkdir -p ~/.local/bin
ln -sf ~/hermes-agent/venv/bin/hermes ~/.local/bin/hermes
ln -sf ~/hermes-agent/venv/bin/hermes-chat ~/.local/bin/hermes-chat
ln -sf ~/hermes-agent/venv/bin/hermes-doctor ~/.local/bin/hermes-doctor
ln -sf ~/hermes-agent/venv/bin/hermes-setup ~/.local/bin/hermes-setup
ln -sf ~/hermes-agent/venv/bin/hermes-whatsapp ~/.local/bin/hermes-whatsapp

关键修复：让 SSH 非交互式会话也能找到 hermes

Ubuntu 的 .bashrc 默认有 interactive check，导致 SSH 非交互式连接时直接跳过 PATH 配置。在 .bashrc 最开头（interactive check 之前）添加 PATH：

# 加在 ~/.bashrc 第一行
if [ -d "$HOME/.local/bin" ]; then PATH="$HOME/.local/bin:$PATH"; fi

或者直接执行：

sed -i '1i if [ -d "$HOME/.local/bin" ]; then PATH="$HOME/.local/bin:$PATH"; fi' ~/.bashrc

之后即可全局使用 hermes 命令：

hermes --version      # 全局可用
hermes doctor         # 全局可用

六、初步配置

6.1 交互式初始化

hermes setup

6.2 配置模型提供商

# 配置 OpenAI
hermes login openai

# 配置 Anthropic
hermes login anthropic

6.3 查看帮助

hermes --help

主要命令：

hermes chat — 交互式对话
hermes model — 选择默认模型
hermes skills — 管理 skills
hermes cron — 定时任务
hermes config — 查看/编辑配置
hermes status — 查看所有组件状态

七、常见问题

Q1: `git clone` 超时

A：使用 Release 源码包方式下载（见本文第二步），不依赖 git 协议。

Q2: `mautrix[encryption]` 安装失败

A：python-olm 包在国内镜像不存在。解决方案见本文 4.3 节，手动指定除 matrix 以外的额外依赖。

Q3: `uv` 命令不存在

A：确保执行了 source ~/.bashrc 或重新登录 shell 使环境变量生效。也可手动将 ~/.local/bin 加入 PATH：

export PATH="$HOME/.local/bin:$PATH"

Q4: 依赖安装速度慢

A：确保设置了清华 PyPI 镜像（见本文 3.2 节）。如仍慢，可尝试阿里云镜像：

export UV_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/
export PIP_INDEX_URL=https://mirrors.aliyun.com/pypi/simple/

八、完整安装脚本

以下是一键安装脚本（在服务器上直接运行）：

#!/bin/bash
set -e

# 1. 系统依赖
sudo apt update && sudo apt install -y python3-pip python3-venv git curl build-essential sshpass

# 2. 下载源码
wget https://codeload.github.com/NousResearch/hermes-agent/tar.gz/refs/tags/v2026.4.23 -O /tmp/hermes-agent.tar.gz
tar -xzf /tmp/hermes-agent.tar.gz -C /tmp/
rm -rf ~/hermes-agent
mv /tmp/hermes-agent-*/ ~/hermes-agent/

# 3. 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

# 4. 配置清华镜像
echo 'export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
echo 'export PIP_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple' >> ~/.bashrc
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

# 5. 创建虚拟环境并安装
cd ~/hermes-agent
python3 -m venv venv
source venv/bin/activate
uv pip install -e '.[modal,daytona,dev,messaging,cron,slack,cli,tts-premium,voice,pty,honcho,mcp,homeassistant,sms,acp,mistral,bedrock,dingtalk,feishu,termux]' --index-url https://pypi.tuna.tsinghua.edu.cn/simple

# 6. 配置全局命令（推荐）
mkdir -p ~/.local/bin
ln -sf ~/hermes-agent/venv/bin/hermes ~/.local/bin/hermes
ln -sf ~/hermes-agent/venv/bin/hermes-chat ~/.local/bin/hermes-chat
ln -sf ~/hermes-agent/venv/bin/hermes-doctor ~/.local/bin/hermes-doctor
ln -sf ~/hermes-agent/venv/bin/hermes-setup ~/.local/bin/hermes-setup
ln -sf ~/hermes-agent/venv/bin/hermes-whatsapp ~/.local/bin/hermes-whatsapp

# 6.5 修复 .bashrc 让 SSH 非交互式会话也能找到 hermes
# 在 interactive check 之前添加 PATH
sed -i '1i if [ -d "$HOME/.local/bin" ]; then PATH="$HOME/.local/bin:$PATH"; fi' ~/.bashrc

# 7. 验证
echo "=== 安装验证 ==="
hermes --version
hermes doctor

九、部署信息汇总

项目	内容
系统	Ubuntu 24.04 LTS
Hermes 版本	v0.11.0 (2026.4.23)
Python 版本	3.12.3
安装方式	源码包 + uv + 清华 PyPI 镜像
安装路径	/home/ubuntu/hermes-agent
虚拟环境	/home/ubuntu/hermes-agent/venv
已安装包数量	172

总结

本文验证了在国内网络环境（腾讯云服务器）下，从零部署 Hermes Agent 的完整流程。核心解决思路是：

用 codeload.github.com 下载源码包代替 git clone
用 uv 加速包管理
用清华 TUNA 镜像解决 PyPI 访问速度问题
跳过 matrix 依赖组（python-olm 国内不可用）

部署完成后的 Hermes Agent 位于 ~/hermes-agent/，可通过 hermes 命令直接使用。

项目	内容
作者	胡小纯
发布日期	2026-04-24
联系微信	hu--xiaochun
个人主页	https://胡小纯.cn
备用主页	https://xn--yets91feqb.cn/

技术没有捷径，但有方向

背景

服务器环境

一、系统准备

1.1 更新软件源（使用腾讯云镜像）

1.2 安装基础依赖

二、获取源码（GitHub 访问受阻的解决方案）

方案一：下载 Release 源码包（推荐）

方案二：Gitee 镜像（不推荐）

三、配置 Python 镜像

3.1 安装 uv 包管理器

3.2 配置 PyPI 镜像

四、安装 Hermes Agent

4.1 创建 Python 虚拟环境

4.2 安装依赖（关键步骤）

⚠️ 关于 `[all]` 额外依赖组

4.3 可选额外依赖说明

五、验证安装

5.1 激活虚拟环境后验证

5.2 配置全局命令（推荐）

六、初步配置

6.1 交互式初始化

6.2 配置模型提供商

6.3 查看帮助

七、常见问题

Q1: `git clone` 超时

Q2: `mautrix[encryption]` 安装失败

Q3: `uv` 命令不存在

Q4: 依赖安装速度慢

八、完整安装脚本

九、部署信息汇总

总结

胡小纯

分享文章

文章目录

背景

服务器环境

一、系统准备

1.1 更新软件源（使用腾讯云镜像）

1.2 安装基础依赖

二、获取源码（GitHub 访问受阻的解决方案）

方案一：下载 Release 源码包（推荐）

方案二：Gitee 镜像（不推荐）

三、配置 Python 镜像

3.1 安装 uv 包管理器

3.2 配置 PyPI 镜像

四、安装 Hermes Agent

4.1 创建 Python 虚拟环境

4.2 安装依赖（关键步骤）

⚠️ 关于 [all] 额外依赖组

4.3 可选额外依赖说明

五、验证安装

5.1 激活虚拟环境后验证

5.2 配置全局命令（推荐）

六、初步配置

6.1 交互式初始化

6.2 配置模型提供商

6.3 查看帮助

七、常见问题

Q1: git clone 超时

Q2: mautrix[encryption] 安装失败

Q3: uv 命令不存在

Q4: 依赖安装速度慢

八、完整安装脚本

九、部署信息汇总

总结

分享文章

文章目录

⚠️ 关于 `[all]` 额外依赖组

Q1: `git clone` 超时

Q2: `mautrix[encryption]` 安装失败

Q3: `uv` 命令不存在