Solución de problemas: El uso de tokens de contexto no se rastrea en backends personalizados compatibles con OpenAI

Síntomas

Si estás usando un backend personalizado o no estándar compatible con OpenAI (como llama-cpp, LM Studio, u otros servidores de inferencia locales), es posible que encuentres los siguientes síntomas después de actualizar a ciertas versiones:

• El uso de tokens siempre se muestra como 0% o 0 tokens en respuestas de streaming
• El seguimiento de la ventana de contexto parece roto incluso cuando el modelo claramente está consumiendo tokens
• Comportamiento inconsistente entre solicitudes de streaming y no streaming (las solicitudes no streaming muestran uso preciso mientras que streaming muestra 0%)

Este problema impacta específicamente las respuestas de solicitudes de streaming desde backends alternativos mientras que los endpoints estándar de la API de OpenAI continúan reportando el uso correctamente.

Causa raíz

La función buildOpenAICompletionsParams() en la capa de transporte de OpenAI solo incluía el campo stream_options: { include_usage: true } en las cargas útiles de solicitudes cuando compat.supportsUsageInStreaming se evaluaba como true.

Para los endpoints estándar de OpenAI, esta bandera de compatibilidad se resolvía correctamente, permitiendo que la función resolveIncludeUsageForStreaming() del gateway rastreara el uso adecuadamente. Sin embargo, para backends personalizados como llama-cpp y LM Studio, esta bandera se resolvía como false, lo que causaba que el campo se omitiera completamente. Sin este campo presente en la solicitud, el gateway no tenía datos para procesar, resultando en que el uso de tokens de contexto siempre se mostrara como cero.

Solución paso a paso

Actualizar a la versión v2026.4.19-beta.2 resuelve este problema automáticamente. No se requieren cambios de configuración.

1. Actualiza el paquete OpenClaw a v2026.4.19-beta.2 o posterior
2. Reinicia tu servicio de gateway para cargar la capa de transporte actualizada
3. Verifica la corrección iniciando una solicitud de streaming a tu backend personalizado

Verificación

Para confirmar que la corrección está funcionando:

1. Envía una solicitud de completación con streaming a tu backend personalizado (llama-cpp, LM Studio, etc.)
2. Monitorea la carga útil de respuesta para el campo usage que aparece en los fragmentos de streaming
3. Verifica que el seguimiento de tokens de contexto ahora muestra el conteo real de tokens en lugar de 0%

// Ejemplo de verificación: Verificar que el uso aparece en la respuesta de streaming
const response = await openai.chat.completions.create({
  model: 'your-model',
  messages: [{ role: 'user', content: 'Hello' }],
  stream: true,
  stream_options: { include_usage: true }  // Ahora siempre incluido
});

for await (const chunk of response) {
  if (chunk.usage) {
    console.log('Uso rastreado:', chunk.usage);
  }
}

Errores comunes

• Interferencia de proxy: Algunos proxies de API o middleware pueden eliminar campos desconocidos de las cargas útiles de solicitudes. Si usas una capa de proxy personalizada, verifica que reenvíe stream_options al backend sin cambios.

• Configuración específica del backend: Aunque el campo ahora siempre se incluye y los backends que no lo soportan lo ignoran de forma segura, algunos backends personalizados más antiguos pueden tener comportamiento inesperado al encontrar campos desconocidos. Prueba primero en un entorno de staging.

• Entornos mixtos: Si ejecutas múltiples instancias de gateway con diferentes versiones, el seguimiento de tokens será inconsistente entre solicitudes. Asegúrate de que todas las instancias estén actualizadas a v2026.4.19-beta.2 para un comportamiento uniforme.

Errores relacionados

• Agotamiento de la ventana de contexto no detectado: Porque el uso siempre era 0%, el sistema no podía advertir con precisión a los usuarios cuando se acercaban a los límites de contexto durante las solicitudes de streaming.
• Inconsistencia en el reporte de uso: Comparar métricas de uso entre solicitudes de streaming y no streaming era imposible ya que streaming siempre reportaba uso cero.

Versión afectada: v2026.4.19-beta.2 Referencia del issue: #68707 Archivos modificados: src/agents/openai-transport-stream.ts, src/agents/openai-transport-stream.test.ts