Clawdbot Gateway es el servicio siempre activo que gestiona las conexiones de mensajería, el tiempo de ejecución del agente y el plano de control para tu asistente de IA.

Descripción General de Clawdbot Gateway

Clawdbot Gateway es el proceso siempre activo que posee las conexiones de mensajería (WhatsApp vía Baileys, Telegram vía grammY, Discord, Slack y más) y el plano de control/eventos. Es el servicio central que mantiene tu asistente de IA Clawdbot funcionando 24/7.

¿Qué es el Gateway?

El Gateway es un daemon de larga duración que:

Mantiene todas las conexiones de proveedores de mensajería
Expone una API WebSocket tipada para solicitudes, respuestas y eventos push del servidor
Valida los frames entrantes contra JSON Schema
Emite eventos como agent, chat, presence, health, heartbeat, cron

Principio clave: Un Gateway por host; es el único lugar que abre sesiones de mensajería (como WhatsApp).

Inicio Rápido

Iniciar el Gateway

clawdbot gateway --port 18789

Para logs completos de depuración/rastreo:

clawdbot gateway --port 18789 --verbose

Si el puerto está ocupado, termina los listeners y luego inicia:

clawdbot gateway --force

Modo Desarrollo

Para desarrollo con recarga automática en cambios de TypeScript:

pnpm gateway:watch

Arquitectura del Gateway

Componentes

Componente	Descripción
Gateway (daemon)	Mantiene conexiones de proveedores, expone WS API
Clientes	App macOS, CLI, UI web conectan vía WebSocket
Nodos	Dispositivos macOS/iOS/Android/headless con `role: node`
WebChat	UI estática usando Gateway WS API
Canvas Host	Sirve HTML editable por agentes (puerto predeterminado 18793)

Flujo de Conexión

Client                    Gateway
  |                          |
  |---- req:connect -------->|
  |<------ res (ok) ---------|
  |                          |
  |<------ event:presence ---|
  |<------ event:tick -------|
  |                          |
  |------- req:agent ------->|
  |<------ res:agent --------|
  |<------ event:agent ------|

Configuración del Gateway

Configuración Básica

Ubicación del archivo de configuración: ~/.clawdbot/clawdbot.json

{
  "gateway": {
    "port": 18789,
    "auth": {
      "token": "your-secret-token"
    },
    "reload": {
      "mode": "hybrid"
    }
  }
}

Configuración de Puerto

Precedencia del puerto:

Flag CLI --port
Variable de entorno CLAWDBOT_GATEWAY_PORT
gateway.port en la configuración
Predeterminado: 18789

Autenticación

La autenticación del Gateway es requerida por defecto. Configúrala vía:

gateway.auth.token en la configuración
Variable de entorno CLAWDBOT_GATEWAY_TOKEN
gateway.auth.password para autenticación basada en contraseña

Los clientes deben enviar connect.params.auth.token o connect.params.auth.password.

Recarga en Caliente

La recarga en caliente de configuración vigila ~/.clawdbot/clawdbot.json:

Modo	Descripción
`hybrid` (predeterminado)	Aplica cambios seguros en caliente, reinicia en críticos
`off`	Deshabilita la recarga en caliente

Servicios del Gateway

Endpoints HTTP

El Gateway sirve múltiples endpoints HTTP en el mismo puerto:

Endpoint	Descripción
`/v1/chat/completions`	Compatible con OpenAI Chat Completions
`/v1/responses`	API OpenResponses
`/tools/invoke`	Invocación de herramientas
UI de Control	Dashboard basado en web

Canvas Host

Inicia por defecto en el puerto 18793, sirviendo:

http://<gateway-host>:18793/__clawdbot__/canvas/

Desde ~/.clawdbot/workspace/canvas. Deshabilitar con:

canvasHost.enabled: false
CLAWDBOT_SKIP_CANVAS_HOST=1

Dashboard

Accede a la UI de Control en:

http://127.0.0.1:18789/

O ejecuta:

clawdbot dashboard

Acceso Remoto

Túnel SSH (Recomendado)

ssh -N -L 18789:127.0.0.1:18789 user@host

Los clientes luego conectan a ws://127.0.0.1:18789 a través del túnel.

Tailscale/VPN

Preferido para acceso remoto en producción. El mismo handshake + token de autenticación aplica.

Gestión del Gateway

Comandos de Servicio

# Verificar estado
clawdbot gateway status

# Verificación de salud
clawdbot health

# Auditoría de seguridad
clawdbot security audit --deep

# Detener gateway
clawdbot gateway stop

Supervisión

macOS: Usa LaunchAgent (bot.molt.<profile>)

Linux: Usa servicio de usuario systemd (clawdbot-gateway-<profile>.service)

Windows: Usa Windows Service (Clawdbot Gateway (<profile>))

Múltiples Gateways

Usualmente innecesario—un Gateway puede servir múltiples canales y agentes. Usa múltiples Gateways solo para:

Redundancia
Aislamiento estricto (ej., bot de rescate)

Requisitos:

Aislar estado + configuración
Usar puertos únicos

Protocolo Wire

Transporte

WebSocket con frames de texto conteniendo payloads JSON
El primer frame debe ser connect

Tipos de Mensajes

Solicitudes:

{"type": "req", "id": "...", "method": "...", "params": {...}}

Respuestas:

{"type": "res", "id": "...", "ok": true, "payload": {...}}

Eventos:

{"type": "event", "event": "...", "payload": {...}, "seq": 1}

Verifica si el puerto está en uso: lsof -i :18789
Revisa logs: cat /tmp/clawdbot/gateway.log
Usa --force para terminar listeners existentes

Problemas de Conexión

Verifica que el token de autenticación coincida
Verifica conectividad de red
Revisa logs de handshake WebSocket con --verbose

Problemas de Canal

Verifica estado del canal: clawdbot channels status
Re-autentica canales: clawdbot channels login
Revisa logs específicos del canal

Mejores Prácticas

Usa Tokens de Auth: Siempre configura gateway.auth.token para seguridad
Monitorea Salud: Verifica regularmente clawdbot health
Usa Supervisión: Deja que launchd/systemd gestione los reinicios
Respalda Configuración: Mantén backups de ~/.clawdbot/clawdbot.json
Revisa Logs: Verifica logs regularmente para detectar problemas

Próximos Pasos

Guía de Configuración de Clawdbot - Guía completa de instalación
Integración de WhatsApp con Clawdbot - Conectar a WhatsApp
Integración de Telegram con Clawdbot - Conectar a Telegram

Clawdbot Gateway