Gateway

Runbook zur Gateway-Exposition

Dieses Runbook überführt die umfassenderen Hinweise unter Sicherheit in eine Checkliste für Betreiber zur Freigabe von Remote-Zugriff und Messaging.

Freigabemuster auswählen

Bevorzugen Sie das restriktivste Muster, das den Workflow erfüllt.

Muster	Empfohlen für	Erforderliche Kontrollen
Loopback + SSH-Tunnel	Persönliche Nutzung, Admin-Zugriff, Debugging	`gateway.bind: "loopback"` beibehalten und `127.0.0.1:18789` tunneln
Loopback + Tailscale Serve	Persönlicher Tailnet-Zugriff auf Control UI/WebSocket	Gateway auf Loopback beschränken; Tailscale-Identitätsheader authentifizieren nur die WebSocket-Oberfläche der Control UI, nicht andere Authentifizierungspfade
Tailnet-/LAN-Bindung	Dediziertes privates Netzwerk mit bekannten Geräten	Gateway-Authentifizierung, Firewall-Zulassungsliste, keine öffentliche Portweiterleitung
Vertrauenswürdiger Reverse-Proxy	Organisationsweites SSO/OIDC vor dem Gateway	`trusted-proxy`-Authentifizierung, strikte `trustedProxies`, Regeln zum Überschreiben/Entfernen von Headern, ausdrücklich zugelassene Benutzer
Öffentliches Internet	Seltene Bereitstellungen mit hohem Risiko	Identitätsbasierter Proxy, TLS, Ratenbegrenzungen, strikte Zulassungslisten, isolierte Nicht-Hauptsitzungen

Vermeiden Sie eine direkte öffentliche Portweiterleitung zum Gateway. Wenn öffentlicher Zugriff erforderlich ist, schalten Sie einen identitätsbasierten Proxy davor und machen Sie den Proxy zum einzigen Netzwerkpfad zum Gateway.

Bestandsaufnahme vor der Freigabe

Erfassen Sie Folgendes, bevor Sie Bindungs-, Proxy-, Tailscale- oder Kanalrichtlinien ändern:

Gateway-Host, Betriebssystembenutzer und Zustandsverzeichnis (Standard: ~/.openclaw).
Gateway-URL und Bindungsmodus (gateway.bind; Standardport: 18789).
Authentifizierungsmodus, Quelle für Token/Passwort oder Identitätsquelle des vertrauenswürdigen Proxys.
Jeder aktivierte Kanal und ob er Direktnachrichten, Gruppen oder Webhooks akzeptiert.
Agenten, die für nicht lokale Absender erreichbar sind.
Tool-Profil, Sandbox-Modus und Richtlinie für privilegierte Tools für jeden erreichbaren Agenten.
Externe Anmeldedaten, die diesen Agenten zur Verfügung stehen.
Sicherungsort für ~/.openclaw/openclaw.json und Anmeldedaten.

Wenn mehr als eine Person dem Bot Nachrichten senden kann, behandeln Sie dies als gemeinsam delegierte Tool-Berechtigung und nicht als Host-Isolation pro Benutzer.

Grundlegende Prüfungen

Führen Sie vor der Zugriffsfreigabe Folgendes aus:

bash

openclaw doctoropenclaw security auditopenclaw security audit --deepopenclaw health

Beheben Sie zuerst kritische Befunde. Akzeptieren Sie Warnungen nur, wenn sie für die Bereitstellung beabsichtigt und dokumentiert sind. Unter Prüfungen des Sicherheitsaudits finden Sie die Bedeutung jedes checkId und den zugehörigen Korrekturschlüssel.

Übergeben Sie Anmeldedaten zur Remote-Validierung per CLI ausdrücklich:

bash

openclaw gateway probe --url ws://127.0.0.1:18789 --token "$OPENCLAW_GATEWAY_TOKEN"

Gehen Sie nicht davon aus, dass Anmeldedaten aus der lokalen Konfiguration für eine ausdrücklich angegebene Remote-URL gelten.

Minimaler sicherer Ausgangszustand

Verwenden Sie diese Struktur als Ausgangspunkt für freigegebene Bereitstellungen:

json5

{  gateway: {    bind: "loopback",    auth: {      mode: "token",      token: "replace-with-a-long-random-token",    },  },  session: {    dmScope: "per-channel-peer",  },  agents: {    defaults: {      sandbox: { mode: "non-main" },    },  },  tools: {    profile: "messaging",    exec: { security: "deny", ask: "always" },    elevated: { enabled: false },  },}

Lockern Sie jeweils nur eine Kontrolle: Fügen Sie eine spezifische Kanal-Zulassungsliste hinzu, bevor Sie schreibfähige Tools aktivieren, oder aktivieren Sie einen Reverse-Proxy, bevor Sie Remote-Datenverkehr der Control UI akzeptieren.

