How to Set Up OpenClaw OAuth and API Key Authentication

GitGuardian's 2025 State of Secrets Sprawl report counted 1.2 million AI-service API secrets exposed in public GitHub repositories, an 81% year-over-year increase. Leaked cloud credentials get scanned and exploited fast. For teams running AI agents through gateways like OpenClaw, every API key, OAuth token, and CLI credential becomes a target the moment it touches a config file or environment variable.

Most authentication guides cover a single path: paste an API key into an environment variable and move on. That works for a solo developer running one model. It falls apart when you manage multiple providers, rotate keys on quota errors, or scope credentials to individual agents in a multi-agent deployment. OpenClaw addresses this with three distinct authentication mechanisms for Anthropic and other model providers.

The three paths are:

• API keys stored as environment variables, with a defined priority order and automatic rotation on rate-limit errors
• OAuth 2.0 Authorization Code Flow with PKCE, where the provider password never touches OpenClaw
• Claude CLI credential reuse, which lets OpenClaw inherit an existing Anthropic login without creating a separate key

Each method supports per-agent scoping and works with OpenClaw's built-in diagnostics. The right choice depends on your deployment: API keys for headless servers, OAuth for interactive setups where you want token auto-refresh, and CLI reuse for developers already authenticated through Claude Code. The OpenClaw authentication reference documents the full configuration surface for each path.

API keys are the most straightforward authentication path and the recommended choice for long-running, unattended gateways. OpenClaw reads keys from environment variables, deduplicates them, and rotates through alternatives when it hits rate-limit responses. Store your provider key using whatever secret management approach fits your environment, and restrict read access to the process that runs the gateway.

The Priority Order

When multiple keys exist for the same provider, OpenClaw resolves them through a four-tier priority ladder. A dedicated live-override key takes top priority, followed by a rotation list variable, then the standard single-key variable, then numbered key variants. Keys are deduplicated before use, so listing the same value in more than one variable does not create extra rotation slots. The OpenClaw authentication docs list the exact variable names and provider-specific fallbacks for each tier.

Rotation Behavior OpenClaw rotates to the next key only on rate-limit errors: HTTP 429 responses, quota exhaustion, throttling, and concurrency-limit rejections. Authentication failures (401, 403) do not trigger rotation, because a bad key will be bad on retry too. Rate-limit cooldowns apply per-model rather than provider-wide, so hitting a limit on one model does not block sibling models from the same provider. If you see repeated auth errors, the fix is a new key from your provider's console, not more keys in the rotation pool.

OAuth is the higher-security option for providers that support it. OpenClaw implements the standard OAuth 2.0 Authorization Code Flow with Proof Key for Code Exchange (PKCE), which means no client secret is stored locally and the provider password never passes through OpenClaw.

The flow works like this: OpenClaw generates a random state parameter for CSRF protection and a PKCE code_verifier, redirects your browser to the provider's authorization endpoint, receives an authorization code on callback, and exchanges that code for an access token and refresh token pair. The tokens land in your auth profile alongside any API keys you have configured.

The OpenClaw OAuth reference covers the full setup flow and storage layout. For providers where you already have a token from another tool, openclaw models auth paste-token lets you import it directly without re-running the browser flow.

Token Lifecycle

Access tokens typically expire after one hour. OpenClaw triggers an automatic refresh before expiration, so you rarely notice the rotation. Refresh tokens last roughly 30 days, depending on the provider. When a refresh token expires, you need to re-authenticate with that provider.

Set up expiration alerts in your provider's developer console. A lapsed refresh token at 3 AM stops your agents cold. Unlike API key rotation where OpenClaw can fall through to the next key, OAuth has no built-in fallback unless you also have an API key configured as a secondary path. For production gateways, keeping an API key alongside OAuth as a safety net is worth the minor complexity.

Persist agent work across credential rotations

Free 50GB workspace with audit logging and granular permissions. Your OpenClaw agents read and write files through the Fastio MCP server while credentials rotate underneath, no credit card required.

Start 14-Day Trial

Developers who already use Claude Code have a third option: tell OpenClaw to piggyback on the existing Claude CLI authentication. This avoids creating a separate API key or running through an OAuth flow. The credential stays wherever Claude Code stores it, and OpenClaw reads it at runtime.

The setup takes two commands:

claude auth login
openclaw models auth login --provider anthropic --method cli --set-default

The first command authenticates Claude Code if you have not already done so. The second tells OpenClaw to use the claude-cli backend for Anthropic requests and sets it as the default profile.

This path is best for individual developers working on a single machine. It keeps credential management centralized in Claude Code rather than split across two tools. The tradeoff is that it ties your OpenClaw authentication to your Claude Code session. If you log out of Claude Code or switch accounts, OpenClaw loses access.

For team or server deployments, API keys are more predictable. CLI reuse depends on an interactive login session, which makes it awkward for CI pipelines, cron jobs, or remote servers where nobody is around to re-authenticate. Use it for local development, and switch to environment-variable API keys when you deploy to production.

When you run multiple agents, you often want different agents to use different credentials. An agent handling customer-facing requests might use a production API key with higher rate limits, while a background research agent uses a secondary key with a lower billing cap. OpenClaw supports this through credential pinning at two levels: session and agent.

Session-level pinning uses the /model command with an @ suffix to select a named credential profile. Typing /model claude-3-5-sonnet@anthropic:production locks the current session to the production profile without changing defaults. Use /model list to see available profiles and /model status to check which one is active.

For persistent agent-level scoping, assign a credential priority order to each agent by name:

openclaw models auth order set --provider anthropic --agent research-bot anthropic:secondary
openclaw models auth order set --provider anthropic --agent customer-bot anthropic:production

Clear an agent's custom order with openclaw models auth order clear to fall back to the default priority ladder. Use openclaw models auth order get to inspect what is currently pinned.

Credential profiles and endpoint configuration live in separate files. Profiles (auth type, provider, key reference) belong in the auth profile store, while routing details like base URLs, model IDs, headers, and timeouts belong in your OpenClaw gateway configuration. Keeping these concerns separated means rotating a key never requires touching endpoint config, and vice versa.

For multi-agent systems that produce files, the agents need somewhere to write outputs that survives credential rotations and session resets. Local filesystem works for a single machine, but shared deployments benefit from a persistent workspace. Fastio's Business Trial provides 50GB of storage accessible through the MCP server, with audit logging that tracks which agent wrote which file.

OpenClaw ships with built-in diagnostics. Run these before and after any credential change to confirm the setup works.

Status Checks

The primary verification command is openclaw models status, which displays all configured auth profiles, their providers, and current state. Two flags add deeper inspection:

• --check exits with code 1 if any credential is expired or missing, and code 2 if a credential is about to expire. This makes it useful as a CI gate or health-check monitor: wrap it in a script and alert when the exit code is nonzero.
• --probe runs live authentication tests against each provider and reports detailed results per profile. The output flags profiles that were skipped due to auth ordering, profiles with no matching model candidate, and any rate-limit cooldown state. This is the fast way to confirm that a freshly rotated key actually works end to end.

For broader gateway health, openclaw doctor runs diagnostics across your entire configuration and suggests fixes. It catches mismatches between credential files and gateway config, missing environment variables, and format issues from older OpenClaw versions.

Common Errors and What They Mean "No credentials found": No API key or token is configured for the requested provider. Export the correct environment variable and re-run openclaw models status to confirm OpenClaw picks it up.

Token expiring or expired: Identify the affected profile with openclaw models status, then refresh OAuth credentials through the provider's authorization flow or rotate the API key in your provider's console.

Auth errors (401/403) not triggering rotation: This is intentional. A revoked or invalid key will fail at the provider regardless of retries, so cycling through it wastes quota on other keys. Generate a fresh key from your provider's console instead.

Stale legacy credentials: If you upgraded from an older OpenClaw version that stored credentials in a flat format, run openclaw doctor to detect and migrate to the current named-profile structure. The OpenClaw docs cover the migration path in detail.

One thing to remember: removing a provider's auth through the OpenClaw gateway deletes saved profiles for that provider, but it does not revoke keys at the provider itself. If a credential was compromised, you still need to manually delete it in your provider's developer console to prevent reuse.