OpenClaw model onboarding

Registering a brand-new provider model (Gemini 3.7 Flash, released hours earlier) into OpenClaw's config and proving it actually works end-to-end.

Dogfooded 2026-08-13/14 at Gavin's request: "Let's configure a sub-agent with Gemini 3.7 ... via the Gemini API ... just test it with a hello world and report back."

Goals

Wire a model that didn't exist in the catalog yet into the google direct-API provider, then get one verifiable "hello world" response back from it — proof the credential, provider plugin, and model string are all actually connected, not just present in config.

Effectiveness

In progress / adequate. The config side went cleanly once attempted: enabling the google provider plugin (missing from plugins.allow), adding gemini-3.7-flash to the model catalog, and wiring it as a fallback all worked on the first pass. But the test side failed twice, silently, before producing a real result — both failures were self-inflicted, not platform bugs.

What made it effective

• Config changes were small, isolated, and each independently verifiable — provider plugin, catalog entry, fallback chain could be checked one at a time rather than as one opaque bundle.
• Once a real signal was needed, dropping to the CLI directly (openclaw agent --model google/gemini-3.7-flash --message '...' --json) after a gateway restart gave an unambiguous, structured result instead of relying on a subagent's self-reported summary.
• .direnv/.envrc was the right place to look for the actual credential once asked — the fix was one line once the file was checked directly rather than trusted from config.get's masked output.

Friction, pain points, surprises

A false-positive test report. First attempt: "Registered Gemini 3.7 Flash ... and kicked off a test subagent asking it to say hello world. Waiting for that to come back." The subagent was spawned without a model= override, so it silently ran on the default (claude-sonnet-5), echoed "hello world," and looked like a passing test. Nothing about the subagent's own output would have revealed this — the request it received never mentioned Gemini at all. Gavin had to quote the original claim back before the gap surfaced. The mechanical fix was easy (pass the override); the actual lesson is procedural: verify that the parameter defining what's being tested was really passed before reporting a dispatched test as running or done.

A placeholder credential, four silent failures deep. GEMINI_API_KEY was set, but to a literal your_actual_api_key_here-style template value. Four consecutive retries against it failed as bare [assistant turn failed before producing content] — no error text surfaced anywhere in the session, just empty turns. The actual cause (400 API key not valid) only appeared once traced through Google's own API response, not from anything OpenClaw exposed at the call site. Checking .direnv directly (per Gavin's own suggestion) found the real value in seconds; the four failed attempts before that point produced no diagnostic signal on their own.

Verdict: the plumbing is fine, the reporting discipline was the weak link. Every piece of config — provider, catalog, credential source, fallback — worked exactly as designed once actually correct. Both failures were claims of success or attempted diagnosis that outran what had actually been verified. The CLI-with---json re-test after fixing the key is the pattern worth keeping: it's the one step in this whole exercise that couldn't have produced a false positive.