Gateway
Was ist das Gateway?
Das Gateway ist das Herzstueck von Neotask -- ein einzelner dauerhaft laufender Dienst, der alle Agent-Sessions, Messaging-Kanaele, Tool-Ausfuehrung und Geraeteverbindungen verwaltet. Alles fliesst durch das Gateway.
Es ist ein WebSocket-Server, der auf Verbindungen von Clients (Desktop-App, Mobile-Apps, Web-Dashboard) wartet und den gesamten KI-Assistenten-Lebenszyklus verwaltet.
Architektur
Komponenten
- WebSocket-Server -- Akzeptiert Client-Verbindungen (Standard-Port 18789)
- HTTP-Server -- Stellt die Control-UI, den Canvas-Host und Health-Endpunkte bereit
- Channel-Adapter -- Halten Verbindungen zu Messaging-Plattformen aufrecht (WhatsApp, Telegram, Discord usw.)
- Session-Manager -- Speichert und verwaltet den Agenten-Konversationsstatus
- Cron-Scheduler -- Fuehrt geplante Jobs und Heartbeat-Weckrufe aus
- Plugin-Runtime -- Laedt und verwaltet den Plugin-Lebenszyklus
- Browser-Service -- Steuert Chromium-Instanzen fuer Web-Automatisierung
Bindungsmodi
| Modus | Beschreibung |
|---|---|
| Loopback | Standard. Nur von localhost (127.0.0.1) zugaenglich |
| LAN | In Ihrem lokalen Netzwerk zugaenglich. Auto-erkennbar ueber Bonjour/mDNS |
| Tailnet | Ueber Tailscale VPN mit MagicDNS zugaenglich |
| Custom | An eine bestimmte Adresse binden |
Authentifizierung
| Methode | Beschreibung |
|---|---|
| Token | WebSocket Bearer-Token (UUID oder benutzerdefinierte Zeichenkette) |
| Password | Passwortbasierte Auth (bcrypt-gehasht) |
| Trusted Proxy | Fuer Reverse-Proxys mit Pre-Auth-Headern |
| Local Trust | Loopback-Verbindungen automatisch genehmigt |
Konfiguration
Das Gateway wird ueber neotask.json (JSON5-Format) konfiguriert. Wichtige Abschnitte:
| Abschnitt | Steuert |
|---|---|
agents |
Agentenliste, Standardwerte, Workspaces |
gateway |
Port, Bindungsmodus, Auth, Reload-Verhalten |
channels |
Pro-Channel-Konfiguration und Anmeldedaten |
tools |
Tool-Berechtigungen, Profile, Sicherheit |
plugins |
Plugin-Laden, Aktivierung, Pro-Plugin-Konfiguration |
models |
Anbieter-Auth, Fallbacks, Anbietereinstellungen |
skills |
Skill-Verzeichnisse, Pro-Skill-Konfiguration |
browser |
Browserprofile, Ports, Headless-Modus |
cron |
Scheduler-Konfiguration |
session |
Reset-Regeln, Komprimierungsschwellen |
messages |
TTS-Einstellungen, Medien-Policies |
memory |
Speicher-Indizierungskonfiguration |
security |
Sandboxing, Elevated-Modus, Genehmigungen |
Hot Reload
Konfigurationsaenderungen koennen ohne Neustart angewendet werden:
| Modus | Verhalten |
|---|---|
| Hybrid (Standard) | Sichere Aenderungen hot-anwenden, fuer andere neu starten |
| Hot | Nur hot-safe Aenderungen anwenden, andere ignorieren |
| Restart | Bei jeder reload-erfordernden Aenderung neu starten |
| Off | Kein automatisches Reload |
Remote-Zugriff
Tailscale (Empfohlen)
Tailscale bietet sicheren, konfigurationsfreien Remote-Zugriff:
- Gateway an Ihr Tailnet binden
- Von jedem Geraet im selben Tailscale-Netzwerk zugreifen
- Automatisches DNS ueber MagicDNS
- Tailscale Serve kann das Dashboard mit HTTPS bereitstellen
SSH-Tunnel
Gateway-Port ueber SSH weiterleiten:
- Einfach, sicher, keine Konfigurationsaenderungen noetig
- Funktioniert mit jeder SSH-faehigen Maschine
- Unterstuetzt das vollstaendige WebSocket-Protokoll und die Control-UI
Sicherheitsregeln
- Loopback + SSH/Tailscale ist die sicherste Kombination
- Nicht-Loopback-Bindung erfordert Auth-Token-Konfiguration
- TLS-Fingerprint-Pinning fuer zusaetzliche Sicherheit verfuegbar
- Browser-Steuerung ist fuer Remote-Verbindungen standardmaessig deaktiviert
Health-Monitoring
Health-Endpunkt
Der /health HTTP-Endpunkt gibt zurueck:
- Gateway-Status
- RPC-Verfuegbarkeit
- Pro-Channel-Gesundheit (verbunden, Auth-Status, Kontoanzahl)
- Browser-Bereitschaft
- Aktive Agenten und verbundene Nodes
- Betriebszeit
Probes
- RPC-Verfuegbarkeit -- WebSocket-Verbindung + Echo-Test
- Channel-Gesundheit -- Auth-Check + API-Ping pro Channel
- Browser-Bereitschaft -- Port-Check, Prozess-Check
- Node-Konnektivitaet -- Letzter Heartbeat-Zeitstempel
Erkennung
Bonjour/mDNS
Bei LAN-Bindung kuendigt sich das Gateway ueber Multicast-DNS an:
- Service-Typ:
_neotask-gw._tcp - Beinhaltet Port, Transport, TLS-Status und Tailscale-DNS-Info
- Begleit-Apps erkennen das Gateway automatisch
Wide-Area-Erkennung
Gateways in Ihrem Netzwerk mit konfigurierbaren Timeouts erkennen. Unterstuetzt sowohl lokale Bonjour- als auch Tailscale-DNS-Erkennung.
Mehrere Gateways
Sie koennen mehrere Gateway-Instanzen auf demselben Rechner mit Profilen betreiben:
- Jedes Profil hat separate Konfiguration, Workspace, Sessions und Status
- Verschiedene Ports fuer jedes Gateway
- Nuetzlich fuer Isolation (persoenlich vs. Arbeit) oder Tests
Diagnose
Doctor
Das integrierte Diagnosetool prueft:
- Konfigurationsgueltigheit
- Dateiberechtigungen
- Channel-Konnektivitaet
- Modell-Auth-Status
- Node.js-Versionskompatibilitaet
- Haeufige Fehlkonfigurationen
Es kann viele Probleme automatisch beheben, wenn die Berechtigung erteilt wird.
Protokollierung
Gateway-Logs werden in taegliche JSONL-Dateien geschrieben:
- Pro-Completion-Token-Nutzungsverfolgung
- Channel-Event-Logs
- Fehlerprotokollierung mit strukturiertem Kontext
- Konfigurierbare Log-Levels