M
Openclaw
DocumentationGitHubDiscord
Browse docs

Docs / concepts / oauth

OAuth

OAuth

  • how the OAuth token exchange works (PKCE)
  • where tokens are stored (and why)
  • how to handle multiple accounts (profiles + per-session overrides)
text
openclaw models auth login --provider <id>

The token sink (why it exists)

  • you log in via OpenClaw and via Claude Code / Codex CLI → one of them randomly gets “logged out” later
  • the runtime reads credentials from one place
  • we can keep multiple profiles and route them deterministically

Storage (where tokens live)

  • Auth profiles (OAuth + API keys): ~/.openclaw/agents/<agentId>/agent/auth-profiles.json
  • Runtime cache (managed automatically; don’t edit): ~/.openclaw/agents/<agentId>/agent/auth.json
  • ~/.openclaw/credentials/oauth.json (imported into auth-profiles.json on first use)

Anthropic setup-token (subscription auth)

text
openclaw models auth setup-token --provider anthropic
text
openclaw models auth paste-token --provider anthropic
text
openclaw models status

OAuth exchange (how login works)

Anthropic (Claude Pro/Max) setup-token

  1. run claude setup-token
  2. paste the token into OpenClaw
  3. store as a token auth profile (no refresh)

OpenAI Codex (ChatGPT OAuth)

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

Refresh + expiry

  • if expires is in the future → use the stored access token
  • if expired → refresh (under a file lock) and overwrite the stored credentials

Multiple accounts (profiles) + routing

1) Preferred: separate agents

text
openclaw agents add work
openclaw agents add personal

2) Advanced: multiple profiles in one agent

  • globally via config ordering (auth.order)
  • per-session via /model ...@<profileId>
  • /model Opus@anthropic:work
  • openclaw channels list --json (shows auth[])