openclaw-vertex-setup

name

openclaw-vertex-setup

description

Configure OpenClaw to use Google Vertex AI Gemini models so normal OpenClaw startup, Gateway service startup, and TUI usage all work without manual shell setup, and keep the Gateway service aligned with the globally installed npm OpenClaw binary. Covers gcloud ADC login, project and location setup, OpenClaw model defaults, shared env wiring, auth profile fixes, npm upgrade hygiene, and end-to-end verification.

OpenClaw Vertex Setup

Use this skill when the task is to configure or repair OpenClaw so it uses Vertex AI models such as google-vertex/gemini-3.1-pro-preview, and the result must work from normal openclaw commands instead of only from a manually prepared shell. Also use it when the user's openclaw tui or Gateway service is broken after upgrading the globally installed npm package.

Target outcome:

• openclaw models status recognizes Vertex
• openclaw gateway start or openclaw gateway restart works
• openclaw tui can chat through Vertex without manually exporting env vars first
• Gateway LaunchAgent points at the same global npm openclaw binary that which openclaw resolves to

Keep the workflow minimal and verify each layer separately:

1. Vertex itself
2. OpenClaw model discovery
3. OpenClaw local agent execution
4. Gateway and TUI execution

What to inspect first

• User config: ~/.openclaw/openclaw.json
• Shared OpenClaw env: ~/.openclaw/.env
• Agent auth store: ~/.openclaw/agents/main/agent/auth-profiles.json
• Active CLI path: which -a openclaw
• Gateway service wiring: openclaw gateway status --deep
• launchd service file: ~/Library/LaunchAgents/ai.openclaw.gateway.plist
• Shell env: ~/.zshrc
• ADC file: ~/.config/gcloud/application_default_credentials.json

Confirm the default OpenClaw model points at Vertex:

{
  "agents": {
    "defaults": {
      "model": {
        "primary": "google-vertex/gemini-3.1-pro-preview"
      }
    }
  }
}

Important model note:

• In current OpenClaw builds, google-vertex/gemini-3.1-pro-preview is the config id commonly exposed by the CLI.
• In Google Vertex AI docs, the corresponding preview family is documented as gemini-3-pro-preview.
• Treat 3.1 pro here as a preview track, not the latest stable track.

Required environment

Ensure these are available to the process that launches the Gateway:

export GOOGLE_CLOUD_PROJECT="<project-id>"
export GOOGLE_CLOUD_LOCATION="global"
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"

ADC must exist at the standard path, or GOOGLE_APPLICATION_CREDENTIALS must point to it:

gcloud auth application-default login
gcloud config set project <project-id>
gcloud auth application-default set-quota-project <project-id>

If gcloud cannot be installed via dl.google.com, the Google Cloud CLI tarball can be downloaded from storage.googleapis.com/cloud-sdk-release/.

Make normal startup work

Do not rely only on the interactive shell. Put the Vertex env into OpenClaw's shared env file so launchd/systemd and plain openclaw commands see the same values:

~/.openclaw/.env

Example:

GOOGLE_CLOUD_PROJECT=<project-id>
GOOGLE_CLOUD_LOCATION=global
GOOGLE_APPLICATION_CREDENTIALS=/Users/<user>/.config/gcloud/application_default_credentials.json

This is the most reliable fix for:

• openclaw gateway start
• openclaw gateway restart
• openclaw tui
• launchd/systemd service startup

Keep Gateway aligned with the global npm install

Avoid mixing a source-linked openclaw command with a Gateway service that was installed from a different build. The service should normally follow the globally installed npm package.

Preferred steady state:

• which openclaw resolves to the global npm path, for example ~/.npm-global/bin/openclaw
• openclaw gateway status --deep shows the service command under the matching global npm module path

After any npm install -g openclaw@latest, always refresh the service installation:

openclaw gateway install --force
openclaw gateway restart
openclaw gateway status --deep

If the user switches back to a local source checkout with npm link, reinstall the Gateway service from that same source-managed CLI before testing. Do not leave an old LaunchAgent around from a different installation source.

OpenClaw config changes

Recommended minimum ~/.openclaw/openclaw.json changes:

• Set default model to google-vertex/gemini-3.1-pro-preview
• Enable shell env import:

{
  "env": {
    "shellEnv": {
      "enabled": true,
      "timeoutMs": 15000
    }
  }
}

Source-level hardening

If you are repairing OpenClaw itself rather than only configuring a machine, make these code-level fixes in the OpenClaw repo:

• add GOOGLE_CLOUD_PROJECT, GCLOUD_PROJECT, GOOGLE_CLOUD_LOCATION, and GOOGLE_APPLICATION_CREDENTIALS to the shell env fallback key list
• make Vertex auth detection use a stable ADC file check instead of a cold-start-sensitive provider helper
• pass Vertex env vars through daemon service environment generation

These changes prevent the common failure where openclaw agent --local works but Gateway or TUI fails because the service process started without Vertex project/location env.

Auth profile fix

OpenClaw can report No API key found for provider "google-vertex" even when ADC is already valid. If openclaw models status shows google-vertex under Missing auth, add a profile entry in:

~/.openclaw/agents/main/agent/auth-profiles.json

Example:

{
  "profiles": {
    "google-vertex:default": {
      "type": "api_key",
      "provider": "google-vertex",
      "key": "<authenticated>"
    }
  },
  "lastGood": {
    "google-vertex": "google-vertex:default"
  }
}

This is a practical compatibility fix. Prefer the source-level hardening above when you control the OpenClaw codebase.

Verification sequence

Run these in order.

1. Verify ADC token

gcloud auth application-default print-access-token | head -c 20; echo

2. Verify direct Vertex REST call

Use the global endpoint and a tiny prompt. For direct Vertex API verification, prefer Google's documented model id:

python3 - <<'PY'
import json, subprocess, urllib.request
project='<project-id>'
model='gemini-3-pro-preview'
url=f'https://aiplatform.googleapis.com/v1/projects/{project}/locations/global/publishers/google/models/{model}:generateContent'
token=subprocess.check_output(['zsh','-lc','gcloud auth application-default print-access-token'], text=True).strip()
payload={
  'contents':[{'role':'user','parts':[{'text':'Reply with exactly: VERTEX_OK'}]}],
  'generationConfig':{'temperature':0}
}
req=urllib.request.Request(url, data=json.dumps(payload).encode(), method='POST')
req.add_header('Authorization', f'Bearer {token}')
req.add_header('Content-Type', 'application/json')
with urllib.request.urlopen(req, timeout=60) as r:
    print(r.status)
    print(r.read().decode())
PY

3. Verify OpenClaw sees the model

openclaw models list
openclaw models status

Expected signals:

• google-vertex/gemini-3.1-pro-preview appears in model list
• auth overview shows source=gcloud adc

4. Verify local OpenClaw agent

source ~/.zshrc >/dev/null 2>&1
export GOOGLE_APPLICATION_CREDENTIALS="$HOME/.config/gcloud/application_default_credentials.json"
openclaw agent --local --agent main --message "Reply with exactly: OPENCLAW_VERTEX_OK" --json

If google-vertex/gemini-3.1-pro-preview returns an incomplete turn or Agent couldn't generate a response, keep the service and env fixes, then temporarily fall back to google-vertex/gemini-2.5-pro. As of 2026-04-19, 2.5-pro is the latest stable model in Vertex docs, while Gemini 3 Pro is still preview.

5. Verify Gateway/TUI path

Install the Gateway service if it is not loaded:

openclaw gateway install --force
openclaw gateway start
openclaw gateway status --deep

If you are only doing a foreground smoke test, start the gateway directly:

openclaw gateway run --verbose

In another terminal:

openclaw tui

Also verify the Gateway path directly:

openclaw agent --agent main --message "Reply with exactly: OPENCLAW_VERTEX_OK" --json

Common failures

openclaw: command not found

Install the local repo as a global command:

cd ~/openclaw
npm link

TUI shows (no output)

Check the session .jsonl log. If the assistant message contains:

Vertex AI requires a project ID. Set GOOGLE_CLOUD_PROJECT/GCLOUD_PROJECT or pass project in options.

then the Gateway process was started without the required Vertex env. Restart the Gateway from a shell that has:

• GOOGLE_CLOUD_PROJECT
• GOOGLE_CLOUD_LOCATION
• optionally GOOGLE_APPLICATION_CREDENTIALS

Then move those values into ~/.openclaw/.env so the next normal service start inherits them.

No API key found for provider "google-vertex"

This usually means OpenClaw's auth profile store is missing a google-vertex profile entry, even though ADC is already valid. Patch auth-profiles.json as described above, then re-run:

openclaw models status

gateway restart says service not loaded

Install the service first:

openclaw gateway install --force
openclaw gateway start

Then confirm with:

openclaw gateway status --deep

TUI shows invalid connect params

This usually means the CLI and Gateway service were installed from different OpenClaw versions. Reinstall the service from the currently active CLI:

which openclaw
openclaw gateway install --force
openclaw gateway restart
openclaw gateway status --deep

Confirm the Command: shown by status --deep points at the same installation family as the active openclaw command.

Success criteria

The setup is complete when all of these are true:

• direct Vertex REST call returns 200
• openclaw models status shows google-vertex
• openclaw agent --local returns OPENCLAW_VERTEX_OK
• openclaw agent via Gateway returns OPENCLAW_VERTEX_OK
• openclaw gateway status --deep shows RPC probe: ok
• openclaw tui can answer a prompt through google-vertex/gemini-3.1-pro-preview, or the skill explicitly documents a temporary fallback to google-vertex/gemini-2.5-pro when the preview model produces incomplete turns