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 获取*新修复。

类型：广告