Die fest codierte Medien-Staging-Limitierung äußert sich in mehreren unterschiedlichen Fehlermustern:

Primäre Fehleräußerung

Beim Versuch, Mediendateien zu stagen oder zurückzugeben, die 5MB überschreiten, tritt der folgende Fehler auf:

Error: Media exceeds 5MB limit
    at MediaStore.validateSize (dist/store-CA7OW_2w.js:XX:XX)
    at MediaStore.stage (dist/store-CA7OW_2w.js:XX:XX)
    at MediaPipeline.processOutput (dist/store-CA7OW_2w.js:XX:XX)
    at async CodexAgent.handleToolResult (dist/store-CA7OW_2w.js:XX:XX)

Fehlerablauf während der Medienverarbeitung

Der Fehler tritt während der Staging-Validierungsphase der Medien-Pipeline auf, bevor eine kanalspezifische Limit-Auflösung stattfindet:

1. Erfassungsphase — Vom Agenten generierte oder empfangene Medien
2. Staging-Validierung — Fest codierte 5MB-Prüfung in dist/store-CA7OW_2w.js ← Fehlerstelle
3. Kanalauflösung — Kanal-/Agenten-Medienlimits (nie erreicht)
4. Zustellung — Ausgabe an den konfigurierten Kanal

Bedingungen, die das Problem auslösen

• Videogenerierungs-Workflows, die Dateien > 5MB erzeugen
• Kompositionen mit mehreren Bildern oder GIFs mit Frame-Daten, die den Schwellenwert überschreiten
• Audiodateien mit langer Dauer und hohen Abtastraten
• Jede Medien-Tool-Ausgabe, die über openclaw.media.stage() gestagt wird

Stilles Überschreibungsverhalten

Das fest codierte Limit überschreibt stillschweigend gültige Kanal-Konfigurationen. Benutzer, die dieses Verhalten beobachten, bemerken möglicherweise:

# Channel config specifies 25MB limit
openclaw config get channels.slack.media.maxBytes
# Output: 26214400 (25MB)

# But generated media still fails at 5MB threshold
openclaw run --tool video-generate --prompt "Generate a 30-second clip"
# Error: Media exceeds 5MB limit

Dies erzeugt ein irreführendes Erlebnis, bei dem konfigurierte Limits wirkungslos erscheinen.

Architektonisches Problem: Vorzeitiges Validierungstor

Die Ursache ist ein Validierungsreihenfolge-Problem in der OpenClaw-Medien-Pipeline-Architektur. Die gebündelte Runtime-Datei dist/store-CA7OW_2w.js enthält:

// From dist/store-CA7OW_2w.js
const MEDIA_MAX_BYTES = 5 * 1024 * 1024; // 5,242,880 bytes

class MediaStore {
  validateSize(bufferOrPath) {
    const size = this.getSize(bufferOrPath);
    if (size > MEDIA_MAX_BYTES) {
      throw new MediaLimitError(
        `Media exceeds ${MEDIA_MAX_BYTES} limit`
      );
    }
    // ... downstream processing
  }
}

Warum dies das Problem verursacht

1. Fest codierte Konstante außerhalb des Konfigurationsbereichs — Der MEDIA_MAX_BYTES-Wert wird zum Build-Zeitpunkt in das Runtime-Bundle kompiliert und kann nicht über Konfigurationsdateien, Umgebungsvariablen oder Laufzeiteinstellungen überschrieben werden.
2. Pipeline-Position — Die Validierung erfolgt in der MediaStore.validateSize()-Methode, die während der Staging-Phase aufgerufen wird, bevor eine kanal spezifische Limit-Auflösung stattfindet.
3. Fehlende Konfigurationsvererbung — Die Staging-Schicht konsultiert channel.media.maxBytes, agent.mediaLimits oder keine andere Konfigurationshierarchie bei der Durchsetzung dieser Prüfung.
4. Stille Fehlerpfad — Wenn der 5MB-Schwellenwert überschritten wird, wird der Fehler geworfen, ohne auf konfigurierbare Limits zu verweisen oder eine Anleitung zum Überschreiben des Staging-Limits zu geben.

