Referencia de configuración

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

Cubre las superficies principales de configuración de OpenClaw y enlaza a 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 ajustes profundos de memoria/QMD, viven en sus propias páginas en lugar de en esta.

Fuente de verdad del código:

• openclaw config schema imprime el JSON Schema activo usado para validación y Control UI, con metadatos de paquetes incluidos/plugins/canales combinados cuando están disponibles
• config.schema.lookup devuelve un nodo de esquema limitado a una 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 actual del esquema

Ruta de consulta del agente: usa la acción de herramienta gateway config.schema.lookup para 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 bajo plugins.entries.memory-core.config.dreaming
• Comandos de barra diagonal 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, varias cuentas, control de menciones).

Valores predeterminados del agente, multiagente, sesiones y mensajes

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

• 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 toda la ejecución del agente OpenClaw detrás de las consultas en tiempo real de Talk de Control UI
  • talk.consultFastMode: anulación puntual del modo rápido para consultas en tiempo real de Talk de Control UI
  • talk.speechLocale: id de configuración regional BCP 47 opcional para el 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)
  • talk.realtime.consultRouting: alternativa de relay del Gateway para transcripciones finalizadas en tiempo real de Talk que omiten openclaw_agent_consult

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.providers.*.localService: gestor de procesos bajo demanda opcional para servidores de modelos locales. OpenClaw sondea el endpoint de salud configurado, inicia el command absoluto cuando hace falta, espera la disponibilidad 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 empieza después de que los sidecars y canales alcancen la ruta lista del Gateway. Cuando es false, el Gateway omite las consultas a los catálogos de precios de OpenRouter y LiteLLM; los valores configurados en models.providers.*.models[].cost siguen funcionando para estimaciones de coste locales.

MCP

Las definiciones de servidores MCP gestionadas por OpenClaw viven bajo mcp.servers y son consumidas por OpenClaw integrado y otros adaptadores de runtime. Los comandos openclaw mcp list, show, set y unset gestionan 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        timeout: 20,        connectTimeout: 5,        supportsParallelToolCalls: true,        headers: {          Authorization: "Bearer ${MCP_REMOTE_TOKEN}",        },        auth: "oauth",        oauth: {          scope: "docs.read",        },        sslVerify: true,        clientCert: "/path/to/client.crt",        clientKey: "/path/to/client.key",        toolFilter: {          include: ["search_*"],          exclude: ["admin_*"],        },        // Optional Codex app-server projection controls.        codex: {          agents: ["main"],          defaultToolsApprovalMode: "approve", // auto | prompt | approve        },      },    },  },}

