OpenClaw lee una configuración opcional desdeDocumentation 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/openclaw.json.
La ruta de configuración activa debe ser un archivo normal. Los diseños de openclaw.json
con enlaces simbólicos no son compatibles con las escrituras propiedad de OpenClaw; una escritura atómica puede reemplazar
la ruta en lugar de preservar el enlace simbólico. Si mantienes la configuración fuera del
directorio de estado predeterminado, apunta OPENCLAW_CONFIG_PATH directamente al archivo real.
Si el archivo no existe, OpenClaw usa valores predeterminados seguros. Motivos habituales para añadir una configuración:
- Conectar canales y controlar quién puede enviar mensajes al bot
- Definir modelos, herramientas, aislamiento o automatización (cron, hooks)
- Ajustar sesiones, medios, red o UI
config.schema.lookup para obtener documentación exacta
a nivel de campo antes de editar la configuración. Usa esta página como guía orientada a tareas y
la Referencia de configuración para el mapa de campos y valores
predeterminados más amplio.
Configuración mínima
Editar la configuración
- Asistente interactivo
- CLI (comandos de una línea)
- UI de control
- Edición directa
Validación estricta
openclaw config schema imprime el JSON Schema canónico usado por la UI de control
y la validación. config.schema.lookup obtiene un único nodo acotado por ruta más
resúmenes de hijos para herramientas de exploración detallada. Los metadatos de documentación de campos title/description
se propagan a través de objetos anidados, comodines (*), elementos de array ([]) y ramas anyOf/
oneOf/allOf. Los esquemas de plugins y canales en tiempo de ejecución se fusionan cuando se
carga el registro de manifiestos.
Cuando falla la validación:
- El Gateway no arranca
- Solo funcionan los comandos de diagnóstico (
openclaw doctor,openclaw logs,openclaw health,openclaw status) - Ejecuta
openclaw doctorpara ver los problemas exactos - Ejecuta
openclaw doctor --fix(o--yes) para aplicar reparaciones
openclaw.json
falla la validación (incluida la validación local del plugin), el inicio del Gateway falla o
se omite la recarga y el runtime actual conserva la última configuración aceptada.
Ejecuta openclaw doctor --fix (o --yes) para reparar configuraciones con prefijos/sobrescritas o
restaurar la copia de última configuración válida. La promoción a última configuración válida se omite cuando un
candidato contiene marcadores de secretos redactados como ***.
Tareas comunes
Configurar un canal (WhatsApp, Telegram, Discord, etc.)
Configurar un canal (WhatsApp, Telegram, Discord, etc.)
channels.<provider>. Consulta la página dedicada del canal para ver los pasos de configuración:- WhatsApp -
channels.whatsapp - Telegram -
channels.telegram - Discord -
channels.discord - Feishu -
channels.feishu - Google Chat -
channels.googlechat - Microsoft Teams -
channels.msteams - Slack -
channels.slack - Signal -
channels.signal - iMessage -
channels.imessage - Mattermost -
channels.mattermost
Elegir y configurar modelos
Elegir y configurar modelos
agents.defaults.modelsdefine el catálogo de modelos y actúa como allowlist para/model; las entradasprovider/*filtran/model,/modelsy los selectores de modelos a los proveedores seleccionados mientras siguen usando descubrimiento dinámico de modelos.- Usa
openclaw config set agents.defaults.models '<json>' --strict-json --mergepara añadir entradas a la allowlist sin eliminar modelos existentes. Los reemplazos planos que eliminarían entradas se rechazan a menos que pases--replace. - Las referencias de modelo usan el formato
provider/model(por ejemplo,anthropic/claude-opus-4-6). agents.defaults.imageMaxDimensionPxcontrola la reducción de escala de imágenes de transcripción/herramientas (valor predeterminado1200); valores más bajos suelen reducir el uso de tokens de visión en ejecuciones con muchas capturas de pantalla.- Consulta CLI de modelos para cambiar modelos en el chat y Conmutación por error de modelos para la rotación de autenticación y el comportamiento de fallback.
- Para proveedores personalizados/autohospedados, consulta Proveedores personalizados en la referencia.
Controlar quién puede enviar mensajes al bot
Controlar quién puede enviar mensajes al bot
dmPolicy:"pairing"(predeterminado): los remitentes desconocidos reciben un código de vinculación de un solo uso para aprobación"allowlist": solo remitentes enallowFrom(o en el almacén de permisos vinculados)"open": permite todos los DM entrantes (requiereallowFrom: ["*"])"disabled": ignora todos los DM
groupPolicy + groupAllowFrom o allowlists específicas del canal.Consulta la referencia completa para ver detalles por canal.Configurar el control de menciones en chats grupales
Configurar el control de menciones en chats grupales
- Menciones de metadatos: @-menciones nativas (mencionar tocando en WhatsApp, @bot de Telegram, etc.)
- Patrones de texto: patrones regex seguros en
mentionPatterns - Respuestas visibles:
messages.visibleRepliespuede requerir envíos mediante herramienta de mensajes globalmente;messages.groupChat.visibleReplieslo sobrescribe para grupos/canales. - Consulta la referencia completa para los modos de respuesta visible, las sobrescrituras por canal y el modo de chat consigo mismo.
Restringir Skills por agente
Restringir Skills por agente
agents.defaults.skills para una base compartida y luego sobrescribe agentes
específicos con agents.list[].skills:- Omite
agents.defaults.skillspara permitir Skills sin restricciones de forma predeterminada. - Omite
agents.list[].skillspara heredar los valores predeterminados. - Define
agents.list[].skills: []para no permitir Skills. - Consulta Skills, Configuración de Skills y la Referencia de configuración.
Ajustar la supervisión de estado de canales del Gateway
Ajustar la supervisión de estado de canales del Gateway
- Define
gateway.channelHealthCheckMinutes: 0para desactivar globalmente los reinicios del monitor de estado. channelStaleEventThresholdMinutesdebe ser mayor o igual que el intervalo de comprobación.- Usa
channels.<provider>.healthMonitor.enabledochannels.<provider>.accounts.<id>.healthMonitor.enabledpara desactivar los reinicios automáticos de un canal o cuenta sin desactivar el monitor global. - Consulta Comprobaciones de estado para depuración operativa y la referencia completa para todos los campos.
Ajustar el timeout del handshake WebSocket del Gateway
Ajustar el timeout del handshake WebSocket del Gateway
- El valor predeterminado es
15000milisegundos. OPENCLAW_HANDSHAKE_TIMEOUT_MSsigue teniendo prioridad para sobrescrituras puntuales de servicio o shell.- Prefiere corregir primero los bloqueos de inicio/bucle de eventos; este ajuste es para hosts que están sanos pero son lentos durante el calentamiento.
Configurar sesiones y restablecimientos
Configurar sesiones y restablecimientos
dmScope:main(compartido) |per-peer|per-channel-peer|per-account-channel-peerthreadBindings: valores predeterminados globales para el enrutamiento de sesiones vinculadas a hilos (Discord admite/focus,/unfocus,/agents,/session idley/session max-age).- Consulta Gestión de sesiones para el alcance, los enlaces de identidad y la política de envío.
- Consulta la referencia completa para ver todos los campos.
Habilitar el aislamiento
Habilitar el aislamiento
scripts/sandbox-setup.sh, o desde una instalación de npm consulta el comando docker build en línea en Aislamiento § Imágenes y configuración.Consulta Aislamiento para ver la guía completa y la referencia completa para ver todas las opciones.Habilitar push respaldado por relay para compilaciones oficiales de iOS
Habilitar push respaldado por relay para compilaciones oficiales de iOS
openclaw.json.Define esto en la configuración del Gateway:- Permite que el Gateway envíe
push.test, avisos de activación y activaciones de reconexión a través del relay externo. - Usa una concesión de envío con alcance de registro reenviada por la app de iOS emparejada. El Gateway no necesita un token de relay para todo el despliegue.
- Vincula cada registro respaldado por relay con la identidad del Gateway con la que se emparejó la app de iOS, por lo que otro Gateway no puede reutilizar el registro almacenado.
- Mantiene las compilaciones locales/manuales de iOS en APNs directas. Los envíos respaldados por relay se aplican solo a las compilaciones distribuidas oficiales que se registraron a través del relay.
- Debe coincidir con la URL base del relay integrada en la compilación oficial/TestFlight de iOS, para que el tráfico de registro y envío llegue al mismo despliegue del relay.
- Instala una compilación oficial/TestFlight de iOS compilada con la misma URL base del relay.
- Configura
gateway.push.apns.relay.baseUrlen el Gateway. - Empareja la app de iOS con el Gateway y deja que se conecten tanto las sesiones del nodo como las del operador.
- La app de iOS obtiene la identidad del Gateway, se registra con el relay usando App Attest más el recibo de la app y luego publica la carga útil
push.apns.registerrespaldada por relay en el Gateway emparejado. - El Gateway almacena el identificador del relay y la concesión de envío, y luego los usa para
push.test, avisos de activación y activaciones de reconexión.
- Si cambias la app de iOS a un Gateway diferente, vuelve a conectar la app para que pueda publicar un nuevo registro de relay vinculado a ese Gateway.
- Si publicas una nueva compilación de iOS que apunta a un despliegue de relay diferente, la app actualiza su registro de relay en caché en lugar de reutilizar el origen de relay anterior.
OPENCLAW_APNS_RELAY_BASE_URLyOPENCLAW_APNS_RELAY_TIMEOUT_MSsiguen funcionando como sobrescrituras temporales de entorno.OPENCLAW_APNS_RELAY_ALLOW_HTTP=truesigue siendo una vía de escape de desarrollo solo para local loopback; no persistas URLs de relay HTTP en la configuración.
Configurar Heartbeat (comprobaciones periódicas)
Configurar Heartbeat (comprobaciones periódicas)
every: cadena de duración (30m,2h). Define0mpara deshabilitar.target:last|none|<channel-id>(por ejemplodiscord,matrix,telegramowhatsapp)directPolicy:allow(predeterminado) oblockpara destinos de Heartbeat de estilo DM- Consulta Heartbeat para ver la guía completa.
Configurar trabajos de Cron
Configurar trabajos de Cron
sessionRetention: elimina sesiones de ejecución aisladas completadas desessions.json(predeterminado24h; definefalsepara deshabilitar).runLog: recortacron/runs/<jobId>.jsonlpor tamaño y líneas conservadas.- Consulta Trabajos de Cron para ver una descripción general de la función y ejemplos de CLI.
Configurar webhooks (hooks)
Configurar webhooks (hooks)
- Trata todo el contenido de las cargas útiles de hook/Webhook como entrada no confiable.
- Usa un
hooks.tokendedicado; no reutilices el token compartido del Gateway. - La autenticación de hook es solo por encabezado (
Authorization: Bearer ...ox-openclaw-token); los tokens en la cadena de consulta se rechazan. hooks.pathno puede ser/; mantén el ingreso de Webhook en una subruta dedicada, como/hooks.- Mantén deshabilitadas las marcas de omisión de contenido no seguro (
hooks.gmail.allowUnsafeExternalContent,hooks.mappings[].allowUnsafeExternalContent) salvo para depuración con alcance muy limitado. - Si habilitas
hooks.allowRequestSessionKey, define tambiénhooks.allowedSessionKeyPrefixespara acotar las claves de sesión elegidas por el llamador. - Para agentes impulsados por hooks, prefiere niveles de modelo modernos y sólidos y una política de herramientas estricta (por ejemplo, solo mensajería más aislamiento cuando sea posible).
Configurar enrutamiento multiagente
Configurar enrutamiento multiagente
Dividir la configuración en varios archivos ($include)
Dividir la configuración en varios archivos ($include)
$include para organizar configuraciones grandes:- Archivo único: reemplaza el objeto contenedor
- Matriz de archivos: se fusiona en profundidad en orden (gana el posterior)
- Claves hermanas: se fusionan después de los includes (sobrescriben los valores incluidos)
- Includes anidados: admitidos hasta 10 niveles de profundidad
- Rutas relativas: se resuelven en relación con el archivo que incluye
- Escrituras propiedad de OpenClaw: cuando una escritura cambia solo una sección de nivel superior
respaldada por un include de archivo único como
plugins: { $include: "./plugins.json5" }, OpenClaw actualiza ese archivo incluido y dejaopenclaw.jsonintacto - Write-through no admitido: los includes raíz, las matrices de includes y los includes con sobrescrituras hermanas fallan de forma cerrada para escrituras propiedad de OpenClaw en lugar de aplanar la configuración
- Confinamiento: las rutas de
$includedeben resolverse bajo el directorio que contieneopenclaw.json. Para compartir un árbol entre máquinas o usuarios, defineOPENCLAW_INCLUDE_ROOTScomo una lista de rutas (:en POSIX,;en Windows) de directorios adicionales que los includes pueden referenciar. Los enlaces simbólicos se resuelven y se vuelven a comprobar, por lo que una ruta que léxicamente vive en un directorio de configuración pero cuyo destino real escapa de todas las raíces permitidas también se rechaza. - Gestión de errores: errores claros para archivos faltantes, errores de análisis e includes circulares
Recarga en caliente de la configuración
El Gateway observa~/.openclaw/openclaw.json y aplica los cambios automáticamente; no se necesita reinicio manual para la mayoría de los ajustes.
Las ediciones directas de archivos se tratan como no confiables hasta que se validan. El observador espera
a que se estabilice la actividad de escrituras temporales/renombrados del editor, lee el archivo final y rechaza
las ediciones externas no válidas sin reescribir openclaw.json. Las escrituras de configuración
propiedad de OpenClaw usan la misma puerta de esquema antes de escribir; las sobrescrituras destructivas como
eliminar gateway.mode o reducir el archivo a menos de la mitad se rechazan y
se guardan como .rejected.* para inspección.
Si ves config reload skipped (invalid config) o el arranque informa Invalid config, inspecciona la configuración, ejecuta openclaw config validate y luego ejecuta openclaw doctor --fix para reparar. Consulta Solución de problemas del Gateway
para ver la lista de comprobación.
Modos de recarga
| Modo | Comportamiento |
|---|---|
hybrid (predeterminado) | Aplica en caliente los cambios seguros al instante. Reinicia automáticamente para los críticos. |
hot | Aplica en caliente solo los cambios seguros. Registra una advertencia cuando se necesita reiniciar; tú te encargas. |
restart | Reinicia el Gateway ante cualquier cambio de configuración, sea seguro o no. |
off | Deshabilita la observación de archivos. Los cambios surten efecto en el siguiente reinicio manual. |
Qué se aplica en caliente y qué necesita un reinicio
La mayoría de los campos se aplican en caliente sin tiempo de inactividad. En modohybrid, los cambios que requieren reinicio se gestionan automáticamente.
| Categoría | Campos | ¿Requiere reinicio? |
|---|---|---|
| Canales | channels.*, web (WhatsApp): todos los canales integrados y de Plugin | No |
| Agente y modelos | agent, agents, models, routing | No |
| Automatización | hooks, cron, agent.heartbeat | No |
| Sesiones y mensajes | session, messages | No |
| Herramientas y medios | tools, browser, skills, mcp, audio, talk | No |
| IU y varios | ui, logging, identity, bindings | No |
| Servidor Gateway | gateway.* (puerto, enlace, autenticación, tailscale, TLS, HTTP) | Sí |
| Infraestructura | discovery, plugins | Sí |
gateway.reload y gateway.remote son excepciones: cambiarlos no activa un reinicio.Planificación de recarga
Cuando editas un archivo fuente referenciado mediante$include, OpenClaw planifica
la recarga desde el diseño definido en la fuente, no desde la vista aplanada en memoria.
Esto mantiene predecibles las decisiones de recarga en caliente (aplicación en caliente frente a reinicio), incluso cuando una
única sección de nivel superior vive en su propio archivo incluido, como
plugins: { $include: "./plugins.json5" }. La planificación de recarga falla de forma cerrada si el
diseño de origen es ambiguo.
RPC de configuración (actualizaciones programáticas)
Para herramientas que escriben configuración mediante la API de Gateway, prefiere este flujo:config.schema.lookuppara inspeccionar un subárbol (nodo de esquema superficial + resúmenes de hijos)config.getpara obtener la instantánea actual máshashconfig.patchpara actualizaciones parciales (parche de fusión JSON: los objetos se fusionan,nullelimina, los arreglos reemplazan)config.applysolo cuando pretendas reemplazar toda la configuraciónupdate.runpara una autoactualización explícita más reinicio; incluyecontinuationMessagecuando la sesión posterior al reinicio deba ejecutar un turno de seguimientoupdate.statuspara inspeccionar el centinela de reinicio de la actualización más reciente y verificar la versión en ejecución después de un reinicio
config.schema.lookup como el primer punto de consulta para obtener
documentación y restricciones exactas a nivel de campo. Usa Referencia de configuración
cuando necesiten el mapa de configuración más amplio, los valores predeterminados o enlaces a referencias dedicadas
de subsistemas.
config.apply, config.patch, update.run) están
limitadas a 3 solicitudes por 60 segundos por deviceId+clientIp. Las solicitudes de reinicio
se fusionan y luego aplican un periodo de espera de 30 segundos entre ciclos de reinicio.
update.status es de solo lectura, pero está dentro del ámbito de administración porque el centinela de reinicio puede
incluir resúmenes de pasos de actualización y colas de salida de comandos.config.apply como config.patch aceptan raw, baseHash, sessionKey,
note y restartDelayMs. baseHash es obligatorio para ambos métodos cuando ya existe una
configuración.
Variables de entorno
OpenClaw lee variables de entorno del proceso padre, además de:.envdesde el directorio de trabajo actual (si está presente)~/.openclaw/.env(respaldo global)
Importación de entorno de shell (opcional)
Importación de entorno de shell (opcional)
OPENCLAW_LOAD_SHELL_ENV=1Sustitución de variables de entorno en valores de configuración
Sustitución de variables de entorno en valores de configuración
${VAR_NAME}:- Solo coinciden nombres en mayúsculas:
[A-Z_][A-Z0-9_]* - Las variables faltantes/vacías generan un error en el momento de carga
- Escapa con
$${VAR}para salida literal - Funciona dentro de archivos
$include - Sustitución en línea:
"${BASE}/v1"→"https://api.example.com/v1"
Referencias secretas (env, archivo, exec)
Referencias secretas (env, archivo, exec)
secrets.providers para env/file/exec) están en Gestión de secretos.
Las rutas de credenciales compatibles se enumeran en Superficie de credenciales de SecretRef.Referencia completa
Para la referencia completa campo por campo, consulta Referencia de configuración.Relacionado: Ejemplos de configuración · Referencia de configuración · Doctor