Análisis en profundidad de la arquitectura OpenClaw: principios del diseño en tres capas y práctica de extensión

Conclusión rápida (captura la línea principal de la arquitectura)

La forma más rápida de entender OpenClaw es captar las responsabilidades de las tres capas: Gateway gestiona sesiones, Channel el enrutamiento de mensajes, LLM la interfaz del modelo.
En cuanto clasificas un problema en una de estas tres capas, la depuración y la extensión van mucho más rápido.
Desarrollar un Channel o Provider nuevo consiste esencialmente en implementar la interfaz y registrarla.

A las dos de la madrugada miraba el repositorio de OpenClaw en el editor, listo para añadir un Channel de DingTalk. Decenas de archivos en src/, gateway, channel y llm entrelazados — no sabía por dónde empezar. ¿Modificar gateway afectaría a otros Channels? ¿Copiar el código de WhatsApp sería fiable? ¿Y si nada arranca tras mis cambios?

Sinceramente, fue desalentador. La documentación oficial explica cómo usar el producto, no cómo funciona por dentro. Para desarrollo personalizado era como tantear en la oscuridad: tocar el procesamiento webhook sin entender el enrutamiento; ver la llamada LLM sin captar el registro de Providers.

Luego pasé tres días enteros recorriendo el código fuente y descubrí lo ingenioso del diseño de OpenClaw: Gateway gestiona sesiones, Channel el enrutamiento, LLM la interfaz — tres capas con responsabilidades claras. Una vez entendido, el desarrollo personalizado deja de ser exploración a ciegas y pasa a ser un proceso estructurado.

Este artículo recoge de forma sistemática el fruto de esos tres días. Verás por qué OpenClaw se divide en tres capas, qué problema resuelve cada una, cómo Gateway gestiona el estado de las sesiones, cómo Channel adapta distintas plataformas, cómo está diseñado el sistema de plugins Provider de la capa LLM y, por último, una guía paso a paso para desarrollar Channels y Providers personalizados.

Guía de «cría de langosta» de bajo costo: ArkClaw democratiza el agente de IA

OpenClaw (la «langosta») es popular pero su configuración espanta. ArkClaw de ByteDance Volcano Engine baja la barrera al mínimo. Sin servidor ni configuración de Token, un clic basta para un «agente de IA» en línea 24 h, capaz de controlar el navegador, ejecutar scripts y gestionar el calendario.

El precio es realmente bajo: 9,9 yuanes/mes; con mi código de invitación ZLKUK54M (regístrate aquí), solo 8,9 yuanes. Si eres desarrollador, el Coding Plan Pro ofrece acceso gratuito.

Panorama de la arquitectura OpenClaw: ¿por qué tres capas?

Al descubrir OpenClaw me preguntaba: ¿por qué tanta complejidad en capas? ¿No basta con pasar el mensaje del usuario a la IA?

Al estudiar el código fuente lo entendí: un diseño monolítico funciona a pequeña escala, pero OpenClaw debe soportar varias plataformas (WhatsApp, Telegram, Gmail), varios modelos (Claude, GPT, modelos locales) y gestionar cientos de sesiones de usuario. Sin separación en capas, toda la lógica se amontona — cambiar un punto puede impactar todo, haciendo imposible el mantenimiento.

Filosofía del diseño en tres capas

OpenClaw divide el sistema en tres capas, cada una con su responsabilidad:

Capa Gateway (centro de gestión de sesiones)

• Gestión del ciclo de vida completo de las sesiones de usuario
• Cola y planificación de mensajes (prioridades)
• Autenticación y control de permisos (quién puede usar)
• Mantenimiento de conexiones WebSocket persistentes

Capa Channel (adaptador de plataforma)

• Adaptación de formatos de mensaje según la plataforma (WhatsApp y Telegram difieren)
• Reglas de enrutamiento (DM o grupo, respuesta solo con @)
• Gestión de eventos (recepción, envío, errores)

Capa LLM (interfaz de modelo)

• Interfaz Provider unificada (mismo modo de llamada para Claude o GPT)
• Llamada a herramientas (Function Calling)
• Procesamiento de respuestas en streaming
• Integración de servidores MCP

Flujo completo de procesamiento de un mensaje

Un escenario concreto: envías un mensaje al bot en WhatsApp.

1. Recepción Channel: el Channel WhatsApp recibe el webhook y normaliza el mensaje al formato interno
2. Decisión de enrutamiento: comprueba DM/grupo, mención del bot, permisos del usuario
3. Planificación Gateway: encuentra (o crea) la Session del usuario y añade el mensaje a la cola
4. Procesamiento LLM: según la config, elige un Provider (p. ej. Anthropic) y envía el contexto de conversación
5. Retorno de respuesta: resultado LLM → Gateway → Channel → el usuario recibe la respuesta

Lo ingenioso de este diseño: cada capa es independiente. ¿Nueva plataforma? Solo modifica Channel. ¿Cambiar de modelo? Solo LLM. Gateway queda intacto.

Capa Gateway: eje central de la gestión de sesiones

Al leer el código Gateway, lo que más me desconcertó fue el objeto Session. Cada usuario tiene una — pero ¿qué contiene exactamente y cómo se gestiona?

Ciclo de vida de una Session

Imagina Gateway como un centro de clasificación postal: cada usuario es una dirección de entrega, la Session es el registro de esa dirección.

Railway - Plataforma de despliegue moderna, sin ops complejas, en producción en minutos

Empezar ahora →Anuncio

Contenido de un objeto Session:

• conversationHistory: historial de conversación (últimos N mensajes)
• context: variables de contexto (preferencias del usuario, datos temporales)
• state: estado actual (idle, processing, waiting)
• channelInfo: información de la plataforma de origen (Channel de procedencia)

Gestión del ciclo de vida:

// Ejemplo simplificado, lógica central
class SessionManager {
  // Al recibir un mensaje
  async handleMessage(userId, channelId, message) {
    // 1. Buscar Session (o crear una)
    let session = this.getOrCreate(userId, channelId);

    // 2. Actualizar historial
    session.conversationHistory.push(message);

    // 3. Añadir a la cola de procesamiento
    await this.messageQueue.enqueue(session, message);

    // 4. Persistir (evitar pérdida en caso de caída)
    await this.persist(session);
  }
}

Punto clave: OpenClaw usa el modo de aislamiento per-channel-peer. En concreto, el mismo usuario en WhatsApp y Telegram tiene dos Sessions independientes. Evita confusión de contexto — técnica en WhatsApp, tiempo en Telegram, sin mezclarse.

Estrategia de prioridad en la planificación de mensajes

Gateway no procesa cada mensaje recibido al instante; pasa por una cola de planificación. Resuelve dos problemas:

Problema 1: control de concurrencia
Si 100 usuarios envían un mensaje a la vez y todo va directo al LLM, la API se satura. La cola Gateway limita la tasa, p. ej. «máximo 10 peticiones simultáneas».

Problema 2: reintento ante error
¿Falló la llamada LLM? Gateway reintenta automáticamente 3 veces con intervalo creciente (1 s, 2 s, 4 s), evitando pérdida de mensajes por fallo transitorio.

// Lógica central de la cola de mensajes
class MessageQueue {
  async enqueue(session, message) {
    // Comprobar concurrencia
    if (this.activeJobs >= this.maxConcurrency) {
      // Colocar en cola de espera
      this.waitingQueue.push({ session, message });
      return;
    }

    // Ejecutar procesamiento
    this.activeJobs++;
    try {
      await this.process(session, message);
    } catch (error) {
      // Lógica de reintento
      await this.retryWithBackoff(session, message);
    } finally {
      this.activeJobs--;
      this.processNext(); // procesar el siguiente
    }
  }
}

Trampas de las conexiones WebSocket persistentes

Para aplicaciones que exigen tiempo real (p. ej. bot de soporte), gestionar WebSocket es un reto real.

Enfoque de OpenClaw:

• Heartbeat: ping cada 30 segundos; timeout = conexión considerada cortada
• Reconexión automática: backoff exponencial tras desconexión (1 s, 2 s, 4 s… máx. 30 s)
• Sincronización de estado: restauración automática de Session tras reconexión

Estos detalles parecen menores, pero mejoran mucho la estabilidad. Ya escribí un sistema similar sin heartbeat — conexión zombi, mensajes perdidos sin que el programa lo supiera.

Capa Channel: enrutamiento multiplataforma

La capa Channel es para mí la más interesante. Resuelve un problema central: los formatos de mensaje difieren totalmente según la plataforma — ¿cómo tratarlos de forma unificada?

Utilidad del patrón Adapter

Mensaje WhatsApp:

{
  "from": "1234567890",
  "body": "Hola",
  "type": "text"
}

Mensaje Telegram:

{
  "message": {
    "chat": {"id": 123},
    "text": "Hola"
  }
}

Escribir lógica por plataforma haría explotar el código. OpenClaw aplica el patrón Adapter clásico: una interfaz Message estandarizada, cada Channel convierte el mensaje de su plataforma a ese formato.

// Formato de mensaje estandarizado
interface StandardMessage {
  userId: string;      // ID de usuario unificado
  content: string;     // Contenido del mensaje
  timestamp: number;   // Marca de tiempo
  metadata: any;       // Datos específicos de la plataforma
}

// Adaptador WhatsApp
class WhatsAppChannel implements Channel {
  adaptMessage(rawMessage): StandardMessage {
    return {
      userId: rawMessage.from,
      content: rawMessage.body,
      timestamp: Date.now(),
      metadata: { platform: 'whatsapp' }
    };
  }
}

Ventaja: Gateway y LLM ignoran la plataforma de origen — solo procesan StandardMessage.

Principio de implementación de reglas de enrutamiento

Otra responsabilidad importante de Channel: decidir qué mensajes merecen respuesta.

OpenClaw admite dos tipos de reglas:

dmPolicy (política de mensajes privados)

• pairing: emparejamiento previo requerido (lo más seguro)
• allowlist: solo usuarios en lista blanca
• open: cualquiera puede usar (bot público)
• disabled: mensajes privados desactivados

mentionGating (disparador por @ en grupos)
En grupo, respuesta solo si se menciona al bot, evitando spam. Lógica simple:

class TelegramChannel {
  shouldRespond(message): boolean {
    // Mensaje privado: responder directamente
    if (message.chat.type === 'private') {
      return this.checkDmPolicy(message.from.id);
    }

    // Grupo: comprobar @
    if (message.chat.type === 'group') {
      const mentioned = message.entities?.some(
        e => e.type === 'mention' && e.user.id === this.botId
      );
      return mentioned;
    }

    return false;
  }
}

Al desarrollar un Channel DingTalk, seguí esta lógica. La detección @ de DingTalk difiere ligeramente (campo atUsers), pero el marco es el mismo.

Método para desarrollar un Channel personalizado

Para integrar Discord, el flujo es así:

1. Crear la clase Channel: implementar la interfaz Channel
2. Implementar métodos requeridos:
   • start(): iniciar Channel (escuchar webhook o WebSocket)
   • sendMessage(): enviar mensaje a la plataforma
   • adaptMessage(): conversión de formato
3. Registrar en el sistema: añadir config del Channel
4. Probar: exponer servicio local con ngrok, probar webhook

Los ejemplos completos están en la sección práctica al final del artículo.

Capa LLM: diseño con plugins de la interfaz de modelo

La capa LLM sufrió en 2026 una refactorización mayor, pasando de hardcode a sistema de plugins. Este cambio determina cuántos modelos puede soportar OpenClaw.

Vultr - Servidor cloud NVMe de alto rendimiento, 32 ubicaciones globales, despliegue Docker con un clic

Ver precios →Anuncio

