Aplica a OpenClaw v2026.2 | Este artículo es adecuado para usuarios que han completado la configuración básica y quieren entender la arquitectura en profundidad. Se recomienda completar los 3 primeros tutoriales.

TL;DR: El Gateway es el plano de control central de OpenClaw. Session es el contenedor de contexto de conversación (main/channel/group), Message Router decide el enrutamiento de mensajes, Tool Registry gestiona permisos de herramientas, Skills son extensiones de capacidades empaquetadas. Endpoint WebSocket ws://127.0.0.1:18789/ws, comandos frecuentes openclaw gateway/doctor/config. Entender estos conceptos es la base para la configuración avanzada.

Visión general de la arquitectura

Arquitectura general

flowchart TB
    subgraph Clients["Capa de clientes"]
        WA[WhatsApp]
        TG[Telegram]
        DC[Discord]
        SL[Slack]
        WC[WebChat]
        CLI[CLI]
        MAC[App macOS]
        IOS[Nodo iOS]
        AND[Nodo Android]
    end
    
    subgraph Gateway["Capa Gateway"]
        WS[Servidor WebSocket]
        HTTP[Servidor HTTP]
        MR[Enrutador de Mensajes]
        SM[Gestor de Sesiones]
        TR[Registro de Herramientas]
        EM[Gestor de Eventos]
        CFG[Almacén de Configuración]
    end
    
    subgraph Agent["Capa Agent"]
        PI[Pi Agent]
        PROMPT[Motor de Prompts]
        TOOLS[Ejecutor de Herramientas]
        SKILLS[Gestor de Skills]
    end
    
    subgraph External["Servicios externos"]
        FS[Sistema de archivos]
        BR[Navegador]
        API[Servicios API]
        DB[Base de datos]
        CAL[Programador Cron]
    end
    
    Clients --> WS
    Clients --> HTTP
    WS --> MR
    HTTP --> MR
    MR --> SM
    SM --> PI
    PI --> PROMPT
    PI --> TOOLS
    PI --> SKILLS
    TOOLS --> TR
    TR --> External
    EM --> MR
    CFG --> SM
    CFG --> TR

Responsabilidades de los componentes

Flujo de datos

sequenceDiagram
    participant U as Usuario
    participant C as Canal
    participant WS as WebSocket
    participant MR as Router
    participant SM as Sesión
    participant A as Agent
    participant T as Herramientas
    
    U->>C: Envía mensaje
    C->>WS: Envía mensaje
    WS->>MR: Solicitud de enrutamiento
    MR->>SM: Buscar/crear sesión
    SM-->>MR: Devolver sesión
    MR->>A: Entregar mensaje
    A->>A: Procesar mensaje
    A->>T: Invocar herramienta (opcional)
    T-->>A: Devolver resultado
    A-->>MR: Generar respuesta
    MR->>WS: Enviar respuesta
    WS->>C: Enviar respuesta
    C-->>U: Mostrar mensaje

Modelo de sesiones (Session)

¿Qué es una Session?

Session es uno de los conceptos más centrales de OpenClaw. Cada Session representa un contexto de conversación independiente que contiene:

Tipos de Session

{
  "sessions": {
    "main": {
      "type": "main",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "high",
      "channel": null,
      "created": "2026-02-26T10:00:00Z"
    },
    "telegram:user:123456789": {
      "type": "channel",
      "model": "anthropic/claude-opus-4-6",
      "thinkingLevel": "normal",
      "channel": "telegram",
      "sender": "123456789",
      "created": "2026-02-26T10:05:00Z"
    },
    "telegram:group:-100123456789": {
      "type": "group",
      "model": "anthropic/claude-sonnet-4",
      "thinkingLevel": "minimal",
      "channel": "telegram",
      "groupId": "-100123456789",
      "created": "2026-02-26T10:10:00Z"
    }
  }
}

Ciclo de vida de la Session

