fallback key set | Friends of the Crustacean 🦞🤝 | Page 1

wanton pilot Apr 21, 2026, 11:23 PM

#

how to set fallback key and how it work

hardy dragonBOT Apr 21, 2026, 11:23 PM

#

vivid owlBOT Apr 21, 2026, 11:23 PM

#

To help others find answers, you can mark your question as solved via Right click solution message -> Apps -> ✅ Mark Solution

hardy dragonBOT Apr 21, 2026, 11:23 PM

#

fringe sundialBOT Apr 21, 2026, 11:25 PM

#

There isn’t a fallbackKey config field.

If you mean API key fallback/rotation, set multiple provider keys on the gateway host, usually in ~/.openclaw/.env:

# OpenAI
OPENAI_API_KEYS=sk-key-1,sk-key-2

# Anthropic
ANTHROPIC_API_KEYS=sk-ant-1,sk-ant-2

# Gemini
GEMINI_API_KEYS=key-1,key-2

Then restart the gateway:

#

openclaw gateway restart
openclaw models status

How it works:

OpenClaw tries keys in this order:
1. OPENCLAW_LIVE_<PROVIDER>_KEY
2. <PROVIDER>_API_KEYS
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_1, _2, etc.
It only switches to the next key on rate limit / quota / concurrency style errors.
It does not rotate on normal bad-request errors.
If all keys fail, you get the last error back.

Example, if key 1 gets 429, it retries with key 2 automatically.

#

If you meant model fallback instead, that’s separate:

openclaw models fallbacks add openai/gpt-5.4-mini
openclaw models fallbacks list

Docs:

If you want, I can give you the exact example for OpenAI, Anthropic, or Gemini.

wanton pilot Apr 21, 2026, 11:34 PM

#

i dont have .env , it only have auth

fringe sundialBOT Apr 21, 2026, 11:35 PM

#

Yep, that’s normal. The .env file is optional, it usually does not exist until you create it.

The auth stuff is different. That stores login/token profiles.
For simple fallback API keys, you can create this file yourself:

~/.openclaw/.env

Example:

mkdir -p ~/.openclaw
cat > ~/.openclaw/.env <<'EOF'
OPENAI_API_KEYS=sk-key-1,sk-key-2
# or

#

ANTHROPIC_API_KEYS=sk-ant-1,sk-ant-2
EOF

Then restart:

openclaw gateway restart
openclaw models status

You can also put it in config instead of .env:

#

  env: {
    OPENAI_API_KEYS: "sk-key-1,sk-key-2",
  },
}

Important:

auth / auth-profiles.json = stored logins / tokens
~/.openclaw/.env = extra env vars like OPENAI_API_KEYS
OpenClaw only switches to the next key on rate limit/quota type errors

Docs:

#

If you want, I can show the exact setup for your provider, just say OpenAI / Anthropic / Gemini.

wanton pilot Apr 21, 2026, 11:43 PM

#

how to set it in auth then

fringe sundialBOT Apr 21, 2026, 11:44 PM

#

Yep, but in auth it’s done as multiple auth profiles, not a single fallbackKey field.

1) `openclaw.json` (metadata + order)

{
  auth: {
    profiles: {
      "openai:key1": { provider: "openai", mode: "api_key" },
      "openai:key2": { provider: "openai", mode: "api_key" },
    },
    order: {
      openai: ["openai:key1", "openai:key2"],
    },
  },
}

#

2) `auth-profiles.json` (actual secrets)

Path is usually:

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Example:

{
  "version": 1,
  "profiles": {
    "openai:key1": {
      "type": "api_key",

#

      "provider": "openai",
      "key": "sk-key-1"
    },
    "openai:key2": {
      "type": "api_key",
      "provider": "openai",
      "key": "sk-key-2"
    }
  }
}

How it works

OpenClaw uses the profile order from auth.order
it tries openai:key1 first

#

if that profile gets a failover-worthy error, like rate limit/quota/auth cooldown, it can rotate to openai:key2
profile choice is also sticky per session, so it does not randomly swap every message

Useful check

openclaw models auth order set --provider openai openai:key1 openai:key2
openclaw models status --probe

So, short version:

auth.profiles = declare profiles
auth-profiles.json = store the real keys
auth.order = decide fallback order

Docs:

#

If you want, I can write the exact OpenAI or Anthropic version for you.

wanton pilot Apr 21, 2026, 11:48 PM

#

what u mean profile choice is also sticky per session, so it does not randomly swap every message , are they both work the same, lets say i have two model from same provider and 2 api key for them, they will auto switch when fallback and go 4 times in a row?

fringe sundialBOT Apr 21, 2026, 11:48 PM

#

Yeah, roughly yes, but only for failover-worthy errors.

What “sticky per session” means:

if this session already picked key1, the next normal message in the same chat session keeps using key1 first
it does not alternate key1, then key2, then key1 on every message
it switches only when needed, like rate limit, auth failure, cooldown, etc.

So with:

