vrr/agent-zero
2
0
Fork 0
mirror of https://github.com/agent0ai/agent-zero.git synced 2026-10-21 04:40:13 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
agent-zero/plugins/_oauth/README.md
Alessandro 45b74ab7cf fix(oauth): guide Codex reconnection and add sign-in code copying 
Handle rejected Codex refresh tokens with a clear authentication error and
an actionable toast that opens OAuth settings. Stop retrying marked tokens
and offer Reconnect without requiring a manual disconnect; successful
sign-in replaces credentials while cancellation preserves model choices.

Display device challenge codes in a selectable box with an accessible copy
button and success/error feedback. Keep recovery behavior inside _oauth
and document the connection lifecycle.

Validation: 221 Python checks and the Node frontend regression passed.
Verified recovery navigation, reconnect cancellation, clipboard copying,
keyboard access, and desktop/mobile layouts at localhost:32081 using
simulated OAuth responses.
2026-09-23 21:56:23 +02:00

3.4 KiB
Raw Blame History

OAuth Connections

Generic local OAuth bridge for Agent Zero.

Tokens in auth.json are password-equivalent credentials. Keep this plugin on trusted local machines only. Do not configure auth_file_path to share a rotating refresh-token file with Codex CLI or another client.

The settings UI groups providers as account-backed connections. More than one account provider can be connected at the same time, and the Main/Utility model slots can choose models from any connected OAuth provider.

Each model slot has its own provider selector. The selector lists connected OAuth accounts only, so Main and Utility can use different account-backed providers when more than one account is connected.

OAuth-backed model providers do not require users to enter API keys. Agent Zero supplies a local dummy key only at runtime after the selected account provider is connected, so unconnected providers stay blank in API-key surfaces.

Providers

Codex/ChatGPT (codex_oauth)

  • Uses the existing Codex device-code flow.
  • Shows the sign-in code in a selectable box with a copy button.
  • Writes Codex-compatible credentials to an Agent Zero-owned auth.json file.
  • Refreshes local tokens when needed.
  • If a refresh token expires or is revoked, shows an Open OAuth settings toast. Choose Reconnect on the Codex row and complete sign-in, then retry your request. No manual disconnect is needed; cancelling sign-in preserves the saved credentials and model choices.
  • Exposes the local OpenAI-compatible wrapper at /oauth/codex/v1.
  • Lets users choose default reasoning effort, visible reasoning summaries, and answer verbosity while preserving explicit per-request settings.

GitHub Copilot (github_copilot_oauth)

  • Uses GitHub's OAuth device flow.
  • Exchanges the GitHub access token for a Copilot API token.
  • Stores credentials under usr/plugins/_oauth/github_copilot/auth.json.

Google Cloud Gemini (gemini_api_oauth)

  • Uses Google's OAuth authorization-code flow with PKCE.
  • Requires a user-provided Google Cloud OAuth client with the Generative Language API enabled.
  • Proxies the official Gemini OpenAI-compatible endpoint at /oauth/gemini-api/v1.
  • Stores credentials under usr/plugins/_oauth/gemini_api/auth.json.
  • Uses Gemini API billing and quotas. It does not use Antigravity, Gemini Code Assist, Gemini CLI, Google AI Pro, or Google AI Ultra subscription quota.

xAI Grok (xai_grok_oauth)

  • Uses xAI's browser-based PKCE flow.
  • Supports manual callback paste for remote hosts where the browser cannot reach the local callback directly.
  • Stores credentials under usr/plugins/_oauth/xai_grok/auth.json.

Usage Plan Metadata

The status API exposes usage_plan_catalog for subscription and billing context. It covers only connectable providers: Codex, GitHub Copilot, Google Cloud Gemini, and xAI Grok.

The same status response also includes oauth_accounts, a compact summary used by the settings modal, welcome discovery card, and onboarding wizard. Keep that summary provider-registry driven so new OAuth providers appear consistently across those surfaces.

Remote xAI Callback

When Agent Zero is running on a remote host, the browser may complete the xAI authorization step somewhere other than the machine serving the local callback route. In that case, paste the callback value into the xAI card.

The xAI card accepts any of these formats:

  • Full callback URL.
  • Query string such as ?code=...&state=....
  • Bare authorization code.