Hermes Agent 免费安装与配置最全避坑指南【防割韭菜】

先说几个核心判断：零成本部署 Hermes Agent 这件事，技术门槛其实不高，但坑是真不少。尤其是最新版本的文档里，有三类硬伤根本没写透——网络劫持导致脚本中断、PATH 没刷新造成命令失效、API Key 粘贴时无回显让你误以为配置无效。这三个坎过不去，后续所有操作都是白费功夫。

想零成本部署 Hermes Agent，却被 pip install hermes-agent 卡死在 401 错误，被 command not found 反复打脸，被 WSL2 权限和 macOS 开发者警告拦在门外？问题的根源往往不是你不会装，而是没避开那三类隐蔽的硬坑。

选对安装命令，绕开第一道墙

先泼一盆冷水：别迷信网上那些五花八门的 pip 命令。v0.14.0 版本已经明确弃用了 PyPI 上的旧版包，

。正确做法是根据你的系统类型选择对应命令：

执行：curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash
这条命令走的是国内镜像源直连，跳过了 GitHub 被墙的环节，自动帮你装好 uv、Python 3.11、Node.js v22、ffmpeg 全套依赖。

以管理员身份打开 PowerShell，执行：irm https://res1.hermesagent.org.cn/install.ps1 | iex

先执行 pkg install git curl，再运行 Linux 同款镜像命令：curl -fsSL https://res1.hermesagent.org.cn/install.sh | bash

安装后立刻验证，别等配置完才翻车

脚本执行完毕不等于能用。立刻运行以下三步验证链：

输入 which hermes，应返回 ~/.local/bin/hermes（Linux/macOS）或 %LOCALAPPDATA%hermesbinhermes.exe（Windows）。若为空，说明 PATH 未生效。

Linux/macOS 执行：source ~/.bashrc 或 source ~/.zshrc；Windows PowerShell 关闭重开——。

输入 hermes doctor，看到 ✅ Python 3.11.x、✅ Hermes CLI installed、✅ Core dependencies OK 三行绿色标记才算通过。若报 “Browser tools not configured”，可忽略；若报 “AuthenticationError”，说明还没配 API Key，属正常。

配置模型与 API Key 的真实操作路径

别信“hermes setup 一路回车就行”的误导。真实流程中，有两个关键节点必须手动干预：

运行 hermes setup，光标停在 “Select Provider” 时，用方向键上下移动，（仅按回车无效），选中 “Kimi” 后回车进入下一步。

终端出现锁形图标并提示 “Enter your API key” 后，直接 Ctrl+V 粘贴——。粘贴完立刻按回车，系统会自动校验并写入 ~/.hermes/.env。

运行 hermes model ping，返回 “Model responded successfully” 即成功。若仍报 401，请检查 ~/.hermes/.env 文件里是否多出空格或换行符，手动删净再试。

实战前必做的权限与目录隔离

新手最容易犯的致命错误：在根目录或项目主目录下直接运行 hermes。Hermes 默认会扫描当前目录及子目录所有文件，一旦误触系统配置、Git 仓库或敏感文档，可能触发不可逆读写。

①

执行：mkdir -p ~/hermes-workspace && cd ~/hermes-workspace

②

新建一个测试文件：echo "今天要完成会议纪要整理和邮件草稿" > sample.txt

③

运行：hermes --working-dir .
这一步强制 Hermes 只读取当前目录下的 sample.txt，不向上穿透、不扫描隐藏文件、不访问家目录其他内容。

④

在 TUI 界面中输入：请从 sample.txt 中提取待办事项，并生成三条可执行任务
避免模糊表述如“帮我看看这个文件”，否则 agent 可能调用浏览器工具或尝试联网搜索。