windows用户必须通过wsl2部署hermes agent，因其原生依赖linux内核特性，原生powershell/cmd仅支持轻量验证；跳过wsl2直接安装将导致90%报错。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
你在Win10/11上执行安装命令后，终端突然卡住、报错“hermes: command not found”、提示Python版本不兼容，或者配置完火山引擎却始终返回401认证失败——这些不是你操作错了，而是Hermes Agent在Windows生态下存在明确的路径限制与环境陷阱。
先确认你是否真的该在原生Windows装
官方文档明确声明：For Windows users, WSL2 is the only supported installation method。原生PowerShell或CMD安装仅用于轻量验证，【所有正式使用场景必须走WSL2】。如果你跳过这步直接在PowerShell里敲install.sh，后续90%的报错都源于此前提错误。
验证方式：打开PowerShell，运行 wsl -l -v。若无输出或显示“WSL未安装”，立刻停手，先完成WSL2部署。
WSL2安装阶段高频报错修复
方法一：一键启用失败（常见于Win10旧版或企业版）
以管理员身份打开PowerShell，逐行执行：
wsl --install
shutdown /r /t 5
重启后若仍提示“wsl命令不存在”，手动启用虚拟机平台与Windows子系统功能：
Enable-WindowsOptionalFeature -Online -FeatureName VirtualMachinePlatform -NoRestart
Enable-WindowsOptionalFeature -Online -FeatureName Microsoft-Windows-Subsystem-Linux -NoRestart
重启电脑
方法二：Ubuntu初始化卡在用户名输入
WSL首次启动要求创建Linux用户，【用户名不能以数字开头，也不能含大写字母或特殊符号】。输入7455、User66、ADMIN都会失败；正确示例：ubuntu、devuser、a123。
密码输入时屏幕无回显，这是Linux标准行为，正常输入两次即可。
安装脚本执行阶段排错
第一步：区分终端类型
在WSL2 Ubuntu终端中运行，不要用Git Bash或Windows Terminal的PowerShell标签页。终端提示符应为 ubuntu@DESKTOP-XXX:~$ 形式。
第二步：补全系统依赖（Ubuntu 24.04必做）
官方install.sh在新发行版中可能漏装 ripgrep 和 ffmpeg：
sudo apt update && sudo apt install -y ripgrep ffmpeg
第三步：修复“hermes: command not found”
安装完成后，执行 source ~/.bashrc（bash用户）或 source ~/.zshrc（zsh用户）。若仍无效，检查可执行文件路径：
ls ~/.local/bin/hermes
如存在，手动加入PATH：
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc
API认证类报错直击根因
① HTTP 401 Invalid API key（火山引擎/通义千问通用）
根本原因不是密钥写错，而是Hermes强制使用国际版接口地址。国内密钥必须配合国内域名，且config.yaml中api_key字段必须顶格、无空格、无引号包裹。
② AuthenticationError: Invalid API key（通义千问）
DashScope密钥需搭配国内接口：https://dashscope.aliyuncs.com/api/v1/services/aigc/text-generation/generation。若误填国际版 https://dashscope-intl.aliyuncs.com，必然401。
③ model provider not found
执行 hermes model 后无可用模型列表，说明config.yaml未被识别。检查文件路径是否为 ~/.hermes/config.yaml，注意.hermes是隐藏文件夹，需在文件管理器地址栏手动输入 C:\Users\你的用户名\.hermes 才可见。
快速诊断三连击
遇到任何异常，立即按顺序执行：
hermes --version → 验证命令是否注册成功
hermes doctor → 检查环境依赖与配置文件读取状态
hermes config show → 确认model、api_key、base_url三项是否完整输出
只要 doctor 无红色ERROR，且 config show 能打印出你填入的火山引擎API Key，就代表核心链路已通。
