Hermes Agent使用教程：安装、模型接入、Skill与Gateway完整指南（2026最新）

前言：Hermes Agent 是什么？

Hermes Agent 是 Nous Research 在 2026 年推的开源 AI Agent 框架。

官方定位就一句话：The agent that grows with you.

它跟 Claude Code、OpenClaw、Cursor 定位不一样：

产品	干啥的
Claude Code	代码仓库里的工程 Agent，编程、重构、测试、代码审查
OpenClaw	全天候自动化生活工作流 Agent，邮件、日历、网页、消息自动化
Hermes Agent	会学习、会沉淀 Skill 的自进化 Agent，长期任务、个人助理、多平台自动化

Hermes 最大的几个特点：

• 支持 20+ 模型 Provider，自由切换模型
• 支持 Skill 系统，能把复杂流程沉淀成可复用技能
• 支持持久记忆，长期记住用户偏好和项目上下文
• 支持 MCP Client / Server 双模式
• 支持 Telegram、Discord、Slack、飞书、企业微信、微信、QQBot 等 17 个消息平台
• 支持本地、Docker、SSH、Modal、Daytona、Singularity 等执行后端

如果你想要一个可以长期运行、能接消息平台、能积累工作流经验的 Agent，Hermes 是目前最值得关注的开源方案之一。

---

一、最新版本能力概览

截至 2026 年 4 月，Hermes Agent 最新版本为 v0.11.0。

重要版本节点

版本	日期	重点
v0.8.0	2026-04-08	Live Model Switching、后台任务通知、Google AI Studio 原生 Provider
v0.9.0	2026-04-13	本地 Web Dashboard、Fast Mode、iMessage / WeChat、Android Termux
v0.10.0	2026-04-16	Nous Tool Gateway：搜索、图片生成、TTS、浏览器自动化
v0.11.0	2026-04-23	React/Ink TUI 重写、Transport 架构、GPT-5.5、QQBot、插件系统、/steer 中途纠偏

v0.11.0 新增重点

• 全新 TUI 界面：基于 React/Ink，支持固定输入框、实时流式输出、状态栏监控
• Transport 架构：统一支持 Anthropic、OpenAI ChatCompletions、Responses API、AWS Bedrock
• 新 Provider：NVIDIA NIM、Arcee AI、Step Plan、Gemini CLI OAuth、Vercel AI Gateway
• GPT-5.5 支持：通过 ChatGPT Codex OAuth 与动态模型发现接入
• QQBot 支持：成为第 17 个消息平台，支持扫码向导
• 插件系统增强：Slash Command、工具直调、工具 veto、自定义 Dashboard Tab
• /steer 命令：Agent 正在跑任务时可以中途纠偏，不需要强行中断

---

二、安装 Hermes Agent

2.1 系统要求

官方支持：

• Linux ✅ 推荐环境
• macOS ✅ 原生支持
• Windows ⚠️ 需使用 WSL2，不支持原生 Windows 命令行
• Android ✅ 通过 Termux 支持

基础依赖：Git、Python、Node.js、ripgrep、ffmpeg

一键安装脚本会自动处理大部分依赖，但建议提前安装 Git。

2.2 一键安装

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

安装器会自动完成：

1. 检查并安装 Python / Node.js / ripgrep / ffmpeg
2. 克隆 Hermes Agent 仓库
3. 创建 Python 虚拟环境
4. 注册全局 hermes 命令
5. 引导配置模型 Provider

安装完成后，重新加载 shell：

source ~/.zshrc
# 或
source ~/.bashrc

验证安装：

hermes version
hermes doctor

2.3 初始化配置

hermes setup

hermes setup 是完整配置向导，会依次引导你配置：

1. 主模型 Provider
2. API Key
3. 默认模型
4. 工具开关
5. Gateway 消息平台
6. 执行环境
7. 记忆与 Skill 系统

如果你只想先配置模型，可以运行：

hermes model

---

三、基础启动方式

# 经典 CLI 模式
hermes

