Primäre Fehlererscheinung

Wenn web_fetch-Anfragen über das Firecrawl-Plugin mit einer 1Password SecretRef für den API-Schlüssel geleitet werden, schlägt der Vorgang mit einem Authentifizierungsfehler fehl, obwohl das Gateway anzeigt, dass das Geheimnis ordnungsgemäß aufgelöst wurde.

shell

Terminal 1: Konfigurationsauflösungsstatus überprüfen

$ openclaw config get plugins.entries.firecrawl.config.webFetch.apiKey –verbose

sourceConfig: “op://openclaw/Firecrawl API key/credential” resolved: “••••••••••••••••” resolvedAt: “2026-04-15T10:23:41Z” status: “resolved”

shell

Terminal 2: web_fetch-Anfrage ausführen

$ openclaw tools web-fetch “https://example.com”

Error: Firecrawl API error (401): Unauthorized: Invalid token at FirecrawlProvider.fetch (firecrawl-provider.ts:147) at WebFetchTool.execute (web-fetch-tool.ts:89) at Gateway.handleToolCall (gateway.ts:204)

Diskrepanz bei der Konfigurationsinspektion

Die Laufzeitkonfigurationsansicht zeigt das Feld als resolved und masked, was darauf hindeutet, dass die Materialisierungsschicht die SecretRef akzeptiert hat. Der Firecrawl-Anfragepfad scheint jedoch entweder zu erhalten:

• Die rohe unaufgelöste `op://...`-Zeichenkette
• Einen veralteten oder falschen Konfigurations-Snapshot
• Einen Wert, der aufgelöst wurde, aber nicht an die Provider-Instanz weitergegeben wurde

Diagnose-CLI-Befehle

shell

Plugin-Registrierung und Laufzeitstatus überprüfen

openclaw plugins list –verbose | grep -A5 firecrawl

Den tatsächlich vom Provider verwendeten API-Schlüssel anzeigen

openclaw debug provider firecrawl –show-config

Trace-Logging für Geheimnisauflösung aktivieren

OPENCLAW_LOG_LEVEL=trace openclaw gateway start 2>&1 | grep -i “firecrawl|secretref|apiKey”

Umgebungskontext

• OpenClaw-Version: 2026.4.11
• Betriebssystem: Ubuntu (Linux-Kernel 5.15+)
• Laufzeitmodus: Gateway-Lokalmodus
• Geheimnis-Provider: 1Password CLI (`op://`-Schema)
• Gateway-Konfiguration: JSON-Konfigurationsdatei

Architektonischer Fehlerpunkt

Der Fehler stammt aus einem Konfigurations-Snapshot-Isolierungsfehler zwischen der Konfigurationsauflösungsschicht des Gateways und der Anfrageausführungsschicht des Firecrawl-Providers.

┌─────────────────────────────────────────────────────────────────────┐ │ GATEWAY-PROZESS │ ├─────────────────────────────────────────────────────────────────────┤ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Konfig-Lader │───▶│ Geheimnis- │───▶│ Laufzeit- │ │ │ │ (JSON/YAML) │ │ Auflöser │ │ Konfiguration │ │ │ │ │ │ (1Password CLI)│ │ Snapshot │ │ │ └─────────────────┘ └─────────────────┘ └────────┬────────┘ │ │ │ │ │ │ Snapshot │ │ │ kopiert │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ WebFetchTool │───▶│ FirecrawlProv │───▶│ Provider- │ │ │ │ (web-fetch) │ │ Instanz │ │ Initialisierung│ │ │ │ │ │ │ │ (ctor/Snapshot)│ │ │ └─────────────────┘ └─────────────────┘ └────────┬────────┘ │ │ │ │ │ │ verwendet │ │ ▼ │ │ ┌─────────────────┐ │ │ │ Firecrawl REST │ │ │ │ API-Aufruf │ │ │ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────────┘

Fehlersequenz

1. Konfigurations-Ladephase: Das Gateway lädt die JSON-Konfiguration mit `plugins.entries.firecrawl.config.webFetch.apiKey: "op://openclaw/Firecrawl API key/credential"`.
2. Geheimnis-Auflösungsphase: Der SecretResolver-Dienst verarbeitet die 1Password SecretRef und ruft das Klartext-Token ab. Die Laufzeitkonfigurationsansicht zeigt dies korrekt als aufgelöst und maskiert an.
3. Provider-Initialisierungsphase (FEHLER): Wenn FirecrawlProvider instanziiert wird, erhält er einen veralteten Konfigurations-Snapshot anstelle des nach der Auflösung aktuellen Konfigurationsobjekts. Der Konstruktor des Providers erfasst:

   // firecrawl-provider.ts - Konstruktor (fehlerhaft)
   constructor(config: FirecrawlConfig) {
     // Erfasst Konfigurations-Snapshot zum Initialisierungszeitpunkt
     this.apiKey = config.webFetch.apiKey;
     this.baseUrl = config.webFetch.baseUrl;
     // ...
   }

4. Anfrageausführungsphase: Wenn web_fetch aufgerufen wird, verwendet der Provider this.apiKey, das noch immer die rohe SecretRef-Zeichenkette "op://openclaw/Firecrawl API key/credential" enthält, da der Snapshot aufgenommen wurde, bevor die Geheimnisauflösung abgeschlossen war.
5. Firecrawl-API-Ablehnung: Die Firecrawl-API erhält die literale op://...-Zeichenkette als API-Schlüssel, was zu 401 Unauthorized führt.

Code-Pfad-Analyse

Die Grundursache manifestiert sich in der Initialisierungsreihenfolge innerhalb von src/plugins/firecrawl/firecrawl-provider.ts:

// Problematische Initialisierungsreihenfolge
class FirecrawlProvider {
  private apiKey: string;
  private baseUrl: string;

  // Wird beim Gateway-Start aufgerufen, erhält Pre-Resolution-Konfiguration
  constructor(config: FirecrawlConfig) {
    this.apiKey = config.webFetch.apiKey;  // ← Erhält "op://..."-Zeichenkette
    this.baseUrl = config.webFetch.baseUrl;
  }

  // Diese Methode wird zur Anfragezeit aufgerufen, verwendet aber den erfassten Wert
  async fetch(url: string): Promise<FetchResult> {
    const headers = {
      'Authorization': `Bearer ${this.apiKey}`,  // ← Sendet unaufgelöste Referenz
      'Content-Type': 'application/json'
    };
    // ...
  }
}

Kontrast zum funktionierenden Klartext-Pfad

Bei Verwendung einer Klartext-Konfiguration ist keine Geheimnisauflösung erforderlich:

{
  "plugins": {
    "entries": {
      "firecrawl": {
        "config": {
          "webFetch": {
            "apiKey": "fc-actual-token-plaintext"  // ← Direkte Zuweisung
          }
        }
      }
    }
  }
}

Der Provider empfängt und speichert das tatsächliche Token direkt und umgeht den fehlerhaften Snapshot-Mechanismus.

Verwandtes Architekturmuster

Dieser Fehler teilt Merkmale mit dem SecretRef-Laufzeitmaterialisierungsfehler #28359, bei dem Konfigurations-Snapshots, die in verschiedenen Lebenszyklusphasen aufgenommen wurden, inkonsistente Auflösungszustände enthalten. Der Konstruktor des Firecrawl-Providers erfasst den Zustand zum Initialisierungszeitpunkt, aber die Geheimnisauflösung erfolgt nach der Initialisierung für diesen spezifischen Konfigurationspfad.

Option 1: Lazy Resolution (Empfohlen)

Ändern Sie den Firecrawl-Provider so, dass die Geheimnisauflösung zur Anfragezeit und nicht zur Konstruktionszeit durchgeführt wird.

Datei: src/plugins/firecrawl/firecrawl-provider.ts

typescript // VORHER (fehlerhaft) class FirecrawlProvider { private apiKey: string;

constructor(config: FirecrawlConfig) { this.apiKey = config.webFetch.apiKey; // Erfasst bei Init }

async fetch(url: string): Promise { const response = await fetch(this.apiEndpoint, { headers: { ‘Authorization’: Bearer ${this.apiKey} } }); } }

// NACHHER (korrigiert) import { SecretResolver } from ‘@openclaw/core/secrets’;

