[x_search schlägt bei unaufgelöster SecretRef am kanonischen xAI-Authentifizierungspfad fehl] - x_search Fails with Unresolved SecretRef on Canonical xAI Auth Path

Primäre Fehlermanifestation

Beim Aufruf des integrierten x_search-Tools mit xAI-Anmeldedaten, die als exec SecretRef am kanonischen plugin-eigenen Pfad konfiguriert sind, schlägt der Vorgang sofort mit der folgenden Fehlerantwort fehl:

{
  "status": "error",
  "tool": "x_search",
  "error": "plugins.entries.xai.config.webSearch.apiKey: unresolved SecretRef \"exec:onepassword_xai:value\". Resolve this command against an active gateway runtime snapshot before reading it."
}

CLI-Reproduktionssequenz

# Attempt to invoke x_search via gateway CLI
$ clawctl tools invoke x_search --input '{"query": "latest OpenClaw release notes"}'

# Expected: Successful search response
# Actual: Error with unresolved SecretRef

{
  "status": "error",
  "tool": "x_search",
  "error": "plugins.entries.xai.config.webSearch.apiKey: unresolved SecretRef \"exec:onepassword_xai:value\". Resolve this command against an active gateway runtime snapshot before reading it."
}

Konfigurationskontext

Der Fehler tritt mit dieser Konfigurationsstruktur auf (verifiziert funktionierend vor April auf derselben Infrastruktur):

{
  "tools": {
    "web": {
      "search": {
        "provider": "brave"
      },
      "x_search": {
        "enabled": true,
        "model": "grok-4-1-fast-non-reasoning",
        "maxTurns": 2,
        "timeoutSeconds": 30,
        "cacheTtlMinutes": 15
      }
    }
  },
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "exec",
              "provider": "onepassword_xai",
              "id": "value"
            }
          }
        }
      }
    }
  }
}

Umgebungsdetails

• OpenClaw Version: 2026.4.10 (commit 44e5b62)
• Betriebssystem: macOS 25.3.0 (arm64)
• Installationsmethode: global npm install / lokaler Gateway-Dienst
• Installationstyp: exec SecretRef über 1Password-Anbieter

Verwirrende Beobachtung

Der Fehler bleibt bestehen, obwohl:

• web_search für die Verwendung des brave-Anbieters konfiguriert ist (nicht xAI)
• Die xAI-Anmeldedaten am kanonischen plugin-eigenen Pfad vorhanden sind
• Dieselbe Konfiguration vor den April-xAI-Refactorings funktioniert hat

Architektonischer Kontext: Die April xAI-Refactorings

Das Problem stammt aus einer Reihe von Breaking Changes, die in den April-2026-Refactorings eingeführt wurden:

1. Issue #59674 — x_search-Konfiguration hinter die xAI-Plugin-Grenze verschoben, wodurch es sich um eine plugin-eigene Funktion handelt, anstatt ein Tool auf oberster Ebene zu sein.
2. Issue #59691 — x_search-Authentifizierung plugin-eigen gemacht, wobei Anmeldedaten über den xAI-Plugin-Konfigurationspfad fließen müssen, anstatt über direkte Tool-Konfiguration.

Ursache: Runtime-Snapshot-Staleness bei Exec-Anbietern

Der spezifische Fehlermechanismus beinhaltet eine Race-Condition oder Snapshot-Staleness in der Art und Weise, wie die Gateway-Runtime exec SecretRefs für plugin-eigene Authentifizierung auflöst:

1. Snapshot-Initialisierung: Wenn das Gateway startet, erstellt es einen Runtime-Snapshot, der aufgelöste Werte für alle Konfigurationen einschließlich SecretRefs enthält.
2. Exec-Anbieter-Timing: Exec-Anbieter (wie 1Password) erfordern die Ausführung externer Befehle zum Abrufen von Secrets. Diese werden während der Snapshot-Erstellung aufgelöst.
3. Zugriff nach Initialisierung: Der x_search-Tool-Pfad greift während der Tool-Ausführung auf plugins.entries.xai.config.webSearch.apiKey zu, nicht während der ursprünglichen Snapshot-Erstellung.
4. Veraltete Referenz: Wenn sich die Ausgabe des exec-Anbieterbefehls seit der Snapshot-Erstellung geändert hat (oder wenn der Snapshot nicht ordnungsgemäß für den plugin-eigenen Pfad hydriert wurde), erscheint der SecretRef als unaufgelöst.

Code-Pfad-Analyse

Der Fehler tritt in dieser Ausführungssequenz auf:

