Hermes 接入飞书保姆级教程：打造你的全天候 AI 私人助理！

Hhaizhr
0 阅读5分钟

想要在大模型时代，拥有一个24小时待命、随时听从调遣的 AI 私人助理吗？

这篇保姆级教程将带你通过 Hermes 将强大的 AI 能力无缝连通到飞书，而且我们采用 WebSocket 模式，无需配置公网回调地址即可轻松搞定！

🌟 前置准备工作 (Prerequisites)

为了保证接下来的操作顺畅，请确认你已经具备以下条件：

  • 云服务器：一台拥有公网 IP 的云服务器（如 Ubuntu 操作系统），用于长时间稳定运行服务。
  • 环境要求：服务器已安装 Python 环境及包管理工具（本文中主要使用的是 uv）。
  • 飞书权限：拥有一个飞书账号，并具备“创建企业自建应用”的权限。

🚀 一、在飞书开发者后台创建并配置应用

1.1 创建企业自建应用

首先，打开并登录 飞书开发者后台。点击 “创建企业自建应用”，为你的应用填写名称和描述并确认创建。 在这里插入图片描述

在这里插入图片描述

1.2 获取应用凭证（App ID / Secret）

应用创建完成后，在左侧菜单栏找到 “凭证与基础信息”。 在这里你能看到属于该应用的 App ID 和 App Secret，请务必复制并妥善保存好（这是该应用的敏感数据，请不要泄露测试环境外）。 在这里插入图片描述

1.3 开通机器人能力与消息权限

在左侧菜单栏找到 “添加应用能力”，点击为该应用启用 “机器人” 能力。 在这里插入图片描述

接着，为你的机器人赋予收发消息的权限： 点击左侧的 “权限管理”，进入页面后点击“开通权限”。在搜索框中搜索 “获取与发送单聊、群组消息” 并点击确认开通。 在这里插入图片描述

🎉 开通该权限后，你的机器人就可以向用户发送单聊消息，或是向机器人所在的群聊发送群消息了。

1.4 配置事件订阅

为了让机器人能接收到用户发送过来的消息指令，我们需要在左侧菜单栏进入 “事件与回调” > “添加事件” > 勾选 “消息与群组” 中的“接收消息”事件。 在这里插入图片描述

1.5 创建版本并发布

以上所有核心配置完成后，必须进行应用发布。进入左侧菜单栏的 “版本管理与发布”，点击“创建版本”。 在这里插入图片描述

在这里插入图片描述

往下拉，填写好版本详情后点击“保存”，最后点击 “确认发布”。 在这里插入图片描述

⚠️ 注意：今后无论是修改核心权限，还是配置不同事件，每次修改机器人功能后，都需要重新创建版本并发布才能生效！

💻 二、服务器端环境准备与依赖安装

接下来我们回到云服务器。你需要在 Hermes 的安装路径下，使用 uv 安装飞书所需的依赖包：lark-oapi 和 websockets。

请在终端中执行以下命令：

cd ~/.hermes/hermes-agent
uv pip install lark-oapi websockets

⚙️ 三、配置 Hermes 环境变量

将飞书的配置告诉 Hermes，极力推荐使用交互式引导设置。在终端运行以下命令：

hermes gateway setup

配置步骤指南：

  1. 在应用列表中选择 Feishu / Lark。

  2. 根据提示输入刚才复制的 App ID，回车。

  3. 根据提示输入 App Secret（注意：这里默认不会显示你输入的文本内容，直接复制粘贴过来回车即可）。 在这里插入图片描述

    在这里插入图片描述

  4. 当提示 Domain 和 Connection mode 时，直接回车继续使用默认配置即可。

  5. Allowed user IDs：强烈建议这里填写你自己的飞书 Open ID，用于限制只有你可以使用和指挥该机器人。 在这里插入图片描述

  6. Home chat ID：这里暂时留空，直接回车。

    • 👉 小贴士：等你把服务正式启动后，在飞书里找到你的机器人，无论是在私聊对话框，还是把它拉进通知群组，直接对它发送命令 /set-home。
    • Hermes 收到这个命令后，就会自动把当前所在的聊天窗口标记为它的“主阵地”（Home Chat）。以后的定时任务 (Cron) 和报警通知 (Notifications) 就都会推送到这里啦！ 在这里插入图片描述

🔌 四、注册系统服务与启动

在上述配置的最后阶段，终端会询问：“是否安装网关为系统服务？” 选择 “是”。然后按需选择你的环境安装方式：

  • 安装在自己的个人笔记本电脑上：选择第一个。
  • 安装在云服务器、VPS，全天候待命：选择第二个。 在这里插入图片描述

在这里插入图片描述

按照提示运行下列两条命令，即可完成注册并启动： 在这里插入图片描述

sudo hermes gateway install --system --run-as-user ubuntu
sudo hermes gateway start --system

看到成功提示后，你就可以前往飞书发送消息测试你的智能助手啦！ 在这里插入图片描述

💡 系统服务重启须知： 如果你修改了 .env 配置文件（如增加了新同事的白名单），或者在飞书后台新增了“核心权限”，亦或者是升级了 Hermes 的版本。你必须切换到项目目录下 ~/.hermes/hermes-agent 运行 sudo $(which uv) run hermes gateway restart --system 命令，否则后台系统仍然在按老规矩办事。

🛠️ 五、常见问题与排错 (FAQ)

遇到问题不要慌，以下是配置过程中大家最常遇到的“坑”以及全套排查指南。

Q1：执行注册启动系统服务命令时，提示 sudo 可执行文件或 hermes 找不到 怎么办？ 由于使用 sudo 提升管理员权限时，默认可能会找不到特定用户的 hermes 或 uv 工具执行路径。 答：建议使用 $(which uv) 来确保 sudo 能准确找到执行环境：

  1. 先手动切换到项目目录： 
    cd ~/.hermes/hermes-agent
  2. 用管理员权限加路径指引执行真正的安装和启动命令： 
    sudo $(which uv) run hermes gateway install --system --run-as-user ubuntu

    sudo $(which uv) run hermes gateway start --system

Q2：不想用交互式命令配置，或者事后想进行深层排错配置，怎样进入手动配置模式？ 答：打开主目录下的 .env 文件 ~/.hermes/.env，找到或追加以下参数块即可：

FEISHU_APP_ID=你的_App_ID
FEISHU_APP_SECRET=你的_App_Secret
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket

# 【强烈建议配置】你的飞书 Open ID，用于限制只有你可以使用该机器人
# FEISHU_ALLOWED_USERS=ou_xxxxxx

补充完毕后注意重启系统服务。

🎉 结语

至此，我们已经成功将大模型的核心能力接入了飞书体系！ 后续你还可以结合个人专属工作流，让它负责抓取特定网站内容、自动推送监控日志服务器报错、充当私人的万能问答库。快去搭建属于你的超强工作大脑吧！ 在这里插入图片描述

avatar
文章
阅读
粉丝