feishu-file-upload（飞书文件上传）

Feishu File Upload

Upload local files to Feishu Drive and send as file messages to chats or users.

When to Use

• User asks to "send file", "upload file", or "share file" to Feishu
• Need to share documents (CSV, PDF, Excel, Word) with group or individual
• Bot needs to send files that Feishu's native message API doesn't support directly
• Images/videos: Use media parameter in message tool instead (no need for this skill)

Quick Start

Send to Group Chat

python scripts/upload_to_feishu.py /path/to/file.csv oc_xxxxxx --type chat_id

Send to Individual User

python scripts/upload_to_feishu.py /path/to/file.pdf ou_xxxxxx --type open_id

Send via Email

python scripts/upload_to_feishu.py /path/to/file.zip user@example.com --type email

Use Environment Variable

export OPENCLAW_CHAT_ID=oc_xxxxxx
python scripts/upload_to_feishu.py /path/to/file.csv --env

How It Works

1. Read credentials from ~/.openclaw/openclaw.json (channels.feishu.appId/appSecret)
2. Get tenant access token from Feishu Auth API
3. Upload file to Feishu Drive → returns file_key
4. Send file message using file_key to target chat/user

Script Usage

Arguments

*Not required if --env is used

Receive ID Types

Extract Chat ID from Feishu Message

From Feishu message metadata:

{
  "conversation_label": "oc_06a6b40e03e98e41c8aebcbed8b09871"
}

→ receive_id = oc_06a6b40e03e98e41c8aebcbed8b09871, type = chat_id

From sender info:

{
  "sender_id": "ou_b0f83ea276761ab10ebb3f4f277453b8"
}

→ receive_id = ou_b0f83ea276761ab10ebb3f4f277453b8, type = open_id

Prerequisites

• Python 3.6+
• requests library: pip install requests
• Feishu bot credentials in openclaw.json

Feishu API Permissions

Bot needs these permissions in Feishu Developer Console:

Required for file upload:

• im:resource:upload - Upload files (preferred)
• OR im:resource - Read and upload files

Required for sending messages:

• im:message - Send messages to chats

How to Enable Permissions

1. Open Feishu Developer Console: https://open.feishu.cn/app/YOUR_APP_ID/auth
2. Search for im:resource:upload or im:resource
3. Click "Apply" and enable the permission
4. Wait a few minutes for permission to take effect

Quick link: https://open.feishu.cn/app/cli_a94a21db99385bd8/auth?q=im:resource:upload,im:resource

File Size Limits

• Single file: 30MB max (Feishu API limit)
• Large files may take longer to upload

Supported File Types

All file types supported by Feishu Drive:

Error Handling

Script handles:

• Missing credentials → Error message
• File not found → Error message
• Upload failure → API error details
• Send failure → API error details
• Missing permissions → Clear error with fix link

Testing

# Test with a small file to a group chat
python scripts/upload_to_feishu.py /tmp/test.txt oc_xxxxxx --type chat_id

# Test sending to yourself (find your open_id from message metadata)
python scripts/upload_to_feishu.py /tmp/test.pdf ou_xxxxxx --type open_id

Troubleshooting

"Access denied" / "99991672"

• Bot lacks im:resource:upload or im:resource permission
• Open: https://open.feishu.cn/app/cli_a94a21db99385bd8/auth?q=im:resource:upload,im:resource
• Enable permission and wait a few minutes

"Bot/User can NOT be out of the chat (230002)"

• Bot is not a member of the target group chat
• Add bot to the chat, or send to a different chat

"Invalid receive_id"

• Check the ID format matches the type
• chat_id starts with oc_
• open_id starts with ou_
• user_id is numeric
• email must be valid email format

Upload fails for large files

• Feishu API limit is 30MB
• Compress file or use Feishu Drive web interface for larger files

Alternative: Manual Upload

If script fails, user can manually:

1. Upload file to Feishu Drive via web/app
2. Share file with the chat
3. Bot can then reference the file

Security Notes

• Credentials read from openclaw.json (local only)
• Token expires after ~2 hours (auto-refreshed each run)
• Files uploaded to Feishu Drive follow Feishu's security policies
• Script does not store or transmit credentials

Comparison with Message Tool

Recommendation: Use media parameter for images/videos, use this skill for documents and other files.