前置条件
- 1已安装飞书客户端（7.28 及以上）并拥有飞书账号
- 2在目标飞书群里是群管理员（自定义机器人只有群管理员能添加）
- 3已注册 DeepSeek 开放平台账号并拿到 API Key
- 4有一台能出网的服务跑中转脚本（本地 / 服务器 / 云函数均可），Python 3.10+ 或 Node.js 18+
读完想动手？新用户首单 8 折上云
服务器 + 大模型 API + 对象存储，新用户首购享 20% 补贴
常见问题
Q自定义机器人为什么收不到群里用户发的消息？
群自定义机器人的 Webhook 是单向的，只能由你的服务往群里推消息，飞书不会把用户消息转发给你。要「收到用户问题再回答」，必须走方式 B：在开放平台建企业自建应用，开启机器人能力，订阅 im.message.receive_v1 事件（长连接或 Webhook 回调二选一），拿到 message_id 后再调 im/v1/messages 回复。
Q加签一直返回 19021 sign match fail 怎么办？
三个高频原因：一是 timestamp 用了毫秒（13 位），必须改成秒级（10 位）；二是拼接串写错，正确内容是 timestamp + 换行符 + secret，不是 secret + 换行符 + timestamp；三是加密结果编码错了，飞书要 HMAC-SHA256 的十六进制字符串（小写），而钉钉要 base64，两套不通用。另外服务端与飞书时间相差超过 1 小时也会被拒。
Qtenant_access_token 多久过期？能不能每次发消息都重新获取？
有效期 2 小时。不要每次请求都重新获取：开放平台对 /auth/v3/tenant_access_token/internal 有独立限流，实测连续高频调用会在几十秒内被打回限流错误。正确做法是进程内缓存 token，在过期前 5 分钟（即剩余有效期小于 300 秒）主动刷新，多实例部署时放进 Redis 并加锁避免并发刷新。
Q卡片消息返回 230002 怎么排查？
230002 表示消息体校验失败。按顺序查：header.template 的颜色值必须是飞书内置色号（blue / wathet / turquoise / green / yellow / orange / red / carmine / violet / purple / indigo / grey，不能写 #FF0000）；elements 里每个元素的 tag 必须是受支持的标签；actions 里的按钮 type 不能为空、value 字段必须有且不超过 512 字节；整个卡片 JSON 序列化后不超过 30KB。建议先用飞书「卡片搭建工具」拖拽生成，再把 JSON 复制到代码里。
Q一个群能放几个机器人？发送频率上限是多少？
群自定义机器人数量没有硬性上限，但建议每个群不要超过 3 个，否则消息噪音会让机器人被停用。发送频率上，同一 Webhook 连续推送超过 50 条/分钟会触发限流（返回频率错误码并在几分钟内拒绝请求）。生产环境建议做两件事：把回复合并成一条消息发送，以及在代码里加一个每分钟最多 40 条的令牌桶。