Corregir errores de instalación y versión de DeepSeek

Qué es realmente la instalación de DeepSeek Harness

La instalación de DeepSeek Harness consiste en un comando: npx @deepseek-ai/dsh web. No hay ningún instalador ni ningún servicio que configurar. La mayoría de los problemas que aparecen no son problemas de instalación. Son problemas de resolución de versiones: qué compilación de @deepseek-ai/dsh decidió ejecutar npx ese día y si la versión de Node.js puede ejecutarla. Cuando se inicia, la dirección que muestra está vinculada a localhost, y por qué la Web UI sólo responde en 127.0.0.1:3080 es un problema distinto de los que se tratan en esta página.

Dos hechos determinan todo lo que sigue. Primero, todas las versiones de @deepseek-ai/dsh publicadas hasta ahora en npm son versiones preliminares. La mayoría son candidatas de lanzamiento (-rc.N), y desde el 30 de agosto de 2026 también hay compilaciones alpha (-alpha.N). La etiqueta latest apunta a una candidata de lanzamiento. A fecha de 6 de octubre de 2026, esa versión es 0.2.0-rc.2, publicada el 29 de septiembre de 2026. Segundo, el README del proyecto indica que el harness está en developer preview, que evoluciona rápidamente y que tendrá cambios que pueden romper la compatibilidad. Una opción que funcionaba la semana pasada puede haber desaparecido esta semana. Fije una versión antes de crear cualquier componente sobre esta base.

Primero, algunos términos. dsh es la herramienta de línea de comandos de DeepSeek Harness. Node.js es el entorno de ejecución de JavaScript que necesita. npx es el ejecutor de paquetes incluido con npm (node package manager) y obtiene un paquete cuando se necesita, en lugar de instalarlo de forma permanente. Si el término harness tiene un significado poco habitual en esa frase, un harness de agente es el programa que envuelve al modelo, mantiene el bucle, las herramientas, los permisos y el estado de la sesión. Por eso, un número de versión que usted no eligió puede cambiar el comportamiento de su agente.

¿Qué versión de Node.js necesita dsh?

La raíz del repositorio package.json declara "engines": {"node": "^22.19.0 || >=24.0.0"}, según la lectura del 6 de octubre de 2026, cuando el repositorio estaba en la versión 0.2.1-alpha.1. Por tanto, necesita Node 22.19.0 o una versión posterior de la línea 22, o Node 24 o posterior. Node 20 no es compatible.

Compruebe primero qué versión tiene.

node -v
npm -v

Esta es la parte que suele sorprender. El paquete @deepseek-ai/dsh publicado no incluye un campo engines propio. Sólo la raíz del monorepo declara uno, y ese archivo raíz nunca se publica en npm. Por tanto, npm no tiene nada que comprobar: no muestra ninguna advertencia EBADENGINE y no rechaza la instalación. En Node 20, la instalación parece completarse correctamente. El fallo aparece después, cuando el código cargado utiliza sintaxis o una API que el runtime no proporciona. No existe una cadena de error única y estable que pueda buscar, porque la línea que falla primero depende del módulo que se cargue primero. Lea node -v en lugar de limitarse a leer el error del proceso.

Si su versión de Node es demasiado antigua, nvm (node version manager) es la solución menos invasiva en un VPS, porque se instala en el directorio de inicio del usuario y deja intacto el Node del sistema.

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.6/install.sh | bash
exec $SHELL -l
nvm install 24
nvm use 24
node -v

node -v debería mostrar ahora una versión que empiece por v24.. Si el shell sigue mostrando la versión antigua, la función de shell de nvm no se cargó. Abra un nuevo shell de inicio de sesión y vuelva a intentarlo. Node 24 es la línea LTS (long term support) activa a fecha del 6 de octubre de 2026, y su versión más reciente en esa fecha es 24.21.0. Es el objetivo recomendado por un segundo motivo que se explica más adelante.

¿Por qué npx ejecuta una versión diferente cada día?

npx @deepseek-ai/dsh web no especifica ninguna versión, por lo que npx consulta en el registro a qué apunta la etiqueta latest. Esa etiqueta cambia con frecuencia. 0.1.0-rc.8 apareció el 19 de agosto de 2026, dos días después de 0.1.0-rc.7, y el 6 de octubre de 2026 latest ya apuntaba a 0.2.0-rc.2. Cada vez que cambia, el comando guardado en las notas empieza a ejecutar código diferente, sin solicitar confirmación y sin mostrar un registro de cambios.

Puede inspeccionar todos los elementos desde la línea de comandos.

npm view @deepseek-ai/dsh dist-tags
npm view @deepseek-ai/dsh versions --json
npm view @deepseek-ai/dsh time --json

