Codex SDK

Se utilizar o Codex através da Codex CLI, da extensão do IDE ou do Codex cloud, também pode controlá-lo programaticamente.

Utilize o SDK quando precisar de:

• Controlar o Codex como parte do seu pipeline de CI/CD
• Criar o seu próprio agente, capaz de interagir com o Codex para executar tarefas complexas de engenharia
• Incorporar o Codex nas suas próprias ferramentas e fluxos de trabalho internos
• Integrar o Codex na sua própria aplicação

Utilize o Codex SDK para threads do Codex orientados para programação. Se o Codex for um especialista num fluxo de trabalho orquestrado mais abrangente, execute a Codex CLI como um servidor MCP e orquestre-a com o Agents SDK.

Se tiver acesso à versão beta e precisar de análises de repositórios ou alterações com conclusões de segurança estruturadas e cobertura, utilize o Codex Security TypeScript SDK.

Biblioteca TypeScript

A biblioteca TypeScript permite que a sua aplicação inicie, continue e retome threads locais do Codex.

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

Instalação

Para começar, instale o Codex SDK utilizando npm:

npm install @openai/codex-sdk

Utilização

Inicie um thread com o Codex e execute-o com o seu prompt.

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 novamente run() para continuar no mesmo thread ou retome um thread anterior ao fornecer um ID de thread.

// 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 obter mais detalhes, consulte o repositório TypeScript.

Biblioteca Python

O Python SDK controla o app-server local do Codex através de JSON-RPC. Requer Python 3.10 ou posterior. As compilações publicadas do SDK incluem uma dependência de runtime da Codex CLI com uma versão fixada.

Instalação

Para instalar o SDK, execute:

pip install openai-codex

As compilações publicadas do SDK utilizam automaticamente o respetivo runtime fixado. Passe CodexConfig(codex_bin=...) apenas quando pretender deliberadamente utilizar um executável local específico do Codex.

Enquanto o Python SDK estiver em beta, pip install openai-codex seleciona a versão beta publicada mais recente. Quando existir uma versão estável do SDK, utilize pip install --pre openai-codex para optar por compilações de pré-lançamento mais recentes.

Utilização

Inicie o Codex, crie um thread 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)

Utilize AsyncCodex quando a sua aplicação já for assíncrona:

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 da sandbox

Utilize as mesmas predefinições de Sandbox ao criar um thread ou ao alterar o respetivo acesso ao sistema de ficheiros num 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: Leia ficheiros sem permitir operações de escrita.
• Sandbox.workspace_write: Leia ficheiros e escreva dentro do espaço de trabalho e das raízes configuradas com permissão de escrita.
• Sandbox.full_access: Execute sem restrições de acesso ao sistema de ficheiros.

Quando omite sandbox=, o app-server utiliza a predefinição configurada. Uma sandbox passada para run(...) ou turn(...) aplica-se a esse turno e aos turnos posteriores do thread.

Para obter mais detalhes, consulte o repositório Python.