OpenClaw model authentication

The docs open this page with a scope note worth repeating: it covers model-provider authentication, API keys, OAuth, Claude CLI reuse and the Anthropic setup token, not the token or password that protects the Gateway connection. OpenClaw supports OAuth and API keys for providers, and the recommendation is plain: for an always-on Gateway host an API key is the most predictable option, while subscription and OAuth flows work when they match your provider account. Here is the recommended setup, the Anthropic paths, where credentials live, how to check them, rotation, and how to pick which credential a session uses.

The recommended setup

• Create a key in the provider console, export it on the Gateway host, the machine running the Gateway, and check with the models status command.
• If the Gateway runs under systemd or launchd, put the key in the state directory’s env file so the daemon can read it, restart, and check again with models status and the doctor; onboarding can store keys for daemon use if you would rather not manage variables.
• Claude CLI reuse is a sanctioned Anthropic path and the preferred one for local or desktop use when a Claude login exists on the host: log Claude Code in, then tell OpenClaw to route Anthropic models through the local Claude CLI backend; OpenClaw never reads, stores, refreshes or forwards the native login tokens, the installed process refreshes its own login, and the service must resolve the executable on its path.
• The setup token is the other Anthropic path: a long-lived token printed by Claude Code on any machine, stored on the host through the auth login command in setup-token mode, which needs an interactive terminal.

For an always-on gateway host, an API key is the most predictable option; subscription/OAuth flows work too when they match your provider account model.

Where credentials live

Manual token entry works for any provider and writes the per-agent SQLite auth store, which is where OpenClaw reads auth profiles from; endpoint details such as base URLs, API kinds, model ids, headers and timeouts belong in the provider config, not in profiles. Older installs with JSON auth files are imported by the doctor with timestamped backups, external routes such as a Bedrock SDK mode are config metadata rather than credentials, and credentials can be secret references for keys and tokens, except that OAuth-mode profiles reject them. Removing saved auth does not revoke the key at the provider, and removing a provider’s auth through the control plane while the Gateway runs aborts active runs on that provider with an auth-revoked stop reason so clients can show why the run stopped.

Checking, rotating, choosing

• Models status and the doctor are the checks; the check flag exits one when a credential is expired or missing and two when it is expiring, for automation, and the probe flag runs live auth probes with scope flags, reporting profiles excluded by the auth order, providers with auth but no probeable model, and model-scoped rate-limit cooldowns that leave sibling models usable.
• Some providers retry a rate-limited request with an alternate configured key, in a fixed priority: a single live override key, a delimited list of keys, the plain key variable, then any prefixed variant, with Google providers also falling back to the generic Google key; rotation triggers only on rate-limit, quota and too-many-requests errors, and provider-specific throttling phrases drive the separate failover classification instead.
• OpenAI API-key and ChatGPT or Codex OAuth profiles both use the canonical OpenAI id, and the doctor rewrites legacy Codex profile ids and auth-order entries. Multiple logins for one provider stay separate through profile ids, a force flag deletes a stuck or wrong-account profile and reruns the flow, a session pins a specific credential with the model command and a profile suffix, and per-agent auth-order commands get, set and clear the automatic selection.

OpenClaw with Claude and OpenClaw on a ChatGPT subscription are the two subscription routes this page keeps distinct from an API key.

When it fails

No credentials found means the key is not on the Gateway host, or the setup-token path was never run, and models status confirms the fix; a token expiring or expired shows in the same status, refreshed through the setup token or replaced by an API key. New-session and reset commands clear automatic fallback and rotation state but preserve valid explicit profile pins, and changing the auth order changes automatic selection only. OpenClaw model failover is the mechanism that switches models or providers on repeated failure, distinct from key rotation, and OpenClaw secrets the reference syntax the key and token references use.

On Diali

On Diali a key you bring goes in the vault and the config we generate references it; without one, the assistant runs on the managed AI credits, and the dashboard shows which is in use. Hosted OpenClaw on Diali is the assistant and OpenClaw models and providers covers the providers behind the keys.

• An API key on the host for an always-on Gateway.
• Auth profiles in SQLite, endpoints in config.
• Rotation on rate limits; failover on everything else.