OpenClaw

Una entrada models.providers en ~/.openclaw/openclaw.json — baseUrl https://api.kunavo.com, api "anthropic-messages" — conecta un agente OpenClaw siempre activo a Claude; cacheRetention se configura junto a ella, porque un endpoint Anthropic personalizado no recibe marcadores de caché hasta que se establece.

// ~/.openclaw/openclaw.json — merge into the file you already have
{
  models: {
    mode: "merge",
    providers: {
      kunavo: {
        baseUrl: "https://api.kunavo.com",   // origin — no /v1 on this wire
        apiKey: "${KUNAVO_API_KEY}",         // from the environment or ~/.openclaw/.env
        api: "anthropic-messages",
        models: [
          {
            id: "claude-sonnet-5",
            name: "Claude Sonnet 5",
            reasoning: true,
            input: ["text", "image"],
            contextWindow: 1000000,
            contextTokens: 200000,           // optional: compact here, not at 1M
            maxTokens: 32000,
          },
          {
            id: "claude-haiku-4-5",
            name: "Claude Haiku 4.5",
            input: ["text", "image"],
            contextWindow: 200000,
            maxTokens: 16000,
          },
        ],
      },
    },
  },
  agents: {
    defaults: {
      model: { primary: "kunavo/claude-sonnet-5" },
      models: {
        // Required for caching: a custom Anthropic endpoint gets no cache
        // markers from OpenClaw until cacheRetention is set explicitly.
        "kunavo/claude-sonnet-5": { params: { cacheRetention: "short" } },
        "kunavo/claude-haiku-4-5": { params: { cacheRetention: "short" } },
      },
    },
  },
}

Paso a paso

1. Cree una clave en /app/keys y cópiela: se muestra una sola vez.
2. Proporciona la clave al Gateway: añade KUNAVO_API_KEY=sk-kn-... a ~/.openclaw/.env o expórtala en el entorno en el que se inicia el Gateway. Al cargar la configuración, el valor de ${KUNAVO_API_KEY} en el bloque se sustituye por el de allí.
3. Combina el bloque con ~/.openclaw/openclaw.json, conservando los proveedores, agentes y canales que ya tienes. El archivo está en JSON5, así que puedes dejar los comentarios.
4. Ejecuta openclaw config validate. OpenClaw se niega a iniciarse si el archivo contiene una configuración que no reconoce, así que es mejor detectar aquí un error tipográfico que en el siguiente reinicio.
5. Ejecuta openclaw models list --provider kunavo y comprueba que aparezcan ambos identificadores. Si un Gateway en ejecución no ha aplicado el cambio, openclaw gateway restart.
6. Abre una sesión nueva con /new — una sesión existente conserva el modelo que ya tenía —, envía dos mensajes y luego consulta /usage tokens: el segundo turno debería mostrar cacheRead.

Comprobado con Referencia de proveedores personalizados de OpenClaw el 5 de octubre de 2026. La configuración de terceros puede cambiar; si el nombre de un campo ya no coincide con lo que ves, esa página es la autoridad, no esta.

Verifica antes de depurar el cliente

Una solicitud determina si el fallo está en el endpoint, la clave o el archivo de configuración. Si devuelve JSON, la misma URL base y la misma clave funcionan en OpenClaw.

# Settles whether a failure is the endpoint, the key, or the client.
curl -sS https://api.kunavo.com/v1/messages \
  -H "Authorization: Bearer sk-kn-..." \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d '{"model":"claude-sonnet-5","max_tokens":16,"messages":[{"role":"user","content":"ping"}]}'

Qué ID de modelo introducir en el campo

Todos los modelos de texto están disponibles mediante un ID de modelo; la lista activa está en GET /v1/models, y el catálogo con precios está en la página de modelos. Las tarifas son USD por 1M de tokens, entrada / salida.

El protocolo compatible con OpenAI

La misma clave permite acceder a cualquier otra familia de modelos mediante /v1/chat/completions. Regístrala en una segunda entrada de proveedor para mantener separados los dos protocolos y haz referencia a sus modelos como kunavo-openai/<id>:

// ~/.openclaw/openclaw.json — a second entry, beside "kunavo"
{
  models: {
    providers: {
      "kunavo-openai": {
        baseUrl: "https://api.kunavo.com/v1",   // this wire keeps /v1
        apiKey: "${KUNAVO_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "gpt-6-sol",
            name: "GPT-6 Sol",
            reasoning: true,
            input: ["text"],
            contextWindow: 1050000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

// then: /model kunavo-openai/gpt-6-sol

Hay tres diferencias respecto al bloque de arriba. La URL base conserva /v1, como en los ejemplos propios de OpenClaw para proveedores personalizados. api es openai-completions; también es lo que OpenClaw supone cuando un proveedor personalizado especifica baseUrl pero no api. Y maxTokens deja de ser opcional en la práctica: cuando se desconoce el límite de salida de un modelo, OpenClaw no envía ningún límite en este protocolo y Kunavo termina entonces una respuesta de Claude en 4096 tokens.

Los identificadores de Claude también funcionan aquí, y este es el protocolo que debes usar si quieres una sola entrada para todo. Hay dos diferencias: los niveles de razonamiento no se transmiten para Claude en chat completions, y Kunavo, no OpenClaw, coloca los puntos de corte de caché.

Almacenamiento en caché de prompts en cada protocolo

En el protocolo Anthropic, OpenClaw coloca por su cuenta los puntos de corte de caché, pero, para un endpoint personalizado, solo cuando se configura cacheRetention. Su referencia sobre el almacenamiento en caché de prompts lo especifica claramente: el valor predeterminado de short se establece para los proveedores anthropic y anthropic-vertex únicamente, y las demás rutas de la familia Anthropic requieren un valor explícito. El endpoint /v1/messages de Kunavo reenvía el cuerpo tal como se recibió y no añade puntos de corte, así que una configuración sin esas líneas no almacena nada en caché.

short solicita una entrada de cinco minutos y long, una de una hora. Kunavo reenvía cualquiera de los marcadores y factura la escritura a la misma tarifa. Conviene confirmar en tus propios datos de uso si una entrada de una hora sigue disponible cuando llega la siguiente señal de actividad antes de planificar una frecuencia en función de ello: un turno que muestra cacheRead conservó la caché; uno que vuelve a mostrar cacheWrite, no. /usage tokens y /status muestran ambos contadores.

En el protocolo compatible con OpenAI ocurre lo contrario. OpenClaw no envía indicaciones de caché a un endpoint proxy, y Kunavo coloca por su cuenta los puntos de corte para los modelos Claude — en el prompt del sistema, las definiciones de herramientas y el final de la conversación — cuando el prompt tiene la longitud suficiente para almacenarse en caché. No hay nada que configurar, y el proveedor almacena en caché implícitamente los modelos GPT.

Independientemente de qué lado coloque los puntos de corte, la factura es la misma. En Claude Sonnet 5, leer de la caché cuesta $0.14 por cada millón de tokens, frente a $1.40 por la entrada nueva, y escribir en la caché cuesta $1.75: la prima que Claude aplica a la escritura sobre la entrada, cobrada a esa misma tarifa cuando la entrada solicita una duración de una hora. Cada entrada dura cinco minutos y cada lectura la renueva, así que lo que paga un agente depende menos del modelo que de si su siguiente solicitud llega dentro de esa ventana. Las tarifas de caché de cada modelo están en la página sobre el almacenamiento en caché de prompts.

OpenClaw puede mostrar los mismos cálculos localmente. El resumen /usage cost y la línea de coste de /status necesitan un objeto cost en cada fila de modelo; sin él muestran cero aunque Kunavo siga facturando con normalidad. Estas filas se generan a partir del catálogo en tiempo real:

// merge into the rows of models.providers.kunavo.models — USD per 1M tokens
{ id: "claude-sonnet-5", cost: { input: 1.4, output: 7, cacheRead: 0.14, cacheWrite: 1.75 } },
{ id: "claude-haiku-4-5", cost: { input: 0.7, output: 3.5, cacheRead: 0.07, cacheWrite: 0.875 } },
{ id: "claude-opus-5-5", cost: { input: 2.8, output: 14, cacheRead: 0.14, cacheWrite: 3.5 } },
{ id: "claude-fable-5", cost: { input: 7, output: 35, cacheRead: 0.7, cacheWrite: 8.75 } },

Coste diario de un agente siempre activo

Un agente de OpenClaw genera cargos incluso cuando nadie interactúa con él debido al heartbeat: una ejecución programada del agente que, de forma predeterminada, se realiza cada 30 minutos, es decir, 48 al día. Si no se indica lo contrario, se ejecuta en la sesión principal y vuelve a enviar la conversación; la referencia de OpenClaw estima que esa ejecución requiere aproximadamente 100.000 tokens, y varios miles cuando se aísla. Treinta minutos superan la ventana de caché de cinco minutos, así que en cada ejecución se factura de nuevo todo el prompt: a la tarifa de entrada o, si se coloca un punto de ruptura, a la tarifa de escritura más alta. La tabla calcula el costo de un día inactivo con la tarifa de entrada, usando 5000 tokens para la ejecución aislada:

El bloque siguiente muestra la parte económica de esa tabla: heartbeats con Haiku, en una sesión aislada, sin los archivos de inicialización del espacio de trabajo y solo durante las horas de vigilia. Todos los ajustes incluidos proceden de la referencia de heartbeats de OpenClaw. Un intervalo every más largo es la otra opción, y "0m" desactiva las ejecuciones periódicas.

// ~/.openclaw/openclaw.json — what decides the cost of an idle day
{
  agents: {
    defaults: {
      utilityModel: "kunavo/claude-haiku-4-5",   // titles and other short internal tasks
      heartbeat: {
        every: "30m",                            // the default with an API key
        model: "kunavo/claude-haiku-4-5",        // wake-ups on the cheapest tier
        isolatedSession: true,                   // a fresh session, not the whole conversation
        lightContext: true,                      // skip the workspace bootstrap files
        activeHours: { start: "08:00", end: "24:00" },
      },
    },
  },
}

Las horas en que el agente está trabajando realmente son la otra mitad de la factura, y ahí es donde la caché marca la diferencia. Supongamos 100 solicitudes consecutivas, cada una reenviando un contexto de 100.000 tokens, con 2000 tokens nuevos adicionales y devolviendo 800 tokens de salida. En Claude Sonnet 5, eso cuesta aproximadamente $2.31 cuando el contexto se lee de la caché, y aproximadamente $14.84 cuando en cada solicitud el contexto se factura como entrada nueva. El mismo trabajo, el mismo modelo: la diferencia está en si se colocan los puntos de ruptura y si las solicitudes se realizan con menos de cinco minutos de diferencia.

Para tener una referencia basada en mediciones, no en suposiciones: entre las cuentas de Kunavo que ejecutan un agente siempre activo, el coste de un día activo mediano es de $12.67 y el de un día en el percentil 90 es de aproximadamente $163. Son importes facturados hasta 5 de octubre de 2026, según las tarifas vigentes cada día. Es un grupo pequeño, así que interprétalo como la amplitud del intervalo, no como una previsión para tu agente.

Cuando se agota el saldo

Kunavo es de prepago: cada llamada se paga con el saldo de la cartera, y un agente que trabaja mientras duermes lo consume mientras duermes. Si el saldo no alcanza para cubrir una solicitud, esta se rechaza con HTTP 402 y el código insufficient_balance, en cualquiera de los dos protocolos, y no se cobra nada. El rechazo se produce antes de que el saldo de la cartera llegue a cero: cada solicitud primero reserva su costo máximo, es decir, el de su prompt más el de la respuesta más larga que tiene permitido generar. Por eso, cuanto mayor sea el límite de salida que solicite un agente, antes empezarán a rechazarse sus llamadas. El error indica cuánto faltaba, en balance_usd y needed_usd.

OpenClaw determina qué significa un 402 a partir del mensaje que lo acompaña. Según las reglas de OpenClaw 2026.9.8, el rechazo de la cartera es un error de facturación, y su referencia sobre la conmutación por error explica qué ocurre después: la credencial se desactiva durante diez minutos, la ejecución pasa al siguiente modelo de agents.defaults.model.fallbacks y la recarga no elimina ese período; por eso, después de añadir fondos, el agente puede seguir sin usar kunavo/… hasta que termine. El rechazo por alcanzar el límite mensual de una clave se interpreta de otra manera. El mensaje indica un límite que se restablece, lo que las mismas reglas clasifican como límite de frecuencia: OpenClaw vuelve a intentarlo y luego pone la credencial en pausa durante 30 segundos al principio, hasta un máximo de cinco minutos. openclaw models status muestra las credenciales desactivadas y cuándo se reactivan.

Dos ajustes mantienen a un agente desatendido lejos de esa situación, y cumplen funciones distintas:

• Recarga automática, en Facturación. Guarda una tarjeta una sola vez y configura tres cifras: el saldo por debajo del cual se recargará la cuenta, el importe que se añadirá cada vez y un límite mensual. A partir de entonces, la billetera se recarga en cuestión de segundos cuando una llamada hace que el saldo caiga por debajo del umbral. Si llega una solicitud mientras el saldo sigue siendo insuficiente, espera a que se complete el cargo y luego se atiende en lugar de rechazarse. Aun así, se devuelve un 402 si no se puede realizar el cargo —por ejemplo, si se rechaza la tarjeta o se alcanza el límite mensual—, o si una solicitud reserva más de lo que contiene la billetera después de la recarga. Se necesita una tarjeta o Link; no se pueden realizar cargos automáticos mediante Alipay, WeChat Pay, Pix ni los demás métodos de pago locales.
• Un límite mensual para la clave, en Claves API. Asigna al agente una clave propia y establece el importe máximo que podrá gastar esa clave durante un mes natural. Al superar esa cifra, sus llamadas se rechazan con un 402 y no se cobra nada, mientras que las demás claves siguen funcionando. Ese es el límite que necesita un bucle descontrolado y que la billetera no puede ofrecer, porque todas las claves utilizan la misma billetera.

Establece el umbral de recarga por encima de lo que reserva una solicitud y calcula el importe según el gasto diario de tu agente, no según el mínimo: la recarga mínima es $10 y el gasto mediano de un día de funcionamiento continuo indicado arriba es $12.67. Los límites de la recarga automática están en la página de facturación, y el cuerpo completo del error, en la página de errores.

Guías relacionadas

• La mejor API para OpenClaw: elegir un proveedor y un modelo para cada tipo de tarea.
• Precios de OpenClaw: el coste total de funcionamiento, incluido el software, el alojamiento, los modelos y las herramientas.
• OpenClaw con varios agentes y modelos: dirigir cada agente a su propio modelo y atribuir el coste según la ruta.
• Hermes frente a OpenClaw: la misma configuración para el otro agente, en la página de Hermes Agent.