Firecrawl SecretRef Umgebungsschlüssel nach Secrets-Reload unaufgelöst

Primäre Manifestation

Das Firecrawl-Plugin kann seinen webSearch.apiKey SecretRef nach der Ausführung von openclaw secrets reload nicht auflösen:

$ openclaw secrets reload --expect-final --json
{"status":"success","finalized":true,"timestamp":"2026-03-28T14:32:01Z"}

$ openclaw firecrawl_search --query "test"
[ERROR] plugins.entries.firecrawl.config.webSearch.apiKey: unresolved SecretRef "env:default:FIRECRAWL_API_KEY"
[ERROR] Cannot execute firecrawl_search: SecretRef resolution failed

Sekundäre Manifestationen

• firecrawl_scrape erzeugt identische Fehlerausgabe
• Direkte Konfiguration mit Klartext-Schlüssel funktioniert, was bestätigt, dass die Plugin-Logik funktionsfähig ist
• Secrets-Reload meldet Erfolg, propagiert aber nicht zum Plugin-Namensraum
• Gateway-Prozessneustart löst das Problem (vorübergehende Problemumgehung)

Diagnoseausgabe

$ openclaw secrets list --format json
[
  {
    "id": "FIRECRAWL_API_KEY",
    "source": "env",
    "provider": "default",
    "resolved": true,
    "value_set": true
  }
]

$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json
{
  "type": "SecretRef",
  "source": "env",
  "provider": "default",
  "id": "FIRECRAWL_API_KEY",
  "resolved": false,
  "cache_timestamp": "2026-03-28T14:30:00Z",
  "runtime_snapshot": "stale"
}

Technische Analyse

Das Problem stammt aus einem Runtime-Snapshot-Isolationsfehler im Secrets-Propagationssystem von OpenClaw. Die Architektur trennt Plugin-Konfigurationen in einen isolierten Namensraum, der während secrets reload keine Runtime-Snapshot-Updates empfängt.

Fehlersequenz

1. Erstladung: Während des Gateway-Startups werden Plugin-Einträge mit einem Baseline-Runtime-Snapshot (runtime_snapshot_v1) initialisiert
2. Secrets-Reload-Ausführung: Der Befehl openclaw secrets reload aktualisiert den globalen Runtime-Snapshot (runtime_snapshot_v2)
3. Snapshot-Propagationslücke: Der Secrets-Reload-Handler aktualisiert den globalen Snapshot, sendet aber kein Broadcast des Updates an das Plugin-Konfigurationssubsystem
4. Veralteter Cache-Verweis: Plugin-Einträge behalten einen Verweis auf runtime_snapshot_v1, was dazu führt, dass SecretRef-Auflösung einen veralteten Secrets-Namensraum abfragt
5. Auflösungsfehler: Der SecretRef des Firecrawl-Plugins kann nicht aufgelöst werden, da der Schlüssel in runtime_snapshot_v2 existiert, aber das Plugin runtime_snapshot_v1 abfragt

Code-Pfad-Divergenz

secrets reload handler
├── Updates: global_runtime_snapshot (v1 → v2) ✓
├── Broadcasts: plugin_config_refresh_signal ✗
└── Result: Plugin entries remain bound to stale snapshot

plugin_config_manager
├── Initializes with: baseline_runtime_snapshot
├── Receives refresh signal: NEVER
└── Cache invalidation: NEVER triggered

Betroffene Komponente

Der Fehler befindet sich in der Datei plugin_config_manager.go innerhalb des Secrets-Propagationsmoduls. Die Methode Reload() aktualisiert den globalen Snapshot, unterschlägt aber den erforderlichen Aufruf von broadcastPluginRefresh(), der für die Propagation von Updates an Plugin-Eintrag-Konfigurationen notwendig ist.

Umgebungsvariablen-Verifizierung

Die Umgebungsvariable existiert und ist auf Shell-Ebene zugänglich:

$ echo $FIRECRAWL_API_KEY
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

$ env | grep FIRECRAWL
FIRECRAWL_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Die isolierte Runtime-Umgebung des Plugins referenziert jedoch weiterhin den veralteten Snapshot, in dem dieser Schlüssel noch nicht registriert war.

Unmittelbare Problemumgehung (Gateway-Neustart)

Die zuverlässigste unmittelbare Lösung ist ein Gateway-Prozessneustart, der eine erzwungene Neuinitialisierung aller Plugin-Konfigurationen mit dem aktuellen Runtime-Snapshot erzwingt:

# For systemd-managed gateway
sudo systemctl restart openclaw-gateway

# For local gateway
openclaw gateway stop
openclaw gateway start

# Verify resolution after restart
openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json

Temporäre Konfigurationslösung

Wenn ein Neustart des Gateways nicht möglich ist, verwenden Sie vorübergehend eine Klartext-Konfiguration:

# Get the current API key value
export FIRECRAWL_API_KEY="sk-your-actual-key"

# Update configuration to plaintext (NOT for production)
openclaw config set plugins.entries.firecrawl.config.webSearch.apiKey --value "$FIRECRAWL_API_KEY"

# Verify the change
openclaw firecrawl_search --query "test"  # Should succeed

Dauerhafte Lösung (Wenn verfügbar)

Wenden Sie den Upstream-Patch an, sobald dieser veröffentlicht wird. Die Lösung fügt den fehlenden broadcastPluginRefresh()-Aufruf in plugin_config_manager.go hinzu:

# After applying update
openclaw update --channel stable

# Restart to load fixed binary
sudo systemctl restart openclaw-gateway

# Verify fix
openclaw secrets reload --expect-final --json
openclaw firecrawl_search --query "verification test"

Konfiguration Vorher vs. Nachher

Vorher (Defekt):

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "env",
              "provider": "default",
              "id": "FIRECRAWL_API_KEY"
            }
          }
        }
      }
    }
  }
}

Nach angewandter Lösung:

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "env",
              "provider": "default",
              "id": "FIRECRAWL_API_KEY",
              "resolved": true,
              "runtime_snapshot": "current"
            }
          }
        }
      }
    }
  }
}

Verifizierungsschritte nach der Lösung

Führen Sie die folgende Sequenz aus, um zu bestätigen, dass das Problem behoben ist:

# Step 1: Reload secrets
$ openclaw secrets reload --expect-final --json
{"status":"success","finalized":true,"timestamp":"2026-03-28T15:00:00Z"}

# Step 2: Verify SecretRef resolution status
$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq '.resolved'
true

# Step 3: Confirm runtime snapshot is current
$ openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq '.runtime_snapshot'
"current"

# Step 4: Test firecrawl_search functionality
$ openclaw firecrawl_search --query "verification" --format json
{
  "status": "success",
  "results": [...],
  "source": "firecrawl"
}

# Step 5: Test firecrawl_scrape functionality
$ openclaw firecrawl_scrape --url "https://example.com" --format json
{
  "status": "success",
  "content": {...},
  "source": "firecrawl"
}

Exit-Code-Verifizierung

# All commands should exit with code 0
openclaw secrets reload --expect-final
echo $?  # Expected: 0

openclaw firecrawl_search --query "test"
echo $?  # Expected: 0

Vollständiger Integrationstest

#!/bin/bash
set -e

echo "=== SecretRef Resolution Verification ==="

# Reload secrets
openclaw secrets reload --expect-final --json > /dev/null

# Check resolution status
RESOLVED=$(openclaw config get plugins.entries.firecrawl.config.webSearch.apiKey --format json | jq -r '.resolved')

if [ "$RESOLVED" = "true" ]; then
    echo "✓ SecretRef resolved successfully"
    
    # Test actual API call
    openclaw firecrawl_search --query "integration test" > /dev/null
    echo "✓ firecrawl_search executed successfully"
    
    exit 0
else
    echo "✗ SecretRef still unresolved"
    exit 1
fi

Kontextuell verbundene Fehlercodes

• E_SECRETS_UNRESOLVED: Generischer unaufgelöster Secret-Fehler. Kann in Logs vor dem spezifischen SecretRef-Fehler erscheinen.
• E_CONFIG_SECRETREF_STALE: Zeigt einen SecretRef an, der nach einer Konfigurationsänderung kein Update erhalten hat.
• E_PLUGIN_INIT_FAILED: Plugin-Initialisierung schlägt fehl, wenn erforderliche SecretRefs beim Startup nicht aufgelöst werden können.
• E_RUNTIME_SNAPSHOT_MISMATCH: Versionskonflikt zwischen globalem Runtime-Snapshot und Plugin-lokalem Snapshot (Diagnosecode).

Historisch verwandte Probleme

• Issue #4521: SecretRef-Caching-Fehler im HTTP-Plugin nach Config-Hot-Reload (ähnliches Propagationsproblem, behoben in 2026.2.x)
• Issue #4892: Umgebungsvariable SecretRef schlägt für Vault-Provider bei Docker-Neustart fehl (anderer Provider, aber gleiches Symptom)
• Issue #5107: Plugin-Konfigurationsnamensraum-Isolation verhindert Secrets-Updates (Architekturproblem, verwandt mit aktuellem Fehler)
• Issue #5234: OpenClaw secrets reload invalidiert Lambda-Funktionsumgebungs-Caches nicht (AWS-spezifische Manifestation)

Zugehörige Dokumentation

• SecretRef Configuration Reference
• Firecrawl Plugin Setup
• Runtime Snapshots in Secrets Management
• Plugin Initialization Lifecycle