Referencia de configuración

Referencia de configuración central para ~/.openclaw/openclaw.json. Para una vista general orientada a tareas, consulta Configuración.

Cubre las principales superficies de configuración de OpenClaw y enlaza hacia otras páginas cuando un subsistema tiene su propia referencia más profunda. Los catálogos de comandos propiedad de canales y plugins, y los controles profundos de memoria/QMD, viven en sus propias páginas en lugar de esta.

Fuente de verdad del código:

• openclaw config schema imprime el JSON Schema activo usado para la validación y la Control UI, con metadatos de paquetes incluidos/plugins/canales fusionados cuando están disponibles
• config.schema.lookup devuelve un nodo de esquema con ámbito de ruta para herramientas de exploración detallada
• pnpm config:docs:check / pnpm config:docs:gen validan el hash de referencia de la documentación de configuración contra la superficie de esquema actual

Ruta de búsqueda del agente: usa la acción de herramienta gateway config.schema.lookup para obtener documentación y restricciones exactas a nivel de campo antes de editar. Usa Configuración para orientación orientada a tareas y esta página para el mapa de campos más amplio, valores predeterminados y enlaces a referencias de subsistemas.

Referencias profundas dedicadas:

• Referencia de configuración de memoria para agents.defaults.memorySearch.*, memory.qmd.*, memory.citations y la configuración de dreaming en plugins.entries.memory-core.config.dreaming
• Comandos slash para el catálogo actual de comandos integrados + incluidos
• páginas de canales/plugins propietarios para superficies de comandos específicas del canal

El formato de configuración es JSON5 (se permiten comentarios y comas finales). Todos los campos son opcionales: OpenClaw usa valores predeterminados seguros cuando se omiten.

# Canales

Las claves de configuración por canal se movieron a una página dedicada: consulta Configuración - canales para channels.*, incluidos Slack, Discord, Telegram, WhatsApp, Matrix, iMessage y otros canales incluidos (autenticación, control de acceso, múltiples cuentas, control de menciones).

# Valores predeterminados de agentes, multiagente, sesiones y mensajes

Movido a una página dedicada: consulta Configuración - agentes para:

• agents.defaults.* (espacio de trabajo, modelo, pensamiento, heartbeat, memoria, medios, skills, sandbox)
• multiAgent.* (enrutamiento y enlaces multiagente)
• session.* (ciclo de vida de sesión, compaction, poda)
• messages.* (entrega de mensajes, TTS, renderizado de markdown)
• talk.* (modo Talk)
  • talk.speechLocale: id de locale BCP 47 opcional para reconocimiento de voz de Talk en iOS/macOS
  • talk.silenceTimeoutMs: cuando no se establece, Talk mantiene la ventana de pausa predeterminada de la plataforma antes de enviar la transcripción (700 ms on macOS and Android, 900 ms on iOS)

# Herramientas y proveedores personalizados

La política de herramientas, los interruptores experimentales, la configuración de herramientas respaldadas por proveedores y la configuración de proveedor personalizado / URL base se movieron a una página dedicada: consulta Configuración - herramientas y proveedores personalizados.

# Modelos

Las definiciones de proveedores, listas de modelos permitidos y configuración de proveedores personalizados viven en Configuración - herramientas y proveedores personalizados. La raíz models también controla el comportamiento global del catálogo de modelos.

{
  models: {
    // Optional. Default: true. Requires a Gateway restart when changed.
    pricing: { enabled: false },
  },
}

• models.mode: comportamiento del catálogo de proveedores (merge o replace).
• models.providers: mapa de proveedores personalizados indexado por id de proveedor.
• models.pricing.enabled: controla el arranque de precios en segundo plano que comienza después de que los sidecars y canales alcancen la ruta de Gateway listo. Cuando es false, el Gateway omite las consultas a los catálogos de precios de OpenRouter y LiteLLM; los valores configurados models.providers.*.models[].cost siguen funcionando para estimaciones de coste locales.

# MCP

Las definiciones de servidores MCP administradas por OpenClaw viven bajo mcp.servers y son consumidas por Pi integrado y otros adaptadores de runtime. Los comandos openclaw mcp list, show, set y unset administran este bloque sin conectarse al servidor de destino durante las ediciones de configuración.

{
  mcp: {
    // Optional. Default: 600000 ms (10 minutes). Set 0 to disable idle eviction.
    sessionIdleTtlMs: 600000,
    servers: {
      docs: {
        command: "npx",
        args: ["-y", "@modelcontextprotocol/server-fetch"],
      },
      remote: {
        url: "https://example.com/mcp",
        transport: "streamable-http", // streamable-http | sse
        headers: {
          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",
        },
      },
    },
  },
}

• mcp.servers: definiciones con nombre de servidores MCP stdio o remotos para runtimes que exponen herramientas MCP configuradas. Las entradas remotas usan transport: "streamable-http" o transport: "sse"; type: "http" es un alias nativo de CLI que openclaw mcp set y openclaw doctor --fix normalizan al campo canónico transport.
• mcp.sessionIdleTtlMs: TTL de inactividad para runtimes MCP incluidos con ámbito de sesión. Las ejecuciones integradas de un solo uso solicitan limpieza al final de la ejecución; este TTL es el respaldo para sesiones de larga duración y llamadores futuros.
• Los cambios bajo mcp.* se aplican en caliente descartando los runtimes MCP de sesión en caché. El siguiente descubrimiento/uso de herramientas los recrea desde la nueva configuración, por lo que las entradas eliminadas de mcp.servers se recolectan inmediatamente en lugar de esperar el TTL de inactividad.

Consulta MCP y Backends de CLI para el comportamiento de runtime.

# Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
    },
    entries: {
      "image-lab": {
        apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" }, // or plaintext string
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
      sag: { enabled: false },
    },
  },
}

• allowBundled: lista de permitidos opcional solo para Skills incluidos (los Skills administrados/de espacio de trabajo no se ven afectados).
• load.extraDirs: raíces adicionales compartidas de Skills (menor precedencia).
• install.preferBrew: cuando es true, prefiere instaladores de Homebrew cuando brew está disponible antes de recurrir a otros tipos de instalador.
• install.nodeManager: preferencia de instalador de node para especificaciones metadata.openclaw.install (npm | pnpm | yarn | bun).
• entries.<skillKey>.enabled: false deshabilita un Skill incluso si está incluido/instalado.
• entries.<skillKey>.apiKey: conveniencia para Skills que declaran una variable de entorno primaria (cadena de texto plano u objeto SecretRef).

# Plugins

