Hermes Agent 快速上手指南
从零开始配置 Hermes Agent，包含 Telegram 接入、插件开发、自定义工具注册、Cron 任务编排的完整实战教程。适合想在本地搭建 AI Agent 系统的开发者。
Hermes Agent 是一个开源的 AI Agent 框架，支持多平台（CLI、Telegram、Discord、Slack）、自定义工具注册、Cron 定时任务。本教程从安装到生产部署，手把手带你搭建完整的 AI Agent 系统。
Table of Contents
Hermes Agent 简介
Hermes Agent 是一个多平台 AI 助手框架，核心特性：
多平台接入
CLI / Telegram / Discord / Slack / WhatsApp
自定义工具
注册任意 Python 函数作为 Agent 工具
Cron 调度
定时任务，自动执行并推送结果
MCP 协议
支持 Model Context Protocol 扩展
多模型支持
Claude / GPT-4 / Gemini / 本地模型
记忆系统
会话持久化、跨会话记忆
安装与环境配置
前置要求
- Python 3.10+
- API Key（OpenAI / Anthropic / Groq 等）
- pip / uv 包管理器
安装 Hermes Agent
$
# 推荐使用 uv 安装（更快）
uv pip install hermes-ai --system
# 或使用 pip
pip install hermes-ai
# 验证安装
hermes --version初始化配置
$
hermes setup按照提示输入：
- 选择主模型（推荐
anthropic/claude-sonnet-4） - 输入 API Key
- 选择启用哪些工具集（terminal / web / file / delegate 等）
配置文件位置
配置文件在
配置文件在
~/.hermes/config.yaml，API Key 保存在 ~/.hermes/.env。不要把 .env 提交到 Git！
CLI 模式测试
$
hermes chat "Hello, explain what you can do"Telegram 接入配置
创建 Telegram Bot
- 打开 Telegram，搜索 @BotFather
- 发送
/newbot - 设置机器人名称和用户名
- 获取 Bot Token（格式：
123456789:ABCdefGHI...）
配置 Webhook 或 Long Polling
Hermes 支持两种模式，推荐使用 Gateway 模式：
$
# 在 config.yaml 中添加 Telegram 配置
hermes config set telegram.enabled true
hermes config set telegram.bot_token "YOUR_BOT_TOKEN"
hermes config set telegram.admin_ids [123456789]admin_ids 是你的 Telegram User ID，可以通过 @userinfobot 获取。
启动 Gateway 模式
$
hermes gateway --platform telegram
Telegram 接入成功！
现在在 Telegram 中给你的机器人发消息，Agent 会自动回复。admin_ids 之外的用户消息会被忽略。
现在在 Telegram 中给你的机器人发消息，Agent 会自动回复。admin_ids 之外的用户消息会被忽略。
自定义工具注册
Hermes 的核心能力之一是可以注册任意 Python 函数作为 Agent 工具。
创建工具文件
在 ~/.hermes/tools/ 目录下创建 Python 文件：
# ~/.hermes/tools/my_tools.py
def get_weather(city: str) -> str:
"""Get current weather for a city.
Args:
city: City name (e.g., 'Beijing', 'Shanghai')
Returns:
Weather description with temperature
"""
# 这里可以接入真实的天气 API
return f"The weather in {city} is sunny, 22°C"
def search_jobs(query: str, location: str = "remote") -> str:
"""Search for jobs matching the query.
Args:
query: Job title or keyword
location: Location filter (default: remote)
Returns:
List of matching job openings
"""
# 接入招聘 API（如 LinkedIn、Rust）
return f"Found 3 jobs for '{query}' in {location}: 1) Senior Dev, 2) AI Engineer, 3) Full-stack Dev"注册工具
$
# 工具会被自动发现
hermes tools list确保 ~/.hermes/config.yaml 中启用了自定义工具：
tools:
enabled:
- my_tools # 对应 my_tools.py
disabled: []
安全注意
工具在 Agent 的上下文中执行，Agent 可以调用任意工具。请在
工具在 Agent 的上下文中执行，Agent 可以调用任意工具。请在
admin_ids 中只配置信任的用户，并审查每个工具的代码逻辑。
Cron 定时任务
Hermes 支持 Cron 定时任务，可以在指定时间自动执行并推送结果。
创建 Cron 任务
$
# 创建每日日报任务
hermes cron create \
--name "Daily Report" \
--schedule "0 9 * * *" \
--prompt "Search for the top 3 developer tools news from yesterday. Format as a concise bullet-point report." \
--deliver "telegram" \
--model "anthropic/claude-sonnet-4"Cron 调度表达式参考
| 表达式 | 含义 |
|---|---|
0 9 * * * |
每天 09:00 |
*/15 * * * * |
每 15 分钟 |
0 */2 * * * |
每 2 小时 |
30 18 * * 1-5 |
工作日 18:30 |
管理 Cron 任务
$
# 列出所有任务
hermes cron list
# 暂停任务
hermes cron pause <job_id>
# 恢复任务
hermes cron resume <job_id>
# 删除任务
hermes cron remove <job_id>Mac Mini 24/7 部署
Mac Mini (M1/M2) 是非常适合长期运行 Agent 的硬件 — 功耗低、稳定性高、可以 24/7 运行。
使用 pm2 管理进程
$
# 安装 pm2
npm install -g pm2
# 启动 Hermes Gateway
pm2 start hermes -- gateway --platform telegram --name hermes-agent
# 保存进程列表（重启后自动恢复）
pm2 save
# 设置开机自启
pm2 startup监控与日志
$
# 实时查看日志
pm2 logs hermes-agent
# 查看资源使用
pm2 monit
24/7 部署完成！
Hermes Agent 现在在 Mac Mini 上后台运行，Telegram 随时可响，cron 任务准时执行。
Hermes Agent 现在在 Mac Mini 上后台运行，Telegram 随时可响，cron 任务准时执行。
扩展与进阶
多平台同时运行
$
# 同时启用 Telegram 和 Discord
hermes gateway --platform telegram,discord使用 MCP 服务器
# 在 config.yaml 中配置 MCP
mcp:
servers:
- name: filesystem
command: npx
args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]多模型路由
# 在 config.yaml 中配置模型路由
models:
default: anthropic/claude-sonnet-4
fallback: openai/gpt-4o
routing:
"complex-reasoning": anthropic/claude-opus-4
"fast-response": anthropic/claude-haiku-3Advertisement