x_search falla con SecretRef sin resolver en la ruta canónica de autenticación xAI - x_search Fails with Unresolved SecretRef on Canonical xAI Auth Path

Manifestación principal del error

Al invocar la herramienta integrada x_search con credenciales xAI configuradas como un exec SecretRef en la ruta canónica propiedad del plugin, la operación falla inmediatamente con la siguiente respuesta de error:

{
  "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."
}

Secuencia de reproducción mediante CLI

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

Contexto de configuración

El fallo ocurre con esta forma de configuración (verificado como funcional antes de abril en la misma infraestructura):

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

Detalles del entorno

• Versión de OpenClaw: 2026.4.10 (commit 44e5b62)
• Sistema operativo: macOS 25.3.0 (arm64)
• Método de instalación: Instalación global de npm / servicio local de gateway
• Tipo de instalación: exec SecretRef a través del proveedor 1Password

Observación confusa

El error persiste aunque:

• web_search está configurado para usar el proveedor brave (no xAI)
• Las credenciales xAI existen en la ruta canónica propiedad del plugin
• La misma configuración funcionaba antes de las refactorizaciones de xAI en abril

Contexto arquitectónico: Las refactorizaciones de xAI en abril

El problema proviene de una secuencia de cambios ruptura introducidos en las refactorizaciones de abril de 2026:

1. Issue #59674 — Movió la configuración de x_search detrás del límite del plugin xAI, convirtiéndola en una característica propiedad del plugin en lugar de una herramienta de nivel superior.
2. Issue #59691 — Hizo que la autenticación de x_search fuera propiedad del plugin, requiriendo que las credenciales fluyan a través de la ruta de configuración del plugin xAI en lugar de la configuración directa de la herramienta.

Causa raíz: Obsolescencia de la instantánea del runtime con proveedores exec

El mecanismo de fallo específico involucra una condición de carrera o estancamiento de la instantánea en cómo el runtime del gateway resuelve los exec SecretRefs para autenticación propiedad del plugin:

1. Inicialización de la instantánea: Cuando el gateway se inicia, crea una instantánea del runtime que contiene valores resueltos para toda la configuración, incluyendo los SecretRefs.
2. Tiempo del proveedor exec: Los proveedores exec (como 1Password) requieren ejecución de comandos externos para recuperar secretos. Estos se resuelven durante la creación de la instantánea.
3. Acceso posterior a la inicialización: La ruta de la herramienta x_search ahora accede a plugins.entries.xai.config.webSearch.apiKey durante la ejecución de la herramienta, no durante la creación inicial de la instantánea.
4. Referencia obsoleta: Si la salida del comando del proveedor exec ha cambiado desde la creación de la instantánea (o si la instantánea no se hidrató correctamente para la ruta propiedad del plugin), el SecretRef aparece como no resuelto.

Análisis de la ruta del código

El fallo ocurre en esta secuencia de ejecución:

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)

Por qué esto es una regresión

Antes de las refactorizaciones de abril:

• x_search usaba una ruta de autenticación directa que no requería resolución de credenciales propiedad del plugin
• Los exec SecretRefs se resolvían en el momento de la invocación de la herramienta, no en el momento dependiente de la instantánea
• El mismo comando exec de 1Password funcionaba porque la ruta de resolución no atravesaba el límite del plugin

Después de abril:

• x_search ahora es completamente propiedad del plugin
• La resolución de autenticación ocurre contra la instantánea del runtime del gateway
• Los exec SecretRefs se evalúan como "no resueltos" cuando la instantánea no contiene un valor resuelto actual

Problemas adyacentes

Esta regresión se conecta con problemas más amplios de instantánea del runtime / resolución de SecretRef:

• #50161 — Manejo general de SecretRef no resuelto en el runtime del gateway
• #51263 — Obsolescencia de la instantánea con proveedores dinámicos
• #57272 — Caché del proveedor exec vs. resolución fresca
• #54555 — Detección de clave API de xAI faltante (superficie de autenticación relacionada)

Opción A: Usar SecretRef estático (Recomendado para producción)

Reemplaza el exec SecretRef con una referencia estática que no requiere ejecución de comandos en runtime:

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

Luego configura la variable de entorno:

# 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

Opción B: Valor estático en línea (Solo desarrollo)

Para desarrollo/pruebas, usa un valor estático en línea directamente en la configuración:

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

Opción C: Forzar actualización de instantánea (Solución alternativa)

Si debes usar proveedores exec, fuerza una actualización de la instantánea del gateway:

# 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

Luego prueba:

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

Opción D: Migrar al proveedor nativo de secretos

Si usas 1Password, migra a la integración nativa de OpenClaw con 1Password que no requiere comandos exec:

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

Antes vs. Después de la configuración

Antes (Fallando)

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

Después (Funcionando)

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

Paso 1: Confirmar que el gateway está en ejecución

$ clawctl gateway status

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

Paso 2: Verificar la configuración del plugin xAI

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

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

Paso 3: Verificar que la variable de entorno está configurada

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

xai-sk-12...

Paso 4: Probar la invocación de la herramienta x_search

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

Paso 5: Verificar el código de salida

$ echo $?
0

Una invocación exitosa de x_search debe devolver el código de salida 0.

Paso 6: Verificar que no hay errores de SecretRef en los logs

$ 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

Paso 7: Verificar la resolución de credenciales del plugin

$ 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. Servicio del gateway vs. Entorno del shell del usuario

Problema: Las variables de entorno configuradas en tu shell no están disponibles para el daemon del servicio del gateway.

# 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

Solución: Configura las variables de entorno para el servicio del gateway:

# 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. Instantánea no actualizada después del cambio de configuración

Problema: Cambiar de exec a SecretRef estático no surte efecto hasta la actualización de la instantánea.

Solución:

# Always restart the gateway after config changes
clawctl gateway restart

# Or force snapshot refresh
clawctl gateway snapshot --refresh

3. Plugin no habilitado

Problema: El plugin xAI debe estar explícitamente habilitado para que x_search propiedad del plugin funcione.

Solución:

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

# If not enabled:
clawctl plugins enable xai

4. Incompatibilidad de versiones

Problema: Las refactorizaciones de abril (x_search propiedad del plugin) requieren OpenClaw 2026.4.0 o posterior.

Solución:

# Check current version
clawctl --version

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

5. Tiempo de espera del proveedor exec

Problema: Si la CLI de 1Password tarda demasiado, los exec SecretRefs agotan el tiempo de espera durante la creación de la instantánea.

Solución: Añade configuración de tiempo de espera al proveedor exec:

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

6. Problemas de Gatekeeper/Notarización en macOS

Problema: En macOS, la CLI de 1Password (op) puede ser bloqueada por Gatekeeper si no está correctamente firmada.

Solución:

# 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. Variables de entorno en Docker/Entorno de contenedores

Problema: Las variables de entorno deben pasarse explícitamente a los contenedores.

Solución:

# 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 — Error general cuando un SecretRef no puede resolverse contra la instantánea actual del runtime. Se manifiesta como: unresolved SecretRef "exec:provider:id". Ver issues #50161, #51263.
• MISSING_XAI_API_KEY — Indica que las credenciales xAI no están presentes en la configuración en absoluto, independientemente del formato. Puede ocurrir incluso cuando las credenciales existen pero no están en la ruta canónica propiedad del plugin. Ver issue #54555.
• SNAPSHOT_STALE — La instantánea del runtime contiene valores obsoletos y requiere actualización. A menudo se manifiesta junto con fallos de resolución de SecretRef.
• PLUGIN_NOT_INITIALIZED — El plugin xAI no ha sido cargado o habilitado. x_search requiere que el plugin esté activo.
• EXEC_PROVIDER_TIMEOUT — El comando externo para exec SecretRef excedió el tiempo de espera. El comando op (CLI de 1Password) puede ser lento o estar bloqueado.
• INVALID_SECRET_REF_FORMAT — El SecretRef no cumple con el formato esperado source:provider:id.
• GATEWAY_NOT_RUNNING — No se pueden invocar herramientas cuando el servicio del gateway está detenido. Asegúrate de que clawctl gateway status muestre RUNNING.

Issues históricos

Referencias de documentación

• Gestión de secretos de OpenClaw
• Configuración del plugin xAI
• Referencia de la herramienta x_search
• Instantáneas del runtime