dist-tags muestra a qué apunta actualmente latest. El 6 de octubre de 2026, tanto latest como next apuntaban a 0.2.0-rc.2, y una tercera etiqueta, alpha, apuntaba a 0.2.1-alpha.1. Ninguna de ellas es un canal estable al que pueda cambiar. La lista de versions resulta más interesante porque contiene huecos. El 6 de octubre de 2026 incluía 30 versiones, desde 0.0.1-rc.1 hasta 0.2.1-alpha.1. La línea 0.0.1 salta de -rc.2 a -rc.5, la línea 0.1.0 salta de -rc.3 a -rc.6, las compilaciones alfa comienzan en 0.1.2-alpha.2 y 0.1.3-alpha.2, y no existe 0.1.4. Faltan números porque algunas compilaciones nunca se publicaron, y las compilaciones alfa y las candidatas a versión final aparecen intercaladas en la misma lista. Suponer el siguiente -rc.N en un script de despliegue provocará un error, así que lea la lista en lugar de incrementarla.

¿Por qué npx sigue ejecutando una versión antigua?

Esta es la queja opuesta. Ambas situaciones son posibles, según la versión de npm que esté utilizando.

npx mantiene su propio directorio de paquetes, separado de la caché de tarballs, en una carpeta llamada _npx dentro de la caché de npm. Muestre la ruta y revísela.

npm config get cache
ls "$(npm config get cache)/_npx"

Durante años, npx reutilizaba lo que encontraba allí para un nombre de paquete sin especificar y nunca volvía a consultar el registro. npm 11.2.0 cambió este comportamiento. Cuando la especificación es un nombre sin especificar o un rango de versiones, npx obtiene ahora el manifiesto y reutiliza la copia en caché sólo cuando el tarball resuelto coincide con el que acaba de devolver el registro.

El comportamiento depende de la versión de Node, porque Node incluye una versión específica de npm:

• Node 20.20.2 incluye npm 10.8.2.
• Node 22.19.0 incluye npm 10.9.3.
• Node 22.23.3, la versión más reciente de la línea 22 a fecha de 6 October 2026, incluye npm 10.9.9.
• Node 24.19.0 incluye npm 11.17.0.
• Node 24.21.0, la versión más reciente de la línea 24 a fecha de 6 October 2026, incluye npm 11.19.0.

Por tanto, toda la línea Node 22, que el harness admite oficialmente, incluye una versión de npm anterior a 11.2.0. En Node 22, un npx @deepseek-ai/dsh web sin especificar seguirá ejecutando la release candidate que almacenó en caché hace semanas. El mismo comando en Node 24 vuelve a resolver la versión en cada ejecución. Un comando, dos comportamientos, y ninguno muestra una advertencia. Consulte al programa qué versión utiliza:

npx @deepseek-ai/dsh --version

Borrar la caché de npx

En npm 11.2.0 y versiones posteriores hay subcomandos específicos.

npm cache npx ls
npm cache npx rm --force

Sin --force, npm se niega a borrar todo y muestra Please use --force to remove entire npx cache. Use npm cache npx ls primero cuando quiera eliminar una entrada por clave en lugar de eliminarlas todas.

En npm 10 esos subcomandos no existen. Elimine el directorio manualmente.

rm -rf "$(npm config get cache)/_npx"

npm cache clean --force no sirve en este caso. Borra _cacache, el almacén de tarballs, y deja _npx intacto. Esta separación explica precisamente por qué npm añadió después los subcomandos npm cache npx. Borrar _npx tampoco implica una pérdida permanente: contiene paquetes descargados, mientras el estado del harness se encuentra en $DSH_HOME/profiles/<name> y no se modifica.

¿Cómo fijo un release candidate exacto?

Indique la cadena completa de la versión, incluida la parte -rc.N.

npx --yes @deepseek-ai/dsh@0.1.0-rc.7 web

Los ejemplos de esta página usan 0.1.0-rc.7. Sustitúyalo por la compilación que haya probado realmente. El 6 de octubre de 2026, la etiqueta latest apuntaba a 0.2.0-rc.2.

--yes es importante en un script porque, de lo contrario, npx muestra un aviso antes de instalar un paquete que no ha encontrado y espera una respuesta que nunca llega.

Una versión exacta también es la opción más rápida. npx basa el directorio de caché en la especificación que escribió y, con una versión exacta, compara esa especificación con el identificador del paquete que ya está instalado allí y lo ejecuta sin ninguna consulta al registro. En npm 11.2.0 y versiones posteriores, usar un nombre sin versión obliga a obtener el manifiesto en cada inicio.

Una instalación global se fija de la misma forma y permite usar un comando corto.

npm install -g @deepseek-ai/dsh@0.1.0-rc.7
dsh --version

No matching version found for @deepseek-ai/dsh@^0.1.0

