How the Codex Plugin Handles Authentication and Provider Configuration

The Codex plugin delegates all authentication concerns to the locally-installed Codex CLI and its app-server, querying for account information and global configuration to build a unified status object that drives the plugin's authorization decisions.

The openai/codex-plugin-cc repository implements a VS Code extension that integrates OpenAI's Codex CLI into the editor. Rather than implementing its own authentication flow or credential storage, the plugin relies entirely on the locally installed Codex CLI and its app-server component to manage credentials and provider settings.

Detecting Codex CLI Availability

Before attempting any authentication checks, the plugin verifies that the codex binary and its app-server are present. In plugins/codex/scripts/lib/process.mjs, the binaryAvailable function checks for the CLI on disk. If the binary is missing, the auth status short-circuits immediately with available: false, preventing further RPC calls to a non-existent server.

Querying the App-Server for Account and Configuration

The core authentication logic resides in plugins/codex/scripts/lib/codex.mjs. The exported getCodexAuthStatus function instantiates a CodexAppServerClient (defined in plugins/codex/scripts/lib/app-server.mjs) and delegates to getCodexAuthStatusFromClient. This helper issues two synchronous RPC calls to the local app-server:

• account/read (with refreshToken: false): Returns the active account type, either "chatgpt" or "apiKey"
• config/read (with includeLayers: false): Returns the global Codex configuration, including model_provider and model_providers

Both calls are wrapped in try / catch blocks. Network failures or RPC errors are transformed into a loggedIn: false status, ensuring the plugin degrades gracefully when the app-server is unreachable.

Resolving Provider Configuration

Raw configuration data from the app-server requires normalization before the plugin can use it to determine authorization requirements.

Normalizing Provider Information

The resolveProviderConfig function in plugins/codex/scripts/lib/codex.mjs processes the config response:

• Extracts model_provider as providerId
• Looks up the matching entry in the model_providers array as providerConfig
• Returns an object { providerId, providerConfig } where missing values become null

Formatting Provider Labels

The formatProviderLabel helper converts provider identifiers into human-readable strings. It maintains a built-in mapping for known providers including openai, ollama, and lmstudio, falling back to the raw ID string for custom or unknown configurations.

Building the Unified Auth Status

The plugin standardizes authentication state through two builder functions in plugins/codex/scripts/lib/codex.mjs, ensuring consistent data structures for downstream commands.

The Status Object Structure

buildAuthStatus creates a baseline object with fields used throughout the plugin:

function buildAuthStatus(fields = {}) {
  return {
    available: true,
    loggedIn: false,
    detail: "not authenticated",
    source: "unknown",
    authMethod: null,
    verified: null,
    requiresOpenaiAuth: null,
    provider: null,
    ...fields
  };
}

Authentication Method Mapping

buildAppServerAuthStatus combines the account payload and resolved provider info into the final status object:

• ChatGPT login: Sets authMethod: "chatgpt", verified: true, and includes the user's email in the detail field
• API key login: Sets authMethod: "apiKey" with verified: false
• Local providers (e.g., Ollama): Sets loggedIn: true with a detail message indicating the provider is configured and does not require OpenAI authentication
• OpenAI-dependent providers: Sets loggedIn: false when OpenAI authentication is required but missing, with an appropriate detail message

All branches return the standardized object created by buildAuthStatus, exposing a consistent shape to callers regardless of the underlying authentication method.

Public API and Usage

The plugin exports getCodexAuthStatus(cwd, options?) as the primary entry point used by commands like /codex:setup. The function returns an object with the following TypeScript interface:

{
  available: boolean,
  loggedIn: boolean,
  detail: string,
  source: "app-server" | "availability" | "unknown",
  authMethod: "chatgpt" | "apiKey" | null,
  verified: boolean | null,
  requiresOpenaiAuth: boolean | null,
  provider: string | null
}

This status object determines whether to prompt the user to run !codex login, enable the review gate, or allow background tasks that do not require OpenAI credentials.

import { getCodexAuthStatus } from "./plugins/codex/scripts/lib/codex.mjs";

async function checkAuth() {
  const status = await getCodexAuthStatus(process.cwd());
  console.log(`Available: ${status.available}`);
  console.log(`Logged in: ${status.loggedIn}`);
  console.log(`Provider: ${status.provider}`);
  console.log(`Method: ${status.authMethod}`);
}

Summary

• The plugin delegates authentication to the Codex CLI app-server rather than implementing its own credential flow or storage
• Availability checks in process.mjs prevent calls to missing binaries and return available: false immediately
• RPC calls to account/read and config/read retrieve credentials and provider settings from the local app-server
• Provider resolution via resolveProviderConfig normalizes provider IDs and configuration objects
• Status standardization through buildAuthStatus ensures consistent output for downstream commands regardless of whether the user authenticated via ChatGPT or API key

Frequently Asked Questions

Does the Codex plugin store API keys or credentials locally?

No. According to the openai/codex-plugin-cc source code, the plugin does not implement its own authentication flow or store credentials. It delegates all auth concerns to the locally-installed Codex CLI and queries the app-server for current account information via the account/read RPC method.

What happens if the Codex CLI is not installed?

If binaryAvailable in plugins/codex/scripts/lib/process.mjs detects that the codex binary is missing, getCodexAuthStatus returns immediately with available: false and loggedIn: false, short-circuiting further authentication checks and preventing RPC errors.

How does the plugin handle different AI providers like Ollama or LM Studio?

The plugin reads the model_provider and model_providers fields from the app-server configuration via the config/read RPC call. It supports built-in labels for openai, ollama, and lmstudio through formatProviderLabel, and can distinguish between providers that require OpenAI authentication versus local instances that operate without it.

What is the difference between ChatGPT and API key authentication methods in the status object?

ChatGPT login sets authMethod: "chatgpt" with verified: true and includes the user's email address in the detail field, while API key login sets authMethod: "apiKey" with verified: false. This verification status affects how downstream commands interpret the authentication context and whether they prompt for additional login steps.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}