Configuración de OpenClaw

Configurar herramientas nuevas suele ser un proceso frustrante cuando los valores por defecto no encajan con lo que necesitas. Si quieres que tu bot responda solo a ciertos usuarios o necesitas que tus agentes usen un workspace específico, tienes que tomar el control de la configuración para que el sistema se adapte a tu flujo de trabajo.

OpenClaw utiliza un archivo opcional en ~/.openclaw/openclaw.json. Lo mejor de usar el formato JSON5 es que permite añadir comentarios y comas finales, algo que ayuda mucho a mantener el orden. Si no creas este archivo, el sistema usará valores por defecto seguros.

What You’ll Need

• Acceso al archivo de configuración en ~/.openclaw/openclaw.json.
• La CLI de OpenClaw instalada para ejecutar comandos de diagnóstico.

Quick Start

Para tener OpenClaw listo en menos de 5 minutos, te recomiendo usar el asistente interactivo. Es la ruta más sencilla para evitar errores manuales.

Ejecuta este comando para iniciar la configuración:

openclaw onboard

Si prefieres editar el archivo directamente, aquí tienes una configuración mínima para empezar:

~/.openclaw/openclaw.json

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

Tienes cuatro formas de gestionar tus ajustes:

1. Asistentes interactivos: Usa openclaw onboard para una configuración completa o openclaw configure para ajustes específicos.
2. CLI: Puedes usar comandos como openclaw config set agents.defaults.heartbeat.every "2h" para cambios rápidos sin abrir editores.
3. Control UI: Abre http://127.0.0.1:18789 y usa la pestaña Config. Tienes un formulario visual y un editor Raw JSON.
4. Edición directa: Modifica ~/.openclaw/openclaw.json. El Gateway detecta los cambios y los aplica automáticamente.

Troubleshooting

OpenClaw aplica una validación estricta. Si el archivo tiene claves desconocidas o tipos de datos incorrectos, el Gateway no arrancará.

Si algo falla, sigue estos pasos:

• El Gateway no iniciará si la validación falla; solo podrás usar comandos de diagnóstico.
• Ejecuta openclaw doctor para ver los errores exactos en tu archivo.
• Usa openclaw logs, openclaw health o openclaw status para obtener más información del sistema.
• Ejecuta openclaw doctor --fix (o añade --yes) para que el sistema intente reparar los errores por ti.

AI Setup Assistant

What’s Next

• Configuration Reference
• Configuration Examples

Configurar un bot para que funcione en múltiples plataformas suele ser un proceso tedioso. Te encuentras lidiando con diferentes formatos de mensaje, gestionando quién tiene permiso para escribir y tratando de que la configuración no se convierta en un archivo gigante imposible de leer.

Esta guía te ayuda a resolver esos problemas comunes para que tu Gateway funcione exactamente como necesitas, sin complicaciones innecesarias.

Requisitos previos

• Un archivo de configuración de OpenClaw (JSON5).
• Acceso al Gateway.
• Tokens o credenciales de los canales que quieras conectar.

Inicio rápido

Configura lo básico en 5 minutos siguiendo estos pasos:

1. Elige tu canal: Define tu botToken y habilitación en la sección channels.
2. Configura el modelo: Elige un modelo primary y sus fallbacks.
3. Define el acceso: Ajusta dmPolicy para controlar quién puede hablar con el bot.
4. Organiza tu código: Usa $include si tu archivo de configuración crece demasiado.

---

Configurar canales (WhatsApp, Telegram, Discord, etc.)

Cada canal tiene su propia sección bajo channels.<provider>. Puedes encontrar los pasos específicos en las páginas dedicadas:

• WhatsApp — channels.whatsapp
• Telegram — channels.telegram
• Discord — channels.discord
• Slack — channels.slack
• Signal — channels.signal
• iMessage — channels.imessage
• Google Chat — channels.googlechat
• Mattermost — channels.mattermost
• MS Teams — channels.msteams

Todos los canales usan el mismo patrón para la política de mensajes directos (DM):

{
  channels: {
    telegram: {
      enabled: true,
      botToken: "123:abc",
      dmPolicy: "pairing",   // pairing | allowlist | open | disabled
      allowFrom: ["tg:123"], // solo para allowlist/open
    },
  },
}

Elegir y configurar modelos

Define el modelo principal y los respaldos opcionales en caso de fallos:

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

