Skip to content

fix(google-vertex): add Google Vertex AI onboarding wizard, fix ADC auth, add provider docs#87800

Open
koverholt wants to merge 33 commits into
openclaw:mainfrom
koverholt:fix/google-vertex-adc-end-to-end
Open

fix(google-vertex): add Google Vertex AI onboarding wizard, fix ADC auth, add provider docs#87800
koverholt wants to merge 33 commits into
openclaw:mainfrom
koverholt:fix/google-vertex-adc-end-to-end

Conversation

@koverholt

@koverholt koverholt commented May 28, 2026

Copy link
Copy Markdown

Summary

What problem does this PR solve?

The google-vertex provider does not work end-to-end for developers using Application Default Credentials (ADC). The auth gate requires a credentials file on disk, rejecting metadata server ADC (GCE/GKE/Cloud Run) before the transport layer can run. The onboarding wizard has no auth flow for google-vertex, doesn't register models in the provider config, doesn't prompt for GCP project/location, has no model catalog, and has no dedicated documentation.

Why does this matter now?

Multiple open issues document this problem (#56253, #79595, #85864, #79837, #11413). We reproduced the issue on a fresh install: a new OpenClaw install requires numerous manual undocumented steps and manual edits to JSON config to get a working google-vertex setup. Users on GCE/GKE with valid GCP credentials consistently hit "No API key found" because the auth gate only accepts file-based ADC.

What is the intended outcome?

A developer picks "Google Vertex AI" in the onboarding wizard, confirms their auto-detected GCP project, and sends a message. Three steps without manual config editing.

What is intentionally out of scope?

  • Changes to the google (AI Studio) or google-gemini-cli providers

What does success look like?

openclaw onboard --auth-choice google-vertex-adc on a GCE VM (or any machine with ADC configured) produces a working setup with zero manual config editing.

What should reviewers focus on?

  • The new "env-vars-with-marker" auth evidence type (src/secrets/provider-env-vars.ts, src/plugins/manifest.ts, src/agents/model-auth-env.ts)
  • The relaxed auth gate in src/llm/env-api-keys.ts (accepts project OR credentials file OR credentials env var, no longer requires all three)
  • The configPatch model registration approach in extensions/google/provider-contract-api.ts (workaround for applyPrimaryModel not persisting models.providers through the wizard config serialization)
  • The gcp-vertex-credentials marker profile stored during onboarding for auth detection

All changes were reviewed and tested by the author on a fresh VM.

Linked context

Which issue does this close?

Related #56253, #85864, #79595, #79837, #11413

Which issues, PRs, or discussions are related?

Related #49191, #50053, #52476, #48910, #77643, #55572, #53566, #9729

See also #83971 (merged, fixed transport-layer ADC but not the upstream auth gate)

Was this requested by a maintainer or owner?

No. Reproduced independently on a GCE VM based on multiple open issues reporting the same auth failure.

Real behavior proof (required for external PRs)

  • Behavior or issue addressed: google-vertex provider fails with "No API key found" on GCE VMs using metadata server ADC. Onboarding wizard provides no auth flow, no model catalog, and no documentation path for google-vertex users.
  • Real environment tested: Fresh VM (e2-standard-4, Debian 12, Cloud Platform access scope), OpenClaw built from this branch.
  • Exact steps or command run after this patch:
    pnpm openclaw uninstall --all --yes
    pnpm openclaw onboard --auth-choice google-vertex-adc
    # Confirmed auto-detected project
    # Accepted "global" location
    # Kept default model (google-vertex/gemini-flash-latest)
    # Hatched in Terminal, sent "Wake up, my friend!"
  • Evidence after fix:
Screenshot 2026-05-28 at 17 31 32 Screenshot 2026-05-28 at 17 33 12
  • Observed result after fix: Gemini responded successfully via Vertex AI with ADC from the GCE metadata server. No auth warnings during onboarding. Model catalog populated in "Browse all models." Project auto-detected. Default model gemini-flash-latest set and registered in provider config.
  • What was not tested: gcloud CLI auth path (local development), service account key file auth, Windows environments, non-GCE cloud VMs.
  • Proof limitations or environment constraints: The gcloud CLI and service account key auth paths follow the same downstream transport code (vertex-adc.ts) which is unchanged; only the upstream auth gate and wizard flow are new.
  • Before evidence: Same VM, same credentials, fresh OpenClaw install produced "No API key found for provider google-vertex" on both v2026.5.27 (npm release) and v2026.5.28 (main branch pre-patch). Direct curl to the Vertex AI endpoint with the same metadata server credentials succeeded, confirming the issue is in OpenClaw's auth gate.

Tests and validation

Which commands did you run?

pnpm build                    # clean, no errors
pnpm check                    # typecheck + lint passed
pnpm test:extension google    # 293 tests, all passed

End-to-end onboarding and API call on GCE VM validated across multiple iterations.

What regression coverage was added or updated?

No new unit tests. Existing tests for hasVertexAdcCredentials, resolveAuthEvidence, normalizeManifestSetupProviderAuthEvidence, and the google extension transport/auth tests (293 tests) cover the touched code paths and all passed.

What failed before this fix, if known?

"No API key found for provider google-vertex" on any environment using metadata server ADC (GCE, GKE, Cloud Run). Also: "Unknown model" after onboarding (wizard didn't register models in provider config), requests routed to OpenAI endpoints (wrong default transport type), empty model catalog in "Browse all models," no auth flow during onboarding.

If no test was added, why not?

The changes span auth gating, manifest parsing, wizard flow, model resolution, and transport defaults across multiple subsystems. Real behavior proof from a GCE VM is more representative than unit tests for this class of end-to-end configuration issue.

Risk checklist

Did user-visible behavior change? Yes. New wizard auth flow for google-vertex (project auto-detection, location default, model catalog). New default model gemini-flash-latest. "Google Vertex AI" label in wizard (was "Google Vertex"). New dedicated docs page.

Did config, environment, or migration behavior change? Yes. New "env-vars-with-marker" auth evidence type in the plugin manifest system. GOOGLE_CLOUD_LOCATION no longer required (defaults to "global"). Auth gate accepts GOOGLE_CLOUD_PROJECT alone without requiring a credentials file on disk.

Did security, auth, secrets, network, or tool execution behavior change? Yes. The auth gate is more permissive: accepts project env var OR credentials file OR credentials env var (previously required all three of: file + project + location). The gcp-vertex-credentials marker is stored as an auth profile credential during onboarding. nonSecretAuthMarkers added to the google plugin manifest.

What is the highest-risk area?

The relaxed auth gate in src/llm/env-api-keys.ts. Previously required hasCredentials && hasProject && hasLocation. Now accepts hasProject || hasCredentials || hasCredentialsEnv.

How is that risk mitigated?

The downstream transport (extensions/google/vertex-adc.ts) validates credentials at request time via google-auth-library's GoogleAuth. If ADC is not actually available, the request fails with a clear error ("Google Vertex ADC fallback did not return an access token") rather than the opaque "No API key found" gate error. The gate change only affects whether the request reaches the transport layer, not whether it succeeds.

Current review state

What is the next action?

Ready for maintainer review.

What is still waiting on author, maintainer, CI, or external proof?

Nothing blocking. pnpm test:extension google (293 tests) and pnpm check (typecheck + lint) passed cleanly.

Which bot or reviewer comments were addressed?

N/A (new PR).

@koverholt koverholt requested a review from a team as a code owner May 28, 2026 22:36
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation agents Agent runtime and tooling extensions: google size: M proof: supplied External PR includes structured after-fix real behavior proof. labels May 28, 2026
@koverholt koverholt changed the title Fix/google vertex adc end to end fix(google-vertex): fix ADC auth gate, add onboarding flow and provider docs May 28, 2026
@clawsweeper

clawsweeper Bot commented May 28, 2026

Copy link
Copy Markdown
Contributor

Codex review: needs maintainer review before merge. Reviewed June 1, 2026, 3:07 PM ET / 19:07 UTC.

Summary
The PR adds google-vertex ADC onboarding and docs, introduces marker-based auth evidence, updates Google plugin catalog/setup metadata, and adjusts Vertex routing/default-location behavior.

PR surface: Source +276, Tests +8, Docs +270. Total +554 across 17 files.

Reproducibility: yes. from source and supplied proof: current main still has stricter google-vertex ADC gating and fallback routing gaps, while the PR shows a real GCE VM onboarding and response path after the change; I did not rerun a live GCE VM in this read-only review.

Review metrics: 2 noteworthy metrics.

  • Config/auth surfaces changed: 1 auth evidence type added; 1 setup auth choice added; 1 marker profile/default config path added. These surfaces affect how existing and fresh google-vertex users are detected, onboarded, and upgraded.
  • Provider routing defaults changed: 1 provider-name default added for google-vertex. The route fixes a real fallback bug but moves provider-specific behavior into a core model-resolution path.

Merge readiness
Overall: 🐚 platinum hermit
Proof: 🦞 diamond lobster ✨ media proof bonus
Patch quality: 🐚 platinum hermit
Result: ready for maintainer review.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

  • [P2] Get explicit maintainer acceptance of marker-based auth presence and the google-vertex core fallback before merge.

Risk before merge

  • [P1] The PR intentionally makes google-vertex auth presence marker-based and more permissive, so a setup with partial ADC environment can look configured and then fail at request time instead of being rejected earlier.
  • [P1] The onboarding flow writes provider defaults, a marker profile, default model, and default location; existing or rerun setups need maintainer acceptance that the merge/upgrade behavior is the desired public contract.
  • [P2] The core fallback now contains a google-vertex provider-name default to avoid openai-responses routing; that fixes the reported path but creates a provider-specific core exception that maintainers should explicitly accept.

Maintainer options:

  1. Accept marker-based ADC gating (recommended)
    A maintainer can land this if they explicitly accept that google-vertex may show auth as available from marker/environment evidence and let invalid ADC fail at request time.
  2. Strengthen upgrade proof first
    Before merge, require focused proof or tests for rerunning onboarding over an existing google-vertex config and for both service-account and gcloud ADC paths.
  3. Move routing back behind a generic seam
    If provider-specific core fallback is not acceptable, pause the PR until the plugin normalize/default API seam can cover the google-vertex fallback path without a core special case.

Next step before merge

  • [P2] The remaining action is maintainer judgment on compatibility and provider-auth contract changes, not a narrow ClawSweeper repair.

Security
Cleared: No concrete security or supply-chain regression found; the auth marker is non-secret and real ADC resolution still occurs through google-auth-library at request time.

Review details

Best possible solution:

Land only after maintainers accept the auth-gate, default-config, and routing tradeoffs as the google-vertex provider contract, or narrow the patch to an approved provider-auth seam before merge.

Do we have a high-confidence way to reproduce the issue?

Yes, from source and supplied proof: current main still has stricter google-vertex ADC gating and fallback routing gaps, while the PR shows a real GCE VM onboarding and response path after the change; I did not rerun a live GCE VM in this read-only review.

Is this the best way to solve the issue?

Yes, with maintainer acceptance: the Google-plugin onboarding/docs and generic marker evidence seam fit the existing ownership model, but the relaxed auth gate and provider-specific core fallback are compatibility-sensitive choices rather than automatic cleanup.

AGENTS.md: found and applied where relevant.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 65a805ac2878.

Label changes

Label justifications:

  • P2: This is a normal-priority provider/auth fix with meaningful user impact but limited blast radius to google-vertex users.
  • merge-risk: 🚨 compatibility: The PR changes auth detection, setup-written config, default model/location behavior, and rerun/upgrade expectations for google-vertex users.
  • merge-risk: 🚨 auth-provider: The PR changes how google-vertex ADC is detected, represented, and routed through the provider/auth stack.
  • rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🦞 diamond lobster and patch quality is 🐚 platinum hermit.
  • status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (screenshot): The PR supplies after-fix VM proof for google-vertex ADC onboarding and a successful model response, with the real-behavior proof check passing on the PR head.
  • proof: sufficient: Contributor real behavior proof is sufficient. The PR supplies after-fix VM proof for google-vertex ADC onboarding and a successful model response, with the real-behavior proof check passing on the PR head.
  • proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR supplies after-fix VM proof for google-vertex ADC onboarding and a successful model response, with the real-behavior proof check passing on the PR head.
Evidence reviewed

PR surface:

Source +276, Tests +8, Docs +270. Total +554 across 17 files.

View PR surface stats
Area Files Added Removed Net
Source 10 347 71 +276
Tests 3 10 2 +8
Docs 4 271 1 +270
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 17 628 74 +554

Acceptance criteria:

  • [P1] Review supplied GCE VM proof for google-vertex ADC onboarding and response.
  • [P1] Before landing, verify rerun/upgrade behavior over an existing google-vertex provider config.
  • [P1] Run the PR's stated provider checks such as pnpm build, pnpm check, and pnpm test:extension google in the normal maintainer validation path.

What I checked:

  • Repository review policy applied: Root AGENTS.md and relevant scoped guides require provider/auth/config/default/routing changes to be treated as compatibility-sensitive and reviewed against callers, siblings, tests, docs, and dependency contracts. (AGENTS.md, 65a805ac2878)
  • Google plugin owns the new onboarding flow: The PR adds a google-vertex ADC auth flow that dynamically imports GoogleAuth, prompts for project/location, writes a non-secret marker profile, and returns a config patch for GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and google-vertex model entries. (extensions/google/provider-contract-api.ts:47, d06267a51732)
  • Manifest/auth evidence seam extended: The PR adds the env-vars-with-marker evidence type and google-vertex nonSecretAuthMarkers/setup metadata so ADC presence can be represented without storing a real secret. (extensions/google/openclaw.plugin.json:48, d06267a51732)
  • Current-main ADC gate is stricter than the PR: Current main still requires google-vertex credentials, project, and location before returning the gcloud ADC marker from env API key detection, while the PR deliberately defers more validation to request time. (src/llm/env-api-keys.ts:226, 65a805ac2878)
  • Request-time ADC contract checked: google-auth-library's GoogleAuth project and ADC lookup paths include environment variables, credential files, Cloud SDK defaults, and GCE metadata before throwing when no ADC source exists, matching the PR's request-time validation design.
  • Provider routing change is real: Current main can still fall back to openai-responses in embedded model resolution when a google-vertex provider lacks an explicit api/baseUrl path; the PR adds a provider-name default to route google-vertex through its native transport. (src/agents/embedded-agent-runner/model.ts:717, 65a805ac2878)

Likely related people:

  • steipete: Recent history includes Vertex catalog/auth support and large agent-runtime/provider refactors touching the same Google provider and embedded routing surfaces. (role: recent google/provider runtime contributor; confidence: high; commits: fba9eac7, 0b59964, bb46b79; files: extensions/google/provider-registration.ts, extensions/google/vertex-adc.ts, src/agents/embedded-agent-runner/model.ts)
  • 1052326311: Recent provider default API routing work changed the same embedded fallback area that this PR adjusts for google-vertex. (role: recent provider routing contributor; confidence: medium; commits: b73e135f; files: src/agents/embedded-agent-runner/model.ts, extensions/google/provider-registration.ts)
  • damianFelixPago: Recent google-vertex production ADC work is adjacent to the auth and transport behavior this PR extends. (role: recent google-vertex ADC contributor; confidence: medium; commits: f09b4ebe; files: extensions/google/provider-registration.ts, extensions/google/transport-stream.ts, extensions/google/vertex-adc.ts)
  • sallyom: Recent plugin provider/auth integration work is adjacent to the manifest auth evidence surface changed by this PR. (role: recent plugin auth integration contributor; confidence: low; commits: 6037a746; files: src/plugins/manifest.ts, src/secrets/provider-env-vars.ts)
What the crustacean ranks mean
  • 🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
  • 🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
  • 🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
  • 🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
  • 🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
  • 🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
  • 🌊 off-meta tidepool: rating does not apply to this item.

Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

How this review workflow works
  • ClawSweeper keeps one durable marker-backed review comment per issue or PR.
  • Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
  • A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
  • PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
  • Maintainers can also comment @clawsweeper review to request a fresh review only.
  • Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
  • Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
  • Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.

@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. P2 Normal backlog priority with limited blast radius. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. labels May 28, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 28, 2026
@clawsweeper clawsweeper Bot added proof: sufficient ClawSweeper judged the real behavior proof convincing. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. and removed rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. labels May 28, 2026
@koverholt

Copy link
Copy Markdown
Author

Addressed the ClawSweeper review findings:

  • Stale model hint assertion (model.test.ts): Updated to expect the new format with both id and name fields (e73321d).
  • Auth gate test (env-api-keys.test.ts): Updated to expect "<authenticated>" when GOOGLE_CLOUD_PROJECT is set without a credentials file, matching the relaxed ADC gate behavior (c89c145).
  • Docs formatting: Applied pnpm format:docs to fix table alignment and component spacing (105dd22).

All CI checks pass.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented May 28, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

@clawsweeper

clawsweeper Bot commented May 28, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

Re-review progress:

@clawsweeper clawsweeper Bot added rating: 🦐 gold shrimp Decent PR readiness signal, but merge confidence is limited. status: ⏳ waiting on author ClawSweeper has contributor-facing work open and is waiting for author action. and removed rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR. labels May 28, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 28, 2026
@koverholt

koverholt commented May 28, 2026

Copy link
Copy Markdown
Author

Addressed the remaining finding:

  • Document env-vars-with-marker auth evidence type (docs/plugins/manifest.md): Updated the plugin manifest docs to describe the new env-vars-with-marker type alongside local-file-with-env, explaining when to use each (2ee6bec).

All CI checks pass. All review findings addressed.

@clawsweeper re-review

koverholt added 26 commits June 1, 2026 12:38
Narrow hasLocalFileAuthEvidence parameter type to the
"local-file-with-env" variant of the ProviderAuthEvidence union so
TypeScript can see fileEnvVar and fallbackPaths properties.

Cast the providers assignment in applyPrimaryModel to
OpenClawConfig["models"] to satisfy the Record<string,
ModelProviderConfig> constraint.
…t default

Add a static model catalog for the google-vertex provider, following the
same pattern as the google (AI Studio) provider's runtime catalog. The
catalog includes:

- Auto-updating latest aliases: gemini-flash-latest (default),
  gemini-pro-latest, gemini-flash-lite-latest
- Shared Gemini text models from the existing google catalog:
  gemini-3.1-pro-preview, gemini-3-flash-preview

The latest aliases always point to the latest stable model in each family
and are recommended for most users. gemini-flash-latest is tagged as the
default model and is set as the wizard default for new google-vertex
setups.

Update the docs page to document both latest aliases (recommended) and
specific version model IDs.
Change the google-vertex setup.providers authMethods from "api-key" to
"adc" so the auto-generated wizard choice matches our ADC auth method.

Previously the manifest declared authMethods: ["api-key"] but the
google-vertex provider had no auth method with id "api-key" (and the
original provider had auth: [] entirely). The wizard generated a choice
ID "google-vertex-api-key" that matched nothing, so selecting
"Google Vertex" in onboarding skipped the auth flow entirely.

Now the wizard generates "google-vertex-adc" which matches our ADC auth
method, triggering project auto-detection and config writing.
Move the google-vertex static model catalog from the TypeScript runtime
catalog (provider-catalog.ts / provider-discovery.ts) to the manifest
JSON (openclaw.plugin.json) with discovery: "static".

The model picker's "Browse all models" reads from manifest JSON via
planManifestModelCatalogRows, not from the staticCatalog.run callback.
The runtime catalog approach only served the "openclaw models list" CLI
command, leaving the model picker empty. Moving to manifest JSON serves
both paths.

Models: gemini-flash-latest (default), gemini-pro-latest,
gemini-flash-lite-latest, gemini-3.1-pro-preview, gemini-3-flash-preview.

Remove buildGoogleVertexStaticCatalogProvider() and revert
provider-discovery.ts to only return google (AI Studio) models. No
duplication, single source of truth in the manifest.
Add models.providers["google-vertex"].models to the auth flow's
configPatch so the default model (gemini-flash-latest) is registered
in the provider config when the config is written to disk.

The applyPrimaryModel path correctly sets models.providers in memory
but the value is lost during the wizard's config serialization. The
configPatch path persists reliably (proven by env values persisting
through the same mechanism).
Return a gcp-vertex-credentials marker profile from the google-vertex
auth flow instead of empty profiles. This makes the auth detection
system recognize google-vertex as having valid auth, which fixes:

1. The "No auth configured" warning during onboarding model check
2. The model picker auth filter dropping all google-vertex catalog
   models (only the configured model was visible)

Add nonSecretAuthMarkers: ["gcp-vertex-credentials"] to the google
plugin manifest so the auth system treats the marker as a non-secret
auth token. This matches the anthropic-vertex plugin which uses the
same marker for the same purpose (ADC-based auth with no real API key).

The transport layer recognizes the marker via
isGoogleVertexCredentialsMarker() and resolves a real Bearer token
via google-auth-library at request time.
Add an explicit providerAuthChoices entry for google-vertex to override
the auto-generated label. The auto-generation derives the label from the
provider id ("google-vertex" → "Google Vertex") which drops the "AI"
suffix. The explicit entry sets groupLabel to "Google Vertex AI" to
match the full product name.
…ss-references

Update the google-vertex docs page:
- Add models.providers section to the config example to match what
  onboarding actually writes
- Add Verify step to the service account tab
- Clarify that GOOGLE_CLOUD_PROJECT is auto-detected during onboarding
  on GCE/GKE
- Note that gemini-flash-latest is the default model set by onboarding
- Clarify that the OpenAI routing issue only affects custom configs

Add cross-references between google.md and google-vertex.md:
- Add a Note on the google.md page pointing users to google-vertex
  for GCP project billing and credits
- Add a Related card on google.md linking to google-vertex.md
…g entry

The transport type defaults to google-vertex automatically (commit
7ba19c8). No user going through the normal onboarding flow would
encounter this issue.
…ormatting

- Change GOOGLE_APPLICATION_CREDENTIALS default from "Auto-detected" to
  "None" since the env var is not auto-detected (the system falls back
  to the default gcloud ADC file path, but that is a file lookup, not
  env var detection)
- Add guidance to the "No API key found" troubleshooting entry noting
  this should not appear after onboarding and suggesting re-running
  onboarding if it does
- Remove stray blank line before closing AccordionGroup tag
Add providers/google-vertex to the Mintlify docs.json navigation config
so the page appears in the sidebar between Google (Gemini) and Gradium.
- Remove AI Studio comparison from intro paragraph and credits note.
  The page should describe what google-vertex is, not compare it to
  another provider.
- Rename "Local development" tab to "gcloud CLI" to match the
  credential type naming pattern used by other tabs. No other provider
  docs page uses "Local development" as a tab title.
- Fix Related card title from "Google (AI Studio)" to "Google (Gemini)"
  to match the actual page title of google.md.
- Update frontmatter summary to use "gcloud CLI" instead of "local dev"
- Fix "Best for" on gcloud CLI tab to remove "developing" assumption
- Remove "Model names are the same as on Google AI Studio" claim
- Update troubleshooting to say "With gcloud CLI" instead of "On local dev"
Replace "For local development" with "With gcloud CLI" in the wizard
provider notes to match the docs tab naming convention.
The configPatch models.providers entry omits baseUrl (which is required
by ModelProviderConfig) because google-vertex constructs URLs dynamically
from project/location. Cast the configPatch as Partial<OpenClawConfig> so
TypeScript accepts the partial provider config.
The stricter tsgo type checker rejects a direct cast from the
configPatch object literal to Partial<OpenClawConfig> because the
models.providers entry omits baseUrl. Use the standard unknown
intermediate cast pattern.
- Expand auth bullet to list credential sources (metadata server,
  gcloud CLI, service account key) instead of just saying "ADC"
- Remove API key comparison from read_when frontmatter since this page
  does not cover API key / Express Mode auth
- Change "auth method" to "setup" since the three tabs are different
  credential sources for the same auth method, not different methods
The project's lint rules require curly braces around if bodies.
Run pnpm format:docs to fix table column alignment and add required
blank lines before closing Mintlify component tags.
The test expected getEnvApiKey("google-vertex") to return undefined when
GOOGLE_CLOUD_PROJECT is set but no credentials file exists. With the
relaxed auth gate, GOOGLE_CLOUD_PROJECT alone is sufficient to return
"<authenticated>" since the downstream transport handles actual
credential resolution at request time via google-auth-library.
The missing-model registration hint now includes both id and name
fields (commit 0152bcc). Update the test assertion to expect the
new format.
Update the plugin manifest docs to describe the new env-vars-with-marker
auth evidence type alongside the existing local-file-with-env type.
Explains when to use each: local-file-with-env for credential files on
disk, env-vars-with-marker for ambient credential sources like GCE
metadata server or workload identity.
…istration

Fix two issues found by ClawSweeper re-review:

1. The configPatch in the google-vertex auth flow now reads existing
   models.providers["google-vertex"].models and merges the default model
   instead of replacing the array. Re-running onboarding no longer drops
   user-registered Vertex models.

2. applyPrimaryModel now only auto-registers models in models.providers
   for providers that already have a config entry. This prevents creating
   invalid provider config (missing baseUrl) for unknown custom providers
   when a user sets a manual slash-prefixed model.
Move the google-vertex API transport default from the core model
resolver (resolveProviderNameDefaultApi) into the Google plugin's
normalizeTransport hook. When the provider is google-vertex and no
api is explicitly set, the plugin now returns api: google-vertex.

This keeps provider-specific routing in the owning plugin instead of
the generic core resolver, matching the architectural pattern for
other provider plugins.
… path

Commit e4c0dd2 moved the google-vertex transport default from
resolveProviderNameDefaultApi in the core model resolver into the
Google plugin normalizeTransport hook. The hook only fires when
api is null/undefined, but the two fallback paths in model.ts
hardcode "openai-responses" as the default before the hook runs.
This caused google-vertex requests to route through the OpenAI
transport, sending the "gcp-vertex-credentials" marker as a literal
API key to platform.openai.com.

Restore resolveProviderNameDefaultApi in the core fallback chains
so it runs before the "openai-responses" default. Keep the plugin
hook as a redundant safety net for the discovered-model path.
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
@koverholt

Copy link
Copy Markdown
Author

Rebased onto latest main to resolve merge conflicts and clean up the diff.

Three files had conflicts with recent upstream changes (PR #88512 and direct maintainer commits):

  • src/llm/env-api-keys.ts: Adopted Boolean() lint syntax from deb7bc65, kept the relaxed ADC auth gate (OR logic, removed location requirement, added GOOGLE_APPLICATION_CREDENTIALS check)
  • src/agents/embedded-agent-runner/model.ts: Adopted the refactored provider-aware resolveConfiguredProviderDefaultApi from fix: resolve google provider default API to google-generative-ai #88512, kept resolveProviderNameDefaultApi as a fallback for providers with no baseUrl (the google-vertex ADC onboarding case, where the upstream refactor short-circuits at the !providerConfig?.baseUrl check)
  • extensions/google/provider-registration.ts: Merged the google-vertex transport guard with the upstream provider passthrough to resolveGoogleGenerativeAiTransport

All CI checks pass (136/136). Re-tested the full onboarding flow with OpenClaw running on a VM after the rebase: project auto-detection, ADC auth, model catalog, and Gemini response all working.

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

🦞🧹
ClawSweeper re-review requested.

I asked ClawSweeper to review this item again.
Action: item re-review queued (workflow sweep.yml, event repository_dispatch).
Result: the existing ClawSweeper review comment will be edited in place when the review finishes.

@koverholt

koverholt commented Jun 1, 2026

Copy link
Copy Markdown
Author

@clawsweeper re-review

@clawsweeper

clawsweeper Bot commented Jun 1, 2026

Copy link
Copy Markdown
Contributor

🦞👀
ClawSweeper picked this up.

Command router queued. I will update this comment with the next step.

Re-review progress:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agents Agent runtime and tooling docs Improvements or additions to documentation extensions: google merge-risk: 🚨 auth-provider 🚨 May break OAuth, tokens, provider routing, model choice, or credentials. merge-risk: 🚨 compatibility 🚨 May break existing users, config, migrations, defaults, or upgrade paths. P2 Normal backlog priority with limited blast radius. proof: 📸 screenshot Contributor real behavior proof includes screenshot evidence. proof: sufficient ClawSweeper judged the real behavior proof convincing. proof: supplied External PR includes structured after-fix real behavior proof. rating: 🐚 platinum hermit Good normal PR readiness with ordinary maintainer review expected. size: M status: 👀 ready for maintainer look ClawSweeper has no concrete contributor-facing blocker left for this PR.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants