Clawdbot Gateway

Aperçu de Clawdbot Gateway

Clawdbot Gateway est le processus permanent qui gère les connexions de messagerie (WhatsApp via Baileys, Telegram via grammY, Discord, Slack et plus) et le plan de contrôle/événements. C'est le service central qui maintient votre assistant IA Clawdbot en fonctionnement 24h/24 et 7j/7.

Qu'est-ce que le Gateway ?

Le Gateway est un daemon à longue durée de vie qui :

• Maintient toutes les connexions aux fournisseurs de messagerie
• Expose une API WebSocket typée pour les requêtes, réponses et événements push du serveur
• Valide les trames entrantes selon le JSON Schema
• Émet des événements comme agent, chat, presence, health, heartbeat, cron

Principe clé : Un Gateway par hôte ; c'est le seul endroit qui ouvre les sessions de messagerie (comme WhatsApp).

Démarrage Rapide

Démarrer le Gateway

clawdbot gateway --port 18789

Pour des logs de débogage/traçage complets :

clawdbot gateway --port 18789 --verbose

Si le port est occupé, terminez les listeners puis démarrez :

clawdbot gateway --force

Mode Développement

Pour le développement avec rechargement automatique sur les modifications TypeScript :

pnpm gateway:watch

Architecture du Gateway

Composants

Flux de Connexion

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

Configuration du Gateway

Configuration de Base

Emplacement du fichier de configuration : ~/.clawdbot/clawdbot.json

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

Configuration du Port

Priorité du port :

1. Flag CLI --port
2. Variable d'environnement CLAWDBOT_GATEWAY_PORT
3. gateway.port dans la configuration
4. Par défaut : 18789

Authentification

L'authentification du Gateway est requise par défaut. Configurez via :

• gateway.auth.token dans la configuration
• Variable d'environnement CLAWDBOT_GATEWAY_TOKEN
• gateway.auth.password pour l'authentification par mot de passe

Les clients doivent envoyer connect.params.auth.token ou connect.params.auth.password.

Rechargement à Chaud

Le rechargement à chaud de la configuration surveille ~/.clawdbot/clawdbot.json :

Services du Gateway

Points de Terminaison HTTP

Le Gateway sert plusieurs points de terminaison HTTP sur le même port :

Canvas Host

Démarre par défaut sur le port 18793, servant :

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

Depuis ~/.clawdbot/workspace/canvas. Désactiver avec :

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

Tableau de Bord

Accédez à l'UI de Contrôle à :

http://127.0.0.1:18789/

Ou exécutez :

clawdbot dashboard

Accès à Distance

Tunnel SSH (Recommandé)

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

Les clients se connectent ensuite à ws://127.0.0.1:18789 via le tunnel.

Tailscale/VPN

Préféré pour l'accès à distance en production. Le même handshake + token d'authentification s'applique.

Gestion du Gateway

Commandes de Service

# Vérifier le statut
clawdbot gateway status

# Vérification de santé
clawdbot health

# Audit de sécurité
clawdbot security audit --deep

# Arrêter le gateway
clawdbot gateway stop

Supervision

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

Linux : Utilise le service utilisateur systemd (clawdbot-gateway-<profile>.service)

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

Gateways Multiples

Généralement inutile — un Gateway peut servir plusieurs canaux et agents. Utilisez plusieurs Gateways uniquement pour :

• La redondance
• L'isolation stricte (ex., bot de secours)

Exigences :

• Isoler l'état + la configuration
• Utiliser des ports uniques

Protocole Wire

Transport

• WebSocket avec des trames texte contenant des payloads JSON
• La première trame doit être connect

Types de Messages

Requêtes :

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

Réponses :

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

Événements :

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

Idempotence

Les clés d'idempotence sont requises pour les méthodes à effets de bord (send, agent) pour un retry sûr.

Dépannage

Le Gateway Ne Démarre Pas

1. Vérifiez si le port est utilisé : lsof -i :18789
2. Consultez les logs : cat /tmp/clawdbot/gateway.log
3. Utilisez --force pour terminer les listeners existants

Problèmes de Connexion

1. Vérifiez que le token d'authentification correspond
2. Vérifiez la connectivité réseau
3. Consultez les logs de handshake WebSocket avec --verbose

Problèmes de Canal

1. Vérifiez le statut du canal : clawdbot channels status
2. Ré-authentifiez les canaux : clawdbot channels login
3. Consultez les logs spécifiques au canal

Bonnes Pratiques

1. Utilisez des Tokens d'Auth : Configurez toujours gateway.auth.token pour la sécurité
2. Surveillez la Santé : Vérifiez régulièrement clawdbot health
3. Utilisez la Supervision : Laissez launchd/systemd gérer les redémarrages
4. Sauvegardez la Configuration : Conservez des sauvegardes de ~/.clawdbot/clawdbot.json
5. Consultez les Logs : Vérifiez régulièrement les logs pour détecter les problèmes

Prochaines Étapes

• Guide d'Installation de Clawdbot - Guide d'installation complet
• Intégration WhatsApp de Clawdbot - Connecter à WhatsApp
• Intégration Telegram de Clawdbot - Connecter à Telegram