Integración con DeepSeek: configuración práctica de los modelos de la serie V4
La integración de OpenClaw con DeepSeek es la primera parada de la página dedicada a modelos nacionales, y la más sencilla: API compatible con OpenAI, una variable de entorno y un comando de onboarding. Los tres pasos de la lección anterior («instalar plugin → configurar credenciales → elegir modelo») se recorren aquí completos, en unos 8 minutos en total (el registro de la cuenta de DeepSeek se cuenta aparte).
Aquí tienes primero una tabla de vista rápida; toda la configuración de esta lección parte de ella:
| Propiedad | Valor |
|---|---|
| Provider id | deepseek |
| Variable de entorno de autenticación | DEEPSEEK_API_KEY |
| Forma de la API | Compatible con OpenAI |
| Base URL | https://api.deepseek.com |
| Plugin oficial | @openclaw/deepseek-provider (plugin externo, requiere instalación) |
| Modelo predeterminado de onboarding | deepseek/deepseek-v4-pro |
Una mala noticia que conviene saber de antemano: deepseek-chat y deepseek-reasoner fueron retirados el 2026-07-24; los ID antiguos ya no son accesibles. Muchos tutoriales viejos de internet siguen usándolos; esta lección emplea en todo momento los ID activos de la serie V4, y la migración de las configuraciones antiguas se trata en el apartado de advertencias. Este tutorial se basa en v2026.10.9.
Qué podrás hacer al terminar
- Instalar el plugin oficial de DeepSeek
@openclaw/deepseek-providery configurarDEEPSEEK_API_KEYen OpenClaw: a elegir entre onboarding, archivo de configuración y script no interactivo - Distinguir los cuatro ID de modelos activos de la serie V4 y saber cuándo conviene cambiar el
deepseek-v4-proque onboarding asigna por defecto - Migrar las configuraciones antiguas que aún usan
deepseek-chat/deepseek-reasonera los nuevos ID - Controlar la intensidad de razonamiento de DeepSeek con
/think; al cambiar de provider en mitad de una conversación con múltiples llamadas a herramientas no hace falta/new - Hacer que el mismo plugin proporcione
web_searcha cualquier modelo, sin contratar otro servicio de búsqueda
🎒 Preparativos antes de empezar
- Haber completado Panorama de conexión de modelos: sistema de providers y cambio de modelo: tener claros los tres pasos «instalar plugin → configurar credenciales → elegir modelo» y las reglas de referencia
provider/model - OpenClaw instalado y Gateway en ejecución:
openclaw gateway statusproduce salida (el plugin surte efecto automáticamente en un Gateway en marcha; si no está corriendo, surte efecto en el próximo inicio) - Poder acceder a la plataforma abierta de DeepSeek: en el siguiente paso habrá que registrarse en platform.deepseek.com y crear una API Key
- Si optas por un despliegue en servidor / demonio, saber dónde está
~/.openclaw/.env: la Key acabará viviendo allí
Hazlo conmigo
Paso 1: registrarse en DeepSeek y crear una API Key
Por qué: los modelos de DeepSeek se facturan mediante la API oficial y OpenClaw solo se encarga de las llamadas: la Key hay que obtenerla primero en la plataforma de DeepSeek.
- Abre
https://platform.deepseek.comen el navegador y regístrate / inicia sesión - Entra en la página API Keys:
https://platform.deepseek.com/api_keys - Crea una nueva Key, cópiala y guárdala
Deberías ver: una API Key copiable, con la forma sk-... del ejemplo de configuración oficial. Es la única credencial con la que OpenClaw accede a la API de DeepSeek; el siguiente paso consiste en configurarla.
💡 La Key es la única credencial del lado de DeepSeek
El chat, las imágenes y las búsquedas usan la misma Key (web_search también la utiliza, véase la sección avanzada). Al crearla, no cierres la página todavía: pégala primero en un lugar seguro.
Paso 2: OpenClaw integración con DeepSeek: primero instala el plugin y luego configura DEEPSEEK_API_KEY
Por qué: en OpenClaw, DeepSeek es un plugin oficial externo (a diferencia de MiniMax, que está integrado), así que requiere un paso más que los plugins integrados: la «instalación»; después se configuran las credenciales.
Primero instala el plugin (primer paso común a las tres formas):
openclaw plugins install @openclaw/deepseek-providerDeberías ver: instalación correcta. Surte efecto automáticamente en un Gateway en marcha; si el Gateway no está corriendo, surte efecto en el próximo inicio.
Luego configura la Key, eligiendo una de las tres vías:
Vía A (recomendada): asistente onboarding
openclaw onboard --auth-choice deepseek-api-keyPor qué se recomienda: un solo comando cubre «configurar credenciales + elegir modelo»: te pide pegar la API Key y, tras pasar la verificación, establece automáticamente deepseek/deepseek-v4-pro como modelo predeterminado.
Deberías ver: primero pide introducir la API Key, guarda las credenciales al pasar la verificación de conexión y el modelo predeterminado pasa a ser deepseek/deepseek-v4-pro.
Dos garantías tranquilizadoras (la documentación oficial lo dice claramente):
- El onboarding conserva tus entradas de modelos ya existentes: volver a ejecutarlo no borra la configuración de otros proveedores
- En el modo
models.mode: "replace"se escribe también en el directorio integrado (porque ese modo omite el discovery)
Método B: editar el archivo de configuración manualmente
¿Prefieres tener todo bajo control? Ejemplo de configuración oficial (tal cual):
{
env: { vars: { DEEPSEEK_API_KEY: "sk-..." } },
agents: {
defaults: {
model: { primary: "deepseek/deepseek-v4-pro" },
},
},
}Cada lugar gestiona una cosa: env.vars.DEEPSEEK_API_KEY guarda la Key, agents.defaults.model.primary guarda el modelo por defecto.
Método C: script no interactivo (servidores / automatización)
En una instalación mediante script, pasa todos los parámetros de una vez (tal cual, $DEEPSEEK_API_KEY debe estar ya configurado en el entorno del script):
openclaw onboard --non-interactive \
--mode local \
--auth-choice deepseek-api-key \
--deepseek-api-key "$DEEPSEEK_API_KEY" \
--skip-health \
--accept-risk⚠️ ¿El Gateway corre como demonio? No pongas la Key en una shell interactiva
Cuando el Gateway se ejecuta como servicio de launchd / systemd, no ve las variables de entorno que exportaste en tu terminal con export. Escribe DEEPSEEK_API_KEY en ~/.openclaw/.env, o proporciónaselo a ese proceso mediante env.shellEnv en la configuración.
- En el resumen de credenciales de
openclaw models status, en la línea de deepseek se puede ver el origen deDEEPSEEK_API_KEY
Paso 3: elegir un modelo de la serie V4 y verificar
Por qué: el onboarding elige deepseek-v4-pro por defecto, pero la serie V4 tiene actualmente cuatro IDs activos con roles distintos; echa un vistazo al catálogo, cambia el modelo por defecto según necesites y, por último, envía un mensaje para verificar toda la cadena.
Primero mira el catálogo vigente:
openclaw models list --provider deepseek # Gateway 在运行时
openclaw models list --all --provider deepseek # 不启动 Gateway 也能看静态目录Deberías ver: cuatro referencias de modelos — este es todo el catálogo integrado de DeepSeek en OpenClaw:
| Referencia de modelo | Nombre | Entrada | Contexto | Salida máxima | Posición |
|---|---|---|---|---|---|
deepseek/deepseek-flash | DeepSeek V4.1 Flash | texto, imágenes | 1,000,000 | 384,000 | modelo Flash principal |
deepseek/deepseek-v4-flash | DeepSeek V4 Flash | texto | 1,000,000 | 384,000 | V4 rápido, admite thinking |
deepseek/deepseek-v4-pro | DeepSeek V4 Pro | texto | 1,000,000 | 384,000 | valor por defecto del onboarding |
deepseek/deepseek-v4-flash-vision-exp | DeepSeek V4 Flash Vision (experimental) | texto, imágenes | 1,000,000 | 384,000 | comprensión de imágenes experimental |
Cómo elegir, en tres frases:
| Tu necesidad | Elige este | Fundamento |
|---|---|---|
| No sabes qué elegir / tareas pesadas | deepseek/deepseek-v4-pro | es el valor por defecto del onboarding |
| Quieres enviar imágenes (PNG / JPEG / GIF / WebP) | deepseek/deepseek-flash | el modelo de imágenes principal del catálogo; la selección antigua deepseek-v4-flash-vision-exp también conserva soporte de imágenes |
| Quieres rapidez | deepseek/deepseek-v4-flash | posicionamiento oficial como «Fast V4» |
Cambiar el modelo por defecto (por ejemplo, a Flash):
openclaw models set deepseek/deepseek-flashTambién puedes cambiarlo temporalmente en el chat: /model deepseek/deepseek-v4-pro solo afecta a la sesión actual; la familia de comandos se detalla en Guía rápida de comandos de chat.
Verificación final: envía un mensaje de prueba:
openclaw agent --agent main --model deepseek/deepseek-v4-pro --message "用一句话介绍你自己"(openclaw agent exige al menos un selector de sesión, --agent main apunta al agente por defecto — en instalaciones que completaron el onboarding, main ya existe por defecto; o bien openclaw dashboard abre la Control UI y envíalo directamente en el cuadro de chat).
Deberías ver: el modelo responde con normalidad, sin errores de credenciales faltantes ni de modelo inexistente. Con esto, la conexión de OpenClaw con DeepSeek queda funcionando.
De paso, aclaremos los precios (para que la factura no dé un susto):
El coste en el catálogo de OpenClaw es estimado: la fila
deepseek/deepseek-flashsegún los precios pico de DeepSeek — $0.30 por millón de tokens de entrada, $1.20 de salida, $0.006 de entrada en caché; los precios fuera de pico publicados oficialmente se reducen a la mitaddeepseek-v4-flashydeepseek-v4-flash-vision-expsiguen siendo aceptados por DeepSeek, pero se enrutan a V4.1 Flash y se facturan a los precios actuales de FlashLa documentación de precios de DeepSeek no indica el precio de
deepseek-v4-pro; DeepSeek puede cambiar los precios en cualquier momento — la facturación se rige por la página oficial de Models & PricingEl mensaje de prueba recibió una respuesta de DeepSeek
Punto de control ✅
openclaw plugins install @openclaw/deepseek-providerse ejecutó y el plugin aparece en la lista- En el resumen de credenciales de
openclaw models statusse puede ver elDEEPSEEK_API_KEYde deepseek openclaw models list --provider deepseeklista los cuatro modelos activos de la serie V4- Tras enviar el mensaje de prueba se recibió una respuesta de DeepSeek
- La configuración no contiene IDs retirados como
deepseek-chat/deepseek-reasoner
Advertencias sobre errores comunes
❌ Sigues usando deepseek-chat / deepseek-reasoner (retirados)
Motivo: DeepSeek retiró estos dos IDs de modelo el 24 de julio (mes 7) de 2026 a las 15:59 UTC y ya no son accesibles. Los tutoriales y configuraciones antiguos están llenos de estos dos nombres; copiarlos tal cual provocará errores.
# ❌ Retirado, ya no accesible
deepseek/deepseek-chat
deepseek/deepseek-reasoner
# ✅ Destinos de migración indicados oficialmente (ambos admiten thinking)
deepseek/deepseek-v4-flash
deepseek/deepseek-v4-proLo correcto: sustituye los IDs antiguos de la configuración y de las sesiones por uno de los dos IDs nuevos de arriba; si tienes dudas, ejecuta openclaw models list --provider deepseek y copia del catálogo vigente.
❌ Tras instalar el Gateway como demonio, la Key exportada «no surte efecto»
Motivo: los servicios de launchd / systemd no ven las variables de entorno de tu shell interactiva — la documentación de cada proveedor lo subraya expresamente.
Lo correcto: escribir DEEPSEEK_API_KEY en ~/.openclaw/.env, o proporcionarlo mediante env.shellEnv en la configuración; tras cambiar la Key, reinicia el servicio Gateway.
❌ Quieres que el modelo vea imágenes y elegiste v4-pro / v4-flash
Motivo: deepseek-v4-pro y deepseek-v4-flash del catálogo solo aceptan texto. Para entrada de imágenes hay que usar deepseek/deepseek-flash: acepta PNG, JPEG, GIF y WebP, usa la misma API y la misma Key; la antigua selección deepseek-v4-flash-vision-exp también conserva el soporte de imágenes.
❌ Tomar los precios del catálogo de OpenClaw como factura
Motivo: el coste local de OpenClaw es un valor estimado; DeepSeek puede cambiar los precios en cualquier momento; el precio en horas valle es la mitad del de horas pico, así que las fluctuaciones en la factura son normales.
Lo correcto: la facturación se rige siempre por la página oficial Models & Pricing de DeepSeek; para controlar costos, presta atención a la diferencia entre horas pico y valle, y al precio bajo de la entrada en caché ($0.006 / millón de tokens).
🔧 Capacidades exclusivas de DeepSeek (opcional)
Una vez instalado el plugin, tres capacidades exclusivas de DeepSeek vienen incluidas automáticamente.
Control de thinking
Las series Flash y V4 admiten el control thinking de DeepSeek:
/think xhigh # se mapea al máximo reasoning_effort de DeepSeek "max"
/think max # igualmente se mapea a "max"Al desactivar thinking (incluido el nivel None de la UI), OpenClaw envía thinking: { type: "disabled" } y elimina reasoning_content del historial saliente, manteniendo la sesión estable en la ruta sin thinking.
Las llamadas a herramientas en múltiples turnos tienen un requisito específico de DeepSeek: las sesiones de thinking de V4 exigen que las solicitudes posteriores reproduzcan reasoning_content. El plugin rellena este campo automáticamente, así que las llamadas a herramientas en sesiones de thinking continúan con normalidad; tampoco hace falta /new si cambias a mitad de camino desde otro provider.
Recuperación de herramientas DSML
A veces los modelos de DeepSeek escupen los marcadores de herramientas como texto (marcadores DSML, incluso cuando se reenvían a través de otros providers compatibles con OpenAI como OpenRouter). OpenClaw restaura los bloques válidos calls / tool_calls / tool_call / function_calls como llamadas reales a herramientas, en lugar de dejarte ver un montón de texto con marcadores en el chat.
Tres límites:
- Las llamadas nativas a herramientas tienen prioridad: si una respuesta contiene ambas, las llamadas duplicadas recuperadas no se ejecutan
- Los bloques malformados o incompletos solo se ocultan, no se ejecutan
- Las llamadas recuperadas pasan igualmente por el control de permisos de herramientas existente
web_search: un plugin, dos usos
El mismo plugin deepseek también puede proporcionar web_search a cualquier modelo: va directo al motor de búsqueda de DeepSeek, no es un chat completion. Selecciona DeepSeek en Settings → Search, o:
openclaw configure --section webEscritura en el archivo de configuración (tal cual; la Key puede omitirse; prioridad de credenciales: Key de búsqueda del plugin → variable de entorno DEEPSEEK_API_KEY → Key del provider del modelo):
{
tools: {
web: {
search: { provider: "deepseek" },
},
},
plugins: {
entries: {
deepseek: {
config: {
webSearch: {
apiKey: "YOUR_DEEPSEEK_API_KEY",
},
},
},
},
},
}Facturación y límites: 5 solicitudes por segundo y cuenta; $0.75 / 1000 búsquedas con éxito y no vacías: los resultados vacíos y las solicitudes fallidas no se facturan. La búsqueda llama siempre a https://api.deepseek.com/v1/tools/search; aunque configures un baseUrl de reenvío para el chat, la búsqueda no se redirige al proxy.
Siguiente paso
Con esto completas la configuración de DeepSeek en OpenClaw. La página dedicada a modelos nacionales apenas empieza:
- Siguiente lección Integración con Tongyi Qianwen Qwen: tres planes de DashScope: cómo elegir entre los tres endpoints de DashScope (Coding / Standard / Token Plan) y cómo configurar
QWEN_API_KEY - Las páginas dedicadas a otros modelos (GLM, Kimi, MiniMax, Doubao, Hunyuan / Qianfan) se acceden desde el temario de Panorama de conexión de modelos
- ¿Modelo configurado? Para el uso diario empieza por Uso diario: convive eficientemente con tu Claw: Control UI, comandos de chat y sistema de memoria están en ese capítulo