How to rotate an OpenClaw provider credential without losing your fallback

A provider credential can expire, reach a quota, or need replacement after an access review. The dangerous part is changing it while OpenClaw is still relying on the old route. If the new credential is invalid, the model is unavailable to that account, or the Gateway has not reloaded the change, the fallback may disappear at the same time as the primary.

OpenClaw documents three related mechanisms: API-key rotation, ordered auth profiles, and model fallback. They do different jobs. The safest rotation keeps the old working credential available, adds the replacement under a separate profile or trusted secret source, verifies it, and changes preference only after that check.

This is a documentation-derived procedure, not a claim that these commands were run in a live OpenClaw installation. Check the documentation for the version installed on your Gateway before applying a change. Never put a real credential in a command example, source file, ticket, screenshot, or article.

Decide which fallback you mean

OpenClaw's model failover documentation separates auth-profile rotation from model fallback. That distinction determines what happens when a credential fails.

For a planned credential replacement, named profiles are the clearest route because the old credential remains visible as a deliberate rollback candidate. Environment lists can complement that plan, but they should not be mistaken for a general-purpose backup policy. The OpenClaw authentication guide documents the separate rules for each path.

Prepare the change

Work on the machine that runs the OpenClaw Gateway. You need the provider ID, the agent ID if more than one agent is configured, the current primary model, the configured model fallbacks, and the current credential source. The source may be an auth profile, a Gateway environment variable, a SecretRef, or provider configuration.

Create the replacement credential in the provider's own console first. Give it the smallest scope that can serve the intended model and project. Confirm that the account can use the same model, endpoint, organization, or region as the old credential. A key can be syntactically valid and still lack access to the model OpenClaw is configured to call.

Prepare a harmless test request. It should read or summarize disposable material and should not send a message, modify a file, make a purchase, or trigger another external action. Keep a private change note with profile IDs, timestamps, model names, and results. Do not record secret values.

If the Gateway is remote, perform system or agent auth changes on the Gateway host. The OpenClaw models CLI reference warns that pointing a laptop at a remote Gateway does not make local auth commands write to the server's credential store.

1. Record the known-good route

Start with read-only inspection. Use the exact agent when the installation has multiple agents:

openclaw models status --agent <agentId> --json
openclaw models auth list --agent <agentId> --provider <provider> --json
openclaw models fallbacks list --json

models status shows the resolved default, fallbacks, and authentication overview. models auth list lists saved profiles without printing API keys or OAuth secret material. The fallback command shows the model chain separately from the credential order.

These commands answer different questions. Status does not inspect a chat session's model override; use /model status inside that session when you need to see its selected model and profile. If the status output shows an environment credential but the auth list contains no matching profile, do not invent a profile ID. Keep that route in the environment lane or migrate it deliberately to a named profile.

Write down the old profile ID or the exact trusted secret source. The old route is only “known-good” if it has recently completed the intended kind of request. Its presence in a list proves that OpenClaw can see a reference, not that the provider will accept the credential.

2. Add the replacement beside the old credential

Preferred lane: a named auth profile

For an API-key provider, use the interactive command documented for manual API-key entry:

openclaw models auth paste-api-key --provider <provider> --profile-id <provider>:rotation-2026-09

The --profile-id option lets you update a named profile or add a backup without changing the active provider connection. Let OpenClaw prompt for the value. If you automate the step, pass the secret through standard input rather than an argument so it does not appear in shell history or a process list.

For an OAuth provider that supports named profiles, use its auth flow instead:

openclaw models auth login --provider <provider> --profile-id <provider>:rotation-2026-09

Do not add --force to a staged rotation. The CLI reference says that --force removes saved profiles for the provider before rerunning the auth flow. That is useful for a stuck or wrong-account profile, but it defeats the purpose of preserving a fallback.

Check the result without exposing the secret:

openclaw models auth list --provider <provider> --json

OpenClaw stores provider credentials in its auth store, while configuration entries such as auth.profiles and auth.order describe metadata and routing. The repository's auth credential semantics document the eligibility checks and reason codes used when a profile is missing, expired, excluded, or unresolved.

Alternative lane: provider environment keys

If the existing deployment uses environment credentials, use the provider's documented alternate-key support. OpenClaw's authentication guide lists this priority order:

• OPENCLAW_LIVE_<PROVIDER>_KEY, a single override that pins one key;
• <PROVIDER>_API_KEYS, a list of keys;
• <PROVIDER>_API_KEY, a single key; and
• <PROVIDER>_API_KEY_*, matching numbered or named variables.

For example, the official OpenClaw provider page lists OPENAI_API_KEYS as an optional OpenAI rotation mechanism. A deployment might place placeholders like these in its trusted Gateway secret source:

OPENAI_API_KEYS=NEW_KEY_VALUE,OLD_KEY_VALUE

Use the provider's own documented variable names rather than assuming every provider supports the same list. Also check for an existing OPENCLAW_LIVE_OPENAI_KEY or equivalent override. If it is set, it has higher priority and can make the list appear to be ignored.

Environment-key rotation is narrower than profile rotation. OpenClaw advances to the next key when the error matches documented rate-limit or quota signals such as 429, quota exceeded, resource exhausted, or too many requests. Other errors are not retried with alternate keys. If your main concern is a revoked or mistyped replacement credential, use named profiles and an explicit auth order so the old profile remains an intentional candidate.

Put provider credentials in the Gateway process environment, its trusted global dotenv file, a container secret, or a supported SecretRef. The OpenClaw environment reference says provider credentials in workspace .env files are ignored or blocked because those files are a lower-trust source.

3. Make the new profile preferred, not exclusive

Once both named profiles are present, inspect and set the per-provider order:

openclaw models auth order get --provider <provider>
openclaw models auth order set --provider <provider> <provider>:rotation-2026-09 <provider>:known-good

Replace the placeholders with the exact IDs returned by models auth list. The first profile is the preferred candidate and the old profile remains available after it. The CLI documentation says that the stored order override takes precedence over the configuration order for that provider.

This command changes credential selection. It does not change the model primary. Do not run openclaw models set as part of a credential rotation, and do not pass --set-default to an auth login unless changing the default model is intentional. OpenClaw's quick rules state that adding or reauthenticating a provider preserves the existing primary model unless you explicitly request a new default.

Keep the model fallback chain unchanged while the credential change is being tested. If it is missing, inspect it with openclaw models fallbacks list and add a model only as a separate, reviewed configuration change. A model fallback and an old credential are different recovery layers.

4. Apply the change and check the route

Saved auth changes request a refresh from the running Gateway. If the CLI cannot confirm that the running application adopted the change, follow its restart guidance:

openclaw gateway restart
openclaw models status --agent <agentId> --json --check

For an environment change, restart the Gateway process or service that owns the environment. Restarting only the shell from which you edited a file does not update an already-running daemon.

A live probe is stronger than a syntax check, but it is still an operation against the real provider:

openclaw models status --agent <agentId> --probe --probe-provider <provider> --probe-profile <provider>:rotation-2026-09 --probe-max-tokens 8

Use --probe-profile for the named replacement. For an environment-only route, narrow the probe by provider instead. The CLI documentation warns that probes can consume tokens and require exclusive ownership of the selected state directory. Run this in a maintenance window and stop a running Gateway first when the local probe requires it. A status check with exit code zero is useful evidence, but the documentation does not treat it as proof that every model request will succeed.

The Control UI offers another documented path. In Settings → Models, you can add or replace a provider key, then use Test connection. The Control UI and API keys documentation says that the key stays in the auth store and that the test is a real provider request that may consume a small number of tokens. Saving a key and refreshing the provider catalog are separate outcomes, so check both.

5. Test the default route and the fallback behavior

After the replacement passes its targeted check, send one harmless request through the normal model route. Confirm the selected profile with /model status or the equivalent status view. Keep the prompt read-only and use disposable content.

Session state matters here. OpenClaw pins an automatically selected auth profile per session, and a user-selected profile can remain the first preference even while the runtime temporarily tries another eligible profile. An existing session therefore may not show the same selection behavior as a new session. Treat the session's displayed profile as evidence about that session, not as proof of every agent's routing.

