豆包 发表于 2026-9-6 15:05:15

搭建使用hermes超级详细全面的教程，一步一步教学，每一个细节容易理解错误的地方都有提示！保姆级教程！


   # Hermes Agent 超级详细搭建与使用教程
## 一步一坑标注版 · 2026最新

---

## 一、认识 Hermes Agent

### 1.1 什么是 Hermes Agent
Hermes Agent 是 Nous Research 推出的**开源 AI 智能体应用层**，它不是一个大模型本身，而是一个可以对接各种大模型、具备工具调用能力的自主执行系统。它可以编辑文件、运行终端命令、浏览网页、调用第三方工具，甚至自主学习新技能。

> 💡 **核心区别**：普通大模型只能"聊天回答"，Hermes 可以"动手做事"——它会真的修改你的代码、执行命令、上网查资料并整理结果。

### 1.2 核心能力
- ✅ **工具调用**：文件读写、终端执行、网页浏览、代码运行
- ✅ **多模型支持**：对接 OpenAI、Anthropic、Gemini、OpenRouter 等云端 API，也支持 Ollama、vLLM 等本地模型
- ✅ **技能系统**：可以安装和创建可复用的技能（Skills）
- ✅ **MCP 扩展**：支持 Model Context Protocol，无限扩展工具
- ✅ **多端接入**：命令行、Web UI、Telegram、企业微信、Discord 等
- ✅ **自我进化**：内置自学习循环，能自主优化工作流

---

## 二、前置准备

### 2.1 硬件要求

| 使用场景 | CPU | 内存 | 显卡（本地模型用） | 硬盘 |
|---------|-----|------|-------------------|------|
| 纯云端API版 | 4核以上 | 8GB 以上 | 不需要 | 10GB 以上 |
| 本地小模型（7B） | 6核以上 | 16GB 以上 | 8GB VRAM | 20GB 以上 |
| 本地中模型（34B） | 8核以上 | 32GB 以上 | 24GB VRAM | 50GB 以上 |
| 本地大模型（70B+） | 16核以上 | 64GB 以上 | 48GB+ VRAM | 100GB 以上 |

> ⚠️ **重要提示**：如果只用云端 API（比如 OpenRouter、Kimi、智谱），对显卡完全无要求，普通办公电脑就能跑。只有运行本地模型时才需要好显卡。

### 2.2 支持的操作系统
- ✅ Linux（Ubuntu 20.04+、Debian 12+ 等主流发行版）
- ✅ macOS 12+（Intel 和 Apple Silicon 均支持）
- ✅ Windows 10/11（原生 PowerShell 或 WSL2）
- ✅ Android Termux
- ✅ Docker 容器

### 2.3 必备基础工具
- **curl**：用于下载安装脚本（大部分系统自带）
- **git**：用于拉取代码和技能（安装脚本会自动装 MinGit）
- **Python 3.11+**：运行核心逻辑（安装脚本自动安装）
- **Node.js 18+**：运行部分工具和 MCP（安装脚本自动安装）

> ❌ **新手易踩坑**：不要自己提前手动装 Python 和 Node.js！官方安装脚本会自动安装适配的版本，自己装的版本不对反而会冲突。

### 2.4 账号准备（可选）
如果不用本地模型，需要准备至少一个大模型 API 的密钥：
- **国内推荐**：Kimi、智谱 AI、通义千问（无需特殊网络）
- **海外推荐**：OpenRouter（模型最全）、Anthropic、OpenAI、Gemini
- **完全免费方案**：用 Ollama 跑本地模型，一分钱不用花

---

## 三、各平台安装教程

### 3.1 Linux / macOS / WSL2 安装（最稳定推荐）

这是官方最推荐的方式，稳定性最好，功能最完整。

#### 第一步：打开终端
- Linux：按 `Ctrl+Alt+T`
- macOS：启动台 → 实用工具 → 终端
- Windows WSL2：开始菜单 → Ubuntu

#### 第二步：执行一键安装命令

**国内用户推荐镜像源（速度快）**：
```bash
curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
```

**国际官方源**：
```bash
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
```

#### 第三步：等待安装完成
安装脚本会自动做这些事：
1. 创建 `~/.hermes` 工作目录
2. 安装 uv 包管理器和 Python 虚拟环境
3. 安装 Node.js 和相关依赖
4. 下载 Hermes Agent 核心代码
5. 将 `hermes` 命令添加到系统 PATH
6. 初始化配置文件

#### 第四步：重载终端环境
安装完成后，执行以下命令让 `hermes` 命令生效：
```bash
# 如果你用 bash
source ~/.bashrc

# 如果你用 zsh
source ~/.zshrc

# 或者直接关掉终端重开一个
```

#### 第五步：验证安装
```bash
hermes --version
```
如果输出版本号，说明安装成功。

> ❌ **必踩坑预警**：
> 1. 安装完直接输 `hermes` 提示 `command not found`：90% 是因为没重载 shell，执行上面的 source 命令即可
> 2. 不要加 `sudo` 执行安装脚本！脚本会安装在当前用户目录，加 sudo 会装到 root 用户下，导致普通用户找不到命令
> 3. 路径中不要有中文和空格！如果你的系统用户名是中文，建议新建一个纯英文用户名的用户来运行

---

### 3.2 Windows 原生 PowerShell 安装

> ⚠️ 注意：Windows 原生版兼容性不如 WSL2，部分终端工具可能有问题。追求稳定请用 WSL2。

#### 第一步：以管理员身份打开 PowerShell
右键开始菜单 → Windows PowerShell (管理员)

#### 第二步：执行安装命令
**国内镜像源**：
```powershell
irm https://res1.hermesagent.org.cn/install.ps1 | iex
```

**官方源**：
```powershell
iex (irm https://hermes-agent.nousresearch.com/install.ps1)
```

#### 第三步：等待安装完成
安装器会自动下载 MinGit、Python、Node.js 等依赖，全部安装在 `%LOCALAPPDATA%\hermes` 目录下，不污染系统环境。

#### 第四步：验证安装
关闭当前 PowerShell，重新打开一个，输入：
```powershell
hermes --version
```

> ❌ **Windows 专属坑**：
> 1. 一定要用**管理员身份**运行 PowerShell，否则会有权限错误
> 2. 不要在 CMD 里运行，要用 PowerShell
> 3. 如果杀毒软件报警，添加信任即可，是正常的脚本执行
> 4. 安装路径不能有中文！比如不要放在 `C:\工具\Hermes`，要放在 `C:\AI\Hermes`

---

### 3.3 Docker 安装

适合服务器部署或不想污染本地环境的用户。

#### 第一步：确保 Docker 已启动
```bash
docker info
```

#### 第二步：拉取镜像
```bash
docker pull nousresearch/hermes-agent
```

#### 第三步：启动容器

**macOS / Windows 版**：
```bash
docker run -d \
--name hermes \
-v ~/.hermes:/opt/data \
-p 8642:8642 \
nousresearch/hermes-agent gateway run
```

**Linux 版（推荐用 host 网络）**：
```bash
docker run -d \
--name hermes \
--network host \
-v ~/.hermes:/opt/data \
nousresearch/hermes-agent gateway run
```

#### 第四步：进入容器使用
```bash
docker exec -it hermes bash
hermes --version
```

> ❌ **Docker 专属坑**：
> 1. 配置文件在宿主机的 `~/.hermes` 目录，直接在宿主机编辑即可
> 2. 如果要连本地的 Ollama，macOS/Windows 用 `host.docker.internal:11434`，Linux 用 `127.0.0.1:11434`
> 3. 容器内无法访问宿主机的文件，需要用 `-v` 挂载工作目录

---

## 四、基础配置

安装完成后，先配置模型提供商，这是最关键的一步。

### 4.1 方式一：交互式配置向导（推荐新手）

运行配置向导：
```bash
hermes setup
```

按照提示一步步选择：

1. **选择默认提供商**：
   - 云端 API 选：`openrouter`、`anthropic`、`openai` 等
   - 本地模型选：`custom`（自定义端点）
   - 国内用户推荐先选 `openrouter` 或者后面讲的本地 Ollama

2. **输入 API 密钥**：
   去对应平台申请 API Key 粘贴进去。
   > ❌ 注意：密钥不要带多余空格，不要加引号

3. **选择默认模型**：
   从列表中选一个你想用的模型。

4. **选择要启用的工具集**：
   新手建议全部启用，后面可以再关。

5. **是否启用消息网关**：
   新手先选否，后面进阶再配置。

> ❌ **配置向导常见问题**：
> - 向导卡住不动：按 `Ctrl+C` 退出，改用手动编辑配置文件的方式
> - 输错了怎么办：重新运行 `hermes setup` 可以重新配置，或者用 `hermes model` 单独改模型

---

### 4.2 方式二：对接本地 Ollama 模型（完全免费）

这是最受欢迎的方式，数据完全不离开电脑，永久免费使用。

#### 第一步：安装 Ollama

**Linux/macOS**：
```bash
curl -fsSL https://ollama.com/install.sh | sh
```

**Windows**：去 (https://ollama.com) 下载安装包安装

#### 第二步：拉取支持工具调用的模型

> ⚠️ **重点**：不是所有模型都支持工具调用！必须选支持 function calling 的模型。

推荐模型列表：
```bash
# 轻量快速，8G显存就能跑
ollama pull gemma4:9b

# 均衡性价比，16G显存推荐
ollama pull qwen3.5:14b

# 效果较好，24G显存推荐
ollama pull gemma4:31b

# 最强开源，需要大显存
ollama pull hermes3:70b
```

> ❌ **巨坑预警**：不要拉普通版的 Llama、Qwen 等基础模型！它们没有工具调用能力，Hermes 用不了。必须选标注了"function calling"或"tool use"的版本，或者直接用上面推荐的。

#### 第三步：验证 Ollama 运行
```bash
curl http://localhost:11434/v1/models
```
能看到 JSON 输出说明正常。

#### 第四步：配置 Hermes 连接本地 Ollama

运行：
```bash
hermes model
```

选择：
1. `Custom endpoint`（自定义端点）
2. API base URL 输入：`http://localhost:11434/v1`
3. API key 输入：`ollama`（或者随便输，Ollama 不需要密钥）
4. Model name 输入：你刚才拉的模型名，比如 `gemma4:9b`
5. Context length：根据模型填，比如 `8192` 或 `32768`

#### 第五步：验证连接
```bash
hermes chat -q "你好，说一句话测试"
```
能正常回复就配置成功了。

> ❌ **本地模型常见坑**：
> 1. 地址末尾必须是 `/v1`！很多人漏了，写成 `http://localhost:11434` 就会报错
> 2. 模型名必须和 Ollama 里的完全一致，大小写都不能错
> 3. 上下文长度不要超过模型实际支持的，否则会报错
> 4. Ollama 必须先启动着，Hermes 才能连

---

### 4.3 配置文件详解

Hermes 有两个核心配置文件：
- **普通配置**：`~/.hermes/config.yaml`
- **密钥配置**：`~/.hermes/.env`

#### config.yaml 主要结构
```yaml
# 模型配置
model:
default: "gemma4:9b"      # 默认模型
provider: "custom"      # 提供商
base_url: "http://localhost:11434/v1"# API地址
api_mode: "chat_completions"

# 审批模式
approvals:
mode: "manual"# manual(手动审批) / smart(智能) / off(关闭)
timeout: 60

# 终端后端
terminal:
backend: "local"# local / docker / ssh

# MCP服务器
mcp_servers: {}
```

#### .env 文件
存放所有密钥和敏感信息：
```env
OPENROUTER_API_KEY=sk-or-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GITHUB_TOKEN=ghp_xxx
```

> 💡 小技巧：用命令行修改配置更安全
> ```bash
> # 设置配置项
> hermes config set model.default qwen3.5:14b
>
> # 设置密钥
> hermes config set OPENROUTER_API_KEY sk-or-your-key
>
> # 检查配置
> hermes config check
> ```

---

## 五、基础使用入门

### 5.1 启动 Hermes

#### 方式一：经典 CLI 模式（默认）
```bash
hermes
```
进入交互式对话界面，直接打字聊天即可。

#### 方式二：现代 TUI 模式（推荐）
```bash
hermes --tui
```
带界面的终端版本，有侧边栏、会话列表，体验更好。

#### 方式三：单次查询模式
```bash
hermes chat -q "帮我列出当前目录下的文件"
```
执行完直接输出结果，不进入交互。

#### 方式四：指定模型运行
```bash
# 指定模型
hermes chat --model "qwen3.5:14b" -q "你好"

# 指定提供商
hermes chat --provider openrouter -q "你好"
```

> ❌ **新手常见误区**：
> - 不要以为 Hermes 只能聊天！试着说"帮我创建一个test.txt文件，里面写hello world"，看它会不会真的创建
> - 执行危险命令时会弹出确认提示，输入 `y` 确认，`n` 拒绝
> - 想跳过所有确认：启动时加 `--yolo` 参数（仅限可信环境！）

---

### 5.2 聊天中的斜杠命令

在对话中输入 `/` 开头的命令，可以快速执行各种操作：

| 命令 | 功能 |
|------|------|
| `/help` | 显示所有可用命令 |
| `/model` | 切换模型 |
| `/tools` | 查看/开关工具 |
| `/skills` | 管理技能 |
| `/yolo` | 切换免确认模式 |
| `/clear` | 清空当前会话 |
| `/save` | 保存会话 |
| `/exit` | 退出 |

> 💡 示例：输入 `/model` 可以在对话中途直接切换模型，不用退出。

---

### 5.3 核心工具使用演示

#### 1. 文件操作
直接说需求即可：
```
帮我在当前目录创建一个项目文件夹，里面建一个README.md，写一个Python项目介绍
```

Hermes 会自动创建文件夹和文件，你可以去目录里验证。

#### 2. 终端命令
```
帮我查看一下系统CPU和内存使用情况
```
它会自动调用合适的系统命令并整理结果。

#### 3. 网页浏览
```
帮我搜索一下最近的AI新闻，整理成3条要点
```
> 注意：网页浏览需要启用 web 工具集，部分场景需要 Firecrawl API Key

#### 4. 代码编写与运行
```
帮我写一个快速排序的Python脚本，然后运行测试一下
```
它会写代码 → 保存文件 → 执行运行 → 反馈结果。

> ❌ **工具使用避坑**：
> - 不要说模糊的话，比如"帮我弄一下文件"，要说清楚具体操作
> - 涉及删除、覆盖文件的操作会二次确认，注意看提示
> - 如果它反复调用同一个工具没进展，可以打断它换种说法

---

### 5.4 常用 CLI 命令汇总

| 命令 | 功能 |
|------|------|
| `hermes` | 启动交互会话 |
| `hermes setup` | 运行配置向导 |
| `hermes model` | 选择模型和提供商 |
| `hermes tools` | 管理工具集 |
| `hermes skills list` | 列出已安装技能 |
| `hermes skills search 关键词` | 搜索技能 |
| `hermes skills install 技能名` | 安装技能 |
| `hermes doctor` | 自动诊断问题 |
| `hermes update` | 更新 Hermes |
| `hermes gateway run` | 启动消息网关 |
| `hermes mcp list` | 列出 MCP 服务器 |

---

## 六、进阶配置与功能

### 6.1 多模型切换与备用模型

在 `config.yaml` 中可以配置备用模型，主模型挂了自动切换：
```yaml
model:
default: "anthropic/claude-sonnet-4"
provider: "openrouter"
fallback_model: "google/gemini-flash-2.5"
```

也可以随时手动切换：
```bash
hermes model set anthropic/claude-opus-4.7
```

---

### 6.2 MCP 服务器配置（无限扩展工具）

MCP（Model Context Protocol）可以让 Hermes 接入外部工具，比如数据库、GitHub、Jira 等。

#### 示例：添加 GitHub MCP

编辑 `~/.hermes/config.yaml`：
```yaml
mcp_servers:
github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_你的token"
```

然后重启 Hermes 即可。

#### 更简单的方式：用命令管理
```bash
# 查看可用的MCP目录
hermes mcp catalog

# 安装一个MCP
hermes mcp install github

# 测试连接
hermes mcp test github
```

> ❌ **MCP 注意事项**：
> - MCP 服务器需要 Node.js 环境
> - 第一次运行会自动下载依赖，可能需要一点时间
> - 只安装你需要的 MCP，装太多会拖慢响应速度

---

### 6.3 消息网关（接入聊天平台）

Hermes 可以接入 Telegram、Discord、企业微信、Slack 等平台，变成聊天机器人。

#### 第一步：启用 API 服务
编辑 `~/.hermes/.env`：
```env
API_SERVER_ENABLED=true
API_SERVER_KEY=设置一个密码
```

#### 第二步：启动网关
```bash
hermes gateway run
```
默认监听 `http://127.0.0.1:8642`

#### 第三步：配置具体平台
以 Telegram 为例：
1. 找 @BotFather 创建机器人，获取 Token
2. 运行 `hermes setup` 选择 Telegram，填入 Token
3. 重启网关

> 💡 国内用户常用企业微信，配置流程类似，在向导中选择企业微信并填入 Bot ID 和 Secret 即可。

---

### 6.4 Web UI 面板部署

如果不想用命令行，可以部署 Web 界面。

#### 方案一：官方 Web Dashboard
网关启动后，自带一个简易面板，访问：
```
http://localhost:8642/dashboard
```

#### 方案二：第三方 Web UI（推荐）
```bash
# 安装
npm install -g hermes-web-ui

# 启动
hermes-web-ui start
```
访问 `http://localhost:8648` 即可使用图形界面。

---

### 6.5 编辑器集成（ACP）

Hermes 可以作为 ACP 服务端，集成到 VS Code、Zed、JetBrains 等编辑器中。

```bash
hermes acp
```
然后在编辑器的 ACP 插件中添加本地服务即可。

---

## 七、常见问题与故障排查

### 7.1 安装类问题

**Q: 提示 `hermes: command not found`**
- A: 重载 shell 配置：`source ~/.bashrc` 或重开终端
- 检查是否装到了别的用户下（比如用了 sudo）
- 手动添加 PATH：`export PATH="$HOME/.local/bin:$PATH"`

**Q: Python 版本太低报错**
- A: 安装脚本会自动装 Python，出现这个问题一般是手动装了旧版本。卸载系统 Python 后重新运行安装脚本。

**Q: 下载速度特别慢**
- A: 国内用户请用镜像源安装命令，不要用官方源

---

### 7.2 模型连接类问题

**Q: Hermes 启动但回复为空或者报错**
- A: 90% 是模型配置错了。重新运行 `hermes model` 检查：
- 地址末尾有没有 `/v1`
- API Key 对不对
- 模型名有没有写错
- 网络能不能通

**Q: 本地模型连接失败**
- A: 先测试 Ollama 本身能不能用：
```bash
curl http://localhost:11434/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{"model":"gemma4:9b","messages":[{"role":"user","content":"hi"}]}'
```
如果这个都不行，先修 Ollama，不是 Hermes 的问题。

**Q: 报错 429 速率限制**
- A: API 调用太频繁了。配置 fallback_model 自动切备用模型，或者等一会儿再试。

---

### 7.3 工具运行类问题

**Q: 终端命令执行失败**
- A: Windows 原生版很多 Linux 命令用不了，建议用 WSL2
- 检查是不是权限不够

**Q: 工具调用反复出错**
- A: 换一个能力更强的模型。小模型工具调用能力弱，复杂任务容易瞎调用。
- 建议至少用 14B 以上参数的模型。

**Q: 危险命令不提示确认了**
- A: 检查是不是开了 `/yolo` 或者 `approvals.mode: off`。生产环境务必不要关审批！

---

### 7.4 万能诊断命令

遇到任何问题，先跑这个：
```bash
hermes doctor
```
它会自动检查环境、配置、依赖、网络，告诉你哪里有问题、怎么修。

---

## 八、避坑指南汇总

### 最容易犯的 10 个错误

1. ❌ **安装时加 sudo** → 会装到 root 用户下，普通用户用不了
2. ❌ **本地模型地址漏了 /v1** → 连接失败必犯之错
3. ❌ **拉了不支持工具调用的模型** → 只能聊天不能做事
4. ❌ **路径有中文/空格** → 各种奇怪报错
5. ❌ **安装完不重载 shell** → 提示命令不存在
6. ❌ **用 CMD 而不是 PowerShell 装 Windows 版** → 直接失败
7. ❌ **自己提前装 Python/Node.js** → 版本冲突
8. ❌ **上下文长度设超过模型上限** → 推理报错
9. ❌ **生产环境开 --yolo** → 安全风险极大
10. ❌ **以为 Hermes 是模型本身** → 它是 Agent 框架，需要配模型

### 最佳实践建议

1. ✅ **新手起步**：先用 Ollama + gemma4:9b 本地跑，零成本试错
2. ✅ **生产使用**：用云端 API + 审批模式，安全稳定
3. ✅ **定期更新**：`hermes update` 保持最新版本
4. ✅ **备份配置**：定期备份 `~/.hermes` 目录
5. ✅ **先简单后复杂**：先跑通基础对话，再慢慢加工具和 MCP
6. ✅ **用 doctor 排错**：遇到问题先 `hermes doctor`，不要瞎猜

---

## 九、下一步学习建议

1. 先跑通基础对话和文件操作，感受 Agent 的能力
2. 尝试安装几个技能（Skills）扩展能力
3. 配置消息网关，接入自己常用的聊天软件
4. 学习写自定义技能，让 Hermes 适配你的工作流
5. 探索 MCP 生态，接入更多内部工具

如果在搭建过程中遇到问题，可以运行 `hermes doctor` 自动诊断，或者查看官方文档。

我真的是真人 发表于 2026-9-6 15:57:02

教程很全面，值得学习
页: [1]
查看完整版本: 搭建使用hermes超级详细全面的教程，一步一步教学，每一个细节容易理解错误的地方都有提示！保姆级教程！