Fix: "Max Payload Size Exceeded" When Sending Images in OpenClaw

TL;DR: OpenClaw's webchat WebSocket has a 512KB payload limit. Your image (after base64 encoding) exceeds that. Resize the image, raise the limit, or use a different channel.

The Error

Error: Max payload size exceeded (524288 bytes)

You might also see:

WebSocket connection closed: 1009 (Message Too Big)

RangeError: Max payload size exceeded
  at Receiver._getPayloadLength (ws/lib/receiver.js:...)

Error: Frame size of 847392 exceeds maximum of 524288

Why This Happens

When you send an image through OpenClaw's webchat interface, the image is sent as a base64-encoded string over a WebSocket connection. Two things conspire against you:

1. Base64 encoding inflates size by ~33%. A 400KB image becomes ~533KB after base64 encoding. A 300KB photo from your phone? That's ~400KB encoded.

2. The WebSocket server has a hardcoded 512KB (524,288 bytes) payload limit. This is the default in the ws library that OpenClaw uses for its webchat.

So any image larger than roughly 380KB will fail after base64 encoding pushes it past the 512KB limit. Modern phone cameras shoot photos that are 2-8MB, so... yeah, almost every photo will fail.

This only affects the webchat channel. Telegram, WhatsApp, and Discord handle images through their own APIs and don't have this limitation.

(GitHub #8211)

How to Fix It

Option A: Resize images before sending

The simplest workaround — make the image smaller before you send it.

On the command line:

# Using ImageMagick — resize to max 800px wide, quality 80
convert input.jpg -resize 800x -quality 80 output.jpg

# Using ffmpeg
ffmpeg -i input.jpg -vf scale=800:-1 -q:v 5 output.jpg

Target size: Keep images under 350KB to stay safely under the 512KB limit after base64 encoding.

In a web app (if you've built a custom frontend):

// Resize before sending via WebSocket
function resizeImage(file, maxWidth = 800) {
  return new Promise((resolve) => {
    const canvas = document.createElement('canvas');
    const ctx = canvas.getContext('2d');
    const img = new Image();
    img.onload = () => {
      const ratio = maxWidth / img.width;
      canvas.width = maxWidth;
      canvas.height = img.height * ratio;
      ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
      canvas.toBlob(resolve, 'image/jpeg', 0.8);
    };
    img.src = URL.createObjectURL(file);
  });
}

Option B: Increase the WebSocket payload limit

If you can modify OpenClaw's source, you can raise the limit. Find the WebSocket server initialization (usually in the webchat channel code):

# Find the WebSocket config
grep -r "maxPayload" ~/.config/openclaw/ /usr/lib/openclaw/ node_modules/openclaw/ 2>/dev/null

Look for something like:

const wss = new WebSocket.Server({
  port: 3000,
  maxPayload: 512 * 1024  // 512KB — this is the limit
});

Change it to a larger value:

const wss = new WebSocket.Server({
  port: 3000,
  maxPayload: 10 * 1024 * 1024  // 10MB
});

Or if there's a config option:

{
  "channels": {
    "webchat": {
      "maxPayloadSize": 10485760
    }
  }
}

Then restart:

openclaw gateway restart

Warning: Raising the limit means your server will accept larger payloads into memory. If you're running on a small VPS, be mindful of memory usage — a few concurrent 10MB uploads could cause issues.

Option C: Send images via URL instead of inline

If your images are already hosted somewhere (or you can upload them), send the URL instead of the raw image data:

Check out this image: https://your-host.com/photos/image.jpg

OpenClaw can fetch and process image URLs without going through the WebSocket payload limit. This is how Telegram and Discord handle large files — the image lives on their CDN, and only the URL is sent in the message.

Option D: Use a different channel

This problem is specific to webchat. If you're hitting it frequently, consider using Telegram or Discord instead — they handle images natively through their own APIs with much higher limits:

• Telegram: Up to 10MB for photos, 50MB for files
• Discord: Up to 25MB (8MB on free tier)
• WhatsApp: Up to 16MB for images

How to Prevent It

• Default to Telegram or Discord for image-heavy interactions. The webchat WebSocket was designed for text messages, not file transfer.
• If you must use webchat, add client-side image compression. Most UI frameworks have image resize libraries — use them before sending.
• Set up a reverse proxy (nginx, caddy) in front of the webchat WebSocket. This lets you handle file uploads via HTTP POST (with proper multipart support) instead of cramming everything into a WebSocket frame.

The Easy Way

lobsterfarm is a managed hosting service for OpenClaw — deployment, updates, and support handled for you.

Get started with lobsterfarm →