Configuración

OpenClaw lee una configuración opcional de JSON5 desde ~/.openclaw/openclaw.json.

Si falta el archivo, OpenClaw utiliza valores predeterminados seguros. Razones comunes para añadir 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 interfaz de usuario

Consulte la referencia completa para ver todos los campos disponibles.

Configuración mínima

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

Editar configuración

bash openclaw onboard # full onboarding flow openclaw configure # config wizard

bash openclaw config get agents.defaults.workspace openclaw config set agents.defaults.heartbeat.every "2h" openclaw config unset plugins.entries.brave.config.webSearch.apiKey

Edite ~/.openclaw/openclaw.json directamente. El Gateway supervisa el archivo y aplica los cambios automáticamente (ver recarga en caliente).

Validación estricta

Cuando falla la validación:

El Gateway no se inicia
Solo funcionan los comandos de diagnóstico (openclaw doctor, openclaw logs, openclaw health, openclaw status)
Ejecute openclaw doctor para ver los problemas exactos
Ejecute openclaw doctor --fix (o --yes) para aplicar reparaciones

Tareas comunes

Set up a channel (WhatsApp, Telegram, Discord, etc.)

Cada canal tiene su propia sección de configuración en `channels.

`. Consulte la página dedicada del canal para ver los pasos de configuración:

- [WhatsApp](/en/channels/whatsapp) — `channels.whatsapp`
- [Telegram](/en/channels/telegram) — `channels.telegram`
- [Discord](/en/channels/discord) — `channels.discord`
- [Slack](/en/channels/slack) — `channels.slack`
- [Signal](/en/channels/signal) — `channels.signal`
- [iMessage](/en/channels/imessage) — `channels.imessage`
- [Google Chat](/en/channels/googlechat) — `channels.googlechat`
- [Mattermost](/en/channels/mattermost) — `channels.mattermost`
- [Microsoft Teams](/en/channels/msteams) — `channels.msteams`

Todos los canales comparten el mismo patrón de política de MD:

```json5
{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // only for allowlist/open
    },
  },
}
```

Choose and configure models

Configure el modelo principal y las alternativas opcionales:

{
  agents: {
    defaults: {
      model: {
        primary: "anthropic/claude-sonnet-4-6",
        fallbacks: ["openai/gpt-5.2"],
      },
      models: {
        "anthropic/claude-sonnet-4-6": { alias: "Sonnet" },
        "openai/gpt-5.2": { alias: "GPT" },
      },
    },
  },
}

agents.defaults.models define el catálogo de modelos y actúa como la lista de permitidos para /model.
Las referencias de modelos utilizan el formato provider/model (ej. anthropic/claude-opus-4-6).
agents.defaults.imageMaxDimensionPx controla la reducción de escala de imágenes de transcripciones/herramientas (por defecto 1200); los valores más bajos generalmente reducen el uso de tokens de visión en ejecuciones con muchas capturas de pantalla.
Consulte Models CLI para cambiar modelos en el chat y Model Failover para la rotación de autenticación y el comportamiento de alternancia.
Para proveedores personalizados/autoalojados, consulte Custom providers en la referencia.

Control who can message the bot

El acceso a MD se controla por canal a través de dmPolicy:

"pairing" (predeterminado): los remitentes desconocidos reciben un código de emparejamiento de un solo vez para aprobar
"allowlist": solo remitentes en allowFrom (o el almacenamiento de permisos emparejado)
"open": permitir todos los MD entrantes (requiere allowFrom: ["*"])
"disabled": ignorar todos los MD

Para grupos, utilice groupPolicy + groupAllowFrom o listas de permitidos específicas del canal.

Consulte la referencia completa para obtener detalles por canal.

Set up group chat mention gating

Los mensajes de grupo por defecto requieren mención. Configure patrones por agente:

{
  agents: {
    list: [
      {
        id: "main",
        groupChat: {
          mentionPatterns: ["@openclaw", "openclaw"],
        },
      },
    ],
  },
  channels: {
    whatsapp: {
      groups: { "*": { requireMention: true } },
    },
  },
}

Menciones de metadatos: menciones nativas @-mentions (menciones al tocar en WhatsApp, @bot en Telegram, etc.)
Patrones de texto: patrones de regex seguros en mentionPatterns
Consulte referencia completa para anulaciones por canal y modo de chat propio.

