bot/docs/concepts/oauth.md

summary, read_when, title

summary	read_when	title
OAuth in Hanzo Bot: token exchange, storage, and multi-account patterns	You want to understand Hanzo Bot OAuth end-to-end You hit token invalidation / logout issues You want setup-token or OAuth auth flows You want multiple accounts or profile routing	OAuth

OAuth

Hanzo Bot supports “subscription auth” via OAuth for providers that offer it (notably OpenAI Codex (ChatGPT OAuth)). For Anthropic subscriptions, use the setup-token flow. Anthropic subscription use outside Claude Code has been restricted for some users in the past, so treat it as a user-choice risk and verify current Anthropic policy yourself. OpenAI Codex OAuth is explicitly supported for use in external tools like Hanzo Bot. This page explains:

For Anthropic in production, API key auth is the safer recommended path over subscription setup-token auth.

• how the OAuth token exchange works (PKCE)
• where tokens are stored (and why)
• how to handle multiple accounts (profiles + per-session overrides)

Hanzo Bot also supports provider plugins that ship their own OAuth or API‑key flows. Run them via:

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 Hanzo Bot and via Claude Code / Codex CLI → one of them randomly gets “logged out” later

To reduce that, Hanzo Bot treats auth-profiles.json as a token sink:

• the runtime reads credentials from one place
• we can keep multiple profiles and route them deterministically

Storage (where tokens live)

Secrets are stored per-agent:

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

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

• ~/.hanzo/bot/credentials/oauth.json (imported into auth-profiles.json on first use)

All of the above also respect $BOT_STATE_DIR (state dir override). Full reference: /gateway/configuration

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

Anthropic setup-token (subscription auth)

Anthropic setup-token support is technical compatibility, not a policy guarantee. Anthropic has blocked some subscription usage outside Claude Code in the past. Decide for yourself whether to use subscription auth, and verify Anthropic's current terms.

Run claude setup-token on any machine, then paste it into Hanzo Bot:

openclaw models auth setup-token --provider anthropic

If you generated the token elsewhere, paste it manually:

openclaw models auth paste-token --provider anthropic

Verify:

openclaw models status

OAuth exchange (how login works)

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

Anthropic setup-token

Flow shape:

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

The wizard path is hanzo-bot onboard → auth choice setup-token (Anthropic).

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including Hanzo Bot 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 hanzo-bot 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

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):

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:

• hanzo-bot channels list --json (shows auth[])

Related docs:

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