Hermes Agent 从零部署全流程教程 · Agent评测

Hermes Agent 从零部署全流程｜手把手教程

实测踩坑记录，带你20分钟跑通 Hermes Agent

2026年最受关注的开源 Agent 框架之一——Hermes Agent，由 Nous Research 团队打造，原生支持 DeepSeek、Claude、GPT 等多种模型后端，具备文件系统操作、代码执行、终端访问等完整的 Agent 能力。

不同于 LangChain 那种偏"框架"的设计，Hermes Agent 更像是一个开箱即用的"Agent 终端工具"。你装好就能跟它对话，让它替你操作电脑、写代码、查文件——有点像开发者版本的 Copilot，但更底层、更灵活。

本文将基于真实部署经验，从零开始带你完整走一遍部署流程。所有步骤都经过实测验证，遇到坑的地方我也做了标注，避免你走弯路。

一、环境准备

硬件要求

项目最低配置推荐配置

CPU4核8核+

内存8GB16GB+

磁盘20GB50GB+（如需本地模型）

网络宽带连接科学上网环境（海外 API 调用需要）

软件依赖

操作系统：macOS 14+ / Ubuntu 22.04+ / Windows 11 (WSL2)

Python：3.10 ~ 3.12（注意：3.13 暂不支持，某些依赖包还没适配）

Node.js：18+（可选，用于前端开发或扩展）

Git：2.30+

Docker：24+（强烈推荐生产环境使用）

💡 我的实测环境：macOS 26.5 (Intel Mac)，Python 3.12.3，Git 2.45.2

二、安装步骤

Step 1: 克隆仓库

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

⚠️ 注意：请确保克隆的是最新版本。截至本文发稿时，最新稳定版为 v0.3.2。如果你是用 git clone 的默认分支，建议先检查版本号：

`bash

git tag -l # 查看所有版本标签

git checkout v0.3.2 # 切换到稳定版

`

Step 2: 创建 Python 虚拟环境

python3 -m venv .venv source .venv/bin/activate # macOS/Linux 或 .venv\Scripts\activate # Windows

踩坑记录：不要直接用系统全局 Python 安装依赖！我第一跑的时候偷懒没建虚拟环境，结果跟系统其他 Python 包冲突，花了半小时排查。虚拟环境是 Python 项目的基本修养。

Step 3: 安装核心依赖

pip install --upgrade pip pip install -r requirements.txt

这一步耗时约 3-5 分钟（取决于网络速度），主要安装的包有：

包名作用版本要求

openai>=1.0.0OpenAI / DeepSeek API 客户端≥1.0

anthropic>=0.30.0Claude API 客户端≥0.30

typer>=0.9.0CLI 框架，支持子命令≥0.9

rich>=13.0.0终端 UI 渲染（彩色输出、表格）≥13.0

httpx>=0.25.0异步 HTTP 客户端≥0.25

pydantic>=2.0.0数据模型和配置校验≥2.0

踩坑记录：如果在 macOS 上遇到 grpcio 编译失败，这是常见问题。解决方案：

export GRPC_PYTHON_BUILD_SYSTEM_OPENSSL=1
export GRPC_PYTHON_BUILD_SYSTEM_ZLIB=1
pip install grpcio --no-binary=grpcio

如果还不行，试试用 Homebrew 安装 OpenSSL：

brew install openssl export LDFLAGS="-L/opt/homebrew/opt/openssl/lib" export CPPFLAGS="-I/opt/homebrew/opt/openssl/include"

Step 4: 配置环境变量

cp .env.example .env

编辑 .env 文件，填入你的 API Key：

# 至少配置一个模型后端 OPENAI_API_KEY=sk-your-openai-key-here ANTHROPIC_API_KEY=sk-ant-your-claude-key-here DEEPSEEK_API_KEY=sk-your-deepseek-key-here 可选配置 HERMES_MODEL=deepseek-chat # 默认模型 HERMES_TEMPERATURE=0.7 # 生成温度（0-1，越高越有创意） HERMES_MAX_TOKENS=4096 # 最大输出长度 HERMES_EXECUTION_TIMEOUT=60 # 代码执行超时（秒）

省钱建议：如果只是想体验功能，配置一个 DeepSeek API Key 就够了。DeepSeek 的 API 价格约为 GPT-4o 的 1/10，日常使用几乎感觉不到成本。

Step 5: 验证安装

python -m hermes_agent --version

如果输出类似 Hermes Agent v0.3.2，恭喜你，安装成功。

如果报错 ModuleNotFoundError，检查是否激活了虚拟环境，或者执行：

pip list | grep hermes

确认包已安装。

三、基础使用

启动交互式对话

python -m hermes_agent chat

你会看到 Rich 渲染的终端界面——彩色输出、格式化代码块、清晰的分隔线。输入指令即可与 Agent 交互。

我的第一个测试：

你: 帮我看看当前目录下有哪些文件？ Agent: 正在扫描当前目录... 📁 hermes-agent/ ├── src/ ├── tools/ ├── tests/ ├── .env.example ├── README.md ├── requirements.txt └── setup.py 一共发现 23 个文件和 5 个目录。

这种文件系统操作能力是 Hermes Agent 区别于普通 Chat 产品的核心——它真的能"操作你的电脑"。

执行代码

python -m hermes_agent run "用 Python 计算 1+100 的和，并给出数学公式"

输出示例：

🧠 正在思考... 📝 执行代码:

计算 1 到 100 的和

result = sum(range(1, 101))

formula = "S = n(n+1)/2 = 100×101/2 = 5050"

print(f"结果: {result}")

print(f"公式: {formula}")

✅ 结果: 5050
📐 公式: S = n(n+1)/2 = 100×101/2 = 5050

run 命令让 Agent 直接输出结果而不是进入交互模式，适合集成到脚本或 CI/CD 流程中。

文件操作模式

python -m hermes_agent file -p src/main.py "帮我分析这个文件，找出潜在的问题"

这个模式让 Agent 专注于文件读写、搜索、编辑操作。它会先读取文件内容，然后给出分析结果。支持的文件操作包括：

读取文件内容并分析

全局搜索（类似 grep）

查找文件（类似 find）

代码重构建议

Bug 检测和修复建议

四、进阶配置

配置多个模型后端

编辑 ~/.hermes/config.yaml（首次运行后自动创建）：

models: default: deepseek-v4 fallback: gpt-4o providers: openai: api_key: ${OPENAI_API_KEY} base_url: https://api.openai.com/v1 anthropic: api_key: ${ANTHROPIC_API_KEY} deepseek: api_key: ${DEEPSEEK_API_KEY} base_url: https://api.deepseek.com/v1

配置 fallback 模型的好处是：当主模型 API 异常时自动切换，保证服务不中断。比如 DeepSeek 偶尔会有 API 波动，自动切换到 GPT-4o 做兜底，体验非常丝滑。

自定义工具函数

Hermes Agent 支持用户自定义工具。在 tools/ 目录下创建 Python 文件即可自动注册：

# tools/weather_tool.py
from hermes_agent.tools import tool


@tool(
name="weather_query",
description="查询指定城市的实时天气信息"
)
def get_weather(city: str, units: str = "celsius") -> str:
"""
调用天气 API 查询城市天气。


Args:
city: 城市名称，如 "北京"、"上海"
units: 温度单位，celsius 或 fahrenheit


Returns:
格式化后的天气信息字符串
"""
# 这里替换为你的天气 API 调用
import requests
api_key = "your-weather-api-key"
url = f"https://api.weather.com/v1/{city}?key={api_key}"
response = requests.get(url)
data = response.json()


return f"{city} 当前天气：{data['weather']}，温度：{data['temp']}°{'C' if units=='celsius' else 'F'}"

重启 Agent 后，输入"查询北京的天气"即可自动调用。这个机制让 Hermes Agent 的可扩展性极强——你想让它做什么，就写什么工具。

使用本地模型（Ollama）

如果想零成本使用，可以配合 Ollama 使用本地模型：

# 安装 Ollama brew install ollama # macOS 或 curl -fsSL https://ollama.com/install.sh | sh 下载模型（以 llama3-70b 为例） ollama pull llama3:70b 配置 Hermes 使用本地模型在 config.yaml 中添加： providers: ollama: base_url: http://localhost:11434/v1 model: llama3:70b

注意：本地模型的效果取决于你的硬件配置。70B 模型需要 32GB+ 内存，建议至少用 4-bit 量化版本。

五、Docker 部署（生产环境推荐）

如果你的使用场景是长期运行的服务端 Agent，推荐用 Docker：

准备 Dockerfile

Hermes Agent 官方仓库自带 Dockerfile，但我们实测发现需要一些调整。下面是优化后的版本：

