Hermes Agent 安装与配置完全指南：多平台部署专属 AI 助手

macOS 安装教程

系统要求

第一步：安装 Homebrew（如果未安装）

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

验证安装：

brew --version   # 应显示 4.x+

第二步：安装基础工具

brew install git curl

验证安装：

git --version   # 应显示 2.x+
curl --version  # 应显示 7.x+

第三步：一键安装 Hermes

官方源（默认，国际用户推荐）：

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

国内镜像（官方源慢时再用）：

curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

【注意】 镜像只代理「下载脚本」这一步，代理不了脚本内部的 uv / Node.js 下载。2026-09 实测：官方源 hermes-agent.nousresearch.com 在国内 0.4 秒即可拿到脚本，反而旧文推荐的 ghfast.top 已返回 403 Forbidden by black list；且 curl | bash 管道下即使下载失败也会返回 0，让人误以为装好了。建议先 curl -o install.sh 落盘、肉眼确认是 shell 脚本再执行。

安装器会自动处理所有依赖（Python 3.11、Node.js、ripgrep、ffmpeg）。

第四步：验证安装

hermes --version

应显示版本号，如 hermes v0.21.5（版本迭代较快，以你实际看到的为准）。

如果提示 command not found：手动配置 PATH 后重试：

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

使用 Bash 的用户将 ~/.zshrc 替换为 ~/.bashrc。

第五步：配置 AI 模型

hermes model

按向导提示：

• 选择模型提供商（如 MiMo、DeepSeek、minimax 等）
• 输入对应的 API Key

如果后续需要更换模型，再次执行 hermes model 即可。

第六步：配置飞书消息通道

方式一：扫码配对（推荐）

hermes gateway setup

在向导中选择 飞书 / Lark，然后选择 扫码创建（推荐），用手机飞书扫码授权即可。Hermes 会自动创建机器人应用并配置好所有权限。

【提示】 飞书 SDK（lark-oapi）不需要手动安装：官方安装器建的虚拟环境里没有 pip，手动装必然失败；依赖由 gateway 首次启动时自动装上（日志会出现 Platform 'Feishu / Lark' dependencies missing — attempting install...，随后 完成： feishu connected）。

方式二：手动配置（备选）

如果扫码失败（如无管理员权限），改为手动模式：

1. 在飞书开放平台创建应用，获取 App ID 和 App Secret
2. 执行网关配置向导：

hermes gateway setup

1. 在平台列表里选择 Feishu / Lark，再选手动输入，依次粘贴 App ID、App Secret
2. 连接方式选 WebSocket（推荐，无需公网地址）；域选 feishu（国内版）
3. DM 授权方式选 配对审批（推荐），群聊策略选 仅 @ 机器人时响应（推荐）

第七步：安装并启动 Gateway 服务

hermes gateway install

这一条命令会同时完成：写入 ~/Library/LaunchAgents/ai.hermes.gateway.plist、设置登录时自启、并立即启动网关。

查看运行状态：

hermes gateway status

【注意】 不要用 launchctl load 手动加载 plist：文件名是 ai.hermes.gateway.plist（不是 com.hermes.gateway.plist），且 launchctl load 已是废弃写法，由 hermes gateway install 托管即可。

日常管理用 hermes gateway start / stop / restart / status。

第八步：测试飞书机器人

1. 打开飞书 App，搜索你的机器人名称
2. 发送一条消息（如 你好）

如果使用扫码方式，授权即完成身份绑定，机器人应直接回复。

如果使用手动配置方式，第一次发消息时需要批准配对码：

hermes pairing list                       # 查看待批准的配对请求（不带平台参数）
hermes pairing approve feishu <配对码>     # 批准

【提示】 批准立即生效、无需重启 gateway，下一条消息就会被正常受理（实测：批准后 2 秒内发出的消息即被响应）。

运行诊断（可选）

hermes doctor

检查安装和配置是否完整。

Windows 安装教程

系统要求

