网站发布教程文章｜含封面图、安装流程、命令模板、FAQ 与 SEO 文档
文章导语
HermesAgent 是 Nous Research 推出的 AI Agent 工具，适合在终端里完成代码分析、自动化任务、工具调用、消息网关和长期工作流配置。对 Windows 用户来说，安装时最容易卡住的不是 Hermes 本身，而是 Windows、WSL2、Git、PATH、模型 API Key 和终端环境之间的关系。
这篇教程按新手视角来写：先判断你的电脑适合走哪条安装路线，再一步一步执行命令，最后用 hermes doctor 和首次对话来验证是否真正安装成功。建议首次安装优先走 WSL2 路线；如果你愿意尝试新功能，也可以使用官方提供的 PowerShell 原生 Windows Early Beta 安装方式。
图示：Windows 安装 HermesAgent 的三条路线，普通用户优先选择 WSL2。
安装前先看结论：Windows 用户推荐哪种方案
方案 A：WSL2 安装，推荐新手优先使用
WSL2 是 Windows 上运行 Linux 环境的官方方案。HermesAgent 的核心安装命令和很多终端工具都天然适配 Linux 命令行，因此 WSL2 是目前最稳妥、最容易排查问题的路线。你在 Windows 里打开 Ubuntu 终端，然后像在 Linux 服务器上一样安装 HermesAgent。
方案 B：PowerShell 原生 Windows 安装，适合愿意尝鲜的用户
Hermes Agent 官方安装文档已经提供 Windows 原生 PowerShell 安装命令，但官方同时标注为 Early Beta，意思是常见路径可用，但没有像 POSIX 安装器那样经过更广泛的验证。它的优点是不用先学习 WSL2，缺点是遇到终端、编码、路径或某些工具调用问题时，排查成本可能更高。
方案 C：Docker Desktop + WSL2，适合想要隔离环境的用户
如果你已经熟悉 Docker，可以通过 Docker Desktop 的 WSL2 后端运行 HermesAgent。这个方案隔离性更好，适合测试、部署或避免污染本机环境，但对 Docker Desktop、WSL 集成、端口映射和数据目录挂载要求更高，不建议纯小白第一步就选。
安装前准备清单
| 准备项 | 建议或说明 |
| Windows 系统 | Windows 11，或 Windows 10 版本 2004 及以上，Build 19041 及以上。 |
| 虚拟化 | BIOS/UEFI 里开启虚拟化，WSL2 和 Docker Desktop 都会用到。 |
| 终端工具 | 建议使用 Windows Terminal，PowerShell 和 Ubuntu 终端都更方便管理。 |
| 网络环境 | 需要能访问 GitHub、模型服务商 API、包管理器下载源。 |
| Git | WSL2 里至少要能运行 git –version；官方安装器会自动处理很多其他依赖。 |
| 模型账号 | 准备 OpenRouter、OpenAI、Anthropic、DeepSeek、Kimi、DashScope 等任一可用 Provider 的 API Key 或登录方式。 |
| 磁盘空间 | 建议预留 5GB 以上空间，后续模型缓存、日志和工具环境可能继续增长。 |
方案 A：使用 WSL2 安装 HermesAgent
图示：从安装 WSL2 到跑通 Hermes 对话的完整验收流程。
第 1 步：用管理员 PowerShell 安装 WSL2
在 Windows 搜索框输入 PowerShell，右键选择“以管理员身份运行”。然后执行以下命令：
| PowerShell 管理员窗口 |
| wsl –install |
执行后根据提示重启电脑。首次打开 Ubuntu 时，系统会要求你创建一个 Linux 用户名和密码。这个密码在使用 sudo 命令时会用到，输入时终端可能不会显示星号，这是正常现象。
第 2 步：检查 WSL 版本是否为 2
| PowerShell 检查 WSL |
| wsl –list –verbose wsl –set-default-version 2 |
如果你看到 Ubuntu 后面的 VERSION 是 2，说明已经是 WSL2。如果还是 1，需要先升级到 WSL2，再继续安装 HermesAgent。
第 3 步：进入 Ubuntu 并更新基础环境
从开始菜单打开 Ubuntu，或者在 PowerShell 输入 wsl 进入 Ubuntu。然后执行：
| Ubuntu / WSL2 终端 |
| sudo apt update && sudo apt upgrade -y sudo apt install -y git curl ca-certificates |
虽然 Hermes 官方安装器会处理很多依赖，但先把 Git、curl 和证书包准备好，可以减少后续下载失败、证书错误和 git not found 的概率。
第 4 步：运行 HermesAgent 官方安装命令
| Ubuntu / WSL2 终端 |
| curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash |
安装器会自动处理 HermesAgent 代码、Python 环境、Node.js、ripgrep、ffmpeg 等依赖，并配置 hermes 命令。安装完成后，重新加载 shell：
| 让当前终端识别 hermes 命令 |
| source ~/.bashrc |
第 5 步：验证安装是否成功
| 安装验证命令 |
| hermes –version hermes doctor |
hermes –version 能显示版本号，说明命令已经可用。hermes doctor 会检查环境、配置、依赖和 API Key，如果有缺失，会提示你下一步应该修哪里。
图示：WSL2 路线常用命令速查。
方案 B：PowerShell 原生 Windows Beta 安装
适合什么人使用
如果你不想进入 Ubuntu，也可以尝试官方文档提供的 Windows 原生 PowerShell 安装方式。它会安装 uv、Python 3.11、Node.js 22、ripgrep、ffmpeg 和 PortableGit，并把 HermesAgent 放在 Windows 用户目录下。
但要注意：官方文档把这个能力标记为 Early Beta。也就是说，普通 CLI、网关、定时任务、浏览器工具和 MCP 等常见能力正在支持，但部分 Dashboard 内嵌终端能力仍更适合 WSL2 路线。
安装命令
打开 PowerShell，执行：
| PowerShell 原生 Windows Beta 安装 |
| irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex |
安装完成后，关闭当前 PowerShell，重新打开一个新的 PowerShell 窗口，让 PATH 生效。然后执行：
| PowerShell 验证 |
| hermes –version hermes doctor hermes model hermes |
原生 Windows Beta 常见注意事项
- 如果 hermes 命令不存在，先关闭终端重新打开，再检查用户 PATH 是否已更新。
- 如果安全软件拦截 PortableGit、Node 或 Python 相关文件，需要在安全软件里恢复并加入信任。
- 如果终端出现乱码或编码异常，可以先切回 WSL2 路线；官方也提供了环境变量用于编码问题排查。
- 如果需要最稳定的终端工具调用、复杂文件操作或类 Linux 命令环境，仍建议使用 WSL2。
方案 C：Docker Desktop + WSL2 安装
什么时候选择 Docker
Docker 路线适合已经熟悉容器的用户。它的好处是隔离环境、方便迁移、容易重建；缺点是新手需要额外理解 Docker Desktop、WSL 集成、端口映射和数据卷。
基础思路
- 安装 Docker Desktop，并在设置里启用 WSL2 based engine。
- 在 Docker Desktop 的 Resources / WSL Integration 里启用你的 Ubuntu 发行版。
- 从 Ubuntu 终端运行 docker version，确认 WSL 里能访问 Docker。
- 把 Hermes 数据目录放在 WSL 文件系统内，例如 ~/hermes-data，尽量不要放在 /mnt/c/ 下面。
- 运行官方镜像，并把需要的 API Key 通过环境变量传入容器。
| Docker 运行示例 |
| docker run –rm -it \ -v ~/.hermes:/root/.hermes \ -e OPENAI_API_KEY=$OPENAI_API_KEY \ nousresearch/hermes-agent:latest |
如果你要长期运行，建议后续改成 docker compose，并固定镜像版本，避免 latest 更新带来不可控变化。
配置模型 Provider：让 HermesAgent 真正能回复
先运行 hermes model
安装完成后，最关键的一步是配置模型 Provider。直接运行：
| 交互式选择模型 |
| hermes model |
根据提示选择你要使用的模型服务商，例如 OpenRouter、OpenAI、Anthropic、DeepSeek、Kimi、DashScope、GitHub Copilot、Vercel AI Gateway 或自定义 OpenAI-compatible endpoint。
新手怎么选 Provider
| 情况 | 建议选择 |
| 想省事 | 选择 OpenRouter 或 Nous Portal 这类聚合/官方推荐路径，按提示填 Key。 |
| 已有 OpenAI API Key | 选择 OpenAI 或 OpenAI-compatible endpoint。 |
| 已有 Claude / Anthropic 账号 | 选择 Anthropic 相关 Provider，按官方要求配置 OAuth 或 API Key。 |
| 国内开发者 | 可以尝试 DeepSeek、Kimi / Moonshot、DashScope / Qwen 等 Provider。 |
| 本地模型用户 | 使用 Ollama、vLLM、SGLang 等 OpenAI-compatible 端点，并确保上下文长度足够。 |
为什么模型上下文很重要
HermesAgent 是面向多步工具调用和长期任务的 Agent。官方 Quickstart 明确建议模型上下文至少 64K tokens，否则可能因为上下文窗口太小而无法稳定维护任务状态。使用本地模型时，务必把上下文长度调到足够大。
第一次运行：如何判断真的安装成功
启动 CLI 或 TUI
| 首次启动 |
| hermes # 或者使用更现代的终端界面 hermes –tui |
成功时，你会看到 HermesAgent 的欢迎信息、当前模型、可用工具和会话状态。可以先用一个简单、可验证的问题测试：
| 首次测试提示词 |
| 请检查当前目录，告诉我这里有哪些主要文件，并用 5 条要点说明这个目录可能是什么项目。 |
验证会话保存和继续
| 继续上一次会话 |
| hermes –continue # 简写 hermes -c |
如果能恢复上一次对话，说明会话存储也正常。这个步骤很重要，因为后续你做自动化、网关或长期任务时，很多问题都和 profile、session、config 有关。
常用命令速查
| 命令 | 作用 |
| hermes | 启动经典 CLI 对话。 |
| hermes –tui | 启动现代 TUI 界面。 |
| hermes doctor | 检查依赖、配置和常见环境问题。 |
| hermes model | 选择或切换模型 Provider。 |
| hermes setup | 运行完整配置向导。 |
| hermes tools | 配置工具访问权限。 |
| hermes gateway setup | 配置 Telegram、Discord、Slack 等消息网关。 |
| hermes –continue | 继续最近一次会话。 |
| hermes update | 更新 HermesAgent。 |
| hermes config check | 检查配置是否缺失或过期。 |
| hermes config migrate | 迁移并补齐新版本配置项。 |
后续进阶：Dashboard、网关和工具隔离
打开 Dashboard
如果你需要图形化查看配置、日志、任务和状态，可以尝试启动 Dashboard。WSL2 路线一般可以通过 Windows 浏览器访问 localhost 端口。
| 启动 Dashboard |
| hermes dashboard |
如果浏览器打不开，先确认终端里 dashboard 是否成功启动，再检查端口是否被占用、防火墙是否拦截，以及你是否在 WSL2 中运行。
配置消息网关
当 CLI 已经稳定后，再考虑 Telegram、Discord、Slack、Email 等平台接入。不要在基础聊天还没跑通时就配置网关，否则排查会变复杂。
| 网关配置与状态检查 |
| hermes gateway setup hermes gateway status |
切换终端工具后端
如果你担心 Agent 直接在主机执行命令，可以把终端后端切换到 Docker 或远程 SSH。新手建议先用本地或 WSL2 跑通，再按需启用隔离。
| 工具执行后端配置 |
| hermes config set terminal.backend docker # 或 hermes config set terminal.backend ssh |
常见报错与解决方法
图示：Windows 安装 HermesAgent 常见问题优先排查路径。
| 问题现象 | 可能原因 | 解决方法 |
| wsl –install 无法执行 | Windows 版本过旧、不是管理员、系统组件异常 | 确认 Windows 版本，管理员 PowerShell 运行，必要时执行 wsl –update 并重启。 |
| Ubuntu 打不开或卡住 | WSL 安装未完成或发行版异常 | 重启电脑，执行 wsl –status、wsl –list –verbose 检查状态。 |
| git not found | WSL 内没有安装 Git | 执行 sudo apt install -y git，然后 git –version 验证。 |
| curl 下载失败 | 网络无法访问 GitHub 或证书异常 | 检查网络代理、DNS、证书包，安装 ca-certificates。 |
| hermes: command not found | PATH 未刷新或安装未完成 | 执行 source ~/.bashrc，或关闭终端重新打开，再运行 hermes –version。 |
| hermes doctor 报 API key not set | 模型 Provider 未配置 | 运行 hermes model，按提示选择 Provider 并填入 Key。 |
| 回复空白或失败 | 模型名称、Base URL、Key、上下文长度配置错误 | 重新运行 hermes model，先用官方或稳定 Provider 测试，不要同时配置复杂 fallback。 |
| Dashboard 打不开 | 服务未启动、端口冲突、防火墙拦截 | 确认 hermes dashboard 输出，检查端口占用，允许本机访问。 |
| 原生 Windows Beta 异常 | Beta 路线对路径、编码、终端工具兼容要求更高 | 优先改用 WSL2，或按官方提示收集日志后反馈。 |
新手最容易踩的 8 个坑
- 把 WSL2 命令放到 PowerShell 里执行，或者把 PowerShell 命令放到 Ubuntu 里执行。先看清当前终端是哪一个。
- 安装完不重启终端，导致 hermes 命令找不到。
- 没有配置模型 Provider，就直接期待 Hermes 能回复。
- 使用上下文太小的本地模型，导致 Agent 任务能力不稳定。
- 在 /mnt/c/ 下做大量 Linux 文件操作，导致权限、速度和路径问题。
- 基础 CLI 都没跑通，就开始配置 Dashboard、网关、MCP 和定时任务。
- 看到报错就重装，而不是先运行 hermes doctor。
- 把 API Key、token、配置截图直接发到公开论坛求助，造成密钥泄露。
安装完成后的维护建议
定期更新
HermesAgent 更新可以直接使用官方命令：
| 更新和更新后检查 |
| hermes update hermes config check hermes config migrate hermes doctor |
更新后建议重新跑一次 hermes doctor，再用一个简单任务验证模型和工具是否正常。生产环境或长期运行的网关建议更新前先备份 ~/.hermes。
备份哪些目录
最重要的是 ~/.hermes 目录，其中通常包含配置、密钥、会话、技能、配对数据等。Windows 原生 Beta 路线的数据位置可能在 %LOCALAPPDATA%\hermes 下，具体以安装器输出和官方文档为准。
安全建议
- 不要把 API Key 写进公开文章、截图或仓库。
- 对自动执行命令的 Agent，先从低权限目录开始测试。
- 涉及服务器、数据库、支付或删除文件任务时，先让 Agent 输出计划，再人工确认。
- 企业或团队使用时，建议使用隔离账户、Docker 后端或远程测试环境。
可复制提示词模板
| 让 HermesAgent 检查安装状态 |
| 请检查当前 HermesAgent 安装状态： 1. 运行必要的版本和环境检查； 2. 判断 hermes 命令、模型配置、工具配置是否正常； 3. 把发现的问题按“必须修复 / 建议优化 / 可暂时忽略”分类； 4. 不要直接修改系统配置，先给我修复命令和原因。 |
| 让 HermesAgent 分析当前项目 |
| 请分析当前目录中的项目结构： 1. 找出主要入口文件； 2. 判断技术栈； 3. 总结项目用途； 4. 标出可能需要补充文档或测试的地方； 5. 不要修改文件，只输出分析报告。 |
| 让 HermesAgent 安全执行任务 |
| 我要让你执行一个自动化任务，请先输出执行计划，不要立刻动手。 任务目标：【填写任务】 约束条件：不要删除文件，不要提交代码，不要暴露 API Key。 请先列出：需要读取哪些文件、准备执行哪些命令、每一步可能的风险。 |
FAQ：Windows 安装 HermesAgent 常见问题
HermesAgent 能不能直接装在 Windows 上？
官方文档已经提供 PowerShell 原生 Windows Early Beta 安装命令，但从稳定性和排查成本看，新手仍建议优先使用 WSL2 路线。
为什么教程里推荐 WSL2？
因为 HermesAgent 很多工具调用、脚本、终端操作和依赖处理更适配 Linux 环境。WSL2 能在 Windows 上提供接近 Linux 的命令行体验。
我已经装了 Python 和 Node.js，还需要再装吗？
通常不需要手动准备。官方安装器会处理 uv、Python、Node.js、ripgrep、ffmpeg 等依赖。你只需要保证 Git 和基础网络环境正常。
hermes 命令找不到怎么办？
先重启终端；WSL2 里执行 source ~/.bashrc；然后运行 echo $PATH 和 hermes –version 检查。
安装完成后为什么还是不能聊天？
大概率是模型 Provider 没配置好。运行 hermes model，选择服务商并填入 API Key 或完成 OAuth，再运行 hermes doctor。
可以用 DeepSeek、Kimi、通义千问这些模型吗？
可以尝试官方支持的 Provider 或 OpenAI-compatible endpoint，但要确认 API Key、Base URL、模型名和上下文长度配置正确。
本地 Ollama 能不能用？
可以通过自定义 OpenAI-compatible endpoint 或对应 Provider 方式接入，但本地模型上下文长度需要足够大，官方建议至少 64K tokens。
Docker 路线是不是更安全？
Docker 可以提供一定隔离，但不是万能沙箱。新手先用 WSL2 跑通，再根据需要切换 terminal.backend docker。
Dashboard 打不开是不是安装失败？
不一定。先确认 CLI 能否正常运行。Dashboard 是额外界面，可能受端口、防火墙、WSL 转发或依赖影响。
我应该用哪个终端？
推荐 Windows Terminal。PowerShell 用于安装 WSL2 或原生 Beta；Ubuntu / WSL2 终端用于执行 Linux 安装命令。
参考资料与说明
本文依据 Hermes Agent 官方安装文档、官方 Quickstart、官方更新说明，以及 Microsoft WSL 官方安装文档整理。由于 HermesAgent 和 Windows 原生支持仍在持续更新，发布前建议再次核对官方安装页面中的命令和版本提示。
| 来源 | 本文参考的重点 |
| Hermes Agent 官方 Installation | Linux / macOS / WSL2 一行安装命令、PowerShell 原生 Windows Early Beta、安装器处理依赖、安装后验证和常见问题。 |
| Hermes Agent 官方 Quickstart | hermes model、hermes doctor、hermes –tui、Provider 选择、64K 上下文建议、恢复会话和 Recovery Toolkit。 |
| Hermes Agent 官方 Updating & Uninstalling | hermes update、配置迁移、更新后验证和备份建议。 |
| Microsoft WSL 官方文档 | wsl –install、Windows 版本要求、wsl –list –verbose、wsl –set-default-version 2 等命令。 |
