保姆级图文教程:从零安装 Hermes Agent,接入 DeepSeek 和飞书

保姆级图文教程：从零安装 Hermes Agent，接入 DeepSeek 和飞书

如果你第一次接触 Hermes Agent，这篇教程可以直接照着做。

我们会完成六件事：注册 DeepSeek 并创建 API Key、在手机安装飞书、安装 Hermes Agent、连接模型、切换中文界面、把 Hermes 接入飞书。

本文以 2026 年 7 月 23 日可见的官方页面和 Hermes Agent v2026.7.20 文档为基准。软件更新后，按钮文字和平台序号可能变化，请以你当时看到的界面为准，并用 hermes --help 核对命令。

一、开始前，准备 DeepSeek 和飞书

1. 注册或登录 DeepSeek

打开 DeepSeek Platform：

https://platform.deepseek.com/sign_in

当前页面支持手机号加验证码登录，也支持密码登录。新手机号会按页面提示完成注册。不要在教程截图、聊天或群聊中填写真实手机号和验证码。

图 1｜DeepSeek Platform 当前登录页。截图未填写手机号或验证码，也已裁掉登录二维码。

2. 充值并创建 API Key

登录后依次完成两件事：

1. 打开充值页 https://platform.deepseek.com/top_up，按实际需要充值。DeepSeek API 按用量计费，充值金额以平台页面为准。

2. 打开 API Keys 页 https://platform.deepseek.com/api_keys，创建一个新 Key，并立即复制保存。

图 2｜DeepSeek API 准备流程图。它不是后台界面截图，只用于说明登录后的操作顺序。

3. 手机安装飞书并登录

打开飞书官方下载页：

https://www.feishu.cn/download

iPhone / iPad 选择 iOS/iPadOS，Android 手机选择 Android 客户端；也可以在手机应用商店搜索“飞书”，认准开发者“北京飞书科技有限公司”。安装后打开飞书，用手机号按页面提示注册或登录。

图 3｜飞书手机安装示意图。iOS/iPadOS 与 Android 均应从官方入口或系统应用商店安装。

做到这里，你应当已经准备好：一个有余额的 DeepSeek 账号、一枚 API Key，以及一部已登录飞书的手机。

二、安装 Hermes Agent

1. 从官网下载安装器

打开 Hermes Agent 官网：

https://hermes-agent.nousresearch.com/

根据电脑系统选择下载入口。Windows 10/11 可原生运行，不需要 WSL；x86_64 和 ARM64 均受支持。macOS 正式版只支持 Apple Silicon，也就是 M 系列芯片，Intel Mac 官方不支持。macOS 还要先确认 Git 可用，其余常用依赖由安装器处理。安装包名称、体积和系统版本要求可能变化，以官网当前页面为准。

图 4｜在 Hermes Agent 官网选择对应下载入口。图中的系统版本文字属于截图快照，以官网当前页面为准。

2. 运行安装器

找到刚下载的安装器，双击打开。Windows 如果出现 SmartScreen 提示，先确认文件来自 Hermes 官方域名，再按系统提示继续；单位电脑被策略拦截时，应联系管理员，不要关闭安全软件硬闯。

图 5｜Windows 当次下载示例：双击运行安装器。文件名、日期和体积可能随版本变化。

3. 开始安装

在安装窗口点击 Install Hermes。

图 6｜安装器中的 Install Hermes 按钮。

安装器会自动配置 Hermes 所需的运行环境。保持网络连接，等待它完成，不要中途关闭窗口。

图 7｜安装过程会自动进行，等待完成即可。

4. 启动 Hermes

安装完成后点击 Launch Hermes，进入 Hermes Desktop。

图 8｜安装完成后点击 Launch Hermes。

随后重新打开一个终端窗口，运行：

能看到版本号，且 hermes doctor没有阻断性错误，才算安装真正完成。 如果提示 command not found，先完全退出并重开终端；仍无效时，重新运行官网下载的安装器。

以后也可以在终端运行 hermes desktop 启动桌面端；这是正式文档确认的稳定入口。

三、把 DeepSeek 接入 Hermes

1. 选择 API Key 方式

Hermes 第一次启动会要求连接模型。点击 I have an API key。

图 9｜首次配置时选择“我有 API Key”。

2. 选择 DeepSeek

在模型供应商列表中选择 DeepSeek。供应商列表会更新，按名称找即可。如果新版界面与截图不同，可在终端运行 hermes model，再按向导选择 DeepSeek、输入 Key 并选择当前可用模型；不要照抄截图里的模型 ID。

图 10｜在供应商列表里选择 DeepSeek。

3. 粘贴 API Key

把刚才在 DeepSeek Platform 创建的 Key 粘贴到输入框，点击 Connect。

图 11｜输入框只显示掩码，不含可读取的真实 API Key。

连接成功后，界面会显示 DeepSeek 已连接。点击 Begin 进入主界面。

图 12｜连接成功后点击 Begin；截图中的模型名属于当次结果，不要照抄。

新建一个对话，发送：

收到正确回复后，再追问一句“上一条我让你回复什么？”。两轮都能无报错返回，才说明模型连接真正正常。 没有回复时，依次检查 DeepSeek 余额、Key 是否粘贴完整，以及 Hermes 中是否已经应用 DeepSeek。

四、切换为简体中文

进入 Hermes 主界面后，点击右上角齿轮图标。

图 13｜右上角齿轮是设置入口。

在设置左侧选择 Appearance。

图 14｜进入外观设置。

找到语言选项，切换为 简体中文，然后关闭设置窗口。

图 15｜将 Hermes Desktop 界面切换为简体中文。

五、把 Hermes 接入飞书

1. 打开终端

Windows 按 Win + R，输入 powershell 后回车；macOS 打开 Terminal。

图 16｜Windows 打开 PowerShell 的示例。

2. 启动 Gateway 设置

在终端运行：

如果出现 “gateway service is installed but not running” 并询问是否立即启动，输入 y 后回车。

图 17｜按原终端输出重绘的示意图：执行 hermes gateway setup；启动提示只在服务已安装但未运行时出现。

3. 选择 Feishu / Lark

向导会列出支持的消息平台。找到 Feishu / Lark，输入它在你当前列表里的编号。

截图采集时飞书对应 10，但平台列表会随版本变化，不要把 `10` 当成永远固定的答案。

图 18｜截图中的飞书编号为 10；实际操作以你终端当前显示为准。

4. 选择扫码自动创建

向导会让你选择创建方式。第一次使用建议选择扫码自动创建；如果你已经有飞书应用的 App ID 和 App Secret，才使用手动模式。

图 19｜终端选项示意图：选择二维码自动创建飞书机器人。

5. 用手机飞书扫码

图 20｜示例中的二维码和登录参数已脱敏；实际操作只能使用你终端现场生成的内容。

6. Home Chat ID 可以先留空

在到达 Home Chat 之前，向导会先后询问私信和群聊策略。此时两项都先选择选项 1：私信选择 DM pairing approval，群聊选择 Respond only when @mentioned，然后继续向下走。不要中途退出向导或执行额外命令。 具体的配对审批和“无需 @”设置，等向导完整结束后再做。

Home Chat 用于接收定时任务或主动通知。第一次配置可以直接回车留空，机器人上线后，再在希望接收通知的飞书会话里发送 /set-home。正式文档中 /sethome 也作为等价写法出现。

图 21｜Home Chat ID 是可选项，可以稍后设置。

7. 完成向导并选择 Done

出现 Feishu / Lark configured!，只说明飞书配置已经写入，还不等于消息链路已经打通。向导接着会回到平台列表，请选择 Done，不要直接关闭终端。

图 22｜App ID、Domain 和 Bot 名称已经脱敏，只保留配置成功标志。

然后按 Gateway 当前状态收尾：后台服务尚未安装时先执行一次 install；服务尚未运行时执行 start；如果服务原本已经运行、刚修改完飞书配置，则执行 restart 让它重新加载。最后检查状态。

不要机械地把前三条全部重复执行，应按当前状态选用。setup 保存平台配置，install 登记后台服务，start 才负责当场启动，restart 让已运行服务重新读取新配置。看到 Gateway 正在运行、Feishu 已配置，再做下面两项独立设置。

8. 向导完成后，处理私信授权

刚才在向导中选择的 DM pairing approval 表示：陌生账号第一次私聊时会收到配对码，只有在本机批准后才能继续使用。

图 23｜向导选项示意图，依据原终端画面重绘。推荐使用私信配对审批，而不是向所有人开放。

Gateway 运行后，用准备授权的飞书账号私信机器人。未知账号会收到一个 8 位配对码，配对码约 1 小时后过期。先在终端查看待批准请求，再批准对应代码：

<CODE> 要替换成机器人返回的真实代码；确切命令以机器人提示和 hermes pairing --help 为准。误批后，先运行 hermes pairing list 找到已批准用户 ID，再撤销：

9. 向导完成后，设置群内无需 @

刚才在向导中选择 Respond only when @mentioned，是为了启用群聊；没有选择 Disable group chats。现在再运行下面两条命令，关闭 @ 门槛：

第一条命令会把飞书的全局 require_mention 设为 false，第二条让正在运行的 Gateway 重新加载配置。完成后，只要群聊策略没有被禁用，群里直接发送普通消息也会触发 Hermes，不需要 @机器人。

图 24｜完成向导后，关闭 require_mention 并重启 Gateway。

这会让 Hermes 读取并处理群里的普通消息，噪声、API 消耗和误触发都会增加。建议只把机器人加入专用工作群，不要放进含有敏感讨论或大量闲聊的群。这里设置的是 Hermes 的处理门槛，不会缩小飞书应用本身的权限范围。

六、分别测试飞书和 Hermes Desktop

1. 在飞书里测试

在飞书搜索刚创建的机器人，发送：

如果返回配对码，先按上一节完成批准，再重新发送。机器人能返回正常回复，才说明整条飞书链路已经走通。

图 25｜真实飞书私聊收发示例。保留用户提问与机器人回复开头，姓名、联系人、本机路径和模型环境均已移除。

在已经加入机器人的群里，直接发送普通消息，不要 @机器人。 能收到回复，就说明“无需 @”已经生效；如果仍然不回复，重新执行 hermes gateway restart，再用 hermes config 检查 platforms.feishu.extra.require_mention 是否为 false。

2. 在 Hermes Desktop 里测试

Hermes Desktop 也可以继续直接对话。两边共享同一套模型配置。

图 26｜Hermes Desktop 对话示例，已移除侧栏、路径、版本号和个人信息。

最终验收清单：

• hermes doctor 没有阻断性错误。

• Hermes Desktop 能收到模型回复。

• hermes gateway status 显示 Gateway 正在运行。

• 飞书私聊机器人能回复。

• 群聊中直接发送普通消息、不 @机器人也能回复。

• 如需主动通知，已在目标会话发送 /set-home。

七、最常见的三个问题

Desktop 能聊，飞书不回复

先运行：

仍不正常，再运行 hermes gateway restart。私聊返回配对码时，要先批准配对。

DeepSeek 连接失败

检查 DeepSeek 账户是否有余额、API Key 是否完整、输入框是否夹带空格。不要把真实 Key 发给他人排查。

教程按钮和你的界面不完全一样

Hermes、DeepSeek 和飞书都会更新。优先按功能名称寻找，不要死记编号或安装包文件名。 命令以 hermes --help 和官方文档为准。

八、安全边界与来源

截图采集于 Windows 环境；涉及账号、二维码、登录参数、App ID、Bot 名称、本机路径和联系人信息的画面已脱敏或裁剪。

• API Key、App Secret、配对码和一次性登录链接都不应进入聊天、群聊或公开截图。

• Hermes 调用 DeepSeek 等外部模型 API 时，相关对话内容会发送给所选服务商；不要承诺“数据绝不出本机”。

• 保持命令审批开启，只向 Agent 提供明确的工作文件夹，不把整个家目录或敏感目录直接开放。

• Hermes Agent 官方网站

• Hermes Agent 安装文档

• Hermes Agent 飞书配置文档

• DeepSeek Platform

• DeepSeek API 文档

• 飞书客户端下载