Use this file to discover all available pages before exploring further.

OAuth

OpenClaw supports “subscription auth” via OAuth for providers that offer it (notably OpenAI Codex (ChatGPT OAuth)). For Anthropic, the practical split is now:

Anthropic API key: normal Anthropic API billing
Anthropic Claude CLI / subscription auth inside OpenClaw: Anthropic staff told us this usage is allowed again

OpenAI Codex OAuth is explicitly supported for use in external tools like OpenClaw. This page explains:

For Anthropic in production, API key auth is the safer recommended path.

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:


bash
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

text

auth-profiles.json

as a token sink:

the runtime reads credentials from one place
we can keep multiple profiles and route them deterministically
external CLI reuse is provider-specific: Codex CLI can bootstrap an empty
text
openai-codex:default
profile, but once OpenClaw has a local OAuth profile, the local refresh token is canonical; other integrations can remain externally managed and re-read their CLI auth store
status and startup paths that already know the configured provider set scope external CLI discovery to that set, so an unrelated CLI login store is not probed for a single-provider setup

Storage (where tokens live)

Secrets are stored in agent auth stores:

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

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

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

All of the above also respect

text

$OPENCLAW_STATE_DIR

(state dir override). Full reference: /gateway/configuration

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

When a secondary agent has no local auth profile, OpenClaw uses read-through inheritance from the default/main agent store. It does not clone the main agent's

text

auth-profiles.json

on read. OAuth refresh tokens are especially sensitive: normal copy flows skip them by default because some providers rotate or invalidate refresh tokens after use. Configure a separate OAuth login for an agent when it needs an independent account.

Anthropic legacy token compatibility

warning

Anthropic's public Claude Code docs say direct Claude Code use stays within Claude subscription limits, and Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again. OpenClaw therefore treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.

For Anthropic's current direct-Claude-Code plan docs, see Using Claude Code with your Pro or Max plan and Using Claude Code with your Team or Enterprise plan.

If you want other subscription-style options in OpenClaw, see OpenAI Codex, Qwen Cloud Coding Plan, MiniMax Coding Plan, and Z.AI / GLM Coding Plan.

OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and

text

claude -p

when available.

Anthropic Claude CLI migration

OpenClaw supports Anthropic Claude CLI reuse again. If you already have a local Claude login on the host, onboarding/configure can reuse it directly.

OAuth exchange (how login works)

OpenClaw’s interactive login flows are implemented in

text

@mariozechner/pi-ai

and wired into the wizards/commands.

Anthropic setup-token

Flow shape:

start Anthropic setup-token or paste-token from OpenClaw
OpenClaw stores the resulting Anthropic credential in an auth profile
model selection stays on
text
anthropic/...
existing Anthropic auth profiles remain available for rollback/order control

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.

Flow shape (PKCE):

generate PKCE verifier/challenge + random
text
state
open
text
https://auth.openai.com/oauth/authorize?...
try to capture callback on
text
http://127.0.0.1:1455/auth/callback
if callback can’t bind (or you’re remote/headless), paste the redirect URL/code
exchange at
text
https://auth.openai.com/oauth/token
extract
text
accountId
from the access token and store
text
{ access, refresh, expires, accountId }

Wizard path is

text

openclaw onboard

→ auth choice

text

openai-codex

Refresh + expiry

Profiles store an

text

expires

timestamp.

At runtime:

if
text
expires
is in the future → use the stored access token
if expired → refresh (under a file lock) and overwrite the stored credentials
if a secondary agent reads an inherited main-agent OAuth profile, refresh writes back to the main agent store instead of copying the refresh token into the secondary agent store
exception: some external CLI credentials stay externally managed; OpenClaw re-reads those CLI auth stores instead of spending copied refresh tokens. Codex CLI bootstrap is intentionally narrower: it seeds an empty
text
openai-codex:default
profile, then OpenClaw-owned refreshes keep the local profile canonical.

The refresh flow is automatic; you generally don't need to manage tokens manually.

Multiple accounts (profiles) + routing

Two patterns:

1) Preferred: separate agents

If you want “personal” and “work” to never interact, use isolated agents (separate sessions + credentials + workspace):


bash
openclaw agents add work
openclaw agents add personal

Then configure auth per-agent (wizard) and route chats to the right agent.

2) Advanced: multiple profiles in one agent

text

auth-profiles.json

supports multiple profile IDs for the same provider.

Pick which profile is used:

globally via config ordering (
text
auth.order
)
per-session via
text
/model ...@<profileId>

Example (session override):

text
/model Opus@anthropic:work

How to see what profile IDs exist:

text
openclaw channels list --json
(shows
text
auth[]
)

Related docs:

Model failover (rotation + cooldown rules)
Slash commands (command surface)

Authentication — model provider auth overview
Secrets — credential storage and SecretRef
Configuration Reference — auth config keys

OpenClaw Docs

OAuth

The token sink (why it exists)

Storage (where tokens live)

Anthropic legacy token compatibility

warning

Anthropic Claude CLI migration

OAuth exchange (how login works)

Anthropic setup-token

OpenAI Codex (ChatGPT OAuth)

Refresh + expiry

Multiple accounts (profiles) + routing

1) Preferred: separate agents

2) Advanced: multiple profiles in one agent

Related