{
  plugins: {
    enabled: true,
    allow: ["voice-call"],
    bundledDiscovery: "allowlist",
    deny: [],
    load: {
      paths: ["~/Projects/oss/voice-call-plugin"],
    },
    entries: {
      "voice-call": {
        enabled: true,
        hooks: {
          allowPromptInjection: false,
        },
        config: { provider: "twilio" },
      },
    },
  },
}

• Cargados desde ~/.openclaw/extensions, <workspace>/.openclaw/extensions, más plugins.load.paths.
• El descubrimiento acepta plugins nativos de OpenClaw, además de paquetes Codex compatibles y paquetes Claude, incluidos paquetes Claude sin manifiesto con diseño predeterminado.
• Los cambios de configuración requieren reiniciar el gateway.
• allow: lista de permitidos opcional (solo se cargan los plugins listados). deny prevalece.
• bundledDiscovery: el valor predeterminado para configuraciones nuevas es "allowlist", por lo que un plugins.allow no vacío también limita los plugins de proveedor incluidos, incluidos los proveedores de runtime de búsqueda web. Doctor escribe "compat" para configuraciones de lista de permitidos heredadas migradas para preservar el comportamiento existente de proveedores incluidos hasta que optes por activarlo.
• plugins.entries.<id>.apiKey: campo de conveniencia para clave de API a nivel de plugin (cuando el plugin lo admite).
• plugins.entries.<id>.env: mapa de variables de entorno con ámbito de plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: cuando es false, el core bloquea before_prompt_build e ignora campos que mutan el prompt desde el before_agent_start heredado, conservando modelOverride y providerOverride heredados. Se aplica a hooks de plugins nativos y directorios de hooks proporcionados por paquetes compatibles.
• plugins.entries.<id>.hooks.allowConversationAccess: cuando es true, plugins no incluidos de confianza pueden leer contenido bruto de conversación desde hooks tipados como llm_input, llm_output, before_model_resolve, before_agent_reply, before_agent_run, before_agent_finalize y agent_end.
• plugins.entries.<id>.subagent.allowModelOverride: confía explícitamente en este plugin para solicitar sustituciones de provider y model por ejecución para ejecuciones de subagentes en segundo plano.
• plugins.entries.<id>.subagent.allowedModels: lista de permitidos opcional de objetivos canónicos provider/model para sustituciones de subagentes de confianza. Usa "*" solo cuando intencionalmente quieras permitir cualquier modelo.
• plugins.entries.<id>.config: objeto de configuración definido por el plugin (validado por el esquema de plugin nativo de OpenClaw cuando está disponible).
• La configuración de cuenta/runtime de plugins de canal vive bajo channels.<id> y debe estar descrita por los metadatos channelConfigs del manifiesto del plugin propietario, no por un registro central de opciones de OpenClaw.
• plugins.entries.firecrawl.config.webFetch: configuración del proveedor de obtención web Firecrawl.
  • apiKey: clave de API de Firecrawl (acepta SecretRef). Recurre a plugins.entries.firecrawl.config.webSearch.apiKey, al heredado tools.web.fetch.firecrawl.apiKey o a la variable de entorno FIRECRAWL_API_KEY.
  • baseUrl: URL base de la API de Firecrawl (predeterminada: https://api.firecrawl.dev; las sustituciones autoalojadas deben apuntar a endpoints privados/internos).
  • onlyMainContent: extrae solo el contenido principal de las páginas (predeterminado: true).
  • maxAgeMs: edad máxima de caché en milisegundos (predeterminado: 172800000 / 2 días).
  • timeoutSeconds: tiempo de espera de solicitud de scraping en segundos (predeterminado: 60).
• plugins.entries.xai.config.xSearch: configuración de xAI X Search (búsqueda web de Grok).
  • enabled: habilita el proveedor X Search.
  • model: modelo Grok que se debe usar para la búsqueda (p. ej. "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: configuración de dreaming de memoria. Consulta Dreaming para fases y umbrales.
  • enabled: interruptor maestro de dreaming (predeterminado false).
  • frequency: cadencia cron para cada barrido completo de dreaming ("0 3 * * *" de forma predeterminada).
  • model: sustitución opcional del modelo de subagente Dream Diary. Requiere plugins.entries.memory-core.subagent.allowModelOverride: true; combínalo con allowedModels para restringir objetivos. Los errores de modelo no disponible reintentan una vez con el modelo predeterminado de la sesión; los fallos de confianza o lista de permitidos no recurren a alternativas silenciosamente.
  • la política y los umbrales de fase son detalles de implementación (no claves de configuración orientadas al usuario).
• La configuración completa de memoria vive en Referencia de configuración de memoria:
  • agents.defaults.memorySearch.*
  • memory.backend
  • memory.citations
  • memory.qmd.*
  • plugins.entries.memory-core.config.dreaming
• Los plugins de paquete Claude habilitados también pueden aportar valores predeterminados de Pi integrado desde settings.json; OpenClaw los aplica como ajustes de agente saneados, no como parches brutos de configuración de OpenClaw.
• plugins.slots.memory: elige el id del plugin de memoria activo, o "none" para deshabilitar los plugins de memoria.
• plugins.slots.contextEngine: elige el id del plugin de motor de contexto activo; el valor predeterminado es "legacy" salvo que instales y selecciones otro motor.

Consulta Plugins.

# Compromisos

commitments controla la memoria de seguimiento inferida: OpenClaw puede detectar check-ins a partir de turnos de conversación y entregarlos mediante ejecuciones de heartbeat.

• commitments.enabled: habilita la extracción LLM oculta, almacenamiento y entrega por heartbeat de compromisos de seguimiento inferidos. Predeterminado: false.
• commitments.maxPerDay: número máximo de compromisos de seguimiento inferidos entregados por sesión de agente en un día móvil. Predeterminado: 3.

Consulta Compromisos inferidos.

# Navegador

{
  browser: {
    enabled: true,
    evaluateEnabled: true,
    defaultProfile: "user",
    ssrfPolicy: {
      // dangerouslyAllowPrivateNetwork: true, // opt in only for trusted private-network access
      // allowPrivateNetwork: true, // legacy alias
      // hostnameAllowlist: ["*.example.com", "example.com"],
      // allowedHostnames: ["localhost"],
    },
    tabCleanup: {
      enabled: true,
      idleMinutes: 120,
      maxTabsPerSession: 8,
      sweepMinutes: 5,
    },
    profiles: {
      openclaw: { cdpPort: 18800, color: "#FF4500" },
      work: {
        cdpPort: 18801,
        color: "#0066CC",
        executablePath: "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome",
      },
      user: { driver: "existing-session", attachOnly: true, color: "#00AA00" },
      brave: {
        driver: "existing-session",
        attachOnly: true,
        userDataDir: "~/Library/Application Support/BraveSoftware/Brave-Browser",
        color: "#FB542B",
      },
      remote: { cdpUrl: "http://10.0.0.42:9222", color: "#00AA00" },
    },
    color: "#FF4500",
    // headless: false,
    // noSandbox: false,
    // extraArgs: [],
    // executablePath: "/Applications/Brave Browser.app/Contents/MacOS/Brave Browser",
    // attachOnly: false,
  },
}

• evaluateEnabled: false desactiva act:evaluate y wait --fn.
• tabCleanup recupera las pestañas rastreadas del agente principal después del tiempo de inactividad o cuando una sesión supera su límite. Establece idleMinutes: 0 o maxTabsPerSession: 0 para desactivar esos modos de limpieza individuales.
• ssrfPolicy.dangerouslyAllowPrivateNetwork está desactivado cuando no se establece, por lo que la navegación del navegador se mantiene estricta de forma predeterminada.
• Establece ssrfPolicy.dangerouslyAllowPrivateNetwork: true solo cuando confíes intencionadamente en la navegación del navegador por red privada.
• En modo estricto, los endpoints de perfiles CDP remotos (profiles.*.cdpUrl) están sujetos al mismo bloqueo de red privada durante las comprobaciones de accesibilidad/detección.
• ssrfPolicy.allowPrivateNetwork sigue siendo compatible como alias heredado.
• En modo estricto, usa ssrfPolicy.hostnameAllowlist y ssrfPolicy.allowedHostnames para excepciones explícitas.
• Los perfiles remotos son solo de adjunción (inicio/detención/restablecimiento desactivados).
• profiles.*.cdpUrl acepta http://, https://, ws:// y wss://. Usa HTTP(S) cuando quieras que OpenClaw detecte /json/version; usa WS(S) cuando tu proveedor te dé una URL directa de WebSocket de DevTools.
• remoteCdpTimeoutMs y remoteCdpHandshakeTimeoutMs se aplican a la accesibilidad de CDP remoto y attachOnly, además de a las solicitudes de apertura de pestañas. Los perfiles administrados de loopback mantienen los valores predeterminados de CDP local.
• Si se puede acceder a un servicio CDP administrado externamente a través de loopback, establece attachOnly: true en ese perfil; de lo contrario, OpenClaw trata el puerto de loopback como un perfil de navegador administrado localmente y puede informar errores de propiedad del puerto local.
• Los perfiles existing-session usan Chrome MCP en lugar de CDP y pueden adjuntarse en el host seleccionado o mediante un nodo de navegador conectado.
• Los perfiles existing-session pueden establecer userDataDir para apuntar a un perfil de navegador basado en Chromium específico, como Brave o Edge.
• Los perfiles existing-session mantienen los límites actuales de ruta de Chrome MCP: acciones impulsadas por instantáneas/referencias en lugar de segmentación por selectores CSS, hooks de carga de un solo archivo, sin anulaciones de tiempo de espera de diálogos, sin wait --load networkidle y sin responsebody, exportación a PDF, interceptación de descargas ni acciones por lotes.
• Los perfiles administrados locales openclaw asignan automáticamente cdpPort y cdpUrl; solo establece cdpUrl explícitamente para CDP remoto.
• Los perfiles administrados locales pueden establecer executablePath para reemplazar el browser.executablePath global para ese perfil. Usa esto para ejecutar un perfil en Chrome y otro en Brave.
• Los perfiles administrados locales usan browser.localLaunchTimeoutMs para la detección HTTP de Chrome CDP después del inicio del proceso y browser.localCdpReadyTimeoutMs para la preparación del websocket CDP posterior al lanzamiento. Auméntalos en hosts más lentos donde Chrome se inicia correctamente, pero las comprobaciones de preparación compiten con el arranque. Ambos valores deben ser enteros positivos de hasta 120000 ms; los valores de configuración no válidos se rechazan.
• Orden de detección automática: navegador predeterminado si está basado en Chromium → Chrome → Brave → Edge → Chromium → Chrome Canary.
• browser.executablePath y browser.profiles.<name>.executablePath aceptan ~ y ~/... para el directorio de inicio de tu SO antes de lanzar Chromium. userDataDir por perfil en perfiles existing-session también se expande con tilde.
• Servicio de control: solo loopback (puerto derivado de gateway.port, predeterminado 18791).
• extraArgs agrega flags de lanzamiento adicionales al inicio local de Chromium (por ejemplo --disable-gpu, tamaño de ventana o flags de depuración).

# Interfaz de usuario

{
  ui: {
    seamColor: "#FF4500",
    assistant: {
      name: "OpenClaw",
      avatar: "CB", // emoji, short text, image URL, or data URI
    },
  },
}

• seamColor: color de acento para el contorno de la interfaz de usuario de la app nativa (tinte de burbuja del modo de conversación, etc.).
• assistant: anulación de identidad de la interfaz de usuario de Control. Recurre a la identidad del agente activo.

# Gateway

{
  gateway: {
    mode: "local", // local | remote
    port: 18789,
    bind: "loopback",
    auth: {
      mode: "token", // none | token | password | trusted-proxy
      token: "your-token",
      // password: "your-password", // or OPENCLAW_GATEWAY_PASSWORD
      // trustedProxy: { userHeader: "x-forwarded-user" }, // for mode=trusted-proxy; see /gateway/trusted-proxy-auth
      allowTailscale: true,
      rateLimit: {
        maxAttempts: 10,
        windowMs: 60000,
        lockoutMs: 300000,
        exemptLoopback: true,
      },
    },
    tailscale: {
      mode: "off", // off | serve | funnel
      resetOnExit: false,
    },
    controlUi: {
      enabled: true,
      basePath: "/openclaw",
      // root: "dist/control-ui",
      // embedSandbox: "scripts", // strict | scripts | trusted
      // allowExternalEmbedUrls: false, // dangerous: allow absolute external http(s) embed URLs
      // chatMessageMaxWidth: "min(1280px, 82%)", // optional grouped chat message max-width
      // allowedOrigins: ["https://control.example.com"], // required for non-loopback Control UI
      // dangerouslyAllowHostHeaderOriginFallback: false, // dangerous Host-header origin fallback mode
      // allowInsecureAuth: false,
      // dangerouslyDisableDeviceAuth: false,
    },
    remote: {
      url: "ws://gateway.tailnet:18789",
      transport: "ssh", // ssh | direct
      token: "your-token",
      // password: "your-password",
    },
    trustedProxies: ["10.0.0.1"],
    // Optional. Default false.
    allowRealIpFallback: false,
    nodes: {
      pairing: {
        // Optional. Default unset/disabled.
        autoApproveCidrs: ["192.168.1.0/24", "fd00:1234:5678::/64"],
      },
      allowCommands: ["canvas.navigate"],
      denyCommands: ["system.run"],
    },
    tools: {
      // Additional /tools/invoke HTTP denies
      deny: ["browser"],
      // Remove tools from the default HTTP deny list
      allow: ["gateway"],
    },
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          timeoutMs: 10000,
        },
      },
    },
  },
}

# Endpoints compatibles con OpenAI

• Chat Completions: deshabilitado de forma predeterminada. Habilítalo con gateway.http.endpoints.chatCompletions.enabled: true.
• Responses API: gateway.http.endpoints.responses.enabled.
• Refuerzo de entradas URL de Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Las allowlists vacías se tratan como no establecidas; usa gateway.http.endpoints.responses.files.allowUrl=false y/o gateway.http.endpoints.responses.images.allowUrl=false para deshabilitar la obtención de URL.
• Cabecera opcional de refuerzo de respuestas:
  • gateway.http.securityHeaders.strictTransportSecurity (establécela solo para orígenes HTTPS que controles; consulta Autenticación de proxy de confianza)

# Aislamiento de varias instancias

Ejecuta varios Gateways en un host con puertos y directorios de estado únicos:

OPENCLAW_CONFIG_PATH=~/.openclaw/a.json \
OPENCLAW_STATE_DIR=~/.openclaw-a \
openclaw gateway --port 19001

Flags de conveniencia: --dev (usa ~/.openclaw-dev + puerto 19001), --profile <name> (usa ~/.openclaw-<name>).

Consulta Varios Gateways.

# gateway.tls

{
  gateway: {
    tls: {
      enabled: false,
      autoGenerate: false,
      certPath: "/etc/openclaw/tls/server.crt",
      keyPath: "/etc/openclaw/tls/server.key",
      caPath: "/etc/openclaw/tls/ca-bundle.crt",
    },
  },
}

