openclaw-antigravity-auth

OpenClaw provider plugin that exposes Google Antigravity (Cloud Code Assist) models to OpenClaw over OAuth. It gives you access to models like:

• antigravity/gemini-3.1-pro-high / antigravity/gemini-3.1-pro-low / antigravity/gemini-3-flash
• antigravity/claude-sonnet-4-6
• antigravity/claude-opus-4-6-thinking
• antigravity/gpt-oss-120b-medium

...billed against your Google account's Antigravity (and optional Gemini CLI) quotas.

This is a port of NoeFabris/opencode-antigravity-auth (MIT) to OpenClaw's native provider plugin SDK.

⚠️ Terms of Service / account-risk warning — read first

Using this plugin (and any Antigravity-proxying tool) likely violates Google's Terms of Service for Antigravity / Cloud Code Assist. Upstream users have reported:

• Account suspension (temporary or permanent)
• Shadow-bans / quota throttling with no notification
• Loss of access to other Google services tied to the same account

By installing and using this plugin, you acknowledge that:

1. This is an unofficial integration, not endorsed or supported by Google.
2. Your Google account may be restricted, suspended, or banned at any time.
3. You assume all risk. The authors of this plugin are not liable for any consequences.

If you are unsure whether this is acceptable in your environment, do not install it — use one of Google's officially supported APIs (Gemini API, Vertex AI) instead.

Install

1. Install the plugin

openclaw plugins install openclaw-antigravity-auth
openclaw gateway restart

Or from a local checkout while developing:

openclaw plugins install ./openclaw-antigravity-auth

2. Authenticate

openclaw auth login antigravity

The plugin will either:

• Start a local HTTP server on http://localhost:51121/oauth-callback, open your browser to Google, and receive the redirect automatically (local-desktop mode); or
• Print the authorization URL and ask you to paste the full redirect URL back in (remote / WSL2 mode).

On success, credentials are persisted to ~/.openclaw/antigravity/credentials.json with 0600 permissions (POSIX). See Security notes.

3. Select a model

openclaw models set --model antigravity/claude-opus-4-6-thinking
# or per-agent in openclaw.config.yaml — see example below

Example OpenClaw config

# openclaw.config.yaml
plugins:
  entries:
    # The entry key is the plugin id from openclaw.plugin.json (`antigravity`),
    # not the npm package name.
    antigravity:
      enabled: true
      config: {}            # all defaults — see "Plugin config" below

agents:
  defaults:
    models:
      - antigravity/gemini-3.1-pro-high
      - antigravity/claude-opus-4-6-thinking
    model: antigravity/claude-opus-4-6-thinking

The plugin registers provider id antigravity (with an google-antigravity alias) and advertises the following model prefixes to OpenClaw's auto-loader:

antigravity-gemini-*
antigravity-claude-*
antigravity-gpt-*

so shorthand refs like antigravity-gemini-3.1-pro-high route through this plugin without any models.providers.* boilerplate in your config.

Plugin config

The antigravity: entry under plugins.entries accepts the following optional fields under config:. All of them are honoured at runtime — leaving them blank or omitting them keeps the defaults.

plugins:
  entries:
    antigravity:
      enabled: true
      config:
        # Pin the Cloud Code Assist project id used in the apiKey blob sent
        # upstream. Overrides whatever was returned by `loadCodeAssist` for
        # this account. Useful when your account belongs to multiple GCP
        # projects and you want to bill one specifically.
        projectId: "my-billing-project"

        # Override the Cloud Code Assist endpoint. Useful for corporate
        # proxies that man-in-the-middle Google APIs, internal staging
        # environments, or local mock servers. Defaults to the production
        # endpoint `https://cloudcode-pa.googleapis.com`.
        endpoint: "https://my-corp-proxy.example"

        # Legacy single-account credential file. Auto-migrated into
        # `accounts.json` (multi-account store) on first use. Both the
        # login flow and runtime path read/write at 0600 permissions.
        # Defaults to `~/.openclaw/antigravity/credentials.json` (or
        # `$OPENCLAW_HOME/antigravity/credentials.json` if set).
        tokenPath: "/secure-vault/antigravity-creds.json"

        # Override the multi-account credential store path. Defaults to
        # `~/.openclaw/antigravity/accounts.json`.
        accountsPath: "/secure-vault/antigravity-accounts.json"

        # Multi-account rotation strategy. See "Multi-account rotation"
        # below for details.
        #   failover    (default) — keep using one account until it hits
        #                quota, then move to the next eligible one.
        #   round-robin — advance to the next account on every request.
        #   sticky      — pin to a specific account via `activeAccount`.
        rotationStrategy: "failover"

        # Cooldown (ms) before retrying an account that hit quota.
        # Defaults to 3,600,000 (1 hour).
        cooldownMs: 3600000

        # Pin a specific account id (typically the email address) under
        # the sticky strategy. Ignored by failover / round-robin.
        activeAccount: "[email protected]"

Blank strings ("", " ") are treated the same as the field being absent — the default is used. Each override is independent; you can set just one.

Multi-account rotation

You can register more than one Google account with this plugin and have it rotate between them automatically when one hits Cloud Code Assist quota. This is useful for power users who hit Antigravity quotas frequently and want zero-downtime failover.

How to add accounts

Each invocation of openclaw auth login antigravity adds (or refreshes) one account, keyed by the email address Google reports in the OAuth response. Logging in to a second account simply runs the OAuth flow again with a different Google session.

# Account #1
openclaw auth login antigravity
# → in your browser, sign in as [email protected]

# Account #2 (use a different Chrome profile, or sign out of Google first)
openclaw auth login antigravity
# → sign in as [email protected]

After both flows finish, your ~/.openclaw/antigravity/accounts.json will contain two entries:

{
  "schemaVersion": 1,
  "accounts": [
    { "id": "[email protected]", "label": "primary", ... },
    { "id": "[email protected]",   "label": "primary", ... }
  ],
  "activeAccountId": "[email protected]"
}

The legacy credentials.json from earlier plugin versions is auto-migrated on first load — your existing single-account install keeps working without any manual steps.

Rotation strategies

• failover (default) — Keep using one account until the upstream returns a quota / rate-limit error (HTTP 429, RESOURCE_EXHAUSTED, etc.). The plugin then marks that account exhausted (defaulting to a 1 hour cooldown) and silently retries the same request with the next eligible account. Stops being eligible until the cooldown elapses.
• round-robin — Advance to the next account on every request. Useful when you want to spread load evenly to avoid hitting any single account's quota cap.
• sticky — Always use the account pinned by activeAccount. Falls through to the next eligible account only if the pinned one is exhausted. Use this when you have a primary "production" account and a "backup" you only want triggered after the cooldown logic has kicked in.

The retry only happens when the upstream fails before any user-visible output has been streamed. Once thinking or text starts flowing, the plugin propagates the error rather than restart the response — this avoids confusing duplicated output in chat sessions.

When NOT to use multi-account rotation

• If you only have one account, leave the config untouched. The plugin behaves exactly like a single-account install (zero-overhead).
• This is not a load-balancer. It does not aggregate quotas; it just hides the cooldown by automatically failing over.
• Each account is bound to a single Google identity. Google's Terms of Service may treat aggressive multi-account use as policy circumvention. See the warning at the top of this README.

Runtime transport

OpenClaw's built-in api schema does not include google-gemini-cli or google-antigravity, so this plugin wires the Cloud Code Assist transport itself instead of relying on a built-in adapter. At streaming time the plugin:

1. Loads the on-disk credential, refreshing the access token if it is expired or close to expiring.
2. Hands OpenClaw a {token, projectId} JSON blob via prepareRuntimeAuth so pi-ai's transport sees a fresh access token on every request.
3. Substitutes the catalog's nominal api/provider for google-gemini-cli / google-antigravity via createStreamFn, then delegates to pi-ai's built-in streamSimpleGoogleGeminiCli which already understands the Cloud Code Assist envelope (endpoint fallbacks, Antigravity headers, SSE parsing, retry semantics, function calling).

The library-level helpers in src/transforms.ts and src/streaming.ts are kept around for downstream tooling that wants to drive the protocol directly without going through pi-ai (for example a custom proxy), but the plugin itself uses the pi-ai transport.

Security notes

This plugin handles a Google OAuth refresh token, which is effectively a long-lived credential to your Google account. Treat it like a password.

• The refresh token is stored in ~/.openclaw/antigravity/credentials.json.
• The parent directory is created with mode 0700.
• The credential file is written with mode 0600 (POSIX only — Windows falls back to ACL defaults, documented as a known gap).
• Writes use a write → fsync → rename dance to avoid torn files.
• Nothing in this plugin logs access tokens, refresh tokens, authorization codes, or Authorization: headers. Every error-to-log path goes through redactForLog(), which masks:
  • Bearer <token> headers
  • Quoted JSON authorization fields
  • Any bare token-shaped string of 40+ alphanumeric characters
• On invalid_grant, the plugin instructs the user to re-run openclaw auth login antigravity and (intentionally) does not auto-clear the credential file — you decide when to revoke.

If you want to revoke the plugin's access:

1. Delete ~/.openclaw/antigravity/credentials.json.
2. Revoke the session in myaccount.google.com → Security → Third-party access.

Migrating from opencode-antigravity-auth

This package is a port, not a drop-in replacement. Key differences:

| Aspect | opencode-antigravity-auth | openclaw-antigravity-auth (this plugin) | |------------------------|------------------------------------------------------------|---------------------------------------------------------------| | Host | Opencode | OpenClaw | | Plugin SDK | @opencode-ai/plugin | openclaw/plugin-sdk/* | | Provider id | google (with antigravity-* model namespacing) | antigravity (with google-antigravity alias) | | Model refs | google/antigravity-gemini-3-pro | antigravity/gemini-3.1-pro-high | | Credential location | ~/.local/share/opencode/auth.json | ~/.openclaw/antigravity/credentials.json | | Multi-account rotation | Yes (see upstream README) | Not yet ported — single account today | | Thinking presets | --variant=low/high/max | Via model catalog variants (same semantics; see src/models.ts) | | Gemini CLI quota | Opt-in via cli_first | Model catalog exposes gemini-2.5-* entries separately |

What has been ported:

• OAuth client constants, PKCE flow, loadCodeAssist project discovery, token refresh with invalid_grant handling.
• Full model catalog metadata (context windows, thinking variants).
• SSE streaming parser (split from the Opencode monolith into a reusable module).
• Request-envelope transforms for Gemini + Claude request bodies.
• Error classification (auth / rate-limit / quota / upstream / reauth).
• Secure 0600 on-disk credential storage with atomic writes.

Explicitly out of scope for this port (tracked for later):

• Multi-account auto-rotation on 429 / 5xx.
• The thinking-model tool-call recovery hooks (src/plugin/thinking-recovery.ts in the upstream).
• The auto-update-checker background task.
• The check-quota.mjs / test-regression.ts E2E harnesses.

These live in the OpenClaw host's replay / failover / usage subsystems and should be re-expressed via buildProviderReplayFamilyHooks(...) and friends rather than reimplemented inside this plugin.

Development

npm install
npm run typecheck
npm test
npm run build

The package ships as ESM ("type": "module") targeting Node ≥ 22 (same as OpenClaw).

Changelog

See CHANGELOG.md for the full release history.

License

MIT, including the MIT-licensed ports from opencode-antigravity-auth. See LICENSE.