Sistema de plugins Provider

Diseño antiguo (pseudocódigo):

// Diseño antiguo: hardcode
if (config.provider === 'anthropic') {
  return new AnthropicClient();
} else if (config.provider === 'openai') {
  return new OpenAIClient();
}

Problema: cada modelo nuevo añade un if-else, el código crece sin límite.

El nuevo diseño introduce la interfaz Provider:

// Definición de la interfaz Provider
interface LLMProvider {
  name: string;  // 'anthropic', 'openai', 'ollama'

  // Enviar mensaje, devolver respuesta en streaming
  chat(messages: Message[], options: ChatOptions): AsyncIterator<string>;

  // Soporte de llamadas a herramientas
  supportTools(): boolean;

  // Inicialización de configuración
  initialize(config: ProviderConfig): void;
}

Todo Provider que implemente esta interfaz puede integrarse. Al arrancar, el sistema escanea y registra automáticamente:

// Mecanismo de registro de plugins
class ProviderRegistry {
  private providers = new Map<string, LLMProvider>();

  register(provider: LLMProvider) {
    this.providers.set(provider.name, provider);
  }

  get(name: string): LLMProvider {
    return this.providers.get(name);
  }
}

// Descubrimiento y registro automáticos
const registry = new ProviderRegistry();
registry.register(new AnthropicProvider());
registry.register(new OpenAIProvider());
registry.register(new OllamaProvider());

Ventaja: ¿modelo nuevo? Escribe una clase Provider, regístrala — sin tocar el código central.

Diferencias entre Providers principales

La interfaz está unificada, pero los detalles de implementación varían. Algunas trampas que encontré:

Provider Anthropic (Claude)

• Streaming nativo (stream: true)
• Formato Tool Use particular (array tools)
• Ventana de contexto grande (Claude 3.5 hasta 200k tokens)

Provider OpenAI (ChatGPT)

• Function Calling y Tool Use son dos API (versión antigua functions, nueva tools)
• El streaming devuelve fragmentos delta a concatenar manualmente
• Límites de tasa estrictos (RPM/TPM a controlar)

Provider Ollama (modelos locales)

• Sin clave API, llamada HTTP directa al servicio local
• Rendimiento muy dependiente del hardware (CPU lento, GPU recomendada)
• Soporte de herramientas variable según el modelo (llama3 sí, qwen a veces no)

Quise ejecutar Llama3 en local vía Ollama — el formato de llamada a herramientas difiere totalmente de Claude, adaptación laboriosa.

Mecanismo Tool Use en detalle

Tool Use (llamada a herramientas) es una función central de la capa LLM: permitir que la IA «llame funciones».

Ejemplo: «¿Qué hora es en Pekín?» La IA va a:

1. Decidir llamar la herramienta get_current_time
2. Devolver la petición de llamada: {"name": "get_current_time", "args": {"city": "Pekín"}}
3. OpenClaw ejecuta la herramienta y devuelve: {"time": "2026-02-05 20:30"}
4. La IA genera la respuesta: «Son las 20:30 en Pekín.»

Mecanismo de registro de herramientas en OpenClaw:

// Definición de herramientas
const tools = [
  {
    name: 'get_current_time',
    description: 'Obtener la hora actual de una ciudad',
    parameters: {
      type: 'object',
      properties: {
        city: { type: 'string', description: 'Nombre de la ciudad' }
      },
      required: ['city']
    }
  }
];

// Ejecución de herramientas
async function executeTool(toolName, args) {
  const handlers = {
    'get_current_time': (args) => {
      // La implementación real puede llamar una API
      return { time: new Date().toLocaleString('zh-CN', { timeZone: 'Asia/Shanghai' }) };
    }
  };

  return handlers[toolName](args);
}

Importante: la ejecución de herramientas debe aislarse en sandbox — si no, la IA podría pedir rm -rf /. OpenClaw integra control de permisos que solo autoriza herramientas predefinidas.

Práctica: extender la arquitectura OpenClaw