stateDiagram-v2
    [*] --> Created: Llega un mensaje
    Created --> Active: Primera respuesta
    Active --> Active: Interacción de mensajes
    Active --> Idle: Sin actividad
    Idle --> Active: Nuevo mensaje
    Idle --> Compacted: Compresión automática
    Compacted --> Active: Continuar conversación
    Active --> Reset: Comando /reset
    Reset --> Created: Reiniciar
    Active --> Pruned: Limpieza de sesión
    Idle --> Pruned: Limpieza por timeout
    Pruned --> [*]

Comandos de Session

Envía los siguientes comandos en el chat para gestionar sesiones:

Configuración de Session

{
  "sessionPruning": {
    "enabled": true,
    "maxAge": 86400000,
    "maxSize": 100,
    "pruneOnStartup": true
  },
  "sessionCompression": {
    "enabled": true,
    "threshold": 50000,
    "targetRatio": 0.3
  }
}

Enrutador de mensajes (Message Router)

Reglas de enrutamiento

El Message Router se encarga de enrutar los mensajes recibidos a la Session correcta:

flowchart TB
    MSG[Mensaje llega] --> CH{Tipo de canal?}
    CH -->|Chat privado| DM[Extraer ID del remitente]
    CH -->|Chat grupal| GRP[Extraer ID del grupo]
    CH -->|WebChat/CLI| MAIN[Usar sesión main]
    
    DM --> SID[Session: channel:user:id]
    GRP --> GID[Session: channel:group:id]
    
    SID --> EXISTS{¿Sesión existe?}
    GID --> EXISTS
    
    EXISTS -->|Sí| LOAD[Cargar sesión]
    EXISTS -->|No| CREATE[Crear nueva sesión]
    
    CREATE --> LOAD
    LOAD --> AGENT[Entregar al Agent]

Configuración de enrutamiento

{
  "messageRouting": {
    "defaultSession": "main",
    "channelMapping": {
      "telegram": {
        "userPrefix": "telegram:user",
        "groupPrefix": "telegram:group"
      },
      "whatsapp": {
        "userPrefix": "whatsapp:user",
        "groupPrefix": "whatsapp:group"
      }
    },
    "groupActivation": {
      "mode": "mention",
      "mentionPatterns": ["@bot", "/bot"]
    }
  }
}

Estrategias de activación de grupos

{
  "channels": {
    "telegram": {
      "groups": {
        "*": {
          "requireMention": true
        },
        "-100WORKGROUP": {
          "requireMention": false,
          "activationMode": "always"
        }
      }
    }
  }
}

Registro de herramientas (Tool Registry)

Herramientas integradas

OpenClaw incluye un rico conjunto de herramientas integradas:

Control de permisos de herramientas

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "off",
        "allowlist": ["read", "write", "bash", "web_search"],
        "denylist": []
      }
    }
  }
}

Configuración detallada del sandbox

{
  "agents": {
    "defaults": {
      "sandbox": {
        "mode": "non-main",
        "allowlist": [
          "read",
          "write",
          "edit",
          "bash",
          "web_search",
          "sessions_list",
          "sessions_history"
        ],
        "denylist": [
          "browser",
          "canvas",
          "camera",
          "screen_record"
        ]
      }
    }
  }
}

Sistema de Skills

Arquitectura de Skills

flowchart LR
    subgraph Skills["Directorio de Skills"]
        S1[gmail/SKILL.md]
        S2[calendar/SKILL.md]
        S3[home-assistant/SKILL.md]
    end
    
    subgraph Manager["Gestor de Skills"]
        DISC[Descubrimiento]
        LOAD[Carga]
        EXEC[Ejecución]
    end
    
    subgraph Agent["Agent"]
        PROMPT[Inyectar Prompt]
        TOOLS[Registrar herramientas]
        RES[Devolver resultados]
    end
    
    Skills --> DISC
    DISC --> LOAD
    LOAD --> PROMPT
    LOAD --> TOOLS
    PROMPT --> Agent
    TOOLS --> Agent
    Agent --> EXEC
    EXEC --> RES

Estructura del directorio de Skills

~/.openclaw/workspace/skills/
├── gmail/
│   ├── SKILL.md          # Definición del skill
│   ├── package.json      # Dependencias (opcional)
│   └── src/
│       └── index.js      # Implementación (opcional)
├── calendar/
│   └── SKILL.md
└── my-custom-skill/
    └── SKILL.md