# 现代 TUI 模式（推荐）
hermes --tui

# 恢复上一个会话
hermes --continue

# 查看诊断信息
hermes doctor

进入对话后，常用 Slash 命令：

命令	作用
/new 或 /reset	开启新会话
/model	查看或切换模型
/model provider:model	直接切换模型
/personality	查看 / 切换人格
/skills	查看可用 Skill
/usage	查看 token 与费用
/compress	手动压缩上下文
/retry	重试上一轮
/undo	撤销上一轮
/steer	任务执行中途纠偏

---

四、配置文件结构

Hermes 的所有核心配置都在：~/.hermes/

~/.hermes/
├── config.yaml        # 主配置文件：模型、终端、TTS、压缩、安全等
├── .env               # API Key 与密钥，禁止提交到 git
├── auth.json          # OAuth 凭据，如 Slack、GitHub、Google 等
├── SOUL.md            # Agent 人格定义
├── MEMORY.md          # Agent 自动维护的事实记忆
├── USER.md            # 用户画像与偏好
├── memories/          # 持久记忆目录
├── skills/            # Skill 技能目录
├── cron/              # 定时任务
├── sessions/          # Gateway 会话数据
└── logs/              # 日志

黄金规则：

• API Key 放 ~/.hermes/.env
• 行为配置放 ~/.hermes/config.yaml
• 人格风格放 ~/.hermes/SOUL.md
• 项目规则放项目里的 AGENTS.md / CLAUDE.md

常用配置命令：

hermes config           # 查看当前配置
hermes config edit      # 打开 config.yaml
hermes config set KEY VALUE  # 设置单项配置
hermes config check     # 检查配置合法性
hermes config migrate   # 补全新版本缺失字段

配置优先级： CLI 参数 > config.yaml > .env > 内置默认值

---

五、模型 Provider 配置

5.1 交互式配置

最简单的方式：

hermes model

然后按提示选择 Provider、输入 API Key、选择模型。

Hermes 支持的 Provider 包括：

• Nous Portal / OpenRouter / OpenAI / Anthropic / Google Gemini
• DeepSeek / z.ai / GLM / Kimi / Moonshot / MiniMax
• NVIDIA NIM / AWS Bedrock / Vercel AI Gateway
• Hugging Face / 自定义 OpenAI Compatible Endpoint

5.2 OpenAI 官方配置

# ~/.hermes/config.yaml
provider: openai
model: gpt-5.5

# ~/.hermes/.env
OPENAI_API_KEY=sk-xxxxxxxxxx

5.3 Anthropic / Claude 配置

provider: anthropic
model: claude-sonnet-4-6

ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxx

5.4 DeepSeek 配置

DeepSeek 是长期运行和成本敏感场景的首选。尤其适合 Hermes 这种工具定义较多、请求频繁的 Agent。

provider: deepseek
model: deepseek-v4-pro

DEEPSEEK_API_KEY=sk-xxxxxxxxxx

轻量任务可以用：

provider: deepseek
model: deepseek-v4-flash

推荐搭配：

• 复杂任务 / 编程 / 长上下文 → deepseek-v4-pro
• 日常对话 / 压缩 / 子任务 → deepseek-v4-flash

5.5 MiniMax 配置

MiniMax 官方 Token Plan 支持 Hermes Agent，推荐模型为 MiniMax-M2.7。

hermes model

选择：

• Provider: MiniMax
• Model: MiniMax-M2.7

然后输入 Token Plan API Key。

注意：MiniMax Token Plan API Key 和普通按量付费 API Key 不同，需要在 Token Plan 管理页单独生成。

如果手动配置：

provider: minimax
model: MiniMax-M2.7

MINIMAX_API_KEY=你的 MiniMax Token Plan Key

5.6 Kimi / Moonshot 配置

provider: moonshot
model: kimi-k2.5

MOONSHOT_API_KEY=sk-xxxxxxxxxx

如果使用 Kimi K2.6 API，可根据官方最新 model id 替换。