x_search tool invocation
  → xAI plugin-owned auth path
  → plugins.entries.xai.config.webSearch.apiKey
  → SecretRef resolution check
  → Runtime snapshot lookup for "exec:onepassword_xai:value"
  → Result: UNRESOLVED (snapshot doesn't contain active value)

Warum dies eine Regression ist

Vor den April-Refactorings:

• x_search verwendete einen direkten Authentifizierungspfad, der keine plugin-eigene Anmeldedatenauflösung erforderte
• Exec SecretRefs wurden zum Zeitpunkt der Tool-Invokation aufgelöst, nicht zeitpunktabhängig vom Snapshot
• Derselbe 1Password-Exec-Befehl funktionierte, weil der Auflösungs pfad nicht die Plugin-Grenze durchquerte

Nach April:

• x_search ist jetzt vollständig plugin-eigen
• Die Auth-Auflösung erfolgt gegen den Gateway-Runtime-Snapshot
• Exec SecretRefs werden als "unaufgelöst" bewertet, wenn der Snapshot keinen aktuellen aufgelösten Wert enthält

Zugehörige Probleme

Diese Regression steht im Zusammenhang mit breiteren Runtime-Snapshot- / SecretRef-Auflösungsproblemen:

• #50161 — Allgemeine Behandlung von unaufgelösten SecretRefs in der Gateway-Runtime
• #51263 — Snapshot-Staleness bei dynamischen Anbietern
• #57272 — Exec-Anbieter-Caching vs. frische Auflösung
• #54555 — Fehlende xAI-API-Schlüssel-Erkennung (zugehörige Auth-Oberfläche)

Option A: Statischen SecretRef verwenden (für Produktion empfohlen)

Ersetzen Sie den exec SecretRef durch eine statische Referenz, die keine Laufzeit-Befehlsausführung erfordert:

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "static",
              "value": "${XAI_API_KEY}"
            }
          }
        }
      }
    }
  }
}

Dann setzen Sie die Umgebungsvariable:

# Add to your shell profile or gateway environment
export XAI_API_KEY="xai-your-actual-api-key-here"

# Or inject at gateway startup
XAI_API_KEY="xai-your-actual-api-key-here" clawctl gateway start

Option B: Inline-Statischen Wert verwenden (nur Entwicklung)

Für Entwicklung/Tests verwenden Sie einen inline-statischen Wert direkt in der Konfiguration:

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "inline",
              "value": "xai-your-actual-api-key-here"
            }
          }
        }
      }
    }
  }
}

Option C: Snapshot-Aktualisierung erzwingen (Workaround)

Wenn Sie exec-Anbieter verwenden müssen, erzwingen Sie eine Gateway-Snapshot-Aktualisierung:

# Stop the gateway
clawctl gateway stop

# Clear the runtime snapshot cache
rm -rf ~/.config/openclaw/runtime/snapshots/
rm -rf ~/.local/share/openclaw/snapshots/

# Restart the gateway (this creates a fresh snapshot)
clawctl gateway start

# Verify snapshot is fresh
clawctl gateway status --verbose

Dann testen:

clawctl tools invoke x_search --input '{"query": "test"}'

Option D: Zu nativem Secrets-Anbieter migrieren

Wenn Sie 1Password verwenden, migrieren Sie zur nativen OpenClaw 1Password-Integration, die keine exec-Befehle erfordert:

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "onepassword",
              "vault": "openclaw-secrets",
              "item": "xai-api-key",
              "field": "api_key"
            }
          }
        }
      }
    }
  }
}

Vorher vs. Nachher Konfiguration

Vorher (Fehlgeschlagen)

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "exec",
              "provider": "onepassword_xai",
              "id": "value"
            }
          }
        }
      }
    }
  }
}

Nachher (Funktioniert)

{
  "plugins": {
    "entries": {
      "xai": {
        "config": {
          "webSearch": {
            "apiKey": {
              "source": "static",
              "value": "${XAI_API_KEY}"
            }
          }
        }
      }
    }
  }
}

Schritt 1: Bestätigen, dass das Gateway läuft

$ clawctl gateway status

Gateway Status: RUNNING
Version: 2026.4.10 (44e5b62)
Runtime: Active
Snapshot: Valid (created: 2026-04-XX XX:XX:XX)

Schritt 2: xAI-Plugin-Konfiguration überprüfen

$ clawctl config get plugins.entries.xai.config.webSearch.apiKey

{
  "source": "static",
  "value": "${XAI_API_KEY}"
}

Schritt 3: Überprüfen, ob Umgebungsvariable gesetzt ist

$ echo $XAI_API_KEY | head -c 10 && echo "..."

xai-sk-12...

Schritt 4: x_search-Tool-Invokation testen

$ clawctl tools invoke x_search --input '{"query": "OpenClaw troubleshooting guide"}'

{
  "status": "success",
  "tool": "x_search",
  "results": {
    "query": "OpenClaw troubleshooting guide",
    "results": [
      {
        "title": "OpenClaw Professional Troubleshooting Guide",
        "url": "https://docs.openclaw.io/guides/troubleshooting",
        "snippet": "..."
      }
    ],
    "model": "grok-4-1-fast-non-reasoning",
    "tokensUsed": 142
  }
}

Schritt 5: Exit-Code verifizieren

$ echo $?
0

Eine erfolgreiche x_search-Invokation sollte Exit-Code 0 zurückgeben.

Schritt 6: Überprüfen, dass keine SecretRef-Fehler in den Logs vorhanden sind

$ clawctl logs --tail 50 | grep -E "(x_search|SecretRef|xai)"

# Should show successful resolution, no unresolved errors:
[INFO] x_search: Tool invocation successful
[INFO] xai.plugin: Credential resolved successfully

Schritt 7: Plugin-Anmeldedatenauflösung verifizieren

$ clawctl debug resolve-secret --path plugins.entries.xai.config.webSearch.apiKey

Resolved: true
Value Preview: xai-sk-12****
Source: static (env: XAI_API_KEY)
TTL: Persistent

1. Gateway-Dienst vs. Benutzer-Shell-Umgebung

Problem: Umgebungsvariablen, die in Ihrer Shell gesetzt werden, sind für den Gateway-Dienst-Daemon nicht verfügbar.

# This sets the variable for YOUR shell:
export XAI_API_KEY="xai-..."

# But the GATEWAY SERVICE runs in a different context:
# It won't see this variable unless configured system-wide

Lösung: Konfigurieren Sie Umgebungsvariablen für den Gateway-Dienst:

# For launchd (macOS)
# Edit /Library/LaunchDaemons/com.openclaw.gateway.plist
<key>EnvironmentVariables</key>
<dict>
    <key>XAI_API_KEY</key>
    <string>xai-...</string>
</dict>

# For systemd (Linux)
# Create /etc/systemd/system/openclaw-gateway.service.d/override.conf
[Service]
Environment="XAI_API_KEY=xai-..."

2. Snapshot nach Konfigurationsänderung nicht aktualisiert

Problem: Das Ändern von exec zu static SecretRef wird erst nach Snapshot-Aktualisierung wirksam.

Lösung:

# Always restart the gateway after config changes
clawctl gateway restart

# Or force snapshot refresh
clawctl gateway snapshot --refresh

3. Plugin nicht aktiviert

Problem: Das xAI-Plugin muss explizit aktiviert sein, damit plugin-eigenes x_search funktioniert.

Lösung:

# Verify xAI plugin is enabled
clawctl plugins list --enabled

# If not enabled:
clawctl plugins enable xai

4. Versionsinkongruenz

Problem: Die April-Refactorings (x_search plugin-eigen) erfordern OpenClaw 2026.4.0 oder höher.

Lösung:

# Check current version
clawctl --version

# Update if needed
npm update -g @openclaw/cli
clawctl self-update

5. Exec-Anbieter-Timeout

Problem: Wenn die 1Password-CLI zu lange braucht, timed das exec SecretRef während der Snapshot-Erstellung aus.

Lösung: Timeout-Konfiguration zum exec-Anbieter hinzufügen:

{
  "providers": {
    "exec": {
      "onepassword_xai": {
        "command": "op read op://.../api_key/value",
        "timeout": 10000
      }
    }
  }
}

6. macOS Gatekeeper/Notarisierungsprobleme

Problem: Auf macOS kann die 1Password-CLI (op) von Gatekeeper blockiert werden, wenn sie nicht ordnungsgemäß signiert ist.

Lösung:

# Verify op binary is allowed
xattr -l /usr/local/bin/op
# Should not show com.apple.quarantine

# If quarantined, remove:
xattr -d com.apple.quarantine /usr/local/bin/op

7. Docker/Container-Umgebungsvariablen

Problem: Umgebungsvariablen müssen Containern explizit übergeben werden.

Lösung:

# Pass env vars to Docker container
docker run -e XAI_API_KEY="xai-..." openclaw/gateway:latest

# Or use docker-compose.yml
environment:
  - XAI_API_KEY=xai-...

• UNRESOLVED_SECRET_REF — Allgemeiner Fehler, wenn ein SecretRef nicht gegen den aktuellen Runtime-Snapshot aufgelöst werden kann. Manifestiert sich als: unresolved SecretRef "exec:provider:id". Siehe Issues #50161, #51263.
• MISSING_XAI_API_KEY — Zeigt an, dass xAI-Anmeldedaten in der Konfiguration nicht vorhanden sind, unabhängig vom Format. Kann auftreten, selbst wenn Anmeldedaten vorhanden sind, aber nicht am kanonischen plugin-eigenen Pfad. Siehe Issue #54555.
• SNAPSHOT_STALE — Der Runtime-Snapshot enthält veraltete Werte und erfordert eine Aktualisierung. Tritt oft zusammen mit SecretRef-Auflösungsfehlern auf.
• PLUGIN_NOT_INITIALIZED — Das xAI-Plugin wurde nicht geladen oder aktiviert. x_search erfordert, dass das Plugin aktiv ist.
• EXEC_PROVIDER_TIMEOUT — Externer Befehl für exec SecretRef hat den Timeout überschritten. Der op (1Password-CLI)-Befehl kann langsam oder blockiert sein.
• INVALID_SECRET_REF_FORMAT — SecretRef entspricht nicht dem erwarteten source:provider:id-Format.
• GATEWAY_NOT_RUNNING — Tools können nicht aufgerufen werden, wenn der Gateway-Dienst gestoppt ist. Stellen Sie sicher, dass clawctl gateway status RUNNING anzeigt.

Historische Probleme

Dokumentationsreferenzen

• OpenClaw Secrets Management
• xAI Plugin Configuration
• x_search Tool Reference
• Runtime Snapshots