主要错误表现

当子代理尝试使用 google-vertex 提供商时，身份验证解析器在 Google SDK 初始化之前抛出阻塞错误：

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 重现步骤

bash

尝试使用 google-vertex 提供商生成子代理

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

预期与实际行为

环境上下文

• 平台： macOS 26.3 (arm64) / Linux
• OpenClaw 版本： 2026.2.26
• SDK： @google/genai
• 认证类型： Google Application Default Credentials（服务账号）

架构分析

1. 认证门架构

OpenClaw 在 resolveApiKeyForProvider() 中实现集中式身份验证解析器，在请求处理前强制执行所有提供商的 API 密钥验证：

// 简化的认证门逻辑 (auth-profiles.js)
function resolveApiKeyForProvider(provider, authStore) {
  // ... 规范化逻辑 ...
  
  if (authOverride !== void 0) {
    return { apiKey: authOverride, source: "manual-override", mode: "api-key" };
  }
  
  // 检查 auth store 中的存储凭证
  const stored = authStore[normalized];
  if (stored) {
    return parseStoredCredentials(stored);
  }
  
  // 认证门：如果未找到凭证则阻止
  throw new Error(`No API key found for provider "${normalized}"...`);
}

2. Bedrock 异常模式

amazon-bedrock 被授予异常，因为它使用 AWS SDK 凭证（IAM 角色、环境变量、EC2 元数据）而非静态 API 密钥：

// auth-profiles.js (现有的 Bedrock 异常)
if (authOverride === void 0 && normalized === "amazon-bedrock") {
  return resolveAwsSdkAuthInfo();  // 返回 { mode: "aws-sdk" }
}

3. 缺失的 google-vertex 异常

Google Vertex AI 使用相同的身份验证模式——Application Default Credentials——但缺少对应的异常。解析链执行如下：

resolveApiKeyForProvider("google-vertex")
  → normalized = "google-vertex"
  → authOverride = undefined
  → normalized !== "amazon-bedrock" (跳过)
  → authStore["google-vertex"] = undefined (无存储凭证)
  → throw Error("No API key found...")  ← 在此处被阻止

4. 模型选择中的下游影响

pi-embedded-*.js 模式验证进一步要求明确地将非 API 密钥模式列入白名单：

// model-selection.js (当前限制性检查)
if (apiKeyInfo.mode !== "aws-sdk" && apiKeyInfo.mode !== "api-key") {
  throw new Error("Invalid auth mode for model selection...");
}
// google-vertex ADC 模式 ("adc") 也会在此检查中失败

5. SDK 与平台身份验证不匹配

@google/genai SDK 设计为自动从以下来源解析凭证：

• GOOGLE_APPLICATION_CREDENTIALS（服务账号 JSON）
• GOOGLE_CLOUD_PROJECT（项目 ID）
• GOOGLE_CLOUD_LOCATION（区域，如 us-central1）
• 附加的服务账号（GCE、Cloud Run 等）

OpenClaw 的 API 密钥门在 SDK 执行其原生身份验证之前拦截请求，造成了一个不可能的要求。

前置条件

• 验证 Google ADC 已正确配置：

  # 检查服务账号凭证是否存在
  ls -la $GOOGLE_APPLICATION_CREDENTIALS
  验证 gcloud 认证（替代方案）
  gcloud auth application-default login
  测试 SDK 可以解析凭证
  node -e “const {GoogleAuth} = require(‘google-auth-library’); new GoogleAuth().getClient()"

• 设置所需的环境变量：

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

补丁 1：auth-profiles.js

位置： src/auth/auth-profiles.js（或 dist/ 等效文件）

操作： 在 Bedrock 异常之后添加 google-vertex 的 ADC 透传。

修改前

if (authOverride === void 0 && normalized === "amazon-bedrock") {
  return resolveAwsSdkAuthInfo();
}
// ... resolver 的其余部分

修改后

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

// Google Vertex AI ADC 透传
if (authOverride === void 0 && normalized === "google-vertex") {
  return {
    apiKey: "adc-passthrough",
    source: "google-adc",
    mode: "adc"
  };
}
// ... resolver 的其余部分

补丁 2：model-selection.js

位置： src/model-selection/model-selection.js

操作： 将 "adc" 添加到可接受的模式列表中。

修改前

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

修改后

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

