docs(google-vertex): clarify auth gate, onboarding, and test contracts

koverholt · koverholt · commit d06267a51732 · 2026-06-01T12:56:39.000-05:00
Add inline comments at the three locations flagged by review:
- env-api-keys.ts: explain the intentionally permissive auth gate and
  where invalid setups fail (request time, not gate time)
- provider-contract-api.ts: document that onboarding writes are additive
  and reruns preserve existing models
- model-auth.profiles.test.ts: explain why the missing-explicit-path
  rejection test still passes with env-vars-with-marker evidence
diff --git a/extensions/google/provider-contract-api.ts b/extensions/google/provider-contract-api.ts
@@ -96,6 +96,9 @@ export function createGoogleVertexProvider(): ProviderPlugin {
               ? locationPrompt.trim()
               : VERTEX_DEFAULT_LOCATION;
 
+          // Onboarding writes are additive: env vars, marker profile, and
+          // default model. Reruns preserve existing google-vertex models
+          // via the configPatch merge below.
           return {
             profiles: [
               {
diff --git a/src/agents/model-auth.profiles.test.ts b/src/agents/model-auth.profiles.test.ts
@@ -1457,6 +1457,10 @@ describe("getApiKeyForModel", () => {
     }
   });
 
+  // The env-vars-with-marker evidence entry added for metadata-server ADC does
+  // not affect this test: resolveEnvApiKey uses precomputed authEvidenceMap from
+  // plugin manifests, and the test harness does not load the google plugin
+  // manifest, so only the local-file-with-env entry is evaluated.
   it("resolveEnvApiKey('google-vertex') rejects missing explicit ADC path before fallback paths", async () => {
     const homeDir = await fs.mkdtemp(path.join(os.tmpdir(), "openclaw-google-adc-home-"));
     const fallbackDir = path.join(homeDir, ".config", "gcloud");
diff --git a/src/llm/env-api-keys.ts b/src/llm/env-api-keys.ts
@@ -235,6 +235,10 @@ export function getEnvApiKey(provider: string): string | undefined {
     );
     const hasCredentialsEnv = Boolean(getEnvValue("GOOGLE_APPLICATION_CREDENTIALS"));
 
+    // Intentionally permissive: any signal of GCP intent passes the gate.
+    // Actual credential resolution happens at request time in vertex-adc.ts.
+    // Invalid setups (e.g. stale GOOGLE_APPLICATION_CREDENTIALS path with
+    // project env) will fail with a GoogleAuth error, not "No API key found."
     if (hasProject || hasCredentials || hasCredentialsEnv) {
       return "<authenticated>";
     }

Original file line number	Diff line number	Diff line change
`@@ -96,6 +96,9 @@ export function createGoogleVertexProvider(): ProviderPlugin {`
`96`	`96`	`? locationPrompt.trim()`
`97`	`97`	`: VERTEX_DEFAULT_LOCATION;`
`98`	`98`
	`99`	`+ // Onboarding writes are additive: env vars, marker profile, and`
	`100`	`+ // default model. Reruns preserve existing google-vertex models`
	`101`	`+ // via the configPatch merge below.`
`99`	`102`	`return {`
`100`	`103`	`profiles: [`
`101`	`104`	`{`