← Volver al listado de tecnologías ← Índice de Nod: asistente personal de n8n labs

Referencia de configuración

10 de noviembre de 2026 Por: Artiko

nodconfiguracionvariables-de-entornodockerself-hostedopentelemetry

Referencia de configuración

Objetivos

Saber qué archivo .env lee cada tipo de instalación y qué tiene precedencia.
Aplicar cambios de configuración sin perder datos.
Tener a mano todas las variables y sus valores por defecto.
Desactivar la analítica, el feedback y las trazas cuando haga falta.

Este capítulo aplica a instalaciones desde código y a servidores propios. La app de escritorio no lee .env: cuando se conecta a un servidor usa la configuración de ese servidor, y su dirección y su token son ajustes del cliente.

Cómo funcionan los ajustes

flowchart TD
    Shell["Variables de la shell<br/>solo instalación directa"] -- "ganan sobre" --> EnvRepo[".env del repositorio"]
    EnvRepo --> Srv["Servidor de Nod<br/>lee al arrancar"]
    Shell --> Srv
    EnvStack[".env del stack<br/>deployment/self-host/"] --> Srv
    App["Ajustes hechos en la app<br/>modelos, apps, canales"] --> DB[("Base de datos<br/>cifrados")]
    DB --> Srv

Instalación	Archivo	Detalles
Desde código	`.env` en la carpeta del repositorio	Git lo ignora. `pnpm start` lo crea desde `.env.example`. Una variable de la shell gana sobre la misma variable del archivo
Stack de servidor	`.env` en `deployment/self-host/`	Compose lo pasa con `env_file`, así que no hace falta editar `compose.yaml`. No reenvía variables arbitrarias de la shell del host

La mayoría de las cosas no necesitan variable: modelos, apps y canales se conectan en la app y Nod los guarda cifrados en la base de datos.

En el stack de servidor, NOD_AUTH_TOKEN, NOD_VAULT_KEY y NOD_POSTGRES_PASSWORD deben quedarse en .env.

Aplicar cambios

Nod lee los ajustes al arrancar. Tras editar .env:

docker compose up -d --wait

Con el proxy HTTPS incluido:

docker compose --profile https up -d --wait

Compose recrea los contenedores cuya configuración cambió y conserva los volúmenes de datos. En una instalación directa, detén y vuelve a iniciar el proceso de Nod.

docker compose restart no aplica cambios. Ese comando conserva los valores de entorno antiguos.

Servidor y datos

Variable	Qué hace	Por defecto
`PORT`	Puerto local de la app y de la API	`4310`
`NOD_HOST`	Dirección en la que escucha el servidor. Una dirección que no sea loopback exige `NOD_AUTH_TOKEN`	`127.0.0.1`
`NOD_AUTH_TOKEN`	Token de acceso para clientes web y de escritorio: al menos 43 letras, dígitos, `_` o `-`. Obligatorio para escuchar fuera de loopback o con una URL pública	Sin definir; las instalaciones locales generan una clave de acceso privada
`NOD_DATA_ROOT`	Carpeta de datos locales: sesiones, archivos del workspace y la clave de acceso	`.local`
`NOD_POSTGRES_PASSWORD`	Contraseña del contenedor local de PostgreSQL. Un valor propio necesita al menos 43 caracteres	Generada
`DATABASE_URL`	Conexión a PostgreSQL. `pnpm start` la rellena para el contenedor local en `127.0.0.1:54329`	Contenedor local
`DATABASE_POOL_MAX`	Máximo de conexiones a la base de datos	`12`
`NOD_PUBLIC_URL`	Origen exacto desde el que abres Nod. Sin ruta, query, fragmento ni credenciales	`http://localhost:<PORT>`
`NOD_PRIVACY_NOTICE_FILE`	Aviso de privacidad en Markdown que se sirve en `/privacy`	Sin aviso

Para generar un token a mano:

openssl rand -hex 32

Ejemplo de un servidor remoto:

NOD_PUBLIC_URL=https://nod.example.com
NOD_AUTH_TOKEN=<your-generated-token>

Cambiar NOD_AUTH_TOKEN y aplicar la configuración revoca el token anterior; hay que reconectar los clientes. En una configuración local, omite NOD_AUTH_TOKEN y NOD_PUBLIC_URL si no los usas: un valor vacío explícito no es válido.

Modelos

Variable	Qué hace	Por defecto
`LLM_PROVIDER`	Proveedor de la primera elección de modelo. Un modelo elegido en la app tiene prioridad	`openai`
`LLM_MODEL`	Primera elección de modelo	El del proveedor
`OPENAI_API_KEY`	Añade una conexión OpenAI. También activa la transcripción de voz y las respuestas por voz	Vacío
`ANTHROPIC_API_KEY`	Añade una conexión Anthropic	Vacío
`ANTHROPIC_WORKSPACE_ID`	Workspace para la clave de Anthropic. Solo con claves de organización no limitadas a un workspace	Vacío
`OPENROUTER_API_KEY`	Añade una conexión OpenRouter, con voces de ElevenLabs y Kokoro	Vacío
`ELEVENLABS_API_KEY`	Añade una conexión ElevenLabs para voz y transcripción, sin modelo de chat	Vacío
`OPENAI_COMPATIBLE_BASE_URL`	Añade un servidor compatible con OpenAI, por ejemplo Ollama en `http://localhost:11434/v1`	Vacío
`OPENAI_COMPATIBLE_API_KEY`	Clave de ese servidor, si la necesita	Vacío
`TYPESAFE_API_KEY`	Usa Jev directo para las comprobaciones de correo de acceso a cuentas y para el modo `decision`	Vacío
`NOD_TRUST_MODEL`	Verificador de acciones: `selected`, `llm` o `decision`	`selected`
`TTS_MODEL`	Modelo de voz de OpenAI para las respuestas habladas	`gpt-4o-mini-tts`
`STT_MODEL`	Modelo para transcribir mensajes de voz entrantes	`gpt-transcribe` (`openai/gpt-transcribe` en OpenRouter)
`TTS_VOICE`	Voz de las respuestas habladas	`coral`

Las claves definidas aquí son conexiones gestionadas por el servidor: se mantienen en memoria y no se copian a la base de datos. Se pueden configurar varios proveedores a la vez; LLM_PROVIDER solo fija la selección inicial.

Variables de clave por proveedor

`LLM_PROVIDER`	Variable de clave
`openai`	`OPENAI_API_KEY`
`anthropic`	`ANTHROPIC_API_KEY`
`google`	`GEMINI_API_KEY`
`openrouter`	`OPENROUTER_API_KEY`
`amazon-bedrock`	`AWS_BEARER_TOKEN_BEDROCK` (más `AWS_REGION`)
`google-vertex`	`GOOGLE_CLOUD_API_KEY`
`azure`	`AZURE_OPENAI_API_KEY` (más `AZURE_OPENAI_ENDPOINT`, `AZURE_OPENAI_MODEL`, `AZURE_OPENAI_DEPLOYMENT`)
`cloudflare-workers-ai`	`CLOUDFLARE_WORKERS_AI_API_KEY` (más `CLOUDFLARE_ACCOUNT_ID`)
`cloudflare-ai-gateway`	`CLOUDFLARE_AI_GATEWAY_API_KEY` (más `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_GATEWAY_ID`)
`compatible`	`OPENAI_COMPATIBLE_API_KEY` (más `OPENAI_COMPATIBLE_BASE_URL`)
`deepseek`	`DEEPSEEK_API_KEY`
`groq`	`GROQ_API_KEY`
`mistral`	`MISTRAL_API_KEY`
`together`	`TOGETHER_API_KEY`
`fireworks`	`FIREWORKS_API_KEY`
`cerebras`	`CEREBRAS_API_KEY`
`xai`	`XAI_API_KEY`
`huggingface`	`HF_TOKEN`
`nvidia`	`NVIDIA_API_KEY`
`vercel-ai-gateway`	`AI_GATEWAY_API_KEY`

La documentación de modelos lista además ant-ling, baseten, kimi-coding, meta, minimax, moonshotai, opencode, opencode-go, qwen-token-plan, radius, xiaomi y zai, con sus variantes regionales. Cada variante regional tiene su propia variable, para que la clave de una región no se use en otra.

Apps y Composio

Variable	Qué hace	Por defecto
`NOD_COMPOSIO_PROXY_URL`	Servicio de conexión de confianza para instalaciones desde código o servidor	`https://composio.n8n.cloud`

Debe ser un origen HTTPS sin ruta, query, fragmento ni credenciales. HTTP solo se admite para localhost, 127.0.0.1 o [::1] en desarrollo local. Notion, Linear y n8n no pasan por este servicio: se conectan mediante sus propios servidores MCP.

Vault

Variable	Qué hace	Por defecto
`NOD_VAULT_KEY`	Clave de 32 bytes en base64 que cifra las credenciales guardadas	Sin definir en instalaciones desde código; el stack de servidor la genera en `.env`

openssl rand -base64 32

Sin la variable, una instalación desde código usa el llavero en macOS y el archivo NOD_DATA_ROOT/vault/master-key en Linux. Otras plataformas exigen NOD_VAULT_KEY.

Respalda la clave de Vault. Sin ella no se pueden leer las credenciales guardadas, y una copia de la base de datos sola no las recupera. Nod nunca genera una clave nueva si ya existen datos cifrados.

Canales

Deja vacías o sin definir todas las variables de un canal para gestionarlo desde Channels en la app. Definir cualquier variable no vacía de un canal lo convierte en gestionado por el servidor: la configuración del entorno tiene prioridad y la app no permite editarla ni quitarla.

Variable	Qué hace	Por defecto
`TELEGRAM_ENABLED`	`true` activa Telegram y `false` lo desactiva	Sin definir
`TELEGRAM_MODE`	`polling` recibe mensajes con peticiones salientes. `webhook` necesita una dirección HTTPS pública	`polling`
`TELEGRAM_BOT_TOKEN`	Token del bot de BotFather	Vacío
`TELEGRAM_WEBHOOK_SECRET_TOKEN`	Secreto que Telegram envía en cada llamada: de 16 a 256 letras, dígitos, `_` o `-`. Obligatorio en modo webhook	Generado en memoria para polling
`TELEGRAM_ALLOWED_USER_ID`	Único ID de usuario de Telegram al que Nod responde	Vacío
`WHATSAPP_ENABLED`	`true` activa WhatsApp y `false` lo desactiva	Sin definir
`WHATSAPP_MODE`	`bot` vincula un número separado, `self-chat` vincula tu número y `cloud` usa Meta Cloud API	`cloud`
`WHATSAPP_POLICY_CONFIRMED`	`true` confirma que tu uso está permitido por los términos de WhatsApp. Obligatorio	`false`
`WHATSAPP_ACCESS_TOKEN`	Token de acceso de WhatsApp Cloud API	Vacío
`WHATSAPP_APP_SECRET`	Secreto de la app de Meta, usado para verificar las firmas del webhook	Vacío
`WHATSAPP_PHONE_NUMBER_ID`	ID del número emisor de la cuenta business	Vacío
`WHATSAPP_VERIFY_TOKEN`	Token que Meta envía al verificar el webhook	Vacío
`WHATSAPP_ALLOWED_NUMBER`	Tu número personal con código de país, de 7 a 15 dígitos. Obligatorio para `bot` y Cloud API	Vacío

La configuración mínima de Telegram por entorno es:

TELEGRAM_BOT_TOKEN=<token-de-botfather>
TELEGRAM_ALLOWED_USER_ID=<tu-id-de-usuario>

El capítulo 13 cubre el registro del webhook de Telegram y los modos de WhatsApp.

Analítica y feedback

Variable	Qué hace	Por defecto
`NOD_ANALYTICS_ENABLED`	`false` desactiva los datos de uso para todos	Activo con `pnpm start`, inactivo con `pnpm run dev`
`NOD_ANALYTICS_ENVIRONMENT`	Etiqueta de los eventos: `production` o `development`	Según `NODE_ENV`
`NOD_APP_VERSION`	Versión o revisión que acompaña a los eventos y a los informes de feedback	La de la app o del repositorio
`NOD_FEEDBACK_ENABLED`	`false` desactiva los envíos de feedback	Activo
`NOD_FEEDBACK_URL`	Dirección HTTPS que recibe los informes de Send feedback. Vacío desactiva el envío	El equipo de Nod en n8n
`NOD_FEEDBACK_RECEIPT_URL_PREFIX`	Obligatoria con un colector propio. URL HTTPS que termina en `/`	Issues del colector por defecto
`NOD_FEEDBACK_TOKEN`	Autenticación enviada como `x-nod-feedback-token`	Vacío
`NOD_TRACES_URL`	Dirección HTTPS que recibe las trazas de conversación de quienes las activan. Vacío las desactiva para todos	El equipo de Nod en n8n
`NOD_TRACES_TOKEN`	Token enviado con cada traza. Sin él, Nod no envía trazas y oculta el interruptor	Vacío
`NOD_ONBOARDING_EMAIL_URL`	Dirección HTTPS que acepta los correos de alta en novedades. Vacío desactiva ese registro	Un webhook de n8n

Para desactivar la analítica, el registro de contacto y el feedback:

NOD_ANALYTICS_ENABLED=false
NOD_ONBOARDING_EMAIL_URL=
NOD_FEEDBACK_ENABLED=false

Estos ajustes no desactivan el tráfico de modelos, de apps ni de actualizaciones. Según la documentación, la analítica va a un proyecto de PostHog en la UE, sin opción de cambiar el destino en tiempo de ejecución.

OpenTelemetry

Variable	Qué hace	Por defecto
`OTEL_EXPORTER_OTLP_ENDPOINT`	URL base HTTP o HTTPS de tu colector OTLP. Nod añade `/v1/traces`	Vacío; exportación desactivada

OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:4318

Qué se exporta:

Un span por cada registro de uso de modelo, incluido el trabajo auxiliar y de segundo plano.
Cada span contiene proveedor y modelo, categoría, operación y estado, inicio y fin, tokens de entrada, salida y caché, y costos estimados.
No contiene prompts, respuestas, argumentos ni resultados de herramientas, claves ni errores crudos.
Usa OTLP sobre HTTP con JSON. Envía lotes cada 5 segundos y al apagar. La cola admite 256 spans como máximo; lo que sobra o falla se descarta sin reintentar.
Esta versión exporta solo spans de modelos: no métricas, logs, pasos de navegador ni spans de herramientas. No admite OTLP sobre gRPC ni envía cabeceras de autenticación.

La exportación es independiente de Share usage data y Share conversation traces.

Ordenadores

Variable	Qué hace	Por defecto
`WORKSPACE_CONTAINER`	Contenedor Docker del workspace	`nod-workspace`
`BROWSER_CONTAINER`	Contenedor Docker del navegador	`nod-browser`

El stack de servidor los define como nod-workspace-<project> y nod-browser-<project>, con COMPOSE_PROJECT_NAME como <project>.

Ajustes del stack de Docker

Van en deployment/self-host/.env y controlan Compose.

Variable	Qué hace	Por defecto
`COMPOSE_PROJECT_NAME`	Nombra los contenedores y volúmenes de la instalación. Cambiarlo selecciona otros datos	Generado una vez por `setup.sh`
`NOD_BIND_ADDRESS`	Interfaz del host para el puerto del backend	`127.0.0.1`
`NOD_IMAGE_TAG`	Etiqueta de las imágenes construidas desde tu código	`local`
`NOD_SERVER_MEMORY`	Límite de memoria del contenedor del servidor	`2g`
`NOD_BROWSER_MEMORY`	Límite de memoria del contenedor del navegador	`3g`
`NOD_WORKSPACE_MEMORY`	Límite de memoria del contenedor del workspace	`2g`

Compose fija NOD_HOST, NOD_DATA_ROOT, WORKSPACE_CONTAINER, BROWSER_CONTAINER, NODE_ENV y NOD_ENVIRONMENT para su disposición interna; esos valores sobrescriben el .env del stack.

DATABASE_URL solo se define para usar un PostgreSQL externo. En ese caso, los comandos de respaldo y restauración incluidos no aplican, porque solo soportan la base de datos incluida.

Instalaciones avanzadas desde código

Variable	Qué hace	Por defecto
`NOD_WEB_ROOT`	Directorio de la app web compilada	`dist/web`
`NODE_ENV`	`production` para un servidor persistente	Lo fija el comando de arranque
`NOD_ENVIRONMENT`	Etiqueta del entorno de ejecución	`development`

Las variables que empiezan por NOD_DESKTOP_ y NOD_TEST_ son internas del runtime y de las pruebas, y no se usan para configurar un servidor.

Voz local

En Settings → Voice & audio, elige Free voices y luego Set up → Download voices. Nod descarga modelos de Whisper y Kokoro en su carpeta de datos y los ejecuta en un proceso aparte. El audio se procesa en memoria. Las voces locales cubren inglés, español, francés, hindi, italiano y portugués de Brasil. Si te conectas a un servidor remoto, la inferencia corre en ese servidor.

Actividad

Abre el .env de tu instalación e identifica qué variables están definidas.
Cambia PORT a otro valor, aplica el cambio con docker compose up -d --wait y abre Nod en el puerto nuevo.
Define NOD_ANALYTICS_ENABLED=false y aplica la configuración.
Si tienes un colector OTLP, define OTEL_EXPORTER_OTLP_ENDPOINT y observa los spans de una petición.

Autoevaluación

1. ¿Lee la app de escritorio el archivo .env?

No. Cuando se conecta a un servidor usa la configuración del servidor.

2. ¿Por qué docker compose restart no aplica un cambio de .env?

Porque conserva los valores de entorno antiguos. Hay que usar docker compose up -d --wait, que recrea los contenedores afectados.

3. ¿Qué pasa al definir una sola variable no vacía de un canal?

El canal pasa a estar gestionado por el servidor: la configuración del entorno tiene prioridad y la app no permite editarlo ni quitarlo.

4. ¿Qué contienen los spans que exporta Nod por OpenTelemetry?

Datos de uso de modelos: proveedor, modelo, operación, tiempos, tokens y costos estimados. No contienen prompts, respuestas, argumentos de herramientas ni claves.

5. ¿Qué efecto tiene cambiar COMPOSE_PROJECT_NAME?

Selecciona otros contenedores y volúmenes, es decir, otros datos. No se cambia durante una actualización.

Lista de control

Sé qué .env usa mi instalación.
Aplico los cambios con docker compose up -d --wait o reiniciando el proceso.
Tengo respaldada la clave de Vault.
Decidí el valor de las variables de analítica, feedback y trazas.
Sé que una variable de canal no vacía bloquea la edición desde la app.

Anterior: Conectar un modelo · Siguiente: Apps, MCP, APIs, CLI y n8n