openclaw-openclaw/docs/gateway/authentication.md

summary, read_when, title

summary	read_when	title
Model authentication: OAuth, API keys, Claude CLI reuse, and Anthropic setup-token	Debugging model auth or OAuth expiry Documenting authentication or credential storage	Authentication

This page covers **model provider** authentication (API keys, OAuth, Claude CLI reuse, Anthropic setup-token). For **gateway connection** authentication (token, password, trusted-proxy), see [Configuration](/gateway/configuration) and [Trusted Proxy Auth](/gateway/trusted-proxy-auth).

OpenClaw supports OAuth and API keys for model providers. 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.

• Full OAuth flow and storage layout: /concepts/oauth
• SecretRef-based auth (env/file/exec providers): Secrets Management
• Credential eligibility/reason codes used by models status --probe: Auth Credential Semantics

Recommended setup: API key (any provider)

1. Create an API key in your provider console.
2. Put it on the gateway host (the machine running openclaw gateway):

export <PROVIDER>_API_KEY="..."
openclaw models status

3. If the gateway runs under systemd/launchd, put the key in ~/.openclaw/.env so the daemon can read it:

cat >> ~/.openclaw/.env <<'EOF'
<PROVIDER>_API_KEY=...
EOF

4. Restart the gateway process (or the daemon), then re-check:

openclaw models status
openclaw doctor

openclaw onboard can also store API keys for daemon use if you don't want to manage env vars yourself. See Environment variables for the full env-loading precedence (env.shellEnv, ~/.openclaw/.env, systemd/launchd).

Anthropic: Claude CLI reuse

Anthropic setup-token auth remains a supported path. Claude CLI reuse (claude -p-style usage) is also sanctioned for this integration; when a Claude CLI login is available on the host, that's the preferred path for local/desktop use. For long-lived gateway hosts, an Anthropic API key is still the most predictable choice, with explicit server-side billing control.

Host setup for Claude CLI reuse:

# Run on the gateway host
claude auth login
claude auth status --text
openclaw models auth login --provider anthropic --method cli --set-default

This is two steps: log Claude Code into Anthropic on the host, then tell OpenClaw to route Anthropic model selection through the local claude-cli backend and store the matching OpenClaw auth profile.

If claude isn't on PATH, install Claude Code or set agents.defaults.cliBackends.claude-cli.command to the binary path.

Manual token entry

Works for any provider; writes the per-agent SQLite auth store and updates config:

openclaw models auth paste-token --provider openrouter

OpenClaw reads auth profiles from each agent's openclaw-agent.sqlite. Endpoint details (baseUrl, api, model ids, headers, timeouts) belong under models.providers.<id> in openclaw.json or models.json, not in auth profiles.

If an older install still has auth-profiles.json, auth-state.json, or a flat shape like { "openrouter": { "apiKey": "..." } }, run openclaw doctor --fix to import it into SQLite; doctor keeps timestamped backups beside the original JSON files.

External auth routes such as Bedrock auth: "aws-sdk" aren't credentials. For a named Bedrock route, set auth.profiles.<id>.mode: "aws-sdk" in openclaw.json — don't write type: "aws-sdk" into the auth profile store. openclaw doctor --fix migrates legacy AWS SDK markers from the credential store into config metadata.

SecretRef-backed credentials

• api_key credentials can use keyRef: { source, provider, id }
• token credentials can use tokenRef: { source, provider, id }
• OAuth-mode profiles reject SecretRef credentials: if auth.profiles.<id>.mode is "oauth", a SecretRef-backed keyRef/tokenRef for that profile is rejected.

Checking model auth status

openclaw models status
openclaw doctor

Automation-friendly check, exit 1 when expired/missing, 2 when expiring:

openclaw models status --check

Live auth probes (add --probe-provider, --probe-profile, --probe-timeout, --probe-concurrency, or --probe-max-tokens to narrow scope):

openclaw models status --probe

Notes:

• Probe rows can come from auth profiles, env credentials, or models.json.
• If auth.order.<provider> omits a stored profile, probe reports excluded_by_auth_order for that profile instead of trying it.
• If auth exists but OpenClaw can't resolve a probeable model for that provider, probe reports status: no_model.
• Rate-limit cooldowns can be model-scoped: a profile cooling down for one model can still serve a sibling model on the same provider.

Optional ops scripts (systemd/Termux): Auth monitoring scripts.

API key rotation (gateway)

Some providers retry a request with an alternate configured key when a call hits a provider rate limit.

Key priority order per provider:

1. OPENCLAW_LIVE_<PROVIDER>_KEY (single override, pins one key)
2. <PROVIDER>_API_KEYS (comma/space/semicolon-separated list)
3. <PROVIDER>_API_KEY
4. <PROVIDER>_API_KEY_* (any env var with this prefix)

Google providers (google, google-vertex) additionally fall back to GOOGLE_API_KEY. The combined list is deduplicated before use.

OpenClaw rotates to the next key only when the error message matches: rate_limit, rate limit, 429, quota exceeded/quota_exceeded, resource exhausted/resource_exhausted, or too many requests. Other errors are not retried with alternate keys. If all keys fail, the final error from the last attempt is returned.

Provider-specific phrases like `ThrottlingException`, `concurrency limit reached`, or `workers_ai ... quota limit exceeded` drive **failover/retry classification** (switching models or providers on repeated failure), a separate mechanism from API-key rotation above.

Removing saved auth does not revoke the key at the provider — rotate or revoke it in the provider dashboard when you need provider-side invalidation.

Removing provider auth while the gateway is running

When you remove provider auth through the gateway control plane, OpenClaw deletes the saved auth profiles for that provider and aborts active chat/agent runs whose selected model provider matches the removed one. Aborted runs emit the normal cancellation/lifecycle events with stopReason: "auth-revoked", so connected clients can show the run stopped because credentials were removed.

Controlling which credential is used

OpenAI and legacy openai-codex ids

OpenAI API-key profiles and ChatGPT/Codex OAuth profiles both use the canonical provider id openai. Use openai:* profile ids and auth.order.openai for new config.

If you see openai-codex in older config, auth profile ids, or auth.order.openai-codex, treat it as legacy migration input — don't create new openai-codex profiles. Run:

openclaw doctor --fix
openclaw models auth list --provider openai

Doctor rewrites legacy openai-codex:* profile ids and auth.order.openai-codex entries to the canonical openai route. For OpenAI-specific model/runtime routing, see OpenAI.

During login (CLI)

openclaw models auth login --provider openai --profile-id openai:ritsuko
openclaw models auth login --provider openai --profile-id openai:lain

--profile-id keeps multiple OAuth logins for the same provider separate inside one agent.

--force deletes the saved auth profiles for that provider in the selected agent directory, then reruns the same auth flow. Use it when a saved profile is stuck, expired, or tied to the wrong account. It doesn't revoke credentials at the provider.

openclaw models auth login --provider anthropic --force

Per-session (chat command)

• /model <alias-or-id>@<profileId> pins a specific provider credential for the current session (example profile ids: anthropic:default, anthropic:work).
• /model (or /model list) shows a compact picker; /model status shows the full view (candidates + next auth profile, plus provider endpoint details when configured).

If you change auth order or profile pinning for a chat that's already running, send /new or /reset to start a fresh session — existing sessions keep their current model/profile selection until reset.

Per-agent (CLI override)

Auth order overrides are stored in that agent's SQLite auth state:

openclaw models auth order get --provider anthropic
openclaw models auth order set --provider anthropic anthropic:default
openclaw models auth order clear --provider anthropic

Use --agent <id> to target a specific agent; omit it to use the configured default agent. openclaw models status --probe shows omitted stored profiles as excluded_by_auth_order rather than silently skipping them.

Troubleshooting

"No credentials found"

Configure an Anthropic API key on the gateway host, or set up the Anthropic setup-token path, then re-check:

openclaw models status

Token expiring/expired

Run openclaw models status to see which profile is expiring. If an Anthropic token profile is missing or expired, refresh it via setup-token or migrate to an Anthropic API key.

Related

• Secrets management
• Remote access
• Auth storage