飞书机器人 + 自部署 AI 服务 30 分钟复现（含 4 个报错修法）

从创建企业自建应用到收到第一条 AI 消息（含 4 个报错修法）

TL;DR — 这不是教程，是一份 30 分钟复现清单：飞书开放平台 → 创建自建应用 → 配 Webhook → 跑通 AI 服务 → 在 IM 里收到第一条消息。文末 4 个常见 5xx 报错和修法，每一条都来自我自己踩过的坑。

第 1 步：飞书开放平台创建应用

📌 创建企业自建应用 5 分钟

访问 open.feishu.cn → 用企业管理员扫码登录
开发者后台 → 创建企业自建应用 → 填名称/icon/简介
记录：App ID、App Secret（关页面后再看不到）
权限管理 → 勾选：im:message（收发消息）、im:message.group_at_msg（群 @ 机器人）、im:message.p2p_msg（私聊）
事件订阅 → 添加事件 im.message.receive_v1（用户发消息触发）

第 2 步：跑一个能 echo 的最小 Webhook

🐍 Python Flask 30 行 echo 服务 5 分钟

先跑通 Webhook 连通性验证，再接 AI：

from flask import Flask, request, jsonify
import lark_oapi as lark

app = Flask(__name__)

@app.route("/webhook", methods=["POST"])
def webhook():
    # 1) 验证 URL（首次会带 challenge 字段，原样返回）
    data = request.json
    if data.get("type") == "url_verification":
        return jsonify({"challenge": data["challenge"]})

    # 2) 处理消息事件
    event = data.get("header", {}).get("event_type")
    if event == "im.message.receive_v1":
        msg = data["event"]["message"]
        sender = msg["sender"]["sender_id"]["open_id"]
        text = msg["content"]["text"]

        # 这里先 echo，正式版本替换为 AI 调用
        reply_text = f"你刚说了：{text}"

        send_message(sender, reply_text)

    return jsonify({"code": 0})

def send_message(receive_id, text):
    # 调 lark SDK 发消息（省略，你有自己的实现即可）
    pass

if __name__ == "__main__":
    app.run(host="0.0.0.0", port=8080)

第 3 步：用 ngrok 把本地服务暴露给飞书

🌐 公网回调 URL2 分钟

下载 ngrok（或 bore/cloudflared 等）
运行：ngrok http 8080
复制 https://xxx.ngrok.io 类似 URL，填到飞书"事件订阅 → 请求网址"
点飞书"测试连接" → 看到 {"code": 0} 即通

第 4 步：把 echo 替换成 AI 调用

🤖 接 AI 服务 10 分钟

替换 webhook() 函数里的 echo 逻辑：

import requests

def ask_ai(prompt):
    """调用自部署 AI 服务（你的服务地址）"""
    resp = requests.post(
        "https://your-ai-service/api/chat",
        json={"message": prompt, "max_tokens": 1000},
        timeout=30
    )
    return resp.json()["reply"]

# 在 webhook() 里：
reply_text = ask_ai(text)

第一次跑通后，再加：

记忆（redis 存 user_id → 对话历史）
知识库检索（先查知识库再调用 LLM）
Skill 调用（按 Skill 模板处理）

第 5 步：发布版本、上线

🚀 上线5 分钟

飞书开发者后台 → 版本管理 → 创建版本（v1.0.0）
说明文字："AI 助手内测版，仅对指定用户可见"
提交审核 → 企业管理员审批
审核通过后 → 在 IM 找机器人私聊 / 群 @，问一个问题 → 收到 AI 回复

踩过的 4 个报错（30 分钟够踩完）

报错 1：飞书"测试连接"返回校验失败

Webhook 验证时飞书会发 {type: "url_verification", challenge: "..."}，必须 原样返回 challenge 字段。漏掉就失败，且没有任何错误提示。

✅ 修法：永远先处理 type == "url_verification" 分支，再处理业务逻辑。

报错 2：App Secret 错误（230001）

飞书的 tenant_access_token 通过 App ID + App Secret 换取。App Secret 输错 → 230001 报错。但页面只显示"调用失败"，看不出具体原因。

✅ 修法：把 App Secret 存环境变量，别硬编码。每次更新时同步更新代码。

报错 3：消息发出去了，但 IM 里看不到

最常见：发的 receive_id_type 错了。飞书区分 open_id / user_id / email / chat_id 四种 ID 类型，混用就"成功但收不到"。

✅ 修法：消息事件 payload 里 sender_id 对象里有各种 ID，按发送目标选对类型。私聊用 open_id，群用 chat_id。

报错 4：频繁调用撞限频（230020）

飞书按租户限频 100 QPS。客服群里 20 个人同时 @ 机器人问问题，瞬间超出。

✅ 修法：你的 AI 服务前面加令牌桶 / 滑动窗口（按租户或机器人），削峰到 80 QPS。超限后给用户回"稍等我查一下"——比直接挂掉强。