Un rango con caret o tilde no coincide con este paquete. npm install -g @deepseek-ai/dsh@^0.1.0 responde con el código de error ETARGET y la línea No matching version found for @deepseek-ai/dsh@^0.1.0. El registro funciona correctamente. Esta es una regla de semver: un rango de versiones no coincide con una versión prerelease a menos que el propio rango especifique una prerelease. Todas las compilaciones publicadas de este paquete son prerelease, ya sea -rc.N o -alpha.N, por lo que ^0.1.0 no coincide con ninguna. Escriba la versión exacta.

Esta regla también tiene un efecto útil. Como los rangos no pueden avanzar automáticamente a un nuevo release candidate, no existe un estado parcialmente fijado que deba analizar. Está usando una versión exacta o una etiqueta que cambia.

¿Debo usar npx o instalar dsh globalmente?

Use npx para una primera evaluación, porque no deja nada aparte de un directorio de caché que ahora sabe cómo borrar. Use una instalación global fijada para cualquier herramienta que deba seguir funcionando después de un reinicio, como un agente de programación que mantiene en ejecución en un VPS.

Ambas opciones pueden no coincidir en un equipo donde haya usado las dos, así que compárelas.

which dsh
dsh --version
npx @deepseek-ai/dsh --version

which dsh no encontrar nada justo después de una instalación global correcta casi siempre significa que falta el directorio de binarios globales de npm en su PATH. Ejecute npm prefix -g para mostrar la raíz. Los binarios se encuentran en el directorio bin que está dentro de ella.

Una nota de seguridad. npx descarga y ejecuta código del registro cada vez que resuelve algo nuevo. En un servidor, esto supone una exposición real, no teórica. Fijar las versiones es parte de la solución. El resto se explica en cómo los ataques a la cadena de suministro de npm llegan a un servidor.

Qué significa la vista previa para la reproducibilidad

0.1.0-rc.6 se publicó el 13 de agosto de 2026 y 0.1.0-rc.7 el 17 de agosto de 2026. Sólo los separan cuatro días. El ritmo no se ha ralentizado desde entonces: se publicaron otras 23 versiones entre el 19 de agosto y el 3 de octubre de 2026, incluida 0.2.0-rc.1 el 28 de septiembre y 0.2.0-rc.2 al día siguiente. A ese ritmo, unas instrucciones escritas hace un mes pueden describir una línea de comandos que ya no existe, y esta página no es una excepción. Feche cada afirmación sobre versiones que anote, incluidas sus propias notas.

Dos hábitos permiten trabajar con la vista previa. Fije la versión exacta en cada comando y cada script para que reconstruir un servidor produzca el mismo entorno de ejecución. Después, consulte la salida de ayuda de la compilación fijada, no la de una guía.

npx @deepseek-ai/dsh@0.1.0-rc.7 --help
npx @deepseek-ai/dsh@0.1.0-rc.7 web --dump-config

La segunda parte de la reproducibilidad es el perfil. dsh --profile <name> inicia el perfil almacenado en $DSH_HOME/profiles/<name>, y los perfiles web y headless se crean a partir de las plantillas incluidas la primera vez que se usan. Ese directorio también es donde el entorno de ejecución lee la clave de API, el modelo y la configuración del endpoint, por lo que fijar una versión y tener una configuración operativa son dos tareas independientes. Los paquetes incluidos se resuelven desde la instalación de dsh que se está ejecutando, por lo que cambiar la versión fijada también cambia esos paquetes. Los plugins externos funcionan de otra manera. Se almacenan en el directorio del perfil, y dsh plugin --profile <name> add <package> reenvía sus argumentos a pnpm para instalarlos. Por tanto, pnpm debe estar en su PATH, y dsh lo indica claramente cuando no lo está. Cada plugin que añada se ejecuta con los mismos permisos que tiene su agente, por lo que conviene comprobar a qué puede acceder un plugin antes de instalarlo. El package.json del propio perfil es el archivo que fija esos plugins, así que una fijación completa cubre dos archivos, no uno.

Esta separación resultará familiar si ha mantenido herramientas de Python en entornos aislados en un servidor: la herramienta y los elementos que se le añaden se fijan en lugares separados. Cuando el entorno de ejecución se inicia, la siguiente cuestión suele ser la red, no las versiones. Ahí entran el acceso a la interfaz web de dsh en un VPS remoto y el tutorial más extenso sobre la instalación de DeepSeek Harness en un VPS.

Errores de argumentos que verá realmente

Estos errores proceden del analizador sintáctico de la CLI, y cada uno identifica el problema exacto. El texto se ha mantenido bastante estable entre compilaciones, pero no por completo, por lo que los mensajes siguientes se comprobaron con 0.2.0-rc.2 el 6 de octubre de 2026.

