Codex CLI Provider

The ai-sdk-provider-codex-cli community provider enables using OpenAI's GPT-5 series models through the Codex CLI. It's useful for developers who want to use their ChatGPT Plus/Pro subscription or API key authentication.

Version Compatibility

Provider Version	AI SDK Version	NPM Tag	Status
1.x	v6	`latest`	Stable
0.x	v5	`ai-sdk-v5`	Maintenance

# AI SDK v6 (default)
npm install ai-sdk-provider-codex-cli ai

# AI SDK v5
npm install ai-sdk-provider-codex-cli@ai-sdk-v5 ai@^5.0.0

Setup

pnpm add ai-sdk-provider-codex-cli

Provider Instance

You can import the default provider instance codexCli from ai-sdk-provider-codex-cli:

import { codexCli } from 'ai-sdk-provider-codex-cli';

If you need a customized setup, you can import createCodexCli and provide default settings that apply to every model:

import { createCodexCli } from 'ai-sdk-provider-codex-cli';

const codexCli = createCodexCli({
  defaultSettings: {
    reasoningEffort: 'medium',
    approvalMode: 'on-failure',
    sandboxMode: 'workspace-write',
    verbose: true,
  },
});

Or pass settings per-model:

const model = codexCli('gpt-5.1-codex', {
  reasoningEffort: 'high',
  approvalMode: 'on-failure',
  sandboxMode: 'workspace-write',
});

Model settings:

reasoningEffort 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' - Controls reasoning depth.
approvalMode 'untrusted' | 'on-failure' | 'on-request' | 'never' - Tool approval policy.
sandboxMode 'read-only' | 'workspace-write' | 'danger-full-access' - Sandbox restrictions.
mcpServers Record<string, McpServerConfig> - MCP server configurations.
verbose boolean - Enable verbose logging.
logger Logger | false - Custom logger or disable logging.

Language Models

Create models that call GPT-5 through the Codex CLI using the provider instance:

const model = codexCli('gpt-5.2-codex');

Current Generation Models:

gpt-5.2-codex: Latest agentic coding model
gpt-5.2: Latest general purpose model
gpt-5.1-codex-max: Flagship model with deep reasoning (supports xhigh reasoning)
gpt-5.1-codex-mini: Lightweight, faster variant

Legacy Models (still supported):

gpt-5.1: General purpose
gpt-5.1-codex: Codex variant
gpt-5: Previous generation
gpt-5-codex: Previous Codex variant
gpt-5-codex-mini: Previous lightweight variant

Example

import { codexCli } from 'ai-sdk-provider-codex-cli';
import { generateText } from 'ai';

const { text } = await generateText({
  model: codexCli('gpt-5.2-codex'),
  prompt: 'Write a vegetarian lasagna recipe for 4 people.',
});

Reasoning Configuration

const model = codexCli('gpt-5.1-codex-max', {
  reasoningEffort: 'high', // 'none' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh'
  reasoningSummary: 'detailed',
});

The xhigh reasoning effort is available on gpt-5.1-codex-max and newer model families that support it (including GPT-5.2 variants when supported by your Codex CLI version).

Model Capabilities

Model	Image Input	Object Generation	Tool Usage	Tool Streaming
`gpt-5.2-codex`
`gpt-5.2`
`gpt-5.1-codex-max`
`gpt-5.1-codex-mini`
`gpt-5.1`
`gpt-5.1-codex`

Tool Usage and Tool Streaming show ❌ because this provider does not support AI SDK custom tools (Zod schemas passed to generateText/streamText). Instead, the Codex CLI executes its own tools autonomously, which can be observed via streaming events. Object generation uses native JSON Schema support via --output-schema for guaranteed schema compliance.

Authentication

The provider uses your existing ChatGPT Plus/Pro subscription through the Codex CLI:

npm install -g @openai/codex
codex  # Follow the interactive authentication setup

Alternatively, you can use an OpenAI API key by setting the OPENAI_API_KEY environment variable.

Requirements

Node.js 18 or higher
Codex CLI installed globally (v0.42.0+ for JSON support, v0.60.0+ recommended for latest models)
ChatGPT Plus/Pro subscription or OpenAI API key

For more details, see the provider documentation.