Panorama de conexión de modelos: sistema de providers y cambio de modelos
Con OpenClaw instalado y el onboarding completado, ya tienes a mano un modelo utilizable. Pero OpenClaw en sí no incluye modelos——todos los modelos provienen de “plugins de provider”, y esto es justamente el núcleo de la OpenClaw configuración de modelos: qué plugin conectar, qué credenciales configurar y escribir correctamente la referencia del modelo en provider/model.
Esta lección (1.6) explica de una vez todo este sistema: cómo consultar el estado actual, cómo listar el catálogo, cómo establecer el predeterminado, cómo cambiar en cualquier momento desde el chat y cómo conectar un provider totalmente nuevo. Cada página específica de conexión de modelos de 1.7–1.15 posteriores es una aplicación concreta de estas reglas. Este tutorial se basa en v2026.10.9.
Qué podrás hacer al terminar
- Decir qué modelo está usando ahora OpenClaw:
openclaw models statuslo averiguas de un vistazo - Explorar el catálogo de modelos de cualquier provider con
openclaw models list; “qué modelos admite OpenClaw” ya no depende de búsquedas - Cambiar el modelo predeterminado con
openclaw models set <provider/model>, sin editar a mano los archivos de configuración - Cambiar de modelo en cualquier momento en el chat con la familia de comandos
/model: tanto temporal como persistentemente - Al conectar un provider nuevo, recitar de memoria el orden de tres pasos: instalar plugin → configurar credenciales → elegir modelo
Tu situación actual
- Queda instalado y funciona, pero no sabes explicar “qué modelo se está usando realmente”; quieres cambiar a uno más barato o más potente y no sabes por dónde empezar
- Al buscar “qué modelos admite OpenClaw”, las respuestas son de todo tipo, mezcladas con comandos antiguos de la era Clawdbot / Moltbot
- Ves que otros editan
agents.defaultsen el archivo de configuración y quieres intentarlo también, pero temes romper algo y que el Gateway no arranque
Cuándo usar esta técnica
Cuando necesitas:
- Entender el sistema de modelos de OpenClaw——qué se usa ahora, qué más se puede usar y cómo cambiar
- Cambiar el modelo predeterminado a un modelo nacional (DeepSeek, Qwen, GLM, ...), o hacer que distintas sesiones usen distintos modelos
- Cambiar temporalmente a un modelo más potente en mitad del chat, y volver al anterior al terminar
Y además no quieres:
- Editar a mano el archivo de configuración cada vez que cambias de modelo
- Perderte en el catálogo oficial de providers con más de 70 entradas
- Confundir “conectar un modelo nuevo” con “cambiar entre modelos existentes” y ponerte a probar al azar
🎒 Preparativos antes de empezar
- Haber completado la instalación: 5 minutos para dejarlo funcionando OpenClaw: el onboarding ya tiene configurado al menos un provider(inicio de sesión Claude / Codex o alguna API Key)
- El Gateway está en ejecución:
openclaw gateway statusdebería mostrar que escucha en 18789 (si no está corriendo también puedes consultar modelos, solo quemodels listleerá el catálogo local en caché) - Si quieres conectar de paso un provider nuevo, ten lista la API Key de ese proveedor——desde la próxima lección usaremos DeepSeek como ejemplo
Idea central
OpenClaw en sí no incluye modelos. Los modelos y el agent harness (Claude, Codex, modelos locales) son todos plugins intercambiables. Conectar cada modelo = un plugin de provider + una credencial. La OpenClaw configuración de modelos tiene solo tres conceptos:
- provider: el plugin de conexión de un proveedor de modelos, con un id único (como
deepseek,qwen,anthropic) - Referencia de modelo
provider/model——la escritura unificada para designar un modelo, comodeepseek/deepseek-v4-pro - Modelo predeterminado y cambio——en la configuración se escribe un predeterminado; en el chat,
/modelpermite cambiar en cualquier momento
Las reglas de referencia son el cimiento de toda la lección:
| Regla | Ejemplo | Explicación |
|---|---|---|
Antes del primer / va el id del provider | qwen/qwen3.5-plus | el id del provider siempre va en minúsculas (normalizado) |
Cuando el ID del modelo contiene /, debe llevar el prefijo completo | openrouter/moonshotai/kimi-k2 | se divide según el «primer /»; si falta el prefijo, no se encuentra |
| La ortografía del ID del modelo sigue al fabricante | minimax/MiniMax-M3 | el ID de los modelos de MiniMax distingue mayúsculas y minúsculas, cópialo tal cual del catálogo del plugin |
Dos formas de conexión, distinguidas en una tabla:
| Plugin provider oficial | Endpoint personalizado / de retransmisión | |
|---|---|---|
| Aplica a | Modelos con plugin oficial (DeepSeek, Qwen, GLM, Kimi, MiniMax…) | Modelos sin plugin oficial, retransmisores compatibles con OpenAI, servicios de inferencia local |
¿Hay que escribir models.providers en la configuración? | No: instalar plugin + configurar auth + elegir modelo | Sí: baseUrl, apiKey, lista de models |
| Ver detalles en | 1.7–1.13 la página dedicada de cada proveedor | Más modelos nacionales y endpoints de retransmisión personalizados |
La gran familia de providers (el directorio oficial de Providers incluye 70+ entradas):
| Familia | Representantes | Forma de conexión | Página dedicada de este tutorial |
|---|---|---|---|
| Grandes internacionales | OpenAI (openai), Anthropic (anthropic), Google (google) | Plugin integrado; el onboarding puede reutilizar el inicio de sesión por CLI de Claude Code / Codex | Cubierto en el inicio rápido |
| Modelos nacionales | DeepSeek, Tongyi Qianwen, Zhipu GLM, Kimi, MiniMax, Doubao/Volcano, Hunyuan, Qianfan, StepFun, Xiaomi MiMo, LongCat | Plugin oficial + API Key | 1.7–1.13 Una página por proveedor |
| Enrutadores agregadores | OpenRouter, LiteLLM, ClawRouter | Una sola Key para modelos de varios proveedores | 1.14 Retransmisión y más modelos nacionales |
| Modelos locales | Ollama, vLLM, SGLang, LM Studio, ds4 | Corren en tu propia máquina, cero coste de API | 1.15 Modelos locales |
Buenas noticias para usuarios de China continental: los principales modelos nacionales son todos «ciudadanos de primera clase» — todos tienen plugin provider oficial, y desde 1.7 hay una página por proveedor con configuración paso a paso.
Sígueme haciéndolo
Paso 1: revisa la configuración actual de modelos — openclaw models status
Por qué: el onboarding configuró el modelo por ti, pero mucha gente no sabe decir con claridad «cuál estoy usando realmente». Primero mira bien el estado actual, así cada paso posterior tendrá una referencia contra la que comparar.
openclaw models statusDeberías ver: dos bloques de información — el modelo predeterminado y la cadena de fallback ya resueltos (la referencia provider/model completa), más el resumen de credenciales de cada provider (Auth overview: variables de entorno, configuración del provider, fuentes de credenciales encontradas en el almacenamiento de auth). Si hay credenciales OAuth a punto de expirar (por defecto dentro de 24 horas), también se avisa aquí.
Tres puntos adicionales:
Un
openclaw modelssimple equivale aopenclaw models status; añade--jsonpara obtener un formato legible por máquinaSin
--probeno envía peticiones reales al modelo — que las credenciales «parezcan estar ahí» no significa que funcionen; para probarlo de verdad, añade--probe(llamará al modelo de verdad, puede consumir tokens y disparar límites de tasa)Los cambios temporales dentro de una sesión individual no se ven en el status del CLI; usa el
/model statusde esa sesiónopenclaw models statuspermite encontrar la referenciaprovider/modelcompleta del modelo predeterminado actual
Paso 2: explora el catálogo de modelos — openclaw models list (qué modelos soporta OpenClaw se ve aquí)
Por qué: antes de cambiar de modelo, mira la mercancía. Cada provider tiene su propio catálogo de modelos: ventana de contexto, tipos de entrada, si es un modelo de razonamiento — todo está en la tabla.
openclaw models list # 当前已装 provider 的可见模型
openclaw models list --all # 完整发布目录
openclaw models list --provider deepseek # 只看一家Deberías ver: una referencia de modelo por línea (formato provider/model). Detrás de --provider va el id del provider (como deepseek, moonshot), no el nombre visible en la interfaz (como Moonshot AI).
Cuatro detalles prácticos:
¿Olvidaste el id del provider? Ejecuta primero
openclaw models list --ally búscalo en el catálogo completoUn id de provider desconocido hace que salga con error (exit distinto de cero) y señala el id rechazado
Los modelos recién lanzados pueden no estar en el catálogo local; añade
--refreshpara disparar el redescubrimientoGuardar las credenciales de un proveedor hace que sus modelos entren en el catálogo seleccionable — así que tras conectar un nuevo provider en el paso 5, acuérdate de volver y refrescar para ver
openclaw models list --provider <你已配好的 provider>lista su catálogo de modelos
Paso 3: define el modelo predeterminado — el paso central de la configuración de modelos de OpenClaw
Por qué: el modelo predeterminado determina qué usan las sesiones nuevas y las tareas programadas. Un comando de una línea, sin editar el archivo de configuración a mano.
openclaw models set deepseek/deepseek-v4-pro(El ejemplo usa DeepSeek; el requisito previo es tener instalado su plugin provider — si no lo tienes, mira primero el paso 5, o ve directamente a conectar DeepSeek.)
Deberías ver: el comando se ejecuta con éxito y sin errores; ejecuta de nuevo openclaw models status y el modelo predeterminado ya tiene el nuevo valor.
Lo que hace: escribe la opción de configuración agents.defaults.model.primary. La forma equivalente en el archivo de configuración se ve así:
{
agents: { defaults: { model: { primary: "deepseek/deepseek-v4-pro" } } },
}Dos reglas a prueba de errores (de la documentación oficial del CLI):
- Rechaza directamente los providers desconocidos: exit distinto de cero, la configuración no se toca — el provider de la referencia debe ser un plugin instalado o un provider ya configurado
- Avisa si el modelo no está en el catálogo: no impide la escritura (los modelos recién lanzados o autoalojados pueden aún no estar en el catálogo), pero conviene revisar la ortografía
💡 Otras dos vías para cambiar el predeterminado
openclaw models auth login --provider <id> --set-default adopta de paso el modelo predeterminado recomendado de ese provider al iniciar sesión; para el modelo de imagen predeterminado usa openclaw models set-image <provider/model> (escribe agents.defaults.imageModel.primary).
openclaw models set <provider/model>se ejecuta con éxito (o entiendes por qué te rechazó)
Paso 4: cambia de modelo en el chat — la familia de comandos /model
Por qué: lo que se define en la terminal es el «predeterminado»; en el chat además puedes cambiar en cualquier momento — cambiar temporalmente a un modelo potente, volver al terminar la conversación, sin tocar para nada la configuración global.
/model # ver qué usa la sesión actual
/model list # Explorar providers (/models también sirve)
/model deepseek/deepseek-v4-pro # Cambiar solo la sesión actual (comportamiento por defecto)
/model deepseek/deepseek-v4-pro -a # Actualizar también el valor por defecto del agente (requiere owner/admin)
/model deepseek/deepseek-v4-pro -g # Actualizar el valor por defecto global (requiere owner/admin)
/model default -s # Borrar la selección de esta sesión y volver al valor por defecto de la configuración
/model status # Credenciales candidatas de cada provider y modo baseUrl / apiDeberías ver: el comando de cambio surte efecto de inmediato; si el agente está inactivo, la siguiente ejecución usa el nuevo modelo, y si está corriendo, se encola hasta el siguiente punto seguro de cambio. /models <provider> lista todos los modelos de un provider.
Tres comportamientos que hay que conocer:
- La selección dentro de la sesión es «estricta»: si el modelo elegido no está disponible, da error directamente y no recurre en secreto a la cadena de fallback (solo el valor por defecto configurado recurre a fallback)
- La selección numérica no está soportada (
/model 3no es válido); Discord / Telegram tienen una interfaz de selección nativa - Cuando el ID del modelo incluye
/hay que escribir el prefijo completo:/model openrouter/moonshotai/kimi-k2
Además de /model hay toda una familia de comandos de chat como /think y /new; ver curso rápido de comandos de chat.
- En el chat, tras cambiar con
/model <provider/model>, la siguiente respuesta viene del nuevo modelo
Paso 5: conectar un nuevo provider — instalar el plugin, configurar credenciales, elegir modelo
Por qué: si en el catálogo te interesa el modelo de algún provider, primero haz que OpenClaw lo «conozca». Los plugins oficiales de provider siguen siempre tres pasos:
① Instalar el plugin (algunos providers lo necesitan) → ② Configurar credenciales (openclaw onboard) → ③ Elegir modeloTomando DeepSeek como ejemplo (es un plugin oficial externo, requiere instalación):
openclaw plugins install @openclaw/deepseek-provider
openclaw onboard --auth-choice deepseek-api-keyDeberías ver: el onboarding detecta el acceso a IA existente → espera a que elijas provider → tras pasar la verificación de conexión, guarda solo las rutas disponibles → continúa configurando el resto. Tras elegir --auth-choice, el selector de modelo por defecto se prefiltra a los modelos de ese provider (los providers hermanos del mismo plugin también coinciden, por ejemplo volcengine / volcengine-plan).
Tres cosas que conviene tener claras:
- Si hay que instalar el plugin o no varía según el provider: MiniMax es un plugin integrado (bundled), basta con
openclaw plugins enable minimax; DeepSeek, Qwen, GLM, Kimi y otros plugins externos requierenopenclaw plugins install @openclaw/<名字>-provider. El comando exacto de cada provider está al principio de su página dedicada en 1.7–1.13 - Los plugins oficiales no requieren escribir entradas de configuración
models.providers— instalar el plugin, definir auth y elegir modelo, tres pasos y listo; solo se escribe para endpoints personalizados o para sobrescribir baseUrl (ver 1.14) - Rehacer el onboard no borra la configuración de modelos existente; para cambios de provider de modelos o de enrutado de auth, la recomendación oficial es ejecutar
openclaw onboard(openclaw configurequeda para ajustes de tipo no inferencial)
Para modelos como 01.AI Yi, Baichuan o iFlytek Spark, que aún no tienen plugin oficial, se usa un endpoint compatible con OpenAI personalizado o un agregador; ver más modelos nacionales y endpoints de retransmisión personalizados; si no quieres gastar en API, modelos locales te enseña a ejecutar modelos en tu máquina con Ollama y vLLM.
- Saber decir de memoria el orden de los tres pasos para conectar un nuevo provider: instalar plugin → configurar credenciales → elegir modelo
Punto de control ✅
- Con
openclaw models statuspuedes decir la referenciaprovider/modelcompleta del modelo por defecto actual - Con
openclaw models list --provider <id>puedes listar el catálogo de modelos de un provider - Cambiar el valor por defecto con éxito con
openclaw models set <provider/model>(o entender por qué lo rechaza) - En el chat, el cambio con
/model <provider/model>surte efecto y/model default -spermite volver al valor por defecto - Saber explicar el orden de los tres pasos para conectar un nuevo provider: instalar plugin → configurar credenciales → elegir modelo
Aviso de errores comunes
❌ La referencia del modelo omite el prefijo del provider
Causa: OpenClaw divide la referencia por el «primer /». Si se omite el provider, primero prueba los alias, luego el provider configurado con coincidencia única y solo al final el provider por defecto (comportamiento ya obsoleto) — basta con que exista un modelo homónimo más para que no se seleccione.
/model kimi-k2 # ❌ En la mayoría de los casos no se selecciona
/model kimi/kimi-for-coding # ✅ Incluye el prefijo del provider
/model openrouter/moonshotai/kimi-k2 # ✅ Si el ID del modelo incluye /, hay que escribir el prefijo completoForma correcta: escribir siempre la referencia provider/model completa; si tienes dudas, ejecuta antes openclaw models list --provider <id> y copia el texto tal cual del catálogo (los IDs de modelos de fabricantes como MiniMax distinguen mayúsculas y minúsculas).
❌ Configuraste la Key de un nuevo provider y crees que el modelo por defecto cambiará automáticamente
Causa: guardar las credenciales de un nuevo provider no modifica el modelo por defecto existente — palabras textuales de las Quick rules oficiales: «Adding provider auth does not change your primary model»; solo un --set-default explícito lo cambia.
Forma correcta: para cambiar el valor por defecto usa openclaw models set <provider/model>, o openclaw models auth login --provider <id> --set-default al iniciar sesión. Si los síntomas no encajan, ejecuta primero openclaw models status para ver cuál es realmente el valor por defecto.
❌ Tras instalar el Gateway como demonio, la API Key exportada «no surte efecto»
Causa: cuando el Gateway se ejecuta como servicio de launchd / systemd, no ve las variables de entorno de tu shell interactivo definidas con export — todos los documentos de cada provider destacan expresamente este punto.
Forma correcta: escribe la Key en ~/.openclaw/.env, o proporciónala mediante env.shellEnv de la configuración; si cambias la Key, recuerda reiniciar el servicio del Gateway.
❌ Usaste un ID de modelo antiguo retirado
Causa: los modelos se retiran. deepseek-chat / deepseek-reasoner de DeepSeek fueron retirados el 2026-07-24; los IDs antiguos ya no están disponibles.
Forma correcta: usa openclaw models list --provider deepseek para ver el catálogo vigente y usa IDs nuevos como deepseek/deepseek-v4-pro o deepseek/deepseek-v4-flash; los detalles de la migración están en la siguiente lección Conectar DeepSeek.
Técnicas avanzadas (opcional)
Configurar una cadena de fallback para el modelo por defecto. Los modelos de agents.defaults.model.fallbacks se prueban en orden; la rotación de credenciales ocurre dentro del provider y solo después se pasa al siguiente modelo de fallback. Gestión por CLI:
openclaw models fallbacks list
openclaw models fallbacks add deepseek/deepseek-v4-flash
openclaw models fallbacks remove <model-or-alias>
openclaw models fallbacks clearDeja que OpenClaw elija fallbacks gratuitos por ti. openclaw models scan lee el catálogo público :free de OpenRouter y elige candidatos ordenando por soporte de imágenes, latencia de herramientas, contexto, etc. Dos avisos: el escaneo de metadatos no necesita Key, pero la comprobación en tiempo real y --set-default sí requieren OPENROUTER_API_KEY; un scan con sondeo escribe en la configuración (reemplaza los fallbacks directamente); si solo quieres mirar, añade --no-probe.
Asigna un alias al modelo. openclaw models aliases add Opus anthropic/claude-opus-5-5 Después, en el chat /model Opus ya se puede seleccionar. Los alias se guardan en agents.defaults.models.<key>.alias; un modelo solo puede tener un alias a la vez, y añadir uno nuevo reemplaza al anterior.
Especifica el modelo para una sola ejecución. Si no quieres cambiar ninguna configuración, para una ejecución puntual:
openclaw agent --model deepseek/deepseek-v4-pro --message "..."También se pueden gestionar modelos desde la Control UI. La página Models del Gateway ofrece el mismo flujo de inicio de sesión que la CLI; Settings → Models → Set API key permite cambiar la Key directamente, y al cambiarla se limpian de inmediato el enfriamiento y el contador de fallos de esa credencial, de modo que la siguiente solicitud se puede intentar de inmediato.
Actualiza el catálogo de modelos alojado. openclaw models refresh obtiene el catálogo oficial de metadatos alojados (los nuevos modelos entran al catálogo por aquí); requiere que el Gateway local esté detenido primero (openclaw gateway stop), y se reinicia después de actualizar.
Resumen de esta lección
✅ OpenClaw Los tres conceptos de la configuración de modelos quedaron claros: provider (plugin + credenciales), referencias provider/model, modelo por defecto y cambio de modelo.
✅ La cadena de comandos consultar → listar → establecer → cambiar funciona: models status para ver el estado actual, models list para ver el catálogo, models set para establecer el predeterminado y /model para cambiar en el chat.
✅ Los tres pasos para conectar un nuevo provider quedaron definidos: instalar el plugin (si es necesario) → openclaw onboard --auth-choice <id> para configurar credenciales → elegir modelo; los plugins oficiales no escriben models.providers.
✅ Dos peculiaridades quedaron grabadas: la selección con /model dentro de la sesión es de coincidencia estricta y no recurre al fallback; en modo demonio la Key debe ir en ~/.openclaw/.env.
| Campo de configuración / comando | Forma / valor recomendado | Descripción |
|---|---|---|
agents.defaults.model.primary | "provider/model" | Modelo por defecto; openclaw models set se escribe aquí |
agents.defaults.model.fallbacks | Lista de referencias de modelos | Cadena de respaldo, se intenta en orden |
agents.defaults.models.<key>.alias | Cadena de alias | Acceso rápido a /model <别名> |
models.providers.<id> | Solo se escribe para endpoints personalizados | Los plugins oficiales no lo necesitan |
~/.openclaw/.env | PROVIDER_API_KEY=... | El hogar de la Key en modo demonio |
openclaw onboard --auth-choice <id> | Los valores se ven en la página específica de cada proveedor | Configurar / cambiar credenciales del provider |
La lista completa de la guía rápida de comandos está en Guía rápida de comandos y configuración de la CLI.
Avance de la próxima lección
El sistema ya está claro; desde la próxima lección se practica proveedor por proveedor — el primero es DeepSeek, el más usado. Próxima lección: Conectar DeepSeek: práctica de configuración de los modelos de la serie V4.
Aprenderás:
- Catálogo de modelos de la serie DeepSeek V4:
deepseek-v4-pro/deepseek-v4-flashy cómo elegir - Flujo completo de configuración de
DEEPSEEK_API_KEY: instalación del plugin, onboarding y tres formas de escribir el archivo de configuración - Migración tras el retiro del ID antiguo
deepseek-chat/deepseek-reasoner - Capacidades exclusivas de DeepSeek: niveles de thinking, recuperación de herramientas DSML, web_search