Configuración — agentes

​

Valores predeterminados del agente

​

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"] }, // reemplaza los valores predeterminados
      { id: "locked-down", skills: [] }, // sin Skills
    ],
  },
}

• Omite agents.defaults.skills para Skills sin restricciones por defecto.
• Omite agents.list[].skills para heredar los valores predeterminados.
• Establece agents.list[].skills: [] para no tener Skills.
• Una lista no vacía en agents.list[].skills es el conjunto final para ese agente; no se fusiona con los valores predeterminados.

​

agents.defaults.skipBootstrap

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

​

agents.defaults.contextInjection

• "continuation-skip": los turnos seguros de continuación (después de una respuesta completada del asistente) omiten la reinyección del bootstrap del espacio de trabajo, reduciendo el tamaño del prompt. Las ejecuciones de Heartbeat y los reintentos posteriores a Compaction siguen reconstruyendo el contexto.

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

​

agents.defaults.bootstrapMaxChars

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

​

agents.defaults.bootstrapTotalMaxChars

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

​

agents.defaults.bootstrapPromptTruncationWarning

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

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

​

Mapa de propiedad del presupuesto de contexto

• agents.defaults.bootstrapMaxChars / agents.defaults.bootstrapTotalMaxChars: inyección bootstrap normal del espacio de trabajo.
• agents.defaults.startupContext.*: preludio de inicio de una sola vez para ejecuciones /new y /reset, incluidos archivos recientes diarios memory/*.md.
• skills.limits.*: la lista compacta de Skills inyectada en el prompt del sistema.
• agents.defaults.contextLimits.*: extractos acotados en tiempo de ejecución y bloques inyectados propiedad del tiempo de ejecución.
• memory.qmd.limits.*: tamaño de fragmentos e inyección de búsqueda en memoria indexada.

• agents.list[].skillsLimits.maxSkillsPromptChars
• agents.list[].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,
        memoryGetDefaultLines: 120,
        toolResultMaxChars: 16000,
        postCompactionMaxChars: 1800,
      },
    },
  },
}

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

​

agents.list[].contextLimits

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

​

skills.limits.maxSkillsPromptChars

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

​

agents.list[].skillsLimits.maxSkillsPromptChars

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

​

agents.defaults.imageMaxDimensionPx

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

​

agents.defaults.userTimezone

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

​

agents.defaults.timeFormat

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

​

agents.defaults.model

{
  agents: {
    defaults: {
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "minimax/MiniMax-M2.7": { alias: "minimax" },
      },
      model: {
        primary: "anthropic/claude-opus-4-6",
        fallbacks: ["minimax/MiniMax-M2.7"],
      },
      imageModel: {
        primary: "openrouter/qwen/qwen-2.5-vl-72b-instruct:free",
        fallbacks: ["openrouter/google/gemini-2.0-flash-vision:free"],
      },
      imageGenerationModel: {
        primary: "openai/gpt-image-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" }, // parámetros globales predeterminados del proveedor
      embeddedHarness: {
        runtime: "auto", // auto | pi | id de arnés registrado, p. ej. codex
        fallback: "pi", // pi | none
      },
      pdfMaxBytesMb: 10,
      pdfMaxPages: 20,
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      contextTokens: 200000,
      maxConcurrent: 3,
    },
  },
}

• model: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • La forma de cadena establece solo el modelo principal.
  • La forma de objeto establece el principal más los modelos de conmutación por error en orden.
• imageModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la ruta de herramienta image como configuración de su modelo de visión.
  • También se usa como enrutamiento alternativo cuando el modelo seleccionado/predeterminado no puede aceptar entrada de imagen.
• imageGenerationModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la capacidad compartida de generación de imágenes y cualquier futura superficie de herramienta/plugin que genere imágenes.
  • Valores típicos: google/gemini-3.1-flash-image-preview para generación nativa de imágenes con Gemini, fal/fal-ai/flux/dev para fal, o openai/gpt-image-2 para OpenAI Images.
  • Si seleccionas un proveedor/modelo directamente, configura 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, FAL_KEY para fal/*).
  • Si se omite, image_generate aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los demás proveedores de generación de imágenes registrados en orden por 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.5+.
  • Si se omite, music_generate aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los demás proveedores de generación de música registrados en orden por ID de proveedor.
  • Si seleccionas un proveedor/modelo directamente, configura también la autenticación/clave API correspondiente del proveedor.
• 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 aún puede inferir un proveedor predeterminado respaldado por autenticación. Primero intenta con el proveedor predeterminado actual y luego con los demás proveedores de generación de video registrados en orden por ID de proveedor.
  • Si seleccionas un proveedor/modelo directamente, configura también la autenticación/clave API correspondiente del proveedor.
  • El proveedor incluido de generación de video de Qwen admite hasta 1 video de salida, 1 imagen de entrada, 4 videos de entrada, 10 segundos de duración y opciones a nivel de proveedor size, aspectRatio, resolution, audio y watermark.
• pdfModel: acepta una cadena ("provider/model") o un objeto ({ primary, fallbacks }).
  • Lo usa la herramienta pdf para el enrutamiento de modelos.
  • Si se omite, la herramienta PDF recurre a imageModel y luego al modelo resuelto de sesión/predeterminado.
• pdfMaxBytesMb: límite predeterminado de tamaño PDF para la herramienta pdf cuando no se pasa maxBytesMb al invocarla.
• pdfMaxPages: máximo predeterminado de páginas consideradas por el modo alternativo de extracción en la herramienta pdf.
• verboseDefault: nivel verbose predeterminado para los agentes. Valores: "off", "on", "full". Predeterminado: "off".
• elevatedDefault: nivel predeterminado de salida elevada para los agentes. Valores: "off", "on", "ask", "full". Predeterminado: "on".
• model.primary: formato provider/model (por ejemplo openai/gpt-5.4 para acceso con clave API u openai-codex/gpt-5.5 para OAuth de Codex). Si omites el proveedor, OpenClaw primero intenta un alias, luego una coincidencia única de proveedor configurado para ese ID exacto de modelo y solo después recurre al proveedor predeterminado configurado (comportamiento heredado obsoleto de compatibilidad, así que se prefiere provider/model explícito). Si ese proveedor ya no expone el modelo predeterminado configurado, OpenClaw recurre al primer proveedor/modelo configurado en lugar de mostrar un valor predeterminado obsoleto de un proveedor eliminado.
• models: el catálogo de modelos configurado y allowlist para /model. Cada entrada puede incluir alias (atajo) y params (específicos del proveedor, por ejemplo temperature, maxTokens, cacheRetention, context1m, responsesServerCompaction, responsesCompactThreshold).
  • Ediciones seguras: usa openclaw config set agents.defaults.models '<json>' --strict-json --merge para agregar entradas. config set rechaza reemplazos que eliminen entradas existentes de la allowlist, salvo que pases --replace.
  • Los flujos de configuración/incorporación con alcance de proveedor fusionan los modelos seleccionados del proveedor en este mapa y preservan 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 sobrescribir el umbral. Consulta Compaction del lado del servidor de OpenAI.
• params: parámetros globales predeterminados del proveedor aplicados a todos los modelos. Se establecen en agents.defaults.params (por ejemplo { cacheRetention: "long" }).
• Precedencia de fusión de params (configuración): agents.defaults.params (base global) es sobrescrito por agents.defaults.models["provider/model"].params (por modelo), y luego agents.list[].params (ID de agente coincidente) sobrescribe por clave. Consulta Prompt Caching para más detalles.
• embeddedHarness: política predeterminada de tiempo de ejecución de bajo nivel para agentes integrados. Usa runtime: "auto" para permitir que los arneses registrados por plugins reclamen modelos compatibles, runtime: "pi" para forzar el arnés integrado PI, o un ID de arnés registrado como runtime: "codex". Establece fallback: "none" para deshabilitar la alternativa automática a PI.
• Los escritores de configuración que modifican estos campos (por ejemplo /models set, /models set-image y comandos de agregar/quitar fallback) guardan la forma canónica de objeto y preservan las listas de fallback existentes cuando es posible.
• maxConcurrent: máximo de ejecuciones paralelas del agente entre sesiones (cada sesión sigue serializada). Predeterminado: 4.

​

agents.defaults.embeddedHarness

{
  agents: {
    defaults: {
      model: "openai/gpt-5.5",
      embeddedHarness: {
        runtime: "codex",
        fallback: "none",
      },
    },
  },
}

• runtime: "auto", "pi" o un ID de arnés de Plugin registrado. El Plugin incluido de Codex registra codex.
• fallback: "pi" o "none". "pi" mantiene el arnés integrado PI como alternativa de compatibilidad cuando no se selecciona ningún arnés de Plugin. "none" hace que una selección faltante o no compatible de arnés de Plugin falle en lugar de usar PI silenciosamente. Los fallos del arnés de Plugin seleccionado siempre se muestran directamente.
• Sobrescrituras por entorno: OPENCLAW_AGENT_RUNTIME=<id|auto|pi> sobrescribe runtime; OPENCLAW_AGENT_HARNESS_FALLBACK=none deshabilita la alternativa a PI para ese proceso.
• Para despliegues solo con Codex, establece model: "openai/gpt-5.5", embeddedHarness.runtime: "codex" y embeddedHarness.fallback: "none".
• La elección del arnés se fija por ID de sesión después de la primera ejecución integrada. Los cambios de config/env afectan a sesiones nuevas o reiniciadas, no a una transcripción existente. Las sesiones heredadas con historial de transcripción pero sin fijación registrada se tratan como fijadas a PI. /status muestra IDs de arnés no PI, como codex, junto a Fast.
• Esto solo controla el arnés de chat integrado. La generación de medios, visión, PDF, música, video y TTS siguen usando su configuración de proveedor/modelo.

​

agents.defaults.cliBackends

{
  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",
          systemPromptWhen: "first",
          imageArg: "--image",
          imageMode: "repeat",
        },
      },
    },
  },
}

• Los backends de CLI son de texto primero; las herramientas siempre están deshabilitadas.
• Las sesiones son compatibles cuando se establece sessionArg.
• El paso directo de imágenes es compatible cuando imageArg acepta rutas de archivo.

​

agents.defaults.systemPromptOverride

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

​

agents.defaults.promptOverlays

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

• "friendly" (predeterminado) y "on" habilitan la capa de estilo de interacción amistosa.
• "off" deshabilita solo la capa amistosa; el contrato de comportamiento etiquetado de GPT-5 permanece habilitado.
• El valor heredado plugins.entries.openai.config.personality sigue leyéndose cuando esta configuración compartida no está establecida.

​

agents.defaults.heartbeat

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m", // 0m deshabilita
        model: "openai/gpt-5.4-mini",
        includeReasoning: false,
        includeSystemPromptSection: true, // predeterminado: true; false omite la sección Heartbeat del prompt del sistema
        lightContext: false, // predeterminado: false; true mantiene solo HEARTBEAT.md de los archivos bootstrap del espacio de trabajo
        isolatedSession: false, // predeterminado: false; true ejecuta cada Heartbeat en una sesión nueva (sin historial de conversación)
        session: "main",
        to: "+15555550123",
        directPolicy: "allow", // allow (predeterminado) | block
        target: "none", // predeterminado: none | opciones: 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 API) o 1h (autenticación OAuth). Establece 0m para deshabilitar.
• includeSystemPromptSection: cuando es false, omite la sección Heartbeat del prompt del sistema y omite la inyección de HEARTBEAT.md en el contexto bootstrap. Predeterminado: true.
• suppressToolErrorWarnings: cuando es true, suprime las cargas útiles de advertencia de error de herramienta durante las ejecuciones de Heartbeat.
• timeoutSeconds: tiempo máximo en segundos permitido para un turno del agente de Heartbeat antes de abortarlo. Déjalo sin definir para usar agents.defaults.timeoutSeconds.
• directPolicy: política de entrega directa/DM. allow (predeterminado) permite entrega con destino directo. block suprime la entrega con destino directo y emite reason=dm-blocked.
• lightContext: cuando es true, las ejecuciones de Heartbeat usan contexto bootstrap ligero y conservan solo HEARTBEAT.md de los archivos bootstrap del espacio de trabajo.
• isolatedSession: cuando es true, cada Heartbeat se ejecuta en una sesión nueva sin historial previo de conversación. Mismo patrón de aislamiento que Cron sessionTarget: "isolated". Reduce el coste por Heartbeat de ~100K a ~2-5K tokens.
• Por agente: establece agents.list[].heartbeat. Cuando cualquier agente define heartbeat, solo esos agentes ejecutan Heartbeat.
• Los Heartbeats ejecutan turnos completos del agente: intervalos más cortos consumen más tokens.

​

agents.defaults.compaction

{
  agents: {
    defaults: {
      compaction: {
        mode: "safeguard", // default | safeguard
        provider: "my-provider", // id de un Plugin de proveedor de Compaction registrado (opcional)
        timeoutSeconds: 900,
        reserveTokensFloor: 24000,
        identifierPolicy: "strict", // strict | off | custom
        identifierInstructions: "Preserve deployment IDs, ticket IDs, and host:port pairs exactly.", // se usa cuando identifierPolicy=custom
        postCompactionSections: ["Session Startup", "Red Lines"], // [] deshabilita la reinyección
        model: "openrouter/anthropic/claude-sonnet-4-6", // sobrescritura opcional del modelo solo para Compaction
        notifyUser: true, // envía avisos breves cuando Compaction comienza y termina (predeterminado: false)
        memoryFlush: {
          enabled: true,
          softThresholdTokens: 6000,
          systemPrompt: "Session nearing compaction. Store durable memories now.",
          prompt: "Write any lasting notes to memory/YYYY-MM-DD.md; reply with the exact silent token NO_REPLY if nothing to store.",
        },
      },
    },
  },
}

• mode: default o safeguard (resumen fragmentado para historiales largos). Consulta Compaction.
• provider: id de un Plugin de proveedor de Compaction registrado. Cuando se establece, se llama a summarize() del proveedor en lugar del resumen LLM integrado. Recurre al integrado en caso de fallo. Establecer un proveedor fuerza mode: "safeguard". Consulta Compaction.
• timeoutSeconds: máximo de segundos permitidos para una sola operación de Compaction antes de que OpenClaw la aborte. Predeterminado: 900.
• identifierPolicy: strict (predeterminado), off o custom. strict antepone orientación integrada para conservar identificadores opacos durante el resumen de Compaction.
• identifierInstructions: texto opcional personalizado de conservación de identificadores usado cuando identifierPolicy=custom.
• postCompactionSections: nombres opcionales de secciones H2/H3 de AGENTS.md para reinyectar después de Compaction. Predeterminado ["Session Startup", "Red Lines"]; establece [] para deshabilitar la reinyección. Cuando no se define o se define explícitamente ese par predeterminado, también se aceptan los encabezados antiguos Every Session/Safety como alternativa heredada.
• model: sobrescritura opcional provider/model-id solo para el resumen de Compaction. Úsalo cuando la sesión principal deba mantener un modelo pero los resúmenes de Compaction deban ejecutarse con otro; cuando no se define, Compaction usa el modelo principal de la sesión.
• notifyUser: cuando es true, envía avisos breves al usuario cuando Compaction empieza y cuando termina (por ejemplo, “Compacting context…” y “Compaction complete”). Está deshabilitado por defecto para mantener Compaction silencioso.
• memoryFlush: turno agentivo silencioso antes de la autocompactación para almacenar memorias duraderas. Se omite cuando el espacio de trabajo es de solo lectura.

​

agents.defaults.contextPruning

{
  agents: {
    defaults: {
      contextPruning: {
        mode: "cache-ttl", // off | cache-ttl
        ttl: "1h", // duración (ms/s/m/h), unidad predeterminada: minutos
        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"] },
      },
    },
  },
}

​

Streaming 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 (usa minMs/maxMs)
    },
  },
}

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

​

Indicadores de escritura

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

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

​

agents.defaults.sandbox

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main", // off | non-main | all
        backend: "docker", // docker | ssh | openshell
        scope: "agent", // session | agent | shared
        workspaceAccess: "none", // none | ro | rw
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          containerPrefix: "openclaw-sbx-",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
          capDrop: ["ALL"],
          env: { LANG: "C.UTF-8" },
          setupCommand: "apt-get update && apt-get install -y git curl jq",
          pidsLimit: 256,
          memory: "1g",
          memorySwap: "2g",
          cpus: 1,
          ulimits: {
            nofile: { soft: 1024, hard: 2048 },
            nproc: 256,
          },
          seccompProfile: "/path/to/seccomp.json",
          apparmorProfile: "openclaw-sandbox",
          dns: ["1.1.1.1", "8.8.8.8"],
          extraHosts: ["internal.service:10.0.0.5"],
          binds: ["/home/user/source:/source:rw"],
        },
        ssh: {
          target: "user@gateway-host:22",
          command: "ssh",
          workspaceRoot: "/tmp/openclaw-sandboxes",
          strictHostKeyChecking: true,
          updateHostKeys: true,
          identityFile: "~/.ssh/id_ed25519",
          certificateFile: "~/.ssh/id_ed25519-cert.pub",
          knownHostsFile: "~/.ssh/known_hosts",
          // SecretRefs / contenido inline también compatibles:
          // 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", // opcional
          gatewayEndpoint: "https://lab.example", // opcional
          policy: "strict", // id opcional de política de OpenShell
          providers: ["openai"], // opcional
          autoProviders: true,
          timeoutSeconds: 120,
        },
      },
    },
  },
}

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

​

agents.list (sobrescrituras 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 }
        thinkingDefault: "high", // sobrescritura por agente del nivel de thinking
        reasoningDefault: "on", // sobrescritura por agente de la visibilidad del razonamiento
        fastModeDefault: false, // sobrescritura por agente del modo rápido
        embeddedHarness: { runtime: "auto", fallback: "pi" },
        params: { cacheRetention: "none" }, // sobrescribe por clave los params coincidentes de defaults.models
        skills: ["docs-search"], // reemplaza agents.defaults.skills cuando se establece
        identity: {
          name: "Samantha",
          theme: "helpful sloth",
          emoji: "🦥",
          avatar: "avatars/samantha.png",
        },
        groupChat: { mentionPatterns: ["@openclaw"] },
        sandbox: { mode: "off" },
        runtime: {
          type: "acp",
          acp: {
            agent: "codex",
            backend: "acpx",
            mode: "persistent",
            cwd: "/workspace/openclaw",
          },
        },
        subagents: { allowAgents: ["*"] },
        tools: {
          profile: "coding",
          allow: ["browser"],
          deny: ["canvas"],
          elevated: { enabled: true },
        },
      },
    ],
  },
}

• id: ID estable del agente (obligatorio).
• default: cuando se establecen varios, gana 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 sobrescribe solo primary; la forma de objeto { primary, fallbacks } sobrescribe ambos ([] deshabilita los fallbacks globales). Los trabajos Cron que solo sobrescriben primary siguen heredando los fallbacks predeterminados salvo que establezcas fallbacks: [].
• params: parámetros de stream por agente fusionados sobre la entrada de modelo seleccionada en agents.defaults.models. Úsalo para sobrescrituras específicas del agente como cacheRetention, temperature o maxTokens sin duplicar todo el catálogo de modelos.
• skills: allowlist opcional de Skills por agente. Si se omite, el agente hereda agents.defaults.skills cuando está definido; una lista explícita reemplaza los valores predeterminados en lugar de fusionarse, y [] significa sin Skills.
• thinkingDefault: valor predeterminado opcional por agente para el nivel de thinking (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.
• reasoningDefault: valor predeterminado opcional por agente para la visibilidad del razonamiento (on | off | stream). Se aplica cuando no se establece ninguna sobrescritura por mensaje o sesión del razonamiento.
• fastModeDefault: valor predeterminado opcional por agente para el modo rápido (true | false). Se aplica cuando no se establece ninguna sobrescritura por mensaje o sesión del modo rápido.
• embeddedHarness: sobrescritura opcional por agente de la política de arnés de bajo nivel. Usa { runtime: "codex", fallback: "none" } para hacer que un agente sea solo Codex mientras otros agentes conservan la alternativa predeterminada a PI.
• runtime: descriptor opcional de tiempo de ejecución por agente. Usa type: "acp" con valores predeterminados en runtime.acp (agent, backend, mode, cwd) cuando el agente deba usar por defecto sesiones de arnés ACP.
• identity.avatar: ruta relativa al espacio de trabajo, URL http(s) o URI data:.
• identity deriva valores predeterminados: ackReaction a partir de emoji, mentionPatterns a partir de name/emoji.
• subagents.allowAgents: allowlist de IDs de agente para sessions_spawn (["*"] = cualquiera; predeterminado: solo el mismo agente).
• Protección de herencia de sandbox: si la sesión solicitante está en sandbox, sessions_spawn rechaza destinos que se ejecutarían sin sandbox.
• subagents.requireAgentId: cuando es true, bloquea llamadas sessions_spawn que omiten agentId (fuerza selección explícita de perfil; predeterminado: false).

​

Enrutamiento multiagente

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

​

Campos de coincidencia de binding

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

1. match.peer
2. match.guildId
3. match.teamId
4. match.accountId (exacto, sin peer/guild/team)
5. match.accountId: "*" (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 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/{agentId}/sessions/sessions.json",
    parentForkMaxTokens: 100000, // omitir bifurcación del hilo padre por encima de este recuento de tokens (0 deshabilita)
    maintenance: {
      mode: "warn", // warn | enforce
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
      resetArchiveRetention: "30d", // duración o false
      maxDiskBytes: "500mb", // presupuesto rígido opcional
      highWaterBytes: "400mb", // objetivo opcional de limpieza
    },
    threadBindings: {
      enabled: true,
      idleHours: 24, // desfoco automático predeterminado por inactividad en horas (`0` deshabilita)
      maxAgeHours: 0, // antigüedad máxima rígida predeterminada en horas (`0` deshabilita)
    },
    mainKey: "main", // heredado (el tiempo de ejecución siempre usa "main")
    agentToAgent: { maxPingPongTurns: 5 },
    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
    removeAckAfterReply: false,
    queue: {
      mode: "collect", // steer | followup | collect | steer-backlog | steer+backlog | queue | interrupt
      debounceMs: 1000,
      cap: 20,
      drop: "summarize", // old | new | summarize
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
      },
    },
    inbound: {
      debounceMs: 2000, // 0 deshabilita
      byChannel: {
        whatsapp: 5000,
        slack: 1500,
      },
    },
  },
}

​

Prefijo de respuesta

​

Reacción de confirmación

• Usa por defecto identity.emoji del agente activo; en caso contrario "👀". Establece "" para deshabilitar.
• Sobrescrituras por canal: channels.<channel>.ackReaction, channels.<channel>.accounts.<id>.ackReaction.
• Orden de resolución: cuenta → canal → messages.ackReaction → alternativa desde identity.
• Alcance: group-mentions (predeterminado), group-all, direct, all.
• removeAckAfterReply: elimina la confirmación tras responder en Slack, Discord y Telegram.
• messages.statusReactions.enabled: habilita reacciones de estado del ciclo de vida en Slack, Discord y Telegram. En Slack y Discord, dejarlo sin definir mantiene habilitadas las reacciones de estado cuando las reacciones de confirmación están activas. En Telegram, establécelo explícitamente en true para habilitar las reacciones de estado del ciclo de vida.

​

Debounce de entrada

​

TTS (texto a voz)

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

• auto controla el 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 por defecto; modelOverrides.allowProvider usa por defecto false (requiere habilitación explícita).
• Las claves API recurren a ELEVENLABS_API_KEY/XI_API_KEY y OPENAI_API_KEY.
• openai.baseUrl sobrescribe el endpoint TTS de OpenAI. El orden de resolución es config, luego OPENAI_TTS_BASE_URL, luego https://api.openai.com/v1.
• Cuando openai.baseUrl apunta a un endpoint que no es de OpenAI, OpenClaw lo trata como un servidor TTS compatible con OpenAI y relaja la validación de modelo/voz.

​

Talk

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

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