feat: add OpenAI Codex OAuth PKCE install flow #1129

eureka928 · 2026-02-02T20:49:26Z

Description

This PR adds support for installing and authenticating OpenAI Codex as a tool via OAuth PKCE flow. Users can install Codex from both the Settings/MCP page and the AddWorker tool selection, with automatic token management including refresh and expiry handling.

Closes #834

Key Changes:

Backend (backend/):

app/utils/toolkit/codex_toolkit.py — New CodexOAuthManager implementing the full OpenAI OAuth PKCE flow (authorization URL generation, token exchange, refresh, revocation, and persistent token storage via keyring)
app/controller/tool_controller.py — New endpoints for Codex install, uninstall, save-token, and status; integrated into existing /install/{tool} and /uninstall/{tool} routes

Server (server/):

app/model/config/config.py — Added CODEX config group with OPENAI_API_KEY environment variable mapping
app/type/config_group.py — Registered codex in ConfigGroup enum and CONFIG_GROUP_ENV_VARS

Frontend (src/):

src/pages/Setting/MCP.tsx — Codex card in Settings with install/uninstall buttons and OAuth callback handling
src/components/AddWorker/ToolSelect.tsx — Codex option in worker tool selection with installed state detection
src/hooks/useIntegrationManagement.ts — Codex integration status hook
src/components/IntegrationList/index.tsx — Codex entry in integration list

Files Changed:

backend/app/controller/tool_controller.py
backend/app/utils/toolkit/codex_toolkit.py (new)
server/app/model/config/config.py
server/app/type/config_group.py
src/components/AddWorker/ToolSelect.tsx
src/components/IntegrationList/index.tsx
src/hooks/useIntegrationManagement.ts
src/pages/Setting/MCP.tsx

What is the purpose of this pull request?

Bug fix
New Feature
Documentation update
Other

eureka928 · 2026-02-02T20:50:50Z

@Wendong-Fan @Pakchoioioi would you review my PR?
Thank you

eureka928 · 2026-02-02T20:51:11Z

Also, @Wendong-Fan would you check my DM on discord?
Thank you

eureka928 · 2026-02-02T23:04:40Z

Why these are cancelled?

4pmtong · 2026-02-03T09:27:49Z

Hi @eureka928! Thanks for your contribution! I'm doing a detailed review, @Pakchoioioi Could you help review the OAuth flow?

eureka928 · 2026-02-03T20:02:12Z

Fixed the testing

eureka928 · 2026-02-04T09:31:38Z

Follow up on this

bytecii

Thanks. Left some comments

src/components/AddWorker/ToolSelect.tsx

src/pages/Setting/MCP.tsx

backend/app/utils/codex_oauth.py

backend/app/utils/toolkit/codex_toolkit.py

backend/app/controller/tool_controller.py

backend/app/utils/toolkit/codex_toolkit.py

- Extract Codex config constants (CODEX_CONFIG_GROUP, CODEX_CONFIG_NAME, CODEX_POLL_TIMEOUT_MS) in ToolSelect.tsx - Extract CODEX_TOKEN_PATH constant and clarify CODEX_CLIENT_ID is a fixed public value in codex_toolkit.py - Simplify expires_in/expires_at: compute absolute expiry from relative value and only persist expires_at - Add FileLock around token file reads/writes to prevent parallel update races - Add TODO for response status string improvement and refactor of shared OAuth install logic - Apply formatting suggestion on codex uninstall message

eureka928 · 2026-02-05T01:11:18Z

Hi @bytecii addressed all comments

backend/app/utils/codex_oauth.py

backend/app/utils/toolkit/codex_toolkit.py

eureka928 · 2026-02-05T10:38:50Z

I updated all, please review again

- Extract Codex config constants (CODEX_CONFIG_GROUP, CODEX_CONFIG_NAME, CODEX_POLL_TIMEOUT_MS) in ToolSelect.tsx - Extract CODEX_TOKEN_PATH constant and clarify CODEX_CLIENT_ID is a fixed public value in codex_toolkit.py - Simplify expires_in/expires_at: compute absolute expiry from relative value and only persist expires_at - Add FileLock around token file reads/writes to prevent parallel update races - Add TODO for response status string improvement and refactor of shared OAuth install logic - Apply formatting suggestion on codex uninstall message

4pmtong

LGTM, thanks @eureka928 for contribution!

eureka928 · 2026-02-08T02:30:31Z

@Wendong-Fan please review again, I addressed all comments

Wendong-Fan

seems it's still organized as one toolkit?

eureka928 · 2026-02-09T04:58:03Z

Good catch — moved codex_toolkit.py out of agent/toolkit/ to app/utils/codex_oauth.py (alongside oauth_state_manager.py). Updated imports and tests accordingly: 6463041

Wendong-Fan

thanks @eureka928 's update,

as discussed Codex should not be treated as a "tool" in tool_controller.py. Looking at the implementation:

  # codex_oauth.py
  if token_data.get("access_token"):
      os.environ["OPENAI_API_KEY"] = token_data["access_token"]

The OAuth flow simply obtains an OPENAI_API_KEY, Codex is fundamentally an authentication method for the OpenAI provider, not a standalone tool like Notion or Google Calendar.

now Codex endpoints (/install/tool/codex, /uninstall/tool/codex, /codex/status, /codex/save-token) are in tool_controller.py alongside actual MCP tools which is not in the right place
in /tools/available response: Codex is listed as an available "tool"

Suggested Refactor:

Move Codex OAuth logic to a provider/model authentication controller (or create one), since it belongs with OpenAI provider configuration, which the frontend already handles correctly in Models.tsx

Implements Authorization Code + PKCE flow using Codex CLI's public client_id. Handles background OAuth via localhost callback server, token persistence at ~/.eigent/tokens/codex/, and refresh logic.

Add codex handling to install_tool and uninstall_tool endpoints. Add POST /codex/save-token for manual API key fallback and GET /codex/status for token status. Add Codex to available tools list.

Add CODEX enum to ConfigGroup and corresponding entry in ConfigInfo.configs with OPENAI_API_KEY env var and codex_oauth toolkit.

Add Codex config check in useIntegrationManagement for installed state and uninstall cleanup. Add Codex case in IntegrationList handleInstall to trigger onInstall directly without env dialog.

Add Codex onInstall handler with OAuth status polling in MCP.tsx settings page and ToolSelect.tsx AddWorker flow, following the existing Google Calendar authorization pattern.

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Co-authored-by: bytecii <994513625@qq.com>

- Extract Codex config constants (CODEX_CONFIG_GROUP, CODEX_CONFIG_NAME, CODEX_POLL_TIMEOUT_MS) in ToolSelect.tsx - Extract CODEX_TOKEN_PATH constant and clarify CODEX_CLIENT_ID is a fixed public value in codex_toolkit.py - Simplify expires_in/expires_at: compute absolute expiry from relative value and only persist expires_at - Add FileLock around token file reads/writes to prevent parallel update races - Add TODO for response status string improvement and refactor of shared OAuth install logic - Apply formatting suggestion on codex uninstall message

- Add Fernet encryption for token storage using cryptography library - Derive encryption key from machine-specific identifiers (username, hostname, machine-id) using PBKDF2HMAC with 100k iterations - Set restrictive file permissions (0600) on encrypted token file - Tokens tied to specific machine for additional security

…t config Address review feedback: Codex OAuth obtains an OpenAI API key for model access, not agent tools. After successful OAuth, the key is now saved via the Provider API (/api/provider) so it integrates with the model provider configuration system. Changes: - Backend: return access_token in Codex install response for provider storage - Frontend: replace /api/configs storage with /api/provider for Codex - Server: mark CODEX ConfigInfo entry as type=provider with empty env_vars - i18n: add missing codex translation keys, remove verbose t() fallback pattern - Fix stray merge conflict marker in ToolSelect.tsx - Remove debug console.log statements from MCP.tsx

- Save CODEX_OAUTH_TOKEN marker config after OAuth to track install state - Check marker config instead of OPENAI_API_KEY for install detection - Avoid mutating input dict in CodexOAuthManager.save_token() - Add CODEX_OAUTH_TOKEN to Codex env_vars whitelist in server config - Prioritize named integration descriptions over env_vars fallback

Codex OAuth is a model-provider integration, not a toolkit. Remove it from ConfigInfo.configs so it no longer appears in the /api/config/info response that drives the MCP & Tools UI. Also remove Codex-specific install detection and uninstall handling from useIntegrationManagement and IntegrationList.

Remove the entire Codex onInstall handler, saveCodexAsProvider, and saveCodexMarkerConfig helpers from MCP.tsx and ToolSelect.tsx. Extract OAuth polling constants (OAUTH_POLL_INTERVAL_MS, OAUTH_POLL_TIMEOUT_MS) to replace inline magic numbers in the remaining Google Calendar flow. Add TODO for status string enum extraction.

Add a "Connect via Codex" button to the OpenAI BYOK provider panel in the Models settings page. The OAuth PKCE flow obtains an OpenAI API key and saves it as a provider, with a marker config for state detection. - Add handleCodexOAuth, saveCodexAsProvider, handleCodexDisconnect - Extract refreshProviderForm helper to deduplicate provider list sync - Show "or" divider between Codex OAuth and manual API key entry - Disconnect properly revokes token, removes marker, and resets provider - Add i18n keys for connect/disconnect/status UI text

Codex OAuth is a provider credential manager, not an agent toolkit. Move it to app/utils/codex_oauth.py alongside oauth_state_manager.py.

…ntroller Codex OAuth is an authentication method for the OpenAI provider, not a standalone MCP tool. Move all Codex endpoints to a dedicated controller with semantically correct paths (/codex/connect, /codex/disconnect) and update the frontend to use the new routes.

eureka928 force-pushed the feat/codex-oauth branch from 6c8f1c0 to 30877f8 Compare February 2, 2026 22:33

4pmtong requested review from 4pmtong, Pakchoioioi and Wendong-Fan February 3, 2026 09:17

eureka928 force-pushed the feat/codex-oauth branch from 30877f8 to e64c519 Compare February 3, 2026 19:44

eureka928 force-pushed the feat/codex-oauth branch 2 times, most recently from f33d37b to bdbc3e3 Compare February 4, 2026 09:11

Wendong-Fan requested a review from bytecii February 4, 2026 22:22

bytecii reviewed Feb 4, 2026

View reviewed changes

4pmtong reviewed Feb 5, 2026

View reviewed changes

backend/app/utils/codex_oauth.py Show resolved Hide resolved

eureka928 requested a review from 4pmtong February 5, 2026 04:54

4pmtong reviewed Feb 5, 2026

View reviewed changes

backend/app/utils/codex_oauth.py Show resolved Hide resolved

bytecii reviewed Feb 5, 2026

View reviewed changes

backend/app/utils/codex_oauth.py Show resolved Hide resolved

backend/app/utils/toolkit/codex_toolkit.py Outdated Show resolved Hide resolved

eureka928 requested review from 4pmtong and bytecii February 5, 2026 10:38

eureka928 force-pushed the feat/codex-oauth branch from 5326462 to bdaec62 Compare February 5, 2026 10:39

eureka928 force-pushed the feat/codex-oauth branch from bdaec62 to 89cf2bc Compare February 5, 2026 15:53

4pmtong approved these changes Feb 6, 2026

View reviewed changes

Wendong-Fan added this to the Sprint 13 milestone Feb 6, 2026

Wendong-Fan reviewed Feb 8, 2026

View reviewed changes

Wendong-Fan added the Waiting for Update label Feb 8, 2026

eureka928 requested a review from Wendong-Fan February 9, 2026 04:50

Wendong-Fan reviewed Feb 10, 2026

View reviewed changes

eureka928 and others added 22 commits February 10, 2026 10:44

feat: add CodexOAuthManager for OpenAI Codex PKCE OAuth flow

7650a89

Implements Authorization Code + PKCE flow using Codex CLI's public client_id. Handles background OAuth via localhost callback server, token persistence at ~/.eigent/tokens/codex/, and refresh logic.

feat: add Codex install/uninstall/save-token/status endpoints

c273996

Add codex handling to install_tool and uninstall_tool endpoints. Add POST /codex/save-token for manual API key fallback and GET /codex/status for token status. Add Codex to available tools list.

feat: add Codex config group and OPENAI_API_KEY env var mapping

2d4c4bb

Add CODEX enum to ConfigGroup and corresponding entry in ConfigInfo.configs with OPENAI_API_KEY env var and codex_oauth toolkit.

feat: add Codex installed detection, uninstall, and install handling

145b6a3

Add Codex config check in useIntegrationManagement for installed state and uninstall cleanup. Add Codex case in IntegrationList handleInstall to trigger onInstall directly without env dialog.

feat: add Codex OAuth install flow in Settings and AddWorker

79ef592

Add Codex onInstall handler with OAuth status polling in MCP.tsx settings page and ToolSelect.tsx AddWorker flow, following the existing Google Calendar authorization pattern.

style: fix pre-commit lint errors (E501, yapf formatting)

88d2f15

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

fix: replace undefined Optional with int | None in CodexTokenRequest

87339a4

Update backend/app/controller/tool_controller.py

cd0544d

Co-authored-by: bytecii <994513625@qq.com>

style: apply ruff formatting fixes

54ba1a6

refactor: move imports to top of codex_toolkit.py

aa29c41

test: add unit tests for codex_toolkit.py

1497f1a

feat: add OAuth state parameter for CSRF protection

2699f6e

fix: add missing blank line to pass ruff lint

be38ca5

fix: remove unused Optional import to pass ruff lint

1fc69bb

refactor: move Codex OAuth manager out of agent/toolkit to utils

d09ccba

Codex OAuth is a provider credential manager, not an agent toolkit. Move it to app/utils/codex_oauth.py alongside oauth_state_manager.py.

eureka928 force-pushed the feat/codex-oauth branch from 95d92c8 to d09ccba Compare February 10, 2026 09:44

feat: add OpenAI Codex OAuth PKCE install flow #1129

Are you sure you want to change the base?

feat: add OpenAI Codex OAuth PKCE install flow #1129

Conversation

eureka928 commented Feb 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

What is the purpose of this pull request?

Uh oh!

eureka928 commented Feb 2, 2026

Uh oh!

eureka928 commented Feb 2, 2026

Uh oh!

eureka928 commented Feb 2, 2026

Uh oh!

4pmtong commented Feb 3, 2026

Uh oh!

eureka928 commented Feb 3, 2026

Uh oh!

eureka928 commented Feb 4, 2026

Uh oh!

bytecii left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eureka928 commented Feb 5, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

eureka928 commented Feb 5, 2026

Uh oh!

4pmtong left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

eureka928 commented Feb 8, 2026

Uh oh!

Wendong-Fan left a comment

Choose a reason for hiding this comment

Uh oh!

eureka928 commented Feb 9, 2026

Uh oh!

Wendong-Fan left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

eureka928 commented Feb 2, 2026 •

edited

Loading

4pmtong left a comment •

edited

Loading