class FirecrawlProvider { private config: FirecrawlConfig; private secretResolver: SecretResolver;

constructor(config: FirecrawlConfig, secretResolver: SecretResolver) { this.config = config; this.secretResolver = secretResolver; // Auflöser injizieren }

async fetch(url: string): Promise { // Zur Anfragezeit auflösen, nicht zur Konstruktionszeit const resolvedApiKey = await this.secretResolver.resolve( this.config.webFetch.apiKey );

const response = await fetch(this.apiEndpoint, {
  headers: { 'Authorization': `Bearer ${resolvedApiKey}` }
});

} }

Datei: src/plugins/firecrawl/plugin-registration.ts

typescript // VORHER export function registerFirecrawlPlugin(container: PluginContainer) { container.registerSingleton(FirecrawlProvider, (config) => new FirecrawlProvider(config) ); }

// NACHHER export function registerFirecrawlPlugin(container: PluginContainer) { container.registerSingleton(FirecrawlProvider, (config, secretResolver) => new FirecrawlProvider(config, secretResolver) ); }

Option 2: Post-Resolution Provider-Aktualisierung

Erzwingen Sie eine Provider-Aktualisierung nach Abschluss der Geheimnisauflösung im Gateway-Lebenszyklus.

Datei: src/gateway/boot.ts

typescript // Zur Gateway-Initialisierungssequenz hinzufügen async function initializeGateway(config: GatewayConfig) { // Phase 1: Konfiguration laden und Geheimnisse auflösen const resolvedConfig = await configResolver.resolveWithSecrets(config);

// Phase 2: Provider mit aufgelöster Konfiguration initialisieren await providerRegistry.initialize(resolvedConfig.plugins);

// Phase 3 (KORREKTUR): Alle Provider-Instanzen aktualisieren, um sicherzustellen, dass sie aufgelöste Werte verwenden await providerRegistry.refreshAll();

// Phase 4: Gateway starten await gateway.start(); }

Option 3: Umgebungsvariablen-Workaround (Sofortige Abhilfe)

Wenn Code-Änderungen nicht verfügbar sind, verwenden Sie Umgebungsvariablen-Injektion für den API-Schlüssel:

Schritt 1: Setzen Sie den API-Schlüssel in Ihrer Umgebung:

shell export FIRECRAWL_API_KEY=“your-actual-api-key-from-1password”

Schritt 2: Aktualisieren Sie die Konfiguration, um auf die Umgebungsvariable zu verweisen:

json { “plugins”: { “entries”: { “firecrawl”: { “enabled”: true, “config”: { “webFetch”: { “apiKey”: “${FIRECRAWL_API_KEY}”, “baseUrl”: “https://api.firecrawl.dev” } } } } } }

Schritt 3: Überprüfen Sie, dass die Umgebungsvariable zugänglich ist:

shell echo $FIRECRAWL_API_KEY

Sollte ausgeben: your-actual-api-key-from-1password

Bei direkter Verwendung der 1Password CLI:

export FIRECRAWL_API_KEY=$(op read “op://openclaw/Firecrawl API key/credential”)

Schritt 4: Überprüfen Sie, dass die Korrektur funktioniert

Nach Anwendung einer Korrektur führen Sie aus:

shell openclaw tools web-fetch “https://example.com”

Die erwartete Ausgabe sollte den abgerufenen HTML-Inhalt enthalten, keinen 401-Fehler.

Diagnose vor der Korrektur

Bestätigen Sie, dass der Fehler vorhanden ist, bevor Sie versuchen, ihn zu beheben:

shell

1. Überprüfen, dass die SecretRef konfiguriert ist

openclaw config get plugins.entries.firecrawl.config.webFetch.apiKey

Erwartete Ausgabe:

op://openclaw/Firecrawl API key/credential

2. Überprüfen, ob die 1Password CLI authentifiziert ist

op vault list

Erwartete Ausgabe:

Vaults in personal:

├── openclaw

└── …

3. Bestätigen, dass das Geheimnis existiert und zugänglich ist

op item get “Firecrawl API key” –vault openclaw

Erwartet: Item-Details mit Credential-Feld

4. web_fetch testen (sollte vor der Korrektur fehlschlagen)

openclaw tools web-fetch “https://httpbin.org/headers" –provider firecrawl

Erwartet (vor Korrektur):

Error: Firecrawl API error (401): Unauthorized: Invalid token

Erwartet (nach Korrektur):

{“headers”: {“Host”: “httpbin.org”, …}}

Verifizierungsschritte nach der Korrektur

Schritt 1: Geheimnisauflösung verifizieren

shell openclaw config get plugins.entries.firecrawl.config.webFetch.apiKey –verbose

Erwartet:

{

“sourceConfig”: “op://openclaw/Firecrawl API key/credential”,

“resolved”: “••••••••••••••••”,

“status”: “resolved”,

“resolvedAt”: “2026-04-15T10:23:41Z”

}

Schritt 2: Provider-Initialisierung verifizieren

shell openclaw debug provider firecrawl –show-config

Erwartet: apiKey-Feld sollte “••••••••••••••••” (maskiert) anzeigen

NICHT die rohe “op://…"-Zeichenkette

Schritt 3: Anfrageausführung verifizieren

shell

Testen mit einem einfachen Endpunkt, der den Authorization-Header zurückgibt

openclaw tools web-fetch “https://httpbin.org/headers" –provider firecrawl

Erwartet: Sollte JSON mit Host-Header zurückgeben

Kein 401-Fehler sollte auftreten

Schritt 4: Firecrawl-API-Interaktion verifizieren (Debug-Modus)

shell OPENCLAW_LOG_LEVEL=debug openclaw tools web-fetch “https://example.com” –provider firecrawl 2>&1 | grep -E “(firecrawl|Firecrawl|Authorization|Authorization: Bearer)”

Erwartet: Sollte das aufgelöste Bearer-Token anzeigen, das gesendet wird

Sollte NICHT “op://…” im Authorization-Header anzeigen

Schritt 5: Automatisierte Testsuite

Führen Sie die Firecrawl-Plugin-Testsuit aus, falls verfügbar:

shell openclaw test –plugin firecrawl –secretref-mode

Erwartet: Alle Tests bestehen, einschließlich SecretRef-Szenarien

Exit-Code-Verifizierung

shell

Erfolgsfall

openclaw tools web-fetch “https://example.com” –provider firecrawl echo “Exit code: $?” # Sollte 0 sein

Fehlerfall (vor Korrektur)

openclaw tools web-fetch “https://example.com” –provider firecrawl echo “Exit code: $?” # Sollte ungleich Null sein (typischerweise 1)

Umgebungsspezifische Fallen

• 1Password CLI nicht authentifiziert:
  Bevor Sie SecretRefs verwenden, stellen Sie sicher, dass die 1Password CLI angemeldet ist:
  

  # Authentifizierungsstatus überprüfen
  op account list
  Falls nicht authentifiziert, anmelden:
  op signin
  Zugriff auf den Vault verifizieren:
  op vault list

• Vault-Zugriffsberechtigungen:
  Das 1Password-Konto muss Zugriff auf den in der SecretRef referenzierten Vault haben:
  

  # Vault-Berechtigungen verifizieren
  op account get
  Sicherstellen, dass der Vault “openclaw” zugänglich ist
  op vault get openclaw

• Dienstkonto vs. persönliches Konto:
  Wenn das Gateway als Dienst ausgeführt wird, stellen Sie sicher, dass das Dienstkonto Zugriff auf 1Password hat, nicht nur Ihre persönliche Sitzung:
  

  # Für systemd-Dienst richten Sie die 1Password-Sitzung über Umgebung oder systemd-run ein
  # Vermeiden Sie es, sich auf persönliche 1Password-Sitzungstokens zu verlassen

Konfigurationsfallen

• Doppelauflösung in der Konfiguration:
  Wenn Sie FIRECRAWL_API_KEY als Umgebungsvariable gesetzt haben und auch in der Konfiguration referenzieren, stellen Sie sicher, dass die Konfiguration ${FIRECRAWL_API_KEY}-Syntax verwendet, nicht $FIRECRAWL_API_KEY:
  

  # Falsch - wird wörtlich übergeben
  "apiKey": "$FIRECRAWL_API_KEY"
  Richtig - wird aufgelöst
  “apiKey”: “${FIRECRAWL_API_KEY}"

• Leerzeichen in SecretRefs:
  1Password SecretRefs dürfen keine führenden/nachfolgenden Leerzeichen haben:
  

  # Falsch - kann Auflösungsfehler verursachen
  "apiKey": "op://openclaw/Firecrawl API key/credential "
  Richtig
  “apiKey”: “op://openclaw/Firecrawl API key/credential”

• Sonderzeichen in Item-Namen:
  Wenn der 1Password-Item-Name Sonderzeichen enthält, URL-kodieren Sie sie:
  

  # Für Item mit Namen "Firecrawl API (Dev & Prod)"
  "apiKey": "op://openclaw/Firecrawl%20API%20(Dev%20%26%20Prod)/credential"

Laufzeitfallen

• Gateway-Neustart erforderlich:
  Änderungen an SecretRefs erfordern einen Gateway-Neustart, um wirksam zu werden, auch wenn das Gateway andere Konfigurationsänderungen hot-reloadet:
  

  # Erforderlich nach Änderung der SecretRef
  openclaw gateway restart
  Nicht ausreichend:
  openclaw config reload  # Lädt nur Nicht-Geheimnis-Konfiguration

• Provider-Singleton-Verhalten:
  Aufgrund des Singleton-Provider-Musters verwenden Provider-Instanzen, die vor der Geheimnisauflösung zwischengespeichert wurden, weiterhin veraltete Werte, bis das Gateway vollständig neu startet:
  

  # Verifizieren, dass keine veralteten Instanzen vorhanden sind
  openclaw debug provider firecrawl --status
  Sollte anzeigen: “Initialized: true”, “Config Snapshot: fresh”

• Docker-Volume-Mount-Überlegungen:
  Wenn Sie in Docker ausführen, stellen Sie sicher, dass der 1Password-Socket/die Anmeldedaten ordnungsgemäß gemountet sind:
  

  # Falsch - Anmeldedaten im Container nicht verfügbar
  docker run openclaw:latest
  Richtig - 1Password-Socket mounten
  docker run -v openclaw_config:/app/config -e OP_SESSION=… openclaw:latest

macOS-spezifische Probleme

• Keychain-Zugriffsaufforderungen:
  Die 1Password CLI kann bei nicht-interaktiver Ausführung zur Keychain-Zugriffsaufforderung auffordern. Verwenden Sie op signin --account mit einem Dienstkonto für CI/CD-Umgebungen.
• SSH-Agent-Weiterleitung:
  Wenn 1Password-Anmeldedaten über SSH weitergeleitet werden, stellen Sie sicher, dass die OP_SESSION-Umgebungsvariable ebenfalls weitergeleitet wird.

Windows-spezifische Probleme

• Pfad-Trennzeichen:
  SecretRef-Pfade verwenden Forward Slashes auch unter Windows. Konvertieren Sie diese nicht in Backslashes.
• WSL2-Umgebungsvariablen:
  Wenn Sie OpenClaw in WSL2 mit Windows 1Password ausführen, richten Sie die 1Password CLI in WSL2 ein und authentifizieren Sie sich dort separat vom Windows-Host.

Primäres zugehöriges Problem

• #28359 - SecretRef-Laufzeitmaterialisierungs-Inkonsistenz
  Historisches Problem, das beschreibt, wie SecretRef-Werte in Konfigurations-Snapshots in verschiedenen Auflösungszuständen erfasst werden können. Der Firecrawl-Fehler ist eine spezifische Manifestation dieses breiteren Musters.

Symptomatisch zugehörige Fehler

• 401 Unauthorized: Invalid token
  Allgemeiner Authentifizierungsfehler. In diesem Kontext verursacht durch die literale op://...-Zeichenkette, die als Bearer-Token gesendet wird.
• SecretRef resolution failed: Item not found
  Zeigt an, dass das in der SecretRef angegebene 1Password-Item oder der Vault nicht existiert oder nicht zugänglich ist. Anders als beim Firecrawl-Fehler – hier schlägt die Auflösung selbst fehl.
• Plugin initialization failed: Config snapshot mismatch
  Interner OpenClaw-Fehler, der anzeigt, dass ein Plugin inkonsistente Konfiguration über Initialisierungsphasen hinweg erhalten hat. Kann beim Gateway-Start erscheinen, wenn die Firecrawl-Provider-Initialisierungsreihenfolge geändert wird.
• Gateway config validation error: Invalid SecretRef format
  Schema-Validierungsfehler, wenn die SecretRef nicht dem op://vault/item/field-Muster entspricht.

Fehlercode-Referenz

Übergreifende Plugin-Überlegungen

Dasselbe Snapshot-Isolierungsmuster betrifft andere Plugins, die:

• API-Schlüssel oder Tokens über SecretRef akzeptieren
• Provider während Gateway-Start initialisieren
• Singleton-Provider-Instanzen verwenden

Bekannte potenziell betroffene Plugins:

• plugins.entries.anthropic.config.apiKey
• plugins.entries.google.config.credentials
• plugins.entries.aws.config.accessKeyId
• plugins.entries.azure.config.subscriptionKey

Verifizieren Sie, dass diese Plugins nicht denselben Fehler aufweisen, indem Sie ihre jeweiligen SecretRef-Konfigurationen testen.