Hermes Agent v0.16.0 桌面应用安装指南：Windows / macOS / Linux 全流程

发布于 2026-06-06 07:32

Hermes Agent v0.16.0 桌面应用安装指南：Windows / macOS / Linux 全流程

Hermes Agent v0.16.0 首次推出了桌面应用（Hermes Desktop App），支持 macOS、Windows 和 Linux 三大平台。本文一步步带你完成每个平台的安装，把可能踩的坑全部标出来。

安装方式总览

Hermes Agent v0.16.0 提供两种安装路径：

方式 适用场景 包含桌面应用
桌面安装器（推荐） macOS / Windows 新手 是
命令行脚本安装 Linux / macOS / WSL2 / 高级用户 否（可后续补装）

如果先装了命令行版，后续想补装桌面应用，运行 hermes desktop 即可。

注意：本文讨论的是 v0.16.0 版本的桌面应用安装。如果你是从旧版本升级到 v0.16.0，请先阅读官方的 Updating 指南，确保配置迁移完成后再安装桌面端。

Windows 安装（桌面应用）

前置条件

  • Windows 10 或 Windows 11
  • 网络能访问 hermes-agent.nousresearch.com（国内访问可能较慢，后文有加速方案）

步骤一：下载安装包

访问 https://hermes-agent.nousresearch.com/desktop，点击 "Windows Download" 按钮。

文件格式为 .exe 安装包，文件名类似 Hermes-Setup-Setup-0.16.0.exe，大小约 150-200MB。

坑点 1：国内下载慢

GitHub Releases 和 Hermes 官网的下载链接在国内访问可能很慢或不稳定。如果下载失败，可以尝试：

  • 使用 GitHub 国内加速镜像（如 https://gh-proxy.com/https://github.com/nousresearch/hermes-agent/releases/download/v0.16.0/...）
  • 使用下载工具（如 IDM）开启多线程下载

步骤二：运行安装包

双击 .exe 文件，按向导提示安装。

安装过程会自动完成以下操作：

  1. 安装 Git（如果没有）
  2. 安装 uv（Python 包管理器）
  3. 安装 Python 3.11
  4. 克隆 Hermes Agent 仓库
  5. 创建 Python 虚拟环境
  6. 安装所有 Python 和 Node.js 依赖
  7. 配置系统 PATH
  8. 创建桌面快捷方式

整个过程 5-10 分钟，取决于网络速度。

坑点 2：杀毒软件误报

部分杀毒软件（尤其是 Windows Defender 的实时防护）可能拦截安装脚本的某些操作。如果安装失败，尝试：

  • 临时关闭 Windows Defender 实时防护
  • 安装完成后重新开启
  • 将安装目录添加到白名单

坑点 3：PowerShell 执行策略

如果手动运行 PowerShell 安装脚本（install.ps1），可能遇到执行策略报错：

cannot be loaded because running scripts is disabled on this system

解决方法（以管理员身份运行 PowerShell）：

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

安装完成后可以改回去：

Set-ExecutionPolicy -ExecutionPolicy Restricted -Scope CurrentUser

步骤三：启动桌面应用

安装完成后，桌面会出现 Hermes 图标。双击启动。

首次启动会进入配置向导，需要选择 AI 模型供应商。推荐选择：

  • Nous Portal：一个订阅覆盖 300+ 模型，包括 Web 搜索、图片生成等工具。在终端运行 hermes setup --portal 完成配置。
  • OpenRouter：多供应商路由，支持大量开源模型。需要 API Key。

坑点 4：首次启动白屏或卡住

如果桌面应用启动后白屏或长时间无响应：

  • 检查 https://hermes-agent.nousresearch.com 是否可访问（国内可能需要代理）
  • 在终端运行 hermes doctor，查看具体错误
  • 尝试重启：hermes gateway restart

步骤四：验证安装

在桌面应用的对话框中输入：你好，请用中文回答：今天的日期是？

如果 Agent 正常回复，说明安装成功。进一步验证工具调用能力：

帮我搜索一下今天的天气

如果 Agent 能调用 Web 搜索工具并返回结果，说明 Tool Gateway 配置正确。

Windows 安装（仅命令行）

如果你不想要桌面应用，只需要命令行：

以管理员身份运行 PowerShell，执行：

