Hermes Desktop macOS 安装与排障教程

尝试了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 found

1. 组件关系

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 没有安装完整。

再检查 gateway：

curl -s -D - --max-time 5 http://127.0.0.1:8642/health

如果连接失败，Desktop 聊天窗口就会卡住。

4. 卡在 Trying SSH clone 的原因

安装器会先尝试 SSH clone：

git@github.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.12：

cd /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 Agent：

cd /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

需要生成本地 token：

openssl rand -hex 32

假设生成结果是：

your_random_token_here

写入~/.hermes/.env：

printf '\nAPI_SERVER_KEY=your_random_token_here\n' >> /Users/an/.hermes/.env

写入~/.hermes/config.yaml：

api_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.log

10. 修复后仍报 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 key：

grep -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}, timeout=15, ) 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", }, json=payload, timeout=30, ) print("chat status:", r.status_code) print(r.text[:500]) PY

常见结果：

• 200：key 和模型都正常。

• 401 User not found：key、账号或 Hermes 实际读取的 key 有问题。

• 402 Insufficient credits：OpenRouter 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

检查 8642：

lsof -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 --help

12. 可删除的安装残留

排障过程中可能出现这些失败残留：

/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.yaml

13. 本次实际结论

本次安装卡住的根因分为三层：

1. hermes-agent没有完整安装。

   • 表现：~/.hermes/hermes-agent只有空 Git 仓库和 venv。

   • 修复：绕过 SSH clone，用 tarball 恢复源码。

2. gateway 缺少API_SERVER_KEY。

   • 表现：127.0.0.1:8642/health无响应，日志提示 API server 拒绝启动。

   • 修复：生成 token，写入.env和config.yaml。

3. 模型供应商鉴权或余额问题。

   • 表现：聊天时报401 User not found。

   • 进一步测试：OpenRouter/models正常，但 chat 可能返回402 Insufficient credits。

   • 修复方向：确认 Hermes 实际读取的 key，或给 OpenRouter 账号充值。

最终本地 gateway 验证结果：

HTTP/1.1 200 OK {"status": "ok", "platform": "hermes-agent"}