\r \r

飞书文件/图片发送 Skill\r

\r

快速开始\r

\r

1. 配置文件\r

\r 复制示例配置文件：\r \r

cd ~/.openclaw/workspace/skills/feishu-send-file\r
cp config.json.example config.json\r
# 使用你喜欢的编辑器修改 config.json\r
```\r
\r
**填入你的配置：**\r
\r
```json\r
{\r
  "app_id": "cli_xxxxxxxxxxxxxxxx",\r
  "app_secret": "your_app_secret_here",\r
  "receive_id": "ou_xxxxxxxxxxxxxxxx",\r
  "message_mode": "send"\r
}\r
```\r
\r
**配置说明：**\r
| 字段 | 说明 | 示例 |\r
|------|------|------|\r
| `app_id` | 飞书应用ID | `cli_xxxxxxxxxxxxxxxx` |\r
| `app_secret` | 飞书应用密钥 | `xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |\r
| `receive_id` | 接收人Open ID | `ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |\r
| `message_mode` | 消息模式：`send` = 直接发送 | `send` |\r
\r
**⚠️ 重要**：本脚本**只支持发送模式** (`send`)，不支持回复模式 (`reply`)，避免消息被标记为回复。\r
\r
**安全提示：**\r
- `config.json` 已被添加到 `.gitignore`，不会意外提交到 Git\r
- 建议使用环境变量方式，避免在文件中存储凭证\r
\r
### 2. 发送消息\r
\r
```bash\r
cd ~/.openclaw/workspace/skills/feishu-send-file\r
\r
# 发送文本\r
./scripts/send-message.sh text "你好主人！"\r
\r
# 发送 Markdown 卡片\r
./scripts/send-message.sh card "**加粗** 和 *斜体*"\r
\r
# 发送图片\r
./scripts/send-message.sh image "/path/to/photo.png"\r
\r
# 发送语音（opus格式）\r
./scripts/send-message.sh audio "/path/to/voice.opus"\r
\r
# 发送视频\r
./scripts/send-message.sh video "/path/to/video.mp4"\r
\r
# 发送文件\r
./scripts/send-message.sh file "/path/to/document.pdf"\r
```\r
\r
### 3. 环境变量方式（推荐）\r
\r
使用环境变量临时覆盖配置文件：\r
\r
```bash\r
export FEISHU_APP_ID="cli_xxx"\r
export FEISHU_APP_SECRET="xxx"\r
export FEISHU_RECEIVE_ID="ou_xxx"\r
\r
./scripts/send-message.sh text "消息内容"\r
```\r
\r
**优先级：环境变量 > 配置文件**\r
\r
---\r
\r
## ⚠️ CRITICAL: OpenClaw 自动回复陷阱\r
\r
### 问题描述\r
\r
**OpenClaw 的消息回复机制会自动将响应关联到用户消息，导致变成「回复」而不是「发送」！**\r
\r
即使你用 `curl` 调用 API，如果最后通过 OpenClaw 的 normal 回复输出，系统仍可能标记为 `has_reply_context: true`。\r
\r
### 解决方案：使用独立脚本\r
\r
**必须** 使用提供的独立脚本 `send-message.sh`，它完全绕过 OpenClaw 的回复机制：\r
\r
```bash\r
# ✅ 正确：使用独立脚本（绕过 OpenClaw 回复）\r
./scripts/send-message.sh text "你好主人！"\r
./scripts/send-message.sh image "/path/to/image.png"\r
./scripts/send-message.sh audio "/path/to/voice.opus"\r
```\r
\r
**不要** 这样做：\r
```bash\r
# ❌ 错误：即使 curl 成功，最后通过 OpenClaw 回复输出，仍会变成「回复」\r
curl -X POST ...\r
echo "发送成功"  # 这行输出会被 OpenClaw 标记为回复\r
```\r
\r
---\r
\r
## ⚠️ 重要警告\r
\r
### 1. 发送消息 vs 回复消息\r
\r
**必须使用「发送消息」API，不要混用「回复消息」API**\r
\r
| 用途 | API | URL | 说明 |\r
|------|-----|-----|------|\r
| **✅ 发送消息** | 发送消息 | `POST /im/v1/messages` | 本技能使用，直接发送消息 |\r
| **❌ 回复消息** | 回复消息 | `POST /im/v1/messages/:message_id/reply` | **不使用**，用于回复指定消息 |\r
\r
**正确的发送消息 URL：**\r
```bash\r
POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id\r
```\r
\r
**错误的回复消息 URL：**\r
```bash\r
# 不要用这个！\r
POST https://open.feishu.cn/open-apis/im/v1/messages/:message_id/reply\r
```\r
\r
### 2. 必须使用两步流程\r
\r
**飞书发送文件/图片必须使用两步流程，一步都不能少！**\r
\r
❌ 错误方式：直接通过 message API 发送文件路径\r
✅ 正确方式：先上传获取 `file_key`/`image_key`，再用 key 发送消息\r
\r
## 三种API的区别\r
\r
| 类型 | 上传API | 消息类型 | 返回key | 适用场景 |\r
|------|---------|----------|---------|----------|\r
| **图片** | `/im/v1/images` | `image` | `image_key` | jpg/png/gif等图片 |\r
| **文件** | `/im/v1/files` | `file` | `file_key` | 文档、压缩包等 |\r
| **语音** | `/im/v1/files` | `audio`/`file` | `file_key` | opus/mp3音频 |\r
| **视频** | `/im/v1/files` | `media` | `file_key` | mp4视频 |\r
| **表情包** | `/im/v1/images` | `image` | `image_key` | png/gif表情包 |\r
\r
## 图片发送流程\r
\r
### 第一步：上传图片获取 image_key\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/images" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "image_type=message" \\r
  -F "image=@/path/to/image.jpg"\r
```\r
\r
**响应示例：**\r
```json\r
{\r
  "code": 0,\r
  "data": {\r
    "image_key": "img_v3_02ve_xxxx-xxxx-xxxx-xxxx"\r
  }\r
}\r
```\r
\r
**关键点：**\r
- `image_type` 必须是 `message`\r
- `image` 使用 `@` 符号指定本地图片路径\r
- 保存返回的 `image_key`，下一步要用\r
\r
### 第二步：发送图片消息\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxxx",\r
    "msg_type": "image",\r
    "content": "{\"image_key\":\"img_v3_02ve_xxxx-xxxx-xxxx-xxxx\"}"\r
  }'\r
```\r
\r
## 文件发送流程\r
\r
### 第一步：上传文件获取 file_key\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "file_type=stream" \\r
  -F "file_name=文件名.md" \\r
  -F "file=@/path/to/file"\r
```\r
\r
**响应示例：**\r
```json\r
{\r
  "code": 0,\r
  "data": {\r
    "file_key": "file_v3_00ve_xxxx-xxxx-xxxx-xxxx"\r
  }\r
}\r
```\r
\r
**关键点：**\r
- `file_type` 必须是 `stream`\r
- `file_name` 必须包含扩展名\r
- `file` 使用 `@` 符号指定本地文件路径\r
\r
### 第二步：发送文件消息\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxxx",\r
    "msg_type": "file",\r
    "content": "{\"file_key\":\"file_v3_00ve_xxxx-xxxx-xxxx-xxxx\"}"\r
  }'\r
```\r
\r
## 完整参数说明\r
\r
### 获取 tenant_access_token\r
\r
所有API调用都需要先获取令牌：\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/auth/v3/tenant_access_token/internal" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "app_id": "cli_xxxxx",\r
    "app_secret": "xxxxx"\r
  }'\r
```\r
\r
### receive_id_type 选项\r
\r
| 类型 | 说明 | 示例 |\r
|------|------|------|\r
| `open_id` | 用户的唯一标识（推荐） | `ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |\r
| `user_id` | 用户ID | `user_xxxxx` |\r
| `union_id` | 统一ID | `on_xxxxx` |\r
| `email` | 邮箱 | `[email protected]` |\r
| `chat_id` | 群聊ID | `oc_xxxxx` |\r
\r
## 使用脚本自动发送\r
\r
本skill包含自动化脚本：\r
\r
### 发送图片\r
```bash\r
./scripts/send-image.sh \x3Capp_id> \x3Capp_secret> \x3Creceive_id> \x3Cimage_path>\r
```\r
\r
### 发送文件\r
```bash\r
./scripts/send-file.sh \x3Capp_id> \x3Capp_secret> \x3Creceive_id> \x3Cfile_path>\r
```\r
\r
### 发送语音\r
```bash\r
./scripts/send-audio.sh \x3Capp_id> \x3Capp_secret> \x3Creceive_id> \x3Caudio_path>\r
```\r
\r
### 环境变量方式\r
```bash\r
export FEISHU_APP_ID="cli_xxxxx"\r
export FEISHU_APP_SECRET="xxxxx"\r
./scripts/send-image.sh "" "" "ou_xxxxx" "/path/to/image.jpg"\r
./scripts/send-file.sh "" "" "ou_xxxxx" "/path/to/file.pdf"\r
./scripts/send-audio.sh "" "" "ou_xxxxx" "/path/to/voice.opus"\r
```\r
\r
## 常见错误\r
\r
| 错误 | 原因 | 解决 |\r
|------|------|------|\r
| `field validation failed` | 缺少 `receive_id_type` | URL必须加 `?receive_id_type=open_id` |\r
| `invalid file_key` | file_key格式错误或已过期 | 重新上传文件获取新key |\r
| `invalid image_key` | image_key格式错误或已过期 | 重新上传图片获取新key |\r
| `permission denied` | 应用没有权限 | 检查应用权限设置 |\r
| `user not found` | receive_id错误 | 确认ID类型和值正确 |\r
\r
## 快速判断：用图片API还是文件API？\r
\r
- **图片API** (`/im/v1/images`): jpg, jpeg, png, gif, bmp, webp 等图片格式\r
- **文件API** (`/im/v1/files`): pdf, doc, docx, xls, xlsx, zip, 等其他所有文件\r
- **语音API** (`/im/v1/files`): opus, mp3 等音频格式\r
\r
## 语音消息发送流程\r
\r
飞书语音消息使用文件上传 API，但有一些特殊要求：\r
\r
### 音频格式要求\r
\r
| 格式 | file_type | msg_type | 说明 |\r
|------|-----------|----------|------|\r
| `opus` | `opus` | `audio` | 最佳格式，直接播放 |\r
| `mp3` | `opus` | `file` | 兼容发送，作为文件 |\r
\r
### 发送语音消息\r
\r
#### 方式一：使用脚本（推荐）\r
\r
```bash\r
# 环境变量方式\r
export FEISHU_APP_ID="cli_xxxxx"\r
export FEISHU_APP_SECRET="xxxxx"\r
\r
# 发送语音\r
./scripts/send-audio.sh "" "" "ou_xxxxx" "/path/to/voice.opus"\r
```\r
\r
#### 方式二：手动 curl\r
\r
**第一步：上传音频获取 file_key**\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "file_type=opus" \\r
  -F "file_name=voice.opus" \\r
  -F "file=@/path/to/voice.opus"\r
```\r
\r
**响应示例：**\r
```json\r
{\r
  "code": 0,\r
  "data": {\r
    "file_key": "file_v3_00ve_xxxx-xxxx-xxxx-xxxx"\r
  }\r
}\r
```\r
\r
**第二步：发送语音消息**\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxx",\r
    "msg_type": "audio",\r
    "content": "{\"file_key\":\"file_v3_00ve_xxxx-xxxx-xxxx-xxxx\"}"\r
  }'\r
```\r
\r
**关键点：**\r
- `file_type` 设置为 `opus`（推荐）或 `stream`\r
- `msg_type` 设置为 `audio` 显示为语音消息，或 `file` 显示为文件\r
- 音频文件建议为 opus 格式，兼容性最好\r
\r
### 音频格式转换\r
\r
如果手头是 mp3 格式，可以使用 ffmpeg 转换：\r
\r
```bash\r
# mp3 转 opus\r
ffmpeg -i input.mp3 -c:a libopus -b:a 32k output.opus\r
\r
# 或者直接用 mp3 发送（作为文件类型）\r
# file_type=stream, msg_type=file\r
```\r
\r
---\r
\r
## 视频消息发送流程 ⭐\r
\r
飞书视频消息使用 `media` 消息类型，支持 mp4 格式。\r
\r
### 视频格式要求\r
\r
| 参数 | 要求 |\r
|------|------|\r
| 格式 | mp4 |\r
| 大小 | 最大 500MB |\r
| 上传 API | `/im/v1/files` |\r
| file_type | `mp4` |\r
\r
### 发送视频\r
\r
#### 使用脚本\r
\r
```bash\r
export FEISHU_APP_ID="cli_xxxxx"\r
export FEISHU_APP_SECRET="xxxxx"\r
\r
# 发送视频（可选封面图）\r
./scripts/send-video.sh "" "" "ou_xxxxx" "/path/to/video.mp4" "/path/to/thumb.jpg"\r
```\r
\r
#### 手动 curl\r
\r
**第一步：上传视频**\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "file_type=mp4" \\r
  -F "file=@/path/to/video.mp4"\r
```\r
\r
**第二步：发送视频**\r
\r
```bash\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxx",\r
    "msg_type": "media",\r
    "content": "{\"file_key\":\"file_v3_00ve_xxxx\",\"image_key\":\"img_v3_02ve_xxxx\"}"\r
  }'\r
```\r
\r
**注意**：视频消息可包含封面图 `image_key`（可选）\r
\r
---\r
\r
## 表情包发送流程 ⭐\r
\r
飞书表情包本质上是图片消息，但可以显示为可收藏的表情样式。\r
\r
### 表情包类型\r
\r
| 类型 | 说明 | 方法 |\r
|------|------|------|\r
| Emoji 字符 | 😸🎉🐱 等 | 直接发送文本消息 |\r
| 图片表情 | png/gif 图片 | 发送图片消息 |\r
\r
### 发送表情包\r
\r
#### 方式一：Emoji 字符（最简单）\r
\r
```bash\r
# 发送包含 emoji 的文本\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxx",\r
    "msg_type": "text",\r
    "content": "{\"text\":\"😸🎉🐱👍\"}"\r
  }'\r
```\r
\r
#### 方式二：使用脚本发送图片表情\r
\r
```bash\r
export FEISHU_APP_ID="cli_xxxxx"\r
export FEISHU_APP_SECRET="xxxxx"\r
\r
# 发送图片作为表情包\r
./scripts/send-sticker.sh "" "" "ou_xxxxx" "/path/to/sticker.png"\r
```\r
\r
#### 方式三：手动 curl 发送图片表情\r
\r
```bash\r
# 上传表情图片\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/images" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -F "image_type=message" \\r
  -F "image=@/path/to/sticker.png"\r
\r
# 发送图片（显示为表情样式）\r
curl -X POST "https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id" \\r
  -H "Authorization: Bearer $TOKEN" \\r
  -H "Content-Type: application/json" \\r
  -d '{\r
    "receive_id": "ou_xxxxx",\r
    "msg_type": "image",\r
    "content": "{\"image_key\":\"img_v3_02ve_xxxx\"}"\r
  }'\r
```\r
\r
---\r
\r
## 检查清单\r
\r
发送前确认：\r
\r
- [ ] 已获取 `tenant_access_token`\r
- [ ] 已判断使用图片API还是文件API\r
- [ ] 已上传并获取 `image_key` 或 `file_key`\r
- [ ] URL包含 `?receive_id_type=xxx`\r
- [ ] `msg_type` 设置正确（image/file/audio/media）\r
- [ ] `content` 包含正确的 key\r
- [ ] `receive_id` 与 `receive_id_type` 匹配\r
\r
### 各类型消息检查表\r
\r
| 消息类型 | file_type | msg_type | 需要 Key |\r
|----------|-----------|----------|----------|\r
| 图片 | - | `image` | `image_key` |\r
| 文件 | `stream` | `file` | `file_key` |\r
| 语音 | `opus` | `audio` | `file_key` |\r
| 视频 | `mp4` | `media` | `file_key` (+ 可选 `image_key`) |\r
| 表情包 | - | `image` | `image_key` |\r
\r
## 参考文档\r
\r
- 上传图片API: https://open.feishu.cn/document/server-docs/im-v1/image/create\r
- 上传文件API: https://open.feishu.cn/document/server-docs/im-v1/file/create\r
- 发送消息API: https://open.feishu.cn/document/server-docs/im-v1/message/create\r
- 完整消息类型指南: `MESSAGE_TYPES.md`\r