How to Configure OpenAI API Key for the Codex Plugin

The Codex plugin delegates all authentication to the locally-installed Codex CLI, which reads the OPENAI_API_KEY environment variable or credentials stored via codex login.

The openai/codex-plugin-cc repository provides a Claude Code plugin that relies on your existing Codex CLI installation rather than managing its own API credentials. To configure the OpenAI API key for the Codex plugin, you must ensure the CLI can access your credentials through one of its supported authentication methods. This design keeps sensitive tokens out of the plugin's codebase and leverages the same security model used by the standalone codex command.

Set the OPENAI_API_KEY Environment Variable

The most direct method to configure the OpenAI API key for the Codex plugin is to export the OPENAI_API_KEY variable in your shell environment. According to the source code in plugins/codex/scripts/lib/codex.mjs, the plugin invokes the local codex binary, which checks process.env.OPENAI_API_KEY at startup.

Add the following to your shell profile for persistent access:

# ~/.bashrc, ~/.zshrc, or ~/.bash_profile

export OPENAI_API_KEY="sk-your-key-here"

For temporary use in a single session, run the export command directly in your terminal before starting Claude Code.

Use a Repository-Level .env File

The plugin automatically loads environment variables from a .env file located at the repository root before invoking the CLI. This approach keeps the OpenAI API key configuration local to your project without modifying global shell settings.

Create a file named .env in your project root:

# .env

OPENAI_API_KEY=sk-your-key-here

The plugin's startup script processes this file, making the variable available to the Codex CLI when executing commands like /codex:review or /codex:rescue.

Authenticate Interactively with codex login

If no environment variable is detected, you can configure the OpenAI API key for the Codex plugin using the interactive login flow. The /codex:setup command runs codex login under the hood when it cannot find valid credentials, as documented in plugins/codex/commands/setup.md.

Run the following inside Claude Code:

!codex login

Alternatively, execute from a terminal:

codex login

This prompts you to paste your API key or sign in with a ChatGPT subscription. The credentials are stored in ~/.codex/config.toml, where the CLI retrieves them for subsequent requests. The test fixture tests/fake-codex-fixture.mjs confirms that the plugin expects the OPENAI_API_KEY variable name to match this standard.

Project-Level Configuration Files

While the .codex/config.toml file allows you to override default models and reasoning effort, it does not store the API key itself. The key must still be supplied via OPENAI_API_KEY or the login flow.

Create .codex/config.toml at your repository root to customize behavior:

# .codex/config.toml

model = "gpt-5.4-mini"
model_reasoning_effort = "high"

The Codex CLI continues to read the OpenAI API key from the environment or global config, ensuring sensitive credentials remain separate from project-specific settings.

Verify Your Configuration

Confirm that the OpenAI API key is properly configured for the Codex plugin by running the setup command:

/codex:setup

If the key is correctly detected, you will see a success message. If not, the command offers to launch codex login automatically. This verification step ensures that all subsequent /codex:* commands can authenticate with the OpenAI service.

Summary

• The Codex plugin in openai/codex-plugin-cc does not store API credentials; it forwards authentication to the local Codex CLI.
• Environment variable: Set OPENAI_API_KEY in your shell profile for global access.
• .env file: Place OPENAI_API_KEY in a repository root .env file for project-specific configuration.
• codex login: Run interactively to store credentials in ~/.codex/config.toml when environment variables are unavailable.
• Verification: Use /codex:setup to confirm the plugin can locate your API key before executing other commands.

Frequently Asked Questions

Where does the Codex plugin store my API key?

The plugin does not store your API key. According to the source code in plugins/codex/scripts/lib/codex.mjs, the plugin acts as a wrapper that calls the locally installed codex binary. The CLI stores credentials in ~/.codex/config.toml only if you use the codex login flow; otherwise, it reads from the OPENAI_API_KEY environment variable without persisting the value.

Can I use a different environment variable name for the API key?

No. The Codex CLI specifically checks for OPENAI_API_KEY, as verified by the test fixture tests/fake-codex-fixture.mjs. The plugin relies on this exact variable name to match the OpenAI standard used across their ecosystem.

Why does the plugin require the Codex CLI to be installed separately?

The plugin architecture delegates all API communication and authentication to the CLI to avoid duplicating credential management logic. This ensures that any security updates or authentication changes in the Codex CLI automatically apply to the plugin, and it prevents sensitive tokens from being embedded in the plugin's source code or configuration files.

How do I switch between different OpenAI API keys for different projects?

Use repository-level .env files. Place a .env file containing OPENAI_API_KEY in each project's root directory. The plugin loads this file before invoking the CLI, allowing you to maintain separate keys for different codebases without changing your global shell environment.

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