Hermes Agent 完整上手指南 — 从安装到高级玩法的全方位教程

本文是基于 Hermes Agent 官方文档及社区实践整理的完整上手指南，涵盖从安装到高级功能的全部核心内容。如果你是第一次接触 Hermes Agent，这篇文章可以帮你从零到一快速上手。

什么是 Hermes Agent

Hermes Agent 是一个开源的、自我改进的 AI Agent 框架，由 Nous Research 团队构建。它不是一个绑定在 IDE 里的编码助手，也不是一个单一 API 的聊天机器人包装器——它是一个真正的自主 Agent，运行时间越长就越智能。

截至 2026 年 6 月，Hermes Agent 在 GitHub 上已获得 185,927 Stars、31,983 Forks，采用 MIT 许可协议，主语言为 Python。

核心特性一览：

一、在 60 秒内安装 Hermes Agent

Hermes Agent 支持 Linux、macOS、WSL2、原生 Windows 以及 Android/Termux。官方推荐通过 Hermes Desktop 安装器获得桌面应用 + CLI，也可以仅安装命令行版本。

1.1 Hermes Desktop（推荐）

从官网下载桌面版安装器，运行即可获得命令行和桌面应用双界面。Desktop 版本包含了完整的图形界面支持。

1.2 命令行安装（无 Desktop）

Linux / macOS / WSL2 / Android (Termux)：

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

Windows 原生 PowerShell：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

💡 Windows 用户：Hermes 支持原生 Windows 安装，不需要 WSL。安装器会自动配置 PortableGit 作为终端工具的 Shell。当然，WSL2 仍然是完全支持的备选方案。

1.3 安装器做了什么

安装器全自动处理一切依赖关系：

重要：你不需要手动安装 Python、Node.js、ripgrep 或 ffmpeg。安装器会自动检测缺失项并安装。你只需要确保系统已安装 curl（Linux/macOS）或 PowerShell（Windows）。

1.4 安装后的文件布局

安装器根据运行方式决定文件位置：

安装完成后，重新加载 shell 即可使用：

# 或 source ~/.zshrc

1.5 更新与卸载

# 更新到最新版本
hermes update

# 卸载
hermes uninstall  # 或运行卸载脚本

二、快速开始：从零到可对话的 Agent

拿到一个能用的 Hermes 需要三步：安装 → 配置 Provider → 开始聊天。

2.1 选择 Provider（最重要的一步）

使用交互式向导选择模型提供商：

hermes setup --portal  # 一键搞定：OAuth 登录 + 模型配置 + 工具网关

如果不使用 Portal，可以单独配置 Provider：

2.2 配置本地模型

如果你希望使用本地部署的模型（Ollama / vLLM / llama.cpp 等）：

hermes setup
# 选择: Custom endpoint (enter URL manually)
# API base URL: http://localhost:11434/v1
# API key: ollama
# Model name: qwen3.5:27b
# Context length: 64000

或者直接在 ~/.hermes/config.yaml 中配置：

provider: custom
custom:
  endpoint: http://localhost:11434/v1
  api_key: ollama
  model: qwen3.5:27b
  context_length: 64000

2.3 验证安装

# 开始对话
hermes

# 或者一次性问题
hermes -e "告诉我你的版本和可用的工具"

⚠️ 核心原则：如果 Hermes 连基本对话都无法完成，不要急着添加更多功能。先保证一次干净的对话能正常工作，然后再叠加 gateway、cron、skills、voice 或 routing。

三、配置详解

Hermes Agent 的所有配置存放在 ~/.hermes/ 目录下。

3.1 目录结构

~/.hermes/
├── config.yaml     # 设置（模型、终端、TTS、压缩等）
├── .env            # API 密钥和 secrets
├── auth.json       # OAuth 提供商凭据
├── SOUL.md         # Agent 身份定义（系统提示 #1）
├── memories/       # 持久记忆（MEMORY.md, USER.md）
├── skills/         # Agent 创建的技能
├── cron/           # 定时任务
├── sessions/       # 网关会话
└── logs/           # 日志（secrets 自动脱敏）

3.2 配置管理命令

# 查看当前配置
hermes config show

# 编辑配置文件
hermes config edit

# 设置具体值
hermes config set model anthropic/claude-opus-4
hermes config set terminal.backend docker
hermes config set terminal.cwd /home/user/projects

# 检查配置完整性
hermes config check

# 迁移（交互式添加缺失选项）
hermes config migrate

💡 hermes config set 命令自动将值路由到正确的位置——API 密钥存入 .env，其他配置存入 config.yaml。

3.3 配置优先级

设置按以下顺序解析（高优先级优先）：

3.4 环境变量替换

你可以在 config.yaml 中引用环境变量：

terminal:
  backend: docker
  cwd: "${CUSTOM_VISION_URL}"

语法：${VARIABLE_NAME}。如果变量未设置，占位符保留原样。

3.5 多 Provider 与 Provider 超时

providers:
  openai:
    request_timeout_seconds: 300
    models:
      gpt-5-codex:
        timeout_seconds: 600

四、工具与工具集

Hermes Agent 内置了 60+ 工具，按逻辑分组为工具集（Toolsets），可针对不同平台启用或禁用。

4.1 内置工具类别

4.2 工具集配置

# 列出所有可用工具
hermes tools list

# 配置每个平台的工具集（交互式）
hermes gateway setup

# 在配置文件中指定
hermes config set toolsets "web,terminal,vision,memory,cron,file"

4.3 Nous 工具网关

对于 Portal 订阅用户，可以通过 Nous Tool Gateway 使用以下工具，无需单独申请 API 密钥：

启用方法：hermes setup --portal 即可一次性完成配置。

4.4 终端后端

Hermes 的 terminal 工具可以在不同环境中执行命令：

# ~/.hermes/config.yaml
terminal:
  backend: local        # local | docker | ssh | singularity | modal | daytona
  cwd: /home/user/projects
  timeout_seconds: 300

💡 Docker 模式下，Hermes 启动一个长期存活容器（docker run -d ... sleep 2h），所有终端操作、文件操作都路由到该容器中，工作目录、安装的包、环境修改跨工具调用保持。

五、消息网关（Messaging Gateway）

消息网关是一个后台进程，连接到你配置的所有消息平台，处理会话、运行 Cron 任务、投递语音消息。

5.1 支持的平台

5.2 配置消息平台

# 交互式配置所有消息平台
hermes gateway setup

# 启动网关（前台运行）
hermes gateway start

# 安装为系统服务（Linux/macOS）
hermes gateway install

# 查看状态
hermes gateway status

# 停止
hermes gateway stop

5.3 聊天内命令

在消息平台中，你可以使用以下命令：

5.4 会话管理

会话在消息之间持久存在，Agent 会记住你的对话上下文。会话重置策略可配置：

• 每日固定时间重置
• 达到消息数量上限后重置
• 手动调用 /new 重置

六、技能系统（Skills）

Skills 是 Hermes Agent 的程序化记忆——按需加载的知识文档。Agent 在需要时才加载完整内容，采用渐进式披露模式以最小化 Token 消耗。

6.1 什么是 Skills

一个 Skill 就是一份有结构的 Markdown 文档（SKILL.md），包含 YAML 前置元数据和正文指令。它们存放在 ~/.hermes/skills/ 目录下，Agent 通过 skill_manage 工具自行创建、修改或删除。

Skills vs 记忆（Memory）：

6.2 渐进式披露（Progressive Disclosure）

Skills 采用三级加载模式：

Agent 只在实际需要时才加载完整的 Skill 内容。

6.3 使用 Skills

# 在 CLI 或消息平台中
/gif-search funny cats
/github-pr-workflow create a PR
/plan design a rollout

# 也可以自然对话
"你有哪些技能？"
"显示 axolotl 技能的内容"

6.4 创建与管理 Skills

Agent 会在以下情况自动创建 Skill：

• 复杂任务成功完成（5 次以上工具调用）
• 克服了棘手的错误
• 发现非平凡的、可复用的工作流
• 用户明确要求 "记住这个流程"

# 列出可用技能
hermes skills list

# 查看一个技能
hermes skills view skill-name

每个 Skill 的 SKILL.md 文件包含：

---
name: skill-name
description: 该技能做什么
platforms: [linux, macos, windows]  # 可选
requires_toolsets: [terminal, file]  # 可选
required_commands: [python3]         # 可选
---
# 技能正文
1. 第一步...
2. 第二步...

6.5 外部技能目录

你可以让 Hermes 扫描额外的技能目录：

# ~/.hermes/config.yaml
skill_directories:
  - /path/to/my-skills
  - /path/to/team-skills

6.6 Skills Hub（社区技能）

Hermes 兼容 OpenClaw 生态的 Skills Hub，社区贡献的技能可通过以下方式安装：

hermes skills install hub skill-name

七、Cron 自动化（定时任务）

Hermes Agent 内置 Cron 调度器，可以定时执行任务并投递结果到任意平台。

7.1 创建定时任务