• agents.defaults.models define el catálogo de modelos y funciona como una allowlist para el comando /model.
• Las referencias de modelos usan el formato provider/model (ej. anthropic/claude-opus-4-6).
• Revisa Models CLI para cambiar modelos en el chat y Model Failover para ver el comportamiento de rotación de autenticación.
• Para proveedores personalizados, consulta Custom providers.

Controlar quién puede mensajear al bot

El acceso por DM se controla por canal mediante dmPolicy:

• "pairing" (por defecto): los remitentes desconocidos reciben un código de vinculación de un solo uso para aprobación.
• "allowlist": solo se permiten remitentes en allowFrom o en el almacén de permitidos vinculados.
• "open": permite todos los mensajes entrantes (requiere allowFrom: ["*"]).
• "disabled": ignora todos los DMs.

Para grupos, usa groupPolicy + groupAllowFrom o listas de permitidos específicas del canal. Tienes más detalles en full reference.

Configurar menciones en chats grupales

Por defecto, los mensajes de grupo requieren una mención. Puedes configurar patrones por agente:

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

• Menciones de metadatos: menciones nativas con @ (como en WhatsApp o Telegram).
• Patrones de texto: expresiones regulares en mentionPatterns.
• Consulta la full reference para ver excepciones por canal.

Configurar sesiones y reinicios

Las sesiones gestionan la continuidad y el aislamiento de las conversaciones:

{
  session: {
    dmScope: "per-channel-peer",  // recomendado para multi-usuario
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 120,
    },
  },
}

• dmScope: puede ser main (compartido), per-peer, per-channel-peer o per-account-channel-peer.
• Revisa Session Management para entender el alcance y las políticas de envío.

Habilitar Sandboxing

Ejecuta las sesiones de los agentes en contenedores Docker aislados:

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

Primero debes construir la imagen usando: scripts/sandbox-setup.sh. Tienes la guía completa en Sandboxing.

Configurar Heartbeat (comprobaciones periódicas)

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

• every: duración en formato string (30m, 2h). Usa 0m para desactivarlo.
• target: puede ser last, whatsapp, telegram, discord o none.

Configurar Cron jobs

{
  cron: {
    enabled: true,
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },
}

Mira los ejemplos de CLI en Cron jobs.

Configurar Webhooks (hooks)

Habilita endpoints HTTP en el Gateway:

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

Revisa la full reference para ver opciones de mapeo e integración con Gmail.

Configurar enrutamiento Multi-Agent

Ejecuta varios agentes aislados con espacios de trabajo y sesiones independientes:

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

Más información en Multi-Agent.

Dividir configuración en varios archivos ($include)

Usa $include para organizar configuraciones extensas:

~/.openclaw/openclaw.json

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

• Archivo único: reemplaza el objeto que lo contiene.
• Array de archivos: se fusionan profundamente en orden (el último gana).
• Rutas relativas: se resuelven respecto al archivo que incluye.
• Niveles: soporta hasta 10 niveles de profundidad.

Solución de problemas

• Error al cargar archivos incluidos: Verifica que las rutas en $include sean correctas respecto al archivo principal.
• El Sandbox no inicia: Asegúrate de haber ejecutado scripts/sandbox-setup.sh antes de habilitar el modo Docker.
• Menciones no detectadas: Comprueba que los mentionPatterns coincidan con el texto exacto o la regex que estás enviando.
• Fallo en modelos: Revisa que el formato sea provider/model y que tengas configurados los fallbacks en agents.defaults.model.fallbacks.

¿Necesitas ayuda con una configuración específica? Prueba el AI Setup Assistant.

Próximos pasos

• Session Management
• Sandboxing Guide
• Model Failover
• Multi-Agent Routing

Seguro te ha pasado: haces un pequeño ajuste en un archivo de configuración y tienes que detener el proceso, volver a ejecutarlo y esperar a que todo cargue de nuevo. Es una pérdida de tiempo que interrumpe tu ritmo de trabajo, especialmente cuando estás probando diferentes modelos o ajustando el comportamiento de tus agentes.

Lo ideal es que tus cambios se reflejen al instante. El Gateway permite precisamente esto, permitiéndote iterar rápido sin perder la conexión con tus servicios.

What You’ll Need

• Acceso al archivo de configuración en ~/.openclaw/openclaw.json.