第一步：安装 Git

以管理员身份打开 PowerShell，安装 Git：

winget install Git.Git

安装完成后关闭并重新打开 PowerShell，验证：

git --version   # 应显示 2.x+

第二步：安装 Hermes

以管理员身份打开 PowerShell，执行官方安装脚本：

官方源（默认，国际用户推荐）：

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

国内镜像（官方源慢时再用）：

iex (irm https://ghproxy.net/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.ps1)

【注意】 镜像只代理「下载脚本」这一步。2026-09 实测 ghfast.top 已返回 403，改用 ghproxy.net；irm | iex 管道下即使下载失败也可能不报错，建议先 irm -OutFile install.ps1 落盘确认再执行。

安装器会自动处理所有依赖（Python 3.11、Node.js、ripgrep、ffmpeg）。

第三步：验证安装

hermes --version

应显示版本号，如 hermes v0.21.5（版本迭代较快，以你实际看到的为准）。

如果提示 command not found：重启 PowerShell 终端，或手动添加 PATH：

# 将 %USERPROFILE%\.local\bin 添加到用户 PATH
[Environment]::SetEnvironmentVariable("Path", $env:Path + ";$env:USERPROFILE\.local\bin", "User")
# 重启终端后生效

第四步：配置 AI 模型

hermes model

按向导提示：

• 选择模型提供商（如 MiMo、DeepSeek、minimax 等）
• 输入对应的 API Key

如果后续需要更换模型，再次执行 hermes model 即可。

第五步：配置飞书消息通道

方式一：扫码配对（推荐）

hermes gateway setup

在向导中选择 飞书 / Lark，然后选择 扫码创建（推荐），用手机飞书扫码授权即可。Hermes 会自动创建机器人应用并配置好所有权限。

【提示】 飞书 SDK 不需要手动安装，由 gateway 首次启动时自动装好。

方式二：手动配置（备选）

如果扫码失败（如无管理员权限），改为手动模式：

1. 在飞书开放平台创建应用，获取 App ID 和 App Secret
2. 执行网关配置向导：

hermes gateway setup

1. 在平台列表里选择 Feishu / Lark，再选手动输入，依次粘贴 App ID、App Secret
2. 连接方式选 WebSocket（推荐）；域选 feishu
3. DM 授权方式选 配对审批（推荐），群聊策略选 仅 @ 机器人时响应（推荐）

第六步：安装并启动 Gateway 服务

hermes gateway install

这一条命令会同时完成：注册计划任务、设置开机自启、并立即启动网关。

查看运行状态：

hermes gateway status   # 应显示 Gateway process running (PID: xxxx)

【注意】 不能跳过 install 直接 hermes gateway start：没装服务时它会以退出码 1 结束并提示 未完成： Gateway service is not installed。

日常管理用 hermes gateway start / stop / restart / status。

第七步：测试飞书机器人

1. 打开飞书 App，搜索你的机器人名称
2. 发送一条消息（如 你好）

如果使用扫码方式，授权即完成身份绑定，机器人应直接回复。

如果使用手动配置方式，第一次发消息时需要批准配对码：

hermes pairing list                       # 查看待批准的配对请求（不带平台参数）
hermes pairing approve feishu <配对码>     # 批准

【提示】 批准立即生效、无需重启 gateway。

运行诊断（可选）

hermes doctor

检查安装和配置是否完整。

Linux 安装教程（Ubuntu / Debian）

系统要求

第一步：安装基础工具

sudo apt update
sudo apt install -y git curl xz-utils build-essential

验证安装：

git --version   # 应显示 2.x+
curl --version  # 应显示 7.x+
xz --version    # 应显示 5.x+
g++ --version   # 应显示 11 或更高

【注意】 build-essential 不要省。实测在一台没装编译器的干净 Ubuntu 上，官方安装器只打印几行 【注意】 Could not install a C++ compiler automatically 就继续走，然后在编译 node-pty 时报 not found: make 直接退出——整个过程没有任何一句「安装失败」，最后 hermes 命令也不存在。装上 build-essential 是唯一解。

第二步：一键安装 Hermes

官方源（默认，国际用户推荐）：

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

国内镜像（官方源慢时再用）：

curl -fsSL https://ghproxy.net/https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

【注意】 镜像只代理「下载脚本」这一步，代理不了脚本内部的 uv / Node.js 下载。2026-09 实测：官方源 hermes-agent.nousresearch.com 在国内 0.4 秒即可拿到脚本，反而旧文推荐的 ghfast.top 已返回 403 Forbidden by black list；且 curl | bash 管道下即使下载失败也会返回 0，让人误以为装好了。建议先 curl -o install.sh 落盘、肉眼确认是 shell 脚本再执行。

安装器会自动处理所有依赖（Python 3.11、Node.js、ripgrep、ffmpeg）。

第三步：验证安装

hermes --version

应显示版本号，如 hermes v0.21.5（版本迭代较快，以你实际看到的为准）。

如果提示 command not found：手动配置 PATH 后重试：

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

使用 Zsh 的用户将 ~/.bashrc 替换为 ~/.zshrc。

第四步：配置 AI 模型

hermes model

按向导提示：

• 选择模型提供商（如 MiMo、DeepSeek、minimax 等）
• 输入对应的 API Key

如果后续需要更换模型，再次执行 hermes model 即可。

第五步：配置飞书消息通道

方式一：扫码配对（推荐）

hermes gateway setup

在向导中选择 飞书 / Lark，然后选择 扫码创建（推荐），用手机飞书扫码授权即可。Hermes 会自动创建机器人应用并配置好所有权限。

【提示】 飞书 SDK（lark-oapi）不需要手动安装：官方安装器建的虚拟环境里没有 pip，手动装必然失败；依赖由 gateway 首次启动时自动装上（日志会出现 Platform 'Feishu / Lark' dependencies missing — attempting install...，随后 完成： feishu connected）。

方式二：手动配置（备选）

如果扫码失败（如无管理员权限），改为手动模式：

1. 在飞书开放平台创建应用，获取 App ID 和 App Secret
2. 执行网关配置向导：

hermes gateway setup

1. 在平台列表里选择 Feishu / Lark，再选手动输入，依次粘贴 App ID、App Secret
2. 连接方式选 WebSocket（推荐，无需公网地址）；域选 feishu（国内版）
3. DM 授权方式选 配对审批（推荐），群聊策略选 仅 @ 机器人时响应（推荐）

第六步：安装并启动 Gateway 服务

hermes gateway install

这一条命令会同时完成：写入 ~/.config/systemd/user/hermes-gateway.service、systemctl --user enable、自动开启 linger（注销后仍运行、开机自启）、并立即启动网关。

查看运行状态：

hermes gateway status
systemctl --user status hermes-gateway

【注意】 不能跳过 install 直接 hermes gateway start：没装服务时会以退出码 1 结束并提示 未完成： Gateway service is not installed。

只写 systemctl --user enable hermes-gateway 不能实现开机自启——还需要 sudo loginctl enable-linger $USER，而 hermes gateway install 已经替你做了（日志有 完成： Linger enabled — gateway will persist after logout）。

查日志：journalctl --user -u hermes-gateway -f

第七步：测试飞书机器人

1. 打开飞书 App，搜索你的机器人名称
2. 发送一条消息（如 你好）

如果使用扫码方式，授权即完成身份绑定，机器人应直接回复。

如果使用手动配置方式，第一次发消息时需要批准配对码：

hermes pairing list                       # 查看待批准的配对请求（不带平台参数）
hermes pairing approve feishu <配对码>     # 批准

【提示】 批准立即生效、无需重启 gateway，下一条消息就会被正常受理（实测：批准后 2 秒内发出的消息即被响应）。

运行诊断（可选）

hermes doctor

检查安装和配置是否完整。