Manifestación principal del error

Cuando un sub-agente intenta usar el proveedor google-vertex, el resolvedor de autenticación lanza un error bloqueante antes de que el SDK de Google pueda inicializarse:

Error: No API key found for provider "google-vertex". Auth store: .../auth-profiles.json
    at resolveApiKeyForProvider (auth-profiles.js:247:15)
    at async sessions_spawn (router.js:892:4)
    at async handleAgentRequest (gateway.js:214:9)

Pasos para reproducir desde CLI

bash

Attempt to spawn a sub-agent with google-vertex provider

curl -X POST http://localhost:3000/v1/sessions/spawn
-H “Content-Type: application/json”
-d ‘{ “agent”: “sub-agent”, “provider”: “google-vertex”, “model”: “gemini-2.0-flash-001” }’

Comportamiento esperado vs comportamiento real

Contexto del entorno

• Plataforma: macOS 26.3 (arm64) / Linux
• Versión de OpenClaw: 2026.2.26
• SDK: @google/genai
• Tipo de autenticación: Credenciales predeterminadas de aplicación de Google (cuenta de servicio)

Análisis arquitectónico

1. Arquitectura del gate de autenticación

OpenClaw implementa un resolvedor de autenticación centralizado en resolveApiKeyForProvider() que aplica la validación de clave API para todos los proveedores antes del procesamiento de solicitudes:

// Simplified auth gate logic (auth-profiles.js)
function resolveApiKeyForProvider(provider, authStore) {
  // ... normalization logic ...
  
  if (authOverride !== void 0) {
    return { apiKey: authOverride, source: "manual-override", mode: "api-key" };
  }
  
  // Check auth store for stored credentials
  const stored = authStore[normalized];
  if (stored) {
    return parseStoredCredentials(stored);
  }
  
  // THE GATE: Blocks if no credentials found
  throw new Error(`No API key found for provider "${normalized}"...`);
}

2. El patrón de excepción de Bedrock

amazon-bedrock recibió una excepción porque utiliza credenciales del SDK de AWS (roles IAM, variables de entorno, metadatos de EC2) en lugar de claves API estáticas:

// auth-profiles.js (existing Bedrock exception)
if (authOverride === void 0 && normalized === "amazon-bedrock") {
  return resolveAwsSdkAuthInfo();  // Returns { mode: "aws-sdk" }
}

3. La excepción faltante de google-vertex

Google Vertex AI utiliza un patrón de autenticación idéntico—Credenciales predeterminadas de aplicación—pero carece de la excepción correspondiente. La cadena de resolución procede así:

resolveApiKeyForProvider("google-vertex")
  → normalized = "google-vertex"
  → authOverride = undefined
  → normalized !== "amazon-bedrock" (skip)
  → authStore["google-vertex"] = undefined (no stored creds)
  → throw Error("No API key found...")  ← BLOCKED HERE

4. Impacto aguas abajo en la selección de modelo

La validación del modo en pi-embedded-*.js requiere además la inclusión explícita en lista blanca de modos que no son clave API:

// model-selection.js (current restrictive check)
if (apiKeyInfo.mode !== "aws-sdk" && apiKeyInfo.mode !== "api-key") {
  throw new Error("Invalid auth mode for model selection...");
}
// google-vertex ADC mode ("adc") would also fail this check

5. Desajuste de autenticación entre SDK y plataforma

El SDK @google/genai está diseñado para resolver automáticamente credenciales desde:

• GOOGLE_APPLICATION_CREDENTIALS (JSON de cuenta de servicio)
• GOOGLE_CLOUD_PROJECT (ID del proyecto)
• GOOGLE_CLOUD_LOCATION (región, ej. us-central1)
• Cuenta de servicio adjunta (GCE, Cloud Run, etc.)

El gate de clave API de OpenClaw intercepta la solicitud antes de que el SDK pueda realizar su autenticación nativa, creando un requisito imposible.

Requisitos previos

• Verificar que Google ADC esté configurado correctamente:

  # Check service account credentials exist
  ls -la $GOOGLE_APPLICATION_CREDENTIALS
  Verify gcloud auth (alternative)
  gcloud auth application-default login
  Test SDK can resolve credentials
  node -e “const {GoogleAuth} = require(‘google-auth-library’); new GoogleAuth().getClient()"

• Configurar las variables de entorno requeridas:

  export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json"
  export GOOGLE_CLOUD_PROJECT="your-project-id"
  export GOOGLE_CLOUD_LOCATION="us-central1"

Patch 1: auth-profiles.js

