Configuración

Cada canal tiene su propia sección de configuración bajo channels.<provider>. Consulta la página dedicada del canal para ver los pasos de configuración:

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

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

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

Define el modelo principal y los fallbacks 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 la lista de permitidos para /model; las entradas provider/* filtran /model, /models y los selectores de modelos a los proveedores seleccionados, mientras siguen usando el descubrimiento dinámico de modelos.
• Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge para agregar entradas a la lista de permitidos sin quitar los modelos existentes. Se rechazan los reemplazos simples que quitarían entradas, a menos que pases --replace.
• Las referencias de modelo usan 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/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.
• Consulta CLI de modelos para cambiar modelos en el chat y Conmutación por error de modelos para la rotación de autenticación y el comportamiento de reserva.
• Para proveedores personalizados/autohospedados, consulta Proveedores personalizados en la referencia.

El acceso por MD se controla por canal mediante dmPolicy:

• "pairing" (predeterminado): los remitentes desconocidos reciben un código de emparejamiento de un solo uso para aprobarlos
• "allowlist": solo remitentes en allowFrom (o en el almacén de permitidos emparejado)
• "open": permite todos los MD entrantes (requiere allowFrom: ["*"])
• "disabled": ignora todos los MD

Para grupos, usa groupPolicy + groupAllowFrom o listas de permitidos específicas del canal.

Consulta la referencia completa para obtener detalles por canal.

Los mensajes de grupo requieren mención de forma predeterminada. Configura patrones de activación por agente. Las respuestas normales de grupo/canal se publican automáticamente; opta por la ruta de herramienta de mensajes para salas compartidas donde el agente debe decidir cuándo hablar:

{  messages: {    visibleReplies: "automatic", // establece "message_tool" para requerir envíos de herramienta de mensajes en todas partes    groupChat: {      visibleReplies: "message_tool", // opción explícita; la salida visible requiere message(action=send)      unmentionedInbound: "room_event", // la charla de grupo siempre activa sin mención es contexto silencioso    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

• Menciones de metadatos: @-menciones nativas (mención por toque de WhatsApp, @bot de Telegram, etc.)
• Patrones de texto: patrones regex seguros en mentionPatterns
• Respuestas visibles: messages.visibleReplies puede requerir envíos de herramienta de mensajes globalmente; messages.groupChat.visibleReplies lo anula para grupos/canales.
• Consulta la referencia completa para modos de respuesta visible, anulaciones por canal y modo de chat consigo mismo.

Usa agents.defaults.skills para una base compartida y luego anula agentes específicos con 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    ],  },}

• Omite agents.defaults.skills para permitir Skills sin restricciones de forma predeterminada.
• Omite agents.list[].skills para heredar los valores predeterminados.
• Establece agents.list[].skills: [] para no tener Skills.
• Consulta Skills, Configuración de Skills y la Referencia de configuración.

Controla con qué agresividad el gateway reinicia los canales que parecen obsoletos:

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

• Establece gateway.channelHealthCheckMinutes: 0 para desactivar globalmente los reinicios del monitor de estado.
• channelStaleEventThresholdMinutes debe ser mayor o igual que el intervalo de comprobación.
• Usa channels.<provider>.healthMonitor.enabled o channels.<provider>.accounts.<id>.healthMonitor.enabled para desactivar los reinicios automáticos de un canal o cuenta sin desactivar el monitor global.
• Consulta Comprobaciones de estado para depuración operativa y la referencia completa para todos los campos.

Da a los clientes locales más tiempo para completar el handshake WebSocket previo a la autenticación en hosts cargados o de baja potencia:

{  gateway: {    handshakeTimeoutMs: 30000,  },}

• El valor predeterminado es 15000 milisegundos.
• OPENCLAW_HANDSHAKE_TIMEOUT_MS sigue teniendo prioridad para anulaciones puntuales de servicio o shell.
• Prefiere corregir primero los bloqueos de inicio/bucle de eventos; este ajuste es para hosts que están sanos pero son lentos durante el calentamiento.

Las sesiones controlan la continuidad y el aislamiento de la conversación:

{  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 (Discord admite /focus, /unfocus, /agents, /session idle y /session max-age).
• Consulta Gestión de sesiones para el ámbito, los vínculos de identidad y la política de envío.
• Consulta la referencia completa para ver todos los campos.

Ejecuta sesiones de agente en runtimes de sandbox aislados:

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

Construye primero la imagen: desde un checkout de código fuente, ejecuta scripts/sandbox-setup.sh; o desde una instalación de npm, consulta el comando docker build en línea en Sandboxing § Imágenes y configuración.

Consulta Sandboxing para ver la guía completa y la referencia completa para ver todas las opciones.

El push respaldado por relay para builds públicas de la App Store usa el relay hospedado de OpenClaw: https://ios-push-relay.openclaw.ai.

Los despliegues de relay personalizados requieren una ruta de build/despliegue de iOS deliberadamente separada cuya URL de relay coincida con la URL de relay del Gateway. Si usas una build de relay personalizada, define esto en la configuración del Gateway:

{  gateway: {    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          // Optional. Default: 10000          timeoutMs: 10000,        },      },    },  },}

Equivalente de CLI:

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

Qué hace esto:

• Permite que el Gateway envíe push.test, nudges de activación y activaciones de reconexión a través del relay externo.
• Usa una concesión de envío con ámbito de registro reenviada por la app de iOS emparejada. El Gateway no necesita un token de relay para todo el despliegue.
• Vincula cada registro respaldado por relay a la identidad del Gateway con la que se emparejó la app de iOS, de modo que otro Gateway no pueda reutilizar el registro almacenado.
• Mantiene las builds locales/manuales de iOS en APNs directo. Los envíos respaldados por relay se aplican solo a builds distribuidas oficialmente que se registraron a través del relay.
• Debe coincidir con la URL base del relay integrada en la build de iOS, para que el tráfico de registro y de envío llegue al mismo despliegue de relay.

Flujo de extremo a extremo:

1. Instala la app oficial de iOS.
2. Opcional: configura gateway.push.apns.relay.baseUrl en el Gateway solo cuando uses una build de relay personalizada deliberadamente separada.
3. Empareja la app de iOS con el Gateway y deja que se conecten tanto las sesiones de nodo como las de operador.
4. La app de iOS obtiene la identidad del Gateway, se registra con el relay usando App Attest más el recibo de la app y luego publica la carga útil push.apns.register respaldada por relay en el Gateway emparejado.
5. El Gateway almacena el handle de relay y la concesión de envío, y luego los usa para push.test, nudges de activación y activaciones de reconexión.

Notas operativas:

• Si cambias la app de iOS a otro Gateway, vuelve a conectar la app para que pueda publicar un nuevo registro de relay vinculado a ese Gateway.
• Si publicas una nueva build de iOS que apunta a un despliegue de relay diferente, la app actualiza su registro de relay en caché en lugar de reutilizar el origen de relay anterior.

Nota de compatibilidad:

• OPENCLAW_APNS_RELAY_BASE_URL y OPENCLAW_APNS_RELAY_TIMEOUT_MS siguen funcionando como overrides temporales de entorno.
• Las URL de relay de Gateway personalizadas deben coincidir con la URL base de relay integrada en la build de iOS. La línea de lanzamiento pública de la App Store rechaza overrides de URL de relay de iOS personalizados.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true sigue siendo una vía de escape de desarrollo solo para loopback; no persistas URL de relay HTTP en la configuración.

Consulta App de iOS para ver el flujo de extremo a extremo y Autenticación y flujo de confianza para el modelo de seguridad del relay.

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

• every: cadena de duración (30m, 2h). Define 0m para deshabilitar.
• target: last | none | <channel-id> (por ejemplo discord, matrix, telegram o whatsapp)
• directPolicy: allow (predeterminado) o block para destinos de Heartbeat de estilo DM
• Consulta Heartbeat para ver la guía completa.

{  cron: {    enabled: true,    maxConcurrentRuns: 8, // default; cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: purga las sesiones de ejecución aisladas completadas de sessions.json (predeterminado 24h; define false para deshabilitar).
• runLog: purga las filas conservadas del historial de ejecución de Cron por trabajo. maxBytes sigue aceptándose para logs de ejecución antiguos respaldados por archivos.
• Consulta Trabajos de Cron para ver la descripción general de la función y ejemplos de CLI.

Habilita 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:

• Trata todo el contenido de cargas útiles de hooks/webhooks como entrada no confiable.
• Usa un hooks.token dedicado; no reutilices 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 usa encabezados (Authorization: Bearer ... o x-openclaw-token); se rechazan los tokens en la cadena de consulta.
• hooks.path no puede ser /; conserva el ingreso de Webhook en una subruta dedicada como /hooks.
• Mantén deshabilitadas las flags de omisión de contenido inseguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) salvo que estés haciendo depuración con alcance estricto.
• Si habilitas hooks.allowRequestSessionKey, también define hooks.allowedSessionKeyPrefixes para delimitar las claves de sesión seleccionadas por el llamador.
• Para agentes impulsados por hooks, prefiere tiers de modelos modernos sólidos y una política de herramientas estricta (por ejemplo, solo mensajería más sandboxing cuando sea posible).

Consulta la referencia completa para ver todas las opciones de mapeo y la integración con Gmail.

Ejecuta varios agentes aislados con workspaces y sesiones separados:

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

Consulta Multiagente y la referencia completa para ver reglas de vinculación y perfiles de acceso por agente.

Usa $include para organizar configuraciones grandes:

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

• Archivo único: reemplaza el objeto contenedor
• Array de archivos: se fusiona en profundidad en orden (lo posterior gana)
• Claves hermanas: se fusionan después de los includes (sobrescriben los valores incluidos)
• Includes anidados: admitidos hasta 10 niveles de profundidad
• Rutas relativas: se resuelven en relación con el archivo que incluye
• Formato de ruta: las rutas de include no deben contener bytes nulos y deben ser estrictamente menores que 4096 caracteres antes y después de la resolución
• Escrituras propiedad de OpenClaw: cuando una escritura cambia solo una sección de nivel superior respaldada por un include de archivo único como plugins: { $include: "./plugins.json5" }, OpenClaw actualiza ese archivo incluido y deja openclaw.json intacto
• Escritura directa no admitida: los includes raíz, arrays de includes e includes con overrides hermanos fallan cerrados para escrituras propiedad de OpenClaw en lugar de aplanar la configuración
• Confinamiento: las rutas de $include deben resolverse bajo el directorio que contiene openclaw.json. Para compartir un árbol entre máquinas o usuarios, define OPENCLAW_INCLUDE_ROOTS como una lista de rutas (: en POSIX, ; en Windows) de directorios adicionales a los que los includes pueden hacer referencia. Los symlinks se resuelven y se vuelven a comprobar, por lo que una ruta que léxicamente vive en un directorio de configuración pero cuyo destino real escapa de toda raíz permitida sigue siendo rechazada.
• Manejo de errores: errores claros para archivos faltantes, errores de análisis, includes circulares, formato de ruta inválido y longitud excesiva