Provider bridges
Provider bridges
Gemini bridge
Gemini has two paths. Which one an advisory call takes is set by
providers.gemini.transport (auto default, api, agy):
| Path | When | How |
|---|---|---|
| API key (default) | advisory call with GEMINI_API_KEY set (auto), or any call with transport: "api" |
POST {GEMINI_API_BASE}/chat/completions on Google's OpenAI-compatible endpoint, Authorization: Bearer <key>, model providers.gemini.apiModel (default gemini-flash-latest). Same HTTP client as OpenRouter (server/openrouter callOpenRouter), with reasoning_effort as a top-level field and errors labelled Gemini. Multi-turn sessions are in memory. File-blind, so fan-outs attach the orientation bundle. |
| agy (opt-in) | workspace-write calls under auto and agy; advisory calls with no GEMINI_API_KEY (auto) or with transport: "agy". Never under transport: "api" |
the Antigravity CLI, described below |
GEMINI_API_KEY wins over GOOGLE_API_KEY, and GOOGLE_API_KEY alone does not switch
auto (it is often a key for another Google API). The key is never passed to agy: the API path
does not spawn it, and the agy child env scrubs every *_KEY variable anyway. In the
standalone bridge, a gemini-reply to a thread that started on the API path continues on
the API path; asking for workspace-write on such a thread is an invalid-params error. Under
transport: "api" one gate in front of agy refuses everything that would run it
(workspace-write, or a reply to a thread the API path does not know) with invalid params.
With the API path selected, the standalone bridge starts even when agy is missing (a
stderr warning; workspace-write calls then fail). The per-call model argument of the
standalone gemini tool is an agy id, so the API path ignores it and uses
providers.gemini.apiModel.
Antigravity terms. The Antigravity terms (external), section 6,
list "Using third party software, tools, or services to access the Service (e.g. using
OpenClaw with Antigravity OAuth)" as a breach that "may be grounds for suspension or
termination of your Antigravity and/or Gemini CLI accounts". Deliberation drives agy as
third-party software, which is why the key path is the default and agy is opt-in.
The agy path wraps the Antigravity CLI (agy) in print mode (agy -p) and adds two
reliability behaviors:
- Soft-timeout drain - on timeout it keeps
agyalive, keeps buffering its streamed stdout, and returns the answer ifagycompletes cleanly within the grace budget. The unified MCP orchestration uses hard absolute deadlines for single calls and shared fan-outs, so it disables this drain; it remains available on standalone bridge calls without a hard deadline or host cap. See Gemini timeout recovery. - Plain-stdout answer with an
Error:sentinel -agy -pprints the answer as plain UTF-8 text on stdout and exits 0; there is no-o jsonmode. The bridge treats stdout as the answer unless it matches/^\s*Error:/(agy reports failures asError: <message>on stdout, still at exit 0), in which case it classifies the failure into an error envelope.
Flag mapping the bridge applies to agy:
| Bridge input | agy flag |
|---|---|
sandbox: read-only (advisory) |
--sandbox (terminal-only; see below) |
sandbox: workspace-write |
--dangerously-skip-permissions |
include-directories: [...] |
repeated --add-dir <dir> |
gemini-reply (multi-turn) |
--conversation <id> |
| always | --print-timeout <duration> and -p <prompt> |
There is no -o json. agy (>= 1.0.9) does take --model, and the bridge always
pins it, so a run never inherits the operator's ~/.gemini/settings.json
(model.name). Model ids fuse family and reasoning effort - gemini-3.6-flash-high;
the bare family (gemini-3.6-flash) is rejected with requires --effort. agy models
prints display names (Gemini 3.6 Flash (High)) which --model also accepts, but the
slug is canonical. Resolution order is per-call model > providers.gemini.model in
config.json > GEMINI_DEFAULT_MODEL > the built-in auto-gemini-3. Point at a
different agy binary with AGY_BIN. agy print mode does not enforce folder trust.
The bridge probes agy --help once per process to learn whether the flag exists (agy
< 1.0.9 rejects unknown flags outright). agy 1.1.x prints its usage to stderr only, so
the probe reads both streams - reading stdout alone never saw --model, warned "does not
support --model" on every boot, and silently dropped the pin
(issue #180 (external)). That also means the
pin had never reached a real agy before: the built-in auto-gemini-3 alias is not in
agy models on 1.1.x, and agy rejects an unknown id with invalid model selection (exit 1,
about 3.5s, because it fetches its catalog first). Two outcomes, by whose pin it was:
- The shipped alias (
auto-gemini-3, seeded into every install's config): the call does not fail.runGeminiretries once without--modelwithin the remaining time budget (agy then uses its~/.gemini/settings.json), warns once per process on stderr, and omits the alias for the rest of the process. The response carriespinDropped: trueand the unified envelope reportsmodel: "agy-settings-default"rather than an id that never ran. Setproviders.gemini.modelto an idagy modelslists to stop the warning. - Any other id (config,
GEMINI_DEFAULT_MODEL, or the call): a typo or a stale pin is the operator's config error, and running some other model behind their back would be worse than failing. The call fails aserrorKind: "model-not-allowed"(not retried) with agy's own message, which lists the catalog, forwarded asmessage.
The pin is located by position (--model <id> sits immediately before the -p <prompt>
tail that buildAgyArgs always emits), never by scanning argv values, so an --add-dir
path or a prompt can never be mistaken for the flag. The --help probe itself is bounded
(15s); a probe that times out is treated like a failed spawn (assume supported).
The built-in stays the portable auto-gemini-3 router alias because the concrete
catalog differs per install - shipping a pinned id would hard-fail every call on a
machine that lacks it. Pin a concrete id in config.json where you can: the alias
routes server-side, and agy's catalog also carries Claude and GPT-OSS entries, so a
routed call can seat a non-Gemini model in the Gemini slot and silently collapse
cross-vendor independence in ask-all / consensus, with nothing in the result
envelope showing it. Run agy models to see what this machine actually offers.
Read-only is enforced by the bridge, not by agy. agy's --sandbox
restricts only terminal commands - the agent's file-edit tool is unrestricted, and
the model can bypass the terminal restriction per tool call. So a read-only
dispatch does NOT rely on --sandbox alone. The bridge layers its own enforcement
on every read-only run:
- macOS OS sandbox - the
agyprocess is wrapped insandbox-execwith a Seatbelt profile that denies all file writes except~/.gemini(OAuth + the conversation cache that backsthreadIdcontinuity) and temp dirs. Workspace writes are blocked at the kernel. Disable withDELIBERATION_DISABLE_OS_SANDBOX=1. - Prompt guard - a hard advisory instruction block is prepended to the prompt.
- Git mutation detection (all platforms) - the bridge snapshots
git rev-parse HEAD+git status --porcelainof the consulted cwd (and any--add-dirroots) before and after the run; on a diff it prepends aWORKSPACE MUTATION DETECTEDwarning and setsworkspaceMutated: trueon the result. No auto-revert - the result is surfaced as tainted for the caller to act on. - Env scrub - the child env drops the kill-switch and push/exfil credentials
(
GITHUB_TOKEN,GH_TOKEN,GIT_ASKPASS,SSH_AUTH_SOCK).
The network is intentionally NOT isolated (agy needs its API + OAuth token
refresh), so a determined delegate could still push pre-existing commits or exfil
over the network - read-only contains local writes. On Linux there is no OS sandbox
in v1; read-only there relies on the prompt guard + mutation detection (bwrap is a
documented future seam). workspace-write (the direct gemini tool only) is an
explicit opt-in that intentionally skips all of the above.
Grok bridge
A bundled zero-dependency Node bridge over the xAI Responses API
(/v1/responses). It is advisory-only (it cannot edit files) but it can read
attached files: pass files: [{ path | file_id | file_url | dir }] and the
bridge delivers them per the mode setting - uploaded to the xAI Files API
(default), inlined as input_text (for line-by-line reading of source files),
or expanded via the bundled glob walker for directories. Resolution is against
the top-level roots: string[] (first-root-wins) or cwd when roots is
omitted. Uploaded files are SHA-256 dedup-cached locally and carry an
expires_after (default 7 days); manage with /grok-files
(list / prune / gc). See Grok files and cleanup.
The bridge default model is grok-4.6. It needs XAI_API_KEY in its environment;
a missing key surfaces errorKind: "missing-auth". Replies are read as a stream,
which is what makes a configured timeout above 300s reachable at all - see
Grok streaming.