Feishu File Operations

飞书文件操作：发送文件到对话、创建和写入飞书云文档。适用于需要通过飞书 Bot API 发送文件或创建文档的场景。

飞书文件操作指南

本技能提供通过飞书 Bot API 发送文件和创建/写入云文档的完整方法。

🌟 推荐方式：OpenClaw CLI（最简单）

OpenClaw 内置 message send 命令支持 --media 参数发送文件：

bash

openclaw message send --channel feishu --target ou_xxx --media "/path/to/file.md" --message "文件说明"

参数说明：

• --channel feishu - 使用飞书渠道
• --target - 接收者 ID（open_id 如 ou_xxx，或群聊 ID）
• --media - 本地文件路径或 URL
• --message - 可选，附带文字说明

支持的媒体类型：

• 图片（jpg, png, gif, webp）
• 音频（mp3, wav, ogg 等）
• 视频（mp4, mov 等）
• 文档（pdf, doc, docx, md, txt 等）

优点：

• 无需手动获取 token
• 自动处理文件上传
• 支持所有 OpenClaw 渠道（Telegram、Discord、WhatsApp 等）

---

备选方式：直接调用飞书 API

适用于需要在其他程序中调用或需要更精细控制的场景。

前置条件

• 飞书应用已启用，有 appId 和 appSecret
• 需要的权限：
  • im:file - 发送文件消息
  • docx:document - 创建和编辑云文档
  • drive:drive - 云空间访问

一、获取 Tenant Access Token

所有 API 调用都需要先获取 tenant_access_token：

bash

curl -s -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \
  -H "Content-Type: application/json" \
  -d '{
    "app_id": "YOUR_APP_ID",
    "app_secret": "YOUR_APP_SECRET"
  }'

返回示例：

json

{
  "code": 0,
  "tenant_access_token": "t-gxxxxx",
  "expire": 7200
}

二、发送文件到飞书对话

步骤 1：上传文件获取 file_key

bash

curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN" \
  -F "file=@/path/to/file.md" \
  -F "file_name=文件名.md" \
  -F "file_type=doc"

参数说明：

• file: 本地文件路径（使用 @ 前缀）
• file_name: 显示的文件名
• file_type: 文件类型（doc/stream 等）

返回示例：

json

{
  "code": 0,
  "data": {
    "file_key": "file_v3_00100_xxx"
  }
}

步骤 2：发送文件消息

bash

curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receive_id": "ou_xxx",
    "msg_type": "file",
    "content": "{\"file_key\":\"file_v3_00100_xxx\"}"
  }'

重要提示：

• ⚠️ receive_id_type 必须作为查询参数传递，不能放在 JSON body 中！
• 放在 body 中会报错："receive_id_type is required"

receive_id_type 可选值：

• open_id - 用户 open_id（如 ou_xxx）
• user_id - 用户 user_id
• union_id - 用户 union_id
• chat_id - 群聊 ID

三、创建和写入飞书云文档

步骤 1：创建文档

bash

curl -X POST "https://open.feishu.cn/open-apis/docx/v1/documents" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "文档标题"
  }'

返回示例：

json

{
  "code": 0,
  "data": {
    "document": {
      "document_id": "EqOQdnxWqoUW9JxL8RRckUeYn3y",
      "title": "文档标题"
    }
  }
}

步骤 2：获取文档根 block_id

bash

curl -X GET "https://open.feishu.cn/open-apis/docx/v1/documents/$DOCUMENT_ID/blocks" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN"

返回的根 block_id 通常与 document_id 相同。

步骤 3：写入内容

bash

curl -X POST "https://open.feishu.cn/open-apis/docx/v1/documents/$DOCUMENT_ID/blocks/$ROOT_BLOCK_ID/children" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "children": [
      {
        "block_type": 2,
        "text": {
          "elements": [
            {
              "text_run": {
                "content": "这是第一段文字内容"
              }
            }
          ]
        }
      },
      {
        "block_type": 3,
        "heading1": {
          "elements": [
            {
              "text_run": {
                "content": "这是一级标题"
              }
            }
          ]
        }
      }
    ],
    "index": 0
  }'

block_type 说明：

值	类型
1	页面（Page）
2	文本（Text）
3	一级标题（Heading1）
4	二级标题（Heading2）
5	三级标题（Heading3）
6	四级标题（Heading4）
7	五级标题（Heading5）
8	六级标题（Heading6）
10	无序列表（Bullet）
11	有序列表（Ordered）
12	代码块（Code）
13	引用（Quote）

四、文档分享

飞书文档 URL 格式：

text

https://[domain].feishu.cn/docx/[document_id]

例如：https://tt-pc.feishu.cn/docx/EqOQdnxWqoUW9JxL8RRckUeYn3y

可以通过消息发送文档链接：

bash

curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \
  -H "Authorization: Bearer $TENANT_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "receive_id": "ou_xxx",
    "msg_type": "text",
    "content": "{\"text\":\"文档链接：https://xxx.feishu.cn/docx/xxx\"}"
  }'

五、常见错误

1. receive_id_type is required

原因： receive_id_type 放在了 JSON body 中

解决： 将 receive_id_type 作为查询参数传递：

text

POST /open-apis/im/v1/messages?receive_id_type=open_id

2. 权限不足

原因： 飞书应用缺少相应权限

解决： 在飞书开放平台为应用添加所需权限

3. Token 过期

原因： tenant_access_token 有效期约 2 小时

解决： 重新调用获取 token 的 API

六、完整示例（OpenClaw exec 调用）

bash

# 1. 获取 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":"cli_xxx","app_secret":"xxx"}' | jq -r '.tenant_access_token')

# 2. 上传文件
FILE_KEY=$(curl -s -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file=@/path/to/file.md" \
  -F "file_name=file.md" \
  -F "file_type=doc" | jq -r '.data.file_key')

# 3. 发送文件
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\":\"ou_xxx\",\"msg_type\":\"file\",\"content\":\"{\\\"file_key\\\":\\\"$FILE_KEY\\\"}\"}"

七、参考资料

• 飞书开放平台：https://open.feishu.cn/
• 发送消息 API：https://open.feishu.cn/document/server-docs/im-v1/message/create
• 云文档 API：https://open.feishu.cn/document/server-docs/docs/docx-v1/document

---

本技能由 OpenClaw 龙虾创建，适用于飞书 Bot 文件操作场景