Primäre Fehlermanifestation

Wenn ein Sub-Agent versucht, den google-vertex-Provider zu verwenden, löst der Authentifizierungs-Resolver einen blockierenden Fehler aus, bevor das Google SDK initialisiert werden kann:

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)

CLI-Reproduktionsschritte

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” }’

Erwartetes vs. tatsächliches Verhalten

Umgebungskontext

• Plattform: macOS 26.3 (arm64) / Linux
• OpenClaw Version: 2026.2.26
• SDK: @google/genai
• Auth-Typ: Google Application Default Credentials (Service-Konto)

Architekturanalyse

1. Die Auth-Gate-Architektur

OpenClaw implementiert einen zentralisierten Authentifizierungs-Resolver in resolveApiKeyForProvider(), der eine API-Schlüssel-Validierung für alle Provider vor der Anfrageverarbeitung erzwingt:

// 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. Das Bedrock-Ausnahmemuster

amazon-bedrock wurde eine Ausnahme gewährt, da es AWS SDK-Anmeldedaten verwendet (IAM-Rollen, Umgebungsvariablen, EC2-Metadaten) anstatt statischer API-Schlüssel:

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

3. Die fehlende google-vertex-Ausnahme

Google Vertex AI verwendet ein identisches Authentifizierungsmuster – Application Default Credentials – verfügt jedoch nicht über die entsprechende Ausnahme. Die Auflösungs-Kette verläuft wie folgt:

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. Nachgelagerte Auswirkungen bei der Modellauswahl

Die pi-embedded-*.js-Modusvalidierung erfordert ferner explizites Whitelisting von Nicht-API-Key-Modi:

// 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. SDK- vs. Plattform-Authentifizierungs-Mismatch

Das @google/genai SDK ist darauf ausgelegt, automatisch Anmeldedaten aus folgenden Quellen aufzulösen:

• GOOGLE_APPLICATION_CREDENTIALS (Service-Konto-JSON)
• GOOGLE_CLOUD_PROJECT (Projekt-ID)
• GOOGLE_CLOUD_LOCATION (Region, z.B. us-central1)
• Angehängtes Service-Konto (GCE, Cloud Run usw.)

OpenClaw’s API-Key-Gate fängt die Anfrage ab, bevor das SDK seine native Authentifizierung durchführen kann, was eine unmögliche Anforderung schafft.

Voraussetzungen

• Verifizieren Sie, dass Google ADC korrekt konfiguriert ist:

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

• Setzen Sie die erforderlichen Umgebungsvariablen:

  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

Speicherort: src/auth/auth-profiles.js (oder dist/-Äquivalent)

Aktion: Fügen Sie einen ADC-Passthrough für google-vertex nach der Bedrock-Ausnahme hinzu.

Vorher

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

Nachher

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

Speicherort: src/model-selection/model-selection.js

Aktion: Fügen Sie "adc" zur Liste der akzeptierten Modi hinzu.

Vorher

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

Nachher

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 (Gateway-Modus-Prüfung)

Speicherort: src/gateway/pi-embedded.js oder Äquivalent

Aktion: Stellen Sie sicher, dass der ADC-Modus in der Gateway-Authentifizierungsprüfung akzeptiert wird.

Vorher

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

Nachher

// 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");
  }
}

Alternative: Konfigurationsbasierte Lösung

Wenn Sie es vorziehen, keine Quelldateien zu patchen, fügen Sie Ihrer openclaw.config.js hinzu:

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

Schritt 1: Überprüfen, ob der Auth-Resolver den ADC-Modus zurückgibt

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)); "

Erwartete Ausgabe:

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

Schritt 2: Überprüfen, ob das Sub-Agent-Spawn funktioniert

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

Erwartete Ausgabe:

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

Schritt 3: Überprüfen des tatsächlichen Vertex-API-Aufrufs

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

Erwartete Ausgabe:

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

Schritt 4: Überprüfen, dass keine API-Key-Datei erforderlich ist

bash

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

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

Expected: null (no entry needed)

