​

Referencia de configuración

​

Canales

​

Acceso a MD y grupos

​

Anulaciones de modelo por canal

{
  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 de canal y heartbeat

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

• channels.defaults.groupPolicy: política de grupo de respaldo cuando groupPolicy a nivel de proveedor no está configurada.
• channels.defaults.contextVisibility: modo predeterminado de visibilidad de contexto suplementario para todos los canales. Valores: all (predeterminado, incluye todo el contexto citado/de hilo/historial), allowlist (solo incluye contexto de remitentes permitidos), allowlist_quote (igual que allowlist, pero conserva el contexto explícito de cita/respuesta). Anulación por canal: channels.<channel>.contextVisibility.
• channels.defaults.heartbeat.showOk: incluir estados correctos de canales en la salida de heartbeat.
• channels.defaults.heartbeat.showAlerts: incluir estados degradados/con errores en la salida de heartbeat.
• channels.defaults.heartbeat.useIndicator: renderizar la salida de heartbeat en formato compacto con indicadores.

​

WhatsApp

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000,
      chunkMode: "length", // length | newline
      mediaMaxMb: 50,
      sendReadReceipts: true, // doble check azul (false en modo self-chat)
      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,
    },
  },
}

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

​

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; opt in explicitly to avoid preview-edit rate limits)
      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",
    },
  },
}

• Token del bot: channels.telegram.botToken o channels.telegram.tokenFile (solo archivo normal; se rechazan enlaces simbólicos), con TELEGRAM_BOT_TOKEN como respaldo para la cuenta predeterminada.
• channels.telegram.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• En configuraciones de múltiples cuentas (2 o más ID de cuenta), configura un valor predeterminado explícito (channels.telegram.defaultAccount o channels.telegram.accounts.default) para evitar el enrutamiento por respaldo; openclaw doctor muestra una advertencia cuando falta o no es válido.
• configWrites: false bloquea las escrituras de configuración iniciadas por Telegram (migraciones de ID de supergrupo, /config set|unset).
• Las entradas bindings[] de nivel superior con type: "acp" configuran enlaces ACP persistentes para temas de foros (usa el ID canónico chatId:topic:topicId en match.peer.id). La semántica de los campos se comparte en Agentes ACP.
• Las vistas previas de streaming de Telegram usan sendMessage + editMessageText (funciona en chats directos y de grupo).
• Política de reintento: consulta Política de reintento.

​

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" },
        },
      },
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["987654321098765432"],
        agentFilter: ["default"],
        sessionFilter: ["discord:"],
        target: "dm", // dm | channel | both
        cleanupAfterResolve: false,
      },
      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; la configuración de reintento/política de la cuenta sigue viniendo de la cuenta seleccionada en la instantánea activa del entorno de ejecución.
• channels.discord.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• Usa user:<id> (MD) o channel:<id> (canal del servidor) para los destinos de entrega; los ID numéricos sin prefijo se rechazan.
• Los slugs de los servidores van en minúsculas con espacios reemplazados por -; las claves de canal usan el nombre convertido en slug (sin #). Prefiere ID de servidor.
• Los mensajes escritos por bots se ignoran de forma predeterminada. 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 las anulaciones por canal) descarta mensajes que mencionan a otro usuario o rol pero no al bot (excluyendo @everyone/@here).
• maxLinesPerMessage (predeterminado 17) divide mensajes altos incluso cuando están por debajo de 2000 caracteres.
• channels.discord.threadBindings controla el enrutamiento vinculado a hilos de Discord:
  • enabled: anulación de Discord para funciones de sesión vinculadas a hilos (/focus, /unfocus, /agents, /session idle, /session max-age y entrega/enrutamiento vinculados)
  • idleHours: anulación de Discord para desfocalización automática por inactividad en horas (0 desactiva)
  • maxAgeHours: anulación de Discord para edad máxima estricta en horas (0 desactiva)
  • spawnSubagentSessions: interruptor optativo para la creación/enlace automático de hilos de sessions_spawn({ thread: true })
