Coze机器人加入空间后无法接收消息，如何排查权限配置？

Question

Coze机器人加入飞书/钉钉等协作空间后无法接收消息，常见原因多为权限配置缺失。首先确认机器人在管理后台已开启「消息接收」权限（如飞书需勾选“接收群消息”并完成事件订阅配置）；其次检查空间内是否完成机器人添加且未被禁言或移出群组；再验证应用权限范围是否覆盖目标群类型（如仅支持“全员群”而误加至“临时会话”）；最后排查事件订阅URL是否有效、签名密钥是否匹配，以及机器人Token是否过期。建议通过平台开发者控制台的「事件日志」或「调试工具」实时查看回调请求状态，结合HTTP 200响应与事件体内容交叉验证。权限变更后需重新安装应用或刷新授权。

Answer 1

```html

一、表层现象：消息“静默”——机器人无响应的直观表现

Coze机器人加入飞书/钉钉群后，用户发送消息无任何回复，日志无记录，后台无事件触发痕迹。该现象常被误判为“机器人宕机”或“网络中断”，实则90%以上源于权限链路中的某个环节未激活。需明确：协作平台的消息投递是“推模式”（Event-Driven），非轮询，因此无回调即无感知。

二、权限基线核查：四层授权模型逐级验证

• ① 应用级权限开关：飞书开发者后台 →「机器人」→「权限配置」→ 必须启用「接收群消息」+「接收私聊消息」（按需）；钉钉需在「应用管理」→「机器人」→「事件订阅」中勾选message与group_message
• ② 群组级可见性：确认机器人已通过「添加成员」操作正式入群（非仅@提及），且未被管理员设置为「禁言」或「移出群聊」；飞书临时会话（如单聊邀请链接生成的会话）默认不触发群事件，需单独开通im:message:receive私域权限
• ③ 权限范围覆盖性：检查应用发布状态——「开发中」应用仅对开发者账号生效；「已上架」应用需完成「应用授权」流程，且授权范围必须包含目标群类型（如飞书「全员群」「部门群」支持群事件，但「聊天室」「临时会话」需额外申请白名单权限）
• ④ Token生命周期管理：Coze侧「Bot Settings」中显示的Bot Token存在7天自动过期机制（飞书）或长期有效但需手动刷新（钉钉），过期后所有API调用返回401 Unauthorized，事件回调亦被平台拒绝

三、事件通道深度诊断：HTTP回调链路全栈追踪

协作平台将消息封装为JSON事件体，以POST方式推送至Coze配置的Event Callback URL。常见故障点如下表所示：

故障维度	典型症状	验证方法
URL可达性	飞书控制台「事件日志」显示Connection refused或超时	curl -I https://your-coze-domain.com/api/v1/event （检查200/404/502）
签名验签失败	日志提示invalid signature，但HTTP状态码为200	比对飞书Header中X-Lark-Signature与本地用App Secret计算的HMAC-SHA256值
事件体解析异常	Coze服务返回500，或日志出现json decode error	捕获原始Payload（使用RequestBin或Ngrok），验证UTF-8 BOM、转义字符、嵌套结构深度

四、调试闭环：从平台日志到端到端验证

推荐采用以下mermaid流程图指导排障路径：

flowchart TD
    A[发现无消息接收] --> B{检查飞书/钉钉事件日志}
    B -->|无请求记录| C[验证Callback URL与Token有效性]
    B -->|有请求但失败| D[比对签名密钥与事件体结构]
    B -->|请求成功但Coze无响应| E[检查Coze Bot Settings中「事件处理开关」是否开启]
    C --> F[重装应用并重新授权]
    D --> G[更新Coze Webhook密钥并同步至平台]
    E --> H[重启Coze Bot服务实例]
    F & G & H --> I[发送测试消息并观察三方日志联动]

五、高阶实践：权限变更后的强制生效机制

权限配置修改（如新增群事件订阅）不会热生效。飞书要求执行「重新安装应用」操作：进入飞书管理后台 →「应用管理」→「已安装应用」→ 找到对应Bot →「卸载」→「重新安装」→ 管理员二次授权；钉钉则需在「工作台」中点击「重新授权」按钮，并勾选新增权限项。此过程将刷新tenant_access_token及bot_access_token，旧Token立即失效。未执行此步骤是导致“明明改了权限却仍不生效”的最常见根因。

六、生产环境加固建议

• 建立权限配置Checklist：每次上线前校验「事件订阅URL」、「App Secret」、「Bot Token有效期」、「群类型兼容性声明」四项
• 接入平台告警：飞书「事件日志」支持Webhook导出，可对接企业微信/钉钉机器人，当连续5分钟无message事件时触发告警
• 实施Token自动续期：通过飞书/open-apis/auth/v3/tenant_access_token/internal/接口定时刷新，避免人工遗漏
• 构建沙箱验证环境：使用飞书「测试群」+ Coze「Staging Bot」组合，模拟全员群/部门群/临时会话三类场景，覆盖权限边界

七、跨平台差异速查表（飞书 vs 钉钉）

维度	飞书	钉钉
群事件触发条件	仅「全员群」「部门群」「项目群」支持；临时会话需单独申请chat:msg:read	所有群类型均支持，但「保密群」需管理员开启「允许机器人读取消息」
签名算法	HMAC-SHA256(timestamp + nonce_str + body)	HMAC-SHA256(body + timestamp + suite_key)
Token刷新周期	Bot Token 7天，Tenant Token 2小时	AppKey/AppSecret长期有效，AccessToken 2小时

```