OpenClaw model authentication

There are two different things called authentication in an OpenClaw deployment. One is how a client proves itself to the gateway. The other, covered here, is how the gateway proves itself to a model provider. For a machine that is always on, the docs are direct about the trade: an API key is the most predictable option, while subscription flows work when they match your provider account model.

Getting a credential onto the host

• Create a key in the provider console, export it on the gateway host and check the model status; when the gateway runs as a service, put the key in the state directory environment file so the daemon can read it, restart, then check status and run the doctor.
• Reusing a local assistant login is two steps rather than one: log that command-line tool into the provider on the host, then tell OpenClaw to route the provider's models through its local backend; the gateway service must be able to resolve that executable on its search path, and a nonstandard path needs a wrapper registered through a plugin.
• A long-lived setup token is the other supported path: generate it on any machine with the assistant installed, then store it on the gateway host with the auth login command, which requires an interactive terminal; manual token entry works for any provider and writes the same per-agent store.
• Profiles live in each agent's database file, and endpoint details such as the base address, the wire format, model ids, headers and timeouts belong in configuration rather than in an auth profile; older installations with flat credential files are imported by the doctor fix, which keeps timestamped backups beside the originals.

OpenClaw never reads, stores, refreshes, or forwards the native login tokens.

Checking, probing and rotating

The status command shows what is configured, and an automation-friendly variant exits with one code when a credential is expired or missing and another when one is expiring, which makes it usable in a cron check. A live probe actually calls the provider, and its rows can come from auth profiles, environment credentials or the registry file. Two probe results are worth recognising: a profile omitted from the configured auth order is reported as excluded rather than quietly skipped, and a provider with valid auth but no resolvable model is reported as having no model rather than as broken auth. Rate-limit cooldowns are model-scoped, so a profile cooling down for one model can still serve a sibling on the same provider. For key rotation, the priority order runs from a single pinned override, to a delimited list variable, to the single key variable, to any variable sharing the key prefix, with the combined list deduplicated before use.

Choosing which credential runs

• Rotation is deliberately narrow: OpenClaw moves to the next key only when the error text matches a rate limit, a quota exhaustion, a resource exhaustion or a too-many-requests phrase, other errors are not retried with alternate keys, and if every key fails the last error is returned.
• At login, a profile id keeps multiple accounts for one provider separate inside a single agent, and a force flag deletes that provider's saved profiles in the selected agent directory before rerunning the flow, which is the fix for a stuck or wrongly bound profile; it does not revoke anything at the provider.
• Per session, a model command with a profile suffix pins one credential for that conversation, while per agent the auth order commands get, set and clear the ordering stored in that agent's state; removing provider auth through the control plane also aborts active runs on that provider with an explicit revoked stop reason so clients can explain why a run stopped.

OpenClaw OAuth explained covers the subscription side of the same store and OpenClaw secrets management how credentials can be referenced rather than pasted.

The part people forget

Removing saved auth inside OpenClaw is not revocation at the provider. The stored profile disappears, active runs on that provider stop, and nothing else changes on the provider side, so a leaked key still needs rotating or revoking in the provider dashboard. The second easy trap is the identifier: API-key profiles and subscription profiles for the same vendor share one canonical provider id, and an older split identifier found in configuration is legacy migration input that the doctor rewrites rather than a second provider to keep alive. OpenClaw models explained explains how a selected model resolves to one of these credentials and The OpenClaw doctor is the command that repairs the store.

On Diali

On Diali the model credentials are managed by the platform and the runtime configuration is generated from the dashboard and replaced at each release, so there is no key to paste on a server. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around each runtime.

• Provider auth, not gateway auth: two different doors.
• Rotation fires on rate-limit text only, never on other errors.
• Deleting a profile locally never revokes the key upstream.