飞书转发消息读取器

核心用法

飞书转发消息读取器（feishu-forward-reader）是专为 OpenClaw 生态设计的消息解析工具，用于处理飞书平台特有的 merge_forward 消息类型。当用户收到合并转发消息时，系统默认仅显示 "Merged and Forwarded Message" 占位文本，此 skill 通过调用飞书开放平台的 im/v1/messages API，递归获取被转发的原始消息列表，还原完整对话内容。

使用方法支持三种模式：Python 脚本（推荐，支持自动凭证读取、JSON 输出、用户名查询优化）、Shell 脚本（轻量级原始输出）、直接 API 调用（开发者调试）。凭证优先级为命令行参数 > 环境变量 > OpenClaw 配置文件，已配置飞书插件的用户可零配置使用。

显著优点

1. 无缝集成 OpenClaw：自动读取 ~/.openclaw/openclaw.json 配置，无需重复设置凭证
2. 多格式输出支持：提供人类可读的格式化文本与机器友好的 JSON 两种输出模式
3. 智能用户名解析：可选查询用户真实姓名，平衡信息完整性与调用效率
4. 广泛消息类型兼容：覆盖 text/post/interactive/image/file/audio/video 等主流消息格式

潜在缺点与局限性

• 敏感权限依赖：必须申请 im:message:readonly 权限，可获取群组全部消息，存在隐私合规风险
• 飞书生态锁定：仅适配飞书开放平台 API，无法迁移至企业微信、钉钉等平台
• 嵌套层级限制：当前实现针对单层合并转发，未明确支持多层转发递归解析
• 可见性边界：群外成员用户名无法解析，显示截断 ID

适合人群

• 使用 OpenClaw 对接飞书的企业运维/开发者
• 需要审计、归档群聊转发内容的合规人员
• 构建飞书消息自动化工作流的集成工程师

常规风险

| 风险类型 | 说明 | 缓解措施 |

|---------|------|---------|

| 凭证泄露 | App Secret 硬编码或日志泄露 | 优先使用环境变量或配置文件，避免命令行暴露 |

| 权限滥用 | `im:message:readonly` 可读取全部消息 | 最小权限原则，定期审计应用授权范围 |

| API 限流 | 高频调用触发飞书速率限制 | 实现指数退避重试，缓存用户 ID 映射 |

| 数据留存 | 转发内容可能含敏感信息 | 遵循企业数据分级策略，设置自动清理周期 |

核心用法

feishu-forward-reader 是一款专门解决飞书合并转发消息内容读取问题的实用技能。当飞书消息在 OpenClaw 中显示为 "Merged and Forwarded Message" 时，该技能通过调用飞书官方 Open API 获取转发消息的完整子消息列表，还原原始对话内容。

技能提供三种使用方式：Python 脚本（推荐）支持自动凭证读取、JSON 格式输出、跳过用户名查询等选项；Shell 脚本提供轻量级原始 JSON 输出；也可直接调用飞书 REST API 进行自定义集成。凭证配置灵活，支持命令行参数、环境变量或 OpenClaw 配置文件三种来源，已与飞书插件配置兼容。

技能完整解析 merge_forward 消息结构，自动识别父消息与子消息的关联关系（通过 upper_message_id），支持 text、post、interactive、image、file、audio、video 等 7 种消息类型的格式化输出。

显著优点

官方 API 保障：完全基于飞书开放平台官方接口，数据来源可靠，API 稳定性与长期维护有保障。网络行为高度可控，仅向 open.feishu.cn 域名发起 HTTPS 请求。

安全凭证管理：无硬编码密钥风险，支持多层次凭证获取优先级，与现有 OpenClaw 飞书插件配置无缝衔接。生产环境推荐环境变量方式，符合安全运维最佳实践。

消息解析全面：不仅支持纯文本，还完整支持富文本（post）、卡片消息（interactive）等复杂格式，图片、文件、语音、视频等媒体类型也有清晰的占位提示。

输出格式友好：默认生成易读的时间线格式，包含发信人、时间戳和内容；可选 JSON 输出便于程序化处理；用户名显示支持通过 contact API 解析真实姓名。

潜在缺点与局限性

依赖飞书应用权限：需要申请 im:message:readonly 敏感权限，该权限需通过飞书开放平台审核，小型团队或个人开发者可能面临权限申请门槛。

用户画像范围限制：仅可见范围内的用户可显示真实姓名，范围外用户显示 ID 前缀，这在跨租户或外部群场景下可能影响阅读体验。

API 速率限制：飞书开放平台对 API 调用有频率限制，高频消息解析场景下可能触发限流，需要实现重试或缓存机制。

无持久化存储：技能本身不保存历史解析结果，每次查询均为实时 API 调用，断网或 API 故障时无法离线查看。

适合的目标群体

• 企业运营人员：需要查看客户或同事转发的群聊记录，快速了解上下文背景
• 客服与售后团队：处理用户反馈时，解析用户转发的历史对话，提升问题定位效率
• 项目管理角色：追踪跨群讨论的关键决策过程，整理会议纪要素材
• 飞书生态开发者：作为 OpenClaw 飞书插件的配套工具，补充消息解析能力
• 数据合规审计：在授权范围内提取结构化消息记录，支持合规审查场景

使用风险与注意事项

性能风险：实时调用飞书 API 存在网络延迟，批量处理大量消息时建议添加异步或并发控制；--no-names 参数可在无需用户名时减少约 30% 的 API 调用量。

凭证泄露风险：虽然技能本身无硬编码密钥，但用户需自行保管 App ID 和 App Secret，避免提交至公共代码仓库或日志系统。建议配置文件设置 600 权限。

权限变更风险：飞书开放平台可能调整 API 权限要求或接口版本，需关注官方公告及时更新。当前依赖的 im:message:readonly 属于较敏感权限，存在未来收紧审核的可能。

数据隐私边界：技能仅提供读取能力，不存储或转发数据，但使用者需确保在组织授权范围内操作，避免越权访问非管辖群组的对话内容。