Configuración de API personalizada de IronClaw: proveedores, claves y límites de privacidad

IronClaw acepta una API personalizada en un único bloque de cuatro campos: un bloque [llm.default] en ~/.ironclaw/reborn/config.toml que contiene provider_id, base_url, model y api_key_env; o, cuando no existe ningún bloque, las variables de entorno LLM_BACKEND, LLM_BASE_URL y LLM_API_KEY a las que recurre. Ambas formas son actuales y están documentadas. Lo que las páginas de configuración no reúnen en un solo lugar es la lista de elementos que un endpoint personalizado no obtiene después —streaming nativo, descubrimiento de modelos, puntos de interrupción Anthropic cache_control y una visualización precisa del coste, entre ellos—, y esa es la parte que conviene leer antes de elegir un proveedor.

Primero, una aclaración, porque los resultados de búsqueda están dominados por otros productos. Esta página trata sobre github.com/nearai/ironclaw, descrito por los propios metadatos de su repositorio como «IronClaw is an Agent OS focused on privacy, security and extensibility»: Rust, no archivado y no un fork, 12,626 estrellas, creado el 3 de febrero de 2026 y actualizado por última vez el 21 de septiembre de 2026 (API de GitHub, ese mismo día). No es el ratón gaming de Corsair con ese nombre, el RPG de mesa de Sanguine Productions, el token de criptomonedas IRONCLAW ni el repositorio no relacionado JoasASantos/ironclaw; ninguno de cuyos precios o configuraciones pertenece a esta página. La documentación canónica es docs.ironclaw.com y el propio árbol docs/ del repositorio; un espejo de Mintlify de terceros aparece en los resultados para los mismos títulos y puede estar desactualizado.

Merece la pena citar la atribución en lugar de parafrasearla, porque las propias superficies del proveedor difieren: ironclaw.com coloca «Built by» junto a un logotipo de NEAR y las palabras «Near Foundation» en el cuerpo, y «— by NEAR AI» en el pie de página, mientras que la organización de GitHub es nearai.

Configuración mínima de un proveedor personalizado de IronClaw

La estructura del bloque en ironclaw_config acepta exactamente cuatro campos opcionales, y sus propios comentarios de documentación los describen como reemplazos de la entrada del catálogo: model reemplaza el default_model del proveedor, api_key_env reemplaza su api_key_env y base_url reemplaza su default_base_url. La documentación del proveedor añade que base_url «también funciona con cualquier otro proveedor cuando necesitas dirigirlo mediante un proxy o un endpoint regional», por lo que no es una función exclusiva del adaptador genérico.

[llm.default]
provider_id = "openai_compatible"
base_url    = "https://api.kunavo.com/v1"
model       = "claude-sonnet-4-6"
api_key_env = "LLM_API_KEY"

Tres reglas importantes. Omitir base_url es fatal, no se establece un valor predeterminado: la documentación dice que «deja el bloque sin destino y la resolución del modelo falla», y la entrada de catálogo openai_compatible incluye base_url_required: true. api_key_env recibe el nombre de una variable, nunca una clave: un secreto pegado se «rechaza durante el análisis, no se acepta silenciosamente», y ironclaw config set <provider>.api_key solicita la entrada con el valor oculto. Nada se aplica hasta reiniciar: config set «nunca reinicia nada», sino que muestra el paso ironclaw service restart que todavía debes ejecutar. Y no esperes que config set escriba el bloque por ti: la página de configuración incluye [llm.default] entre las secciones «editadas directamente en config.toml», y config set «rechaza una clave no compatible en lugar de no hacer nada silenciosamente».

La forma basada en el entorno es la alternativa documentada cuando falta [llm.default], y la documentación resuelve la elección claramente: «Ambas funcionan… Prefiere el bloque TOML para una instalación permanente y la forma basada en el entorno para ejecuciones puntuales y contenedores».

export LLM_BACKEND=openai_compatible
export LLM_BASE_URL=https://api.kunavo.com/v1
export LLM_API_KEY=sk-kn-...
export LLM_MODEL=claude-sonnet-4-6

# optional: LLM_EXTRA_HEADERS is the openai_compatible entry's
# extra_headers_env; the timeout is a general .env.example setting
export LLM_EXTRA_HEADERS=X-Title:MyAgent
export LLM_REQUEST_TIMEOUT_SECS=120

El orden de resolución es compiled defaults < config.toml < environment variables < CLI flags, por lo que una variable exportada prevalece silenciosamente sobre el archivo que acabas de editar. La ruta de la CLI evita editar a mano por completo: ironclaw models list, después ironclaw models set-provider <id> --model <model> y después ironclaw models status. Confirma tus rutas con ironclaw config path en lugar de confiar en cualquiera de las ubicaciones documentadas: la página de inicio rápido dice que todo vive en ~/.ironclaw, mientras que las páginas de configuración y puesta en marcha dicen ~/.ironclaw/reborn. Una trampa operativa para los usuarios alojados: la página de configuración dice que los comandos ironclaw service «no funcionan en una instancia alojada de NEAR AI: no existe ningún gestor de servicios de usuario con el que puedan comunicarse», por lo que debes conectarte por SSH para ironclaw config y reiniciar desde el panel de control del agente. Todas las citas se obtuvieron de la rama main el 21 de septiembre de 2026.

Lo que un endpoint personalizado no proporciona

Estas son las propias afirmaciones de IronClaw sobre el comportamiento previsto de su entorno de ejecución, obtenidas del código fuente y de los archivos de contrato de main. No son ejecuciones observadas, y main estaba por delante de la etiqueta de lanzamiento 1.4.0 —publicada el 28 de agosto de 2026, según la API de versiones de GitHub— cuando se consultó.

El catálogo de IronClaw es un catálogo de chat, y Kunavo no ofrece ningún modelo de embeddings, texto a voz o voz a texto, por lo que cualquier parte de tu configuración que necesite uno debe apuntar a otro sitio completamente distinto.

La visualización de costes de IronClaw no es tu factura

Dos rutas independientes calculan importes dentro de IronClaw, no coinciden y ninguna consulta a tu proveedor. price_usage() en ironclaw_common calcula precios a partir de una tabla de tarifas por token fijada en el código y recurre a default_cost(): 0.0000025 de entrada y 0.00001 por token, una tarifa de tipo GPT-4o de $2.50 / $10.00 por millón, con el razonamiento declarado de que «un nuevo modelo de pago nunca recibe silenciosamente un precio cero». Mientras tanto, el StaticModelCostTable del host del bucle hace lo contrario para las reservas de presupuesto: un perfil ausente de su tabla «recurre a None, que el contable trata como coste cero». Y en la ruta llm_costs, el descuento por lectura de caché se deduce del nombre del modelo mediante una subcadena: claude divide entre diez, gpt o un prefijo o1/o3/o4 divide entre dos, y todo lo demás entre uno.

La consecuencia práctica es que budget.user_daily_usd, budget.pause_at y el resto de las claves de [budget] de IronClaw controlan una estimación, no un cargo. Aun así, merece la pena establecerlas en un agente siempre activo —detener pronto un bucle descontrolado es precisamente el objetivo—, pero concilia los datos con el uso registrado por tu proveedor, no con la cifra en pantalla.

Una estimación práctica para un día de agente

Esto es cálculo de tokens, no un coste medido de una tarea ni un límite máximo de facturación. Supongamos un día de actividad del agente que totaliza 1,000,000 tokens de entrada no almacenados en caché y 40,000 tokens de salida: una suposición ilustrativa, elegida porque un entorno siempre activo acumula entradas mediante latidos y rutinas, en lugar de hacerlo mediante respuestas largas. Las tarifas son precios vigentes del catálogo de Kunavo por millón de tokens.

La última columna es la sorpresa útil, y es una propiedad de la cadena del id, no del modelo. vision_models.rs busca coincidencias de subcadenas en una lista fija que incluye claude-opus-, claude-sonnet-, claude-haiku- y claude-fable-, por lo que esos ids enrutan los archivos adjuntos de imágenes; los demás ids de la tabla anterior no coinciden con ninguno de gpt-4o, gemini-1.5, gemini-2 ni con el resto de la lista, y se clasificarían como texto únicamente. Si no hay coincidencia, la pasarela loop-host envía el texto del mensaje sin las partes de imagen y no genera ningún error: la transcripción persistente conserva un puntero <attachments>, pero el modelo nunca ve la imagen. Comprueba la lista de patrones con el id exacto que pretendes escribir antes de dar por hecho que la entrada de imagen funciona. Escala las cifras en dólares según tus propios días antes de tratarlas como un presupuesto. El importe del catálogo de Kunavo es un mínimo de facturación, no un límite máximo: cuando el proveedor ascendente informa de su cargo, la factura es el mayor valor entre el coste del catálogo y el coste del proveedor ascendente multiplicado por el margen aplicable. Los cargos de caché y las herramientas externas quedan fuera de este ejemplo, y la recarga mínima es de $10 en crédito prepago: un mínimo de financiación, no una tarifa por tarea ni una suscripción. Consulta los detalles de facturación.

Qué ruta gana y cuánto cuesta IronClaw en sí

El software es gratuito: la raíz del repositorio incluye LICENSE-APACHE y LICENSE-MIT, y su README indica MIT OR Apache 2.0. No existe una edición de pago del binario ni una tarifa de licencia. Lo que pagas son tokens, además del alojamiento si eliges el del proveedor.

Los precios de los planes alojados se consultaron en ironclaw.com el 21 de septiembre de 2026; no existe una página /pricing, los planes están en la página de inicio y el marcado renderizado muestra los $5 dentro de un span tachado, con $0 como precio vigente. La página de inicio también afirma «Inicia hasta 5 agentes en un Entorno de Ejecución Confiable con hasta 130M de tokens al mes»; esa frase aparece encima de las tres tarjetas y no nombra ningún plan, así que no la asocies con uno. Hay tres cosas que esta guía no pudo establecer y no supondrá: si los planes alojados permiten una clave de terceros, qué compran realmente los créditos incluidos o qué ocurre cuando se agotan, y a qué plan corresponde la cifra de 130M. Las tarifas de tokens se consultaron en near.ai/pricing ese mismo día; allí se indica «No hay ninguna tarifa de plataforma adicional a la tarifa del modelo» y se cubren únicamente sus modelos de texto confidencial.

Hay un límite de privacidad que conviene expresar claramente, porque es la razón por la que algunas personas eligen este runtime. Los controles que describen el README y la página de seguridad del propio IronClaw —secretos «cifrados en reposo» e inyectados en el límite del host, el sandbox WASM para herramientas no confiables, la lista de permitidos de endpoints y la detección de filtraciones— son controles locales sobre la máquina que ejecuta el agente. La atestación del hardware es una propiedad independiente de NEAR AI Cloud: near.ai afirma que la inferencia allí «se ejecuta en un enclave de GPU confidencial Intel TDX + NVIDIA» y que «cada respuesta incluye una prueba de hardware verificable». Dirigir IronClaw a un endpoint de terceros envía el contenido de los prompts a ese endpoint conforme a sus condiciones, y nada de ninguna de las dos listas lo acompaña allí. La tabla «OpenClaw frente a IronClaw» redactada por el proveedor en ironclaw.com es marketing de una de las partes, no una comparación neutral. Además, ten cuidado con los resultados de búsqueda: en una muestra de página de resultados tomada el 17 de septiembre de 2026, las cuatro formas de consulta best api for ironclaw, cheapest api for ironclaw, best model for ironclaw y ironclaw custom provider devolvieron cada una ocho o más resultados de OpenClaw entre los diez primeros, cuyos rankings de modelos describen un producto diferente.

Configúralo y comprueba después el primer cargo

Kunavo publica un endpoint con formato de OpenAI en https://api.kunavo.com/v1 y uno con formato de Anthropic, que se asignan a los identificadores de proveedor openai_compatible y anthropic. Kunavo no ha probado IronClaw en runtime, así que considera el bloque anterior un punto de partida basado en el protocolo documentado, no una afirmación de compatibilidad: mantén disponible una ruta funcional, ejecuta una tarea acotada y lee el cargo que realmente registró tu cuenta. Si controlas Goose desde IronClaw mediante ACP — .env.example documenta el sandbox del Agent Client Protocol y el comando ironclaw acp add goose —, la integración con Goose cubre esa parte por separado, y crear una cuenta de Kunavo proporciona fondos para una clave cuando estés listo. Para las opciones relacionadas, consulta la referencia de la API compatible con OpenAI, las alternativas a OpenRouter y la optimización de costes de IA.

Preguntas frecuentes

Los metadatos del repositorio, providers.json, CONTRACT.md, llm_costs.rs, vision_models.rs, el árbol docs/, ironclaw.com y near.ai/pricing se consultaron el 21 de septiembre de 2026, desde la rama main y no desde la etiqueta de lanzamiento 1.4.0. No se ha enviado ninguna solicitud de IronClaw a un endpoint de Kunavo; todas las afirmaciones de compatibilidad aquí expuestas se basan en la lectura de la documentación de ambas partes. Las tarifas de tokens de Kunavo proceden del catálogo activo y todos los ejemplos en dólares son cálculos ilustrativos de tokens.