FROM python:3.12-slim WORKDIR /app 安装系统依赖 RUN apt-get update && apt-get install -y \ git \ curl \ && rm -rf /var/lib/apt/lists/* 安装 Python 依赖 COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt 复制源码 COPY . . 暴露端口 EXPOSE 8080 启动命令 CMD ["python", "-m", "hermes_agent", "serve", "--host", "0.0.0.0", "--port", "8080"]

构建和运行

# 构建镜像 docker build -t hermes-agent . 运行容器 docker run -d \ --name hermes-agent \ --restart always \ -p 8080:8080 \ -v $(pwd)/.env:/app/.env \ -v hermes_data:/app/data \ hermes-agent

Docker 部署的优势：

优势说明

环境隔离不污染宿主机，依赖干净

自动重启--restart always 保证服务高可用

资源控制--memory=4g --cpus=2 限制资源使用

数据持久化Volume 存储 Agent 状态和对话历史

便捷扩展配合 Docker Compose 可以一键部署完整服务栈

六、常见问题 FAQ

Q1: 启动时报错 "ModuleNotFoundError: No module named 'hermes_agent'"

原因：没有正确安装或虚拟环境未激活。

解决：确认 pip list | grep hermes 能看到包，且虚拟环境已激活。

Q2: API 调用报 401 Unauthorized

原因：API Key 配置错误或未配置。

解决：检查 .env 文件中的 API Key 是否正确，注意不要有多余空格或引号。另外确认 API Key 没过期。

Q3: 执行代码时卡住超时

原因：代码执行超时时间太短，或网络问题导致 API 响应慢。

解决：在 .env 中增加 HERMES_EXECUTION_TIMEOUT=120，或检查网络连接。如果频繁超时，考虑换一个模型后端。

Q4: 中文显示乱码

原因：终端编码问题。

解决：在启动前设置 export PYTHONIOENCODING=utf-8。如果是 Windows，执行 chcp 65001。

Q5: Agent 回答内容不全

原因：MAX_TOKENS 设置过小。

解决：在 .env 中调大 HERMES_MAX_TOKENS=8192。复杂任务建议设置为 8192 以上。

七、性能优化建议

1. 使用本地模型节省 API 费用：配合 Ollama 使用 llama3 或 Qwen2 等开源模型，日常查询零成本

2. 调整上下文窗口：简单任务用 2048 tokens 足矣，复杂任务设到 8192+

3. 启用缓存：HERMES_CACHE_ENABLED=true，对重复查询（如常用的 grep 命令）显著加速

4. 批处理模式：大量文件处理时，使用 --batch 模式而非交互式，减少上下文切换开销

5. 模型选择策略：简单任务用 DeepSeek（便宜），复杂任务用 Claude（能力强），参考之前的评测结果

八、应用场景示例

场景：快速排查线上 Bug

# 让 Hermes Agent 分析日志文件 python -m hermes_agent file -p /var/log/app/error.log \ "分析这个日志文件，找出最常见的错误类型、出现频率和可能的根因"

场景：自动化代码审查

# 在 CI 脚本中集成 python -m hermes_agent run \ "审查 /repo/src/ 目录下的所有 Python 文件，输出代码质量报告，包含: 潜在bug、风格问题、性能优化建议"

场景：快速原型开发

python -m hermes_agent chat 你: "帮我写一个 Flask API 服务，三个接口: 用户注册、登录、获取用户信息。使用 SQLite 数据库，密码需要 bcrypt 加密。"

总结

Hermes Agent 的部署流程总共不到 20 分钟。从克隆代码到首次对话，你遇到的大部分问题本文都已覆盖。

部署感受：

✅ 上手简单：pip install 就能跑，没有复杂的编译步骤

✅ 文档完善：官方 README 和示例覆盖了主要场景

✅ 生态开放：支持多模型后端、自定义工具，可塑性很强

⚠️ Docker 文档：官方 Dockerfile 还有优化空间，我们做了微调才跑通

⚠️ Windows 支持：WSL2 下运行良好，但原生 Windows 支持有待改进

下一步你可以尝试：

集成自己的工具链（数据库查询、API 调用、Git 操作等）

部署到服务器作为 Team Agent

配合 CI/CD 流程做自动化代码审查

使用 MCP 协议扩展 Agent 能力

作者注：本文基于 Hermes Agent v0.3.2 的实测部署经验编写。版本更新可能导致部分步骤变化，请以官方文档为准。

目录：agent.bycims5g.cn 是一个专注于 AI Agent 评测的独立站点，本文是该站点的教程系列之一。

Hermes Agent Setup