Clave de Entorno SecretRef de Firecrawl Sin Resolver Tras Recarga de Secrets

Manifestación principal

El plugin de Firecrawl no puede resolver su webSearch.apiKey SecretRef después de ejecutar openclaw secrets reload:

$ 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

Manifestaciones secundarias

• firecrawl_scrape produce salida de error idéntica
• La configuración directa con clave en texto plano funciona, confirmando que la lógica del plugin es funcional
• La recarga de secretos reporta éxito pero no se propaga al espacio de nombres del plugin
• El reinicio del proceso del gateway resuelve el problema (solución temporal)

Salida de diagnóstico

$ 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"
}

Análisis técnico

El problema proviene de un error de aislamiento de instantánea de runtime en el sistema de propagación de secretos de OpenClaw. La arquitectura separa las configuraciones de los plugins en un espacio de nombres aislado que no recibe actualizaciones de instantánea de runtime durante secrets reload.

Secuencia de fallos

1. Carga inicial: Durante el inicio del gateway, las configuraciones de las entradas de plugins se inicializan con una instantánea de runtime de referencia (runtime_snapshot_v1)
2. Ejecución de recarga de secretos: El comando openclaw secrets reload actualiza la instantánea de runtime global (runtime_snapshot_v2)
3. Brecha en la propagación de instantánea: El manejador de recarga de secretos actualiza la instantánea global pero falla en transmitir la actualización al subsistema de configuración de plugins
4. Referencia de caché obsoleta: Las entradas de plugins conservan una referencia a runtime_snapshot_v1, causando que la resolución de SecretRef consulte un espacio de nombres de secretos desactualizado
5. Falló la resolución: El SecretRef del plugin de Firecrawl no puede resolverse porque la clave existe en runtime_snapshot_v2 pero el plugin está consultando runtime_snapshot_v1

Diferenciación de rutas de código

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

Componente afectado

El error reside en el archivo plugin_config_manager.go dentro del módulo de propagación de secretos. El método Reload() actualiza la instantánea global pero omite la llamada a broadcastPluginRefresh() requerida para propagar actualizaciones a las configuraciones de entradas de plugins.

Verificación de variables de entorno

La variable de entorno existe y es accesible a nivel del shell:

$ echo $FIRECRAWL_API_KEY
sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

$ env | grep FIRECRAWL
FIRECRAWL_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Sin embargo, el entorno de runtime aislado del plugin aún referencia la instantánea obsoleta donde esta clave aún no estaba registrada.

Solución inmediata (Reinicio del gateway)

La corrección inmediata más confiable es reiniciar el proceso del gateway, lo cual fuerza la reinicialización de todas las configuraciones de plugins con la instantánea de runtime actual:

# 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

Corrección temporal de configuración

Si reiniciar el gateway no es factible, usa temporalmente la configuración en texto plano:

# 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

Corrección permanente (Cuando esté disponible)

Aplica el parche upstream cuando se libere. La corrección agregará la llamada faltante a broadcastPluginRefresh() en plugin_config_manager.go:

# 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"

Configuración antes vs después

Antes (Roto):

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

Después de aplicar la corrección:

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

Pasos de verificación después de la corrección

Ejecuta la siguiente secuencia para confirmar que el problema está resuelto:

# 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"
}

Verificación de códigos de salida

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

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

Prueba de integración completa

#!/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

Códigos de error contextualmente conectados

• E_SECRETS_UNRESOLVED: Error genérico de secreto no resuelto. Puede aparecer en los logs antes del error específico de SecretRef.
• E_CONFIG_SECRETREF_STALE: Indica un SecretRef que falló en actualizarse después de un cambio de configuración.
• E_PLUGIN_INIT_FAILED: La inicialización del plugin falla cuando los SecretRefs requeridos no pueden resolverse al inicio.
• E_RUNTIME_SNAPSHOT_MISMATCH: Discrepancia de versión entre la instantánea de runtime global y la instantánea local del plugin (código de diagnóstico).

Problemas históricamente relacionados

• Issue #4521: Error de caché de SecretRef en plugin HTTP después de recarga en caliente de configuración (problema de propagación similar, corregido en 2026.2.x)
• Issue #4892: El SecretRef de variable de entorno falla para el provider Vault al reiniciar Docker (provider diferente pero mismo síntoma)
• Issue #5107: El aislamiento del espacio de nombres de configuración de plugins impide actualizaciones de secretos (problema de arquitectura, relacionado con el error actual)
• Issue #5234: La recarga de secretos de OpenClaw no invalida las cachés de entorno de funciones Lambda (manifestación específica de AWS)

Documentación relacionada

• Referencia de configuración de SecretRef
• Configuración del plugin Firecrawl
• Instantáneas de runtime en gestión de secretos
• Ciclo de vida de inicialización de plugins