Zum Hauptinhalt springen

Documentation Index

Fetch the complete documentation index at: https://docs.openclaw.ai/llms.txt

Use this file to discover all available pages before exploring further.

Verwenden Sie diese Seite für die Inbetriebnahme am ersten Tag und den Betrieb ab Tag 2 des Gateway-Dienstes.

Deep troubleshooting

Symptomorientierte Diagnose mit exakten Befehlsabfolgen und Log-Signaturen.

Configuration

Aufgabenorientierte Einrichtungsanleitung und vollständige Konfigurationsreferenz.

Secrets management

SecretRef-Vertrag, Verhalten von Runtime-Snapshots und Migrations-/Reload-Vorgänge.

Secrets plan contract

Exakte Ziel-/Pfadregeln für secrets apply und ref-only-Verhalten von auth-Profilen.

​
5-Minuten-Start lokal

1

Start the Gateway

openclaw gateway --port 18789
# debug/trace mirrored to stdio
openclaw gateway --port 18789 --verbose
# force-kill listener on selected port, then start
openclaw gateway --force
2

Verify service health

openclaw gateway status
openclaw status
openclaw logs --follow
Gesunde Ausgangslage: Runtime: running, Connectivity probe: ok und Capability: ..., passend zu Ihrer Erwartung. Verwenden Sie openclaw gateway status --require-rpc, wenn Sie einen RPC-Nachweis mit Lesebereich benötigen, nicht nur Erreichbarkeit.
3

Validate channel readiness

openclaw channels status --probe
Bei einem erreichbaren Gateway führt dies Live-Prüfungen pro Account-Channel und optionale Audits aus. Wenn das Gateway nicht erreichbar ist, fällt die CLI auf reine Konfigurationszusammenfassungen der Channels zurück, statt Live-Prüfungsausgaben zu liefern.
Der Reload der Gateway-Konfiguration überwacht den aktiven Konfigurationsdateipfad (aufgelöst aus Profil-/Status-Defaults oder aus OPENCLAW_CONFIG_PATH, wenn gesetzt). Der Standardmodus ist gateway.reload.mode="hybrid". Nach dem ersten erfolgreichen Laden bedient der laufende Prozess den aktiven In-Memory-Konfigurationssnapshot; ein erfolgreicher Reload tauscht diesen Snapshot atomar aus.

​
Runtime-Modell

  • Ein dauerhaft laufender Prozess für Routing, Control Plane und Channel-Verbindungen.
  • Einzelner multiplexter Port für:
    • WebSocket-Control/RPC
    • HTTP-APIs, OpenAI-kompatibel (/v1/models, /v1/embeddings, /v1/chat/completions, /v1/responses, /tools/invoke)
    • Control-UI und Hooks
  • Standard-Bind-Modus: loopback.
  • Auth ist standardmäßig erforderlich. Shared-Secret-Setups verwenden gateway.auth.token / gateway.auth.password (oder OPENCLAW_GATEWAY_TOKEN / OPENCLAW_GATEWAY_PASSWORD), und Reverse-Proxy-Setups außerhalb von loopback können gateway.auth.mode: "trusted-proxy" verwenden.

​
OpenAI-kompatible Endpunkte

OpenClaws wichtigste Kompatibilitätsoberfläche ist jetzt:
  • GET /v1/models
  • GET /v1/models/{id}
  • POST /v1/embeddings
  • POST /v1/chat/completions
  • POST /v1/responses
Warum diese Auswahl wichtig ist:
  • Die meisten Integrationen mit Open WebUI, LobeChat und LibreChat prüfen zuerst /v1/models.
  • Viele RAG- und Memory-Pipelines erwarten /v1/embeddings.
  • Agent-native Clients bevorzugen zunehmend /v1/responses.
Planungshinweis:
  • /v1/models ist agent-first: Es gibt openclaw, openclaw/default und openclaw/<agentId> zurück.
  • openclaw/default ist der stabile Alias, der immer dem konfigurierten Standard-Agent zugeordnet ist.
  • Verwenden Sie x-openclaw-model, wenn Sie einen Backend-Provider-/Modell-Override wünschen; andernfalls bleibt das normale Modell- und Embedding-Setup des ausgewählten Agent maßgeblich.
Alle diese Endpunkte laufen auf dem Hauptport des Gateway und verwenden dieselbe vertrauenswürdige Operator-Auth-Grenze wie die übrige Gateway-HTTP-API.

​
Port- und Bind-Priorität

EinstellungAuflösungsreihenfolge
Gateway-Port--port → OPENCLAW_GATEWAY_PORT → gateway.port → 18789
Bind-ModusCLI/Override → gateway.bind → loopback
Installierte Gateway-Dienste speichern den aufgelösten --port in Supervisor-Metadaten. Nachdem Sie gateway.port geändert haben, führen Sie openclaw doctor --fix oder openclaw gateway install --force aus, damit launchd/systemd/schtasks den Prozess auf dem neuen Port startet. Der Gateway-Start verwendet denselben effektiven Port und Bind, wenn er lokale Control-UI-Origins für Nicht-loopback-Binds initialisiert. Beispielsweise initialisiert --bind lan --port 3000 http://localhost:3000 und http://127.0.0.1:3000, bevor die Runtime-Validierung ausgeführt wird. Fügen Sie Remote-Browser-Origins, etwa HTTPS-Proxy-URLs, explizit zu gateway.controlUi.allowedOrigins hinzu.

​
Hot-Reload-Modi

gateway.reload.modeVerhalten
offKein Konfigurations-Reload
hotNur hot-safe Änderungen anwenden
restartBei reloadpflichtigen Änderungen neu starten
hybrid (Standard)Hot-Apply, wenn sicher, Neustart, wenn erforderlich

​
Operator-Befehlssatz

openclaw gateway status
openclaw gateway status --deep   # adds a system-level service scan
openclaw gateway status --json
openclaw gateway install
openclaw gateway restart
openclaw gateway stop
openclaw secrets reload
openclaw logs --follow
openclaw doctor
gateway status --deep dient zusätzlicher Diensterkennung (LaunchDaemons/systemd-System- Units/schtasks), nicht einer tieferen RPC-Health-Prüfung.

​
Mehrere Gateways (derselbe Host)

Die meisten Installationen sollten ein Gateway pro Maschine ausführen. Ein einzelnes Gateway kann mehrere Agents und Channels hosten. Sie benötigen mehrere Gateways nur, wenn Sie bewusst Isolation oder einen Rescue-Bot wünschen. Nützliche Prüfungen: 
openclaw gateway status --deep
openclaw gateway probe
Zu erwarten:
  • gateway status --deep kann Other gateway-like services detected (best effort) melden und Bereinigungshinweise ausgeben, wenn veraltete launchd/systemd/schtasks-Installationen noch vorhanden sind.
  • gateway probe kann vor multiple reachable gateways warnen, wenn mehr als ein Ziel antwortet.
  • Wenn das beabsichtigt ist, isolieren Sie Ports, Konfiguration/Status und Workspace-Roots pro Gateway.
Checkliste pro Instanz:
  • Eindeutiger gateway.port
  • Eindeutiger OPENCLAW_CONFIG_PATH
  • Eindeutiger OPENCLAW_STATE_DIR
  • Eindeutiger agents.defaults.workspace
Beispiel: 
OPENCLAW_CONFIG_PATH=~/.openclaw/a.json OPENCLAW_STATE_DIR=~/.openclaw-a openclaw gateway --port 19001
OPENCLAW_CONFIG_PATH=~/.openclaw/b.json OPENCLAW_STATE_DIR=~/.openclaw-b openclaw gateway --port 19002
Detaillierte Einrichtung: /gateway/multiple-gateways.

​
Remotezugriff

Bevorzugt: Tailscale/VPN. Fallback: SSH-Tunnel. 
ssh -N -L 18789:127.0.0.1:18789 user@host
Verbinden Sie Clients anschließend lokal mit ws://127.0.0.1:18789.
SSH-Tunnel umgehen die Gateway-Auth nicht. Bei Shared-Secret-Auth müssen Clients auch über den Tunnel token/password senden. Bei identitätsführenden Modi muss die Anfrage weiterhin diesen Auth-Pfad erfüllen.
Siehe: Remote Gateway, Authentifizierung, Tailscale.

​
Supervision und Dienstlebenszyklus

Verwenden Sie überwachte Ausführungen für produktionsähnliche Zuverlässigkeit. 
openclaw gateway install
openclaw gateway status
openclaw gateway restart
openclaw gateway stop
Verwenden Sie openclaw gateway restart für Neustarts. Verketten Sie openclaw gateway stop und openclaw gateway start nicht als Ersatz für einen Neustart.Unter macOS verwendet gateway stop standardmäßig launchctl bootout — dadurch wird der LaunchAgent aus der aktuellen Boot-Sitzung entfernt, ohne eine Deaktivierung dauerhaft zu speichern, sodass die KeepAlive-Auto-Wiederherstellung nach unerwarteten Abstürzen weiterhin funktioniert und gateway start sauber wieder aktiviert. Um Auto-Respawn über Neustarts hinweg dauerhaft zu unterdrücken, übergeben Sie --disable: openclaw gateway stop --disable.LaunchAgent-Labels sind ai.openclaw.gateway (Standard) oder ai.openclaw.<profile> (benanntes Profil). openclaw doctor auditiert und repariert Abweichungen in der Dienstkonfiguration.

​
Schneller Pfad für das Dev-Profil

openclaw --dev setup
openclaw --dev gateway --allow-unconfigured
openclaw --dev status
Defaults umfassen isolierten Status/isolierte Konfiguration und den Basis-Gateway-Port 19001.

​
Protokoll-Kurzreferenz (Operator-Sicht)

  • Der erste Client-Frame muss connect sein.
  • Gateway gibt einen hello-ok-Snapshot zurück (presence, health, stateVersion, uptimeMs, Limits/Policy).
  • hello-ok.features.methods / events sind eine konservative Discovery-Liste, kein generierter Dump jeder aufrufbaren Helper-Route.
  • Anfragen: req(method, params) → res(ok/payload|error).
  • Häufige Events umfassen connect.challenge, agent, chat, session.message, session.tool, sessions.changed, presence, tick, health, heartbeat, Lebenszyklus-Events für Pairing/Approval und shutdown.
Agent-Ausführungen sind zweistufig:
  1. Sofortige Accepted-Bestätigung (status:"accepted")
  2. Finale Completion-Antwort (status:"ok"|"error"), mit gestreamten agent-Events dazwischen.
Siehe vollständige Protokolldokumentation: Gateway-Protokoll.

​
Betriebsprüfungen

​
Liveness

  • WS öffnen und connect senden.
  • hello-ok-Antwort mit Snapshot erwarten.

​
Readiness

openclaw gateway status
openclaw channels status --probe
openclaw health

​
Gap Recovery

Events werden nicht erneut abgespielt. Aktualisieren Sie bei Sequenzlücken den Status (health, system-presence), bevor Sie fortfahren.

​
Häufige Fehlersignaturen

SignaturWahrscheinliches Problem
refusing to bind gateway ... without authNicht-Loopback-Bindung ohne gültigen Gateway-Auth-Pfad
another gateway instance is already listening / EADDRINUSEPortkonflikt
Gateway start blocked: set gateway.mode=localConfig ist auf Remote-Modus gesetzt, oder der Local-Mode-Stempel fehlt in einer beschädigten Config
unauthorized during connectAuth-Abweichung zwischen Client und Gateway
Für vollständige Diagnoseleitern verwenden Sie Gateway-Fehlerbehebung.

​
Sicherheitsgarantien

  • Gateway-Protokoll-Clients schlagen schnell fehl, wenn Gateway nicht verfügbar ist (kein impliziter Fallback auf einen direkten Kanal).
  • Ungültige/nicht verbindende erste Frames werden abgewiesen und geschlossen.
  • Ordnungsgemäßes Herunterfahren gibt vor dem Schließen des Sockets ein shutdown-Ereignis aus.
Verwandt:

​
Verwandt