b3os-telegram-file-deliverylisted

# b3rys Telegram File Delivery Telegram으로 **파일을 그대로 보내야 할 때** 쓰는 스킬이다. 팀에서 반복되는 실수 = "텔레그램에서 파일이 안 보내진다." 원인은 런타임의 `message`/첨부 도구가 파일 직접 첨부를 보안 제한으로 막거나(특히 OpenClaw/Forin 계열 `.html`), 첨부 경로/형식이 도구 제약에 안 맞는 것이다. **해법은 일관된다 — Telegram Bot API의 `sendDocument`를 직접 호출한다.** HTML만이 아니라 PDF·이미지·ZIP·CSV·로그 등 모든 파일에 동일하게 적용된다. ## 언제 쓰나 - `message`/reply 도구로 파일 첨부가 막히거나 실패할 때 (가장 흔한 케이스). - HTML 산출물을 ZIP으로 우회하지 않고 원본 그대로 보내고 싶을 때. - 보고서(PDF/HTML), 스크린샷(PNG/JPG), 데이터(CSV/JSON), 압축본(ZIP) 등 어떤 파일이든 텔레그램으로 보내야 할 때. ## 원칙 - 파일 전송이 도구로 막히면 ZIP/링크로 우회하기 **전에** 이 스킬(`sendDocument`)을 먼저 쓴다. - 외부 전송이므로 the team lead 또는 요청자의 명시 컨펌을 받은 뒤 보낸다. - bot token(봇 토큰), chat id(채팅방 ID), credential은 env/profile에서 읽고 stdout에 노출하지 않는다. - 성공 여부는 Telegram API 응답의 `ok`, `message_id`, 파일명만 보고한다. 토큰·전체 응답·chat id는 불필요하게 출력하지 않는다. ## 필요한 값 - `TELEGRAM_BOT_TOKEN`: ��낼 봇의 token (Hermes profile env, OpenClaw account env 등). - `TELEGRAM_CHAT_ID`: 대상 채팅방 또는 DM id. - 파일 경로: 실제 존재하는 파일. - 선택 caption: 짧게. ## 파일 형식별 MIME 타입 `document=@경로;type=<mime>` 로 명시하면 텔레그램이 올바르게 인식한다. (생략해도 대개 동작하지만 HTML 등은 명시 권장.) | 파일 | MIME | |---|---| | `.html` | `text/html` | | `.pdf` | `application/pdf` | | `.png` / `.jpg` | `image/png` / `image/jpeg` | | `.zip` | `application/zip` | | `.csv` | `text/csv` | | `.json` | `application/json` | | `.md` / `.txt` / `.log` | `text/plain` | ## 절차 1. 파일 확인 - 파일이 존재하는지, 비어있지 않은지(`[ -s 파일 ]`) 확인한다. - 민감정보·로컬 절대경로·토큰·비공개 데이터가 파일 안에 들어있지 않은지 빠르게 확인한다. 2. 전송 컨펌 - 외부 Telegram 전송이므로 보내기 전에