翻了一下 OpenClaw PR #75581，Host-Mediated Attachment 的設計思路比我想的更有意思
最近在追 OpenClaw 的 GitHub，看到 PR #75581 合進去了，標題是「Add host-mediated session attachments」。乍看覺得只是個小功能，翻了一下 diff 發現規模不小——39 個檔案，+1769 / -48，而且改動的層面蠻深的。
整理一下我看完之後覺得值得討論的部分。
問題是什麼？
原本 bundled plugin 如果想發附件，要自己處理各個 channel 的發送邏輯。這聽起來沒什麼問題，但實際上等於每個 plugin 都要自己知道「現在跑在哪個 channel 上」「這個 channel 支援哪種格式」「檔案要怎麼傳」。這些邏輯重複性高，而且 plugin 不應該直接掌控 channel 層的發送——那是 host 的責任範圍。
PR 的描述裡有一句話：讓 plugin 可以「請 host 驗證本地檔案並透過當前 session route 發送附件」。這個設計把權限邊界切得更清楚：plugin 只負責說「我有這個檔案要發」，host 決定要不要發、怎麼發。
SDK 面的 API 設計
新增的 API 是 sendSessionAttachment，加在 OpenClawPluginApi 上，同時有 SDK export。
這個命名我覺得蠻準確的。session 在這裡有明確意義——附件是透過「當前 session 的 route」發送，不是 plugin 自己建立連線。Attachment 而不是 File 也是刻意的——它帶著 delivery 語意，不只是資料傳輸。
Host 端的 Validation 層
這是我覺得最值得細看的部分。Host 端加了幾層防護：
size / count limits：限制單次附件的數量和大小。這種限制放在 host 端而不是 plugin 端是對的，因為 plugin 沒有辦法知道目標 channel 的實際限制。
symlink 防護：不追 symlink。這防的是 plugin 用 symlink 繞過路徑限制來讀到本來不該碰的檔案。翻了一下，這類防護在 file serving 相關的 PR 裡算是常見的 hardening 手段。
MIME 驗證：不信任副檔名，從檔案內容推斷 MIME type。這個如果之前沒做，其實蠻容易被用來傳不預期格式的東西。
delivery-route lookup hardening：確保 route 在發送時是有效的，防止用 stale registry 的資訊去發。這個細節有點意思——表示他們之前有遇過或預期會遇到 route 資訊過期的問題。
bundled-plugin enforcement：這個限制是說，sendSessionAttachment 只開放給 bundled plugin 用，不是所有 plugin 都能呼叫。這把 surface area 限縮了，比較好審計。
Channel 特定的 Hints
PR 裡有提到 Telegram 和 Slack 相關的 attachment hints，包括：
- Telegram：
silent、force-document、caption 的 parse-mode 優先序 - Slack：thread hint support
force-document 這個 hint 以前想用的話，plugin 要自己想辦法。現在透過 hint 的方式讓 plugin 可以表達意圖，host 再翻譯成各 channel 的格式。這個抽象層我覺得是對的方向——plugin 說「我要當 document 不是 preview」，不需要知道 Telegram API 裡面叫什麼。
caption 的 parse-mode 優先序也是個有點隱晦的改動。之前如果 caption 裡有 Markdown，但 parse-mode 沒設對，Telegram 那邊會直接顯示原始標記符號。這次應該是把這個邏輯統一了，減少 edge case。
非目標也值得看
PR 的描述裡有明確列出「這次不做什麼」：scheduled turns、finalization retry/run-context lifecycle、tool-derived paths 等。
這種寫法我蠻欣賞的——明確劃定邊界，表示這個 PR 是一條 seam，後續還有更多東西要疊上來。workflow stack 的拆解不是一次到位，而是先建立這個「host 驗證 + route 發送」的接縫，其他功能之後再接上去。
整體感想
這個 PR 讓我想到 capability-based security 的概念——與其給 plugin 直接的 channel access，不如讓它透過 host 請求能力，由 host 做授權和驗證。規模 +1769 行看起來多，但大部分應該在 validation logic 和測試上，核心的 API surface 其實很窄。
在 PR 裡看到測試指令有 plugin contract test 和 telegram api test，表示這個改動有對應的整合測試覆蓋，不只是 unit test。對於這種跨層的改動，這個測試策略是必要的。
有在寫 OpenClaw plugin 的人可以開始關注 sendSessionAttachment 這個 API，應該是之後附件相關功能的標準路徑。
作者：jiaweiOrz