🚀 1. 安装与初始化

Hermes Agent 通过 Shell 脚本一键安装，支持 Linux、macOS、WSL2 和 Android（Termux）：

bash

# 一键安装（自动配置 Python 3.11, Node.js v22, ripgrep, ffmpeg）
curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

# 重载 Shell 配置（安装后必须执行）
source ~/.bashrc   # zsh 用户改为 ~/.zshrc

# 验证安装
hermes --version
hermes doctor

💡 安装原理：脚本会将 Hermes 二进制文件安装到 ~/.local/bin/，并在 Shell 配置文件中添加 PATH。配置目录为 ~/.hermes/，包含 .env（密钥）和 config.yaml（配置）两个核心文件。

首次配置向导

安装后运行 hermes setup 进入交互式配置向导，或直接运行 hermes model 选择 AI 提供商。配置完成后即可启动：

bash

hermes        # 经典 CLI 模式
hermes --tui  # 现代 TUI 模式（推荐，有更好的多行编辑体验）

🏗️ 2. 整体架构

Hermes Agent 的整体架构分为三层：接入层（Gateway）、核心层（Agent Core）、执行层（Tool Runtime）。

接入层 Gateway

CLI / TUI Telegram Discord Slack Email

↓ 消息标准化

核心层 Agent Core

上下文管理 Agent Loop Skills Cron Tasks

↓ 工具调用 / 模型推理

执行层 Tool Runtime

Terminal File I/O Web Search MCP Servers Docker / SSH 沙箱

Agent Loop 运作机制

Agent Loop 是 Hermes 的核心执行引擎，每一轮对话都经历以下完整循环：

📥

感知输入

接收用户消息，附加到上下文

→

🧠

模型推理

发送完整上下文给 LLM

→

🔀

解析意图

工具调用 or 直接回复？

→

📤

输出响应

返回最终文本给用户

↓ 工具调用

👁️

观察结果

tool_result 追加到上下文

→

⚙️

执行工具

在 Tool Runtime 中执行

↑ 继续推理

感知输入：接收用户消息，附加到对话上下文
模型推理：将完整上下文发送给 LLM，获取响应
解析意图：判断响应是直接回复还是工具调用请求
执行工具：若有工具调用，在 Tool Runtime 中执行
观察结果：将工具执行结果作为 tool_result 追加到上下文
继续推理：带着工具结果再次调用模型，直到无工具调用为止
输出响应：将最终文本响应返回给用户

🔍 设计洞察：这种 ReAct（Reasoning + Acting）模式让 Agent 能够将复杂任务分解为多步工具调用，每步都能观察结果并调整策略。Hermes 的 Loop 没有硬编码的步骤上限，而是依赖模型自身判断何时停止。

上下文管理策略

Hermes 要求模型上下文窗口至少 64K tokens，这是因为 Agent 需要在上下文中保存：系统提示、工具定义、完整对话历史、工具调用结果。

⚠️ 为什么是 64K？工具调用结果（尤其是终端输出、文件内容）可能非常长。64K 的最低要求确保 Agent 在处理中等复杂任务时不会因上下文溢出而截断关键信息。对于复杂的多步任务，建议使用 128K+ 的模型。

🧠 3. 模型提供商深度解析

运行 hermes model 进入交互式选择界面。不同提供商在工具调用能力、上下文长度、价格上差异显著：

提供商	推荐模型	上下文	工具调用	适用场景
Nous Portal	Hermes 系列	128K	原生优化	新手首选，摩擦最小
Anthropic	Claude Opus/Sonnet	200K	极强	复杂推理、长文档处理
OpenAI	GPT-4o	128K	成熟稳定	代码生成、工具调用
DeepSeek	DeepSeek-V3	64K	良好	性价比高，中文场景
OpenRouter	任意模型	取决于模型	取决于模型	多模型路由，灵活切换
Ollama	Qwen2.5/Llama3	需手动设置	需要支持 FC 的模型	完全本地，隐私优先

💡 Ollama 注意事项：本地模型必须支持 Function Calling（工具调用），且需手动设置 --ctx-size 65536。推荐使用 Qwen2.5-7B-Instruct 或 Llama-3.1-8B-Instruct，这两个模型的工具调用能力相对可靠。

🔧 4. 工具调用机制

Hermes 的工具调用遵循 OpenAI Function Calling 格式。模型在响应中输出结构化的工具调用请求，Hermes 解析后在 Tool Runtime 中执行，再将结果返回给模型。

内置工具集

terminal：执行 Shell 命令，支持交互式和非交互式模式
read_file / write_file：文件读写，支持大文件分块处理
web_search：网络搜索，返回结构化结果
web_fetch：抓取指定 URL 的页面内容
list_directory：目录结构查看

工具调用的完整链路

json

// 1. 模型输出工具调用请求
{
  "tool_calls": [{
    "function": {
      "name": "terminal",
      "arguments": { "command": "ls -la" }
    }
  }]
}

// 2. Hermes 执行工具，获取结果
// 3. 将结果作为 tool_result 追加到上下文
{
  "role": "tool",
  "content": "total 48\ndrwxr-xr-x ..."
}

MCP 协议与工具扩展

Model Context Protocol（MCP）是 Anthropic 提出的开放标准，允许 Agent 通过统一接口接入外部工具服务。Hermes 原生支持 MCP，可以接入任何兼容 MCP 的服务器。

yaml