tools.exec.security: "deny" blockiert alle Exec-Aufrufe, einschließlich unbedenklicher Diagnosen. Wenn Diagnosen oder Befehle mit geringem Risiko erforderlich sind, lockern Sie dies erst, nachdem Sie die konkreten Absender, Agenten, Befehle und den Genehmigungsmodus ausgewählt haben, die Ihrem Bedrohungsmodell entsprechen.

Freigabe von Direktnachrichten und Gruppen

Messaging-Kanäle sind Oberflächen für nicht vertrauenswürdige Eingaben. Bevor Sie Direktnachrichten oder Gruppen zulassen:

Bevorzugen Sie dmPolicy: "pairing" oder eine strikte allowFrom-Liste gegenüber dmPolicy: "open".
Kombinieren Sie "*"-Zulassungslisten nicht mit umfassendem Tool-Zugriff.
Verlangen Sie Erwähnungen in Gruppen, sofern der Raum nicht streng kontrolliert wird.
Legen Sie session.dmScope: "per-channel-peer" (oder "per-account-channel-peer" für Kanäle mit mehreren Konten) fest, wenn mehrere Personen dem Bot Direktnachrichten senden können, damit Direktnachrichtensitzungen keinen Kontext gemeinsam nutzen.
Leiten Sie gemeinsam genutzte Kanäle an Agenten mit minimalen Tools und ohne persönliche Anmeldedaten weiter.

Durch die Kopplung wird der Absender berechtigt, den Bot auszulösen. Sie macht diesen Absender nicht zu einer separaten Host-Sicherheitsgrenze.

Prüfungen für Reverse-Proxys

Für identitätsbasierte Proxys:

Der Proxy muss Benutzer authentifizieren, bevor er Anfragen an den Gateway weiterleitet.
Eine Firewall- oder Netzwerkrichtlinie muss den direkten Zugriff auf den Gateway-Port blockieren.
gateway.trustedProxies darf ausschließlich die Quell-IP-Adressen des Proxys enthalten.
Der Proxy muss vom Client bereitgestellte Identitäts- und Weiterleitungsheader entfernen oder überschreiben.
Legen Sie gateway.auth.trustedProxy.allowUsers fest, wenn der Proxy mehr als eine Zielgruppe bedient.
Verwenden Sie gateway.auth.trustedProxy.allowLoopback nur für einen Proxy auf demselben Host, wenn lokalen Prozessen vertraut wird und der Proxy die Identitätsheader kontrolliert.

Führen Sie nach Proxy-Änderungen openclaw security audit --deep aus. Befunde zu vertrauenswürdigen Proxys sind besonders aussagekräftig, da der Proxy zur Authentifizierungsgrenze wird.

Überprüfung von Tools und Sandbox

Bevor Sie einen Agenten für Remote-Absender freigeben:

Prüfen Sie, welche Sitzungen auf dem Host und welche in der Sandbox ausgeführt werden.
Verweigern Sie die Ausführung auf dem Host oder verlangen Sie dafür eine Genehmigung.
Lassen Sie privilegierte Tools deaktiviert, sofern sie nicht von einem bestimmten vertrauenswürdigen Absender benötigt werden.
Vermeiden Sie Browser-, Canvas-, Node-, Cron-, Gateway- und Tools zum Erzeugen von Sitzungen für offene oder teilweise offene Messaging-Oberflächen.
Beschränken Sie Bind-Mounts eng; vermeiden Sie Pfade zu Anmeldedaten, Home-Verzeichnissen, Docker-Sockets und Systempfaden.
Verwenden Sie separate Gateways, Betriebssystembenutzer oder Hosts für wesentlich unterschiedliche Vertrauensgrenzen.

Wenn Remote-Benutzern nicht vollständig vertraut wird, muss die Isolation durch separate Bereitstellungen erfolgen, nicht nur durch Prompts oder Sitzungsbezeichnungen.

Validierung nach Änderungen

Nach jeder Änderung der Freigabe:

Führen Sie openclaw security audit --deep erneut aus.
Bestätigen Sie, dass eine autorisierte Verbindung erfolgreich hergestellt wird.
Bestätigen Sie, dass ein nicht autorisierter Absender oder eine nicht autorisierte Browsersitzung abgewiesen wird.
Bestätigen Sie, dass Geheimnisse in Protokollen unkenntlich gemacht werden.
Bestätigen Sie, dass die Weiterleitung von Direktnachrichten und Gruppen nur den vorgesehenen Agenten erreicht.
Bestätigen Sie, dass Tools mit hohen Auswirkungen eine Genehmigung anfordern oder abgewiesen werden.
Dokumentieren Sie die akzeptierten verbleibenden Warnungen.

Fahren Sie erst mit der nächsten Freigabeänderung fort, wenn die aktuelle Änderung verstanden ist.

Rücksetzplan

Falls der Gateway möglicherweise zu weitgehend freigegeben ist: