Hermes Desktop macOS 安装与排障教程

张

张建站

2026/6/2 6:00:14

10分钟阅读

尝试了hermes cli之后,了解到有桌面版的, 就从github下载https://github.com/fathah/hermes-desktop/releases, 结果一直安装不成功,本文记录一次在 macOS 上安装 Hermes Desktop 的完整流程、常见卡点和修复方法。适用场景下载并安装hermes-desktop-0.5.2-arm64.dmg首次启动后聊天窗口一直卡住http://127.0.0.1:8642/health无响应安装器卡在Trying SSH clone...聊天时报401 User not found1. 组件关系Hermes Desktop 不是完整后端它主要是桌面壳。正常工作链路是Hermes Desktop - 本地 Hermes Agent - 本地 gateway/API server - http://127.0.0.1:8642 - OpenRouter/OpenAI/其他模型供应商关键路径/Applications/Hermes Agent.app /Users/an/.hermes /Users/an/.hermes/hermes-agent /Users/an/.hermes/.env /Users/an/.hermes/config.yaml /Users/an/.hermes/logs/gateway.log /Users/an/Library/LaunchAgents/ai.hermes.gateway.plist其中/Applications/Hermes Agent.app是桌面端 App。~/.hermes/hermes-agent是真正的 Python agent 源码和虚拟环境。~/.hermes/.env保存模型 API key、本地 API server token 等。~/.hermes/config.yaml保存模型、gateway、端口等配置。127.0.0.1:8642是 Desktop 和本地 gateway 通信的 HTTP API。2. 正常安装流程下载 macOS Apple Silicon 版本hermes-desktop-0.5.2-arm64.dmg安装后打开/Applications/Hermes Agent.app首次启动时Desktop 会尝试安装 Hermes Agent 到/Users/an/.hermes/hermes-agent安装成功后本地健康检查应该返回curl -s -D - --max-time 5 http://127.0.0.1:8642/health正常结果HTTP/1.1 200 OK {status: ok, platform: hermes-agent}3. 判断是否安装失败检查 agent 目录ls -la /Users/an/.hermes/hermes-agent正常目录应该包含类似文件pyproject.toml uv.lock README.md hermes hermes_cli/ agent/ gateway/ venv/如果只看到.git venv .DS_Store并且 Git 状态是git -C /Users/an/.hermes/hermes-agent status --short --branch输出类似## No commits yet on main说明 agent 没有安装完整。再检查 gatewaycurl -s -D - --max-time 5 http://127.0.0.1:8642/health如果连接失败Desktop 聊天窗口就会卡住。4. 卡在 Trying SSH clone 的原因安装器会先尝试 SSH clonegitgithub.com:NousResearch/hermes-agent.git如果 GitHub SSH key 没配置好、网络不稳定、代理链路中断就可能卡在Trying SSH clone...此时常见残留/Users/an/.hermes/hermes-agent/.git/objects/pack/tmp_pack_*这表示 Git 下载或解包中断。5. 修复方式 A重新安装 agent先退出 Hermes Desktop。如果当前hermes-agent是半安装状态可以先备份cd /Users/an/.hermes mv hermes-agent hermes-agent.broken然后用官方安装脚本curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash -s -- --skip-setup如果又卡在 SSH clone可以改用下面的 tarball 方式。6. 修复方式 B绕过 SSH用 tarball 安装当 SSH clone 和 HTTPS git clone 都不稳定时可以直接下载源码压缩包。下载curl --http1.1 -L --fail --connect-timeout 10 --retry 5 --retry-all-errors --retry-delay 5 \ -o /private/tmp/hermes-agent-main.tar.gz \ https://codeload.github.com/NousResearch/hermes-agent/tar.gz/refs/heads/main解压tar -xzf /private/tmp/hermes-agent-main.tar.gz -C /Users/an/.hermes mv /Users/an/.hermes/hermes-agent-main /Users/an/.hermes/hermes-agent如果已经存在旧目录先移动旧目录mv /Users/an/.hermes/hermes-agent /Users/an/.hermes/hermes-agent.broken注意tarball 安装没有.git历史能正常运行但以后hermes update可能不如标准 git clone 顺滑。7. 创建 Python venv推荐使用 Python 3.11 或 3.12不建议使用过新的 Python 3.14。本机示例使用/opt/anaconda3/bin/python --version如果是 Python 3.12cd /Users/an/.hermes/hermes-agent /opt/anaconda3/bin/python -m venv venv确认/Users/an/.hermes/hermes-agent/venv/bin/python --version应该看到Python 3.12.x升级基础安装工具/Users/an/.hermes/hermes-agent/venv/bin/python -m pip install --upgrade pip setuptools wheel安装 Hermes Agentcd /Users/an/.hermes/hermes-agent /Users/an/.hermes/hermes-agent/venv/bin/python -m pip install -e .[all]验证 CLI/Users/an/.hermes/hermes-agent/venv/bin/hermes --help正常情况下会显示chat、gateway、setup、doctor等命令。8. 配置本地 API server token如果 gateway 日志出现API_SERVER_KEY is required for the API server需要生成本地 tokenopenssl rand -hex 32假设生成结果是your_random_token_here写入~/.hermes/.envprintf \nAPI_SERVER_KEYyour_random_token_here\n /Users/an/.hermes/.env写入~/.hermes/config.yamlapi_server: token: your_random_token_here注意不要把真实 token 发到公开位置。9. 启动 gateway前台验证/Users/an/.hermes/hermes-agent/venv/bin/hermes gateway run另开终端测试curl -s -D - --max-time 5 http://127.0.0.1:8642/health正常结果HTTP/1.1 200 OK {status: ok, platform: hermes-agent}安装成 macOS 用户后台服务/Users/an/.hermes/hermes-agent/venv/bin/hermes gateway install /Users/an/.hermes/hermes-agent/venv/bin/hermes gateway start检查监听lsof -nP -iTCP:8642 -sTCP:LISTEN正常会看到 Python 进程监听TCP 127.0.0.1:8642 (LISTEN)日志路径tail -f /Users/an/.hermes/logs/gateway.log10. 修复后仍报 401 User not found如果聊天窗口不再卡住但返回Error code: 401 - {error: {message: User not found., code: 401}}这通常不是本地 gateway 问题而是模型供应商鉴权问题。本次日志显示Provider: openrouter Model: deepseek/deepseek-chat Endpoint: https://openrouter.ai/api/v1 HTTP 401: User not found.检查当前模型配置sed -n 1,80p /Users/an/.hermes/config.yaml示例model: base_url: https://openrouter.ai/api/v1 default: deepseek/deepseek-chat provider: auto检查.env中是否有 OpenRouter keygrep -n OPENROUTER_API_KEY /Users/an/.hermes/.env不要打印完整 key只确认是否存在。可以用一个最小请求验证 OpenRouter key/Users/an/.hermes/hermes-agent/venv/bin/python - PY from pathlib import Path import httpx vals {} for line in Path(/Users/an/.hermes/.env).read_text().splitlines(): if in line and not line.strip().startswith(#): k, v line.split(, 1) vals[k.strip()] v.strip().strip().strip() key vals.get(OPENROUTER_API_KEY, ) print(OPENROUTER_API_KEY present:, bool(key), length:, len(key), prefix:, key[:8] ... if key else ) if key: r httpx.get( https://openrouter.ai/api/v1/models, headers{Authorization: Bearer key}, timeout15, ) print(models status:, r.status_code) print(r.text[:300] if r.status_code ! 200 else models ok) PY再测 chat/Users/an/.hermes/hermes-agent/venv/bin/python - PY from pathlib import Path import httpx vals {} for line in Path(/Users/an/.hermes/.env).read_text().splitlines(): if in line and not line.strip().startswith(#): k, v line.split(, 1) vals[k.strip()] v.strip().strip().strip() key vals[OPENROUTER_API_KEY] payload { model: deepseek/deepseek-chat, messages: [{role: user, content: hello}], max_tokens: 8, } r httpx.post( https://openrouter.ai/api/v1/chat/completions, headers{ Authorization: Bearer key, Content-Type: application/json, HTTP-Referer: http://localhost, X-Title: Hermes local test, }, jsonpayload, timeout30, ) print(chat status:, r.status_code) print(r.text[:500]) PY常见结果200key 和模型都正常。401 User not foundkey、账号或 Hermes 实际读取的 key 有问题。402 Insufficient creditsOpenRouter key 有效但账号没有余额。如果是402需要到 OpenRouter 充值https://openrouter.ai/settings/credits如果直接测试是402但 Hermes 里是401说明 Hermes 可能读到了另一个 key例如CUSTOM_API_KEY OPENAI_API_KEY OPENROUTER_API_KEY建议把不使用的干扰 key 暂时移除或重命名只保留当前 provider 需要的 key。11. 常用诊断命令查看 agent 目录ls -la /Users/an/.hermes/hermes-agent查看 gateway 日志tail -160 /Users/an/.hermes/logs/gateway.log查看 agent 错误tail -160 /Users/an/.hermes/logs/agent.log tail -120 /Users/an/.hermes/logs/errors.log检查 8642lsof -nP -iTCP:8642 -sTCP:LISTEN curl -s -D - --max-time 5 http://127.0.0.1:8642/health检查 Hermes CLI/Users/an/.hermes/hermes-agent/venv/bin/hermes --help /Users/an/.hermes/hermes-agent/venv/bin/hermes gateway --help12. 可删除的安装残留排障过程中可能出现这些失败残留/Users/an/.hermes/hermes-agent.broken /Users/an/.hermes/hermes-agent.ssh-stuck /private/tmp/hermes-agent-main.tar.gz /private/tmp/hermes-agent-main.tar.gz.partial /private/tmp/hermes-agent-main.tar.gz.http2-cancel确认当前有效目录存在du -sh /Users/an/.hermes/hermes-agent确认后再删除残留rm -rf /Users/an/.hermes/hermes-agent.broken rm -rf /Users/an/.hermes/hermes-agent.ssh-stuck rm -f /private/tmp/hermes-agent-main.tar.gz rm -f /private/tmp/hermes-agent-main.tar.gz.partial rm -f /private/tmp/hermes-agent-main.tar.gz.http2-cancel不要删除/Users/an/.hermes/hermes-agent /Users/an/.hermes/.env /Users/an/.hermes/config.yaml13. 本次实际结论本次安装卡住的根因分为三层hermes-agent没有完整安装。表现~/.hermes/hermes-agent只有空 Git 仓库和 venv。修复绕过 SSH clone用 tarball 恢复源码。gateway 缺少API_SERVER_KEY。表现127.0.0.1:8642/health无响应日志提示 API server 拒绝启动。修复生成 token写入.env和config.yaml。模型供应商鉴权或余额问题。表现聊天时报401 User not found。进一步测试OpenRouter/models正常但 chat 可能返回402 Insufficient credits。修复方向确认 Hermes 实际读取的 key或给 OpenRouter 账号充值。最终本地 gateway 验证结果HTTP/1.1 200 OK {status: ok, platform: hermes-agent}