前置条件
- 1已安装飞书客户端（7.28 及以上）并拥有企业/团队账号
- 2是目标飞书群的群管理员（自定义机器人只有群管理员能添加）
- 3已注册阿里云百炼（DashScope）账号并开通 Qwen3.8-Omni-Flash 模型服务
- 4有一台能出网的机器跑中转脚本，Python 3.10+ 或 Node.js 18+
读完想动手？新用户首单 8 折上云
服务器 + 大模型 API + 对象存储，新用户首购享 20% 补贴
常见问题
Q群里发张截图让机器人看懂，怎么做？
分三步：一是用飞书的 im:resource 权限把用户发的图片下载下来；二是把图片转成 base64 或传一个公网可访问的 URL；三是按百炼的多模态消息格式组装 content 数组，里面放一条 type 为 image_url 的元素和一条 type 为 text 的元素。注意图片会折算成 tokens 计费，一张 1080P 截图约几百到一千多 tokens，建议先压缩再上传。
Q加签一直返回 19021 sign match fail 怎么办？
三个高频原因：timestamp 用了毫秒（13 位）必须改成秒级（10 位）；待签名串必须是 timestamp 加换行符加 secret，顺序不能反；加密结果要取 HMAC-SHA256 的十六进制小写字符串，而钉钉要的是 base64。另外服务器时间与飞书相差超过 1 小时也会被拒。
Q音频和视频怎么传给 Omni 模型？
音频在 content 数组里放一条 type 为 audio_url 的元素，视频放 type 为 video_url 的元素，取值可以是公网 URL 或 data URI。音频按秒折算 tokens（约每秒几十个），视频按抽帧后的图片折算，长视频建议抽 8-16 帧再传，直接传整段视频既慢又贵。
Qtenant_access_token 多久过期？能不能每次发消息都重新获取？
有效期 2 小时，不要每次都重新获取。飞书对鉴权接口有独立限流，实测高频换取会在几十秒内被打回限流错误，导致全部发消息请求失败。正确做法是进程内缓存，在剩余有效期小于 300 秒时刷新；多实例部署放 Redis 并加分布式锁。
Q卡片消息返回 230002 怎么排查？
230002 是消息体校验失败。按顺序查：header.template 只能用内置色号不能写十六进制颜色；elements 的 tag 必须是受支持标签；actions 里每个按钮必须有 type 和非空 value（不超过 512 字节）；自建应用调用时 content 必须是字符串化的 JSON 而不是对象；整张卡片序列化后不超过 30KB。