HermesAgent 在 Windows 原生环境安装运行指南

大家好，我是张大鹏，10 年全栈开发经验，目前在做 AI 在线教育培训。最近在研究 HermesAgent 这个开源 AI Agent 框架，准备基于它做二次开发。本文记录我在 Windows 11 原生环境下搭建开发环境的完整过程，踩了不少坑，分享给大家。

为什么要写这篇文章

HermesAgent 是 Nous Research 开源的自改进 AI Agent 框架，功能很强大------内置闭环学习系统、技能自动创建、跨会话记忆等。我打算基于它做教育场景的二次开发。

但官方 README 明确写着：不支持原生 Windows，建议使用 WSL2。

作为一个在 Windows 上开发了 10 年的全栈工程师，我对 WSL2 一直有心理阴影------文件系统性能差、网络配置麻烦、和 Windows 工具链割裂。所以我的第一反应是：能不能在 Windows 原生环境下跑起来？

翻了一下代码，发现项目其实提供了 PowerShell 安装脚本（scripts/install.ps1），bash 安装脚本也会把 Windows 用户重定向到它。所以官方说的"不支持"可能只是"不推荐"，实际上是可以跑的。

本文就是我在 Windows 11 原生环境下从零搭建 HermesAgent 二次开发环境的完整记录，包括踩过的坑和解决方案。

快速开始（TL;DR）

如果你也是老手，直接看这几行命令：

bash 复制代码

cd D:\code\HermesAgent
uv venv venv --python 3.11
source venv/Scripts/activate
uv pip install -e ".[all]"
npm install
npx playwright install chromium
cp .env.example .env
# 编辑 .env 填入 XIAOMI_API_KEY 和 XIAOMI_BASE_URL
# 编辑 ~/.hermes/config.yaml 设置 model.default
./venv/Scripts/hermes.exe

下面展开讲每一步的细节和踩坑。

一、我的开发环境

先交代一下我的环境，方便大家对照：

项目	版本
操作系统	Windows 11 Home China
Python	3.13.13（系统自带）
uv	0.11.7（Python 包管理神器）
Node.js	v24.15.0
Git	2.54.0

HermesAgent 要求 Python >= 3.11，我的系统 Python 是 3.13，完全满足。但后面创建 venv 时我会用 3.11，原因后面说。

如果你还没有 uv，强烈推荐装一个，比 pip 快 10 倍以上：

powershell 复制代码

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

二、安装方案选择

官方提供了两种安装方式：

方案 A：PowerShell 一键安装

powershell 复制代码

irm https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1 | iex

这个脚本会自动克隆代码到 %LOCALAPPDATA%\hermes\hermes-agent，创建 venv、安装依赖、配置 PATH。

适合：从零开始、没有现成代码仓库的用户。

方案 B：手动搭建（我选的这个）

我已经 clone 了代码到 D:\code\HermesAgent，不想再搬一份。所以直接在现有目录里搭建。

适合：已有代码仓库、需要二次开发的开发者。

三、安装过程（含踩坑记录）

3.1 创建 Python 虚拟环境

bash 复制代码

cd D:\code\HermesAgent
uv venv venv --python 3.11

输出：

复制代码

Downloading cpython-3.11.15-windows-x86_64-none (download) (24.4MiB)
Downloaded cpython-3.11.15-windows-x86_64-none (download)
Using CPython 3.11.15
Creating virtual environment at: venv

为什么用 3.11 而不是系统的 3.13？

HermesAgent 的 pyproject.toml 写的是 requires-python = ">=3.11"，理论上 3.13 也行。但官方安装脚本统一用 3.11，有些第三方依赖在 3.13 上可能缺 wheel。用 3.11 是最保险的选择。

uv 的好处是它会自动下载 Python 3.11.15，不需要你手动装。

3.2 安装 Python 依赖

bash 复制代码

source venv/Scripts/activate
uv pip install -e ".[all]"

这一步是最耗时的，大概 5-6 分钟。输出：

复制代码

Resolved 190 packages
Prepared 189 packages in 5m 47s

190 个包！HermesAgent 的依赖确实多，因为它支持太多功能了------LLM 调用、终端工具、浏览器自动化、语音转文字、消息平台集成等等。