• 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 en el campo canónico transport.
• mcp.servers.<name>.enabled: establece false para conservar una definición de servidor guardada mientras la excluyes del descubrimiento MCP integrado de OpenClaw y de la proyección de herramientas.
• mcp.servers.<name>.timeout / requestTimeoutMs: timeout de solicitud MCP por servidor en segundos o milisegundos.
• mcp.servers.<name>.connectTimeout / connectionTimeoutMs: timeout de conexión por servidor en segundos o milisegundos.
• mcp.servers.<name>.supportsParallelToolCalls: pista opcional de concurrencia para adaptadores que pueden elegir si emitir llamadas paralelas a herramientas MCP.
• mcp.servers.<name>.auth: establece "oauth" para servidores MCP HTTP que requieren OAuth. Ejecuta openclaw mcp login <name> para guardar tokens bajo el estado de OpenClaw.
• mcp.servers.<name>.oauth: anulaciones opcionales de alcance OAuth, URL de redirección y URL de metadatos de cliente.
• mcp.servers.<name>.sslVerify, clientCert, clientKey: controles TLS HTTP para endpoints privados y TLS mutuo.
• mcp.servers.<name>.toolFilter: selección opcional de herramientas por servidor. include limita las herramientas MCP descubiertas a nombres coincidentes; exclude oculta nombres coincidentes. Las entradas son nombres exactos de herramientas MCP o globs simples con *. Los servidores con recursos o prompts también generan nombres de herramientas de utilidad (resources_list, resources_read, prompts_list, prompts_get), y esos nombres usan el mismo filtro.
• mcp.servers.<name>.codex: controles opcionales de proyección de servidor de app de Codex. Este bloque es metadato de OpenClaw solo para hilos del servidor de app de Codex; no afecta a sesiones ACP, configuración genérica del arnés de Codex ni otros adaptadores de runtime. codex.agents no vacío limita el servidor a los ids de agentes OpenClaw listados. Las listas de agentes con alcance vacías, en blanco o inválidas son rechazadas por la validación de configuración y omitidas por la ruta de proyección de runtime en lugar de volverse globales. codex.defaultToolsApprovalMode emite el default_tools_approval_mode nativo de Codex para ese servidor. OpenClaw elimina el bloque codex antes de pasar la configuración nativa mcp_servers a Codex. Omite el bloque para mantener el servidor proyectado para cada agente de servidor de app de Codex con el comportamiento predeterminado de aprobación MCP de Codex.
• mcp.sessionIdleTtlMs: TTL de inactividad para runtimes MCP incluidos con alcance de sesión. Las ejecuciones integradas puntuales 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 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 recogen de inmediato en lugar de esperar al TTL de inactividad.
• El descubrimiento en runtime también respeta notificaciones de cambio de lista de herramientas MCP descartando el catálogo en caché para esa sesión. Los servidores que anuncian recursos o prompts obtienen herramientas de utilidad para listar/leer recursos y listar/obtener prompts. Los fallos repetidos de llamadas a herramientas pausan brevemente el servidor afectado antes de intentar otra llamada.

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

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,    },    workshop: {      allowSymlinkTargetWrites: 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 incluidos (Skills gestionados/de espacio de trabajo no afectados).
• load.extraDirs: raíces de Skills compartidas adicionales (precedencia más baja).
• 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.
• workshop.allowSymlinkTargetWrites: permite que Skill Workshop aplique escrituras a través de destinos de symlink ya confiables (predeterminado: false).
• install.preferBrew: cuando es true, prefiere instaladores 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 de confianza operator.admin 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 desactiva un Skill aunque esté incluido/instalado.
• entries.<skillKey>.apiKey: comodidad para Skills que declaran una variable de entorno principal (cadena de texto plano u objeto SecretRef).

Plugins

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

• Se cargan desde directorios de paquetes o bundles bajo ~/.openclaw/extensions y <workspace>/.openclaw/extensions, además de los archivos o directorios listados en plugins.load.paths.
• Coloca los archivos de plugins independientes en plugins.load.paths; las raíces de extensiones descubiertas automáticamente ignoran los archivos .js, .mjs y .ts de nivel superior para que los scripts auxiliares en esas raíces no bloqueen el arranque.
• El descubrimiento acepta plugins nativos de OpenClaw además de bundles compatibles de Codex y Claude, incluidos bundles 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 tiene prioridad.
• plugins.entries.<id>.apiKey: campo de conveniencia para clave API a nivel de plugin (cuando el plugin lo admite).
• plugins.entries.<id>.env: mapa de variables de entorno con alcance de plugin.
• plugins.entries.<id>.hooks.allowPromptInjection: cuando es false, el núcleo bloquea before_prompt_build e ignora los campos que mutan prompts desde el before_agent_start heredado, mientras conserva los modelOverride y providerOverride heredados. Se aplica a hooks de plugins nativos y a directorios de hooks proporcionados por bundles admitidos.
• plugins.entries.<id>.hooks.allowConversationAccess: cuando es true, los plugins confiables no incluidos en bundle pueden leer contenido sin procesar de conversaciones 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 reemplazos 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 reemplazos confiables de subagentes. Usa "*" solo cuando quieras permitir intencionalmente cualquier modelo.
• plugins.entries.<id>.llm.allowModelOverride: confía explícitamente en este plugin para solicitar reemplazos de modelo para api.runtime.llm.complete.
• plugins.entries.<id>.llm.allowedModels: lista de permitidos opcional de destinos canónicos provider/model para reemplazos confiables de finalización LLM de plugins. 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 del plugin nativo de OpenClaw cuando está disponible).
• La configuración de cuenta/runtime de plugins de canal vive bajo channels.<id> y debe ser descrita por los metadatos channelConfigs del manifiesto del plugin propietario, no por un registro central de opciones de OpenClaw.

