最近在研究怎么把 DeepSeek 接入飞书做日常工作助手，试了 Hermes Agent 这个工具，整体流程不算复杂，但中间有几个环节容易踩坑，记录一下搭建过程。涉及飞书开放平台配置、DeepSeek API 设置、Hermes Agent 安装和对接几个环节。

整体架构

先理清整个链路里三个角色的分工：

用户在飞书发消息
       ↓
飞书机器人接收（通过事件订阅回调推送到 Hermes Agent）
       ↓
Hermes Agent 处理消息（上下文管理、意图识别、工具调用）
       ↓
调用 DeepSeek API 生成回复
       ↓
Hermes Agent 拿到结果，通过飞书 API 发回消息
       ↓
用户在飞书收到回复

DeepSeek 提供模型能力，Hermes Agent 做中间调度（消息路由、上下文管理、工具调用），飞书机器人作为前端交互入口。Hermes 这层不是必须的，你也可以直接用飞书 SDK 调 DeepSeek API，但 Hermes 帮你封装好了上下文管理、会话保持、多轮对话这些逻辑，省得自己写。

环境准备

需要提前备好几样东西：

项目	说明	获取方式
DeepSeek API Key	调用模型接口的凭证	DeepSeek 开放平台后台创建
飞书 App ID	飞书自建应用标识	飞书开放平台创建应用后获得
飞书 App Secret	飞书应用密钥	同上，创建应用后获得
公网可访问地址	接收飞书事件回调	云服务器或内网穿透工具
Node.js 环境	Hermes Agent 运行依赖	本地或服务器安装
Hermes Agent	中间调度工具	GitHub 下载或官方渠道获取

搭建步骤详解

下面按顺序梳理每个环节，每步都有几个细节要注意。

第0步：理解 Agent 的定位

这一步是背景铺垫。很多人直接拿 DeepSeek 的对话 API 接到飞书就完事了，发现机器人只能一问一答，没有上下文记忆，也不会调用外部工具（查天气、查数据库、发通知这些）。Agent 就是在模型和聊天入口之间加一层调度逻辑：

• 管理多轮对话的历史消息

• 根据用户意图决定要不要调工具

• 把工具返回的结果喂回给模型继续生成

• 处理并发请求和会话隔离

理解了这层，后面每步的操作目的就清楚了。

第1步：安装 Hermes Agent

Hermes 本体的安装不复杂，但有几个环境依赖容易漏：

• Node.js 版本：建议 18+，低版本跑不起来，报错信息还不明显，排查浪费时间

• 依赖安装：拉完代码先 npm install，如果网络不好可以换国内镜像源

• 配置文件：安装完成后会有一个配置文件模板，后面填 API Key 和飞书凭证就是改这个文件

• 端口占用：Hermes 默认监听一个端口接收飞书回调，确认这个端口没被其他服务占用

装好后可以先跑一次启动命令，看到服务起来没报错，再进入下一步配置。

第2步：DeepSeek 开放平台设置 API Key

这步在 DeepSeek 开放平台操作：

• 登录 DeepSeek 开放平台，进控制台

• 在 API Keys 页面创建新 Key，起个能区分用途的名字，比如 feishu-bot

• Key 只在创建时显示一次，复制下来存好，页面关掉就看不到了

• 注意看 Key 的额度和调用限制，免费额度跑日常对话够用，但接了飞书之后如果群活跃度高，消耗会比想象中快

• DeepSeek 的 API 接口兼容 OpenAI 格式，所以 Hermes 里配置时 base_url 填 DeepSeek 的地址，模型名按 DeepSeek 文档里的来

第3步：飞书开放平台创建机器人

这步操作最多，也最容易出错：

创建应用：

• 登录 飞书开放平台，进开发者后台

• 点"创建企业自建应用"，填应用名称和描述

• 应用类型选"机器人"

配置机器人能力：

• 在应用功能里找到"机器人"，点击启用

• 这步不做的话，后面发消息机器人根本没反应，而且不会有明显报错

配置权限：
进权限管理页面，至少开这几个：

• im:message — 接收消息