Ubicación: src/auth/auth-profiles.js (o equivalente en dist/)

Acción: Agregar paso a través ADC para google-vertex después de la excepción de Bedrock.

Antes

if (authOverride === void 0 && normalized === "amazon-bedrock") {
  return resolveAwsSdkAuthInfo();
}
// ... rest of resolver

Después

if (authOverride === void 0 && normalized === "amazon-bedrock") {
  return resolveAwsSdkAuthInfo();
}

// Google Vertex AI ADC passthrough
if (authOverride === void 0 && normalized === "google-vertex") {
  return {
    apiKey: "adc-passthrough",
    source: "google-adc",
    mode: "adc"
  };
}
// ... rest of resolver

Patch 2: model-selection.js

Ubicación: src/model-selection/model-selection.js

Acción: Agregar "adc" a la lista de modos aceptados.

Antes

if (apiKeyInfo.mode !== "aws-sdk" && apiKeyInfo.mode !== "api-key") {
  throw new Error("Invalid authentication mode for model selection...");
}

Después

if (apiKeyInfo.mode !== "aws-sdk" && apiKeyInfo.mode !== "api-key" && apiKeyInfo.mode !== "adc") {
  throw new Error("Invalid authentication mode for model selection...");
}

Patch 3: pi-embedded-*.js (Verificación del modo gateway)

Ubicación: src/gateway/pi-embedded.js o equivalente

Acción: Asegurar que el modo ADC sea aceptado en la verificación de autenticación del gateway.

Antes

if (apiKeyInfo.mode !== "aws-sdk" && apiKeyInfo.mode !== "adc") {
  throw new AuthenticationError("Unsupported auth mode");
}

Después

// Verify GOOGLE_* environment variables are present for ADC providers
if (apiKeyInfo.mode === "adc") {
  if (!process.env.GOOGLE_CLOUD_PROJECT) {
    throw new AuthenticationError("GOOGLE_CLOUD_PROJECT not set for ADC authentication");
  }
  if (!process.env.GOOGLE_CLOUD_LOCATION) {
    throw new AuthenticationError("GOOGLE_CLOUD_LOCATION not set for ADC authentication");
  }
}

Alternativa: Corrección basada en configuración

Si prefieres no aplicar parches a los archivos fuente, añade a tu openclaw.config.js:

module.exports = {
  providers: {
    "google-vertex": {
      authStrategy: "adc",
      envVars: ["GOOGLE_CLOUD_PROJECT", "GOOGLE_CLOUD_LOCATION"]
    }
  }
};

Paso 1: Verificar que el resolvedor de autenticación devuelva el modo ADC

bash

Start a Node REPL in the OpenClaw context

node -e " const { resolveApiKeyForProvider } = require(’./dist/auth/auth-profiles.js’); const result = resolveApiKeyForProvider(‘google-vertex’, {}); console.log(JSON.stringify(result, null, 2)); "

Salida esperada:

json { “apiKey”: “adc-passthrough”, “source”: “google-adc”, “mode”: “adc” }

Paso 2: Verificar que el sub-agente pueda ser creado

bash

Set environment variables

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account.json” export GOOGLE_CLOUD_PROJECT=“your-project-id” export GOOGLE_CLOUD_LOCATION=“us-central1”

Test sub-agent spawn via CLI

openclaw agents spawn
–provider google-vertex
–model gemini-2.0-flash-001
–session-id test-session-001

Salida esperada:

[INFO] Spawning sub-agent with google-vertex provider [INFO] Auth mode: adc (Google ADC passthrough) [INFO] Sub-agent spawned successfully: agent-abc123

Paso 3: Verificar la llamada real a la API de Vertex

javascript // test-vertex-adc.js const { VertexAI } = require(’@google-cloud/vertexai’);

async function test() { const vertex = new VertexAI({ project: process.env.GOOGLE_CLOUD_PROJECT, location: process.env.GOOGLE_CLOUD_LOCATION, });

const model = vertex.getGenerativeModel({ model: ‘gemini-2.0-flash-001’ }); const result = await model.generateContent(‘Hello, testing ADC auth.’); console.log(‘Response:’, result.response.text()); }

test().catch(console.error);

bash node test-vertex-adc.js

Salida esperada:

Response: Hello! I’m ready to help you test…

Paso 4: Verificar que no se requiere archivo de clave API

bash

Confirm auth-profiles.json does NOT need google-vertex entry

cat ~/.openclaw/auth-profiles.json | jq ‘.[“google-vertex”]’

Expected: null (no entry needed)

Paso 5: Prueba de integración con la API de sesiones

bash

Create session with google-vertex sub-agent

curl -X POST http://localhost:3000/v1/sessions
-H “Content-Type: application/json”
-d ‘{ “agentType”: “sub-agent”, “provider”: “google-vertex”, “model”: “gemini-2.0-flash-001” }’

Verify response does NOT contain auth error

Expected: 200 OK with session object

1. Variables de entorno faltantes

Síntoma: El SDK falla silenciosamente o lanza errores crípticos de credenciales.

• GOOGLE_CLOUD_PROJECT — Requerido para todas las llamadas a Vertex AI
• GOOGLE_CLOUD_LOCATION — Requerido (ej. us-central1, europe-west4)
• GOOGLE_APPLICATION_CREDENTIALS — Requerido para desarrollo local; opcional en infraestructura GCP

Solución: Añadir al archivo .env o configuración de despliegue:

GOOGLE_CLOUD_PROJECT=my-gcp-project
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_APPLICATION_CREDENTIALS=/secrets/service-account.json

2. Credenciales de cuenta de servicio expiradas o inválidas

Síntoma: Error: Unable to read credential file o PERMISSION_DENIED

bash

Verify service account key is valid

cat $GOOGLE_APPLICATION_CREDENTIALS | jq ‘.type’ # Should output “service_account”

Check service account has Vertex AI permissions

gcloud projects get-iam-policy $GOOGLE_CLOUD_PROJECT
–filter=“bindings.members:serviceAccount:YOUR-SA@PROJECT.iam.gserviceaccount.com”

3. Normalización incorrecta del nombre del proveedor

Síntoma: El gate de autenticación pasa pero el SDK falla con UNKNOWN_PROVIDER.

OpenClaw normaliza los nombres de proveedores a kebab-case. Asegúrate de usar:

• google-vertex (correcto)
• ❌ google_vertex (incorrecto)
• ❌ GoogleVertexAI (incorrecto)
• ❌ vertex-ai (incorrecto - este es un proveedor diferente)

4. Mezclar autenticación con clave API y ADC

Síntoma: El sub-agente funciona pero usa credenciales incorrectas (clave API del usuario vs. cuenta de servicio).

Si la variable de entorno GOOGLE_API_KEY está configurada, el SDK @google/genai puede preferirla sobre ADC. Para uso exclusivo de ADC:

bash unset GOOGLE_API_KEY

5. Entorno de contenedor Docker

Síntoma: Funciona localmente pero falla en Docker con ADC resolution failed.

Al ejecutar dentro de Docker:

• Montar el JSON de la cuenta de servicio:

  docker run -v /path/to/service-account.json:/secrets/sa.json \
        -e GOOGLE_APPLICATION_CREDENTIALS=/secrets/sa.json \
        my-openclaw-image

• O usar Docker con identidad de carga de trabajo GCP:

  docker run --device /dev/sdb ...  # Not recommended for security

6. Discrepancia de región

Síntoma: INVALID_ARGUMENT: Region 'us-central1' is not supported for model 'gemini-2.0-flash-001'

Verificar la disponibilidad del modelo en tu región:

gcloud ai models list --region us-central1

• NO_API_KEY_FOUND

  Error genérico cuando no hay credenciales configuradas para ningún proveedor. Puede afectar a cualquier proveedor cuando auth-profiles.json está vacío o corrupto.

• AUTH_MODE_UNSUPPORTED

  Lanzado por model-selection.js cuando el modo de autenticación no está en la lista blanca. Ocurre después de la corrección del paso a través ADC si pi-embedded-*.js no se actualiza también.

• AWS_SDK_AUTH_FAILED

  Análogo al problema de Google Vertex para Bedrock. Ocurre cuando las credenciales de AWS faltan o están expiradas, y amazon-bedrock se usa sin una configuración adecuada del rol IAM.

• GOOGLE_ADC_RESOLUTION_FAILED

  El error subyacente del SDK cuando Google ADC no puede encontrar credenciales válidas. Esto debería aparecer después de que el gate de autenticación de OpenClaw pase, indicando que el paso a través funciona pero la configuración ADC subyacente está rota.

• SESSION_SPAWN_AUTH_BLOCKED

  Error del manejador sessions_spawn cuando el resolvedor de autenticación lanza una excepción. El mensaje de error específico indicará "No API key found for provider 'google-vertex'".

• INVALID_AUTH_MODE_TRANSITION

  Ocurre en configuraciones de alta seguridad donde los modos de autenticación no pueden transicionar de api-key a adc en tiempo de ejecución.

Contexto histórico