Configuración del plugin del arnés Codex

El plugin codex incluido en bundle posee la configuración del arnés nativo del servidor de aplicaciones Codex bajo plugins.entries.codex.config. Consulta la referencia del arnés Codex para ver toda la superficie de configuración y arnés Codex para el modelo de runtime.

codexPlugins se aplica solo a sesiones que seleccionan el arnés nativo Codex. No habilita plugins Codex para ejecuciones de proveedores OpenClaw, enlaces de conversación ACP ni ningún arnés que no sea 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 con plugins/apps de Codex para el arnés Codex. Predeterminado: false.
• plugins.entries.codex.config.codexPlugins.allow_destructive_actions: política predeterminada de acciones destructivas para solicitudes migradas de apps de plugins. Usa true para aceptar esquemas seguros de aprobación Codex sin preguntar, false para rechazarlos, "auto" para enrutar aprobaciones requeridas por Codex a través de aprobaciones de plugins OpenClaw, o "ask" para preguntar por cada acción de escritura/destructiva de plugin sin aprobación duradera. El modo "ask" borra los reemplazos duraderos de aprobación por herramienta de Codex para la app afectada y selecciona el revisor humano de aprobaciones para esa app antes de que comience el hilo Codex. Predeterminado: true.
• plugins.entries.codex.config.codexPlugins.plugins.<key>.enabled: habilita una entrada de plugin migrada cuando codexPlugins.enabled global también es true. 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 del plugin Codex desde la migración, por ejemplo "google-calendar".
• plugins.entries.codex.config.codexPlugins.plugins.<key>.allow_destructive_actions: reemplazo de acciones destructivas por plugin. Cuando se omite, se usa el valor global allow_destructive_actions. El valor por plugin acepta las mismas políticas true, false, "auto" o "ask".

Cada app de plugin admitida que usa "ask" enruta las solicitudes de aprobación de esa app al revisor humano. Otras apps y aprobaciones de hilos que no son apps conservan su revisor configurado, por lo que las políticas mixtas de plugins no heredan el comportamiento "ask".

codexPlugins.enabled es la directiva global de habilitación. Las entradas explícitas de plugins escritas por la migración son el conjunto duradero de instalación y elegibilidad para reparación. plugins["*"] no es compatible, no hay interruptor install y los valores locales marketplacePath no son campos de configuración intencionalmente porque son específicos del host.

Las comprobaciones de preparación de app/list se almacenan en caché durante una hora y se actualizan de forma asíncrona cuando quedan obsoletas. La configuración de apps de hilos Codex se calcula al establecer la sesión del arnés Codex, no en cada turno; usa /new, /reset o un reinicio del gateway después de cambiar la configuración nativa de plugins.

