前置条件
- 1已安装飞书客户端（7.28 及以上）并拥有企业/团队账号
- 2是目标飞书群的群管理员（自定义机器人只有群管理员能添加）
- 3已开通百度智能云千帆大模型平台，拿到 API Key（AK）与 Secret Key（SK）
- 4有一台能出网的机器跑中转脚本，Python 3.10+ 或 Node.js 18+
即时通信 IM + AI
高效构建智能聊天能力
常见问题
Q千帆的 access_token 和飞书的 tenant_access_token 是一回事吗？
完全不是，别混。千帆 access_token 是你调用文心一言的凭证，由 AK/SK 换得，有效期 30 天；飞书 tenant_access_token 是你调用飞书开放接口的凭证，由 app_id/app_secret 换得，有效期 2 小时。一次群问答要同时用到两个 token，建议分别缓存，不要在每次请求里现取。
Q返回 error_code 110 Access token invalid 怎么办？
三种可能：一是 access_token 过期或被手动吊销，重新用 AK/SK 换一个；二是你用的是旧版百度 AI 开放平台的 token（aip.baidubce.com 换的），而调用的是千帆 v2 接口，两者不通用；三是请求头格式不对，千帆 v2 只认 Authorization: Bearer 前缀。
Q加签一直返回 19021 sign match fail 怎么办？
检查三点：timestamp 必须是秒级 10 位而不是毫秒 13 位；待签名串是 timestamp 加换行符加 secret，顺序不能反；HMAC-SHA256 的密钥是空字符串、输出取十六进制小写，而钉钉的密钥是 secret 本身、输出取 base64，两套不通用。另外服务器时间与飞书相差超过 1 小时也会被拒。
Q卡片消息返回 230002 怎么排查？
230002 是消息体校验失败。按顺序查：header.template 只能用内置色号（blue/wathet/turquoise/green/yellow/orange/red/carmine/violet/purple/indigo/grey），不能写十六进制颜色；elements 里 tag 必须是受支持标签；actions 每个按钮必须有 type 和非空 value（不超过 512 字节）；自建应用调用时 content 必须是字符串化的 JSON 而不是对象。
Q为什么群里 @ 机器人没有反应？
自定义机器人 Webhook 只能单向推送，收不到用户消息。要让机器人听见群里的话，必须走自建应用：开启机器人能力、勾选 im:message 与 im:message:send_as_bot 权限、订阅 im.message.receive_v1 事件（长连接或 Webhook 回调二选一），并把机器人重新拉进群。