Agdi 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 Agdi. 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)
Agdi also supports provider plugins that ship their own OAuth or API‑key
flows. Run them via:
agdi 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 Agdi and via Claude Code / Codex CLI → one of them randomly gets “logged out” later
To reduce that, Agdi treats auth-profiles.json as a token sink:
the runtime reads credentials from one place
we can keep multiple profiles and route them deterministically
Legacy compatibility file: ~/.agdi/agents/<agentId>/agent/auth.json
(static api_key entries are scrubbed when discovered)
Legacy import-only file (still supported, but not the main store):
~/.agdi/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/configurationFor 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 Agdi:
agdi models auth setup-token --provider anthropic
If you generated the token elsewhere, paste it manually:
agdi models auth paste-token --provider anthropic
Verify:
agdi models status
OAuth exchange (how login works)
Agdi’s interactive login flows are implemented in @mariozechner/pi-ai and wired into the wizards/commands.
Anthropic setup-token
Flow shape:
run claude setup-token
paste the token into Agdi
store as a token auth profile (no refresh)
The wizard path is agdi onboard → auth choice setup-token (Anthropic).
OpenAI Codex (ChatGPT OAuth)
OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including Agdi 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 agdi 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):
agdi agents add workagdi 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:
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Agdi","description":"Local-first agent workspace for assistants, automations, connected chat apps, and real tool execution on your own machine or private host.","colors":{"primary":"#2D7FF5","light":"#5BA0FF","dark":"#2266CC"},"logo":{"light":"https://mintcdn.com/agdiai-597e782f/655WPadtB96t29Rn/assets/agdi-mark.svg?fit=max\u0026auto=format\u0026n=655WPadtB96t29Rn\u0026q=85\u0026s=6ee0846be8797573d4bffde5f0eff316","dark":"https://mintcdn.com/agdiai-597e782f/655WPadtB96t29Rn/assets/agdi-mark.svg?fit=max\u0026auto=format\u0026n=655WPadtB96t29Rn\u0026q=85\u0026s=6ee0846be8797573d4bffde5f0eff316"},"favicon":"https://mintcdn.com/agdiai-597e782f/655WPadtB96t29Rn/assets/agdi-mark.svg?fit=max\u0026auto=format\u0026n=655WPadtB96t29Rn\u0026q=85\u0026s=6ee0846be8797573d4bffde5f0eff316","navbar":{"links":[{"icon":"github","href":"https://github.com/anassagd432/Agdi","label":"GitHub"},{"icon":"package","href":"https://github.com/anassagd432/Agdi/releases","label":"Releases"}]},"fonts":{"heading":{"family":"DM Sans"},"body":{"family":"Fragment Mono"}},"icons":{"library":"lucide"},"styling":{"codeblocks":{"theme":{"light":"min-light","dark":"min-dark"}},"latex":true},"navigation":{"languages":[{"language":"en","href":""},{"language":"zh-Hans","href":"zh-CN"},{"language":"ja","href":"ja-JP"}]}},"deployment":{"deploymentMetadataValue":{"subdomain":"agdiai-597e782f","hasAudioNarration":false,"actualSubdomain":"agdiai-597e782f","customDomains":[],"gitSource":{"type":"github","owner":"anassagd432","repo":"agdi","deployBranch":"main","contentDirectory":"docs","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6ab33d680f22712cd987acc8","clientVersion":"0.0.4143","searchFilterCounts":[{"language":"en","tag":"Reference","count":73},{"language":"zh-Hans","tag":"参考","count":63},{"language":"en","tag":"Tools \u0026 Plugins","count":61},{"language":"en","tag":"Workspace \u0026 Ops","count":55},{"language":"zh-Hans","tag":"工具","count":48},{"language":"en","tag":"CLI commands","count":47},{"language":"en","tag":"Models","count":41},{"language":"zh-Hans","tag":"CLI 命令","count":41},{"language":"zh-Hans","tag":"网关与运维","count":37},{"language":"en","tag":"Providers","count":36},{"language":"en","tag":"Runtime","count":34},{"language":"en","tag":"Channels","count":30},{"language":"en","tag":"Install","count":28},{"language":"zh-Hans","tag":"消息渠道","count":28},{"language":"en","tag":"Tools","count":27},{"language":"zh-Hans","tag":"网关","count":26},{"language":"zh-Hans","tag":"平台","count":26},{"language":"zh-Hans","tag":"模型","count":24},{"language":"zh-Hans","tag":"帮助","count":20},{"language":"zh-Hans","tag":"消息平台","count":20},{"language":"ja","tag":"はじめに","count":3},{"language":"ja","tag":"初回セットアップ","count":2},{"language":"ja","tag":"概要","count":1}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-rbac-roles","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"rbac-expansion","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-metadata","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-serve","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"live-agents","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":true},"customCss":[{"filePath":"style.css","content":"#content>h1:first-of-type{display:none!important}.nav-tabs{position:relative}.nav-tabs-item>div{opacity:0}.nav-tabs-underline{position:absolute;left:0;bottom:0;height:1.5px;width:var(--nav-tab-underline-width, 0);transform:translateX(var(--nav-tab-underline-x, 0));background-color:rgb(var(--primary));border-radius:999px;pointer-events:none;opacity:0;transition:transform 260ms ease-in-out,\n width 260ms ease-in-out,\n opacity 160ms ease-in-out;will-change:transform, width}html.dark .nav-tabs-underline{background-color:rgb(var(--primary-light))}.nav-tabs-underline-ready .nav-tabs-underline{opacity:1}"}],"page":{"pagePath":"concepts/oauth","slug":"/concepts/oauth","pageMetadata":{"summary":"OAuth in Agdi: token exchange, storage, and multi-account patterns","read_when":["You want to understand Agdi 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"],"title":"OAuth","description":null,"href":"/concepts/oauth"},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx,jsxs:_jsxs}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){const _components={a:`a`,code:`code`,em:`em`,li:`li`,ol:`ol`,p:`p`,pre:`pre`,span:`span`,strong:`strong`,ul:`ul`,..._provideComponents(),...props.components},{CodeBlock,Heading,Warning}=_components;if(!CodeBlock)_missingMdxReference(`CodeBlock`,true);if(!Heading)_missingMdxReference(`Heading`,true);if(!Warning)_missingMdxReference(`Warning`,true);return _jsxs(_Fragment,{children:[_jsx(Heading,{level:`1`,id:`oauth`,children:`OAuth`}),`\n`,_jsxs(_components.p,{children:[`Agdi supports “subscription auth” via OAuth for providers that offer it (notably `,_jsx(_components.strong,{children:`OpenAI Codex (ChatGPT OAuth)`}),`). For Anthropic subscriptions, use the `,_jsx(_components.strong,{children:`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 Agdi. This page explains:`]}),`\n`,_jsx(_components.p,{children:`For Anthropic in production, API key auth is the safer recommended path over subscription setup-token auth.`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`how the OAuth `,_jsx(_components.strong,{children:`token exchange`}),` works (PKCE)`]}),`\n`,_jsxs(_components.li,{children:[`where tokens are `,_jsx(_components.strong,{children:`stored`}),` (and why)`]}),`\n`,_jsxs(_components.li,{children:[`how to handle `,_jsx(_components.strong,{children:`multiple accounts`}),` (profiles + per-session overrides)`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Agdi also supports `,_jsx(_components.strong,{children:`provider plugins`}),` that ship their own OAuth or API‑key\nflows. Run them via:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes min-light min-dark`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#1f1f1f`,color:`#24292eff`,\"--shiki-dark\":`#b392f0`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` models`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` auth`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` login`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` --provider`}),_jsx(_components.span,{style:{color:`#D32F2F`,\"--shiki-dark\":`#F97583`},children:` \u003c`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:`i`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:`d`}),_jsx(_components.span,{style:{color:`#D32F2F`,\"--shiki-dark\":`#F97583`},children:`>`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`the-token-sink-why-it-exists`,children:`The token sink (why it exists)`}),`\n`,_jsxs(_components.p,{children:[`OAuth providers commonly mint a `,_jsx(_components.strong,{children:`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.`]}),`\n`,_jsx(_components.p,{children:`Practical symptom:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`you log in via Agdi `,_jsx(_components.em,{children:`and`}),` via Claude Code / Codex CLI → one of them randomly gets “logged out” later`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`To reduce that, Agdi treats `,_jsx(_components.code,{children:`auth-profiles.json`}),` as a `,_jsx(_components.strong,{children:`token sink`}),`:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`the runtime reads credentials from `,_jsx(_components.strong,{children:`one place`})]}),`\n`,_jsx(_components.li,{children:`we can keep multiple profiles and route them deterministically`}),`\n`]}),`\n`,_jsx(Heading,{level:`2`,id:`storage-where-tokens-live`,children:`Storage (where tokens live)`}),`\n`,_jsxs(_components.p,{children:[`Secrets are stored `,_jsx(_components.strong,{children:`per-agent`}),`:`]}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`Auth profiles (OAuth + API keys + optional value-level refs): `,_jsx(_components.code,{children:`~/.agdi/agents/\u003cagentId>/agent/auth-profiles.json`})]}),`\n`,_jsxs(_components.li,{children:[`Legacy compatibility file: `,_jsx(_components.code,{children:`~/.agdi/agents/\u003cagentId>/agent/auth.json`}),`\n(static `,_jsx(_components.code,{children:`api_key`}),` entries are scrubbed when discovered)`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Legacy import-only file (still supported, but not the main store):`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`~/.agdi/credentials/oauth.json`}),` (imported into `,_jsx(_components.code,{children:`auth-profiles.json`}),` on first use)`]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`All of the above also respect `,_jsx(_components.code,{children:`$OPENCLAW_STATE_DIR`}),` (state dir override). Full reference: `,_jsx(_components.a,{href:`/gateway/configuration-reference#auth-storage`,children:`/gateway/configuration`})]}),`\n`,_jsxs(_components.p,{children:[`For static secret refs and runtime snapshot activation behavior, see `,_jsx(_components.a,{href:`/gateway/secrets`,children:`Secrets Management`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`anthropic-setup-token-subscription-auth`,children:`Anthropic setup-token (subscription auth)`}),`\n`,_jsx(Warning,{children:_jsx(_components.p,{children:`Anthropic setup-token support is technical compatibility, not a policy guarantee.\nAnthropic has blocked some subscription usage outside Claude Code in the past.\nDecide for yourself whether to use subscription auth, and verify Anthropic’s current terms.`})}),`\n`,_jsxs(_components.p,{children:[`Run `,_jsx(_components.code,{children:`claude setup-token`}),` on any machine, then paste it into Agdi:`]}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes min-light min-dark`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#1f1f1f`,color:`#24292eff`,\"--shiki-dark\":`#b392f0`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` models`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` auth`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` setup-token`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` --provider`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` anthropic`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`If you generated the token elsewhere, paste it manually:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes min-light min-dark`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#1f1f1f`,color:`#24292eff`,\"--shiki-dark\":`#b392f0`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` models`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` auth`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` paste-token`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` --provider`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` anthropic`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Verify:`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`1`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes min-light min-dark`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#1f1f1f`,color:`#24292eff`,\"--shiki-dark\":`#b392f0`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`1`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` models`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` status`})]}),`\n`]})})}),`\n`,_jsx(Heading,{level:`2`,id:`oauth-exchange-how-login-works`,children:`OAuth exchange (how login works)`}),`\n`,_jsxs(_components.p,{children:[`Agdi’s interactive login flows are implemented in `,_jsx(_components.code,{children:`@mariozechner/pi-ai`}),` and wired into the wizards/commands.`]}),`\n`,_jsx(Heading,{level:`3`,id:`anthropic-setup-token`,children:`Anthropic setup-token`}),`\n`,_jsx(_components.p,{children:`Flow shape:`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`run `,_jsx(_components.code,{children:`claude setup-token`})]}),`\n`,_jsx(_components.li,{children:`paste the token into Agdi`}),`\n`,_jsx(_components.li,{children:`store as a token auth profile (no refresh)`}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`The wizard path is `,_jsx(_components.code,{children:`agdi onboard`}),` → auth choice `,_jsx(_components.code,{children:`setup-token`}),` (Anthropic).`]}),`\n`,_jsx(Heading,{level:`3`,id:`openai-codex-chatgpt-oauth`,children:`OpenAI Codex (ChatGPT OAuth)`}),`\n`,_jsx(_components.p,{children:`OpenAI Codex OAuth is explicitly supported for use outside the Codex CLI, including Agdi workflows.`}),`\n`,_jsx(_components.p,{children:`Flow shape (PKCE):`}),`\n`,_jsxs(_components.ol,{children:[`\n`,_jsxs(_components.li,{children:[`generate PKCE verifier/challenge + random `,_jsx(_components.code,{children:`state`})]}),`\n`,_jsxs(_components.li,{children:[`open `,_jsx(_components.code,{children:`https://auth.openai.com/oauth/authorize?...`})]}),`\n`,_jsxs(_components.li,{children:[`try to capture callback on `,_jsx(_components.code,{children:`http://127.0.0.1:1455/auth/callback`})]}),`\n`,_jsx(_components.li,{children:`if callback can’t bind (or you’re remote/headless), paste the redirect URL/code`}),`\n`,_jsxs(_components.li,{children:[`exchange at `,_jsx(_components.code,{children:`https://auth.openai.com/oauth/token`})]}),`\n`,_jsxs(_components.li,{children:[`extract `,_jsx(_components.code,{children:`accountId`}),` from the access token and store `,_jsx(_components.code,{children:`{ access, refresh, expires, accountId }`})]}),`\n`]}),`\n`,_jsxs(_components.p,{children:[`Wizard path is `,_jsx(_components.code,{children:`agdi onboard`}),` → auth choice `,_jsx(_components.code,{children:`openai-codex`}),`.`]}),`\n`,_jsx(Heading,{level:`2`,id:`refresh-+-expiry`,children:`Refresh + expiry`}),`\n`,_jsxs(_components.p,{children:[`Profiles store an `,_jsx(_components.code,{children:`expires`}),` timestamp.`]}),`\n`,_jsx(_components.p,{children:`At runtime:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`if `,_jsx(_components.code,{children:`expires`}),` is in the future → use the stored access token`]}),`\n`,_jsx(_components.li,{children:`if expired → refresh (under a file lock) and overwrite the stored credentials`}),`\n`]}),`\n`,_jsx(_components.p,{children:`The refresh flow is automatic; you generally don’t need to manage tokens manually.`}),`\n`,_jsx(Heading,{level:`2`,id:`multiple-accounts-profiles-+-routing`,children:`Multiple accounts (profiles) + routing`}),`\n`,_jsx(_components.p,{children:`Two patterns:`}),`\n`,_jsx(Heading,{level:`3`,id:`1-preferred-separate-agents`,children:`1) Preferred: separate agents`}),`\n`,_jsx(_components.p,{children:`If you want “personal” and “work” to never interact, use isolated agents (separate sessions + credentials + workspace):`}),`\n`,_jsx(CodeBlock,{filename:``,numberOfLines:`2`,language:`shellscript`,children:_jsx(_components.pre,{className:`shiki shiki-themes min-light min-dark`,style:{backgroundColor:`#ffffff`,\"--shiki-dark-bg\":`#1f1f1f`,color:`#24292eff`,\"--shiki-dark\":`#b392f0`},language:`shellscript`,children:_jsxs(_components.code,{language:`shellscript`,numberOfLines:`2`,children:[_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` agents`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` add`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` work`})]}),`\n`,_jsxs(_components.span,{className:`line`,children:[_jsx(_components.span,{style:{color:`#6F42C1`,\"--shiki-dark\":`#B392F0`},children:`agdi`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` agents`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` add`}),_jsx(_components.span,{style:{color:`#2B5581`,\"--shiki-dark\":`#9DB1C5`},children:` personal`})]}),`\n`]})})}),`\n`,_jsx(_components.p,{children:`Then configure auth per-agent (wizard) and route chats to the right agent.`}),`\n`,_jsx(Heading,{level:`3`,id:`2-advanced-multiple-profiles-in-one-agent`,children:`2) Advanced: multiple profiles in one agent`}),`\n`,_jsxs(_components.p,{children:[_jsx(_components.code,{children:`auth-profiles.json`}),` supports multiple profile IDs for the same provider.`]}),`\n`,_jsx(_components.p,{children:`Pick which profile is used:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[`globally via config ordering (`,_jsx(_components.code,{children:`auth.order`}),`)`]}),`\n`,_jsxs(_components.li,{children:[`per-session via `,_jsx(_components.code,{children:`/model ...@\u003cprofileId>`})]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Example (session override):`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsx(_components.li,{children:_jsx(_components.code,{children:`/model Opus@anthropic:work`})}),`\n`]}),`\n`,_jsx(_components.p,{children:`How to see what profile IDs exist:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.code,{children:`agdi channels list --json`}),` (shows `,_jsx(_components.code,{children:`auth[]`}),`)`]}),`\n`]}),`\n`,_jsx(_components.p,{children:`Related docs:`}),`\n`,_jsxs(_components.ul,{children:[`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/concepts/model-failover`,children:`/concepts/model-failover`}),` (rotation + cooldown rules)`]}),`\n`,_jsxs(_components.li,{children:[_jsx(_components.a,{href:`/tools/slash-commands`,children:`/tools/slash-commands`}),` (command surface)`]}),`\n`]})]})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent};function _missingMdxReference(id,component){throw new Error(`Expected `+(component?`component`:`object`)+\" `\"+id+\"` to be defined: you likely forgot to import, pass, or provide it.\")}","frontmatter":{},"scope":{"codeStyling":{"theme":{"light":"min-light","dark":"min-dark"}},"config":{},"pageMetadata":{"summary":"OAuth in Agdi: token exchange, storage, and multi-account patterns","read_when":["You want to understand Agdi 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"],"title":"OAuth","description":null,"href":"/concepts/oauth"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[{"title":"OAuth","slug":"oauth","depth":1,"children":[]},{"title":"The token sink (why it exists)","slug":"the-token-sink-why-it-exists","depth":2,"children":[]},{"title":"Storage (where tokens live)","slug":"storage-where-tokens-live","depth":2,"children":[]},{"title":"Anthropic setup-token (subscription auth)","slug":"anthropic-setup-token-subscription-auth","depth":2,"children":[]},{"title":"OAuth exchange (how login works)","slug":"oauth-exchange-how-login-works","depth":2,"children":[{"title":"Anthropic setup-token","slug":"anthropic-setup-token","depth":3,"children":[]},{"title":"OpenAI Codex (ChatGPT OAuth)","slug":"openai-codex-chatgpt-oauth","depth":3,"children":[]}]},{"title":"Refresh + expiry","slug":"refresh-+-expiry","depth":2,"children":[]},{"title":"Multiple accounts (profiles) + routing","slug":"multiple-accounts-profiles-+-routing","depth":2,"children":[{"title":"1) Preferred: separate agents","slug":"1-preferred-separate-agents","depth":3,"children":[]},{"title":"2) Advanced: multiple profiles in one agent","slug":"2-advanced-multiple-profiles-in-one-agent","depth":3,"children":[]}]}],"codeExamples":{}},"jsLinks":["/_mintlify/custom/agdiai-597e782f/27fa1e35cfee10a0/nav-tabs-underline.js"],"subdomain":"agdiai-597e782f","siteName":"Agdi","title":"OAuth - Agdi","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{"en":{"href":"/concepts/oauth","matchLevel":0},"zh-Hans":{"href":"/zh-CN/concepts/oauth","matchLevel":1},"ja":{"href":"/ja-JP","matchLevel":4}}},"lastModified":"2026-05-19T00:09:28.372Z","originalFileLocation":"concepts/oauth.md","locale":"en"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"application-name\" content=\"Agdi\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"OAuth - Agdi\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Agdi\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://agdiai-597e782f.mintlify.app/concepts/oauth\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://agdiai-597e782f.mintlify.site/_mintlify/api/og/v2?division=Fundamentals\u0026amp;title=OAuth\u0026amp;theme=5f7e62ada99f9144d8a99b50\u0026amp;signature=dbd184be56efa0e0fb9edb61689553180187591a227a4821eefb2ec288da4921\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"OAuth - Agdi\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://agdiai-597e782f.mintlify.site/_mintlify/api/og/v2?division=Fundamentals\u0026amp;title=OAuth\u0026amp;theme=5f7e62ada99f9144d8a99b50\u0026amp;signature=dbd184be56efa0e0fb9edb61689553180187591a227a4821eefb2ec288da4921\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/agdiai-597e782f/RRAJpq1o960cFJkG/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Agdi\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2D7FF5\">\u003clink data-mint-head rel=\"canonical\" href=\"https://agdiai-597e782f.mintlify.app/concepts/oauth\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/concepts/oauth.md\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"en\" href=\"https://agdiai-597e782f.mintlify.app/concepts/oauth\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"zh-Hans\" href=\"https://agdiai-597e782f.mintlify.app/zh-CN/concepts/oauth\">\u003clink data-mint-head rel=\"alternate\" hreflang=\"x-default\" href=\"https://agdiai-597e782f.mintlify.app/concepts/oauth\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://agdiai-597e782f.mintlify.app/#organization\",\"name\":\"Agdi\",\"url\":\"https://agdiai-597e782f.mintlify.app\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/agdiai-597e782f/655WPadtB96t29Rn/assets/agdi-mark.svg?fit=max\u0026auto=format\u0026n=655WPadtB96t29Rn\u0026q=85\u0026s=6ee0846be8797573d4bffde5f0eff316\"}},{\"@type\":\"WebSite\",\"@id\":\"https://agdiai-597e782f.mintlify.app#website\",\"name\":\"Agdi\",\"url\":\"https://agdiai-597e782f.mintlify.app\",\"publisher\":{\"@id\":\"https://agdiai-597e782f.mintlify.app/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth#webpage\",\"url\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth\",\"name\":\"OAuth\",\"dateModified\":\"2026-05-19T00:09:28.372Z\",\"isPartOf\":{\"@id\":\"https://agdiai-597e782f.mintlify.app#website\"},\"breadcrumb\":{\"@id\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Fundamentals\",\"item\":\"https://agdiai-597e782f.mintlify.app/concepts/architecture\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"OAuth\",\"item\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth\"}]},{\"@type\":[\"Article\",\"TechArticle\"],\"@id\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth#article\",\"headline\":\"OAuth\",\"name\":\"OAuth\",\"url\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth\",\"mainEntityOfPage\":{\"@id\":\"https://agdiai-597e782f.mintlify.app/concepts/oauth#webpage\"},\"dateModified\":\"2026-05-19T00:09:28.372Z\",\"publisher\":{\"@id\":\"https://agdiai-597e782f.mintlify.app/#organization\"},\"isPartOf\":{\"@id\":\"https://agdiai-597e782f.mintlify.app#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Agdi\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"Agdi\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/concepts/oauth.md","siteName":"Agdi","nav":{"global":null,"languages":[{"language":"en","tabs":[{"tab":"Get started","pages":[{"title":"Get started","href":""}]},{"tab":"Install","pages":[{"title":"Install","href":"/install"}]},{"tab":"Channels","pages":[{"title":"Channels","href":"/channels"}]},{"tab":"Agents","groups":[{"group":"Fundamentals","pages":[{"title":"Gateway Architecture","href":"/concepts/architecture"},{"title":"Agent Runtime","href":"/concepts/agent"},{"title":"Agent Loop","href":"/concepts/agent-loop"},{"title":"System Prompt","href":"/concepts/system-prompt"},{"title":"Context","href":"/concepts/context"},{"title":"Context Engine","href":"/concepts/context-engine"},{"title":"Agent Workspace","description":null,"href":"/concepts/agent-workspace"},{"title":"OAuth","href":"/concepts/oauth"},{"title":"Agent Bootstrapping","sidebarTitle":"Bootstrapping","description":null,"href":"/start/bootstrapping"}]},{"group":"Sessions and memory","pages":[{"title":"Session Management","href":"/concepts/session"},{"title":"Session Pruning","href":"/concepts/session-pruning"},{"title":"Session Tools","href":"/concepts/session-tool"},{"title":"Memory","href":"/concepts/memory"},{"title":"Compaction","href":"/concepts/compaction"}]},{"group":"Multi-agent","pages":[{"title":"Multi-Agent Routing","href":"/concepts/multi-agent"},{"title":"Presence","href":"/concepts/presence"},{"title":"Delegate Architecture","href":"/concepts/delegate-architecture"}]},{"group":"Messages and delivery","pages":[{"title":"Messages","href":"/concepts/messages"},{"title":"Streaming and Chunking","href":"/concepts/streaming"},{"title":"Retry Policy","href":"/concepts/retry"},{"title":"Command Queue","href":"/concepts/queue"}]}]},{"tab":"Tools \u0026 Plugins","pages":[{"title":"Tools \u0026 Plugins","href":"/tools"}]},{"tab":"Models","pages":[{"title":"Models","href":"/providers"}]},{"tab":"Platforms","pages":[{"title":"Platforms","href":"/platforms"}]},{"tab":"Workspace \u0026 Ops","pages":[{"title":"Workspace \u0026 Ops","href":"/gateway"}]},{"tab":"Reference","pages":[{"title":"Reference","href":"/cli"}]},{"tab":"Help","pages":[{"title":"Help","href":"/help"}]}]},{"language":"zh-Hans","pages":[{"title":"zh-Hans","href":"/zh-CN/concepts/oauth"}]},{"language":"ja","pages":[{"title":"ja","href":"/ja-JP"}]}]},"basePath":"","title":"OAuth - Agdi","buildId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","deploymentId":"dpl_Fyv1NbzwP68g2bEH2Roy98uY1zmE","dynamics":[],"chunks":[]}