Resumen
Twenty ofrece dos modos de configuración para adaptarse a diferentes necesidades de implementación: Acceso al panel de administración: Solo los usuarios con privilegios de administrador (canAccessFullAdminPanel: true) pueden acceder a la interfaz de configuración.
1. Configuración del Panel de Administración (Predeterminado)
- Acceda a su instancia de Twenty (normalmente
http://localhost:3000) - Vaya a Configuración / Panel de Administración / Variables de Configuración
- Configure integraciones, correo electrónico, almacenamiento y más
- Los cambios se aplican inmediatamente (dentro de 15 segundos para implementaciones multicontenedor)
- Autenticación - OAuth de Google/Microsoft, configuración de contraseñas
- Correo Electrónico - Configuración de SMTP, plantillas, verificación
- Almacenamiento - Configuración S3, rutas de almacenamiento local
- Integraciones - Gmail, Google Calendar, servicios de Microsoft
- Flujo de Trabajo y Limitación de Tasas - Límites de ejecución, restricción de API
- Y mucho más…

Claves de cifrado
Twenty utiliza dos claves de cifrado definidas únicamente mediante variables de entorno:
Para mantener la compatibilidad con versiones anteriores, si
ENCRYPTION_KEY no está definida, Twenty recurre a APP_SECRET para el cifrado en reposo, lo que coincide con el comportamiento heredado de implementaciones más antiguas. Las nuevas instalaciones siempre deben establecer una ENCRYPTION_KEY dedicada.
Genera valores con openssl rand -base64 32 y guárdalos en un lugar seguro (un gestor de secretos, configuración sellada, etc.). Perder la ENCRYPTION_KEY significa perder el acceso a todos los secretos almacenados en la base de datos.
Para rotar ENCRYPTION_KEY sin tiempo de inactividad, consulta la Guía de rotación de claves.
2. Configuración Solo de Entorno
.env:
- Establezca
IS_CONFIG_VARIABLES_IN_DB_ENABLED=falseen su archivo.env - Agregue todas las variables de configuración a su archivo
.env - Reinicie los contenedores para que los cambios tengan efecto
- El panel de administración mostrará los valores actuales pero no podrá modificarlos
Modo de múltiples espacios de trabajo
De forma predeterminada, Twenty se ejecuta en modo de un solo espacio de trabajo — ideal para la mayoría de las implementaciones autoalojadas en las que necesitas una instancia de CRM para tu organización.Modo de un solo espacio de trabajo (predeterminado)
- Un espacio de trabajo por instancia de Twenty
- El primer usuario se convierte automáticamente en administrador con privilegios completos (
canImpersonateycanAccessFullAdminPanel) - Los nuevos registros se deshabilitan después de crear el primer espacio de trabajo
- Estructura de URL simple:
https://your-domain.com
Habilitar el modo de múltiples espacios de trabajo
- Se pueden crear varios espacios de trabajo en la misma instancia
- Cada espacio de trabajo obtiene su propio subdominio (p. ej.,
sales.your-domain.com,marketing.your-domain.com) - Los usuarios se registran e inician sesión en
{DEFAULT_SUBDOMAIN}.your-domain.com(p. ej.,app.your-domain.com) - Sin privilegios de administrador automáticos — el primer usuario de cada espacio de trabajo es un usuario normal
- Configuraciones específicas del espacio de trabajo, como subdominio y dominio personalizado, están disponibles en la configuración del espacio de trabajo
Configuración de DNS para múltiples espacios de trabajo
Al usar el modo de múltiples espacios de trabajo, configura tu DNS con un registro comodín para permitir la creación dinámica de subdominios:Restricción de la creación de espacios de trabajo
En el modo de múltiples espacios de trabajo, es posible que quieras limitar quién puede crear nuevos espacios de trabajo:canAccessFullAdminPanel pueden crear espacios de trabajo adicionales. Los usuarios aún pueden crear su primer espacio de trabajo durante el registro inicial.
Integración con Gmail y Google Calendar
Crear Proyecto en Google Cloud
- Vaya a Google Cloud Console
- Cree un nuevo proyecto o seleccione uno existente
- Habilite estas APIs:
Configurar OAuth
- Vaya a Credenciales
- Cree un ID de Cliente OAuth 2.0
- Agregue estas URIs de redirección:
https://{your-domain}/auth/google/redirect(para SSO)https://{your-domain}/auth/google-apis/get-access-token(para integraciones)
Configurar en Twenty
- Vaya a Configuración → Panel de Administración → Variables de Configuración
- Encuentre la sección Google Auth
- Establezca estas variables:
MESSAGING_PROVIDER_GMAIL_ENABLED=trueCALENDAR_PROVIDER_GOOGLE_ENABLED=trueAUTH_GOOGLE_CLIENT_ID={client-id}AUTH_GOOGLE_CLIENT_SECRET={client-secret}AUTH_GOOGLE_CALLBACK_URL=https://{your-domain}/auth/google/redirectAUTH_GOOGLE_APIS_CALLBACK_URL=https://{your-domain}/auth/google-apis/get-access-token
https://www.googleapis.com/auth/calendar.eventshttps://www.googleapis.com/auth/gmail.readonlyhttps://www.googleapis.com/auth/profile.emails.read
Si su aplicación está en modo de prueba
Si su aplicación está en modo de prueba, deberá agregar usuarios de prueba a su proyecto. En Pantalla de consentimiento OAuth, agregue sus usuarios de prueba en la sección “Usuarios de prueba”.Integración con Microsoft 365
Cree un proyecto en Microsoft Azure
Necesitará crear un proyecto en Microsoft Azure y obtener las credenciales.Habilitar APIs
En la Consola de Microsoft Azure habilite las siguientes APIs en “Permisos”:- Microsoft Graph: Mail.ReadWrite
- Microsoft Graph: Mail.Send
- Microsoft Graph: Calendars.ReadWrite
- Microsoft Graph: User.Read
- Microsoft Graph: openid
- Microsoft Graph: email
- Microsoft Graph: profile
- Microsoft Graph: offline_access
Todos estos permisos son obligatorios, incluso si solo desea sincronizar correos electrónicos y eventos de calendario. Twenty siempre solicita “Mail.ReadWrite”, “Mail.Send” y “Calendars.ReadWrite” cuando un usuario conecta su cuenta, por lo que los permisos de solo lectura como “Mail.Read” o “Calendars.Read” no son suficientes.
Si su inquilino no permite que los usuarios habituales den su consentimiento para estos permisos, verán el error AADSTS90094 al conectar su cuenta. Un administrador puede solucionar esto haciendo clic en “Grant admin consent for ” en la página “API permissions” del registro de la aplicación.
URIs de redirección autorizadas
Necesita agregar las siguientes URIs de redirección a su proyecto:https://{your-domain}/auth/microsoft/redirectsi quieres usar el inicio de sesión único de Microsofthttps://{your-domain}/auth/microsoft-apis/get-access-token
Configurar en Twenty
- Vaya a Configuración → Panel de Administración → Variables de Configuración
- Encuentre la sección Microsoft Auth
- Establezca estas variables:
MESSAGING_PROVIDER_MICROSOFT_ENABLED=trueCALENDAR_PROVIDER_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_ENABLED=trueAUTH_MICROSOFT_CLIENT_ID={client-id}AUTH_MICROSOFT_CLIENT_SECRET={client-secret}AUTH_MICROSOFT_CALLBACK_URL=https://{your-domain}/auth/microsoft/redirectAUTH_MICROSOFT_APIS_CALLBACK_URL=https://{your-domain}/auth/microsoft-apis/get-access-token
Configurar ámbitos
Ver código fuente relevante- ‘openid’
- ‘correo Electrónico’
- ‘perfil’
- ‘offline_access’
- ‘Mail.ReadWrite’
- ‘Mail.Send’
- ‘Calendars.ReadWrite’
- ‘User.Read’
Si su aplicación está en modo de prueba
Si su aplicación está en modo de prueba, deberá agregar usuarios de prueba a su proyecto. Agregue sus usuarios de prueba a la sección “Usuarios y grupos”.Trabajos en segundo plano para Calendarios y Mensajes
Después de configurar las integraciones de Gmail, Google Calendar, o Microsoft 365, necesita iniciar los trabajos en segundo plano que sincronizan los datos. Registre los siguientes trabajos recurrentes en su contenedor de trabajo:Conexiones salientes a hosts internos
De forma predeterminada, Twenty rechaza las conexiones salientes a direcciones IP privadas/internas (protección SSRF). Esto abarca las acciones de flujo de trabajo HTTP, los webhooks, los proveedores de identidad SSO y las conexiones IMAP/SMTP/CalDAV. Si su proveedor de identidad, servidor de correo o de calendario se ejecuta en una red privada, indique su nombre de host o dirección IP literal:http://keycloak:8080/realms/twenty, indique keycloak. Todas las demás direcciones privadas permanecen bloqueadas e incluso un host permitido nunca puede acceder al rango de direcciones de metadatos de la nube. Establezca la variable en * para desactivar por completo la protección, lo cual solo es apropiado en redes aisladas y de confianza.
OUTBOUND_HTTP_SAFE_MODE_ENABLED está obsoleta. Mientras esté establecida en false, la protección permanecerá completamente desactivada y se ignorará OUTBOUND_HTTP_ALLOWED_INTERNAL_HOSTS, así que elimínela cuando migre a la lista.
Esta lista no cubre los archivos adjuntos de IA: las imágenes y los PDF llegan al modelo como enlaces creados a partir de SERVER_URL, recuperados por el proveedor de IA o por el SDK de IA en el trabajador, que rechaza las direcciones privadas. Para que los archivos adjuntos funcionen, SERVER_URL debe ser público; con un SERVER_URL de localhost o privado, los chats y agentes de IA solo funcionan con texto.
Configuración de Correo Electrónico
- Vaya a Configuración → Panel de Administración → Variables de Configuración
- Encuentre la sección Correo Electrónico
- Configure su configuración SMTP:
- Gmail
- Office365
- smtp4dev
Necesitará proporcionar una Contraseña de Aplicación.
- EMAIL_DRIVER=smtp
- EMAIL_SMTP_HOST=smtp.gmail.com
- EMAIL_SMTP_PORT=465
- EMAIL_SMTP_USER=gmail_email_address
- EMAIL_SMTP_PASSWORD=‘gmail_app_password’
Almacenamiento de S3
EstableceSTORAGE_TYPE=S_3 y configura las variables STORAGE_S3_* a través del panel de administración o .env.
Un
.env mínimo para AWS S3 con un usuario de IAM:
El archivo Docker Compose reenvía
STORAGE_TYPE, STORAGE_S3_REGION, STORAGE_S3_NAME, STORAGE_S3_ENDPOINT y las dos variables de credenciales desde .env. Configure las variables de URL prefirmadas en el panel de administración o agréguelas al bloque environment de los servicios server y worker.Credenciales
CuandoSTORAGE_S3_ACCESS_KEY_ID no está configurado, el servidor resuelve las credenciales mediante la cadena predeterminada del SDK de AWS: las variables de entorno AWS_ACCESS_KEY_ID y AWS_SECRET_ACCESS_KEY, un archivo de credenciales compartido, un rol de tarea de ECS, un rol de cuenta de servicio de EKS (IRSA) o un perfil de instancia de EC2.
CredentialsProviderError: Could not load credentials from any providers en la primera carga, mientras que la interfaz de usuario solo muestra un error genérico.
Permisos del bucket
Una carga se escribe primero en una ruta pendiente, se valida, luego se copia a su ruta final y se elimina el objeto pendiente. Por lo tanto, la política necesita más ques3:PutObject:
s3:ListBucket se utiliza para eliminar carpetas, por ejemplo, cuando se elimina un espacio de trabajo. Sin él, S3 responde a las solicitudes de objetos inexistentes con acceso denegado en lugar de no encontrado, por lo que el servidor no puede distinguir un archivo inexistente de un problema de permisos.
Endpoint y direccionamiento
Twenty siempre utiliza direccionamiento de estilo de ruta, por lo que las solicitudes van ahttps://endpoint/bucket/key. Para AWS S3 nativo, deje STORAGE_S3_ENDPOINT sin configurar: el SDK crea https://s3.{region}.amazonaws.com a partir de STORAGE_S3_REGION, por lo que una región escrita incorrectamente se manifiesta como un error de DNS en lugar de un error de S3. Configure el endpoint solo para servicios compatibles con S3 o cuando el servidor acceda a S3 mediante un endpoint de interfaz de VPC.
CORS
CuandoSTORAGE_S3_PRESIGNED_URL_ENABLED es true, los navegadores se comunican directamente con el bucket. Las descargas son solicitudes GET y las cargas son solicitudes PUT que incluyen una cabecera Content-Type, lo que hace que el navegador envíe primero una solicitud de comprobación previa. Por lo tanto, la política CORS del bucket debe permitir su origen de Twenty, ambos métodos y esa cabecera:
Solución de Problemas
Los errores de carga llegan a la interfaz de usuario como un error genérico. El error de S3 subyacente está en los registros del servidor (docker compose logs server) y en la respuesta de GraphQL visible en la pestaña de red del navegador.
Funciones de lógica e intérprete de código
Twenty admite funciones de lógica para flujos de trabajo y el intérprete de código para el análisis de datos con IA. Ambos ejecutan código proporcionado por el usuario y requieren una configuración explícita por motivos de seguridad.Valores Predeterminados de Seguridad
En producción (NODE_ENV=production): Tanto las funciones de lógica como el intérprete de código tienen como valor predeterminado Desactivado. Debes habilitarlos explícitamente conLOGIC_FUNCTION_TYPE y CODE_INTERPRETER_TYPE si necesitas estas funciones.
En desarrollo (NODE_ENV=development): Ambos usan LOCAL de forma predeterminada para mayor comodidad al ejecutarse localmente.
Funciones de lógica - Controladores disponibles
Funciones de lógica - Configuración recomendada
Para desarrollo:Intérprete de código - Controladores disponibles
Al usar
LOGIC_FUNCTION_TYPE=DISABLED o CODE_INTERPRETER_TYPE=DISABLED, cualquier intento de ejecución devolverá un error. Esto es útil si desea ejecutar Twenty sin estas capacidades.API y front-end en hosts separados
Solo es relevante si no permites que el back-end sirva el front-end. Las implementaciones de mismo origen no necesitan nada aquí. Declara cada origen de navegador que se comunique con la API, separados por comas.SERVER_URL
y FRONTEND_URL ya son de confianza. El servidor registra una advertencia cuando un navegador
lo llama desde un origen no declarado.
AUTH_COOKIE_SAME_SITE=none, lo cual requiere HTTPS.
Con varios espacios de trabajo habilitados, no listes aquí todos los subdominios de los espacios de trabajo.
En su lugar, enruta las rutas de la API (/graphql, /metadata, /rest, /auth/,
/client-config, /file) al back-end en cada nombre de host de cada espacio de trabajo, de modo que cada
espacio de trabajo permanezca en el mismo origen — así es como funciona Twenty Cloud.