5.7 GLM / 智谱配置

provider: z-ai
model: glm-5.1

ZAI_API_KEY=你的智谱 API Key

常用模型：

• glm-5.1（旗舰能力）
• glm（平衡）
• glm-5-turbo（快速）

5.8 OpenRouter 配置

OpenRouter 适合一个 Key 接入 200+ 模型：

provider: openrouter
model: deepseek/deepseek-chat-v3-0324

OPENROUTER_API_KEY=sk-or-xxxxxxxxxx

5.9 自定义 OpenAI Compatible Endpoint

如果你使用中转站或私有网关，把 Provider 设为 openai，再配置 OPENAI_BASE_URL。

provider: openai
model: claude-opus-4-7

OPENAI_BASE_URL=https://hongmacc.com/v1
OPENAI_API_KEY=sk-xxxxxxxxxx

---

六、接入中转 API

如果你要长期挂机跑 Hermes，官方 API 会遇到两个问题：

1. 高频请求容易触发 429
2. 主模型 + 辅助模型分散在多个平台，不好统一记账

可以考虑使用中转 API。

6.1 基础配置

# ~/.hermes/config.yaml
provider: openai
model: claude-opus-4-7

# ~/.hermes/.env
OPENAI_BASE_URL=https://hongmacc.com/v1
OPENAI_API_KEY=你的 HongMaCC Key

重启 Hermes：

hermes --tui

6.2 推荐模型搭配

任务	推荐模型	说明
主任务 / 深度推理	claude-opus-4-7	工具调用稳定，适合复杂 Agent 循环
日常任务	claude-sonnet-4-6	速度和质量平衡
GPT 生态任务	gpt-5.4	OpenAI 生态兼容性强
上下文压缩	gpt-5.4-mini	低成本即可胜任
子 Agent / delegation	gpt-5.4-mini	控制成本

6.3 主模型 + 辅助模型都走中转

provider: openai
model: claude-opus-4-7
auxiliary:
  compression:
    provider: openai
    base_url: https://hongmacc.com/v1
    api_key: ${OPENAI_API_KEY}
    model: gpt-5.4-mini
  delegation:
    provider: openai
    base_url: https://hongmacc.com/v1
    api_key: ${OPENAI_API_KEY}
    model: gpt-5.4-mini

6.4 验证是否生效

hermes --debug

确认日志中 base_url 指向：https://hongmacc.com/v1

开启费用显示：

hermes config set display.show_cost true

---

七、辅助模型与降本配置

Hermes 每次请求会携带大量工具定义，固定开销较高：

• CLI 模式：6,000–8,000 tokens / 次
• Gateway 消息平台：15,000–20,000 tokens / 次

因此强烈建议：主模型用强模型，辅助任务用便宜模型。

7.1 辅助模型配置

auxiliary:
  compression:
    provider: deepseek
    model: deepseek-v4-flash
  delegation:
    provider: deepseek
    model: deepseek-v4-flash
  vision:
    provider: openai
    model: gpt-4.1-vision

7.2 上下文压缩

compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20

含义：

• 上下文超过 50% 时自动压缩
• 保留最近 20% 内容不压缩
• 最近 20 条消息永远保留原文

7.3 选择有缓存优惠的模型

DeepSeek 对 Prompt Cache 命中价格极低，适合 Hermes 这种每次都携带相似工具定义的场景。

推荐：

• 主任务：deepseek-v4-pro
• 压缩：deepseek-v4-flash
• 子任务：deepseek-v4-flash

---

八、执行环境配置

Hermes 支持多种 Terminal Backend：

Backend	运行位置	适合场景
local	本机	日常使用、开发调试
docker	Docker 容器	安全沙箱、生产环境
ssh	远程服务器	远程运维、多机管理
modal	Modal 云沙箱	临时云计算任务
daytona	Daytona 工作区	托管云环境
singularity	HPC 容器	高性能集群

8.1 本地模式

terminal:
  backend: local
  persistent_shell: false

8.2 Docker 沙箱模式（推荐）

terminal:
  backend: docker
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  docker_mount_cwd_to_workspace: false
  docker_forward_env:
    - GITHUB_TOKEN
  docker_volumes:
    - /home/user/projects:/workspace/projects
    - /home/user/data:/data:ro
  container_cpu: 2
  container_memory: 8192
  container_disk: 51200

Docker 模式适合让 Agent 执行代码、跑脚本、访问文件时降低风险。

8.3 SSH 远程模式

# .env
TERMINAL_SSH_HOST=my-server.example.com
TERMINAL_SSH_USER=ubuntu
TERMINAL_SSH_PORT=22
TERMINAL_SSH_KEY=/path/to/private_key
TERMINAL_SSH_PERSISTENT=true

适合让 Hermes 操作远程服务器。

---

九、SOUL.md：定制 Agent 人格

SOUL.md 是 Hermes 的人格文件，每次会话都会注入系统提示。

位置：~/.hermes/SOUL.md

示例：

你是一个高效、谨慎的技术助理。
沟通风格：
- 回答简洁，不写空话
- 不确定时直接说明
- 涉及风险操作先询问
执行偏好：
- 文件修改前先读取现有内容
- 长任务先拆步骤
- 优先给出可运行方案

不建议写进 SOUL.md 的内容：

不建议	原因
项目路径	项目会变化，应放 AGENTS.md
一次性任务	会污染长期人格
过长文档	增加每次请求 token 开销

人格切换：

/personality technical
/personality teacher
/personality creative

自定义人格：

agent:
  personalities:
    codereview: >
      你是严格的代码审查者，重点关注安全、性能和可维护性。

使用：/personality codereview

---

十、Skill 技能系统

Skill 是 Hermes 的核心能力：Agent 完成复杂任务后，可以把流程沉淀为可复用技能。

10.1 Skill 目录结构

~/.hermes/skills/
└── devops/
    └── deploy-check/
        ├── SKILL.md
        ├── scripts/
        ├── templates/
        └── references/

10.2 SKILL.md 示例

---
name: deploy-check
description: 检查服务部署状态并输出摘要
version: 1.0.0
platforms: [linux, macos]
metadata:
  hermes:
    tags: [devops, monitoring]
    category: operations
---

# 部署检查

## When to Use

当需要确认服务是否正常运行时使用。

## Procedure

1. 检查 systemd 服务状态
2. 查看最近日志
3. 检查端口监听
4. 输出摘要

## Pitfalls

- systemd 服务名区分大小写
- 日志可能被轮转

## Verification

服务 active，端口正常，无 ERROR 日志。

10.3 常用 Skill 命令

# 查看技能
hermes skills list

# 从 GitHub 安装
hermes skills install github:username/repo/skills/my-skill

# 从 ClawHub 安装
hermes skills install openai/skills/k8s

# 让 Agent 自动创建 Skill
# 在对话中说："把刚才这个流程保存成 Skill，名字叫 deploy-check"

10.4 外部 Skill 目录

skills:
  external_dirs:
    - ~/.agents/skills
    - /home/shared/team-skills

适合团队共享工作流。

---

十一、记忆系统

Hermes 会维护两类记忆：

• MEMORY.md — 项目信息、工作流、环境事实
• USER.md — 用户偏好、背景、习惯

配置：

memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

注意：这些内容每次请求都会进入上下文，越长越贵。建议定期清理过时记忆。

---

十二、MCP 集成

Hermes 支持 MCP Client 和 MCP Server 双模式。

12.1 作为 MCP Client

Hermes 可以连接外部 MCP Server，调用 GitHub、Figma、数据库、浏览器、文件系统等工具。

常见 MCP：

MCP Server	用途
GitHub MCP	Issue、PR、仓库管理
Filesystem MCP	本地文件读写
Context7 MCP	获取最新库文档
Figma Dev MCP	从设计稿生成代码
PostgreSQL MCP	查询数据库
Firecrawl MCP	网页抓取