La teoría está puesta; pasemos a la práctica. Dos ejemplos completos: desarrollar un Channel Discord y un Provider Kimi.

Desarrollar un Channel personalizado: integración Discord

Discord difiere de WhatsApp: WebSocket para recibir, REST API para enviar.

Paso 1: implementar la interfaz Channel

import { Client, GatewayIntentBits } from 'discord.js';

class DiscordChannel implements Channel {
  private client: Client;
  private gateway: Gateway; // Instancia Gateway OpenClaw

  async start() {
    // Inicializar cliente Discord
    this.client = new Client({
      intents: [
        GatewayIntentBits.Guilds,
        GatewayIntentBits.GuildMessages,
        GatewayIntentBits.DirectMessages
      ]
    });

    // Escuchar mensajes
    this.client.on('messageCreate', async (msg) => {
      if (msg.author.bot) return; // Ignorar mensajes de bots

      // Convertir al formato estándar
      const standardMsg = this.adaptMessage(msg);

      // Delegar en Gateway
      const response = await this.gateway.handleMessage(standardMsg);

      // Enviar respuesta
      await msg.reply(response.content);
    });

    // Conexión
    await this.client.login(process.env.DISCORD_TOKEN);
  }

  adaptMessage(discordMsg): StandardMessage {
    return {
      userId: discordMsg.author.id,
      channelId: 'discord',
      content: discordMsg.content,
      timestamp: discordMsg.createdTimestamp,
      metadata: {
        guildId: discordMsg.guildId,
        channelType: discordMsg.channel.type
      }
    };
  }

  async sendMessage(userId: string, content: string) {
    const user = await this.client.users.fetch(userId);
    await user.send(content);
  }
}

Paso 2: registrar en OpenClaw

En config.json:

{
  "channels": {
    "discord": {
      "enabled": true,
      "token": "YOUR_DISCORD_BOT_TOKEN",
      "dmPolicy": "open"
    }
  }
}

En el script de arranque:

KiloClaw - OpenClaw gestionado para empresas: orquestación de agentes IA y enrutamiento inteligente

Empezar →Anuncio

import { DiscordChannel } from './channels/discord';

const gateway = new Gateway(config);
const discordChannel = new DiscordChannel(gateway, config.channels.discord);
gateway.registerChannel('discord', discordChannel);

await discordChannel.start();

Paso 3: probar

1. Crear un Bot en la plataforma de desarrolladores Discord, obtener el Token
2. Invitar el Bot a tu servidor
3. Iniciar OpenClaw, enviar mensaje privado al Bot
4. Revisar logs para confirmar el flujo de mensajes

Trampa que encontré: el sistema de permisos de Discord es complejo — el Bot debe tener Send Messages y Read Message History, si no el envío falla.

Desarrollar un Provider personalizado: integración Kimi

La API Kimi (Moonshot AI) se parece a OpenAI, con algunas diferencias.

Implementación Provider:

class KimiProvider implements LLMProvider {
  name = 'kimi';
  private apiKey: string;
  private baseURL = 'https://api.moonshot.cn/v1';

  initialize(config: ProviderConfig) {
    this.apiKey = config.apiKey;
  }

  async *chat(messages: Message[], options: ChatOptions) {
    const response = await fetch(`${this.baseURL}/chat/completions`, {
      method: 'POST',
      headers: {
        'Authorization': `Bearer ${this.apiKey}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        model: options.model || 'moonshot-v1-8k',
        messages: messages.map(m => ({
          role: m.role,
          content: m.content
        })),
        stream: true,
        temperature: options.temperature || 0.7
      })
    });

    // Procesar respuesta en streaming
    const reader = response.body.getReader();
    const decoder = new TextDecoder();

    while (true) {
      const { done, value } = await reader.read();
      if (done) break;

      const chunk = decoder.decode(value);
      const lines = chunk.split('\n').filter(line => line.trim());

      for (const line of lines) {
        if (line.startsWith('data: ')) {
          const data = line.slice(6);
          if (data === '[DONE]') continue;

          const parsed = JSON.parse(data);
          const content = parsed.choices[0]?.delta?.content;
          if (content) {
            yield content;
          }
        }
      }
    }
  }

  supportTools(): boolean {
    return false; // Kimi aún no admite Function Calling
  }
}

Registrar el Provider:

const registry = new ProviderRegistry();
registry.register(new KimiProvider());

// Configuración de uso
const config = {
  llm: {
    provider: 'kimi',
    apiKey: process.env.KIMI_API_KEY,
    model: 'moonshot-v1-32k'
  }
};

Lecciones aprendidas:

• El formato de streaming de Kimi es idéntico a OpenAI, reutilizable directamente
• El manejo de errores difiere — el timeout no devuelve código de error estándar
• Sin Function Calling por ahora — inutilizable si tu aplicación depende de ello

Prácticas de optimización de rendimiento

Hacer funcionar el código es solo el primer paso; la optimización es el trabajo real. Algunos puntos que probé:

Optimización de caché Session
Por defecto, la Session está en memoria — se pierde al reiniciar. Integración Redis posible:

class RedisSessionStore {
  private redis: Redis;

  async get(userId: string, channelId: string): Promise<Session> {
    const key = `session:${channelId}:${userId}`;
    const data = await this.redis.get(key);
    return data ? JSON.parse(data) : null;
  }

  async set(session: Session) {
    const key = `session:${session.channelId}:${session.userId}`;
    await this.redis.setex(key, 3600, JSON.stringify(session)); // expiración 1 h
  }
}

Ajuste de la cola de mensajes
En alta concurrencia, la cola en memoria no basta — Bull (cola de tareas Redis):

import Queue from 'bull';

const messageQueue = new Queue('openclaw-messages', {
  redis: { host: 'localhost', port: 6379 }
});

messageQueue.process(10, async (job) => { // 10 concurrentes máx.
  const { session, message } = job.data;
  return await gateway.processMessage(session, message);
});

Control del número de conexiones concurrentes
Las API LLM tienen límites de tasa (p. ej. OpenAI 60 RPM). Biblioteca p-limit:

import pLimit from 'p-limit';

const limit = pLimit(10); // 10 peticiones concurrentes máx.

const tasks = messages.map(msg =>
  limit(() => provider.chat(msg))
);

await Promise.all(tasks);

Comparación antes/después de optimización (mis mediciones):

• Antes: 100 peticiones concurrentes, tiempo de respuesta medio 8 s, tasa de fallo 15 %
• Después: 100 peticiones concurrentes, tiempo de respuesta medio 3 s, tasa de fallo < 1 %

Conclusión

De Gateway a Channel y luego LLM, la arquitectura en tres capas de OpenClaw es notablemente clara. Cada capa tiene su responsabilidad, los límites son netos, la extensión es sencilla.

Una vez entendido este marco, desarrollar nuevas funciones fluye mejor. ¿Nueva plataforma? Escribe un Channel Adapter. ¿Nuevo modelo? Implementa un Provider. ¿Optimizar rendimiento? Identifica la capa concernida y actúa de forma dirigida.

Si piensas personalizar OpenClaw en profundidad, clona primero el código fuente y recórrelo siguiendo la lógica de este artículo. Session Gateway, enrutamiento Channel, registro Provider — estos tres bloques son el núcleo del sistema.

Dominar esto significa que ya no «copias la config de la documentación» — entiendes el sistema y puedes extenderlo y optimizarlo libremente.

Prueba luego un Channel personalizado simple (WeCom, Lark/Feishu): la práctica profundiza la comprensión. La comunidad open source de OpenClaw está activa — GitHub Issues acoge tus preguntas.

Próximas lecturas

• Guía de configuración OpenClaw: openclaw.json completo
• Configuración multiplataforma OpenClaw: 13 Channels unificados
• Guía de instalación OpenClaw 2026: despliegue desde cero