El límite de preparación de medios codificado se manifiesta a través de varios patrones de error distintos:

Manifestación Principal del Error

Al intentar preparar o devolver archivos multimedia que exceden 5MB, aparece el siguiente error:

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)

Flujo del Error Durante el Procesamiento de Medios

El error ocurre durante la fase de validación de preparación del pipeline de medios, antes de cualquier resolución de límite específico del canal:

1. Fase de Ingesta — Medios generados o recibidos por el agente
2. Validación de Preparación — Verificación codificada de 5MB en dist/store-CA7OW_2w.js ← Punto de falla
3. Resolución de Canal — Límites de medios del canal/agente (nunca alcanzado)
4. Entrega — Salida al canal configurado

Condiciones que Activan el Problema

• Flujos de trabajo de generación de video que producen archivos > 5MB
• Composiciones de múltiples imágenes o GIFs con datos de cuadros que exceden el umbral
• Archivos de audio con duración extendida y altas tasas de muestreo
• Cualquier salida de herramienta multimedia preparada a través de openclaw.media.stage()

Comportamiento de Anulación Silenciosa

El límite codificado anula silenciosamente las configuraciones válidas de los canales. Los usuarios que observen este comportamiento pueden notar:

# 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

Esto crea una experiencia engañosa donde los límites configurados parecen ineficaces.

Problema Arquitectónico: Compuerta de Validación Prematura

La causa raíz es un problema de orden de validación en la arquitectura del pipeline de medios de OpenClaw. El archivo de runtime empaquetado dist/store-CA7OW_2w.js contiene:

// 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
  }
}

Por Qué Esto Causa el Problema

1. Constante Codificada Fuera del Alcance de Configuración — El valor MEDIA_MAX_BYTES está compilado en el bundle de runtime en tiempo de construcción y no puede ser anulado a través de archivos de configuración, variables de entorno ni configuraciones en tiempo de ejecución.
2. Posición en el Pipeline — La validación ocurre en el método MediaStore.validateSize(), que se invoca durante la fase de preparación antes de que ocurra cualquier resolución de límite específico del canal.
3. Ausencia de Herencia de Configuración — La capa de preparación no consulta channel.media.maxBytes, agent.mediaLimits, ni ninguna otra jerarquía de configuración al aplicar esta verificación.
4. Ruta de Fallo Silenciosa — Cuando se excede el umbral de 5MB, el error se lanza sin hacer referencia a ningún límite configurable ni proporcionar orientación sobre cómo anular el límite de preparación.

Jerarquía de Límites Prevista vs. Actual

El diseño de OpenClaw parece tener la intención de una jerarquía de límites donde los límites efectivos se resuelven desde múltiples fuentes:

// 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
)

Sin embargo, la ruta de ejecución real se cortocircuita al valor codificado de 5MB antes de que cualquiera de estas rutas de resolución se ejecute.

Por Qué Existe Esto

El límite máximo codificado de 5MB probablemente se originó como una medida de seguridad para:

• Prevenir el consumo de memoria sin límites durante la preparación
• Imponer un techo razonable para operaciones de medios "rápidas"
• Garantizar límites de memoria predecibles en la capa de preparación

Sin embargo, se implementó como una constante opaca en lugar de un parámetro documentado y configurable con semántica clara.

Solución 1: Derivar el Límite de Preparación de los Límites de Medios Efectivos (Recomendado)

Modificar la clase MediaStore para resolver el límite de preparación desde la jerarquía de configuración efectiva:

// 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'})`
      );
    }
  }
}

Solución 2: Agregar Configuración del Límite de Preparación (Solución Alternativa)

Hasta que la solución anterior esté disponible en una versión, agregar el límite de preparación al sistema de configuración:

Paso 1: Actualizar el esquema de configuración

# 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"
    }
  }
}

Paso 2: Modificar la inicialización de MediaStore

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

Paso 3: Establecer a través de la configuración

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

# Or via environment variable
export OPENCLAW_MEDIA_STAGING_MAX_BYTES=26214400

Solución 3: Anulación Temporal en Tiempo de Ejecución (Solución Inmediata)

Si no puede modificar el bundle directamente, aplique un monkey-patch antes de las operaciones de medios:

// 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');

Después de aplicar la corrección, verifique la resolución a través de los siguientes pasos de verificación:

Prerrequisitos

# 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)

Prueba de Verificación: Preparar Medios que Exceden el Límite Original de 5MB

# 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

Prueba de Verificación: Flujo de Trabajo de Generación de Video

# 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

Prueba de Verificación: Resolución de Jerarquía de Límites

# 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');
"

Prueba de Verificación: Claridad del Mensaje de Error

# 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

Trampas Específicas del Entorno

• Despliegues Docker/Contenedor — El runtime empaquetado en dist/store-CA7OW_2w.js está embebido en la imagen del contenedor. Modificar node_modules dentro de un contenedor en ejecución no persiste entre reinicios. Siempre reconstruir imágenes o montar anulaciones de configuración.

  # 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

• Instalación Global vs. Local de npm — La ubicación del bundle difiere:

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

  Corregir la ubicación equivocada hace que la solución parezca ineficaz.

• Configuraciones Monorepo/Workspace — Cuando OpenClaw está instalado en la raíz del workspace, los paquetes anidados pueden resolver una instancia diferente del bundle. Asegurar que todos los paquetes referencien la misma instalación de OpenClaw.

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

Casos Extremos de Configuración

• Valores de Límite Cero o Nulo — La corrección debe filtrar valores no positivos:

  # 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

• Límites Específicos del Canal vs. Valores Predeterminados Globales — El mínimo de todos los límites suele ser el límite efectivo correcto, pero algunos flujos de trabajo pueden pretender el máximo. Documentar claramente la semántica elegida.
• Archivos de Configuración Heredados — Los archivos JSON .openclawrc antiguos pueden usar mediaMaxBytes en lugar de media.maxBytes. Verificar la compatibilidad hacia atrás.

Trampas de Comportamiento en Tiempo de Ejecución

• Bundle en Caché Después de Actualizar — Después de actualizar OpenClaw, limpiar la caché de módulos:

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

• Medios en Streaming No Bufferizados — Si los medios se transmiten en streaming (por ejemplo, generación de video), la validación de tamaño puede necesitar leer todo el stream primero. Asegurar que la corrección maneje tanto escenarios bufferizados como en streaming.
• Presión de Memoria con Límites Altos — Establecer límites de preparación muy altos (por ejemplo, 500MB+) sin configuración de memoria correspondiente puede causar errores OOM durante las operaciones de preparación.

Fallos de Verificación

Si las pruebas de verificación fallan inesperadamente:

1. Confirmar que el bundle fue realmente actualizado (md5sum dist/store-CA7OW_2w.js)
2. Verificar la existencia de múltiples instalaciones de OpenClaw en la ruta de resolución de módulos
3. Asegurar que las variables de entorno se lean correctamente (console.log(process.env.OPENCLAW_MEDIA_STAGING_MAX_BYTES))
4. Confirmar que el proceso tiene permiso para leer el archivo del bundle actualizado

Los siguientes errores y problemas están contextualmente relacionados con el límite de preparación de 5MB codificado:

• MediaLimitError — La clase de error principal que se lanza cuando los medios exceden el umbral de preparación. Puede aparecer como "Media exceeds 5MB limit" o, después de las correcciones, "Media exceeds {effectiveLimit} bytes".
• MEDIA_EXCEEDS_CHANNEL_LIMIT — Un error posterior que ocurre después de la preparación si el límite específico del canal todavía se excede. Este error NO debería ocurrir si el límite de preparación se deriva correctamente de la configuración del canal.
• ENFILE / EMFILE (Límites de Descriptores de Archivo) — No relacionados directamente pero pueden aparecer cuando se procesan archivos multimedia grandes sin streaming adecuado. A menudo confundidos con errores de límite de tamaño.
• EBADMSG (Mensaje No Procesable) — Puede ocurrir si la validación de medios falla parcialmente debido a restricciones de tamaño antes del análisis completo. El límite de 5MB puede causar que objetos multimedia incompletos se pasen a las capas posteriores.
• Problema: Truncamiento Silencioso de Metadatos de Medios — Problema relacionado aguas arriba donde los metadatos de medios se eliminan cuando el tamaño se acerca al límite de preparación, causando fallos de entrega posteriores con mensajes de error poco claros.
• Problema: La Generación de Video Falla para Duraciones > ~15s — Los usuarios reportan que la generación de video falla para duraciones más largas, probablemente debido a que los datos de cuadros acumulados exceden el límite de preparación de 5MB antes de que el video esté completamente ensamblado.
• Problema: Archivos de Audio Sin Metadatos — Relacionado con el comportamiento de preparación de medios donde archivos de audio de alta tasa de bits se procesan parcialmente, perdiendo etiquetas ID3/metadatos cuando la validación de tamaño es estricta.
• Upload payload too large — Errores específicos del canal de integraciones posteriores (Slack, Discord, etc.) que indican que se excedió el límite real del canal. Si este error aparece después de la corrección de preparación, el límite del canal mismo necesita ajuste.
• BufferOverflowError (Personalizado) — Puede aparecer en despliegues personalizados de OpenClaw si la capa de preparación se extiende sin los ajustes correspondientes de tamaño de buffer.
• Histórico: dist/store.js Renombrado a dist/store-CA7OW_2w.js — El nombre del archivo del bundle cambió entre versiones. Asegurar que la documentación referencie el nombre correcto del bundle actual para la versión instalada.

Matriz de Referencias Cruzadas