如果 [all] 安装失败（有些可选依赖在 Windows 上可能编译不过），回退到基础安装：

bash 复制代码

uv pip install -e "."

基础安装只包含核心功能，足够跑了。

3.3 安装 Node.js 依赖

bash 复制代码

npm install

这一步安装浏览器工具相关的依赖（Playwright 等）。HermesAgent 的浏览器自动化能力需要用到。

3.4 安装 Playwright 浏览器引擎

bash 复制代码

npx playwright install chromium

下载约 290MB，包括 Chrome、FFmpeg、Chrome Headless Shell。

输出：

复制代码

Chrome for Testing 147.0.7727.15 downloaded to C:\Users\18010\AppData\Local\ms-playwright\chromium-1217
FFmpeg (playwright ffmpeg v1011) downloaded
Chrome Headless Shell 147.0.7727.15 downloaded

这一步如果不装，浏览器相关的工具就不能用，但不影响核心功能。

3.5 配置环境文件

bash 复制代码

cp .env.example .env

然后编辑 .env，填入你的 API Key。

我用的是小米 MiMo Coding Plan，所以配置如下：

bash 复制代码

XIAOMI_API_KEY=你的小米API Key
XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

3.6 配置默认模型

把配置文件复制到用户目录：

bash 复制代码

cp .env ~/.hermes/.env
cp cli-config.yaml.example ~/.hermes/config.yaml

编辑 ~/.hermes/config.yaml（Windows 路径：C:\Users\你的用户名\.hermes\config.yaml）：

yaml 复制代码

model:
  default: "xiaomi/mimo-v2.5-pro"
  provider: "auto"

可选模型：

xiaomi/mimo-v2.5-pro --- 推理能力最强，适合复杂任务
xiaomi/mimo-v2.5 --- 速度快，适合日常对话

3.7 启动

bash 复制代码

# 方式 1：直接调用 venv 中的 hermes（推荐，不需要激活 venv）
./venv/Scripts/hermes.exe

# 方式 2：激活 venv 后使用 hermes 命令
source venv/Scripts/activate
hermes

# 方式 3：通过 Python 模块启动
python -m hermes_cli.main

单次查询模式（Oneshot）

不想进交互界面？用 -z 参数：

bash 复制代码

hermes -z "用一句话介绍HermesAgent"

指定模型：

bash 复制代码

hermes -z "1+1=?" -m xiaomi/mimo-v2.5

这个模式很适合脚本调用或快速验证。

四、踩坑记录（重点！）

坑 1：小米 Coding Plan 的 API 地址不对

现象：用默认地址 https://api.xiaomimimo.com/v1 调用 API，返回 401 Invalid API Key。

排查过程：一开始以为 Key 填错了，反复检查了好几遍。后来用 curl 直接测试，发现请求确实到了小米的服务器，但认证失败。

根因：小米 Coding Plan 用的是专用 API 地址，和普通版不一样！

解决：在 .env 中设置：

bash 复制代码

XIAOMI_BASE_URL=https://token-plan-cn.xiaomimimo.com/v1

小米 Coding Plan 的完整地址：

OpenAI 兼容：https://token-plan-cn.xiaomimimo.com/v1
Anthropic 兼容：https://token-plan-cn.xiaomimimo.com/anthropic

教训：用第三方 LLM 提供商时，一定要确认 API 地址是否正确，不能想当然。

坑 2：Windows GBK 编码导致 Unicode 报错

现象：运行 hermes doctor 时出现：

复制代码

UnicodeEncodeError: 'gbk' codec can't encode character '\U0001fa7a' in position 18

原因：HermesAgent 的输出包含 emoji（🩺、✓、⚠ 等），但 Windows 默认终端编码是 GBK，不支持这些字符。

解决：设置环境变量 PYTHONIOENCODING=utf-8：

Git Bash：

bash 复制代码

export PYTHONIOENCODING=utf-8

PowerShell：

powershell 复制代码

$env:PYTHONIOENCODING = "utf-8"

永久设置（推荐，一劳永逸）：

powershell 复制代码

[System.Environment]::SetEnvironmentVariable("PYTHONIOENCODING", "utf-8", "User")

