openclaw-vertex-setup（OpenClaw vertex 设置）

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