# ~/.hermes/config.yaml 中配置 MCP 服务器
mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_xxx"
  filesystem:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]

🔍 MCP 的价值：MCP 将工具定义与 Agent 实现解耦。工具提供方只需实现 MCP Server，任何支持 MCP 的 Agent（不只是 Hermes）都能接入。这是 AI 工具生态标准化的重要一步。

⚡ 5. Skills 系统深度解析

Skills 是 Hermes 的插件系统，本质上是一组预定义的工作流指令和工具配置，安装后会注入到 Agent 的系统提示中，赋予 Agent 特定领域的专项能力。

Skills 的工作原理

每个 Skill 包含：系统提示扩展（告诉模型如何处理特定任务）、工具配置（启用或限制特定工具）、工作流模板（预定义的任务执行步骤）。

bash

# 搜索可用 Skills
hermes skills search kubernetes

# 安装 Skill
hermes skills install openai/skills/k8s

# 查看已安装的 Skills
hermes skills list

# 在对话中激活特定 Skill
hermes --skill k8s

自定义 Skill 开发

Skills 以 YAML 格式定义，存放在 ~/.hermes/skills/ 目录下：

yaml

# ~/.hermes/skills/my-skill/skill.yaml
name: my-skill
description: 我的自定义技能
system_prompt: |
  你是一个专注于 XXX 的专家助手。
  当用户提到 XXX 时，你应该...
tools:
  enabled: [terminal, web_search]
  disabled: []

🔄 6. 定时任务（Cron Tasks）

Hermes 内置 Cron 调度器，支持标准 cron 表达式，让 Agent 在无人值守时自动执行周期性任务。

yaml

# 在 config.yaml 中配置定时任务
cron_tasks:
  - name: daily-report
    schedule: "0 9 * * *"   # 每天早 9 点
    prompt: "生成今日工作计划摘要并发送到 Telegram"
    gateway: telegram
  - name: weekly-cleanup
    schedule: "0 2 * * 0"   # 每周日凌晨 2 点
    prompt: "清理 /tmp 目录下超过 7 天的文件"

💡 Cron + Gateway 组合：将定时任务与 Gateway 结合，可以实现"定时推送到 Telegram 群"的效果，无需任何额外开发，只需配置 prompt 和目标 gateway 即可。

🛡️ 7. 沙箱安全机制

Hermes 支持两种执行环境隔离方式，防止 Agent 的工具调用（尤其是终端命令）影响宿主机：

Docker 容器隔离

bash

# 配置 Docker 沙箱
hermes config set terminal.backend docker
hermes config set terminal.docker_image ubuntu:22.04

# 可选：挂载特定目录到容器
hermes config set terminal.docker_volumes /workspace:/workspace

SSH 远程服务器

bash

# 配置 SSH 远程执行
hermes config set terminal.backend ssh
hermes config set terminal.ssh_host user@your-server.com
hermes config set terminal.ssh_key ~/.ssh/id_rsa

🔍 安全设计哲学：Hermes 默认在本地执行，这对开发调试很方便。生产环境或多用户场景下，强烈建议启用 Docker 或 SSH 隔离。SSH 模式还能让 Agent 直接操作远程服务器，是运维自动化的理想方案。

⚙️ 8. 配置体系详解

Hermes 将配置分为两类，安全隔离：

~/.hermes/.env：存放 API Key、Token 等敏感信息，不应提交到版本控制
~/.hermes/config.yaml：存放模型选择、工具配置、MCP 服务器等普通配置

常用配置项速查

bash

# 模型配置
hermes config set model anthropic/claude-opus-4.6
hermes config set ANTHROPIC_API_KEY sk-ant-xxx

# 工具配置
hermes config set tools.web_search.enabled true
hermes config set tools.terminal.enabled true

# 沙箱配置
hermes config set terminal.backend docker

# 查看所有配置
hermes config list

# 切换 Profile（多场景配置）
hermes --profile work

🔧 9. 诊断排错

诊断工具包

bash

hermes doctor          # 自动诊断配置问题
hermes model           # 重新选择模型
hermes setup           # 完整配置向导
hermes sessions list   # 查看所有历史会话
hermes --continue      # 恢复上次会话
hermes gateway status  # 查看 Gateway 运行状态

常见问题根因分析

现象	根因	解决方案
启动后回复为空	API Key 无效或模型名称错误	重新运行 `hermes model`
工具调用无响应	模型不支持 Function Calling	切换到支持 FC 的模型
上下文截断	模型上下文窗口不足 64K	切换到更大上下文的模型
Gateway 收不到消息	Bot Token 错误或白名单未配置	重新运行 `hermes gateway setup`
Docker 沙箱启动失败	Docker 未安装或权限不足	检查 Docker 服务状态

🔬 Hermes Agent 架构深度解析

🚀 1. 安装与初始化

首次配置向导

🏗️ 2. 整体架构

Agent Loop 运作机制

上下文管理策略

🧠 3. 模型提供商深度解析

🔧 4. 工具调用机制

内置工具集

工具调用的完整链路

MCP 协议与工具扩展

⚡ 5. Skills 系统深度解析

Skills 的工作原理

自定义 Skill 开发

🔄 6. 定时任务（Cron Tasks）

🛡️ 7. 沙箱安全机制

Docker 容器隔离

SSH 远程服务器

⚙️ 8. 配置体系详解

常用配置项速查

🔧 9. 诊断排错

诊断工具包

常见问题根因分析