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

本文是 Hermes Agent 的一站式使用指南，覆盖安装、配置、首次对话、工具启用、技能系统、多平台网关、定时任务、语音交互到故障排查的完整流程。适合想快速上手 AI 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 安装（最简单）

bash 复制代码

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

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

bash 复制代码

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

# 安装后刷新 shell
source ~/.bashrc  # 或 source ~/.zshrc

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

验证安装

bash 复制代码

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

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

第二步：配置模型提供商

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

交互式配置

bash 复制代码

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

快速配置（Nous Portal）

bash 复制代码

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

手动配置

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

bash 复制代码

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxxxxxx

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

yaml 复制代码

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

或用命令行：

bash 复制代码

hermes config set model openrouter/anthropic/claude-sonnet-4
hermes config set OPENROUTER_API_KEY sk-or-v1-xxxxxxxxxxxx

主流提供商一览

提供商	环境变量	特点
OpenRouter	`OPENROUTER_API_KEY`	聚合多家模型，推荐新手
Anthropic	`ANTHROPIC_API_KEY`	Claude 系列，质量最高
DeepSeek	`DEEPSEEK_API_KEY`	国内可用，性价比高
Nous Portal	OAuth 登录	零配置，自带 Tool Gateway
OpenAI	`OPENAI_API_KEY`	GPT 系列
本地 Ollama	自定义端点	完全离线，隐私优先

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

第三步：首次对话

启动

bash 复制代码

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

测试对话

输入一个简单问题：

复制代码

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

成功的标志：

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

验证会话恢复

bash 复制代码

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

常用斜杠命令

命令	功能
`/help`	查看所有命令
`/tools`	列出可用工具
`/model`	切换模型
`/reset`	新开会话
`/compress`	手动压缩上下文
`/quit`	退出

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

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

第四步：启用工具和技能

查看工具列表

bash 复制代码

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

交互式管理工具

bash 复制代码

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

主要工具集

工具集	功能
`web`	网页搜索和内容提取
`browser`	浏览器自动化
`terminal`	终端命令执行
`file`	文件读写搜索
`code_execution`	沙盒 Python 执行
`vision`	图像分析
`image_gen`	AI 图像生成
`tts`	文字转语音
`memory`	持久化记忆
`session_search`	搜索历史会话
`delegation`	子代理委派

技能系统

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

bash 复制代码

# 浏览技能市场
hermes skills browse

# 搜索技能
hermes skills search "github"

# 安装技能
hermes skills install github

# 在会话中加载技能
/skill github

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

bash 复制代码

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

第五步：配置多平台网关

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

支持的平台

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

启动网关

bash 复制代码

# 配置平台
hermes gateway setup

# 前台运行（调试用）
hermes gateway run

# 后台服务（生产用）
hermes gateway install
hermes gateway start

Telegram 配置示例

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

yaml 复制代码

# ~/.hermes/config.yaml
gateway:
  platforms:
    telegram:
      enabled: true
      token: "${TELEGRAM_BOT_TOKEN}"
      allowed_users:
        - 你的Telegram_User_ID

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

bash 复制代码

TELEGRAM_BOT_TOKEN=7123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

飞书配置示例

yaml 复制代码

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

检查网关状态

bash 复制代码

hermes gateway status

输出示例：

复制代码

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

第六步：高级功能

定时任务（Cron）

bash 复制代码

# 创建定时任务
hermes cron create "0 9 * * *"   # 每天早上 9 点

# 列出任务
hermes cron list

# 手动触发
hermes cron run <job_id>

语音交互

bash 复制代码

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

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

多 Profile 隔离

bash 复制代码

# 创建独立配置
hermes profile create work
hermes profile use work

# 每个 Profile 有独立的：
# - config.yaml
# - .env
# - skills/
# - sessions/
# - memories/

MCP 服务器集成

yaml 复制代码

# ~/.hermes/config.yaml
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"

子代理委派

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

复制代码

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

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

常见问题与排查

1. `command not found: hermes`

bash 复制代码

# 刷新 shell
source ~/.bashrc

# 或重新打开终端

2. 模型返回 401/403

bash 复制代码

# 检查 API Key 是否正确
hermes doctor

# 重新配置
hermes model

3. 工具不可用

bash 复制代码

# 检查工具集是否启用
hermes tools list

# 启用工具后需要重启会话
/reset

4. 网关连不上

bash 复制代码

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

# 检查状态
hermes gateway status

5. 记忆不工作

Hermes 有两个记忆系统：

系统	用途	存储位置
`memory` 工具	长期事实（偏好、环境）	`~/.hermes/memories/`
`session_search` 工具	历史会话全文	`~/.hermes/sessions/`

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

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

6. Windows 环境注意

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

7. 配置修改不生效

修改类型	生效方式
工具/技能	`/reset` 新开会话
Gateway 配置	`hermes gateway restart`
代码修改	重启 CLI 或 Gateway 进程

总结

Hermes Agent 的完整使用流程：

复制代码

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

推荐上手路径：

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

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

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

目录

Hermes Agent 是什么

第一步：安装

环境要求

安装方式

验证安装

第二步：配置模型提供商

交互式配置

快速配置（Nous Portal）

手动配置

主流提供商一览

第三步：首次对话

启动

测试对话

验证会话恢复

常用斜杠命令

第四步：启用工具和技能

查看工具列表

交互式管理工具

主要工具集

技能系统

第五步：配置多平台网关

支持的平台

启动网关

Telegram 配置示例

飞书配置示例

检查网关状态

第六步：高级功能

定时任务（Cron）

语音交互

多 Profile 隔离

MCP 服务器集成

子代理委派

常见问题与排查

1. command not found: hermes

2. 模型返回 401/403

3. 工具不可用

4. 网关连不上

5. 记忆不工作

6. Windows 环境注意

7. 配置修改不生效

总结

参考

1. `command not found: hermes`