Feishu / Lark 设置
KOPI AI AGENT 以功能完整的 bot(机器人)形式与 Feishu 和 Lark 集成。连接成功后,你可以在单聊或群聊中与 agent 对话、在 home chat 中接收 cron job 结果,并通过正常的 gateway 流程发送文本、图片、音频和文件附件。
该集成支持两种连接模式:
websocket—— 推荐方式;Kopi Agent 会主动发起出站连接,你无需拥有公开的 webhook endpointwebhook—— 当你希望 Feishu/Lark 通过 HTTP 将事件推送到你的 gateway 时,此模式很有用
Kopi Agent 的行为方式
| 场景 | 行为 |
|---|---|
| 单聊 | Kopi Agent 会回复每条消息。 |
| 群聊 | 仅当 bot 在群聊中被 @提及时,Kopi Agent 才会回复。 |
| 共享群聊 | 默认情况下,共享群聊中的会话历史按用户相互隔离。 |
此共享群聊行为由 config.yaml 控制:
group_sessions_per_user: true
仅当你明确希望每个聊天共享同一个对话时,才将其设置为 false。
步骤 1:创建 Feishu / Lark 应用
推荐方式:扫码创建(一条命令)
kopi gateway setup
选择 Feishu / Lark,然后用你的 Feishu 或 Lark 手机应用扫描二维码。Kopi Agent 会自动创建一个具有正确权限的 bot 应用并保存凭据。
备选方式:手动设置
如果扫码创建不可用,向导会回退到手动输入:
- 打开 Feishu 或 Lark 开发者控制台:
- Feishu:https://open.feishu.cn/
- Lark:https://open.larksuite.com/
- 创建一个新应用。
- 在 Credentials & Basic Info(凭据与基本信息)中,复制 App ID 和 App Secret。
- 为该应用启用 Bot 能力。
- 运行
kopi gateway setup,选择 Feishu / Lark,并在提示时输入凭据。
请妥善保管 App Secret。任何获得它的人都可以冒充你的应用。
配置权限
在 Feishu 开发者控制台中,进入 Permission Management(权限管理)并添加以下 scope(权限范围)。你可以在权限页面中批量导入它们。
必需权限:
| Scope | 用途 |
|---|---|
im:message | 接收并读取消息 |
im:message:send_as_bot | 以 bot 身份发送消息 |
im:resource | 访问用户发送的图片、文件和音频 |
im:chat | 访问聊天/群组元数据 |
im:chat:readonly | 读取聊天列表和成员信息 |
推荐权限(用于完整功能):
| Scope | 用途 |
|---|---|
im:message.reactions:readonly | 接收表情回应事件 |
admin:app.info:readonly | 自动识别 bot 身份以进行 @提及判断 |
contact:user.id:readonly | 解析用户 ID 以进行 allowlist(允许列表)匹配 |
配置事件
在 Events and Callbacks(事件与回调)中:
- 将连接模式设置为 Long Connection (WebSocket)(长连接)(推荐),或配置一个 webhook URL
- 在 Event Configuration(事件配置)部分,订阅:
im.message.receive_v1—— 接收消息所必需
发布应用
配置完权限和事件后,进入 Version Management(版本管理)并发布应用的新版本。只有在版本发布并通过审批后,权限才会生效(对于企业应用,这可能需要管理员审批)。
步骤 2:选择连接模式
推荐:WebSocket 模式
当 Kopi Agent 运行在你的笔记本电脑、工作站或私有服务器上时,请使用 WebSocket 模式。此模式不需要公开 URL。官方 Lark SDK 会建立并维护一个持久的出站 WebSocket 连接,并支持自动重连。
FEISHU_CONNECTION_MODE=websocket
要求: 必须安装 websockets Python 包。SDK 会在内部处理连接生命周期、心跳和自动重连。
工作原理: adapter(适配器)在后台 executor 线程中运行 Lark SDK 的 WebSocket 客户端。传入事件(消息、表情回应、卡片操作)会被分发到主 asyncio 事件循环。断开连接后,SDK 会自动尝试重新连接。
可选:Webhook 模式
仅当你已在可访问的 HTTP endpoint 后面运行 Kopi Agent 时,才使用 webhook 模式。
FEISHU_CONNECTION_MODE=webhook
在 webhook 模式下,Kopi Agent 会启动一个 HTTP 服务器(通过 aiohttp),并在以下地址提供 Feishu endpoint:
/feishu/webhook
要求: 必须安装 aiohttp Python 包。
你可以自定义 webhook 服务器的绑定地址和路径:
FEISHU_WEBHOOK_HOST=127.0.0.1 # default: 127.0.0.1
FEISHU_WEBHOOK_PORT=8765 # default: 8765
FEISHU_WEBHOOK_PATH=/feishu/webhook # default: /feishu/webhook
当 Feishu 发送 URL verification challenge(URL 验证挑战)(type: url_verification)时,webhook 会自动响应,以便你在 Feishu 开发者控制台中完成订阅设置。设置 FEISHU_VERIFICATION_TOKEN 后,challenge 响应会进行校验——token 缺失或不匹配的 challenge 请求将被拒绝,这样未经认证的远程方就无法通过回显攻击者可控的 challenge 数据来证明对 endpoint 的控制权。
步骤 3:配置 Kopi Agent
选项 A:交互式设置
kopi gateway setup
选择 Feishu / Lark 并根据提示填写。
选项 B:手动配置
将以下内容添加到 ~/.kopi/.env:
FEISHU_APP_ID=cli_xxx
FEISHU_APP_SECRET=secret_xxx
FEISHU_DOMAIN=feishu
FEISHU_CONNECTION_MODE=websocket
# Optional but strongly recommended
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
FEISHU_HOME_CHANNEL=oc_xxx
FEISHU_DOMAIN 接受:
feishu用于 Feishu 中国版lark用于 Lark 国际版
步骤 4:启动 gateway
kopi gateway
然后从 Feishu/Lark 向 bot 发送消息,确认连接已建立。
Home Chat
在 Feishu/Lark 聊天中使用 /set-home,可将其标记为接收 cron job 结果和跨平台通知的 home channel(主频道)。
你也可以预先配置它:
FEISHU_HOME_CHANNEL=oc_xxx
安全性
用户允许列表
在生产环境中使用时,请设置飞书 Open ID 的允许列表:
FEISHU_ALLOWED_USERS=ou_xxx,ou_yyy
如果允许列表留空,任何能访问到该机器人的用户都可能使用它。在群聊中,消息处理前会先根据发送者的 open_id 检查允许列表。
Webhook 加密密钥
在 webhook 模式下运行时,请设置加密密钥以对入站 webhook 载荷进行签名校验:
FEISHU_ENCRYPT_KEY=your-encrypt-key
该密钥可在飞书应用配置的事件订阅部分找到。设置后,适配器将使用以下签名算法校验每个 webhook 请求:
SHA256(timestamp + nonce + encrypt_key + body)
计算出的哈希值会与 x-lark-signature 请求头进行时间安全比较。签名无效或缺失的请求将以 HTTP 401 被拒绝。
在 WebSocket 模式下,签名校验由 SDK 自身处理,因此 FEISHU_ENCRYPT_KEY 是可选的。在 webhook 模式下,强烈建议在生产环境中启用它。
校验 Token
这是额外一层身份验证,用于检查 webhook 载荷中的 token 字段:
FEISHU_VERIFICATION_TOKEN=your-verification-token
该 token 同样可在飞书应用的事件订阅部分找到。设置后,每个入站 webhook 载荷都必须在其 header 对象中包含匹配的 token。token 不匹配的请求将以 HTTP 401 被拒绝。
FEISHU_ENCRYPT_KEY 和 FEISHU_VERIFICATION_TOKEN 可以配合使用,实现纵深防御。
群消息策略
FEISHU_GROUP_POLICY 环境变量控制 Kopi Agent 是否以及如何在群聊中响应:
FEISHU_GROUP_POLICY=allowlist # default
| 值 | 行为 |
|---|---|
open | Kopi Agent 响应任何群组中任何用户的 @提及。 |
allowlist | Kopi Agent 仅响应 FEISHU_ALLOWED_USERS 中列出的用户的 @提及。 |
disabled | Kopi Agent 完全忽略所有群消息。 |
在所有模式下,机器人必须在群中被明确 @提及(或 @all)后,消息才会被处理。私信始终绕过此门限。
设置 FEISHU_REQUIRE_MENTION=false 可让 Kopi Agent 读取所有群流量而无需 @提及:
FEISHU_REQUIRE_MENTION=false
若要按会话粒度控制,请在 group_rules 条目上设置 require_mention —— 详见下文的按群组访问控制。
机器人身份
Kopi Agent 启动时会自动检测机器人的 open_id 和显示名称。仅当自动检测无法访问飞书 API,或你的应用使用租户范围的用户 ID 时,才需要手动设置这些值:
FEISHU_BOT_OPEN_ID=ou_xxx # only when auto-detection fails
FEISHU_BOT_USER_ID=xxx # required if your app uses sender_id_type=user_id
FEISHU_BOT_NAME=MyBot # only when auto-detection fails
机器人间消息
默认情况下,Kopi Agent 会忽略其他机器人发送的消息。当你希望 Kopi Agent 参与 A2A 编排或接收同一群组中其他机器人的通知时,可以启用机器人间消息。
FEISHU_ALLOW_BOTS=mentions # default: none
| 值 | 行为 |
|---|---|
none | 忽略来自其他机器人的所有消息(默认)。 |
mentions | 仅当对端机器人 @提及 Kopi Agent 时才接受。 |
all | 接受对端机器人的每条消息。 |
也可在 config.yaml 中配置为 feishu.allow_bots(两者都设置时以环境变量优先)。
对端机器人无需添加到 FEISHU_ALLOWED_USERS —— 该允许列表仅适用于人类发送者。
授予 application:bot.basic_info:read scope 可显示对端机器人的名称;没有该权限时,对端机器人仍能正确路由,但会显示为其 open_id。
交互式卡片操作
当用户点击按钮或与机器人发送的交互式卡片交互时,适配器会将这些操作路由为合成的 /card 命令事件:
- 按钮点击变为:
/card button {"key": "value", ...} - 卡片定义中该操作的
value载荷会以 JSON 形式包含在内。 - 卡片操作会以 15 分钟的窗口进行去重,以防止重复处理。
网关驱动的更新提示使用原生飞书 Yes / No 卡片,而不会回退为纯文本回复。当 kopi update --gateway 需要确认时,适配器会将所选答案记录到 Kopi Agent 的 .update_response 文件中,并将卡片就地替换为已解决状态。
卡片操作事件通过 MessageType.COMMAND 分发,因此它们会流经正常的命令处理管道。
这也是命令审批的工作方式 —— 当 agent 需要运行危险命令时,它会发送一个带有“允许一次 / 会话内 / 始终允许 / 拒绝”按钮的交互式卡片。用户点击按钮后,卡片操作回调会将审批决定传回给 agent。
必需的飞书应用配置
交互式卡片需要在飞书开发者控制台完成三个配置步骤。缺少其中任何一项,用户点击卡片按钮时都会导致错误 200340。
-
订阅卡片操作事件: 在事件订阅中,将
card.action.trigger添加到你已订阅的事件中。 -
启用交互式卡片能力: 在应用功能 > 机器人中,确保已开启交互式卡片开关。这会告知飞书你的应用可以接收卡片操作回调。
-
配置卡片请求 URL(仅 webhook 模式需要): 在应用功能 > 机器人 > 消息卡片请求网址中,将 URL 设置为与事件 webhook 相同的端点(例如
https://your-server:8765/feishu/webhook)。在 WebSocket 模式下,SDK 会自动处理此项。
若未完成这三个步骤,飞书仍能成功发送交互式卡片(发送仅需要 im:message:send 权限),但点击任何按钮都会返回错误 200340。卡片看似正常工作 —— 错误只有在用户与之交互时才会显现。
文档评论智能回复
除了聊天之外,该 adapter 还能回答留在飞书/Lark 文档上的 @ 提及。当用户在文档上发表评论(本地文本选区评论或全文评论)并 @ 提及机器人时,Kopi Agent 会读取文档及其周围的评论线程,并在该线程中直接发布 LLM 回复。
该处理器由 drive.notice.comment_add_v1 事件驱动,执行以下操作:
- 并行获取文档内容和评论时间线(全文评论线程取 20 条消息,本地选区评论线程取 12 条)。
- 使用
feishu_doc+feishu_drive工具集运行 agent,并限定在该单个评论会话范围内。 - 以 4000 字符为单位对回复进行分块,并以线程回复的形式发回。
- 缓存每个文档的会话 1 小时,上限为 50 条消息,以便同一文档上的后续评论保持上下文。
三层访问控制
文档评论回复仅支持显式授权 —— 不存在隐式的全部允许模式。权限按以下顺序解析(逐字段,首个匹配生效):
- 精确文档 —— 限定到特定文档 token 的规则。
- 通配符 —— 匹配一组文档模式的规则。
- 顶层 —— 工作区的默认规则。
每条规则提供两种策略:
allowlist—— 用户/租户的静态列表。pairing—— 静态列表 ∪ 运行时批准的存储。适用于管理员可以实时授予访问权限的灰度发布场景。
规则存放在 ~/.kopi/feishu_comment_rules.json(配对授权存放在 ~/.kopi/feishu_comment_pairing.json),支持基于 mtime 缓存的热重载 —— 编辑会在下一个评论事件时生效,无需重启 gateway。
CLI:
# Inspect current rules and pairing state
python -m gateway.platforms.feishu_comment_rules status
# Simulate an access check for a specific doc + user
python -m gateway.platforms.feishu_comment_rules check <fileType:fileToken> <user_open_id>
# Manage pairing grants at runtime
python -m gateway.platforms.feishu_comment_rules pairing list
python -m gateway.platforms.feishu_comment_rules pairing add <user_open_id>
python -m gateway.platforms.feishu_comment_rules pairing remove <user_open_id>
所需的飞书应用配置
在已授予的聊天/卡片权限基础上,还需添加 drive 评论事件:
- 在 Event Subscriptions 中订阅
drive.notice.comment_add_v1。 - 授予
docs:doc:readonly和drive:drive:readonlyscope,以便处理器能够读取文档内容。
会议邀请事件
你可以像邀请人类参与者一样,将 Kopi Agent 的飞书/Lark 机器人邀请到视频会议中。当机器人收到会议邀请事件时,Kopi Agent 可以自动启动一次 agent 回合,尝试加入会议。
该流程由 vc.bot.meeting_invited_v1 事件驱动,具体如下:
- 用户将机器人邀请到飞书/Lark 视频会议。
- 飞书/Lark 向 Kopi Agent 发送会议邀请事件。
- Kopi Agent 提取邀请人、会议主题和会议号。
- 如果邀请人通过常规 gateway 允许列表或配对策略获得授权,agent 会收到会议号并尝试自动加入。
- 如果邀请格式不正确,或 agent 无法加入,Kopi Agent 会丢弃该事件,或向邀请人回复简要说明。
不同时包含邀请人和 meeting_no 的格式错误邀请将被忽略。
所需的飞书应用配置
在已授予的聊天/卡片权限基础上,还需添加视频会议邀请事件:
- 在 Event Subscriptions 中订阅
vc.bot.meeting_invited_v1。 - 启用飞书/Lark 开发者控制台针对该事件提示的视频会议权限 scope。
- 保持
im:message和im:message:send_as_bot处于启用状态,以便 Kopi Agent 回复邀请人。 - 确保 gateway 用户允许列表或配对策略对邀请人已授权。会议邀请不会绕过常规的 gateway 访问检查。
媒体支持
入站(接收)
该 adapter 接收并缓存来自用户的以下媒体类型:
| 类型 | 扩展名 | 处理方式 |
|---|---|---|
| 图片 | .jpg、.jpeg、.png、.gif、.webp、.bmp | 通过飞书 API 下载并缓存到本地 |
| 音频 | .ogg、.mp3、.wav、.m4a、.aac、.flac、.opus、.webm | 下载并缓存;小型文本文件会自动提取 |
| 视频 | .mp4、.mov、.avi、.mkv、.webm、.m4v、.3gp | 下载并作为文档缓存 |
| 文件 | .pdf、.doc、.docx、.xls、.xlsx、.ppt、.pptx 等 | 下载并作为文档缓存 |
来自富文本(post)消息的媒体(包括内联图片和文件附件)也会被提取并缓存。
对于小型基于文本的文档(.txt、.md),文件内容会自动注入消息文本中,这样 agent 无需工具即可直接读取。
出站(发送)
| 方法 | 发送内容 |
|---|---|
send | 文本或富文本 post 消息(根据 markdown 内容自动检测) |
send_image / send_image_file | 将图片上传到飞书,然后以原生图片气泡发送(可附带说明文字) |
send_document | 将文件上传到飞书 API,然后作为文件附件发送 |
send_voice | 将音频文件作为飞书文件附件上传 |
send_video | 上传视频并作为原生媒体消息发送 |
send_animation | GIF 会降级为文件附件(飞书没有原生 GIF 气泡) |
文件上传会根据扩展名自动路由:
.ogg、.opus→ 作为opus音频上传.mp4、.mov、.avi、.m4v→ 作为mp4媒体上传.pdf、.doc(x)、.xls(x)、.ppt(x)→ 按其文档类型上传- 其他所有文件 → 作为通用流文件上传
Markdown 渲染与 Post 回退
当出站文本包含 markdown 格式(标题、加粗、列表、代码块、链接等)时,该 adapter 会自动将其作为飞书 post 消息发送,并内嵌 md 标签,而非纯文本。这使飞书客户端能够进行富文本渲染。
如果飞书 API 拒绝 post 载荷(例如由于不支持的 markdown 结构),该 adapter 会自动回退为发送去除 markdown 的纯文本。这种两阶段回退确保消息始终能够送达。
纯文本消息(未检测到 markdown)以简单的 text 消息类型发送。
处理状态 Reaction
在 agent 工作期间,机器人会在你的消息上显示一个 Typing reaction。当回复到达时会清除该 reaction;如果处理失败,则替换为 CrossMark。
设置 FEISHU_REACTIONS=false 可关闭此功能。
突发保护与消息批处理
该适配器包含针对突发消息的防抖处理,以避免对 agent 造成过载:
文本批处理
当用户连续快速发送多条文本消息时,这些消息会在派发前合并为单个事件:
| 设置 | Env Var | 默认值 |
|---|---|---|
| 静默时间 | KOPI_FEISHU_TEXT_BATCH_DELAY_SECONDS | 0.6s |
| 每批最大消息数 | KOPI_FEISHU_TEXT_BATCH_MAX_MESSAGES | 8 |
| 每批最大字符数 | KOPI_FEISHU_TEXT_BATCH_MAX_CHARS | 4000 |
媒体批处理
连续快速发送的多个媒体附件(例如拖拽多张图片)会被合并为单个事件:
| 设置 | Env Var | 默认值 |
|---|---|---|
| 静默时间 | KOPI_FEISHU_MEDIA_BATCH_DELAY_SECONDS | 0.8s |
按会话串行处理
同一会话中的消息按串行方式处理(一次一条),以保持对话的连贯性。每个会话都有各自的锁,因此不同会话的消息会并发处理。
速率限制(Webhook 模式)
在 webhook 模式下,适配器会执行按 IP 的速率限制,以防止滥用:
- 时间窗口: 60 秒滑动窗口
- 限制: 每个 (app_id, path, IP) 三元组在每个窗口内最多 120 个请求
- 跟踪上限: 最多跟踪 4096 个唯一键(防止内存无限增长)
超出限制的请求会收到 HTTP 429(Too Many Requests)。
Webhook 异常跟踪
适配器会跟踪每个 IP 地址的连续错误响应。如果同一 IP 在 6 小时窗口内出现 25 次连续错误,会记录一条警告。这有助于检测配置错误的客户端或探测尝试。
其他 webhook 保护措施:
- 请求体大小限制: 最大 1 MB
- 请求体读取超时: 30 秒
- Content-Type 强制: 仅接受
application/json
WebSocket 调优
使用 websocket 模式时,你可以自定义重连和 ping 行为:
platforms:
feishu:
extra:
ws_reconnect_interval: 120 # Seconds between reconnect attempts (default: 120)
ws_ping_interval: 30 # Seconds between WebSocket pings (optional; SDK default if unset)
| 设置 | Config key | 默认值 | 说明 |
|---|---|---|---|
| 重连间隔 | ws_reconnect_interval | 120s | 两次重连尝试之间的等待时间 |
| Ping 间隔 | ws_ping_interval | (SDK 默认值) | WebSocket 保活 ping 的频率 |
按群组访问控制
除了全局的 FEISHU_GROUP_POLICY 之外,你还可以在 config.yaml 中使用 group_rules 为每个群聊设置细粒度规则:
platforms:
feishu:
extra:
default_group_policy: "open" # Default for groups not in group_rules
admins: # Users who can manage bot settings
- "ou_admin_open_id"
group_rules:
"oc_group_chat_id_1":
policy: "allowlist" # open | allowlist | blacklist | admin_only | disabled
allowlist:
- "ou_user_open_id_1"
- "ou_user_open_id_2"
"oc_group_chat_id_2":
policy: "admin_only"
"oc_group_chat_id_3":
policy: "blacklist"
blacklist:
- "ou_blocked_user"
"oc_free_chat":
policy: "open"
require_mention: false # overrides FEISHU_REQUIRE_MENTION for this chat
| 策略 | 说明 |
|---|---|
open | 群里的任何人都可以使用机器人 |
allowlist | 只有群的 allowlist 中的用户可以使用机器人 |
blacklist | 除了群的 blacklist 中的用户之外,其他人都可以使用机器人 |
admin_only | 在该群中,只有全局 admins 列表中的用户可以使用机器人 |
disabled | 机器人忽略该群中的所有消息 |
在 group_rules 条目上设置 require_mention: false,可跳过该特定会话的 @提及要求。未设置时,该会话继承全局的 FEISHU_REQUIRE_MENTION 值。
未列在 group_rules 中的群组会回退到 default_group_policy(默认为 FEISHU_GROUP_POLICY 的值)。
去重
入站消息使用消息 ID 进行去重,TTL 为 24 小时。去重状态会持久化到 ~/.kopi/feishu_seen_message_ids.json,以便在重启后保留。
| 设置 | Env Var | 默认值 |
|---|---|---|
| 缓存大小 | KOPI_FEISHU_DEDUP_CACHE_SIZE | 2048 条 |
全部环境变量
| 变量 | 是否必需 | 默认值 | 说明 |
|---|---|---|---|
FEISHU_APP_ID | ✅ | — | Feishu/Lark App ID |
FEISHU_APP_SECRET | ✅ | — | Feishu/Lark App Secret |
FEISHU_DOMAIN | — | feishu | feishu(中国)或 lark(国际) |
FEISHU_CONNECTION_MODE | — | websocket | websocket 或 webhook |
FEISHU_ALLOWED_USERS | — | (空) | 用于用户允许列表的逗号分隔 open_id 列表 |
FEISHU_ALLOW_BOTS | — | none | 是否接受来自其他机器人的消息:none、mentions 或 all |
FEISHU_REQUIRE_MENTION | — | true | 群消息是否必须 @提及机器人 |
FEISHU_HOME_CHANNEL | — | — | 用于 cron/通知输出的会话 ID |
FEISHU_ENCRYPT_KEY | — | (空) | 用于 webhook 签名验证的加密密钥 |
FEISHU_VERIFICATION_TOKEN | — | (空) | 用于 webhook payload 认证的验证 token |
FEISHU_GROUP_POLICY | — | allowlist | 群消息策略:open、allowlist、disabled |
FEISHU_BOT_OPEN_ID | — | (空) | 机器人的 open_id(用于 @提及检测) |
FEISHU_BOT_USER_ID | — | (空) | 机器人的 user_id(用于 @提及检测) |
FEISHU_BOT_NAME | — | (空) | 机器人的显示名称(用于 @提及检测) |
FEISHU_WEBHOOK_HOST | — | 127.0.0.1 | Webhook 服务器绑定地址 |
FEISHU_WEBHOOK_PORT | — | 8765 | Webhook 服务器端口 |
FEISHU_WEBHOOK_PATH | — | /feishu/webhook | Webhook 端点路径 |
KOPI_FEISHU_DEDUP_CACHE_SIZE | — | 2048 | 要跟踪的最大去重消息 ID 数量 |
KOPI_FEISHU_TEXT_BATCH_DELAY_SECONDS | — | 0.6 | 文本突发防抖静默时间 |
KOPI_FEISHU_TEXT_BATCH_MAX_MESSAGES | — | 8 | 每个文本批次合并的最大消息数 |
KOPI_FEISHU_TEXT_BATCH_MAX_CHARS | — | 4000 | 每个文本批次合并的最大字符数 |
KOPI_FEISHU_MEDIA_BATCH_DELAY_SECONDS | — | 0.8 | 媒体突发防抖静默时间 |
WebSocket 和按群组 ACL 设置通过 platforms.feishu.extra 下的 config.yaml 进行配置(参见上文的 WebSocket 调优 和 按群组访问控制)。
故障排查
| 问题 | 解决方法 |
|---|---|
lark-oapi not installed | 安装 SDK:pip install lark-oapi |
websockets not installed; websocket mode unavailable | 安装 websockets:pip install websockets |
aiohttp not installed; webhook mode unavailable | 安装 aiohttp:pip install aiohttp |
FEISHU_APP_ID or FEISHU_APP_SECRET not set | 同时设置这两个环境变量,或通过 kopi gateway setup 进行配置 |
Another local Kopi Agent gateway is already using this Feishu app_id | 同一时刻只能有一个 Kopi Agent 实例使用相同的 app_id。请先停止另一个网关。 |
| 机器人在群组中无响应 | 确认机器人已被 @提及,检查 FEISHU_GROUP_POLICY,并且当 policy 为 allowlist 时确认发送者位于 FEISHU_ALLOWED_USERS 中 |
Webhook rejected: invalid verification token | 确认 FEISHU_VERIFICATION_TOKEN 与飞书应用「事件订阅」配置中的 token 一致 |
Webhook rejected: invalid signature | 确认 FEISHU_ENCRYPT_KEY 与飞书应用配置中的加密密钥(encrypt key)一致 |
| 消息卡片显示为纯文本 | 飞书 API 拒绝了 post 类型的消息体;这是正常的回退行为。详情请查看日志。 |
| 机器人收不到图片/文件 | 为你的飞书应用授予 im:message 和 im:resource 权限范围 |
| 机器人身份无法自动检测 | 通常是访问飞书机器人信息接口时出现的临时网络问题。可手动设置 FEISHU_BOT_OPEN_ID 和 FEISHU_BOT_NAME 作为临时解决方案。 |
启用 FEISHU_ALLOW_BOTS 后,同行机器人(peer bot)的消息仍被忽略 | Kopi Agent 尚无法识别自身 —— 请设置 FEISHU_BOT_OPEN_ID(如果你的应用使用 sender_id_type=user_id,还需设置 FEISHU_BOT_USER_ID)。 |
同行机器人显示为 ou_xxxxxx 而不是名称 | 授予 application:bot.basic_info:read 权限范围。 |
| 点击审批按钮时出现 Error 200340 | 在飞书开发者后台启用 Interactive Card 能力并配置 Card Request URL。参见上文的 Required Feishu App Configuration。 |
Webhook rate limit exceeded | 同一 IP 每分钟发送超过 120 个请求。这通常是配置错误或循环调用导致的。 |
工具集
飞书 / Lark 使用 kopi-feishu 平台预设,包含与 Telegram 及其他基于网关的消息平台相同的核心工具。