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 respaldos 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.
• Usa openclaw config set agents.defaults.models '<json>' --strict-json --merge para agregar entradas a la lista de permitidos sin eliminar modelos existentes. Los reemplazos simples 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); 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 respaldo.
• 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 aprobarlos
• "allowlist": solo remitentes en allowFrom (o en el almacén de permitidos vinculados)
• "open": permite todos los DM entrantes (requiere allowFrom: ["*"])
• "disabled": ignora todos los DM

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

Consulta la referencia completa para ver detalles por canal.

Los mensajes de grupo 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 la herramienta de mensajes, salvo que quieras intencionalmente las 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 (mención táctil de WhatsApp, @bot de Telegram, etc.)
• Patrones de texto: patrones regex seguros en mentionPatterns
• Respuestas visibles: messages.visibleReplies puede requerir envíos con herramienta de mensajes globalmente; messages.groupChat.visibleReplies lo sobrescribe para grupos/canales.
• Consulta la referencia completa para ver los modos de respuesta visible, las sobrescrituras por canal y el modo de chat propio.

Usa agents.defaults.skills como 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 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 sobrescrituras puntuales de servicio o shell.
• Prefiere corregir primero los bloqueos de inicio o del 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",  // 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 vinculado a hilos (Discord admite /focus, /unfocus, /agents, /session idle y /session max-age).
• Consulta Gestión de sesiones para ámbitos, enlaces de identidad y política de envío.
• Consulta la referencia completa para 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
      },
    },
  },
}

Compila primero la imagen: desde un checkout de origen 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 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 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 iOS, de modo que otro gateway no pueda reutilizar el registro almacenado.
• Mantiene las compilaciones locales/manuales de iOS en APNs directo. Los envíos respaldados por relay solo se aplican a compilaciones oficiales distribuidas 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 de relay.

Flujo de extremo a extremo:

1. Instala una compilación oficial/TestFlight de iOS que se haya compilado con la misma URL base del relay.
2. Configura gateway.push.apns.relay.baseUrl en el gateway.
3. Empareja la app iOS con el gateway y deja que se conecten tanto las sesiones del nodo como las del operador.
4. La app 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 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 iOS a otro gateway, vuelve a conectar la app para que pueda publicar un nuevo registro de relay vinculado a ese gateway.
• Si distribuyes una nueva compilación de iOS que apunta a un despliegue de relay distinto, 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 limitada a loopback; no persistas URLs de relay HTTP en la configuración.

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

• sessionRetention: depura las sesiones de ejecución aisladas completadas de sessions.json (predeterminado 24h; define false para deshabilitar).
• runLog: depura cron/runs/<jobId>.jsonl por tamaño y líneas conservadas.
• 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 carga de hook/Webhook como entrada no confiable.
• Usa un hooks.token dedicado; no reutilices el token compartido del Gateway.
• 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 /; mantén la entrada de Webhook en una subruta dedicada como /hooks.
• Mantén deshabilitadas las marcas para omitir contenido inseguro (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) salvo que estés haciendo depuración de alcance muy limitado.
• Si habilitas hooks.allowRequestSessionKey, define también hooks.allowedSessionKeyPrefixes para limitar las claves de sesión seleccionadas por el llamador.
• Para agentes controlados por hooks, prefiere niveles de modelos modernos y sólidos, y una política de herramientas estricta (por ejemplo, solo mensajería más sandboxing donde sea posible).

Consulta la referencia completa para ver todas las opciones de asignación y la integración de 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 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 que lo contiene
• Array de archivos: se fusiona en profundidad en orden (el último 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
• 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 transparente no admitida: los includes raíz, los arrays 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 $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 enlaces simbólicos se resuelven y se vuelven a comprobar, por lo que una ruta que vive léxicamente en un directorio de configuración pero cuyo destino real escapa de todas las raíces permitidas se sigue rechazando.
• Manejo de errores: errores claros para archivos faltantes, errores de análisis e includes circulares