12.2 作为 MCP Server

Hermes 可以暴露自己的会话、记忆和对话接口给其他 MCP 客户端使用：

hermes mcp serve

可被 Claude Desktop、Cursor、VS Code 等 MCP Client 调用。

典型能力：

• 浏览 Hermes 会话
• 搜索历史消息
• 读取附件
• 复用 Hermes 的 Skill 与记忆

---

十三、消息网关 Gateway

Hermes Gateway 可以让 Agent 接入聊天平台，像真人助理一样收发消息。

13.1 支持平台

截至 v0.11.0，支持约 17 个平台：

Telegram / Discord / Slack / WhatsApp / Signal / Email
Matrix / 钉钉 / 飞书 / 企业微信 / 微信
iMessage / QQBot / Mattermost / Home Assistant / Webhook / SMS

13.2 配置 Gateway

hermes gateway setup
hermes gateway start

重启：

hermes gateway restart

13.3 飞书配置

hermes gateway setup

选择 Feishu / Lark 后输入：

• App ID
• App Secret
• Encrypt Key（如有）
• Verification Token（如有）

支持：群聊 / 私聊 / 图片 / 文件附件 / 消息卡片 / 交互式按钮回调

13.4 企业微信 / 微信

企业微信（WeCom）支持：文本 / 图片 / 语音 / 群聊 / 回调验证

普通微信通常依赖兼容层或第三方 Gateway，部署时要注意稳定性和账号风控。

13.5 Gateway 安全建议

不要把 Gateway 端口裸露到公网。推荐方式：

# 使用 Tailscale，只在私有网络暴露
tailscale serve 7860

# 或使用 Nginx + IP 白名单

---

十四、定时任务 Cron

Hermes 可以定时执行任务：

# 每天早上 8:30 总结新闻
hermes cron add "30 8 * * *" "总结今日 AI 新闻并发到 Telegram"

# 每小时检查服务状态
hermes cron add "0 * * * *" "检查服务器状态并报告异常"

适合：

• 每日报告
• 服务巡检
• 定时抓取网页
• 自动生成周报
• 监控 GitHub Issue

---

十五、安全配置

如果你让 Hermes 长期运行，一定要做安全限制。

15.1 基础安全配置

security:
  redact_secrets: true
  tirith_enabled: true
  tirith_fail_open: true
  website_blocklist:
    enabled: true
    domains:
      - "*.internal.company.com"
  approvals:
    mode: smart
  code_execution:
    mode: project
    timeout: 300
    max_tool_calls: 50

15.2 approvals 模式

模式	含义	适合场景
smart	高风险操作需要确认	日常推荐
manual	所有操作都确认	高安全场景
off	全自动执行	私有沙箱 / 挂机任务

15.3 最佳实践

• API Key 只放 .env
• Gateway 不暴露公网
• 生产任务用 Docker backend
• 开启 redact_secrets
• 限制 max_tool_calls 防止死循环
• 不要给 Agent root 权限

---

十六、常见问题排查

16.1 命令不存在：hermes not found

source ~/.zshrc
# 或
source ~/.bashrc

如果仍不行，检查 PATH。

16.2 模型上下文不足

错误：Model context window is below minimum

解决：换至少 64K 上下文的模型，例如：

• deepseek-v4-pro
• deepseek-v4-flash
• claude-sonnet-4-6
• claude-opus-4-7
• kimi-k2.5 / kimi-k2.6

16.3 429 Rate Limit

来源	解决
Provider 限流	换模型 / 换 Provider / 降低并发
Skill 市场限流	稍后重试
本地任务过多	降低 max_turns / max_tool_calls

可配置 fallback：

hermes config set fallback.provider deepseek
hermes config set fallback.model deepseek-v4-flash

16.4 Gateway 收不到消息

hermes gateway status
hermes gateway logs

常见原因：

