> 内容来源：Onevium 官方文档
> 文章: 连接飞书机器人
> 原文: https://onevium.com/zh/docs/channels/feishu
> 语言：简体中文
> 更新于: 2026-09-09
> 适用版本: 1.1.22
> 功能状态: 已发布

---

# 连接飞书机器人

创建飞书应用、配置消息接收、连接 Onevium，并验证两轮回复。

## 把飞书群连接到 Onevium

本教程创建飞书企业自建应用，把机器人接入 Onevium，再验证两轮群聊。桌面字段以 1.1.22 为准，平台步骤使用中国大陆飞书后台；Lark 的凭据和接口域名不能直接当成同一配置。

## 创建平台应用

1. 打开[飞书开发者后台](https://open.feishu.cn/app)，在目标企业创建自建应用。
2. 在**添加应用能力 → 机器人**启用机器人，填写名称和图标。
3. 到**凭证与基础信息**取得 **App ID、App Secret**，稍后填入 Onevium 的专用字段。
4. 准备测试群，应用可用范围需要包含测试成员。

Onevium 通过长连接接收事件，此流程不需要自行部署公网回调服务器。

## 配置消息、事件和卡片

在**权限管理**按需要添加下列能力：

| 需要的能力          | 权限标识                               |
| -------------- | ---------------------------------- |
| 接收群成员 @机器人的消息  | `im:message.group_at_msg:readonly` |
| 接收用户私聊，启用私聊时需要 | `im:message.p2p_msg:readonly`      |
| 以机器人身份发送回复     | `im:message:send_as_bot`           |
| 创建和更新流式卡片实体    | `cardkit:card:write`               |

标识分别来自官方[接收消息事件](https://open.feishu.cn/document/server-docs/im-v1/message/events/receive)、[发送消息接口](https://open.feishu.cn/document/server-docs/im-v1/message/create)和[创建卡片接口](https://open.feishu.cn/document/cardkit-v1/card/create)。提交所选权限，组织要求审批时等待通过后再测试。

在**事件与回调**选择**使用长连接接收事件**，添加**接收消息 v2.0**，事件标识为 `im.message.receive_v1`。使用卡片审批按钮时，还要配置 `card.action.trigger` 回调。保存配置，创建版本并发布到测试成员范围。

后台提示没有可用长连接时，先完成下方 Onevium 连接并确认运行，再返回验证、保存订阅；不必为连接状态问题重新创建应用。

## 填写 Onevium 连接

打开**渠道 → 新建渠道**，选择**单个机器人、飞书**，填写 App ID 和 App Secret，点击**注册凭据**，检查通过后继续。

| 字段     | 首次测试填写方法          |
| ------ | ----------------- |
| 机器人名称  | `文档助手`            |
| 描述     | `回答演示项目的问题`       |
| 模型     | 选择普通会话中已可用的提供商和模型 |
| 工作目录   | 点击选择目录，选演示项目      |
| 会话模式   | 每人独立会话            |
| 聊天范围   | 仅群聊               |
| 自动批准操作 | 首次选择“每项操作前询问”     |
| 角色描述   | 可选，用一句话概括职责       |
| 系统提示词  | 使用下方示例            |

```text
你是演示项目的文档助手。
回答用户明确指定文件的问题。
修改文件或运行命令前，先说明准备执行的动作。
连接测试时，在当前会话记住测试代号。
```

保存后查看运行状态；处于停止状态时点击**启动**。把已发布机器人加入飞书测试群，保持电脑和 Onevium 运行。

## 验证两轮回复

在群中 @机器人：“本次测试代号 alpha-27。”收到回复后再 @它询问代号。应得到 `alpha-27`，并能在 Onevium 对应聊天中找到执行记录。

需要共享上下文时，打开该聊天的**聊天设置 → 会话模式**，切为**所有人共享会话**，再用两个测试用户复测。会话共享不会自动增加读取平台历史消息的权限。

## 按需增加能力

| 新需求          | 要补充什么                                                     |
| ------------ | --------------------------------------------------------- |
| 私聊           | 添加 `im:message.p2p_msg:readonly`，开放私聊范围并设置私聊策略/允许用户 ID    |
| 上传图片、文件      | 添加 `im:resource` 或对应上传权限，再单独测试附件                          |
| 显示成员、群名称     | 需要相应查询时检查 `contact:user.base:readonly`、`im:chat:readonly` |
| 接收未 @机器人的群消息 | 需要 `im:message.group_msg` 等更广的群消息权限，并开启聊天的“被动上下文”         |

选配权限见官方[文件上传](https://open.feishu.cn/document/server-docs/im-v1/file/create)、[用户查询](https://open.feishu.cn/document/server-docs/contact-v3/user/get)和[群信息查询](https://open.feishu.cn/document/uAjLw4CM/ukTMukTMukTM/reference/im-v1/chat/get)。普通群聊回复不需要顺带申请文档写入或幻灯片写入权限。

## 按阶段排错

- 注册凭据失败：检查 App ID、Secret 是否来自同一应用，阅读界面网络或令牌错误。
- 已运行但没收到消息：核对 `im.message.receive_v1`、长连接方式、发布范围、群成员和 @方式。
- 收到消息却没回复：检查模型结果、待审批动作和发送权限。
- 卡片失败：检查 `cardkit:card:write` 和平台错误。Onevium 有回退消息路径，仍要在群里确认最终文字可读。

## 下一步

会话范围见[渠道概览](https://onevium.com/zh/docs/team-channels)，定时投递见[自动化](https://onevium.com/zh/docs/scheduled-runs)。其他平台可参考[钉钉接入](https://onevium.com/zh/docs/channels/dingtalk)。