Primäre Manifestation

Die Ausführung von openclaw approvals get --gateway erzeugt eine abgeschnittene Ausgabe mit einem irreführenden Gesundheitsstatus:

$ openclaw approvals get --gateway
gateway timeout after 10000ms
...
Effective Policy -> Config unavailable.
[Command exits with non-zero status]

Sekundäre Manifestationen

• Exit-Code: Ungleich Null (typischerweise 124 für Timeout oder 1 für allgemeinen Fehler)
• Zeitverhalten: Befehl schlägt zwischen 10s und 11s nach Aufruf fehl
• Partielle Ausgabe: Approvals-Snapshot-Daten können vor dem Timeout-Fehler erscheinen
• Effective Policy-Abschnitt: Wird als wörtlicher Text Config unavailable. anstatt tatsächlicher Richtliniendaten gerendert

Gateway-Status bestätigt irreführenden Bericht

$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Version:     2026.4.12
Last Check:  2026-04-15T10:30:00Z

Erfolgreiche Ausführung mit verlängertem Timeout

$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running
...
Effective Policy -> orion: approved, admin: approved
[Command exits 0]

Sequenzielles RPC-Aufruf-Muster

Der Befehl openclaw approvals get --gateway führt zwei unterschiedliche RPC-Aufrufe sequenziell aus:

1. Aufruf 1: Approvals-Snapshot (approvals.get_snapshot)
   • Ruft den vollständigen Approvals-Datensatz ab
   • Wird typischerweise in 50-500ms auf gesunden Netzwerken abgeschlossen
   • Füllt erfolgreich die primäre Ausgabetabelle
2. Aufruf 2: Gateway-Konfiguration (config.get)
   • Ruft die Gateway-Konfiguration für das Effective Policy-Rendering ab
   • Erforderlich für die Effective Policy-Spalte in der Ausgabe
   • Auf leistungsschwachen Hosts kann dieser Aufruf 30-45 Sekunden dauern

Timeout-Behandlungsarchitektur

// Pseudocode-Darstellung des CLI-Verhaltens
func getApprovalsWithGateway(timeout_ms int) {
    // Schritt 1: Immer erfolgreich
    snapshot := rpc.Call("approvals.get_snapshot")
    printSnapshot(snapshot)
// Schritt 2: Schlägt bei Timeout fehl, wird stillschweigend abgefangen
defer func() {
    if r := recover(); r != nil {
        print("Effective Policy -> Config unavailable.")
    }
}()

// Dieser Aufruf blockiert und berücksichtigt den Timeout
config := rpc.CallWithTimeout("config.get", timeout_ms)
printEffectivePolicy(config)
}

Unzureichender Standard-Timeout

Mehrdeutigkeit der Fehlermeldung

Die CLI vermischt zwei unterschiedliche Fehlerarten:

• Echte Nichtverfügbarkeit: Gateway hat keine Konfiguration oder Konfigurationsdienst ist ausgefallen
• Timeout: Gateway ist gesund, aber RPC dauerte länger als der CLI-Timeout

Beide Szenarien erzeugen identische Ausgabe: Config unavailable.

Betroffener Code-Pfad

// Datei: cli/commands/approvals/get.go (abgeleitet)
type GetCommand struct {
    Timeout int `flag:"timeout,10000"`  // <-- Fest codierter Standardwert
}
func (c *GetCommand) Execute(ctx context.Context) error {
snapshot, err := c.client.GetSnapshot(ctx)
if err != nil {
return fmt.Errorf(“snapshot fetch failed: %w”, err)
}
// Gateway-Modus erfordert Konfiguration für Effective Policy
if c.gatewayMode {
    config, err := c.client.GetConfig(ctx, rpc.WithTimeout(c.Timeout))
    if err != nil {
        // Mehrdeutige Fehlerbehandlung
        fmt.Println("Config unavailable.")
        // Gibt Erfolg zurück, da partielle Daten abgerufen wurden
        return nil
    }
    // ... Konfiguration rendern ...
}
}

Sofortige Problemumgehung (Benutzerseitig)

# Timeout für den Approvals-Befehl temporär überschreiben
openclaw approvals get --gateway --timeout 60000

Permanente Konfigurationskorrektur

Fügen Sie Folgendes zu Ihrer OpenClaw CLI-Konfigurationsdatei hinzu:

# Datei: ~/.config/openclaw/CLI config oder Äquivalent
# Für Linux/macOS: ~/.config/openclaw/config.yaml
# Für Windows: %APPDATA%\openclaw\config.yaml

approvals:
  get:
    timeout: 60000  # 60 Sekunden in Millisekunden
    gateway:
      timeout: 60000

Umgebungsvariablen-Überschreibung

# Timeout über Umgebungsvariable setzen (falls unterstützt)
export OPENCLAW_APPROVALS_TIMEOUT=60000
export OPENCLAW_GATEWAY_TIMEOUT=60000

# Dann ohne expliziten Timeout-Flag ausführen
openclaw approvals get --gateway

Persistenter Alias (Bash/Zsh)

# Zu ~/.bashrc oder ~/.zshrc hinzufügen
alias openclaw-approvals='openclaw approvals get --gateway --timeout 60000'

# Verwendung
openclaw-approvals

Systemd-Dienst-Überschreibung (Daemon-Modus)

# Drop-in-Override erstellen
mkdir -p /etc/systemd/system/openclaw-gateway.service.d/

cat > /etc/systemd/system/openclaw-gateway.service.d/timeout.conf << EOF
[Service]
Environment="OPENCLAW_RPC_TIMEOUT=60000"
ExecStartPost=/usr/bin/openclaw approvals warm-cache --timeout 60000
EOF

systemctl daemon-reload
systemctl restart openclaw-gateway

Vorher-Nachher-Vergleich

gateway timeout after 10000ms
Effective Policy -> Config unavailable.

gateway: healthy
Effective Policy -> orion: approved

Vorbereitende Prüfungen

# 1. OpenClaw-Version verifizieren
$ openclaw version
openclaw v2026.4.12 (commit: abc123)

# 2. Gateway-Status verifizieren
$ openclaw gateway status
Runtime:     running
RPC Probe:   ok
Uptime:      7d 12h 34m

Funktionale Verifizierung

# Mit verlängertem Timeout testen - sollte erfolgreich abgeschlossen werden
$ openclaw approvals get --gateway --timeout 60000
gateway: healthy
runtime: running

APPROVALS SNAPSHOT
==================
ID       | Subject     | Policy      | Expires
---------|-------------|-------------|------------------
uuid-001 | alice       | orion       | 2026-04-20
uuid-002 | bob         | admin       | 2026-04-25

Effective Policy
================
orion -> approved
admin -> approved

# Exit-Code auf 0 verifizieren
$ echo $?
0

Bestätigung der Timeout-Erkennung funktioniert

# Test, dass künstlich kurzer Timeout den erwarteten Fehler erzeugt
$ openclaw approvals get --gateway --timeout 100
gateway timeout after 100ms

# Non-Zero Exit-Code verifizieren
$ echo $?
124

Konfigurationsdatei-Syntax validieren

# Bei Verwendung der Konfigurationsdatei-Überschreibung YAML-Syntax validieren
$ cat ~/.config/openclaw/config.yaml | python3 -c "import yaml, sys; yaml.safe_load(sys.stdin)"
# Keine Ausgabe bedeutet gültiges YAML

# Effektive Konfiguration prüfen
$ openclaw config show --verbose 2>&1 | grep -i timeout

Regressionstest-Suite

# Testskript für CI/CD erstellen
#!/bin/bash
set -e

TIMEOUT_MS=60000
EXPECTED_EXIT=0

openclaw approvals get --gateway --timeout $TIMEOUT_MS > /tmp/output.txt
ACTUAL_EXIT=$?

if [ $ACTUAL_EXIT -ne $EXPECTED_EXIT ]; then
    echo "FAIL: Expected exit $EXPECTED_EXIT, got $ACTUAL_EXIT"
    cat /tmp/output.txt
    exit 1
fi

if grep -q "Config unavailable" /tmp/output.txt; then
    echo "FAIL: Output contains 'Config unavailable'"
    cat /tmp/output.txt
    exit 1
fi

if ! grep -q "Effective Policy" /tmp/output.txt; then
    echo "FAIL: Output missing 'Effective Policy' section"
    cat /tmp/output.txt
    exit 1
fi

echo "PASS: Approvals command completed successfully"
exit 0

Umgebungsspezifische Fallen

• Docker-Container-Ressourcenbeschränkungen

  # Ausführung innerhalb von speicher-/cpu-limitierterem Container kann Latenz verschlimmern
  docker run --memory=256m --cpus=0.5 openclaw:latest approvals get --gateway --timeout 60000

  Lösung: Container-Ressourcen erhöhen oder --network host verwenden, um Netzwerkoverhead zu reduzieren.

• Kubernetes Pod QoS-Klasse

  Pods mit BestEffort QoS können inkonsistente Planungsverzögerungen erleben.

  # Sicherstellen, dass Pod-Spezifikation garantierte Ressourcen enthält
  resources:
    requests:
      memory: "256Mi"
      cpu: "500m"
    limits:
      memory: "512Mi"
      cpu: "1000m"

• SSH-Tunnel-Overhead

  Befehle, die über SSH-Tunnel ausgeführt werden, fügen Latenz hinzu. Timeout benötigt möglicherweise +10s Puffer.

  # Vom Remote-Host (innerhalb SSH-Sitzung)
  ssh user@gateway-host "openclaw approvals get --gateway --timeout 60000"

Konfigurationsfehler

• YAML-Einrückungsprobleme

  # FALSCH - Tabs oder falsche Einrückung
  approvals:
  get:
    timeout: 60000
  RICHTIG - korrekte YAML-Einrückung
  approvals:
  get:
  timeout: 60000

• Widersprüchliche Umgebungsvariablen

  Umgebungsvariablen können Konfigurationsdateieinstellungen unerwartet überschreiben.

  # Prüfen, was tatsächlich angewendet wird
  openclaw debug config --show-sources

• Veralteter Konfigurationscache

  CLI kann Konfiguration cachen. Erzwungenes Neuladen.

  openclaw config reload
  openclaw approvals get --gateway --timeout 60000

Fehlinterpretationsrisiken

• "Config unavailable" als Richtlinienverlust interpretieren

  Operatoren könnten in Panik geraten und unnötige Richtlinien-Neuimplementierung einleiten.

  Abhilfe: Immer zuerst openclaw gateway status ausführen, um den tatsächlichen Gateway-Gesundheitszustand zu bestätigen.

• Regression nach Upgrade annehmen

  Ein Upgrade von OpenClaw kann neue Konfigurationsabrufpfade einführen.

  Abhilfe: Changelog auf approvals oder gateway-Änderungen prüfen, bevor Regression angenommen wird.

Netzwerküberlegungen

# Latenztest zum Gateway
ping -c 5 gateway-host

# RPC-Round-Trip-Timing
openclaw debug rpc ping --count 5 --format json

# Firewall/MTU-Probleme
openclaw gateway status --verbose
# Achten auf: "RPC latency: Xms" in der Ausgabe

Versionsspezifische Hinweise

Häufige zugehörige Fehlercodes

• ETIMEDOUT / Exit 124

  Allgemeines RPC-Timeout. Zeigt an, dass der clientseitige Timeout ausgelöst wurde, bevor der Server antwortete.

  # Beispiel
  openclaw approvals get --gateway
  # Error: context deadline exceeded: timeout 10000ms

• ECONNREFUSED

  Gateway läuft nicht oder ist nicht erreichbar. Unterscheidet sich von Timeout.

  $ openclaw gateway status
  Error: dial tcp 127.0.0.1:9090: connect: connection refused

• gateway: unreachable

  Gateway-Prozess ist ausgefallen oder Netzwerkpfad ist blockiert.

• config.get: context canceled

  Client hat die Anfrage abgebrochen (z.B. Strg+C) während des Fluges.

Historische Probleme

• Issue #4521: Gateway-Status hängt auf langsamen Netzwerken

  Ähnliches Timeout-Handling-Problem im gateway status-Befehl. Behoben durch Hinzufügen von --timeout-Flag in v2026.3.0.

• Issue #3890: Config unavailable trotz gesundem Gateway

  Früherer Bericht desselben Symptommusters. Ursache war Initialisierungsrennbbedingung des Konfigurationsdienstes (jetzt behoben).

• Issue #5102: Approval exec Fallback-Timeout

  Execution-Approvals im Fallback-Modus hatten fest codierten 5s-Timeout, der falsche Negative verursachte.

Bekannte Falsch-Positiv-Muster

Referenz der Diagnosebefehle

# Vollständige Diagnose-Suite
openclaw gateway status --verbose
openclaw config show --effective
openclaw approvals list --all --format json
openclaw debug rpc stats --since 1h

Eskalationspfad

1. openclaw gateway status ausführen, um den tatsächlichen Gateway-Gesundheitszustand zu bestätigen
2. openclaw approvals get --gateway --timeout 60000 mit verlängertem Timeout ausführen
3. Wenn verlängerter Timeout fehlschlägt, folgende sammeln: openclaw debug logs --since 5m
4. Issue einreichen mit: Version, OS, verwendetem Timeout und vollständiger Fehlerausgabe