SDK do Codex

Se você usa o Codex por meio do Codex CLI, da extensão para IDE ou do Codex Cloud, também pode controlá-lo por meio de código.

Use o SDK quando precisar:

• Controlar o Codex como parte do seu pipeline de CI/CD
• Criar seu próprio agente para interagir com o Codex e executar tarefas complexas de engenharia
• Incorporar o Codex às suas ferramentas internas e aos seus fluxos de trabalho
• Integrar o Codex ao seu próprio aplicativo

Use o SDK do Codex para automatizar tarefas de programação, incluindo jobs de CI. Use o App Server do Codex para criar clientes personalizados que gerenciem autenticação, histórico de conversas, aprovações e eventos do agente transmitidos por streaming.

O comando codex mcp-server e o binário independente codex-mcp-server foram removidos. Use o App Server do Codex nas integrações existentes.

Se você tem acesso à versão beta e precisa de análises de repositórios ou alterações com achados de segurança e cobertura estruturados, use o SDK TypeScript do Codex Security.

Biblioteca TypeScript

A biblioteca TypeScript permite que seu aplicativo inicie, continue e retome conversas locais do Codex.

Use a biblioteca no lado do servidor; ela requer Node.js 18 ou posterior.

Instalação

Para começar, instale o SDK do Codex usando npm:

npm install @openai/codex-sdk

Uso

Inicie uma conversa com o Codex e execute-a com seu prompt.

import { Codex } from "@openai/codex-sdk";

const codex = new Codex();
const thread = codex.startThread();
const result = await thread.run(
  "Make a plan to diagnose and fix the CI failures"
);

console.log(result.finalResponse);

Chame run() novamente para continuar na mesma conversa ou retome uma conversa anterior fornecendo o ID dela.

// running the same thread
const result = await thread.run("Implement the plan");

console.log(result.finalResponse);

// resuming past thread

const threadId = "<thread-id>";
const thread2 = codex.resumeThread(threadId);
const result2 = await thread2.run("Pick up where you left off");

console.log(result2.finalResponse);

Para mais detalhes, consulte o repositório TypeScript.

Biblioteca Python

O SDK Python controla o app-server local do Codex por meio de JSON-RPC. Ele requer Python 3.10 ou posterior. As versões publicadas do SDK incluem uma dependência do ambiente de execução do Codex CLI com versão fixada.

Instalação

Para instalar o SDK, execute:

pip install openai-codex

As versões publicadas do SDK usam automaticamente o ambiente de execução com versão fixada. Passe CodexConfig(codex_bin=...) somente quando quiser usar intencionalmente um executável local específico do Codex.

O SDK Python está disponível em uma versão estável. pip install openai-codex instala a versão estável mais recente. Use pip install --pre openai-codex para optar por versões preliminares mais recentes.

Uso

Inicie o Codex, crie uma conversa e execute um prompt:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(
        model="gpt-5.6-terra",
        sandbox=Sandbox.workspace_write,
    )
    result = thread.run("Make a plan to diagnose and fix the CI failures")
    print(result.final_response)

Use AsyncCodex quando seu aplicativo já for assíncrono:

import asyncio

from openai_codex import AsyncCodex


async def main() -> None:
    async with AsyncCodex() as codex:
        thread = await codex.thread_start(model="gpt-5.6-terra")
        result = await thread.run("Implement the plan")
        print(result.final_response)


asyncio.run(main())

Predefinições de Sandbox

Use as mesmas predefinições de Sandbox ao criar uma conversa ou alterar o acesso dela ao sistema de arquivos para um turno posterior:

from openai_codex import Codex, Sandbox

with Codex() as codex:
    thread = codex.thread_start(sandbox=Sandbox.workspace_write)
    thread.run("Make the requested change.")
    review = thread.run("Review the diff only.", sandbox=Sandbox.read_only)

Predefinições disponíveis:

• Sandbox.read_only: Ler arquivos sem permitir gravações.
• Sandbox.workspace_write: Ler arquivos e gravar no workspace e nos diretórios raiz configurados com permissão de gravação.
• Sandbox.full_access: Executar sem restrições de acesso ao sistema de arquivos.

Quando você omite sandbox=, o app-server usa o padrão configurado. Um sandbox passado para run(...) ou turn(...) se aplica a esse turno e aos turnos posteriores da conversa.

Para mais detalhes, consulte o repositório Python.