Estructura de SKILL.md

# Gmail Skill

## Description
Send and read Gmail messages through OpenClaw.

## Triggers
- email
- gmail
- mail
- send email
- read email

## Instructions
When the user wants to send an email:
1. Ask for recipient, subject, and body
2. Use the gmail_send tool
3. Confirm the email was sent

When the user wants to check emails:
1. Use the gmail_list tool
2. Summarize the results

## Tools
- gmail_list: List recent emails
- gmail_send: Send an email
- gmail_read: Read a specific email

## Examples
User: "Check my email"
Action: Use gmail_list tool

User: "Send an email to [email protected]"
Action: Ask for subject and body, then use gmail_send

Métodos de instalación de Skills

# Instalar desde ClawHub
openclaw skill install gmail

# Instalar desde GitHub
openclaw skill install github:user/repo/skill-name

# Instalación manual
git clone https://github.com/user/skill-repo.git ~/.openclaw/workspace/skills/skill-name

Configuración de Skills

{
  "skills": {
    "bundled": true,
    "managed": true,
    "workspace": true,
    "installGating": true
  }
}

Protocolo WebSocket

Endpoint de conexión

ws://127.0.0.1:18789/ws

Formato de mensajes

{
  "type": "message_type",
  "id": "unique_message_id",
  "data": {
    // Contenido del mensaje
  }
}

Tipos de mensajes del cliente

Tipos de mensajes del servidor

Ejemplo: Enviar mensaje

// Conectar WebSocket
const ws = new WebSocket('ws://127.0.0.1:18789/ws');

// Enviar mensaje
ws.send(JSON.stringify({
  type: 'agent.send',
  id: 'msg-001',
  data: {
    session: 'main',
    message: 'Hola, preséntate por favor'
  }
}));

// Recibir respuesta
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
  
  // Salida ejemplo:
  // {
  //   type: 'agent.response',
  //   id: 'msg-001',
  //   data: {
  //     content: '¡Hola! Soy tu asistente OpenClaw...',
  //     session: 'main'
  //   }
  // }
};

Sistema de eventos (Event System)

Eventos integrados

Configuración de Webhooks

{
  "webhooks": [
    {
      "url": "https://your-server.com/webhook/openclaw",
      "events": ["message.received", "tool.invoked"],
      "secret": "your_webhook_secret",
      "headers": {
        "X-Custom-Header": "value"
      }
    }
  ]
}

Payload del Webhook

{
  "event": "message.received",
  "timestamp": "2026-02-26T10:30:00Z",
  "data": {
    "channel": "telegram",
    "sender": "123456789",
    "session": "telegram:user:123456789",
    "message": "Hola",
    "metadata": {
      "messageId": "msg_abc123",
      "timestamp": "2026-02-26T10:30:00Z"
    }
  },
  "signature": "sha256=..."
}

Tareas programadas Cron

Ejemplo de configuración

{
  "cron": [
    {
      "id": "daily-briefing",
      "schedule": "0 9 * * *",
      "session": "main",
      "message": "Por favor dame mi agenda de hoy",
      "enabled": true
    },
    {
      "id": "weekly-summary",
      "schedule": "0 18 * * 5",
      "session": "main",
      "message": "Genera un resumen semanal del trabajo",
      "enabled": true
    }
  ]
}

Expresión Cron

┌───────────── minuto (0 - 59)
│ ┌───────────── hora (0 - 23)
│ │ ┌───────────── día del mes (1 - 31)
│ │ │ ┌───────────── mes (1 - 12)
│ │ │ │ ┌───────────── día de la semana (0 - 6, 0 = domingo)
│ │ │ │ │
* * * * *

Ejemplos comunes

Jerarquía y prioridad de configuración

Orden de prioridad

Parámetros CLI > Variables de entorno > Archivo de configuración > Valores por defecto

Fuentes de configuración

Ejemplo de fusión de configuración

// ~/.openclaw/openclaw.json
{
  "agent": {
    "model": "anthropic/claude-opus-4-6"
  }
}

# Variable de entorno sobrescribe
export OPENCLAW_AGENT_MODEL="anthropic/claude-sonnet-4"

# Parámetro CLI sobrescribe (máxima prioridad)
openclaw gateway --model "anthropic/claude-opus-4"

Actualización en caliente de configuración

# Actualizar configuración (sin reiniciar)
openclaw config set agent.model "anthropic/claude-sonnet-4"

# Recargar archivo de configuración
openclaw config reload

# Verificar configuración
openclaw config get agent.model

Referencia rápida de comandos comunes

Gestión del Gateway

# Iniciar Gateway
openclaw gateway

# Especificar puerto
openclaw gateway --port 18790

# Ejecución en segundo plano
openclaw gateway --daemon

# Logs detallados
openclaw gateway --verbose

# Health check
openclaw health

Gestión de sesiones

# Listar todas las sesiones
openclaw session list

# Ver detalles de una sesión
openclaw session show main
openclaw session show telegram:user:123456789

# Reiniciar sesión
openclaw session reset main

# Eliminar sesión
openclaw session delete telegram:user:123456789

Gestión de configuración

# Ver configuración
openclaw config get agent.model
openclaw config get channels.telegram.botToken

# Establecer configuración
openclaw config set agent.thinkingLevel high

# Listar toda la configuración
openclaw config list

# Validar configuración
openclaw config validate

Herramientas de diagnóstico

# Diagnóstico completo
openclaw doctor

# Verificar elemento específico
openclaw doctor --check gateway
openclaw doctor --check config
openclaw doctor --check channels

# Ver logs
openclaw logs
openclaw logs --follow
openclaw logs --level error

Resolución de problemas

Gateway no puede iniciarse

# Verificar puerto ocupado
lsof -i :18789
netstat -tlnp | grep 18789

# Verificar sintaxis de configuración
openclaw config validate

# Ver error detallado
openclaw gateway --verbose 2>&1 | tee gateway.log

Sesión perdida

# Verificar directorio de sesiones
ls -la ~/.openclaw/sessions/

# Verificar configuración de limpieza
openclaw config get sessionPruning

# Deshabilitar limpieza automática
openclaw config set sessionPruning.enabled false

Fallo en invocación de herramientas

# Verificar configuración de sandbox
openclaw config get agents.defaults.sandbox

# Deshabilitar sandbox temporalmente
openclaw config set agents.defaults.sandbox.mode off

# Ver logs de herramientas
openclaw logs --filter tool

Fallo de conexión WebSocket

# Verificar estado del Gateway
curl http://127.0.0.1:18789/health

# Verificar endpoint WebSocket
wscat -c ws://127.0.0.1:18789/ws

# Verificar firewall
sudo ufw status
sudo iptables -L -n | grep 18789

Resumen

Entender los conceptos centrales del Gateway es clave para dominar OpenClaw:

• Session: Contenedor de contexto de conversación, soporta aislamiento por tipo
• Message Router: Núcleo del enrutamiento de mensajes, decide el destino de los mensajes
• Tool Registry: Centro de registro de herramientas, controla las capacidades del Agent
• Skills: Sistema de extensión de habilidades, amplía funcionalidades rápidamente
• WebSocket: Protocolo de comunicación en tiempo real, soporta clientes personalizados
• Event System: Mecanismo de distribución de eventos, soporta Webhooks y Cron

Estos conceptos aparecerán repetidamente en los artículos siguientes. Comprenderlos en profundidad te ayudará a configurar y usar OpenClaw de manera más efectiva.

Resumen de este artículo:

• Dominaste la arquitectura general del Gateway y las responsabilidades de los componentes
• Entendiste el modelo de sesiones y su ciclo de vida
• Aprendiste el enrutamiento de mensajes y las estrategias de activación de grupos
• Conociste los permisos de herramientas y la configuración de sandbox
• Dominaste el protocolo WebSocket y el sistema de eventos

Historial de actualizaciones:

• 2026-02-26: Versión inicial publicada, basada en OpenClaw v2026.2

Navegación de la serie:

• ← Anterior: Configuración de canales: Comenzando con Telegram
• → Siguiente: Configuración multimodelo y cambio