Hermes Agent 的本地部署并接入飞书的完整攻略

最近在开源 Agent 圈里，Hermes Agent 的名字反复出现在各种讨论中。有人戏称它为"爱马仕 Agent"，起初我也以为这又只是一个新出的 AI CLI 工具。但在实际部署体验一周后，我发现它与普通 Agent 之间的差异很明显——它不只是在"完成任务"，而是在每一次交互中沉淀经验，用一套学习闭环让自己变得越来越好用。

这篇文章将我从零开始部署 Hermes Agent 并接入飞书的完整过程做一个系统梳理，希望能帮助想入手的同学降低试错成本。

一、Hermes Agent 是什么

简单来说，Hermes Agent 是由 AI 研究机构 Nous Research 开发的开源自主 AI 智能体框架，遵循 MIT 开源协议，这意味着使用上手门槛几乎为零。它的核心定位是——一个运行在你自己服务器上、越用越聪明的 AI Agent。

与常见 AI Agent 的关键区别在于，它内置了一套闭环学习机制：

• 记住跨会话上下文：通过 FTS5 全文搜索与 LLM 摘要，能够搜索数周前的对话细节，而不是"聊完就忘"。
• 自主沉淀技能文档：完成复杂任务后，将经验自动提炼为可复用的结构化 Skill 文件。
• 持续自我改进：技能在使用中会持续优化，越用越好用。

这套体系意味着，Hermes 不仅执行任务，还能在实践中不断反思、学习、进化，而无需用户手动来微调或编写提示词。

Hermes 支持 400+ 模型调用（包括 OpenAI、Claude、Ollama 本地模型、Kimi 等），并通过 Telegram、Discord、飞书等多个消息平台与用户交互，可 7×24 小时在服务器上自主运行。

二、安装前的环境准备

在动安装前，先确认环境满足要求：

• 操作系统：Linux（主流发行版）、macOS、Windows WSL2、Android Termux 均可。
• Python：3.10+（不用手动装，安装脚本会自动处理）。
• Git：需要手动装一下。
• 内存：建议 4GB+，如果打算本地跑 7B+ 模型的话建议 16GB+。
• 网络：需要能够正常访问 GitHub（因为安装脚本需要从仓库下载）。

Windows 不支持原生环境，一定要先启用 WSL2（管理员 PowerShell 中执行 wsl --install）。

三、一行命令完成安装

环境就绪后就可以开始安装了。Hermes 的安装方式是目前见过的开源 Agent 里最简单的那档——一条命令行搞定。

打开终端（Windows 用户在 WSL2 的 Ubuntu 终端中），执行：

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

这条命令会自动检测并安装所有必需依赖：uv（Python 包管理）、Python 3.10+、Node.js、ripgrep、ffmpeg 等，无需逐一手动安装。

脚本跑完后，如果看到 “Starting setup wizard”，那恭喜你，安装成功。

四、按照向导完成初始配置

安装成功后会自动进入交互式初始配置向导。这个过程决定了 Hermes 的"大脑"用哪个模型，以及一会儿要在哪些平台上用。

4.1 选择配置模式

向导会给出两个选择：

• Quick setup：适合新手，按流程一步步配就完事。
• Advanced setup：适合有经验的老手，想细化配置的用这个。

新手同学直接选 Quick setup 就行。

4.2 配置模型供应商

这里你根据自己的情况来选：

• 有 OpenAI / Anthropic / Kimi 等 API Key：在 provider 列表里直接选对应服务商，然后填入 API Key 和 Model Name。
• 要用 Ollama 跑本地模型：选 Ollama provider，确认本地服务地址（通常是 http://localhost:11434）。
• 使用自定义 API 端点（比如火山方舟、阿里云百炼）：选 “Custom endpoint (enter URL manually)”，然后手动填 API Base URL 和 Key。

4.3 消息平台选择（建议先跳过）

在向导的消息平台列表中，可能没有飞书选项，这属于正常。建议在这个环节直接选择 Skip，飞书的接入我们后面通过 hermes gateway setup 单独来做。

4.4 验证安装

配置完成后，在终端输入：

hermes

进入交互式 CLI 界面，随便输入一句，如果能正常收到响应，就说明安装和模型配置已经 OK 了。

五、飞书接入完整流程

安装配置没问题之后，接下来就是飞书对接。

整个飞书接入分为两大步：飞书开放平台侧配置（获取 App ID、App Secret、配置回调）和 Hermes 侧配置（Gateway 设置）。

5.1 飞书开放平台侧配置

第一步：创建企业自建应用

登录 飞书开放平台，进入开发者后台，点击 「创建企业自建应用」，输入应用名称和应用描述后点创建。应用名称会对应之后用户在飞书上搜到的机器人名，建议取一个好记的。

第二步：添加机器人能力

在应用详情页左侧，找到 「添加应用能力」，然后勾选 「机器人」 能力添加。

第三步：配置必要权限

左侧导航栏进入 「权限管理」，至少需要添加：

• im:message — 获取与发送消息的核心权限
• im:resource — 获取消息中的资源文件

如果想让机器人在群聊中也稳定工作，建议再补上 im:chat:readonly 和 admin:app.info:readonly。

第四步：获取 App ID 和 App Secret

左侧导航栏进入 「凭证与基础信息」，找到 App ID 和 App Secret，这两样先存好，一会儿 Hermes 侧配置就靠它了。

第五步：配置事件订阅

左侧导航栏进入 「事件与回调」，在订阅方式里选择 「长连接」，然后添加事件 im.message.receive_v1。这样每当有用户在飞书里给机器人发消息时，Hermes 就能第一时间收到回调事件。

第六步：发布应用

完成以上配置后，在左侧导航栏进入 「版本管理与发布」，创建新版本并提交发布。审核通过后，飞书内就能搜到并开始用了。

5.2 Hermes 侧配置

飞书侧的准备工作都搞完了，现在回到 Hermes 的终端环境：

第一步：启动 Gateway 配置向导

hermes gateway setup

在出现的渠道列表中选 飞书 (Feishu)，然后按提示依次填入：

• App ID：上面飞书后台拿到的。
• App Secret：上面飞书后台拿到的。
• Domain：国内版直接填 feishu 就行。
• Connection Mode：建议选 websocket（默认就是它）。
• 访问控制：鉴权环节选 “1—不限制对话人”，这样群里所有人都能跟机器人互动。

配置无误的话，选 Done 保存，所有配置会自动写入 ~/.hermes/.env 文件。

第二步：启动 Gateway

hermes gateway start

此时 Gateway 会在后台持续监控飞书消息并路由到 Hermes 的 AI 核心去处理。

5.3 验证接入

Gateway 启动后，打开飞书客户端，在搜索栏搜到你创建的机器人，发送一条消息（比如简单的"你好"）。如果能正常收到回复，那飞书与 Hermes 的接入就全部搞定了。

六、常见问题与排障

在实际部署中，我也遇到了一些坑点，这里总结几个高频问题和解决办法。

Q1：安装脚本执行失败，提示 curl 命令不存在？

运行 sudo apt update && sudo apt install -y curl git 先把 curl 和 git 装好，再重新执行安装脚本。

Q2：飞书机器人不响消息？

首先检查 hermes gateway start 是否确实在跑。然后去飞书开放平台后台，确认 「事件与回调」 里订阅方式是长连接，并且 im.message.receive_v1 这个事件已添加。最后看下飞书应用的审核/发布状态——未发布的应用机器人不会对消息做出响应。

Q3：Windows 下安装报错？

Hermes Agent 不支持原生 Windows 环境，确认你已经安装并启用了 WSL2。

Q4：Hermes Gateway 启动时报 App ID 或 App Secret 无效？

回去在飞书开放平台的「凭证与基础信息」页面里仔细检查一下，看有没有漏填或者粘贴时多了空格。

七、总结

写到这里，整个部署到飞书接入的过程就算是完整地梳理完了。

相比很多开源 Agent 框架动辄需要手动配置各路依赖、折腾各种环境变量的复杂流程，Hermes Agent 的安装体验确实更顺畅一些：一条命令搞定安装、交互式向导完成配置、Gateway 无缝对接飞书。更重要的是，它这套"越用越聪明"的自我学习机制，确实让 Agent 从一个"工具"变成了一个会成长的"助手"。

当然，Hermes 目前也有需要改进的地方：Gateway 消费的内存不算少，低配机器上长期跑需要留意资源；飞书侧的权限配置对新手来说仍有一定的门槛。但这些不影响它成为当前最值得尝试的开源 AI Agent 之一。