permissions.md

权限说明

FeishuCodexBridge 的基础目标是把飞书消息转给本机 Codex，并把 Codex 回复发回飞书。

建议第一次配置飞书应用时，除了消息收发，也把交互卡片、飞书文档和创建群组权限一起申请好。完整 JSON 见 初始权限清单。

最小权限

权限	是否必需	说明
im:message.p2p_msg:readonly	私聊必需	机器人接收单聊消息
im:message.group_at_msg:readonly	群聊 @ 必需	机器人接收群聊中 @ 它的消息
im:message:send_as_bot	必需	机器人回复消息

卡片能力

Bridge 默认支持飞书交互卡片回复，并监听卡片按钮点击或表单提交，把点击内容续回同一个 Codex 会话。Codex 生成的 JSON 2.0 卡片默认通过 CardKit 创建卡片实体后再发送。

需要：

权限或事件	是否必需	说明
im:message:send_as_bot	必需	发送 interactive 消息
卡片回调事件	按钮回调必需	用于接收用户点击卡片按钮
cardkit:card:write	JSON 2.0 卡片必需	创建 CardKit 2.0 卡片实体

FEISHU_CARDKIT_ENABLED=1 默认开启。Bridge 会用 CardKit 2.0 先创建卡片实体，再按 card_id 发送。多选、表单和提交反馈应使用 JSON 2.0 的 form 容器和 multi_select_static 组件，不要使用普通交互卡片不支持的 checkbox_group。

建群能力

如果要支持“建群 测试”或“创建一个只有我和机器人的群，名字叫测试”这类命令，需要提前申请：

权限	是否必需	说明
im:chat:create	建群必需	允许应用创建群组
im:chat	建议同时申请	允许应用获取与更新群组信息，便于后续群管理

飞书创建群组 API 支持在创建时邀请用户和机器人入群。Bridge 会使用当前消息发送人的 open_id 作为建群成员之一，再把当前应用机器人加入群组。

飞书文档能力

文档能力默认关闭。开启 FEISHU_DOCS_ENABLED=1 前，需要在飞书开放平台给应用申请新版文档创建/编辑权限。建议在权限搜索框里搜索：

• 创建新版文档
• 查看、评论和编辑新版文档
• 云空间文件夹读写相关权限（仅当配置 FEISHU_DOCS_FOLDER_TOKEN 时需要）

推荐配置一个专门的目标文件夹，并把 FEISHU_DOCS_FOLDER_TOKEN 写入 .env.feishu。这样机器人创建出来的文档会集中放在你可见、可管理的位置。

事件订阅

需要订阅：

im.message.receive_v1
card.action.trigger

Bridge 使用飞书长连接能力接收这些事件。没有卡片回调事件时，普通消息仍可使用，但 Codex 发出的卡片按钮不会续回会话。

不默认申请的权限

权限	原因
im:message.group_msg	可读取群内所有消息，敏感度更高；只有需要“不 @ 也能读取群消息”时才考虑
群成员读取权限	只有启用两人小群自动回复时需要；用于判断群里是否只有 1 个真人用户
飞书表格权限	Bridge 不内置表格读取能力
多维表格权限	Bridge 不内置多维表格能力
任务权限	Bridge 不内置任务系统能力

权限生效提醒

飞书应用权限变化后，通常需要重新发布应用版本，或等待管理员审批。权限未生效时，Bridge 可能能启动，但收不到消息或无法回复。