• Webhook 地址不可访问
• 平台 App Secret 填错
• 群聊没有 @ 机器人
• Gateway 工作目录未设置

16.5 Skill 不生效

hermes skills list

确认：

• SKILL.md 文件存在
• 目录结构正确
• frontmatter 格式正确
• 所需工具集已开启

---

十七、完整配置模板

# ~/.hermes/config.yaml

# 主模型
provider: deepseek
model: deepseek-v4-pro

# 执行环境
terminal:
  backend: docker
  docker_image: nikolaik/python-nodejs:python3.11-nodejs20
  docker_mount_cwd_to_workspace: false
  container_cpu: 2
  container_memory: 8192
  container_disk: 51200

# Agent 行为
agent:
  max_turns: 90
  reasoning_effort: ""
  tool_use_enforcement: auto

# 记忆系统
memory:
  memory_enabled: true
  user_profile_enabled: true
  memory_char_limit: 2200
  user_char_limit: 1375

# 上下文压缩
compression:
  enabled: true
  threshold: 0.50
  target_ratio: 0.20
  protect_last_n: 20

# 辅助模型
auxiliary:
  compression:
    provider: deepseek
    model: deepseek-v4-flash
  delegation:
    provider: deepseek
    model: deepseek-v4-flash

# 安全
approvals:
  mode: smart
security:
  redact_secrets: true
  tirith_enabled: true
  tirith_fail_open: true
code_execution:
  mode: project
  timeout: 300
  max_tool_calls: 50

# Gateway
group_sessions_per_user: true
unauthorized_dm_behavior: pair

# 显示
display:
  tool_progress: all
  show_cost: true

# ~/.hermes/.env
DEEPSEEK_API_KEY=sk-xxxxxxxxxx
OPENAI_API_KEY=sk-xxxxxxxxxx
OPENAI_BASE_URL=https://hongmacc.com/v1
ANTHROPIC_API_KEY=sk-ant-xxxxxxxxxx
MOONSHOT_API_KEY=sk-xxxxxxxxxx
MINIMAX_API_KEY=sk-xxxxxxxxxx
ZAI_API_KEY=sk-xxxxxxxxxx
OPENROUTER_API_KEY=sk-or-xxxxxxxxxx

---

十八、推荐配置方案

方案 A：低成本长时间挂机

provider: deepseek
model: deepseek-v4-pro
auxiliary:
  compression:
    provider: deepseek
    model: deepseek-v4-flash
  delegation:
    provider: deepseek
    model: deepseek-v4-flash

适合：自动日报、定时巡检、长时间运行任务。

方案 B：高质量复杂任务

provider: openai
model: claude-opus-4-7
auxiliary:
  compression:
    provider: openai
    model: gpt-5.4-mini

配合中转统一 Key。适合：复杂代码任务、长链路 Agent、重要工作流。

方案 C：MiniMax Token Plan

provider: minimax
model: MiniMax-M2.7

适合：已经购买 MiniMax Token Plan 的用户。

方案 D：OpenRouter 全家桶

provider: openrouter
model: anthropic/claude-sonnet-4-6

适合：想一个 Key 切换多模型的用户。

---

十九、总结

Hermes Agent 最适合以下人群：

• 想要一个长期运行的个人 AI 助理
• 想把重复工作流沉淀成 Skill
• 想接入 Telegram / 飞书 / 微信 / QQBot 等消息平台
• 想在 Claude、GPT、DeepSeek、Kimi、MiniMax 之间自由切换
• 想用 Docker / SSH 后端把 Agent 放到服务器跑

不太适合：

• 只想写代码，且不需要消息平台 → 直接用 Claude Code 更简单
• 不愿意配置 API Key 和 YAML → 可能会觉得门槛高
• 要求完全稳定的企业级生产环境 → 目前更新很快，建议先小范围试用

一句话总结：

Claude Code 是最强的编程 Agent，OpenClaw 是生活自动化 Agent，Hermes Agent 则是最像”会学习的个人 AI 助理”的开源 Agent。