OpenClaw OAuth

Subscription authentication looks simple until two tools own the same account. Then logins start cancelling each other, seemingly at random. OpenClaw's design addresses that directly: one place per agent owns the credential, external tool reuse is narrow and provider-specific, and refresh writes back to whoever owns the token rather than to a copy.

The token sink

• Providers commonly mint a new refresh token on every login or refresh, and some invalidate the previous one for the same user and application; the practical symptom is logging in through two tools and having one of them silently logged out later.
• So the auth profile store is treated as a sink: the runtime reads credentials from one place per agent, multiple profiles coexist and route deterministically, and once OpenClaw owns a local profile for a provider its refresh token is canonical, with a rejection reported for re-authentication rather than falling back to external token material.
• Credentials use a shared read-through base with agent-local overrides: a shared state database, an agent database for credentials and routing, one table for credential rows and another for order, last-good, cooldown and usage; personal accounts added by a signed-in person live in identity-scoped records instead.
• Retired credential files are handled explicitly: when the database already holds profiles a leftover file is just bytes and gets archived on the next doctor fix, and when the store is empty the runtime reads only enough metadata to scope a migration-required error to the affected providers, refusing to fall through to environment auth for those while others keep working.

OAuth refresh tokens are especially sensitive: normal copy flows skip them by default because some providers rotate or invalidate refresh tokens after use.

The exchange and the refresh

The subscription login flow is an authorization-code exchange with proof key: OpenClaw generates a verifier, a challenge and a random state, opens the provider authorize URL with the usual identity and offline scopes, and tries to capture the callback on a loopback port whose host only accepts loopback addresses. If you are headless, or the callback cannot bind, you paste the redirect back instead, and whichever completes first wins the race. The code is exchanged for tokens, and the account identifier is extracted from the access token and stored with the access, refresh and expiry values. At runtime an unexpired access token is used as is, an expired one is refreshed and written back to the owning store rather than copied into an agent database, and externally managed command-line credentials are re-read instead of spending a copied refresh token. The refresh flow is automatic, so tokens do not normally need manual management.

Running several accounts

• The preferred pattern is separate agents, because an agent is its own sessions, credentials and workspace, so personal and work never interact; add the agents and configure auth per agent.
• The advanced pattern keeps several profile ids for one provider inside one agent and picks between them globally through the configured auth order or per session with a model command carrying the profile suffix.
• The multi-user pattern is per-person accounts on a shared gateway: each verified person saves accounts per provider and chooses a default for new chats, both sign-in surfaces show the gateway, the person and the personal scope before asking for provider credentials, and personal credentials stay outside the shared profile list because a shared gateway token does not identify a person.

OpenClaw model authentication is the wider provider-auth picture and OpenClaw secrets management the reference-based alternative to pasted keys.

Why agents beat profiles for isolation

Multiple profiles inside one agent solve routing, not isolation. The agent still shares one workspace, one session store and one set of tools, so a mistake in routing is a mistake with someone else's account attached. Separate agents make the boundary structural, and the docs recommend that path first for exactly that reason. The same logic governs copying: when an agent has no local profile it reads the shared store rather than cloning credentials into its own database, and refresh tokens are skipped by normal copy flows because rotation would break whichever copy loses the race. If an agent genuinely needs an independent account, the answer is a separate login for that agent rather than a duplicated token. OpenClaw model failover explains rotation and cooldown between credentials and OpenClaw models explained how a selected model reaches one.

On Diali

On Diali the model credentials belong to the platform, so customers do not run provider logins on a server of their own, and the runtime configuration is generated from the dashboard and replaced at each release. Hosted OpenClaw on Diali describes the hosted assistant and Diali security the boundary around each runtime.

• One owner per agent; copies lose the refresh race.
• The callback is loopback only; pasting the redirect is the fallback.
• Separate agents isolate accounts; profiles only route them.