一个下午省出来的运维时间 - 飞书机器人接入大模型的完整路径

为什么要走网关

独立开发者给飞书做机器人，最常见的卡点不是飞书侧的 SDK，而是大模型这头：要注册账号、绑卡、处理各家的 SDK 差异，模型一换，代码跟着改。上周我帮一个三人的小团队接入，最初估了两天，实际走网关方案，从注册到机器人回复第一条消息，用了不到两小时——其中大半时间花在等飞书审核，真正写代码的部分不到二十分钟。

走网关（如 ThisToken.AI）的好处是把“多模型接入”压缩成一个 OpenAI 兼容接口：换模型只改一个模型名字符串，不用重装 SDK，不用重新处理鉴权逻辑。对一个人身兼前后端运维的小团队来说，省下的不只是开发时间，还有后续的维护成本——以前每次模型调价或接口变更都要回来改代码，现在基本不用动。

前置准备

1. 飞书开放平台创建一个「企业自建应用」，开启「机器人」能力
2. 在「事件与回调」中配置回调地址（建议用飞书的加密模式，官方 SDK 会帮你处理 challenge 校验）
3. 注册 ThisToken.AI 账号，在控制台创建一个 API Key（价格以官网价格页为准，按量计费，不用预付大额费用）
4. Python 环境 3.8+，安装依赖：

pip install lark-oapi openai

核心代码

下面的代码是可跑通的最小版本：飞书机器人收到私聊消息后，调用网关背后的大模型，把回复发回会话。

import json
from lark_oapi.api.im.v1 import (
    P2ImMessageReceiveV1, ReplyMessageRequest, ReplyMessageRequestBody
)
import lark_oapi as lark
from openai import OpenAI

# ===== 配置 =====
FEISHU_APP_ID = "你的飞书App ID"
FEISHU_APP_SECRET = "你的飞书App Secret"
THISTOKEN_API_KEY = "你的ThisToken API Key"

client = OpenAI(
    api_key=THISTOKEN_API_KEY,
    base_url="https://api.thistoken.ai/v1"
)

llm_client = lark.Client.builder() \
    .app_id(FEISHU_APP_ID) \
    .app_secret(FEISHU_APP_SECRET) \
    .build()

def ask_llm(question: str) -> str:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",  # 换模型只改这一行
        messages=[
            {"role": "system", "content": "你是一个简洁友好的团队助手。"},
            {"role": "user", "content": question},
        ],
    )
    return resp.choices[0].message.content

def do_reply(data: P2ImMessageReceiveV1) -> None:
    msg = data.event.message
    if msg.chat_type != "p2p":  # 本示例只处理私聊
        return
    question = json.loads(msg.content).get("text", "")
    answer = ask_llm(question)

    request = ReplyMessageRequest.builder() \
        .message_id(msg.message_id) \
        .request_body(ReplyMessageRequestBody.builder()
            .content(json.dumps({"text": answer}))
            .msg_type("text")
            .build()) \
        .build()
    llm_client.im.v1.message.reply(request)

event_handler = lark.EventDispatcherHandler.builder("", "") \
    .register_p2_im_message_receive_v1(do_reply) \
    .build()

ws_client = lark.ws.Client(FEISHU_APP_ID, FEISHU_APP_SECRET,
                           event_handler=event_handler)

if __name__ == "__main__":
    ws_client.start()

几个值得注意的点：

• 用的是飞书长连接模式（lark.ws.Client），不需要公网服务器和域名，本地跑起来就能收消息。这对没有运维的独立开发者是个关键省时项——省掉了买服务器、配 HTTPS、做鉴权那一整套，通常这套流程要占掉半天。
• 大模型调用走的是标准 OpenAI SDK，只改了 base_url。以后想对比不同模型的效果，改 model 参数即可，其他代码零改动。
• 生产环境建议把 API Key 放到环境变量里，别硬编码进仓库。

调试时常见的问题

收到消息但没回复：先看终端日志里 LLM 调用是否报错。最常见的是 API Key 没复制完整，或者 Key 没启用对应模型。

回复了但消息是空的：飞书要求 content 是合法 JSON 字符串，json.dumps 不能省。

首次启动卡住：确认飞书应用已发布版本，且「机器人」能力已开启，事件订阅里勾选了「接收消息」。

成本和时间的账

给小团队算笔账（不含模型调用费，那部分以官网价格页为准）：

这套方案跑通之后，团队把机器人的用途从「问答」扩展到了「群内周报摘要」和「值班提醒生成」，每次加功能只是改 prompt 和监听的事件类型，主链路完全复用。第一个机器人从想法到上线不到两小时，第二个开始基本就是十分钟级别的改动。

下一步

跑通私聊回复后，可以逐步加上：群聊 @ 触发（处理 mentions 字段）、会话上下文（把历史消息拼进 messages）、流式输出（飞书支持卡片消息的流式更新）。这些都在同一套网关接口上叠加，不引入新的接入成本。

如果你还没注册，可以直接在这里创建账号、拿到 API Key，把上面的代码跑起来：https://api.thistoken.ai/register

---

想直接跑通示例？访问 https://api.thistoken.ai/register 注册 ThisToken.AI，获取 API Key 后即可开始。