Skip to content

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

Open
koverholt wants to merge 38 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 38 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 real behavior proof before merge. Reviewed July 25, 2026, 6:08 AM ET / 10:08 UTC.

ClawSweeper review

What this changes

Adds a Google Vertex AI onboarding path that records a GCP project and location, recognizes ambient ADC, registers Vertex models, selects the Vertex transport, and documents provider setup.

Merge readiness

Blocked until stronger real behavior proof is added - 5 items remain

Keep this PR open for human review: current main has parts of Google Vertex runtime support, but it still lacks the proposed onboarding/auth-evidence path, so the central user problem is not already implemented. The branch now changes the persisted onboarding environment shape after its visible GCE proof, so it needs fresh exact-head live proof as well as a maintainer decision on the compatibility-sensitive ADC contract. citeturn1fetch0turn2fetch0turn4fetch0.

Priority: P2
Reviewed head: a5c2b333db75946ec740162a4420b7b6fc3d71fb
Owner decision: Required. See Decision needed.

Review scores

Measure Result What it means
Overall readiness 🦪 silver shellfish (2/6) The patch has substantial useful implementation signal, but exact-head real-environment proof is stale relative to a setup-path change and the product contract remains undecided.
Proof confidence 🦪 silver shellfish (2/6) Needs stronger real behavior proof before merge: The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Patch quality 🦐 gold shrimp (3/6) No actionable review findings were identified.

Verification

Check Result Evidence
Real behavior Needs proof Needs stronger real behavior proof before merge: The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
Evidence reviewed 5 items Current main remains incomplete for metadata-server onboarding: Current main still declares Google Vertex setup with api-key and local-file auth evidence; it does not include the proposed non-secret ADC marker or environment-only evidence path. That confirms this PR's central onboarding/auth change is not already implemented.
Current main has partial overlapping Vertex runtime work: The Google plugin on current main already has Vertex catalog and transport handling, so this PR overlaps the active provider surface but still adds the missing setup/auth contract rather than duplicating an already-complete flow.
Current main still requires explicit project/location at the Vertex config-key boundary: The current Vertex configuration resolver accepts a key only when an ADC file signal, project, and location are present; the PR deliberately changes that gate and defaults location. This is a real auth/upgrade contract decision, not obsolete cleanup.
Findings None None.
Security None None.

How this fits together

OpenClaw onboarding gathers provider credentials and writes configuration, then the embedded agent resolves a configured model and routes requests through the provider plugin. This PR changes the Google Vertex portion of that path so ambient Google credentials can reach the existing Vertex transport instead of being rejected during setup.

flowchart LR
A[User runs onboarding] --> B[Google Vertex setup]
B --> C[Config environment values]
C --> D[Auth evidence check]
D --> E[Vertex transport]
E --> F[Gemini response]
B --> G[Model catalog and default]
Loading

Decision needed

Question Recommendation
Should OpenClaw make Google Vertex ambient ADC a supported onboarding path and extend manifest auth evidence so a configured GCP project can represent ambient credentials without a local credential file? Adopt the ambient ADC onboarding contract: Approve the provider-owned wizard and manifest evidence direction, then require a current-head live proof and upgrade coverage before merge.

Why: This is not only a bug repair: it adds a new provider onboarding route, a new manifest auth-evidence variant, and a different failure boundary for existing Google Vertex users.

Before merge

  • Add real behavior proof - Needs stronger real behavior proof before merge: The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
  • Resolve merge risk (P1) - The PR changes Google Vertex from file-and-location-gated auth discovery to project-backed ambient ADC discovery; existing installs may move from an immediate setup error to a request-time credential failure if project configuration is incomplete.
  • Resolve merge risk (P1) - The July 23, 2026 env.vars schema update directly affects the advertised fresh-install path, but the visible real-environment proof predates that head change.
  • Complete next step (P2) - A maintainer must choose the Google Vertex ambient-ADC and manifest-auth-evidence contract; proof renewal cannot be supplied by an automated repair lane.
Agent review details

Security

None.

PR surface

Source +210, Tests +51, Docs +264. Total +525 across 19 files.

View PR surface stats
Area Files Added Removed Net
Source 11 361 151 +210
Tests 3 52 1 +51
Docs 5 265 1 +264
Config 0 0 0 0
Generated 0 0 0 0
Other 0 0 0 0
Total 19 678 153 +525

Review metrics

Metric Value Why it matters
Persisted setup contract 1 environment write shape changed (env to env.vars) The latest head modifies the exact configuration written by onboarding, so earlier live proof does not fully verify the current fresh-install path.
Auth evidence surface 1 new manifest auth-evidence variant env-vars-with-marker changes how provider auth availability is inferred without a local credential file.

Merge-risk options

Maintainer options:

  1. Approve the contract, then refresh exact-head proof (recommended)
    Rebase onto current main, preserve existing gcloud and service-account-file behavior, and provide a redacted GCE/GKE/Cloud Run onboarding-to-response transcript for the env.vars head.
  2. Narrow the onboarding scope
    Keep the current explicit ADC configuration path and split any reusable manifest auth-evidence API into a separately approved provider-contract change.
  3. Pause the feature direction
    Close or defer the PR if maintainers do not want onboarding to treat project configuration as ambient ADC availability.

Technical review

Best possible solution:

Adopt a maintainer-approved, provider-owned Google Vertex ADC onboarding contract, then rebase it onto current main and show a fresh GCE/GKE/Cloud Run onboarding-to-response run plus focused coverage for existing gcloud and service-account-file setups.

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

Yes for the reported old behavior: current main's source still requires file-backed evidence plus project/location before treating Google Vertex ADC as available, while its Vertex transport can use ADC downstream. A live GCE reproduction was supplied for an earlier PR head, but was not re-established against the July 23, 2026 head.

Is this the best way to solve the issue?

Unclear. The proposed flow addresses the missing onboarding path, but the reusable environment-only manifest evidence and changed auth boundary need an explicit provider-contract decision before it can be called the best maintainable solution.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against 3b1212b39716.

Labels

Label changes:

  • add rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
  • add status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
  • remove proof: sufficient: Current real behavior proof status is insufficient, not sufficient.
  • remove rating: 🐚 platinum hermit: Current PR rating is rating: 🦪 silver shellfish, so this older rating label is no longer current.
  • remove status: 👀 ready for maintainer look: Current PR status label is status: 📣 needs proof.

Label justifications:

  • P2: This is a substantial provider/setup improvement with a bounded but compatibility-sensitive blast radius, not an active emergency regression.
  • merge-risk: 🚨 compatibility: The onboarding flow persists Google Vertex project/location settings and changes the configuration shape used by the current schema.
  • merge-risk: 🚨 auth-provider: The PR changes the condition under which Google Vertex is considered authenticated and moves some failures to the downstream ADC transport.
  • rating: 🦪 silver shellfish: Overall readiness is 🦪 silver shellfish; proof is 🦪 silver shellfish and patch quality is 🦐 gold shrimp.
  • status: 📣 needs proof: The PR needs real behavior proof before ClawSweeper can clear the contributor ask. Needs stronger real behavior proof before merge: The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response. After adding proof, update the PR body; ClawSweeper should re-review automatically. If it does not, the PR author or someone with repository write access can comment @clawsweeper re-review.
  • proof: 📸 screenshot: Contributor real behavior proof includes screenshot evidence. The PR contains credible May 28, 2026 GCE screenshots showing onboarding and a Gemini response, but its July 23, 2026 head changes the persisted env.vars write path without current-head live output; provide a redacted terminal transcript, logs, or recording that shows onboarding through a successful response.

Evidence

What I checked:

  • Current main remains incomplete for metadata-server onboarding: Current main still declares Google Vertex setup with api-key and local-file auth evidence; it does not include the proposed non-secret ADC marker or environment-only evidence path. That confirms this PR's central onboarding/auth change is not already implemented. (extensions/google/openclaw.plugin.json:1, 3b1212b39716)
  • Current main has partial overlapping Vertex runtime work: The Google plugin on current main already has Vertex catalog and transport handling, so this PR overlaps the active provider surface but still adds the missing setup/auth contract rather than duplicating an already-complete flow. (extensions/google/provider-registration.ts:1, 3b1212b39716)
  • Current main still requires explicit project/location at the Vertex config-key boundary: The current Vertex configuration resolver accepts a key only when an ADC file signal, project, and location are present; the PR deliberately changes that gate and defaults location. This is a real auth/upgrade contract decision, not obsolete cleanup. (extensions/google/vertex-adc.ts:1, 3b1212b39716)
  • Current-head proof needs renewal: The supplied screenshots show a real GCE result from May 28, 2026, and a June comment says the flow was re-run, but the July 23, 2026 head update changes the persisted config from direct env keys to env.vars. No visible current-head GCE transcript, terminal output, or recording proves that altered write path through successful onboarding and a response. (extensions/google/provider-contract-api.ts:1, a5c2b333db75)
  • Related merged work is only a partial overlap: The July 2026 release notes credit merged Google Vertex catalog/runtime work, consistent with the current plugin source; it does not establish that Google Vertex ADC onboarding is already available on main. (extensions/google/provider-catalog.ts:1, 3b1212b39716)

Likely related people:

  • 849261680: July 2026 release history credits this contributor on merged Google Vertex catalog/runtime work that overlaps the current plugin surface; the remaining question is how that established runtime should expose onboarding and ADC evidence. (role: recent area contributor; confidence: medium; files: extensions/google/openclaw.plugin.json, extensions/google/provider-registration.ts, extensions/google/provider-catalog.ts)

Rank-up moves

Optional improvements that raise the rating; they are not merge blockers.

  • Provide redacted current-head GCE/GKE/Cloud Run onboarding-to-response proof, including the generated env.vars configuration shape.
  • Obtain maintainer confirmation for the environment-only Google Vertex auth-evidence contract.
  • Rebase onto current main after that decision and confirm gcloud CLI and service-account-file ADC remain supported.

Rating scale

Score Internal tier Crab rank Meaning
6/6 S 🦀 challenger crab Exceptional readiness
5/6 A 🦞 diamond lobster Very strong readiness
4/6 B 🐚 platinum hermit Good normal PR; ordinary maintainer review
3/6 C 🦐 gold shrimp Useful, but confidence is limited
2/6 D 🦪 silver shellfish Proof or implementation needs work
1/6 F 🧂 unranked krab Not merge-ready
N/A NA 🌊 off-meta tidepool Rating does not apply

Overall follows the weaker of proof and patch quality.
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.

Workflow

  • 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.

History

Review history (4 earlier review cycles)
  • reviewed 2026-06-22T18:59:00.153Z sha 7c561f1 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-06T21:14:38.336Z sha eb64930 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-07T01:03:04.623Z sha eb64930 :: needs maintainer review before merge. :: none
  • reviewed 2026-07-07T06:52:33.147Z sha eb64930 :: needs maintainer review before merge. :: none

@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 30 commits July 23, 2026 13:02
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.
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
…AuthEvidence

Discriminate the ProviderAuthEvidence union in the auth-presence loop so
hasLocalFileAuthEvidence is only called on the local-file variant (fixes
TS2345) and env-vars-with-marker evidence (ambient ADC) is satisfied by
its required env vars alone.
Gate google-vertex on a non-blank GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT
instead of also accepting a credentials file/env alone. A credentials
file without a configured project no longer authenticates, matching the
upstream 'requires non-blank project and location markers' expectation.
Remove the now-unused hasVertexAdcCredentials helper and its lazy
node-fs/os/path loader chain (credentials are resolved at request time
by the transport).
The onboarding AI access test (verifySetupInferenceConfig) ran the probe
with raw process.env and never applied the candidate config's env section,
so providers that resolve credentials from config env at request time (e.g.
google-vertex reading GOOGLE_CLOUD_PROJECT) failed the test even though they
work through the gateway and 'agent --local', which both call
applyConfigEnvVars. Apply the candidate config env around the probe,
mirroring gateway startup, and snapshot/restore so later onboarding steps
see the original environment.
… gemini-3.5-flash

Point the google-vertex catalog at current Vertex Gemini model IDs
(gemini-3.5-flash, gemini-3.6-flash, gemini-3.5-flash-lite, gemini-3.1-pro)
and default onboarding to gemini-3.5-flash, a Gemini 3 model that supports
thinking_level so the onboarding AI access test succeeds.
…schema

Upstream restructured the top-level config env section into a strict object
that only allows shellEnv and vars keys (src/config/zod-schema.root-shape.ts).
The onboarding auth flow still wrote GOOGLE_CLOUD_PROJECT/GOOGLE_CLOUD_LOCATION
directly under env, so onboarding config validation failed with
'Unrecognized keys' after syncing to latest upstream.

Nest the ADC env vars under env.vars so they satisfy the new schema and are
picked up by collectConfigEnvVarsByTarget. Update the google-vertex docs
config examples and prose to the env.vars shape.
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: supplied External PR includes structured after-fix real behavior proof. rating: 🦪 silver shellfish Thin PR readiness signal; proof, validation, or implementation needs work. size: L status: 📣 needs proof The PR needs real behavior proof before ClawSweeper can clear the contributor ask.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants