聪叙
发布于 2026-09-29 / 28 阅读
2
0

Hermes安装及配置自定义模型

如果你想在 Windows 11 上体验 Hermes,但又担心环境复杂、命令太多、装完跑不起来,这篇文章就是写给你的。

我会按照“先跑通,再进阶”的思路,带你完成这几件事:

  • 在 Win11 上正确安装 Hermes

  • 理解为什么官方推荐走 WSL2

  • 完成首次模型配置与可用性验证

  • 解决新手最常遇到的报错

  • 掌握一批真正有用的使用技巧

这篇文章基于 Hermes 官方文档整理,适合发布到技术论坛,也适合你收藏后照着一步步操作。

1. Hermes 是什么,适合哪些人?

Hermes Agent 可以理解为一个“可调用工具的 AI 助手框架”。它不只是普通聊天,而是能在合适授权下使用终端、读写文件、搜索网页、调用技能,并把这些能力串起来完成任务。

它比较适合这几类人:

  • 想把 AI 真正接入日常开发工作流的程序员

  • 想做自动化助手、消息机器人、知识工作流的人

  • 想把本地工具、远程环境、LLM 模型能力串起来的人

如果你只是想“随便问答”,网页聊天就够了;如果你想让 AI 真的“干活”,Hermes 会更有意思。

2. 为什么 Win11 不建议原生装,而是推荐 WSL2?

这一点非常关键。

根据官方安装文档,原生 Windows 当前不受支持,Windows 用户推荐先安装 WSL2,然后在 WSL2 的 Linux 终端里安装和运行 Hermes。

原因并不复杂:

  • Hermes 的安装与运行链路更偏 Linux/Unix 环境

  • 一些依赖、脚本、工具链在 WSL2 下更稳定

  • 后续如果你要接入终端、脚本、自动化、开发环境,WSL2 兼容性会明显更好

所以,Win11 安装 Hermes 的正确思路不是“Windows 原生安装”,而是:

Windows 11 -> WSL2 -> Ubuntu -> 安装 Hermes

如果你一开始方向就错了,后面会遇到很多没必要的坑。

3. 安装前准备

正式开始前,先确认几件事:

  • 你的系统是 Windows 11

  • 可以使用管理员权限打开 PowerShell

  • 网络能够访问 GitHub 及相关依赖源

  • 你至少准备好一个可用的模型提供方账号

官方文档提到,Hermes 安装时最核心的前置条件其实只有一个:Git 可用。Python、Node.js、ripgrep、ffmpeg 等依赖,安装器会尽量自动处理。

不过从实战经验看,Win11 用户还要额外注意两点:

  • 如果 WSL2 安装失败,先检查 BIOS 里是否开启虚拟化

  • 如果公司网络较严格,建议提前准备代理,否则安装脚本和后续模型连接都可能失败

4. 第一步:在 Win11 上安装 WSL2

先用管理员身份打开 PowerShell,执行:

wsl --install -d Ubuntu

这条命令会自动完成 WSL2 和 Ubuntu 的安装。执行完成后,通常需要重启系统。

重启后,打开 Ubuntu,第一次启动会提示你创建 Linux 用户名和密码,照提示完成即可。

安装成功后,可以在 PowerShell 里检查一下:

wsl --status

如果你能看到 WSL 正常启用,并且默认版本是 2,基本就可以继续了。

5. 第二步:进入 Ubuntu,准备基础环境

后面的命令,默认都在 WSL2 的 Ubuntu 终端 里执行,不是在 PowerShell 里执行。

先更新软件源并确保 git 可用:

sudo apt update
sudo apt install -y git curl
git --version

只要 git --version 能正常输出版本号,说明前置条件满足。

6. 第三步:在 WSL2 中安装 Hermes

官方推荐的一键安装命令如下:

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

安装完成后,按官方建议重新加载 Shell:

source ~/.bashrc

如果你使用的是 zsh,则改成:

source ~/.zshrc

然后执行:

hermes

如果命令能正常启动,说明安装链路基本没问题。

7. 第四步:配置模型 Provider,这是最容易出错的一步

很多人以为“装完就能用”,实际上真正决定 Hermes 能不能正常工作的,是模型提供方配置。

官方建议用下面的命令进入交互式配置:

hermes model

如果你是第一次使用,建议优先选择摩擦最小的路径:

  • 想快速跑通:Nous Portal 或 OpenRouter

  • 已有 Claude / OpenAI 相关认证:可选对应 Provider

  • 想跑本地模型:可接 Ollama 或兼容 OpenAI API 的自建端点

一个重要要求:上下文窗口至少 64K

官方文档明确提到,Hermes 需要模型至少支持 64,000 tokens 的上下文窗口。上下文太小,很多多步工具调用场景会直接失效,甚至在启动时被拒绝。

所以你在选模型时,不要只看“便宜”或者“快”,还要看它是否满足上下文要求。

