OpenClaw OAuth Explained

OAuth in OpenClaw is not treated like a casual login button. The docs frame it as subscription auth for providers that offer it, with OpenAI Codex ChatGPT OAuth named directly and Anthropic handled through a mix of API key, Claude CLI reuse, and legacy token paths. The important idea is that OpenClaw is trying to make subscription-style auth usable in a gateway environment without turning token storage and refresh into a random mess.

The token sink idea is the key concept

One of the best explanations in the docs is the token sink. OAuth providers can issue new refresh tokens during login or refresh, and in some ecosystems that can invalidate older refresh tokens for the same user and app. The practical symptom is that you log in from OpenClaw and another CLI, then one of them mysteriously gets logged out later. OpenClaw uses auth-profiles.json as a single sink so the runtime reads credentials from one place and can manage multiple profiles deterministically.

Storage is per agent, not global by accident

The docs say secrets are stored per agent in ~/.openclaw/agents//agent/auth-profiles.json, with a legacy compatibility auth.json still present and an old import-only oauth.json path supported for legacy import. That per-agent storage model matters because it lets you isolate work and personal identities by agent instead of letting them collide in one giant bucket. The docs explicitly recommend separate agents when you want those worlds to never interact.

The OpenAI Codex OAuth flow uses PKCE

For OpenAI Codex OAuth, the documented flow generates a PKCE verifier and challenge plus a random state, opens the OpenAI authorize URL, tries to capture the callback on http://127.0.0.1:1455/auth/callback, and falls back to pasted redirect URLs or codes when that local callback path is not available. After the token exchange, OpenClaw extracts accountId from the access token and stores access, refresh, expires, and accountId in the auth profile. That is very concrete, which is exactly what operators need.

Refresh behavior is automatic but controlled

Profiles store an expires timestamp. If the token is still valid, OpenClaw uses it. If it is expired, OpenClaw refreshes it under a file lock and writes back the updated credentials. The exception is reused external CLI credentials. In that case, OpenClaw re-reads the external CLI auth store and does not spend the copied refresh token itself. That is another subtle safety choice aimed at avoiding refresh-token fights with outside tooling.

Multiple accounts are a routing problem, not a mystery

The docs describe two patterns for multiple accounts. The preferred one is separate agents, which keeps workspaces, sessions, and credentials isolated. The advanced one is multiple profiles within one agent, selected through auth.order or per-session /model ...@profileId overrides. That framing is useful because it pushes you toward isolation first and complexity second. If the accounts should never touch, make that true structurally instead of hoping profile selection is always perfect.

So the short version is that OpenClaw OAuth is disciplined rather than decorative. PKCE is explicit, storage is per agent, refresh is locked, reused CLI credentials are treated carefully, and multiple profiles are first-class citizens instead of undocumented hacks. That is how you make subscription-style auth usable in an operator product without quietly turning it into token roulette.

The docs also do a nice job separating what is supported from what is merely technically possible. OAuth exists for the providers that offer it, but OpenClaw still pushes operators toward explicit isolation, predictable storage, and status visibility. That is the real point. OAuth is not there to feel modern. It is there to be usable inside a gateway that might run for weeks without human babysitting.

If you want the operator version of these docs turned into a practical working system, read The OpenClaw Playbook. It connects official OpenClaw features to real workflows, guardrails, and deployment decisions.