Configuración y operaciones

Configuración

OpenClaw lee una configuración JSON5 opcional desde ~/.openclaw/openclaw.json. Si el archivo falta, OpenClaw usa valores predeterminados seguros. Razones comunes para agregar una configuración:

Conectar canales y controlar quién puede enviar mensajes al bot
Establecer modelos, herramientas, sandboxing o automatización (cron, hooks)
Ajustar sesiones, medios, redes o UI

Consulta la referencia completa para cada campo disponible.

💡 ¿Nuevo en configuración? Comienza con openclaw onboard para una configuración interactiva, o revisa la guía Ejemplos de Configuración para configuraciones completas para copiar y pegar.

Configuración mínima

// ~/.openclaw/openclaw.json
{
  agents: { defaults: { workspace: "~/.openclaw/workspace" } },
  channels: { whatsapp: { allowFrom: ["+15555550123"] } },
}

Editar configuración

openclaw onboard       # asistente de configuración completo
openclaw configure     # asistente de configuración

Validación estricta

⚠️ OpenClaw solo acepta configuraciones que coincidan completamente con el esquema. Claves desconocidas, tipos malformados o valores inválidos hacen que el Gateway se niegue a iniciar. La única excepción a nivel raíz es $schema (string), para que los editores puedan adjuntar metadatos de JSON Schema.

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 doctor para ver los problemas exactos
Ejecuta openclaw doctor --fix (o --yes) para aplicar reparaciones

Tareas comunes

Configurar un canal (WhatsApp, Telegram, Discord, etc.)

Elegir y configurar modelos

Controlar quién puede enviar mensajes al bot

Configurar la compuerta de menciones en chat grupal

Configurar sesiones y reinicios

Habilitar sandboxing

Configurar heartbeat (comprobaciones periódicas)

Configurar trabajos cron

Configurar webhooks (hooks)

Configurar enrutamiento multi-agente

Dividir configuración en múltiples archivos ($include)

Recarga en caliente de 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.

Modos de recarga

Modo	Comportamiento
`hybrid` (predeterminado)	Aplica cambios seguros al instante. Reinicia automáticamente para los críticos.
`hot`	Solo aplica cambios seguros en caliente. Registra una advertencia cuando se necesita un reinicio — lo manejas tú.
`restart`	Reinicia el Gateway en cualquier cambio de configuración, seguro o no.
`off`	Desactiva la observación de archivos. Los cambios surten efecto en el próximo reinicio manual.

{
  gateway: {
    reload: { mode: "hybrid", debounceMs: 300 },
  },
}

Qué se aplica en caliente vs qué necesita un reinicio

La mayoría de los campos se aplican en caliente sin tiempo de inactividad. En modo hybrid, los cambios que requieren reinicio se manejan automáticamente.

Categoría	Campos	¿Se necesita reinicio?
Canales	`channels.*`, `web` (WhatsApp) — todos los canales integrados y de extensión	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`, `audio`, `talk`	No
UI y misceláneos	`ui`, `logging`, `identity`, `bindings`	No
Servidor Gateway	`gateway.*` (puerto, bind, auth, tailscale, TLS, HTTP)	Sí
Infraestructura	`discovery`, `canvasHost`, `plugins`	Sí

ℹ️ gateway.reload y gateway.remote son excepciones — cambiarlos no desencadena un reinicio.

RPC de configuración (actualizaciones programáticas)

ℹ️ Los RPC de escritura del plano de control (config.apply, config.patch, update.run) están limitados a 3 solicitudes por 60 segundos por deviceId+clientIp. Cuando se limita, el RPC devuelve UNAVAILABLE con retryAfterMs.

config.apply (reemplazo completo)

config.patch (actualización parcial)

Variables de entorno

OpenClaw lee variables de entorno del proceso padre más:

.env desde el directorio de trabajo actual (si está presente)
~/.openclaw/.env (respaldo global)

Ningún archivo anula las variables de entorno existentes. También puedes establecer variables de entorno en línea en la configuración:

{
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: { GROQ_API_KEY: "gsk-..." },
  },
}

Importación de entorno de shell (opcional)

Sustitución de variables de entorno en valores de configuración

Referencias secretas (env, file, exec)

Consulta Entorno para la precedencia completa y fuentes.

Referencia completa

Para la referencia completa campo por campo, consulta Referencia de Configuración.

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

Runbook del Gateway Referencia de Configuración