Hermes Agent 2026年6月Windows原生完整、全流程安装指南
【天极网IT新闻频道】适用系统：Windows 10 2004+(Build 19041+)/ Windows 11
版本状态：官方 Early Beta(v0.14.0+ 已支持核心功能原生运行)
核心参考：NousResearch 官方 Windows 原生文档 + 社区实测踩坑汇总
一、先明确：Windows 原生能做什么/不能做什么
已原生支持的核心功能
完整 CLI 对话与 TUI 界面
终端命令执行、文件读写、全文搜索
所有主流 LLM 提供商对接(含国内智谱、Kimi、通义千问)
MCP 协议服务对接(GitHub、浏览器等)
消息网关(Telegram、Discord、Slack、Email 等)
定时任务(Cron)、技能安装与管理
语音输入输出(Voice 模式)
仍需 WSL2 的限制功能
Dashboard 网页端的内嵌终端面板(依赖 POSIX PTY)
部分依赖 Linux 系统调用的第三方技能
极端复杂的 shell 管道与进程管理
提示：原生安装与 WSL2 安装可完全共存，数据目录相互独立(原生在 %LOCALAPPDATA%\hermes，WSL2 在 ~/.hermes)
二、系统要求与安装前准备
2.1 *低系统要求
操作系统：Windows 10 20H2 及以上 / Windows 11
内存：8GB 以上(推荐 16GB)
磁盘：至少 5GB 空闲空间(依赖+模型缓存)
终端：PowerShell 5.1+ 或 PowerShell 7+(强烈推荐 PowerShell 7，兼容性更好)
网络：能正常访问 GitHub(国内需提前配置代理或镜像)
2.2 必做：调整 PowerShell 执行策略
Windows 默认阻止未签名脚本运行，需先临时放开权限：
# 以管理员身份打开 PowerShell 执行
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
# 输入 Y 确认
安装完成后可恢复默认：Set-ExecutionPolicy Restricted -Scope CurrentUser
2.3 国内网络提前优化(关键!否则必失败)
方案1：使用 GitHub 镜像加速安装脚本
将官方安装脚本的域名替换为国内镜像：
# 原官方命令(国内可能超时)
# irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
# 国内镜像加速命令(推荐)
irm https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
方案2：配置全局包管理器镜像(一劳永逸)
# 1. 配置 uv(Python 包管理器)国内源
uv config set pypi.index-url https://pypi.tuna.tsinghua.edu.cn/simple
# 2. 配置 npm(Node.js 包管理器)国内源
npm config set registry https://registry.npmmirror.com
# 3. 配置 Playwright 浏览器下载镜像
$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"
[Environment]::SetEnvironmentVariable("PLAYWRIGHT_DOWNLOAD_HOST", "https://npmmirror.com/mirrors/playwright", "User")
2.4 提前准备模型 API Key(必做!)
Hermes Agent 本身不自带大模型，必须配置至少一个模型提供商才能使用。建议在安装前就申请好 API Key，这样安装完成后可以直接配置使用。
国内优先推荐(无需代理，网络稳定)
模型提供商 所需环境变量
月之暗面(Kimi)
KIMI_API_KEY / KIMI_CN_API_KEY
智谱 AI(GLM)
GLM_API_KEY / ZAI_API_KEY
通义千问(Qwen)
DASHSCOPE_API_KEY
DeepSeek
DEEPSEEK_API_KEY
海外提供商(需代理)
模型提供商 所需环境变量
OpenAI
OPENAI_API_KEY
Anthropic
ANTHROPIC_API_KEY
OpenRouter
OPENROUTER_API_KEY
新手建议：先只申请并配置一个国内可用的稳定模型(推荐kimi或通义千问)，完成基础功能验证后，再逐步添加其他模型。
三、一键原生安装(官方推荐)
3.1 执行安装脚本
打开 普通用户权限 的 PowerShell(无需管理员)，执行以下命令：
# 国内用户优先使用镜像加速版
irm https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
3.2 安装器自动完成的工作
下载并安装 PortableGit(自带完整 bash 工具链，用于执行 shell 命令)
自动安装 uv(Python 包管理器)和 Python 3.11(独立虚拟环境，不污染系统)
安装 Node.js 22、ripgrep、ffmpeg 等核心依赖
克隆 Hermes Agent 仓库到 %LOCALAPPDATA%\hermes\hermes-agent
创建虚拟环境并安装所有 Python 依赖
自动配置 hermes 全局命令(添加到用户 PATH)
安装 Playwright 及 Chromium 浏览器(用于浏览器自动化)
3.3 验证安装成功
安装完成后，关闭并重新打开 PowerShell(使 PATH 生效)，执行以下命令：
# 查看版本号
hermes --version
# 自动诊断环境问题(必做!会列出所有待修复项)
hermes doctor
若 hermes doctor 提示所有检查项通过，则安装成功;若有红色错误，按提示修复即可。
3.4 默认安装目录说明
# 核心安装目录
%LOCALAPPDATA%\hermes\
├─ hermes-agent\ # Hermes 源代码目录
├─ git\ # PortableGit 安装目录(自带 bash)
├─ venv\ # Python 虚拟环境
└─ data\ # 会话记录、配置文件、技能缓存
四、手动安装(适合自动安装失败的情况)
如果一键脚本因网络或权限问题失败，可按以下步骤手动安装：
4.1 手动安装基础依赖
# 1. 安装 Git(若系统已有可跳过)
winget install Git.Git --accept-source-agreements --accept-package-agreements
# 2. 安装 uv(Python 包管理器)
irm https://astral.sh/uv/install.ps1 | iex
# 3. 安装 Python 3.11
uv python install 3.11
# 4. 安装 Node.js 22
winget install OpenJS.NodeJS.22 --accept-source-agreements --accept-package-agreements
4.2 克隆仓库并安装
# 1. 进入本地应用数据目录
cd $env:LOCALAPPDATA
# 2. 克隆仓库(国内用镜像加速)
git clone https://ghfast.top/https://github.com/NousResearch/hermes-agent.git hermes\hermes-agent
# 3. 进入项目目录
cd hermes\hermes-agent
# 4. 创建虚拟环境并安装依赖
uv venv
.\venv\Scripts\Activate.ps1
uv pip install -e "."
# 5. 安装 Node.js 依赖
npm install
# 6. 安装 Playwright 浏览器
npx playwright install chromium
# 7. 注册全局 hermes 命令
python -m hermes_cli postinstall
4.3 验证手动安装
关闭并重新打开 PowerShell，执行 hermes doctor 检查环境。
五、初始配置与功能验证
5.1 核心配置步骤(按顺序执行)
# 1. 环境诊断(确保所有依赖正常)
hermes doctor
# 2. 配置 LLM 模型(*关键步骤)
hermes model
模型配置详细说明
运行 hermes model 后，会进入交互式配置向导：
选择你的模型提供商(如 zai 对应智谱 AI，qwen 对应通义千问)
输入你提前准备好的 API Key
选择默认使用的模型
等待 Hermes 自动测试连接
Windows 环境下的其他配置方式
除了交互式向导，你还可以通过以下方式配置：
方式1：直接设置环境变量(推荐，更安全)
# 临时生效(当前终端)
$env:GLM_API_KEY = "你的智谱APIKey"
# 永久生效(用户级)
[Environment]::SetEnvironmentVariable("GLM_API_KEY", "你的智谱APIKey", "User")
方式2：通过配置命令设置
hermes config set providers.zai.api_key "你的智谱APIKey"
hermes config set model.default "zai/glm-4.7"
方式3：编辑 .env 文件
在 %LOCALAPPDATA%\hermes\.env 文件中添加：
GLM_API_KEY=你的智谱APIKey
DEFAULT_MODEL=zai/glm-4.7
安全提示：永远不要将 API Key 硬编码到 config.yaml 文件中，所有敏感凭证都应该放在 .env 文件或系统环境变量中。
5.2 基础功能验证
# 1. 启动对话
hermes
# 2. 测试基础问答
# 输入：你好，介绍一下你自己
# 3. 测试终端工具调用
# 输入：列出当前目录下的所有文件
# 4. 测试会话恢复
# 输入 /exit 退出后，执行：
hermes --continue # 或简写 hermes -c
5.3 中文乱码终极解决方案
虽然官方已自动处理大部分编码问题，若仍出现中文显示为 ? 或 UnicodeEncodeError：
临时解决(当前终端生效)
$env:HERMES_DISABLE_WINDOWS_UTF8 = "1"
chcp 65001
hermes
永久解决(系统级)
以管理员身份打开 PowerShell
执行以下命令修改系统默认编码为 UTF-8：
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v ACP /t REG_SZ /d 65001 /f
reg add "HKLM\SYSTEM\CurrentControlSet\Control\Nls\CodePage" /v OEMCP /t REG_SZ /d 65001 /f
重启电脑生效
六、Windows 原生高频问题排查
问题1：提示 hermes: 无法将“hermes”项识别为 cmdlet、函数、脚本文件或可运行程序的名称
原因：PATH 环境变量未生效或命令未正确注册
解决：
关闭所有 PowerShell 窗口，重新打开
手动添加 PATH：
$env:PATH += ";$env:LOCALAPPDATA\hermes\hermes-agent\venv\Scripts"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, "User")
重新执行 python -m hermes_cli postinstall 注册命令
问题2：提示 API key not set 或 Invalid API Key
原因：API Key 未配置或配置错误
解决：
重新运行交互式配置向导：hermes model
检查 API Key 是否复制完整，没有多余的空格或换行
确认你使用的环境变量名称是否正确(如智谱是 GLM_API_KEY 不是 ZAI_API_KEY)
登录对应平台的控制台，检查 API Key 是否有效且账户有余额
问题3：模型能连接但回答异常/乱码
原因：模型名称错误或 base URL 配置错误
解决：
检查模型名称是否正确(如 zai/glm-4.7 而不是 glm-4.7)
关闭多模型路由和 fallback 配置，只保留一个模型测试
确认没有配置错误的代理或中转地址
问题4：Playwright/Chromium 下载失败
原因：网络问题或镜像未配置
解决：
先配置 Playwright 镜像(见 2.3 节)
手动安装浏览器：
$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"
npx playwright install chromium
若不需要浏览器功能，可跳过：
hermes config set browser.enabled false
问题5：终端工具调用失败(提示找不到 bash)
原因：PortableGit 未正确安装或路径未配置
解决：
检查 PortableGit 是否存在：Test-Path $env:LOCALAPPDATA\hermes\git\usr\bin\bash.exe
若不存在，手动下载安装：
winget install Git.Git
手动指定 Git Bash 路径：
hermes config set terminal.shell "C:\Program Files\Git\usr\bin\bash.exe"
问题6：依赖安装失败(提示 Microsoft Visual C++ 14.0 或更高版本是必需的)
原因：缺少 C++ 编译环境，部分 Python 包需要编译
解决：
下载 Microsoft C++ Build Tools
运行安装程序，勾选 "使用 C++ 的桌面开发"
确保右侧勾选了 "Windows 10/11 SDK" 和 "MSVC v143 - VS 2022 C++ x64/x86 构建工具"
安装完成后重启电脑，重新执行安装命令
七、Windows 原生*佳实践与安全建议
不要用管理员权限运行：普通用户权限足够，避免误操作系统文件
文件路径建议：将需要 Hermes 操作的项目文件放在纯英文路径下，避免中文和空格
权限*小化：首次运行时，先在测试目录验证工具调用，不要直接授予全盘读写权限
定期备份数据：所有配置和会话记录都在 %LOCALAPPDATA%\hermes\data，建议定期备份
消息网关安全：连接 Telegram、Discord 等平台时，务必设置用户白名单：
hermes config set gateway.allowlist ["你的用户ID"]
避免同时开启过多功能：先确保 CLI 聊天和终端工具正常，再逐步添加网关、技能和 MCP 服务
八、日常维护命令(Windows 原生通用)
操作 命令
启动聊天
hermes
恢复*近会话
hermes -c
环境诊断
hermes doctor
配置模型
hermes model
配置消息网关
hermes gateway setup
查看网关状态
hermes gateway status
搜索技能
hermes skills search <关键词>
安装技能
hermes skills install <技能名>
检查更新
hermes update --check
执行更新
hermes update
仅卸载程序
hermes uninstall
完全卸载(删除所有数据)
hermes uninstall --full
九、新手一步到位安装流程
# 1. 提前准备：申请好任意一个国内模型的 API Key(推荐kimi或通义千问)
# 2. 以管理员身份打开 PowerShell，设置执行策略
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser -Force
# 3. 配置国内镜像(关键)
uv config set pypi.index-url https://pypi.tuna.tsinghua.edu.cn/simple
npm config set registry https://registry.npmmirror.com
$env:PLAYWRIGHT_DOWNLOAD_HOST = "https://npmmirror.com/mirrors/playwright"
[Environment]::SetEnvironmentVariable("PLAYWRIGHT_DOWNLOAD_HOST", "https://npmmirror.com/mirrors/playwright", "User")
# 4. 执行一键安装(镜像加速版)
irm https://ghfast.top/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex
# 5. 关闭并重新打开 PowerShell
# 6. 检查环境
hermes doctor
# 7. 配置模型(输入你提前准备好的 API Key)
hermes model
# 8. 启动聊天
hermes
*后提醒：Windows 原生版本仍处于 Early Beta 阶段，若遇到无法解决的兼容性问题，可临时切换到 WSL2 方案。官方正在持续优化 Windows 支持，建议定期执行 hermes update 获取*新修复。
类型：广告
免责声明：以上内容来源于互联网，如有侵权请联系我们删除。