Ajustar la supervisión del estado de los canales de la puerta de enlace

Controle la frecuencia con la que la puerta de enlace reinicia los canales que parecen obsoletos:

{
  gateway: {
    channelHealthCheckMinutes: 5,
    channelStaleEventThresholdMinutes: 30,
    channelMaxRestartsPerHour: 10,
  },
  channels: {
    telegram: {
      healthMonitor: { enabled: false },
      accounts: {
        alerts: {
          healthMonitor: { enabled: true },
        },
      },
    },
  },
}

Establezca gateway.channelHealthCheckMinutes: 0 para desactivar globalmente los reinicios de supervisión de estado.
channelStaleEventThresholdMinutes debe ser mayor o igual que el intervalo de verificación.
Use `channels.

.healthMonitor.enabledochannels.

.accounts.

.healthMonitor.enabled` para desactivar los reinicios automáticos para un canal o cuenta sin desactivar el supervisor global. - Consulte Verificaciones de estado para la depuración operativa y la referencia completa para todos los campos.

Configurar sesiones y restablecimientos

Las sesiones controlan la continuidad y el aislamiento de la conversación:

{
  session: {
    dmScope: "per-channel-peer",  // recommended for multi-user
    threadBindings: {
      enabled: true,
      idleHours: 24,
      maxAgeHours: 0,
    },
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

dmScope: main (compartida) | per-peer | per-channel-peer | per-account-channel-peer
threadBindings: valores predeterminados globales para el enrutamiento de sesiones vinculadas a hilos (Discord admite /focus, /unfocus, /agents, /session idle y /session max-age).
Consulte Gestión de sesiones para obtener información sobre el ámbito, los enlaces de identidad y la política de envío.
Consulte la referencia completa para todos los campos.

Activar el aislamiento (sandboxing)

Ejecute sesiones de agentes en contenedores Docker aislados:

{
  agents: {
    defaults: {
      sandbox: {
        mode: "non-main",  // off | non-main | all
        scope: "agent",    // session | agent | shared
      },
    },
  },
}

Compile primero la imagen: scripts/sandbox-setup.sh

Consulte Aislamiento para obtener la guía completa y la referencia completa para todas las opciones.

Habilitar notificaciones con respaldo de relay para compilaciones oficiales de iOS

Las notificaciones con respaldo de relay se configuran en openclaw.json.

Establézcalo en la configuración de la puerta de enlace:

{
  gateway: {
    push: {
      apns: {
        relay: {
          baseUrl: "https://relay.example.com",
          // Optional. Default: 10000
          timeoutMs: 10000,
        },
      },
    },
  },
}

Equivalente de CLI:

openclaw config set gateway.push.apns.relay.baseUrl https://relay.example.com

Lo que esto hace:

Permite que la puerta de enlace envíe push.test, empujes de activación (wake nudges) y activaciones de reconexión a través del relay externo.
Utiliza un permiso de envío con alcance de registro reenviado por la aplicación iOS emparejada. La puerta de enlace no necesita un token de relay para todo el despliegue.
Vincula cada registro con respaldo de relay a la identidad de la puerta de enlace con la que la aplicación iOS se emparejó, de modo que otra puerta de enlace no pueda reutilizar el registro almacenado.
Mantiene las compilaciones locales/manuales de iOS en APNs directos. Los envíos con respaldo de relay se aplican solo a compilaciones distribuidas oficialmente 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, de modo que el tráfico de registro y envío llegue al mismo despliegue del relay.

Flujo de un extremo a otro:

Instale una compilación oficial/TestFlight de iOS que se compiló con la misma URL base del relay.
Configure gateway.push.apns.relay.baseUrl en la puerta de enlace.
Empareje la aplicación iOS con la puerta de enlace y permita que se conecten tanto las sesiones de nodo como las de operador.
La aplicación iOS obtiene la identidad de la puerta de enlace, se registra con el relay usando App Attest más el recibo de la aplicación y luego publica el payload push.apns.register con respaldo de relay en la puerta de enlace emparejada.
La puerta de enlace almacena el identificador y el permiso de envío del relay, y luego los usa para push.test, empujes de activación y activaciones de reconexión.

Notas operativas:

Si cambia la aplicación iOS a una puerta de enlace diferente, reconecte la aplicación para que pueda publicar un nuevo registro de relay vinculado a esa puerta de enlace.
Si envía una nueva compilación de iOS que apunta a un despliegue de relay diferente, la aplicación actualiza su registro de relay en caché en lugar de reutilizar el origen del relay antiguo.

Nota de compatibilidad:

OPENCLAW_APNS_RELAY_BASE_URL y OPENCLAW_APNS_RELAY_TIMEOUT_MS aún funcionan como anulaciones de entorno temporales.
OPENCLAW_APNS_RELAY_ALLOW_HTTP=true sigue siendo una salida de emergencia para desarrollo solo de bucle invertido; no persista las URLs de relay HTTP en la configuración.

Consulte iOS App para el flujo de un extremo a otro y Authentication and trust flow para el modelo de seguridad del relay.

Configurar latido (verificaciones periódicas)

{
  agents: {
    defaults: {
      heartbeat: {
        every: "30m",
        target: "last",
      },
    },
  },
}

every: cadena de duración (30m, 2h). Establezca 0m para desactivar.
target: last | none | `

(por ejemplodiscord, matrix, telegram, o whatsapp) - directPolicy: allow(predeterminado) oblock` para objetivos de latido estilo DM - Vea Heartbeat para la guía completa.

Configurar trabajos cron

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
    runLog: {
      maxBytes: "2mb",
      keepLines: 2000,
    },
  },
}

sessionRetention: eliminar sesiones de ejecución aisladas completadas de sessions.json (predeterminado 24h; establezca false para desactivar).
runLog: eliminar `cron/runs/

.jsonl` por tamaño y líneas retenidas. - Vea Cron jobs para la descripción general de las características y ejemplos de CLI.

Configurar webhooks (hooks)

Activar endpoints de webhook HTTP en la Pasarela (Gateway):

{
  hooks: {
    enabled: true,
    token: "shared-secret",
    path: "/hooks",
    defaultSessionKey: "hook:ingress",
    allowRequestSessionKey: false,
    allowedSessionKeyPrefixes: ["hook:"],
    mappings: [
      {
        match: { path: "gmail" },
        action: "agent",
        agentId: "main",
        deliver: true,
      },
    ],
  },
}

Nota de seguridad:

Trate todo el contenido del payload de hook/webhook como entrada no confiable.
Mantenga las banderas de omisión de contenido no seguro desactivadas (hooks.gmail.allowUnsafeExternalContent, hooks.mappings[].allowUnsafeExternalContent) a menos que esté realizando una depuración de alcance limitado.
Para los agentes impulsados por hooks, prefiera niveles de modelo modernos y fuertes y una política de herramientas estricta (por ejemplo, solo mensajería más sandbox donde sea posible).

Vea referencia completa para todas las opciones de mapeo e integración con Gmail.

Configurar el enrutamiento multi-agente

Ejecute múltiples agentes aislados con espacios de trabajo y sesiones separados:

{
  agents: {
    list: [
      { id: "home", default: true, workspace: "~/.openclaw/workspace-home" },
      { id: "work", workspace: "~/.openclaw/workspace-work" },
    ],
  },
  bindings: [
    { agentId: "home", match: { channel: "whatsapp", accountId: "personal" } },
    { agentId: "work", match: { channel: "whatsapp", accountId: "biz" } },
  ],
}

Consulte Multi-Agent y referencia completa para conocer las reglas de vinculación y los perfiles de acceso por agente.

Dividir la configuración en varios archivos ($include)

Use $include para organizar configuraciones grandes:

{
  gateway: { port: 18789 },
  agents: { $include: "./agents.json5" },
  broadcast: {
    $include: ["./clients/a.json5", "./clients/b.json5"],
  },
}

Archivo único: reemplaza el objeto contenedor
Array de archivos: fusionados en profundidad por orden (los últimos prevalecen)
Claves hermanas: se fusionan después de las inclusiones (anulan los valores incluidos)
Inclusiones anidadas: compatibles hasta 10 niveles de profundidad
Rutas relativas: se resuelven en relación con el archivo que incluye
Manejo de errores: errores claros para archivos faltantes, errores de análisis e inclusiones 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.

Modos de recarga

Modo	Comportamiento
`hybrid` (predeterminado)	Aplica cambios seguros en caliente al instante. Reinicia automáticamente para los críticos.
`hot`	Solo aplica cambios seguros en caliente. Registra una advertencia cuando es necesario un reinicio: usted lo maneja.
`restart`	Reinicia el Gateway ante 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 el modo hybrid, los cambios que requieren reinicio se manejan automáticamente.

Categoría	Campos	¿Reinicio necesario?
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
Interfaz de usuario y varios	`ui`, `logging`, `identity`, `bindings`	No
Servidor Gateway	`gateway.*` (puerto, bind, auth, tailscale, TLS, HTTP)	Sí
Infraestructura	`discovery`, `canvasHost`, `plugins`	Sí

Config RPC (actualizaciones programáticas)

config.apply (reemplazo total)

Valida + escribe la configuración completa y reinicia el Gateway en un solo paso.

Parámetros:

raw (cadena) — carga útil JSON5 para toda la configuración
baseHash (opcional) — hash de configuración de config.get (requerido cuando existe configuración)
sessionKey (opcional) — clave de sesión para el ping de activación posterior al reinicio
note (opcional) — nota para el centinela de reinicio
restartDelayMs (opcional) — retraso antes del reinicio (predeterminado 2000)

Las solicitudes de reinicio se combinan mientras una ya está pendiente/en curso, y se aplica un enfriamiento de 30 segundos entre los ciclos de reinicio.

openclaw gateway call config.get --params '{}'  # capture payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "

”, “sessionKey”: “agent:main:whatsapp:direct:+15555550123” }’ ```

config.patch (actualización parcial)

Combina una actualización parcial en la configuración existente (semántica de parche de combinación JSON):

Los objetos se combinan recursivamente
null elimina una clave
Las matrices se reemplazan

Parámetros:

raw (cadena) — JSON5 con solo las claves a cambiar
baseHash (requerido) — hash de configuración de config.get
sessionKey, note, restartDelayMs — igual que config.apply

El comportamiento de reinicio coincide con config.apply: reinicios pendientes combinados más un tiempo de espera de 30 segundos entre ciclos de reinicio.

openclaw gateway call config.patch --params '{
  "raw": "{ channels: { telegram: { groups: { \"*\": { requireMention: false } } } } }",
  "baseHash": "

” }’ ```

Variables de entorno

OpenClaw lee las variables de entorno del proceso principal y también:

.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)

Si está habilitado y las claves esperadas no están establecidas, OpenClaw ejecuta su shell de inicio de sesión e importa solo las claves faltantes:

{
  env: {
    shellEnv: { enabled: true, timeoutMs: 15000 },
  },
}

Equivalente de variable de entorno: OPENCLAW_LOAD_SHELL_ENV=1

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

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

{
  gateway: { auth: { token: "${OPENCLAW_GATEWAY_TOKEN}" } },
  models: { providers: { custom: { apiKey: "${CUSTOM_API_KEY}" } } },
}

Reglas:

Solo coinciden los nombres en mayúsculas: [A-Z_][A-Z0-9_]*
Las variables faltantes/vacías arrojan un error en el momento de la carga
Escapar con $${VAR} para una salida literal
Funciona dentro de archivos $include
Sustitución en línea: "${BASE}/v1" → "https://api.example.com/v1"

Secret refs (env, file, exec)

Para los campos que admiten objetos SecretRef, puedes usar:

{
  models: {
    providers: {
      openai: { apiKey: { source: "env", provider: "default", id: "OPENAI_API_KEY" } },
    },
  },
  skills: {
    entries: {
      "image-lab": {
        apiKey: {
          source: "file",
          provider: "filemain",
          id: "/skills/entries/image-lab/apiKey",
        },
      },
    },
  },
  channels: {
    googlechat: {
      serviceAccountRef: {
        source: "exec",
        provider: "vault",
        id: "channels/googlechat/serviceAccount",
      },
    },
  },
}

Los detalles de SecretRef (incluyendo secrets.providers para env/file/exec) están en Gestión de secretos. Las rutas de credenciales compatibles se enumeran en Superficie de credenciales SecretRef.

Consulta Entorno para obtener la precedencia y fuentes completas.

Referencia completa

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

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