Feishu Send Media
Send media files (images, documents, audio, video) directly to Feishu users or chats using the message tool.
Sending Media
Basic File Send
Use the message tool with action: send and path parameter:
CODEBLOCK0
Supported types:
- - Images:
.png, .jpg, .jpeg, .gif, INLINECODE8 - Documents:
.doc, .docx, .pdf, .txt, INLINECODE13 - Audio:
.mp3, .wav, INLINECODE16 - Video:
.mp4, INLINECODE18
Parameters:
- -
target: User open_id (e.g., ou_3ac66d1ad7b8c1xxxxxxxxxxxxxxs) or chat ID - INLINECODE22 : Absolute path to local file
- Optional
filename: Override display name
Sending to Group Chats
Use chat_id as target:
CODEBLOCK1
Inline Images
For images to display inline in the message (not as attachments), use the image parameter with base64:
CODEBLOCK2
High-Reliability Workflow (Recommended)
Follow these steps exactly for maximum success rate:
Step 1: Copy file to workspace (with deduplication)
CODEBLOCK3
Why overwrite (-f): Ensures fresh copy every time, avoids stale file issues.
Step 2: Get absolute path and validate
CODEBLOCK4
Step 3: Send with message tool
CODEBLOCK5
Step 4: Verify response
Check tool response:
- - ✅ Success:
"messageId" field present - ❌ Failure:
"error" field present
Automatic Error Recovery (Critical)
If Step 4 fails, automatically attempt fallbacks in order:
Fallback 1: Retry once with workspace path
CODEBLOCK6
Fallback 2: Use base64 for images (especially .png, .gif)
CODEBLOCK7
When to use: Path method fails, small images (<3MB), .png/.gif files
Fallback 3: Upload to Feishu drive then share
{
"action": "upload_file",
"doc_token": "xxx",
"file_path": "$abs_path"
}
Then send the returned file URL.
When to use: Files >20MB, persistent path failures
Error Handling Checklist
| Error | Cause | Solution |
|---|
| File not found | Wrong path | Verify source path exists |
| Permission denied |
File permission issue |
chmod 644 on file |
| Tool error | Feishu API issue | Retry → base64 → drive |
| Empty file | Zero-byte file | Check source before copying |
| File too large | >20MB | Use Feishu drive |
Quick Reference
| Scenario | Primary Method | Fallback 1 | Fallback 2 |
|---|
| Small image (<3MB) | path | base64 | - |
| Large image (3-20MB) |
path | base64 | drive |
| Document | path | drive | - |
| Audio/Video | path | drive | - |
| Very large (>20MB) | drive | - | - |
Mandatory Rules
- 1. ALWAYS copy to workspace first - Never send from /tmp, Downloads, or other临时路径
- ALWAYS verify copy succeeded - Check file exists before sending
- ALWAYS use absolute path - No relative paths in message tool
- ALWAYS attempt fallback on failure - Never give up after one try
- ALWAYS extract basename - Preserve original filename, don't rename
Feishu 发送媒体
使用 message 工具直接将媒体文件（图片、文档、音频、视频）发送给飞书用户或群聊。
发送媒体
基础文件发送
使用 message 工具，配合 action: send 和 path 参数：
json
{
action: send,
target: ouxxx, // 用户 openid 或 chat_id
path: /path/to/file.pdf
}
支持的文件类型：
- - 图片：.png、.jpg、.jpeg、.gif、.webp
- 文档：.doc、.docx、.pdf、.txt、.rtf
- 音频：.mp3、.wav、.m4a
- 视频：.mp4、.mov
参数说明：
- - target：用户的 openid（例如 ou3ac66d1ad7b8c1xxxxxxxxxxxxxxs）或群聊 ID
- path：本地文件的绝对路径
- 可选 filename：覆盖显示名称
发送到群聊
使用 chat_id 作为目标：
json
{
action: send,
target: oc_xxx, // 群聊 ID
path: /path/to/file.pdf
}
内嵌图片
如需在消息中内嵌显示图片（而非作为附件），请使用 image 参数配合 base64：
json
{
action: send,
target: ou_xxx,
image: data:image/png;base64,...
}
高可靠性工作流程（推荐）
请严格按照以下步骤操作以获得最高成功率：
步骤 1：将文件复制到工作区（含去重）
bash
从源路径提取文件名
filename=$(basename /source/path/to/file.png)
复制到工作区（如已存在则覆盖）
cp -f /source/path/to/file.png ~/.openclaw/workspace/${filename}
验证复制是否成功
if [ ! -f ~/.openclaw/workspace/${filename} ]; then
echo 错误：文件复制失败
exit 1
fi
为什么使用覆盖（-f）： 确保每次都是全新副本，避免文件过时问题。
步骤 2：获取绝对路径并验证
bash
获取绝对路径
abs_path=$(cd ~/.openclaw/workspace && pwd)/${filename}
验证文件存在且可读
if [ ! -r $abs_path ]; then
echo 错误：文件不可读：$abs_path
exit 1
fi
记录日志以便调试
echo 正在发送：$abs_path
步骤 3：使用 message 工具发送
json
{
action: send,
target: ou_xxx,
path: /Users/casia/.openclaw/workspace/filename.png
}
步骤 4：验证响应
检查工具响应：
- - ✅ 成功：存在 messageId 字段
- ❌ 失败：存在 error 字段
自动错误恢复（关键）
如果步骤 4 失败，请按顺序自动尝试以下备用方案：
备用方案 1：使用工作区路径重试一次
bash
有时是临时性故障，重试
cp -f /source/path/to/file.png ~/.openclaw/workspace/${filename}
重新发送
备用方案 2：对图片使用 base64（特别是 .png、.gif）
bash
转换为 base64
base64
string=$(base64 -i $abspath)
作为内嵌图片发送
{
action: send,
target: ou_xxx,
image: data:image/png;base64,${base64_string}
}
适用场景： 路径方式失败、小图片（<3MB）、.png/.gif 文件
备用方案 3：上传到飞书云盘后分享
json
{
action: upload_file,
doc_token: xxx,
file
path: $abspath
}
然后发送返回的文件 URL。
适用场景： 文件 >20MB、路径方式持续失败
错误处理清单
| 错误 | 原因 | 解决方案 |
|---|
| 文件未找到 | 路径错误 | 验证源路径是否存在 |
| 权限被拒绝 |
文件权限问题 | 对文件执行 chmod 644 |
| 工具错误 | 飞书 API 问题 | 重试 → base64 → 云盘 |
| 空文件 | 零字节文件 | 复制前检查源文件 |
| 文件过大 | >20MB | 使用飞书云盘 |
快速参考
| 场景 | 主要方法 | 备用方案 1 | 备用方案 2 |
|---|
| 小图片（<3MB） | 路径 | base64 | - |
| 大图片（3-20MB） |
路径 | base64 | 云盘 |
| 文档 | 路径 | 云盘 | - |
| 音频/视频 | 路径 | 云盘 | - |
| 超大文件（>20MB） | 云盘 | - | - |
强制规则
- 1. 始终先复制到工作区 - 切勿从 /tmp、Downloads 或其他临时路径发送
- 始终验证复制是否成功 - 发送前检查文件是否存在
- 始终使用绝对路径 - message 工具中不要使用相对路径
- 失败时始终尝试备用方案 - 不要尝试一次就放弃
- 始终提取 basename - 保留原始文件名，不要重命名
