OAuth

OpenClaw supports "subscription auth" via OAuth for providers that offer it (notably OpenAI Codex (ChatGPT OAuth)). For Anthropic subscriptions, use the setup-token flow. This page explains:

- How 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>

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.

実際的症状：

- 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

代理每个密钥存储：

- Auth profiles (OAuth + API keys): ''~/.openclaw/agents/<agentId>/agent/auth-profiles.json''

- 运行时缓存（自动管理、编辑不要）：''~/.openclaw/agents/<agentId>/agent/auth.json''

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

- ''~/.openclaw/credentials/oauth.json''（初回使用時在 ''auth-profiles.json'' 在导入被）

上記的全部是 ''$OPENCLAW_STATE_DIR''（状态目录的覆盖）也尊重执行。完全那参考：''/gateway/configuration''

Run ''claude setup-token'' on any machine, then paste it into OpenClaw:

openclaw models auth setup-token --provider anthropic

如果您在其他地方生成了令牌，请手动粘贴：

openclaw models auth paste-token --provider anthropic

検証：

openclaw models status

OpenClaw's interactive login flows are implemented in ''@mariozechner/pi-ai'' and wired into the wizards/commands.

流程的形状：

1. ''claude setup-token'' 运行执行

2. paste the token into OpenClaw

3. store as a token auth profile (no refresh)'
'Wizard path is ''openclaw onboard'' → auth choice ''setup-token'' (Anthropic).

流程的形状（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. ''https://auth.openai.com/oauth/token'' 在交換执行

6. extract ''accountId'' from the access token and store ''{ access, refresh, expires, accountId }''

向导路径是 ''openclaw onboard'' → 认证选择 ''openai-codex''。

Profiles store an ''expires'' timestamp.

运行时時：

- if ''expires'' is in the future → use the stored access token

- if expired → refresh (under a file lock) and overwrite the stored credentials'
'The refresh flow is automatic; you generally don't need to manage tokens manually.

Two patterns:

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

openclaw agents add work
openclaw agents add personal

然后为每个代理配置认证（向导）并将聊天路由到正确的代理。

''auth-profiles.json'' supports multiple profile IDs for the same provider.

选择使用的配置文件：

- 设置顺序在全局在 (''auth.order'')

- ''/model ...@<profileId>'' 在会话每个

示示例（会话覆盖）：

- ''/model Opus@anthropic:work''

如何查看存在哪些配置文件 ID：

- ''openclaw channels list --json''（''auth[]'' 显示）

関連文档：

- ''/concepts/model-failover'' (rotation + cooldown rules)'
'- ''/tools/slash-commands'' (command surface)