# 每 30 分钟执行一次
hermes cron create \
  --schedule "30m" \
  --prompt "检查系统磁盘使用情况" \
  --deliver origin

# 每天上午 9 点发送日报
hermes cron create \
  --schedule "0 9 * * *" \
  --prompt "执行日报生成技能，生成今天的日报并发送" \
  --deliver telegram

# 一次性任务
hermes cron create \
  --schedule "2026-06-10T09:00:00" \
  --prompt "发送端午节提醒消息"

7.2 Cron 参数详解

7.3 管理任务

# 列出所有任务
hermes cron list

# 暂停任务
hermes cron pause --job-id <id>

# 恢复任务
hermes cron resume --job-id <id>

# 立即执行一次
hermes cron run --job-id <id>

# 删除任务
hermes cron remove --job-id <id>

# 更新任务
hermes cron update --job-id <id> --schedule "0 8 * * *" --prompt "新的提示词"

7.4 脚本模式（无 LLM 的看门狗）

对于不需要 Agent 推理的简单监控任务，可以使用 --no-agent 模式：

hermes cron create \
  --schedule "5m" \
  --script /path/to/check-disk.sh \
  --no-agent

规则：

• 脚本的 stdout 直接作为消息投递
• 空输出 = 静默（什么也不发送）—— 适合只做阈值告警的看门狗模式
• 非零退出码 / 超时会发送错误告警

7.5 Cron 的权限与安全

# ~/.hermes/config.yaml
approvals:
  cron: deny  # deny | approve — 定时任务遇到危险命令时的默认行为

• deny：阻止危险命令（Agent 必须找其他路径）
• approve：在 Cron 上下文中自动批准所有命令

八、记忆系统（Memory）

Hermes Agent 拥有有界、精炼的持久记忆，跨会话持续存在。Agent 能记住你的偏好、项目、环境和学到的东西。

8.1 两个记忆文件

两者存储在 ~/.hermes/memories/，在会话开始时作为冻结快照注入系统提示。

8.2 记忆如何出现在系统提示中

══════════════════════════════════════════════
MEMORY (your personal notes) [67% — 1,474/2,200 chars]
══════════════════════════════════════════════
User's project is a Rust web service at ~/code/myapi using Axum + SQLx
This machine runs Ubuntu 22.04, has Docker and Podman installed
User prefers concise responses, dislikes verbose explanations

8.3 Agent 如何管理记忆

Agent 通过 memory 工具自主管理记忆：

# 添加新记忆
memory(action="add", target="memory", content="项目使用 Python 3.13 + FastAPI")

# 替换已有记忆（通过子串匹配）
memory(action="replace", target="memory", 
       old_text="Python 3.12", 
       content="项目使用 Python 3.13 + FastAPI")

# 删除不再相关的记忆
memory(action="remove", target="memory", old_text="old fact")

子串匹配：replace 和 remove 使用短唯一子串匹配，不需要完整内容。

8.4 什么应该保存到记忆

九、MCP 集成

MCP（Model Context Protocol）让 Hermes Agent 连接外部工具服务器——GitHub、数据库、文件系统、浏览器栈、内部 API 等。

9.1 安装 MCP 支持

# 如果使用标准安装脚本，MCP 已包含
pip install ".[mcp]"

9.2 配置 MCP 服务器

在 ~/.hermes/config.yaml 中添加：

mcp_servers:
  filesystem:
    command: npx
    args:
      - "@modelcontextprotocol/server-filesystem"
      - "/home/user/projects"
  github:
    command: npx
    args:
      - "@modelcontextprotocol/server-github"

配置完成后，Agent 会自动发现 MCP 服务器的工具并在需要时使用。

9.3 MCP 目录（Canned Catalog）

Hermes 内置一个经 Nous 团队审阅的 MCP 服务器目录：

# 交互式选择（默认）
hermes mcp catalog

# 纯文本列表（可脚本化）
hermes mcp catalog --plain

# 安装指定条目
hermes mcp install linear

目录中的每个条目包含：

• 名称：如 github、linear、n8n
• 状态：available / enabled / installed (disabled)
• 类型：
  • 有凭据：安装时提示输入，写入 .env
  • 远程 MCP（OAuth）：首次连接时打开浏览器认证
  • 三方 OAuth：指向 hermes auth <provider>

9.4 工具选择（安装时的安全检查）

安装 MCP 服务器时，Hermes 会探测其暴露的所有工具并提供勾选清单：

