Der Befehl sessions_spawn schlägt sofort fehl, wenn versucht wird, isolierte Logik-Subagenten zu starten, unabhängig von der Laufzeitkonfiguration (acp, subagent oder isolated).

Fehlerausgabe

$ openclaw sessions_spawn --agent my-agent --runtime acp -- "analyze this data"

Error: gateway closed (1008): pairing required
    at WebSocket.<anonymous> (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:142:15)
    at WebSocket.emit (node:events:518:28)
    at WebSocket.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:89:12)
    at SockJS.onClose (/path/to/node_modules/@openclaw/core/src/gateway/ws-client.js:56:14)

Session spawn failed: Connection rejected by gateway security policy

Gateway-Protokolle

[gateway] WARN  [12:34:56.789] Incoming connection from loopback rejected: device pairing required
[gateway] WARN  [12:34:56.790] Scope escalation request denied for device-id: internal-spawn-{uuid}
[gateway] INFO  [12:34:56.791] Connection closed: code=1008, reason=pairing required

Kontext der Konfiguration

Die folgende Konfiguration ist in openclaw.json vorhanden:

{
  "acp": {
    "allowedAgents": ["my-agent", "analysis-agent"]
  }
}

Verhaltensmanifestationen

• Sub-Agent-Spawn schlägt bei jeder Aufruf konsistent fehl
• Manuelle Gerätefreigabe über openclaw devices approve löst das Problem nicht
• Der Fehler tritt auch beim Spawnen von Agenten auf, die auf localhost oder 127.0.0.1 abzielen
• Die Hauptsitzung funktioniert normal weiter; nur gespawnte Subagenten sind betroffen
• Alle zugehörigen Probleme (#12210, #21445, #30740, #59428) zeigen identische Fehlercodes und Verhaltensweisen

Architekturanalyse

Der sessions_spawn-Mechanismus in OpenClaw v2026.4.12 baut eine interne WebSocket-Verbindung vom gespawnten Subagent-Prozess zum Gateway auf. Diese Verbindung durchläuft die Loopback-Schnittstelle (127.0.0.1) und unterliegt der Pairing-Durchsetzungsschicht des Gateways.

Fehlersequenz

1. Spawn-Initierung: Die Hauptsitzung ruft sessions_spawn auf und erstellt einen neuen isolierten Prozess für den Zielagenten.
2. Gateway-Handshake: Der Subagent-Prozess initiiert eine WebSocket-Verbindung zu ws://localhost:{gateway-port}/acp.
3. Geräteidentifikation: Die Pairing-Middleware des Gateways weist der internen Verbindung eine transiente Gerätekennung zu: internal-spawn-{uuid}.
4. Scope-Escalation-Block: Der gespawnte Agent erhöhte Berechtigungen (Agent-Ausführung, Sitzungsverwaltung) an, die das Gateway als erforderlich für ein gepaartes Gerät klassifiziert.
5. 1008-Ablehnung: Das Gateway beendet die Verbindung mit dem WebSocket-Schließcode 1008 (Policy Violation) mit der Begründung "pairing required".

Technische Ursache

Die Regression stammt aus einer Änderung in v2026.4.12, die den impliziten Pairing-Umgehung für interne Loopback-Verbindungen entfernte. Frühere Versionen behandelten 127.0.0.1-Verbindungen als vertrauenswürdig und gewährten automatisch den internal:spawn-Scope. Das Update vereinheitlichte die Pairing-Durchsetzung über alle Netzwerkschnittstellen und brach unbeabsichtigt den Sub-Agent-Spawn-Pfad.

Die Gateway-Konfiguration unterscheidet nicht zwischen:

• Externen Geräteverbindungen (die legitimerweise Pairing erfordern)
• Internen Loopback-Verbindungen von gespawnten Subagenten

Code-Pfad-Analyse

// gateway/src/middleware/pairing-enforcer.ts (v2026.4.12)
function enforcePairing(ws, req) {
  const remoteAddr = req.socket.remoteAddress;
  
  // REMOVED: Legacy bypass for loopback
  // if (remoteAddr === '127.0.0.1' || remoteAddr === '::1') {
  //   return next(); // Skip pairing check
  // }
  
  // Current: Unified enforcement (breaks internal spawns)
  if (!isDevicePaired(req.headers['x-device-id'])) {
    ws.close(1008, 'pairing required');
    return;
  }
}

Konfigurationslücke

Die Einstellung acp.allowedAgents steuert, welche Agenten aufgerufen werden können, gewährt jedoch keine Pairing-Befreiung für die interne Gateway-Verbindung des Agenten. Dies sind orthogonale Sicherheitskontrollen, die fälschlicherweise gleichgesetzt wurden.

Option 1: Loopback-Pairing-Befreiung konfigurieren (Empfohlen)

Fügen Sie eine explizite Loopback-Pairing-Befreiung in der Gateway-Konfiguration hinzu:

Schritt 1: Lokalisieren oder erstellen Sie die Gateway-Konfigurationsdatei:

# Linux/macOS
~/.config/openclaw/gateway.json

# Windows
%APPDATA%\openclaw\gateway.json

# Docker container
/path/to/config/gateway.json

Schritt 2: Fügen Sie die pairing-Befreiungseinstellungen hinzu:

{
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  },
  "security": {
    "devicePairing": {
      "requireForExternal": true,
      "skipForLoopback": true
    }
  }
}