• im:message:send_as_bot — 以机器人身份发消息

• im:resource — 获取消息里的资源（图片、文件）

• 根据实际需要再加其他权限

权限配完需要等几分钟生效，有时候还要重新发布应用版本才能生效。

配置事件订阅：

• 在"事件与回调"页面，配置接收地址（就是 Hermes Agent 那个公网地址）

• 订阅 im.message.receive_v1 事件（接收消息）

• 飞书会往这个地址发 POST 请求，Hermes 收到后处理，再通过 API 回复

• 配置时飞书会发一个验证请求，Hermes 要能正确响应，否则保存不了

拿到凭证：

• 在"凭证与基础信息"页面，复制 App ID 和 App Secret

• 这两个值后面要填进 Hermes 配置文件

第4步：Hermes 配置 API 和连接飞书

最后这步是把前面准备的东西都串起来。打开 Hermes 的配置文件，需要填几个关键项：

DeepSeek 侧配置：

DEEPSEEK_API_KEY=sk-xxxxxxxxxxxx
DEEPSEEK_BASE_URL=https://api.deepseek.com
DEEPSEEK_MODEL=deepseek-chat

飞书侧配置：

FEISHU_APP_ID=cli_xxxxxxxxx
FEISHU_APP_SECRET=xxxxxxxxxxxxxxxx
FEISHU_VERIFY_TOKEN=xxxxxxxxxxxxxxxx

服务配置：

PORT=3000
CALLBACK_URL=https://your-server.com/webhook

配置说明：

• FEISHU_VERIFY_TOKEN 是飞书事件订阅里生成的验证 Token，要和飞书后台填的一致

• CALLBACK_URL 必须是飞书后台能访问到的公网地址，路径和飞书事件订阅里填的一致

• API Key 和 Secret 走环境变量注入，别硬编码在配置文件里提交到 git

• 配完重启 Hermes，去飞书给机器人发条消息测试

验证成功的标志：在飞书里 @机器人 发一句话，几秒内收到 DeepSeek 生成的回复。如果没反应，按下面顺序排查。

排查清单

搭完后不通的话，按这个顺序查：

现象	排查方向
飞书发消息完全没反应	先看 Hermes 日志有没有收到回调请求。没有 → 飞书事件订阅地址配错或网络不通；有 → 往下查
Hermes 收到回调但没回复	看 DeepSeek API Key 是否填对、额度是否用完，Hermes 日志会有调用 DeepSeek 的报错
机器人发不出消息	飞书权限 im:message:send_as_bot 没开，或者应用没发布生效
回复很慢	DeepSeek 接口响应慢，或者 Hermes 的超时配置太短导致提前断开
多人同时用会串上下文	Hermes 会话隔离没配，默认可能共用一个对话历史

几个注意点

成本控制：DeepSeek 按输入 + 输出 token 计费。飞书群如果活跃度高，每个消息都走模型，成本会涨得快。建议在 Hermes 里加一层判断，只有 @机器人 或者特定前缀的消息才触发模型调用，其他消息忽略。也可以限制单用户每日调用次数。

上下文长度：多轮对话的消息历史会越来越长，最终超出模型的上下文窗口。Hermes 一般有上下文截断策略，但默认值可能不合适，根据实际对话场景调整保留的历史轮数。

安全审查：如果机器人加到业务群，用户发的消息会被发到 DeepSeek，涉及敏感信息的话需要评估数据合规。DeepSeek 的数据处理策略看官方文档，敏感场景考虑本地部署模型替代。

飞书审核：自建应用默认只在企业内部可见，要加到外部群或者跨企业使用，需要在飞书后台提交审核，审核通过后才能正常使用。

学习素材

搭建过程的操作录屏我放这里，需要的话自行查阅：

链接：https://pan.baidu.com/s/1-ZAG2q_EdumL-hJN4vY-0g
提取码：1234

素材包里除了4节操作录屏，还有一份飞书配置相关的文本说明（飞书.txt）和一个配套图片，搭的时候对照着看比较方便。录屏里每步操作都有演示，文字版里容易跳过的界面细节，视频里看得更清楚。