• enabled: habilita la terminación TLS en el listener del Gateway (HTTPS/WSS) (predeterminado: false).
• autoGenerate: genera automáticamente un par cert/key autofirmado local cuando no se configuran archivos explícitos; solo para uso local/dev.
• certPath: ruta del sistema de archivos al archivo de certificado TLS.
• keyPath: ruta del sistema de archivos al archivo de clave privada TLS; mantenla con permisos restringidos.
• caPath: ruta opcional a un bundle de CA para verificación de cliente o cadenas de confianza personalizadas.

# gateway.reload

{
  gateway: {
    reload: {
      mode: "hybrid", // off | restart | hot | hybrid
      debounceMs: 500,
      deferralTimeoutMs: 300000,
    },
  },
}

• mode: controla cómo se aplican las ediciones de configuración en tiempo de ejecución.
  • "off": ignora las ediciones en vivo; los cambios requieren un reinicio explícito.
  • "restart": reinicia siempre el proceso del Gateway ante un cambio de configuración.
  • "hot": aplica cambios en el proceso sin reiniciar.
  • "hybrid" (predeterminado): intenta primero una recarga hot; vuelve a reiniciar si es necesario.
• debounceMs: ventana de debounce en ms antes de que se apliquen los cambios de configuración (entero no negativo).
• deferralTimeoutMs: tiempo máximo opcional en ms para esperar operaciones en curso antes de forzar un reinicio o una recarga hot de canal. Omítelo para usar la espera acotada predeterminada (300000); establécelo en 0 para esperar indefinidamente y registrar advertencias periódicas de pendientes.

# Hooks

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    maxBodyBytes: 262144,
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: true,
    allowedSessionKeyPrefixes: ["hook:", "hook:gmail:"],
    allowedAgentIds: ["hooks", "main"],
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks/transforms",
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "hooks",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}\n{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        model: "openai/gpt-5.4-mini",
      },
    ],
  },
}

Autenticación: Authorization: Bearer <token> o x-openclaw-token: <token>. Se rechazan los tokens de hook en la cadena de consulta.

Notas de validación y seguridad:

• hooks.enabled=true requiere un hooks.token no vacío.
• hooks.token debe ser distinto de gateway.auth.token; se rechaza reutilizar el token de Gateway.
• hooks.path no puede ser /; usa una subruta dedicada como /hooks.
• Si hooks.allowRequestSessionKey=true, limita hooks.allowedSessionKeyPrefixes (por ejemplo, ["hook:"]).
• Si un mapeo o preajuste usa un sessionKey con plantilla, establece hooks.allowedSessionKeyPrefixes y hooks.allowRequestSessionKey=true. Las claves de mapeo estáticas no requieren esa adhesión explícita.

Endpoints:

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • El sessionKey de la carga útil de la solicitud solo se acepta cuando hooks.allowRequestSessionKey=true (predeterminado: false).
• POST /hooks/<name> → se resuelve mediante hooks.mappings
  • Los valores de sessionKey de mapeo renderizados desde plantillas se tratan como suministrados externamente y también requieren hooks.allowRequestSessionKey=true.

# Integración de Gmail

• El preajuste integrado de Gmail usa sessionKey: "hook:gmail:{{messages[0].id}}".
• Si conservas ese enrutamiento por mensaje, establece hooks.allowRequestSessionKey: true y limita hooks.allowedSessionKeyPrefixes para que coincida con el espacio de nombres de Gmail, por ejemplo ["hook:", "hook:gmail:"].
• Si necesitas hooks.allowRequestSessionKey: false, sustituye el preajuste con un sessionKey estático en lugar del predeterminado con plantilla.

{
  hooks: {
    gmail: {
      account: "[email protected]",
      topic: "projects/<project-id>/topics/gog-gmail-watch",
      subscription: "gog-gmail-watch-push",
      pushToken: "shared-push-token",
      hookUrl: "http://127.0.0.1:18789/hooks/gmail",
      includeBody: true,
      maxBytes: 20000,
      renewEveryMinutes: 720,
      serve: { bind: "127.0.0.1", port: 8788, path: "/" },
      tailscale: { mode: "funnel", path: "/gmail-pubsub" },
      model: "openrouter/meta-llama/llama-3.3-70b-instruct:free",
      thinking: "off",
    },
  },
}

• Gateway inicia automáticamente gog gmail watch serve al arrancar cuando está configurado. Establece OPENCLAW_SKIP_GMAIL_WATCHER=1 para desactivarlo.
• No ejecutes un gog gmail watch serve separado junto con Gateway.

# Host del plugin Canvas

{
  plugins: {
    entries: {
      canvas: {
        config: {
          host: {
            root: "~/.openclaw/workspace/canvas",
            liveReload: true,
            // enabled: false, // or OPENCLAW_SKIP_CANVAS_HOST=1
          },
        },
      },
    },
  },
}

• Sirve HTML/CSS/JS editables por agentes y A2UI mediante HTTP bajo el puerto de Gateway:
  • http://<gateway-host>:<gateway.port>/__openclaw__/canvas/
  • http://<gateway-host>:<gateway.port>/__openclaw__/a2ui/
• Solo local: mantén gateway.bind: "loopback" (predeterminado).
• Enlaces que no son de loopback: las rutas de canvas requieren autenticación de Gateway (token/contraseña/proxy de confianza), igual que otras superficies HTTP de Gateway.
• Las WebViews de Node normalmente no envían encabezados de autenticación; después de que un nodo se empareja y se conecta, Gateway anuncia URL de capacidad con alcance de nodo para el acceso a canvas/A2UI.
• Las URL de capacidad están vinculadas a la sesión WS activa del nodo y expiran rápidamente. No se usa respaldo basado en IP.
• Inyecta el cliente de recarga en vivo en el HTML servido.
• Crea automáticamente un index.html inicial cuando está vacío.
• También sirve A2UI en /__openclaw__/a2ui/.
• Los cambios requieren reiniciar Gateway.
• Desactiva la recarga en vivo para directorios grandes o errores EMFILE.

# Detección

# mDNS (Bonjour)

{
  discovery: {
    mdns: {
      mode: "minimal", // minimal | full | off
    },
  },
}

• minimal (predeterminado cuando el plugin bonjour incluido está habilitado): omite cliPath + sshPort de los registros TXT.
• full: incluye cliPath + sshPort; el anuncio multicast en LAN todavía requiere que el plugin bonjour incluido esté habilitado.
• off: suprime el anuncio multicast en LAN sin cambiar la habilitación del plugin.
• El plugin bonjour incluido se inicia automáticamente en hosts macOS y es opcional en Linux, Windows y despliegues de Gateway en contenedores.
• El nombre de host usa de forma predeterminada el nombre de host del sistema cuando es una etiqueta DNS válida, con respaldo a openclaw. Sustitúyelo con OPENCLAW_MDNS_HOSTNAME.

# Área amplia (DNS-SD)

{
  discovery: {
    wideArea: { enabled: true },
  },
}

Escribe una zona DNS-SD unicast bajo ~/.openclaw/dns/. Para la detección entre redes, combínalo con un servidor DNS (se recomienda CoreDNS) + DNS dividido de Tailscale.

Configuración: openclaw dns setup --apply.

# Entorno

# env (variables de entorno en línea)

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },
}

• Las variables de entorno en línea solo se aplican si el entorno del proceso no tiene la clave.
• Archivos .env: .env del CWD + ~/.openclaw/.env (ninguno sobrescribe variables existentes).
• shellEnv: importa las claves esperadas faltantes desde tu perfil de shell de inicio de sesión.
• Consulta Entorno para ver la precedencia completa.

# Sustitución de variables de entorno

Referencia variables de entorno en cualquier cadena de configuración con ${VAR_NAME}:

{
  gateway: {
    auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" },
  },
}

• Solo coinciden nombres en mayúsculas: [A-Z_][A-Z0-9_]*.
• Las variables faltantes/vacías generan un error al cargar la configuración.
• Escapa con $${VAR} para un ${VAR} literal.
• Funciona con $include.

# Secretos

Las referencias a secretos son aditivas: los valores en texto plano siguen funcionando.

# SecretRef

Usa una forma de objeto:

{ source: "env" | "file" | "exec", provider: "default", id: "..." }

Validación:

• Patrón de provider: ^[a-z][a-z0-9_-]{0,63}$
• Patrón de id de source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• Id de source: "file": puntero JSON absoluto (por ejemplo "/providers/openai/apiKey")
• Patrón de id de source: "exec": ^[A-Za-z0-9][A-Za-z0-9._:/-]{0,255}$
• Los ids de source: "exec" no deben contener segmentos de ruta delimitados por barras . ni .. (por ejemplo, a/../b se rechaza)

# Superficie de credenciales compatible

• Matriz canónica: Superficie de credenciales de SecretRef
• secrets apply apunta a rutas de credenciales compatibles de openclaw.json.
• Las referencias de auth-profiles.json se incluyen en la resolución en tiempo de ejecución y en la cobertura de auditoría.

# Configuración de proveedores de secretos

{
  secrets: {
    providers: {
      default: { source: "env" }, // optional explicit env provider
      filemain: {
        source: "file",
        path: "~/.openclaw/secrets.json",
        mode: "json",
        timeoutMs: 5000,
      },
      vault: {
        source: "exec",
        command: "/usr/local/bin/openclaw-vault-resolver",
        passEnv: ["PATH", "VAULT_ADDR"],
      },
    },
    defaults: {
      env: "default",
      file: "filemain",
      exec: "vault",
    },
  },
}

Notas:

• El proveedor file admite mode: "json" y mode: "singleValue" (id debe ser "value" en modo singleValue).
• Las rutas de proveedores file y exec fallan en cerrado cuando la verificación de ACL de Windows no está disponible. Define allowInsecurePath: true solo para rutas de confianza que no puedan verificarse.
• El proveedor exec requiere una ruta absoluta de command y usa cargas útiles de protocolo en stdin/stdout.
• De forma predeterminada, se rechazan las rutas de comandos que son enlaces simbólicos. Define allowSymlinkCommand: true para permitir rutas de enlaces simbólicos mientras se valida la ruta de destino resuelta.
• Si trustedDirs está configurado, la comprobación de directorio de confianza se aplica a la ruta de destino resuelta.
• El entorno del proceso hijo de exec es mínimo de forma predeterminada; pasa las variables requeridas explícitamente con passEnv.
• Las referencias a secretos se resuelven en el momento de la activación en una instantánea en memoria; después, las rutas de solicitud solo leen la instantánea.
• El filtrado de superficie activa se aplica durante la activación: las referencias sin resolver en superficies habilitadas hacen fallar el inicio/recarga, mientras que las superficies inactivas se omiten con diagnósticos.

# Almacenamiento de autenticación

{
  auth: {
    profiles: {
      "anthropic:default": { provider: "anthropic", mode: "api_key" },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai-codex:personal": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:default", "anthropic:work"],
      "openai-codex": ["openai-codex:personal"],
    },
  },
}

• Los perfiles por agente se almacenan en <agentDir>/auth-profiles.json.
• auth-profiles.json admite referencias a nivel de valor (keyRef para api_key, tokenRef para token) para modos de credenciales estáticas.
• Los mapas planos heredados de auth-profiles.json, como { "provider": { "apiKey": "..." } }, no son un formato de tiempo de ejecución; openclaw doctor --fix los reescribe como perfiles de clave de API canónicos provider:default con una copia de seguridad .legacy-flat.*.bak.
• Los perfiles en modo OAuth (auth.profiles.<id>.mode = "oauth") no admiten credenciales de perfil de autenticación respaldadas por SecretRef.
• Las credenciales estáticas en tiempo de ejecución proceden de instantáneas resueltas en memoria; las entradas estáticas heredadas de auth.json se eliminan cuando se detectan.
• Las importaciones OAuth heredadas provienen de ~/.openclaw/credentials/oauth.json.
• Consulta OAuth.
• Comportamiento en tiempo de ejecución de secretos y herramientas audit/configure/apply: Gestión de secretos.

# auth.cooldowns

{
  auth: {
    cooldowns: {
      billingBackoffHours: 5,
      billingBackoffHoursByProvider: { anthropic: 3, openai: 8 },
      billingMaxHours: 24,
      authPermanentBackoffMinutes: 10,
      authPermanentMaxMinutes: 60,
      failureWindowHours: 24,
      overloadedProfileRotations: 1,
      overloadedBackoffMs: 0,
      rateLimitedProfileRotations: 1,
    },
  },
}

• billingBackoffHours: retroceso base en horas cuando un perfil falla por errores reales de facturación/crédito insuficiente (predeterminado: 5). El texto explícito de facturación puede seguir llegando aquí incluso en respuestas 401/403, pero los comparadores de texto específicos del proveedor permanecen acotados al proveedor que los posee (por ejemplo OpenRouter Key limit exceeded). Los mensajes HTTP 402 reintentables de ventana de uso o de límite de gasto de organización/espacio de trabajo permanecen en la ruta rate_limit en su lugar.
• billingBackoffHoursByProvider: anulaciones opcionales por proveedor para las horas de retroceso por facturación.
• billingMaxHours: límite en horas para el crecimiento exponencial del retroceso por facturación (predeterminado: 24).
• authPermanentBackoffMinutes: retroceso base en minutos para fallos auth_permanent de alta confianza (predeterminado: 10).
• authPermanentMaxMinutes: límite en minutos para el crecimiento del retroceso auth_permanent (predeterminado: 60).
• failureWindowHours: ventana móvil en horas usada para los contadores de retroceso (predeterminado: 24).
• overloadedProfileRotations: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores de sobrecarga antes de cambiar al respaldo de modelo (predeterminado: 1). Formas de proveedor ocupado como ModelNotReadyException llegan aquí.
• overloadedBackoffMs: demora fija antes de reintentar una rotación de proveedor/perfil sobrecargado (predeterminado: 0).
• rateLimitedProfileRotations: máximo de rotaciones de perfil de autenticación del mismo proveedor para errores de límite de frecuencia antes de cambiar al respaldo de modelo (predeterminado: 1). Ese grupo de límite de frecuencia incluye texto con forma de proveedor como Too many concurrent requests, ThrottlingException, concurrency limit reached, workers_ai ... quota limit exceeded y resource exhausted.

# Registro

{
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty", // pretty | compact | json
    redactSensitive: "tools", // off | tools
    redactPatterns: ["\\bTOKEN\\b\\s*[=:]\\s*([\"']?)([^\\s\"']+)\\1"],
  },
}

• Archivo de registro predeterminado: /tmp/openclaw/openclaw-YYYY-MM-DD.log.
• Define logging.file para una ruta estable.
• consoleLevel sube a debug cuando se usa --verbose.
• maxFileBytes: tamaño máximo del archivo de registro activo en bytes antes de la rotación (entero positivo; predeterminado: 104857600 = 100 MB). OpenClaw conserva hasta cinco archivos numerados junto al archivo activo.
• redactSensitive / redactPatterns: enmascaramiento de mejor esfuerzo para salida de consola, registros de archivo, registros de log OTLP y texto de transcripción de sesión persistido. redactSensitive: "off" solo desactiva esta política general de registros/transcripciones; las superficies de seguridad de UI/herramientas/diagnóstico siguen redactando secretos antes de emitirlos.

# Diagnósticos

{
  diagnostics: {
    enabled: true,
    flags: ["telegram.*"],
    stuckSessionWarnMs: 30000,
    stuckSessionAbortMs: 600000,

    otel: {
      enabled: false,
      endpoint: "https://otel-collector.example.com:4318",
      tracesEndpoint: "https://traces.example.com/v1/traces",
      metricsEndpoint: "https://metrics.example.com/v1/metrics",
      logsEndpoint: "https://logs.example.com/v1/logs",
      protocol: "http/protobuf", // http/protobuf | grpc
      headers: { "x-tenant-id": "my-org" },
      serviceName: "openclaw-gateway",
      traces: true,
      metrics: true,
      logs: false,
      sampleRate: 1.0,
      flushIntervalMs: 5000,
      captureContent: {
        enabled: false,
        inputMessages: false,
        outputMessages: false,
        toolInputs: false,
        toolOutputs: false,
        systemPrompt: false,
      },
    },

    cacheTrace: {
      enabled: false,
      filePath: "~/.openclaw/logs/cache-trace.jsonl",
      includeMessages: true,
      includePrompt: true,
      includeSystem: true,
    },
  },
}

• enabled: interruptor maestro para la salida de instrumentación (predeterminado: true).
• flags: arreglo de cadenas de marcas que habilitan salida de registro dirigida (admite comodines como "telegram.*" o "*").
• stuckSessionWarnMs: umbral de antigüedad sin progreso en ms para clasificar sesiones de procesamiento de larga duración como session.long_running, session.stalled o session.stuck. Las respuestas, herramientas, estados, bloques y el progreso de ACP reinician el temporizador; los diagnósticos session.stuck repetidos aplican retroceso mientras no haya cambios.
• stuckSessionAbortMs: umbral de antigüedad sin progreso en ms antes de que el trabajo activo atascado elegible pueda abortarse y drenarse para recuperación. Cuando no se define, OpenClaw usa la ventana incrustada extendida más segura de al menos 10 minutos y 5 veces stuckSessionWarnMs.
• otel.enabled: habilita la canalización de exportación de OpenTelemetry (predeterminado: false). Para la configuración completa, el catálogo de señales y el modelo de privacidad, consulta exportación de OpenTelemetry.
• otel.endpoint: URL del recopilador para la exportación OTel.
• otel.tracesEndpoint / otel.metricsEndpoint / otel.logsEndpoint: endpoints OTLP opcionales específicos de señal. Cuando se definen, anulan otel.endpoint solo para esa señal.
• otel.protocol: "http/protobuf" (predeterminado) o "grpc".
• otel.headers: encabezados adicionales de metadatos HTTP/gRPC enviados con las solicitudes de exportación OTel.
• otel.serviceName: nombre de servicio para atributos de recurso.
• otel.traces / otel.metrics / otel.logs: habilitan la exportación de trazas, métricas o registros.
• otel.sampleRate: tasa de muestreo de trazas 0-1.
• otel.flushIntervalMs: intervalo periódico de vaciado de telemetría en ms.
• otel.captureContent: captura opcional de contenido sin procesar para atributos de spans de OTEL. Está desactivada de forma predeterminada. El booleano true captura contenido de mensajes/herramientas que no sea del sistema; la forma de objeto permite habilitar inputMessages, outputMessages, toolInputs, toolOutputs y systemPrompt explícitamente.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: interruptor de entorno para los atributos de proveedor de spans GenAI experimentales más recientes. De forma predeterminada, los spans conservan el atributo heredado gen_ai.system por compatibilidad; las métricas GenAI usan atributos semánticos acotados.
• OPENCLAW_OTEL_PRELOADED=1: interruptor de entorno para hosts que ya registraron un SDK global de OpenTelemetry. OpenClaw omite entonces el inicio/apagado del SDK propiedad del plugin mientras mantiene activos los escuchadores de diagnóstico.
• OTEL_EXPORTER_OTLP_TRACES_ENDPOINT, OTEL_EXPORTER_OTLP_METRICS_ENDPOINT y OTEL_EXPORTER_OTLP_LOGS_ENDPOINT: variables de entorno de endpoint específicas de señal usadas cuando la clave de configuración correspondiente no está definida.
• cacheTrace.enabled: registra instantáneas de traza de caché para ejecuciones incrustadas (predeterminado: false).
• cacheTrace.filePath: ruta de salida para JSONL de traza de caché (predeterminado: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: controlan qué se incluye en la salida de traza de caché (todos predeterminados: true).

# Actualización

{
  update: {
    channel: "stable", // stable | beta | dev
    checkOnStart: true,

    auto: {
      enabled: false,
      stableDelayHours: 6,
      stableJitterHours: 12,
      betaCheckIntervalHours: 1,
    },
  },
}

• channel: canal de lanzamiento para instalaciones npm/git: "stable", "beta" o "dev".
• checkOnStart: comprueba actualizaciones de npm cuando se inicia el Gateway (predeterminado: true).
• auto.enabled: habilita la actualización automática en segundo plano para instalaciones de paquetes (predeterminado: false).
• auto.stableDelayHours: demora mínima en horas antes de aplicar automáticamente el canal estable (predeterminado: 6; máximo: 168).
• auto.stableJitterHours: ventana adicional de distribución gradual del canal estable en horas (predeterminado: 12; máximo: 168).
• auto.betaCheckIntervalHours: frecuencia en horas con la que se ejecutan las comprobaciones del canal beta (predeterminado: 1; máximo: 24).

# ACP

{
  acp: {
    enabled: true,
    dispatch: { enabled: true },
    backend: "acpx",
    defaultAgent: "main",
    allowedAgents: ["main", "ops"],
    maxConcurrentSessions: 10,

    stream: {
      coalesceIdleMs: 50,
      maxChunkChars: 1000,
      repeatSuppression: true,
      deliveryMode: "live", // live | final_only
      hiddenBoundarySeparator: "paragraph", // none | space | newline | paragraph
      maxOutputChars: 50000,
      maxSessionUpdateChars: 500,
    },

    runtime: {
      ttlMinutes: 30,
    },
  },
}

• enabled: puerta de función global de ACP (predeterminado: true; define false para ocultar las facilidades de despacho y creación de ACP).
• dispatch.enabled: puerta independiente para el despacho de turnos de sesión ACP (predeterminado: true). Define false para mantener disponibles los comandos ACP mientras se bloquea la ejecución.
• backend: id del backend de tiempo de ejecución ACP predeterminado (debe coincidir con un plugin de tiempo de ejecución ACP registrado). Instala primero el plugin de backend y, si plugins.allow está definido, incluye el id del plugin de backend (por ejemplo acpx) o el backend ACP no se cargará.
• defaultAgent: id de agente ACP de destino de respaldo cuando las creaciones no especifican un destino explícito.
• allowedAgents: lista de permitidos de ids de agente autorizados para sesiones de tiempo de ejecución ACP; vacío significa que no hay restricción adicional.
• maxConcurrentSessions: máximo de sesiones ACP activas concurrentemente.
• stream.coalesceIdleMs: ventana de vaciado por inactividad en ms para texto transmitido.
• stream.maxChunkChars: tamaño máximo de fragmento antes de dividir la proyección de bloque transmitido.
• stream.repeatSuppression: suprime líneas repetidas de estado/herramienta por turno (predeterminado: true).
• stream.deliveryMode: "live" transmite incrementalmente; "final_only" almacena en búfer hasta los eventos terminales del turno.
• stream.hiddenBoundarySeparator: separador antes del texto visible después de eventos de herramienta ocultos (predeterminado: "paragraph").
• stream.maxOutputChars: máximo de caracteres de salida del asistente proyectados por turno ACP.
• stream.maxSessionUpdateChars: máximo de caracteres para líneas de estado/actualización ACP proyectadas.
• stream.tagVisibility: registro de nombres de etiquetas a anulaciones booleanas de visibilidad para eventos transmitidos.
• runtime.ttlMinutes: TTL de inactividad en minutos para trabajadores de sesión ACP antes de que sean elegibles para limpieza.
• runtime.installCommand: comando de instalación opcional que se ejecuta al inicializar un entorno de tiempo de ejecución ACP.

# CLI

{
  cli: {
    banner: {
      taglineMode: "off", // random | default | off
    },
  },
}

• cli.banner.taglineMode controla el estilo del lema del banner:
  • "random" (predeterminado): lemas rotativos humorísticos/estacionales.
  • "default": lema neutral fijo (All your chats, one OpenClaw.).
  • "off": sin texto de lema (se siguen mostrando el título y la versión del banner).
• Para ocultar todo el banner (no solo los lemas), define la variable de entorno OPENCLAW_HIDE_BANNER=1.

# Asistente

Metadatos escritos por los flujos de configuración guiada de la CLI (onboard, configure, doctor):

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

# Identidad

Consulta los campos de identidad agents.list en valores predeterminados de agente.

# Puente (heredado, eliminado)

Las compilaciones actuales ya no incluyen el puente TCP. Los Node se conectan mediante el WebSocket del Gateway. Las claves bridge.* ya no forman parte del esquema de configuración (la validación falla hasta que se eliminan; openclaw doctor --fix puede quitar claves desconocidas).

{
"bridge": {
  "enabled": true,
  "port": 18790,
  "bind": "tailnet",
  "tls": {
    "enabled": true,
    "autoGenerate": true
  }
}
}

# Cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2, // cron dispatch + isolated cron agent-turn execution
    webhook: "https://example.invalid/legacy", // deprecated fallback for stored notify:true jobs
    webhookToken: "replace-with-dedicated-token", // optional bearer token for outbound webhook auth
    sessionRetention: "24h", // duration string or false
    runLog: {
      maxBytes: "2mb", // default 2_000_000 bytes
      keepLines: 2000, // default 2000
    },
  },
}

• sessionRetention: cuánto tiempo conservar las sesiones completadas de ejecuciones cron aisladas antes de eliminarlas de sessions.json. También controla la limpieza de transcripciones cron eliminadas archivadas. Predeterminado: 24h; establece false para desactivarlo.
• runLog.maxBytes: tamaño máximo por archivo de registro de ejecución (cron/runs/<jobId>.jsonl) antes de la depuración. Predeterminado: 2_000_000 bytes.
• runLog.keepLines: líneas más recientes retenidas cuando se activa la depuración del registro de ejecución. Predeterminado: 2000.
• webhookToken: token bearer usado para la entrega POST de Webhook de Cron (delivery.mode = "webhook"); si se omite, no se envía ningún encabezado de autenticación.
• webhook: URL de Webhook heredada obsoleta de respaldo (http/https) usada solo para trabajos almacenados que aún tienen notify: true.

# cron.retry

{
  cron: {
    retry: {
      maxAttempts: 3,
      backoffMs: [30000, 60000, 300000],
      retryOn: ["rate_limit", "overloaded", "network", "timeout", "server_error"],
    },
  },
}

• maxAttempts: reintentos máximos para trabajos de una sola ejecución en errores transitorios (predeterminado: 3; rango: 0-10).
• backoffMs: arreglo de demoras de espera en ms para cada intento de reintento (predeterminado: [30000, 60000, 300000]; 1-10 entradas).
• retryOn: tipos de error que activan reintentos: "rate_limit", "overloaded", "network", "timeout", "server_error". Omite para reintentar todos los tipos transitorios.

Se aplica solo a trabajos Cron de una sola ejecución. Los trabajos recurrentes usan una gestión de fallos separada.

# cron.failureAlert

{
  cron: {
    failureAlert: {
      enabled: false,
      after: 3,
      cooldownMs: 3600000,
      includeSkipped: false,
      mode: "announce",
      accountId: "main",
    },
  },
}

• enabled: habilita alertas de fallo para trabajos Cron (predeterminado: false).
• after: fallos consecutivos antes de que se dispare una alerta (entero positivo, mínimo: 1).
• cooldownMs: milisegundos mínimos entre alertas repetidas para el mismo trabajo (entero no negativo).
• includeSkipped: cuenta las ejecuciones omitidas consecutivas hacia el umbral de alerta (predeterminado: false). Las ejecuciones omitidas se registran por separado y no afectan la espera por errores de ejecución.
• mode: modo de entrega: "announce" envía mediante un mensaje de canal; "webhook" publica en el Webhook configurado.
• accountId: cuenta o id de canal opcional para delimitar la entrega de alertas.

# cron.failureDestination

{
  cron: {
    failureDestination: {
      mode: "announce",
      channel: "last",
      to: "channel:C1234567890",
      accountId: "main",
    },
  },
}

• Destino predeterminado para notificaciones de fallo de Cron en todos los trabajos.
• mode: "announce" o "webhook"; se establece en "announce" de forma predeterminada cuando existen suficientes datos de destino.
• channel: anulación de canal para la entrega de announce. "last" reutiliza el último canal de entrega conocido.
• to: destino announce explícito o URL de Webhook. Obligatorio para el modo Webhook.
• accountId: anulación opcional de cuenta para la entrega.
• delivery.failureDestination por trabajo anula este valor predeterminado global.
• Cuando no se define ningún destino de fallo global ni por trabajo, los trabajos que ya entregan mediante announce recurren a ese destino announce principal en caso de fallo.
• delivery.failureDestination solo es compatible con trabajos sessionTarget="isolated" a menos que el delivery.mode principal del trabajo sea "webhook".

Consulta Trabajos Cron. Las ejecuciones Cron aisladas se registran como tareas en segundo plano.

# Variables de plantilla del modelo multimedia

Marcadores de posición de plantilla expandidos en tools.media.models[].args:

# Inclusiones de configuración ($include)

Divide la configuración en varios archivos:

// ~/.openclaw/openclaw.json
{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/mueller.json5", "./clients/schmidt.json5"],
  },
}

Comportamiento de fusión:

• Archivo único: reemplaza el objeto contenedor.
• Arreglo de archivos: se fusionan en profundidad en orden (los posteriores anulan a los anteriores).
• Claves hermanas: se fusionan después de las inclusiones (anulan los valores incluidos).
• Inclusiones anidadas: hasta 10 niveles de profundidad.
• Rutas: se resuelven en relación con el archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (dirname de openclaw.json). Las formas absolutas/../ se permiten solo cuando aún se resuelven dentro de ese límite.
• Las escrituras propiedad de OpenClaw que cambian solo una sección de nivel superior respaldada por una inclusión de archivo único escriben directamente en ese archivo incluido. Por ejemplo, plugins install actualiza plugins: { $include: "./plugins.json5" } en plugins.json5 y deja openclaw.json intacto.
• Las inclusiones raíz, los arreglos de inclusiones y las inclusiones con anulaciones hermanas son de solo lectura para escrituras propiedad de OpenClaw; esas escrituras fallan cerradas en lugar de aplanar la configuración.
• Errores: mensajes claros para archivos faltantes, errores de análisis e inclusiones circulares.

Relacionado: Configuración · Ejemplos de configuración · Doctor

# Relacionado

• Configuración
• Ejemplos de configuración