Clawdbot Gateway

Clawdbot Gateway Übersicht

Das Clawdbot Gateway ist der dauerhaft laufende Prozess, der die Messaging-Verbindungen (WhatsApp über Baileys, Telegram über grammY, Discord, Slack und mehr) sowie die Steuerungs-/Ereignisebene besitzt. Es ist der Kerndienst, der Ihren Clawdbot KI-Assistenten rund um die Uhr am Laufen hält.

Was ist das Gateway?

Das Gateway ist ein langlebiger Daemon, der:

• Alle Messaging-Provider-Verbindungen aufrechterhält
• Eine typisierte WebSocket-API für Anfragen, Antworten und Server-Push-Events bereitstellt
• Eingehende Frames gegen JSON Schema validiert
• Events wie agent, chat, presence, health, heartbeat, cron ausgibt

Kernprinzip: Ein Gateway pro Host; es ist der einzige Ort, der Messaging-Sitzungen (wie WhatsApp) öffnet.

Schnellstart

Gateway starten

clawdbot gateway --port 18789

Für vollständige Debug-/Trace-Logs:

clawdbot gateway --port 18789 --verbose

Wenn der Port belegt ist, beenden Sie Listener und starten Sie dann:

clawdbot gateway --force

Entwicklungsmodus

Für Entwicklung mit automatischem Neuladen bei TypeScript-Änderungen:

pnpm gateway:watch

Gateway-Architektur

Komponenten

Verbindungsablauf

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

Gateway-Konfiguration

Grundkonfiguration

Speicherort der Konfigurationsdatei: ~/.clawdbot/clawdbot.json

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

Port-Konfiguration

Port-Priorität:

1. CLI-Flag --port
2. Umgebungsvariable CLAWDBOT_GATEWAY_PORT
3. gateway.port in der Konfiguration
4. Standard: 18789

Authentifizierung

Gateway-Authentifizierung ist standardmäßig erforderlich. Konfigurieren Sie über:

• gateway.auth.token in der Konfiguration
• Umgebungsvariable CLAWDBOT_GATEWAY_TOKEN
• gateway.auth.password für Passwort-basierte Authentifizierung

Clients müssen connect.params.auth.token oder connect.params.auth.password senden.

Hot Reload

Konfigurations-Hot-Reload überwacht ~/.clawdbot/clawdbot.json:

Gateway-Dienste

HTTP-Endpunkte

Das Gateway stellt mehrere HTTP-Endpunkte auf demselben Port bereit:

Canvas Host

Startet standardmäßig auf Port 18793 und stellt bereit:

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

Aus ~/.clawdbot/workspace/canvas. Deaktivieren mit:

• canvasHost.enabled: false
• CLAWDBOT_SKIP_CANVAS_HOST=1

Dashboard

Zugriff auf die Steuerungs-UI unter:

http://127.0.0.1:18789/

Oder ausführen:

clawdbot dashboard

Fernzugriff

SSH-Tunnel (Empfohlen)

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

Clients verbinden sich dann über den Tunnel mit ws://127.0.0.1:18789.

Tailscale/VPN

Bevorzugt für Fernzugriff in der Produktion. Derselbe Handshake + Auth-Token gilt.

Gateway-Verwaltung

Dienstbefehle

# Status prüfen
clawdbot gateway status

# Gesundheitsprüfung
clawdbot health

# Sicherheitsaudit
clawdbot security audit --deep

# Gateway stoppen
clawdbot gateway stop

Überwachung

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

Linux: Verwendet systemd-Benutzerdienst (clawdbot-gateway-<profile>.service)

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

Mehrere Gateways

Normalerweise unnötig — ein Gateway kann mehrere Kanäle und Agenten bedienen. Verwenden Sie mehrere Gateways nur für:

• Redundanz
• Strikte Isolation (z.B. Rettungsbot)

Anforderungen:

• Zustand + Konfiguration isolieren
• Einzigartige Ports verwenden

Wire-Protokoll

Transport

• WebSocket mit Textframes, die JSON-Payloads enthalten
• Der erste Frame muss connect sein

Nachrichtentypen

Anfragen:

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

Antworten:

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

Events:

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

Idempotenz

Idempotenzschlüssel sind für Methoden mit Seiteneffekten (send, agent) erforderlich, um sicher wiederholen zu können.

Fehlerbehebung

Gateway startet nicht

1. Prüfen Sie, ob der Port belegt ist: lsof -i :18789
2. Überprüfen Sie die Logs: cat /tmp/clawdbot/gateway.log
3. Verwenden Sie --force, um bestehende Listener zu beenden

Verbindungsprobleme

1. Überprüfen Sie, ob der Auth-Token übereinstimmt
2. Prüfen Sie die Netzwerkverbindung
3. Überprüfen Sie WebSocket-Handshake-Logs mit --verbose

Kanalprobleme

1. Prüfen Sie den Kanalstatus: clawdbot channels status
2. Authentifizieren Sie Kanäle erneut: clawdbot channels login
3. Überprüfen Sie kanalspezifische Logs

Best Practices

1. Auth-Tokens verwenden: Konfigurieren Sie immer gateway.auth.token für Sicherheit
2. Gesundheit überwachen: Prüfen Sie regelmäßig clawdbot health
3. Überwachung nutzen: Lassen Sie launchd/systemd Neustarts verwalten
4. Konfiguration sichern: Erstellen Sie Backups von ~/.clawdbot/clawdbot.json
5. Logs prüfen: Überprüfen Sie Logs regelmäßig auf Probleme

Nächste Schritte

• Clawdbot Einrichtungsanleitung - Vollständige Installationsanleitung
• Clawdbot WhatsApp-Integration - Mit WhatsApp verbinden
• Clawdbot Telegram-Integration - Mit Telegram verbinden