Hermes Agent 完全指南

Hermes Agent 是由 Nous Research 开发的开源 AI Agent 框架，可在终端、消息平台和 IDE 中运行。它属于与 Claude Code、OpenAI Codex、OpenClaw 同类的自主编码与任务执行代理，通过工具调用与系统交互。

Hermes 的核心设计理念是提供商无关——你可以在 OpenRouter、Anthropic、OpenAI、DeepSeek、Google Gemini 等 15+ 提供商之间自由切换模型，无需修改任何工作流。

一、架构概述

Hermes Agent 的架构分为三层：

核心引擎 (Core) — 负责工具调用、会话管理、记忆系统和技能系统的编排
网关 (Gateway) — 多平台消息网关，将 Telegram、Discord、Slack、Matrix 等 10+ 平台的消息统一路由到核心引擎
CLI 层 — 终端交互界面（TUI），支持 /slash 命令和会话管理

数据存储方面：

会话历史：本地 SQLite（~/.hermes/sessions/）
记忆：Hindsight 语义搜索 + 持久化记忆文件
技能：~/.hermes/skills/ 下的 SKILL.md 文件
配置：~/.hermes/config.yaml + ~/.hermes/.env

二、安装方式

方式一：一键安装脚本（推荐）

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

脚本会自动检测系统环境，安装依赖，并创建 hermes 命令。安装完成后：

hermes doctor        # 检查依赖和配置
hermes --version     # 查看版本

方式二：pip 安装

pip install hermes-agent

或者从源码安装：

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

方式三：Docker 部署

Hermes 提供了官方 Docker 镜像，适合服务器端持续运行：

docker pull nousresearch/hermes-agent:latest

基础运行：

docker run -it --rm \
  -v ~/.hermes:/home/hermes/.hermes \
  nousresearch/hermes-agent:latest \
  hermes chat

使用 Docker Compose 持久化运行（推荐）：

# docker-compose.yml
version: '3.8'
services:
  hermes:
    image: nousresearch/hermes-agent:latest
    container_name: hermes
    restart: unless-stopped
    volumes:
      - ~/.hermes:/home/hermes/.hermes
    environment:
      - OPENROUTER_API_KEY=${OPENROUTER_API_KEY}
      - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
      - TZ=Asia/Shanghai
    command: hermes gateway run

启动：

docker compose up -d

Docker 部署注意事项：

务必挂载 ~/.hermes 目录，否则重启后配置丢失
API Key 通过环境变量传入，或提前在 ~/.hermes/.env 中配置
如果使用网关模式，需要暴露对应端口（如 Telegram 不需要额外端口）
ARM 架构（如 Oracle ARM、树莓派）完全兼容，镜像支持 multi-arch

三、初始化配置

首次运行需要配置模型提供商：

hermes setup          # 交互式配置向导
hermes model          # 选择和切换模型

常用的提供商配置示例（~/.hermes/.env）：

OPENROUTER_API_KEY=sk-or-v1-xxxxxxxx
ANTHROPIC_API_KEY=sk-ant-xxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxx
DEEPSEEK_API_KEY=sk-xxxxxxxx

配置模型（~/.hermes/config.yaml）：

default_model: deepseek/deepseek-chat
provider: openrouter

# 也可以使用 Anthropic 直连
# default_model: claude-sonnet-4-20250514
# provider: anthropic

四、核心功能详解

技能系统 (Skills)

技能是 Hermes 的程序性记忆——将复杂的任务流程保存为可复用的 SKILL.md 文件。当你完成一个复杂操作后，可以将其保存为技能，下次直接加载执行。

hermes skills browse          # 浏览技能库
hermes skills install <name>  # 安装社区技能

技能文件结构：

~/.hermes/skills/
├── devops/
│   ├── SKILL.md
│   └── scripts/
├── github/
│   └── SKILL.md
└── mlops/
    └── SKILL.md

记忆系统 (Memory)

Hermes 支持跨会话持久记忆，包括：

Hindsight 记忆 — 基于语义搜索的长时记忆，自动索引历史会话
显性记忆 — 手动保存的用户偏好、环境事实、项目约定
会话搜索 — FTS5 全文搜索历史会话内容

多平台网关

Hermes 可以通过网关同时运行在多个消息平台上：

hermes gateway run

支持的平台：Telegram、Discord、Slack、Matrix、Signal、WeChat、WhatsApp、X/Twitter DM 等。每个平台需要在 config.yaml 中配置对应的 Token 或 Webhook URL。

定时任务 (Cron)

支持创建周期性任务：

hermes cron create --schedule "0 9 * * *" --prompt "每天早报"

MCP 协议支持

Hermes 内置原生 MCP（Model Context Protocol）客户端，可以连接任意 MCP 服务器来扩展工具集：

# config.yaml 配置
mcp:
  servers:
    time:
      command: uvx
      args: [mcp-server-time]
    fetch:
      command: uvx
      args: [mcp-server-fetch]

五、Docker 部署详解

生产环境 Docker Compose

适合在服务器上长期运行 Hermes 网关的完整配置：

# docker-compose.yml
version: '3.8'
services:
  hermes-gateway:
    image: nousresearch/hermes-agent:latest
    container_name: hermes-gateway
    restart: unless-stopped
    user: "1000:1000"
    volumes:
      - /path/to/hermes/data:/home/hermes/.hermes
    env_file:
      - .env
    environment:
      - TZ=Asia/Shanghai
    command: hermes gateway run
    logging:
      driver: json-file
      options:
        max-size: 10m
        max-file: 3

使用 Docker 运行单次任务

echo "你的问题" | docker run -i --rm \
  -v ~/.hermes:/home/hermes/.hermes \
  nousresearch/hermes-agent:latest \
  hermes chat -q "$(cat)"

Docker 更新

docker compose pull
docker compose up -d

使用 systemd 管理 Docker 容器

# /etc/systemd/system/hermes-gateway.service
[Unit]
Description=Hermes Gateway
After=docker.service
Requires=docker.service

[Service]
Restart=always
RestartSec=10
WorkingDirectory=/opt/hermes
ExecStart=/usr/bin/docker compose up
ExecStop=/usr/bin/docker compose down

[Install]
WantedBy=multi-user.target

sudo systemctl enable --now hermes-gateway

六、WebUI 常见问题 (FAQ)

Q: 启动后 WebUI 页面空白或无法加载

原因： 端口被占用或 Gateway 未正确启动。

解决：

# 检查 Gateway 日志
docker logs hermes-gateway

# 确认端口占用
ss -tlnp | grep 8080

# 修改端口（config.yaml）
gateway:
  webui_port: 8081  # 改为其他端口

Q: WebUI 显示 "Cannot connect to Hermes core"

原因： WebUI 无法与 Hermes 核心引擎建立连接。

解决：

确认 hermes gateway run 或容器正在运行
检查防火墙是否放行了 WebSocket 连接
反向代理需要配置 WebSocket 支持（Nginx 需添加 Upgrade/Connection 头）

Q: Docker 容器重启后配置丢失

原因： 未挂载 .hermes 数据卷。

解决： 始终使用 -v ~/.hermes:/home/hermes/.hermes 挂载持久化目录。

Q: 模型响应慢或超时

原因：

API Key 速率限制
选择的模型负载过高
网络延迟

解决：

切换为更快的模型（如 deepseek-chat 比 claude-opus 快）
检查 API 账户余额
使用 OpenRouter 等聚合提供商进行 fallback

Q: Skills 不生效或加载失败

原因： SKILL.md 格式错误或路径不对。

解决：

确保 SKILL.md 包含正确的 YAML frontmatter
检查文件是否在 ~/.hermes/skills/ 下
运行 hermes skills browse 确认是否加载

Q: Telegram / Discord 消息不响应

原因：

Bot Token 配置错误或过期
Webhook URL 失效
网关未运行

解决：

重新生成 Bot Token 并更新 config.yaml
确认网关处于运行状态：hermes gateway status
检查网络是否能访问对应平台 API

七、常用 CLI 命令速查

hermes doctor              # 检查环境
hermes setup               # 配置向导
hermes model               # 切换模型
hermes chat -q "问题"      # 单次查询
hermes --continue          # 恢复最近会话
hermes gateway run         # 启动消息网关
hermes gateway status      # 网关状态
hermes skills browse       # 浏览技能库
hermes skills install <name>  # 安装技能
hermes cron list           # 查看定时任务
hermes update              # 更新到最新版

八、相关资源

官方文档：hermes-agent.nousresearch.com/docs
GitHub：github.com/NousResearch/hermes-agent
配置文件参考：Configuration · Hermes Agent

gink的笔记

Hermes Agent 完全指南

Hermes Agent 完全指南

一、架构概述

二、安装方式

方式一：一键安装脚本（推荐）

方式二：pip 安装

方式三：Docker 部署

三、初始化配置

四、核心功能详解

技能系统 (Skills)

记忆系统 (Memory)

多平台网关

定时任务 (Cron)

MCP 协议支持

五、Docker 部署详解

生产环境 Docker Compose

使用 Docker 运行单次任务

Docker 更新

使用 systemd 管理 Docker 容器

六、WebUI 常见问题 (FAQ)

Q: 启动后 WebUI 页面空白或无法加载

Q: WebUI 显示 "Cannot connect to Hermes core"

Q: Docker 容器重启后配置丢失

Q: 模型响应慢或超时

Q: Skills 不生效或加载失败

Q: Telegram / Discord 消息不响应

七、常用 CLI 命令速查

八、相关资源

Administrator

Hermes Agent 完全指南

一、架构概述

二、安装方式

方式一：一键安装脚本（推荐）

方式二：pip 安装

方式三：Docker 部署

三、初始化配置

四、核心功能详解

技能系统 (Skills)

记忆系统 (Memory)

多平台网关

定时任务 (Cron)

MCP 协议支持

五、Docker 部署详解

生产环境 Docker Compose

使用 Docker 运行单次任务

Docker 更新

使用 systemd 管理 Docker 容器

六、WebUI 常见问题 (FAQ)

Q: 启动后 WebUI 页面空白或无法加载

Q: WebUI 显示 "Cannot connect to Hermes core"

Q: Docker 容器重启后配置丢失

Q: 模型响应慢或超时

Q: Skills 不生效或加载失败

Q: Telegram / Discord 消息不响应

七、常用 CLI 命令速查

八、相关资源

Xray 使用与节点搭建指南

OpenClaw 完全指南

Administrator