ai-sdk-codex-provider

AI SDK - Codex SDK Provider

The ai-sdk-codex-provider package provides a Codex SDK-backed provider for the AI SDK, using @openai/codex-sdk under the hood.

Setup

Install the provider with ai:

npm i ai-sdk-codex-provider ai

Skill for Coding Agents

If you use coding agents such as Claude Code or Cursor, we recommend adding the AI SDK skill to your repository:

npx skills add vercel/ai

Provider Instance

You can import the default provider instance codexSdk:

import { codexSdk } from "ai-sdk-codex-provider";

Or create a customized provider instance:

import { createCodexSdk } from "ai-sdk-codex-provider";

const provider = createCodexSdk({
  name: "codex-sdk",
  baseURL: process.env.OPENAI_BASE_URL,
  threadOptions: {
    workingDirectory: process.cwd(),
    sandboxMode: "read-only",
    approvalPolicy: "never",
  },
});

Example

import { codexSdk } from "ai-sdk-codex-provider";
import { generateText } from "ai";

const { text } = await generateText({
  model: codexSdk("gpt-5"),
  prompt: "Summarize the repository state in one paragraph.",
});

console.log(text);

Including Model IDs for Auto-Completion

import { createCodexSdk } from "ai-sdk-codex-provider";

type CodexModelIds = "gpt-5.3-codex" | "gpt-5.2-codex" | (string & {});

const provider = createCodexSdk<CodexModelIds>();

provider("gpt-5.3-codex");

To refresh the generated model catalog (model ids + metadata) from upstream Codex:

bun --cwd packages/ai-sdk-codex-provider run sync:model-catalog

Read generated model metadata at runtime:

import { getCodexSdkModelInfo } from "ai-sdk-codex-provider";

const info = getCodexSdkModelInfo("gpt-5.3-codex");
console.log(info?.contextWindow);

Notes

• This provider targets LanguageModelV3 only.
• AI SDK tools are ignored by the provider because Codex executes tools autonomously.
• Provider-executed Codex tools are surfaced through stream events (tool-call, tool-result).
• Set includeRawChunks: true in AI SDK call options to receive raw Codex ThreadEvent payloads in the stream.
• Codex SDK authentication (ChatGPT account or API key) must already be configured in your environment.

Option Coverage

Audited against @openai/codex-sdk@0.101.0.

• CodexOptions support: createCodexSdk(...) forwards all current CodexOptions fields. baseUrl is supported via baseURL (preferred) and baseUrl (deprecated alias). If both are provided, baseURL wins.
• ThreadOptions support: supported at all adapter layers:
  • Provider default: createCodexSdk({ threadOptions: ... })
  • Model default: codexSdk(modelId, modelSettings)
  • Per-call override: providerOptions["<provider-name>"]
• Resume support: providerOptions["<provider-name>"].threadId maps to codex.resumeThread(threadId, threadOptions).
• Provider options lookup supports both providerOptions["codex-sdk"] (canonical key) and providerOptions["<provider-name>"] (custom provider name). If both are present, custom-key values override canonical values.
• Turn options support: AI SDK abortSignal maps to Codex TurnOptions.signal; AI SDK JSON response schema maps to Codex TurnOptions.outputSchema (responseFormat.name/description are mapped to schema title/description when missing).

Not fully passthrough:

• ThreadOptions.model is intentionally overridden by the AI SDK model id (codexSdk("<model-id>")) on every call.

AI SDK call options currently not forwarded to Codex (warnings emitted):

• tools, toolChoice
• headers
• temperature, topP, topK
• maxOutputTokens
• stopSequences
• presencePenalty, frequencyPenalty
• seed

Documentation

• AI SDK community custom provider guide: https://ai-sdk.dev/providers/community-providers/custom-providers
• Codex SDK docs: https://github.com/openai/codex/tree/main/sdk/typescript