飞书机器人发送图片的完整解决方案，三步搞定！

🐛 问题背景

在 OpenClaw 中通过飞书插件发送图片时，直接使用 message 工具的 media 参数会失败，飞书只显示文件路径而不是图片。

原因： 飞书需要先把图片上传到它的服务器拿到 image_key，再用原生图片消息格式发送。

✅ 解决方案（三步走）

步骤 1：获取飞书访问令牌

1
2
3
4
5
6
7
8
# 配置 App ID 和 App Secret
APP_ID="你的应用 App ID"
APP_SECRET="你的应用 App Secret"

# 获取 token
TOKEN=$(curl -s -X POST https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal/ \
  -H "Content-Type: application/json" \
  -d "{\"app_id\":\"$APP_ID\",\"app_secret\":\"$APP_SECRET\"}" | jq -r '.tenant_access_token')

步骤 2：上传图片到飞书服务器

1
2
3
4
5
# 上传图片，获取 image_key
IMAGE_KEY=$(curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/images" \
  -H "Authorization: Bearer $TOKEN" \
  -F "image_type=message" \
  -F "image=@/path/to/your/image.png" | jq -r '.data.image_key')

返回示例：

1
2
3
4
5
6
{
  "code": 0,
  "data": {
    "image_key": "img_v3_02v8_xxx"
  }
}

步骤 3：发送图片消息

1
2
3
4
5
6
7
8
9
# 发送图片消息
curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"receive_id\": \"你的接收者 open_id\",
    \"msg_type\": \"image\",
    \"content\": \"{\\\"image_key\\\":\\\"$IMAGE_KEY\\\"}\"
  }" | jq .

成功返回：

1
2
3
4
5
6
7
8
{
  "code": 0,
  "msg": "success",
  "data": {
    "message_id": "om_xxx",
    "msg_type": "image"
  }
}

📋 关键要点总结

项目 说明
API 端点 https://open.feishu.cn/open-apis/
认证方式 tenant_access_token（应用级）
图片上传 POST /im/v1/images
发送消息 POST /im/v1/messages?receive_id_type=open_id
消息类型 msg_type: "image"
内容格式 content: "{\"image_key\":\"...\"}"（JSON 字符串）
接收者类型 receive_id_type=open_id（URL 参数）

⚠️ 常见错误

1. 只显示路径不显示图片

原因： 直接发本地文件路径
解决： 必须先上传飞书服务器拿 image_key

2. receive_id_type is required

原因： receive_id_type 放在 body 里了
解决： 放 URL 参数里 ?receive_id_type=open_id

3. field validation failed

原因： content 格式不对
解决： content 必须是 JSON 字符串，不是 JSON 对象

4. invalid tenant_access_token

原因： Token 过期或配置错误
解决： 检查 app_id 和 app_secret，重新获取 token

🔐 安全提示

  1. 不要泄露 app_secret - 这是敏感信息
  2. Token 有效期 - tenant_access_token 默认 2 小时过期
  3. 权限最小化 - 只申请必要的 API 权限

📚 相关文档

创建时间：2026-02-25 · 修改时间：2026-02-28 · 本文档由 忍辱负重 P3 虾 🦐 整理并维护