proxy.enabled · OPENCLAW_PROXY_URL · Acht-Schritte-Runbook · VNC-Checks
OpenClaw v2026.4.27 formalisiert operativ geführtes ausgehendes HTTP-Forward-Proxy-Routing für die Laufzeit: Aktivierung über Konfiguration (proxy.enabled, proxy.proxyUrl) oder rein in der Shell OPENCLAW_PROXY_URL, mit strikter Validierung von http://-Forward-Proxy-URLs und Bereinigung des Proxy-Dispatcher-Zustands beim Beenden. Dieselbe Version schärft das Gateway-Bootverhalten und setzt die Migration zu manifest-first Plugin-Metadaten fort — das verändert, wie lange ein „kalter Start“ wirkt, wenn Provider-Discovery oder Pricing-Refresh um Bandbreite konkurrieren. In Banken, OEM-Werken oder Regionalbüros mit zwingendem Egress-Host scheitert es selten an „OpenClaw kennt keinen Proxy“, sondern daran, dass Loopback-Konsolentraffic auf dem falschen Pfad landet oder TLS-Inspektion Katalog-Downloads halb durchreißt. Dieser Leitfaden trennt eingehenden Reverse-Proxy-TLS (wie Nutzer Gateway erreichen) von ausgehender Forward-Proxy-Politik (wie Gateway OpenAI, Anthropic, Slack-APIs usw. erreicht), liefert eine Acht-Schritte-Runbook, eine Symptommatrix, vier tickettaugliche Fakten und eine VNC-Checkliste auf einem gemieteten Mac. Ergänzend: Triage Firmenzugang / VNC und Gateway HTTPS-Reverse-Proxy — sie adressieren andere Kanten desselben Graphen.
Praktisch bedeutet das für Bereitschaftsteams: Jede Änderung am Ausgang braucht denselben Besitzer wie DNS-Zertifikatsrotationen vor der öffentlichen Kante — sonst interpretiert das Produktteam langsame Kanäle als „Provider down“, während in Wahrheit ein PAC-File den Forwarder überschreibt. Dokumentieren Sie explizit, ob der Daemon per launchd, systemd oder manuellem Screen läuft; nur dann stimmen Variablenlisten zwischen interaktiver Shell und Dienstumgebung überein. Auf Remote-Macs ohne dedizierte Grafiksitzung verlieren Sie außerdem die Chance, Browser-Devtools und Systemproxy visuell gegen die Ticketwerte zu halten — genau dafür ist Abschnitt fünf gedacht.
Wenn Sie parallel große Migrationen fahren, halten Sie migrate & Plugin-Verzeichnisse und Netzwerkänderungen zeitlich auseinander oder labeln Sie Smoke-Runs eindeutig; gemischte Deployments verwischen Boot-Zeitlinien und machen Regressionen schwer beweisbar. Für Secrets am Proxy-Endpunkt gehört ein Verweis auf SecretRef und Audit in dieselbe Change-Story wie Firewall-Ausnahmen — Klartext-Passwörter in Shell-Profilen sind der häufigste Grund für 407-Schleifen zwischen zwei gültigen Konfigurationen.
Schließlich: Ein Laptop mit wechselndem Gast-WLAN macht PAC-Tests unzuverlässig; ein stationärer Cloud-Mac mit Snapshot isoliert Proxyexperimente und verkürzt Eskalationen. Nach erfolgreichem Staging promoten Sie Policy teamweit und verknüpfen wiederkehrende Symptome mit häufigen Fehlerbildern, damit der nächste Dienst nicht bei Null beginnt.
macOS „Automatische Proxy-Konfiguration“ hilft Safari und vielen GUI-Apps, aber Node-basierte CLIs ignorieren sie oft, bis Sie klassische Variablen wie HTTP_PROXY exportieren. OpenClaws explizite Schalter reduzieren Ratespiele: Sie deklarieren den Forwarder einmal auf OpenClaw-Ebene, validieren das Schema und verlassen sich auf Shutdown-Hooks, damit nach Rotationen kein veralteter Dispatcher hängen bleibt. Das meldet sich nicht automatisch bei Chrome-Profilen für Meet oder Browserautomatisierung — die folgen eigenen Proxy-Politiken; Ihr Runbook muss beide Stacks nennen.
Release Notes betonen zudem nur-Loopback-Gateway-Bypass-Semantik: Wenn lokale Control-UI über einen corporate MITM gezwungen wird, entstehen WebSocket-Fehler, die wie Anwendungsbugs wirken. Behandeln Sie „localhost-Konsole“ und „Internet-APIs“ als zwei Routingtabellen; eine Zeile aus der anderen zu kopieren ist der klassische Mitternachts-Incident.
In stark regulierten Umgebungen sollten Sie zusätzlich festhalten, welche Root-CAs der Forwarder ausstellt und ob Zertifikatspinner nach Updates dokumentiert sind — sonst interpretiert das Team sporadische TLS-Fehler als Modellausfall. Halten Sie Messscripts klein und wiederholbar: zwei Provider-Endpunkte plus optional die PAC-URL genügen oft, um „halb geblockt“ von „vollständig offline“ zu trennen.
Betreiberabsicht: auditierter Egress mit rotierenden Credentials statt Ad-hoc-Exports in zwölf Shell-Profilen.
TLS-Realität: Transparente Proxys müssen firmenvertrauenswürdige Roots an OpenClaws TLS-Stack ausliefern; sonst jagen Sie Phantom-„Model-Ausfall“-Fehler.
Trennung vom Eingehenden: TLS-Terminierung auf nginx/Caddy vor Gateway konfiguriert nicht automatisch das Upstream-Fetch-Verhalten — Dokumentation getrennt halten.
Secrets-Hygiene: Proxy-Passwörter wo möglich mit SecretRef-Workflows ausrichten.
Telemetrie: Handshake-Zeiten vor und nach Proxy-Aktivierung erfassen und an Change-Tickets anhängen.
Nutzen Sie die Matrix als Routing-Funktion für Bereitschaft. Wenn die letzte Spalte „fälschlich gelesen als …“ lautet, wiederholen Sie nicht dasselbe Playbook mit anderem Namen.
| Symptom | Zuerst prüfen | Dann | Fälschliche Lesart |
|---|---|---|---|
| Gateway gesund, Kanäle stocken Minuten | Ausgehende Katalog-/Pricing-Fetches durch Proxy blockiert | Pfad zur Plugin-Manifest-Regeneration | „Telegram-Plugin-Regression“ |
| 407 / Proxy-Auth-Schleifen | Credentials zwischen launchd und interaktiven Shells uneinheitlich | PAC überschreibt explizite URL | „Provider-Rate-Limit“ |
| Control-UI-WS-Fehler | Browser erzwingt Firmenproxy für localhost | Upgrade-Header am Reverse Proxy übersehen | „OpenClaw-SSL-Bug“ |
| CPU-Spitzen nur beim Boot | Parallele Manifest-Scans | Plattenkonkurrenz auf kleinen Cloud-Datenträgern | „Größeres LLM nötig“ |
Messen Sie Boot-bis-bereit und Kanal-bereit unabhängig; fusionieren Sie Zeitleisten erst, wenn beide grün sind.
v2026.4.27 bringt weitergehende Zuverlässigkeitsarbeit (Telegram-Grenzen, Slack-Socket-Timeouts, Gateway-Prewarm-Reihenfolge). Koinzidiert Ihre Regression mit Kanal-Fixes, bisectieren Sie durch temporäres Deaktivieren nicht-kritischer Plugins statt den Proxy jede Minute umzuschalten — sonst erzeugen Sie korrelierte Noise in den Logs.
Achten Sie bei gemischten Umgebungen auf Zeitzonen in Log-Aggregation: Ein Forwarder in UTC und Gateway-Logs in Lokalzeit verwandeln sonst harmloses Scheduling in falsche Kausalitäten. Ein kurzer Kommentar im Incident-Dokument reicht oft, um spätere Retro-Zeit zu sparen.
Sequenziell auf einem Staging-Host mit produktionsgleichem Egress ausführen. Proxy-URL, Auth-Domain und Notfall-Bypass-Genehmigung dokumentieren, bevor Produktion angetastet wird.
Versionen pinnen: openclaw --version muss v2026.4.27 (oder Ihren Patch) zeigen; Node-Distribution notieren.
Konfigurationen archivieren: Config-Roots plus launchd-Plist oder systemd-Fragmente tarballen.
Roher Egress-Test: unter demselben Dienstkonto curl -v gegen zwei Provider und ggf. die Firmen-PAC-URL.
OpenClaw-Proxy anwenden: strukturierte Keys aktivieren oder OPENCLAW_PROXY_URL nur in der Daemon-Umgebung; widersprüchliche Legacy-HTTP_PROXY-Duplikate vermeiden, sofern nicht zwingend.
Doctor-Gate: openclaw doctor; Schema-Warnungen vor Restart-Schleifen beheben.
Neustart & Zeitstempel: Wandzeit von Prozessstart bis erstem gesunden Kanal-Marker protokollieren.
Risikoarmes Chat-Sonde: Minimalprompt ohne schweres Tooling auf zwei Kanälen.
Notizen veröffentlichen: Änderung mit häufigen Fehlermustern verknüpfen für spätere Triage.
export OPENCLAW_PROXY_URL="http://proxy.corp.example.com:8080" openclaw doctor openclaw gateway restart
Hinweis: Keys entwickeln sich weiter; vertrauen Sie openclaw doctor und offizieller Doku mehr als kopierten YAML-Schnipseln.
Nach dem Smoke sollte das Ticket mindestens drei Zahlen enthalten: Dauer bis Gateway „ready“, Zeit bis erster Kanal „online“, und RTT-Sample für einen repräsentativen Provider-Call. Ohne diese Dreierbasis wiederholen Incident Bridges dieselbe Diskussion mit neuem Stress.
Unter demselben macOS-Benutzer wie der Gateway-Dienst ausführen. Log-Tailing allein über SSH übersieht browserseitige Proxy-Overrides.
| Check | Wie | Pass |
|---|---|---|
| Systemproxy | Netzwerk-Einstellungen / PAC. | Entspricht Policy; kein Drift. |
| Control UI | Browser-Devtools Netzwerk. | WS 101; kein Mixed Content. |
| Daemon-Umgebung | Parent-Umgebung inspizieren. | Entspricht Ticketwerten. |
| Doppel-curl | Zwei Provider durch Proxy. | Stabiles TLS ohne Retry-Sturm. |
| Kanal-Sonde | Risikoarme Nachricht. | Kein Retry-Sturm. |
Ein dedizierter Cloud-Mac isoliert Proxyexperimente von Roaming-WLAN-Profilen auf dem Laptop: Sie snapshotten ein Image, beweisen den Stack und promoten — günstiger als PAC-Kriege während eines Ausfalls auf einem geteilten Ultrabook. Dokumentieren Sie zudem, welcher Bildschirmfreigabe-Client genutzt wird; manche Viewer injizieren eigene Proxy-Defaults in eingebettete Browser.
Wenn mehrere Administratoren gleichzeitig eingeloggt sind, prüfen Sie kurz Fast User Switching und verwaiste Sessions — sie sind eine häufige Quelle für „Proxy gesetzt, aber Prozess sieht es nicht“. Ein konsistenter Single-User-Betrieb für Gateway vermeidet halbe Zustände.
Eingehendes TLS vs ausgehende Forward-Proxy-Verantwortung.
Lesen →Zuerst den Mac erreichen, dann OpenClaw-Egress tunen.
Lesen →Große Upgrades parallel zu Netzwerkänderungen.
Lesen →Kein automatischer Ersatz — beides bewusst angleichen und PAC-Overrides beachten.
Localhost-Konsolentraffic ausnehmen; upstream HTTPS über den genehmigten Forwarder senden.
Gateway-Boot-Zeitlinie und ausgehendes TLS prüfen, bevor Bundles neu installiert werden.
CLI deckt vieles; browsernahe Checks brauchen weiterhin VNC-Level-Verifikation.
Ausgangs-Proxy-Unterstützung verwandelt undurchsichtige „Slack klemmt“-Vorfälle in routbare Netzwerk-Tickets — aber nur bei Respekt vor Loopback-Semantik und erfassten Zeitleisten.
Ein Wechsel-Laptop mit wöchentlich neuem WLAN macht PAC-Tests laut; ein gemieteter Apple-Silicon-Mac liefert eine stationäre Sandbox.
Brauchen Sie diese Sandbox mit NDA-freundlichem Turnover? Nutzen Sie VNCMac: mehr zur Mietseite, Produktüberblick auf der Startseite, dann Abschnitt fünf auf dem Knoten wiederholen.