Configura OpenClaw: Guía de canales y políticas de acceso

Channels

Cada canal se inicia automáticamente cuando existe su sección de configuración (a menos que establezcas enabled: false).

Acceso a DM y grupos

Todos los canales admiten políticas de DM y de grupo:

Política de DM	Comportamiento
pairing (default)	Los remitentes desconocidos reciben un código de vinculación; el dueño aprueba
allowlist	Solo remitentes en allowFrom (o en el almacén de vinculaciones permitidas)
open	Permite todos los DM entrantes (requiere allowFrom: ["*"])
disabled	Ignora todos los DM entrantes

Política de grupo	Comportamiento
allowlist (default)	Solo grupos que coincidan con la lista de permitidos configurada
open	Omite las listas de permitidos (se sigue aplicando el filtro mención)
disabled	Bloquea todos los mensajes de grupos o salas

Nota

channels.defaults.groupPolicy establece el valor predeterminado cuando la groupPolicy de un provider no está definida. Los códigos de vinculación caducan después de 1 hora. Las solicitudes de vinculación de DM pendientes están limitadas a 3 por canal. Si falta por completo un bloque de provider (ausencia de channels.<provider>), la política de grupo en tiempo de ejecución recurre a allowlist (cierre por fallo) con una advertencia al iniciar.

Sobrescritura de modelos por canal

Usa channels.modelByChannel para fijar IDs de canales específicos a un modelo. Los valores aceptan provider/model o alias de modelos configurados. El mapeo de canales se aplica cuando una sesión no tiene ya una sobrescritura de modelo (por ejemplo, establecida mediante /model).

{
  channels: {
    modelByChannel: {
      discord: {
        "123456789012345678": "anthropic/claude-opus-4-6",
      },
      slack: {
        C1234567890: "openai/gpt-4.1",
      },
      telegram: {
        "-1001234567890": "openai/gpt-4.1-mini",
        "-1001234567890:topic:99": "anthropic/claude-sonnet-4-6",
      },
    },
  },
}

Valores predeterminados y heartbeat de canales

Usa channels.defaults para el comportamiento compartido de políticas de grupo y heartbeat entre providers:

{
  channels: {
    defaults: {
      groupPolicy: "allowlist", // open | allowlist | disabled
      heartbeat: {
        showOk: false,
        showAlerts: true,
        useIndicator: true,
      },
    },
  },
}

• channels.defaults.groupPolicy: política de grupo de respaldo cuando no se define groupPolicy a nivel de provider.
• channels.defaults.heartbeat.showOk: incluye estados de canales saludables en la salida del heartbeat.
• channels.defaults.heartbeat.showAlerts: incluye estados degradados o de error en la salida del heartbeat.
• channels.defaults.heartbeat.useIndicator: genera una salida de heartbeat compacta tipo indicador.

WhatsApp

WhatsApp funciona a través del canal web del gateway (Baileys Web). Se inicia automáticamente cuando existe una sesión vinculada.

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // blue ticks (false in self-chat mode)
      groups: {
        "*": { requireMention: true },
      },
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
  },
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

Multi-account WhatsApp

{
  channels: {
    whatsapp: {
      accounts: {
        default: {},
        personal: {},
        biz: {
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

• Los comandos salientes usan por defecto la cuenta default si está presente; de lo contrario, usan el primer ID de cuenta configurado (ordenado).
• El campo opcional channels.whatsapp.defaultAccount sobrescribe esa selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• El directorio de autenticación de Baileys para una sola cuenta (legacy) es migrado por openclaw doctor a whatsapp/default.
• Sobrescrituras por cuenta: channels.whatsapp.accounts.<id>.sendReadReceipts, channels.whatsapp.accounts.<id>.dmPolicy, channels.whatsapp.accounts.<id>.allowFrom.

Telegram

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing",
      allowFrom: ["tg:123456789"],
      groups: {
        "*": { requireMention: true },
        "-1001234567890": {
          allowFrom: ["@admin"],
          systemPrompt: "Keep answers brief.",
          topics: {
            "99": {
              requireMention: false,
              skills: ["search"],
              systemPrompt: "Stay on topic.",
            },
          },
        },
      },
      customCommands: [
        { command: "backup", description: "Git backup" },
        { command: "generate", description: "Create an image" },
      ],
      historyLimit: 50,
      replyToMode: "first", // off | first | all
      linkPreview: true,
      streaming: "partial", // off | partial | block | progress (default: off)
      actions: { reactions: true, sendMessage: true },
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 100,
      retry: {
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        autoSelectFamily: true,
        dnsResultOrder: "ipv4first",
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook",
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Bot token: channels.telegram.botToken o channels.telegram.tokenFile (solo archivos regulares; se rechazan symlinks), con TELEGRAM_BOT_TOKEN como respaldo para la cuenta predeterminada.
• El campo opcional channels.telegram.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• En configuraciones multi-account (2+ IDs de cuenta), establece una predeterminada explícita (channels.telegram.defaultAccount o channels.telegram.accounts.default) para evitar el enrutamiento de respaldo; openclaw doctor advierte si falta o no es válida.
• configWrites: false bloquea las escrituras de configuración iniciadas desde Telegram (migraciones de ID de supergrupos, /config set|unset).
• Las entradas de nivel superior bindings[] con type: "acp" configuran vinculaciones ACP persistentes para temas de foros (usa el formato canónico chatId:topic:topicId en match.peer.id). La semántica de los campos se comparte en ACP Agents.
• Las previsualizaciones de streaming en Telegram usan sendMessage + editMessageText (funciona en chats directos y de grupo).
• Política de reintento: consulta Retry policy.

Discord

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8,
      allowBots: false,
      actions: {
        reactions: true,
        stickers: true,
        polls: true,
        permissions: true,
        messages: true,
        threads: true,
        pins: true,
        search: true,
        memberInfo: true,
        roleInfo: true,
        roles: false,
        channelInfo: true,
        voiceStatus: true,
        events: true,
        moderation: false,
      },
      replyToMode: "off", // off | first | all
      dmPolicy: "pairing",
      allowFrom: ["1234567890", "123456789012345678"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["openclaw-dm"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          ignoreOtherMentions: true,
          reactionNotifications: "own",
          users: ["987654321098765432"],
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20,
      textChunkLimit: 2000,
      chunkMode: "length", // length | newline
      streaming: "off", // off | partial | block | progress (progress maps to partial on Discord)
      maxLinesPerMessage: 17,
      ui: {
        components: {
          accentColor: "#5865F2",
        },
      },
      threadBindings: {
        enabled: true,
        idleHours: 24,
        maxAgeHours: 0,
        spawnSubagentSessions: false, // opt-in for sessions_spawn({ thread: true })
      },
      voice: {
        enabled: true,
        autoJoin: [
          {
            guildId: "123456789012345678",
            channelId: "234567890123456789",
          },
        ],
        daveEncryption: true,
        decryptionFailureTolerance: 24,
        tts: {
          provider: "openai",
          openai: { voice: "alloy" },
        },
      },
      retry: {
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• Token: channels.discord.token, con DISCORD_BOT_TOKEN como respaldo para la cuenta predeterminada.
• Las llamadas salientes directas que proporcionan un token de Discord explícito usan ese token para la llamada; los ajustes de reintento/política de la cuenta siguen proviniendo de la cuenta seleccionada en el snapshot activo.
• El campo opcional channels.discord.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• Usa user:<id> (DM) o channel:<id> (canal de guild) para los objetivos de entrega; se rechazan los IDs numéricos simples.
• Los slugs de guild están en minúsculas con espacios reemplazados por -; las claves de canal usan el nombre con slug (sin #). Es preferible usar IDs de guild.
• Los mensajes escritos por bots se ignoran por defecto. allowBots: true los habilita; usa allowBots: "mentions" para aceptar solo mensajes de bots que mencionen al bot (los mensajes propios siguen filtrados).
• channels.discord.guilds.<id>.ignoreOtherMentions (y sobrescrituras de canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here).
• maxLinesPerMessage (por defecto 17) divide mensajes largos incluso si tienen menos de 2000 caracteres.
• channels.discord.threadBindings controla el enrutamiento vinculado a hilos de Discord:
  • enabled: sobrescritura de Discord para funciones de sesión vinculadas a hilos (/focus, /unfocus, /agents, /session idle, /session max-age, y entrega/enrutamiento vinculado).
  • idleHours: sobrescritura de Discord para el desenfoque automático por inactividad en horas (0 desactiva).
  • maxAgeHours: sobrescritura de Discord para la edad máxima estricta en horas (0 desactiva).
  • spawnSubagentSessions: interruptor opcional para la creación/vinculación automática de hilos en sessions_spawn({ thread: true }).
• Las entradas de nivel superior bindings[] con type: "acp" configuran vinculaciones ACP persistentes para canales e hilos (usa el ID de canal/hilo en match.peer.id). La semántica de los campos se comparte en ACP Agents.
• channels.discord.ui.components.accentColor establece el color de acento para los contenedores de componentes v2 de Discord.
• channels.discord.voice habilita conversaciones en canales de voz de Discord y sobrescrituras opcionales de auto-join + TTS.
• channels.discord.voice.daveEncryption y channels.discord.voice.decryptionFailureTolerance se pasan a las opciones DAVE de @discordjs/voice (true y 24 por defecto).
• OpenClaw intenta adicionalmente la recuperación de recepción de voz saliendo y volviendo a entrar en una sesión de voz tras fallos repetidos de descifrado.
• channels.discord.streaming es la clave canónica del modo de stream. Los valores legacy streamMode y booleanos streaming se migran automáticamente.
• channels.discord.autoPresence mapea la disponibilidad en tiempo de ejecución a la presencia del bot (saludable => online, degradado => idle, agotado => dnd) y permite sobrescrituras opcionales de texto de estado.
• channels.discord.dangerouslyAllowNameMatching vuelve a habilitar la coincidencia por nombre/tag mutable (modo de compatibilidad de emergencia).

Modos de notificación de reacciones: off (ninguno), own (mensajes del bot, por defecto), all (todos los mensajes), allowlist (desde guilds.<id>.users en todos los mensajes).

Google Chat

{
  channels: {
    googlechat: {
      enabled: true,
      serviceAccountFile: "/path/to/service-account.json",
      audienceType: "app-url", // app-url | project-number
      audience: "https://gateway.example.com/googlechat",
      webhookPath: "/googlechat",
      botUser: "users/1234567890",
      dm: {
        enabled: true,
        policy: "pairing",
        allowFrom: ["users/1234567890"],
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• JSON de cuenta de servicio: en línea (serviceAccount) o basado en archivo (serviceAccountFile).
• También se admite SecretRef de cuenta de servicio (serviceAccountRef).
• Respaldos de variables de entorno: GOOGLE_CHAT_SERVICE_ACCOUNT o GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Usa spaces/<spaceId> o users/<userId> para los objetivos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching vuelve a habilitar la coincidencia por principal de email mutable (modo de compatibilidad de emergencia).

Slack

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dmPolicy: "pairing",
      allowFrom: ["U123", "U456", "*"],
      dm: { enabled: true, groupEnabled: false, groupChannels: ["G123"] },
      channels: {
        C123: { allow: true, requireMention: true, allowBots: false },
        "#general": {
          allow: true,
          requireMention: true,
          allowBots: false,
          users: ["U123"],
          skills: ["docs"],
          systemPrompt: "Short answers only.",
        },
      },
      historyLimit: 50,
      allowBots: false,
      reactionNotifications: "own",
      reactionAllowlist: ["U123"],
      replyToMode: "off", // off | first | all
      thread: {
        historyScope: "thread", // thread | channel
        inheritParent: false,
      },
      actions: {
        reactions: true,
        messages: true,
        pins: true,
        memberInfo: true,
        emojiList: true,
      },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
      typingReaction: "hourglass_flowing_sand",
      textChunkLimit: 4000,
      chunkMode: "length",
      streaming: "partial", // off | partial | block | progress (preview mode)
      nativeStreaming: true, // use Slack native streaming API when streaming=partial
      mediaMaxMb: 20,
    },
  },
}

• Socket mode requiere tanto botToken como appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN como respaldo de entorno para la cuenta predeterminada).
• HTTP mode requiere botToken más signingSecret (en la raíz o por cuenta).
• configWrites: false bloquea las escrituras de configuración iniciadas desde Slack.
• El campo opcional channels.slack.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• channels.slack.streaming es la clave canónica del modo de stream. Los valores legacy streamMode y booleanos streaming se migran automáticamente.
• Usa user:<id> (DM) o channel:<id> para los objetivos de entrega.

Modos de notificación de reacciones: off, own (por defecto), all, allowlist (desde reactionAllowlist).

Aislamiento de sesión en hilos: thread.historyScope es por hilo (por defecto) o compartido en todo el canal. thread.inheritParent copia el historial del canal padre a los nuevos hilos.

• typingReaction añade una reacción temporal al mensaje entrante de Slack mientras se ejecuta una respuesta, y la elimina al finalizar. Usa un shortcode de emoji de Slack como "hourglass_flowing_sand".

Grupo de acción	Por defecto	Notas
reactions	habilitado	Reaccionar + listar reacciones
messages	habilitado	Leer/enviar/editar/borrar
pins	habilitado	Fijar/desfijar/listar
memberInfo	habilitado	Información de miembros
emojiList	habilitado	Lista de emojis personalizados

Mattermost

Mattermost se distribuye como un plugin: openclaw plugins install @openclaw/mattermost.

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      commands: {
        native: true, // opt-in
        nativeSkills: true,
        callbackPath: "/api/channels/mattermost/command",
        // Optional explicit URL for reverse-proxy/public deployments
        callbackUrl: "https://gateway.example.com/api/channels/mattermost/command",
      },
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

Modos de chat: oncall (responde al mencionar con @, por defecto), onmessage (cada mensaje), onchar (mensajes que comienzan con un prefijo activador).

Cuando los comandos nativos de Mattermost están habilitados:

• commands.callbackPath debe ser una ruta (por ejemplo /api/channels/mattermost/command), no una URL completa.
• commands.callbackUrl debe resolver al endpoint del gateway de OpenClaw y ser accesible desde el servidor de Mattermost.
• Para hosts de callback privados/tailnet/internos, Mattermost puede requerir que ServiceSettings.AllowedUntrustedInternalConnections incluya el host/dominio del callback. Usa valores de host/dominio, no URLs completas.
• channels.mattermost.configWrites: permite o deniega escrituras de configuración iniciadas desde Mattermost.
• channels.mattermost.requireMention: requiere @mención antes de responder en los canales.
• El campo opcional channels.mattermost.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.

Signal

{
  channels: {
    signal: {
      enabled: true,
      account: "+15555550123", // optional account binding
      dmPolicy: "pairing",
      allowFrom: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      configWrites: true,
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50,
    },
  },
}

Modos de notificación de reacciones: off, own (por defecto), all, allowlist (desde reactionAllowlist).

• channels.signal.account: fija el inicio del canal a una identidad de cuenta de Signal específica.
• channels.signal.configWrites: permite o deniega escrituras de configuración iniciadas desde Signal.
• El campo opcional channels.signal.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.

BlueBubbles

BlueBubbles es la vía recomendada para iMessage (basada en plugin, configurada bajo channels.bluebubbles).

{
  channels: {
    bluebubbles: {
      enabled: true,
      dmPolicy: "pairing",
      // serverUrl, password, webhookPath, group controls, and advanced actions:
      // see /channels/bluebubbles
    },
  },
}

• Rutas de claves principales cubiertas aquí: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• El campo opcional channels.bluebubbles.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• La configuración completa del canal BlueBubbles está documentada en BlueBubbles.

iMessage

OpenClaw lanza imsg rpc (JSON-RPC sobre stdio). No requiere daemon ni puerto.

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host",
      dmPolicy: "pairing",
      allowFrom: ["+15555550123", "user@example.com", "chat_id:123"],
      historyLimit: 50,
      includeAttachments: false,
      attachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      remoteAttachmentRoots: ["/Users/*/Library/Messages/Attachments"],
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• El campo opcional channels.imessage.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.

• Requiere Full Disk Access a la base de datos de Messages.

• Es preferible usar objetivos chat_id:<id>. Usa imsg chats --limit 20 para listar los chats.

• cliPath puede apuntar a un wrapper de SSH; establece remoteHost (host o user@host) para la obtención de adjuntos mediante SCP.

• attachmentRoots y remoteAttachmentRoots restringen las rutas de adjuntos entrantes (por defecto: /Users/*/Library/Messages/Attachments).

• SCP usa una verificación estricta de la clave del host, así que asegúrate de que la clave del host de retransmisión ya exista en ~/.ssh/known_hosts.

• channels.imessage.configWrites: permite o deniega escrituras de configuración iniciadas desde iMessage.

iMessage SSH wrapper example

#!/usr/bin/env bash
exec ssh -T gateway-host imsg "$@"

Microsoft Teams

Microsoft Teams se basa en una extensión y se configura bajo channels.msteams.

{
  channels: {
    msteams: {
      enabled: true,
      configWrites: true,
      // appId, appPassword, tenantId, webhook, team/channel policies:
      // see /channels/msteams
    },
  },
}

• Rutas de claves principales cubiertas aquí: channels.msteams, channels.msteams.configWrites.
• La configuración completa de Teams (credenciales, webhook, política de DM/grupo, sobrescrituras por equipo/canal) está documentada en Microsoft Teams.

IRC

IRC se basa en una extensión y se configura bajo channels.irc.

{
  channels: {
    irc: {
      enabled: true,
      dmPolicy: "pairing",
      configWrites: true,
      nickserv: {
        enabled: true,
        service: "NickServ",
        password: "${IRC_NICKSERV_PASSWORD}",
        register: false,
        registerEmail: "bot@example.com",
      },
    },
  },
}

• Rutas de claves principales cubiertas aquí: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• El campo opcional channels.irc.defaultAccount sobrescribe la selección de cuenta predeterminada cuando coincide con un ID de cuenta configurado.
• La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/filtro de mención) está documentada en IRC.

Multi-account (todos los canales)

Ejecuta múltiples cuentas por canal (cada una con su propio accountId):

{
  channels: {
    telegram: {
      accounts: {
        default: {
          name: "Primary bot",
          botToken: "123456:ABC...",
        },
        alerts: {
          name: "Alerts bot",
          botToken: "987654:XYZ...",
        },
      },
    },
  },
}

• default se usa cuando se omite accountId (CLI + enrutamiento).
• Los tokens de entorno solo se aplican a la cuenta predeterminada.
• Los ajustes base del canal se aplican a todas las cuentas a menos que se sobrescriban por cuenta.
• Usa bindings[].match.accountId para enrutar cada cuenta a un agent diferente.
• Si añades una cuenta no predeterminada mediante openclaw channels add (o el onboarding del canal) mientras aún tienes una configuración de canal de nivel superior de una sola cuenta, OpenClaw mueve primero los valores de nivel superior con alcance de cuenta a channels.<channel>.accounts.default para que la cuenta original siga funcionando.
• Las vinculaciones existentes solo de canal (sin accountId) siguen coincidiendo con la cuenta predeterminada; las vinculaciones con alcance de cuenta siguen siendo opcionales.
• openclaw doctor --fix también repara estructuras mixtas moviendo los valores de nivel superior de una sola cuenta a accounts.default cuando existen cuentas con nombre pero falta default.

Otros canales de extensión

Muchos canales de extensión se configuran como channels.<id> y están documentados en sus páginas dedicadas (por ejemplo Feishu, Matrix, LINE, Nostr, Zalo, Nextcloud Talk, Synology Chat y Twitch). Consulta el índice completo de canales: Channels.

Filtro de mención en chats de grupo

Los mensajes de grupo requieren por defecto mención obligatoria (mención de metadatos o patrones regex). Se aplica a chats de grupo de WhatsApp, Telegram, Discord, Google Chat e iMessage.

Tipos de mención:

• Menciones de metadatos: Menciones nativas de la plataforma con @. Se ignoran en el modo self-chat de WhatsApp.
• Patrones de texto: Patrones regex en agents.list[].groupChat.mentionPatterns. Se comprueban siempre.
• El filtro de mención se aplica solo cuando la detección es posible (menciones nativas o al menos un patrón).

{
  messages: {
    groupChat: { historyLimit: 50 },
  },
  agents: {
    list: [{ id: "main", groupChat: { mentionPatterns: ["@openclaw", "openclaw"] } }],
  },
}

messages.groupChat.historyLimit establece el valor predeterminado global. Los canales pueden sobrescribirlo con channels.<channel>.historyLimit (o por cuenta). Establece 0 para desactivarlo.

Límites de historial de DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30,
      dms: {
        "123456789": { historyLimit: 50 },
      },
    },
  },
}

Resolución: sobrescritura por DM → valor predeterminado del provider → sin límite (se conserva todo).

Soportado en: telegram, whatsapp, discord, slack, signal, imessage, msteams.

Modo Self-chat

Incluye tu propio número en allowFrom para habilitar el modo self-chat (ignora menciones nativas con @, solo responde a patrones de texto):

{
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["reisponde", "@openclaw"] },
      },
    ],
  },
}

Commands (gestión de comandos de chat)

{
  commands: {
    native: "auto", // register native commands when supported
    text: true, // parse /commands in chat messages
    bash: false, // allow ! (alias: /bash)
    bashForegroundMs: 2000,
    config: false, // allow /config
    debug: false, // allow /debug
    restart: false, // allow /restart + gateway restart tool
    allowFrom: {
      "*": ["user1"],
      discord: ["user:123"],
    },
    useAccessGroups: true,
  },
}

Command details

• Los comandos de texto deben ser mensajes independientes que comiencen con /.
• native: "auto" activa los comandos nativos para Discord/Telegram y los deja desactivados para Slack.
• Sobrescritura por canal: channels.discord.commands.native (booleano o "auto"). false borra los comandos registrados previamente.
• channels.telegram.customCommands añade entradas extra al menú del bot de Telegram.
• bash: true habilita ! <cmd> para la shell del host. Requiere tools.elevated.enabled y que el remitente esté en tools.elevated.allowFrom.<channel>.
• config: true habilita /config (lee/escribe openclaw.json). Para clientes chat.send del gateway, las escrituras persistentes de /config set|unset también requieren operator.admin; el comando de solo lectura /config show sigue disponible para clientes operadores normales con permiso de escritura.
• channels.<provider>.configWrites filtra las mutaciones de configuración por canal (por defecto: true).
• Para canales multi-account, channels.<provider>.accounts.<id>.configWrites también filtra las escrituras dirigidas a esa cuenta (por ejemplo /allowlist --config --account <id> o /config set channels.<provider>.accounts.<id>...).
• allowFrom es por provider. Cuando se establece, es la única fuente de autorización (se ignoran las listas de permitidos/vinculación del canal y useAccessGroups).
• useAccessGroups: false permite que los comandos omitan las políticas de grupos de acceso cuando allowFrom no está configurado.

---

Valores predeterminados del Agent

agents.defaults.workspace

Por defecto: ~/.openclaw/workspace.

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
}

agents.defaults.repoRoot

Raíz del repositorio opcional que se muestra en la línea Runtime del system prompt. Si no se establece, OpenClaw la detecta automáticamente subiendo desde el workspace.

{
  agents: { defaults: { repoRoot: "~/Projects/openclaw" } },
}

agents.defaults.skipBootstrap

Desactiva la creación automática de archivos de bootstrap del workspace (AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md, HEARTBEAT.md, BOOTSTRAP.md).

{
  agents: { defaults: { skipBootstrap: true } },
}

agents.defaults.bootstrapMaxChars

Máximo de caracteres por archivo de bootstrap del workspace antes de truncar. Por defecto: 20000.

{
  agents: { defaults: { bootstrapMaxChars: 20000 } },
}

agents.defaults.bootstrapTotalMaxChars

Máximo total de caracteres inyectados a través de todos los archivos de bootstrap del workspace. Por defecto: 150000.

{
  agents: { defaults: { bootstrapTotalMaxChars: 150000 } },
}

agents.defaults.bootstrapPromptTruncationWarning

Controla el texto de advertencia visible para el agent cuando el contexto de bootstrap está truncado. Por defecto: "once".

• "off": nunca inyecta texto de advertencia en el system prompt.
• "once": inyecta la advertencia una vez por cada firma de truncamiento única (recomendado).
• "always": inyecta la advertencia en cada ejecución cuando existe truncamiento.

{
  agents: { defaults: { bootstrapPromptTruncationWarning: "once" } }, // off | once | always
}

agents.defaults.imageMaxDimensionPx

Tamaño máximo en píxeles para el lado más largo de la imagen en los bloques de imagen de herramientas/transcripción antes de las llamadas al provider. Por defecto: 1200.

Valores más bajos suelen reducir el uso de vision-tokens y el tamaño del payload de la solicitud para ejecuciones con muchas capturas de pantalla. Valores más altos preservan más detalle visual.

{
  agents: { defaults: { imageMaxDimensionPx: 1200 } },
}

agents.defaults.userTimezone

Zona horaria para el contexto del system prompt (no para los timestamps de los mensajes). Recurre a la zona horaria del host.

{
  agents: { defaults: { userTimezone: "America/Chicago" } },
}

agents.defaults.timeFormat

Formato de hora en el system prompt. Por defecto: auto (preferencia del SO).

{
  agents: { defaults: { timeFormat: "auto" } }, // auto | 12 | 24
}

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.5": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.5"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5-mini"],
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • El formato de cadena establece solo el modelo primario.
  • El formato de objeto establece el primario más los modelos de failover ordenados.
• imageModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Usado por la ruta de la herramienta image como su configuración de vision-model.
  • También se usa como enrutamiento de respaldo cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen.
• pdfModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Usado por la herramienta pdf para el enrutamiento del modelo.
  • Si se omite, la herramienta PDF recurre a imageModel, y luego a los valores predeterminados del provider.
• pdfMaxBytesMb: límite de tamaño de PDF por defecto para la herramienta pdf cuando no se pasa maxBytesMb en la llamada.
• pdfMaxPages: máximo de páginas por defecto consideradas por el modo de respaldo de extracción en la herramienta pdf.
• model.primary: formato provider/model (ej. anthropic/claude-opus-4-6). Si omites el provider, OpenClaw asume anthropic (deprecated).
• models: el catálogo de modelos configurado y la lista de permitidos para /model. Cada entrada puede incluir alias (acceso rápido) y params (específicos del provider, por ejemplo temperature, maxTokens, cacheRetention, context1m).
• Precedencia de fusión de params (configuración): agents.defaults.models["provider/model"].params es la base, luego agents.list[].params (que coincida con el ID del agent) sobrescribe por clave.
• Los escritores de configuración que mutan estos campos (por ejemplo comandos /models set, /models set-image y comandos de añadir/quitar fallbacks) guardan el formato de objeto canónico y preservan las listas de fallbacks existentes cuando es posible.
• maxConcurrent: máximo de ejecuciones de agents en paralelo a través de las sesiones (cada sesión sigue serializada). Por defecto: 1.

Alias abreviados integrados (solo se aplican cuando el modelo está en agents.defaults.models):

Alias	Modelo
opus	anthropic/claude-opus-4-6
sonnet	anthropic/claude-sonnet-4-6
gpt	openai/gpt-5.4
gpt-mini	openai/gpt-5-mini
gemini	google/gemini-3.1-pro-preview
gemini-flash	google/gemini-3-flash-preview
gemini-flash-lite	google/gemini-3.1-flash-lite-preview

Tus alias configurados siempre tienen prioridad sobre los predeterminados.

Los modelos Z.AI GLM-4.x activan automáticamente el modo thinking a menos que establezcas --thinking off o definas agents.defaults.models["zai/<model>"].params.thinking tú mismo. Los modelos Z.AI habilitan tool_stream por defecto para el streaming de llamadas a herramientas. Establece agents.defaults.models["zai/<model>"].params.tool_stream a false para desactivarlo. Los modelos Anthropic Claude 4.6 usan por defecto el modo thinking adaptive cuando no se establece un nivel explícito.

agents.defaults.cliBackends

Backends de CLI opcionales para ejecuciones de respaldo solo de texto (sin llamadas a herramientas). Útiles como respaldo cuando fallan los providers de API.

{
  agents: {
    defaults: {
      cliBackends: {
        "claude-cli": {
          command: "/opt/homebrew/bin/claude",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Los backends de CLI son prioritarios para texto; las herramientas siempre están desactivadas.
• Sesiones admitidas cuando se establece sessionArg.
• Paso de imágenes admitido cuando imageArg acepta rutas de archivos.

agents.defaults.heartbeat

Ejecuciones periódicas de heartbeat.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.2-mini",
        includeReasoning: false,
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Read HEARTBEAT.md if it exists...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
      },
    },
  },
}

• every: cadena de duración (ms/s/m/h). Por defecto: 30m.
• suppressToolErrorWarnings: si es true, suprime los payloads de advertencia de error de herramientas durante las ejecuciones de heartbeat.
• directPolicy: política de entrega directa/DM. allow (por defecto) permite la entrega al objetivo directo. block suprime la entrega al objetivo directo y emite reason=dm-blocked.
• lightContext: si es true, las ejecuciones de heartbeat usan un contexto de bootstrap ligero y conservan solo HEARTBEAT.md de los archivos de bootstrap del workspace.
• Por agent: establece agents.list[].heartbeat. Cuando cualquier agent define heartbeat, solo esos agents ejecutan heartbeats.
• Los heartbeats ejecutan turnos completos de agent; los intervalos más cortos consumen más tokens.

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-5", // optional compaction-only model override
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default o safeguard (resumen por fragmentos para historiales largos). Consulta Compaction.
• identifierPolicy: strict (por defecto), off o custom. strict antepone una guía integrada para la retención de identificadores opacos durante el resumen de compactación.
• identifierInstructions: texto personalizado opcional para la preservación de identificadores usado cuando identifierPolicy=custom.
• postCompactionSections: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar tras la compactación. Por defecto es ["Session Startup", "Red Lines"]; establece [] para desactivar la reinyección. Cuando no se establece o se establece explícitamente a ese par predeterminado, también se aceptan los encabezados antiguos Every Session/Safety como respaldo legacy.
• model: sobrescritura opcional de provider/model-id solo para el resumen de compactación. Úsalo cuando la sesión principal deba mantener un modelo pero los resúmenes de compactación deban ejecutarse en otro; si no se establece, la compactación usa el modelo primario de la sesión.
• memoryFlush: turno agéntico silencioso antes de la auto-compactación para almacenar memorias duraderas. Se omite cuando el workspace es de solo lectura.

agents.defaults.contextPruning

Elimina resultados de herramientas antiguos del contexto en memoria antes de enviarlo al LLM. No modifica el historial de la sesión en el disco.

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duration (ms/s/m/h), default unit: minutes
        keepLastAssistants: 3,
        softTrimRatio: 0.3,
        hardClearRatio: 0.5,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" },
        tools: { deny: ["browser", "canvas"] },
      },
    },
  },
}

cache-ttl mode behavior

• mode: "cache-ttl" habilita las pasadas de limpieza.
• ttl controla cada cuánto puede ejecutarse la limpieza de nuevo (tras el último toque de caché).
• La limpieza primero recorta suavemente (soft-trim) los resultados de herramientas excesivamente grandes, y luego borra por completo (hard-clear) los resultados más antiguos si es necesario.

Soft-trim conserva el inicio + el final e inserta ... en el medio.

Hard-clear reemplaza todo el resultado de la herramienta con el marcador de posición.

Notas:

• Los bloques de imagen nunca se recortan ni se borran.
• Los ratios se basan en caracteres (aproximado), no en recuentos exactos de tokens.
• Si existen menos de keepLastAssistants mensajes del asistente, se omite la limpieza.

Consulta Session Pruning para detalles sobre el comportamiento.

Block streaming

{
  agents: {
    defaults: {
      blockStreamingDefault: "off", // on | off
      blockStreamingBreak: "text_end", // text_end | message_end
      blockStreamingChunk: { minChars: 800, maxChars: 1200 },
      blockStreamingCoalesce: { idleMs: 1000 },
      humanDelay: { mode: "natural" }, // off | natural | custom (use minMs/maxMs)
    },
  },
}

• Los canales que no son Telegram requieren *.blockStreaming: true explícito para habilitar respuestas por bloques.
• Sobrescrituras de canal: channels.<channel>.blockStreamingCoalesce (y variantes por cuenta). Signal/Slack/Discord/Google Chat tienen por defecto minChars: 1500.
• humanDelay: pausa aleatoria entre respuestas por bloques. natural = 800–2500ms. Sobrescritura por agent: agents.list[].humanDelay.

Consulta Streaming para detalles sobre comportamiento y fragmentación.

Typing indicators

{
  agents: {
    defaults: {
      typingMode: "instant", // never | instant | thinking | message
      typingIntervalSeconds: 6,
    },
  },
}

• Valores por defecto: instant para chats directos/menciones, message para chats de grupo sin mención.
• Sobrescrituras por sesión: session.typingMode, session.typingIntervalSeconds.

Consulta Typing Indicators.

agents.defaults.sandbox

Sandboxing con Docker opcional para el agent embebido. Consulta Sandboxing para la guía completa.

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        browser: {
          enabled: false,
          image: "openclaw-sandbox-browser:bookworm-slim",
          network: "openclaw-sandbox-browser",
          cdpPort: 9222,
          cdpSourceRange: "172.21.0.1/32",
          vncPort: 5900,
          noVncPort: 6080,
          headless: false,
          enableNoVnc: true,
          allowHostControl: false,
          autoStart: true,
          autoStartTimeoutMs: 12000,
        },
        prune: {
          idleHours: 24,
          maxAgeDays: 7,
        },
      },
    },
  },
  tools: {
    sandbox: {
      tools: {
        allow: [
          "exec",
          "process",
          "read",
          "write",
          "edit",
          "apply_patch",
          "sessions_list",
          "sessions_history",
          "sessions_send",
          "sessions_spawn",
          "session_status",
        ],
        deny: ["browser", "canvas", "nodes", "cron", "discord", "gateway"],
      },
    },
  },
}

Sandbox details

Acceso al workspace:

• none: workspace de sandbox por alcance bajo ~/.openclaw/sandboxes
• ro: workspace de sandbox en /workspace, workspace del agent montado como solo lectura en /agent
• rw: workspace del agent montado como lectura/escritura en /workspace

Alcance (Scope):

• session: contenedor y workspace por sesión
• agent: un contenedor y workspace por agent (por defecto)
• shared: contenedor y workspace compartidos (sin aislamiento entre sesiones)

setupCommand se ejecuta una vez tras la creación del contenedor (vía sh -lc). Requiere salida a red, raíz escribible y usuario root.

Los contenedores usan por defecto network: "none" — establécelo a "bridge" (o una red bridge personalizada) si el agent necesita acceso de salida. "host" está bloqueado. "container:<id>" está bloqueado por defecto a menos que establezcas explícitamente sandbox.docker.dangerouslyAllowContainerNamespaceJoin: true (emergencia).

Los adjuntos entrantes se preparan en media/inbound/* dentro del workspace activo.

docker.binds monta directorios adicionales del host; los montajes globales y por agent se fusionan.

Navegador en sandbox (sandbox.browser.enabled): Chromium + CDP en un contenedor. La URL de noVNC se inyecta en el system prompt. No requiere browser.enabled en openclaw.json. El acceso de observador de noVNC usa autenticación VNC por defecto y OpenClaw emite una URL con token de corta duración (en lugar de exponer la contraseña en la URL compartida).

• allowHostControl: false (por defecto) bloquea que las sesiones en sandbox apunten al navegador del host.
• network tiene por defecto openclaw-sandbox-browser (red bridge dedicada). Establécelo a bridge solo si quieres explícitamente conectividad bridge global.
• cdpSourceRange restringe opcionalmente el ingreso de CDP en el borde del contenedor a un rango CIDR (por ejemplo 172.21.0.1/32).
• sandbox.browser.binds monta directorios adicionales del host solo en el contenedor del navegador en sandbox. Cuando se establece (incluyendo []), reemplaza a docker.binds para el contenedor del navegador.
• Los valores predeterminados de lanzamiento se definen en scripts/sandbox-browser-entrypoint.sh y están ajustados para hosts de contenedores:
  • --remote-debugging-address=127.0.0.1
  • --remote-debugging-port=<derivado de OPENCLAW_BROWSER_CDP_PORT>
  • --user-data-dir=${HOME}/.chrome
  • --no-first-run
  • --no-default-browser-check
  • --disable-3d-apis
  • --disable-gpu
  • --disable-software-rasterizer
  • --disable-dev-shm-usage
  • --disable-background-networking
  • --disable-features=TranslateUI
  • --disable-breakpad
  • --disable-crash-reporter
  • --renderer-process-limit=2
  • --no-zygote
  • --metrics-recording-only
  • --disable-extensions (habilitado por defecto)
  • --disable-3d-apis, --disable-software-rasterizer y --disable-gpu están habilitados por defecto y pueden desactivarse con OPENCLAW_BROWSER_DISABLE_GRAPHICS_FLAGS=0 si el uso de WebGL/3D lo requiere.
  • OPENCLAW_BROWSER_DISABLE_EXTENSIONS=0 vuelve a habilitar las extensiones si tu flujo de trabajo depende de ellas.
  • --renderer-process-limit=2 puede cambiarse con OPENCLAW_BROWSER_RENDERER_PROCESS_LIMIT=<N>; establece 0 para usar el límite de procesos por defecto de Chromium.
  • más --no-sandbox y --disable-setuid-sandbox cuando noSandbox está habilitado.
  • Los valores predeterminados son la línea base de la imagen del contenedor; usa una imagen de navegador personalizada con un entrypoint personalizado para cambiar los valores predeterminados del contenedor.

Construir imágenes:

scripts/sandbox-setup.sh           # main sandbox image
scripts/sandbox-browser-setup.sh   # optional browser image

agents.list (sobrescrituras por agent)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // or { primary, fallbacks }
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: ID de agent estable (requerido).
• default: cuando se establecen varios, el primero gana (se registra una advertencia). Si no se establece ninguno, la primera entrada de la lista es la predeterminada.
• model: el formato de cadena sobrescribe solo el primary; el formato de objeto { primary, fallbacks } sobrescribe ambos ([] desactiva los fallbacks globales). Los cron jobs que solo sobrescriben primary siguen heredando los fallbacks predeterminados a menos que establezcas fallbacks: [].
• params: parámetros de stream por agent fusionados sobre la entrada del modelo seleccionado en agents.defaults.models. Úsalo para sobrescrituras específicas del agent como cacheRetention, temperature o maxTokens sin duplicar todo el catálogo de modelos.
• runtime: descriptor de runtime opcional por agent. Usa type: "acp" con los valores predeterminados de runtime.acp (agent, backend, mode, cwd) cuando el agent deba usar por defecto sesiones de harness ACP.
• identity.avatar: ruta relativa al workspace, URL http(s) o URI data:.
• identity deriva valores predeterminados: ackReaction desde emoji, mentionPatterns desde name/emoji.
• subagents.allowAgents: lista de IDs de agents permitidos para sessions_spawn (["*"] = cualquiera; por defecto: solo el mismo agent).
• Protección de herencia de sandbox: si la sesión solicitante está en sandbox, sessions_spawn rechaza objetivos que se ejecutarían fuera de sandbox.

---

Enrutamiento multi-agent

Ejecuta múltiples agents aislados dentro de un mismo Gateway. Consulta Multi-Agent.

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

Prefijo de respuesta

Puedes usar sobrescrituras por canal o cuenta: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

La resolución (gana la más específica) es: cuenta → canal → global. "" desactiva y detiene la cascada. "auto" deriva de [{identity.name}].

Variables de plantilla:

Variable	Descripción	Ejemplo
{model}	Nombre corto del modelo	claude-opus-4-6
{modelFull}	Identificador completo	anthropic/claude-opus-4-6
{provider}	Nombre del proveedor	anthropic
{thinkingLevel}	Nivel de pensamiento	high, low, off
{identity.name}	Nombre del agente	(igual que "auto")

Las variables no distinguen entre mayúsculas y minúsculas. {think} funciona como alias de {thinkingLevel}.

Reacción de confirmación (Ack)

• Por defecto usa el identity.emoji del agente activo, si no, usa "👀". Configura "" para desactivarlo.
• Sobrescrituras por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Orden de resolución: cuenta → canal → messages.ackReaction → fallback de identidad.
• Alcance (Scope): group-mentions (por defecto), group-all, direct, all.
• removeAckAfterReply: elimina la reacción tras responder (solo en Slack/Discord/Telegram/Google Chat).

Debounce de entrada

Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los archivos multimedia y adjuntos se envían de inmediato. Los comandos de control ignoran el debouncing.

TTS (text-to-speech)

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all
      provider: "elevenlabs",
      summaryModel: "openai/gpt-4.1-mini",
      modelOverrides: { enabled: true },
      maxTextLength: 4000,
      timeoutMs: 30000,
      prefsPath: "~/.openclaw/settings/tts.json",
      elevenlabs: {
        apiKey: "elevenlabs_api_key",
        baseUrl: "https://api.elevenlabs.io",
        voiceId: "voice_id",
        modelId: "eleven_multilingual_v2",
        seed: 42,
        applyTextNormalization: "auto",
        languageCode: "en",
        voiceSettings: {
          stability: 0.5,
          similarityBoost: 0.75,
          style: 0.0,
          useSpeakerBoost: true,
          speed: 1.0,
        },
      },
      openai: {
        apiKey: "openai_api_key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• auto controla el TTS automático. /tts off|always|inbound|tagged lo sobrescribe por sesión.
• summaryModel sobrescribe agents.defaults.model.primary para el resumen automático.
• modelOverrides está activado por defecto; modelOverrides.allowProvider está desactivado por defecto.
• Las API keys usan como fallback ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY.
• openai.baseUrl sobrescribe el endpoint de OpenAI TTS. El orden de resolución es la configuración, luego OPENAI_TTS_BASE_URL y finalmente https://api.openai.com/v1.
• Si openai.baseUrl apunta a un endpoint que no es de OpenAI, OpenClaw lo trata como un servidor TTS compatible con OpenAI y relaja la validación de modelos y voces.

---

Talk

Valores por defecto para el modo Talk (macOS/iOS/Android).

{
  talk: {
    voiceId: "elevenlabs_voice_id",
    voiceAliases: {
      Clawd: "EXAVITQu4vr4xnSDxMaL",
      Roger: "CwhRBWXzGAHq8TQ4Fs17",
    },
    modelId: "eleven_v3",
    outputFormat: "mp3_44100_128",
    apiKey: "elevenlabs_api_key",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
  },
}

• Los IDs de voz usan como fallback ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
• apiKey y providers.*.apiKey aceptan strings de texto plano u objetos SecretRef.
• El fallback ELEVENLABS_API_KEY solo se aplica si no hay una API key de Talk configurada.
• voiceAliases permite que las directivas de Talk usen nombres amigables.
• silenceTimeoutMs controla cuánto espera el modo Talk tras el silencio del usuario antes de enviar la transcripción. Si no se configura, usa el valor por defecto de la plataforma (700 ms en macOS y Android, 900 ms en iOS).

---

Herramientas

Perfiles de herramientas

tools.profile establece una lista de permitidos base antes de tools.allow/tools.deny:

El proceso de onboarding local asigna tools.profile: "coding" a las nuevas configuraciones locales si no está definido (se mantienen los perfiles explícitos existentes).

Perfil	Incluye
minimal	solo session_status
coding	group:fs, group:runtime, group:sessions, group:memory, image
messaging	group:messaging, sessions_list, sessions_history, sessions_send, session_status
full	Sin restricciones (igual que si no se define)

Grupos de herramientas

Grupo	Herramientas
group:runtime	exec, process (bash se acepta como alias de exec)
group:fs	read, write, edit, apply_patch
group:sessions	sessions_list, sessions_history, sessions_send, sessions_spawn, session_status
group:memory	memory_search, memory_get
group:web	web_search, web_fetch
group:ui	browser, canvas
group:automation	cron, gateway
group:messaging	message
group:nodes	nodes
group:openclaw	Todas las herramientas integradas (excluye plugins de proveedores)

tools.allow / tools.deny

Política global de permitir/denegar herramientas (denegar tiene prioridad). No distingue mayúsculas y admite comodines *. Se aplica incluso si el sandbox de Docker está apagado.

{
  tools: { deny: ["browser", "canvas"] },
}

tools.byProvider

Restringe herramientas para proveedores o modelos específicos. Orden: perfil base → perfil del proveedor → permitir/denegar.

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

tools.elevated

Controla el acceso de ejecución elevado (en el host):

{
  tools: {
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        discord: ["1234567890123", "987654321098765432"],
      },
    },
  },
}

• La sobrescritura por agente (agents.list[].tools.elevated) solo puede restringir más.
• /elevated on|off|ask|full guarda el estado por sesión; las directivas inline se aplican a un solo mensaje.
• El exec elevado se ejecuta en el host, saltándose el sandboxing.

tools.exec

{
  tools: {
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
      notifyOnExit: true,
      notifyOnExitEmptySuccess: false,
      applyPatch: {
        enabled: false,
        allowModels: ["gpt-5.2"],
      },
    },
  },
}

tools.loopDetection

Las comprobaciones de seguridad para bucles de herramientas están desactivadas por defecto. Configura enabled: true para activarlas. Los ajustes pueden definirse globalmente en tools.loopDetection y sobrescribirse por agente en agents.list[].tools.loopDetection.

{
  tools: {
    loopDetection: {
      enabled: true,
      historySize: 30,
      warningThreshold: 10,
      criticalThreshold: 20,
      globalCircuitBreakerThreshold: 30,
      detectors: {
        genericRepeat: true,
        knownPollNoProgress: true,
        pingPong: true,
      },
    },
  },
}

• historySize: historial máximo de llamadas a herramientas para analizar bucles.
• warningThreshold: umbral de patrones repetitivos sin progreso para avisos.
• criticalThreshold: umbral más alto para bloquear bucles críticos.
• globalCircuitBreakerThreshold: umbral de parada total para cualquier ejecución sin progreso.
• detectors.genericRepeat: avisa sobre llamadas repetidas a la misma herramienta con los mismos argumentos.
• detectors.knownPollNoProgress: avisa o bloquea herramientas de sondeo conocidas (process.poll, command_status, etc.).
• detectors.pingPong: avisa o bloquea patrones de pares alternos sin progreso.
• Si warningThreshold >= criticalThreshold o criticalThreshold >= globalCircuitBreakerThreshold, la validación falla.

tools.web

{
  tools: {
    web: {
      search: {
        enabled: true,
        apiKey: "brave_api_key", // or BRAVE_API_KEY env
        maxResults: 5,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
      },
      fetch: {
        enabled: true,
        maxChars: 50000,
        maxCharsCap: 50000,
        timeoutSeconds: 30,
        cacheTtlMinutes: 15,
        userAgent: "custom-ua",
      },
    },
  },
}

tools.media

Configura la comprensión de medios entrantes (imagen/audio/video):

{
  tools: {
    media: {
      concurrency: 2,
      audio: {
        enabled: true,
        maxBytes: 20971520,
        scope: {
          default: "deny",
          rules: [{ action: "allow", match: { chatType: "direct" } }],
        },
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] },
        ],
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },
}

Campos de entrada para modelos de medios

Entrada de proveedor (type: "provider" u omitido):

• provider: ID del proveedor de la API (openai, anthropic, google/gemini, groq, etc.)
• model: sobrescritura del ID del modelo
• profile / preferredProfile: selección de perfil en auth-profiles.json

Entrada CLI (type: "cli"):

• command: ejecutable a correr
• args: argumentos con plantilla (admite {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc.)

Campos comunes:

• capabilities: lista opcional (image, audio, video). Por defecto: openai/anthropic/minimax → image, google → image+audio+video, groq → audio.
• prompt, maxChars, maxBytes, timeoutSeconds, language: sobrescrituras por entrada.
• Si hay un fallo, se pasa a la siguiente entrada.

La autenticación del proveedor sigue el orden estándar: auth-profiles.json → variables de entorno → models.providers.*.apiKey.

tools.agentToAgent

{
  tools: {
    agentToAgent: {
      enabled: false,
      allow: ["home", "work"],
    },
  },
}

tools.sessions

Controla qué sesiones pueden ser objetivo de las herramientas de sesión (sessions_list, sessions_history, sessions_send).

Por defecto: tree (sesión actual + sesiones generadas por ella, como subagentes).

{
  tools: {
    sessions: {
      // "self" | "tree" | "agent" | "all"
      visibility: "tree",
    },
  },
}

Notas:

• self: solo la clave de la sesión actual.
• tree: sesión actual + sesiones generadas por la sesión actual (subagentes).
• agent: cualquier sesión que pertenezca al ID del agente actual.
• all: cualquier sesión. El targeting entre agentes requiere además tools.agentToAgent.
• Restricción de sandbox: si la sesión actual está en un sandbox y agents.defaults.sandbox.sessionToolsVisibility="spawned", la visibilidad se fuerza a tree aunque tools.sessions.visibility="all".

tools.sessions_spawn

Controla el soporte de archivos adjuntos inline para sessions_spawn.

{
  tools: {
    sessions_spawn: {
      attachments: {
        enabled: false, // opt-in: set true to allow inline file attachments
        maxTotalBytes: 5242880, // 5 MB total across all files
        maxFiles: 50,
        maxFileBytes: 1048576, // 1 MB per file
        retainOnSessionKeep: false, // keep attachments when cleanup="keep"
      },
    },
  },
}

Notas:

• Los adjuntos solo funcionan con runtime: "subagent". El runtime ACP los rechaza.
• Los archivos se materializan en el workspace hijo en .openclaw/attachments/<uuid>/ con un .manifest.json.
• El contenido de los adjuntos se oculta automáticamente en la persistencia de la transcripción.
• Las entradas Base64 se validan con comprobaciones estrictas de alfabeto/padding y un guardián de tamaño previo a la decodificación.
• Los permisos de archivos son 0700 para directorios y 0600 para archivos.
• La limpieza sigue la política cleanup: delete siempre borra los adjuntos; keep solo los mantiene si retainOnSessionKeep: true.

tools.subagents

{
  agents: {
    defaults: {
      subagents: {
        model: "minimax/MiniMax-M2.5",
        maxConcurrent: 1,
        runTimeoutSeconds: 900,
        archiveAfterMinutes: 60,
      },
    },
  },
}

• model: modelo por defecto para subagentes generados. Si se omite, heredan el modelo del llamador.
• runTimeoutSeconds: tiempo de espera por defecto (segundos) para sessions_spawn si la llamada a la herramienta lo omite. 0 significa sin límite.
• Política de herramientas por subagente: tools.subagents.tools.allow / tools.subagents.tools.deny.

---

Proveedores personalizados y URLs base

OpenClaw utiliza el catálogo de modelos de pi-coding-agent. Añade proveedores personalizados mediante models.providers en la configuración o en ~/.openclaw/agents/<agentId>/agent/models.json.

{
  models: {
    mode: "merge", // merge (default) | replace
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-completions", // openai-completions | openai-responses | anthropic-messages | google-generative-ai
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },
}

• Usa authHeader: true + headers para necesidades de autenticación personalizadas.
• Sobrescribe la raíz de configuración del agente con OPENCLAW_AGENT_DIR (o PI_CODING_AGENT_DIR).
• Prioridad de fusión para IDs de proveedores coincidentes:
  • Los valores de baseUrl en el models.json del agente tienen prioridad si no están vacíos.
  • Los valores de apiKey del agente ganan solo si el proveedor no está gestionado por SecretRef.
  • Los valores de apiKey gestionados por SecretRef se refrescan desde los marcadores de origen (ENV_VAR_NAME para env, secretref-managed para archivos/ejecución) en lugar de persistir secretos resueltos.
  • Los valores de cabecera gestionados por SecretRef se refrescan desde los marcadores de origen.
  • Si faltan o están vacíos en el agente, se usa models.providers de la configuración.
  • Para contextWindow/maxTokens, se usa el valor más alto entre la configuración explícita y el catálogo implícito.
  • Usa models.mode: "replace" si quieres que la configuración reescriba totalmente models.json.
  • La persistencia de marcadores manda: se escriben desde la configuración de origen activa (antes de resolver), no desde los valores secretos resueltos en ejecución.

Detalles de los campos del proveedor

• models.mode: comportamiento del catálogo de proveedores (merge o replace).
• models.providers: mapa de proveedores personalizados por ID.
• models.providers.*.api: adaptador de peticiones (openai-completions, openai-responses, anthropic-messages, google-generative-ai, etc).
• models.providers.*.apiKey: credencial del proveedor (se recomienda SecretRef o sustitución de entorno).
• models.providers.*.auth: estrategia de autenticación (api-key, token, oauth, aws-sdk).
• models.providers.*.injectNumCtxForOpenAICompat: para Ollama + openai-completions, inyecta options.num_ctx en las peticiones (por defecto: true).
• models.providers.*.authHeader: fuerza el transporte de credenciales en la cabecera Authorization.
• models.providers.*.baseUrl: URL base de la API upstream.
• models.providers.*.headers: cabeceras estáticas extra para routing de proxy o tenant.
• models.providers.*.models: entradas explícitas del catálogo de modelos del proveedor.
• models.providers.*.models.*.compat.supportsDeveloperRole: pista opcional de compatibilidad. Para api: "openai-completions" con un baseUrl no nativo (que no sea api.openai.com), OpenClaw fuerza esto a false en ejecución.
• models.bedrockDiscovery: raíz de ajustes para el auto-descubrimiento de Bedrock.
• models.bedrockDiscovery.enabled: activa o desactiva el sondeo de descubrimiento.
• models.bedrockDiscovery.region: región de AWS para el descubrimiento.
• models.bedrockDiscovery.providerFilter: filtro opcional por ID de proveedor.
• models.bedrockDiscovery.refreshInterval: intervalo de refresco del descubrimiento.
• models.bedrockDiscovery.defaultContextWindow: ventana de contexto de fallback para modelos descubiertos.
• models.bedrockDiscovery.defaultMaxTokens: máximo de tokens de salida de fallback para modelos descubiertos.

Ejemplos de proveedores

Cerebras (GLM 4.6 / 4.7)

{
  env: { CEREBRAS_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: {
        primary: "cerebras/zai-glm-4.7",
        fallbacks: ["cerebras/zai-glm-4.6"],
      },
      models: {
        "cerebras/zai-glm-4.7": { alias: "GLM 4.7 (Cerebras)" },
        "cerebras/zai-glm-4.6": { alias: "GLM 4.6 (Cerebras)" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      cerebras: {
        baseUrl: "https://api.cerebras.ai/v1",
        apiKey: "${CEREBRAS_API_KEY}",
        api: "openai-completions",
        models: [
          { id: "zai-glm-4.7", name: "GLM 4.7 (Cerebras)" },
          { id: "zai-glm-4.6", name: "GLM 4.6 (Cerebras)" },
        ],
      },
    },
  },
}

Usa cerebras/zai-glm-4.7 para Cerebras; zai/glm-4.7 para Z.AI directo.

OpenCode

{
  agents: {
    defaults: {
      model: { primary: "opencode/claude-opus-4-6" },
      models: { "opencode/claude-opus-4-6": { alias: "Opus" } },
    },
  },
}

Configura OPENCODE_API_KEY (o OPENCODE_ZEN_API_KEY). Usa referencias opencode/... para el catálogo Zen o opencode-go/... para el catálogo Go. Atajo: openclaw onboard --auth-choice opencode-zen o openclaw onboard --auth-choice opencode-go.

Z.AI (GLM-4.7)

{
  agents: {
    defaults: {
      model: { primary: "zai/glm-4.7" },
      models: { "zai/glm-4.7": {} },
    },
  },
}

Configura ZAI_API_KEY. Se aceptan los alias z.ai/* y z-ai/*. Atajo: openclaw onboard --auth-choice zai-api-key.

• Endpoint general: https://api.z.ai/api/paas/v4
• Endpoint de coding (por defecto): https://api.z.ai/api/coding/paas/v4
• Para el endpoint general, define un proveedor personalizado con la sobrescritura de la URL base.

Moonshot AI (Kimi)

{
  env: { MOONSHOT_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "moonshot/kimi-k2.5" },
      models: { "moonshot/kimi-k2.5": { alias: "Kimi K2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      moonshot: {
        baseUrl: "https://api.moonshot.ai/v1",
        apiKey: "${MOONSHOT_API_KEY}",
        api: "openai-completions",
        models: [
          {
            id: "kimi-k2.5",
            name: "Kimi K2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 256000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Para el endpoint de China: baseUrl: "https://api.moonshot.cn/v1" o openclaw onboard --auth-choice moonshot-api-key-cn.

Kimi Coding

{
  env: { KIMI_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "kimi-coding/k2p5" },
      models: { "kimi-coding/k2p5": { alias: "Kimi K2.5" } },
    },
  },
}

Proveedor integrado compatible con Anthropic. Atajo: openclaw onboard --auth-choice kimi-code-api-key.

Synthetic (compatible con Anthropic)

{
  env: { SYNTHETIC_API_KEY: "sk-..." },
  agents: {
    defaults: {
      model: { primary: "synthetic/hf:MiniMaxAI/MiniMax-M2.5" },
      models: { "synthetic/hf:MiniMaxAI/MiniMax-M2.5": { alias: "MiniMax M2.5" } },
    },
  },
  models: {
    mode: "merge",
    providers: {
      synthetic: {
        baseUrl: "https://api.synthetic.new/anthropic",
        apiKey: "${SYNTHETIC_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "hf:MiniMaxAI/MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 192000,
            maxTokens: 65536,
          },
        ],
      },
    },
  },
}

La URL base debe omitir /v1 (el cliente de Anthropic lo añade). Atajo: openclaw onboard --auth-choice synthetic-api-key.

MiniMax M2.5 (directo)

{
  agents: {
    defaults: {
      model: { primary: "minimax/MiniMax-M2.5" },
      models: {
        "minimax/MiniMax-M2.5": { alias: "Minimax" },
      },
    },
  },
  models: {
    mode: "merge",
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        apiKey: "${MINIMAX_API_KEY}",
        api: "anthropic-messages",
        models: [
          {
            id: "MiniMax-M2.5",
            name: "MiniMax M2.5",
            reasoning: false,
            input: ["text"],
            cost: { input: 15, output: 60, cacheRead: 2, cacheWrite: 10 },
            contextWindow: 200000,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Configura MINIMAX_API_KEY. Atajo: openclaw onboard --auth-choice minimax-api.

Modelos locales (LM Studio)

Consulta Modelos Locales. En resumen: ejecuta MiniMax M2.5 vía LM Studio Responses API en hardware potente; mantén los modelos en la nube fusionados como fallback.

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn
    },
    entries: {
      "nano-banana-pro": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: lista blanca opcional solo para skills empaquetadas (las skills de workspace o gestionadas no se ven afectadas).
• entries.<skillKey>.enabled: false: desactiva una skill aunque esté empaquetada o instalada.
• entries.<skillKey>.apiKey: una forma cómoda de configurar skills que declaran una variable de entorno principal (puedes usar un string de texto plano o un objeto SecretRef).

---

Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-extension"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Se cargan desde ~/.openclaw/extensions, <workspace>/.openclaw/extensions y las rutas definidas en plugins.load.paths.
• Si haces cambios en la configuración, tendrás que reiniciar el Gateway.
• allow: lista blanca opcional (solo se cargarán los plugins que listes aquí). Si un plugin está en deny, esa regla tiene prioridad.
• plugins.entries.<id>.apiKey: campo de conveniencia para la API key a nivel de plugin (siempre que el plugin lo soporte).
• plugins.entries.<id>.env: mapa de variables de entorno con alcance específico para el plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: si lo pones en false, el núcleo bloquea before_prompt_build e ignora los campos que modifican el prompt del antiguo before_agent_start, aunque mantiene los valores heredados de modelOverride y providerOverride.
• plugins.entries.<id>.config: objeto de configuración definido por el plugin (se valida con el esquema del propio plugin).
• plugins.slots.memory: elige el ID del plugin de memoria activo, o usa "none" si prefieres desactivar los plugins de memoria.
• plugins.slots.contextEngine: elige el ID del plugin de motor de contexto activo; por defecto usa "legacy" a menos que instales y selecciones otro motor.
• plugins.installs: metadatos de instalación gestionados por la CLI que utiliza el comando openclaw plugins update.
  • Incluye campos como source, spec, sourcePath, installPath, version, resolvedName, resolvedVersion, resolvedSpec, integrity, shasum, resolvedAt e installedAt.
  • Te recomiendo tratar plugins.installs.* como un estado gestionado; usa los comandos de la CLI en lugar de editarlo a mano.

Echa un vistazo a Plugins.

---

Navegador

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "chrome",
    ssrfPolicy: {
      dangerouslyAllowPrivateNetwork: true, // default trusted-network mode
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: { cdpPort: 18801, color: "#0066CC" },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // relayBindHost: "0.0.0.0", // only when the extension relay must be reachable across namespaces (for example WSL2)
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false: desactiva las funciones act:evaluate y wait --fn.
• ssrfPolicy.dangerouslyAllowPrivateNetwork: por defecto es true si no se especifica (modelo de red de confianza).
• Configura ssrfPolicy.dangerouslyAllowPrivateNetwork: false si necesitas una navegación estricta solo por la red pública.
• ssrfPolicy.allowPrivateNetwork: se mantiene como un alias heredado por compatibilidad.
• En el modo estricto, puedes usar ssrfPolicy.hostnameAllowlist y ssrfPolicy.allowedHostnames para añadir excepciones explícitas.
• Los perfiles remotos son de tipo “attach-only” (las funciones de start, stop y reset están desactivadas).
• Orden de detección automática: navegador por defecto si es basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• Servicio de control: solo funciona en loopback (el puerto se deriva de gateway.port, por defecto es 18791).
• extraArgs: añade flags de lanzamiento adicionales al proceso local de Chromium (útil para --disable-gpu, definir el tamaño de ventana o flags de depuración).
• relayBindHost: cambia la dirección donde escucha el relay de la extensión de Chrome. No lo toques si solo necesitas acceso local; configura una dirección como 0.0.0.0 únicamente si el relay debe cruzar un límite de namespace (como en WSL2) y la red del host es de confianza.

---

Interfaz de usuario

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: color de acento para la interfaz de la aplicación nativa (como el tinte de la burbuja en Talk Mode).
• assistant: permite sobrescribir la identidad visual de la interfaz de control. Si no se configura, se usará la identidad del agente que esté activo.

Configurar un Gateway o gestionar Hooks puede ser un proceso complejo si no tienes claros los parámetros de red y autenticación. Aquí tienes los detalles técnicos para configurar cada componente de OpenClaw de forma precisa.

Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
  },
}

Detalles del campo Gateway

• mode: local (ejecuta el gateway) o remote (conecta a un gateway remoto). El Gateway no arrancará a menos que esté en local.
• port: puerto único multiplexado para WS + HTTP. Prioridad: --port > OPENCLAW_GATEWAY_PORT > gateway.port > 18789.
• bind: auto, loopback (por defecto), lan (0.0.0.0), tailnet (solo IP de Tailscale), o custom.
• Alias de bind heredados: usa los valores de modo bind en gateway.bind (auto, loopback, lan, tailnet, custom), no los alias de host (0.0.0.0, 127.0.0.1, localhost, ::, ::1).
• Nota sobre Docker: el bind loopback por defecto escucha en 127.0.0.1 dentro del contenedor. Con redes bridge de Docker (-p 18789:18789), el tráfico llega por eth0, por lo que el gateway será inalcanzable. Usa --network host, o establece bind: "lan" (o bind: "custom" con customBindHost: "0.0.0.0") para escuchar en todas las interfaces.
• Auth: requerido por defecto. Los binds que no sean loopback requieren un token o password compartido. El asistente de configuración genera un token por defecto.
• Si configuras tanto gateway.auth.token como gateway.auth.password (incluyendo SecretRefs), establece gateway.auth.mode explícitamente a token o password. Los flujos de inicio e instalación/reparación del servicio fallarán si ambos están configurados y el modo no está definido.
• gateway.auth.mode: "none": modo explícito sin autenticación. Úsalo solo para configuraciones locales de loopback confiables; esta opción no se ofrece en los prompts de configuración inicial.
• gateway.auth.mode: "trusted-proxy": delega la autenticación a un reverse proxy con gestión de identidad y confía en los headers de identidad de gateway.trustedProxies (ver Trusted Proxy Auth).
• gateway.auth.allowTailscale: cuando es true, los headers de identidad de Tailscale Serve pueden satisfacer la autenticación de Control UI/WebSocket (verificado vía tailscale whois); los endpoints de la API HTTP siguen requiriendo autenticación por token/password. Este flujo sin token asume que el host del gateway es confiable. Por defecto es true cuando tailscale.mode = "serve".
• gateway.auth.rateLimit: limitador opcional de intentos fallidos. Se aplica por IP de cliente y por ámbito de autenticación (el secreto compartido y el token de dispositivo se rastrean de forma independiente). Los intentos bloqueados devuelven 429 + Retry-After.
  • gateway.auth.rateLimit.exemptLoopback es true por defecto; cámbialo a false si quieres limitar también el tráfico de localhost (para entornos de prueba o despliegues estrictos con proxy).
• Los intentos de autenticación WS desde el navegador siempre están limitados con la exención de loopback desactivada (defensa en profundidad contra ataques de fuerza bruta en localhost desde el navegador).
• tailscale.mode: serve (solo tailnet, bind loopback) o funnel (público, requiere autenticación).
• controlUi.allowedOrigins: lista blanca explícita de orígenes de navegador para conexiones WebSocket del Gateway. Es necesario cuando se esperan clientes de navegador desde orígenes que no sean loopback.
• controlUi.dangerouslyAllowHostHeaderOriginFallback: modo peligroso que permite el fallback de origen basado en el header Host para despliegues que dependen intencionadamente de esta política.
• remote.transport: ssh (por defecto) o direct (ws/wss). Para direct, remote.url debe ser ws:// o wss://.
• OPENCLAW_ALLOW_INSECURE_PRIVATE_WS=1: anulación de emergencia en el lado del cliente que permite ws:// en texto plano hacia IPs de redes privadas confiables; el valor por defecto sigue siendo solo loopback para texto plano.
• gateway.remote.token / .password son campos de credenciales para clientes remotos. No configuran la autenticación del gateway por sí mismos.
• Las rutas de llamada al gateway local pueden usar gateway.remote.* como fallback solo cuando gateway.auth.* no está configurado.
• Si gateway.auth.token / gateway.auth.password se configura explícitamente mediante SecretRef y no se resuelve, la resolución falla por seguridad (sin ocultamiento por fallback remoto).
• trustedProxies: IPs de reverse proxies que terminan TLS. Incluye solo proxies que tú controles.
• allowRealIpFallback: cuando es true, el gateway acepta X-Real-IP si falta X-Forwarded-For. Por defecto es false para un comportamiento de fallo seguro.
• gateway.tools.deny: nombres de herramientas adicionales bloqueadas para HTTP POST /tools/invoke (extiende la lista de denegación por defecto).
• gateway.tools.allow: elimina nombres de herramientas de la lista de denegación HTTP por defecto.

OpenAI-compatible endpoints

• Chat Completions: desactivado por defecto. Actívalo con gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Refuerzo de entrada de URL para Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist
• Header opcional de seguridad para respuestas:
  • gateway.http.securityHeaders.strictTransportSecurity (configúralo solo para orígenes HTTPS que controles; ver Trusted Proxy Auth)

Multi-instance isolation

Ejecuta múltiples gateways en un solo host con puertos y directorios de estado únicos:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

Flags de conveniencia: --dev (usa ~/.openclaw-dev + puerto 19001), --profile <nombre> (usa ~/.openclaw-<nombre>).

Consulta Multiple Gateways.

---

Hooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.2-mini",
      },
    ],
  },
}

Auth: Authorization: Bearer <token> o x-openclaw-token: <token>.

Endpoints:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • sessionKey del payload de la solicitud se acepta solo cuando hooks.allowRequestSessionKey=true (por defecto: false).
• POST /hooks/<name> → resuelto mediante hooks.mappings

Detalles de Mapping

• match.path coincide con la sub-ruta después de /hooks (ej. /hooks/gmail → gmail).
• match.source coincide con un campo del payload para rutas genéricas.
• Las plantillas como {{messages[0].subject}} leen datos del payload.
• transform puede apuntar a un módulo JS/TS que devuelva una acción de hook.
  • transform.module debe ser una ruta relativa y permanecer dentro de hooks.transformsDir (se rechazan rutas absolutas y saltos de directorio).
• agentId dirige a un agente específico; los IDs desconocidos usan el valor por defecto.
• allowedAgentIds: restringe el enrutamiento explícito (* u omitido = permitir todos, [] = denegar todos).
• defaultSessionKey: clave de sesión fija opcional para ejecuciones de agentes de hook sin sessionKey explícita.
• allowRequestSessionKey: permite que quienes llaman a /hooks/agent establezcan sessionKey (por defecto: false).
• allowedSessionKeyPrefixes: lista blanca de prefijos opcional para valores de sessionKey explícitos (solicitud + mapping), ej. ["hook:"].
• deliver: true envía la respuesta final a un canal; channel por defecto es last.
• model sobrescribe el LLM para esta ejecución del hook (debe estar permitido si el catálogo de modelos está configurado).

Gmail integration

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• El Gateway inicia automáticamente gog gmail watch serve al arrancar si está configurado. Usa OPENCLAW_SKIP_GMAIL_WATCHER=1 para desactivarlo.
• No ejecutes un proceso gog gmail watch serve independiente junto al Gateway.

---

Canvas host

{
  canvasHost: {
    root: "~/.openclaw/workspace/canvas",
    liveReload: true,
    // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
  },
}

• Sirve HTML/CSS/JS editable por agentes y A2UI sobre HTTP bajo el puerto del Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Solo local: mantén gateway.bind: "loopback" (por defecto).
• Binds que no sean loopback: las rutas de canvas requieren autenticación del Gateway (token/password/trusted-proxy), igual que otras superficies HTTP del Gateway.
• Los WebViews de Node normalmente no envían headers de autenticación; después de que un nodo se vincula y conecta, el Gateway anuncia URLs de capacidad con ámbito de nodo para el acceso a canvas/A2UI.
• Las URLs de capacidad están vinculadas a la sesión WS activa del nodo y expiran rápido. No se utiliza fallback basado en IP.
• Inyecta un cliente de live-reload en el HTML servido.
• Crea automáticamente un index.html inicial si está vacío.
• También sirve A2UI en /__openclaw__/a2ui/.
• Los cambios requieren reiniciar el gateway.
• Desactiva el live reload para directorios grandes o si encuentras errores EMFILE.

---

Discovery

mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (por defecto): omite cliPath + sshPort de los registros TXT.
• full: incluye cliPath + sshPort.
• El hostname por defecto es openclaw. Sobrescríbelo con OPENCLAW_MDNS_HOSTNAME.

Wide-area (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

Escribe una zona DNS-SD unicast bajo ~/.openclaw/dns/. Para descubrimiento entre redes, emparéjalo con un servidor DNS (se recomienda CoreDNS) + Tailscale split DNS.

Configuración: openclaw dns setup --apply.

AI Setup Assistant

Siguientes pasos

• Configuración de Trusted Proxy
• Gestión de múltiples Gateways
• Uso de Hooks con agentes

Entorno

env (variables de entorno inline)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• Las variables de entorno inline solo se aplican si la clave no existe en el entorno del proceso.
• Archivos .env: se busca en el CWD .env + ~/.openclaw/.env (ninguno sobrescribe las variables existentes).
• shellEnv: importa las claves que falten desde tu perfil de inicio de sesión de la shell.
• Consulta Environment para ver la precedencia completa.

Sustitución de variables de entorno

Puedes referenciar variables de entorno en cualquier cadena de configuración usando ${VAR_NAME}:

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Solo coinciden los nombres en mayúsculas: [A-Z_][A-Z0-9_]*.
• Si faltan variables o están vacías, se lanzará un error al cargar la configuración.
• Usa $${VAR} para escapar y obtener un texto literal ${VAR}.
• Funciona con $include.

---

Secretos

Las referencias a secretos son aditivas: los valores en texto plano siguen funcionando.

SecretRef

Usa esta estructura de objeto:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validación:

• Patrón de provider: ^[a-z][a-z0-9_-]{0,63}$
• Patrón de ID para source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• ID para source: "file": puntero JSON absoluto (por ejemplo, "/providers/openai/apiKey")
• Patrón de ID para source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• Los IDs de source: "exec" no deben contener segmentos de ruta delimitados por barras como . o .. (por ejemplo, a/../b será rechazado).

Superficie de credenciales soportada

• Matriz canónica: SecretRef Credential Surface
• Los objetivos de secrets apply soportan las rutas de credenciales de openclaw.json.
• Las referencias en auth-profiles.json se incluyen en la resolución en tiempo de ejecución y en la cobertura de auditoría.

Configuración de proveedores de secretos

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

Notas:

• El proveedor file soporta mode: "json" y mode: "singleValue" (el id debe ser "value" en el modo singleValue).
• El proveedor exec requiere una ruta de command absoluta y utiliza protocolos de carga útil en stdin/stdout.
• Por defecto, se rechazan las rutas de comando que sean symlinks. Configura allowSymlinkCommand: true para permitirlas mientras se valida la ruta del objetivo resuelto.
• Si trustedDirs está configurado, la comprobación de directorio de confianza se aplica a la ruta del objetivo resuelto.
• El entorno hijo de exec es mínimo por defecto; pasa las variables necesarias explícitamente con passEnv.
• Las referencias a secretos se resuelven al momento de la activación en una instantánea en memoria; luego, las rutas de solicitud solo leen esa instantánea.
• El filtrado de superficie activa se aplica durante la activación: las referencias no resueltas en superficies habilitadas causan un fallo en el inicio o recarga, mientras que las superficies inactivas se omiten con diagnósticos.

Almacenamiento de Auth

{
  auth: {
    profiles: {
      "anthropic:me@example.com": { provider: "anthropic", mode: "oauth", email: "me@example.com" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
    },
  },
}

• Los perfiles por agente se guardan en <agentDir>/auth-profiles.json.
• auth-profiles.json admite referencias a nivel de valor (keyRef para api_key, tokenRef para token).
• Las credenciales estáticas en tiempo de ejecución provienen de snapshots resueltos en memoria; las entradas heredadas del archivo estático auth.json se eliminan cuando se detectan.
• Importaciones de OAuth heredadas desde ~/.openclaw/credentials/oauth.json.
• Consulta OAuth.
• Comportamiento de secretos en tiempo de ejecución y herramientas de audit/configure/apply: Secrets Management.

Logging

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• Archivo de log por defecto: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Configura logging.file si necesitas una ruta estable.
• consoleLevel sube a debug cuando usas --verbose.

CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

cli.banner.taglineMode controla el estilo del mensaje (tagline) del banner:

• "random" (por defecto): frases aleatorias divertidas o de temporada.
• "default": una frase neutral fija (All your chats, one OpenClaw.).
• "off": desactiva el texto de la frase (el título y la versión del banner se siguen mostrando).

Si prefieres ocultar el banner por completo, configura la variable de entorno OPENCLAW_HIDE_BANNER=1.

---

Wizard

Metadatos generados por los asistentes de la CLI (onboard, configure, doctor):

{
  wizard: {
    lastRunAt: "2026-01-01T00:00:00.000Z",
    lastRunVersion: "2026.1.4",
    lastRunCommit: "abc1234",
    lastRunCommand: "configure",
    lastRunMode: "local",
  },
}

Identidad

{
  agents: {
    list: [
      {
        id: "main",
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
      },
    ],
  },
}

Esta sección la escribe el asistente de configuración de macOS y define algunos valores por defecto:

• messages.ackReaction y mentionPatterns se configuran automáticamente usando identity.emoji e identity.name (si no hay emoji, se usa 👀 por defecto).
• avatar admite varios formatos: rutas relativas al workspace, URLs http(s) o URIs data:.

---

Bridge (legacy, eliminado)

Las versiones actuales ya no incluyen el bridge TCP. Ahora los Nodes se conectan a través del WebSocket del Gateway. Las claves bridge.* ya no forman parte del esquema de configuración; de hecho, la validación fallará hasta que las elimines. Puedes usar openclaw doctor --fix para limpiar estas claves desconocidas de forma automática.

Configuración legacy del bridge (referencia histórica)

{
  "bridge": {
    "enabled": true,
    "port": 18790,
    "bind": "tailnet",
    "tls": {
      "enabled": true,
      "autoGenerate": true
    }
  }
}

Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: cuánto tiempo se mantienen las sesiones de ejecuciones cron aisladas y completadas antes de eliminarlas de sessions.json. También controla la limpieza de las transcripciones de cron eliminadas y archivadas. Por defecto: 24h; usa false para desactivarlo.
• runLog.maxBytes: tamaño máximo por archivo de registro de ejecución (cron/runs/<jobId>.jsonl) antes de la limpieza. Por defecto: 2_000_000 bytes.
• runLog.keepLines: líneas más recientes que se conservan cuando se activa la limpieza del registro de ejecución. Por defecto: 2000.
• webhookToken: token de portador (bearer token) usado para la entrega POST del webhook de cron (delivery.mode = "webhook"). Si se omite, no se envía ninguna cabecera de autenticación.
• webhook: URL de webhook de legado (http/https) que está obsoleta y solo se usa para tareas guardadas que todavía tienen notify: true.

Consulta Cron Jobs.

---

Variables de plantilla para modelos de Media

Marcadores de posición de plantilla que se expanden en tools.media.models[].args:

Variable	Descripción
{{Body}}	Cuerpo completo del mensaje entrante
{{RawBody}}	Cuerpo original (sin envoltorios de historial o remitente)
{{BodyStripped}}	Cuerpo sin las menciones de grupo
{{From}}	Identificador del remitente
{{To}}	Identificador de destino
{{MessageSid}}	ID de mensaje del canal
{{SessionId}}	UUID de la sesión actual
{{IsNewSession}}	"true" cuando se crea una sesión nueva
{{MediaUrl}}	Pseudo-URL del contenido media entrante
{{MediaPath}}	Ruta local del contenido media
{{MediaType}}	Tipo de media (image/audio/document/…)
{{Transcript}}	Transcripción de audio
{{Prompt}}	Prompt de media resuelto para entradas de CLI
{{MaxChars}}	Caracteres máximos de salida resueltos para entradas de CLI
{{ChatType}}	"direct" o "group"
{{GroupSubject}}	Asunto del grupo (mejor esfuerzo)
{{GroupMembers}}	Vista previa de los miembros del grupo (mejor esfuerzo)
{{SenderName}}	Nombre visible del remitente (mejor esfuerzo)
{{SenderE164}}	Número de teléfono del remitente (mejor esfuerzo)
{{Provider}}	Pista del proveedor (whatsapp, telegram, discord, etc.)

---

Inclusiones de configuración ($include)

Puedes dividir tu configuración en varios archivos para que sea más fácil de gestionar:

~/.openclaw/openclaw.json

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

Comportamiento de la fusión:

• Archivo único: reemplaza el objeto que lo contiene.
• Array de archivos: se fusionan profundamente en orden (los archivos posteriores sobrescriben a los anteriores).
• Claves hermanas: se fusionan después de las inclusiones (sobrescriben los valores incluidos).
• Inclusiones anidadas: hasta 10 niveles de profundidad.
• Rutas: se resuelven de forma relativa al archivo que las incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (dirname de openclaw.json). Las formas absolutas o con ../ solo se permiten si se resuelven dentro de ese límite.
• Errores: mensajes claros para archivos faltantes, errores de análisis y referencias circulares.

---

AI Setup Assistant

Pasos siguientes

• Configuration
• Configuration Examples
• Doctor

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

{
  agents: {
    list: [
      {
        id: "personal",
        workspace: "~/.openclaw/workspace-personal",
        sandbox: { mode: "off" },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "family",
        workspace: "~/.openclaw/workspace-family",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "ro" },
        tools: {
          allow: [
            "read",
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
          ],
          deny: ["write", "edit", "apply_patch", "exec", "process", "browser"],
        },
      },
    ],
  },
}

{
  agents: {
    list: [
      {
        id: "public",
        workspace: "~/.openclaw/workspace-public",
        sandbox: { mode: "all", scope: "agent", workspaceAccess: "none" },
        tools: {
          allow: [
            "sessions_list",
            "sessions_history",
            "sessions_send",
            "sessions_spawn",
            "session_status",
            "whatsapp",
            "telegram",
            "slack",
            "discord",
            "gateway",
          ],
          deny: [
            "read",
            "write",
            "edit",
            "apply_patch",
            "exec",
            "process",
            "browser",
            "canvas",
            "nodes",
            "cron",
            "gateway",
            "image",
          ],
        },
      },
    ],
  },
}

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // skip parent-thread fork above this token count (0 disables)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duration or false
      maxDiskBytes: "500mb", // optional hard budget
      highWaterBytes: "400mb", // optional cleanup target
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // default inactivity auto-unfocus in hours (`0` disables)
      maxAgeHours: 0, // default hard max age in hours (`0` disables)
    },
    mainKey: "main", // legacy (runtime always uses "main")
    agentToAgent: { maxPingPongTurns: 5 },
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}