OpenClaw ha sido diseñado para ser independiente del proveedor, lo cual es su superpoder oculto. Soporta los nombres habituales como OpenAI y Anthropic, pero también permite conectar cualquier API compatible con OpenAI como proveedor personalizado (OpenClaw docs, 2026). Esa elección de diseño es la que te permite mantener el agente que te gusta mientras lo ejecutas en modelos de pesos abiertos mucho más económicos, que cuestan una fracción del precio por token de los modelos de vanguardia.
El truco es que la configuración tiene un paso que casi todo el mundo omite, y hacerlo mal produce un mensaje de error que lleva a los usuarios por el camino equivocado. Esta guía detalla cómo realizar correctamente la configuración de una API personalizada en OpenClaw: cómo funciona internamente, la configuración exacta a copiar, el problema de la lista blanca y cómo verificar la conexión. Dedícale unos cinco minutos.
Por qué configurar una API personalizada en OpenClaw
La razón honesta es el coste. Las herramientas agénticas como OpenClaw reenvían el contexto acumulado en cada paso de razonamiento, por lo que consumen de 10 a 100 veces más tokens que una ventana de chat para la misma tarea (LeanOps, 2026). Ese multiplicador es la razón por la que las facturas de los agentes suben tan rápido; los usuarios intensivos de modelos de vanguardia alcanzan unos 13 USD por desarrollador activo al día (CloudZero, 2026). Una configuración de API personalizada en OpenClaw ataca esa factura donde realmente reside: el precio por token. Apunta el agente a un modelo de pesos abiertos en lugar de a uno de vanguardia y el coste unitario cae drásticamente, a menudo un 70% o más en trabajos rutinarios, mientras que la diferencia de calidad en la programación diaria sigue siendo pequeña. Mantienes el flujo de trabajo de OpenClaw que ya conoces y simplemente cambias lo que responde a las solicitudes. Hay una segunda razón importante para los equipos fuera de las regiones en las que un proveedor sirve directamente. Un proveedor personalizado te ofrece una forma estable y compatible de ejecutar el agente sin depender de la facturación, el calendario de lanzamientos o la disponibilidad regional de una sola empresa.
Cómo funciona la configuración de una API personalizada en OpenClaw: Los dos pasos que la gente omite
Antes de pegar la configuración, entiende el modelo que usa OpenClaw, porque explica el error con el que todos se topan. Un proveedor personalizado se define en dos lugares, y ambos son obligatorios.
Primero, describes el proveedor en sí en la sección models.providers: su URL base, clave API, el protocolo de red (openai-completions para cualquier endpoint compatible con OpenAI) y la lista de modelos que ofrece. Segundo, y esta es la parte que la gente omite, debes incluir el modelo exacto en la lista blanca dentro de agents.defaults.models, usando el identificador totalmente calificado nombre-proveedor/nombre-modelo (OpenClaw docs, 2026). Definir un proveedor no hace que sus modelos sean utilizables automáticamente. OpenClaw rechazará cualquier cosa que no esté en la lista blanca.
Eso es intencional. La lista blanca es lo que te permite definir un gran catálogo de proveedores y modelos, pero exponer solo los específicos a los que realmente quieres que el agente acceda. Una vez que interiorizas que los proveedores y la lista blanca son capas separadas, el resto de la configuración de la API personalizada en OpenClaw es mecánico.
Configuración de API personalizada en OpenClaw, paso a paso
El siguiente ejemplo utiliza Atlas Cloud como proveedor, ya que expone un endpoint compatible con OpenAI que centraliza los principales modelos de pesos abiertos bajo una sola clave. Esto mantiene la configuración corta y te permite cambiar de modelo más tarde sin registrar nada nuevo. Los mismos pasos se aplican a cualquier proveedor compatible; solo cambian la URL base y la clave.
Paso 1: Obtén tu endpoint y clave API
Al final de este paso tendrás dos cadenas: una URL base y una clave.
- Crea una cuenta con tu proveedor y abre su sección de claves API.
- Genera una clave con alcance para uso de programación. En Atlas Cloud, selecciona Coding Plan como tipo de clave, lo que la vincula a la cuota de programación basada en créditos en lugar de al pago por uso general.
- Anota la URL base. Para clientes compatibles con OpenAI como OpenClaw, Atlas Cloud utiliza https://api.atlascloud.ai/v1 (el sufijo /v1 es importante aquí).
Paso 2: Ejecuta el asistente de integración, la forma más rápida
Al final de este paso la conexión estará activa, de la forma sencilla. En una terminal, inicia el asistente guiado:
Bash1openclaw onboard
Luego sigue las indicaciones: elige Yes, selecciona QuickStart y elige Custom Provider. El asistente pedirá la URL base de la API (https://api.atlascloud.ai/v1), la clave API que copiaste y el ID del modelo. Asegúrate de elegir el protocolo OpenAI-compatible cuando se te solicite. Cuando aparezca Verification successful, el endpoint funciona. Termina dándole al endpoint un ID y un nombre descriptivo. La ventaja oculta del asistente: escribe tanto la definición del proveedor como la entrada de la lista blanca del modelo por ti, y luego reinicia la puerta de enlace, por lo que te saltas por completo el modo de fallo más común.
Paso 3: O edita el archivo de configuración directamente
Al final de este paso entenderás lo que el asistente escribió realmente, lo cual importa cuando quieras añadir más modelos más adelante. La configuración reside en ~/.openclaw/openclaw.json (OpenClaw docs, 2026). Define el proveedor:
JSON1{ 2 "models": { 3 "mode": "merge", 4 "providers": { 5 "atlascloud": { 6 "baseUrl": "https://api.atlascloud.ai/v1", 7 "apiKey": "tu-clave-api-atlas", 8 "api": "openai-completions", 9 "models": [ 10 { "id": "zai-org/glm-5.1", "name": "glm-5.1", "contextWindow": 200000 } 11 ] 12 } 13 } 14 } 15}
El "mode": "merge" mantiene intactos tus proveedores existentes en lugar de sobrescribirlos. Para los proveedores personalizados, campos como reasoning, cost y maxTokens son opcionales y vuelven a valores predeterminados sensatos, por lo que no necesitas rellenar todo para empezar.
Paso 4: Añade el modelo a la lista blanca
Al final de este paso, OpenClaw te permitirá usar el modelo. Este es el paso que la gente omite. Añade el identificador totalmente calificado a la lista blanca:
JSON1{ 2 "agents": { 3 "defaults": { 4 "models": { 5 "atlascloud/zai-org/glm-5.1": { "alias": "glm" } 6 } 7 } 8 } 9}
La clave es el nombre de tu proveedor seguido del ID del modelo exactamente como lo definiste. El alias es solo un atajo que puedes escribir en lugar de la ruta completa. Sin este bloque, el proveedor existe pero cada solicitud será rechazada.
Paso 5: Verifica tu configuración de API personalizada en OpenClaw
Al final de este paso sabrás que funciona. Inicia OpenClaw, selecciona tu modelo (o su alias) y dale una tarea trivial, como explicar un archivo. Una respuesta normal significa que las solicitudes están llegando a tu endpoint. Si ves "model not allowed", revisa el Paso 4; la clave de la lista blanca casi con seguridad no coincide exactamente con los nombres del proveedor y del modelo. Si recibes un error de autenticación, la clave es incorrecta o tiene un espacio de más. Si no puede conectarse, verifica de nuevo la URL base y el sufijo /v1.
Elegir un modelo para tu configuración de API personalizada
Elegir el modelo es donde se deciden los ahorros. El patrón inteligente es usar por defecto un modelo abierto, fuerte y barato para el trabajo diario y reservar uno más caro para los razonamientos más difíciles. La capacidad es real: en SWE-Bench Pro, los modelos abiertos líderes obtienen puntuaciones en el rango alto de 70 frente a aproximadamente 91 de los modelos de vanguardia (Codersera, 2026), una brecha significativa en los problemas más difíciles pero pequeña para el trabajo de funciones rutinarias y refactorizaciones. En una puerta de enlace basada en créditos, cada modelo tiene un multiplicador que asigna el uso de tokens a créditos, lo que facilita la comparación de costes relativos:
| ID de modelo | Contexto | Multiplicador entrada | Multiplicador salida | Ahorro aprox. vs oficial |
|---|---|---|---|---|
| deepseek-ai/deepseek-v4-flash | 1M | 0.23 | 0.46 | ~50% |
| deepseek-ai/deepseek-v3.2 | 160K | 0.42 | 0.62 | ~55% |
| minimaxai/minimax-m2.5 | 200K | 0.65 | 2.18 | ~45% |
| moonshotai/kimi-k2.6 | 262K | 1.72 | 7.26 | ~45% |
| zai-org/glm-5.1 | 200K | 2.54 | 7.99 | ~45% |
Fuente: Reglas de crédito del Plan de Programación de Atlas Cloud. Coste en créditos = tokens de entrada × multiplicador de entrada + tokens de salida × multiplicador de salida. Una opción sensata: ejecuta GLM-5.1 o Kimi K2.6 para programación interactiva, baja a DeepSeek V4 Flash para trabajos de gran volumen o en segundo plano, y solo recurre a un modelo de vanguardia para la tarea ocasional que un modelo abierto no pueda resolver. Como todo reside detrás de un mismo proveedor, cambiar es solo un cambio de una línea en el alias que llamas.
Un endpoint para OpenClaw, Claude Code y Codex
El endpoint que potencia tu configuración de OpenClaw no se limita a OpenClaw. La mayoría de los desarrolladores ejecutan más de un agente, y apuntar cada uno a un proveedor diferente significa hacer malabares con claves, paneles de control y facturas separadas. Consolidar todo en un único endpoint compatible con OpenAI reduce eso a un solo fondo de créditos y un solo lugar para cambiar de modelos.
Como Atlas Cloud expone la misma URL base en diferentes herramientas, la configuración de OpenClaw anterior tiene equivalentes directos en otros lugares. Claude Code lee su backend desde ~/.claude/settings.json usando ANTHROPIC_BASE_URL configurada en https://api.atlascloud.ai (nota: no lleva /v1 para Claude Code específicamente). Codex utiliza ~/.codex/config.toml con base_url apuntando a https://api.atlascloud.ai/v1. Los clientes estilo Cursor, OpenCode y Copilot aceptan el mismo endpoint /v1. Una clave, un presupuesto, todas las herramientas.
Esa consolidación también mejora el control de gastos. Un plan que refresca una asignación fija de créditos diarios a medianoche pone un techo estructural a un bucle de agente fuera de control, mientras que los paquetes de pago por uso absorben el pico ocasional. Los planes de Atlas Cloud comienzan en 10 USD al mes, los paquetes de pago por uso tienen un 41% de descuento y las actualizaciones a mitad de ciclo son prorrateadas, por lo que un cambio de nivel puede costar solo la diferencia en lugar de un plan nuevo.
Errores comunes en la configuración de API personalizada de OpenClaw
La mayoría de las configuraciones fallidas se remontan a una breve lista de errores, y casi todos residen en la configuración más que en algo más profundo. Olvidar la lista blanca. El error más común. Definir el proveedor es solo la mitad del trabajo. Si ves "model not allowed", el modelo falta en agents.defaults.models o la clave no coincide (haimaker, 2026). Clave de lista blanca no coincidente. La clave de la lista blanca debe ser nombre-proveedor/nombre-modelo usando las cadenas exactas que definiste. Un error tipográfico en cualquiera de las dos mitades produce el mismo rechazo que omitirlo por completo. Ruta de URL base incorrecta. Las herramientas compatibles con OpenAI como OpenClaw esperan la ruta /v1. Dejarla fuera, o añadirla donde una herramienta específica no la quiere, causa errores de conexión. Sobrescribir en lugar de fusionar. Si editas la configuración a mano sin "mode": "merge", puedes borrar tus otros proveedores. Mantén el modo de fusión a menos que quieras reemplazar todo.
Preguntas frecuentes: Configuración de API personalizada de OpenClaw
¿Es difícil realizar una configuración de API personalizada en OpenClaw?
No. El camino más rápido es el asistente openclaw onboard, que escribe la definición del proveedor y la lista blanca del modelo por ti y toma unos cinco minutos. El camino manual son dos pequeñas ediciones JSON. El único obstáculo conceptual es recordar que definir un proveedor y añadir un modelo a la lista blanca son pasos separados.
¿Cuál es el error más común en la configuración de API personalizada de OpenClaw?
El rechazo "model not allowed", que casi siempre significa que el modelo falta en la lista blanca en agents.defaults.models, o que la clave nombre-proveedor/nombre-modelo tiene un error tipográfico. No incluir el modelo en la lista blanca es la causa número uno de este error (haimaker, 2026), que es exactamente por lo que el asistente de integración lo maneja automáticamente.
¿Qué modelo debería elegir para mi configuración de API personalizada en OpenClaw?
Para programación interactiva, un modelo abierto general fuerte como GLM-5.1 o Kimi K2.6 es una buena opción por defecto. Para trabajos de gran volumen o en segundo plano, un modelo más barato como DeepSeek V4 Flash tiene sentido. Mantén un modelo de vanguardia en espera solo para tareas que un modelo abierto realmente no pueda resolver.
¿Cuánto puedo ahorrar realmente con un proveedor personalizado?
Depende del modelo, pero la diferencia es grande. DeepSeek V4 Flash funciona cerca de 0.14 USD por millón de tokens de entrada frente a varios dólares de los modelos de vanguardia (Codersera, 2026), por lo que derivar el trabajo rutinario a un modelo abierto suele reducir la factura por token en un 70% o más sin cambiar tu forma de trabajar.
¿Puedo volver a mi proveedor original más tarde?
Sí. Los proveedores personalizados son aditivos cuando mantienes "mode": "merge", por lo que tus proveedores originales siguen definidos. Cambiar es solo cuestión de seleccionar un modelo o alias diferente en OpenClaw, y puedes eliminar un bloque de proveedor en cualquier momento.
Conclusión
Una configuración de API personalizada en OpenClaw es uno de los cambios de cinco minutos con mayor impacto que un desarrollador puede realizar en 2026. El agente sigue siendo el mismo, pero el backend y la factura no. Define el proveedor, añade el modelo a la lista blanca, apúntalo a una opción de pesos abiertos y mantendrás el flujo de trabajo de OpenClaw que conoces mientras pagas una fracción de los precios de vanguardia. Si quieres tenerlo bajo una sola clave y un solo presupuesto que también cubra Claude Code y Codex, puedes iniciarlo a través de la consola del Plan de Programación de Atlas Cloud y cambiar de modelo siempre que la tarea cambie.
