Configurar dsh con claves API, modelos y endpoints

Dónde guarda dsh su configuración

dsh (DeepSeek Harness) guarda su configuración en un directorio: $DSH_HOME, que de forma predeterminada es ~/.dsh. Todo lo que configure en la interfaz web se escribe allí como archivos de texto sin formato. Copie ese directorio a otro servidor y el nuevo equipo funcionará como el anterior.

Cuatro rutas contienen todo lo que deberá modificar.

• ~/.dsh/settings.yaml contiene la configuración escrita manualmente y desde la interfaz web, incluidas las rutas de proveedores y modelos.
• ~/.dsh/.credentials.yaml contiene los secretos. La configuración sólo conserva una referencia a cada credencial, por lo que el valor de la clave se almacena en un único archivo.
• ~/.dsh/profiles/ contiene los perfiles con nombre y ~/.dsh/storages/ contiene las sesiones guardadas.
• ~/.dsh/cordis.patch.yml es su propia capa de parches. Se aplica sobre la configuración integrada para cada perfil.

DeepSeek anunció el harness como una versión preliminar para desarrolladores con licencia MIT el 17 de agosto de 2026, y el README indica que habrá cambios incompatibles. Los nombres de campo y las rutas de esta guía corresponden a la documentación del repositorio de agosto de 2026. Compruébelos en la documentación de la versión que instaló antes de copiar la configuración de cualquier guía, incluida esta, porque una versión preliminar puede cambiar los nombres entre releases.

El mínimo real para obtener la primera respuesta

dsh necesita Node.js 22.19 o posterior de la línea 22, o bien Node.js 24 o superior. Node 23 queda fuera de ese rango. Compruebe primero la versión, porque una incompatibilidad de versiones provoca un fallo al iniciar y el error parece indicar que el paquete está dañado.

node -v
npx @deepseek-ai/dsh web

npx descarga el paquete del registro npm e inicia la interfaz web en http://127.0.0.1:3080. Se enlaza a la dirección de loopback, por lo que el puerto no es accesible desde otra máquina aunque el firewall lo permita. En un VPS, reenvíelo mediante SSH en lugar de abrir 3080 a Internet. Si esa URL impresa resulta confusa, por qué dsh se inicia en esa dirección explica qué protege el enlace a loopback y qué no protege.

ssh -N -L 3080:127.0.0.1:3080 you@your-server

Abra http://127.0.0.1:3080 en su portátil y vaya a Settings y Models. La tarjeta de DeepSeek tiene un único campo para la clave de API. Pegue la clave de platform.deepseek.com y guárdela. La ruta del modelo queda disponible de inmediato, sin reiniciar, porque el servidor en ejecución almacena la credencial y resuelve la referencia en tiempo real. Acceder a la interfaz web de dsh en un servidor remoto cubre el caso del túnel y del proxy inverso, y instalar DeepSeek Harness en un VPS cubre la preparación del servidor que presupone esta guía.

Después de guardar, compruebe qué ha creado la aplicación.

ls -la ~/.dsh
stat -c '%a %n' ~/.dsh/.credentials.yaml

Debería ver settings.yaml, .credentials.yaml y profiles/. Si stat muestra un modo distinto de 600, ejecute chmod 600 ~/.dsh/.credentials.yaml. Un archivo de credenciales legible por el grupo o por cualquier usuario entrega la clave a todas las demás cuentas del sistema.

Para una primera ejecución sin navegador, basta con un comando.

npx @deepseek-ai/dsh --profile headless "summarise the files in this directory"

El perfil sin interfaz gráfica ejecuta una sola sesión y muestra la respuesta final.

Variables de entorno o el archivo de configuración

Hay dos formas de proporcionar una clave a dsh, y no son intercambiables.

Un proveedor del catálogo (DeepSeek, Anthropic, OpenAI y el resto de la lista integrada) recibe su clave desde la página Models. El valor se guarda en ~/.dsh/.credentials.yaml, y la configuración sólo conserva una referencia a él. La Web UI no vuelve a mostrar la clave después de guardarla.

En su lugar, un proveedor personalizado puede especificar una variable de entorno mediante apiKeyEnv. Este es el formato que muestra la documentación para ~/.dsh/settings.yaml.

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

Añada primero un proveedor desde la Web UI. Después, abra ~/.dsh/settings.yaml y copie la estructura que escribió. Durante una vista previa para desarrolladores, la anidación es el elemento con más probabilidades de cambiar, y el archivo que acaba de escribir la aplicación siempre está actualizado.

apiKeyEnv se lee del entorno del proceso dsh, no del shell de inicio de sesión. Una clave exportada en una sesión interactiva no está disponible para una unidad de systemd. Por eso, la misma configuración que funciona al escribir dsh web manualmente devuelve MISSING_CREDENTIAL cuando se ejecuta como servicio. Proporcione a la unidad su propio archivo.

[Service]
EnvironmentFile=/etc/dsh/dsh.env

Mantenga ese archivo con permisos 600 y asígnelo al usuario con el que se ejecuta el servicio.

Elegir modelos y el ID que no se puede cambiar de nombre

Todos los proveedores configurados aparecen en el selector de modelos. Al seleccionar un modelo, también se establece como predeterminado para las sesiones nuevas. Las sesiones que ya existen conservan el modelo registrado en ellas, por lo que cambiarlo no modifica una conversación anterior.

El ID del proveedor es permanente. Las solicitudes, las sesiones guardadas, los modelos predeterminados y las referencias a credenciales apuntan a él, por lo que no existe ningún botón para cambiarle el nombre. Para cambiarlo, debe crear un proveedor nuevo y eliminar el anterior. Elija un nombre que pueda mantener: local-ollama en lugar de test2.

Los modelos son sólo de texto, salvo que se indique lo contrario. Añada input: [text, image] a una entrada de modelo para declarar que admite imágenes, o establezca defaultInput en el nivel de la ruta como alternativa para los modelos que el catálogo no describe. La ruta de chat-completions propia de DeepSeek sólo admite texto y no se puede configurar de otra forma, por lo que una imagen adjunta a esa ruta se rechaza antes de enviar nada.

Indique a dsh un endpoint local para mantener el código en el servidor

Ollama expone una API compatible con OpenAI en http://127.0.0.1:11434/v1. dsh puede usar cualquier URL base compatible con OpenAI mediante un proveedor personalizado, por lo que ambos se conectan directamente. Configure primero el servidor de modelos: alojar un LLM en un VPS con Ollama explica la instalación y la descarga del modelo.

Confirme que el endpoint responde antes de modificar dsh.

ollama list
curl -s http://127.0.0.1:11434/v1/models

ollama list muestra la etiqueta exacta de cada modelo que ha descargado. Copie esa cadena. curl devuelve los mismos modelos en formato JSON. Una lista vacía indica que Ollama se está ejecutando sin ningún modelo descargado. Connection refused indica que Ollama no se está ejecutando o que no está escuchando en 11434.

Ahora añada el proveedor. Ollama requiere un campo de clave de API e ignora su valor, por lo que sirve cualquier cadena no vacía.

llm-pi-ai:
  providers:
    local-ollama:
      apiKeyEnv: OLLAMA_API_KEY
      api: openai-completions
      baseURL: http://127.0.0.1:11434/v1
      models:
        - id: <the exact tag printed by ollama list>

Exporte la variable donde pueda verla el proceso de dsh.

sudo install -d -m 700 /etc/dsh
printf 'OLLAMA_API_KEY=ollama\n' | sudo tee /etc/dsh/dsh.env
sudo chmod 600 /etc/dsh/dsh.env

Tres fallos cubren casi todos los intentos. MISSING_CREDENTIAL indica que dsh no pudo leer la variable cuyo nombre aparece en apiKeyEnv, así que compruebe el entorno del proceso, no el entorno de su terminal. UNKNOWN_MODEL indica que id no coincide con ningún modelo configurado, así que compárelo con ollama list carácter por carácter, incluida la etiqueta posterior a los dos puntos. Un error 401 al obtener los modelos disponibles procede del descubrimiento de modelos, que llama a GET /models en la URL base; los endpoints que no sirven esa ruta requieren introducir los modelos manualmente.

Hay otro problema frecuente con la URL base. No incluya /v1 al final; de lo contrario, las solicitudes se envían a rutas que Ollama no sirve, la llamada devuelve un error 404 y el modelo no se ejecuta. El sufijo forma parte de la interfaz compatible con OpenAI; no es decorativo.

Si Ollama se ejecuta en otra máquina, la dirección de esa máquina se convierte en la URL base y las solicitudes cruzan la red en texto claro mediante HTTP sin cifrar. Manténgalo en el mismo host o protéjalo con TLS (seguridad de la capa de transporte) y autenticación: proteger un endpoint de Ollama expuesto.

Qué sale de la máquina en cada modo

Con una clave de DeepSeek, cada solicitud se envía a la API de DeepSeek. Esa solicitud incluye el prompt, el contenido de los archivos que el agente leyó para responder, la salida de los comandos que ejecutó y cualquier resultado de herramientas que decidiera incluir. El código fuente queda dentro de esa carga cuando el agente abre un archivo. Así funciona un modelo alojado, y por eso conviene tener en cuenta en qué directorio inicia el agente.

Con otro proveedor del catálogo o con una pasarela de la empresa, la misma carga se envía a ese proveedor. La URL base indica exactamente adónde.

Con un endpoint local, la solicitud al modelo se envía a 127.0.0.1:11434 y permanece en el equipo. Ninguna parte del código llega a un proveedor de modelos. Aun así, tres elementos atraviesan la red. npx descarga el paquete del registro de npm. Cualquier herramienta que ejecute el agente puede acceder a Internet por su cuenta, incluidos los servidores MCP (protocolo de contexto del modelo) que haya conectado; ejecutar servidores MCP en un VPS lo explica en detalle. Un plugin pertenece a la misma categoría, porque instalarlo ejecuta código de otro autor con los permisos del agente, así que conviene comprobar a qué puede acceder un plugin antes de instalarlo. También la telemetría, si la activa.

La telemetría está desactivada hasta que se acepta explícitamente. DSH_TELEMETRY_MODE es el interruptor de consentimiento, y los valores no definidos, vacíos o no reconocidos se resuelven como DISABLED. En ese estado, dsh no crea ningún proveedor, procesador ni exportador de OpenTelemetry (OTel), por lo que un perfil nuevo no realiza ninguna solicitud de red de telemetría. FEEDBACK_ONLY activa el uso compartido de registros de sesión desencadenado por comentarios. FULL también permite informar sobre el lanzador. El flujo de la sesión puede exportar contenido de la sesión, datos de herramientas, prompts y rutas del espacio de trabajo, así que considere FULL como el envío de su trabajo a DeepSeek.

Para detenerlo por completo sin depender de acertar con la cadena del modo, establezca DSH_TELEMETRY_DISABLED=1. Cualquier valor no vacío constituye una exclusión autorizada, y se lee antes de iniciar la ejecución, por lo que el código del proyecto no puede volver a activarlo durante la sesión. La dirección predeterminada del colector es harness-telemetry.deepseeksvc.com, un nombre útil para identificarla al revisar sus propios registros del firewall.

Verifique la configuración en lugar de confiar en ella. Con una tarea en ejecución, muestre las conexiones salientes que mantiene el proceso.

sudo ss -tnp | grep -i node

En el modo de modelo local debería ver la conexión de loopback a 11434 y ninguna conexión a una dirección pública. Conviene identificar cualquier otra conexión antes de continuar. Qué envía un agente de programación a su proveedor realiza la misma comprobación con otros harnesses y explica cómo interpretar el resultado.

Dónde no deben almacenarse los secretos

• Historial del shell. export DEEPSEEK_API_KEY=sk-... se escribe en ~/.bash_history en texto sin cifrar y permanece allí mucho después de rotar la clave. Anteponer un espacio al comando cuando HISTCONTROL=ignorespace está configurada, o evitar el shell y escribir el valor directamente en un archivo con modo 600.
• Archivos dot confirmados en el repositorio. Una clave en ~/.bashrc o ~/.zshrc queda a git add de un repositorio público si mantiene los archivos dot en git. Ejecute git grep -I -n 'sk-' en ese repositorio antes de hacer push.
• settings.yaml. Use apiKeyEnv para los proveedores personalizados, de modo que el archivo contenga un nombre de variable en lugar de un secreto. Los archivos de configuración se pegan en informes de incidencias y chats de soporte. Los archivos de credenciales no.
• Salida de env y capturas de pantalla del terminal. Todo lo que muestre el entorno completo también muestra la clave.
• Copias de seguridad. Vale la pena incluir ~/.dsh en las copias de seguridad, pero .credentials.yaml dentro de él es un secreto activo. Excluya ese archivo o cifre el archivo comprimido.