A fallback drill is a proposed test, not a requirement to break a production key. In a disposable agent or maintenance environment, make the preferred profile unavailable, send a read-only request, and confirm that the old profile answers. Then restore the preferred profile and check the next turn. Do not use a write, payment, message, or file mutation for this exercise. OpenClaw's failover rules require evidence that replaying an unfinished attempt is safe; a second request can duplicate an external action.

Remember that the fallback winner is turn-local. It does not permanently replace the configured primary. An explicit user model selection can also be strict, so a pinned session may report failure instead of moving to an unrelated configured model.

6. Roll back without revoking the old route

If the new profile fails after activation, move the known-good profile to the front:

openclaw models auth order set --provider <provider> <provider>:known-good <provider>:rotation-2026-09
openclaw gateway restart
openclaw models status --agent <agentId> --json --check

If the old route is environment-based, remove the replacement from the provider's key list, clear any single-key override that pins the wrong value, and restart the Gateway. Keep the old secret available until the rollback check succeeds.

Common failure signals have different meanings:

• excluded_by_auth_order means the profile exists but the explicit order omits it.
• missing_credential, expired, or unresolved_ref means OpenClaw cannot use the configured credential source.
• no_model means credentials exist but OpenClaw could not resolve a probeable model candidate.
• A saved key with a failed catalog refresh is still a saved key. Refresh failure does not prove that the credential itself is invalid.

These reason codes are documented in the auth credential semantics and CLI references. Read the reason before changing another setting.

Finish the rotation carefully

Keep the old profile or key active for an observation period that matches the workload. This is an operating recommendation, not a duration prescribed by OpenClaw. A route used once a day needs more time to observe than one exercised continuously.

When the new route has passed the required checks, remove the old local profile only when no active run depends on it:

openclaw models auth logout <provider>:known-good --yes

The CLI removes the profile from the selected auth store and clears its configuration references, while model defaults and connection settings remain. Removing saved auth does not revoke the credential at the provider. Revoke or expire the old key in the provider dashboard as a separate final step. Removing provider auth through the running Gateway can also abort active runs whose selected model uses that provider.

If the old credential may have leaked, do not wait for the observation period. Revoke it through the provider's incident or credential-management flow, then use whatever fallback remains available. OpenClaw's secrets documentation also describes SecretRefs as an optional way to keep supported credentials out of plaintext configuration. They reduce local exposure only after the supported credentials and old plaintext copies have been migrated and audited.

Limits to keep in the runbook

• An alternate environment API key is not a universal authentication fallback; its automatic rotation is tied to recognized rate-limit and quota errors.
• A successful status check or one live probe does not establish that every model, skill, scheduled task, cost profile, or external workflow will behave the same way.
• Auth profiles, environment credentials, and model fallbacks may belong to different agents or Gateway processes.
• Local logout changes OpenClaw's store. Provider-side revocation is a separate action.

The practical rule is simple: add the replacement, verify it without disturbing the old route, put the new profile first while leaving the old one eligible, and revoke the old credential only after rollback is still possible without it. That gives the credential change a recovery path instead of making it a one-shot switch.

Sources

• OpenClaw Authentication — provider auth methods, status and probe commands, API-key priority, alternate-key limits, and provider-side revocation. Accessed 2026-09-13.
• OpenClaw Models CLI — auth profile commands, named profiles, order management, status checks, probe behavior, remote-agent scope, and logout. Accessed 2026-09-13.
• OpenClaw Model failover — auth-profile rotation, session stickiness, cooldowns, model fallback, and strict explicit selections. Accessed 2026-09-13.
• OpenClaw Quick rules — adding or reauthenticating a provider without changing the existing primary model unless requested. Accessed 2026-09-13.
• OpenClaw Control UI and API keys — saved-key behavior, hidden key material, catalog refresh, and live connection tests. Accessed 2026-09-13.
• OpenClaw Environment variables — trusted credential sources, precedence, and workspace dotenv restrictions. Accessed 2026-09-13.
• OpenClaw auth credential semantics — profile eligibility, stable probe reason codes, and credential resolution behavior. Accessed 2026-09-13.
• OpenClaw Secrets management — SecretRefs and the residual risk of plaintext credentials in agent-readable files. Accessed 2026-09-13.
• OpenClaw official provider plugins — provider-specific authentication variables, including OpenAI's optional API-key rotation variables. Accessed 2026-09-13.