Quick Start

El Gateway monitorea ~/.openclaw/openclaw.json y aplica los cambios automáticamente. Para la mayoría de los ajustes, no necesitas reiniciar el proceso manualmente.

Solo tienes que definir el objeto reload dentro de la configuración de tu Gateway. Te recomiendo usar el modo hybrid para obtener lo mejor de ambos mundos:

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

Reload modes

Dependiendo de cómo prefieras trabajar, puedes elegir entre estos cuatro modos:

Mode	Behavior
hybrid (default)	Aplica cambios seguros al instante. Reinicia automáticamente cuando detecta cambios críticos.
hot	Solo aplica cambios seguros en caliente. Si hace falta un reinicio, registra un aviso en los logs y tú lo gestionas.
restart	Reinicia el Gateway con cualquier cambio en la configuración, sea seguro o no.
off	Desactiva el monitoreo de archivos. Los cambios solo surten efecto en el siguiente reinicio manual.

Qué se aplica en caliente vs qué necesita reinicio

La mayoría de los campos en el archivo de configuración se aplican sin tiempo de inactividad. Si utilizas el modo hybrid, los cambios que requieren reinicio se gestionan solos.

Categoría	Fields	¿Requiere reinicio?
Channels	channels.*, web (WhatsApp) — canales internos y extensiones	No
Agent & models	agent, agents, models, routing	No
Automation	hooks, cron, agent.heartbeat	No
Sessions & messages	session, messages	No
Tools & media	tools, browser, skills, audio, talk	No
UI & misc	ui, logging, identity, bindings	No
Gateway server	gateway.* (port, bind, auth, tailscale, TLS, HTTP)	Yes
Infrastructure	discovery, canvasHost, plugins	Yes

Nota

gateway.reload y gateway.remote son excepciones: modificar estos campos no activa un reinicio automático.

Troubleshooting

• El Gateway se reinicia constantemente: Esto ocurre si estás en modo hybrid o restart y tu editor de texto guarda archivos temporalmente. Ajusta el valor de debounceMs a uno más alto (por ejemplo, 500 o 1000) para esperar a que terminen las operaciones de escritura.
• Los cambios en el puerto no se ven reflejados: Los cambios en gateway.* requieren un reinicio. Si estás en modo hot, revisa los logs para confirmar que el Gateway está esperando un reinicio manual.

¿Necesitas ayuda para configurar tu entorno? Prueba nuestro AI Setup Assistant.

What’s Next

• Configuración de canales
• Gestión de agentes y modelos
• Uso de Hooks y automatización
• Configuración de seguridad y TLS

Gestionar archivos de configuración manualmente es un dolor de cabeza, sobre todo cuando necesitas automatizar cambios mediante scripts o llamadas remotas. Es fácil romper algo o perder el rastro de las versiones actuales mientras intentas que todo funcione en sincronía.

Si quieres evitar editar archivos JSON a mano y prefieres que tu sistema se encargue de las actualizaciones, estas herramientas de RPC son lo que buscas.

Requisitos previos

• CLI de openclaw instalada.
• Un Gateway en ejecución.

Inicio rápido

Para actualizar tu configuración en menos de 5 minutos, sigue estos pasos:

1. Obtén el hash de tu configuración actual ejecutando openclaw gateway call config.get --params '{}'. Guarda el valor de payload.hash.
2. Elige entre config.patch para cambios pequeños o config.apply para un reemplazo total.
3. Ejecuta el comando correspondiente pasando el baseHash que obtuviste en el primer paso.

Config RPC (programmatic updates)

config.apply (full replace)

Este método valida y escribe la configuración completa, reiniciando el Gateway en un solo paso.

[!WARNING] config.apply reemplaza la configuración completa. Usa config.patch para actualizaciones parciales o openclaw config set para claves individuales.

Params:

• raw (string): Payload JSON5 para toda la configuración.
• baseHash (opcional): Hash de la configuración obtenido de config.get (obligatorio si ya existe una configuración).
• sessionKey (opcional): Clave de sesión para el ping de reactivación tras el reinicio.
• note (opcional): Nota para el centinela de reinicio.
• restartDelayMs (opcional): Retraso antes del reinicio (por defecto 2000).

openclaw gateway call config.get --params '{}'  # captura payload.hash
openclaw gateway call config.apply --params '{
  "raw": "{ agents: { defaults: { workspace: \"~/.openclaw/workspace\" } } }",
  "baseHash": "<hash>",
  "sessionKey": "agent:main:whatsapp:dm:+15555550123"
}'

config.patch (partial update)

Este método fusiona una actualización parcial con la configuración existente siguiendo la semántica de JSON merge patch:

• Los objetos se fusionan de forma recursiva.
• El valor null elimina una clave.
• Los arrays se reemplazan por completo.
• Las cadenas de texto se sobrescriben.

Params:

• raw (string): JSON5 con solo las claves que quieres cambiar.
• baseHash (obligatorio): Hash de la configuración obtenido de config.get.
• sessionKey, note, restartDelayMs: Mismos parámetros que en config.apply.

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

Solución de problemas

• Error de validación de hash: Si recibes un error relacionado con el hash, asegúrate de llamar primero a config.get. El Gateway usa este valor para evitar colisiones entre actualizaciones concurrentes.
• Configuración desaparecida: Si usaste config.apply y perdiste datos, es porque este método no fusiona cambios, sino que sobrescribe todo el sistema. Para cambios incrementales, usa siempre config.patch.

Si necesitas ayuda para configurar tus llamadas RPC, consulta al AI Setup Assistant.

Próximos pasos

• Configuración de Agents
• Gestión de Channels
• CLI Reference
• Gateway Architecture

---
title: Manejo de variables de entorno en OpenClaw
description: Aprende a configurar tus API keys y variables de entorno de forma segura y eficiente en OpenClaw.
---

¿Alguna vez has tenido problemas gestionando credenciales entre distintos entornos de desarrollo? Es frustrante lidiar con archivos de configuración que exponen datos sensibles o tener que exportar manualmente cada API key cada vez que abres una terminal nueva. Gestionar estas variables de forma limpia es fundamental para que tu flujo de trabajo no se detenga por errores de autenticación.

Para evitar estos problemas, OpenClaw ofrece un sistema flexible para cargar y sustituir variables de entorno sin complicaciones.

## Requisitos previos

- Un archivo de configuración de OpenClaw (JSON5).
- Acceso al proceso padre o a la terminal donde ejecutas OpenClaw.

## Inicio rápido

OpenClaw busca variables de entorno automáticamente en el proceso padre y en dos ubicaciones específicas:

1. El archivo `.env` en tu directorio de trabajo actual.
2. El archivo `~/.openclaw/.env` como respaldo global si el anterior no existe.

Es importante que sepas que estos archivos no sobrescriben las variables que ya existan en tu sistema. Si prefieres definir variables directamente en tu configuración, usa el siguiente formato:

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

Importación desde el Shell (opcional)

Si activas esta opción y faltan claves esperadas, OpenClaw ejecuta tu shell de inicio e importa únicamente las claves que no están presentes:

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

También puedes usar la variable de entorno equivalente: OPENCLAW_LOAD_SHELL_ENV=1.

Sustitución de variables en la configuración

Puedes referenciar variables de entorno en cualquier valor de cadena dentro de tu configuración usando ${VAR_NAME}:

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

Sigue estas reglas para evitar errores:

• Solo se reconocen nombres en mayúsculas: [A-Z_][A-Z0-9_]*.
• Si una variable falta o está vacía, OpenClaw lanzará un error al cargar.
• Usa $${VAR} si necesitas que el texto aparezca literal (escape).
• Funciona dentro de archivos $include y permite sustitución inline: "${BASE}/v1" se convierte en "https://api.example.com/v1".

Solución de problemas

• Error al cargar la configuración: Verifica que todas las variables referenciadas con ${VAR_NAME} estén definidas en tu sistema o archivos .env. OpenClaw detendrá la ejecución si encuentra una variable vacía.
• Variables que no se actualizan: Recuerda que los archivos .env locales y globales no sobrescriben las variables que ya están configuradas en tu proceso actual. Limpia tu entorno si necesitas usar los valores del archivo.

Consulta Environment para ver todos los detalles sobre la precedencia y las fuentes de datos.

Full reference

Para revisar cada campo en detalle, consulta la Configuration Reference.

---

¿Necesitas ayuda con tu configuración? Prueba nuestro AI Setup Assistant.

What’s Next:

• Configuration Examples
• Configuration Reference
• Doctor