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    },  },}

Defina el modelo principal y los modelos alternativos 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 define el catálogo de modelos y actúa como lista de permitidos para /model; las entradas provider/* filtran /model, /models y los selectores de modelos a los proveedores seleccionados, a la vez que se sigue usando el descubrimiento dinámico de modelos.
• Use openclaw config set agents.defaults.models '<json>' --strict-json --merge para añadir entradas a la lista de permitidos sin eliminar los modelos existentes. Los reemplazos simples que eliminarían entradas se rechazan a menos que se especifique --replace.
• Las referencias de modelos usan el formato provider/model (por ejemplo, anthropic/claude-opus-4-6).
• agents.defaults.imageMaxDimensionPx controla la reducción de escala de las imágenes de transcripciones y herramientas (valor predeterminado: 1200); los valores más bajos suelen reducir el uso de tokens de visión en ejecuciones con muchas capturas de pantalla.
• Consulte la CLI de modelos para cambiar de modelo en el chat y la conmutación por error de modelos para conocer la rotación de autenticación y el comportamiento de los modelos alternativos.
• 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 emparejamiento de un solo uso que debe aprobarse
• "allowlist": solo se permiten los remitentes incluidos en allowFrom (o en el almacén de remitentes emparejados permitidos)
• "open": se permiten todos los mensajes directos entrantes (requiere allowFrom: ["*"])
• "disabled": se ignoran todos los mensajes directos

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

Consulte la referencia completa para conocer los detalles de cada canal.

De forma predeterminada, los mensajes grupales requieren una mención. Configure patrones de activación para cada agente. Las respuestas normales de grupos y canales se publican automáticamente; habilite 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 mediante 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 permanente sin menciones se usa como contexto silencioso    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

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

Use agents.defaults.skills como base compartida y, después, sustituya la configuración de agentes específicos mediante agents.list[].skills:

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

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

Controle con qué agresividad el Gateway reinicia los canales que parecen inactivos:

{  gateway: {    channelHealthCheckMinutes: 5,    channelStaleEventThresholdMinutes: 30,    channelMaxRestartsPerHour: 10,  },  channels: {    telegram: {      healthMonitor: { enabled: false },      accounts: {        alerts: {          healthMonitor: { enabled: true },        },      },    },  },}

• Los valores mostrados son los predeterminados. Establezca gateway.channelHealthCheckMinutes: 0 para deshabilitar globalmente los reinicios del monitor de estado.
• channelStaleEventThresholdMinutes debe ser mayor o igual que el intervalo de comprobación.
• Use channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled para deshabilitar los reinicios automáticos de un canal o una cuenta sin deshabilitar el monitor global.
• Consulte Comprobaciones de estado para la depuración operativa y la referencia completa para conocer todos los campos.

Conceda más tiempo a los clientes locales para completar el protocolo de enlace WebSocket previo a la autenticación en hosts con mucha carga o pocos recursos:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• El valor predeterminado es 15000 milisegundos.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS sigue teniendo prioridad para sustituciones puntuales en servicios o shells.
• Es preferible corregir primero los bloqueos del inicio o del bucle de eventos; este ajuste está destinado a hosts que funcionan correctamente, pero son lentos durante el calentamiento.

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.

Ejecuta las sesiones del agente en entornos de ejecución aislados:

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

Primero, crea la imagen: desde un repositorio de código fuente, ejecuta scripts/sandbox-setup.sh; si se trata de una instalación mediante npm, consulta el comando docker build incluido en Entorno aislado § Imágenes y configuración.

Consulta 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 la 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 utilizas una compilación con retransmisión personalizada, establece 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

Qué hace esto:

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

Flujo de extremo a extremo:

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

Notas operativas:

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

Nota de compatibilidad:

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

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

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

• every: cadena de duración (30m, 2h). Establezca 0m para desactivarlo. 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 similares a mensajes directos
• Consulte Heartbeat para ver la guía completa.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // valor predeterminado; despacho de Cron + ejecución aislada del turno del agente de Cron    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: elimina las sesiones de ejecuciones aisladas completadas de las filas de sesiones de SQLite (valor predeterminado: 24h; usar false para deshabilitarlo).
• runLog: elimina las filas conservadas del historial de ejecuciones de Cron por trabajo. El historial se almacena en SQLite; maxBytes (valor predeterminado: 2_000_000) se conserva por compatibilidad con registros de ejecución anteriores basados en archivos y keepLines tiene como valor predeterminado 2000.
• Consultar Trabajos de Cron para obtener una descripción general de la función y ejemplos de la CLI.

Habilitar los endpoints de Webhook HTTP 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:

• Tratar todo el contenido de las cargas útiles de hooks/Webhooks como entrada no confiable.
• Usar un hooks.token específico; no reutilizar 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 /; mantener la entrada de Webhooks en una subruta específica, como /hooks.
• Mantener deshabilitadas las opciones para omitir la protección contra contenido no seguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent), salvo para una depuración de alcance muy limitado.
• Si se habilita hooks.allowRequestSessionKey, establecer también hooks.allowedSessionKeyPrefixes para limitar las claves de sesión seleccionadas por quien realiza la llamada.
• Para los agentes controlados mediante hooks, se recomienda usar niveles de modelos modernos y potentes, así como una política de herramientas estricta (por ejemplo, solo mensajería y aislamiento cuando sea posible).

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

Ejecutar 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" } },  ],}

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

Usar $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 que lo contiene
• Matriz de archivos: se fusionan en profundidad en orden (prevalecen los posteriores), con hasta 10 niveles de anidamiento
• Claves del mismo nivel: se fusionan después de las inclusiones (sobrescriben los valores incluidos)
• Rutas relativas: se resuelven en relación con el 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 compatible: las inclusiones raíz, las matrices de inclusiones y las inclusiones con sobrescrituras del mismo nivel producen un fallo seguro en las escrituras propiedad de OpenClaw, en lugar de aplanar la configuración
• Confinamiento: las rutas de $include deben resolverse dentro del directorio que contiene openclaw.json. Para compartir un árbol entre máquinas o usuarios, establecer OPENCLAW_INCLUDE_ROOTS en una lista de rutas (: en POSIX, ; en Windows) de directorios adicionales a los que pueden hacer referencia las inclusiones. Los enlaces simbólicos se resuelven y se vuelven a comprobar, por lo que una ruta que léxicamente se encuentra dentro de un directorio de configuración, pero cuyo destino real queda fuera de todas las raíces permitidas, se sigue rechazando.
• Gestión de errores: errores claros para archivos ausentes, errores de análisis, inclusiones circulares, formatos de ruta no válidos y longitudes excesivas