​

Configuración 🔧

• restringir quién puede activar el bot (channels.whatsapp.allowFrom, channels.telegram.allowFrom, etc.)
• controlar listas de permitidos de grupos y el comportamiento de menciones (channels.whatsapp.groups, channels.telegram.groups, channels.discord.guilds, agents.list[].groupChat)
• personalizar prefijos de mensajes (messages)
• establecer el espacio de trabajo del agente (agents.defaults.workspace o agents.list[].workspace)
• ajustar los valores predeterminados del agente integrado (agents.defaults) y el comportamiento de sesión (session)
• establecer la identidad por agente (agents.list[].identity)

¿Nuevo en la configuración? Consulte la guía de Ejemplos de configuración para ver ejemplos completos con explicaciones detalladas.

​

Validación estricta de configuración

• El Gateway no arranca.
• Solo se permiten comandos de diagnóstico (por ejemplo: openclaw doctor, openclaw logs, openclaw health, openclaw status, openclaw service, openclaw help).
• Ejecute openclaw doctor para ver los problemas exactos.
• Ejecute openclaw doctor --fix (o --yes) para aplicar migraciones/reparaciones.

​

Esquema + pistas de UI

​

Aplicar + reiniciar (RPC)

• raw (string) — carga útil JSON5 para la configuración completa
• baseHash (opcional) — hash de configuración de config.get (requerido cuando ya existe una configuración)
• sessionKey (opcional) — clave de la última sesión activa para el ping de activación
• note (opcional) — nota para incluir en el centinela de reinicio
• restartDelayMs (opcional) — retraso antes del reinicio (predeterminado 2000)

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{\\n  agents: { defaults: { workspace: \\"~/.openclaw/workspace\\" } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

​

Actualizaciones parciales (RPC)

• los objetos se fusionan recursivamente
• null elimina una clave
• los arreglos se reemplazan
  Al igual que config.apply, valida, escribe la configuración, almacena un centinela de reinicio y programa el reinicio del Gateway (con una activación opcional cuando se proporciona sessionKey).

• raw (string) — carga útil JSON5 que contiene solo las claves a cambiar
• baseHash (requerido) — hash de configuración de config.get
• sessionKey (opcional) — clave de la última sesión activa para el ping de activación
• note (opcional) — nota para incluir en el centinela de reinicio
• restartDelayMs (opcional) — retraso antes del reinicio (predeterminado 2000)

openclaw gateway call config.get --params '{}' # capture payload.hash
openclaw gateway call config.patch --params '{
  "raw": "{\\n  channels: { telegram: { groups: { \\"*\\": { requireMention: false } } } }\\n}\\n",
  "baseHash": "<hash-from-config.get>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123",
  "restartDelayMs": 1000
}'

​

Configuración mínima (punto de partida recomendado)

{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

scripts/sandbox-setup.sh

​

Modo de autochat (recomendado para control de grupos)

{
  agents: {
    defaults: { workspace: "~/.openclaw/workspace" },
    list: [
      {
        id: "main",
        groupChat: { mentionPatterns: ["@openclaw", "reisponde"] },
      },
    ],
  },
  channels: {
    whatsapp: {
      // Allowlist is DMs only; including your own number enables self-chat mode.
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

​

Inclusiones de configuración ($include)

• Organizar configuraciones grandes (p. ej., definiciones de agentes por cliente)
• Compartir ajustes comunes entre entornos
• Mantener configuraciones sensibles separadas

​

Uso básico

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },

  // Include a single file (replaces the key's value)
  agents: { $include: "./agents.json5" },

  // Include multiple files (deep-merged in order)
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

// ~/.openclaw/agents.json5
{
  defaults: { sandbox: { mode: "all", scope: "session" } },
  list: [{ id: "main", workspace: "~/.openclaw/workspace" }],
}

​

Comportamiento de fusión

• Archivo único: Reemplaza el objeto que contiene $include
• Arreglo de archivos: Fusiona profundamente los archivos en orden (los posteriores sobrescriben a los anteriores)
• Con claves hermanas: Las claves hermanas se fusionan después de las inclusiones (sobrescriben valores incluidos)
• Claves hermanas + arreglos/primitivos: No compatible (el contenido incluido debe ser un objeto)

// Sibling keys override included values
{
  $include: "./base.json5", // { a: 1, b: 2 }
  b: 99, // Result: { a: 1, b: 99 }
}

​

Incluye anidados

// clients/mueller.json5
{
  agents: { $include: "./mueller/agents.json5" },
  broadcast: { $include: "./mueller/broadcast.json5" },
}

​

Resolución de rutas

• Rutas relativas: Se resuelven relativas al archivo que incluye
• Rutas absolutas: Utilizado como es
• Directorios padre: Las referencias ../ funcionan como se espera

{ "$include": "./sub/config.json5" }      // relative
{ "$include": "/etc/openclaw/base.json5" } // absolute
{ "$include": "../shared/common.json5" }   // parent dir

​

Manejo de errores

• Archivo faltante: Error claro con la ruta resuelta
• Error de parseo: Muestra qué archivo incluido falló
• Inclusiones circulares: Detectadas y reportadas con la cadena de inclusión

​

Ejemplo: Configuración legal multi‑cliente

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789, auth: { token: "secret" } },

  // Common agent defaults
  agents: {
    defaults: {
      sandbox: { mode: "all", scope: "session" },
    },
    // Merge agent lists from all clients
    list: { $include: ["./clients/mueller/agents.json5", "./clients/schmidt/agents.json5"] },
  },

  // Merge broadcast configs
  broadcast: {
    $include: ["./clients/mueller/broadcast.json5", "./clients/schmidt/broadcast.json5"],
  },

  channels: { whatsapp: { groupPolicy: "allowlist" } },
}

// ~/.openclaw/clients/mueller/agents.json5
[
  { id: "mueller-transcribe", workspace: "~/clients/mueller/transcribe" },
  { id: "mueller-docs", workspace: "~/clients/mueller/docs" },
]

// ~/.openclaw/clients/mueller/broadcast.json5
{
  "[email protected]": ["mueller-transcribe", "mueller-docs"],
}

​

Opciones comunes

​

Env vars + .env

• .env desde el directorio de trabajo actual (si existe)
• un respaldo global .env desde ~/.openclaw/.env (también conocido como $OPENCLAW_STATE_DIR/.env)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
  },
}

​

env.shellEnv (opcional)

{
  env: {
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• OPENCLAW_LOAD_SHELL_ENV=1
• OPENCLAW_SHELL_ENV_TIMEOUT_MS=15000

​

Sustitución de var Env en configuración

{
  models: {
    providers: {
      "vercel-gateway": {
        apiKey: "${VERCEL_GATEWAY_API_KEY}",
      },
    },
  },
  gateway: {
    auth: {
      token: "${OPENCLAW_GATEWAY_TOKEN}",
    },
  },
}

• Solo se reconocen nombres de variables en mayúsculas: [A-Z_][A-Z0-9_]*
• Variables faltantes o vacías provocan un error al cargar la configuración
• Escape con $${VAR} para producir un ${VAR} literal
• Funciona con $include (los archivos incluidos también reciben sustitución)

{
  models: {
    providers: {
      custom: {
        baseUrl: "${CUSTOM_API_BASE}/v1", // → "https://api.example.com/v1"
      },
    },
  },
}

​

Almacenamiento de autenticación (OAuth + claves de API)

• <agentDir>/auth-profiles.json (predeterminado: ~/.openclaw/agents/<agentId>/agent/auth-profiles.json)

• ~/.openclaw/credentials/oauth.json (o $OPENCLAW_STATE_DIR/credentials/oauth.json)

• <agentDir>/auth.json (administrada automáticamente; no edite manualmente)

• ~/.openclaw/agent/* (migrado por openclaw doctor a ~/.openclaw/agents/<defaultAgentId>/agent/*)

• Directorio OAuth (solo importación heredada): OPENCLAW_OAUTH_DIR
• Directorio de agente (anulación de la raíz del agente predeterminado): OPENCLAW_AGENT_DIR (preferido), PI_CODING_AGENT_DIR (heredado)

​

auth

{
  auth: {
    profiles: {
      "anthropic:[email protected]": { provider: "anthropic", mode: "oauth", email: "[email protected]" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
    },
    order: {
      anthropic: ["anthropic:[email protected]", "anthropic:work"],
    },
  },
}

​

agents.list[].identity

• messages.ackReaction a partir del identity.emoji del agente activo (retrocede a 👀)
• agents.list[].groupChat.mentionPatterns a partir del identity.name/identity.emoji del agente (para que “@Samantha” funcione en grupos en Telegram/Slack/Discord/Google Chat/iMessage/WhatsApp)
• identity.avatar acepta una ruta de imagen relativa al espacio de trabajo o una URL remota/data URL. Los archivos locales deben residir dentro del espacio de trabajo del agente.

• Ruta relativa al espacio de trabajo (debe permanecer dentro del espacio del agente)
• URL http(s)
• URI data:

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

​

wizard

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

​

logging

• Archivo de registro predeterminado: /tmp/openclaw/openclaw-YYYY-MM-DD.log
• Si desea una ruta estable, establezca logging.file en /tmp/openclaw/openclaw.log.
• La salida de consola puede ajustarse por separado mediante:
  • logging.consoleLevel (predeterminado info, aumenta a debug cuando --verbose)
  • logging.consoleStyle (pretty | compact | json)
• Los resúmenes de herramientas pueden redactarse para evitar filtraciones de secretos:
  • logging.redactSensitive (off | tools, predeterminado: tools)
  • logging.redactPatterns (arreglo de cadenas regex; sobrescribe los valores predeterminados)

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
    redactPatterns: [
      // Example: override defaults with your own rules.
      "\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1",
      "/\\bsk-[A-Za-z0-9_-]{8,}\\b/gi",
    ],
  },
}

​

channels.whatsapp.dmPolicy

• "pairing" (predeterminado): remitentes desconocidos reciben un código de emparejamiento; el propietario debe aprobar
• "allowlist": solo permitir remitentes en channels.whatsapp.allowFrom (o en el almacén de permitidos emparejados)
• "open": permitir todos los DMs entrantes (requiere que channels.whatsapp.allowFrom incluya "*")
• "disabled": ignorar todos los DMs entrantes

• openclaw pairing list whatsapp
• openclaw pairing approve whatsapp <code>

​

channels.whatsapp.allowFrom

{
  channels: {
    whatsapp: {
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "+447700900123"],
      textChunkLimit: 4000, // optional outbound chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      mediaMaxMb: 50, // optional inbound media cap (MB)
    },
  },
}

​

channels.whatsapp.sendReadReceipts

{
  channels: {
    whatsapp: { sendReadReceipts: false },
  },
}

​

channels.whatsapp.accounts (multicuenta)

{
  channels: {
    whatsapp: {
      accounts: {
        default: {}, // optional; keeps the default id stable
        personal: {},
        biz: {
          // Optional override. Default: ~/.openclaw/credentials/whatsapp/biz
          // authDir: "~/.openclaw/credentials/whatsapp/biz",
        },
      },
    },
  },
}

• Los comandos salientes usan por defecto la cuenta default si está presente; de lo contrario, el primer ID de cuenta configurado (ordenado).
• El directorio de autenticación Baileys heredado de cuenta única se migra por openclaw doctor a whatsapp/default.

​

channels.telegram.accounts / channels.discord.accounts / channels.googlechat.accounts / channels.slack.accounts / channels.mattermost.accounts / channels.signal.accounts / channels.imessage.accounts

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

• Se usa default cuando se omite accountId (CLI + enrutamiento).
• Los tokens de entorno solo aplican a la cuenta predeterminada.
• Los ajustes base del canal (política de grupos, control de menciones, etc.) aplican a todas las cuentas a menos que se anulen por cuenta.
• Use bindings[].match.accountId para enrutar cada cuenta a un agents.defaults diferente.

​

Control de menciones en chats de grupo (agents.list[].groupChat + messages.groupChat)

• Menciones por metadatos: menciones @ nativas de la plataforma (p. ej., tocar para mencionar en WhatsApp). Se ignoran en el modo de autochat de WhatsApp (ver channels.whatsapp.allowFrom).
• Patrones de texto: patrones regex definidos en agents.list[].groupChat.mentionPatterns. Siempre se verifican independientemente del modo de autochat.
• El control de menciones solo se aplica cuando la detección de menciones es posible (menciones nativas o al menos un mentionPattern).

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

​

Límites de historial en DM

{
  channels: {
    telegram: {
      dmHistoryLimit: 30, // limit DM sessions to 30 user turns
      dms: {
        "123456789": { historyLimit: 50 }, // per-user override (user ID)
      },
    },
  },
}

1. Anulación por DM: channels.<provider>.dms[userId].historyLimit
2. Predeterminado del proveedor: channels.<provider>.dmHistoryLimit
3. Sin límite (se conserva todo el historial)

{
  agents: {
    list: [
      { id: "work", groupChat: { mentionPatterns: ["@workbot", "\\+15555550123"] } },
      { id: "personal", groupChat: { mentionPatterns: ["@homebot", "\\+15555550999"] } },
    ],
  },
}

{
  channels: {
    whatsapp: {
      // Include your own number to enable self-chat mode (ignore native @-mentions).
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          // Only these text patterns will trigger responses
          mentionPatterns: ["reisponde", "@openclaw"],
        },
      },
    ],
  },
}

​

Política de grupos (por canal)

{
  channels: {
    whatsapp: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    telegram: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["tg:123456789", "@alice"],
    },
    signal: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15551234567"],
    },
    imessage: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["chat_id:123"],
    },
    msteams: {
      groupPolicy: "allowlist",
      groupAllowFrom: ["[email protected]"],
    },
    discord: {
      groupPolicy: "allowlist",
      guilds: {
        GUILD_ID: {
          channels: { help: { allow: true } },
        },
      },
    },
    slack: {
      groupPolicy: "allowlist",
      channels: { "#general": { allow: true } },
    },
  },
}

• "open": los grupos omiten listas de permitidos; el control de menciones sigue aplicando.
• "disabled": bloquear todos los mensajes de grupos/salas.
• "allowlist": permitir solo grupos/salas que coincidan con la lista de permitidos configurada.
• channels.defaults.groupPolicy establece el valor predeterminado cuando el groupPolicy de un proveedor no está configurado.
• WhatsApp/Telegram/Signal/iMessage/Microsoft Teams usan groupAllowFrom (respaldo: allowFrom explícito).
• Discord/Slack usan listas de permitidos de canal (channels.discord.guilds.*.channels, channels.slack.channels).
• Los DMs de grupo (Discord/Slack) siguen controlados por dm.groupEnabled + dm.groupChannels.
• El valor predeterminado es groupPolicy: "allowlist" (a menos que lo anule channels.defaults.groupPolicy); si no se configura una lista de permitidos, los mensajes de grupo se bloquean.

​

Enrutamiento multi‑agente (agents.list + bindings)

• agents.list[]: anulaciones por agente.
  • id: ID estable del agente (requerido).
  • default: opcional; cuando se establecen varios, gana el primero y se registra una advertencia. Si no se establece ninguno, la primera entrada de la lista es el agente predeterminado.
  • name: nombre visible del agente.
  • workspace: ~/.openclaw/workspace-<agentId> predeterminado (para main, retrocede a agents.defaults.workspace).
  • agentDir: ~/.openclaw/agents/<agentId>/agent predeterminado.
  • model: modelo predeterminado por agente, anula agents.defaults.model para ese agente.
    • forma de cadena: "provider/model", anula solo agents.defaults.model.primary
    • forma de objeto: { primary, fallbacks } (los retrocesos anulan agents.defaults.model.fallbacks; [] deshabilita los retrocesos globales para ese agente)
  • identity: nombre/tema/emoji por agente (usado para patrones de mención + reacciones de acuse).
  • groupChat: control de menciones por agente (mentionPatterns).
  • sandbox: configuración de sandbox por agente (anula agents.defaults.sandbox).
    • mode: "off" | "non-main" | "all"
    • workspaceAccess: "none" | "ro" | "rw"
    • scope: "session" | "agent" | "shared"
    • workspaceRoot: raíz personalizada del espacio de trabajo del sandbox
    • docker: anulaciones de docker por agente (p. ej., image, network, env, setupCommand, límites; se ignora cuando scope: "shared")
    • browser: anulaciones del navegador en sandbox por agente (se ignora cuando scope: "shared")
    • prune: anulaciones de depuración del sandbox por agente (se ignora cuando scope: "shared")
  • subagents: valores predeterminados de sub‑agente por agente.
    • allowAgents: lista de permitidos de IDs de agente para sessions_spawn desde este agente (["*"] = permitir cualquiera; predeterminado: solo el mismo agente)
  • tools: restricciones de herramientas por agente (aplicadas antes de la política de herramientas del sandbox).
    • profile: perfil base de herramientas (aplicado antes de permitir/denegar)
    • allow: arreglo de nombres de herramientas permitidas
    • deny: arreglo de nombres de herramientas denegadas (la denegación prevalece)
• agents.defaults: valores predeterminados compartidos del agente (modelo, espacio de trabajo, sandbox, etc.).
• bindings[]: enruta mensajes entrantes a un agentId.
  • match.channel (requerido)
  • match.accountId (opcional; * = cualquier cuenta; omitido = cuenta predeterminada)
  • match.peer (opcional; { kind: direct|group|channel, id })
  • match.guildId / match.teamId (opcional; específico del canal)

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exacto, sin par/gremio/equipo)
5. match.accountId: "*" (a nivel de canal, sin par/gremio/equipo)
6. agente predeterminado (agents.list[].default, o la primera entrada de la lista, o "main")

​

Perfiles de acceso por agente (multi‑agente)

• Acceso completo (agente personal)
• Solo lectura de herramientas + espacio de trabajo
• Sin acceso al sistema de archivos (solo herramientas de mensajería/sesión)

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

{
  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" } },
  ],
  channels: {
    whatsapp: {
      accounts: {
        personal: {},
        biz: {},
      },
    },
  },
}

​

tools.agentToAgent (opcional)

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

​

messages.queue

{
  messages: {
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog (steer+backlog ok) | interrupt (queue=steer legacy)
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },
}

​

messages.inbound

{
  messages: {
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
        discord: 1500,
      },
    },
  },
}

• La desaceleración agrupa mensajes solo de texto; los medios/adjuntos se envían de inmediato.
• Los comandos de control (p. ej., /queue, /new) omiten la desaceleración para mantenerse independientes.

​

commands (manejo de comandos de chat)

{
  commands: {
    native: "auto", // register native commands when supported (auto)
    text: true, // parse slash commands in chat messages
    bash: false, // allow ! (alias: /bash) (host-only; requires tools.elevated allowlists)
    bashForegroundMs: 2000, // bash foreground window (0 backgrounds immediately)
    config: false, // allow /config (writes to disk)
    debug: false, // allow /debug (runtime-only overrides)
    restart: false, // allow /restart + gateway restart tool
    useAccessGroups: true, // enforce access-group allowlists/policies for commands
  },
}

• Los comandos de texto deben enviarse como un mensaje independiente y usar el prefijo inicial / (sin alias de texto plano).
• commands.text: false deshabilita el análisis de mensajes de chat para comandos.
• commands.native: "auto" (predeterminado) activa comandos nativos para Discord/Telegram y deja Slack desactivado; los canales no compatibles permanecen solo texto.
• Establezca commands.native: true|false para forzar todos, o anule por canal con channels.discord.commands.native, channels.telegram.commands.native, channels.slack.commands.native (bool o "auto"). false borra comandos registrados previamente en Discord/Telegram al iniciar; los comandos de Slack se gestionan en la app de Slack.
• channels.telegram.customCommands agrega entradas adicionales al menú del bot de Telegram. Los nombres se normalizan; los conflictos con comandos nativos se ignoran.
• commands.bash: true habilita ! <cmd> para ejecutar comandos del shell del host (/bash <cmd> también funciona como alias). Requiere tools.elevated.enabled y listar al remitente en tools.elevated.allowFrom.<channel>.
• commands.bashForegroundMs controla cuánto espera bash antes de pasar a segundo plano. Mientras un trabajo de bash se ejecuta, nuevas solicitudes ! <cmd> se rechazan (una a la vez).
• commands.config: true habilita /config (lee/escribe openclaw.json).
• channels.<provider>.configWrites controla las mutaciones de configuración iniciadas por ese canal (predeterminado: true). Aplica a /config set|unset más migraciones automáticas específicas del proveedor (cambios de ID de supergrupo de Telegram, cambios de ID de canal de Slack).
• commands.debug: true habilita /debug (anulaciones solo en tiempo de ejecución).
• commands.restart: true habilita /restart y la acción de reinicio de la herramienta del gateway.
• commands.useAccessGroups: false permite que los comandos omitan listas de permitidos/políticas de grupos de acceso.
• Los comandos slash y directivas solo se respetan para remitentes autorizados. La autorización se deriva de listas de permitidos/emparejamiento del canal más commands.useAccessGroups.

​

web (tiempo de ejecución del canal web de WhatsApp)

{
  web: {
    enabled: true,
    heartbeatSeconds: 60,
    reconnect: {
      initialMs: 2000,
      maxMs: 120000,
      factor: 1.4,
      jitter: 0.2,
      maxAttempts: 0,
    },
  },
}

​

channels.telegram (transporte del bot)

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "your-bot-token",
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["tg:123456789"], // optional; "open" requires ["*"]
      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, // include last N group messages as context (0 disables)
      replyToMode: "first", // off | first | all
      linkPreview: true, // toggle outbound link previews
      streamMode: "partial", // off | partial | block (draft streaming; separate from block streaming)
      draftChunk: {
        // optional; only for streamMode=block
        minChars: 200,
        maxChars: 800,
        breakPreference: "paragraph", // paragraph | newline | sentence
      },
      actions: { reactions: true, sendMessage: true }, // tool action gates (false disables)
      reactionNotifications: "own", // off | own | all
      mediaMaxMb: 5,
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 400,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
      network: {
        // transport overrides
        autoSelectFamily: false,
      },
      proxy: "socks5://localhost:9050",
      webhookUrl: "https://example.com/telegram-webhook", // requires webhookSecret
      webhookSecret: "secret",
      webhookPath: "/telegram-webhook",
    },
  },
}

• Usa sendMessageDraft de Telegram (burbuja de borrador, no un mensaje real).
• Requiere temas de chat privado (message_thread_id en DMs; el bot tiene temas habilitados).
• /reasoning stream transmite el razonamiento al borrador y luego envía la respuesta final. Los valores predeterminados y el comportamiento de la política de reintentos están documentados en Política de reintentos.

​

channels.discord (transporte del bot)

{
  channels: {
    discord: {
      enabled: true,
      token: "your-bot-token",
      mediaMaxMb: 8, // clamp inbound media size
      allowBots: false, // allow bot-authored messages
      actions: {
        // tool action gates (false disables)
        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
      dm: {
        enabled: true, // disable all DMs when false
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["1234567890", "steipete"], // optional DM allowlist ("open" requires ["*"])
        groupEnabled: false, // enable group DMs
        groupChannels: ["openclaw-dm"], // optional group DM allowlist
      },
      guilds: {
        "123456789012345678": {
          // guild id (preferred) or slug
          slug: "friends-of-openclaw",
          requireMention: false, // per-guild default
          reactionNotifications: "own", // off | own | all | allowlist
          users: ["987654321098765432"], // optional per-guild user allowlist
          channels: {
            general: { allow: true },
            help: {
              allow: true,
              requireMention: true,
              users: ["987654321098765432"],
              skills: ["docs"],
              systemPrompt: "Short answers only.",
            },
          },
        },
      },
      historyLimit: 20, // include last N guild messages as context
      textChunkLimit: 2000, // optional outbound text chunk size (chars)
      chunkMode: "length", // optional chunking mode (length | newline)
      maxLinesPerMessage: 17, // soft max lines per message (Discord UI clipping)
      retry: {
        // outbound retry policy
        attempts: 3,
        minDelayMs: 500,
        maxDelayMs: 30000,
        jitter: 0.1,
      },
    },
  },
}

• off: sin eventos de reacción.
• own: reacciones en los mensajes propios del bot (predeterminado).
• all: todas las reacciones en todos los mensajes.
• allowlist: reacciones de guilds.<id>.users en todos los mensajes (lista vacía deshabilita). El texto saliente se fragmenta por channels.discord.textChunkLimit (predeterminado 2000). Establezca channels.discord.chunkMode="newline" para dividir por líneas en blanco (límites de párrafo) antes de fragmentar por longitud. Los clientes de Discord pueden recortar mensajes muy altos, por lo que channels.discord.maxLinesPerMessage (predeterminado 17) divide respuestas multilínea largas incluso cuando están por debajo de 2000 caracteres. Los valores predeterminados y el comportamiento de la política de reintentos están documentados en Política de reintentos.

​

channels.googlechat (webhook de Chat API)

{
  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", // optional; improves mention detection
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["users/1234567890"], // optional; "open" requires ["*"]
      },
      groupPolicy: "allowlist",
      groups: {
        "spaces/AAAA": { allow: true, requireMention: true },
      },
      actions: { reactions: true },
      typingIndicator: "message",
      mediaMaxMb: 20,
    },
  },
}

• El JSON de la cuenta de servicio puede ser en línea (serviceAccount) o basado en archivo (serviceAccountFile).
• Respaldos de entorno para la cuenta predeterminada: GOOGLE_CHAT_SERVICE_ACCOUNT o GOOGLE_CHAT_SERVICE_ACCOUNT_FILE.
• audienceType + audience deben coincidir con la configuración de autenticación del webhook de la app de Chat.
• Use spaces/<spaceId> o users/<userId|email> al establecer destinos de entrega.

​

channels.slack (modo socket)

{
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      appToken: "xapp-...",
      dm: {
        enabled: true,
        policy: "pairing", // pairing | allowlist | open | disabled
        allowFrom: ["U123", "U456", "*"], // optional; "open" requires ["*"]
        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, // include last N channel/group messages as context (0 disables)
      allowBots: false,
      reactionNotifications: "own", // off | own | all | allowlist
      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,
      },
      textChunkLimit: 4000,
      chunkMode: "length",
      mediaMaxMb: 20,
    },
  },
}

• off: sin eventos de reacción.
• own: reacciones en los mensajes propios del bot (predeterminado).
• all: todas las reacciones en todos los mensajes.
• allowlist: reacciones de channels.slack.reactionAllowlist en todos los mensajes (lista vacía deshabilita).

• channels.slack.thread.historyScope controla si el historial del hilo es por hilo (thread, predeterminado) o compartido en el canal (channel).
• channels.slack.thread.inheritParent controla si las nuevas sesiones de hilo heredan la transcripción del canal padre (predeterminado: false).

​

channels.mattermost (token del bot)

{
  channels: {
    mattermost: {
      enabled: true,
      botToken: "mm-token",
      baseUrl: "https://chat.example.com",
      dmPolicy: "pairing",
      chatmode: "oncall", // oncall | onmessage | onchar
      oncharPrefixes: [">", "!"],
      textChunkLimit: 4000,
      chunkMode: "length",
    },
  },
}

• oncall (predeterminado): responder a mensajes del canal solo cuando se menciona con @.
• onmessage: responder a cada mensaje del canal.
• onchar: responder cuando un mensaje comienza con un prefijo disparador (channels.mattermost.oncharPrefixes, predeterminado [">", "!"]).

• DMs predeterminados: channels.mattermost.dmPolicy="pairing" (los remitentes desconocidos reciben un código de emparejamiento).
• DMs públicos: channels.mattermost.dmPolicy="open" más channels.mattermost.allowFrom=["*"].
• Grupos: channels.mattermost.groupPolicy="allowlist" de forma predeterminada (controlado por menciones). Use channels.mattermost.groupAllowFrom para restringir remitentes.

​

channels.signal (signal-cli)

{
  channels: {
    signal: {
      reactionNotifications: "own", // off | own | all | allowlist
      reactionAllowlist: ["+15551234567", "uuid:123e4567-e89b-12d3-a456-426614174000"],
      historyLimit: 50, // include last N group messages as context (0 disables)
    },
  },
}

• off: sin eventos de reacción.
• own: reacciones en los mensajes propios del bot (predeterminado).
• all: todas las reacciones en todos los mensajes.
• allowlist: reacciones de channels.signal.reactionAllowlist en todos los mensajes (lista vacía deshabilita).

​

channels.imessage (CLI de imsg)

{
  channels: {
    imessage: {
      enabled: true,
      cliPath: "imsg",
      dbPath: "~/Library/Messages/chat.db",
      remoteHost: "user@gateway-host", // SCP for remote attachments when using SSH wrapper
      dmPolicy: "pairing", // pairing | allowlist | open | disabled
      allowFrom: ["+15555550123", "[email protected]", "chat_id:123"],
      historyLimit: 50, // include last N group messages as context (0 disables)
      includeAttachments: false,
      mediaMaxMb: 16,
      service: "auto",
      region: "US",
    },
  },
}

• Requiere Acceso Completo al Disco para la base de datos de Mensajes.
• El primer envío solicitará permiso de automatización de Mensajes.
• Prefiera destinos chat_id:<id>. Use imsg chats --limit 20 para listar chats.
• channels.imessage.cliPath puede apuntar a un script contenedor (p. ej., ssh a otra Mac que ejecute imsg rpc); use claves SSH para evitar solicitudes de contraseña.
• Para contenedores SSH remotos, establezca channels.imessage.remoteHost para obtener adjuntos vía SCP cuando includeAttachments esté habilitado.

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

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skipBootstrap

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

messages

{
  messages: {
    responsePrefix: "🦞", // or "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
    removeAckAfterReply: false,
  },
}

• channels.<channel>.responsePrefix
• channels.<channel>.accounts.<id>.responsePrefix

1. channels.<channel>.accounts.<id>.responsePrefix
2. channels.<channel>.responsePrefix
3. messages.responsePrefix

• undefined cae al siguiente nivel.
• "" deshabilita explícitamente el prefijo y detiene la cascada.
• "auto" deriva [{identity.name}] para el agente enrutado.

​

Variables de plantilla

{
  messages: {
    responsePrefix: "[{model} | think:{thinkingLevel}]",
  },
}

• group-mentions (predeterminado): solo cuando un grupo/sala requiere menciones y el bot fue mencionado
• group-all: todos los mensajes de grupo/sala
• direct: solo mensajes directos
• all: todos los mensajes

​

mensajes.tts

{
  messages: {
    tts: {
      auto: "always", // off | always | inbound | tagged
      mode: "final", // final | all (include tool/block replies)
      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",
        model: "gpt-4o-mini-tts",
        voice: "alloy",
      },
    },
  },
}

• messages.tts.auto controla automáticamente TTS (off, siempre, inbound, tagged).
• /tts apagado|siempre|inbound|tagged establece el modo automático de la sesión permanente (sobreescribe la configuración).
• messages.tts.enabled es legado; doctor lo migra a messages.tts.auto.
• prefsPath almacena anulaciones locales (proveedor/límite/resumen).
• maxTextLength es un tapón duro para la entrada TTS; los resúmenes se truncan para que encajen.
• TextyModel anula agents.defaults.model.primary para autoresumir.
  • Acepta provider/model o un alias de agents.defaults.models.
• modelOverrides habilita anulaciones basadas en modelos como etiquetas [[tts:...]] (por defecto).
• /tts limit y /tts Resumy controlan la configuración de resumen por usuario.
• Los valores apiKey regresan a ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY.
• elevenlabs.baseUrl anula la URL base de la API.
• elevenlabs.voiceSettings soporta stability/similarityBoost/style (0..1), useSpeakerBoost, y speed (0.5..2.0).

​

hablar

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

​

agents.defaults

• alias (atajo de modelo opcional, por ejemplo, /opus).
• params (parámetros API específicos del proveedor opcional pasaron a través de la solicitud del modelo).

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-sonnet-4-5-20250929": {
          params: { temperature: 0.6 },
        },
        "openai/gpt-5. ": {
          parámetros: { maxTokens: 8192 },
        },
      },
    },
  },
}

• establecer --thinking off, o
• defina agents.defaults.models["zai/<model>"].params.thinking usted mismo.

• opus -> antropic/claude-opus-4-6
• sonnet -> anthropic/claude-sonnet-4-5
• gpt -> openai/gpt-5.2
• gpt-mini -> openai/gpt-5-mini
• gemini -> google/gemini-3-pro-preview
• gemini-flash -> google/gemini-3-flash-preview

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.1": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.1"],
      },
    },
  },
}

​

agents.defaults.cliBackends (CLI fallback)

• Los backends de CLI son text-first; las herramientas siempre están deshabilitadas.
• Las sesiones son soportadas cuando sessionArg está establecido; los ids de sesión persisten por backend.
• Para claude-cli, los valores por defecto están conectados. Reemplazar la ruta del comando si PATH es mínimo (launchd/systemd).

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

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "Opus" },
        "anthropic/claude-sonnet-4-1": { alias: "Sonnet" },
        "openrouter/deepseek/deepseek-r1:free": {},
        "zai/glm-4.7": {
          alias: "GLM",
          params: {
            thinking: {
              type: "enabled",
              clear_thinking: false,
            },
          },
        },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: [
          "openrouter/deepseek/deepseek-r1:free",
          "openrouter/meta-llama/llama-3.3-70b-instruct:free",
        ],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      heartbeat: {
        every: "30m",
        target: "last",
      },
      maxConcurrent: 3,
      subagents: {
        model: "minimax/MiniMax-M2.1",
        maxConcurrent: 1,
        archiveAfterMinutes: 60,
      },
      exec: {
        backgroundMs: 10000,
        timeoutSec: 1800,
        cleanupMs: 1800000,
      },
      contextTokens: 200000,
    },
  },
}

​

agents.defaults.contextPruning (tool-result poding)

• Nunca toca los mensajes del usuario/asistente.
• Protege los últimos mensajes de asistente keepLastAssistants (no se podarán los resultados de la herramienta después de ese punto).
• Protege el prefijo de la correa de arranque (nada antes de que el primer mensaje del usuario sea podado).
• Modos:
  • adaptive: resultados de herramientas de gran tamaño (mantener cabeza/tail) cuando la proporción de contexto estimada cruza softTrimRatio. Entonces limpia duramente los resultados de la herramienta elegible más antiguos cuando la proporción de contexto estimada cruza hardClearRatio y hay suficiente granel de resultado de herramientas prunable (minPrunableTools).
  • agresivo: siempre reemplaza los resultados de herramientas elegibles antes del corte con el hardClear.placeholder (sin comprobación de la relación).

• Suave-trim: sólo para los resultados de la herramienta oversized. Mantiene el principio + final e inserta ... en el medio.
  • Before: toolResult("…salida muy larga…")
  • Después: toolResult("HEAD…\n...\n…TAIL\n\n[resultado de la herramienta recortado: …]")
• Hard-clear: reemplaza todo el resultado de la herramienta con el marcador de posición.
  • Before: toolResult("…salida muy larga…")
  • Después: toolResult("[Contenido de la herramienta antigua borrado]")

• Los resultados de la herramienta que contienen bloques de imagen son omitidos (nunca borrados) ahora mismo.
• La “relación de contexto” estimada se basa en caracteres (aproximadamente), no en tokens exactos.
• Si la sesión no contiene al menos mensajes de asistente de keepLastAssistants todavía, se omite la poda.
• En modo agresivo, hardClear.enabled es ignorado (los resultados de herramientas elegibles siempre son reemplazados por hardClear.placeholder).

{
  agents: { defaults: { contextPruning: { mode: "adaptive" } },
}

{
  agents: { defaults: { contextPruning: { mode: "off" } },
}

• keepLastAssistants: 3
• softTrimRatio: 0.3 (sólo adaptativo)
• hardClearRatio: 0.5 (sólo adaptativo)
• minPrunableToolChars: 50000 (sólo adaptativo)
• softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 } (solo adaptativo)
• hardClear: { enabled: true, placeholder: "[Old tool result content cleared]" }

{
  agents: { defaults: { contextPruning: { mode: "aggressive" } } },
}

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "adaptive",
        keepLastAssistants: 3,
        softTrimRatio: 0. ,
        Relación de cierre duro: 0. ,
        minPrunableToolChars: 50000,
        softTrim: { maxChars: 4000, headChars: 1500, tailChars: 1500 },
        hardClear: { enabled: true, marcador de posición: "[Contenido de resultado de la herramienta antigua eliminado]" },
        // Opcional: restringir la poda a herramientas específicas (negar ganancias; soporta "*" comodín)
        herramientas: { deny: ["browser", "canvas"] },
      },
    },
  },
}

​

agents.defaults.compaction (reserva cabecera + memoria de flush)

• memoryFlush.enabled: true
• memoryFlush.softThresholdTokens: 4000
• memoryFlush.prompt / memoryFlush.systemPrompt: predeterminado integrado con NO_REPLY
• Nota: la descarga de memoria se omite cuando el espacio de trabajo de sesión es de solo lectura (agents.defaults.sandbox.workspaceAccess: "ro" o "ninguno").

{
  agents: {
    defaults: {
      compaction: {
        mode: "salvaguard",
        reserveTokensFloor: 24000,
        memoryFlush: {
          habilitado: true,
          soft ThresholdTokens: 6000,
          systemPrompt: "Sesión cerca de la compacción. Almacena recuerdos duraderos ahora.",
          indica: "Escribe cualquier nota duradera para memorar/AAA-MM-DD. d; responder con NO_REPLY si no hay nada que almacenar. ,
        },
      },
    },
  },
}

• agents.defaults.blockStreamingDefault: "on"/"off" (desactivado por defecto).
• Anulaciones del canal: *.blockStreaming (y variantes por cuenta) para bloquear el streaming activado/apagado. Los canales que no sean de Telegram requieren un *.blockStreaming: true explícito para habilitar las respuestas de bloques.
• agents.defaults.blockStreamingBreak: "text_end" o "message_end" (por defecto: text_end).
• agents.defaults.blockStreamingChunk: chunking suave para bloques streamed. Por defecto es 800–1200 caracteres, prefiere saltos de párrafo (\n\n), luego nuevas líneas, luego frases. Ejemplo:
  {
    agents: { defaults: { blockStreamingChunk: { minChars: 800, maxChars: 1200 } } },
  }
  
• agents.defaults.blockStreamingCoalesce: combina bloques streaming antes de enviar. Por defecto es { idleMs: 1000 } y hereda minChars de blockStreamingChunk con maxChars limitado al límite de texto del canal. Signal/Slack/Discord/Google Chat predeterminado a minChars: 1500 a menos que sea reemplazado. Anulaciones del canal: channels.whatsapp.blockStreamingCoalesce, channels.telegram.blockStreamingCoalesce, channels.discord.blockStreamingCoalesce, channels.slack.blockStreamingCoalesce, channels.msteams.blockStreamingCoalesce, channels.signal.blockStreamingCoalesce, channels.imessage.blockStreamingCoalesce, channels.msteamingCoalesce, channels.googlechat.blockStreamingCoalesce (y variantes de la cuenta).
• agents.defaults.humanDelay: pausa aleatoriamente entre respuestas de bloque después de la primera. Modos: off (por defecto), natural (800–2500ms), custom (usa minMs/maxMs). Por agente anular: agents.list[].humanDelay. Ejemplo:
  {
    agents: { defaults: { humanDelay: { mode: "natural" } } },
  }
  
  Vea /concepts/streaming para el comportamiento + detalles de chunking.

• agents.defaults.typingMode: "nunca" | "instantáneo" | "pensando" | "mensaje". Por defecto instantáneo para chats directos / menciones y mensaje para chats de grupo no mencionados.
• session.typingMode: sobreescritura por sesión para el modo.
• agents.defaults.typingIntervalSeconds: con qué frecuencia se actualiza la señal de escritura (por defecto: 6s).
• session.typingIntervalSegundos: sobreescritura por sesión para el intervalo de actualización. Vea /concepts/typing-indicators para detalles de comportamiento.

• cada: cadena de duración (ms, s, m, h); minutos unitarios por defecto. Predeterminado: 30m. Establece 0m para desactivar.
• model: modelo opcional de anulación para ejecuciones de heartbeat (provider/model).
• includeReasoning: cuando true, heartbeats también entregará el mensaje separado Reasoning: cuando esté disponible (misma forma que /reasoning on). Predeterminado: false.
• session: tecla opcional de sesión para controlar en qué sesión se ejecuta el latido del corazón. Por defecto: main.
• to: reemplazo opcional del destinatario (id específico del canal, p.e. E.164 para WhatsApp, id del chat para Telegram).
• target: canal opcional de entrega (last, whatsapp, telegram, discord, slack, msteams, signal, imessage, ninguno). Predeterminado: last.
• prompt: sobreescritura opcional para el cuerpo del latido del corazón (por defecto: Leer HEARTBEAT.md si existe (contexto del espacio de trabajo). Follow it strictly. Do not infer or repeat old tasks from prior chats. If nothing needs attention, reply HEARTBEAT_OK.). Los overrides se envían literalmente; incluye una línea Read HEARTBEAT.md si quieres que el archivo lea.
• ackMaxChars: caracteres máximos permitidos después de HEARTBEAT_OK antes de la entrega (por defecto: 300).

• Establece agents.list[].heartbeat para activar o anular la configuración de latido cardíaco para un agente específico.
• Si cualquier entrada de agente define heartbeat, solo esos agentes ejecutan heartbeats; por defecto se convierte en la línea base compartida para esos agentes.

• backgroundMs: tiempo antes del auto-background (ms, predeterminado 10000)
• timeoutSec: auto-kill después de este tiempo de ejecución (segundos, por defecto 1800)
• cleanupMs: cuánto tiempo mantener las sesiones terminadas en memoria (ms, por defecto 18000)
• notifyOnExit: encolar un evento del sistema + solicitar latido al salir en segundo plano de exec (por defecto true)
• applyPatch.enabled: habilita el apply_patch experimental (sólo OpenAI/OpenAI Codex; por defecto falso)
• applyPatch.allowModels: lista permitida opcional de ids de modelo (por ejemplo, gpt-5.2 o openai/gpt-5.2) Nota: applyPatch sólo está bajo tools.exec.

• tools.web.search.enabled (por defecto: verdadero cuando la clave está presente)
• tools.web.search.apiKey (recomendado: establece a través de openclaw configure --section web, o usa BRAVE_API_KEY var)
• tools.web.search.maxResults (1–10, por defecto 5)
• tools.web.search.timeoutSeconds (predeterminado 30)
• tools.web.search.cacheTtlMinutes (predeterminado 15)
• tools.web.fetch.enabled (por defecto true)
• tools.web.fetch.maxChars (predeterminado 50000)
• tools.web.fetch.maxCharsCap (por defecto 50000; clampa maxChars de las llamadas config/tools)
• tools.web.fetch.timeoutSeconds (predeterminado 30)
• tools.web.fetch.cacheTtlMinutes (predeterminado 15)
• tools.web.fetch.userAgent (anulación opcional)
• tools.web.fetch.readability (por defecto true; deshabilita para usar sólo limpieza básica de HTML)
• tools.web.fetch.firecrawl.enabled (por defecto es verdad cuando se establece una clave API)
• tools.web.fetch.firecrawl.apiKey (opcional; por defecto FIRECRAWL_API_KEY)
• tools.web.fetch.firecrawl.baseUrl (por defecto https://api.firecrawl.dev)
• tools.web.fetch.firecrawl.onlyMainContent (por defecto true)
• tools.web.fetch.firecrawl.maxAgeMs (opcional)
• tools.web.fetch.firecrawl.timeoutSeconds (opcional)

• tools.media.models: lista de modelos compartidos (capacidad etiquetada; usada después de listas por cap).
• tools.media.concurrency: ejecución máxima de capacidad concurrente (por defecto 2).
• tools.media.image / tools.media.audio / tools.media.video:
  • enabled: opt-out switch (predeterminado verdadero cuando los modelos están configurados).
  • prompt: opción de anulación del prompt (imagen/video añade una pista de maxChars automáticamente).
  • maxChars: caracteres de salida máximos (por defecto 500 para imagen/vídeo; unset para audio).
  • maxBytes: tamaño máximo de medios a enviar (por defecto: imagen 10MB, audio 20MB, vídeo 50MB).
  • timeoutSegundos: timeout de solicitud (por defecto: imagen 60s, audio 60s, video 120s).
  • language: pista de audio opcional.
  • attachments: política de adjuntos (mode, maxAttachments, prefer).
  • scope: compuerta opcional (primero coincide con ganancias) con match.channel, match.chatType, o match.keyPrefix.
  • models: lista ordenada de entradas de modelo; fallos o soportes sobredimensionados caen en la siguiente entrada.
• Cada entrada modelos[]:
  • Entrada del proveedor (type: "provider" o omitido):
    • provider: API provider id (openai, anthropic, google/gemini, groq, etc).
    • model: model id override (requerido para la imagen; predeterminado para gpt-4o-mini-transcribe/whisper-(0)[video] v3-turbo para proveedores de audio, y gemini-3-flash-preview para video).
    • profile / preferredProfile: selección de perfil de autor.
  • Entrada CLI (type: "cli"):
    • command: ejecutable a ejecutar.
    • args: argumentos con plantillas (soporta {{MediaPath}}, {{Prompt}}, {{MaxChars}}, etc).
  • capabilities: lista opcional (image, audio, video) para comprimir una entrada compartida. Por defecto al omitir: openai/anthropic/minimax → imagen, google → image+audio+video, groq → audio.
  • prompt, maxChars, maxBytes, timeoutSegundds, language puede ser anulado por entrada.

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

• model: modelo predeterminado para los subagentes generados (cadena o { primary, fallbacks }). Si se omite, los subagentes heredan el modelo de la persona que llama a menos que se sobreescriba por agente o por llamada.
• maxConcurrent: ejecución máxima de sub-agente simultáneo (por defecto 1)
• archiveAfterMinutes: sesiones de sub-agente autoarchivadas después de N minutos (por defecto 60; establece 0 a desactivar)
• Política de herramientas por subagente: tools.subagents.tools.allow / tools.subagents.tools.deny (negar victorias)

• 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 restricción (igual que no configurado)

{
  tools: {
    profile: "messaging",
    allow: ["slack", "discord"],
  },
}

{
  tools: {
    profile: "coding",
    deny: ["group:runtime"],
  },
}

{
  tools: {
    profile: "coding",
    byProvider: {
      "google-antigravity": { profile: "minimal" },
    },
  },
}

{
  tools: {
    allow: ["group:fs", "group:runtime", "sessions_list"],
    byProvider: {
      "openai/gpt-5.2": { allow: ["group:fs", "sessions_list"] },
    },
  },
}

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

• group:runtime: exec, bash, process
• 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 de OpenClaw (excluye plugins de proveedores)

• activado: permitir modo elevado (por defecto verdadero)
• allowFrom: listas permitidas por canal (vacío = deshabilitado)
  • whatsapp: E.164 números
  • telegram: identificadores de chat o nombres de usuario
  • discord: identificadores de usuario o nombres de usuario (se repite a channels.discord.dm.allowFrom si se omite)
  • signal: E.164 números
  • imessage: manejadores/identificadores de chat
  • webchat: identificadores de sesión o nombres de usuario

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

{
  agents: {
    list: [
      {
        id: "family", Herramientas
        : {
          elevado: { enabled: false },
        },
      },
    ],
  },
}

• tools.elevated es la línea de base global. agents.list[].tools.elevated sólo puede restringir aún más (ambos deben permitir).
• /elevated on|off|ask|full almacena el estado por clave de sesión; las directivas en línea se aplican a un solo mensaje.
• Ejecutado exec se ejecuta en el anfitrión y evita el sandboxing.
• La política de herramientas sigue aplicándose; si exec es negada, no se puede usar elevado.

​

agents.defaults.sandbox

• scope: "agent" (un contenedor + espacio de trabajo por agente)
• Imagen basada en gusanos de libros de Debian
• agente de acceso al espacio de trabajo: workspaceAccess: "None " (por defecto)
  • "ninguno ": usa un espacio de trabajo sandbox por ámbito bajo ~/.openclaw/sandboxes
• "ro": mantén el espacio de trabajo del entorno de pruebas en /workspace, y monta el espacio de trabajo del agente sólo en /agent (desactiva write/edit/apply_patch)
  • "rw": montar el área de trabajo del agente leer/escribir en /workspace
• poda automática: inactivo > 24 h O antigüedad > 7 d
• política de herramientas: permitir sólo exec, process, read, write, edit, apply_patch, sessions_list, sessions_history, sessions_send, sessions_spawn, session_status (denegar victorias)
  • configure a través de tools.sandbox.tools, sobreescribe por agente a través de agents.list[].tools.sandbox.tools
  • grupos de herramientas soportados en la política de sandbox: group:runtime, group:fs, group:sessions, group:memory (ver Sandbox vs Tool Policy vs Applicated)
• navegador opcional de arena (Chromium + CDP, observador noVNC)
• knobs: network, user, pidsLimit, memory, cpus, ulimits, seccompProfile, apparmorProfile