feishu-fetch

下载飞书群聊中收到的 file / image / audio 消息附件到本地。

何时使用

• 群里收到 file 消息，需要下载到本地处理
• 用户要求读取、转发、转换收到的附件
• message.read 工具对 file 消息只返回占位符，需要 fallback

不处理发送消息（那是另一个 skill 的事）。如果需要"下载-上传-转发"链路，本 skill 只负责下载第一步。

调用方式

首选：通过脚本

bash ~/.openclaw/skills/feishu-fetch/scripts/feishu-fetch.sh \x3Cmessage_id> [options]

或者在调用前 export AGENT_NAME=\x3Cname> 选择非 main 账户。

入参

输出

示例

# 默认：下载 file 消息到 /tmp/\x3C原文件名>
bash scripts/feishu-fetch.sh om_xxxxx

# 下载图片到指定路径
bash scripts/feishu-fetch.sh om_xxxxx --type image --output /tmp/photo.png

# 用非 main 账户（多 bot 场景）
AGENT_NAME=mala bash scripts/feishu-fetch.sh om_xxxxx

# 拿 key 而不下载（调试）
bash scripts/feishu-fetch.sh om_xxxxx --print-key

agent 拿 stdout 的路径继续后续处理（用 image 工具读图、feishu-send 转发等）。

thread / reply 注意事项

用户用文本消息 reply 一条 file 消息时：

• file 消息本体在 thread root（parent_id / root_id 指向）
• reply 的文本消息里没有 file_key

如果传进来的 message_id 拿不到 file_key：

1. 不要反复试 reply 链
2. 重新定位 file 消息本身：message.read 取 reply 消息的 root_id → 用 root_id 调本 skill
3. 实在拿不到 → 提示用户"消息链断了，请直接给我 file 消息的 message_id"

applink 链接

https://applink.feishu.cn/client/message/link/open?token=*** 里的 token 没有公开 API 反查到 message_id。

解法：

• 让用户直接给 message_id（最快）
• 或者用户重新发送文件到当前对话（不通过 reply 引用旧消息）
• 不要尝试 token 反查

凭据安全

不要：

• 把 appId / appSecret 硬编码在调用里 → 不行，凭据必须从 openclaw.json 读
• 把 file_key / token 打印到日志 / 返回值 → 脚本已做，正常流程不会泄露
• 用裸 curl -d 把 secret 放命令行 → 脚本内部已用 stdin/临时文件，secret 不会出现在 ps

如果需要调试 file_key，用 --print-key（仅自己看，不要入日志）。

错误码速查

范围边界

做：file / image / audio 三类资源下载

不做：

• 发消息（用其他 skill）
• 读云文档 / Drive / Bitable / Wiki
• applink token 反查 message_id
• 后台进程、长连接、polling
• 转发到任何非 open.feishu.cn 的域

与其他 skill 组合

本 skill 完成后可能接入的下游：

• feishu-send —— 上传 + 转发到其他群
• image 工具 —— 读图（--type image 下载后）
• pdf 工具 —— 读 PDF

具体组合由调用方按需拼装，本 skill 不假设任何特定下游。

安全

• appSecret 仅运行时从磁盘读，不入日志、不入返回值
• 临时文件由脚本 trap 清理（退出后自动删）
• tenant_access_token 2 小时自动过期，无需手动 rotation
• 主机被入侵时立即在飞书开放平台重置 appSecret
• 最小权限：飞书 app 后台只勾必要 scope（im:resource 等），不要 *:read 通配

OpenClaw 内部凭据

读 ~/.openclaw/openclaw.json：

{
  "channels": {
    "feishu": {
      "accounts": {
        "\x3Cagent_name>": {
          "appId": "cli_xxx",
          "appSecret": "..."
        }
      }
    }
  }
}

agent 名字优先级：--agent \x3Cname> > $AGENT_NAME 环境变量 > main 兜底。