1 引入

我经常需要让程序与通讯工具联动。例如：单向提醒：利用程序盯盘，并通过飞书将买卖信号或涨跌提醒发送到手机，实现程序的单向通知。双向交互：AI 机器人流行之后，这种需求明显多了——我在本地跑一个服务，通过飞书和它对话，下指令、拿结果。

一两年前不少人用微信做过类似的事，但由于并非官方接口，封号风险极高；而飞书、钉钉提供了完整、合规的开放平台，适合长期使用。本文记录一次完整的原理和配置流程。

2 原理

飞书机器人的两种通讯模式，其核心原理与配置复杂度有明显差异：

  • 单向通讯：类似于“广播”。只需在飞书群中创建一个自定义机器人，获取其专属的Webhook URL。任何程序只需向该URL发送一个HTTP POST请求，即可将消息推送到群聊。身份验证已内置于URL中，实现极为简单。
  • 双向通讯：则类似于“客服对话”。它要求开发者自己部署一个具有公网访问能力的后端服务。该服务启动后，需在飞书开放平台进行配置，完成“双向绑定”。当用户在飞书客户端中与机器人对话时，消息会经由飞书服务器转发到你的后端服务，服务处理后再将回复传回飞书。整个过程涉及服务部署、公网暴露、权限配置与事件订阅，更为复杂。

3 单向通讯：快速实现消息推送

3.1 配置步骤

在电脑端飞书中操作：

  • 创建群组：新建一个用于接收消息的群组。
  • 添加机器人：进入群设置 -> 群机器人 -> 添加机器人 -> 自定义机器人。
  • 获取密钥：为机器人命名后，系统将提供一个 Webhook URL，用于发消息。

3.2 调用方式

获取URL后，几乎可以用任何能发送HTTP请求的工具或编程语言来发送消息。以下是一个 curl 命令示例：

1
2
3
4
curl -X POST -H "Content-Type: application/json" \
-d '{"msg_type":"text","content":{"text":"您的程序提醒：监测到关键信号"}}' \
https://open.feishu.cn/open-apis/bot/v2/hook/your-webhook-token

4 双向通讯：搭建可交互的机器人

双向通讯的搭建是一个系统工程，至少需要按顺序完成以下四个核心环节：

4.1 第一步：在飞书开放平台创建应用

在飞书官方注册你的机器人身份并获取密钥。

  • 访问 飞书开放平台，扫码登录。
  • 点击创建“企业自建应用”，填写名称和描述。
  • 添加应用能力 ->机器人 ->添加。
  • 获取凭证：在应用配置中，务必记录好以下三个核心凭证，后续配置本地服务时需要填入：
    • App ID 与 App Secret：应用的身份标识。（发新版本时 appid/app secret 可能变化，需要在配置文件.env 中更新）
    • Verification Token：用于验证事件请求的合法性（在“事件与回调”页面获取）。
  • 配置权限：在“权限管理”中，为机器人开通至少以下权限：
    • im:message （获取用户发给机器人的单聊消息）
    • im:message.p2p_msg （发送单聊消息）
  • 创建测试环境：在“测试企业和人员”中创建一个测试企业，并将你的应用关联进去，后续测试均在此环境中进行。

4.2 第二步：创建并启动本地服务

需要一个后端服务来处理飞书转发的消息。飞书官方提供了Python的示例代码（200多行代码，基于Flask实现），可以快速启动。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# 1. 克隆示例代码
git clone https://github.com/larksuite/lark-samples.git
cd lark-samples/robot_quick_start/python 

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置凭证
vi .env
# 在.env文件中填入第一步获取的凭证
APP_ID=cli_9fxxxx00b
APP_SECRET=EX6xxxxOF
APP_VERIFICATION_TOKEN=cq3xxxxxxkUS
ENCRYPT_KEY= # 如未启用加密，此项留空

# 4. 启动服务 (默认运行在3000端口)
python3 server.py

4.3 第三步：将本地服务暴露至公网

飞书的服务器需要能访问到你刚启动的本地服务，因此必须为其提供一个公网可访问的地址。开发调试阶段，推荐使用 ngrok 工具进行内网穿透。

1
2
3
4
5
6
7
8
9
10
11
# 1. 安装 ngrok (以Debian/Ubuntu为例)
curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" | sudo tee /etc/apt/sources.list.d/ngrok.list
sudo apt update && sudo apt install ngrok

# 2. 登录 ngrok 官网获取并配置 Authtoken
ngrok config add-authtoken $YOUR_NGROK_AUTH_TOKEN

# 3. 将本地3000端口映射到公网
ngrok http 3000

命令执行成功后，ngrok 会生成一个临时的公网URL（如 https://xxxx.ngrok-free.dev），请复制此URL。

4.4 第四步：在飞书平台完成最终配置

这是将前几步串联起来的关键环节，目的是告诉飞书“将消息发送到哪里”。

  • 回到飞书开放平台，进入应用配置页面。
  • 找到 “事件与回调” 设置项，配置请求地址：在“事件配置”中，将 “请求地址” 填写为上一步 ngrok 生成的公网URL（注意：配置时你的本地服务 server.py 必须正在运行）。**
  • 添加订阅事件：在“已添加事件”区域，点击“添加事件”，搜索并添加 “接收消息” 事件。
  • 保存所有配置。如果配置成功，飞书服务器会向你的服务地址发送一个验证请求，示例代码会自动处理此验证。

4.5 测试与使用

完成以上所有步骤后，在飞书客户端中搜索你的机器人名称，即可开始对话。你发送的消息会经过：飞书客户端 -> 飞书服务器 -> ngrok公网URL -> 你的本地服务，然后你的服务处理完再原路返回回复。

5 参考与资源

5.1 飞书官方文档

https://open.feishu.cn/document/historical-version/develop-a-bot-in-5-minutes/step-1-create-app-and-enable-robot-capabilities