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 allowlist para /model; las entradas provider/* filtran /model, /models y los selectores de modelos a los proveedores seleccionados mientras siguen usando descubrimiento dinámico de modelos.
• Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge para añadir entradas a la allowlist sin eliminar modelos existentes. Los reemplazos planos que eliminarían entradas se rechazan 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 transcripción/herramientas (valor predeterminado 1200); 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 fallback.
• Para proveedores personalizados/autohospedados, consulta Proveedores personalizados en la referencia.

El acceso por DM se controla por canal mediante dmPolicy:

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

Para grupos, usa groupPolicy + groupAllowFrom o allowlists específicas del canal.

Consulta la referencia completa para ver detalles por canal.

Los mensajes grupales requieren mención de forma predeterminada. Configura patrones de activación por agente y mantén las respuestas visibles de sala en la ruta predeterminada de herramienta de mensajes, a menos que quieras intencionalmente respuestas finales automáticas heredadas:

{  messages: {    visibleReplies: "automatic", // set "message_tool" to require message-tool sends everywhere    groupChat: {      visibleReplies: "message_tool", // default; use "automatic" for legacy room replies    },  },  agents: {    list: [      {        id: "main",        groupChat: {          mentionPatterns: ["@openclaw", "openclaw"],        },      },    ],  },  channels: {    whatsapp: {      groups: { "*": { requireMention: true } },    },  },}

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

Usa agents.defaults.skills para una base compartida y luego sobrescribe agentes específicos con agents.list[].skills:

{  agents: {    defaults: {      skills: ["github", "weather"],    },    list: [      { id: "writer" }, // inherits github, weather      { id: "docs", skills: ["docs-search"] }, // replaces defaults      { id: "locked-down", skills: [] }, // no skills    ],  },}

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

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

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

• Define 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 más tiempo a los clientes locales 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 sobrescrituras 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 las conversaciones:

{  session: {    dmScope: "per-channel-peer",  // recommended for multi-user    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 alcance, los enlaces 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 aislamiento aislados:

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

Compila 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 Aislamiento § Imágenes y configuración.

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

El push respaldado por relay se configura en openclaw.json.

Define esto en la configuración del Gateway:

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

Equivalente en 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 a través del relay externo.
• Usa una concesión de envío con alcance 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 con la identidad del Gateway con la que se emparejó la app de iOS, por lo que otro Gateway no puede reutilizar el registro almacenado.
• Mantiene las compilaciones locales/manuales de iOS en APNs directas. Los envíos respaldados por relay se aplican solo a las compilaciones distribuidas oficiales que se registraron a través del relay.
• Debe coincidir con la URL base del relay integrada en la compilación oficial/TestFlight de iOS, para que el tráfico de registro y envío llegue al mismo despliegue del relay.

Flujo de extremo a extremo:

1. Instala una compilación oficial/TestFlight de iOS compilada con la misma URL base del relay.
2. Configura gateway.push.apns.relay.baseUrl en el Gateway.
3. Empareja la app de iOS con el Gateway y deja que se conecten tanto las sesiones del nodo como las del 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 identificador del relay y la concesión de envío, y luego los usa para push.test, avisos de activación y activaciones de reconexión.

Notas operativas:

• Si cambias la app de iOS a un Gateway diferente, vuelve a conectar la app para que pueda publicar un nuevo registro de relay vinculado a ese Gateway.
• Si publicas una nueva compilación 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 sobrescrituras temporales de entorno.
• OPENCLAW_APNS_RELAY_ALLOW_HTTP=true sigue siendo una vía de escape de desarrollo solo para local loopback; no persistas URLs de relay HTTP en la configuración.

Consulta App de iOS para ver el flujo de extremo a extremo y Flujo de autenticación y confianza para ver 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: 2, // cron dispatch + isolated cron agent-turn execution    sessionRetention: "24h",    runLog: {      maxBytes: "2mb",      keepLines: 2000,    },  },}

• sessionRetention: elimina sesiones de ejecución aisladas completadas de sessions.json (predeterminado 24h; define false para deshabilitar).
• runLog: recorta cron/runs/<jobId>.jsonl por tamaño y líneas conservadas.
• Consulta Trabajos de Cron para ver una descripción general de la función y ejemplos de CLI.

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

• Trata todo el contenido de las cargas útiles de hook/Webhook como entrada no confiable.
• Usa un hooks.token dedicado; no reutilices el token compartido del Gateway.
• La autenticación de hook es solo por encabezado (Authorization: Bearer ... o x-openclaw-token); los tokens en la cadena de consulta se rechazan.
• hooks.path no puede ser /; mantén el ingreso de Webhook en una subruta dedicada, como /hooks.
• Mantén deshabilitadas las marcas de omisión de contenido no seguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) salvo para depuración con alcance muy limitado.
• Si habilitas hooks.allowRequestSessionKey, define también hooks.allowedSessionKeyPrefixes para acotar las claves de sesión elegidas por el llamador.
• Para agentes impulsados por hooks, prefiere niveles de modelo modernos y sólidos y una política de herramientas estricta (por ejemplo, solo mensajería más aislamiento cuando sea posible).

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

Ejecuta varios agentes aislados con espacios de trabajo 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 las reglas de vinculación y los 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
• Matriz de archivos: se fusiona en profundidad en orden (gana el posterior)
• 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
• 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
• Write-through no admitido: los includes raíz, las matrices de includes y los includes con sobrescrituras hermanas fallan de forma cerrada 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 que los includes pueden referenciar. Los enlaces simbólicos 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 todas las raíces permitidas también se rechaza.
• Gestión de errores: errores claros para archivos faltantes, errores de análisis e includes circulares