教训：Windows 上跑国际化开源项目，UTF-8 环境变量是标配。

坑 3：hermes doctor 命令卡住

现象：运行 hermes doctor 时命令挂起，没有任何输出。

原因：doctor 命令会检测各种网络服务，某些检测可能因为网络问题超时。

解决：用 Python 直接验证配置：

bash 复制代码

python -c "from hermes_cli.config import load_config; cfg = load_config(); print(cfg.get('model',{}).get('default'))"

输出 xiaomi/mimo-v2.5-pro 就说明配置正确。

五、依赖说明

HermesAgent 的依赖很多，这里挑几个核心的说明：

依赖	用途	是否必需
openai	OpenAI API 客户端（小米 MiMo 兼容）	核心
anthropic	Anthropic Claude API 客户端	核心
prompt_toolkit	交互式 CLI 终端界面	核心
rich	终端富文本渲染	核心
edge-tts	文字转语音（免费）	可选
exa-py	AI 原生网页搜索	可选
firecrawl-py	网页搜索、提取、爬取	可选
pywinpty	Windows PTY 支持	可选
faster-whisper	本地语音转文字	可选
discord.py	Discord 集成	可选
python-telegram-bot	Telegram 集成	可选

核心依赖只有 4 个，其他的都是按需安装。这也是为什么基础安装 [all] 失败时可以回退到 pip install -e "."。

六、验证安装

模块导入测试

bash 复制代码

python -c "import hermes_cli; print('OK')"
python -c "import agent; print('OK')"

两个都输出 OK 就没问题。

API 连通性测试

bash 复制代码

python -c "
import openai, os
from dotenv import load_dotenv
load_dotenv()
client = openai.OpenAI(
    api_key=os.getenv('XIAOMI_API_KEY'),
    base_url=os.getenv('XIAOMI_BASE_URL')
)
resp = client.chat.completions.create(
    model='mimo-v2.5-pro',
    messages=[{'role':'user','content':'1+1=?'}],
    max_tokens=200
)
print(f'OK! Reply: {resp.choices[0].message.content}')
"

实际输出：

复制代码

OK! Reply: 1 + 1 = **2** 😊

hermes 命令测试

bash 复制代码

./venv/Scripts/hermes.exe -z "1+1=?"

输出：

复制代码

1 + 1 = 2

能跑起来就说明环境没问题了。

七、常用命令速查

命令	说明
`hermes`	启动交互式对话
`hermes -z "问题"`	单次查询（不进入交互界面）
`hermes -m xiaomi/mimo-v2.5`	指定模型启动
`hermes model`	选择默认模型和提供商
`hermes setup`	运行设置向导
`hermes config`	查看配置
`hermes config edit`	编辑配置文件
`hermes doctor`	诊断环境问题
`hermes status`	检查配置状态
`hermes sessions list`	查看历史会话
`hermes skills`	浏览和安装技能

八、总结

经过这次实践，我确认了 HermesAgent 可以在 Windows 11 原生环境下作为二次开发环境正常运行，不需要 WSL2。

作为有 10 年全栈开发经验的老兵，我的经验是：开源项目说"不支持"，不代表"不能用"，很多时候只是"没测试过"。只要你愿意花时间踩坑，大多数 Linux 优先的项目都能在 Windows 上跑起来。

关键步骤：

uv 创建 Python 3.11 虚拟环境（自动下载，省心）
安装 Python 和 Node.js 依赖
配置小米 MiMo Coding Plan（注意专用 API 地址）
设置 PYTHONIOENCODING=utf-8 解决编码问题

整个过程约 10-15 分钟，主要时间花在下载依赖上。接下来我会基于这个环境进行 HermesAgent 的教育场景二次开发，后续会分享更多开发经验。

参考

HermesAgent GitHub 仓库
$HermesAgent 深度解析博客\](./001-HermesAgent深度解析-NousResearch开源的自改进AI Agent框架.md)$
HermesAgent 文档全面中文化博客
uv 官方文档
小米 MiMo 开放平台

我是张大鹏，10 年全栈开发，现在专注于 AI 在线教育培训。大鹏 AI 教育团队持续分享 AI Agent 开发实战经验，欢迎关注。