error: --profile <name> is required

Ejecutó npx @deepseek-ai/dsh sin subcomando ni perfil. El comando sin argumentos inicia un perfil, por lo que necesita un nombre. dsh web funciona sin --profile porque el analizador interpreta la primera palabra independiente como el nombre del perfil e inicia por usted el perfil incluido web.

error: --patch needs a path

Se pasó --patch sin ningún valor después. La opción puede repetirse, y cada aparición recibe una ruta de archivo.

error: --dump-config and --dump-default-config are mutually exclusive

Elija una de las dos opciones. En 0.2.0-rc.2, la compilación a la que apuntaba latest el 6 de octubre de 2026, el mensaje menciona una tercera opción y muestra error: --dump-config, --dump-default-config, and --dump-config-schema are mutually exclusive, porque --dump-config-schema, que imprime el JSON Schema de las entradas y los parches de los perfiles, se ha añadido a las otras dos. --dump-default-config imprime las capas del paquete incluido y no acepta --patch. --dump-config imprime la configuración compuesta de un perfil. Todas imprimen el resultado y terminan sin iniciar el harness, por lo que son la forma segura de comprobar qué ha cambiado una nueva versión candidata.

error: plugin needs pnpm arguments to forward (e.g. add <package>)

Se ejecutó dsh plugin --profile <name> sin nada que reenviar. El subcomando inicializa el perfil si falta y después pasa el resto de la línea de comandos a pnpm, por lo que necesita argumentos como add @scope/dsh-plugin-example.

FAQ

¿Qué versión de Node.js necesita DeepSeek Harness?

El repositorio declara ^22.19.0 || >=24.0.0 en su package.json raíz, según la lectura del 6 de octubre de 2026, cuando el repositorio estaba en la versión 0.2.1-alpha.1. Por tanto, necesita Node 22.19.0 o posterior de la línea 22, o Node 24 y versiones posteriores. Node 20 no funcionará. El paquete npm publicado no tiene un campo engines propio, por lo que npm nunca muestra una advertencia ni bloquea la instalación; el fallo aparece en tiempo de ejecución. Compruebe primero node -v. Node 24 es la opción más recomendable, porque incluye npm 11, que corrige la reutilización de versiones por parte de npx.

¿Cómo obligo a npx a usar la versión más reciente de dsh en lugar de una versión almacenada en caché?

En npm 11.2.0 y versiones posteriores, npx @deepseek-ai/dsh vuelve a comprobar el registro para un nombre de paquete sin versión en cada ejecución. En npm 10, incluido en todas las versiones de Node 22, no lo hace. Borre la caché de npx con npm cache npx rm --force en npm 11, o elimine la carpeta con rm -rf "$(npm config get cache)/_npx" en npm 10. Después, confirme el resultado con npx @deepseek-ai/dsh --version. Tenga en cuenta que npm cache clean --force borra un directorio diferente y no resolverá este problema.

¿Por qué falla la instalación de @deepseek-ai/dsh@^0.1.0?

npm devuelve el código de error ETARGET con la línea No matching version found for @deepseek-ai/dsh@^0.1.0.. Todas las compilaciones publicadas son versiones preliminares, como 0.2.0-rc.2 o 0.2.1-alpha.1, y un intervalo semver no coincide con versiones preliminares a menos que el propio intervalo especifique una. Instale la cadena de versión exacta, incluido el sufijo. Ejecute npm view @deepseek-ai/dsh versions --json para ver qué versiones existen, porque la secuencia contiene huecos correspondientes a compilaciones que nunca se publicaron.

¿Debo instalar dsh globalmente o ejecutarlo mediante npx?

npx es adecuado para una primera prueba, porque no conserva nada salvo un directorio de caché. Una instalación global fijada, como npm install -g @deepseek-ai/dsh@0.1.0-rc.7, es adecuada para cualquier uso que deba seguir funcionando, porque la versión sólo cambia cuando usted la cambia. Si no se encuentra el comando dsh después de una instalación global, el directorio binario global de npm no está incluido en PATH, y npm prefix -g muestra la raíz bajo la que se encuentra.

¿DeepSeek Harness es lo bastante estable para basar trabajo en él?

Todavía no, según su propia descripción. El README indica que el proyecto está en vista previa para desarrolladores, que evoluciona rápidamente y que habrá cambios incompatibles. Las versiones candidatas 0.1.0-rc.6 y 0.1.0-rc.7 se publicaron con cuatro días de diferencia en agosto de 2026, y 0.2.0-rc.1 y 0.2.0-rc.2 con un día de diferencia en septiembre de 2026. Fije una versión exacta y lea --help de esa compilación fijada, no de una guía cualquiera. Feche sus propias notas para poder determinar cuándo han quedado obsoletas.