Claude Agent SDK: comprueba el consumo del límite de 5 horas
Compara el consumo del cupo de cinco horas en Claude Agent SDK, claude -p y Claude Code interactivo. Revisa las etiquetas del cliente y los eventos de uso, conoce los riesgos de las soluciones no oficiales y evalúa la facturación API o los créditos de Max y Team para tus automatizaciones.
Índice
Si Claude Agent SDK o claude -p agotan pronto tu cupo de cinco horas, compara la misma tarea en Claude Code interactivo. Las pruebas de la comunidad registran un consumo de aproximadamente 1.6×–2.97× el de referencia, pero no establecen un multiplicador universal. Para automatizaciones recurrentes, la facturación API documentada ofrece un saldo independiente y cargos por tokens que puedes medir.
A fecha de 2026-10-27, la incidencia #97074 de Anthropic sigue abierta. Los informes aportan pruebas de diferencias de consumo entre los puntos de entrada de los clientes. No permiten determinar si Anthropic ha establecido esa diferencia de forma deliberada o la considera un defecto.
Qué midieron las pruebas comparativas
Varios autores registraron un mayor consumo del cupo de cinco horas al realizar trabajos comparables mediante claude -p o aplicaciones de Agent SDK. Son experimentos independientes, con distintas versiones, modelos, combinaciones de tokens y clientes de referencia.
| Informe | Condiciones de la prueba | Resultado comunicado |
|---|---|---|
| qvarker, 25 de septiembre | Max; Claude Code 2.1.282; claude-opus-5; esfuerzo de razonamiento alto | Consumo de aproximadamente 1.8× el del terminal interactivo al ejecutar sin interfaz interactiva |
| kler, 17 de octubre | Team; Claude Code 2.1.300; claude-opus-5-5; esfuerzo de razonamiento alto | sdk-ts: 2.97×; sdk-cli: 2.83×, frente a un entorno de pruebas que usaba la etiqueta claude-vscode |
| Informe de Theo sobre T3 Code, 25 de octubre | Una cuenta Max; carga de trabajo equivalente; terminal interactivo, T3 Code y claude -p | Consumo de aproximadamente 1.6×–1.7× el del terminal interactivo por las vías SDK o sin interfaz interactiva, tras la comparación de caché del informe |
| frostfire575, 26 de octubre | Windows 11; Claude Code 2.1.310; claude-opus-5-5; esfuerzo de razonamiento bajo | Consumo por token ponderado de aproximadamente 2.4× el del terminal interactivo al usar claude -p |
El resultado más alto requiere una aclaración: el entorno de pruebas de kler emulaba la etiqueta de la extensión de VS Code. No controlaba la interfaz real de la extensión. El resultado aísla una diferencia relacionada con la etiqueta dentro de ese experimento.
Las cantidades en dólares del informe de qvarker son estimaciones del coste API equivalente que sirven para comparar el trabajo realizado. No son cargos adicionales de la suscripción. Un valor menor de «dólares de trabajo por 1%» indica que el cupo se agotaba más rápido.
El cupo semanal debe analizarse por separado. Theo registró el mismo aumento de dos puntos porcentuales semanales en cada ejecución. El indicador semanal de frostfire575 solo pasó de 0% a 1%, una resolución insuficiente para sacar conclusiones. Las pruebas respaldan un consumo semanal igual en el experimento de Theo, sin garantizarlo para todas las cuentas.
Qué demuestran sdk-cli y sdk-ts
La etiqueta entrypoint identifica al cliente que realiza la llamada. Su presencia no revela la fórmula de consumo que Anthropic aplica en el servidor.
El paquete publicado @anthropic-ai/claude-agent-sdk 0.3.311 contiene este valor predeterminado en sdk.mjs:
if(!c.CLAUDE_CODE_ENTRYPOINT)c.CLAUDE_CODE_ENTRYPOINT="sdk-ts"Por tanto, el SDK asigna sdk-ts cuando falta ese valor de entorno. Los registros de sesiones aportados por la comunidad muestran sdk-cli para ejecuciones normales de claude -p y cli para el terminal interactivo.
En la comparación de tráfico de qvarker, las solicitudes diferían en cc_entrypoint, dentro del bloque de sistema x-anthropic-billing-header. El autor también observó diferencias en User-Agent y en un indicador beta.
Es una observación de la comunidad sobre el contenido de las solicitudes. No describe una interfaz de facturación documentada oficialmente ni demuestra que un único campo explique todas las diferencias.
El registro de cambios de Claude Code 2.1.311 no anuncia una corrección de esta discrepancia de consumo. Esa omisión no permite determinar si ha cambiado el comportamiento del servidor.
Cómo comprobar tu flujo de trabajo
Identifica el cliente real, la vía de autenticación y la carga de trabajo antes de modificar la configuración.
Confirma la autenticación y las condiciones de comparación
Revisa el entorno que utiliza el proceso de Claude de tu aplicación. Según la referencia de autenticación, una clave de API puede tener prioridad sobre la autenticación de la suscripción en modo -p.
Anota el ejecutable, la versión de la CLI, la versión del paquete SDK, el plan, el ID exacto del modelo y el nivel de esfuerzo. Una aplicación puede iniciar un binario distinto del que ejecutas desde el terminal.
Para realizar la comparación:
- Usa la misma cuenta, copia del proyecto, lista de prompts, herramientas y configuración de caché.
- Pausa cualquier otra actividad en esa cuenta.
- Inicia sesiones nuevas y completa ambas ejecuciones dentro de la misma ventana de cinco horas.
- Detén la comparación si la ventana se reinicia o el consumo pasa al uso adicional de pago.
Usa una tarea representativa, como resumir los mismos archivos de código fuente. Separa los totales de tokens de entrada, salida, lectura de caché y escritura de caché. Una salida de la misma longitud no demuestra por sí sola que el trabajo sea equivalente.
Captura el indicador de consumo y la etiqueta registrada
Conserva todos los datos del evento de límite de uso, porque los campos disponibles cambian entre versiones.
La siguiente comprobación en Bash requiere jq y una sesión ya autenticada con la suscripción. Consume parte del cupo. Comprueba la telemetría y la autenticación; una respuesta de una palabra no sirve para medir un multiplicador.
set -o pipefail
claude --version
claude auth status | jq '{authMethod}'
claude -p "Reply with exactly OK." \
--model claude-sonnet-5-5 \
--max-turns 1 \
--disallowedTools "*" \
--output-format stream-json --verbose |
jq -c '
if .type == "rate_limit_event" then
{type, session_id, rate_limit_info}
elif .type == "result" then
{type, subtype, is_error, session_id,
usage, modelUsage, total_cost_usd, result}
else empty end
'La referencia de la CLI documenta estas opciones y el comando que muestra el estado de autenticación. Una respuesta correcta debe incluir un registro result con subtype: "success" e is_error: false.
Las compilaciones instrumentadas de la incidencia usaban esta ruta:
rate_limit_event.rate_limit_info.unifiedWindows.five_hour.utilization
Sin embargo, unifiedWindows no aparece en el tipo de evento público del SDK 0.3.311. Ese tipo declara campos como rateLimitType y utilization. No interpretes la ausencia de un campo o evento como consumo cero. Consulta la página Usage de la cuenta si el flujo no ofrece una lectura útil.
Compara mediciones de la misma interfaz y escala. La utilización del evento y la respuesta independiente de control de uso del SDK tienen esquemas distintos. Sus cifras no son intercambiables.
Usa el session_id devuelto para localizar el registro de la sesión. La documentación de sesiones sitúa estos registros en ~/.claude/projects/<encoded-cwd>/<session-id>.jsonl. Un valor personalizado de CLAUDE_CONFIG_DIR cambia ese directorio raíz.
Consulta únicamente la etiqueta entrypoint registrada con Bash:
read -r -p "Transcript path: " CLAUDE_TRANSCRIPT
jq -r 'select(.entrypoint? | type == "string") | .entrypoint' \
"$CLAUDE_TRANSCRIPT" | sort -uUn resultado vacío significa que el campo no estaba disponible. No identifica la sesión como interactiva.
Para comparar con el terminal, inicia el cliente interactivo real de Claude Code desde un shell con el entorno limpio. qvarker informó de que un servidor tmux heredó CLAUDE_CODE_ENTRYPOINT y lo transmitió a sesiones de terminal posteriores. Comprueba el registro resultante, sin dar por hecho que la interfaz determina la etiqueta.
Compara el cupo consumido por unidad de trabajo
Compara los puntos porcentuales consumidos por unidad de trabajo equivalente. El tiempo transcurrido y el número de prompts no bastan.
Frostfire575 registró 1.43 millones de tokens ponderados para un aumento de cinco puntos en el terminal. La ejecución sin interfaz interactiva usó 1.32 millones de tokens ponderados y aumentó once puntos. Con esas cifras:
Headless / terminal = (11 / 1.32) / (5 / 1.43) = 2.38
El cálculo explica el resultado comunicado de 2.4×. Utiliza la medida de tokens ponderados del autor y solo se aplica a esa comparación.
Los cambios de un punto son demasiado imprecisos para comparar ejecuciones pequeñas. Si hace falta, repite el trabajo habitual en orden inverso. Evita que la ventana se reinicie o que haya actividad simultánea en la cuenta.
Usa los resultados finales de sesiones nuevas para estimar costes. No sumes registros de resultados acumulados de sesiones reanudadas. La documentación de seguimiento de costes distingue el cómputo de tokens de la facturación real. Ni total_cost_usd ni modelUsage miden el cupo de la suscripción.
Si la diferencia desaparece al igualar el comportamiento de la caché o eliminar la actividad simultánea, investiga primero esas causas.
¿Conviene cambiar CLAUDE_CODE_ENTRYPOINT?
Considera el cambio de etiqueta del cliente como un experimento sin soporte oficial.
El 26 de octubre, qvarker y oviano informaron de un menor consumo al usar los nombres de sus propias herramientas. En sus comparaciones, el consumo con la etiqueta predeterminada sdk-cli fue aproximadamente 1.9×–2.4× el registrado con la etiqueta personalizada.
Esos informes no acreditan un método aprobado para obtener un cupo distinto. Una etiqueta personalizada cambia la atribución del cliente, que parece relevante para el cómputo del consumo. Su tratamiento podría cambiar y su situación respecto a las políticas sigue sin resolverse.
No etiquetes tu aplicación como cli o claude-vscode para recibir el tratamiento de otro cliente. Esos nombres identifican clientes diferentes.
La pull request #25597 de T3 Code seguía abierta y sin integrar cuando se comprobó el 2026-10-27. Su existencia no demuestra que T3 Code haya publicado una corrección ni que Anthropic la haya aprobado.
Para trabajo interactivo, prueba el cliente de terminal real. Si tu automatización necesita mantener entradas y salidas estructuradas, evalúa la facturación API.
¿Qué saldo paga la automatización con Agent SDK?
La autenticación determina si una tarea consume el cupo de la suscripción o créditos API.
La actualización de facturación del 7 de octubre de Anthropic mantiene el uso de la suscripción para Agent SDK, claude -p y aplicaciones de terceros. También permite usar créditos API de Max y Team que cumplan los requisitos para tareas de SDK y claude -p que ejecutes por tu cuenta. Deben autenticarse con una clave de API de una organización de Console vinculada.
Distingue estos saldos y cupos:
| Vía de facturación | Qué consume la tarea |
|---|---|
| Inicio de sesión con una suscripción de Claude | Cupos de la suscripción, incluida la ventana de cinco horas |
| Uso adicional habilitado, también llamado créditos de uso | Continuación de pago independiente después de agotar el cupo incluido |
| Clave de API de Anthropic | Créditos API aplicables o saldo API de pago de la organización de Console |
| Gateway API independiente | Saldo y reglas de facturación de ese proveedor |
La facturación API elimina la dependencia del cupo de cinco horas de la suscripción para esa tarea. Siguen aplicándose los límites de tasa, los límites de gasto y los fondos disponibles de la API.
A fecha de 2026-10-27, el programa de créditos API mensuales enumera estas cantidades:
| Plan que cumple los requisitos | Crédito API mensual |
|---|---|
| Max 5x | $100 USD |
| Max 20x | $200 USD |
| Team Standard | $20 USD por puesto |
| Team Premium | $100 USD por puesto |
Los créditos de Team se agrupan en un fondo común con un límite de $500 USD. Pro no cumple los requisitos. Los nuevos suscriptores deben permanecer siete días en un plan elegible.
Para activar los créditos, abre Settings > Billing en Max u Organization settings > Billing en Team. Selecciona Link organization en el apartado de créditos API. Necesitas el rol exigido de suscriptor o propietario y permisos de facturación en Console. Crea la clave de API en esa organización vinculada.
El programa excluye Claude Code interactivo, el uso adicional y las ejecuciones iniciadas desde Claude Code GitHub Action, extensiones de IDE o la aplicación de escritorio de Claude. Añadir -p no elimina esas exclusiones.
La documentación de créditos de la plataforma explica que los créditos no utilizados caducan y no se acumulan para el siguiente periodo. Los créditos incluidos se consumen antes que los comprados. Al agotarse, los fondos comprados o la facturación aplicable pueden mantener el servicio; de lo contrario, las solicitudes se detienen. No pasan a consumir automáticamente el cupo de la suscripción.
Comprueba la facturación API antes de trasladar tareas recurrentes
Verifica una ejecución directa con clave de API y su consumo en Console antes de migrar una cola de tareas.
Usa un terminal Bash configurado para acceder directamente a Anthropic. Comprueba primero ANTHROPIC_BASE_URL, ANTHROPIC_AUTH_TOKEN y la configuración de proveedores de nube existentes. Pueden seleccionar otro endpoint u otra fuente de credenciales.
Crea una clave de API en la organización de Console que corresponda. Introdúcela sin mostrarla en pantalla:
read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
claude --bare -p \
--model claude-sonnet-5-5 \
--tools "" \
--max-turns 1 \
--max-budget-usd 1.00 \
--output-format json \
"Reply with exactly OK."La documentación de uso programático indica que --bare omite las credenciales OAuth de la suscripción y las personalizaciones detectadas. Por eso resulta adecuado para comprobar la API. Si lo usaras al comparar el consumo de la suscripción, cambiarías la vía de autenticación.
Deberías obtener un resultado JSON correcto que contenga la respuesta. Después, comprueba el consumo y el saldo de la organización correspondiente en Console. La estimación de costes de la CLI no demuestra por sí sola que la solicitud se haya pagado con créditos promocionales.
Si falla la autenticación, revisa la clave y el proveedor activo. Si el saldo se ha agotado, consulta la facturación en Console. Los errores por límites de tasa o de gasto de la API requieren revisar esos límites, aunque quede cupo de suscripción.
El presupuesto de $1.00 de la CLI es un umbral estimado para detener la ejecución. Una solicitud puede superarlo, así que configura también un límite de gasto adecuado en Console.
Como ejemplo de presupuesto, los precios actuales de Anthropic sitúan claude-sonnet-5-5 en $2 por millón de tokens de entrada sin caché. La salida cuesta $10 por millón de tokens. A fecha de 2026-10-27, un millón de tokens de entrada más 100,000 de salida da este cargo estimado por tokens:
(1 × $2) + (0.1 × $10) = $3
El cálculo supone solicitudes síncronas estándar con enrutamiento global, sin caché ni herramientas de servidor con cargos independientes. No incluye los impuestos aplicables. Si reutilizas contexto, calcula las escrituras y lecturas de caché con sus tarifas correspondientes.
Un gateway independiente ofrece otra vía. El catálogo actualizado de BetterToken incluía claude-sonnet-5-5 y claude-opus-5-5 el 2026-10-27. Su guía de Claude Code utiliza tu propia clave de BetterToken y la URL base https://bettertoken.ai, sin /v1. Compara sus precios actuales y la compatibilidad necesaria con tus herramientas según tu carga de trabajo. Los créditos API incluidos de Anthropic no se transfieren a esa vía de facturación independiente.
