n8n es una plataforma de automatización visual que conecta disparadores, nodos de procesamiento y nodos de salida en un flujo de trabajo. La plataforma no ofrece modelos propios: los modelos provienen del servicio de API que configures. Para muchos equipos, la práctica habitual es preparar una pasarela compatible con OpenAI y después configurar una Base URL personalizada en n8n, de modo que los pasos de conversación, resumen y clasificación se integren en los procesos de negocio.

Este artículo sigue el orden real de montaje: instalación, preparación de parámetros, configuración de credenciales, puesta en marcha del flujo, tratamiento de errores y, por último, despliegue en equipo. Los nombres de la interfaz cambian según la versión; toma como referencia la que uses actualmente.

Nota: n8n es una marca de n8n GmbH y OpenAI es una marca de OpenAI, Inc. Este artículo es solo una guía técnica de integración y no implica afiliación ni relación con esas empresas. El catálogo de modelos y los precios se rigen por la página de precios de modelos.

1. ¿Nube o autoalojamiento?

n8n ofrece alojamiento en la nube y autoalojamiento. La nube evita el mantenimiento del servidor y sirve para validar rápido; el autoalojamiento permite controlar la ruta de los datos, la salida de red y el ritmo de actualización, y encaja en equipos con requisitos de cumplimiento o necesidad de acceso a la red interna. Este artículo se centra en el autoalojamiento, porque la Base URL personalizada, las variables de entorno y los permisos de equipo aparecen con más frecuencia en ese escenario.

El autoalojamiento también tiene costos: servidor, base de datos, copias de seguridad, HTTPS, actualizaciones y configuración de seguridad corren por tu cuenta. Antes de decidir, aclara quién se encargará de la operación.

2. Instalación e inicialización

El método de producción recomendado por n8n es Docker Compose; para una prueba en una sola máquina basta un comando docker run. La imagen es n8nio/n8n, el puerto predeterminado es 5678 y el volumen de datos se monta en /home/node/.n8n. Ese directorio no solo contiene la base de datos SQLite, también archivos como la clave de cifrado, y debe persistir.

docker volume create n8n_data

docker run -it --rm --name n8n \
  -p 5678:5678 \
  -e GENERIC_TIMEZONE="UTC" \
  -e TZ="UTC" \
  -e N8N_ENFORCE_SETTINGS_FILE_PERMISSIONS=true \
  -v n8n_data:/home/node/.n8n \
  n8nio/n8n

Tras el arranque, abre http://localhost:5678 y crea la cuenta de propietario siguiendo las indicaciones. En producción no conviene mantener SQLite en una sola máquina durante mucho tiempo: configura DB_TYPE=postgresdb y DB_POSTGRESDB_* para conectar PostgreSQL, e incluye la base de datos en las copias de seguridad. La instalación por npm (npx n8n o instalación global) sirve para pruebas locales; la documentación de n8n indica que la instalación por npm queda obsoleta desde n8n 3.0 y que producción debe usar Docker. Los requisitos de versión de Node.js se rigen por la documentación de instalación; el rango que figura actualmente es 20.19 a 24.x.

3. Prepare la clave, la Base URL y el ID del modelo

Para conectar cualquier servicio compatible con OpenAI solo hacen falta tres parámetros:

Parámetro Cómo rellenarlo Error habitual
API Key Se crea en la consola de la pasarela, con un nombre por proyecto Espacios o saltos de línea al copiar
Base URL https://ai.zhongshangqihang.com/v1 Escribir la ruta completa /chat/completions
ID del modelo El identificador de API que aparece en la página de precios Usar el nombre visible o un sufijo de versión antiguo

La clave se crea después de registrarte en ZSQH AI Gateway. Conviene usar una clave por entorno, separando pruebas y producción, para poder revocarla de forma individual si se filtra. El ID del modelo se copia de la página de precios de modelos; revisa mayúsculas y sufijos de versión. Los modelos disponibles y la facturación pueden cambiar, así que toma como referencia la consola y la página de precios.

4. Configure la credencial de OpenAI

