Configuración

Cada canal tiene su propia sección de configuración en channels.<provider>. Consulte la página específica del canal para conocer los pasos de configuración:

• Discord - channels.discord
• Feishu - channels.feishu
• Google Chat - channels.googlechat
• iMessage - channels.imessage
• Mattermost - channels.mattermost
• Microsoft Teams - channels.msteams
• Signal - channels.signal
• Slack - channels.slack
• Telegram - channels.telegram
• WhatsApp - channels.whatsapp

Todos los canales comparten el mismo patrón de política de mensajes directos:

{  channels: {    telegram: {      enabled: true,      botToken: "123:abc",      dmPolicy: "pairing",   // pairing | allowlist | open | disabled      allowFrom: ["tg:123"], // solo para allowlist/open    },  },}

Establezca el modelo principal y las alternativas opcionales:

{  agents: {    defaults: {      model: {        primary: "anthropic/claude-sonnet-4-6",        fallbacks: ["openai/gpt-5.4"],      },      models: {        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },        "openai/gpt-5.4": { alias: "GPT" },      },    },  },}

• agents.defaults.models almacena alias y ajustes por modelo; añadir una entrada nunca restringe las sobrescrituras de /model ni de --model.
• agents.defaults.modelPolicy.allow es la lista de permitidos explícita para las sobrescrituras y los selectores de modelos. Acepta referencias exactas y comodines provider/*; omítala o use [] para permitir cualquier modelo.
• Las referencias de modelos utilizan el formato provider/model (por ejemplo, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controla la reducción de escala de imágenes de transcripciones y herramientas (valor predeterminado: 1200); los valores inferiores suelen reducir el uso de tokens de visión en ejecuciones con muchas capturas de pantalla.
• Consulte CLI de modelos para cambiar de modelo en el chat y Conmutación por error de modelos para conocer la rotación de autenticación y el comportamiento de las alternativas.
• Para proveedores personalizados o autoalojados, consulte Proveedores personalizados en la referencia.

El acceso a los mensajes directos se controla por canal mediante dmPolicy (valor predeterminado: "pairing"):

• "pairing": los remitentes desconocidos reciben un código de vinculación de un solo uso para su aprobación
• "allowlist": solo los remitentes incluidos en allowFrom (o en el almacén de permitidos vinculados)
• "open": permite todos los mensajes directos entrantes (requiere allowFrom: ["*"])
• "disabled": ignora todos los mensajes directos

Para los grupos, use groupPolicy ("allowlist" | "open" | "disabled") junto con groupAllowFrom o las listas de permitidos específicas del canal.

Consulte la referencia completa para obtener información específica de cada canal.

De forma predeterminada, los mensajes de grupo requieren una mención. Configure los patrones de activación por agente. Las respuestas normales de grupos y canales se publican automáticamente; active la ruta de la herramienta de mensajes para las salas compartidas en las que el agente deba decidir cuándo intervenir:

{  messages: {    visibleReplies: "automatic", // establezca "message_tool" para exigir envíos con la herramienta de mensajes en todas partes    groupChat: {      visibleReplies: "message_tool", // opcional; la salida visible requiere message(action=send)      unmentionedInbound: "room_event", // la conversación grupal continua sin menciones sirve como contexto silencioso    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menciones mediante metadatos: menciones @ nativas (mención mediante toque en WhatsApp, @bot en Telegram, etc.)
• Patrones de texto: patrones de expresiones regulares seguros en mentionPatterns
• Respuestas visibles: messages.visibleReplies puede exigir globalmente los envíos con la herramienta de mensajes; messages.groupChat.visibleReplies sobrescribe ese comportamiento para grupos y canales.
• Consulte la referencia completa para conocer los modos de respuesta visible, las sobrescrituras por canal y el modo de chat con uno mismo.

Use agents.defaults.skills como base compartida y, después, sobrescriba agentes específicos con agents.entries.*.skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // hereda github, weather      { id: "docs", skills: ["docs-search"] }, // sustituye los valores predeterminados      { id: "locked-down", skills: [] }, // sin skills    ],  },}

• Omita agents.defaults.skills para permitir de forma predeterminada Skills sin restricciones.
• Omita agents.entries.*.skills para heredar los valores predeterminados.
• Establezca agents.entries.*.skills: [] para no permitir ninguna Skill.
• Consulte Skills, Configuración de Skills y la referencia de configuración.

Desactive o active los reinicios automáticos por estado para un canal o una cuenta:

{  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Use channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled para controlar los reinicios automáticos de un canal o una cuenta.
• Consulte Comprobaciones de estado para la depuración operativa y la referencia completa para conocer todos los campos.

Las sesiones controlan la continuidad y el aislamiento de las conversaciones:

{  session: {    dmScope: "per-channel-peer",  // recomendado para varios usuarios    threadBindings: {      enabled: true,      idleHours: 24,      maxAgeHours: 0,    },    reset: {      mode: "daily",      atHour: 4,      idleMinutes: 120,    },  },}

• dmScope: main (compartido) | per-peer | per-channel-peer | per-account-channel-peer
• threadBindings: valores predeterminados globales para el enrutamiento de sesiones vinculadas a hilos. /focus, /unfocus, /agents, /session idle y /session max-age vinculan, desvinculan, enumeran y ajustan esta configuración por sesión (Discord vincula hilos; Telegram vincula temas/conversaciones).
• Consulte Gestión de sesiones para obtener información sobre el ámbito, los vínculos de identidad y la política de envío.
• Consulte la referencia completa para conocer todos los campos.

Ejecute las sesiones de agentes en entornos aislados:

{  agents: {    defaults: {      sandbox: {        mode: "non-main",  // off | non-main | all        scope: "agent",    // session | agent | shared      },    },  },}

Primero compile la imagen: desde una copia de trabajo del código fuente, ejecute scripts/sandbox-setup.sh; si se instaló mediante npm, consulte el comando docker build incluido en Aislamiento § Imágenes y configuración.

Consulte Aislamiento para ver la guía completa y la referencia completa para conocer todas las opciones.

Las notificaciones push mediante retransmisión para las compilaciones públicas de App Store utilizan el servicio de retransmisión alojado de OpenClaw: https://ios-push-relay.openclaw.ai.

Las implementaciones de retransmisión personalizadas requieren una ruta de compilación e implementación de iOS deliberadamente independiente cuya URL de retransmisión coincida con la URL de retransmisión del Gateway. Si se utiliza una compilación de retransmisión personalizada, establezca lo siguiente en la configuración del Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Opcional. Valor predeterminado: 10000          timeoutMs: 10000,        },      },    },  },}

Equivalente en la CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Función de esta configuración:

• Permite que el Gateway envíe push.test, avisos de activación y activaciones de reconexión mediante el servicio de retransmisión externo.
• Utiliza una autorización de envío limitada al registro y reenviada por la aplicación iOS emparejada. El Gateway no necesita un token de retransmisión para toda la implementación.
• Vincula cada registro mediante retransmisión con la identidad del Gateway con el que se emparejó la aplicación iOS, de modo que ningún otro Gateway pueda reutilizar el registro almacenado.
• Mantiene las compilaciones locales/manuales de iOS en APNs directas. Los envíos mediante retransmisión solo se aplican a las compilaciones distribuidas oficialmente que se registraron mediante el servicio de retransmisión.
• Debe coincidir con la URL base de retransmisión integrada en la compilación de iOS, de modo que el tráfico de registro y envío llegue a la misma implementación de retransmisión.

Flujo de extremo a extremo:

1. Instale la aplicación oficial de iOS.
2. Opcional: configure gateway.push.apns.relay.baseUrl en el Gateway únicamente cuando utilice una compilación de retransmisión personalizada deliberadamente independiente.
3. Empareje la aplicación iOS con el Gateway y permita que se conecten tanto las sesiones de Node como las del operador.
4. La aplicación iOS obtiene la identidad del Gateway, se registra en el servicio de retransmisión mediante App Attest y el recibo de la aplicación y, a continuación, publica la carga útil push.apns.register mediante retransmisión en el Gateway emparejado.
5. El Gateway almacena el identificador de retransmisión y la autorización de envío y, a continuación, los utiliza para push.test, los avisos de activación y las activaciones de reconexión.

Notas operativas:

• Si se cambia la aplicación iOS a un Gateway diferente, vuelva a conectar la aplicación para que pueda publicar un nuevo registro de retransmisión vinculado a ese Gateway.
• Si se distribuye una nueva compilación de iOS que apunta a una implementación de retransmisión diferente, la aplicación actualiza su registro de retransmisión almacenado en caché en lugar de reutilizar el origen de retransmisión anterior.

Nota de compatibilidad:

• OPENCLAW_APNS_RELAY_BASE_URL y OPENCLAW_APNS_RELAY_TIMEOUT_MS siguen funcionando como sustituciones temporales mediante variables de entorno.
• Las URL de retransmisión personalizadas del Gateway deben coincidir con la URL base de retransmisión integrada en la compilación de iOS; el canal de publicación pública de App Store rechaza las sustituciones personalizadas de la URL de retransmisión de iOS.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true sigue siendo una vía de escape de desarrollo limitada a la interfaz de bucle invertido; no conserve URL de retransmisión HTTP en la configuración.

Consulte Aplicación iOS para ver el flujo de extremo a extremo y Flujo de autenticación y confianza para conocer el modelo de seguridad del servicio de retransmisión.

{  agents: {    defaults: {      heartbeat: {        every: "30m",        target: "last",      },    },  },}

• every: cadena de duración (30m, 2h). Establezca 0m para deshabilitarlo. Valor predeterminado: 30m.
• target: last | none | <channel-id> (por ejemplo, discord, matrix, telegram o whatsapp)
• directPolicy: allow (valor predeterminado) o block para destinos de Heartbeat al estilo de mensajes directos
• Consulte Heartbeat para ver la guía completa.

{  cron: {    enabled: true,    sessionRetention: "24h",  },}

• sessionRetention: elimina de las filas de sesiones de SQLite las sesiones finalizadas de ejecuciones aisladas (valor predeterminado: 24h; establezca false para deshabilitarlo).
• El historial de ejecuciones conserva automáticamente las 2000 filas de terminal más recientes por tarea; las filas perdidas mantienen su periodo de limpieza de 24 horas.
• Consulte Tareas Cron para ver una descripción general de la función y ejemplos de la CLI.

Habilite los puntos de conexión HTTP de Webhook en el Gateway:

{  hooks: {    enabled: true,    token: "shared-secret",    path: "/hooks",    defaultSessionKey: "hook:ingress",    allowRequestSessionKey: false,    allowedSessionKeyPrefixes: ["hook:"],    mappings: [      {        match: { path: "gmail" },        action: "agent",        agentId: "main",        deliver: true,      },    ],  },}

Nota de seguridad:

• Trate todo el contenido de las cargas útiles de hooks/Webhook como entrada no fiable.
• Utilice un hooks.token específico; no reutilice secretos de autenticación activos del Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD).
• La autenticación de hooks solo admite encabezados (Authorization: Bearer ... o x-openclaw-token); se rechazan los tokens en la cadena de consulta.
• hooks.path no puede ser /; mantenga la entrada de Webhook en una subruta específica, como /hooks.
• Mantenga deshabilitadas las opciones para omitir la protección frente a contenido no seguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), salvo durante una depuración con un ámbito estrictamente limitado.
• Si habilita hooks.allowRequestSessionKey, establezca también hooks.allowedSessionKeyPrefixes para limitar las claves de sesión seleccionadas por el emisor de la llamada.
• Para agentes controlados mediante hooks, se recomienda utilizar niveles de modelos modernos y potentes, además de una política de herramientas estricta (por ejemplo, solo mensajería y aislamiento cuando sea posible).

Consulte la referencia completa para conocer todas las opciones de asignación y la integración con Gmail.

Ejecute varios agentes aislados con espacios de trabajo y sesiones independientes:

{  agents: {    list: [      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },      { id: "work", workspace: "~/.openclaw/workspace-work" },    ],  },  bindings: [    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },  ],}

Consulte Multiagente y la referencia completa para conocer las reglas de vinculación y los perfiles de acceso de cada agente.

Utilice $include para organizar configuraciones extensas:

// ~/.openclaw/openclaw.json{  gateway: { port: 18789 },  agents: { $include: "./agents.json5" },  broadcast: {    $include: ["./clients/a.json5", "./clients/b.json5"],  },}

• Archivo único: sustituye el objeto contenedor
• Matriz de archivos: se combinan en profundidad por orden (el último prevalece), hasta 10 niveles anidados
• Claves hermanas: se combinan después de las inclusiones (sustituyen los valores incluidos)
• Rutas relativas: se resuelven con respecto al archivo que realiza la inclusión
• Formato de ruta: las rutas de inclusión no deben contener bytes nulos y deben tener estrictamente menos de 4096 caracteres antes y después de su resolución
• Escrituras propiedad de OpenClaw: cuando una escritura modifica únicamente una sección de nivel superior respaldada por una inclusión de un solo archivo, como plugins: { $include: "./plugins.json5" }, OpenClaw actualiza ese archivo incluido y deja openclaw.json intacto
• Escritura directa no admitida: las inclusiones raíz, las matrices de inclusiones y las inclusiones con sustituciones en claves hermanas producen un fallo seguro en las escrituras propiedad de OpenClaw, en lugar de aplanar la configuración
• Confinamiento: las rutas $include deben resolverse dentro del directorio que contiene openclaw.json. Para compartir un árbol entre máquinas o usuarios, establezca OPENCLAW_INCLUDE_ROOTS en una lista de rutas (: en POSIX, ; en Windows) de directorios adicionales a los que puedan hacer referencia las inclusiones. Los enlaces simbólicos se resuelven y vuelven a comprobarse, por lo que una ruta que léxicamente se encuentre en un directorio de configuración, pero cuyo destino real quede fuera de todas las raíces permitidas, también se rechaza.
• Gestión de errores: errores claros para archivos ausentes, errores de análisis, inclusiones circulares, formatos de ruta no válidos y longitudes excesivas