OpenClaw kennt ein häufiges Schein-Grün: openclaw gateway status meldet RPC als gesund, der Client wirft aber gateway closed (1000) oder nach einem Upgrade sind Tools plötzlich weg. Dieser Artikel folgt Symptom → wahrscheinliche Ursache → Prüfbefehle → Fix, deckt die drei häufigsten Klassen ab—Token, Scopes, Workspace-Pfade und Modell-Backends (einschließlich CLI-only-Routen, die Tools abschalten)—und liefert ein sechsstufiges Recovery-Runbook sowie die relevanten Logzeilen unter systemd und Docker. Zusammen mit den Artikeln Produktions-Observability, Security-Hardening und Cross-Platform-Installation liegt der Fokus hier auf Verbindungs- und Session-Konsistenz: zuerst den Pfad reparieren, dann Monitoring und Änderungssteuerung dem Observability-Guide übergeben.
Gateway-Control-Plane-Sonden beantworten oft nur, ob der Prozess läuft und der Port antwortet. Clientfehler wie gateway closed (1000) folgen häufig auf ein vom Server geschlossenes WebSocket/Session oder Drift bei Auth und Policy. Nutzen Sie die sieben Punkte als Erstlinien-Checkliste: je mehr zutreffen, desto weniger sollten Sie auf UI-Reload setzen—führen Sie stattdessen den geordneten Neustart und die Konfigurationsvalidierung aus Abschnitt 3 aus.
Sonden-Grün als End-to-End-Grün: RPC OK im Status ist eine enge Prüfung; Gerätebefehle und Tool-Kanäle können bei fehlenden Scopes oder abgelaufener Session dennoch scheitern.
Token-Drift: Umgebungsvariablen, Konfigurationsdateien und das vom Gateway geladene Token sind nicht dieselbe Kopie; Rotation nur auf einer Seite erzeugt sporadischen Erfolg und Massenfehler.
Workspace-Pfad-Mismatch: zeigt agents.defaults.workspace auf ein altes Verzeichnis oder stimmen Container-Binds nicht, kann die Tool-Schicht ablehnen oder sofort trennen.
CLI-only-Modell-Backends: manche *-cli/...-Routen deaktivieren Datei-Tools bewusst; das wirkt wie „Gateway online, Tools weg“ und lässt sich leicht mit closed(1000) verwechseln.
Doppelprozess nach Upgrade: Paket aktualisiert, aber altes Gateway hält den Port oder PID-Dateien blieben; der neue Prozess startet halb, Sonden treffen den alten Listener.
Verschärfte Security-Policy: nach dmPolicy / networkPolicy kann der Handshake gelingen und das erste Paket fällt der Policy zum Opfer; vergleichen Sie Allowlists im Artikel Security-Hardening.
Kein minimales Repro-Paket: Tickets mit halber Fehlerzeile ohne CLI-Version, Config-Auszug oder letzte Änderung zwingen die zweite Linie zu Raten und verlängern die Recovery.
Die gemeinsame Wurzel ist, mehrschichtige Gesundheit in einem verteilten System auf ein einzelnes Boolean zu komprimieren. Als Nächstes mappt eine Tabelle Ihre sichtbaren Symptome auf die zuerst auszuführenden Befehle.
Tabelle oben im On-Call-Runbook: exakt den sichtbaren String abstimmen, dann den kürzesten Prüfpfad wählen. Unterbefehle hängen von Ihrer OpenClaw-Version ab; die Namen unten sind beispielhaft.
| Sie sehen | Wahrscheinliche Ursache | Zuerst ausführen |
|---|---|---|
| RPC OK, aber Gerät/Kanal meldet closed(1000) | Session-Scope passt nicht zur Aktion oder Token weicht vom Gateway-Runtime ab | openclaw status --all; Token-Quellen nachziehen; Allowlists in der Security-Config prüfen |
| Nach Upgrade sind alle Tools ausgegraut | Modell-Routing auf CLI-only oder Gateway ohne Neustart, neue Config nicht geladen | openclaw models list; CLI-only verlassen, dann openclaw gateway restart |
| Mal Erfolg, meist Massenfehler | Mehrere Terminals mit verschiedenen Tokens oder Reverse-Proxy mit alten Verbindungen | Env aus einer Shell vereinheitlichen; Client-Sessions leeren; Proxy-Idle-Timeout prüfen |
| Pfad-Tools lehnen ab | Workspace-Config stimmt nicht mit dem echten Repo-Pfad | openclaw config get agents.defaults.workspace mit Platte vergleichen |
| Trennung direkt nach Policy-Änderung | dmPolicy / networkPolicy verschärft; erstes Paket abgewiesen | Abschnitt Security-Hardening erneut lesen; für bekannte Session kurz lockern zum Test |
Sonden-Grün belegt nur, dass die Control Plane lebt; zuverlässig arbeiten können Sie erst, wenn Token, Workspace, Modell-Backend und Policy zusammenpassen.
Ausführlichere Logs und Rollback-Taktik: Artikel Produktions-Observability. Hier geht es darum, in etwa zehn Minuten zwischen „Neustart + Validierung“ und „Config-Rollback“ zu entscheiden.
The order deliberately places low-cost steps first and config rollback later, so you do not open firewalls or reinstall immediately. In production, note in the ticket whether impact is “this CLI only” or “multi-user sessions.”
Freeze concurrent work: ask teammates to pause new sessions and batch jobs so a Gateway restart is not drowned in reconnect storms.
Capture a state snapshot: run openclaw --version, openclaw status --all (if available), and save output; record recent token rotation or openclaw.json edits.
Validate workspace and model routing: confirm workspace points at a real directory; use openclaw models list to ensure you did not select a CLI-only backend by mistake.
Run doctor / validate: use the CLI’s openclaw doctor, config:validate, or equivalent to fix obvious mismatches.
Restart Gateway in order: openclaw gateway restart (or restart the systemd unit / container) so the old process exits before the new one listens.
Minimal acceptance tests: one read-only tool call and one write call; only then reopen for others. If it still fails, go to section 4 for system logs.
openclaw --version openclaw status --all 2>&1 | tee /tmp/openclaw-status.txt openclaw config get agents.defaults.workspace openclaw models list openclaw doctor openclaw gateway restart # Then run one minimal read tool call and one write call to verify session and scope
Note: when the Gateway runs on a dedicated remote Mac, long SSH sessions and GUI prompts can still interrupt the toolchain; for stable unattended execution, pair with the directory and session isolation checklist in the agent node article.
If section 3’s restart still yields closed(1000), suspect first a process that never exited or drifted bind mounts inside a container. As in the observability article: establish who is listening and which user started it before debating config.
systemd (bare-metal Linux): use systemctl status to see whether the main process is crash-looping; journalctl -u <unit> -n 200 --no-pager for close codes and policy keywords. Docker Compose: align timestamps with docker compose ps and docker compose logs --tail=200 gateway. If you deployed with the Linux systemd + Tunnel guide, also confirm the tunnel and loopback binding are not pointing at a stale port.
Warning: do not temporarily expose the Gateway to the public internet to “test connectivity” before you know which interface is listening; validate inside the constraints of the security hardening article so troubleshooting does not become an incident.
These fields shorten the second round of diagnosis; redact before sharing externally.
Running the Gateway only on a laptop is fragile to sleep, OS updates, and multi-user desktop sessions; a small Linux box often lacks the macOS toolchain and graphical edge cases you need. When OpenClaw must sit on a long-lived, contract-friendly execution tier, a dedicated remote Mac is usually steadier than repeatedly borrowing hardware. Compared to building your own Mac rack, NodeMini Mac Mini cloud rental makes it easier to define a repeatable node profile so “Gateway + toolchain” hands off like a VPS estate.
Probes cover a narrow path; session, scope, token, and model backend can still be out of sync. Follow section 3 for an ordered restart and run doctor/validate. To plan execution-tier capacity, see Mac Mini rental rates and the help center.
Check model routing for a CLI-only backend; confirm the Gateway restarted and loaded new config; then verify workspace paths and complete token rotation across CLI and service.
Open the blog OpenClaw category for install, systemd, Docker, security, and observability posts; cross-check connectivity baselines in the help center.