Ejemplos de configuración para tu Gateway

Configurar tu Gateway no debería ser un proceso de prueba y error. Es frustrante dedicar tiempo a escribir archivos de configuración solo para descubrir que los nombres de los campos han cambiado o que la estructura que estás siguiendo ya no es compatible con la versión actual de tu herramienta.

Esa pérdida de tiempo ocurre cuando la documentación y el código no van de la mano. Lo que necesitas es claridad y ejemplos que reflejen exactamente lo que el sistema espera hoy, permitiéndote avanzar en tu proyecto sin detenerte por errores de validación innecesarios.

What You’ll Need

Acceso al esquema de configuración actual.
Referencia de campos específicos disponible en Configuration.

Quick Start

Para configurar tu Gateway en pocos minutos, sigue estos pasos utilizando el esquema vigente. Esto asegura que tu API y tu Gateway se comuniquen sin contratiempos.

Revisa los ejemplos que cumplen con el esquema de configuración actual.
Si tienes dudas sobre un parámetro particular, consulta las notas por campo en la documentación de Configuration.

Troubleshooting

Si encuentras problemas al aplicar la configuración, revisa estos puntos basados en la documentación oficial:

Error de validación de esquema: Asegúrate de que los campos coincidan con la versión actual del esquema.
Valores no reconocidos: Verifica las notas por campo en la referencia exhaustiva para confirmar los valores permitidos.

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

What’s Next

Configuration

---
title: Inicio rápido
description: Configura tu agente de OpenClaw y conéctalo a WhatsApp en pocos minutos.
---

¿Alguna vez has intentado configurar un bot y has terminado rindiéndote por la complejidad de los archivos? Es normal sentirse frustrado cuando solo quieres ver a tu IA respondiendo mensajes y te encuentras con una montaña de configuración innecesaria.

OpenClaw elimina esa fricción para que puedas empezar a interactuar con tu agente de inmediato, sin perderte en procesos eternos.

## Requisitos previos

- Un directorio para el `workspace` en `~/.openclaw/workspace`.
- Un número de teléfono activo para usar en WhatsApp.

## Inicio rápido

Sigue estos pasos para tener tu agente listo en menos de 5 minutos.

### 1. El mínimo absoluto

Crea el archivo de configuración en `~/.openclaw/openclaw.json`. Si buscas la ruta más rápida para que todo funcione, usa este código:

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

Guarda el archivo y ya puedes enviar un DM al bot desde el número que configuraste.

2. Starter recomendado

Si quieres una configuración más completa desde el principio, te sugiero esta opción. Define una identidad clara para tu agente y especifica el modelo de Anthropic.

{
  identity: {
    name: "Clawd",
    theme: "helpful assistant",
    emoji: "🦞",
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "anthropic/claude-sonnet-4-5" },
  },
  channels: {
    whatsapp: {
      allowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },
  },
}

Esta configuración incluye requireMention: true para los grupos, lo que evita que el bot responda a cada mensaje a menos que lo menciones específicamente.

¿Necesitas ayuda para ajustar tu configuración? Consulta nuestro AI Setup Assistant.

Próximos pasos

Configuración de canales
Personalización de la identidad del agente

Configurar un agente que funcione en varios canales a la vez suele ser un caos. Terminas con archivos de configuración dispersos y parámetros que no recuerdas para qué sirven. Para evitar ese desorden, lo mejor es tener una referencia clara de todas las opciones disponibles en un solo lugar.

Aquí tienes un ejemplo exhaustivo que cubre desde la autenticación hasta el manejo de sandboxes y webhooks.

### What You'll Need

- API keys de proveedores compatibles (OpenRouter, Anthropic, OpenAI, Google Gemini).
- Tokens de acceso para bots de Telegram, Discord o Slack.
- Node.js instalado para la gestión de skills.
- Docker instalado si planeas ejecutar herramientas en entornos aislados.

### Quick Start

1. Crea un archivo de configuración con extensión `.json5`. Esto te permite usar comentarios y comas finales para que el archivo sea más legible.
2. Define tus variables de entorno base y las llaves de API en la sección `env`.
3. Configura tus perfiles de autenticación en `auth.profiles` para gestionar diferentes cuentas.
4. Activa los canales que necesites (WhatsApp, Telegram, etc.) dentro del objeto `channels`.

```json
{
  // Environment + shell
  env: {
    OPENROUTER_API_KEY: "sk-or-...",
    vars: {
      GROQ_API_KEY: "gsk-...",
    },
    shellEnv: {
      enabled: true,
      timeoutMs: 15000,
    },
  },

  // Auth profile metadata (secrets live in auth-profiles.json)
  auth: {
    profiles: {
      "anthropic:me@example.com": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:work": { provider: "anthropic", mode: "api_key" },
      "openai:default": { provider: "openai", mode: "api_key" },
      "openai-codex:default": { provider: "openai-codex", mode: "oauth" },
    },
    order: {
      anthropic: ["anthropic:me@example.com", "anthropic:work"],
      openai: ["openai:default"],
      "openai-codex": ["openai-codex:default"],
    },
  },

  // Identity
  identity: {
    name: "Samantha",
    theme: "helpful sloth",
    emoji: "🦥",
  },

  // Logging
  logging: {
    level: "info",
    file: "/tmp/openclaw/openclaw.log",
    consoleLevel: "info",
    consoleStyle: "pretty",
    redactSensitive: "tools",
  },

  // Message formatting
  messages: {
    messagePrefix: "[openclaw]",
    responsePrefix: ">",
    ackReaction: "👀",
    ackReactionScope: "group-mentions",
  },

  // Routing + queue
  routing: {
    groupChat: {
      mentionPatterns: ["@openclaw", "openclaw"],
      historyLimit: 50,
    },
    queue: {
      mode: "collect",
      debounceMs: 1000,
      cap: 20,
      drop: "summarize",
      byChannel: {
        whatsapp: "collect",
        telegram: "collect",
        discord: "collect",
        slack: "collect",
        signal: "collect",
        imessage: "collect",
        webchat: "collect",
      },
    },
  },

  // Tooling
  tools: {
    media: {
      audio: {
        enabled: true,
        maxBytes: 20971520,
        models: [
          { provider: "openai", model: "gpt-4o-mini-transcribe" },
          // Optional CLI fallback (Whisper binary):
          // { type: "cli", command: "whisper", args: ["--model", "base", "{{MediaPath}}"] }
        ],
        timeoutSeconds: 120,
      },
      video: {
        enabled: true,
        maxBytes: 52428800,
        models: [{ provider: "google", model: "gemini-3-flash-preview" }],
      },
    },
  },

  // Session behavior
  session: {
    scope: "per-sender",
    reset: {
      mode: "daily",
      atHour: 4,
      idleMinutes: 60,
    },
    resetByChannel: {
      discord: { mode: "idle", idleMinutes: 10080 },
    },
    resetTriggers: ["/new", "/reset"],
    store: "~/.openclaw/agents/default/sessions/sessions.json",
    maintenance: {
      mode: "warn",
      pruneAfter: "30d",
      maxEntries: 500,
      rotateBytes: "10mb",
    },
    typingIntervalSeconds: 5,
    sendPolicy: {
      default: "allow",
      rules: [{ action: "deny", match: { channel: "discord", chatType: "group" } }],
    },
  },

  // Channels
  channels: {
    whatsapp: {
      dmPolicy: "pairing",
      allowFrom: ["+15555550123"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["+15555550123"],
      groups: { "*": { requireMention: true } },
    },

    telegram: {
      enabled: true,
      botToken: "YOUR_TELEGRAM_BOT_TOKEN",
      allowFrom: ["123456789"],
      groupPolicy: "allowlist",
      groupAllowFrom: ["123456789"],
      groups: { "*": { requireMention: true } },
    },

    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["steipete"] },
      guilds: {
        "123456789012345678": {
          slug: "friends-of-openclaw",
          requireMention: false,
          channels: {
            general: { allow: true },
            help: { allow: true, requireMention: true },
          },
        },
      },
    },

    slack: {
      enabled: true,
      botToken: "xoxb-REPLACE_ME",
      appToken: "xapp-REPLACE_ME",
      channels: {
        "#general": { allow: true, requireMention: true },
      },
      dm: { enabled: true, allowFrom: ["U123"] },
      slashCommand: {
        enabled: true,
        name: "openclaw",
        sessionPrefix: "slack:slash",
        ephemeral: true,
      },
    },
  },

  // Agent runtime
  agents: {
    defaults: {
      workspace: "~/.openclaw/workspace",
      userTimezone: "America/Chicago",
      model: {
        primary: "anthropic/claude-sonnet-4-5",
        fallbacks: ["anthropic/claude-opus-4-6", "openai/gpt-5.2"],
      },
      imageModel: {
        primary: "openrouter/anthropic/claude-sonnet-4-5",
      },
      models: {
        "anthropic/claude-opus-4-6": { alias: "opus" },
        "anthropic/claude-sonnet-4-5": { alias: "sonnet" },
        "openai/gpt-5.2": { alias: "gpt" },
      },
      thinkingDefault: "low",
      verboseDefault: "off",
      elevatedDefault: "on",
      blockStreamingDefault: "off",
      blockStreamingBreak: "text_end",
      blockStreamingChunk: {
        minChars: 800,
        maxChars: 1200,
        breakPreference: "paragraph",
      },
      blockStreamingCoalesce: {
        idleMs: 1000,
      },
      humanDelay: {
        mode: "natural",
      },
      timeoutSeconds: 600,
      mediaMaxMb: 5,
      typingIntervalSeconds: 5,
      maxConcurrent: 3,
      heartbeat: {
        every: "30m",
        model: "anthropic/claude-sonnet-4-5",
        target: "last",
        to: "+15555550123",
        prompt: "HEARTBEAT",
        ackMaxChars: 300,
      },
      memorySearch: {
        provider: "gemini",
        model: "gemini-embedding-001",
        remote: {
          apiKey: "${GEMINI_API_KEY}",
        },
        extraPaths: ["../team-docs", "/srv/shared-notes"],
      },
      sandbox: {
        mode: "non-main",
        perSession: true,
        workspaceRoot: "~/.openclaw/sandboxes",
        docker: {
          image: "openclaw-sandbox:bookworm-slim",
          workdir: "/workspace",
          readOnlyRoot: true,
          tmpfs: ["/tmp", "/var/tmp", "/run"],
          network: "none",
          user: "1000:1000",
        },
        browser: {
          enabled: false,
        },
      },
    },
  },

  tools: {
    allow: ["exec", "process", "read", "write", "edit", "apply_patch"],
    deny: ["browser", "canvas"],
    exec: {
      backgroundMs: 10000,
      timeoutSec: 1800,
      cleanupMs: 1800000,
    },
    elevated: {
      enabled: true,
      allowFrom: {
        whatsapp: ["+15555550123"],
        telegram: ["123456789"],
        discord: ["steipete"],
        slack: ["U123"],
        signal: ["+15555550123"],
        imessage: ["user@example.com"],
        webchat: ["session:demo"],
      },
    },
  },

  // Custom model providers
  models: {
    mode: "merge",
    providers: {
      "custom-proxy": {
        baseUrl: "http://localhost:4000/v1",
        apiKey: "LITELLM_KEY",
        api: "openai-responses",
        authHeader: true,
        headers: { "X-Proxy-Region": "us-west" },
        models: [
          {
            id: "llama-3.1-8b",
            name: "Llama 3.1 8B",
            api: "openai-responses",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 128000,
            maxTokens: 32000,
          },
        ],
      },
    },
  },

  // Cron jobs
  cron: {
    enabled: true,
    store: "~/.openclaw/cron/cron.json",
    maxConcurrentRuns: 2,
    sessionRetention: "24h",
  },

  // Webhooks
  hooks: {
    enabled: true,
    path: "/hooks",
    token: "shared-secret",
    presets: ["gmail"],
    transformsDir: "~/.openclaw/hooks",
    mappings: [
      {
        id: "gmail-hook",
        match: { path: "gmail" },
        action: "agent",
        wakeMode: "now",
        name: "Gmail",
        sessionKey: "hook:gmail:{{messages[0].id}}",
        messageTemplate: "From: {{messages[0].from}}\nSubject: {{messages[0].subject}}",
        textTemplate: "{{messages[0].snippet}}",
        deliver: true,
        channel: "last",
        to: "+15555550123",
        thinking: "low",
        timeoutSeconds: 300,
        transform: {
          module: "./transforms/gmail.js",
          export: "transformGmail",
        },
      },
    ],
    gmail: {
      account: "openclaw@gmail.com",
      label: "INBOX",
      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" },
    },
  },

  // Gateway + networking
  gateway: {
    mode: "local",
    port: 18789,
    bind: "loopback",
    controlUi: { enabled: true, basePath: "/openclaw" },
    auth: {
      mode: "token",
      token: "gateway-token",
      allowTailscale: true,
    },
    tailscale: { mode: "serve", resetOnExit: false },
    remote: { url: "ws://gateway.tailnet:18789", token: "remote-token" },
    reload: { mode: "hybrid", debounceMs: 300 },
  },

  skills: {
    allowBundled: ["gemini", "peekaboo"],
    load: {
      extraDirs: ["~/Projects/agent-scripts/skills"],
    },
    install: {
      preferBrew: true,
      nodeManager: "npm",
    },
    entries: {
      "nano-banana-pro": {
        enabled: true,
        apiKey: "GEMINI_KEY_HERE",
        env: { GEMINI_API_KEY: "GEMINI_KEY_HERE" },
      },
      peekaboo: { enabled: true },
    },
  },
}

Troubleshooting

Error en archivos multimedia: Si el audio o video no se procesan, revisa que el archivo no supere el límite de maxBytes definido en tools.media. Por defecto, el audio tiene un límite de 20MB.
Gateway inaccesible: Verifica que el port 18789 esté libre en tu máquina local y que el token de autenticación sea el correcto si estás usando el modo token.
Timeouts en ejecución: Si los comandos de shell fallan, intenta aumentar el timeoutMs en la sección env.shellEnv.
Fallo en sandboxes: Asegúrate de que la imagen de Docker openclaw-sandbox:bookworm-slim esté disponible localmente si el modo está configurado como non-main.

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

What’s Next

Configurar un agente para que funcione en varios canales a la vez o gestione fallbacks de modelos puede ser un dolor de cabeza. A veces terminas con archivos de configuración enormes y sesiones de usuario mezcladas que arruinan la experiencia.

Si buscas una forma clara de organizar tu entorno sin perder el control de la seguridad o la disponibilidad de los modelos, estos patrones te ayudarán a estandarizar tu setup.

Requisitos previos

Para implementar estos patrones, asegúrate de tener:

Tokens de acceso para tus canales (Telegram, Discord, Slack)
API keys de los proveedores (Anthropic, MiniMax) o un servidor local (LM Studio)
Una ruta definida para tu workspace
Node.js configurado para ejecutar el proceso

Inicio rápido

La forma más rápida de tener un agente activo en varios servicios es el patrón multi-plataforma. Solo necesitas definir los canales y quién tiene permiso para interactuar en ellos.

{
  agent: { workspace: "~/.openclaw/workspace" },
  channels: {
    whatsapp: { allowFrom: ["+15555550123"] },
    telegram: {
      enabled: true,
      botToken: "YOUR_TOKEN",
      allowFrom: ["123456789"],
    },
    discord: {
      enabled: true,
      token: "YOUR_TOKEN",
      dm: { allowFrom: ["yourname"] },
    },
  },
}

Patrones recomendados

Modo DM seguro (inbox compartido / DMs multi-usuario)

Si más de una persona puede enviar mensajes directos a tu bot, activa el secure DM mode. Esto evita que diferentes usuarios compartan el mismo contexto por defecto, lo cual es vital para la privacidad.

{
  // Modo DM seguro (recomendado para agentes multi-usuario o DMs sensibles)
  session: { dmScope: "per-channel-peer" },

  channels: {
    // Ejemplo: Bandeja de entrada multi-usuario en WhatsApp
    whatsapp: {
      dmPolicy: "allowlist",
      allowFrom: ["+15555550123", "+15555550124"],
    },

    // Ejemplo: Bandeja de entrada multi-usuario en Discord
    discord: {
      enabled: true,
      token: "YOUR_DISCORD_BOT_TOKEN",
      dm: { enabled: true, allowFrom: ["alice", "bob"] },
    },
  },
}

OAuth con failover a API key

Este patrón es ideal si usas una suscripción personal pero quieres que el agente siga funcionando con una API key si el OAuth falla o alcanza sus límites.

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "me@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-sonnet-4-5",
      fallbacks: ["anthropic/claude-opus-4-6"],
    },
  },
}

Suscripción Anthropic + API key y MiniMax como fallback

Si necesitas redundancia total, puedes saltar entre proveedores. Aquí configuramos Anthropic como prioridad y MiniMax como respaldo mediante un Gateway compatible.

{
  auth: {
    profiles: {
      "anthropic:subscription": {
        provider: "anthropic",
        mode: "oauth",
        email: "user@example.com",
      },
      "anthropic:api": {
        provider: "anthropic",
        mode: "api_key",
      },
    },
    order: {
      anthropic: ["anthropic:subscription", "anthropic:api"],
    },
  },
  models: {
    providers: {
      minimax: {
        baseUrl: "https://api.minimax.io/anthropic",
        api: "anthropic-messages",
        apiKey: "${MINIMAX_API_KEY}",
      },
    },
  },
  agent: {
    workspace: "~/.openclaw/workspace",
    model: {
      primary: "anthropic/claude-opus-4-6",
      fallbacks: ["minimax/MiniMax-M2.1"],
    },
  },
}

Bot de trabajo (acceso restringido)

Para entornos profesionales, lo mejor es limitar el acceso a canales específicos de Slack y desactivar permisos elevados para mayor seguridad.

{
  identity: {
    name: "WorkBot",
    theme: "professional assistant",
  },
  agent: {
    workspace: "~/work-openclaw",
    elevated: { enabled: false },
  },
  channels: {
    slack: {
      enabled: true,
      botToken: "xoxb-...",
      channels: {
        "#engineering": { allow: true, requireMention: true },
        "#general": { allow: true, requireMention: true },
      },
    },
  },
}

Uso exclusivo de modelos locales

Si prefieres la privacidad total o el desarrollo offline, puedes conectar con LM Studio usando este patrón de configuración.

{
  agent: {
    workspace: "~/.openclaw/workspace",
    model: { primary: "lmstudio/minimax-m2.1-gs32" },
  },
  models: {
    mode: "merge",
    providers: {
      lmstudio: {
        baseUrl: "http://127.0.0.1:1234/v1",
        apiKey: "lmstudio",
        api: "openai-responses",
        models: [
          {
            id: "minimax-m2.1-gs32",
            name: "MiniMax M2.1 GS32",
            reasoning: false,
            input: ["text"],
            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
            contextWindow: 196608,
            maxTokens: 8192,
          },
        ],
      },
    },
  },
}

Solución de problemas

Contextos mezclados en DMs: Si notas que el agente confunde conversaciones entre distintos usuarios, asegúrate de que dmScope esté configurado como per-channel-peer.
Fallo en autenticación Anthropic: Revisa el order en tu configuración de auth. El agente intentará usar los perfiles en el orden que definas en la lista.

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

Próximos pasos

Seguro que te ha pasado: pasas un buen rato configurando una integración y, al probarla, algo falla por un pequeño detalle en el formato de un ID o una regla de permisos. Configurar canales de comunicación requiere precisión para evitar bloqueos innecesarios en el flujo de datos.

Aquí tienes los puntos clave que debes revisar para que tu configuración funcione a la primera.

What You’ll Need

Acceso a tu archivo de configuración del Gateway.
Documentación técnica de tu proveedor (para validar formatos de identidad).

Quick Start

Si quieres habilitar una política de mensajes abiertos, debes ser explícito con los permisos. Sigue esta regla técnica:

Si configuras "dmPolicy": "open", es obligatorio que la lista de allowFrom incluya el comodín "*":

{
  "dmPolicy": "open",
  "allowFrom": ["*"]
}

Puedes añadir estas secciones opcionales más adelante para extender las capacidades de tu Gateway:

web
browser
ui
discovery
canvasHost
talk
signal
imessage

Troubleshooting

Los mensajes no se envían o el Provider ID falla Los Provider IDs no son universales; cambian drásticamente entre plataformas. Algunos proveedores usan números de teléfono, otros usan user IDs o channel IDs específicos. Si tienes errores de autenticación o envío, consulta la documentación de tu proveedor para confirmar el formato exacto que requiere su API.

Si necesitas ayuda con un error específico, consulta el AI Setup Assistant.

What’s Next

OpenClaw Expert

Sigues atascado?

Si esta pagina no resolvio tu caso, pregunta a OpenClaw Expert para pasos concretos.