Feishu File Sender

核心用法

Feishu File Sender 是 OpenClaw 生态的桥接型工具技能，专门解决飞书渠道原生不支持文件消息的架构缺口。通过直接调用飞书 OpenAPI，实现「本地文件 → 飞书云存储 → IM 消息」的完整链路。

典型场景：Agent 生成 Excel 报表、PDF 文档或图片后，自动触发该技能将文件投递到当前聊天会话，无需用户手动下载再上传。

使用方式

python3 scripts/feishu_file_sender.py --file /path/to/report.xlsx --receive-id oc_xxx

参数设计极简：仅 --file 为必填，接收方 ID 支持自动从环境变量读取或前缀智能识别（oc_/ou_/on_），降低集成成本。

显著优点

• 零配置感知：自动匹配当前工作区解析 agentId，从 ~/.openclaw/openclaw.json 读取对应凭证，无需硬编码
• 双 API 原子封装：内部完成「上传获取 file_key → 发送文件消息」两步，对外暴露单一命令接口
• 多身份类型兼容：支持 chat_id（群）、open_id（用户）、user_id 三种接收方标识
• 环境变量兜底：OPENCLAW_CHAT_ID 等变量支持无参调用，适合流水线场景

潜在缺点与局限性

• 凭证耦合强：依赖本地 OpenClaw 专属配置文件路径，非标准飞书 SDK 鉴权方式，迁移成本较高
• 单租户限制：仅支持通过 tenant access token 访问，未实现多租户动态切换
• 无重试与幂等：脚本级实现，未内置网络异常重试或重复发送防护
• 文件类型简化：默认 stream 类型，对飞书特殊的 opus 音频等场景未做细分适配
• 错误码依赖人工：230002（机器人未进群）等错误需用户自行排查，无自动修复建议

适合人群

• OpenClaw 平台用户：已深度使用 OpenClaw agent 框架的开发者
• 飞书企业自建应用开发者：拥有 appId/appSecret 管理权限的技术人员
• 自动化报表场景：需要将 Python/R 生成的数据文件自动投递到飞书群的 DevOps/数据团队

常规风险

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

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

| 凭证泄露 | `~/.openclaw/openclaw.json` 包含 appSecret，若文件权限 644 可能被同服务器用户读取 | 设置 600 权限，或使用密钥管理服务 |

| 越权发送 | 拿到凭证后可向任意飞书群发送文件，若 agent 被提示注入攻击可能滥用 | 绑定 agentId → 指定 accountId 的映射白名单 |

| 敏感文件外泄 | Agent 生成的临时文件可能含业务数据，上传后留存飞书云端 | 配置飞书应用的数据居留策略，定期清理 |

| 日志残留 | 脚本执行可能留下含 file_key 或 chat_id 的 shell history | 启用 HISTCONTROL=ignorespace 或使用子进程隔离 |

核心用法

feishu-file-sender 是专为 OpenClaw 生态设计的飞书文件发送补全工具。由于飞书渠道插件原生仅支持文本消息，该 skill 通过直接调用飞书 OpenAPI（上传+发送双接口）实现文件投递闭环。

关键执行流程：
1. 通过当前工作目录（cwd）匹配 OpenClaw 工作区，自动解析 agent ID
2. 从 ~/.openclaw/openclaw.json 读取对应飞书应用的 appId/appSecret
3. 调用 im/v1/files 上传文件获取 file_key
4. 调用 im/v1/messages 发送文件消息到指定会话

命令示例：

python3 scripts/feishu_file_sender.py \
  --file /path/to/report.xlsx \
  --receive-id oc_xxx

接收者 ID 支持自动识别前缀（oc_/ou_/on_），也可通过环境变量 OPENCLAW_CHAT_ID 注入。

---

显著优点

• 架构补位精准：填补 OpenClaw 飞书渠道的能力缺口，无需修改核心框架
• 自动凭证管理：智能读取 OpenClaw 配置文件，避免重复配置飞书应用
• 安全编码规范：无 eval/exec/system 等危险函数，无 SQL 注入风险
• 依赖极简：仅依赖标准库 + requests，无供应链攻击面
• HTTPS 全链路：所有 API 调用均走 TLS1.2+ 加密，符合企业合规要求
• MIT 开源协议：可自由 fork 定制，适合二次开发

---

潜在缺点与局限性

• T3 来源可信度：作者为个人开发者 wen-ai，无知名公司或基金会背书
• 凭证本地存储依赖：需确保 ~/.openclaw/openclaw.json 权限管控（建议 600）
• 飞书平台绑定：强依赖飞书 OpenAPI 稳定性，如遇平台限流或接口变更需适配
• 无内建重试机制：网络异常时需调用方自行处理重试
• 文件大小受限：受飞书平台 100MB 上传限制约束

---

适合人群

• OpenClaw 用户：需要将 agent 生成的文件（报表、图片、文档）自动发回飞书聊天
• 飞书企业用户：已通过飞书开放平台配置自建应用，具备 appId/appSecret
• 自动化工作流构建者：需要补齐"生成文件→投递到 IM"的最后一步
• 安全意识较强的团队：接受 T3 来源但要求代码可审计、无恶意行为

---

常规风险

| 风险类别 | 等级 | 说明 |

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

| 凭证泄露 | 低 | 配置文件需严格权限控制，建议 90 天轮换 appSecret |

| 机器人权限 | 低 | 需确保机器人已在目标群内，否则返回 230002 错误 |

| API 限流 | 中 | 高频场景需监控调用频率，遵守飞书平台策略 |

| 来源可信度 | 中 | T3 级个人项目，建议 fork 后自行维护关键更新 |

| 数据外泄 | 低 | 仅访问飞书官方域名，无第三方数据传输 |

故障排查要点：

• 230002 → 机器人不在群内，需添加机器人或更换会话
• 缺少凭证 → 检查 channels.feishu.accounts 及 agentId→accountId 绑定
• HTTP 错误 → 提取响应中的 log_id 联系飞书技术支持