前置条件
- 1已安装飞书客户端（7.28 及以上）并拥有企业/团队账号
- 2是目标飞书群的群管理员（自定义机器人只有群管理员能添加）
- 3已开通火山方舟（Volcano Ark）并在控制台创建了豆包 1.5 Pro 的推理接入点
- 4有一台能出网的机器跑中转脚本，Python 3.10+ 或 Node.js 18+
即时通信 IM + AI
高效构建智能聊天能力
常见问题
Q为什么我填 doubao-1.5-pro-32k 作为 model 会报错 model not found？
火山方舟不直接用模型名做请求参数。你必须在控制台「在线推理 → 创建推理接入点」里选定豆包 1.5 Pro，系统会生成一个 ep- 开头的接入点 ID（形如 ep-20260723123456-abcde），请求时 model 填这个 ID。这是方舟和 DeepSeek、Kimi 最大的区别，第一次接的人几乎都会踩。
Q接入点 ID 和 API Key 是什么关系？能复用吗？
API Key 是账号级凭证，接入点 ID 是「某个模型 + 某套配置」的实例。同一个 API Key 可以调多个接入点；同一个接入点也可以被多个应用共用（不推荐，因为配额和限流是分开的）。建议按「一个机器人一个接入点」来建，这样在控制台能单独看到每个机器人的用量和限流情况。
Q加签一直返回 19021 sign match fail 怎么办？
三个高频原因：timestamp 用了毫秒（13 位）必须改成秒级（10 位）；待签名串必须是 timestamp 加换行符加 secret，顺序不能反；加密结果要取 HMAC-SHA256 的十六进制小写字符串，而钉钉要的是 base64。另外服务器时间与飞书相差超过 1 小时也会被拒。
Qtenant_access_token 多久过期？能不能每次发消息都重新获取？
有效期 2 小时，不要每次都重新获取。飞书对鉴权接口有独立限流，实测高频换取会在几十秒内被打回限流错误，导致全部发消息请求失败。正确做法是进程内缓存，在剩余有效期小于 300 秒时刷新；多实例部署放 Redis 并加分布式锁。
Q卡片消息返回 230002 怎么排查？
230002 是消息体校验失败。按顺序查：header.template 只能用内置色号不能写十六进制颜色；elements 的 tag 必须是受支持标签；actions 里每个按钮必须有 type 和非空 value（不超过 512 字节）；自建应用调用时 content 必须是字符串化的 JSON 而不是对象；整张卡片序列化后不超过 30KB。