Model A and Model B as fallback
Key 1 and Key 2 for the same provider

the common retry chain is:

Model A + Key 1
Model A + Key 2

#

Model B + Key 1
Model B + Key 2

So yes, it can be up to 4 tries in a row.

But important:

this is for rate limit / overload / auth failover type errors
for some normal errors, it may stop early
if you manually pin a profile, OpenClaw keeps that profile locked and will go to the next model instead of swapping keys

Also, .env key rotation and auth profiles are similar goal, not identical:

.env = simpler multi-key retry
auth profiles = ordered profiles, session stickiness, cooldowns, per-session pinning

Docs:

#

If you want, I can draw the exact flow for your setup like:

openrouter/model1 + keyA,keyB -> fallback model2 + keyA,keyB

wanton pilot Apr 22, 2026, 12:07 AM

#

still not understand diff in .env and auth use for fallback api key

fringe sundialBOT Apr 22, 2026, 12:08 AM

#

Easiest way to think about it:

`.env`

Just a bag of raw keys.

Example:

OPENAI_API_KEYS=key1,key2

OpenClaw sees: “I have 2 OpenAI keys, try next one if needed.”

Use .env when:

you just want simple backup keys
you do not care which key is named what

#

you do not need per-session profile control

`auth`

A named profile system.

Example idea:

openai:main
openai:backup

Each profile has its own key.

OpenClaw sees: “I have 2 named OpenAI profiles, with order/cooldowns/session stickiness.”

Use auth when:

#

you want named keys/profiles
you want to control order with auth.order
you want per-session pinning like /model ...@openai:main
you may mix API keys + OAuth in one provider

Practical difference

`.env`

simpler
global to the gateway
best for “just use next API key if first one is rate-limited”

`auth`

more advanced
per-agent profile store

#

best for “I want named credentials and smarter routing behavior”

My recommendation

If your goal is only:

“I have 2 API keys, use the second if the first hits limit”

then use .env. It’s the simpler path.

If your goal is:

“I want main and backup as separate identities/profiles, and maybe choose them per session”

then use auth.

#

Docs:

If you want, I can give you a same-provider 2-key example in both styles, side by side.

wanton pilot Apr 22, 2026, 12:14 AM

#

yes

fringe sundialBOT Apr 22, 2026, 12:14 AM

#

Cool, here’s the same setup both ways, side by side.

Goal

You have 2 OpenAI keys:

key1
key2

and you want OpenClaw to use key2 if key1 gets rate-limited.

Option A, `.env` way, simple

Create:

#

~/.openclaw/.env

Put:

OPENAI_API_KEYS=sk-key1,sk-key2

Then restart:

openclaw gateway restart
openclaw models status --probe

#

What happens

OpenClaw tries sk-key1
if rate-limited, it retries with sk-key2

Good for

simple backup key setup
fastest/easiest setup

Limitation

keys are just a list
no profile names
no per-session control

Option B, `auth` way, advanced

#

`openclaw.json`

{
  auth: {
    profiles: {
      "openai:main": { provider: "openai", mode: "api_key" },
      "openai:backup": { provider: "openai", mode: "api_key" },
    },
    order: {
      openai: ["openai:main", "openai:backup"],
    },
  },
}

`auth-profiles.json`

Usually:

#

~/.openclaw/agents/<agentId>/agent/auth-profiles.json

Put:

{
  "version": 1,
  "profiles": {
    "openai:main": {
      "type": "api_key",
      "provider": "openai",
      "key": "sk-key1"
    },
    "openai:backup": {

#

      "type": "api_key",
      "provider": "openai",
      "key": "sk-key2"
    }
  }
}

Then:

openclaw gateway restart
openclaw models status --probe

What happens

#

OpenClaw tries profile openai:main
if that fails in a failover-worthy way, it can move to openai:backup

Good for

named credentials
explicit order
per-session pinning like /model ...@openai:main

Short version

Use .env if you just want:

key1, then key2 if needed

Use auth if you want:

#

main profile, backup profile, with more control

My honest recommendation

For your case, I’d use .env unless you specifically need named profiles. It’s much simpler.

Docs:

If you want, I can do the same side-by-side example for Anthropic too.

wanton pilot Apr 22, 2026, 12:28 AM

#

google/gemini-3. │ google:2 (api_key) │ timeout · 21.5s │
│ 1-flash-lite- │ │ ↳ LLM request timed out. │
│ preview │ │ │
│ google/gemini-3. │ google:default (api_ │ timeout · 24.3s │
│ 1-flash-lite- │ key) │ ↳ LLM request timed out. │
│ preview │ │ │
│ llamacpp/gemma- │ models.json (api_key) │ timeout · 10.1s │
│ 4-26B-A4B-it-UD- │ │ ↳ LLM request timed out.

fringe sundialBOT Apr 22, 2026, 12:29 AM

#

Yep, this output means the fallback chain is working.

What happened:

google/gemini-3.1-flash-lite-preview with profile google:2 timed out
OpenClaw rotated to google:default on the same provider/model
That timed out too
Then it fell back to llamacpp/gemma-4-26B-A4B-it-UD-IQ4_XS from models.json
That timed out too

So the problem is not “fallback key didn’t work”.

The problem is:

all candidates timed out

Important difference:

#

fallback keys help when one key is rate-limited / blocked / cooled down
they do not magically fix a provider/backend that is just not responding in time

So in your case:

both Gemini auth profiles were tried
then model fallback was tried
all of them still timed out

That usually means one of these:

Gemini requests are timing out upstream
your local llama.cpp fallback is too slow / not responding
timeout settings are too low for that model/backend

So yes, the chain is basically:

#

google:2 -> google:default -> llamacpp

and it did switch.

If you want to debug the actual timeout now, please paste:

openclaw --version
openclaw models status --probe

Docs:

wanton pilot Apr 22, 2026, 12:37 AM

#

how to know and check why its timeout? google

fringe sundialBOT Apr 22, 2026, 12:38 AM

#

First, grab your version:

openclaw --version

Then the fastest way to check why Google is timing out is:

1) Probe auth/model state

openclaw models status --probe

This tells you whether Google auth is basically usable.

2) Watch logs live

#

In one terminal:

openclaw logs --follow

Then send one tiny test message to the bot, like:

hi

Now watch the logs for the Google attempt.

3) Get the full report

openclaw status --all

#

How to read the result

If you see:

429
quota
resource exhausted

That is rate limit / quota, not a timeout.

If you see:

401
403
invalid api key
permission denied

#

That is bad key / auth / project access.

If you see only:

LLM request timed out

That usually means:

Google accepted the request path, but never answered in time
network / upstream / provider slowness
or your configured/local timeout is too short

Important clue from your earlier output

Because both Google profiles timed out:

#

google:2
google:default

this looks less like a bad key and more like a provider/request timeout issue

If one key was broken, you’d usually see 401/403, not just timeout on both.

If you paste these 3 outputs, I can read them:

openclaw --version
openclaw models status --probe
openclaw status --all

#

Docs:

wanton pilot Apr 22, 2026, 8:23 AM

#

why openclaw models status --probe all timeout , but it seems I can still use those
google/gemini-3. │ google:2 (api_key) │ timeout · 21.5s │
│ 1-flash-lite- │ │ ↳ LLM request timed out. │
│ preview │ │ │
│ google/gemini-3. │ google:default (api_ │ timeout · 53.5s │
│ 1-flash-lite- │ key) │ ↳ LLM request timed out. │
│ preview │ │ │
│ llamacpp/gemma- │ models.json (api_key) │ timeout · 9.7s │
│ 4-26B-A4B-it-UD- │ │ ↳ LLM request timed out. │
│ Q5_K_S │ │ │
│ nvidia/z-ai/ │ models.json (api_key) │ ok · 3s │
│ glm4.7

fringe sundialBOT Apr 22, 2026, 8:24 AM

#

Because models status --probe is a live health probe, not a full “real chat works exactly the same” test.

So a probe timeout means:

“this provider/model did not answer the probe fast enough”

It does not always mean:

“you can never use this model”

Why that can happen:

probe uses its own timeout budget
real chats can have slightly different runtime behavior
fallback/retries/session behavior in a normal run is not identical to the probe path
some providers/models are just slower or bursty on health probes

#

Your output shows that clearly:

Google probe timed out
local llama.cpp probe timed out
nvidia/z-ai/glm4.7 replied in 3s

So the probe system itself is working, it’s just that some candidates are too slow for the probe.

Best next check

Try Google only, with a bigger probe timeout:

openclaw models status --probe --probe-provider google --probe-timeout 120000

If you want to isolate one key/profile:

#

openclaw models status --probe --probe-provider google --probe-profile google:default --probe-timeout 120000
openclaw models status --probe --probe-provider google --probe-profile google:2 --probe-timeout 120000

If that starts showing ok, then the issue is mostly probe timeout too short / provider too slow, not broken auth.

Also watch logs while probing:

openclaw logs --follow

If you still want, paste:

#fallback key set

1) openclaw.json (metadata + order)

2) auth-profiles.json (actual secrets)

How it works

Useful check

.env

auth

Practical difference

.env

auth

My recommendation

Goal

Option A, .env way, simple

What happens

Good for

Limitation

Option B, auth way, advanced

openclaw.json

auth-profiles.json

What happens

Good for

Short version

My honest recommendation

1) Probe auth/model state

2) Watch logs live

3) Get the full report

How to read the result

If you see:

If you see:

If you see only:

Important clue from your earlier output

If you paste these 3 outputs, I can read them:

Best next check

1) `openclaw.json` (metadata + order)

2) `auth-profiles.json` (actual secrets)

`.env`

`auth`

`.env`

`auth`

Option A, `.env` way, simple

Option B, `auth` way, advanced

`openclaw.json`

`auth-profiles.json`