本文基于 Windows 系统下安装 Hermes 的实战经验整理而成。整个部署流程的核心在于打通 WSL2、Ubuntu 环境与 Hermes 配置的完整链路而非单一命令操作。文中同步梳理了版本兼容、接口适配、参数填写等常见踩坑点为 Windows 用户提供一份可直接参考的落地教程。一、为何优先用 WSL2 安装 HermesHermes 的运行逻辑与依赖适配更贴合 Linux 环境。对 Windows 用户而言无需重装系统、无需搭建双系统通过 WSL2Windows 子系统 Linux构建虚拟 Linux 环境是最便捷、稳定的部署方案。整体部署路径校验 Windows 系统版本确认 WSL2 兼容性启用 WSL 与虚拟机平台核心功能安装 WSL2 专属 Linux 内核更新包部署并初始化 Ubuntu 子系统在 Ubuntu 中执行 Hermes 一键安装脚本对接大模型服务完成 Hermes 自定义配置下面按实操顺序分步详解。二、Windows 前置准备启用 WSL2 核心能力2.1 校验系统版本必备前提WSL2 对 Windows 版本有明确要求需满足Windows 10 190318362及以上 / Windows 11 全版本。快捷键WinR输入winver回车查看系统版本号版本过低时先通过 Windows 更新完成系统升级避免后续兼容报错2.2 开启 WSL 与虚拟机平台功能以管理员身份打开 PowerShell / 命令提示符依次执行以下 2 条命令启用核心系统功能powershell# 启用Linux子系统功能 dism.exe /online /enable-feature /featurename:Microsoft-Windows-Subsystem-Linux /all /norestart # 启用虚拟机平台功能WSL2依赖 dism.exe /online /enable-feature /featurename:VirtualMachinePlatform /all /norestart✅ 关键步骤命令执行完成后必须重启电脑否则后续 WSL2 初始化、Ubuntu 转换会出现未知异常。2.3 安装 WSL2 Linux 内核更新包重启后需安装微软官方 WSL2 内核包确保虚拟 Linux 环境正常运行下载WSL2 Linux 内核更新包微软官方渠道安装双击下载文件按提示完成安装再次重启电脑让内核更新完全生效2.4 设定 WSL2 为默认版本重启后在管理员 PowerShell 中执行命令确保后续 Linux 分发版默认使用 WSL2powershellwsl --set-default-version 2三、Ubuntu 子系统部署与版本切换3.1 安装 Ubuntu 子系统打开 Microsoft Store搜索 “Ubuntu”选择官方版本推荐 22.04 LTS安装安装完成后在 Windows 开始菜单找到 Ubuntu建议以管理员身份运行减少权限报错3.2 已有 Ubuntu 切换至 WSL2若此前已安装 Ubuntu默认 WSL1需手动转换为 WSL2powershell# 停止正在运行的Ubuntu wsl --terminate Ubuntu # 转换为WSL2版本 wsl --set-version Ubuntu 2 # 设为默认分发版可选 wsl --set-default Ubuntu3.3 WSL 异常修复转换失败或运行报错时执行以下命令排查修复powershell# 更新WSL组件 wsl --update # 网络异常时用国内源更新 wsl --update --web-download # 重置WSL后重试谨慎操作避免数据丢失 wsl --shutdown四、Ubuntu 环境安装 Hermes打开 Ubuntu 终端进入 Linux 环境执行 Hermes 官方一键安装脚本4.1 官方脚本海外网络bash运行curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash4.2 国内源脚本网络不佳时bash运行curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash -x4.3 安装过程说明脚本会自动完成以下操作全程无需手动干预安装 uv 包管理器Python 依赖管理工具检测并安装 Python 3.11Hermes 指定版本下载 Hermes 核心程序与技能包配置环境变量完成基础部署等待终端提示安装完成即可进入 Hermes 初始化配置界面。五、Hermes 模型配置自定义接口实操安装完成后Hermes 会自动启动配置向导核心是对接大模型服务本文以自定义 OpenAI 兼容接口为例适配国内主流平台5.1 选择配置模式向导提供 2 种模式新手推荐快速配置Quick setup仅需配置模型供应商、接口与消息服务进阶用户可选完整配置。5.2 选择模型供应商在供应商列表中选择Custom endpoint自定义接口适配国内大模型平台如 Routin、通义千问、DeepSeek 等。5.3 填写接口核心参数关键按平台文档准确填写以下信息参数错误会导致连接失败API 基础地址API base URL如https://cn.routin.ai/plan/v1API 密钥API key平台生成的专属密钥模型名称Model name严格复制平台标准名称如gpt-5.4上下文长度、显示名称按平台默认填写即可5.4 消息服务配置可选配置完成后可选择连接消息平台Telegram、飞书、微信等实现跨设备控制新手可先选择跳过Skip后续通过命令补充配置。✅ 配置成功后终端会显示 Hermes 欢迎界面列出已加载的工具与技能包至此部署完成。六、安装后自检与常用维护命令6.1 退出 Hermes终端执行CtrlC即可退出交互界面返回 Ubuntu 命令行。6.2 环境自检必做检查配置完整性、依赖缺失、接口连通性bash运行hermes doctor提示可自动修复时执行bash运行hermes doctor --fix6.3 重新配置需修改模型接口、补充消息服务时重启配置向导bash运行hermes setup6.4 查看运行面板监控 Hermes 运行日志、配置信息、技能状态bash运行hermes dashboard6.5 版本更新升级至最新版 Hermes获取新技能与功能bash运行hermes update七、总结Windows 部署 Hermes 核心要点WSL2 是基础系统版本、虚拟机功能、内核更新包缺一不可重启步骤不能省Ubuntu 必须 WSL2旧版本及时转换避免兼容问题模型配置要精准接口地址、密钥、模型名称严格按平台填写切勿自定义命名先自检再使用部署后用hermes doctor排查问题减少后续报错。整体而言Hermes 安装脚本成熟稳定Windows 用户的核心难点集中在WSL2 环境搭建。只要打通 Windows 到 Linux 的过渡环节后续安装、配置、维护都能高效完成轻松拥有本地可执行的 AI 智能体。