Manage OAuth and Subscriptions in OpenClaw

Ever felt the frustration of getting kicked out of one AI tool just because you logged into another? Managing OAuth tokens across different providers and CLI tools can feel like a game of whack-a-mole. OpenClaw handles this by being smart about how it stores and refreshes your credentials so you can focus on building.

OpenClaw supports “subscription auth” via OAuth for providers that offer it (notably OpenAI Codex (ChatGPT OAuth)). For Anthropic subscriptions, you can either use the setup-token flow or reuse a local Claude CLI login on the gateway host. Anthropic subscription use outside Claude Code has been restricted for some users in the past, so treat it as a user-choice risk and verify current Anthropic policy yourself. OpenAI Codex OAuth is explicitly supported for use in external tools like OpenClaw.

For Anthropic in production, API key auth is the safer recommended path over subscription setup-token auth.

This guide explains:

• how the OAuth token exchange works (PKCE)
• where tokens are stored (and why)
• how to handle multiple accounts (profiles + per-session overrides)

OpenClaw also supports provider plugins that ship their own OAuth or API‑key flows. Run them via:

openclaw models auth login --provider <id>

The token sink (why it exists)

OAuth providers commonly mint a new refresh token during login/refresh flows. Some providers (or OAuth clients) can invalidate older refresh tokens when a new one is issued for the same user/app.

Practical symptom:

• you log in via OpenClaw and via Claude Code / Codex CLI → one of them randomly gets “logged out” later

To reduce that, OpenClaw treats auth-profiles.json as a token sink:

• the runtime reads credentials from one place
• we can keep multiple profiles and route them deterministically

Storage (where tokens live)

Secrets are stored per-agent:

• Auth profiles (OAuth + API keys + optional value-level refs): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
• Legacy compatibility file: ~/.openclaw/agents/<agentId>/agent/auth.json (static api_key entries are scrubbed when discovered)

Legacy import-only file (still supported, but not the main store):

• ~/.openclaw/credentials/oauth.json (imported into auth-profiles.json on first use)

All of the above also respect $OPENCLAW_STATE_DIR (state dir override). Full reference: /gateway/configuration

For static secret refs and runtime snapshot activation behavior, see Secrets Management.

Anthropic setup-token (subscription auth)

[!WARNING] Anthropic setup-token support is technical compatibility, not a policy guarantee. Anthropic has blocked some subscription usage outside Claude Code in the past

openclaw models auth setup-token --provider anthropic

openclaw models auth paste-token --provider anthropic

openclaw models status

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

openclaw onboard --auth-choice anthropic-cli

openclaw agents add work
openclaw agents add personal