Select tools for 'linear' (SPACE toggle, ENTER confirm)
[x] find_issues       Find issues matching a query
[x] get_issue         Get a single issue
[x] create_issue      Create a new issue
[ ] delete_workspace  Delete a Linear workspace

只有勾选的工具才会被注册，未选择的（如危险的 delete_workspace）不会被暴露给 Agent。

9.5 运行时管理

# 重新加载所有 MCP 服务器（无需重启）
/reload-mcp  # 聊天内命令
hermes mcp reload

# 查看 MCP 状态
hermes mcp status

十、安全策略

Hermes Agent 设计了七层纵深防御安全模型：

10.1 危险命令审批模式

# ~/.hermes/config.yaml
approvals:
  mode: smart     # manual | smart | off
  timeout: 60     # 等待用户响应的秒数
  cron: deny      # cron 遇到危险命令时的策略
  mcp_reload_confirm: true   # 重新加载 MCP 前确认
  destructive_slash_confirm: true  # /clear /new 等前确认

10.2 YOLO 模式

--yolo 标志会绕过当前会话的危险命令审批：

# 启动时开启
hermes chat --yolo

# 会话中切换
/yolo

# 环境变量
HERMES_YOLO_MODE=1

激活后会有红色横幅提示：⚠ YOLO mode — all approval prompts bypassed

⚠️ approvals.mode: off 禁用所有安全提示。仅在 CI/CD、容器等受信任环境中使用。

十一、CLI 命令速查

11.1 全局入口

hermes [--profile name] [--resume session] [-r session] [--yolo]

11.2 常用命令

十二、最佳实践与技巧

12.1 获得更好的结果

明确具体： 模糊的提示产生模糊的结果。不要只说「修复代码」，要说「修复 process_request() 函数第 47 行的 TypeError——它收到的是 None」。

前置提供上下文： 在请求中前置相关细节：文件路径、错误信息、预期行为。一条精心编写的消息胜过三轮反复澄清。直接粘贴错误回溯——Agent 可以解析。

使用 AGENTS.md 文件： 在项目根目录放一个 AGENTS.md，记录架构决策、编码约定和项目特定指令。Agent 每次会话自动读取——一次配置，永久生效。

# AGENTS.md 示例
这是一个 FastAPI 后端项目，使用 SQLAlchemy ORM
始终为数据库操作使用 async/await
测试使用 pytest + pytest-asyncio

让 Agent 使用它的工具： 不要手把手指导每一步。说「找到并修复那个失败的测试」而不是「打开 tests/test_foo.py，看第 42 行，然后…」。Agent 有文件搜索、终端访问和代码执行能力——让它自由探索。

使用 Skills 处理复杂工作流： 在写长提示之前，先检查是否有现成的 Skill。输入 /help 浏览可用 Skills，或直接调用 /github-pr-workflow。

12.2 CLI 高效使用

12.3 会话管理

# 恢复之前会话
hermes -r "research project"
hermes --continue

# 输出模式切换（聊天中）
Ctrl+T  # 循环: off → new → all → verbose

AGENTS.md 文件是项目的「大脑」——放在项目根目录，Agent 每次使用该工作目录时自动加载。

12.4 学习路径推荐

12.5 常见故障排除

总结

Hermes Agent 是一个真正能「越用越聪明」的开源 AI Agent 框架。它的核心竞争壁垒在于三件事：

1. 闭环学习系统——记忆 + Skills + 跨会话召回，让 Agent 从每一次交互中积累经验
2. 无处不在的部署能力——从本地到云端，从 CLI 到 20+ 消息平台
3. 开放的生态系统——MCP 集成、Skills Hub、OpenClaw 兼容

对于开发者来说，从一条 curl 命令开始，60 秒内就能拥有一个属于自己的 AI Agent。建议按以下路线图深入：

1. Day 1：安装 + 配置 Provider + 开始聊天
2. Day 2：配置消息平台 + 设置 Cron 自动化
3. Week 1：学习创建 Skills + 连接 MCP 服务器
4. Month 1：全面定制 SOUL.md + 训练自己的模型

项目地址

参考资料

• Hermes Agent 官方文档：完整的安装、配置、使用指南。 → https://hermes-agent.nousresearch.com/docs
• Hermes Agent GitHub 仓库：源代码发布页面。 → https://github.com/NousResearch/hermes-agent
• Hermes Agent 中文社区：中文文档与安装教程。 → https://hermesagent.org.cn
• Nous Portal 服务：一站式模型 + 工具网关订阅。 → https://nousresearch.com/portal
• MCP 协议文档：Model Context Protocol 官方规范。 → https://modelcontextprotocol.io