补丁 3：pi-embedded-*.js（网关模式检查）

位置： src/gateway/pi-embedded.js 或等效文件

操作： 确保 ADC 模式在网关身份验证检查中被接受。

修改前

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

修改后

// 验证 ADC 提供商的 GOOGLE_* 环境变量是否存在
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");
  }
}

替代方案：基于配置的修复

如果您不想修补源文件，请添加到您的 openclaw.config.js 中：

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

步骤 1：验证 Auth Resolver 返回 ADC 模式

bash

在 OpenClaw 上下文中启动 Node REPL

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

预期输出：

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

步骤 2：验证子代理生成是否正常工作

bash

设置环境变量

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

通过 CLI 测试子代理生成

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

预期输出：

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

步骤 3：验证实际的 Vertex API 调用

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

预期输出：

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

步骤 4：验证不需要 API 密钥文件

bash

确认 auth-profiles.json 不需要 google-vertex 条目

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

预期：null（不需要条目）

步骤 5：与 Sessions API 的集成测试

bash

使用 google-vertex 子代理创建会话

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

验证响应不包含认证错误

预期：200 OK 以及会话对象

1. 缺少环境变量

症状： SDK 静默失败或抛出模糊的凭证错误。

• GOOGLE_CLOUD_PROJECT — 所有 Vertex AI 调用必需
• GOOGLE_CLOUD_LOCATION — 必需（如 us-central1、europe-west4）
• GOOGLE_APPLICATION_CREDENTIALS — 本地开发必需；在 GCP 基础设施上可选

修复： 添加到 .env 文件或部署配置中：

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

2. 服务账号凭证过期或无效

症状： Error: Unable to read credential file 或 PERMISSION_DENIED

bash

验证服务账号密钥有效

cat $GOOGLE_APPLICATION_CREDENTIALS | jq ‘.type’ # 应输出 “service_account”

检查服务账号是否具有 Vertex AI 权限

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

3. 提供商名称规范化错误

症状： 认证门通过但 SDK 失败并显示 UNKNOWN_PROVIDER。

OpenClaw 将提供商名称规范化为 kebab-case。请确保使用：

• google-vertex（正确）
• ❌ google_vertex（错误）
• ❌ GoogleVertexAI（错误）
• ❌ vertex-ai（错误 - 这是不同的提供商）

4. 混用 API 密钥和 ADC 身份验证

症状： 子代理工作但使用了错误的凭证（用户的 API 密钥与服务账号）。

如果设置了 GOOGLE_API_KEY 环境变量，@google/genai SDK 可能优先使用它而非 ADC。如需纯 ADC 使用：

bash unset GOOGLE_API_KEY

5. Docker 容器环境

症状： 本地工作正常但在 Docker 中失败并显示 ADC resolution failed。

在 Docker 内部运行时：

• 挂载服务账号 JSON：

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

• 或使用带有 GCP 工作负载身份认证的 Docker：

  docker run --device /dev/sdb ...  # 不建议出于安全考虑

6. 区域不匹配

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

验证模型在您所在区域的可用性：

gcloud ai models list --region us-central1

• NO_API_KEY_FOUND

  当任何提供商未配置凭证时的通用错误。当 auth-profiles.json 为空或损坏时可能影响任何提供商。

• AUTH_MODE_UNSUPPORTED

  当认证模式不在白名单中时由 model-selection.js 抛出。如果未同时更新 pi-embedded-*.js，则在 ADC 透传修复后也会发生此错误。

• AWS_SDK_AUTH_FAILED

  与 Google Vertex 问题类似，用于 Bedrock。当 AWS 凭证缺失或过期，且 amazon-bedrock 在没有正确 IAM 角色配置的情况下使用时发生。

• GOOGLE_ADC_RESOLUTION_FAILED

  当 Google ADC 找不到有效凭证时的底层 SDK 错误。这应该在 OpenClaw 的认证门通过后浮出水面，表明透传正常工作但底层 ADC 设置有问题。

• SESSION_SPAWN_AUTH_BLOCKED

  当认证解析器抛出异常时来自 sessions_spawn 处理程序的错误。具体的错误消息将显示"No API key found for provider 'google-vertex'"。

• INVALID_AUTH_MODE_TRANSITION

  在高安全配置中发生，其中认证模式不能在运行时从 api-key 转换到 adc。

历史背景