En el menú izquierdo de n8n, entra en Credentials y crea una credencial de tipo OpenAI. En la versión actual, los campos incluyen API Key, Organization ID (opcional) y Base URL. Si usas una pasarela, cambia la Base URL por la dirección de la pasarela, normalmente hasta /v1, sin /chat/completions. El Organization ID solo hace falta al conectar con el servicio propio de OpenAI y cuando la cuenta pertenece a varias organizaciones; con una pasarela compatible suele quedar vacío.

Algunas prácticas:

  1. Guarda la clave solo en la credencial; no la escribas en nodos Code, nodos Set ni en el JSON del flujo.
  2. Pon un nombre claro a la credencial, por ejemplo «pasarela-producción-resumen», no «prueba1».
  3. Después de guardar, pulsa Probar; si falla, revisa primero la Base URL y la salida de red.
  4. En instancias de equipo, crea credenciales por proyecto; que varias personas compartan una sola clave es mala idea.
  5. Si autoalojas, protege N8N_ENCRYPTION_KEY: al cambiarla, las credenciales existentes pueden quedar sin descifrar.

5. Ejecute el primer flujo

Tomemos como ejemplo «generar un borrador de respuesta tras enviar un formulario»:

  1. Crea un flujo nuevo y añade un Form Trigger o un Manual Trigger.
  2. Añade un nodo OpenAI y elige Text en Resource.
  3. En Operation, selecciona Generate a Chat Completion; en versiones antiguas el nombre correspondiente es Message a Model.
  4. Elige la credencial y el modelo recién creados y pasa los campos del formulario con una expresión, por ejemplo {{ $json.message }}.
  5. En el prompt, delimita el rol, el formato de salida y la longitud para reducir contenido irrelevante.
  6. Añade un nodo Set y conserva solo los campos que usarás después.
  7. Añade un nodo de Gmail, Slack o de hoja de cálculo y escribe el resultado en el destino.
  8. Ejecuta primero a mano y revisa la entrada y la salida de cada nodo; activa el flujo cuando todo esté confirmado.

Si la pasarela no admite la API de Responses, no elijas Generate a Model Response; usa la operación correspondiente a Chat Completions. Los parámetros que admite el nodo dependen de tu versión de n8n y de la documentación de la pasarela.

6. Llame a la interfaz compatible con el nodo HTTP Request

Para parámetros que el nodo no expone, peticiones en lote o campos especiales, puedes usar el nodo HTTP Request y llamar directamente a /v1/chat/completions. Elige POST como método, escribe la dirección completa de la interfaz en URL, selecciona Predefined Credential Type en Authentication y elige la credencial de OpenAI, o usa Bearer Auth dentro de Generic Credential Type. En Body, elige JSON y rellena el modelo, los mensajes y los parámetros.

El cuerpo de la petición no debe incluir la clave; la autenticación la inyecta la credencial. La respuesta se interpreta con el formato Chat Completions de OpenAI y normalmente se toma choices[0].message.content. Si la respuesta llega en streaming, en n8n hay que desactivar el streaming o usar un método que procese SSE; de lo contrario, el análisis fallará con facilidad.

7. Pruebas y tratamiento de errores

Antes de tocar el flujo, valida la dirección, la clave y el modelo con curl fuera de n8n; así ahorras muchas vueltas. En un flujo sin supervisión, los fallos deben tratarse como algo normal:

  1. Activa Retry On Fail en los ajustes del nodo y reintenta 2 o 3 veces en 429, 5xx y timeouts.
  2. Define un intervalo de reintento para no añadir presión cuando hay límite de tasa.
  3. Elige On Error según el negocio: detener, continuar o derivar la salida de error a una rama de excepción.
  4. Fija un timeout en las peticiones HTTP; la generación de textos largos puede tener más margen, pero nunca debe esperar indefinidamente.
  5. Configura un flujo de errores que envíe el ID de ejecución, el nombre del nodo y un resumen de la entrada a Slack o por correo.
  6. Antes de reintentar, comprueba la idempotencia para no duplicar mensajes ni registros.
Síntoma Causa habitual Solución
401 Clave incorrecta, caducada o credencial no seleccionada Vuelve a elegir la credencial y revisa espacios y estado
403 Modelo no habilitado o permisos insuficientes Verifica los permisos del modelo y el límite del proyecto
404 Base URL o ruta de la interfaz incorrecta Escribe solo hasta /v1, sin la ruta completa
429 Concurrencia alta o cuota superada Reduce la concurrencia y activa reintentos con retroceso
400 Parámetro no admitido por la pasarela Elimina los campos incompatibles y revisa el ID del modelo
Timeout Salida de red o respuesta lenta del upstream Revisa el proxy, el DNS y la configuración de timeout

8. Puntos clave para el despliegue en equipo

Cuando un equipo usa n8n, lo importante no es crear más cuentas, sino delimitar credenciales, proyectos y responsabilidades de operación:

  • Usa Projects para aislar líneas de negocio; los flujos y las credenciales pertenecen a un proyecto.
  • Emite claves por persona y por proyecto, para poder revocarlas de forma individual ante una baja o una filtración.
  • En producción, usa siempre HTTPS y configura N8N_WEBHOOK_URL con una dirección accesible desde fuera; en versiones antiguas la variable se llama WEBHOOK_URL.
  • En modo cola, todos los workers deben usar el mismo N8N_ENCRYPTION_KEY; de lo contrario, las credenciales no se descifran.
  • En producción, usa un task runner externo; no ejecutes los nodos Code en el proceso principal.
  • Haz copias de seguridad de la base de datos y de la clave de cifrado, guárdalas por separado y controla el acceso.
  • Define un tiempo de retención de los datos de ejecución para evitar que el historial crezca sin límite y reducir la exposición de datos sensibles.

Autoalojar no equivale a cumplimiento automático. Aún hay que confirmar por separado si el proveedor del modelo conserva las peticiones y si las usa para entrenar; en los procesos con datos de clientes, añade nodos de anonimización y revisión humana.

Preguntas frecuentes

¿El nodo OpenAI de n8n admite una Base URL personalizada?

Sí. La credencial de OpenAI actual incluye un campo Base URL cuyo valor predeterminado es https://api.openai.com/v1; basta cambiarlo por la dirección de la pasarela. Si tu versión no tiene ese campo, también puedes llamar con el nodo HTTP Request y Bearer Auth.

¿Hasta qué nivel hay que rellenar la Base URL?

Normalmente hasta /v1, por ejemplo https://ai.zhongshangqihang.com/v1. No escribas /v1/chat/completions, porque el nodo añade la ruta por su cuenta. El síntoma más habitual de un nivel incorrecto es un 404.

¿Por qué la prueba de credencial pasa pero la ejecución dice que el modelo no existe?

La prueba de credencial suele validar solo la clave y la dirección, no que todos los modelos estén disponibles para ti. Comprueba que el ID del modelo coincide con la página de precios, que el proyecto tiene permiso para ese modelo y que la petición no se está enviando a otra Base URL.

¿Es obligatorio usar PostgreSQL con n8n autoalojado?

No es obligatorio; SQLite sirve para pruebas y tráfico bajo. En producción se suele pasar a PostgreSQL para facilitar copias de seguridad, concurrencia y escalado; consulta la documentación de Docker Compose. Sea cual sea la base de datos, el directorio /home/node/.n8n debe persistir.

¿Qué hay que tener en cuenta cuando varias personas usan la instancia?

Separa credenciales por proyecto y por persona, sin compartir claves de larga duración; controla el acceso a flujos y credenciales con roles de proyecto; activa HTTPS, MFA y un task runner externo en producción; haz copia de la clave de cifrado y limita su acceso. Si necesitas un punto de entrada unificado de modelos y gestión de uso, puedes usar las claves virtuales y las cuotas de la pasarela.

Siguiente paso

La dificultad de conectar una API personalizada a n8n no está en arrastrar nodos, sino en alinear tres cosas: Base URL, clave e ID del modelo. Primero valida con curl, después configura la credencial de OpenAI y por último añade reintentos, ramas de error y permisos de equipo. Si necesitas un punto de entrada unificado, puedes registrarte en ZSQH AI Gateway; los modelos y los precios se rigen por la página de precios de modelos.

Lecturas relacionadas: