Feishu IM Tool
Use the message tool with channel=feishu for all IM operations.
Send Text Message
message(action=send, channel=feishu, target=<user_id or chat_id>, message="text")
Send Image (CORRECT method)
Always use filePath or media, never paste a raw path in message text.
message(action=send, channel=feishu, target=<chat_id>, filePath="/absolute/path/to/image.jpg")
Or with caption:
message(action=send, channel=feishu, target=<chat_id>, media="/path/to/image.jpg", message="caption text")
The tool handles the two-step upload internally:
- POST /im/v1/images → get image_key
- POST /im/v1/messages with image_key
Common Failure Modes — Images Show as Path/Link
See references/image-sending-pitfalls.md for full diagnosis.
TL;DR root causes:
- Assistant wrote raw file path in message text instead of calling
messagetool → plain text, no upload - Used
MEDIA:/absolute/path→ security filter strips it image_typewrong during upload (must bemessage, notavatar)tenant_access_tokenexpired (TTL ~2h) → upload silently fails, key is empty- Webhook custom bot used instead of Bot App → no access_token, can't upload images
Permissions Required
| Scope | Purpose |
|---|---|
im:resource | Upload image/file to IM, get file_key / image_key |
im:message | Send messages with media |
im:message:send_as_bot | Send as bot identity |
All three are currently granted on this installation.
Bot Type Comparison
| Feature | Webhook Custom Bot | Bot App (自建应用) |
|---|---|---|
| Send text | ✅ | ✅ |
| Send image | ⚠️ base64 only (不推荐) | ✅ via image_key |
| access_token | ❌ 无 | ✅ tenant_access_token |
| Upload API | ❌ 不支持 | ✅ /im/v1/images |
OpenClaw uses Bot App — always use the message tool, not raw Webhook POST.
Token Refresh
tenant_access_token expires in ~2 hours. If uploads silently fail:
- Error code
99991663= image_key invalid - Error code
99991400= token expired
OpenClaw refreshes tokens automatically on each API call. If you see these errors, check Gateway logs.
References
references/image-sending-pitfalls.md— detailed failure mode diagnosis- Feishu API docs: https://open.feishu.cn/document/server-docs/im-v1/image/create