vultr/openclaw
1
0
Fork 0
mirror of https://github.com/openclaw/openclaw.git synced 2026-05-06 04:50:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(slack): document attachment vision behavior and known limits

Browse Source 
Adds a Slack attachment vision reference covering downloaded media handling, PDF/file limits, thread-starter media fallback, multi-attachment behavior, and known troubleshooting cases.

Fixes #51355

Thanks @haroldfabla2-hue.
This commit is contained in:
Alberto Farah Blair
2026-04-28 22:12:44 -05:00
committed by GitHub
parent 5847c0ed58
commit aa03c5be82
1 changed files with 65 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

65
docs/channels/slack.md
View File

@@ -899,6 +899,71 @@ openclaw pairing list slack
</Accordion>
</AccordionGroup>
## Attachment vision reference
Slack can attach downloaded media to the agent turn when Slack file downloads succeed and size limits permit. Image files can be passed through the media understanding path or directly to a vision-capable reply model; other files are retained as downloadable file context rather than treated as image input.
### Supported media types
| Media type | Source | Current behavior | Notes |
| ------------------------------ | -------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| JPEG / PNG / GIF / WebP images | Slack file URL | Downloaded and attached to the turn for vision-capable handling | Per-file cap: `channels.slack.mediaMaxMb` (default 20 MB) |
| PDF files | Slack file URL | Downloaded and exposed as file context for tools such as `download-file` or `pdf` | Slack inbound does not convert PDFs into image-vision input automatically |
| Other files | Slack file URL | Downloaded when possible and exposed as file context | Binary files are not treated as image input |
| Thread replies | Thread starter files | Root-message files can be hydrated as context when the reply has no direct media | File-only starters use an attachment placeholder |
| Multi-image messages | Multiple Slack files | Each file is evaluated independently | Slack processing is capped at eight files per message |
### Inbound pipeline
When a Slack message with file attachments arrives:
1. OpenClaw downloads the file from Slack's private URL using the bot token (`xoxb-...`).
2. The file is written to the media store on success.
3. Downloaded media paths and content types are added to the inbound context.
4. Image-capable model/tool paths can use image attachments from that context.
5. Non-image files remain available as file metadata or media references for tools that can handle them.
### Thread-root attachment inheritance
When a message arrives in a thread (has a `thread_ts` parent):
- If the reply itself has no direct media and the included root message has files, Slack can hydrate the root files as thread-starter context.
- Direct reply attachments take precedence over root-message attachments.
- A root message that has only files and no text is represented with an attachment placeholder so the fallback can still include its files.
### Multi-attachment handling
When a single Slack message contains multiple file attachments:
- Each attachment is processed independently through the media pipeline.
- Downloaded media references are aggregated into the message context.
- Processing order follows Slack's file order in the event payload.
- A failure in one attachment's download does not block others.
### Size, download, and model limits
- **Size cap**: Default 20 MB per file. Configurable via `channels.slack.mediaMaxMb`.
- **Download failures**: Files that Slack cannot serve, expired URLs, inaccessible files, oversize files, and Slack auth/login HTML responses are skipped instead of being reported as unsupported formats.
- **Vision model**: Image analysis uses the active reply model when it supports vision, or the image model configured at `agents.defaults.imageModel`.
### Known limits
| Scenario | Current behavior | Workaround |
| -------------------------------------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Expired Slack file URL | File skipped; no error shown | Re-upload the file in Slack |
| Vision model not configured | Image attachments are stored as media references, but not analyzed as images | Configure `agents.defaults.imageModel` or use a vision-capable reply model |
| Very large images (> 20 MB by default) | Skipped per size cap | Increase `channels.slack.mediaMaxMb` if Slack allows |
| Forwarded/shared attachments | Text and Slack-hosted image/file media are best-effort | Re-share directly in the OpenClaw thread |
| PDF attachments | Stored as file/media context, not automatically routed through image vision | Use `download-file` for file metadata or the `pdf` tool for PDF analysis |
### Related documentation
- [Media understanding pipeline](/nodes/media-understanding)
- [PDF tool](/tools/pdf)
- Epic: [#51349](https://github.com/openclaw/openclaw/issues/51349) — Slack attachment vision enablement
- Regression tests: [#51353](https://github.com/openclaw/openclaw/issues/51353)
- Live verification: [#51354](https://github.com/openclaw/openclaw/issues/51354)
## Related
<CardGroup cols={2}>