feishu-send-file

Lark ファイル／画像送信スキル

クイックスタート

1. 設定ファイル

設定ファイルのサンプルをコピーします：

cd ~/.openclaw/workspace/skills/feishu-send-file
cp config.json.example config.json
# 使用你喜欢的编辑器修改 config.json

設定を入力します：

{
  "app_id": "cli_xxxxxxxxxxxxxxxx",
  "app_secret": "your_app_secret_here",
  "receive_id": "ou_xxxxxxxxxxxxxxxx",
  "message_mode": "send"
}

設定の説明：

フィールド	説明	例
app_id	Lark アプリ ID	cli_xxxxxxxxxxxxxxxx
app_secret	Lark アプリのシークレット	xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
receive_id	受信者の Open ID	ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
message_mode	メッセージモード：send = 直接送信	send

⚠️ 重要：このスクリプトは送信モード (send) のみをサポートし、返信モード (reply) はサポートしていません。メッセージが返信としてマークされるのを防ぐためです。

セキュリティに関する注意：

• config.json は .gitignore に追加されているため、誤って Git にコミットされることはありません
• ファイルに認証情報を保存しないよう、環境変数の使用をおすすめします

2. メッセージを送信する

cd ~/.openclaw/workspace/skills/feishu-send-file

# 发送文本
./scripts/send-message.sh text "你好主人！"

# 发送 Markdown 卡片
./scripts/send-message.sh card "**加粗** 和 *斜体*"

# 发送图片
./scripts/send-message.sh image "/path/to/photo.png"

# 发送语音（opus格式）
./scripts/send-message.sh audio "/path/to/voice.opus"

# 发送视频
./scripts/send-message.sh video "/path/to/video.mp4"

# 发送文件
./scripts/send-message.sh file "/path/to/document.pdf"

3. 環境変数を使用する方法（推奨）

環境変数を使用して設定ファイルの値を一時的に上書きします：

export FEISHU_APP_ID="cli_xxx"
export FEISHU_APP_SECRET="xxx"
export FEISHU_RECEIVE_ID="ou_xxx"

./scripts/send-message.sh text "消息内容"

優先順位：環境変数 > 設定ファイル

---

⚠️ CRITICAL：OpenClaw の自動返信の落とし穴

問題の説明

OpenClaw のメッセージ返信機能は、応答をユーザーメッセージに自動的に関連付けるため、「送信」ではなく「返信」になってしまいます！

curl で API を呼び出した場合でも、最後に OpenClaw の通常の返信出力を経由すると、システムによって has_reply_context: true とマークされることがあります。

解決策：独立したスクリプトを使用する

OpenClaw の返信機能を完全に迂回するため、必ず付属の独立したスクリプト send-message.sh を使用してください：

# ✅ 正确：使用独立脚本（绕过 OpenClaw 回复）
./scripts/send-message.sh text "你好主人！"
./scripts/send-message.sh image "/path/to/image.png"
./scripts/send-message.sh audio "/path/to/voice.opus"

次の方法は使用しないでください：

# ❌ 错误：即使 curl 成功，最后通过 OpenClaw 回复输出，仍会变成「回复」
curl -X POST ...
echo "发送成功"  # 这行输出会被 OpenClaw 标记为回复

---

⚠️ 重要な警告

1. メッセージの送信と返信

必ず「メッセージ送信」API を使用してください。「メッセージ返信」API と混在させないでください

用途	API	URL	説明
✅ メッセージ送信	メッセージ送信	POST /im/v1/messages	このスキルで使用します。メッセージを直接送信します
❌ メッセージ返信	メッセージ返信	POST /im/v1/messages/:message_id/reply	使用しません。指定したメッセージへの返信に使用します

正しいメッセージ送信 URL：

POST https://open.feishu.cn/open-apis/im/v1/messages?receive_id_type=open_id

誤ったメッセージ返信 URL：

# 不要用这个！
POST https://open.feishu.cn/open-apis/im/v1/messages/:message_id/reply

2. 2 段階の手順が必須です

Lark でファイル／画像を送信するには、2 段階の手順が必須です。どちらの手順も省略できません！

❌ 誤った方法：message API を使ってファイルパスを直接送信する ✅ 正しい方法：まずアップロードして file_key／image_key を取得し、そのキーを使ってメッセージを送信する

3 種類の API の違い

種類	アップロード API	メッセージタイプ	返されるキー	用途
画像	/im/v1/images	image	image_key	jpg/png/gif などの画像
ファイル	/im/v1/files	file	file_key	ドキュメント、圧縮ファイルなど
音声	/im/v1/files	audio/file	file_key	opus/mp3 音声
動画	/im/v1/files	media	file_key	mp4 動画
スタンプ	/im/v1/images	image	image_key	png/gif スタンプ

画像の送信手順

1 番目：画像をアップロードして image_key を取得する

curl -X POST "https://open.feishu.cn/open-apis/im/v1/images" \
  -H "Authorization: Bearer $TOKEN" \
  -F "image_type=message" \
  -F "image=@/path/to/image.jpg"

応答例：

{
  "code": 0,
  "data": {
    "image_key": "img_v3_02ve_xxxx-xxxx-xxxx-xxxx"
  }
}

重要なポイント：

• image_type は message にする必要があります
• image では @ 記号を使ってローカル画像のパスを指定します
• 返された image_key を保存します。次の手順で使用します

2 番目：画像メッセージを送信する

curl -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_xxxxxx",
    "msg_type": "image",
    "content": "{\"image_key\":\"img_v3_02ve_xxxx-xxxx-xxxx-xxxx\"}"
  }'

ファイルの送信手順

1 番目：ファイルをアップロードして file_key を取得する

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

応答例：

{
  "code": 0,
  "data": {
    "file_key": "file_v3_00ve_xxxx-xxxx-xxxx-xxxx"
  }
}

重要なポイント：

• file_type は stream にする必要があります
• file_name には拡張子を含める必要があります
• file では @ 記号を使ってローカルファイルのパスを指定します

2 番目：ファイルメッセージを送信する

curl -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_xxxxxx",
    "msg_type": "file",
    "content": "{\"file_key\":\"file_v3_00ve_xxxx-xxxx-xxxx-xxxx\"}"
  }'

パラメーターの詳細

tenant_access_token の取得

すべての API 呼び出しでは、最初にトークンを取得する必要があります：

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

receive_id_type の選択肢

種類	説明	例
open_id	ユーザー固有の識別子（推奨）	ou_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
user_id	ユーザー ID	user_xxxxx
union_id	統合 ID	on_xxxxx
email	メールアドレス	[email protected]
chat_id	グループチャット ID	oc_xxxxx

スクリプトを使った自動送信

このスキルには自動化スクリプトが含まれています：

画像を送信する

./scripts/send-image.sh <app_id> <app_secret> <receive_id> <image_path>

ファイルを送信する

./scripts/send-file.sh <app_id> <app_secret> <receive_id> <file_path>

音声を送信する

./scripts/send-audio.sh <app_id> <app_secret> <receive_id> <audio_path>

環境変数を使用する方法

export FEISHU_APP_ID="cli_xxxxx"
export FEISHU_APP_SECRET="xxxxx"
./scripts/send-image.sh "" "" "ou_xxxxx" "/path/to/image.jpg"
./scripts/send-file.sh "" "" "ou_xxxxx" "/path/to/file.pdf"
./scripts/send-audio.sh "" "" "ou_xxxxx" "/path/to/voice.opus"

よくあるエラー

エラー	原因	解決方法
field validation failed	receive_id_type が指定されていません	URL に ?receive_id_type=open_id を追加してください
invalid file_key	file_key の形式が誤っているか、有効期限が切れています	ファイルを再アップロードして新しいキーを取得してください
invalid image_key	image_key の形式が誤っているか、有効期限が切れています	画像を再アップロードして新しいキーを取得してください
permission denied	アプリに権限がありません	アプリの権限設定を確認してください
user not found	receive_id が正しくありません	ID の種類と値が正しいことを確認してください

クイック判定：画像 API とファイル API のどちらを使う？

• 画像 API (`/im/v1/images)：jpg、jpeg、png、gif、bmp、webp などの画像形式
• ファイル API (`/im/v1/files)：pdf、doc、docx、xls、xlsx、zip など、その他すべてのファイル
• 音声 API (`/im/v1/files)：opus、mp3 などの音声形式

音声メッセージの送信手順

Lark の音声メッセージではファイルアップロード API を使用しますが、いくつかの特別な要件があります：

音声形式の要件

形式	file_type	msg_type	説明
opus	opus	audio	最適な形式です。そのまま再生できます
mp3	opus	file	ファイルとして送信する互換形式です

音声メッセージを送信する

方法 1：スクリプトを使用する（推奨）

# 环境变量方式
export FEISHU_APP_ID="cli_xxxxx"
export FEISHU_APP_SECRET="xxxxx"

# 发送语音
./scripts/send-audio.sh "" "" "ou_xxxxx" "/path/to/voice.opus"

方法 2：curl を手動で使用する

1 番目：音声をアップロードして file_key を取得する

curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_type=opus" \
  -F "file_name=voice.opus" \
  -F "file=@/path/to/voice.opus"

応答例：

{
  "code": 0,
  "data": {
    "file_key": "file_v3_00ve_xxxx-xxxx-xxxx-xxxx"
  }
}

2 番目：音声メッセージを送信する

curl -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_xxxxx",
    "msg_type": "audio",
    "content": "{\"file_key\":\"file_v3_00ve_xxxx-xxxx-xxxx-xxxx\"}"
  }'

重要なポイント：

• file_type は opus（推奨）または stream に設定します
• msg_type を audio に設定すると音声メッセージとして表示され、file に設定するとファイルとして表示されます
• 互換性を高めるため、音声ファイルには opus 形式をおすすめします

音声形式の変換

mp3 形式のファイルがある場合は、ffmpeg を使って変換できます：

# mp3 转 opus
ffmpeg -i input.mp3 -c:a libopus -b:a 32k output.opus

# 或者直接用 mp3 发送（作为文件类型）
# file_type=stream, msg_type=file

---

動画メッセージの送信手順 ⭐

Lark の動画メッセージでは media メッセージタイプを使用し、mp4 形式をサポートしています。

動画形式の要件

パラメーター	要件
形式	mp4
サイズ	最大 500MB
アップロード API	/im/v1/files
file_type	mp4

動画を送信する

スクリプトを使用する

export FEISHU_APP_ID="cli_xxxxx"
export FEISHU_APP_SECRET="xxxxx"

# 发送视频（可选封面图）
./scripts/send-video.sh "" "" "ou_xxxxx" "/path/to/video.mp4" "/path/to/thumb.jpg"

curl を手動で使用する

1 番目：動画をアップロードする

curl -X POST "https://open.feishu.cn/open-apis/im/v1/files" \
  -H "Authorization: Bearer $TOKEN" \
  -F "file_type=mp4" \
  -F "file=@/path/to/video.mp4"

2 番目：動画を送信する

curl -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_xxxxx",
    "msg_type": "media",
    "content": "{\"file_key\":\"file_v3_00ve_xxxx\",\"image_key\":\"img_v3_02ve_xxxx\"}"
  }'

注意：動画メッセージにはカバー画像 image_key を含めることができます（任意）

---

表情包发送流程 ⭐

飞书表情包本质上是图片消息，但可以显示为可收藏的表情样式。

表情包类型

类型	说明	方法
Emoji 字符	😸🎉🐱 等	直接发送文本消息
图片表情	png/gif 图片	发送图片消息

发送表情包

方式一：Emoji 字符（最简单）

# 发送包含 emoji 的文本
curl -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_xxxxx",
    "msg_type": "text",
    "content": "{\"text\":\"😸🎉🐱👍\"}"
  }'

方式二：使用脚本发送图片表情

export FEISHU_APP_ID="cli_xxxxx"
export FEISHU_APP_SECRET="xxxxx"

# 发送图片作为表情包
./scripts/send-sticker.sh "" "" "ou_xxxxx" "/path/to/sticker.png"

方式三：手动 curl 发送图片表情

# 上传表情图片
curl -X POST "https://open.feishu.cn/open-apis/im/v1/images" \
  -H "Authorization: Bearer $TOKEN" \
  -F "image_type=message" \
  -F "image=@/path/to/sticker.png"

# 发送图片（显示为表情样式）
curl -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_xxxxx",
    "msg_type": "image",
    "content": "{\"image_key\":\"img_v3_02ve_xxxx\"}"
  }'

---

检查清单

发送前确认：

• 已获取 tenant_access_token
• 已判断使用图片API还是文件API
• 已上传并获取 image_key 或 file_key
• URL包含 ?receive_id_type=xxx
• msg_type 设置正确（image/file/audio/media）
• content 包含正确的 key
• receive_id 与 receive_id_type 匹配

各类型消息检查表

消息类型	file_type	msg_type	需要 Key
图片	-	image	image_key
文件	stream	file	file_key
语音	opus	audio	file_key
视频	mp4	media	file_key (+ 可选 image_key)
表情包	-	image	image_key

参考文档

• 上传图片API: https://open.feishu.cn/document/server-docs/im-v1/image/create
• 上传文件API: https://open.feishu.cn/document/server-docs/im-v1/file/create
• 发送消息API: https://open.feishu.cn/document/server-docs/im-v1/message/create
• 完整消息类型指南: MESSAGE_TYPES.md