Estas reglas no son específicas de dsh, y mantener los secretos fuera de los archivos de entorno de Compose aborda el mismo problema en el lado de los contenedores del mismo servidor.

Trabajar con una versión preliminar para desarrolladores

Fije la versión que probó, porque una versión preliminar puede cambiar una clave de configuración en una versión de corrección y el proveedor puede dejar de cargarse. Si la instalación fijada se niega a iniciar, o npx sigue entregándole una compilación que no solicitó, los errores de instalación y versión que produce una versión preliminar cubre la caché de npx y el npm incluido con Node. Mantenga settings.yaml y cordis.patch.yml bajo control de versiones, con el archivo de credenciales excluido, para poder ver qué cambió después de una actualización.

Dos opciones ayudan cuando un perfil no se comporta como espera. --dump-default-config muestra la configuración predeterminada compuesta sin iniciar el servicio, y --dump-config muestra de la misma forma la configuración compuesta para su perfil. Compararlas muestra qué cambió realmente la capa de parches, lo que es más rápido que leer las capas manualmente.

dsh --profile web --dump-config

Cuando algo falle después de una actualización, ejecute primero ese comando. Una clave que se haya movido entre versiones aparece como una rama ausente en el volcado, y la corrección consiste en editar una sola línea en lugar de reinstalar.

FAQ

¿Dónde almacena dsh mi clave de API de DeepSeek?

En $DSH_HOME/.credentials.yaml, que es ~/.dsh/.credentials.yaml salvo que establezca DSH_HOME usted mismo. La página Models escribe la clave allí y la configuración sólo conserva una referencia a ella, por lo que el secreto queda en un único archivo. Compruebe los permisos con stat -c '%a %n' ~/.dsh/.credentials.yaml y establézcalos en 600 si son menos restrictivos. Un proveedor personalizado puede evitar por completo el archivo si especifica una variable de entorno con apiKeyEnv.

¿Cómo hago que dsh use un modelo local en lugar de la API de DeepSeek?

Añada un proveedor personalizado cuya URL base sea su endpoint local compatible con OpenAI. Para Ollama es http://127.0.0.1:11434/v1, con api: openai-completions y un modelo id copiado exactamente de ollama list. Ollama requiere un valor para la clave de API, pero lo ignora, por lo que sirve cualquier cadena no vacía. Confirme que el endpoint responde con curl -s http://127.0.0.1:11434/v1/models antes de editar la configuración de dsh, porque un endpoint inactivo y una configuración incorrecta producen errores similares.

¿Envía dsh mi código a algún sitio de forma predeterminada?

Con un modelo alojado, sí. El prompt y el contenido de los archivos que lee el agente se incluyen en la solicitud de API enviada a ese proveedor. Con un endpoint local, esa solicitud se envía a loopback y permanece en el equipo. La telemetría es un flujo independiente y está desactivada de forma predeterminada: DSH_TELEMETRY_MODE se resuelve en DISABLED cuando no está definida y, en ese estado, no se crea ningún exporter. Establezca DSH_TELEMETRY_DISABLED=1 para impedir la telemetría; esta opción se lee antes de iniciar la ejecución.

¿Por qué dsh informa de MISSING_CREDENTIAL si mi variable está definida?

Porque dsh lee de su propio entorno de procesos la variable cuyo nombre indica apiKeyEnv. Una variable exportada en su shell no llega a un servicio de systemd, a la sesión de otro usuario ni a un proceso iniciado antes de exportarla. Coloque el valor en un EnvironmentFile con permisos 600 para la unidad, o expórtelo en el mismo shell desde el que inicia dsh. Confirme qué conserva realmente el proceso en ejecución con sudo tr '\0' '\n' < /proc/$(pgrep -f dsh | head -1)/environ.

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

Node.js 22.19 o posterior dentro de la línea 22, o 24 y posteriores. Node 23 no está dentro del intervalo compatible. Ejecute node -v antes de cualquier otra acción, porque un fallo de inicio causado por un runtime no compatible parece una instalación dañada y puede llevar a reinstalar el paquete en lugar del runtime.