Configuración — agentes

Claves de configuración con alcance de agente bajo agents.*, multiAgent.*, session.*, messages.* y talk.*. Para canales, herramientas, el runtime del Gateway y otras claves de nivel superior, consulta Referencia de configuración.

# Valores predeterminados de agente

# agents.defaults.workspace

Valor predeterminado: ~/.openclaw/workspace.

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

# agents.defaults.repoRoot

Raíz de repositorio opcional mostrada en la línea Runtime del prompt del sistema. Si no se establece, OpenClaw la detecta automáticamente subiendo desde el espacio de trabajo.

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

# agents.defaults.skills

Lista de permitidos predeterminada opcional de Skills para agentes que no establecen agents.list[].skills.

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

• Omite agents.defaults.skills para permitir Skills sin restricciones de forma predeterminada.
• Omite agents.list[].skills para heredar los valores predeterminados.
• Establece agents.list[].skills: [] para no usar Skills.
• Una lista no vacía de agents.list[].skills es el conjunto final para ese agente; no se combina con los valores predeterminados.

# agents.defaults.skipBootstrap

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

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

# agents.defaults.skipOptionalBootstrapFiles

Omite la creación de archivos opcionales seleccionados del espacio de trabajo sin dejar de escribir los archivos de arranque requeridos. Valores válidos: SOUL.md, USER.md, HEARTBEAT.md e IDENTITY.md.

{
  agents: {
    defaults: {
      skipOptionalBootstrapFiles: ["SOUL.md", "USER.md"],
    },
  },
}

# agents.defaults.contextInjection

Controla cuándo se inyectan los archivos de arranque del espacio de trabajo en el prompt del sistema. Valor predeterminado: "always".

• "continuation-skip": los turnos de continuación seguros (después de una respuesta completada del asistente) omiten la reinyección del arranque del espacio de trabajo, lo que reduce el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a la Compaction siguen reconstruyendo el contexto.
• "never": desactiva el arranque del espacio de trabajo y la inyección de archivos de contexto en cada turno. Usa esto solo para agentes que controlan por completo el ciclo de vida de su prompt (motores de contexto personalizados, runtimes nativos que construyen su propio contexto o flujos de trabajo especializados sin arranque). Los turnos de Heartbeat y de recuperación de Compaction también omiten la inyección.

{
  agents: { defaults: { contextInjection: "continuation-skip" } },
}

# agents.defaults.bootstrapMaxChars

Máximo de caracteres por archivo de arranque del espacio de trabajo antes del truncamiento. Valor predeterminado: 12000.

{
  agents: { defaults: { bootstrapMaxChars: 12000 } },
}

# agents.defaults.bootstrapTotalMaxChars

Máximo total de caracteres inyectados entre todos los archivos de arranque del espacio de trabajo. Valor predeterminado: 60000.

{
  agents: { defaults: { bootstrapTotalMaxChars: 60000 } },
}

# agents.defaults.bootstrapPromptTruncationWarning

Controla el aviso visible para el agente en el prompt del sistema cuando se trunca el contexto de arranque. Valor predeterminado: "once".

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

Los recuentos detallados sin procesar/inyectados y los campos de ajuste de configuración permanecen en diagnósticos como informes de contexto/estado y registros; el contexto rutinario de usuario/runtime de WebChat solo recibe el aviso conciso de recuperación.

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

# Mapa de propiedad del presupuesto de contexto

OpenClaw tiene varios presupuestos de prompt/contexto de alto volumen, y están divididos intencionalmente por subsistema en lugar de pasar todos por una única opción genérica.

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: inyección normal del arranque del espacio de trabajo.
• agents.defaults.startupContext.*: preámbulo único de ejecución de modelo en reinicio/arranque, incluidos archivos recientes diarios memory/*.md. Los comandos de chat simples /new y /reset se confirman sin invocar el modelo.
• skills.limits.*: la lista compacta de Skills inyectada en el prompt del sistema.
• agents.defaults.contextLimits.*: extractos acotados de runtime y bloques inyectados propiedad del runtime.
• memory.qmd.limits.*: tamaño de fragmentos de búsqueda de memoria indexada e inyección.

Usa la sobrescritura por agente correspondiente solo cuando un agente necesita un presupuesto diferente:

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].contextLimits.*

# agents.defaults.startupContext

Controla el preámbulo de arranque del primer turno que se inyecta en ejecuciones de modelo de reinicio/arranque. Los comandos de chat simples /new y /reset confirman el reinicio sin invocar el modelo, por lo que no cargan este preámbulo.

{
  agents: {
    defaults: {
      startupContext: {
        enabled: true,
        applyOn: ["new", "reset"],
        dailyMemoryDays: 2,
        maxFileBytes: 16384,
        maxFileChars: 1200,
        maxTotalChars: 2800,
      },
    },
  },
}

# agents.defaults.contextLimits

Valores predeterminados compartidos para superficies acotadas de contexto de runtime.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: límite predeterminado del extracto de memory_get antes de que se agreguen metadatos de truncamiento y aviso de continuación.
• memoryGetDefaultLines: ventana de líneas predeterminada de memory_get cuando se omite lines.
• toolResultMaxChars: límite de resultados de herramientas en vivo usado para resultados persistidos y recuperación de desbordamiento.
• postCompactionMaxChars: límite de extracto de AGENTS.md usado durante la inyección de actualización posterior a la Compaction.

# agents.list[].contextLimits

Sobrescritura por agente para las opciones compartidas de contextLimits. Los campos omitidos heredan de agents.defaults.contextLimits.

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        toolResultMaxChars: 16000,
      },
    },
    list: [
      {
        id: "tiny-local",
        contextLimits: {
          memoryGetMaxChars: 6000,
          toolResultMaxChars: 8000,
        },
      },
    ],
  },
}

# skills.limits.maxSkillsPromptChars

Límite global para la lista compacta de Skills inyectada en el prompt del sistema. Esto no afecta la lectura de archivos SKILL.md bajo demanda.

{
  skills: {
    limits: {
      maxSkillsPromptChars: 18000,
    },
  },
}

# agents.list[].skillsLimits.maxSkillsPromptChars

Sobrescritura por agente para el presupuesto del prompt de Skills.

{
  agents: {
    list: [
      {
        id: "tiny-local",
        skillsLimits: {
          maxSkillsPromptChars: 6000,
        },
      },
    ],
  },
}

# agents.defaults.imageMaxDimensionPx

Tamaño máximo en píxeles del lado más largo de una imagen en bloques de imagen de transcripción/herramienta antes de las llamadas al proveedor. Valor predeterminado: 1200.

Los valores más bajos suelen reducir el uso de tokens de visión y el tamaño de la carga útil de la solicitud en ejecuciones con muchas capturas de pantalla. Los valores más altos conservan más detalle visual.

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

# agents.defaults.userTimezone

Zona horaria para el contexto del prompt del sistema (no para las marcas de tiempo de los mensajes). Recurre a la zona horaria del host.

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

# agents.defaults.timeFormat

Formato de hora en el prompt del sistema. Valor predeterminado: auto (preferencia del SO).

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

# agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.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-2",
        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
      agentRuntime: {
        id: "pi", // pi | auto | registered harness id, e.g. codex
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "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 modelos de conmutación por error 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 reserva cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen.
  • Prefiere referencias provider/model explícitas. Los ID simples se aceptan por compatibilidad; si un ID simple coincide de forma única con una entrada configurada compatible con imágenes en models.providers.*.models, OpenClaw lo califica para ese proveedor. Las coincidencias configuradas ambiguas requieren un prefijo de proveedor explícito.
• imageGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de imágenes y cualquier superficie futura de herramienta/Plugin que genere imágenes.
  • Valores típicos: google/gemini-3.1-flash-image-preview para generación nativa de imágenes de Gemini, fal/fal-ai/flux/dev para fal, openai/gpt-image-2 para OpenAI Images, o openai/gpt-image-1.5 para salida OpenAI PNG/WebP con fondo transparente.
  • Si seleccionas un proveedor/modelo directamente, configura también la autenticación de proveedor correspondiente (por ejemplo, GEMINI_API_KEY o GOOGLE_API_KEY para google/*, OPENAI_API_KEY u OpenAI Codex OAuth para openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY para fal/*).
  • Si se omite, image_generate todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los proveedores registrados restantes de generación de imágenes en orden de ID de proveedor.
• musicGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de música y la herramienta integrada music_generate.
  • Valores típicos: google/lyria-3-clip-preview, google/lyria-3-pro-preview o minimax/music-2.6.
  • Si se omite, music_generate todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los proveedores registrados restantes de generación de música en orden de ID de proveedor.
  • Si seleccionas un proveedor/modelo directamente, configura también la autenticación/clave de API de proveedor correspondiente.
• videoGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de video y la herramienta integrada video_generate.
  • 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.
  • Si se omite, video_generate todavía puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y luego los proveedores registrados restantes de generación de video en orden de ID de proveedor.
  • Si seleccionas un proveedor/modelo directamente, configura también la autenticación/clave de API de proveedor correspondiente.
  • El proveedor integrado de generación de video Qwen admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, 10 segundos de duración y opciones de 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 sesión/predeterminado.
• pdfMaxBytesMb: límite predeterminado de tamaño de PDF para la herramienta pdf cuando no se pasa maxBytesMb en el momento de la llamada.
• pdfMaxPages: páginas máximas predeterminadas consideradas por el modo de reserva de extracción en la herramienta pdf.
• verboseDefault: nivel detallado predeterminado para agentes. Valores: "off", "on", "full". Predeterminado: "off".
• toolProgressDetail: modo de detalle para los resúmenes de herramientas de /verbose y las líneas de herramienta de borrador de progreso. Valores: "explain" (predeterminado, etiquetas humanas compactas) o "raw" (añade comando/detalle sin procesar cuando está disponible). agents.list[].toolProgressDetail por agente reemplaza este valor predeterminado.
• reasoningDefault: visibilidad de razonamiento predeterminada para agentes. Valores: "off", "on", "stream". agents.list[].reasoningDefault por agente reemplaza este valor predeterminado. Los valores predeterminados de razonamiento configurados solo se aplican para propietarios, remitentes autorizados o contextos Gateway de administrador-operador cuando no está establecida una anulación de razonamiento por mensaje o por sesión.
• elevatedDefault: nivel predeterminado de salida elevada para agentes. Valores: "off", "on", "ask", "full". Predeterminado: "on".
• model.primary: formato provider/model (p. ej., openai/gpt-5.5 para acceso con clave de API de OpenAI o Codex OAuth). Si omites el proveedor, OpenClaw prueba primero un alias, luego una coincidencia única de proveedor configurado para ese ID de modelo exacto, y solo después recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto, 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 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, responsesServerCompaction, responsesCompactThreshold, chat_template_kwargs, extra_body/extraBody).
  • Ediciones seguras: usa openclaw config set agents.defaults.models '<json>' --strict-json --merge para añadir entradas. config set rechaza reemplazos que eliminarían entradas existentes de la lista de permitidos a menos que pases --replace.
  • Los flujos de configuración/incorporación con ámbito de proveedor combinan los modelos de proveedor seleccionados en este mapa y conservan los proveedores no relacionados ya configurados.
  • Para modelos directos de OpenAI Responses, la Compaction del lado del servidor se habilita automáticamente. Usa params.responsesServerCompaction: false para dejar de inyectar context_management, o params.responsesCompactThreshold para anular el umbral. Consulta Compaction del lado del servidor de OpenAI.
• params: parámetros de proveedor predeterminados globales aplicados a todos los modelos. Se establecen en agents.defaults.params (p. ej., { cacheRetention: "long" }).
• Precedencia de combinación de params (configuración): agents.defaults.params (base global) es reemplazado por agents.defaults.models["provider/model"].params (por modelo), luego agents.list[].params (ID de agente coincidente) reemplaza por clave. Consulta Caché de prompts para obtener detalles.
• params.extra_body/params.extraBody: JSON avanzado de paso directo combinado en cuerpos de solicitud api: "openai-completions" para proxies compatibles con OpenAI. Si colisiona con claves de solicitud generadas, el cuerpo extra gana; las rutas de completions no nativas siguen eliminando después store exclusivo de OpenAI.
• params.chat_template_kwargs: argumentos de plantilla de chat compatibles con vLLM/OpenAI combinados en cuerpos de solicitud de nivel superior api: "openai-completions". Para vllm/nemotron-3-* con pensamiento desactivado, el Plugin vLLM integrado envía automáticamente enable_thinking: false y force_nonempty_content: true; chat_template_kwargs explícito reemplaza los valores predeterminados generados, y extra_body.chat_template_kwargs sigue teniendo la precedencia final. Para controles de pensamiento de vLLM Qwen, establece params.qwenThinkingFormat en "chat-template" o "top-level" en esa entrada de modelo.
• compat.supportedReasoningEfforts: lista de esfuerzo de razonamiento compatible con OpenAI por modelo. Incluye "xhigh" para endpoints personalizados que realmente lo acepten; OpenClaw entonces expone /think xhigh en menús de comandos, filas de sesión de Gateway, validación de parches de sesión, validación de CLI de agente y validación de llm-task para ese proveedor/modelo configurado. Usa compat.reasoningEffortMap cuando el backend quiera un valor específico del proveedor para un nivel canónico.
• params.preserveThinking: opción de Z.AI para conservar pensamiento. Cuando está habilitada y el pensamiento está activado, OpenClaw envía thinking.clear_thinking: false y reproduce reasoning_content anterior; consulta pensamiento y pensamiento conservado de Z.AI.
• agentRuntime: política predeterminada de bajo nivel de tiempo de ejecución del agente. El ID omitido usa OpenClaw Pi de forma predeterminada. Usa id: "pi" para forzar el arnés PI integrado, id: "auto" para permitir que los arneses de Plugin registrados reclamen modelos compatibles y usar PI cuando ninguno coincida, un ID de arnés registrado como id: "codex" para requerir ese arnés, o un alias de backend CLI compatible como id: "claude-cli". Los tiempos de ejecución de Plugin explícitos fallan de forma cerrada cuando el arnés no está disponible o falla. Mantén las referencias de modelos canónicas como provider/model; selecciona Codex, Claude CLI, Gemini CLI y otros backends de ejecución mediante la configuración de tiempo de ejecución en lugar de prefijos heredados de proveedor de tiempo de ejecución. Consulta Tiempos de ejecución de agente para ver en qué se diferencia esto de la selección de proveedor/modelo.
• Los escritores de configuración que mutan estos campos (por ejemplo, /models set, /models set-image y comandos para añadir/eliminar reservas) guardan la forma canónica de objeto y conservan las listas de reserva existentes cuando es posible.
• maxConcurrent: máximo de ejecuciones paralelas de agente entre sesiones (cada sesión sigue serializada). Predeterminado: 4.

# agents.defaults.agentRuntime

agentRuntime controla qué ejecutor de bajo nivel ejecuta los turnos del agente. La mayoría de las implementaciones deben mantener el tiempo de ejecución OpenClaw Pi predeterminado. Úsalo cuando un Plugin de confianza proporcione un arnés nativo, como el arnés de servidor de aplicación Codex integrado, o cuando quieras un backend CLI compatible como Claude CLI. Para el modelo mental, consulta Tiempos de ejecución de agente.

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      agentRuntime: {
        id: "codex",
      },
    },
  },
}

• id: "auto", "pi", un ID de arnés de Plugin registrado o un alias de backend CLI compatible. El Plugin Codex integrado registra codex; el Plugin Anthropic integrado proporciona el backend CLI claude-cli.
• id: "auto" permite que los arneses de Plugin registrados reclamen turnos compatibles y usa PI cuando no coincide ningún arnés. Un tiempo de ejecución de Plugin explícito como id: "codex" requiere ese arnés y falla de forma cerrada si no está disponible o falla.
• Anulación de entorno: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> anula id para ese proceso.
• Los modelos de agente de OpenAI usan el arnés Codex de forma predeterminada; agentRuntime.id: "codex" sigue siendo válido cuando quieres hacerlo explícito.
• Para implementaciones de Claude CLI, prefiere model: "anthropic/claude-opus-4-7" más agentRuntime.id: "claude-cli". Las referencias de modelo heredadas claude-cli/claude-opus-4-7 siguen funcionando por compatibilidad, pero la configuración nueva debe mantener canónica la selección de proveedor/modelo y poner el backend de ejecución en agentRuntime.id.
• Las claves antiguas de política de tiempo de ejecución son reescritas a agentRuntime por openclaw doctor --fix.
• La elección del arnés queda fijada por ID de sesión después de la primera ejecución integrada. Los cambios de configuración/entorno afectan a sesiones nuevas o reiniciadas, no a una transcripción existente. Las sesiones heredadas de OpenAI con historial de transcripción pero sin pin registrado usan Codex; los pines obsoletos de OpenAI PI se pueden reparar con openclaw doctor --fix. /status informa el tiempo de ejecución efectivo, por ejemplo Runtime: OpenClaw Pi Default o Runtime: OpenAI Codex.
• Esto solo controla la ejecución de turnos de agente de texto. La generación de medios, visión, PDF, música, video y TTS siguen usando su configuración de proveedor/modelo.

Atajos de alias integrados (solo se aplican cuando el modelo está en agents.defaults.models):

Tus alias configurados siempre prevalecen sobre los valores predeterminados.

Los modelos Z.AI GLM-4.x activan automáticamente el modo de razonamiento salvo que configures --thinking off o definas agents.defaults.models["zai/<model>"].params.thinking por tu cuenta. Los modelos Z.AI activan tool_stream de forma predeterminada para la transmisión de llamadas a herramientas. Configura agents.defaults.models["zai/<model>"].params.tool_stream en false para desactivarlo. Los modelos Anthropic Claude 4.6 usan adaptive como razonamiento predeterminado cuando no se establece un nivel de razonamiento explícito.

# agents.defaults.cliBackends

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

{
  agents: {
    defaults: {
      cliBackends: {
        "codex-cli": {
          command: "/opt/homebrew/bin/codex",
        },
        "my-cli": {
          command: "my-cli",
          args: ["--json"],
          output: "json",
          modelArg: "--model",
          sessionArg: "--session",
          sessionMode: "existing",
          systemPromptArg: "--system",
          // Or use systemPromptFileArg when the CLI accepts a prompt file flag.
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Los backends de CLI priorizan el texto; las herramientas siempre están desactivadas.
• Se admiten sesiones cuando sessionArg está configurado.
• Se admite el paso directo de imágenes cuando imageArg acepta rutas de archivos.

# agents.defaults.systemPromptOverride

Reemplaza todo el prompt del sistema ensamblado por OpenClaw con una cadena fija. Configúralo en el nivel predeterminado (agents.defaults.systemPromptOverride) o por agente (agents.list[].systemPromptOverride). Los valores por agente tienen prioridad; se ignora un valor vacío o que solo contenga espacios en blanco. Útil para experimentos de prompt controlados.

{
  agents: {
    defaults: {
      systemPromptOverride: "You are a helpful assistant.",
    },
  },
}

# agents.defaults.promptOverlays

Superposiciones de prompt independientes del proveedor aplicadas por familia de modelos. Los identificadores de modelos de la familia GPT-5 reciben el contrato de comportamiento compartido entre proveedores; personality controla solo la capa de estilo de interacción amigable.

{
  agents: {
    defaults: {
      promptOverlays: {
        gpt5: {
          personality: "friendly", // friendly | on | off
        },
      },
    },
  },
}

• "friendly" (predeterminado) y "on" activan la capa de estilo de interacción amigable.
• "off" desactiva solo la capa amigable; el contrato de comportamiento GPT-5 etiquetado permanece activado.
• El valor heredado plugins.entries.openai.config.personality todavía se lee cuando esta configuración compartida no está definida.

# agents.defaults.heartbeat

Ejecuciones periódicas de Heartbeat.

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m disables
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // default: true; false omits the Heartbeat section from the system prompt
        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)
        skipWhenBusy: false, // default: false; true also waits for subagent/nested lanes
        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,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: cadena de duración (ms/s/m/h). Predeterminado: 30m (autenticación con clave de API) o 1h (autenticación OAuth). Configúralo en 0m para desactivarlo.
• includeSystemPromptSection: cuando es false, omite la sección Heartbeat del prompt del sistema y omite la inyección de HEARTBEAT.md en el contexto de arranque. Predeterminado: true.
• suppressToolErrorWarnings: cuando es true, suprime las cargas útiles de advertencia de errores de herramientas durante las ejecuciones de Heartbeat.
• timeoutSeconds: tiempo máximo en segundos permitido para un turno de agente de Heartbeat antes de abortarlo. Déjalo sin configurar para usar agents.defaults.timeoutSeconds.
• directPolicy: política de entrega directa/DM. allow (predeterminado) permite la entrega a destino directo. block suprime la entrega a destino directo y emite reason=dm-blocked.
• lightContext: cuando es true, las ejecuciones de Heartbeat usan contexto de arranque ligero y conservan solo HEARTBEAT.md de los archivos de arranque del espacio de trabajo.
• isolatedSession: cuando es true, cada Heartbeat se ejecuta en una sesión nueva sin historial de conversación previo. El mismo patrón de aislamiento que sessionTarget: "isolated" de Cron. Reduce el costo de tokens por Heartbeat de ~100K a ~2-5K tokens.
• skipWhenBusy: cuando es true, las ejecuciones de Heartbeat se aplazan en carriles ocupados adicionales: trabajo de subagente o comando anidado. Los carriles de Cron siempre aplazan los Heartbeats, incluso sin esta marca.
• Por agente: configura agents.list[].heartbeat. Cuando cualquier 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
        provider: "my-provider", // id of a registered compaction provider plugin (optional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        keepRecentTokens: 50000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // used when identifierPolicy=custom
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional Pi tool-loop pressure check
        postCompactionSections: ["Session Startup", "Red Lines"], // [] disables reinjection
        model: "openrouter/anthropic/claude-sonnet-4-6", // optional compaction-only model override
        truncateAfterCompaction: true, // rotate to a smaller successor JSONL after compaction
        maxActiveTranscriptBytes: "20mb", // optional preflight local compaction trigger
        notifyUser: true, // send brief notices when compaction starts and completes (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          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 fragmentos para historiales largos). Consulta Compaction.
• provider: identificador de un Plugin proveedor de Compaction registrado. Cuando se configura, se llama a summarize() del proveedor en lugar del resumen LLM integrado. Recurre al integrado si falla. Configurar un proveedor fuerza mode: "safeguard". Consulta Compaction.
• timeoutSeconds: segundos máximos permitidos para una sola operación de Compaction antes de que OpenClaw la aborte. Predeterminado: 900.
• keepRecentTokens: presupuesto de punto de corte de Pi para conservar literalmente la cola más reciente de la transcripción. /compact manual respeta esto cuando se configura explícitamente; de lo contrario, la Compaction manual es un punto de control rígido.
• identifierPolicy: strict (predeterminado), off o custom. strict antepone orientación integrada para la retención de identificadores opacos durante el resumen de Compaction.
• identifierInstructions: texto personalizado opcional de preservación de identificadores usado cuando identifierPolicy=custom.
• qualityGuard: comprobaciones de reintento ante salida mal formada para resúmenes de salvaguarda. Activado de forma predeterminada en modo de salvaguarda; configura enabled: false para omitir la auditoría.
• midTurnPrecheck: comprobación opcional de presión del bucle de herramientas de Pi. Cuando enabled: true, OpenClaw comprueba la presión del contexto después de anexar los resultados de herramientas y antes de la siguiente llamada al modelo. Si el contexto ya no cabe, aborta el intento actual antes de enviar el prompt y reutiliza la ruta de recuperación de precomprobación existente para truncar los resultados de herramientas o compactar y reintentar. Funciona con los modos de Compaction default y safeguard. Predeterminado: desactivado.
• postCompactionSections: nombres opcionales de secciones H2/H3 de AGENTS.md para volver a inyectar después de la Compaction. El valor predeterminado es ["Session Startup", "Red Lines"]; configúralo en [] para desactivar la reinyección. Cuando no está configurado o se configura explícitamente en ese par predeterminado, también se aceptan los encabezados antiguos Every Session/Safety como respaldo heredado.
• model: sustitución opcional provider/model-id solo para el resumen de Compaction. Úsala cuando la sesión principal deba conservar un modelo pero los resúmenes de Compaction deban ejecutarse en otro; cuando no está configurado, Compaction usa el modelo principal de la sesión.
• maxActiveTranscriptBytes: umbral opcional en bytes (number o cadenas como "20mb") que activa la Compaction local normal antes de una ejecución cuando el JSONL activo supera el umbral. Requiere truncateAfterCompaction para que una Compaction correcta pueda rotar a una transcripción sucesora más pequeña. Desactivado cuando no está configurado o es 0.
• notifyUser: cuando es true, envía avisos breves al usuario cuando la Compaction comienza y cuando se completa (por ejemplo, "Compacting context..." y "Compaction complete"). Desactivado de forma predeterminada para mantener silenciosa la Compaction.
• memoryFlush: turno agéntico silencioso antes de la Compaction automática para almacenar memorias duraderas. Configura model en un proveedor/modelo exacto, como ollama/qwen3:8b, cuando este turno de mantenimiento deba permanecer en un modelo local; la sustitución no hereda la cadena de respaldo de la sesión activa. Se omite cuando el espacio de trabajo es de solo lectura.

# agents.defaults.contextPruning

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

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

Consulta Poda de sesión para obtener detalles de comportamiento.

# Transmisión por bloques

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

Consulta Transmisión para obtener detalles de comportamiento y fragmentación.

# Indicadores de escritura

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

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

Consulta Indicadores de escritura.

# agents.defaults.sandbox

Sandboxing opcional para el agente integrado. Consulta Sandboxing para ver la guía completa.

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

El sandboxing del navegador y sandbox.docker.binds son solo para Docker.

Compila imágenes (desde un checkout del código fuente):

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

Para instalaciones de npm sin un checkout del código fuente, consulta Sandboxing § Imágenes y configuración para ver comandos docker build en línea.

# agents.list (anulaciones por agente)

Usa agents.list[].tts para asignar a un agente su propio proveedor de TTS, voz, modelo, estilo o modo de TTS automático. El bloque del agente se fusiona en profundidad sobre messages.tts, por lo que las credenciales compartidas pueden permanecer en un solo lugar mientras los agentes individuales anulan solo los campos de voz o proveedor que necesitan. La anulación del agente activo se aplica a las respuestas habladas automáticas, /tts audio, /tts status y la herramienta de agente tts. Consulta Texto a voz para ver ejemplos de proveedores y precedencia.

{
  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
        agentRuntime: { id: "auto" },
        params: { cacheRetention: "none" }, // overrides matching defaults.models params by key
        tts: {
          providers: {
            elevenlabs: { voiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        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 de agente estable (obligatorio).
• default: cuando se configuran varios, gana el primero (se registra una advertencia). Si no se configura ninguno, la primera entrada de la lista es la predeterminada.
• model: la forma de cadena establece un primario estricto por agente sin reserva de modelo; la forma de objeto { primary } también es estricta salvo que agregues fallbacks. Usa { primary, fallbacks: [...] } para habilitar la reserva para ese agente, o { primary, fallbacks: [] } para hacer explícito el comportamiento estricto. Los trabajos de Cron que solo sobrescriben primary siguen heredando las reservas predeterminadas salvo que establezcas fallbacks: [].
• params: parámetros de flujo por agente combinados sobre la entrada del modelo seleccionado en agents.defaults.models. Usa esto para sobrescrituras específicas del agente, como cacheRetention, temperature o maxTokens, sin duplicar todo el catálogo de modelos.
• tts: sobrescrituras opcionales de texto a voz por agente. El bloque se fusiona en profundidad sobre messages.tts, así que mantén las credenciales compartidas del proveedor y la política de reserva en messages.tts, y establece aquí solo valores específicos de la personalidad, como proveedor, voz, modelo, estilo o modo automático.
• 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 vez de fusionarse, y [] significa sin Skills.
• thinkingDefault: nivel de pensamiento predeterminado opcional por agente (off | minimal | low | medium | high | xhigh | adaptive | max). Sobrescribe agents.defaults.thinkingDefault para este agente cuando no se establece ninguna sobrescritura por mensaje o sesión. El perfil del proveedor/modelo seleccionado controla qué valores son válidos; para Google Gemini, adaptive conserva el pensamiento dinámico propiedad del proveedor (thinkingLevel omitido en Gemini 3/3.1, thinkingBudget: -1 en Gemini 2.5).
• reasoningDefault: visibilidad de razonamiento predeterminada opcional por agente (on | off | stream). Sobrescribe agents.defaults.reasoningDefault para este agente cuando no se establece ninguna sobrescritura de razonamiento por mensaje o sesión.
• fastModeDefault: valor predeterminado opcional por agente para el modo rápido (true | false). Se aplica cuando no se establece ninguna sobrescritura de modo rápido por mensaje o sesión.
• agentRuntime: sobrescritura opcional de política de runtime de bajo nivel por agente. Usa { id: "codex" } para hacer que un agente sea solo Codex mientras otros agentes mantienen la reserva PI predeterminada en modo auto.
• runtime: descriptor de runtime opcional por agente. Usa type: "acp" con valores predeterminados de runtime.acp (agent, backend, mode, cwd) cuando el agente deba usar de forma predeterminada sesiones del arnés ACP.
• identity.avatar: ruta relativa al workspace, URL http(s) o URI data:.
• identity deriva valores predeterminados: ackReaction desde emoji, mentionPatterns desde name/emoji.
• subagents.allowAgents: lista de permitidos de ids de agentes para objetivos explícitos sessions_spawn.agentId (["*"] = cualquiera; predeterminado: solo el mismo agente). Incluye el id del solicitante cuando deban permitirse llamadas agentId autodirigidas.
• Protección de herencia de sandbox: si la sesión solicitante está en sandbox, sessions_spawn rechaza objetivos que se ejecutarían sin sandbox.
• subagents.requireAgentId: cuando es true, bloquea llamadas sessions_spawn que omiten agentId (fuerza la selección explícita de perfil; predeterminado: false).

# Enrutamiento multiagente

Ejecuta varios agentes aislados dentro de un Gateway. Consulta 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 de coincidencia de enlace

• type (opcional): route para enrutamiento normal (si falta el tipo, el predeterminado es route), acp para enlaces de conversación ACP persistentes.
• 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ífico del canal)
• acp (opcional; solo para type: "acp"): { mode, label, cwd, backend }

Orden de coincidencia determinista:

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

Dentro de cada nivel, gana la primera entrada coincidente de bindings.

Para entradas type: "acp", OpenClaw resuelve por identidad exacta de conversación (match.channel + cuenta + match.peer.id) y no usa el orden de niveles de enlace de ruta anterior.

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

Consulta Sandbox y herramientas multiagente para ver los detalles de precedencia.

# 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",
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      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: "steer", // steer | queue (legacy one-at-a-time) | followup | collect | steer-backlog | steer+backlog | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "steer",
        telegram: "steer",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 disables
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

# Prefijo de respuesta

Anulaciones por canal/cuenta: channels.<channel>.responsePrefix, channels.<channel>.accounts.<id>.responsePrefix.

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

Variables de plantilla:

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

# Reacción de confirmación

• De forma predeterminada usa identity.emoji del agente activo; de lo contrario, "👀". Configura "" para desactivarla.
• Anulaciones por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Orden de resolución: cuenta → canal → messages.ackReaction → reserva de identidad.
• Ámbito: group-mentions (predeterminado), group-all, direct, all.
• removeAckAfterReply: elimina la confirmación después de responder en canales compatibles con reacciones, como Slack, Discord, Telegram, WhatsApp y BlueBubbles.
• messages.statusReactions.enabled: habilita reacciones de estado del ciclo de vida en Slack, Discord y Telegram. En Slack y Discord, dejarlo sin configurar mantiene las reacciones de estado habilitadas cuando las reacciones de confirmación están activas. En Telegram, configúralo explícitamente como true para habilitar las reacciones de estado del ciclo de vida.

# Antirrebote de entrada

Agrupa mensajes rápidos de solo texto del mismo remitente en un único turno del agente. Los medios/adjuntos se envían inmediatamente. Los comandos de control omiten el antirrebote.

# 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",
      providers: {
        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,
          },
        },
        microsoft: {
          voice: "en-US-AvaMultilingualNeural",
          lang: "en-US",
          outputFormat: "audio-24khz-48kbitrate-mono-mp3",
        },
        openai: {
          apiKey: "openai_api_key",
          baseUrl: "https://api.openai.com/v1",
          model: "gpt-4o-mini-tts",
          voice: "alloy",
        },
      },
    },
  },
}

• auto controla el modo TTS automático predeterminado: off, always, inbound o tagged. /tts on|off puede anular las preferencias locales, y /tts status muestra el estado efectivo.
• summaryModel anula agents.defaults.model.primary para el resumen automático.
• modelOverrides está habilitado de forma predeterminada; modelOverrides.allowProvider tiene false como valor predeterminado (activación explícita).
• Las claves de API recurren a ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY.
• Los proveedores de voz incluidos pertenecen a Plugins. Si plugins.allow está configurado, incluye cada Plugin proveedor de TTS que quieras usar; por ejemplo, microsoft para Edge TTS. El id de proveedor heredado edge se acepta como alias de microsoft.
• providers.openai.baseUrl anula el endpoint TTS de OpenAI. El orden de resolución es configuración, luego OPENAI_TTS_BASE_URL y luego https://api.openai.com/v1.
• Cuando providers.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

Valores predeterminados del modo Talk (macOS/iOS/Android).

{
  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",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime",
          voice: "alloy",
        },
      },
      mode: "realtime",
      transport: "webrtc",
      brain: "agent-consult",
    },
  },
}

• talk.provider debe coincidir con una clave en talk.providers cuando hay varios proveedores de Talk configurados.
• Las claves planas heredadas de Talk (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) son solo de compatibilidad. Ejecuta openclaw doctor --fix para reescribir la configuración persistida en talk.providers.<provider>.
• Los ID de voz recurren a ELEVENLABS_VOICE_ID o SAG_VOICE_ID.
• providers.*.apiKey acepta cadenas de texto sin formato u objetos SecretRef.
• La reserva ELEVENLABS_API_KEY se aplica solo cuando no hay ninguna clave de API de Talk configurada.
• providers.*.voiceAliases permite que las directivas de Talk usen nombres descriptivos.
• providers.mlx.modelId selecciona el repositorio de Hugging Face usado por el asistente local MLX de macOS. Si se omite, macOS usa mlx-community/Soprano-80M-bf16.
• La reproducción MLX de macOS se ejecuta mediante el asistente incluido openclaw-mlx-tts cuando está presente, o mediante un ejecutable en PATH; OPENCLAW_MLX_TTS_BIN anula la ruta del asistente para desarrollo.
• speechLocale establece el id de configuración regional BCP 47 usado por el reconocimiento de voz de Talk en iOS/macOS. Déjalo sin configurar para usar el valor predeterminado del dispositivo.
• silenceTimeoutMs controla cuánto tiempo espera el modo Talk después del silencio del usuario antes de enviar la transcripción. Dejarlo sin configurar mantiene la ventana de pausa predeterminada de la plataforma (700 ms on macOS and Android, 900 ms on iOS).

# Relacionado

• Referencia de configuración — todas las demás claves de configuración
• Configuración — tareas comunes y configuración rápida
• Ejemplos de configuración