搭建使用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

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

国内用户推荐镜像源（速度快）：

curl -fsSL https://res1.hermesagent.org.cn/install.sh | 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
source ~/.bashrc

# 如果你用 zsh
source ~/.zshrc

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

第五步：验证安装

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 (管理员)

第二步：执行安装命令

国内镜像源：

irm https://res1.hermesagent.org.cn/install.ps1 | iex

官方源：

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

第三步：等待安装完成

安装器会自动下载 MinGit、Python、Node.js 等依赖，全部安装在 %LOCALAPPDATA%\hermes 目录下，不污染系统环境。

第四步：验证安装

关闭当前 PowerShell，重新打开一个，输入：

hermes --version

❌ Windows 专属坑：

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

---

3.3 Docker 安装

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

第一步：确保 Docker 已启动

docker info

第二步：拉取镜像

docker pull nousresearch/hermes-agent

第三步：启动容器

macOS / Windows 版：

docker run -d \
  --name hermes \
  -v ~/.hermes:/opt/data \
  -p 8642:8642 \
  nousresearch/hermes-agent gateway run

Linux 版（推荐用 host 网络）：

docker run -d \
  --name hermes \
  --network host \
  -v ~/.hermes:/opt/data \
  nousresearch/hermes-agent gateway run

第四步：进入容器使用

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 方式一：交互式配置向导（推荐新手）

运行配置向导：

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：

curl -fsSL https://ollama.com/install.sh | sh

Windows：去 ollama.com 下载安装包安装

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

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

推荐模型列表：

# 轻量快速，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 运行

curl http://localhost:11434/v1/models

能看到 JSON 输出说明正常。

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

运行：

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

第五步：验证连接

hermes chat -q "你好，说一句话测试"

能正常回复就配置成功了。

❌ 本地模型常见坑：

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

---

4.3 配置文件详解

Hermes 有两个核心配置文件：

• 普通配置：~/.hermes/config.yaml
• 密钥配置：~/.hermes/.env

config.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 文件

存放所有密钥和敏感信息：

OPENROUTER_API_KEY=sk-or-xxx
ANTHROPIC_API_KEY=sk-ant-xxx
GITHUB_TOKEN=ghp_xxx

💡 小技巧：用命令行修改配置更安全

# 设置配置项
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 模式（默认）

hermes

进入交互式对话界面，直接打字聊天即可。

方式二：现代 TUI 模式（推荐）

hermes --tui

带界面的终端版本，有侧边栏、会话列表，体验更好。

方式三：单次查询模式

hermes chat -q "帮我列出当前目录下的文件"

执行完直接输出结果，不进入交互。

方式四：指定模型运行

# 指定模型
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 中可以配置备用模型，主模型挂了自动切换：

model:
  default: "anthropic/claude-sonnet-4"
  provider: "openrouter"
  fallback_model: "google/gemini-flash-2.5"

也可以随时手动切换：

hermes model set anthropic/claude-opus-4.7

---

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

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

示例：添加 GitHub MCP

编辑 ~/.hermes/config.yaml：

mcp_servers:
  github:
    command: npx
    args: ["-y", "@modelcontextprotocol/server-github"]
    env:
      GITHUB_PERSONAL_ACCESS_TOKEN: "ghp_你的token"

然后重启 Hermes 即可。

更简单的方式：用命令管理

# 查看可用的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：

API_SERVER_ENABLED=true
API_SERVER_KEY=设置一个密码

第二步：启动网关

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（推荐）

# 安装
npm install -g hermes-web-ui

# 启动
hermes-web-ui start

访问 http://localhost:8648 即可使用图形界面。

---

6.5 编辑器集成（ACP）

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

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 本身能不能用：

  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 万能诊断命令

遇到任何问题，先跑这个：

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 自动诊断，或者查看官方文档。

我真的是真人

教程很全面，值得学习