Beabsichtigte vs. tatsächliche Limit-Hierarchie

OpenClaws Design scheint eine Limit-Hierarchie zu beabsichtigen, bei der effektive Limits aus mehreren Quellen aufgelöst werden:

// Intended resolution order (never reached):
effectiveLimit = min(
  channel.media.maxBytes,    // e.g., 25MB for Slack
  agent.mediaLimits.maxBytes, // e.g., 10MB for specific agent
  globalDefaults.maxBytes    // e.g., 50MB global ceiling
)

Der tatsächliche Ausführungspfad wird jedoch auf den fest codierten 5MB-Wert kurzgeschlossen, bevor einer dieser Auflösungs pfade ausgeführt wird.

Warum dies existiert

Das 5MB-Limit wurde wahrscheinlich als Sicherheitsmaßnahme eingeführt, um:

• Unbegrenzten Speicherverbrauch während des Stagings zu verhindern
• Eine vernünftige Obergrenze für "schnelle" Medienoperationen durchzusetzen
• Vorhersehbare Speichergrenzen in der Staging-Schicht zu gewährleisten

Es wurde jedoch als undurchsichtige Konstante implementiert, anstatt als dokumentierter, konfigurierbarer Parameter mit klarer Semantik.

Lösung 1: Staging-Limit aus effektiven Medienlimits ableiten (Empfohlen)

Ändern Sie die MediaStore-Klasse, um das Staging-Limit aus der effektiven Konfigurationshierarchie aufzulösen:

// Before (dist/store-CA7OW_2w.js)
const MEDIA_MAX_BYTES = 5 * 1024 * 1024;

class MediaStore {
  validateSize(bufferOrPath) {
    const size = this.getSize(bufferOrPath);
    if (size > MEDIA_MAX_BYTES) { /* error */ }
  }
}

// After (dist/store-CA7OW_2w.js)
const DEFAULT_STAGING_MAX_BYTES = 50 * 1024 * 1024; // 50MB default

class MediaStore {
  constructor(options = {}) {
    super(options);
    this._effectiveLimit = null;
  }

  getEffectiveLimit(context) {
    if (this._effectiveLimit !== null) {
      return this._effectiveLimit;
    }

    // Resolve from configuration hierarchy
    const configuredLimits = [
      context?.channel?.media?.maxBytes,
      context?.agent?.mediaLimits?.maxBytes,
      context?.config?.media?.stagingMaxBytes
    ].filter(limit => Number.isInteger(limit) && limit > 0);

    this._effectiveLimit = configuredLimits.length > 0
      ? Math.min(...configuredLimits)
      : DEFAULT_STAGING_MAX_BYTES;

    return this._effectiveLimit;
  }

  validateSize(bufferOrPath, context = {}) {
    const size = this.getSize(bufferOrPath);
    const effectiveLimit = this.getEffectiveLimit(context);

    if (size > effectiveLimit) {
      throw new MediaLimitError(
        `Media size (${size} bytes) exceeds effective limit of ${effectiveLimit} bytes ` +
        `(resolved from: ${JSON.stringify(context.channel?.media?.maxBytes ? 'channel' : 'default'})`
      );
    }
  }
}

Lösung 2: Staging-Limit-Konfiguration hinzufügen (Workaround)

Bis die oben genannte Lösung in einem Release verfügbar ist, fügen Sie das Staging-Limit zum Konfigurationssystem hinzu:

Schritt 1: Konfigurationsschema aktualisieren

# Add to openclaw.config.schema.json or equivalent
{
  "media": {
    "stagingMaxBytes": {
      "type": "integer",
      "default": 52428800,
      "description": "Maximum media size (in bytes) for staging/store operations",
      "env": "OPENCLAW_MEDIA_STAGING_MAX_BYTES"
    }
  }
}

Schritt 2: MediaStore-Initialisierung ändern

class MediaStore {
  constructor(options = {}) {
    const config = options.config || globalOpenClawConfig;
    this._stagingLimit = config.media?.stagingMaxBytes || DEFAULT_STAGING_MAX_BYTES;
  }
}

Schritt 3: Über Konfiguration festlegen

# In openclaw.config.yaml or openclaw.config.js
media:
  stagingMaxBytes: 26214400  # 25MB

# Or via environment variable
export OPENCLAW_MEDIA_STAGING_MAX_BYTES=26214400

Lösung 3: Temporäre Laufzeitüberschreibung (Sofortiger Workaround)

Wenn Sie das Bundle nicht direkt ändern können, wenden Sie einen Monkey-Patch vor Medienoperationen an:

// patch-media-limit.js
const originalRequire = module.constructor.prototype.require;

module.constructor.prototype.require = function(id) {
  const module = originalRequire.apply(this, arguments);

  if (id === './store' || id.includes('store-CA7OW')) {
    if (module.MediaStore) {
      const OriginalMediaStore = module.MediaStore;
      module.MediaStore = class PatchedMediaStore extends OriginalMediaStore {
        validateSize(...args) {
          // Override staging limit for this session
          const originalLimit = this.constructor.MEDIA_MAX_BYTES;
          try {
            this.constructor.MEDIA_MAX_BYTES = process.env.OPENCLAW_STAGING_MAX_BYTES || 52428800;
            return super.validateSize(...args);
          } finally {
            this.constructor.MEDIA_MAX_BYTES = originalLimit;
          }
        }
      };
    }
  }
  return module;
};

// Load before OpenClaw initialization
require('./patch-media-limit');
const { OpenClaw } = require('openclaw');

Nach der Anwendung der Lösung verifizieren Sie die Behebung durch die folgenden Verifizierungsschritte:

Voraussetzungen

# Ensure OpenClaw version includes the fix or workaround
openclaw --version
# Expected: 2026.4.12+ (or patched 2026.4.11)

# Verify configuration is set correctly
openclaw config get media.stagingMaxBytes
# Expected: > 5242880 (if explicitly set)

openclaw config get channels[0].media.maxBytes
# Expected: Your configured channel limit (e.g., 26214400 for 25MB)

Verifizierungstest: Medien stagen, die das ursprüngliche 5MB-Limit überschreiten

# Create a test file exceeding 5MB (6MB)
dd if=/dev/urandom of=/tmp/test-media-6mb.bin bs=1M count=6

# Attempt to stage through OpenClaw media pipeline
node -e "
const { MediaStore } = require('openclaw/dist/store-CA7OW_2w');
const store = new MediaStore();
const fs = require('fs');

try {
  const buffer = fs.readFileSync('/tmp/test-media-6mb.bin');
  store.validateSize(buffer);
  console.log('SUCCESS: Media staged without error');
  console.log('Size validated:', buffer.length, 'bytes');
} catch (err) {
  console.error('FAILED:', err.message);
  process.exit(1);
}
"

# Expected output after fix:
# SUCCESS: Media staged without error
# Size validated: 6291456 bytes

Verifizierungstest: Videogenerierungs-Workflow

# Run a video generation that produces > 5MB output
openclaw run \
  --tool video-generate \
  --prompt "Generate a 45-second animated landscape" \
  --output ./output/video.mp4

# Expected after fix:
# - Command completes without "Media exceeds 5MB limit" error
# - Output file exists and has expected size
ls -lh ./output/video.mp4
# Expected: file size > 5MB if generated successfully

Verifizierungstest: Limit-Hierarchie-Auflösung

# Test that effective limit respects the minimum of all configured limits
node -e "
const { MediaStore } = require('openclaw/dist/store-CA7OW_2w');
const store = new MediaStore({
  config: {
    media: { stagingMaxBytes: 10485760 }  // 10MB
  },
  channel: {
    media: { maxBytes: 5242880 }  // 5MB
  },
  agent: {
    mediaLimits: { maxBytes: 15728640 }  // 15MB
  }
});

const context = store.getEffectiveLimit({
  config: store._config,
  channel: store._config.channel,
  agent: store._config.agent
});

console.log('Effective limit:', context, 'bytes');
console.log('Expected: 5242880 (minimum of channel: 5MB)');
console.log('Result:', context === 5242880 ? 'PASS' : 'FAIL');
"

Verifizierungstest: Klarheit der Fehlermeldungen

# Test that error messages now indicate the effective limit source
node -e "
const { MediaStore, MediaLimitError } = require('openclaw/dist/store-CA7OW_2w');
const store = new MediaStore({ config: { media: { stagingMaxBytes: 1000000 } } });
const buffer = Buffer.alloc(2000000); // 2MB

try {
  store.validateSize(buffer);
} catch (err) {
  console.log('Error message:', err.message);
  // Expected: includes both size and effective limit
  // Should NOT just say 'Media exceeds 5MB limit'
}
"

# Expected: Error includes resolved effective limit, not hardcoded 5MB

Umgebungsspezifische Fallen

• Docker/Container-Deployments — Das gebündelte Runtime in dist/store-CA7OW_2w.js ist im Container-Image eingebettet. Das Ändern von node_modules in einem laufenden Container bleibt nach Neustarts nicht bestehen. Erstellen Sie Images immer neu oder mounten Sie Konfigurationsüberschreibungen.

  # Incorrect - changes lost after container restart
  docker exec openclaw-container sed -i 's/5 \* 1024 \* 1024/50 * 1024 * 1024/g' /usr/local/lib/node_modules/openclaw/dist/store-CA7OW_2w.js
  Correct - use environment variables or volume mounts
  docker run -e OPENCLAW_MEDIA_STAGING_MAX_BYTES=52428800 openclaw/app

• npm Global Install vs. Lokale Installation — Der Bundle-Speicherort unterscheidet sich:

  # Global install location
  $(npm root -g)/openclaw/dist/store-CA7OW_2w.js
  Local install location
  ./node_modules/openclaw/dist/store-CA7OW_2w.js

  Das Patchen des falschen Speicherorts führt dazu, dass die Lösung wirkungslos erscheint.

• Monorepo/Workspace-Konfigurationen — Wenn OpenClaw im Workspace-Root installiert ist, können verschachtelte Pakete eine andere Bundle-Instanz auflösen. Stellen Sie sicher, dass alle Pakete auf dieselbe OpenClaw-Installation verweisen.

  # Check bundle resolution
  node -e "console.log(require.resolve('openclaw/dist/store-CA7OW_2w.js'))"

Konfigurations-Grenzfälle

• Null- oder Nullwert-Limitwerte — Die Lösung muss nicht-positive Werte herausfiltern:

  # This should NOT be treated as unlimited
  channels:
    slack:
      media:
        maxBytes: 0  # Disables limit? Or error?
  Verify your fix handles this correctly
  openclaw config validate
  Should warn about invalid zero/null media limits

• Kanal spezifische Limits vs. Globale Standardwerte — Das Minimum aller Limits ist normalerweise das korrekte effektive Limit, aber einige Workflows können das Maximum beabsichtigen. Dokumentieren Sie die gewählte Semantik klar.
• Legacy-Konfigurationsdateien — Alte .openclawrc-JSON-Dateien verwenden möglicherweise mediaMaxBytes anstatt media.maxBytes. Überprüfen Sie die Abwärtskompatibilität.

Laufzeitverhalten-Fallen

• Gecachtes Bundle nach Update — Nach dem Update von OpenClaw leeren Sie den Modul-Cache:

  # Clear require cache in Node.js
  delete require.cache[require.resolve('openclaw/dist/store-CA7OW_2w.js')]
  Or restart the Node.js process entirely

• Streaming-Medien nicht gepuffert — Wenn Medien gestreamt werden (z.B. Videogenerierung), muss die Größenvalidierung möglicherweise zuerst den gesamten Stream lesen. Stellen Sie sicher, dass die Lösung sowohl gepufferte als auch Streaming-Szenarien behandelt.
• Speicherdruck bei großen Limits — Wenn Staging-Limits sehr hoch gesetzt werden (z.B. 500MB+), ohne entsprechende Speicherkonfiguration, können OOM-Fehler während der Staging-Operationen auftreten.

