Web-Interface und Gateway-Konfiguration

Kennst du das? Du hast einen Dienst auf deinem Server laufen, aber der Zugriff von außen ist jedes Mal ein Krampf. Entweder schlägst du dich mit komplexen Firewall-Regeln herum oder du landest bei einer unsicheren Bastellösung, die eigentlich niemand im Netz haben will.

Es ist nervig, wenn man nur kurz den Status checken will, aber erst mühsam Tunnel graben oder Zertifikate manuell verwalten muss. Hier erfährst du, wie du das Control UI sicher und direkt startest.

Voraussetzungen

• Vorhandene UI-Assets im Ordner dist/control-ui
• Eine aktive Tailscale-Installation (falls du die empfohlene Methode nutzt)

Schnellstart

Ich empfehle dir den Weg über Tailscale Serve. Das Gateway bleibt dabei im Loopback, während Tailscale den Proxy-Part übernimmt. Das ist die sicherste und einfachste Methode.

1. Konfiguration anpassen: Erstelle oder editiere deine Konfigurationsdatei:

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "serve" },
  },
}

2. Gateway starten: Führe den Befehl in deinem Terminal aus:

openclaw gateway

3. UI öffnen: Du erreichst das Interface jetzt unter https://<magicdns>/.

Webhooks

Wenn du hooks.enabled=true setzt, stellt das Gateway einen Webhook-Endpoint auf demselben HTTP-Server bereit. Details zu Auth und Payloads findest du in der Gateway-Konfiguration.

Bind-Modi und Security

Du hast verschiedene Möglichkeiten, wie dein Gateway im Netz erreichbar ist.

Tailnet Bind mit Token

Falls du kein Serve nutzen willst, kannst du direkt an das Tailnet binden. Beachte, dass hier ein Token zwingend erforderlich ist.

{
  gateway: {
    bind: "tailnet",
    controlUi: { enabled: true },
    auth: { mode: "token", token: "dein-token" },
  },
}

Public Internet (Funnel)

Wenn du Zugriff aus dem öffentlichen Internet brauchst, nutzt du den Funnel-Modus. Hier ist der Passwort-Modus Pflicht.

{
  gateway: {
    bind: "loopback",
    tailscale: { mode: "funnel" },
    auth: { mode: "password" },
  },
}

Wichtige Security-Eckpunkte

• Gateway-Auth ist standardmäßig aktiv (Token, Passwort oder Tailscale Identity Header).
• Non-loopback Binds verlangen immer nach einem Shared Token oder Passwort.
• Das Control UI sendet Anti-Clickjacking Header.
• Websocket-Verbindungen werden nur vom selben Origin akzeptiert, außer du konfigurierst gateway.controlUi.allowedOrigins.

UI manuell bauen

Falls die statischen Dateien in dist/control-ui fehlen, kannst du sie selbst generieren. Der Befehl installiert beim ersten Mal alle nötigen UI-Abhängigkeiten automatisch.

pnpm ui:build

Fehlerbehebung

• Zugriff verweigert bei Non-loopback: Überprüfe, ob du ein Token oder Passwort in gateway.auth oder per Umgebungsvariable gesetzt hast. Ohne diese Anmeldedaten blockiert das Gateway Verbindungen, die nicht über Loopback kommen.
• Funnel funktioniert nicht: Stelle sicher, dass gateway.auth.mode auf password steht. Funnel erlaubt keinen Betrieb ohne explizites Passwort.

Hast du Fragen zur Einrichtung? Der AI Setup Assistant hilft dir direkt weiter.

Nächste Schritte

• Control UI Dokumentation
• Gateway Konfigurations-Referenz
• Tailscale Integration
• Security Guide