配置文件存在哪里?

这点建议新手顺手记住:

  • 密钥、令牌这类敏感信息:~/.hermes/.env

  • 普通配置项:~/.hermes/config.yaml

如果你通过 CLI 设置,Hermes 会自动把内容写到正确的位置。例如:

hermes config set model anthropic/claude-opus-4.6
hermes config set terminal.backend docker

这种方式比你手改配置文件更稳。

如何使用AI汇聚站接入?

  1. 打开AI汇聚站https://ai.mccxy.top

  2. 选择想要接入的模型并选取好合适分组创建好API Key

    DD475746-53D3-4A8A-A55D-B751D8832F96.png
  3. 进入hermes模型配置页面


hermes model
# 通过键盘 方向键选择 Custom endpoint (enter URL manually)
# 输入 API端点 末尾补上 /v1 是 openai 兼容协议
API base URL [e.g. https://api.example.com/v1]: https://ai.mccxy.top/v1
# 输入刚才创建的API Key
API key [sk-KiHjv...]:  xxxxxx
# 选择兼容协议
Select API compatibility mode:
  1. Auto-detect
     Use Hermes URL heuristics; best for standard OpenAI-compatible endpoints.
  2. Chat Completions
     Use /chat/completions for standard OpenAI-compatible servers.
  3. Responses / Codex [current]
     Use /responses for Codex-compatible tool-calling backends.
  4. Anthropic Messages
     Use /v1/messages for Anthropic-compatible endpoints.
Choice [1-4, Enter to keep current/detected]:  3
#   输入 y 确认
  API mode: codex_responses
  Detected model: swe-2
  Use this model? [Y/n]: y
# 上下文长度 可以直接回车跳过
Context length in tokens [leave blank for auto-detect]:
# 渠道别名 自定义 我这里是使用的 swe-2 模型,就命名为hermes-swe-2
Display name [Ai.mccxy.top]:  hermes-swe-2
# 思考强度选择 选择默认medium就够了
Select reasoning effort:
  ↑↓ navigate  ENTER/SPACE select  ESC cancel  ← previous

   (○) minimal
   (○) low
   (●) medium  ← currently in use
 → (○) high
   (○) xhigh
   (○) max
   (○) ultra
   (○) Disable reasoning
   (○) Skip (keep current)

8. 第五步:跑通第一次对话,别一上来就折腾高级功能

安装和 Provider 配置完成后,先做一件最朴素的事:验证 Hermes 能正常聊天。

你可以用经典 CLI:

hermes

也可以用官方更推荐的 TUI:

hermes --tui

建议你先发一个容易验证结果的请求,比如:

查看我当前目录,告诉我最像项目入口文件的是哪个。

或者:

用 5 个要点总结一下这个仓库。

如果出现以下现象,说明你已经跨过最难的一关:

  • 启动画面能显示你当前选定的模型或 Provider

  • Hermes 能正常回复,而不是报错或空响应

  • 遇到需要时,它能调用工具

  • 对话可以连续进行,而不是第一轮就崩

经验建议:如果基础聊天都还没稳定,不要急着开 Gateway、技能、语音、路由和自动化。

9. 第六步:验证会话恢复功能

这一步很容易被忽略,但非常实用。

执行:

hermes --continue

或者短命令:

hermes -c

如果能恢复到你刚才的会话,说明会话保存没问题。后面你在多项目切换、长任务续跑时,会明显感受到这个功能的价值。

10. 接入微信渠道

  1. 进入hermes网关配置
    hermes setup gateway

  2. 选择微信渠道

Select platforms to configure:
  ↑↓ navigate  SPACE toggle  ENTER confirm  ESC cancel

   [ ] 💬 Mattermost  (not configured)
   [ ] 📡 Signal  (not configured)
   [✓] 💬 Weixin / WeChat  (configured)
   [ ] 💬 BlueBubbles (iMessage)  (not configured)
   [ ] 🐧 QQ Bot  (not configured)
   [ ] 💎 Yuanbao  (not configured)
   [ ] 🧩 A2A  (not configured)
   [ ] 🐝 Buzz  (not configured)
   [ ] 🐳 DingTalk  (not configured)
   [ ] 🎮 Discord  (not configured)
   [ ] 📧 Email  (not configured)
   [ ]   Feishu / Lark  (not configured)
   [ ] 💬 Google Chat  (not configured)
   [ ] 🏠 Home Assistant  (not configured)
   [ ] 💬 IRC  (not configured)
   [ ] 💚 LINE  (not configured)
   [ ] 🔐 Matrix  (not configured)
   [ ] 🔔 ntfy  (not configured)
   [ ] 📱 iMessage via Photon  (not configured)
   [ ] 🔔 Raft  (not configured)
   [ ] 🔒 SimpleX Chat  (not configured)
   [ ] 💼 Slack  (not configured)
   [ ] 📱 SMS (Twilio)  (not configured)
   [ ] 💼 Microsoft Teams  (not configured)
 → [ ] ✈️ Telegram  (not configured)
   [ ] 💼 WeCom (Enterprise WeChat)  (not configured)
   [ ] 💼 WeCom Callback (self-built apps)  (not configured)
   [ ] 💬 WhatsApp  (not configured)
  1. 同意二维码登录

  Start QR login now?
  ↑↓ navigate  ENTER/SPACE select  ESC cancel  ← previous

可以复制链接到浏览器打开扫描二维码,或者直接扫描二维码

B26874CF-CF4F-4348-BCDA-F0B1D7F81061.png
  1. 后续就一直 yes就行,按推荐来就可以

  2. 微信列表就会出现一个带AI表示的联系人

11. Win11 用户最常见的几个问题

1. hermes: command not found

常见原因:

  • 安装后没有重新加载 Shell

  • PATH 没刷新

  • 安装过程本身中断了

优先尝试:

source ~/.bashrc
hermes

如果还是不行,重新执行安装脚本通常比死磕更省时间。

2. 能启动 Hermes,但回复异常、空白或报认证错误

这类问题十有八九是 Provider 没配对。

直接重新执行:

hermes model

重新确认:

  • Provider 选的是不是你真正可用的那个

  • API Key 是否填对

  • 模型名称是否有效

  • 自定义端点是否真的兼容 OpenAI API

3. 自建模型端点“看起来通了”,但回答乱码或行为异常

这是很多本地部署用户会踩的坑。

常见根因有三个:

  • Base URL 填错

  • 模型名填错

  • 这个服务根本不是标准 OpenAI 兼容接口

建议先用其他客户端单独验证接口,再接 Hermes,别把排错难度叠加。

4. 继续会话失败,找不到历史记录

优先检查:

hermes sessions list

有时不是 Hermes 没存,而是你切了 profile,或者之前的会话根本没正常保存。

5. 配置越改越乱,不知道现在哪里有问题

直接跑官方诊断:

hermes doctor

这是最应该优先学会的命令之一。

12. 6 个非常实用的 Hermes 使用技巧

技巧 1:优先写清楚任务,而不是只写一句“帮我看下”

Hermes 的能力越强,越吃上下文。你给的信息越具体,它越容易一次做对。

错误示范:

帮我修一下代码

更好的写法:

帮我检查 `api/handlers.py` 里 `process_request()` 的 TypeError,报错信息如下……

技巧 2:多行输入很好用

在 CLI 里可以用 Alt+Enter 或 Ctrl+J 插入换行。写长提示词、粘贴报错堆栈、贴代码块时非常舒服。

技巧 3:学会中断,而不是傻等

如果你发现 Hermes 跑偏了,别等它输出完。你可以直接输入新消息并回车打断当前任务,或者使用 Ctrl+C。

这会极大提升交互效率。

技巧 4:熟悉几个高频命令

先记住这几个就够用了:

hermes
hermes --tui
hermes model
hermes setup
hermes doctor
hermes update
hermes -c

你不需要第一天就把全部命令背下来,但这几个几乎是日常高频。

技巧 5:基础可用后,再去玩技能和 Gateway

Hermes 后续可以接 Telegram、Discord、Slack 等平台,也支持技能系统和更多自动化能力。

但正确节奏一定是:

先装好 -> 先配模型 -> 先跑通聊天 -> 再叠高级功能

这个顺序看似保守,实际上最省时间。

技巧 6:及时更新,但更新后要做验证

更新命令很简单:

hermes update

更新后建议顺手做这几步:

hermes doctor
hermes version

如果你用到了 Gateway,再检查一下:

hermes gateway status

13. 进阶建议:新手最值得优先掌握的能力

如果你已经跑通基础使用,我建议你按下面顺序继续:

  1. 先熟悉 hermes --tui

  2. 学会 hermes model 和 hermes doctor

  3. 学会恢复会话:hermes -c

  4. 再尝试 /help、/tools、/skills

  5. 最后再接入消息平台或自动化

这样你会比一上来就“全都想要”的用户顺利很多。

14. 一句话总结

在 Windows 11 上安装 Hermes,最正确也最稳的方式就是走 WSL2。不要试图硬上原生 Windows 环境。装好 WSL2 后,用官方安装脚本完成部署,再通过 hermes model 配好 Provider,用 hermes --tui 或 hermes 跑通第一轮对话,基本就算正式入门了。

如果你想少走弯路,请记住一句话:

先让 Hermes 正常完成一次真实对话,再考虑技能、Gateway、自动化和更复杂的玩法。

附:建议收藏的命令清单

# 启动
hermes
hermes --tui

# 配置模型
hermes model

# 一键配置
hermes setup

# 诊断问题
hermes doctor

# 恢复会话
hermes -c

# 查看会话
hermes sessions list

# 更新
hermes update

# 检查网关
hermes gateway status


评论