Schritt 3: Starten Sie das Gateway neu:

# If running as a service
sudo systemctl restart openclaw-gateway

# Or if running directly
openclaw gateway stop
openclaw gateway start

Option 2: Lokale Laufzeit anstelle von ACP verwenden

Vermeiden Sie den ACP-Gateway-Pfad vollständig, indem Sie die lokale Laufzeit für gespawnte Agenten verwenden:

# Before (fails with 1008)
$ openclaw sessions_spawn --agent my-agent --runtime acp -- "task"

# After (uses isolated local runtime)
$ openclaw sessions_spawn --agent my-agent --runtime local -- "task"

Option 3: Umgebungsvariablen-Überschreibung

Setzen Sie die Umgebungsvariable OPENCLAW_INTERNAL_SPAWN_BYPASS vor dem Start des Gateways:

# Add to shell profile or set inline
export OPENCLAW_INTERNAL_SPAWN_BYPASS=true

# Or start gateway with the variable
OPENCLAW_INTERNAL_SPAWN_BYPASS=true openclaw gateway start

Option 4: Pairing-Durchsetzung deaktivieren (Nur Entwicklung)

Deaktivieren Sie für Entwicklungsumgebungen das Pairing vollständig:

{
  "gateway": {
    "port": 18789,
    "security": {
      "enforcePairing": false
    }
  }
}

WARNUNG: Diese Einstellung deaktiviert das Pairing für ALLE Verbindungen, einschließlich externer Geräte. Nicht in der Produktion verwenden.

Konfiguration Vorher vs. Nachher

Vorher (openclaw.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  }
}

Nachher (gateway.json):

{
  "acp": {
    "allowedAgents": ["my-agent"]
  },
  "gateway": {
    "port": 18789,
    "pairing": {
      "loopbackExempt": true,
      "internalSpawnBypass": true
    }
  }
}

Nach Anwendung der Lösung verifizieren Sie die Behebung mit den folgenden Schritten:

Schritt 1: Gateway-Konfiguration bestätigen

$ openclaw gateway config show

Die erwartete Ausgabe sollte enthalten:

{
  "pairing": {
    "loopbackExempt": true,
    "internalSpawnBypass": true
  }
}

Schritt 2: Gateway neu starten und Protokolle prüfen

$ openclaw gateway restart
$ openclaw gateway logs --tail 20

Erwartete Protokolleinträge:

[gateway] INFO  [12:00:00.000] Gateway started on port 18789
[gateway] INFO  [12:00:00.001] Loopback pairing exemption: enabled
[gateway] INFO  [12:00:00.002] Internal spawn bypass: enabled

Schritt 3: Sub-Agent-Spawn testen

$ openclaw sessions_spawn --agent my-agent --runtime acp -- echo "test"

Erwartete Ausgabe:

Spawning agent 'my-agent' with runtime 'acp'...
Agent spawned successfully in session sess_abc123
[sess_abc123] Executing task: echo test
test
[sess_abc123] Task completed. Exit code: 0

Schritt 4: Sitzungsisolation verifizieren

$ openclaw sessions list

Die erwartete Ausgabe sollte die Hauptsitzung und die gespawnte Subagent-Sitzung anzeigen:

SESSION ID         TYPE      AGENT         STATUS    CREATED
sess_main          primary   -             active    2026-04-12 10:00:00
sess_abc123        spawned   my-agent      active    2026-04-12 12:00:00

Schritt 5: Multi-Agent-Orchestrierung testen

$ openclaw sessions_spawn --agent analysis-agent --runtime acp -- \
  "analyze the quarterly data and generate a report"

Erwartet: Agent spawnt ohne 1008-Fehler und beginnt mit der Aufgabenausführung.

Verifizierungs-Exit-Codes

• 0: Lösung erfolgreich, Sub-Agent wurde korrekt gespawnt
• 1008: Lösung nicht angewendet, Pairing-Durchsetzung noch aktiv
• 7: Agent-ID nicht in acp.allowedAgents gefunden

Umgebungsspezifische Fallen

• Docker-Container-Netzwerk: Bei der Ausführung von OpenClaw in Docker kann Loopback-Verkehr anders geroutet werden. Verwenden Sie den host-Netzwerkmodus oder stellen Sie sicher, dass network=host in docker-compose vorhanden ist:

  services:
    openclaw:
      network_mode: host
  

• Windows WSL2: Das Loopback-Verhalten unterscheidet sich zwischen Windows-Host und WSL2. Das Gateway lauscht möglicherweise auf verschiedenen Schnittstellen. Überprüfen Sie mit:

  netstat -tlnp | grep openclaw
  

• macOS Sandbox: Das Konfigurationsverzeichnis kann abweichen: ~/Library/Application Support/openclaw/

Konfigurationsfallen

• Falscher Speicherort der Konfigurationsdatei: Die Gateway-Einstellungen müssen in gateway.json sein, nicht in openclaw.json. Letzteres behandelt Agent-Berechtigungen; ersteres behandelt Gateway-Sicherheit.
• Konfigurationszusammenführungsprobleme: Bei Verwendung von Umgebungsvariablen zusammen mit Konfigurationsdateien haben Umgebungsvariablen Vorrang. Überprüfen Sie mit:

  openclaw gateway config show --merged
  

• Veralteter Gateway-Prozess: Änderungen an gateway.json erfordern einen vollständigen Neustart, nicht nur ein Neuladen. Verifizieren Sie, dass der Prozess tatsächlich neu gestartet wurde:

  ps aux | grep openclaw-gateway
  

Authentifizierungsfallen

• Persistenz des Geräte-Pairing-Status: Genehmigte Geräte werden lokal gespeichert. Das Löschen von App-Daten kann genehmigte Loopback-Geräte ungültig machen:

  # Linux
  rm -rf ~/.local/share/openclaw/devices/*
  macOS
  rm -rf ~/Library/Application\ Support/openclaw/devices/*
  

• Token-Ablauf: Gespawnte Subagenten erben Authentifizierungstoken mit begrenzter Lebensdauer. Für langlebige Aufgaben stellen Sie sicher, dass die Hauptsitzung aktiv bleibt.

Laufzeitauswahl-Fallen

• Laufzeit-Mismatch: --runtime acp leitet durch das ACP-Gateway (von Pairing betroffen), während --runtime local es vollständig umgeht. Verwenden Sie local nur, wenn die Agent-Logik keine Gateway-Dienste erfordert.
• Ungültige Agent-ID: Die Agent-ID in sessions_spawn muss exakt mit einem Eintrag in acp.allowedAgents übereinstimmen (Groß-/Kleinschreibung beachten).

Bekannte Regressionen

• Dieses Problem trat erstmals in v2026.4.12 auf und besteht in nachfolgenden Patch-Releases fort, bis die Konfiguration internalSpawnBypass angewendet wird.
• Version v2026.4.11 und früher sind nicht betroffen und können als Downgrade-Pfad verwendet werden, wenn sofortige Funktionalität erforderlich ist.

Direkt zugehörig

• WebSocket 1008: Policy Violation
  Die Pairing-Durchsetzung des Gateways, die die interne Spawn-Verbindung schließt. Dies ist der primäre Fehler, der das Sub-Agent-Spawnen blockiert.
• Fehler #12210: "sessions_spawn schlägt mit 'pairing required' bei Neuinstallation fehl"
  Originaler Bericht dieses Regressionsmusters in der v2026.4.x-Serie.
• Fehler #21445: "ACP-Laufzeit-Subagenten können keine Verbindung zum Gateway herstellen"
  Verfolgt das Scope-Escalation-Verweigerungsproblem für ACP-vermittelte Spawns.
• Fehler #30740: "Loopback-Verbindungen werden fälschlicherweise als ungepaarte Geräte gekennzeichnet"
  Dokumentiert die Fehlklassifizierung interner Verbindungen als externe Geräte.
• Fehler #59428: "Geräte-Pairing erforderlich trotz OPENCLAW_SKIP_PAIRING=true"
  Umgebungsvariablen-Umgehung funktioniert nicht für gespawnte Subagenten.

Sekundär zugehörige Fehler

• Fehler #45102: "sessions_spawn gibt Exit-Code 7 für erlaubte Agenten zurück"
  Konfigurationsfehlpaarung, die Spawn-Ablehnung vor der Pairing-Prüfung verursacht.
• Fehler #33456: "Gateway schließt Verbindung mit 1011 bei langlebigen Spawns"
  Unabhängiger Fehler, der nach erfolgreichem Spawn auftritt, separates Timeout-Problem.
• Fehler #77890: "Sub-Agent-Sitzung verwaist nach Hauptsitzungs-Trennung"
  Problem bei der Sitzungslebenszyklusverwaltung in Multi-Agent-Workflows.

Fehlercode-Referenz