Configurar los modelos de OpenClaw: API, Ollama y LM Studio

Configura el proveedor en el equipo que ejecuta el Gateway, selecciona el modelo exacto y prueba primero una respuesta y después una herramienta. El asistente openclaw onboard permite conectar tanto proveedores con cuenta como Ollama y LM Studio. Cuando el acceso está preparado, openclaw models set cambia el modelo predeterminado; /model permite elegir uno para una conversación concreta.

Para Ollama, utiliza la conexión nativa con api: "ollama" y una URL base sin /v1. Para LM Studio y vLLM, la inferencia compatible con OpenAI sí utiliza /v1. Esta diferencia importa cuando el agente necesita llamar a herramientas, no solo generar texto.

Los pasos siguientes corresponden a la documentación consultada el 4 de octubre de 2026. Son procedimientos documentados: no hemos realizado llamadas de pago, pruebas de GPU ni una instalación con credenciales reales para esta guía.

Antes de conectar: comprueba dónde trabaja el Gateway

Abre una terminal en el equipo de OpenClaw y comprueba la instalación:

openclaw --version
openclaw gateway status

Si el Gateway funciona dentro de un contenedor, en un servidor remoto o con un usuario de servicio, la conexión al modelo debe funcionar desde ese entorno. Que Ollama responda en tu portátil no demuestra que el contenedor pueda alcanzarlo. Del mismo modo, exportar una clave en tu terminal no la hace accesible automáticamente a un servicio de systemd o launchd.

Elige el acceso que puedes mantener en ese equipo:

Para empezar, conecta un solo acceso y valida el trabajo que necesitas. Añade alternativas cuando puedas identificar qué cuenta, servidor y modelo utiliza cada una. La guía de proveedores y la guía de autenticación del Gateway describen estas conexiones y el acceso de los servicios a las credenciales.

Conectar una API y seleccionar un modelo disponible

Ejecuta el asistente en el equipo del Gateway:

openclaw onboard

Escoge el proveedor y completa su método de autenticación. Para una instalación existente, también puedes abrir Settings → Models → Connect provider, elegir el agente y conectar la cuenta. Test & use comprueba una respuesta y selecciona el modelo; guardar una cuenta por sí solo no equivale a probar una llamada. Estos controles aparecen en la documentación de conexión de cuentas.

En OpenAI, puedes elegir una clave de Platform o un inicio de sesión de Codex. Por ejemplo, para conectar una clave mediante el flujo interactivo:

openclaw models auth login --provider openai --method api-key
openclaw models list --provider openai

Si necesitas el inicio de sesión de Codex desde un servidor sin navegador, el método documentado es:

openclaw models auth login --provider openai --method device-code

Completa la aprobación en el navegador y espera a que la terminal confirme el acceso. Después consulta el catálogo y selecciona una referencia que esté disponible para esa cuenta. Este ejemplo usa un modelo de la configuración actual de OpenClaw; úsalo únicamente si tu acceso lo permite:

openclaw models set openai/gpt-6-astra
openclaw models status

Conectar o renovar una cuenta conserva el modelo predeterminado existente, salvo que solicites expresamente cambiarlo, por ejemplo con --set-default. Por eso conviene ejecutar models set cuando tu intención sea cambiar de modelo. La guía específica de OpenAI y las reglas de selección explican este comportamiento.

La referencia openai/modelo identifica el proveedor y el modelo; no determina por sí sola la ejecución del agente ni cómo se factura. Una clave API utiliza los permisos y la facturación de su proyecto. Un inicio de sesión de Codex usa el acceso concedido a esa cuenta. El catálogo, el método de autenticación y el proceso que ejecuta las herramientas deben comprobarse por separado; elegir un nombre GPT no garantiza cobertura por una suscripción. Consulta la comparación de autenticación de OpenAI en OpenClaw.

Con Anthropic, la clave API y el inicio de sesión nativo de Claude CLI son accesos distintos. Si escoges Claude CLI, el ejecutable y su cuenta deben estar disponibles para el usuario del Gateway; Claude administra ese inicio de sesión. Para Gemini, las referencias actuales son google/* y el acceso habitual es una clave de AI Studio; google-gemini-cli es una ejecución opcional distinta. Amazon Bedrock utiliza credenciales AWS, región y acceso al modelo, no una clave de Anthropic. Las guías de Anthropic, Google y Bedrock detallan cada caso.

Configurar Ollama como modelo local

Instala Ollama en el equipo donde vaya a ejecutarse el modelo y mantén su servidor activo. Si la aplicación ya lo ha iniciado, no abras un segundo servidor. Para iniciarlo manualmente puedes usar:

ollama serve

En otra terminal, consulta qué modelos tienes:

ollama list

Si aún no tienes un modelo adecuado, descarga uno. La documentación usa gemma4 como ejemplo; su descarga no demuestra que vaya a caber o funcionar bien en tu equipo:

ollama pull gemma4

El tamaño de los pesos, la cuantización, el contexto solicitado y el programa que los ejecuta afectan al consumo de memoria. Elige un modelo que puedas cargar y prueba tu tarea con él; no deduzcas una velocidad concreta de una cifra de RAM.

Completa la conexión guiada en modo Local only

Ejecuta openclaw onboard, selecciona Ollama y elige Local only. Si Ollama y el Gateway están en el mismo equipo, conserva la dirección local que propone el asistente. Si están separados, introduce una dirección del servidor que el Gateway pueda alcanzar; ese servidor debe escuchar en la interfaz de red adecuada y permitir la conexión en el cortafuegos.

Selecciona el modelo instalado y deja que el asistente complete la comprobación real antes de guardar la conexión. En una configuración guiada nueva, la elección automática considera modelos ya cargados, con soporte de herramientas y al menos 16K de contexto confirmados por Ollama. Un modelo instalado pero inactivo no es un candidato automático. En la configuración de escritorio, Choose connection → Local only permite preparar expresamente un modelo instalado para la comprobación. Si el asistente propone descargar otro, revisa y aprueba esa descarga; el descubrimiento automático no descarga ni carga modelos inactivos. Son las condiciones actuales de la configuración guiada de Ollama.

Después comprueba el catálogo:

openclaw models list --provider ollama
openclaw models status

Usa el nombre exacto mostrado en tu instalación, incluida la etiqueta si aparece. Para el ejemplo documentado:

openclaw models set ollama/gemma4

El descubrimiento general del catálogo y la selección automática del asistente no tienen el mismo criterio. El primero consulta los modelos instalados con /api/tags y sus capacidades con /api/show; el segundo exige las condiciones de carga, herramientas y contexto anteriores. Además, una lista manual no vacía en models.providers.ollama.models omite el descubrimiento. Si falta un modelo, revisa primero qué modalidad estás usando. Véase descubrimiento de modelos Ollama.

Mantén la API nativa y distingue los modos de nube

En una configuración manual de Ollama, api: "ollama" utiliza /api/chat y la URL base del servidor sin /v1. La conexión nativa admite streaming y herramientas juntos. Añadir /v1 y usar openai-completions selecciona la compatibilidad antigua, cuyas llamadas a herramientas no tienen la misma fiabilidad; no desactives streaming por defecto para corregir una conexión nativa. La configuración de Ollama y su apartado de streaming distinguen ambas rutas.

Para hosts locales o de red privada, OpenClaw utiliza el marcador no secreto ollama-local. Un servidor público remoto y Ollama Cloud requieren una credencial real. Los modos del asistente tienen consecuencias distintas:

• Local only: conecta los modelos locales del servidor seleccionado.
• Cloud + Local: usa ese servidor para modelos locales y modelos :cloud; el acceso de nube requiere que el host haya iniciado sesión con ollama signin.
• Cloud only: conecta el acceso de nube; para usarlo directamente sin un servidor local, OpenClaw ofrece el proveedor separado ollama-cloud.

Un modelo :cloud sigue ejecutándose remotamente aunque lo solicites a través de tu servidor Ollama. Y usar inferencia local no impide por sí solo que una herramienta, un complemento, la memoria o un modelo de respaldo envíe datos a otro servicio. Revisa esos destinos si quieres limitar las salidas de información. La guía de modos y autenticación establece estas diferencias.

Configurar LM Studio o conectar un servidor vLLM

Con LM Studio, instala la aplicación o el servicio llmster, prepara un modelo y arranca el servidor:

lms server start --port 1234
openclaw onboard

Elige LM Studio en el asistente, conserva el servidor local propuesto cuando comparta equipo con el Gateway y escoge el modelo. Si has activado autenticación en LM Studio, usa su token real, accesible mediante LM_API_TOKEN; si está desactivada, deja la clave vacía en el asistente. No inventes una clave secreta para un servidor sin autenticación.

OpenClaw consulta /api/v1/models para descubrir los modelos y puede usar /api/v1/models/load para cargarlos. La inferencia se envía a /v1/chat/completions; aquí sí corresponde conservar /v1. La selección guiada exige entrenamiento para herramientas y al menos 16K de contexto efectivo; en un modelo cargado, prevalece el contexto de esa instancia sobre su máximo anunciado. La guía de LM Studio explica este flujo.

Consulta y selecciona el identificador exacto:

openclaw models list --provider lmstudio
openclaw models set lmstudio/qwen/qwen3.5-9b

El segundo comando es un ejemplo: úsalo si tu catálogo contiene esa referencia. Una clave de LM Studio de tipo autor/modelo recibe el prefijo lmstudio/ en OpenClaw. Si el servidor está en otra máquina, debe escuchar más allá de su interfaz local y ser accesible desde el Gateway; cambiar únicamente el nombre de host no modifica dónde escucha el servidor.

Si ya tienes vLLM administrado y sirviendo un modelo, conserva su API compatible /v1 y el adaptador openai-completions. Puedes activar el descubrimiento con VLLM_API_KEY: el valor vllm-local solo es un marcador válido cuando el servidor no exige autenticación. Si exige una clave, usa la que realmente ha configurado el administrador. Después consulta openclaw models list --provider vllm y selecciona la referencia exacta que devuelve.

Antes de dar por válidas las herramientas, revisa la plantilla de chat y el analizador de llamadas que requiere ese modelo en vLLM. Texto con apariencia de JSON o XML no es una herramienta ejecutada. No impongas tool_choice: "required" a todos los modelos: es una solución específica que cambia el comportamiento de cada turno. Consulta la guía de vLLM.

Cómo cambiar de modelo sin confundir el agente y la conversación

openclaw models set cambia el predeterminado configurado. Dentro de una conversación, /model cambia la elección de esa sesión. Si ya habías fijado un modelo, cambiar el predeterminado no sustituye esa elección anterior.

Para consultar una conversación y devolverla al predeterminado:

/model status
/model default

Para fijar expresamente el ejemplo local en esa conversación:

/model ollama/gemma4

Sustituye la referencia por la de tu catálogo. Una selección explícita es estricta: si ese proveedor o modelo falla, OpenClaw muestra el error en lugar de responder silenciosamente con otro modelo. En cambio, el predeterminado puede utilizar su lista configurada de respaldo. La documentación de modelos explica el predeterminado, los alias y las restricciones opcionales de modelPolicy.allow.

Un alias en agents.defaults.models facilita la selección, pero no registra por sí solo un modelo nuevo en un servidor. Para un proveedor personalizado necesitas definir la URL base, el adaptador API y un identificador real en models.providers. Los campos de capacidad deben corresponder al modelo servido: contextWindow describe la ventana nativa, contextTokens limita la entrada activa y maxTokens limita la salida. Un coste 0 en esos metadatos tampoco es una factura. Véase proveedores personalizados.

Comprueba una respuesta y una herramienta antes de automatizar

Haz las comprobaciones en este orden para saber qué has conseguido:

main es un ejemplo: utiliza tu agente real. Un resultado correcto de models status sin --probe no prueba una petición al modelo, y un perfil guardado no garantiza que se pueda utilizar en ese momento. La referencia de la CLI separa expresamente esas comprobaciones.

Para aislar la conexión Ollama del funcionamiento completo del agente, puedes ejecutar esta prueba breve en el equipo configurado, con el modelo del ejemplo ya disponible:

openclaw infer model run \
  --local \
  --model ollama/gemma4 \
  --prompt "Responde exactamente: conexión correcta" \
  --json

El resultado buscado es una respuesta del modelo seleccionado sin error de conexión o autenticación. Esta prueba omite las herramientas del chat, la memoria y el contexto de sesión; no demuestra que el agente sepa usar herramientas. La documentación de estas pruebas breves describe ese alcance.

Para comprobar una herramienta, crea tú un archivo sin información sensible en el espacio de trabajo del agente:

printf 'Código de comprobación: olivo-742\n' > openclaw-prueba.txt

En una conversación de prueba, pide: «Lee openclaw-prueba.txt con la herramienta de lectura de archivos y dime su código. No modifiques archivos ni ejecutes comandos». Revisa el registro de la herramienta: debe mostrar una lectura real del archivo, su resultado y la respuesta olivo-742. Una respuesta inventada, una llamada escrita como texto o la mera afirmación de haber leído el archivo no cuentan como éxito.

Si no aparece ninguna lectura, comprueba que el archivo esté en el espacio de trabajo correcto y que la política del agente permita esa herramienta. Si la prueba breve funciona pero falla la tarea con herramientas, revisa el modelo, el contexto y la compatibilidad de la API antes de sustituir una credencial que ya responde. Esta comprobación práctica permite aceptar o descartar un modelo para tu tarea; no establece que sea el mejor en todos los usos.

Una prueba directa con models status --probe es opcional. Envía peticiones reales, puede consumir tokens y requiere uso exclusivo del directorio de estado: detén antes el Gateway con openclaw gateway stop y espera a que terminen la prueba y su limpieza antes de volver a iniciar el servicio. Un timeout no confirma que ya se hayan liberado los recursos. Para una primera configuración, la respuesta breve en la conversación evita esa parada adicional. Consulta las condiciones de probe.

Cuándo activar modelos de respaldo

Actívalos cuando ya hayas comprobado el principal y la alternativa y aceptes qué cuenta recibirá las peticiones si hay un fallo. El respaldo sirve para recuperación; no reparte automáticamente cada tarea al modelo más barato.

Este fragmento se integra en la configuración existente. Requiere que ollama/gemma4 funcione y que hayas autenticado y comprobado openai/gpt-6-astra; sustituye las referencias por las que hayas validado:

{
  agents: {
    defaults: {
      model: {
        primary: "ollama/gemma4",
        fallbacks: ["openai/gpt-6-astra"],
      },
    },
  },
}

En una conversación que deba seguir esta configuración, usa /model default. OpenClaw intenta la recuperación limitada del mismo modelo y la rotación de credenciales aplicables antes de avanzar a otro modelo. El respaldo actual se utiliza para ese turno sin sustituir el modelo seleccionado para el siguiente. Las versiones 2026.4.26 a 2026.6.0 podían guardar una selección automática; la documentación actual conserva su tratamiento como estado histórico. Véase conmutación por error de modelos.

Si el agente tiene su propio modelo principal, necesita sus propios fallbacks para admitir alternativas; una lista [] los desactiva. Y una selección concreta hecha con /model sigue siendo estricta aunque el predeterminado tenga respaldo. Consulta /status para distinguir el modelo seleccionado del que haya respondido como alternativa.

Un respaldo hacia una API externa puede cambiar el destino de los datos y la facturación. Tampoco garantiza continuidad ante cancelaciones, límites del turno o fallos de todas las alternativas. Si una tarea ya había realizado una acción, comprueba ese resultado antes de repetirla; cambiar de modelo no deshace una acción anterior.

Si la configuración no responde, empieza por el síntoma

Para un 401, continúa con la guía de errores de autenticación de OpenClaw, que diferencia el token del Gateway, la API del modelo y Claude CLI. No cambies todos los tokens a la vez: primero identifica el acceso que falla.

Si solo falla la carga inicial de un modelo local, la documentación permite ajustar models.providers.ollama.timeoutSeconds y params.keep_alive. Amplía el tiempo de espera cuando la conexión y la carga estén identificadas; esperar más no corrige un servidor inaccesible ni aumenta la memoria. Ajusta también el contexto efectivo cuando el equipo no pueda sostenerlo. Consulta las opciones avanzadas de Ollama.

Preguntas frecuentes

¿Necesito una clave API para usar Ollama local?

No necesitas una credencial real para un host local o de red privada en la conexión documentada: OpenClaw utiliza ollama-local. Los hosts públicos remotos y Ollama Cloud sí requieren autenticación real. El marcador no concede acceso a la nube. Véase autenticación de Ollama.

¿Por qué sigue respondiendo el modelo anterior tras cambiarlo?

La conversación puede tener una selección fija. Consulta /model status y usa /model default si quieres aplicar el predeterminado configurado. Cambiar agents.defaults.model.primary no reescribe las selecciones de las sesiones existentes, según la guía de modelos.

¿Qué modelo local debería elegir para OpenClaw?

Uno que puedas cargar con el contexto necesario y que complete tu tarea con herramientas. Empieza con un modelo compatible que ya tengas o que proponga el asistente, comprueba una respuesta y una lectura de archivo y conserva el que cumpla ese trabajo en tu equipo. Las condiciones del asistente de Ollama y LM Studio filtran capacidades; no son una clasificación de rendimiento.

¿Un modelo local hace que todo OpenClaw sea privado o gratuito?

No. La inferencia local y los demás destinos son decisiones separadas: herramientas, complementos, memoria y respaldos pueden contactar con servicios externos. Además, la ejecución local consume recursos de tu equipo y las cuentas de nube mantienen sus propias condiciones. Comprueba el acceso que utiliza cada función antes de enviar información sensible o activar una alternativa de pago.