Referencia de configuración

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

• openclaw config schema imprime el JSON Schema activo usado para validación y Control UI, con metadatos de paquetes integrados/Plugins/canales combinados cuando están disponibles
• config.schema.lookup devuelve un nodo de esquema con ámbito de ruta para herramientas de inspección detallada
• pnpm config:docs:check / pnpm config:docs:gen validan el hash de línea base de la documentación de configuración contra la superficie de esquema actual

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

​

Canales

​

Valores predeterminados de agente, multiagente, sesiones y mensajes

• agents.defaults.* (espacio de trabajo, modelo, razonamiento, 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.consultThinkingLevel: anulación del nivel de razonamiento para la ejecución completa del agente de OpenClaw detrás de las consultas en tiempo real de Control UI Talk
  • talk.consultFastMode: anulación de modo rápido de un solo uso para las consultas en tiempo real de Control UI Talk
  • talk.speechLocale: id de locale BCP 47 opcional para el reconocimiento de voz de Talk en iOS/macOS
  • talk.silenceTimeoutMs: cuando no está definido, 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

​

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.providers.*.localService: gestor de procesos bajo demanda opcional para servidores de modelos locales. OpenClaw prueba el endpoint de salud configurado, inicia el command absoluto cuando es necesario, espera a que esté listo y luego envía la solicitud del modelo. Consulta Servicios de modelos locales.
• models.pricing.enabled: controla el arranque de precios en segundo plano que comienza después de que sidecars y canales alcanzan la ruta lista del Gateway. Cuando es false, el Gateway omite las recuperaciones de catálogos de precios de OpenRouter y LiteLLM; los valores configurados models.providers.*.models[].cost siguen funcionando para estimaciones de coste locales.

​

MCP

{
  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 de servidores MCP remotos o stdio con nombre para runtimes que exponen herramientas MCP configuradas. Las entradas remotas usan transport: "streamable-http" o transport: "sse"; type: "http" es un alias nativo de la CLI que openclaw mcp set y openclaw doctor --fix normalizan en el campo canónico transport.
• mcp.sessionIdleTtlMs: TTL de inactividad para runtimes MCP empaquetados 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 futuros llamadores.
• 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 mcp.servers eliminadas se purgan inmediatamente en lugar de esperar al TTL de inactividad.

​

Skills

{
  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
      allowSymlinkTargets: ["~/Projects/manager/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm", // npm | pnpm | yarn | bun
      allowUploadedArchives: false,
    },
    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 empaquetadas (Skills gestionadas/de espacio de trabajo no afectadas).
• load.extraDirs: raíces de Skills compartidas adicionales (menor precedencia).
• load.allowSymlinkTargets: raíces de destino real de confianza en las que los symlinks de Skills pueden resolverse cuando el enlace vive fuera de su raíz de origen configurada.
• 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).
• install.allowUploadedArchives: permite que clientes Gateway operator.admin de confianza instalen archivos zip privados preparados mediante skills.upload.* (predeterminado: false). Esto solo habilita la ruta de archivos subidos; las instalaciones normales de ClawHub no lo requieren.
• entries.<skillKey>.enabled: false deshabilita una Skill aunque esté empaquetada/instalada.
• entries.<skillKey>.apiKey: comodidad para Skills que declaran una variable de entorno primaria (cadena de texto sin formato 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 más 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 es "allowlist" para configuraciones nuevas, por lo que un plugins.allow no vacío también controla Plugins de proveedores empaquetados, incluidos proveedores de runtime de búsqueda web. Doctor escribe "compat" para configuraciones de lista de permitidos heredadas migradas a fin de preservar el comportamiento existente de proveedores empaquetados hasta que optes por usarlo.
• plugins.entries.<id>.apiKey: campo de comodidad de clave 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 núcleo bloquea before_prompt_build e ignora campos que mutan prompts desde el before_agent_start heredado, mientras preserva 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 empaquetados 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 anulaciones de provider y model por ejecución para ejecuciones de subagentes en segundo plano.
• plugins.entries.<id>.subagent.allowedModels: lista de permitidos opcional de destinos canónicos provider/model para anulaciones de subagentes de confianza. Usa "*" solo cuando quieras permitir intencionalmente cualquier modelo.
• plugins.entries.<id>.llm.allowModelOverride: confía explícitamente en este Plugin para solicitar anulaciones de modelo para api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: lista de permitidos opcional de destinos canónicos provider/model para anulaciones de finalización LLM de Plugins de confianza. Usa "*" solo cuando quieras permitir intencionalmente cualquier modelo.
• plugins.entries.<id>.llm.allowAgentIdOverride: confía explícitamente en este Plugin para ejecutar api.runtime.llm.complete contra un id de agente no predeterminado.
• 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 debería estar descrita por los metadatos channelConfigs del manifiesto del Plugin propietario, no por un registro central de opciones de OpenClaw.

​

Configuración del Plugin de arnés Codex

{
  plugins: {
    entries: {
      codex: {
        enabled: true,
        config: {
          codexPlugins: {
            enabled: true,
            allow_destructive_actions: true,
            plugins: {
              "google-calendar": {
                enabled: true,
                marketplaceName: "openai-curated",
                pluginName: "google-calendar",
                allow_destructive_actions: false,
              },
            },
          },
        },
      },
    },
  },
}

• plugins.entries.codex.config.codexPlugins.enabled: habilita la compatibilidad nativa de plugin/app de Codex para el arnés de Codex. Valor predeterminado: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: política predeterminada de acciones destructivas para solicitudes de apps de plugin migradas. Valor predeterminado: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: habilita una entrada de plugin migrada cuando codexPlugins.enabled global también es verdadero. Valor predeterminado: true para entradas explícitas.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.marketplaceName: identidad estable del marketplace. V1 solo admite "openai-curated".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.pluginName: identidad estable de plugin de Codex desde la migración, por ejemplo "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: anulación de acciones destructivas por plugin. Cuando se omite, se usa el valor global allow_destructive_actions.

• plugins.entries.firecrawl.config.webFetch: ajustes del proveedor de obtención web de Firecrawl.
  • apiKey: clave de API de Firecrawl (acepta SecretRef). Recurre a plugins.entries.firecrawl.config.webSearch.apiKey, tools.web.fetch.firecrawl.apiKey heredado, o a la variable de entorno FIRECRAWL_API_KEY.
  • baseUrl: URL base de la API de Firecrawl (valor predeterminado: https://api.firecrawl.dev; las anulaciones autoalojadas deben apuntar a endpoints privados/internos).
  • onlyMainContent: extraer solo el contenido principal de las páginas (valor predeterminado: true).
  • maxAgeMs: antigüedad máxima de la caché en milisegundos (valor predeterminado: 172800000 / 2 días).
  • timeoutSeconds: tiempo de espera de la solicitud de scraping en segundos (valor predeterminado: 60).
• plugins.entries.xai.config.xSearch: ajustes de xAI X Search (búsqueda web de Grok).
  • enabled: habilitar el proveedor de X Search.
  • model: modelo de Grok que se usará para la búsqueda (p. ej. "grok-4-1-fast").
• plugins.entries.memory-core.config.dreaming: ajustes de dreaming de memoria. Consulta Dreaming para las fases y los umbrales.
  • enabled: interruptor maestro de dreaming (valor predeterminado false).
  • frequency: cadencia cron para cada barrido completo de dreaming ("0 3 * * *" por defecto).
  • model: anulación opcional del modelo del subagente Dream Diary. Requiere plugins.entries.memory-core.subagent.allowModelOverride: true; combínalo con allowedModels para restringir los destinos. Los errores de modelo no disponible se reintentan una vez con el modelo predeterminado de la sesión; los fallos de confianza o de lista de permitidos no recurren silenciosamente a otro valor.
  • la política de fases y los umbrales 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 habilitados del paquete de Claude también pueden aportar valores predeterminados incrustados de Pi desde settings.json; OpenClaw los aplica como ajustes saneados de agente, no como parches de configuración sin procesar 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.

​

Compromisos

• commitments.enabled: habilitar la extracción oculta con LLM, el almacenamiento y la entrega por Heartbeat de compromisos de seguimiento inferidos. Valor 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. Valor predeterminado: 3.

​

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 deshabilita 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. Define idleMinutes: 0 o maxTabsPerSession: 0 para deshabilitar esos modos individuales de limpieza.
• ssrfPolicy.dangerouslyAllowPrivateNetwork está deshabilitado cuando no se define, por lo que la navegación del navegador permanece estricta de forma predeterminada.
• Define ssrfPolicy.dangerouslyAllowPrivateNetwork: true solo cuando confíes intencionalmente en la navegación del navegador por la 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/descubrimiento.
• 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 de solo conexión (inicio/detención/restablecimiento deshabilitados).
• profiles.*.cdpUrl acepta http://, https://, ws:// y wss://. Usa HTTP(S) cuando quieras que OpenClaw descubra /json/version; usa WS(S) cuando tu proveedor te dé una URL WebSocket directa de DevTools.
• remoteCdpTimeoutMs y remoteCdpHandshakeTimeoutMs se aplican a la accesibilidad de CDP remota y attachOnly, además de las solicitudes de apertura de pestañas. Los perfiles gestionados de loopback conservan los valores predeterminados locales de CDP.
• Si un servicio CDP gestionado externamente es accesible mediante loopback, define attachOnly: true en ese perfil; de lo contrario, OpenClaw trata el puerto de loopback como un perfil de navegador gestionado localmente y puede informar errores de propiedad del puerto local.
• Los perfiles existing-session usan Chrome MCP en lugar de CDP y pueden conectarse en el host seleccionado o mediante un nodo de navegador conectado.
• Los perfiles existing-session pueden definir userDataDir para apuntar a un perfil específico de navegador basado en Chromium, como Brave o Edge.
• Los perfiles existing-session conservan los límites actuales de ruta de Chrome MCP: acciones basadas en snapshot/ref en lugar de selección por 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 gestionados locales openclaw asignan automáticamente cdpPort y cdpUrl; solo define cdpUrl explícitamente para CDP remoto.
• Los perfiles gestionados locales pueden definir executablePath para anular el browser.executablePath global de ese perfil. Usa esto para ejecutar un perfil en Chrome y otro en Brave.
• Los perfiles gestionados locales usan browser.localLaunchTimeoutMs para el descubrimiento HTTP de CDP de Chrome 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 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 invá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 principal de tu sistema operativo antes del lanzamiento de Chromium. userDataDir por perfil en perfiles existing-session también expande la tilde.
• Servicio de control: solo loopback (puerto derivado de gateway.port, predeterminado 18791).
• extraArgs añade flags de lanzamiento adicionales al inicio local de Chromium (por ejemplo --disable-gpu, tamaño de ventana o flags de depuración).

​

UI

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

• seamColor: color de acento para el chrome de la interfaz de la app nativa (tinte de burbuja de Modo Hablar, etc.).
• assistant: anulación de identidad de la UI 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.
• Endurecimiento de entrada de URL de Responses:
  • gateway.http.endpoints.responses.maxUrlParts
  • gateway.http.endpoints.responses.files.urlAllowlist
  • gateway.http.endpoints.responses.images.urlAllowlist Las listas de permitidos vacías se tratan como no definidas; usa gateway.http.endpoints.responses.files.allowUrl=false y/o gateway.http.endpoints.responses.images.allowUrl=false para deshabilitar la obtención de URLs.
• Encabezado opcional de endurecimiento de respuestas:
  • gateway.http.securityHeaders.strictTransportSecurity (defínelo solo para orígenes HTTPS que controles; consulta Autenticación de proxy de confianza)

​

Aislamiento multiinstancia

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

​

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 certificado/clave local autofirmado cuando no se configuran archivos explícitos; solo para uso local/desarrollo.
• 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 del bundle de CA para verificación de clientes 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 cuando cambia la configuración.
  • "hot": aplica cambios dentro del proceso sin reiniciar.
  • "hybrid" (predeterminado): intenta primero la recarga en caliente; recurre al reinicio si es necesario.
• debounceMs: ventana de debounce en ms antes de aplicar 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 en caliente del canal. Omítelo para usar la espera acotada predeterminada (300000); define 0 para esperar indefinidamente y registrar advertencias periódicas de aún pendiente.

​

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

• 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, restringe hooks.allowedSessionKeyPrefixes (por ejemplo, ["hook:"]).
• Si una asignación o preset usa un sessionKey con plantilla, define hooks.allowedSessionKeyPrefixes y hooks.allowRequestSessionKey=true. Las claves de asignación estáticas no requieren esa adhesión explícita.

• POST /hooks/wake → { text, mode?: "now"|"next-heartbeat" }
• POST /hooks/agent → { message, name?, agentId?, sessionKey?, wakeMode?, deliver?, channel?, to?, model?, thinking?, timeoutSeconds? }
  • 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 asignación renderizados con plantilla se tratan como suministrados externamente y también requieren hooks.allowRequestSessionKey=true.

​

Integración de Gmail

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

{
  hooks: {
    gmail: {
      account: "openclaw@gmail.com",
      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. Define OPENCLAW_SKIP_GMAIL_WATCHER=1 para desactivarlo.
• No ejecutes un gog gmail watch serve separado junto con Gateway.

​

Host del Plugin de 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 por 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 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 emparejar y conectar un Node, Gateway anuncia URL de capacidad con alcance de Node para el acceso a canvas/A2UI.
• Las URL de capacidad están vinculadas a la sesión WS activa de Node y caducan 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.

​

Descubrimiento

​

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 sigue requiriendo 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 implementaciones de Gateway en Linux, Windows y 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 },
  },
}

​

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 al entorno del proceso le falta 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

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

• Solo coinciden los 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

​

SecretRef

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

• Patrón de provider: ^[a-z][a-z0-9_-]{0,63}$
• Patrón de id para 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 para 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 . o .. (por ejemplo, a/../b se rechaza)

​

Superficie de credenciales admitida

• Matriz canónica: Superficie de credenciales 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",
    },
  },
}

• El proveedor file admite mode: "json" y mode: "singleValue" (id debe ser "value" en modo singleValue).
• Las rutas de proveedores file y exec fallan de forma cerrada cuando la verificación de ACL de Windows no está disponible. Define allowInsecurePath: true solo para rutas de confianza que no se puedan verificar.
• El proveedor exec requiere una ruta absoluta de command y usa cargas de protocolo en stdin/stdout.
• De forma predeterminada, las rutas de comandos con enlaces simbólicos se rechazan. 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 hijo de exec es mínimo de forma predeterminada; pasa explícitamente las variables requeridas 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 leen solo la instantánea.
• El filtrado de superficies activas se aplica durante la activación: las referencias no resueltas 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 a 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 de tiempo de ejecución provienen de instantáneas resueltas en memoria; las entradas estáticas heredadas de auth.json se depuran cuando se descubren.
• Las importaciones OAuth heredadas provienen de ~/.openclaw/credentials/oauth.json.
• Consulta OAuth.
• Comportamiento de 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: retardo base de reintento 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 clasificándose aquí incluso en respuestas 401/403, pero los comparadores de texto específicos del proveedor permanecen limitados 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 retardo de reintento por facturación.
• billingMaxHours: límite en horas para el crecimiento exponencial del retardo de reintento por facturación (predeterminado: 24).
• authPermanentBackoffMinutes: retardo base de reintento en minutos para fallos auth_permanent de alta confianza (predeterminado: 10).
• authPermanentMaxMinutes: límite en minutos para el crecimiento del retardo de reintento auth_permanent (predeterminado: 60).
• failureWindowHours: ventana móvil en horas usada para los contadores de retardo de reintento (predeterminado: 24).
• overloadedProfileRotations: rotaciones máximas de perfiles de autenticación del mismo proveedor para errores de sobrecarga antes de cambiar al fallback de modelo (predeterminado: 1). Formas de proveedor ocupado como ModelNotReadyException se clasifican aquí.
• overloadedBackoffMs: retraso fijo antes de reintentar una rotación de proveedor/perfil sobrecargado (predeterminado: 0).
• rateLimitedProfileRotations: rotaciones máximas de perfiles de autenticación del mismo proveedor para errores de límite de tasa antes de cambiar al fallback de modelo (predeterminado: 1). Ese grupo de límite de tasa 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 la salida de consola, registros en archivo, registros de log OTLP y texto persistido de la transcripción de sesión. redactSensitive: "off" solo desactiva esta política general de registros/transcripción; las superficies de seguridad de UI/herramientas/diagnóstico siguen redactando secretos antes de emitirlos.

​

Diagnóstico

{
  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 flags que habilitan salida de registros dirigida (admite comodines como "telegram.*" o "*").
• stuckSessionWarnMs: umbral de 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 ACP reinician el temporizador; los diagnósticos session.stuck repetidos aplican retardo cuando no hay cambios.
• stuckSessionAbortMs: umbral de edad sin progreso en ms antes de que el trabajo activo atascado elegible pueda drenarse con cancelación para recuperación. Cuando no está definido, OpenClaw usa la ventana embebida extendida más segura de al menos 10 minutos y 5x 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 colector 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 de metadatos HTTP/gRPC adicionales enviados con 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 OTEL. Está desactivada de forma predeterminada. El booleano true captura contenido de mensajes/herramientas que no sea del sistema; la forma de objeto te permite habilitar explícitamente inputMessages, outputMessages, toolInputs, toolOutputs y systemPrompt.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: interruptor de entorno para los atributos experimentales más recientes del proveedor de spans GenAI. 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 entonces omite el arranque/apagado del SDK propiedad del Plugin mientras mantiene activos los listeners 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 trazas de caché para ejecuciones embebidas (predeterminado: false).
• cacheTrace.filePath: ruta de salida para JSONL de trazas de caché (predeterminado: $OPENCLAW_STATE_DIR/logs/cache-trace.jsonl).
• cacheTrace.includeMessages / includePrompt / includeSystem: controlan qué se incluye en la salida de trazas 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: busca actualizaciones 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: retraso mínimo en horas antes de aplicar automáticamente en el canal estable (predeterminado: 6; máximo: 168).
• auto.stableJitterHours: ventana adicional de distribución de despliegue del canal estable en horas (predeterminado: 12; máximo: 168).
• auto.betaCheckIntervalHours: frecuencia con la que se ejecutan las comprobaciones del canal beta en horas (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 global de la función ACP (predeterminado: true; define false para ocultar el envío ACP y las opciones de generación).
• dispatch.enabled: puerta independiente para el envío de turnos de sesión ACP (predeterminado: true). Define false para mantener disponibles los comandos ACP mientras se bloquea la ejecución.
• backend: id predeterminado del backend de runtime ACP (debe coincidir con un Plugin de runtime 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 objetivo ACP de fallback cuando las generaciones no especifican un destino explícito.
• allowedAgents: lista de permitidos de ids de agente autorizados para sesiones de runtime ACP; vacío significa sin restricción adicional.
• maxConcurrentSessions: número máximo de sesiones ACP activas simultáneamente.
• 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 bloques transmitidos.
• 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 de 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 workers de sesión ACP antes de la limpieza elegible.
• runtime.installCommand: comando de instalación opcional que se ejecuta al arrancar un entorno de runtime ACP.

​

CLI

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

• cli.banner.taglineMode controla el estilo del eslogan del banner:
  • "random" (predeterminado): eslóganes rotativos divertidos/de temporada.
  • "default": eslogan neutral fijo (All your chats, one OpenClaw.).
  • "off": sin texto de eslogan (el título/versión del banner sigue mostrándose).
• Para ocultar todo el banner (no solo los eslóganes), define la variable de entorno OPENCLAW_HIDE_BANNER=1.

​

Asistente

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

​

Identidad

​

Puente (heredado, eliminado)

{
  "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 de Cron aisladas antes de podarlas de sessions.json. También controla la limpieza de transcripciones archivadas de Cron eliminadas. Valor predeterminado: 24h; configúrelo en false para deshabilitarlo.
• runLog.maxBytes: tamaño máximo por archivo de registro de ejecución (cron/runs/<jobId>.jsonl) antes de podarlo. Valor predeterminado: 2_000_000 bytes.
• runLog.keepLines: líneas más recientes conservadas cuando se activa la poda del registro de ejecución. Valor 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 reserva (http/https) usada solo para trabajos almacenados que todavía 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 ejecución única ante errores transitorios (valor predeterminado: 3; rango: 0-10).
• backoffMs: arreglo de demoras de espera en ms para cada intento de reintento (valor predeterminado: [30000, 60000, 300000]; 1-10 entradas).
• retryOn: tipos de error que activan reintentos: "rate_limit", "overloaded", "network", "timeout", "server_error". Omítalo para reintentar todos los tipos transitorios.

​

cron.failureAlert

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

• enabled: habilita alertas de fallo para trabajos de Cron (valor 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 ejecuciones omitidas consecutivas para el umbral de alerta (valor predeterminado: false). Las ejecuciones omitidas se rastrean 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: id opcional de cuenta o canal 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"; el valor predeterminado es "announce" cuando existen suficientes datos de destino.
• channel: anulación de canal para la entrega por anuncio. "last" reutiliza el último canal de entrega conocido.
• to: destino de anuncio explícito o URL de Webhook. Requerido 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 de anuncio principal en caso de fallo.
• delivery.failureDestination solo se admite para trabajos con sessionTarget="isolated", salvo que el delivery.mode principal del trabajo sea "webhook".

​

Variables de plantilla del modelo de medios

​

Inclusiones de configuración ($include)

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

• Archivo único: reemplaza el objeto contenedor.
• Arreglo de archivos: se fusiona en profundidad en orden (los posteriores anulan 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 relativas al archivo que incluye, pero deben permanecer dentro del directorio de configuración de nivel superior (dirname de openclaw.json). Las formas absolutas/../ solo se permiten cuando siguen resolviéndose 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 se escriben 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 de claves hermanas son de solo lectura para escrituras propiedad de OpenClaw; esas escrituras fallan de forma cerrada 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