Configuración — agentes

​

Valores predeterminados de los agentes

​

agents.defaults.workspace

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

​

agents.defaults.repoRoot

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

​

agents.defaults.skills

{
  agents: {
    defaults: { skills: ["github", "weather"] },
    list: [
      { id: "writer" }, // hereda github, weather
      { id: "docs", skills: ["docs-search"] }, // sustituye los valores predeterminados
      { id: "locked-down", skills: [] }, // sin Skills
    ],
  },
}

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

​

agents.defaults.skipBootstrap

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

​

agents.defaults.skipOptionalBootstrapFiles

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

​

agents.defaults.contextInjection

• "continuation-skip": los turnos de continuación seguros (después de una respuesta completada del asistente) omiten volver a inyectar el arranque del espacio de trabajo, lo que reduce el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a Compaction siguen reconstruyendo el contexto.
• "never": deshabilita la inyección del arranque del espacio de trabajo y de archivos de contexto en cada turno. Utilice esta opción únicamente para agentes que controlen por completo el ciclo de vida de su prompt (motores de contexto personalizados, entornos de ejecución 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

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

Anulaciones del perfil de arranque por agente

{
  agents: {
    defaults: {
      contextInjection: "continuation-skip",
      bootstrapMaxChars: 20000,
      bootstrapTotalMaxChars: 60000,
    },
    list: [
      {
        id: "strict-worker",
        contextInjection: "always",
        bootstrapMaxChars: 50000,
        bootstrapTotalMaxChars: 300000,
      },
    ],
  },
}

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

Mapa de propiedad de presupuestos de contexto

• agents.entries.*.skillsLimits.maxSkillsPromptChars
• agents.entries.*.contextInjection
• agents.entries.*.bootstrapMaxChars
• agents.entries.*.bootstrapTotalMaxChars
• agents.entries.*.contextLimits.*

​

agents.defaults.startupContext

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

​

agents.defaults.contextLimits

{
  agents: {
    defaults: {
      contextLimits: {
        memoryGetMaxChars: 12000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

• memoryGetMaxChars: límite predeterminado del extracto memory_get antes de añadir los metadatos de truncamiento y el aviso de continuación.
• Cuando memory_get omite lines, OpenClaw utiliza una ventana integrada de 120 líneas y después aplica memoryGetMaxChars.
• Los resultados de herramientas en vivo utilizan un límite automático de contexto del modelo: 16000 caracteres por debajo de 100K tokens, 32000 caracteres con 100K+ tokens y 64000 caracteres con 200K+ tokens.
• postCompactionMaxChars: límite del extracto de AGENTS.md utilizado durante la inyección de actualización posterior a Compaction.

​

agents.entries.*.contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.entries.*.skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.imageQuality

• auto: se adapta a los límites del modelo y a la cantidad de imágenes.
• efficient: prioriza imágenes más pequeñas para reducir el uso de tokens y bytes.
• balanced: utiliza la escala intermedia estándar.
• high: conserva más detalle en capturas de pantalla, diagramas e imágenes de documentos.

{
  agents: { defaults: { imageQuality: "auto" } },
}

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      utilityModel: "openai/gpt-5.4-mini",
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      mediaModels: {
        image: {
          primary: "openai/gpt-image-2",
          fallbacks: ["google/gemini-3.1-flash-image"],
        },
        video: {
          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" }, // parámetros globales predeterminados del proveedor
      pdfMaxMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      toolProgressDetail: "explain",
      reasoningDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 4,
    },
  },
}

• 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 modelo principal y los modelos de conmutación por error ordenados.
• utilityModel: referencia o alias provider/model opcional para tareas internas breves. Actualmente se utiliza para generar los títulos de sesión de la interfaz de control, los títulos de temas de mensajes directos de Telegram, los títulos automáticos de hilos de Discord y la narración de borradores de progreso. Cuando no se establece, OpenClaw obtiene el modelo pequeño predeterminado declarado por el proveedor principal, si existe (OpenAI → gpt-5.6-luna, Anthropic → claude-haiku-4-5); de lo contrario, las tareas de creación de títulos usan el modelo principal del agente y la narración permanece desactivada. Si un modelo auxiliar distinto no puede preparar o completar un título generado, OpenClaw vuelve a intentar generar ese título una vez con el modelo principal. Para los títulos del panel, la derivación automática del modelo auxiliar y la alternativa habitual usan el proveedor y el perfil de autenticación efectivos de la sesión; un modelo auxiliar explícito conserva el proveedor y la autenticación configurados. Establezca utilityModel: "" para omitir la ruta auxiliar alternativa; la generación de títulos del panel continúa directamente con el modelo habitual de la sesión. agents.entries.*.utilityModel sustituye el valor predeterminado y una sustitución de modelo específica de la operación prevalece sobre ambos. Las tareas auxiliares realizan llamadas independientes al modelo y envían contenido específico de la tarea al proveedor del modelo seleccionado. La generación de títulos del panel envía como máximo los primeros 1.000 caracteres del primer mensaje que no sea un comando; la narración envía la solicitud entrante junto con resúmenes compactos y expurgados de las herramientas. Elija un proveedor que se ajuste a sus requisitos de coste y tratamiento de datos.
• imageModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • La ruta de la herramienta image lo usa como configuración del modelo de visión cuando el modelo activo no admite imágenes. En cambio, los modelos con visión nativa reciben directamente los bytes de las imágenes cargadas.
  • También se usa como ruta alternativa cuando el modelo seleccionado o predeterminado no admite entradas de imagen.
  • Se recomienda usar referencias provider/model explícitas. Se aceptan identificadores sin calificar por compatibilidad; si un identificador sin calificar coincide de forma única con una entrada configurada que admite imágenes en models.providers.*.models, OpenClaw lo califica con ese proveedor. Las coincidencias configuradas ambiguas requieren un prefijo de proveedor explícito.
• mediaModels.image: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usan la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta o Plugin que genere imágenes.
  • Valores habituales: google/gemini-3.1-flash-image para la 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 la salida PNG/WebP de OpenAI con fondo transparente.
  • Si selecciona directamente un proveedor o modelo, configure también la autenticación correspondiente del proveedor (por ejemplo, GEMINI_API_KEY o GOOGLE_API_KEY para google/*, OPENAI_API_KEY u OAuth de OpenAI Codex para openai/gpt-image-2 / openai/gpt-image-1.5, FAL_KEY para fal/*).
  • Si se omite, image_generate aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y, después, los demás proveedores registrados de generación de imágenes, ordenados por identificador de proveedor.
• mediaModels.music: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usan la capacidad compartida de generación de música y la herramienta integrada music_generate.
  • Valores habituales: google/lyria-3-clip-preview, google/lyria-3-pro-preview o minimax/music-2.6.
  • Si se omite, music_generate aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y, después, los demás proveedores registrados de generación de música, ordenados por identificador de proveedor.
  • Si selecciona directamente un proveedor o modelo, configure también la autenticación o clave de API correspondiente del proveedor.
• mediaModels.video: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usan la capacidad compartida de generación de vídeo y la herramienta integrada video_generate.
  • Valores habituales: 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 aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero prueba el proveedor predeterminado actual y, después, los demás proveedores registrados de generación de vídeo, ordenados por identificador de proveedor.
  • Si selecciona directamente un proveedor o modelo, configure también la autenticación o clave de API correspondiente del proveedor.
  • El Plugin oficial de generación de vídeo de Qwen admite hasta 1 vídeo de salida, 1 imagen de entrada, 4 vídeos de entrada, una duración de 10 segundos y las opciones de proveedor size, aspectRatio, resolution, audio y watermark.
• pdfModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • La herramienta pdf lo usa para el enrutamiento de modelos.
  • Si se omite, la herramienta de PDF recurre a imageModel y, después, al modelo resuelto de la sesión o predeterminado.
• pdfMaxMb: límite predeterminado de tamaño de PDF para la herramienta pdf cuando no se pasa maxBytesMb al realizar la llamada.
• pdfMaxPages: número máximo predeterminado de páginas que se tienen en cuenta en el modo alternativo de extracción de la herramienta pdf.
• verboseDefault: nivel de detalle predeterminado de los agentes. Valores: "off", "on", "full". Valor predeterminado: "off".
• toolProgressDetail: modo de detalle para los resúmenes de herramientas de /verbose y las líneas de herramientas de borradores de progreso. Valores: "explain" (predeterminado, etiquetas humanas compactas) o "raw" (añade el comando o detalle sin procesar cuando está disponible). El valor agents.entries.*.toolProgressDetail de cada agente sustituye este valor predeterminado.
• reasoningDefault: visibilidad predeterminada del razonamiento de los agentes. Valores: "off", "on", "stream". El valor agents.entries.*.reasoningDefault de cada agente sustituye este valor predeterminado. Los valores predeterminados de razonamiento configurados solo se aplican a propietarios, remitentes autorizados o contextos de administrador-operador del Gateway cuando no se ha establecido una sustitución de razonamiento por mensaje o sesión.
• elevatedDefault: nivel predeterminado de salida elevada de los agentes. Valores: "off", "on", "ask", "full". Valor predeterminado: "on".
• model.primary: formato provider/model (p. ej., openai/gpt-5.6-sol para el acceso OAuth de Codex). Si omite el proveedor, OpenClaw prueba primero un alias, después una coincidencia única de proveedor configurado para ese identificador exacto de modelo y, solo entonces, recurre al proveedor predeterminado configurado (comportamiento de compatibilidad obsoleto, por lo que se recomienda usar un provider/model explícito). Si ese proveedor ya no ofrece el modelo predeterminado configurado, OpenClaw recurre al primer proveedor y modelo configurados en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado.
• contextTokens: límite máximo opcional para todo el agente. Puede reducir el presupuesto efectivo de un modelo más grande, pero no puede aumentarlo por encima de su contextTokens configurado o detectado. Para habilitar la ventana nativa más grande de un modelo directo de OpenAI, establezca models.providers.openai.models[].contextWindow y contextTokens para ese modelo; consulte Valores predeterminados de la ventana de contexto de OpenAI.
• models: alias configurados y ajustes por modelo. Cada entrada puede incluir alias (acceso directo) y params (específico del proveedor, por ejemplo, temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold, enrutamiento provider de OpenRouter, chat_template_kwargs, extra_body/extraBody). Añadir entradas no restringe las sustituciones de modelos.
  • Use entradas provider/*, como "openai/*": {} o "vllm/*": {}, para mostrar todos los modelos detectados de los proveedores seleccionados sin enumerar manualmente cada identificador de modelo.
  • Añada agentRuntime a una entrada provider/* cuando todos los modelos detectados dinámicamente para ese proveedor deban usar el mismo entorno de ejecución. La política exacta de entorno de ejecución provider/model sigue prevaleciendo sobre el comodín.
  • Ediciones seguras de metadatos: use openclaw config set agents.defaults.models '<json>' --strict-json --merge para añadir entradas. config set rechaza las sustituciones que eliminarían entradas existentes, salvo que se pase --replace.
• modelPolicy.allow: lista explícita de sustituciones permitidas. Acepta alias, referencias provider/model exactas y comodines de prefijo al final, como openai/* o clawrouter/anthropic/*. Omítala o use [] para permitir cualquier modelo. agents.entries.*.modelPolicy.allow sustituye la política predeterminada de ese agente; una lista vacía explícita permite cualquier modelo para ese agente.
  • Los flujos de configuración e incorporación específicos del proveedor combinan en este mapa los modelos seleccionados del proveedor y conservan los proveedores no relacionados que ya estén configurados.
  • Para los modelos directos de OpenAI Responses, la Compaction del lado del servidor se activa automáticamente. Use params.responsesServerCompaction: false para dejar de insertar context_management o params.responsesCompactThreshold para sustituir el umbral. Consulte Compaction de OpenAI del lado del servidor.
• params: parámetros globales predeterminados del proveedor que se aplican 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) se sustituye por agents.defaults.models["provider/model"].params (por modelo) y, después, agents.entries.*.params (identificador de agente coincidente) sustituye los valores por clave. Consulte Almacenamiento en caché de prompts para obtener más información.
• models.providers.openrouter.params.provider: política predeterminada de enrutamiento de proveedores para todo OpenRouter. OpenClaw la reenvía al objeto provider de la solicitud de OpenRouter; los valores agents.defaults.models["openrouter/<model>"].params.provider por modelo y los parámetros del agente prevalecen por clave. Consulte Enrutamiento de proveedores de OpenRouter.
• params.extra_body/params.extraBody: JSON avanzado transferido directamente que se combina en los cuerpos de solicitud api: "openai-completions" para proxies compatibles con OpenAI. Si entra en conflicto con claves de solicitud generadas, prevalece el cuerpo adicional; posteriormente, las rutas de finalización no nativas siguen eliminando store, que es exclusivo de OpenAI.
• params.chat_template_kwargs: argumentos de plantilla de chat compatibles con vLLM/OpenAI que se combinan en los cuerpos de solicitud api: "openai-completions" de nivel superior. Para vllm/nemotron-3-* con el pensamiento desactivado, el Plugin de vLLM incluido envía automáticamente enable_thinking: false y force_nonempty_content: true; los valores chat_template_kwargs explícitos sustituyen los valores predeterminados generados y extra_body.chat_template_kwargs conserva la precedencia final. Los modelos de pensamiento Qwen y Nemotron de vLLM configurados ofrecen opciones binarias /think (off, on) en lugar de la escala de esfuerzo de varios niveles.
• compat.thinkingFormat: estilo de carga útil de pensamiento compatible con OpenAI. Use "together" para reasoning.enabled al estilo de Together, "qwen" para enable_thinking de nivel superior al estilo de Qwen o "qwen-chat-template" para chat_template_kwargs.enable_thinking en backends de la familia Qwen que admitan argumentos de palabra clave de plantilla de chat en el nivel de solicitud, como vLLM. OpenClaw asigna el pensamiento desactivado a false y el pensamiento activado a true, y los modelos Qwen de vLLM configurados ofrecen opciones binarias /think para estos formatos.
• compat.supportedReasoningEfforts: lista de niveles de esfuerzo de razonamiento compatibles con OpenAI por modelo. Incluya "xhigh" para los endpoints personalizados que realmente lo acepten; OpenClaw mostrará entonces /think xhigh en los menús de comandos, las filas de sesiones del Gateway, la validación de parches de sesión, la validación de la CLI del agente y la validación de llm-task para ese proveedor/modelo configurado. Use compat.reasoningEffortMap cuando el backend requiera un valor específico del proveedor para un nivel canónico.
• params.preserveThinking: activación opcional exclusiva de Z.AI para conservar el razonamiento. Cuando está habilitada y el razonamiento está activo, OpenClaw envía thinking.clear_thinking: false y reproduce los reasoning_content anteriores; consulte Razonamiento y razonamiento conservado de Z.AI.
• localService: gestor de procesos opcional a nivel de proveedor para servidores de modelos locales o autoalojados. Cuando el modelo seleccionado pertenece a ese proveedor, OpenClaw comprueba healthUrl (o baseUrl + "/models"), inicia command con args si el endpoint no está disponible, espera hasta readyTimeoutMs y, a continuación, envía la solicitud al modelo. command debe ser una ruta absoluta. idleStopMs: 0 mantiene el proceso activo hasta que OpenClaw finaliza; un valor positivo detiene el proceso iniciado por OpenClaw después de esa cantidad de milisegundos de inactividad. Consulte Servicios de modelos locales.
• La política de tiempo de ejecución corresponde a los proveedores o modelos, no a agents.defaults. Use models.providers.<provider>.agentRuntime para reglas aplicables a todo el proveedor o agents.defaults.models["provider/model"].agentRuntime / agents.entries.*.models["provider/model"].agentRuntime para reglas específicas del modelo. Un prefijo de proveedor/modelo por sí solo nunca selecciona un entorno de ejecución. Si el tiempo de ejecución no está establecido o es auto, OpenAI puede seleccionar Codex implícitamente solo para una ruta oficial HTTPS exacta de Platform Responses o ChatGPT Responses sin ninguna anulación explícita de la solicitud. Consulte Tiempo de ejecución implícito del agente de OpenAI.
• Los escritores de configuración que modifican estos campos (por ejemplo, /models set, /models set-image y los comandos para añadir o eliminar alternativas) guardan la forma de objeto canónica y conservan las listas de alternativas existentes cuando es posible.
• maxConcurrent: número máximo de ejecuciones paralelas de agentes entre sesiones (cada sesión sigue ejecutándose de forma serializada). Valor predeterminado: 4.

​

Política del runtime

{
  models: {
    providers: {
      openai: {
        agentRuntime: { id: "codex" },
      },
    },
  },
  agents: {
    defaults: {
      model: "openai/gpt-5.6-sol",
      models: {
        "anthropic/claude-opus-5": {
          agentRuntime: { id: "claude-cli" },
        },
        "vllm/*": {
          agentRuntime: { id: "openclaw" },
        },
      },
    },
  },
}

• id: "auto", "openclaw", un id de arnés de Plugin registrado o un alias de backend de CLI compatible. El Plugin Codex incluido registra codex; el Plugin Anthropic incluido proporciona el backend de CLI claude-cli.
• id: "auto" permite que los arneses de Plugin registrados asuman rutas efectivas que declaren o satisfagan de otro modo su contrato de compatibilidad, y utiliza OpenClaw cuando ningún arnés coincide. Un runtime de Plugin explícito como id: "codex" requiere ese arnés y una ruta efectiva compatible; aplica un cierre seguro si alguno no está disponible o si la ejecución falla.
• id: "pi" solo se acepta como alias obsoleto de openclaw para preservar las configuraciones publicadas de v2026.5.22 y versiones anteriores. Las configuraciones nuevas deben usar openclaw.
• La precedencia del runtime es: primero la política de modelo exacta (agents.entries.*.models["provider/model"], agents.defaults.models["provider/model"] o models.providers.<provider>.models[]), después agents.entries.* / agents.defaults.models["provider/*"] y, por último, la política para todo el proveedor en models.providers.<provider>.agentRuntime.
• Las claves de runtime para todo el agente son heredadas. agents.defaults.agentRuntime, agents.entries.*.agentRuntime, las fijaciones de runtime de sesión y OPENCLAW_AGENT_RUNTIME se ignoran al seleccionar el runtime. Ejecute openclaw doctor --fix para eliminar los valores obsoletos.
• Las rutas oficiales HTTPS exactas de OpenAI Responses/ChatGPT que sean aptas y no tengan una sustitución de solicitud definida pueden usar implícitamente el arnés Codex. El agentRuntime.id: "codex" del proveedor/modelo convierte Codex en un requisito de cierre seguro, pero no hace compatible una ruta incompatible.
• Para implementaciones de Claude CLI, se recomienda model: "anthropic/claude-opus-5" junto con agentRuntime.id: "claude-cli" con ámbito de modelo. Las referencias heredadas claude-cli/<model> siguen funcionando por compatibilidad, pero las configuraciones nuevas deben mantener canónica la selección de proveedor/modelo y colocar el backend de ejecución en la política de runtime del proveedor/modelo.
• Esto solo controla la ejecución de turnos de agente de texto. La generación multimedia, la visión, los PDF, la música, el vídeo y TTS siguen utilizando sus ajustes de proveedor/modelo.

​

Selección del backend de CLI

​

agents.defaults.promptOverlays

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

• "friendly" (valor predeterminado) y "on" activan la capa de estilo de interacción cordial.
• "off" desactiva únicamente la capa cordial; el contrato de comportamiento GPT-5 etiquetado permanece activado.
• El valor heredado plugins.entries.openai.config.personality todavía se lee cuando este ajuste compartido no está establecido.

​

agents.defaults.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 skips workspace bootstrap files for heartbeat runs
        isolatedSession: false, // default: false; true runs each heartbeat in a fresh session (no conversation history)
        skipWhenBusy: false, // default: false; true also waits for this agent's subagent/nested lanes
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (default) | block
        target: "none", // default: none | options: last | whatsapp | telegram | discord | ...
        prompt: "Follow the heartbeat monitor scratch context...",
        ackMaxChars: 300,
        suppressToolErrorWarnings: false,
        timeoutSeconds: 45,
      },
    },
  },
}

• every: cadena de duración (ms/s/m/h). Valor predeterminado: 30m (autenticación mediante clave de API) o 1h (autenticación OAuth). Establézcalo en 0m para desactivarlo.
• La cadencia se escribe en una fila de monitor Cron gestionada por el sistema. Ejecute openclaw doctor --fix para materializar una fila ausente u obsoleta. Si Cron está desactivado, los Heartbeats programados no se ejecutan y el Gateway registra una advertencia de inicio.
• includeSystemPromptSection: cuando es false, omite la sección Heartbeat de las instrucciones del sistema. Valor predeterminado: true.
• suppressToolErrorWarnings: cuando es true, suprime las cargas de advertencia de errores de herramientas durante las ejecuciones de Heartbeat.
• timeoutSeconds: tiempo máximo permitido, en segundos, para un turno de agente de Heartbeat antes de que se cancele. Déjelo sin establecer para usar agents.defaults.timeoutSeconds cuando esté establecido; de lo contrario, se usa la cadencia de Heartbeat con un límite de 600 segundos.
• directPolicy: política de entrega directa/por mensaje directo. allow (valor predeterminado) permite la entrega a destinos directos. block suprime la entrega a destinos directos y emite reason=dm-blocked.
• lightContext: cuando es true, las ejecuciones de Heartbeat utilizan un contexto de arranque ligero y omiten los archivos de arranque del espacio de trabajo. El ejecutor de Heartbeat inyecta el contexto provisional del monitor en ambos casos.
• isolatedSession: cuando es true, cada Heartbeat se ejecuta en una sesión nueva sin historial de conversación previo. Sigue el mismo patrón de aislamiento que sessionTarget: "isolated" de Cron. Reduce el coste de tokens por Heartbeat de ~100K a ~2-5K tokens.
• skipWhenBusy: cuando es true, las ejecuciones de Heartbeat se aplazan mientras estén ocupados los canales adicionales de ese agente: el trabajo de sus propios subagentes vinculado a la clave de sesión o el trabajo de comandos anidados. Los canales de Cron siempre aplazan los Heartbeats, incluso sin esta opción.
• Por agente: establezca agents.entries.*.heartbeat. Cuando algún agente define heartbeat, solo esos agentes ejecutan Heartbeats.
• Los Heartbeats ejecutan turnos completos del 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)
        thinkingLevel: "low", // optional compaction-only thinking override
        timeoutSeconds: 180,
        keepRecentTokens: 50000,
        recentTurnsPreserve: 3,
        identifierPolicy: "strict", // strict | off
        qualityGuard: { enabled: true, maxRetries: 1 },
        midTurnPrecheck: { enabled: false }, // optional tool-loop pressure check
        postIndexSync: "async", // off | async | await
        postCompactionSections: ["Session Startup", "Red Lines"],
        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, // notices when compaction starts/completes and on memory-flush degradation (default: false)
        memoryFlush: {
          enabled: true,
          model: "ollama/qwen3:8b", // optional memory-flush-only model override
          softThresholdTokens: 6000,
          forceFlushTranscriptBytes: "2mb",
        },
      },
    },
  },
}

• mode: default o safeguard (resumen por fragmentos para historiales largos). Véase Compaction.
• provider: id de un plugin proveedor de Compaction registrado. Cuando se establece, se llama a summarize() del proveedor en lugar de usar el resumen integrado mediante LLM. Si falla, se recurre al mecanismo integrado. Establecer un proveedor fuerza mode: "safeguard". Véase Compaction.
• thinkingLevel: nivel de razonamiento opcional utilizado únicamente para los resúmenes de Compaction integrados de OpenClaw (off, minimal, low, medium, high, xhigh, adaptive, max o ultra). Anula el nivel de razonamiento actual de la sesión y se limita según el modelo o runtime de Compaction seleccionado. Déjelo sin establecer para heredar el nivel de la sesión. La Compaction nativa del servidor de aplicaciones de Codex ignora esta opción porque la solicitud nativa de compactación no permite anular el razonamiento por operación; OpenClaw registra una advertencia cuando está configurada.
• timeoutSeconds: cantidad máxima de segundos permitida para una sola operación de Compaction antes de que OpenClaw la cancele. Valor predeterminado: 180.
• keepRecentTokens: presupuesto del punto de corte del agente para conservar literalmente la parte final más reciente de la transcripción. La ejecución manual de /compact lo respeta cuando se establece explícitamente; de lo contrario, la Compaction manual es un punto de control estricto.
• recentTurnsPreserve: número de turnos más recientes de usuario/asistente que se conservan literalmente fuera del resumen de protección. Valor predeterminado: 3.
• identifierPolicy: strict (predeterminado) o off. strict antepone instrucciones integradas para conservar identificadores opacos durante el resumen de Compaction.
• qualityGuard: comprobaciones con reintento ante resultados con formato incorrecto en los resúmenes de protección. Activadas de forma predeterminada en el modo de protección; establezca enabled: false para omitir la auditoría.
• midTurnPrecheck: comprobación opcional de presión del bucle de herramientas. Cuando enabled: true, OpenClaw comprueba la presión del contexto después de añadir los resultados de las herramientas y antes de la siguiente llamada al modelo. Si el contexto ya no cabe, cancela el intento actual antes de enviar el prompt y reutiliza la ruta existente de recuperación previa para truncar los resultados de herramientas o ejecutar Compaction y volver a intentarlo. Funciona con los modos de Compaction default y safeguard. Valor predeterminado: desactivado.
• postIndexSync: modo de reindexación de la memoria de sesión posterior a Compaction. Valor predeterminado: "async". Use "await" para obtener la máxima actualización, "async" para reducir la latencia de Compaction o "off" únicamente cuando la sincronización de la memoria de sesión se gestione en otro lugar.
• postCompactionSections: nombres opcionales de secciones H2/H3 de AGENTS.md que se volverán a inyectar después de Compaction. Déjelo sin establecer o use [] para desactivarlo.
• model: provider/model-id opcional o alias simple de agents.defaults.models únicamente para el resumen de Compaction. Los alias simples se resuelven antes del envío; los identificadores literales de modelo configurados conservan la prioridad en caso de colisión. Use esta opción cuando la sesión principal deba conservar un modelo, pero los resúmenes de Compaction deban ejecutarse en otro; cuando no se establece, Compaction usa el modelo principal de la sesión.
• truncateAfterCompaction: rota la transcripción de la sesión activa después de Compaction para que los turnos futuros carguen únicamente el resumen y la parte final sin resumir, mientras la transcripción completa anterior permanece archivada. Evita el crecimiento ilimitado de la transcripción activa en sesiones de larga duración. Valor predeterminado: false.
• maxActiveTranscriptBytes: umbral opcional en bytes (number o cadenas como "20mb") que activa la Compaction local normal antes de una ejecución cuando el historial de la transcripción supera el umbral. Requiere truncateAfterCompaction para que una Compaction correcta pueda rotar a una transcripción sucesora más pequeña. Se desactiva cuando no se establece o cuando es 0.
• notifyUser: cuando true, envía al usuario breves avisos de mantenimiento del contexto: cuando Compaction comienza y termina (por ejemplo, «Compactando el contexto…» y «Compaction completada»), y cuando se agota un vaciado de memoria previo a Compaction, por lo que la respuesta continúa en un estado degradado (por ejemplo, «El mantenimiento de la memoria ha fallado temporalmente; se continuará con la respuesta»). Se desactiva de forma predeterminada para mantener estos avisos ocultos.
• memoryFlush: turno agéntico silencioso antes de la Compaction automática para almacenar recuerdos duraderos. Establezca model en un proveedor/modelo exacto, como ollama/qwen3:8b, cuando este turno de mantenimiento deba permanecer en un modelo local; la anulación no hereda la cadena de alternativas de la sesión activa. forceFlushTranscriptBytes fuerza el vaciado cuando el tamaño de la transcripción alcanza el umbral, incluso si los contadores de tokens están desactualizados. Se omite cuando el espacio de trabajo es de solo lectura.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // desactivado (predeterminado) | cache-ttl
      },
    },
  },
}

​

Transmisión por bloques

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

• Los canales distintos de Telegram requieren *.streaming.block.enabled: true explícito para activar las respuestas por bloques. QQ Bot es la excepción: no tiene claves streaming.block y transmite respuestas por bloques salvo que channels.qqbot.streaming.mode sea "off".
• Anulaciones por canal: channels.<channel>.streaming.block.coalesce (y variantes por cuenta). Discord, Google Chat, Mattermost, MS Teams, Signal y Slack usan de forma predeterminada minChars: 1500 / idleMs: 1000.
• blockStreamingChunk.breakPreference: límite de fragmento preferido ("paragraph" | "newline" | "sentence").
• humanDelay: pausa aleatoria entre respuestas por bloques. Valor predeterminado: off. natural = 800-2500ms. custom usa minMs/maxMs (recurre al intervalo natural para cualquier límite sin establecer). Anulación por agente: agents.entries.*.humanDelay.

​

Indicadores de escritura

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

• Valores predeterminados: instant para chats directos/menciones y message para chats grupales sin mención.
• Valor predeterminado de typingIntervalSeconds: 6.
• Anulación por agente: agents.entries.*.typingMode.

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off (predeterminado) | non-main | all
        backend: "docker", // docker (predeterminado) | ssh | openshell
        scope: "agent", // session | agent (predeterminado) | shared
        workspaceAccess: "none", // none (predeterminado) | 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,
          gpus: "all",
          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",
          // También se admiten SecretRefs / contenidos insertados:
          // 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 (predeterminado) | remoto
          command: "openshell",
          from: "openclaw",
          remoteWorkspaceDir: "/sandbox",
          remoteAgentWorkspaceDir: "/agent",
          gateway: "lab", // opcional
          gatewayEndpoint: "https://lab.example", // opcional
          policy: "strict", // identificador opcional de la política de OpenShell
          providers: ["openai"], // opcional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

scripts/sandbox-setup.sh           # imagen principal del entorno aislado
scripts/sandbox-browser-setup.sh   # imagen opcional del navegador

​

agents.entries (configuraciones por agente)

{
  agents: {
    list: [
      {
        id: "main",
        default: true,
        name: "Main Agent",
        workspace: "~/.openclaw/workspace",
        agentDir: "~/.openclaw/agents/main/agent",
        model: "anthropic/claude-opus-4-6", // o { primary, fallbacks }
        utilityModel: "openai/gpt-5.4-mini",
        thinkingDefault: "high", // configuración por agente del nivel de pensamiento
        reasoningDefault: "on", // configuración por agente de la visibilidad del razonamiento
        fastModeDefault: false, // configuración por agente del modo rápido
        params: { cacheRetention: "none" }, // sobrescribe por clave los parámetros coincidentes de defaults.models
        tts: {
          providers: {
            elevenlabs: { speakerVoiceId: "EXAVITQu4vr4xnSDxMaL" },
          },
        },
        skills: ["docs-search"], // sustituye a agents.defaults.skills cuando se establece
        identity: {
          name: "Samantha",
          theme: "perezoso servicial",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent", // persistent | oneshot
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: id estable del agente (obligatorio).
• default: cuando se establecen varios, prevalece el primero (se registra una advertencia). Si no se establece ninguno, la primera entrada de la lista es la predeterminada.
• model: la forma de cadena establece un modelo principal estricto por agente sin respaldo de modelo; la forma de objeto { primary } también es estricta, a menos que se añada fallbacks. Use { primary, fallbacks: [...] } para permitir que ese agente use respaldo, o { primary, fallbacks: [] } para hacer explícito el comportamiento estricto. Los trabajos de Cron que solo sobrescriben primary siguen heredando los respaldos predeterminados, salvo que se establezca fallbacks: [].
• utilityModel: sobrescritura opcional por agente para tareas internas breves, como los títulos generados de sesiones e hilos. Recurre a agents.defaults.utilityModel y, después, al modelo pequeño predeterminado declarado por el proveedor efectivo de la sesión. Los títulos del panel de control vuelven a intentarlo una vez con el modelo normal efectivo de la sesión. Una cadena vacía omite la ruta de utilidad alternativa para este agente sin deshabilitar la generación de títulos del panel de control.
• params: parámetros de transmisión por agente combinados sobre la entrada de modelo seleccionada en agents.defaults.models. Use esta opción 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 combina en profundidad sobre tts, por lo que las credenciales compartidas del proveedor y la política de respaldo deben mantenerse en tts, y aquí solo deben establecerse valores específicos de la personalidad, como el proveedor, la voz, el modelo, el estilo o el modo automático.
• skills: lista de Skills permitidas opcional por agente. Si se omite, el agente hereda agents.defaults.skills cuando está establecido; una lista explícita reemplaza los valores predeterminados en lugar de combinarlos, y [] significa que no hay Skills.
• thinkingDefault: nivel de razonamiento predeterminado opcional por agente (off | minimal | low | medium | high | xhigh | adaptive | max). Sobrescribe agents.defaults.thinkingDefault para este agente cuando no se ha establecido una sobrescritura por mensaje o sesión. El perfil de proveedor/modelo seleccionado controla qué valores son válidos; para Google Gemini, adaptive mantiene el razonamiento dinámico gestionado por el proveedor (thinkingLevel omitido en Gemini 3/3.1, thinkingBudget: -1 en Gemini 2.5).
• reasoningDefault: visibilidad predeterminada opcional del razonamiento por agente (on | off | stream). Sobrescribe agents.defaults.reasoningDefault para este agente cuando no se ha establecido una sobrescritura de razonamiento por mensaje o sesión.
• fastModeDefault: valor predeterminado opcional por agente para el modo rápido ("auto" | true | false). Se aplica cuando no se ha establecido una sobrescritura del modo rápido por mensaje o sesión.
• models: sobrescrituras opcionales del catálogo de modelos o del entorno de ejecución por agente, indexadas por los ids completos de provider/model. Use models["provider/model"].agentRuntime para excepciones del entorno de ejecución por agente.
• runtime: descriptor opcional del entorno de ejecución por agente. Use type: "acp" con los valores predeterminados de runtime.acp (agent, backend, mode, cwd) cuando el agente deba usar de forma predeterminada sesiones del entorno ACP.
• identity.avatar: ruta relativa al espacio de trabajo, URL de http(s) o URI de data:.
• Los archivos de imagen identity.avatar locales con rutas relativas al espacio de trabajo están limitados a 2 MB. Las URL de http(s) y los URI de data: no se comprueban con respecto al límite de tamaño de los archivos locales.
• identity deriva los valores predeterminados: ackReaction de emoji, y mentionPatterns de name/emoji.
• subagents.allowAgents: lista de ids de agentes configurados permitidos para destinos sessions_spawn.agentId explícitos (["*"] = cualquier destino configurado; valor predeterminado: solo el mismo agente). Incluya el id del solicitante cuando deban permitirse llamadas agentId dirigidas a sí mismo. Las entradas obsoletas cuya configuración de agente se haya eliminado son rechazadas por sessions_spawn y se omiten de agents_list; ejecute openclaw doctor --fix para limpiarlas, o añada una entrada agents.entries.* mínima si ese destino debe seguir pudiendo generarse mientras hereda los valores predeterminados.
• Protección de herencia del entorno aislado: si la sesión solicitante está aislada, sessions_spawn rechaza los destinos que se ejecutarían sin aislamiento.
• subagents.requireAgentId: cuando es verdadero, bloquea las llamadas sessions_spawn que omitan agentId (fuerza la selección explícita del perfil; valor predeterminado: falso).
• subagents.maxConcurrent: máximo de ejecuciones simultáneas de agentes secundarios en toda la ejecución de subagentes. Valor predeterminado: 8.
• subagents.maxChildrenPerAgent: máximo de agentes secundarios activos que puede generar una sola sesión de agente. Valor predeterminado: 5.
• subagents.maxSpawnDepth: profundidad máxima de anidamiento para la generación de subagentes (1-5). Valor predeterminado: 1 (sin anidamiento).
• subagents.archiveAfterMinutes: tiempo que debe transcurrir antes de archivar el estado de un subagente completado. Valor predeterminado: 60.

​

Enrutamiento multiagente

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

​

Campos de coincidencia de vinculaciones

• type (opcional): route para el enrutamiento normal (si falta el tipo, el valor predeterminado es route), acp para vinculaciones persistentes de conversaciones ACP.
• 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 }

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

​

Perfiles de acceso por agente

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

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

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

​

Sesión

{
  session: {
    scope: "per-sender",
    dmScope: "main", // main | per-peer | per-channel-peer | per-account-channel-peer
    identityLinks: {
      alice: ["telegram:123456789", "discord:987654321012345678"],
    },
    reset: {
      mode: "daily", // daily | idle
      atHour: 4,
      idleMinutes: 60,
    },
    resetByType: {
      thread: { mode: "daily", atHour: 4 },
      direct: { mode: "idle", idleMinutes: 240 },
      group: { mode: "idle", idleMinutes: 120 },
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 30 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    maintenance: {
      mode: "enforce", // enforce (predeterminado) | warn
      pruneAfter: "30d",
      maxEntries: 500,
      resetArchiveRetention: "30d", // duración o false
      maxDiskBytes: "500mb", // presupuesto máximo opcional
      highWaterBytes: "400mb", // objetivo de limpieza opcional
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // desenfoque automático predeterminado tras inactividad, en horas (`0` lo deshabilita)
      maxAgeHours: 0, // antigüedad máxima estricta predeterminada, en horas (`0` la deshabilita)
    },
    sharing: {
      readOnly: true,
      suggest: true,
      drafts: true,
    },
    mainKey: "main", // heredado (el entorno de ejecución siempre usa "main")
    sendPolicy: {
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
      default: "allow",
    },
  },
}

​

Mensajes

{
  messages: {
    responsePrefix: "🦞", // o "auto"
    ackReaction: "👀",
    ackReactionScope: "group-mentions", // group-mentions | group-all | direct | all | off | none
    queue: {
      mode: "steer", // steer (predeterminado) | followup | collect | interrupt
      debounceMs: 500,
      cap: 20,
      drop: "summarize", // old | new | summarize (predeterminado)
      byChannel: {
        whatsapp: "followup",
        telegram: "followup",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 lo desactiva
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefijo de respuesta

​

Reacción de confirmación

• El valor predeterminado es identity.emoji del agente activo o, en su defecto, "👀". Establezca "" para desactivarla.
• Anulaciones por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Orden de resolución: cuenta → canal → messages.ackReaction → alternativa de identidad.
• Ámbito: group-mentions (predeterminado), group-all, direct, all o off/none (desactiva por completo las reacciones de confirmación).
• messages.statusReactions.enabled: habilita reacciones de estado del ciclo de vida en Slack, Discord, Signal, Telegram y WhatsApp. En Discord, si no se establece, las reacciones de estado permanecen habilitadas cuando las reacciones de confirmación están activas. En Slack, Signal, Telegram y WhatsApp, establézcalo explícitamente en true para habilitar las reacciones de estado del ciclo de vida. Slack usa de forma predeterminada el estado nativo de hilos del asistente y mensajes de carga rotatorios para mostrar el progreso, mientras mantiene estática la reacción de confirmación configurada.

​

Cola

• mode: estrategia de cola para mensajes entrantes que llegan mientras está activa la ejecución de una sesión. Valor predeterminado: "steer".
  • steer: inserta la nueva solicitud en la ejecución activa.
  • followup: ejecuta la nueva solicitud cuando finaliza la ejecución activa.
  • collect: agrupa los mensajes compatibles y los ejecuta juntos más adelante.
  • interrupt: aborta la ejecución activa antes de iniciar la solicitud más reciente.
• debounceMs: retraso antes de despachar un mensaje en cola o redirigido. Valor predeterminado: 500.
• cap: cantidad máxima de mensajes en cola antes de aplicar la política de descarte. Valor predeterminado: 20.
• drop: estrategia cuando se supera el límite. "summarize" (predeterminado) descarta las entradas más antiguas, pero conserva resúmenes compactos; "old" descarta las más antiguas sin resúmenes; "new" rechaza el elemento más reciente.
• byChannel: anulaciones de mode por canal, indexadas por identificador de proveedor.
• debounceMsByChannel: anulaciones de debounceMs por canal, indexadas por identificador de proveedor.

​

Antirrebote de entrada

​

Otras claves de mensajes

• channels.whatsapp.responsePrefix: prefijo de las respuestas salientes de WhatsApp. Doctor mueve aquí el valor retirado de entrada messagePrefix solo cuando este valor canónico no está establecido.
• messages.visibleReplies: controla las respuestas de origen visibles en conversaciones directas, grupales y de canal ("message_tool" requiere message(action=send) para producir una salida visible; "automatic" publica las respuestas normales como antes).
• messages.usageTemplate / messages.responseUsage: plantilla personalizada de pie de página /usage y modo predeterminado de uso por respuesta (off | tokens | full, además del alias antiguo on para tokens).
• messages.groupChat.mentionPatterns / historyLimit: activadores de menciones en mensajes grupales y tamaño de la ventana del historial.
• messages.suppressToolErrors: cuando es true, suprime las advertencias de errores de herramientas ⚠️ que se muestran al usuario (el agente sigue viendo los errores en el contexto y puede volver a intentarlo). Valor predeterminado: false.

​

TTS (texto a voz)

{
  tts: {
    auto: "off", // off (predeterminado) | always | inbound | tagged
    mode: "final", // final | all
    provider: "elevenlabs",
    summaryModel: "openai/gpt-5.4-mini",
    modelOverrides: { enabled: true },
    maxTextLength: 4000,
    timeoutMs: 30000,
    providers: {
      elevenlabs: {
        apiKey: "example-elevenlabs-api-key",
        baseUrl: "https://api.elevenlabs.io",
        speakerVoiceId: "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: {
        speakerVoice: "en-US-MichelleNeural",
        lang: "en-US",
        outputFormat: "audio-24khz-48kbitrate-mono-mp3",
      },
      openai: {
        apiKey: "example-openai-api-key",
        baseUrl: "https://api.openai.com/v1",
        model: "gpt-4o-mini-tts",
        speakerVoice: "coral",
      },
    },
  },
}

• auto controla el modo predeterminado de TTS automático: off, always, inbound o tagged. /tts on|off puede sobrescribir las preferencias locales y /tts status muestra el estado efectivo.
• summaryModel sobrescribe agents.defaults.model.primary para el resumen automático.
• modelOverrides está habilitado de forma predeterminada (enabled !== false); modelOverrides.allowProvider es opcional.
• Las claves de API recurren a ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY como alternativa.
• Los proveedores de voz incluidos pertenecen a sus plugins. Si se establece plugins.allow, incluya cada plugin de proveedor de TTS que desee utilizar; por ejemplo, microsoft para Edge TTS. El identificador de proveedor heredado edge se acepta como alias de microsoft.
• providers.openai.baseUrl sobrescribe el endpoint de TTS de OpenAI. El orden de resolución es la configuración, después OPENAI_TTS_BASE_URL y, por último, https://api.openai.com/v1.
• Cuando providers.openai.baseUrl apunta a un endpoint ajeno a OpenAI, OpenClaw lo trata como un servidor de TTS compatible con OpenAI y flexibiliza la validación del modelo y de la voz.

​

Conversación

{
  talk: {
    provider: "elevenlabs",
    providers: {
      elevenlabs: {
        speakerVoiceId: "elevenlabs_voice_id",
        voiceAliases: {
          Clawd: "EXAVITQu4vr4xnSDxMaL",
          Roger: "CwhRBWXzGAHq8TQ4Fs17",
        },
        modelId: "eleven_multilingual_v2",
        outputFormat: "mp3_44100_128",
        apiKey: "elevenlabs_api_key",
      },
      mlx: {
        modelId: "mlx-community/Soprano-80M-bf16",
      },
      system: {},
    },
    consultThinkingLevel: "low",
    consultFastMode: true,
    speechLocale: "ru-RU",
    silenceTimeoutMs: 1500,
    interruptOnSpeech: true,
    realtime: {
      provider: "openai",
      providers: {
        openai: {
          model: "gpt-realtime-2.1",
          speakerVoice: "cedar",
        },
      },
      instructions: "Habla con calidez y mantén las respuestas breves.",
      mode: "realtime", // realtime | stt-tts | transcription
      transport: "webrtc", // webrtc | provider-websocket | gateway-relay | managed-room
      vadThreshold: 0.5,
      silenceDurationMs: 500,
      prefixPaddingMs: 300,
      reasoningEffort: "medium",
      brain: "agent-consult", // agent-consult | direct-tools | none
    },
  },
}

• talk.provider debe coincidir con una clave de talk.providers cuando se configuran varios proveedores de Conversación.
• Las claves planas heredadas de Conversación (talk.voiceId, talk.voiceAliases, talk.modelId, talk.outputFormat, talk.apiKey) solo existen por compatibilidad. Ejecute openclaw doctor --fix para reescribir la configuración persistente en talk.providers.<provider>.
• Los identificadores de voz recurren a ELEVENLABS_VOICE_ID o SAG_VOICE_ID como alternativa (comportamiento del cliente de Conversación de macOS).
• providers.*.apiKey acepta cadenas de texto sin formato u objetos SecretRef.
• La alternativa ELEVENLABS_API_KEY solo se aplica cuando no se configura ninguna clave de API de Conversación.
• providers.*.voiceAliases permite utilizar nombres descriptivos en las directivas de Conversación.
• providers.mlx.modelId selecciona el repositorio de Hugging Face que utiliza el asistente local de MLX de macOS. Si se omite, macOS utiliza mlx-community/Soprano-80M-bf16.
• La reproducción de MLX en macOS se realiza mediante el asistente incluido openclaw-mlx-tts, si está presente, o mediante un ejecutable disponible en PATH; OPENCLAW_MLX_TTS_BIN sobrescribe la ruta del asistente para el desarrollo.
• consultThinkingLevel controla el nivel de razonamiento de la ejecución completa del agente de OpenClaw que respalda las llamadas openclaw_agent_consult de Conversación en tiempo real de la interfaz de control. Déjelo sin establecer para conservar el comportamiento normal de la sesión y del modelo.
• consultFastMode establece una sobrescritura puntual del modo rápido para las consultas de Conversación en tiempo real de la interfaz de control sin cambiar la configuración normal del modo rápido de la sesión.
• speechLocale establece el identificador de configuración regional BCP 47 que utiliza el reconocimiento de voz de Conversación en Android, iOS y macOS. Android también utiliza su componente de idioma para orientar la transcripción de entrada en tiempo real. Déjelo sin establecer para utilizar el valor predeterminado del dispositivo.
• silenceTimeoutMs controla cuánto tiempo espera el modo Conversación tras el silencio del usuario antes de enviar la transcripción. Si no se establece, se mantiene el intervalo de pausa predeterminado de la plataforma (700 ms on macOS and Android, 900 ms on iOS).
• realtime.instructions añade instrucciones del sistema dirigidas al proveedor al prompt integrado en tiempo real de OpenClaw, lo que permite configurar el estilo de voz sin perder las indicaciones predeterminadas de openclaw_agent_consult.
• realtime.vadThreshold establece el umbral de actividad de voz del proveedor entre 0 (máxima sensibilidad) y 1 (mínima sensibilidad). Si no se establece, se mantiene el valor predeterminado del proveedor.
• realtime.silenceDurationMs establece el intervalo de silencio como número entero positivo antes de que el proveedor confirme un turno del usuario en tiempo real. Si no se establece, se mantiene el valor predeterminado del proveedor.
• realtime.prefixPaddingMs establece como número entero no negativo la cantidad de audio que se conserva antes del inicio de la voz detectada. Si no se establece, se mantiene el valor predeterminado del proveedor.
• realtime.reasoningEffort establece el nivel de razonamiento específico del proveedor para las sesiones en tiempo real. Si no se establece, se mantiene el valor predeterminado del proveedor.
• realtime.consultRouting: "provider-direct" (valor predeterminado) conserva las respuestas directas del proveedor cuando el proveedor en tiempo real genera una transcripción final del usuario sin openclaw_agent_consult. En cambio, "force-agent-consult" encamina la solicitud finalizada a través de OpenClaw.

​

Contenido relacionado

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