如果你想在 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汇聚站接入?
打开AI汇聚站https://ai.mccxy.top
选择想要接入的模型并选取好合适分组创建好API Key

进入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. 接入微信渠道
进入hermes网关配置
hermes setup gateway选择微信渠道
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)同意二维码登录
Start QR login now?
↑↓ navigate ENTER/SPACE select ESC cancel ← previous
可以复制链接到浏览器打开扫描二维码,或者直接扫描二维码

后续就一直 yes就行,按推荐来就可以
微信列表就会出现一个带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. 进阶建议:新手最值得优先掌握的能力
如果你已经跑通基础使用,我建议你按下面顺序继续:
先熟悉
hermes --tui学会
hermes model和hermes doctor学会恢复会话:
hermes -c再尝试
/help、/tools、/skills最后再接入消息平台或自动化
这样你会比一上来就“全都想要”的用户顺利很多。
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