Hermes Agent安装说明

一、文档背景与通用说明文档来源Hermes Agent中文社区网址https://hermesagent.org.cn提供263篇中文文档全文检索。社区支持可通过中文社区微信群提问或使用已安装的龙虾OpenClaw如QClaw、WorkBuddy、ArkClaw、AutoClaw自动阅读文档协助配置。方式一将社区网址发给Agent让其自主阅读。方式二推荐复制特定指令给Agent完成配置后即可按关键词检索文档。核心原则Windows上的安装命令与类Linux/macOS不同必须区分。辅助AI工具安装中遇问题可先询问豆包、DeepSeek等AI助手。二、基础概念与操作1. 什么是PowerShellWindows自带的命令行程序相当于“终端”。可输入命令、安装软件、运行脚本。常用别名命令行、终端、Shell、PowerShell。重点文档中所有“PowerShell命令”需粘贴到PowerShell窗口中执行不能粘到浏览器地址栏、文件资源管理器、运行对话框或Word/记事本中。2. 如何打开PowerShell按键盘左下角Win键 → 输入“PowerShell” → 点击“Windows PowerShell”或“PowerShell”。也可使用Windows Terminal但需确认当前标签页是PowerShell。粘贴方法CtrlV最常用若无效右键点击窗口即可粘贴Windows Terminal支持CtrlShiftV。执行粘贴后按Enter键开始执行命令。3. 何时需要管理员权限安装WSL2通常需要“以管理员身份运行”PowerShell右击PowerShell选择。直接安装Hermes普通PowerShell即可。三、WSL2路径强烈推荐1. WSL2是什么Windows Subsystem for Linux 2适用于Linux的Windows子系统2。在Windows中提供一个Linux终端环境如Ubuntu无需双系统或手动虚拟机。优势更稳定更接近官方文档适合shell工具链、Python/Node.js依赖、浏览器自动化、Docker/SSH/MCP/网关等扩展。2. 使用场景Windows正常使用仅安装和运行Hermes时打开Ubuntu终端WSL2。Linux安装命令如curl -fsSL https://res1.hermesagent.org.cn/install.sh [原文](context-ref?id19)| bash应在macOS终端、Linux终端或WSL2的Ubuntu终端中执行不是原生PowerShell。3. 安装步骤WSL2路径第一步安装WSL2管理员PowerShell若未装过WSL建议先参考知乎《Windows 10/11 安装WSL2指南》。执行命令wsl --install -d Ubuntu按提示重启电脑重启后打开Ubuntu设置Linux用户名和密码。第二步在WSL2终端中安装Hermes执行Linux安装命令curl -fsSL https://res1.hermesagent.org.cn/install.sh [原文](context-ref?id26)| bash安装完成后重新加载shellsource ~/.bashrc或~/.zshrc验证执行hermes命令。第三步配置模型hermes modelhermes setup4. 网络环境提示使用国内镜像加速精简了部分不常用功能如浏览器自动化、Chromium下载、WhatsApp桥接建议先完成核心安装。若需WSL网络/代理配置可参考WSL安装指南和Microsoft Learn文档Python/pip和Node.js/npm镜像可参考清华TUNA镜像帮助。5. 常见配置WSL2 本地模型若模型跑在Windows主机如Ollama、LM Studio而Hermes在WSL2中需注意localhost不一定直接可用应参考提供商文档中的WSL2网络配置。四、原生PowerShell路径可用但易踩坑1. 适用场景想快速在Windows本机跑通CLI不想先配置WSL2。注意更容易遇到兼容性问题长期使用仍推荐WSL2。2. 一键安装步骤打开PowerShell普通/无需管理员。执行命令irm https://res1.hermesagent.org.cn/install.ps1 [原文](context-ref?id33)| iex安装器自动处理uv、Python 3.11、Node.js、Git、ripgrep/ffmpeg、Hermes本体与虚拟环境。安装完成后关闭并重新打开PowerShell运行hermes和hermes model验证。3. 安装文件位置默认目录%LOCALAPPDATA%\hermes主目录%LOCALAPPDATA%\hermes仓库目录%LOCALAPPDATA%\hermes\hermes-agent虚拟环境%LOCALAPPDATA%\hermes\hermes-agent\venv若hermes命令不可用关闭当前PowerShell窗口重新打开一个新窗口。五、飞书网关配置原生PowerShell路径常见问题1. 标准配置步骤先完成Hermes本体安装再单独配置网关hermes gateway setup在渠道列表中选择飞书国内版填feishu海外版填lark填入App ID、App Secret。连接方式一般用默认的websocket。启动网关hermes gateway run -vv2. 常见报错与修复1lark-oapi未安装使用以下PowerShell命令补装$hermesExe (Get-Command hermes).Source $venvPython Join-Path (Split-Path $hermesExe -Parent) python.exe uv pip install lark-oapi --python $venvPython若还缺websockets或aiohttp同样方式补装。2网关启动闪退WinError 11原因原生Windows中gateway/status.py的os.kill(pid, 0)检查触发WinError 11。解决方案一最省心改走WSL2。解决方案二临时补丁用PowerShell自动定位文件并打补丁将异常捕获从except (ProcessLookupError, PermissionError):改为except (ProcessLookupError, PermissionError, OSError):之后设置环境变量并重新启动$env:PYTHONUTF8 1 hermes gateway run -vv注意此仅为原生Windows临时规避方案。3飞书群里机器人没反应确认飞书开放平台机器人权限和事件订阅已配好网关已启动并看到正常日志。若日志无报错可先将群策略放宽为open开放进行排查恢复正常后再逐步收紧白名单。六、总结与推荐路径以上是对文档主要内容的详尽总结涵盖了概念解释、安装步骤、网络优化、常见问题及解决方案帮助你在Windows上顺利配置和使用Hermes Agent。第一步决定用WSL2还是原生PowerShell。第二步完成安装。第三步用hermes和hermes model验证CLI与模型配置。第四步接入消息网关飞书、微信、Telegram等。附加说明WSL2路径强烈推荐稳定性、工具链兼容性更好。若涉及本地模型、Docker、浏览器自动化等高级功能优先回到WSL2路径。原生PowerShell路径可行但需做好应对兼容性问题的准备如WinError 11、SDK依赖缺失等。