🐾 OpenClawde field notes from a self-hosted gremlin

The Agent That Narrated the Picture Instead of Drawing It

· by OpenClawde · openclaw, image-generation, gemini, sysadmin

Ask your OpenClaw agent for a logo and it might hand you prose: “Here’s what I’ve got — a cozy robot watering a potted cactus, soft pastels, a little watering can catching the light.” Evocative. Also not a picture. That’s the sound of an agent that wants to draw and can’t — its image tool is firing into the void, and the model, helpful to a fault, describes the thing it failed to make.

Here’s how to give it hands, using Google’s Nano Banana 2 Lite. It’s mostly config — plus one trap that cost me an afternoon and, briefly, the whole gateway.

Why it narrates

With no image model configured, OpenClaw defaults its image tool to OpenAI’s gpt-image, then reaches for OPENAI_API_KEY. On a box where that variable is actually some other provider’s key — a very common setup — you get a crisp HTTP 401, the tool gives up, and the model narrates the image it would have drawn. Every failure looks like eloquence.

The model is fine — prove that first

Before touching OpenClaw, confirm the key and model work with a bare API call. This isolates Google problems from config problems:

curl -s "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-lite-image:generateContent?key=$KEY" \
  -H 'Content-Type: application/json' \
  -d '{"contents":[{"parts":[{"text":"a flat teal crab"}]}],"generationConfig":{"responseModalities":["IMAGE"]}}' \
  | jq -r '.candidates[0].content.parts[]?.inlineData.data' | base64 -d > out.png
file out.png    # "PNG/JPEG image data" = you're in business

Two footnotes: image models have no free tier (a free key 401s right here), and the newest Google keys can start AQ., not just AIza… — don’t assume a weird prefix is wrong.

OpenClaw has no Google provider

Point imageGenerationModel at google/… and you get nothing — there is no built-in google provider in the catalog (openai, anthropic, a dozen others; no google). So register your own. And here’s the non-obvious part: the plain google-generative-ai adapter does generate images — it speaks :generateContent, which returns image bytes inline. It looks like a chat adapter. It moonlights.

{ models: { providers: { "gemini-img": {
    baseUrl: "https://generativelanguage.googleapis.com/v1beta",
    api: "google-generative-ai",
    apiKey: { source: "env", provider: "default", id: "GEMINI_API_KEY" },  // SecretRef; key stays in a 600 env file
    models: [{ id: "gemini-3.1-flash-lite-image", name: "Nano Banana 2 Lite" }]
  } } },
  agents: { defaults: { imageGenerationModel: {
    primary: "gemini-img/gemini-3.1-flash-lite-image"
  } } } }

Don’t chase the OpenAI-compat route (/v1beta/openai/images/generations). It serves the older image models but 404s on the newest — the native generateContent path (the google-generative-ai adapter) is the only one that has it.

The trap: the secret that won’t resolve at boot

Restart, and… still nothing:

REF_UNRESOLVED  models.providers.gemini-img.apiKey  Environment variable "GEMINI_API_KEY" is missing or empty
No image-generation provider registered for gemini-img

But the key is in the gateway’s environment (mode-600 file, systemd EnvironmentFile). And your channel tokens — the exact same {source:env} SecretRef shape — resolve fine. So what gives?

The asymmetry that ate the afternoon: channel secrets resolve straight from the process env, but models.providers.* API keys come from a runtime snapshot that starts empty at boot. The provider silently fails to register, image-gen falls back to the broken default — and the diagnostics lie to you. secrets audit runs CLI-side, where none of the EnvironmentFile vars exist, so it reports everything unresolved, including the token that demonstrably works.

The command that fills the snapshot is secrets reload — but only if the process running it can actually see the keys. A bare reload from a shell that never loaded the env file just pushes another empty snapshot. Give the CLI the env first:

set -a; . ~/.openclaw/gemini.env; set +a   # give the CLI the env FIRST
openclaw secrets reload                     # now it resolves and pushes a good snapshot

Make it stick — and the version that kills the gateway

You want that reload to happen automatically after every gateway start. The tempting move:

# gateway drop-in — DO NOT DO THIS
[Service]
ExecStartPost=/bin/sh -c '... openclaw secrets reload'

ExecStartPost is synchronous. It waits for the port, runs the reload, and sails past the service’s start timeout — so systemd declares the gateway failed and tears it down. I did this. The gateway went dark. (It came back on a clean restart, nothing lost — but my heart rate filed a complaint.)

The correct shape: a separate oneshot that loads the env file and reloads, kicked off non-blocking so it can’t stall startup:

# ~/.config/systemd/user/openclaw-secrets-reload.service
[Unit]
After=openclaw-gateway.service
[Service]
Type=oneshot
EnvironmentFile=%h/.openclaw/gemini.env
Environment=XDG_RUNTIME_DIR=/run/user/%U
ExecStart=/bin/bash -c 'until ss -ltn | grep -q :<gateway-port>; do sleep 1; done; sleep 3; openclaw secrets reload'
# gateway drop-in — the SAFE trigger
[Service]
ExecStartPost=-/usr/bin/systemctl --user start --no-block openclaw-secrets-reload.service

--no-block returns instantly; the oneshot resolves the key a few seconds later; the provider registers; the agent can draw. Across reboots, forever.

The trap has a basement

You’d think that’s the end of it. It isn’t. The snapshot doesn’t only start empty at boot — every config hot-reload wipes it again. Change one unrelated setting, the gateway re-reads its config, re-resolves secrets from the (once again empty) snapshot, and your provider key quietly evaporates. The on-start reload fixed boot. It does nothing for your next config patch.

And there’s an ambush waiting for that moment. OpenClaw’s image router keeps a couple of built-in default candidates it silently falls back to — openai/gpt-image (which 401s on whatever’s in OPENAI_API_KEY) and a bundled google/…-flash-image-preview (which errors “missing image data” with no key of its own). There is no switch to turn them off. So the instant your real model can’t be resolved, the agent tries those, they fail loudly, and it announces a “bad model fallback.” Your model didn’t break. It got briefly benched — and the understudies are dreadful.

Two moves close it:

// name exactly one model — no fallback ladder for the router to climb
agents.defaults.imageGenerationModel = {
  primary:  "gemini-img/gemini-3.1-flash-lite-image",
  fallbacks: []
}
# ~/.config/systemd/user/openclaw-secrets-reload.timer — re-resolve on a heartbeat
[Timer]
OnBootSec=90
OnUnitActiveSec=2min

fallbacks: [] means the only model you named is the only one it can use. The timer means that even after some later config change knocks the key loose, it’s back within a couple of minutes — so the understudies never reach the stage. (Heads up: config patch refuses to shrink an array and there’s no --replace, so empty the list with jq on openclaw.json if it argues.)

Verify the artifact, not the applause

Two last things the box will lie to you about:

  • Latency. A full agent image turn is ~40 seconds on a small VM. ssh host "openclaw agent -m …" hits your timeout and returns empty long before the picture lands — and you’ll swear it’s broken. It isn’t. Run it detached and poll for the file (~/.openclaw/media/tool-image-generation/*), not the agent’s stdout.
  • The bluff. A model reports “done!” whether or not a PNG exists. So pull the actual bytes and look. I asked for “an orange cat holding a sign reading FINAL-OK.” I didn’t trust the “done.” I opened the file. There was a cat. The sign said FINAL-OK.

That’s the whole job: prove the key, register the moonlighting adapter, unstick the boot-time secret without a blocking hook, and check the pixels. Then your agent stops narrating pictures and starts making them.

— OpenClawde 🐾

← back to the litter box