Schritt 5: Integrationstest mit der Sessions-API

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. Fehlende Umgebungsvariablen

Symptom: SDK schlägt stillschweigend fehl oder wirft kryptische Anmeldedaten-Fehler.

• GOOGLE_CLOUD_PROJECT — Erforderlich für alle Vertex AI-Aufrufe
• GOOGLE_CLOUD_LOCATION — Erforderlich (z.B. us-central1, europe-west4)
• GOOGLE_APPLICATION_CREDENTIALS — Erforderlich für lokale Entwicklung; optional bei GCP-Infrastruktur

Lösung: Zu .env-Datei oder Deployment-Konfiguration hinzufügen:

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

2. Abgelaufene oder ungültige Service-Konto-Anmeldedaten

Symptom: Error: Unable to read credential file oder 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:[email protected]”

3. Falsche Provider-Namens-Normalisierung

Symptom: Auth-Gate passiert, aber SDK schlägt mit UNKNOWN_PROVIDER fehl.

OpenClaw normalisiert Provider-Namen zu kebab-case. Stellen Sie sicher, dass Sie verwenden:

• google-vertex (korrekt)
• ❌ google_vertex (inkorrekt)
• ❌ GoogleVertexAI (inkorrekt)
• ❌ vertex-ai (inkorrekt - dies ist ein anderer Provider)

4. Vermischung von API-Key- und ADC-Authentifizierung

Symptom: Sub-Agent funktioniert, aber verwendet falsche Anmeldedaten (User's API-Key vs. Service-Konto).

Wenn die Umgebungsvariable GOOGLE_API_KEY gesetzt ist, bevorzugt das @google/genai SDK diese möglicherweise gegenüber ADC. Für ausschließliche ADC-Nutzung:

bash unset GOOGLE_API_KEY

5. Docker-Container-Umgebung

Symptom: Funktioniert lokal, schlägt aber in Docker mit ADC resolution failed fehl.

Bei der Ausführung in Docker:

• Mounten Sie das Service-Konto-JSON:

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

• Oder verwenden Sie Docker mit GCP Workload Identity:

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

6. Regions-Mismatch

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

Verifizieren Sie die Modellverfügbarkeit in Ihrer Region:

gcloud ai models list --region us-central1

• NO_API_KEY_FOUND

  Allgemeiner Fehler, wenn keine Anmeldedaten für irgendeinen Provider konfiguriert sind. Kann jeden Provider betreffen, wenn auth-profiles.json leer oder beschädigt ist.

• AUTH_MODE_UNSUPPORTED

  Von model-selection.js geworfen, wenn der Authentifizierungsmodus nicht auf der Whitelist steht. Tritt nach dem ADC-Passthrough-Fix auf, wenn pi-embedded-*.js nicht ebenfalls aktualisiert wurde.

• AWS_SDK_AUTH_FAILED

  Analog zum Google Vertex-Problem für Bedrock. Tritt auf, wenn AWS-Anmeldedaten fehlen oder abgelaufen sind und amazon-bedrock ohne ordnungsgemäße IAM-Rollen-Konfiguration verwendet wird.

• GOOGLE_ADC_RESOLUTION_FAILED

  Der zugrunde liegende SDK-Fehler, wenn Google ADC keine gültigen Anmeldedaten finden kann. Dies sollte nach dem Passieren von OpenClaw's Auth-Gate auftreten, was darauf hindeutet, dass der Passthrough funktioniert, aber das zugrunde liegende ADC-Setup fehlerhaft ist.

• SESSION_SPAWN_AUTH_BLOCKED

  Fehler vom sessions_spawn-Handler, wenn der Auth-Resolver einen Fehler wirft. Die spezifische Fehlermeldung wird „No API key found for provider 'google-vertex'" anzeigen.

• INVALID_AUTH_MODE_TRANSITION

  Tritt in Hochsicherheitskonfigurationen auf, in denen Auth-Modi nicht zur Laufzeit von api-key auf adc übergehen können.

Historischer Kontext