Conceptos principales para entender la arquitectura del asistente de IA Clawdbot, sesiones, enrutamiento multi-agente y manejo de mensajes.

Resumen de Conceptos de Clawdbot

Entender los conceptos principales de Clawdbot te ayuda a configurar y usar tu asistente de IA de manera efectiva. Esta sección cubre los bloques fundamentales de Clawdbot.

Conceptos Clave

Arquitectura del Gateway

El Gateway es el daemon central que:

Mantiene todas las conexiones de proveedores de mensajería
Expone una API WebSocket tipada
Gestiona el runtime de agentes y sesiones
Maneja el enrutamiento de mensajes

Aprende más sobre la Arquitectura del Gateway

Sesiones

Clawdbot trata una sesión de chat directo por agente como principal:

Los chats directos se colapsan a agent:<agentId>:<mainKey>
Los chats de grupo/canal obtienen sus propias claves
El estado de sesión es propiedad del Gateway

Enrutamiento Multi-Agente

Ejecuta múltiples agentes aislados con:

Espacios de trabajo separados (archivos, reglas de persona)
Directorios de estado
Almacenes de sesión
Perfiles de autenticación

Runtime del Agente

El runtime del agente maneja:

Procesamiento de mensajes
Ejecución de herramientas
Gestión de contexto
Generación de respuestas

Gestión de Sesiones

Opciones de Alcance de DM

Alcance	Descripción
`main` (por defecto)	Todos los DMs comparten la sesión principal
`per-peer`	Aislar por ID de remitente entre canales
`per-channel-peer`	Aislar por canal + remitente
`per-account-channel-peer`	Aislar por cuenta + canal + remitente

Claves de Sesión

Fuente	Formato de Clave
Chats directos	`agent:<agentId>:<mainKey>`
Chats de grupo	`agent:<agentId>:<channel>:group:<id>`
Trabajos cron	`cron:<job.id>`
Webhooks	`hook:<uuid>`

Ciclo de Vida de la Sesión

Las sesiones se reutilizan hasta que expiran
El reinicio diario es por defecto a las 4:00 AM hora local
Reinicio opcional por inactividad vía idleMinutes

Configuración Multi-Agente

¿Qué es un Agente?

Un agente es un cerebro completamente delimitado con:

Espacio de trabajo: Archivos, AGENTS.md, SOUL.md, reglas de persona
Directorio de estado: Perfiles de autenticación, registro de modelos
Almacén de sesión: Historial de chat + estado de enrutamiento
Habilidades: Por agente vía carpeta skills/ del espacio de trabajo

Modo de Agente Único (Por Defecto)

agentId es por defecto main
Las sesiones se identifican como agent:main:<mainKey>
Espacio de trabajo en ~/.clawdbot/workspace

Agregar Agentes

# Agregar un nuevo agente
clawdbot agents add work

# Listar agentes con bindings
clawdbot agents list --bindings

Reglas de Enrutamiento

Los mensajes se enrutan a agentes vía bindings:

{
  "bindings": [
    {
      "agentId": "alex",
      "match": {
        "channel": "whatsapp",
        "peer": { "kind": "dm", "id": "+15551230001" }
      }
    }
  ]
}

Manejo de Mensajes

Streaming y Chunking

Clawdbot soporta respuestas en streaming:

Actualizaciones parciales de mensajes
Indicadores de escritura
Entrega por chunks para respuestas largas

Política de Reintentos

Los mensajes fallidos se reintentan con:

Retroceso exponencial
Límites de reintento configurables
Manejo de errores

Dónde Vive el Estado

Elemento	Ubicación
Configuración	`~/.clawdbot/clawdbot.json`
Sesiones	`~/.clawdbot/agents/<agentId>/sessions/`
Transcripciones	`~/.clawdbot/agents/<agentId>/sessions/<SessionId>.jsonl`
Perfiles de autenticación	`~/.clawdbot/agents/<agentId>/agent/auth-profiles.json`

Próximos Pasos

Gateway de Clawdbot - Configuración del Gateway
Herramientas de Clawdbot - Configuración de herramientas
Canales de Clawdbot - Configuración de canales

Conceptos de Clawdbot

On this page