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#

bash

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

Send to Individual User#

bash

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

Send via Email#

bash

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

Use Environment Variable#

bash

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#

ArgumentRequiredDefaultDescriptionfile_pathYes-Absolute path to local filereceive_idYes*-Recipient ID (chat_id, open_id, user_id, or email)--typeNochat_idRecipient type: chat_id, open_id, user_id, email``--envNofalseGet receive_id from OPENCLAW_CHAT_ID env var

*Not required if --env is used

Receive ID Types#

TypeExampleUse Casechat_id``oc_06a6b40e03e98e41c8aebcbed8b09871Group chats (default)open_id``ou_b0f83ea276761ab10ebb3f4f277453b8Individual user (recommended)user_id``123456Individual user (by user_id)email``user@example.comSend to email address

Extract Chat ID from Feishu Message#

From Feishu message metadata:

json

{
  "conversation_label": "oc_06a6b40e03e98e41c8aebcbed8b09871"
}

→ receive_id = oc_06a6b40e03e98e41c8aebcbed8b09871, type = chat_id

From sender info:

json

{
  "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:

CategoryExtensionsDocumentsPDF, DOC, DOCX, XLS, XLSX, PPT, PPTXImagesJPG, PNG, GIF, WEBPArchivesZIP, RAR, 7ZCode/TextTXT, MD, JSON, CSV, XML, PY, JSMediaMP3, MP4, WAV (auto-converted to OPUS)

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#

bash

# 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#

FeatureThis SkillMessage Tool mediaDocuments (PDF, CSV, etc.)✅ Supported❌ Not supportedImages✅ Supported✅ Supported (easier)Videos✅ Supported✅ Supported (easier)File size limit30MBVaries by platformComplexity2 API calls1 API call

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