OpenClaw OAuth route failures: diagnose provider drift before you reset everything

Problem statement: OpenClaw was working yesterday. After an update, a provider that should authenticate through OAuth starts behaving like it has no API key. Or a custom provider route that used to point at one base URL now resolves through the wrong path. The tempting fix is to delete credentials and start over. That is often the wrong move.

Provider failures are confusing because the visible error usually names the last thing that broke, not the first thing that drifted. "No API key" can mean a genuinely missing key. It can also mean an OAuth profile was not selected, a refreshed token was not written back, a fallback route skipped the intended provider, a model ID no longer maps to the expected provider, or a custom base URL was copied into a place where it does not belong. This guide shows how to isolate the failure without destroying working configuration.

The core distinction: auth failure versus route failure

A real auth failure means the selected credential cannot authenticate with the selected provider. A route failure means OpenClaw did not use the credential, provider, base URL, or model route you thought it was using. The symptoms overlap, but the fixes are different. If you rotate credentials for a route failure, you waste time and may break a working provider profile. If you patch routing for a real revoked credential, the runtime will still fail.

The safest approach is to reduce the system to one provider, one auth profile, one model, and one request path. Once that path works, reintroduce fallback models, custom providers, secondary agents, and scheduled jobs one at a time. This feels slower than deleting everything, but it preserves the evidence you need to find the real drift.

Common causes

1. OAuth profile exists, but the selected route expects an API key

Some providers support more than one auth style. If the model route resolves to a key-based provider entry while your valid credential is stored as an OAuth profile, the final error can sound like the key is missing. The credential is not necessarily gone. The selected route may simply be wrong.

2. Token refresh writes to a different state path than the runtime reads

OAuth systems refresh tokens. If refresh output is written to one profile bundle while the running instance reads another, the user experiences an auth failure even though a valid refreshed token exists somewhere. This is why our local smoke harness documentation stores refreshed auth state back into the credential bundle after successful runs.

3. Custom base URLs are copied across agents or providers

Custom provider support is powerful, but it also makes drift easy. A base URL that is correct for one OpenAI-compatible endpoint may be wrong for a different provider or agent. If provider config is copied while creating agents, a bad base URL can spread faster than the operator notices.

4. Fallback routes hide the first failing provider

Fallback models are helpful, but they add another layer to debugging. If the primary route fails and the fallback route uses a different auth type, logs may show a later failure that distracts from the first route decision. Always identify which provider OpenClaw selected for the failing turn.

5. Non-main agents read different provider state

A main agent can work while a specialist agent fails. Multi-agent setups may have agent-specific session paths, workspace paths, or auth outputs. Test the exact agent that failed instead of assuming the global provider configuration is healthy.

Diagnostics: isolate the failing provider route

Step 1: Record the exact error and the selected model

Copy the final error, the model name, the provider name if visible, and the agent or session that produced the failure. Do not start by editing files. Your first job is preserving the failure shape so you can tell whether a change fixed it.

Step 2: Test a known-good provider path

Send a tiny prompt through a provider and model that you know worked recently. If that succeeds, the gateway and general model path are alive. If it fails with the same auth message, the problem is broader than one provider route.

Step 3: Test the failing provider without fallbacks

Disable or bypass fallback for the diagnostic test if your setup allows it. You want the failing provider to fail directly so logs point to the first broken edge, not to a later fallback attempt.

Step 4: Inspect auth type, base URL, and model ID together

These three values form one route. A valid model with the wrong base URL fails. A valid OAuth profile selected through a key-only route fails. A valid base URL paired with the wrong model ID fails. Inspect them as a set instead of changing one random value at a time.

Step 5: Test the same provider from the same agent

If the failing turn came from a non-main agent, reproduce it there. A successful main-agent test is useful, but it does not prove the specialist agent has the right provider files or auth profile.

Step-by-step recovery

Step 1: Back up the provider configuration

Before editing, copy or export the current provider and model configuration. If the fix makes things worse, you need a clean rollback. This is especially important when multiple agents share copied provider state.

Step 2: Patch the smallest wrong value

If the route expects an API key but should use OAuth, change the selected auth profile or model route. If the base URL is malformed, patch only that provider entry. If a fallback route is wrong, patch the fallback without touching the primary route. Avoid broad resets until you have no other choice.

Step 3: Start a new session or reload the runtime deliberately

Provider changes may not affect an already-running session the way you expect. Use a clean new session for verification, or restart the gateway if your setup requires it. The key is deliberate verification, not hopeful clicking.

Step 4: Verify with a cheap prompt before a real task

Send a short prompt that does not call tools and does not touch external systems. You are proving provider routing first. Once that passes, test one normal tool-using workflow. Only then should you return the provider to cron jobs or production channels.

Step 5: Recheck cron jobs and non-main agents

Provider route failures often show up first in scheduled work or specialist agents because those paths run without a human watching every step. After a fix, manually run one important cron job and one important non-main agent task before declaring the system healthy.

Edge cases

• OAuth succeeds in a browser but OpenClaw still fails: check where the token was stored and which runtime path reads it.
• Only custom providers fail: inspect base URL shape, trailing paths, model IDs, and compatibility expectations.
• Only new agents fail: look for copied provider config from an older agent.
• Only cron fails: the scheduled session may select a different model or profile than interactive chat.
• Only fallback fails: the primary provider may be healthy while the fallback route is misconfigured.

Typical mistakes

• Rotating a valid credential when the selected route is wrong.
• Deleting all provider profiles and losing the comparison evidence.
• Testing only the main agent when the failure came from a specialist agent.
• Ignoring custom base URLs copied during agent creation.
• Returning cron jobs to service before running one manual verification pass.

How to verify the fix

A real fix passes four checks. First, a cheap prompt succeeds on the intended provider and model. Second, logs show the expected auth type and route. Third, the failing agent or session now works, not only the main agent. Fourth, one tool-using task completes without fallback confusion. If any of those checks fail, keep the provider in diagnostic mode.

Fix once. Stop recurring provider auth drift.

If this keeps coming back, you can move your existing setup to managed OpenClaw cloud hosting instead of rebuilding the same stack. Import your current instance, keep your context, and move onto a runtime with lower ops overhead.

• Import flow in ~1 minute
• Keep your current instance context
• Run with managed security and reliability defaults

If you would rather compare options first, review OpenClaw cloud hosting or see the best OpenClaw hosting options before deciding.

Import your current OpenClaw instance in 1 click Compare managed and self-hosted provider ops

FAQ

Is this always an OpenClaw bug?

No. It can be an OpenClaw regression, a provider-side auth change, a stale token, a copied custom base URL, or a route selection issue introduced by local configuration. The diagnostic path above is meant to separate those causes before you choose a fix.

Should I keep API-key and OAuth profiles for the same provider?

Only if you can name which route uses which profile. Mixed auth styles are fine when documented. They become dangerous when operators assume the runtime will infer intent from the provider name alone.

Why does this matter more for teams?

Teams usually add multiple agents, scheduled jobs, and shared channels. That means one provider drift can break hidden workflows while the main chat still looks healthy. Provider state needs ownership, not occasional emergency edits.