Hermes Agent 完全使用指南：从安装到多平台部署的全流程教程

本文是 Hermes Agent 的一站式使用指南，覆盖安装、配置、首次对话、工具启用、技能系统、多平台网关、定时任务、语音交互到故障排查的完整流程。适合想快速上手 AI Agent 的开发者。

目录

• Hermes Agent 是什么
• 第一步：安装
• 第二步：配置模型提供商
• 第三步：首次对话
• 第四步：启用工具和技能
• 第五步：配置多平台网关
• 第六步：高级功能
• 常见问题与排查
• 参考

Hermes Agent 是什么

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架，运行在终端、即时通讯平台和 IDE 中。它与 Claude Code（Anthropic）、Codex（OpenAI）、OpenClaw 属于同一品类——自主编码和任务执行 Agent，通过工具调用与系统交互。

核心差异化能力：

• 技能自学习：解决复杂问题后自动保存为 Skill，下次遇到类似任务直接复用
• 跨会话记忆：记住你的偏好、环境、习惯，不只是一次性对话
• 多平台网关：同一个 Agent 同时服务 Telegram、飞书、微信、QQ 等 15+ 平台
• 模型无关：支持 18+ 提供商（OpenRouter、Anthropic、DeepSeek、本地模型等），随时切换
• 配置隔离：通过 Profile 运行多个独立实例，互不干扰

架构图：

┌─────────────────────────────────────────────────────────┐ │ User Interfaces │ │ Terminal CLI │ Telegram │ 飞书 │ 微信 │ IDE │ └───────────────────────────┬─────────────────────────────┘ │ ┌───────────────────────────▼─────────────────────────────┐ │ Hermes Agent Core │ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ │ │ │ Tools │ │ Memory │ │ Skills │ │ │ │ (15+ 内置) │ │ (跨会话) │ │ (可扩展) │ │ │ └───────────┘ └───────────┘ └───────────┘ │ │ ┌──────────────────────────────┐ │ │ │ LLM Provider Router │ │ │ │ (18+ 提供商，自动故障转移) │ │ │ └──────────────────────────────┘ │ └─────────────────────────────────────────────────────────┘

第一步：安装

环境要求

• Python 3.10+
• Git
• 至少一个 LLM 提供商的 API Key

安装方式

方式 A：pip 安装（最简单）

pipinstallhermes-agent hermes postinstall# 可选：安装 Node.js、浏览器、ripgrep、ffmpeg

方式 B：Git 安装器（跟踪最新版）

# Linux / macOS / WSL2curl-fsSLhttps://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh|bash# 安装后刷新 shellsource~/.bashrc# 或 source ~/.zshrc

Windows 用户注意：原生 Windows 不支持，必须先安装 WSL2，在 WSL2 的 Ubuntu 中运行上述命令。

验证安装

hermes--version# 查看版本hermes doctor# 诊断环境

hermes doctor会检查 Python 版本、Node.js、依赖库、配置文件是否就绪。如果报错，先修复再继续。

第二步：配置模型提供商

这是最关键的一步。Hermes 支持 18+ 提供商，推荐新手用 OpenRouter（聚合多家模型，一个 Key 用所有）。

交互式配置

hermes model# 交互式选择提供商和模型

快速配置（Nous Portal）

hermes setup--portal# 一键登录 Nous，设置提供商，启用 Tool Gateway

手动配置

编辑~/.hermes/.env添加 API Key：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxx

编辑~/.hermes/config.yaml设置模型：

model:default:"openrouter/anthropic/claude-sonnet-4"provider:"openrouter"

或用命令行：

hermes configsetmodel openrouter/anthropic/claude-sonnet-4 hermes configsetOPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

主流提供商一览

最低要求：模型必须支持 ≥64K token 上下文。本地模型需设置--ctx-size 65536。

第三步：首次对话

启动

hermes# 经典 CLIhermes--tui# 现代 TUI 界面（推荐）

测试对话

输入一个简单问题：

你能做什么？列出你可用的工具。

成功的标志：

• 显示你选择的模型/提供商
• 正常回复，无报错
• 能调用工具（如果需要）

验证会话恢复

# 退出后重新进入hermes--continue# 恢复最近会话hermes-c# 简写形式

常用斜杠命令

多行输入：Alt+Enter或Shift+Enter

中断回复：直接输入新消息按 Enter，或Ctrl+C

第四步：启用工具和技能

查看工具列表

hermes tools list# 列出所有工具和状态

交互式管理工具

hermes tools# curses 界面，空格启用/禁用

主要工具集

技能系统

技能是 Hermes 的"可复用知识"——解决过的问题、发现的流程、踩过的坑，都可以保存为 Skill。

# 浏览技能市场hermes skills browse# 搜索技能hermes skills search"github"# 安装技能hermes skillsinstallgithub# 在会话中加载技能/skill github

创建自定义技能：在会话中完成复杂任务后，Hermes 会自动提议保存为 Skill。你也可以手动创建：

# 技能文件位置~/.hermes/skills/你的技能名/SKILL.md

第五步：配置多平台网关

这是 Hermes 最强大的功能之一——一个 Agent 同时服务多个即时通讯平台。

支持的平台

Telegram、Discord、Slack、飞书、微信、QQ、WhatsApp、Signal、Matrix、Email、SMS 等 15+ 平台。

启动网关

# 配置平台hermes gateway setup# 前台运行（调试用）hermes gateway run# 后台服务（生产用）hermes gatewayinstallhermes gateway start

Telegram 配置示例

1. 在 Telegram 搜索 @BotFather，发送/newbot，获得 Bot Token
2. 配置：

# ~/.hermes/config.yamlgateway:platforms:telegram:enabled:truetoken:"${TELEGRAM_BOT_TOKEN}"allowed_users:-你的Telegram_User_ID

3. 在~/.hermes/.env中添加：

TELEGRAM_BOT_TOKEN=7123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

飞书配置示例

gateway:platforms:feishu:enabled:trueapp_id:"${FEISHU_APP_ID}"app_secret:"${FEISHU_APP_SECRET}"use_websocket:true# 无需公网 IP

检查网关状态

hermes gateway status

输出示例：

Gateway: running (PID: 12345) Platforms: telegram: connected ✓ feishu: connected ✓ wechat: connected ✓

第六步：高级功能

定时任务（Cron）

# 创建定时任务hermescroncreate"0 9 * * *"# 每天早上 9 点# 列出任务hermescronlist# 手动触发hermescronrun<job_id>

语音交互

# 启用语音模式（在会话中）/voice on# 语音输入 + 语音输出/voice tts# 只有语音输出/voice off# 关闭语音

语音转文字支持：本地 faster-whisper（免费）、Groq Whisper（免费额度）、OpenAI Whisper（付费）。

多 Profile 隔离

# 创建独立配置hermes profile create work hermes profile use work# 每个 Profile 有独立的：# - config.yaml# - .env# - skills/# - sessions/# - memories/

MCP 服务器集成

# ~/.hermes/config.yamlmcp_servers:github:command:npxargs:["-y","@modelcontextprotocol/server-github"]env:GITHUB_PERSONAL_ACCESS_TOKEN:"ghp_xxx"

子代理委派

在会话中，Hermes 可以生成独立的子代理并行处理任务：

帮我同时完成两件事： 1. 搜索最新的 Python 3.13 新特性 2. 检查 ~/myproject 的代码质量

Hermes 会自动拆分任务并委派给子代理。

常见问题与排查

1.command not found: hermes

# 刷新 shellsource~/.bashrc# 或重新打开终端

2. 模型返回 401/403

# 检查 API Key 是否正确hermes doctor# 重新配置hermes model

3. 工具不可用

# 检查工具集是否启用hermes tools list# 启用工具后需要重启会话/reset

4. 网关连不上

# 检查日志grep-i"error"~/.hermes/logs/gateway.log|tail-20# 检查状态hermes gateway status

5. 记忆不工作

Hermes 有两个记忆系统：

如果"机器人不记得上周聊的内容"，检查：

1. 会话文件是否被清理：hermes sessions stats
2. 重要信息是否保存到了 memory

6. Windows 环境注意

• 必须使用 WSL2，不要用原生 PowerShell
• Gateway 不支持 systemd，需要用 Python keepalive 脚本 + Windows 计划任务
• 记忆文件可能是 UTF-16-LE 编码，用 Python 读取时加errors='replace'

7. 配置修改不生效

总结

Hermes Agent 的完整使用流程：

安装 → 配置模型 → 首次对话 → 启用工具 → 配置网关 → 高级功能 ↓ ↓ ↓ ↓ ↓ ↓ pip hermes model hermes hermes tools hermes cron/ install --tui enable gateway voice/ setup profile

推荐上手路径：

1. Day 1：安装 + 配置一个提供商 + 跑通首次对话
2. Day 2：启用常用工具（terminal、file、web）+ 安装几个技能
3. Day 3：配置一个即时通讯平台（推荐 Telegram）
4. Day 4+：按需探索 Cron、语音、多 Profile、MCP 等高级功能

核心原则：先跑通一个干净的工作流，再加高级功能。

参考

• Hermes Agent 官方文档
• Hermes Agent GitHub
• 快速入门指南
• 提供商配置文档
• 消息网关文档
• 工具参考手册