做飞书接入之前，我先说一个真实场景：去年我帮团队搭过一个"会自己干活"的内部工具，不是那种只会群发提醒的机器人，而是真正能在群里接需求、查数据、回状态、做记录的助理。用下来最大的感受是，飞书这套开放能力比大多数人想象中要成熟得多——从前台的消息收发、后台的权限管理，到多维表格当数据库，几乎每个环节都有现成的接口。这个项目做下来，我踩了不少坑，也摸清了一条从零到上线的最短路径，所以打算写成一篇带实操代码的完整记录，给也想在飞书里搭"全天候客服/助理"的朋友做个参考。
这篇文章适合你有这么几种情况：想在飞书群里放一个能自动回复的机器人；想把飞书消息接到大模型做智能问答；想把客服记录、工单状态直接落到多维表格里做统计；甚至只是想搞清楚飞书开放平台的接入流程到底是怎样的。
我会从整体架构讲到后台配置，从消息收发代码讲到大模型对接，再到多维表格落库，最后把常见的坑都列出来。每一段都会附上能直接跑通的核心代码，目标是你照着敲一遍，就能拥有一个自己的飞书助理。
1. 搭建前先想清楚：这套"全天候客服"到底分几层
很多人一上来就打开飞书开放平台创建应用，然后就开始写代码，结果写到一半发现权限不够、事件收不到、消息发不出去，回头再查文档，来回折腾好几天。其实飞书这种平台型接入项目，动手前最该做的是把架构想明白，想明白之后后面的每一步都只是"照做"而已。
1.1 整体调用链路的四个角色
以我搭的这套系统为例，整个链路涉及四个角色：
- 飞书客户端：员工在群里发消息、@机器人，或者直接私聊机器人。
- 飞书开放平台：负责把消息事件推送给你的服务端，也负责校验你的API调用凭证。
- 你的服务端：接收飞书推送的事件，做业务判断，决定是直接回复还是调大模型、查多维表格。
- 外部能力层：大模型API、多维表格API、企业内部的查询接口等等。
这四个角色之间通过两种方式通信：一种是飞书主动把事件推给你（消息回调、机器人被@等），另一种是你的服务端主动调用飞书OpenAPI（发消息、查用户、读写表格）。理解了这两条线，后面看文档就不会迷路。
1.2 为什么建议采用"事件订阅 + Webhook"而不是轮询
飞书开放平台提供了事件订阅机制，也就是在群里有人发消息、@机器人、加好友、进群退群这些动作发生时，飞书会实时把事件数据POST到你配置的回调地址上。这比起你每隔几秒主动调用API去拉新消息，有几个明显优势：
- 实时性高，消息到的瞬间就能响应。
- 服务端压力小，不用一直空转轮询。
- 飞书侧做了重试机制，你的服务临时不可用，它还会尝试重新推送。
当然了，有些场景确实需要主动拉取，比如做历史消息的批量导入，这时候用im/v1/messages这类查询接口就行。但"客服"这个场景，事件订阅是绝对的主流，我在搭建时选的就是这条路线。
1.3 服务端选型：长短连接、框架与部署机的最小可行方案
服务端这块，我用的是Python + FastAPI，原因很简单：Python生态里调用大模型、处理JSON、写脚本都方便，FastAPI又是轻量异步框架，起个Webhook服务几行代码就搞定。项目结构长这样：
feishu-assistant/ ├── app.py # FastAPI入口 ├── feishu_client.py # 飞书API封装 ├── llm_client.py # 大模型调用 ├── bitable_client.py # 多维表格操作 ├── config.py # 配置项 └── requirements.txt部署上，如果你的服务器有公网IP，直接用Webhook方式暴露一个HTTPS地址就行。如果没有公网IP，飞书还提供了长连接模式（WebSocket），服务端主动跟飞书建立连接，消息直接推到这个长连接上，不需要暴露公网端口。这对我这种经常在个人服务器上搭东西的人来说很实用，后面细讲。
2. 飞书开放平台的后台配置：权限、事件订阅与常见错误码
这章是整个接入最容易出问题的地方。大部分第一次接触飞书开放平台的人，都会在"应用后台到底要配哪些东西"上懵掉。我按创建应用到发布上线的完整顺序来讲。
2.1 创建企业自建应用的最低配置路径
在飞书开放平台（open.feishu.cn）用管理员账号登录后，进入开发者后台，点击"创建企业自建应用"，填应用名称和描述。创建好之后，重点要配这么几块：
- 应用能力：添加"机器人"能力。这一步会在应用下生成一个机器人，后面群里提到的就是它。
- 权限管理：在权限列表里搜索并开通以下权限点：
im:message：读取用户发给机器人的消息。im:message:send_as_bot：以机器人的身份发送消息。im:chat:readonly：读取群信息，用于判断消息来自哪个群。contact:user.base:readonly：读取用户基本信息，用于识别发送者是谁。- 如果要读多维表格，还需要
bitable:app。
- 事件订阅：配置回调地址，并订阅你需要的"事件"。
- 版本发布：以上都配好后，创建版本并发布。这里特别提醒，很多人配完权限发现还是不生效，原因就是没发布版本。自建应用需要发布后，权限和事件配置才会真正生效。
我第一回搭建时还犯过一个低级错误：权限开通了，但是发布的是"测试版"，同事那边根本不是这个版本，结果消息一直推不过来。后来学乖了，每次改配置，先发一个版本，再在群里真实验证一次。
2.2 事件订阅里最难的一步：URL验证与加密解密
在事件订阅后台，你需要填一个回调URL。填完保存时，飞书会立刻向这个URL发送一个验证请求：
- 如果没开启"加密"，飞书会POST一个
{"challenge": "xxxx"}的JSON，你的服务端需要原样把challenge字段返回。 - 如果开启了"加密"（通常建议开启），飞书POST请求的body里会带一个
encrypt字段，你需要用配置的Encrypt Key做AES解密，拿到明文后再处理challenge。
很多人在这一步一直报"验证失败"，多半就是加解密没对上。推荐直接用官方SDK，SDK里自带解密逻辑，不需要手写AES。以Python为例，用lark_oapi的EventDispatcherHandler会帮你处理掉解密和challenge响应：
import lark_oapi as lark from lark_oapi.api.im.v1 import P2ImMessageReceiveV1 def do_message_receive(data: P2ImMessageReceiveV1) -> None: # 处理消息事件 pass event_handler = ( lark.EventDispatcherHandler.builder("encrypt_key", "verification_token") .register_p2_im_message_receive_v1(do_message_receive) .build() )如果你坚持用原生Web框架自己实现，也可以，但一定要确认加密模式和填充方式跟飞书文档保持一致，这个踩坑率极高。我在社群里看到很多人问飞书错误代码2700002，我遇到的情况基本都是事件订阅回调校验不过、加解密没对上或者URL不可达，按这个方向排查基本都能解决。
2.3 订阅哪些"事件"才能满足客服/助理需求
事件订阅里可选的"事件"非常多，但对"客服/助理"这个场景来说，最核心的就是这么几个：
im.message.receive_v1：收到消息时触发。这是最关键的，群里@机器人、私聊机器人，都是这个事件。im.chat.member.added_v1：机器人被拉进群时触发，可以做欢迎语。contact.user.updated_v2：用户资料变更，如果助理要维护通讯录相关功能，可以订阅。
实际开发中我基本上只订阅了im.message.receive_v1一个事件，其他都靠主动调API处理。订阅太多反而会增加服务端的处理噪音。
3. 服务端接入：消息收发与事件处理的完整代码
后台配置完成后，就到了最核心的代码部分。这章我会讲清楚两件事：怎么收到消息，怎么发消息。顺便把"避免机器人自己回复自己"和"只响应@自己的消息"这类逻辑也一起讲掉。
3.1 事件回调代码：FastAPI版最小实现
不管后台的加密怎么配，到了服务端，核心逻辑都一样：接收POST请求，解析请求体里的消息事件，提取消息文本、发送者、群ID，然后走业务逻辑。我用FastAPI写了一个可以直接跑的最小版本：
from fastapi import FastAPI, Request import json app = FastAPI() @app.post("/webhook/event") async def receive_event(request: Request): data = await request.json() # 处理URL验证 if "challenge" in data: return {"challenge": data["challenge"]} event = data.get("event", {}) message = event.get("message", {}) chat_id = message.get("chat_id") message_id = message.get("message_id") msg_type = message.get("message_type") # 只处理文本消息 if msg_type != "text": return {"code": 0} # 消息文本在 content 里，是JSON字符串 content = json.loads(message.get("content", "{}")) text = content.get("text", "") # 把事件交给业务处理 await handle_message(text, chat_id, message_id) return {"code": 0}这里的handle_message就是你的业务入口。如果想用官方SDK替代手写解析，也能做到，而且官方SDK会自动处理加密、重试、长连接，后面我会单独介绍。
3.2 发消息：tenant_access_token申请与消息发送
服务端要主动发消息，不是直接用App ID和App Secret调接口，而是先要换取一个tenant_access_token。这个token的有效期通常是2小时，建议做缓存，避免每次都请求换取。
用纯requests实现大概是这样的：
import requests import time import json APP_ID = "your_app_id" APP_SECRET = "your_app_secret" _token_cache = {"token": "", "expire_at": 0} def get_tenant_access_token(): if _token_cache["token"] and _token_cache["expire_at"] > time.time(): return _token_cache["token"] resp = requests.post( "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal", json={"app_id": APP_ID, "app_secret": APP_SECRET}, timeout=5, ) data = resp.json() if data.get("code") == 0: _token_cache["token"] = data["tenant_access_token"] _token_cache["expire_at"] = time.time() + data["expire"] - 60 return _token_cache["token"] else: raise Exception(f"获取token失败: {data}") def send_text(chat_id: str, text: str): token = get_tenant_access_token() resp = requests.post( "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=chat_id", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "receive_id": chat_id, "msg_type": "text", "content": json.dumps({"text": text}), }, timeout=10, ) return resp.json()这里要特别提醒的是receive_id_type参数。如果你传的是chat_id，那receive_id字段就填群ID；如果你传的是open_id，那receive_id就填用户ID。传错类型，接口会一直报参数错误。
3.3 官方SDK与长连接模式：没有公网IP也能接入
如果你不想自己处理加解密、不想申请公网回调地址，那强烈建议用官方Python SDK，它内置了长连接（WebSocket）模式。我后来就把服务切到了长连接，省掉了所有回调配置的麻烦。
长连接模式的核心代码：
import lark_oapi as lark from lark_oapi.api.im.v1 import ( P2ImMessageReceiveV1, ReplyMessageRequest, ReplyMessageRequestBody, ) app_id = "your_app_id" app_secret = "your_app_secret" def handle_message(data: P2ImMessageReceiveV1) -> None: message_id = data.event.message.message_id content = json.loads(data.event.message.content) text = content.get("text", "") # 业务逻辑 reply_text = process(text) # 回复消息 request = ReplyMessageRequest.builder() \ .message_id(message_id) \ .request_body( ReplyMessageRequestBody.builder() .content(json.dumps({"text": reply_text})) .msg_type("text") .build() ) \ .build() client.im.v1.message.reply(request) event_handler = ( lark.EventDispatcherHandler.builder("", "") .register_p2_im_message_receive_v1(handle_message) .build() ) client = lark.Client.builder() \ .app_id(app_id) \ .app_secret(app_secret) \ .log_level(lark.LogLevel.INFO) \ .build() ws_client = lark.ws.Client.builder("", "") \ .event_handler(event_handler) \ .build() ws_client.start()这段代码跑起来后，你的服务会以WebSocket方式连到飞书，之后所有消息事件都会从这个长连接里推送过来。不需要配回调URL，不需要有公网IP，对个人开发者来说太友好了。
3.4 必踩的坑：机器人自己回复自己、风暴刷屏
接入消息收发后，第一个会遇到的诡异问题就是：机器人回复的消息，又触发了im.message.receive_v1事件，于是机器人回复自己的回复，陷入死循环。
解决思路是判断消息发送者是不是机器人自己。飞书的消息事件里有个sender.sender_type和sender.id字段，你只需要在事件处理逻辑开头加一行判断：
sender_id = data.event.sender.sender_id.open_id if sender_id == bot_open_id: returnbot_open_id可以通过调用/open-apis/bot/v3/info接口拿到。更稳妥的做法是：只响应群里@机器人的消息，不响应普通群消息。群里普通消息都去回复的话，会打扰所有人，而且很容易触发频率限制。
判断是否@了机器人，需要解析消息里的mentions数组：
mentions = data.event.message.mentions or [] if not any(m.get("id", {}).get("open_id") == bot_open_id for m in mentions): return这样处理之后，机器人在群里就只会在被点名时出现，平时完全隐身，体验上更符合"客服/助理"的定位。
4. 让机器人真正"会说话"：接入大模型并设计对话边界
一个只会回"你好，我是机器人"的飞书助手，说实话意义不大。要把"全天候助理"做起来，大模型这层是关键。我接的是DeepSeek的API，因为它在中文对话、成本、响应速度上都很均衡。而且它兼容OpenAI的接口格式，这意味着我以后想换GPT、Kimi或者其他模型的API，改动量非常小。
4.1 大模型API接入：OpenAI兼容格式的通用写法
DeepSeek的API地址是https://api.deepseek.com，用OpenAI SDK可以直接调用：
from openai import OpenAI client = OpenAI( api_key="your_deepseek_api_key", base_url="https://api.deepseek.com/v1", ) def call_llm(prompt: str, history: list = None) -> str: messages = [{"role": "system", "content": system_prompt()}] if history: messages.extend(history) messages.append({"role": "user", "content": prompt}) resp = client.chat.completions.create( model="deepseek-chat", messages=messages, temperature=0.7, max_tokens=1024, ) return resp.choices[0].message.content这里的base_url改成其他厂商的地址，就能快速迁移。代码里我故意在max_tokens这里设置了1024，而不是不设上限——因为飞书对机器人回复消息的调用时间有要求，如果大模型一次生成太长，可能会导致回复超时，所以这里宁可截断一点，也要保证响应速度。
4.2 设计System Prompt：让助理知道什么该答、什么不该答
系统提示词是决定"助理"质量的关键。我见过很多人直接让大模型"你是一个客服"，这样出来的回答往往又空又格式化。我的做法是在System Prompt里给机器人设好身份边界、回复风格和禁用范围。
下面这个是我在项目里实际用的简化版：
你是公司的内部客服助理，名叫"小飞"。 你的职责是回答员工关于公司制度、IT支持、日常流程的问题。 回复要求： 1. 简洁、口语化，控制在200字以内。 2. 如果问题涉及公司机密或你无法确认的信息，明确说"这个我需要查一下"。 3. 不要编造具体的人名、数据、日期。 4. 涉及需要人工处理的问题，引导用户在群里@IT值班同事。这样设置之后，机器人的回复明显收敛了很多，不会动不动就长篇大论，也不会一本正经地编造事实。这里我特别想强调一点：大模型本身没有"边界"意识，边界完全靠System Prompt和代码逻辑双重控制。
4.3 多轮上下文：如何在无状态机器人里记住"刚才聊了什么"
飞书消息回调每次都是独立的HTTP请求，服务端如果不做存储，机器人是记不住上文聊了什么的。要让助理"连续对话"，最简单的方案是把历史对话放到多维表格或者本地缓存里。
我用的策略是"按会话ID存缓存"，会话ID就用私聊里的open_id或者群聊里的chat_id：
import time from collections import defaultdict session_cache = defaultdict(list) MAX_HISTORY = 10 def get_session_history(session_id: str) -> list: return session_cache[session_id][-MAX_HISTORY:] def append_session(session_id: str, role: str, content: str): session_cache[session_id].append({ "role": role, "content": content, "time": time.time(), }) if len(session_cache[session_id]) > MAX_HISTORY: session_cache[session_id] = session_cache[session_id][-MAX_HISTORY:]这里我用的是内存缓存，如果服务重启，历史就没了。生产环境建议换成Redis，但原理是一样的。多维表格也能做上下文存储，但每次查表会多几十毫秒延迟，对"实时对话"这个场景来说不是最优解。多维表格我更推荐用来做结构化记录，这个下一章详细说。
4.4 超时与异常处理：大模型挂了，机器人不能跟着挂
大模型API是有可能超时、报错的。如果大模型请求超时，飞书那边还在等回复，用户看到的就是"机器人已读不回"。所以我在调用大模型时做了两件事：一是设置请求超时，二是异常兜底。
def safe_llm_call(prompt: str) -> str: try: return call_llm(prompt) except Exception as e: # 打日志 + 返回兜底文案 print(f"[LLM ERROR] {e}") return "抱歉，我当前有点卡顿，请稍后再试。"5. 多维表格当底座：工单、记忆与每日小结
机器人能聊天之后，你会发现它缺一个"记忆仓库"。客户问过什么问题、哪些问题没有解决、今天总共处理了多少条请求，这些数据如果不落库，就只是一个聊完即焚的玩具。多维表格在这里就是个很好的落库方案，因为飞书自带的多维表格有现成的API，而且表格本身就能做筛选、分组、看板，业务人员不用写代码也能直接查看数据。
5.1 用多维表格建一张"客服工单表"
在建表之前，先在飞书里手动创建一个多维表格，里面至少要有这几个字段：
- 问题（文本）
- 回答（文本）
- 状态（单选：待处理/已解决/已升级）
- 来源（文本，记录是哪个群/哪个用户问的）
- 创建时间（创建时间字段类型，自动生成）
然后用开放API往表格里写记录。调用方式并不复杂，HTTP接口如下：
APP_TOKEN = "your_app_token" TABLE_ID = "your_table_id" def add_record(fields: dict): token = get_tenant_access_token() resp = requests.post( f"https://open.feishu.cn/open-apis/bitable/v1/apps/{APP_TOKEN}/tables/{TABLE_ID}/records", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={"fields": fields}, timeout=10, ) return resp.json()调用时把问题、回答、状态等字段塞进fields字典即可。这里需要注意，多维表格的字段类型和API传参类型是对应的，文本字段传字符串，单选字段也传字符串（但实际上单选字段传的是选项名）。创建时间字段不用你传，表格会自动生成。
5.2 从普通回复到自动登记：让每条问答都留下痕迹
我把这个落库逻辑加到了机器人处理消息的流程里：用户问了一个问题，机器人回复完之后，自动把"问题 + 回答 + 状态"写到多维表格。这样我每天晚上打开表格，就能看到当天所有的问答记录。
实际效果是：团队里很多重复性问题，我直接通过表格筛选功能就能统计出频率最高的前几个，然后针对性优化系统提示词。这个过程完全是数据驱动的，比我拍脑袋改Prompt靠谱太多。
5.3 查询历史记录与工单状态更新
除了写入，多维表格也支持查询。比如"我的历史工单"这种需求，可以通过查询接口检索：
def search_records(condition_field: str, condition_value: str): token = get_tenant_access_token() resp = requests.post( f"https://open.feishu.cn/open-apis/bitable/v1/apps/{APP_TOKEN}/tables/{TABLE_ID}/records/search", headers={ "Authorization": f"Bearer {token}", "Content-Type": "application/json", }, json={ "filter": { "conjunction": "and", "conditions": [ { "field_name": condition_field, "operator": "is", "value": [condition_value], } ], } }, timeout=10, ) return resp.json().get("items", [])这个接口在做"查进度""查历史"这类对话时非常有用。比如用户问"我刚才提交的那个问题处理好了吗"，机器人就先按用户ID去表格里查记录，查到之后再针对状态字段做回复。
5.4 用多维表格做定时日报和统计思路
多维表格另一个我很常用的玩法是定时统计。通过records/search把当天记录拉出来，然后在大模型里做一个简单的汇总Prompt，就能在每天下班前自动发一条"今日客服小结"到群里。内容大概包括：今天处理了多少条问题、高频问题有哪些、有多少待处理。这个功能跑起来之后，团队对"助理"的价值感知会一下子提升很多。
6. 上线一周后遇到的坑与收尾建议
代码写完了，接入也验证通过了，不等于事情结束。真正上线跑起来，遇到的各种问题才会浮出水面。这一章我把这一周里遇到的真实问题和排查思路列出来，希望能让你少走弯路。
6.1 token缓存失效与并发请求导致"凭证错误"
我在第3章写了token缓存，但上线后第一天就发现一个问题：多个事件同时进来时，如果token刚好过期，多个请求同时去获取新token，飞书侧会短暂出现频率限制，导致部分请求失败。
解决方案是给token获取加一个互斥锁，用Python的话就是threading.Lock()：
import threading _token_lock = threading.Lock() def get_tenant_access_token(): with _token_lock: # 检查缓存并刷新 ...这种"锁 + 缓存"的组合，在并发场景下是标准的处理方式。另一个值得一提的点是token要提前60秒刷新（代码里的-60就是为了这个），千万不要刚好卡在过期时刻去换。
6.2 事件重复推送：幂等处理不能偷懒
飞书为了保证事件不丢失，会做重试推送。如果你的服务端处理超时或者返回了非2xx响应，飞书会重新推送同一条事件。这样就会出现同一个用户消息被处理两次、机器人回复两次的情况。
我的做法是在Redis里记录消息ID，处理前先判断是否已经处理过：
def is_duplicate(message_id: str) -> bool: key = f"feishu_msg:{message_id}" if redis.set(key, "1", nx=True, ex=60): return False return True如果服务重启、Redis没配，也可以用多维表格的查找接口来判断，但性能会差一些。这个幂等处理属于"必须做"的，否则用户会看到机器人偶尔发重复消息，观感很差。
6.3 大模型回复里的特殊字符和格式问题
大模型返回的内容有时候会带@符号、Markdown标记、甚至[]()这类特殊字符。如果直接通过飞书文本消息发出去，可能会被飞书解析成某种格式，或者出现奇怪的展示。我在代码里加了清理逻辑，把Markdown的加粗、链接等语法去掉，只保留纯文本。
import re def clean_text(text: str) -> str: # 去掉 @某人的格式 text = re.sub(r"@_user_\d+", "", text) # 去掉 Markdown 链接语法 text = re.sub(r"\[([^\]]+)\]\([^)]*\)", r"\1", text) return text.strip()还有个很隐蔽的问题：大模型输出里如果带了{或者}，直接作为JSON字符串发送可能没问题，但如果拼接飞书卡片（card）消息，结构可能被破坏。所以我跟大模型约定：不要输出JSON，不要输出复杂格式，只用纯文本。
6.4 监控告警：用Uptime Kuma盯住机器人的健康状态
机器人也是服务，服务就会挂。我对服务健康最直接的需求是"当服务不可用时，第一时间在飞书群里收到告警"。这个需求用自托管监控工具Uptime Kuma就能实现，它内置了飞书Webhook通知方式。
配置非常简单：在Uptime Kuma里添加监控项，目标地址填你的机器人服务健康检查接口（比如/healthz），然后在通知设置里添加一个飞书机器人Webhook。飞书群里建一个自定义机器人，拿到Webhook地址填进去，当Uptime Kuma检测到服务挂了，就会往群里推告警。
这个联动非常实用，尤其是"全天候"这三个字，意味着没有人盯着服务，只有告警才能确保出问题时你能及时知道。我把它理解为整个系统最后一道保险丝。
6.5 扩展思路：定时任务、人为升级、语音记录
上线稳定之后，我还做了一些小扩展，这里简单提两个方向：
- 定时任务：每天早上9点把多维表格里"待处理"的任务汇总后发到群里。用APScheduler或者系统的cron请求你的一个内部接口都能实现。
- 人工升级：当大模型对某个问题的置信度过低，或者问题里有"人工""转接"等关键词时，机器人自动@IT值班同事，并附上上下文。
这两个扩展都建立在前面已打通的消息收发、多维表格、大模型三块能力上，属于"加个分支"就完事的需求。整个飞书接入项目走到这一步，你拥有的其实已经不仅仅是一个客服机器人了，而是一个可以不断往上堆功能的自动化底座。我在实际使用中最深的体会是：飞书把办公场景里最常用的"消息"和"数据"都变成了API，你只需要把这两条线串起来，剩下的想象力就是你的了。
