Uso y costos de tokens

OpenClaw rastrea tokens, no caracteres. Los tokens son específicos del modelo, pero la mayoría de los modelos de estilo OpenAI promedian ~4 caracteres por token para texto en inglés.

Cómo se construye el prompt del sistema

OpenClaw ensambla su propio prompt del sistema en cada ejecución. Incluye:

• Lista de herramientas + descripciones breves
• Lista de Skills (solo metadatos; las instrucciones se cargan bajo demanda con read). Los turnos nativos de Codex reciben el bloque compacto de Skills como instrucciones de desarrollador de colaboración con alcance de turno; otros harnesses lo reciben en la superficie normal del prompt. Está limitado por skills.limits.maxSkillsPromptChars, con sobrescritura opcional por agente en agents.list[].skillsLimits.maxSkillsPromptChars.
• Instrucciones de autoactualización
• Workspace + archivos de arranque (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md cuando es nuevo, más MEMORY.md cuando existe). Los turnos nativos de Codex no pegan el MEMORY.md sin procesar desde el workspace del agente configurado cuando las herramientas de memoria están disponibles para ese workspace; incluyen un pequeño puntero de memoria en las instrucciones de desarrollador de colaboración con alcance de turno y usan herramientas de memoria bajo demanda. Si las herramientas están deshabilitadas, la búsqueda de memoria no está disponible o el workspace activo difiere del workspace de memoria del agente, MEMORY.md usa la ruta normal acotada de contexto de turno. La raíz en minúsculas memory.md no se inyecta; es una entrada de reparación heredada para openclaw doctor --fix cuando se combina con MEMORY.md. Los archivos grandes inyectados se truncan mediante agents.defaults.bootstrapMaxChars (predeterminado: 20000), y la inyección total de arranque está limitada por agents.defaults.bootstrapTotalMaxChars (predeterminado: 60000). Los archivos diarios memory/*.md no forman parte del prompt de arranque normal; permanecen disponibles bajo demanda mediante herramientas de memoria en turnos ordinarios, pero las ejecuciones del modelo de reinicio/inicio pueden anteponer un bloque de contexto de inicio de un solo uso con memoria diaria reciente para ese primer turno. Los comandos de chat simples /new y /reset se reconocen sin invocar al modelo. El preámbulo de inicio está controlado por agents.defaults.startupContext. Los extractos de AGENTS.md posteriores a Compaction son independientes y requieren una activación explícita de agents.defaults.compaction.postCompactionSections.
• Hora (UTC + zona horaria del usuario)
• Etiquetas de respuesta + comportamiento de Heartbeat
• Metadatos de runtime (host/SO/modelo/razonamiento)

Consulta el desglose completo en Prompt del sistema.

Al documentar credenciales o fragmentos de autenticación, usa las Convenciones de marcadores de posición de secretos para evitar falsos positivos de escáneres de secretos en cambios solo de documentación.

Qué cuenta en la ventana de contexto

Todo lo que recibe el modelo cuenta para el límite de contexto:

• Prompt del sistema (todas las secciones listadas arriba)
• Historial de conversación (mensajes de usuario + asistente)
• Llamadas a herramientas y resultados de herramientas
• Adjuntos/transcripciones (imágenes, audio, archivos)
• Resúmenes de Compaction y artefactos de poda
• Envoltorios del proveedor o encabezados de seguridad (no visibles, pero aun así contados)

Algunas superficies pesadas en runtime tienen sus propios límites explícitos:

• agents.defaults.contextLimits.memoryGetMaxChars
• agents.defaults.contextLimits.memoryGetDefaultLines
• agents.defaults.contextLimits.toolResultMaxChars
• agents.defaults.contextLimits.postCompactionMaxChars

Las sobrescrituras por agente viven bajo agents.list[].contextLimits. Estos controles son para extractos acotados de runtime y bloques inyectados propiedad del runtime. Son independientes de los límites de arranque, los límites de contexto de inicio y los límites del prompt de Skills.

toolResultMaxChars es un techo avanzado (hasta 1000000 caracteres). Cuando no está definido, OpenClaw elige el límite activo de resultados de herramientas a partir de la ventana de contexto efectiva del modelo: 16000 caracteres por debajo de 100K tokens, 32000 caracteres a partir de 100K tokens y 64000 caracteres a partir de 200K+ tokens, todavía limitado por la protección de cuota de contexto del runtime.

Para imágenes, OpenClaw reduce la escala de las cargas de imagen de transcripción/herramienta antes de las llamadas al proveedor. Usa agents.defaults.imageMaxDimensionPx (predeterminado: 1200) para ajustar esto:

• Los valores más bajos suelen reducir el uso de tokens de visión y el tamaño de la carga.
• Los valores más altos preservan más detalle visual para OCR/capturas de pantalla con mucha UI.

Para un desglose práctico (por archivo inyectado, herramientas, Skills y tamaño del prompt del sistema), usa /context list o /context detail. Consulta Contexto.

Cómo ver el uso actual de tokens

Usa esto en el chat:

• /status → tarjeta de estado con muchos emojis con el modelo de la sesión, uso de contexto, tokens de entrada/salida de la última respuesta y coste estimado cuando los precios locales están configurados para el modelo activo.
• /usage off|tokens|full → añade un pie de uso por respuesta a cada respuesta.
  • Persiste por sesión (almacenado como responseUsage).
  • /usage reset (alias: inherit, clear, default) — borra la sobrescritura de la sesión para que la sesión vuelva a heredar el valor predeterminado configurado.
  • /usage tokens muestra detalles de tokens/caché del turno.
  • /usage full muestra detalles compactos de modelo/contexto/coste; el coste estimado aparece solo cuando OpenClaw tiene metadatos de uso y precios locales para el modelo activo. Los diseños personalizados de messages.usageTemplate pueden incluir campos de tokens/caché.
• /usage cost → muestra un resumen de coste local desde los registros de sesión de OpenClaw.

Otras superficies:

• TUI/Web TUI: /status + /usage están admitidos.
• CLI: openclaw status --usage y openclaw channels list muestran ventanas de cuota de proveedor normalizadas (X% left, no costes por respuesta). Proveedores actuales con ventana de uso: Anthropic, GitHub Copilot, Gemini CLI, OpenAI Codex, MiniMax, Xiaomi y z.ai.

Las superficies de uso normalizan alias comunes de campos nativos del proveedor antes de mostrarlos. Para el tráfico Responses de la familia OpenAI, eso incluye tanto input_tokens / output_tokens como prompt_tokens / completion_tokens, de modo que los nombres de campos específicos del transporte no cambian /status, /usage ni los resúmenes de sesión. El uso de Gemini CLI también se normaliza: el parser predeterminado stream-json lee eventos message del asistente, y stats.cached se asigna a cacheRead, con stats.input_tokens - stats.cached usado cuando la CLI omite un campo explícito stats.input. Las sobrescrituras JSON heredadas todavía leen el texto de respuesta desde response. Para el tráfico Responses nativo de la familia OpenAI, los alias de uso WebSocket/SSE se normalizan del mismo modo, y los totales recurren a entrada + salida normalizadas cuando total_tokens falta o es 0. Cuando la instantánea de la sesión actual es escasa, /status y session_status también pueden recuperar contadores de tokens/caché y la etiqueta del modelo de runtime activo desde el registro de uso de transcripción más reciente. Los valores activos no nulos existentes siguen teniendo precedencia sobre los valores alternativos de transcripción, y los totales de transcripción más grandes orientados al prompt pueden ganar cuando los totales almacenados faltan o son menores. La autenticación de uso para ventanas de cuota de proveedor proviene de hooks específicos del proveedor cuando están disponibles; de lo contrario, OpenClaw recurre a credenciales OAuth/API-key coincidentes desde perfiles de autenticación, entorno o configuración. Las entradas de transcripción del asistente persisten la misma forma de uso normalizada, incluido usage.cost cuando el modelo activo tiene precios configurados y el proveedor devuelve metadatos de uso. Esto da a /usage cost y al estado de sesión respaldado por transcripción una fuente estable incluso después de que desaparezca el estado activo del runtime.

OpenClaw mantiene la contabilidad de uso del proveedor separada de la instantánea de contexto actual. usage.total del proveedor puede incluir entrada en caché, salida y múltiples llamadas al modelo del bucle de herramientas, por lo que es útil para costes y telemetría, pero puede sobrestimar la ventana de contexto activa. Las visualizaciones y diagnósticos de contexto usan la instantánea de prompt más reciente (promptTokens, o la última llamada al modelo cuando no hay instantánea de prompt disponible) para context.used.

Estimación de costes (cuando se muestra)

Los costes se estiman desde tu configuración de precios del modelo:

models.providers.<provider>.models[].cost

Estos son USD por 1M tokens para input, output, cacheRead y cacheWrite. Si faltan precios, /usage full omite el coste; usa /usage tokens o un messages.usageTemplate personalizado cuando necesites detalles de tokens/caché en cada respuesta. La visualización de costes no se limita a autenticación con API-key: proveedores sin API-key como aws-sdk pueden mostrar coste estimado cuando su entrada de modelo configurada incluye precios locales y el proveedor devuelve metadatos de uso.

Después de que los sidecars y canales alcancen la ruta lista del Gateway, OpenClaw inicia un arranque opcional de precios en segundo plano para referencias de modelos configuradas que aún no tienen precios locales. Ese arranque obtiene catálogos remotos de precios de OpenRouter y LiteLLM. Define models.pricing.enabled: false para omitir esas obtenciones de catálogo en redes sin conexión o restringidas; las entradas explícitas models.providers.*.models[].cost continúan impulsando las estimaciones locales de coste.

TTL de caché e impacto de la poda

El almacenamiento en caché de prompts del proveedor solo se aplica dentro de la ventana TTL de caché. OpenClaw puede ejecutar opcionalmente poda por ttl de caché: poda la sesión una vez que el TTL de caché ha expirado, y luego restablece la ventana de caché para que las solicitudes posteriores puedan reutilizar el contexto recién cacheado en lugar de volver a cachear todo el historial. Esto mantiene más bajos los costes de escritura en caché cuando una sesión queda inactiva más allá del TTL.

Configúralo en Configuración del Gateway y consulta los detalles de comportamiento en Poda de sesiones.

Heartbeat puede mantener la caché caliente durante intervalos de inactividad. Si el TTL de caché de tu modelo es 1h, establecer el intervalo de Heartbeat justo por debajo de eso (por ejemplo, 55m) puede evitar volver a cachear el prompt completo, lo que reduce los costes de escritura en caché.

En configuraciones multiagente, puedes mantener una configuración de modelo compartida y ajustar el comportamiento de caché por agente con agents.list[].params.cacheRetention.

Para una guía completa control por control, consulta Prompt Caching.

Para los precios de la API de Anthropic, las lecturas de caché son significativamente más baratas que los tokens de entrada, mientras que las escrituras de caché se facturan con un multiplicador más alto. Consulta los precios de prompt caching de Anthropic para conocer las tarifas y multiplicadores TTL más recientes: https://docs.anthropic.com/docs/build-with-claude/prompt-caching

Ejemplo: mantener caliente una caché de 1h con Heartbeat

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long"    heartbeat:      every: "55m"

Ejemplo: tráfico mixto con estrategia de caché por agente

agents:  defaults:    model:      primary: "anthropic/claude-opus-4-6"    models:      "anthropic/claude-opus-4-6":        params:          cacheRetention: "long" # default baseline for most agents  list:    - id: "research"      default: true      heartbeat:        every: "55m" # keep long cache warm for deep sessions    - id: "alerts"      params:        cacheRetention: "none" # avoid cache writes for bursty notifications

agents.list[].params se fusiona encima de los params del modelo seleccionado, por lo que puedes sobrescribir solo cacheRetention y heredar los demás valores predeterminados del modelo sin cambios.

Contexto 1M de Anthropic

OpenClaw dimensiona modelos Claude 4.x con capacidad GA, como Opus 4.8, Opus 4.7, Opus 4.6 y Sonnet 4.6, con la ventana de contexto 1M de Anthropic. No necesitas params.context1m: true para esos modelos.

agents:  defaults:    models:      "anthropic/claude-opus-4-6":        alias: opus

Las configuraciones antiguas pueden mantener context1m: true, pero OpenClaw ya no envía el encabezado beta retirado context-1m-2025-08-07 de Anthropic para este ajuste y no expande modelos Claude antiguos no admitidos a 1M.

Requisito: la credencial debe ser apta para uso de contexto largo. Si no, Anthropic responde con un error de límite de tasa del lado del proveedor para esa solicitud.

Si autenticas Anthropic con tokens OAuth/suscripción (sk-ant-oat-*), OpenClaw preserva los encabezados beta de Anthropic requeridos por OAuth mientras elimina la beta retirada context-1m-* si permanece en una configuración antigua.

Consejos para reducir la presión de tokens

• Usa /compact para resumir sesiones largas.
• Recorta las salidas extensas de herramientas en tus flujos de trabajo.
• Reduce agents.defaults.imageMaxDimensionPx para sesiones con muchas capturas de pantalla.
• Mantén breves las descripciones de Skills (la lista de Skills se inyecta en el prompt).
• Prefiere modelos más pequeños para trabajo exploratorio y detallado.

Consulta Skills para ver la fórmula exacta de sobrecarga de la lista de Skills.

Relacionado

• Uso y costos de API
• Almacenamiento en caché de prompts
• Seguimiento del uso