mirror of
https://github.com/openclaw/openclaw.git
synced 2026-04-06 23:01:08 +00:00
211 lines
7.3 KiB
Markdown
211 lines
7.3 KiB
Markdown
---
|
||
summary: "OAuth in OpenClaw: token exchange, storage, and multi-account patterns"
|
||
read_when:
|
||
- You want to understand OpenClaw OAuth end-to-end
|
||
- You hit token invalidation / logout issues
|
||
- You want Claude CLI or OAuth auth flows
|
||
- You want multiple accounts or profile routing
|
||
title: "OAuth"
|
||
---
|
||
|
||
# OAuth
|
||
|
||
OpenClaw supports “subscription auth” via OAuth for providers that offer it
|
||
(notably **OpenAI Codex (ChatGPT OAuth)**). For Anthropic subscriptions, new
|
||
setup should use the local **Claude CLI** login path on the gateway host, but
|
||
Anthropic changed third-party harness billing on
|
||
**April 4, 2026 at 12:00 PM PT / 8:00 PM BST**: Anthropic says Claude
|
||
subscription limits no longer cover OpenClaw and Anthropic now requires **Extra
|
||
Usage** for that traffic. 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 `auth-profiles.json` as a **token sink**:
|
||
|
||
- the runtime reads credentials from **one place**
|
||
- we can keep multiple profiles and route them deterministically
|
||
- when credentials are reused from an external CLI like Codex CLI, OpenClaw
|
||
mirrors them with provenance and re-reads that external source instead of
|
||
rotating the refresh token itself
|
||
|
||
## 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](/gateway/configuration-reference#auth-storage)
|
||
|
||
For static secret refs and runtime snapshot activation behavior, see [Secrets Management](/gateway/secrets).
|
||
|
||
## Anthropic legacy token compatibility
|
||
|
||
<Warning>
|
||
Anthropic changed third-party harness billing on **April 4, 2026 at 12:00 PM
|
||
PT / 8:00 PM BST**. Anthropic says Claude subscription limits no longer cover
|
||
OpenClaw or other third-party harnesses. Existing Anthropic token profiles
|
||
remain technically usable in OpenClaw, but Anthropic now requires **Extra
|
||
Usage** (pay-as-you-go billed separately from the subscription) for that
|
||
traffic.
|
||
|
||
If you want other subscription-style options in OpenClaw, see [OpenAI
|
||
Codex](/providers/openai), [Alibaba Cloud Model Studio Coding
|
||
Plan](/providers/qwen_modelstudio), [MiniMax Coding Plan](/providers/minimax),
|
||
and [Z.AI / GLM Coding Plan](/providers/glm).
|
||
</Warning>
|
||
|
||
OpenClaw no longer offers Anthropic setup-token onboarding or auth commands for
|
||
new setup. Existing legacy Anthropic token profiles are still honored at
|
||
runtime if they are already configured.
|
||
|
||
## Anthropic Claude CLI migration
|
||
|
||
If Claude CLI is already installed and signed in on the gateway host, you can
|
||
switch Anthropic model selection over to the local CLI backend. This is a
|
||
supported OpenClaw path when you want to reuse a local Claude CLI login on the
|
||
same host.
|
||
|
||
Prerequisites:
|
||
|
||
- the `claude` binary is installed on the gateway host
|
||
- Claude CLI is already authenticated there via `claude auth login`
|
||
|
||
Migration command:
|
||
|
||
```bash
|
||
openclaw models auth login --provider anthropic --method cli --set-default
|
||
```
|
||
|
||
Onboarding shortcut:
|
||
|
||
```bash
|
||
openclaw onboard --auth-choice anthropic-cli
|
||
```
|
||
|
||
This keeps existing Anthropic auth profiles for rollback, but rewrites the main
|
||
default-model path from `anthropic/...` to `claude-cli/...`, rewrites matching
|
||
Anthropic Claude fallbacks, and adds matching `claude-cli/...` allowlist
|
||
entries under `agents.defaults.models`.
|
||
|
||
Verify:
|
||
|
||
```bash
|
||
openclaw models status
|
||
```
|
||
|
||
## OAuth exchange (how login works)
|
||
|
||
OpenClaw’s interactive login flows are implemented in `@mariozechner/pi-ai` and wired into the wizards/commands.
|
||
|
||
### Anthropic Claude CLI
|
||
|
||
Flow shape:
|
||
|
||
Claude CLI path:
|
||
|
||
1. sign in with `claude auth login` on the gateway host
|
||
2. run `openclaw models auth login --provider anthropic --method cli --set-default`
|
||
3. store no new auth profile; switch model selection to `claude-cli/...`
|
||
4. keep existing Anthropic auth profiles for rollback
|
||
|
||
Interactive assistant path:
|
||
|
||
- `openclaw onboard` / `openclaw configure` → auth choice `anthropic-cli`
|
||
|
||
### OpenAI Codex (ChatGPT OAuth)
|
||
|
||
OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.
|
||
|
||
Flow shape (PKCE):
|
||
|
||
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 }`
|
||
|
||
Wizard path is `openclaw onboard` → auth choice `openai-codex`.
|
||
|
||
## Refresh + expiry
|
||
|
||
Profiles store an `expires` timestamp.
|
||
|
||
At runtime:
|
||
|
||
- if `expires` is in the future → use the stored access token
|
||
- if expired → refresh (under a file lock) and overwrite the stored credentials
|
||
- exception: reused external CLI credentials stay externally managed; OpenClaw
|
||
re-reads the CLI auth store and never spends the copied refresh token itself
|
||
|
||
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
|
||
|
||
`auth-profiles.json` supports multiple profile IDs for the same provider.
|
||
|
||
Pick which profile is used:
|
||
|
||
- globally via config ordering (`auth.order`)
|
||
- per-session via `/model ...@<profileId>`
|
||
|
||
Example (session override):
|
||
|
||
- `/model Opus@anthropic:work`
|
||
|
||
How to see what profile IDs exist:
|
||
|
||
- `openclaw channels list --json` (shows `auth[]`)
|
||
|
||
Related docs:
|
||
|
||
- [/concepts/model-failover](/concepts/model-failover) (rotation + cooldown rules)
|
||
- [/tools/slash-commands](/tools/slash-commands) (command surface)
|
||
|
||
## Related
|
||
|
||
- [Authentication](/gateway/authentication) — model provider auth overview
|
||
- [Secrets](/gateway/secrets) — credential storage and SecretRef
|
||
- [Configuration Reference](/gateway/configuration-reference#auth-storage) — auth config keys
|