• Las entradas bindings[] de nivel superior con type: "acp" configuran enlaces 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 Agentes ACP.
• 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 anulaciones opcionales de auto-join + TTS.
• channels.discord.voice.daveEncryption y channels.discord.voice.decryptionFailureTolerance se transfieren a las opciones DAVE de @discordjs/voice (true y 24 de forma predeterminada).
• OpenClaw también intenta recuperar la recepción de voz saliendo y volviendo a unirse a una sesión de voz después de fallos repetidos de descifrado.
• channels.discord.streaming es la clave canónica del modo de streaming. Los valores heredados streamMode y booleanos streaming se migran automáticamente.
• channels.discord.autoPresence asigna la disponibilidad del entorno de ejecución a la presencia del bot (saludable => online, degradado => idle, agotado => dnd) y permite anulaciones opcionales del texto de estado.
• channels.discord.dangerouslyAllowNameMatching vuelve a habilitar la coincidencia mutable por nombre/tag (modo de compatibilidad de emergencia).
• channels.discord.execApprovals: entrega nativa de aprobaciones de ejecución de Discord y autorización de aprobadores.
  • enabled: true, false o "auto" (predeterminado). En modo auto, las aprobaciones de ejecución se activan cuando se pueden resolver aprobadores desde approvers o commands.ownerAllowFrom.
  • approvers: ID de usuario de Discord autorizados para aprobar solicitudes de ejecución. Recurre a commands.ownerAllowFrom cuando se omite.
  • agentFilter: lista de permitidos opcional de ID de agente. Omítela para reenviar aprobaciones para todos los agentes.
  • sessionFilter: patrones opcionales de clave de sesión (subcadena o regex).
  • target: dónde enviar solicitudes de aprobación. "dm" (predeterminado) las envía a los MD de aprobadores, "channel" al canal de origen, "both" a ambos. Cuando el destino incluye "channel", los botones solo pueden ser usados por aprobadores resueltos.
  • cleanupAfterResolve: cuando es true, elimina los MD de aprobación tras la aprobación, denegación o expiración.

​

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 para la cuenta de servicio (serviceAccountRef).
• Variables de entorno de respaldo: GOOGLE_CHAT_SERVICE_ACCOUNT o GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• Usa spaces/<spaceId> o users/<userId> para destinos de entrega.
• channels.googlechat.dangerouslyAllowNameMatching vuelve a habilitar la coincidencia mutable por principal de correo electrónico (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,
      execApprovals: {
        enabled: "auto", // true | false | "auto"
        approvers: ["U123"],
        agentFilter: ["default"],
        sessionFilter: ["slack:"],
        target: "dm", // dm | channel | both
      },
    },
  },
}

• Socket mode requiere tanto botToken como appToken (SLACK_BOT_TOKEN + SLACK_APP_TOKEN como respaldo de variables de entorno de la cuenta predeterminada).
• HTTP mode requiere botToken más signingSecret (en la raíz o por cuenta).
• botToken, appToken, signingSecret y userToken aceptan cadenas en texto plano u objetos SecretRef.
• Las instantáneas de cuentas de Slack exponen campos por credencial de fuente/estado como botTokenSource, botTokenStatus, appTokenStatus y, en HTTP mode, signingSecretStatus. configured_unavailable significa que la cuenta está configurada mediante SecretRef, pero la ruta actual de comando/ejecución no pudo resolver el valor del secreto.
• configWrites: false bloquea las escrituras de configuración iniciadas por Slack.
• channels.slack.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• channels.slack.streaming es la clave canónica del modo de streaming. Los valores heredados streamMode y booleanos streaming se migran automáticamente.
• Usa user:<id> (MD) o channel:<id> para destinos de entrega.

• typingReaction añade una reacción temporal al mensaje entrante de Slack mientras se ejecuta una respuesta, y luego la elimina al completarse. Usa un shortcode de emoji de Slack como "hourglass_flowing_sand".
• channels.slack.execApprovals: entrega nativa de aprobaciones de ejecución de Slack y autorización de aprobadores. Mismo esquema que Discord: enabled (true/false/"auto"), approvers (ID de usuario de Slack), agentFilter, sessionFilter y target ("dm", "channel" o "both").

​

Mattermost

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      groups: {
        "*": { requireMention: true },
        "team-channel-id": { requireMention: false },
      },
      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",
    },
  },
}

• commands.callbackPath debe ser una ruta (por ejemplo /api/channels/mattermost/command), no una URL completa.
• commands.callbackUrl debe resolverse al endpoint del gateway de OpenClaw y debe ser accesible desde el servidor de Mattermost.
• Los callbacks nativos de slash están autenticados con los tokens por comando devueltos por Mattermost durante el registro del slash command. Si el registro falla o no se activa ningún comando, OpenClaw rechaza los callbacks con Unauthorized: invalid command token.
• 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 URL completas.
• channels.mattermost.configWrites: permitir o denegar escrituras de configuración iniciadas por Mattermost.
• channels.mattermost.requireMention: requerir @mention antes de responder en canales.
• channels.mattermost.groups.<channelId>.requireMention: anulación por canal del control por mención ("*" para el valor predeterminado).
• channels.mattermost.defaultAccount opcional sobrescribe la selección predeterminada de cuenta 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,
    },
  },
}

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

​

BlueBubbles

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

• Rutas clave principales cubiertas aquí: channels.bluebubbles, channels.bluebubbles.dmPolicy.
• channels.bluebubbles.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• Las entradas bindings[] de nivel superior con type: "acp" pueden enlazar conversaciones de BlueBubbles a sesiones ACP persistentes. Usa un handle o cadena de destino de BlueBubbles (chat_id:*, chat_guid:*, chat_identifier:*) en match.peer.id. Semántica compartida de campos: Agentes ACP.
• La configuración completa del canal BlueBubbles está documentada en BlueBubbles.

​

iMessage

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

• channels.imessage.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• Requiere Full Disk Access a la base de datos de Messages.
• Prefiere destinos chat_id:<id>. Usa imsg chats --limit 20 para listar chats.
• cliPath puede apuntar a un wrapper SSH; configura remoteHost (host o user@host) para obtener adjuntos por SCP.
• attachmentRoots y remoteAttachmentRoots restringen las rutas de adjuntos entrantes (predeterminado: /Users/*/Library/Messages/Attachments).
• SCP usa verificación estricta de claves de host, así que asegúrate de que la clave del host relay ya exista en ~/.ssh/known_hosts.
• channels.imessage.configWrites: permitir o denegar escrituras de configuración iniciadas por iMessage.
• Las entradas bindings[] de nivel superior con type: "acp" pueden enlazar conversaciones de iMessage a sesiones ACP persistentes. Usa un handle normalizado o un destino de chat explícito (chat_id:*, chat_guid:*, chat_identifier:*) en match.peer.id. Semántica compartida de campos: Agentes ACP.

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

​

Matrix

{
  channels: {
    matrix: {
      enabled: true,
      homeserver: "https://matrix.example.org",
      accessToken: "syt_bot_xxx",
      proxy: "http://127.0.0.1:7890",
      encryption: true,
      initialSyncLimit: 20,
      defaultAccount: "ops",
      accounts: {
        ops: {
          name: "Ops",
          userId: "@ops:example.org",
          accessToken: "syt_ops_xxx",
        },
        alerts: {
          userId: "@alerts:example.org",
          password: "secret",
          proxy: "http://127.0.0.1:7891",
        },
      },
    },
  },
}

• La autenticación por token usa accessToken; la autenticación por contraseña usa userId + password.
• channels.matrix.proxy enruta el tráfico HTTP de Matrix mediante un proxy HTTP(S) explícito. Las cuentas con nombre pueden sobrescribirlo con channels.matrix.accounts.<id>.proxy.
• channels.matrix.allowPrivateNetwork permite homeservers privados/internos. proxy y allowPrivateNetwork son controles independientes.
• channels.matrix.defaultAccount selecciona la cuenta preferida en configuraciones de múltiples cuentas.
• channels.matrix.execApprovals: entrega nativa de aprobaciones de ejecución de Matrix y autorización de aprobadores.
  • enabled: true, false o "auto" (predeterminado). En modo auto, las aprobaciones de ejecución se activan cuando se pueden resolver aprobadores desde approvers o commands.ownerAllowFrom.
  • approvers: ID de usuario de Matrix (por ejemplo @owner:example.org) autorizados para aprobar solicitudes de ejecución.
  • agentFilter: lista de permitidos opcional de ID de agente. Omítela para reenviar aprobaciones para todos los agentes.
  • sessionFilter: patrones opcionales de clave de sesión (subcadena o regex).
  • target: dónde enviar solicitudes de aprobación. "dm" (predeterminado), "channel" (sala de origen) o "both".
  • Anulaciones por cuenta: channels.matrix.accounts.<id>.execApprovals.
• Los sondeos de estado de Matrix y las búsquedas en directorio en vivo usan la misma política de proxy que el tráfico del entorno de ejecución.
• La configuración completa de Matrix, reglas de destino y ejemplos de configuración están documentados en Matrix.

​

Microsoft Teams

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

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

​

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 clave principales cubiertas aquí: channels.irc, channels.irc.dmPolicy, channels.irc.configWrites, channels.irc.nickserv.*.
• channels.irc.defaultAccount opcional sobrescribe la selección predeterminada de cuenta cuando coincide con un ID de cuenta configurado.
• La configuración completa del canal IRC (host/puerto/TLS/canales/listas de permitidos/control por mención) está documentada en IRC.

​

Multi-account (todos los canales)

{
  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 default.
• La configuración base del canal se aplica a todas las cuentas salvo que se sobrescriba por cuenta.
• Usa bindings[].match.accountId para enrutar cada cuenta a un agente diferente.
• Si añades una cuenta que no sea predeterminada mediante openclaw channels add (o mediante onboarding del canal) mientras sigues con una configuración de canal de nivel superior de una sola cuenta, OpenClaw primero promueve los valores de nivel superior de esa cuenta individual al mapa de cuentas del canal para que la cuenta original siga funcionando. La mayoría de los canales los mueven a channels.<channel>.accounts.default; Matrix puede conservar un destino con nombre/default existente que coincida.
• Los enlaces existentes solo de canal (sin accountId) siguen coincidiendo con la cuenta predeterminada; los enlaces con alcance de cuenta siguen siendo opcionales.
• openclaw doctor --fix también repara formas mixtas moviendo los valores de nivel superior de una sola cuenta con alcance de cuenta a la cuenta promovida elegida para ese canal. La mayoría de los canales usan accounts.default; Matrix puede conservar un destino con nombre/default existente que coincida.

​

Otros canales de extensión

​

Control por mención en chats de grupo

• Menciones de metadatos: @-mentions nativos de la plataforma. Se ignoran en modo self-chat de WhatsApp.
• Patrones de texto: patrones regex seguros en agents.list[].groupChat.mentionPatterns. Los patrones no válidos y la repetición anidada insegura se ignoran.
• El control por mención solo se aplica 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"] } }],
  },
}

​

Límites de historial de MD

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

​

Modo self-chat

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

​

Comandos (manejo 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,
  },
}

​

Valores predeterminados de agentes

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

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

• Omite agents.defaults.skills para que las Skills no tengan restricciones de forma predeterminada.
• Omite agents.list[].skills para heredar los valores predeterminados.
• Configura agents.list[].skills: [] para no tener Skills.
• Una lista no vacía en agents.list[].skills es el conjunto final para ese agente; no se combina con los valores predeterminados.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-1",
        fallbacks: ["google/gemini-3.1-flash-image-preview"],
      },
      videoGenerationModel: {
        primary: "qwen/wan2.6-t2v",
        fallbacks: ["qwen/wan2.6-i2v"],
      },
      pdfModel: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["openai/gpt-5.4-mini"],
      },
      params: { cacheRetention: "long" }, // global default provider params
      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 }).
  • La forma de cadena establece solo el modelo principal.
  • La forma de objeto establece el principal más los modelos de failover ordenados.
• imageModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la ruta de la herramienta image como su configuración de modelo de visión.
  • También se usa como enrutamiento de respaldo cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imágenes.
• imageGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes.
  • Valores típicos: google/gemini-3.1-flash-image-preview para generación nativa de imágenes con Gemini, fal/fal-ai/flux/dev para fal, o openai/gpt-image-1 para OpenAI Images.
  • Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API correspondiente del proveedor (por ejemplo GEMINI_API_KEY o GOOGLE_API_KEY para google/*, OPENAI_API_KEY para openai/*, FAL_KEY para fal/*).
  • Si se omite, image_generate aún puede inferir un valor predeterminado del proveedor respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los proveedores restantes registrados de generación de imágenes en orden de ID de proveedor.
• videoGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de vídeo.
  • Valores típicos: qwen/wan2.6-t2v, qwen/wan2.6-i2v, qwen/wan2.6-r2v, qwen/wan2.6-r2v-flash o qwen/wan2.7-r2v.
  • Configúralo explícitamente antes de usar la generación de vídeo compartida. A diferencia de imageGenerationModel, el entorno de ejecución de generación de vídeo todavía no infiere un proveedor predeterminado.
  • Si seleccionas directamente un proveedor/modelo, configura también la autenticación/clave de API correspondiente del proveedor.
  • El proveedor integrado de generación de vídeo de Qwen actualmente admite hasta 1 vídeo de salida, 1 imagen de entrada, 4 vídeos de entrada, 10 segundos de duración y opciones a nivel de proveedor size, aspectRatio, resolution, audio y watermark.
• pdfModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la herramienta pdf para el enrutamiento de modelos.
  • Si se omite, la herramienta PDF recurre a imageModel y luego al modelo resuelto de la sesión/predeterminado.
• pdfMaxBytesMb: límite de tamaño PDF predeterminado para la herramienta pdf cuando no se pasa maxBytesMb al llamar a la herramienta.
• pdfMaxPages: máximo predeterminado de páginas consideradas por el modo de respaldo de extracción en la herramienta pdf.
• verboseDefault: nivel verbose predeterminado para agentes. Valores: "off", "on", "full". Predeterminado: "off".
• elevatedDefault: nivel predeterminado de salida elevada para agentes. Valores: "off", "on", "ask", "full". Predeterminado: "on".
• model.primary: formato provider/model (por ejemplo openai/gpt-5.4). Si omites el proveedor, OpenClaw intenta primero un alias, luego una coincidencia única de proveedor configurado para ese ID de modelo exacto, y solo entonces recurre al proveedor predeterminado configurado (comportamiento heredado en desuso, así que prefiere provider/model explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado.
• models: el catálogo de modelos configurado y la lista de permitidos para /model. Cada entrada puede incluir alias (atajo) y params (específicos del proveedor, por ejemplo temperature, maxTokens, cacheRetention, context1m).
• params: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Configúralos en agents.defaults.params (por ejemplo { cacheRetention: "long" }).
• Precedencia de combinación de params (configuración): agents.defaults.params (base global) es sobrescrito por agents.defaults.models["provider/model"].params (por modelo), luego agents.list[].params (ID de agente coincidente) sobrescribe por clave. Consulta Prompt Caching para más detalles.
• Los escritores de configuración que mutan estos campos (por ejemplo /models set, /models set-image y comandos add/remove de fallback) guardan la forma canónica de objeto y conservan las listas de fallback existentes cuando es posible.
• maxConcurrent: máximo de ejecuciones paralelas de agentes entre sesiones (cada sesión sigue serializada). Predeterminado: 4.

​

agents.defaults.cliBackends

{
  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 CLI están orientados primero al texto; las herramientas siempre están deshabilitadas.
• Se admiten sesiones cuando sessionArg está configurado.
• Se admite paso directo de imágenes cuando imageArg acepta rutas de archivo.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        lightContext: false, // default: false; true keeps only HEARTBEAT.md from workspace bootstrap files
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        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). Predeterminado: 30m (autenticación con clave de API) o 1h (autenticación OAuth). Configura 0m para desactivar.
• suppressToolErrorWarnings: cuando es true, suprime las cargas útiles de advertencia de error de herramienta durante ejecuciones de heartbeat.
• directPolicy: política de entrega directa/MD. allow (predeterminado) permite entrega a destinos directos. block suprime la entrega a destinos directos y emite reason=dm-blocked.
• lightContext: cuando es true, las ejecuciones de heartbeat usan contexto bootstrap liviano y conservan solo HEARTBEAT.md de los archivos bootstrap del espacio de trabajo.
• isolatedSession: cuando es true, cada ejecución de heartbeat se realiza en una sesión nueva sin historial de conversación previo. Mismo patrón de aislamiento que cron sessionTarget: "isolated". Reduce el costo de tokens por heartbeat de ~100K a ~2-5K tokens.
• Por agente: configura agents.list[].heartbeat. Cuando algún agente define heartbeat, solo esos agentes ejecutan heartbeats.
• Los heartbeats ejecutan turnos completos de agente: los intervalos más cortos consumen más tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        timeoutSeconds: 900,
        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-6", // optional compaction-only model override
        notifyUser: true, // send a brief notice when compaction starts (default: false)
        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 the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default o safeguard (resumen por bloques para historiales largos). Consulta Compactación.
• timeoutSeconds: máximo de segundos permitidos para una sola operación de compactación antes de que OpenClaw la aborte. Predeterminado: 900.
• identifierPolicy: strict (predeterminado), off o custom. strict antepone orientación integrada de conservación de identificadores opacos durante el resumen de compactación.
• identifierInstructions: texto opcional personalizado de preservación de identificadores usado cuando identifierPolicy=custom.
• postCompactionSections: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar después de la compactación. Predeterminado: ["Session Startup", "Red Lines"]; configura [] para desactivar la reinyección. Cuando no está configurado o se establece explícitamente en ese par predeterminado, también se aceptan los encabezados antiguos Every Session/Safety como respaldo heredado.
• model: anulación opcional 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 configura, la compactación usa el modelo principal de la sesión.
• notifyUser: cuando es true, envía un aviso breve al usuario cuando empieza la compactación (por ejemplo, “Compacting context…”). Está desactivado de forma predeterminada para mantener la compactación silenciosa.
• memoryFlush: turno agéntico silencioso antes de la compactación automática para almacenar memorias duraderas. Se omite cuando el espacio de trabajo es de solo lectura.

​

agents.defaults.contextPruning

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

​

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.
• Anulaciones por canal: channels.<channel>.blockStreamingCoalesce (y variantes por cuenta). Signal/Slack/Discord/Google Chat usan minChars: 1500 de forma predeterminada.
• humanDelay: pausa aleatoria entre respuestas por bloques. natural = 800–2500 ms. Anulación por agente: agents.list[].humanDelay.

​

Indicadores de escritura

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

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

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        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"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / inline contents also supported:
          // identityData: { source: "env", provider: "default", id: "SSH_IDENTITY" },
          // certificateData: { source: "env", provider: "default", id: "SSH_CERTIFICATE" },
          // knownHostsData: { source: "env", provider: "default", id: "SSH_KNOWN_HOSTS" },
        },
        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"],
      },
    },
  },
}

{
  plugins: {
    entries: {
      openshell: {
        enabled: true,
        config: {
          mode: "mirror", // mirror | remote
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // optional
          gatewayEndpoint: "https://lab.example", // optional
          policy: "strict", // optional OpenShell policy id
          providers: ["openai"], // optional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

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

​

agents.list (anulaciones por agente)

{
  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 }
        thinkingDefault: "high", // per-agent thinking level override
        reasoningDefault: "on", // per-agent reasoning visibility override
        fastModeDefault: false, // per-agent fast mode override
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        skills: ["docs-search"], // replaces agents.defaults.skills when set
        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 estable del agente (obligatorio).
• default: cuando se configuran varios, el primero gana (se registra advertencia). Si no se configura ninguno, la primera entrada de la lista es la predeterminada.
• model: la forma de cadena sobrescribe solo primary; la forma de objeto { primary, fallbacks } sobrescribe ambos ([] desactiva los fallbacks globales). Los trabajos cron que solo sobrescriben primary siguen heredando los fallbacks predeterminados salvo que configures fallbacks: [].
• params: parámetros de flujo por agente combinados sobre la entrada de modelo seleccionada en agents.defaults.models. Úsalo para anulaciones específicas del agente como cacheRetention, temperature o maxTokens sin duplicar todo el catálogo de modelos.
• skills: lista de permitidos opcional de Skills por agente. Si se omite, el agente hereda agents.defaults.skills cuando está configurado; una lista explícita reemplaza los valores predeterminados en lugar de combinarlos, y [] significa sin Skills.
• thinkingDefault: valor predeterminado opcional de thinking por agente (off | minimal | low | medium | high | xhigh | adaptive). Sobrescribe agents.defaults.thinkingDefault para este agente cuando no se ha establecido una anulación por mensaje o sesión.
• reasoningDefault: visibilidad predeterminada opcional de reasoning por agente (on | off | stream). Se aplica cuando no se ha establecido una anulación de reasoning por mensaje o sesión.
• fastModeDefault: valor predeterminado opcional por agente para fast mode (true | false). Se aplica cuando no se ha establecido una anulación por mensaje o sesión.
• runtime: descriptor opcional del entorno de ejecución por agente. Usa type: "acp" con valores predeterminados runtime.acp (agent, backend, mode, cwd) cuando el agente deba usar por defecto sesiones de arnés ACP.
• identity.avatar: ruta relativa al espacio de trabajo, URL http(s) o URI data:.
• identity deriva valores predeterminados: ackReaction de emoji, mentionPatterns de name/emoji.
• subagents.allowAgents: lista de permitidos de ID de agente para sessions_spawn (["*"] = cualquiera; predeterminado: solo el mismo agente).
• Protección de herencia del sandbox: si la sesión solicitante está en sandbox, sessions_spawn rechaza destinos que se ejecutarían sin sandbox.
• subagents.requireAgentId: cuando es true, bloquea llamadas a sessions_spawn que omitan agentId (fuerza selección explícita de perfil; predeterminado: false).

​

Enrutamiento multiagente

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

​

Campos match del binding

• type (opcional): route para enrutamiento normal (si falta type, usa route por defecto), acp para enlaces ACP persistentes de conversación.
• match.channel (obligatorio)
• match.accountId (opcional; * = cualquier cuenta; omitido = cuenta predeterminada)
• match.peer (opcional; { kind: direct|group|channel, id })
• match.guildId / match.teamId (opcional; específicos del canal)
• acp (opcional; solo para entradas type: "acp"): { mode, label, cwd, backend }

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exacto, sin peer/guild/team)
5. match.accountId: "*" (a nivel de canal)
6. Agente predeterminado

​

Perfiles de acceso por agente

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

​

Sesión

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

​

Mensajes

{
  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

​

Reacción de confirmación

• De forma predeterminada usa identity.emoji del agente activo o, en su defecto, "👀". Configura "" para desactivar.
• Anulaciones por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Orden de resolución: cuenta → canal → messages.ackReaction → respaldo de identidad.
• Alcance: group-mentions (predeterminado), group-all, direct, all.
• removeAckAfterReply: elimina la confirmación tras responder en Slack, Discord y Telegram.
• messages.statusReactions.enabled: habilita reacciones de estado del ciclo de vida en Slack, Discord y Telegram. En Slack y Discord, si no está configurado, las reacciones de estado permanecen habilitadas cuando las reacciones de confirmación están activas. En Telegram, configúralo explícitamente en true para habilitar reacciones de estado del ciclo de vida.

​

Debounce entrante

​

TTS (texto a voz)

{
  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 auto-TTS. /tts off|always|inbound|tagged lo sobrescribe por sesión.
• summaryModel sobrescribe agents.defaults.model.primary para el resumen automático.
• modelOverrides está habilitado por defecto; modelOverrides.allowProvider usa false como valor predeterminado (opt-in).
• Las claves de API usan como respaldo ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY.
• openai.baseUrl sobrescribe el endpoint de TTS de OpenAI. El orden de resolución es configuración, luego OPENAI_TTS_BASE_URL y después https://api.openai.com/v1.
• Cuando 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 modelo/voz.

​

Talk

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

• talk.provider debe coincidir con una clave de talk.providers cuando se configuran varios proveedores Talk.
• Las claves heredadas planas de Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) son solo de compatibilidad y se migran automáticamente a talk.providers.<provider>.
• Los ID de voz usan como respaldo ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
• providers.*.apiKey acepta cadenas en texto plano u objetos SecretRef.
• El respaldo ELEVENLABS_API_KEY solo se aplica cuando no hay una clave de API de Talk configurada.
• providers.*.voiceAliases permite que las directivas de Talk usen nombres amigables.
• silenceTimeoutMs controla cuánto espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Si no se configura, conserva la ventana de pausa predeterminada de la plataforma (700 ms en macOS y Android, 900 ms en iOS).

​

Herramientas

​

Perfiles de herramientas

​

Grupos de herramientas

​

tools.allow / tools.deny

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

​

tools.byProvider

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