• plugins.entries.firecrawl.config.webFetch: configuración del proveedor de obtención web Firecrawl.
  • apiKey: clave API opcional de Firecrawl para límites más altos (acepta SecretRef). Recurre a plugins.entries.firecrawl.config.webSearch.apiKey, al valor heredado tools.web.fetch.firecrawl.apiKey o a la variable de entorno FIRECRAWL_API_KEY.
  • baseUrl: URL base de la API de Firecrawl (predeterminado: https://api.firecrawl.dev; los reemplazos autoalojados deben apuntar a endpoints privados/internos).
  • onlyMainContent: extrae solo el contenido principal de las páginas (predeterminado: true).
  • maxAgeMs: antigüedad máxima de caché en milisegundos (predeterminado: 172800000 / 2 días).
  • timeoutSeconds: tiempo de espera de la 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 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 principal de Dreaming (predeterminado false).
  • frequency: cadencia cron para cada barrido completo de Dreaming ("0 3 * * *" de forma predeterminada).
  • model: reemplazo opcional del modelo del subagente Dream Diary. Requiere plugins.entries.memory-core.subagent.allowModelOverride: true; combínalo con allowedModels para restringir destinos. Los errores por modelo no disponible reintentan una vez con el modelo predeterminado de la sesión; los fallos de confianza o de lista de permitidos no recurren silenciosamente.
  • 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 de bundles Claude habilitados también pueden aportar valores predeterminados de OpenClaw incrustados desde settings.json; OpenClaw los aplica como configuración saneada de agente, no como parches sin procesar 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 inferida de seguimiento: 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, el almacenamiento y la entrega por heartbeat de compromisos de seguimiento inferidos. Predeterminado: false.
• commitments.maxPerDay: cantidad máxima 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 deshabilita act:evaluate y wait --fn.
• tabCleanup recupera las pestañas de agente primario rastreadas 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 de limpieza individuales.
• ssrfPolicy.dangerouslyAllowPrivateNetwork está deshabilitado cuando no se define, por lo que la navegación del navegador sigue siendo estricta de forma predeterminada.
• Define ssrfPolicy.dangerouslyAllowPrivateNetwork: true solo cuando confíes intencionalmente 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 alcanzabilidad/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 solo de 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 alcanzabilidad CDP remota y attachOnly, además de las solicitudes de apertura de pestañas. Los perfiles local loopback administrados mantienen los valores predeterminados locales de CDP.
• Si un servicio CDP administrado externamente es alcanzable mediante loopback, define attachOnly: true en ese perfil; de lo contrario, OpenClaw trata el puerto loopback como un perfil de navegador administrado local y puede informar errores de propiedad de 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 de navegador específico basado en Chromium, como Brave o Edge.
• Los perfiles existing-session pueden definir cdpUrl cuando Chrome ya se está ejecutando detrás de un endpoint de descubrimiento HTTP(S) de DevTools o un endpoint WS(S) directo. En ese modo, OpenClaw pasa el endpoint a Chrome MCP en lugar de usar la conexión automática; userDataDir se ignora para los argumentos de lanzamiento de Chrome MCP.
• Los perfiles existing-session mantienen los límites de ruta actuales de Chrome MCP: acciones basadas en instantánea/ref en lugar de selecció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 PDF, interceptación de descargas ni acciones por lotes.
• Los perfiles openclaw administrados localmente asignan automáticamente cdpPort y cdpUrl; define cdpUrl explícitamente solo para perfiles CDP remotos o conexión a endpoint de existing-session.
• Los perfiles administrados localmente 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 administrados localmente 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 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 del lanzamiento de Chromium. El 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 banderas de lanzamiento adicionales al inicio local de Chromium (por ejemplo --disable-gpu, tamaño de ventana o banderas 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 énfasis para el cromado de la interfaz de usuario de la app nativa (tinte de burbuja de Talk Mode, 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://127.0.0.1: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 for owner/admin callers      allow: ["gateway"],    },    push: {      apns: {        relay: {          baseUrl: "https://relay.example.com",          timeoutMs: 10000,        },      },    },  },}

Endpoints compatibles con OpenAI

• RPC HTTP de administración: desactivado de forma predeterminada como el Plugin admin-http-rpc. Habilita el Plugin para registrar POST /api/v1/admin/rpc. Consulta RPC HTTP de administración.
• 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 por 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 por URL.
• Encabezado opcional de endurecimiento de respuesta:
  • gateway.http.securityHeaders.strictTransportSecurity (establecer solo para orígenes HTTPS que controles; consulta Autenticación con proxy de confianza)

Aislamiento multiinstancia

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 local de certificado/clave autofirmado 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 del bundle 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 cuando cambia la configuración.
  • "hot": aplica los cambios dentro del proceso sin reiniciar.
  • "hybrid" (predeterminado): intenta primero la recarga en caliente; recurre al reinicio si es necesario.
• debounceMs: ventana de antirrebote en ms antes de aplicar los cambios de configuración (entero no negativo).
• deferralTimeoutMs: tiempo máximo opcional en ms para esperar a que terminen las operaciones en curso antes de forzar un reinicio o una recarga en caliente del canal. Omítelo para usar la espera limitada predeterminada (300000); configúralo en 0 para esperar indefinidamente y registrar advertencias periódicas de operaciones aún 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>. Los tokens de hook en la cadena de consulta se rechazan.

Notas de validación y seguridad:

• hooks.enabled=true requiere un hooks.token no vacío.
• hooks.token debe ser distinto de la autenticación compartida activa del Gateway (gateway.auth.token / OPENCLAW_GATEWAY_TOKEN o gateway.auth.password / OPENCLAW_GATEWAY_PASSWORD); el inicio registra una advertencia de seguridad no fatal cuando detecta reutilización.
• openclaw security audit marca la reutilización de autenticación entre hook/Gateway como un hallazgo crítico, incluida la autenticación por contraseña del Gateway proporcionada solo durante la auditoría (--auth password --password <password>). Ejecuta openclaw doctor --fix para rotar un hooks.token persistido y reutilizado; luego actualiza los emisores de hooks externos para que usen el nuevo token de hook.
• hooks.path no puede ser /; usa una subruta dedicada como /hooks.
• Si hooks.allowRequestSessionKey=true, limita hooks.allowedSessionKeyPrefixes (por ejemplo, ["hook:"]).
• Si una asignación o un preset usa un sessionKey con plantilla, configura hooks.allowedSessionKeyPrefixes y hooks.allowRequestSessionKey=true. Las claves de asignación estáticas no requieren esa aceptació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> → resuelto mediante hooks.mappings
  • Los valores de sessionKey de asignación renderizados desde plantillas se tratan como proporcionados externamente y también requieren hooks.allowRequestSessionKey=true.

Integración con Gmail

• El preset integrado de Gmail usa sessionKey: "hook:gmail:{{messages[0].id}}".
• Si conservas ese enrutamiento por mensaje, configura 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, sobrescribe el preset con 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",    },  },}

• El Gateway inicia automáticamente gog gmail watch serve durante el arranque cuando está configurado. Configura OPENCLAW_SKIP_GMAIL_WATCHER=1 para desactivarlo.
• No ejecutes un gog gmail watch serve separado junto al 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 del 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 local loopback: las rutas de canvas requieren autenticación del Gateway (token/contraseña/proxy de confianza), igual que otras superficies HTTP del Gateway.
• Las WebViews de Node normalmente no envían encabezados de autenticación; después de emparejar y conectar un nodo, el Gateway anuncia URLs de capacidad con alcance de nodo para acceso a canvas/A2UI.
• Las URLs 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 el 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; la publicidad multicast LAN aún requiere que el Plugin bonjour incluido esté habilitado.
• off: suprime la publicidad multicast LAN sin cambiar la habilitación del Plugin.
• El Plugin bonjour incluido se inicia automáticamente en hosts macOS y es opt-in en Linux, Windows y despliegues del Gateway en contenedores.
• El nombre de host usa de forma predeterminada el nombre de host del sistema cuando es una etiqueta DNS válida; si no, recurre a openclaw. Sobrescríbelo con OPENCLAW_MDNS_HOSTNAME.

Área amplia (DNS-SD)

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

Escribe una zona DNS-SD unicast bajo ~/.openclaw/dns/. Para descubrimiento 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 al entorno del proceso le falta la clave.
• Archivos .env: .env del CWD + ~/.openclaw/.env (ninguno sobrescribe variables existentes).
• shellEnv: importa 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 claro 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 para source: "env": ^[A-Z][A-Z0-9_]{0,127}$
• id para 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}$ (admite selectores de estilo AWS secret#json_key)
• Los id de source: "exec" no deben contener segmentos de ruta delimitados por barras . o .. (por ejemplo, a/../b se rechaza)

Superficie de credenciales compatible

• 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 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 de forma cerrada cuando la verificación de ACL de Windows no está disponible. Configura 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 symlinks. Configura allowSymlinkCommand: true para permitir rutas symlink mientras se valida la ruta de destino resuelta.
• Si trustedDirs está configurado, la comprobación del 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 necesarias con passEnv.
• Las referencias a secretos se resuelven al activar en una instantánea en memoria; luego las rutas de solicitud solo leen 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 o la 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:personal": { provider: "openai", mode: "oauth" },    },    order: {      anthropic: ["anthropic:default", "anthropic:work"],      openai: ["openai: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 canónicos de clave de API 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 provienen de instantáneas resueltas en memoria; las entradas estáticas heredadas de auth.json se eliminan al descubrirse.
• 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 aún puede llegar aquí incluso en respuestas 401/403, pero los comparadores de texto específicos del proveedor permanecen limitados al proveedor propietario (por ejemplo, Key limit exceeded de OpenRouter). Los mensajes reintentables HTTP 402 de ventana de uso o límite de gasto de organización/espacio de trabajo permanecen en la ruta rate_limit.
• billingBackoffHoursByProvider: sobrescrituras 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 contadores de retroceso (predeterminado: 24).
• overloadedProfileRotations: rotaciones máximas de perfiles de autenticación del mismo proveedor para errores de sobrecarga antes de cambiar a la alternativa de modelo (predeterminado: 1). Las formas de proveedor ocupado, como ModelNotReadyException, llegan 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 a la alternativa 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 de archivo, registros de log OTLP y texto persistido de transcripción de sesión. redactSensitive: "off" solo desactiva esta política general de registros/transcripciones; las superficies de seguridad de UI/herramientas/diagnóstico siguen ocultando secretos antes de emitirlos.

Diagnósticos

{  diagnostics: {    enabled: true,    flags: ["telegram.*"],    stuckSessionWarnMs: 30000,    stuckSessionAbortMs: 300000,    memoryPressureSnapshot: false,     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,      logsExporter: "otlp",      sampleRate: 1.0,      flushIntervalMs: 5000,      captureContent: {        enabled: false,        inputMessages: false,        outputMessages: false,        toolInputs: false,        toolOutputs: false,        systemPrompt: false,        toolDefinitions: 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 registros 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 progreso ACP reinician el temporizador; los diagnósticos session.stuck repetidos aplican retroceso mientras no cambien.
• stuckSessionAbortMs: umbral de antigüedad sin progreso en ms antes de que el trabajo activo atascado elegible pueda drenarse con aborto para recuperación. Cuando no se define, OpenClaw usa la ventana incrustada extendida más segura de al menos 5 minutos y 3x stuckSessionWarnMs.
• memoryPressureSnapshot: captura una instantánea de estabilidad redactada previa a OOM cuando la presión de memoria alcanza critical (predeterminado: false). Defínelo como true para añadir el escaneo/escritura del archivo del paquete de estabilidad mientras se mantienen los eventos normales de presión de memoria.
• 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 por señal. Cuando se definen, sobrescriben 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 los atributos de recurso.
• otel.traces / otel.metrics / otel.logs: habilitan la exportación de trazas, métricas o registros.
• otel.logsExporter: destino de exportación de registros: "otlp" (predeterminado), "stdout" para un objeto JSON por línea de stdout, o "both".
• 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á desactivado de forma predeterminada. El booleano true captura contenido de mensajes/herramientas que no sea de sistema; la forma de objeto permite habilitar explícitamente inputMessages, outputMessages, toolInputs, toolOutputs, systemPrompt y toolDefinitions.
• OTEL_SEMCONV_STABILITY_OPT_IN=gen_ai_latest_experimental: interruptor de entorno para la forma experimental más reciente de spans de inferencia GenAI, incluidos nombres de span {gen_ai.operation.name} {gen_ai.request.model}, tipo de span CLIENT y gen_ai.provider.name en lugar del gen_ai.system heredado. De forma predeterminada, los spans conservan openclaw.model.call y 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 inicio/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 por señal usadas cuando la clave de configuración correspondiente no está definida.
• cacheTrace.enabled: registra instantáneas de trazas de caché para ejecuciones incrustadas (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 el canal estable (predeterminado: 6; máximo: 168).
• auto.stableJitterHours: ventana adicional de dispersión del 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: compuerta global de la función ACP (predeterminado: true; define false para ocultar el despacho ACP y los controles de creación).
• dispatch.enabled: compuerta 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 predeterminado del backend de tiempo de ejecución ACP (debe coincidir con un Plugin registrado de tiempo de ejecución ACP). 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 de destino ACP alternativo cuando las creaciones no especifican un destino explícito.
• allowedAgents: lista de permitidos de ids de agentes autorizados para sesiones de tiempo de ejecución ACP; vacío significa que no hay 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 bloque transmitida.
• 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: caracteres máximos de salida del asistente proyectados por turno ACP.
• stream.maxSessionUpdateChars: caracteres máximos para líneas proyectadas de estado/actualización ACP.
• stream.tagVisibility: registro de nombres de etiquetas a sobrescrituras booleanas de visibilidad para eventos transmitidos.
• runtime.ttlMinutes: TTL de inactividad en minutos para workers de sesión ACP antes de que sean elegibles para limpieza.
• runtime.installCommand: comando de instalación opcional que se ejecuta al arrancar un entorno de tiempo de ejecución 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 fijo y neutral (All your chats, one OpenClaw.).
  • "off": sin texto de eslogan (el título/la versión del banner siguen mostrándose).
• Para ocultar el banner completo (no solo los eslóganes), establece la env 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",    securityAcknowledgedAt: "2026-01-01T00:00:00.000Z",  },}

Identidad

Consulta los campos de identidad de agents.list en Valores predeterminados del agente.

Puente (heredado, eliminado)

Las compilaciones actuales ya no incluyen el puente TCP. Los nodos 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: 8, // default; 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 aisladas de Cron antes de podarlas de sessions.json. También controla la limpieza de las transcripciones archivadas de Cron eliminadas. Predeterminado: 24h; establece false para desactivarlo.
• runLog.maxBytes: se acepta por compatibilidad con registros de ejecución de Cron antiguos respaldados por archivos. Predeterminado: 2_000_000 bytes.
• runLog.keepLines: filas más recientes del historial de ejecución de SQLite conservadas por trabajo. 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 de reserva heredada obsoleta (http/https) usada por openclaw doctor --fix para migrar trabajos almacenados que todavía tienen notify: true; la entrega en tiempo de ejecución usa delivery.mode="webhook" por trabajo junto con delivery.to, o delivery.completionDestination al conservar la entrega de anuncios.

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 Cron ante 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". Omítelo para reintentar todos los tipos transitorios.

Los trabajos de una sola ejecución permanecen habilitados hasta que se agotan los intentos de reintento; después se deshabilitan mientras conservan el estado de error final. Los trabajos recurrentes usan la misma política de reintento transitorio para ejecutarse de nuevo después de la espera antes de su siguiente intervalo programado; los errores permanentes o los reintentos transitorios agotados vuelven al calendario recurrente normal con espera por error.

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 (predeterminado: false).
• after: fallos consecutivos antes de que se dispare una alerta (entero positivo, mín.: 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 (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: 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"; el valor predeterminado es "announce" cuando existen datos de destino suficientes.
• channel: anulación de canal para la entrega de anuncios. "last" reutiliza el último canal de entrega conocido.
• to: destino de anuncio explícito o URL de Webhook. Obligatorio para el modo Webhook.
• accountId: anulación de cuenta opcional para la entrega.
• delivery.failureDestination por trabajo anula este valor predeterminado global.
• Cuando no se establece 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 es compatible con trabajos sessionTarget="isolated" salvo que el delivery.mode principal del trabajo sea "webhook".

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

Variables de plantilla del modelo de medios

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 fusiona profundamente 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 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/../ solo se permiten cuando siguen resolviéndose dentro de ese límite. Las rutas no deben contener bytes nulos y deben tener estrictamente menos de 4096 caracteres antes y después de la resolución.
• Las escrituras propiedad de OpenClaw que cambian solo una sección de nivel superior respaldada por una inclusión de archivo único escriben a través de 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, inclusiones circulares, formato de ruta inválido y longitud excesiva.

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

Relacionado

• Configuración
• Ejemplos de configuración