Hermes Desktop macOS 安装与排障教程

csdnor_012026-06-02 8:17

尝试了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"}
相关推荐
一个人旅程～2 小时前
MacBook Pro安装Win11 IoT LTSC 2024的两种方法操作说明
windows·经验分享·macos·电脑
cmdyu_19 小时前
mac上如何卸载node.js
macos·node.js
黑化旺仔21 小时前
【OC】PHPickerViewController
macos·objective-c·cocoa
AI行业学习1 天前
CC-Switch 下载、安装windows\macOS \Linux 安装
linux·运维·macos
一个人旅程～1 天前
完整精华版macbookHighSierra 至Montere-Ventyra版本跨越评估与避坑指南（含证书有效期）
windows·经验分享·macos·电脑
秋雨梧桐叶落莳1 天前
iOS——抽屉视图详解
开发语言·macos·ui·ios·objective-c·cocoa
pumpkin845141 天前
Mac Studio M4 Max 纯本地化部署 Qwen 3.6 并桥接 Claude Code 实践指南
macos
hurrycry_小亦2 天前
苹果WWDC 2026前瞻：Ferret-Pro端侧大模型即将亮相｜小亦之闻｜AI 编程三日速递！（5月26日～5月28日）
macos·ios·wwdc
搬砖的小码农_Sky2 天前
macOS Sequoia OpenClaw + Ollama 本地离线部署（免API、Apple Silicon金属加速）
人工智能·macos·ai·人机交互
热门推荐
01GitHub 镜像站点02【AI】2026 年具身智能模型和世界模型总结032026 年 AI 编程工具终极横评：Cursor vs Claude Code vs Copilot vs Windsurf04【踩坑记录 | 第一篇】微软商店无法使用时，如何手动安装 OpenAI Codex？附`.msix`文件系统错误解决方法05Codex 下载安装指南：Windows 和 macOS 官方版下载06CC-Switch & Claude 基于 Linux 服务器安装使用指南07Codex 接入 DeepSeek API 完整配置文档08裂开！ChatGPT 居然开始要手机号验证，附详细解决方法09几个好用的ip纯净度检测网站10DeepSeek V4 + Claude Code thinking mode 400 错误修复方案