iex (irm https://hermes-agent.nousresearch.com/install.ps1)

安装完成后，关闭并重新打开 PowerShell，运行：

hermes --version

如果显示 hermes 0.16.0 或类似版本号，安装成功。

补装桌面应用（任何时候都可以）：

hermes desktop

macOS 安装（桌面应用）

前置条件

  • macOS 12（Monterey）或更高版本
  • 网络能访问 Hermes 官网

步骤一：下载安装包

访问 https://hermes-agent.nousresearch.com/desktop，点击 "Mac OS Download"。

下载文件为 .dmg 格式。

坑点 1：Apple Silicon vs Intel

Mac 有两个芯片版本。通常下载页面会自动识别。如果没有：

  • M1/M2/M3/M4 芯片（Apple Silicon）：选择 ARM64 版本
  • Intel 芯片：选择 x64 版本

如果选错了，安装过程会报错或运行极慢（Rosetta 转译）。

步骤二：安装

  1. 双击打开 .dmg 文件
  2. 将 Hermes 图标拖入 Applications 文件夹
  3. 弹出 .dmg 镜像

坑点 2：macOS 安全拦截

首次打开 macOS 可能会弹出「"无法打开，因为无法验证开发者」：

方法 A（推荐）：

  1. 去 系统设置 → 隐私与安全性
  2. 在安全性区域点击「仍要打开」

方法 B（如果找不到选项）：

# 清除隔离属性
sudo xattr -d com.apple.quarantine /Applications/Hermes\ Desktop.app

坑点 3：命令行工具未加入 PATH

桌面应用安装后，命令行工具 hermes 可能暂时不在 PATH 中。重启终端或执行：

source ~/.zshrc

验证：

which hermes

应该输出 /Users/你的用户名/.local/bin/hermes 或类似路径。

步骤三：选择模型供应商

推荐 Nous Portal（一站式）：

hermes setup --portal

或者手动选择：

hermes model

交互式选择供应商。

步骤四：启动与验证

桌面应用从 Applications 文件夹或 Spotlight 搜索 "Hermes" 启动。

验证步骤同 Windows。

macOS 安装（仅命令行）

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装完成后：

source ~/.zshrc
hermes --version

补装桌面应用：

hermes desktop

Linux 安装

Linux 目前没有独立的桌面安装器 .deb/.rpm/.AppImage，需要通过命令行安装核心组件，然后通过 hermes desktop 启动桌面应用。

前置条件

  • 任何主流发行版（Ubuntu / Debian / Fedora / Arch 等）
  • git 已安装（唯一必须的前置依赖）
# Ubuntu/Debian
sudo apt install git

# Fedora
sudo dnf install git

# Arch
sudo pacman -S git

步骤一：安装 Hermes Agent 核心

curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash

安装脚本会自动处理所有依赖：uv、Python 3.11、Node.js v22、ripgrep、ffmpeg。

安装完成后：

source ~/.bashrc    # 如果用 zsh：source ~/.zshrc
hermes --version

坑点 1：sudo 权限问题

如果你用 sudo 执行安装脚本（sudo curl ... | sudo bash），文件会安装到系统路径：

  • 代码：/usr/local/lib/hermes-agent/
  • 命令：/usr/local/bin/hermes
  • 配置：/root/.hermes/

如果以普通用户安装：

  • 代码：~/.hermes/hermes-agent/
  • 命令：~/.local/bin/hermes
  • 配置：~/.hermes/

建议：个人使用用普通用户安装即可。只有多用户共享机器才考虑 sudo 安装。

坑点 2：~/.local/bin 不在 PATH 中

如果执行 hermes --version 报错 command not found：

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

坑点 3：Playwright 系统依赖（仅浏览器自动化需要）

如果需要使用浏览器自动化工具，Linux 需要额外安装系统库：

# 方法一（有 sudo 权限）
sudo npx playwright install-deps chromium

# 方法二（无 sudo，跳过浏览器功能）
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash -s -- --skip-browser

坑点 4：Arch/Fedora/openSUSE 的特殊处理

这些发行版不支持 Playwright 的 --with-deps 自动安装。安装脚本会打印出需要手动安装的系统库命令，照着执行即可。

例如 Fedora：

sudo dnf install -y atk at-spi2-atk cups-libs libdrm libxkbcommon libXcomposite libXdamage libXfixes libXrandr GConf2 nss gtk3

步骤二：启动桌面应用

hermes desktop

这会下载桌面应用组件并启动 GUI 窗口。

坑点 5：Linux 桌面环境兼容性

桌面应用基于 Electron/Tauri 框架。在以下环境下可能遇到问题：

  • Wayland 显示协议：如果桌面启动后窗口空白，尝试设置环境变量：

    WEBKIT_DISABLE_COMPOSITING_MODE=1 hermes desktop

  • 无显示器（纯 CLI 服务器）：桌面应用需要图形界面。如果你在远程 SSH 服务器上，需要：

    • X11 转发：ssh -X user@host
    • 或 VNC 远程桌面
    • 或者直接用命令行版本：hermes

  • 缺失 libsecret（密钥管理）：

    # Ubuntu/Debian
sudo apt install libsecret-1-dev

# Fedora
sudo dnf install libsecret-devel

步骤三：选择 Nous Portal 或 API Key

# 推荐：Nous Portal 一站式配置
hermes setup --portal

# 或手动配置供应商
hermes model

WSL2 安装

WSL2 使用 Linux 安装方式：

# 在 WSL2 Ubuntu 中
curl -fsSL https://hermes-agent.nousresearch.com/install.sh | bash
source ~/.bashrc
hermes --version

桌面应用：

hermes desktop

坑点：WSL2 图形界面

WSL2 本身没有图形界面。运行 hermes desktop 需要：

  • WSLg（Windows 11 内置）：直接运行，窗口会自动显示在 Windows 桌面上
  • Windows 10 或未启用 WSLg：需要安装第三方 X Server（如 VcXsrv），或改用命令行版本

验证 WSLg 是否可用：

echo $DISPLAY

如果输出类似 :0 或包含 .0，WSLg 已启用。如果为空，需要配置 X Server。

安装后必做：配置模型供应商

不管哪个平台，安装完成后必须配置至少一个模型供应商，否则 Agent 无法运行。

最快路径：Nous Portal

Nous Portal 是 Hermes 官方订阅服务，一个账号覆盖 300+ 模型，包含 Web 搜索、图片生成、TTS 等工具。

hermes setup --portal

其他常见选择

供应商 特点 配置方式
OpenRouter 多供应商路由，大量开源模型 hermes model → 输入 API Key
Anthropic Claude 模型，能力顶尖 API Key 或 Max 订阅 OAuth
Google AI Studio Gemini 免费额度大 GOOGLE_API_KEY=xxx
DeepSeek 国产模型，性价比高 DEEPSEEK_API_KEY=xxx
阿里百炼 Qwen 系列，国内接入稳定 DASHSCOPE_API_KEY=xxx
Ollama 本地运行开源模型 OLLAMA_BASE_URL=http://localhost:11434

重要：Hermes Agent 要求模型上下文窗口至少 64K tokens。选择模型时注意。

通用排查流程

安装遇到问题，按这个顺序排查：

# 1. 检查版本
hermes --version

# 2. 运行诊断
hermes doctor

# 3. 检查配置
hermes config check

# 4. 检查 gateway 状态
hermes gateway status

# 5. 查看详细日志
hermes gateway logs

hermes doctor 是最重要的诊断命令，它会告诉你缺少什么、配置有什么问题、怎么修复。

各平台常见问题速查

问题 Windows macOS Linux
命令行找不到 hermes 重装后重启终端 source ~/.zshrc source ~/.bashrc
API Key 未配置 hermes model hermes model hermes model
桌面应用白屏 检查网络/代理 检查网络/代理 检查 $DISPLAY / WSLg
无法更新 hermes update hermes update hermes update
配置迁移 hermes config migrate hermes config migrate hermes config migrate
浏览器自动化报错 — — sudo npx playwright install-deps chromium

总结

新手推荐路径：

  • Windows：下载 .exe 桌面安装器，一路 Next
  • macOS：下载 .dmg，拖入 Applications
  • Linux：命令行安装 + hermes desktop
  • 所有平台：安装完成后 hermes setup --portal 配置模型

核心原则：先用 hermes doctor 确认一切正常，再开始日常使用。如果 hermes doctor 报错，先修问题再继续，不要跳过。

如果你觉得本文有用，请点赞，收藏和转发。

← 返回博客列表
文章信息

标题: Hermes Agent v0.16.0 桌面应用安装指南：Windows / macOS / Linux 全流程

发布时间: 2026-06-06 07:32