openclaw - 💡(How to fix) Fix Proposal: native Telegram file/attachment send support via messaging abstraction [1 participants]

Summary

OpenClaw currently has a gap between:

• receiving Telegram attachments,
• generating local files in the workspace,
• and sending those generated files back to the user through native messaging.

This often pressures agents toward bad workarounds like direct Bot API calls via shell/curl, which bypass OpenClaw routing and safety boundaries.

I’d like to propose a native messaging-level attachment/file-send capability for Telegram, designed in a provider-neutral way.

Recommended v1 scope

Keep the first version intentionally small:

• support document
• support photo
• support workspace-relative file paths only

Defer for later:

• video
• audio
• grouped media
• arbitrary external URLs
• non-file upload sources

Proposed interface direction

Prefer extending the native messaging abstraction rather than adding a Telegram-only ad hoc tool.

Example shape:

message.send({
  chatId,
  text?,
  media: {
    kind: 'document' | 'photo',
    filePath: 'relative/path/from/workspace.pdf',
    filename?: 'report.pdf',
    mimeType?: 'application/pdf',
    caption?: 'Here is the file',
  },
  replyToMessageId?: '12345',
})

Telegram v1 mapping:

• document -> sendDocument
• photo -> sendPhoto

Security boundary

For v1, I’d strongly recommend:

• allow workspace-relative paths only
• reject absolute paths by default
• reject .. path escapes
• optionally support explicit allowlisted OpenClaw-managed media roots later

Provider-side checks before upload:

1. resolve path against workspace root
2. ensure resolved path is still inside allowed root
3. ensure file exists
4. ensure file size is allowed
5. optionally verify MIME consistency

Field responsibility

• filePath: source file to upload
• filename: optional display/upload name
• mimeType: optional hint; may be inferred if omitted
• caption: optional caption attached to the media message
• replyToMessageId: preserve reply context when supported

For v1, caption should preferably stay attached to the media message rather than being split into a separate text message.

Recommended normalized errors

• FILE_NOT_FOUND
• DISALLOWED_PATH
• FILE_TOO_LARGE
• MIME_MISMATCH
• PROVIDER_UPLOAD_FAILED
• CHAT_NOT_REACHABLE
• INVALID_REPLY_TARGET

Why this matters

Without a native path, agents are pushed toward:

• shell-based Telegram API usage
• bypassing provider abstraction
• inconsistent safety behavior
• weaker channel portability

A native messaging capability keeps:

• routing consistent
• safety boundaries clearer
• agent behavior more aligned with OpenClaw design

Practical recommendation

If implemented, this should probably be treated as:

• a messaging capability extension,
• not as an exec/curl workaround,
• and not as a Telegram-only hack embedded in prompts.