本文介绍 CCE Agent 飞书通知渠道的配置及管理方式，帮助用户通过飞书机器人与 CCE Agent 对话，及时获取任务执行的关键信息。

前提条件

• 已创建飞书企业自建应用。事件订阅采用长连接方式，仅企业自建应用支持，商店应用不可用。
• 具有飞书应用的版本发布权限，且应用版本需经企业管理员审核通过。

创建飞书企业应用

在飞书的开发者平台 https://open.feishu.cn/app 创建企业自建应用，具体操作步骤如下：

1. 登录飞书开发者平台，单击创建企业自建应用，填写应用名称与描述。
2. 在左侧导航选择添加应用能力，启用机器人能力。
3. 在左侧导航选择权限管理，搜索并开启以下权限：

权限	控制台中文名	用途
im:message	获取与发送单聊、群组消息	机器人发送、回复消息及更新卡片
im:message:readonly	获取单聊、群组消息	撤回机器人的"正在输入"表情
im:message.p2p_msg:readonly	读取用户发给机器人的单聊消息	接收私聊消息
im:message.group_at_msg:readonly	获取群组中用户 @机器人 消息	接收群内 @ 消息
application:application:self_manage	管理应用自身资源	将应用创建者自动认定为渠道创建者
im:chat:readonly	获取群组信息	校验推送目标群并展示群名称
contact:contact.base:readonly	获取通讯录基本信息	获取会话用户信息
contact:user.base:readonly	获取用户基本信息	在控制台会话列表中展示用户姓名

4. 创建应用版本，勾选允许机器人被添加到外部群中使用，申请发布，并等待企业管理员审核通过。请确认本次申请的 8 条权限已随版本发布生效，再进行 CCE 通知渠道配置。企业自建应用由企业管理员审核，无需飞书团队审核。

说明：首次接入需分两次发布应用版本：
先发布机器人能力和权限，再在 CCE 配置通知渠道；
渠道配置成功后，返回飞书配置长连接事件订阅，并再次创建版本、申请发布、等待企业管理员审核通过。
请按下文顺序操作，避免在长连接尚未建立时保存订阅方式失败。

注意：

• 若未启用机器人能力，在 CCE 控制台注册渠道时会提示 11205 app do not have bot。
• 仅开启权限而未发布版本，权限不会生效，注册渠道时会提示凭据校验失败；事件订阅的变更同样需要发布版本后才会生效。
• 若后续调整了权限范围，需再次发布版本；若影响创建者自动认定，还需在 CCE 控制台重新保存一次 App Secret。

配置通知渠道

您可以在 CCE Agent 的IM渠道页面配置飞书通知渠道，具体步骤如下：

1. 登录 容器引擎 CCE 控制台。
2. 在左侧导航栏选择CCE Agent，再单击IM渠道，进入通知渠道页面。
3. 单击配置通知渠道，配置飞书通知渠道，填写渠道名称以及飞书应用的App ID和App Secret。您可以在飞书开发者平台对应应用的凭据页面获取这两项信息，请妥善保管 App Secret。
4. 完成配置并提交后，在通知渠道列表中查看新增渠道，核对渠道名称、通知渠道和机器人 ID。飞书应用的 App ID 对应列表中的机器人 ID。
5. 确认该渠道的绑定 CCEAgent显示为已开启，状态显示为已启用。
6. 返回飞书开发者平台对应应用，在左侧导航选择事件与回调，进入事件配置，待长连接建立后，将订阅方式选择为使用长连接接收事件并保存。单击添加事件，订阅 im.message.receive_v1（接收消息 v2.0）。
7. 再次创建应用版本并申请发布，等待企业管理员审核通过。事件订阅及订阅方式的变更需随新版本发布后才生效，仅保存事件配置不能完成接入。
8. 在应用的可用范围中添加使用者，至少包含应用创建者本人。完成范围调整，并确认相关使用者可以在飞书中找到并使用机器人。
9. 如需群聊使用，将机器人添加到目标群：群设置 → 群机器人 → 添加机器人。使用外部群时，请确认已在应用版本中勾选允许机器人被添加到外部群中使用，且该版本已审核通过。
10. 按照下文“验证接入是否成功”分别测试私聊及群内 @ 对话。

注意：

• 配置通知渠道前，请先启用飞书应用的机器人能力，并发布已申请的权限。
• 渠道已启用或长连接已建立，不代表机器人能力、消息权限和事件订阅均已生效，仍需完成应用发布并验证实际对话。
• 使用长连接接收事件时，请先在 CCE 完成渠道配置，待连接建立后，再到飞书开发者平台保存长连接事件订阅，并再次发布版本使订阅生效。渠道显示已启用后，仍需通过实际对话验证接入结果。

配置对话策略