Verifizierungsfehler

Wenn Verifizierungstests unerwartet fehlschlagen:

1. Bestätigen Sie, dass das Bundle tatsächlich aktualisiert wurde (md5sum dist/store-CA7OW_2w.js)
2. Prüfen Sie auf mehrere OpenClaw-Installationen im Modulauflösungspfad
3. Überprüfen Sie, ob Umgebungsvariablen korrekt gelesen werden (console.log(process.env.OPENCLAW_MEDIA_STAGING_MAX_BYTES))
4. Stellen Sie sicher, dass der Prozess über die Berechtigung zum Lesen der aktualisierten Bundle-Datei verfügt

Die folgenden Fehler und Probleme stehen im Zusammenhang mit dem fest codierten 5MB-Staging-Limit:

• MediaLimitError — Die primäre Fehlerklasse, die geworfen wird, wenn Medien den Staging-Schwellenwert überschreiten. Kann als "Media exceeds 5MB limit" oder nach Fixes als "Media exceeds {effectiveLimit} bytes" erscheinen.
• MEDIA_EXCEEDS_CHANNEL_LIMIT — Ein nachgelagerter Fehler, der nach dem Staging auftritt, wenn das kanal spezifische Limit immer noch überschritten wird. Dieser Fehler sollte NICHT auftreten, wenn das Staging-Limit korrekt aus der Kanal-Konfiguration abgeleitet wird.
• ENFILE / EMFILE (File-Descriptor-Limits) — Nicht direkt verwandt, kann aber auftreten, wenn große Mediendateien ohne ordnungsgemäßes Streaming verarbeitet werden. Oft mit Größenlimit-Fehlern verwechselt.
• EBADMSG (Nachricht nicht verarbeitbar) — Kann auftreten, wenn die Medienvalidierung aufgrund von Größenbeschränkungen teilweise fehlschlägt, bevor das Parsing abgeschlossen ist. Das 5MB-Limit kann dazu führen, dass unvollständige Medienobjekte nachgelagert übergeben werden.
• Problem: Stille Kürzung von Medien-Metadaten — Verwandtes vorgelagertes Problem, bei dem Medien-Metadaten entfernt werden, wenn die Größe das Staging-Limit erreicht, was zu nachgelagerten Zustellungsfehlern mit unklaren Fehlermeldungen führt.
• Problem: Videogenerierung schlägt bei Dauer > ~15s fehl — Benutzer berichten, dass die Videogenerierung bei längeren Dauerzeiten fehlschlägt, wahrscheinlich aufgrund von akkumulierten Frame-Daten, die das 5MB-Staging-Limit überschreiten, bevor das Video vollständig assembliert ist.
• Problem: Audiodateien verlieren Metadaten — Bezieht sich auf Medien-Staging-Verhalten, bei dem hochbitratige Audiodateien teilweise verarbeitet werden und ID3/Metadaten-Tags verlieren, wenn die Größenvalidierung streng ist.
• Upload payload too large — Kanal spezifische Fehler von nachgelagerten Integrationen (Slack, Discord, etc.), die angeben, dass das tatsächliche Limit der Plattform überschritten wurde. Wenn dieser Fehler nach dem Staging-Fix auftritt, muss das Kanal-Limit selbst angepasst werden.
• BufferOverflowError (Benutzerdefiniert) — Kann in benutzerdefinierten OpenClaw-Deployments erscheinen, wenn die Staging-Schicht erweitert wird, ohne entsprechende Buffer-Größenanpassungen vorzunehmen.
• Historisch: dist/store.js umbenannt in dist/store-CA7OW_2w.js — Der Bundle-Dateiname hat sich zwischen Versionen geändert. Stellen Sie sicher, dass die Dokumentation auf den korrekten aktuellen Bundle-Namen für die installierte Version verweist.

Querverweis-Matrix