openclaw/docs/concepts/oauth.md at fb1dfd486bb9aca05055d88c51efe4fbc279a9fc

mirror of https://github.com/openclaw/openclaw.git synced 2026-05-29 16:55:14 +00:00

Files

Peter Steinberger bb46b79d3c refactor: internalize OpenClaw agent runtime (#85341 )

* refactor: extract agent core package

Introduce packages/agent-core as the OpenClaw-owned home for reusable agent loop, harness, session, prompt, and runtime dependency contracts.

* refactor: extract shared llm runtime

Move provider model registries, stream wrappers, OAuth helpers, and LLM utilities into src/llm with plugin-sdk barrels instead of depending on the old embedded runtime layout.

* refactor: remove pi runtime internals

Rename remaining Pi-shaped agent surfaces to OpenClaw agent runtime names, delete obsolete Pi docs and package graph checks, and add the third-party notice for incorporated code.

* refactor: tighten agent session runtime

Make agent-core/runtime dependencies explicit, consolidate compaction and session transcript helpers, and move model/session helpers behind OpenClaw-owned contracts.

* refactor: remove static model and pi auth paths

Drop static model catalogs and Pi auth bridges, move model/provider facts to manifest-owned runtime contracts, and harden internal embedded-agent utilities.

* refactor: remove legacy provider compat paths

* docs: remove agent parity notes

* fix: skip provider wildcard metadata parsing

* refactor: share session extension sdk loading

* refactor: inline acpx proxy error formatter

* refactor: fold edit recovery into edit tool

* fix: accept extension batch separator

* test: align startup provider plugin expectations

* fix: restore provider-scoped release discovery

* test: align static asset packaging expectations

* fix: run static provider catalogs during scoped discovery

* fix: add provider entry catalogs for scoped live discovery

* fix: load lightweight provider catalog entries

* fix: refresh provider-scoped plugin metadata

* fix: keep provider catalog entries on release live path

* fix: keep static manifest models in release live checks

* fix: harden release model discovery

* fix: reduce OpenAI live cache probe reasoning

* fix: disable OpenAI cache probe reasoning

* ci: extend OpenAI gateway live timeout

* fix: extend live gateway model budget

* fix: stabilize release validation regressions

* fix: honor provider aliases in model rows

* fix: stabilize release validation lanes

* fix: stabilize release memory qa

* ci: stabilize release validation lanes

* ci: prefer ipv4 for live docker node calls

* fix: restore shared tool-call stream wrapper

* ci: remove legacy pi test shard alias

* fix: clean up embedded agent test drift

* fix: stabilize runtime alias status

* fix: clean up embedded agent ci drift

* fix: restore release ci invariants

* fix: clean up post-rebase runtime drift

* fix: restore release ci checks

* fix: restore release ci after rebase

* fix: remove stale pi runtime path

* test: align compaction runtime expectations

* test: update plugin prerelease expectations

* fix: handle claude live tool approvals

* fix: stabilize release validation gates

* fix: finish agent runtime import

* test: finish post-rebase agent runtime mocks

* fix: keep codex compaction native

* fix: stabilize codex app-server hook tests

* test: isolate codex diagnostic active run

* test: remove codex diagnostic completion race

# Conflicts:
#	extensions/codex/src/app-server/run-attempt.test.ts

* ci: fix full release manifest performance run id

* refactor: narrow llm plugin sdk boundary

* chore: drop generated google boundary stamps

* fix: repair rebase fallout

* fix: clean up rebased runtime references

* fix: decode codex jwt payloads as base64url

* fix: preserve shipped pi runtime alias

* fix: add scoped sdk virtual modules

* fix: decode llm codex oauth jwt as base64url

* fix: avoid stale vertex adc negative cache

* fix: harden tool arg decoding and codeql path

* fix: keep vertex adc negative checks live

* refactor: consolidate codex jwt and edit helpers

* fix: await codex oauth node runtime imports

* fix: preserve sdk tool and notice contracts

* fix: preserve shipped compat config boundaries

* fix: align codex oauth callback host

* fix: terminate agent-core loop streams on failure

* fix: keep codex oauth callback alive during fallback

* ci: include session tools in critical codeql scans

* fix: keep Cloudflare Anthropic provider auth header

* docs: redirect legacy pi runtime pages

* fix: honor bundled web provider compat discovery

* fix: protect session output spill files

* fix: keep legacy agent dir env blocked

* fix: contain auto-discovered skill symlinks

* fix: harden agent core sdk proxy surfaces

* fix: restore approval reaction sdk compat

* fix: keep live docker runs bounded

* fix: keep codex oauth redirect host aligned

* fix: resolve post-rebase agent runtime drift

* fix: redact anthropic oauth parse failures

* fix: preserve responses strict tool shaping

* fix: repair agent runtime rebase cleanup

* docs: redirect retired parity pages

* fix: bound auto-discovered resources to roots

* fix: repair post-rebase agent test drift

* fix: preserve bundled provider allowlist migration

* fix: preserve manifest-owned provider aliases

* fix: declare photon image dependency

* fix: keep provider headers out of proxy body

* fix: preserve shipped env aliases

* fix: refresh control ui i18n generated state

* fix: quote read fallback paths

* fix: preview edits through configured backend

* test: satisfy core test typecheck

* fix: preserve ZAI usage auth fallback

* test: repair codex diagnostic test

* fix: repair agent runtime rebase drift

* test: finish embedded runner import rename

* fix: repair agent runtime rebase integrations

* test: align compaction oauth fallback expectations

* fix: allow sdk-auth session models

* fix: update doctor tool schema import

* fix: preserve bedrock plugin region

* fix: stream harmony-like prose immediately

* ci: include session runtime in codeql shards

* fix: repair latest rebase integrations

* fix: honor explicit codex websocket transport

* fix: keep openai-compatible credentials provider-scoped

* fix: refresh sdk api baseline after rebase

* fix: route cli runtime aliases through openclaw harness

* test: rename stale harness mock expectation

* test: rename embedded agent overflow calls

* test: clean embedded auth test wording

* test: use openclaw stream types in deepinfra cache test

* fix: refresh sdk api baseline on latest main

* fix: honor bundled discovery compat allowlists

* fix: refresh sdk api baseline after latest rebase

* fix: remove stale rebase imports

* test: rename stale model catalog mock

* test: mock renamed doctor runtime modules

* fix: map canonical kimi env auth

* fix: use internal model registry in bench script

* fix: migrate deepinfra provider catalog entry

* fix: enforce builtin tool suppression

* fix: route compaction auth and proxy payloads safely

* refactor: prune unused llm registry leftovers

* test: update codex hooks session import

* test: fix model picker ci coverage

* test: align model picker auth mock types

2026-05-27 19:24:04 +01:00

7.9 KiB

Raw Blame History

summary, read_when, title

summary

read_when

title

OAuth in OpenClaw: token exchange, storage, and multi-account patterns

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

OAuth

OpenClaw supports "subscription auth" via OAuth for providers that offer it (notably OpenAI Codex (ChatGPT OAuth)). For Anthropic, the practical split is now:

Anthropic API key: normal Anthropic API billing
Anthropic Claude CLI / subscription auth inside OpenClaw: Anthropic staff told us this usage is allowed again

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:

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
external CLI reuse is provider-specific: Codex CLI can bootstrap an empty openai-codex:default profile, but once OpenClaw has a local OAuth profile, the local refresh token is canonical. If that local refresh token is rejected, OpenClaw can use a usable same-account Codex CLI token as a runtime-only fallback; other integrations can remain externally managed and re-read their CLI auth store
status and startup paths that already know the configured provider set scope external CLI discovery to that set, so an unrelated CLI login store is not probed for a single-provider setup

Storage (where tokens live)

Secrets are stored in agent auth stores:

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

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

When a secondary agent has no local auth profile, OpenClaw uses read-through inheritance from the default/main agent store. It does not clone the main agent's auth-profiles.json on read. OAuth refresh tokens are especially sensitive: normal copy flows skip them by default because some providers rotate or invalidate refresh tokens after use. Configure a separate OAuth login for an agent when it needs an independent account.

Anthropic legacy token compatibility

Anthropic's public Claude Code docs say direct Claude Code use stays within Claude subscription limits, and Anthropic staff told us OpenClaw-style Claude CLI usage is allowed again. OpenClaw therefore treats Claude CLI reuse and `claude -p` usage as sanctioned for this integration unless Anthropic publishes a new policy.

For Anthropic's current direct-Claude-Code plan docs, see Using Claude Code with your Pro or Max plan and Using Claude Code with your Team or Enterprise plan.

If you want other subscription-style options in OpenClaw, see OpenAI Codex, Qwen Cloud Coding Plan, MiniMax Coding Plan, and Z.AI / GLM Coding Plan.

OpenClaw also exposes Anthropic setup-token as a supported token-auth path, but it now prefers Claude CLI reuse and claude -p when available.

Anthropic Claude CLI migration

OpenClaw supports Anthropic Claude CLI reuse again. If you already have a local Claude login on the host, onboarding/configure can reuse it directly.

OpenClaw's interactive login flows are implemented in openclaw/plugin-sdk/llm and wired into the wizards/commands.

Anthropic setup-token

Flow shape:

start Anthropic setup-token or paste-token from OpenClaw
OpenClaw stores the resulting Anthropic credential in an auth profile
model selection stays on anthropic/...
existing Anthropic auth profiles remain available for rollback/order control

OpenAI Codex (ChatGPT OAuth)

OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including OpenClaw workflows.

Flow shape (PKCE):

generate PKCE verifier/challenge + random state
open https://auth.openai.com/oauth/authorize?...
try to capture callback on http://127.0.0.1:1455/auth/callback
if callback can't bind (or you're remote/headless), paste the redirect URL/code
exchange at https://auth.openai.com/oauth/token
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
if a secondary agent reads an inherited main-agent OAuth profile, refresh writes back to the main agent store instead of copying the refresh token into the secondary agent store
exception: some external CLI credentials stay externally managed; OpenClaw re-reads those CLI auth stores instead of spending copied refresh tokens. Codex CLI bootstrap is intentionally narrower: it seeds an empty openai-codex:default profile, then OpenClaw-owned refreshes keep the local profile canonical. If the local Codex refresh fails and Codex CLI has a usable token for the same account, OpenClaw may use that token for the current runtime request without writing it back to auth-profiles.json.

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:

openclaw channels list --json (shows auth[])

Related docs:

Model failover (rotation + cooldown rules)
Slash commands (command surface)

Authentication - model provider auth overview
Secrets - credential storage and SecretRef
Configuration Reference - auth config keys

7.9 KiB Raw Blame History