在控制台编辑通知渠道，可配置以下两个互相独立的策略：

群聊策略

取值	含义
允许群聊与私聊	群内 @ 机器人和私聊均可触发对话（新建渠道默认此策略）
仅允许私聊	只有私聊可以触发，群内 @ 无响应

入站白名单

• 白名单默认开启且不可关闭：名单为空时仅创建者本人可用，其他用户会被拒绝；创建者本人始终无条件放行。
• 如需让其他同事使用，将其 openid（`ou` 开头的字符串，非工号、用户名或邮箱）加入白名单。白名单内尚未绑定个人云账号的用户无需绑定即可对话，此时任务使用渠道创建者的云身份执行，并受创建者的权限约束。添加白名单前，请确认该用户可以使用这一云身份访问相关资源。
• 如需某用户使用其自身的云账号身份（并受其自身权限约束），该用户需完成账号绑定：在飞书中 @ 机器人获取绑定码，再到控制台使用自己的 AK/SK 完成确认。

说明：白名单外的用户 @ 机器人时会收到一张引导卡片：私聊场景直接展示其 open_id，群聊场景提示其私聊机器人获取。管理员拿到 open_id 后加入白名单即可。

对话方式

• 群聊：必须 @ 机器人才会触发。
• 私聊：直接发送消息即可。

管理通知渠道

如需调整已配置的通知渠道，可在IM渠道页面操作：

1. 登录 容器引擎 CCE 控制台，选择CCE Agent > IM渠道。
2. 在通知渠道列表中，找到需要修改的渠道，单击对应行操作列的编辑。
3. 根据需要修改渠道配置并保存，返回列表核对配置结果。若飞书应用的 App Secret 已轮换，请及时更新对应凭据；调整白名单或群聊策略后，请让相关使用者在飞书中验证。

说明：列表中的绑定 CCEAgent与状态分别展示渠道的 CCE Agent 绑定情况和启用状态，不代表每位飞书使用者均已完成个人云账号绑定。

配置变更后的生效方式

• 修改飞书权限：需创建新版本、申请发布并等待企业管理员审核通过。若涉及创建者自动认定，请在版本生效后，到 CCE 编辑渠道并重新保存一次 App Secret。
• 修改事件订阅或订阅方式：需再次创建版本、申请发布并等待企业管理员审核通过，无需在 CCE 重建渠道。
• 轮换 App Secret：无需为此发布飞书应用版本，但需在 CCE 编辑渠道并更新 App Secret；保存时系统会校验凭据。
• 修改白名单或群聊策略：在 CCE 保存后生效，无需发布飞书应用版本或重启服务。

验证接入是否成功

1. 在通知渠道列表中确认目标渠道的通知渠道为飞书，机器人 ID与所配置应用的 App ID 一致，绑定 CCEAgent为已开启，状态为已启用。
2. 确认飞书应用的权限、事件订阅及可用范围已配置并发布生效。
3. 由渠道创建者私聊机器人，发送一条查询消息，例如“查询我的 CCE 集群列表”，确认机器人正常回复。
4. 如需群聊使用，将机器人加入目标群，由具有使用权限的用户在群内 @ 机器人并发送查询消息，确认机器人正常回复。若私聊正常、群聊无响应，请检查群聊策略和群 @ 消息权限。
5. 如需其他同事使用，将其加入白名单后，再由该同事发起一次对话，确认配置已生效。

常见问题

现象	原因	解决方法
注册提示 11205 app do not have bot	应用未启用机器人能力	在飞书开发者平台添加机器人能力
注册时凭据校验失败	App Secret 填写错误，或修改权限后未发布版本	核对 App Secret；发布新版本并等待审核通过
注册提示渠道已存在（冲突）	该 App ID 曾注册过渠道，删除后仍被占用	更换新的飞书应用，或提交工单联系技术支持
机器人长时间无响应，但连接状态显示正常	缺少消息接收相关权限，或事件未订阅，或订阅变更后未发布版本	核对权限清单、事件订阅及版本发布状态
群内 @ 机器人无响应，私聊正常	群聊策略为"仅允许私聊"，或缺少群 @ 消息权限	调整群聊策略；补齐 im:message.group_at_msg:readonly 权限
提示"不在白名单中"并给出 open_id	该用户不在入站白名单内	管理员将其 open_id 加入白名单
提示"未绑定 CCE 账号"并收到绑定码	创建者自动认定未成功（权限未生效或未发布版本）	补齐 application:application:self_manage 权限并发布版本，然后在控制台重新保存一次 App Secret
机器人收到消息但不回复	缺少 im:message 权限	补齐权限并发布版本
会话列表仅显示 ou_ 开头的 ID	缺少通讯录相关权限，或会话创建早于权限生效	补齐两条通讯录权限并发布版本；已创建的会话不会回填姓名